# Research: AstroDeck Inventory Planning for Website Rebuild

## Decision 1: Inventory source boundaries are directory-driven and explicit

- **Decision**: Use current `apps/website/src` structure as the mandatory discovery boundary:
  - `src/pages` -> `Page` primitives
  - `src/components/sections` -> `Section` primitives
  - `src/components/primitives`, `src/components/content`, `src/components/layout` -> `Component` primitives
- **Rationale**: This matches how the website is already authored and prevents hidden omissions.
- **Alternatives considered**:
  - Inventory only referenced components in current routes: rejected because it misses available but currently unused candidates.
  - Inventory from screenshots/manual browsing only: rejected because it is incomplete and non-deterministic.

## Decision 2: Include demo/template artifacts as first-class inventory entries

- **Decision**: Mark template/demo artifacts explicitly (e.g., `demo-only`) instead of excluding them.
- **Rationale**: Excluding them early hides available options and weakens auditability of later keep/adapt/remove decisions.
- **Alternatives considered**:
  - Exclude demo components from inventory: rejected because it creates selective inventory bias.

## Decision 3: Suitability classes must be mandatory and exhaustive

- **Decision**: Every inventory entry receives exactly one suitability class:
  - `A` strong candidate
  - `B` adaptable candidate
  - `C` weak candidate
  - `D` non-candidate
- **Rationale**: Follow-up mapping specs require deterministic triage and cannot rely on narrative-only judgments.
- **Alternatives considered**:
  - Optional suitability scoring: rejected because it creates inconsistent coverage across entries.

## Decision 4: Risk and candidate markers are additive, not substitutive

- **Decision**: Marker tags (e.g., `visual-risk`, `semantic-risk`, `hero-candidate`, `trust-candidate`) augment but do not replace required fields.
- **Rationale**: Tags improve queryability for later mapping while preserving normalized core attributes.
- **Alternatives considered**:
  - Use markers only, skip required fields: rejected because it is too ambiguous for cross-spec traceability.

## Decision 5: Inventory output must be mapping-consumable by contract

- **Decision**: Define a logical OpenAPI contract for inventory publication and summary retrieval so downstream specs can reference stable structures.
- **Rationale**: A contractized shape increases consistency for future tasks and automation without introducing runtime implementation in this feature.
- **Alternatives considered**:
  - Freeform markdown only: rejected because downstream mapping extraction becomes error-prone.

## Decision 6: Existing repo patterns favor normalized inventories with explicit classes

- **Decision**: Mirror existing repository planning patterns by using normalized entity fields, explicit classifications, and deterministic summaries.
- **Rationale**: Prior specs (`040`, `042`, `045`) consistently model inventory-like domains with strict fields and taxonomy semantics.
- **Alternatives considered**:
  - Introduce a novel inventory schema unrelated to existing specs: rejected because it adds unnecessary cognitive overhead.

## Resolved Clarifications

- No unresolved `NEEDS CLARIFICATION` items remain.
- The technical stack and boundaries are sufficient for Phase 1 artifact design.