# Research: Website Homepage Structure & Section Model

## Decision 1: Keep the homepage implementation local to the static Astro website

- **Decision**: Continue treating the homepage as a static `apps/website` route composed from Astro content modules and section components, with no runtime dependency on `apps/platform`.
- **Rationale**: Spec 216 is explicitly website-only. The current website already runs as a standalone Astro app, and the required homepage improvements concern structure, sequencing, and public route discoverability rather than dynamic runtime behavior.
- **Alternatives considered**:
  - Couple homepage composition to `apps/platform` or a shared API: rejected because the spec forbids platform obligations and the homepage needs no dynamic platform data.
  - Introduce a CMS or page-builder layer first: rejected because a single homepage route does not justify that operational overhead.

## Decision 2: Extend the existing content-driven homepage model instead of adding a section registry

- **Decision**: Preserve `apps/website/src/content/pages/home.ts` as the homepage source module and extend it with the smallest missing content objects for outcome, capability, trust, and progress sections.
- **Rationale**: The current site already uses typed content exports and section components (`PageHero`, `FeatureGrid`, `CTASection`, `TrustGrid`, `LogoStrip`). This is the narrowest correct place to express homepage-specific structure without adding a polymorphic section framework.
- **Alternatives considered**:
  - Build a generic section registry with discriminated unions and render dispatch: rejected as premature abstraction for one page.
  - Hardcode all new copy and structure directly in `index.astro`: rejected because it would weaken the existing typed content pattern and make future homepage iteration harder.

## Decision 3: Recompose the homepage into an explicit narrative flow

- **Decision**: Implement the homepage in the following functional order: header, hero, outcome framing, capability model, trust, progress, CTA, footer. Optional supporting context stays secondary and may only appear if it reinforces clarity.
- **Rationale**: Exploration of the current homepage showed that the site already has hero, optional ecosystem context, and CTA pieces, but the middle narrative is misaligned: the current feature grid explains route jobs instead of product outcomes or capabilities, trust is too implicit, and progress is only a CTA target.
- **Alternatives considered**:
  - Keep the current hero → ecosystem → route-jobs → proof → CTA sequence: rejected because it does not satisfy Spec 216’s required block responsibilities.
  - Collapse trust or progress into the CTA block: rejected because the spec requires both to appear explicitly before the final CTA.

## Decision 4: Reuse existing Trust and Changelog truth for homepage proof blocks

- **Decision**: Source homepage trust signals from the existing Trust content (`trust.ts`) and source homepage progress signals from the published changelog collection rather than inventing homepage-only proof systems.
- **Rationale**: The Trust page already contains bounded public claims and principles, while the changelog route already uses dated collection entries. Reusing those sources keeps one truth for proof-oriented content and avoids duplicate claim maintenance.
- **Alternatives considered**:
  - Create homepage-only trust claims arrays disconnected from `/trust`: rejected because it would create duplicate truth and increase drift risk.
  - Create manual homepage progress cards unrelated to the changelog collection: rejected because dated changelog truth already exists and is the stronger source.

## Decision 5: Validate through the existing website smoke harness

- **Decision**: Prove Spec 216 with the existing website build command and focused Playwright smoke updates for homepage section order, CTA hierarchy, and onward route reachability.
- **Rationale**: The homepage contract is about public rendering, navigational clarity, and responsive visibility. Browser smoke coverage is the narrowest proving layer that can validate those concerns.
- **Alternatives considered**:
  - Build-only proof alone: rejected because static output generation does not prove section order, CTA hierarchy, or visible route reachability.
  - Add visual regression or heavier browser matrices immediately: rejected because the feature scope does not require that extra cost.