# Research: Public Docs & Knowledge Base IA

## Decision: Use a dedicated `/docs` route family with `/en/docs/` for English

**Rationale**: The current website already ships a bilingual Starlight docs surface, but it is mounted at the site root through starter-style routes such as `/welcome-to-docs/` and `/guides/*`. The spec explicitly prefers a `/docs` family, and the repo already has the nested docs infrastructure needed to support it. Moving the docs IA under `/docs` gives the public site one clear documentation destination instead of mixing docs pages into the root route tree.

**Alternatives considered**:

- Keep `/welcome-to-docs/` and the root-mounted starter docs as the primary IA: too weak and misaligned with the spec.
- Use `/dokumentation`: possible, but it would add a second localized slug family where the current site already tolerates English technical slugs.
- Build only a single landing page: unnecessary because nested docs routes are already supported.

## Decision: Keep docs slugs stable and English across both locales

**Rationale**: The repo already has a localized slug alias system for `/evaluierung` <-> `/evaluation`, but expanding that approach to twelve docs topic slugs would add unnecessary routing and language-switcher complexity. The wider public site already uses English slugs across both locales (`/platform`, `/trust`, `/pricing`, `/contact`, `/use-cases/...`), so `/docs/getting-started/` and `/en/docs/getting-started/` are the narrowest consistent choice.

**Alternatives considered**:

- Localize every docs slug (`/dokumentation/erste-schritte/` etc.): more route aliasing, more smoke coverage, and more language-switching complexity for little user benefit.
- Keep mixed starter slugs like `/guides/*`: does not match the required IA.

## Decision: Reuse Starlight + MDX for docs pages instead of `siteCopy.ts` or custom Astro pages

**Rationale**: The current repo already validates docs content through `src/content.config.ts`, Starlight docs schema, and the website build. Starlight also already handles the docs shell, sidebar, and generated search assets. The required public docs IA is concept-heavy and page-rich, so MDX content pages are a better fit than large copy objects inside `siteCopy.ts` or a second handcrafted docs rendering system.

**Alternatives considered**:

- Store docs body content in `siteCopy.ts`: workable for nav/footer labels, but not the right shape for twelve bilingual docs pages.
- Build `/docs/*` as custom Astro marketing pages: would duplicate a docs system the repo already has.
- Create a second docs content collection: unnecessary because `src/content/docs/**` already exists.

## Decision: Replace sidebar autogeneration with explicit ordered topic entries

**Rationale**: The current sidebar is a starter mix of `guides/` autogeneration plus one manual `platform/evidence-review/` link. Spec 410 requires a fixed, user-question-based order across twelve topic pages. Explicit sidebar entries are the safest way to guarantee that order and prevent the docs IA from drifting back into guide-first starter organization.

**Alternatives considered**:

- Keep `guides/` autogeneration: too coarse and not aligned with the required category order.
- Split into many autogenerate directories: more structural churn than needed for v1.

## Decision: Preserve public continuity through legacy docs redirects or equivalent aliases

**Rationale**: The repo already exposes `/welcome-to-docs/`, `/guides/*`, and `/platform/evidence-review/` in nav/footer or smoke coverage. Dropping those routes without continuity handling would create user-facing regressions. Redirecting or aliasing those URLs to the new `/docs` family preserves continuity without keeping two parallel docs IAs alive.

**Alternatives considered**:

- Keep both old and new docs trees permanently: duplicate truth and split discoverability.
- Remove the old URLs entirely: too risky and inconsistent with the existing smoke inventory.

## Decision: Keep nav and footer link ownership in `siteCopy.ts`

**Rationale**: Navbar and footer copy already come from `apps/website/src/data_files/site-copy.ts` and use `localizeHref()` from `src/i18n.ts`. Retargeting those existing docs links from `/welcome-to-docs/` to `/docs/` is narrower than adding a second navigation configuration path.

**Alternatives considered**:

- Add a standalone docs-nav config: unnecessary while nav/footer already read from `siteCopy.ts`.
- Hardcode docs links directly in Astro components: weaker localization consistency.

## Decision: Prioritize homepage, platform, trust, evaluation, nav, and footer for guaranteed docs discovery

**Rationale**: Those surfaces are the clearest adjacent entry points named in the spec and already exist in the public route inventory. Review-packs and use-case pages can also expose docs discovery if their current section density stays readable, but the minimum guaranteed discovery set should stay focused.

**Alternatives considered**:

- Footer-only discoverability: too weak.
- Main-nav-only discoverability: not enough contextual handoff.
- Add a large docs mega-menu: too broad for the current public IA.

## Decision: Reuse existing Playwright smoke helpers and route inventories as the narrowest proof

**Rationale**: `apps/website/tests/smoke/public-routes.spec.ts`, `interaction.spec.ts`, and `smoke-helpers.ts` already validate route rendering, metadata, placeholder-link bans, nav/footer reachability, and forbidden public claims. Extending those suites is the narrowest proof path for this feature.

**Alternatives considered**:

- Manual-only browser review: insufficient for metadata and route migration regressions.
- New unit tests for MDX/frontmatter shape: weaker end-user proof than the existing route smokes.
- A second docs-specific browser suite: unnecessary duplication.

## Decision: Treat claim scans as blockers, not optional review aids

**Rationale**: The main risk in this feature is public overclaiming rather than runtime breakage. Static scans over `apps/website/src`, `apps/website/public`, and `apps/website/dist` are a cheap way to catch unsupported trust/provider/automation language, placeholder links, and leaked internal jargon.

**Alternatives considered**:

- Code review only: too easy to miss banned phrases in metadata or generated output.
- A new custom linter: heavier than needed for one bounded website feature.

## Decision: Use only existing website commands for validation

**Rationale**: The website package already exposes `build`, `test`, `test:smoke`, and formatting scripts. The plan should rely on those real commands instead of inventing a standalone `check` script or touching root workspace contracts.

**Alternatives considered**:

- `pnpm --filter @tenantatlas/website check`: not present.
- Root script changes: out of scope.
- Platform/Sail commands: wrong layer for a website-only feature.