TenantAtlas/specs/215-website-core-pages/research.md

# Research: Website Information Architecture / Core Pages

## Decision 1: Preserve the website working contract and keep all IA truth local to `apps/website`

- **Decision**: Treat Spec 215 as a website-only IA change inside `apps/website` and preserve `@tenantatlas/website`, `WEBSITE_PORT`, Astro static output, and the root `dev:website` / `build:website` workflows unchanged.
- **Rationale**: The spec is explicitly scoped to the public website and excludes platform routing, auth, and Filament concerns. The narrowest correct implementation is therefore to evolve the existing Astro app in place without introducing backend, package, or runtime coupling to `apps/platform`.
- **Alternatives considered**:
  - Introduce shared website-platform routing or metadata contracts: rejected because the spec explicitly excludes `apps/platform` obligations.
  - Solve IA through platform-side redirects or a shared CMS: rejected because the website already has a self-contained Astro route layer that can carry the IA truth directly.

## Decision 2: Use the existing `site.ts` and route-definition layer as the canonical IA source of truth

- **Decision**: Reuse `apps/website/src/lib/site.ts`, `apps/website/src/types/site.ts`, and `apps/website/src/content/pages` as the canonical source of truth for core routes, page roles, navigation, footer groupings, CTA hierarchy, and page-family mapping.
- **Rationale**: The current website already centralizes navigation, page definitions, shell tone, CTA variants, and sitemap route generation in the `site.ts` layer. Extending that layer is the narrowest way to encode the new IA without introducing a second route manifest or a CMS-style navigation system.
- **Alternatives considered**:
  - Create a second IA-only config file: rejected because it would duplicate route truth and increase drift risk.
  - Hardcode navigation and page-role decisions separately inside each page component: rejected because it would repeat the current v0 problem in a less controllable form.

## Decision 3: Canonicalize the required core route set and use compatibility paths only when necessary

- **Decision**: Treat `/`, `/product`, `/trust`, `/changelog`, `/contact`, `/privacy`, and `/imprint` as the canonical core route set for the initial website. Replace `/security-trust` with `/trust` as the canonical trust path, add `/changelog`, add `/imprint`, and keep compatibility paths narrow and temporary if route renames would otherwise cause avoidable breakage.
- **Rationale**: The current route inventory contains `/security-trust` instead of `/trust` and lacks both `/changelog` and `/imprint`, even though the spec requires a small, enterprise-credible core that includes visible trust, visible product progress, and legal basics. Canonicalizing these paths aligns the implementation with the spec while keeping change scope focused on the website route layer.
- **Alternatives considered**:
  - Keep `/security-trust` as the long-term canonical path: rejected because the spec names `/trust` and the shorter path is clearer.
  - Add `/changelog` and `/imprint` only as footer labels without real routes: rejected because the spec requires actual public surfaces, not navigation placeholders.
  - Preserve every old route as a permanent parallel surface: rejected because multiple canonical truths would dilute the IA and make future page work harder.

## Decision 4: Keep primary navigation intentionally small and demote non-core v0 routes

- **Decision**: Shrink primary navigation to the Spec 215 core: Product, Trust, Changelog, Contact, plus optional `Resources` only when substantive content exists. Treat `Solutions` and `Integrations` as retained secondary supporting pages rather than core IA peers.
- **Rationale**: The current primary navigation already consumes all 5 available informational slots with Product, Solutions, Security & Trust, Integrations, and Contact, leaving no room for Changelog even though product progress is a first-class public signal in Spec 215. If the IA stays small, solutions-style audience framing must live inside Home/Product first, while already-published supporting pages such as Solutions and Integrations can remain secondary without occupying core nav space.
- **Alternatives considered**:
  - Keep Solutions and Integrations in top-level nav and simply add Changelog as a 6th item: rejected because the spec explicitly prioritizes a small navigation and core-route discipline.
  - Remove outcome explanation entirely when demoting Solutions: rejected because the spec requires buyer-oriented outcome explanation even without a dedicated `/solutions` hub.

## Decision 5: Use Astro content collections as readiness gates for optional surfaces

- **Decision**: Treat the existing `resources` and `changelog` Astro content collections as the current readiness mechanism for optional and recommended public surfaces. The existing `articles` collection remains unpublished until a separate editorial/blog spec activates it. `/changelog` is special: it is part of the recommended core and therefore needs substantive dated entries rather than an empty shell.
- **Rationale**: The repo already has empty content collections for articles, changelog, and resources. Using `resources` and `changelog` as explicit discoverability gates avoids empty prestige routes, while leaving `articles` unpublished prevents the current IA from implying an activated blog/editorial surface that does not yet exist.
- **Alternatives considered**:
  - Publish `/blog` or `/resources` immediately as placeholders because collections already exist: rejected because the spec forbids empty prestige pages.
  - Ignore the existing content collections and hand-build separate page data sources: rejected because it would bypass the narrowest existing structure.

## Decision 6: Validate the IA through route-aware smoke coverage and build proof

- **Decision**: Keep validation in `fast-feedback` using `corepack pnpm build:website` and the existing Playwright smoke suite in `apps/website/tests/smoke`, expanded to cover the canonical core routes, updated nav/footer labels, optional-surface suppression, and any compatibility-route expectations.
- **Rationale**: The feature changes route topology, navigation, footer grouping, and discoverability rules on a static Astro site. The current smoke suite already verifies shell structure, navigation labels, CTA hierarchy, and footer links; expanding those helpers is the smallest realistic proof of the new IA.
- **Alternatives considered**:
  - Build-only validation: rejected because it would miss browser-visible regressions in navigation labels, hidden/visible route links, and compatibility paths.
  - Heavier browser or cross-browser infrastructure: rejected because the public website remains static-first and the current smoke suite is sufficient for this route-contract feature.

## Baseline Findings

- `apps/website` is a standalone Astro 6 app with static output, strict TypeScript, Tailwind CSS v4, and local Playwright smoke coverage.
- The current public route inventory is `/`, `/product`, `/solutions`, `/security-trust`, `/integrations`, `/contact`, `/legal`, `/privacy`, and `/terms`.
- The current primary navigation is driven from `src/lib/site.ts` and uses Product, Solutions, Security & Trust, Integrations, and Contact as the five informational links.
- The current footer also comes from `src/lib/site.ts` and groups Explore, Next step, and Legal links around the v0 route set.
- The current page-definition layer already models page roles, families (`landing`, `trust`, `content`), shell tones, header CTA variants, and footer lead variants.
- Astro content collections for `articles`, `changelog`, and `resources` already exist; the current plan activates `changelog`, reserves `resources` as the only optional content surface in this feature, and leaves `articles` unpublished.
- The current smoke suite already covers Home, Product, Solutions, Security & Trust, Integrations, Contact, and legal surfaces, so route-topology regression proof can stay inside the existing website test harness.