ahmido
af5fa30341
Implements website feature branch `410-public-docs-ia`. Target branch: `website-dev`. Validation: - `corepack pnpm --filter @tenantatlas/website build` - Playwright smoke coverage for public routes and docs interactions - Static claim scans for `apps/website/src`, `apps/website/public`, and `apps/website/dist` Follow-up integration path after merge: `website-dev` -> `dev`. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #412
375 lines
27 KiB
Markdown
375 lines
27 KiB
Markdown
# Implementation Plan: Public Docs & Knowledge Base IA
|
|
|
|
**Branch**: `410-public-docs-ia` | **Date**: 2026-05-31 | **Spec**: [spec.md](spec.md)
|
|
**Input**: Feature specification from `/specs/410-public-docs-ia/spec.md`
|
|
|
|
## Summary
|
|
|
|
Rework the current root-mounted Starlight starter docs into a dedicated bilingual `/docs` route family backed by the existing MDX docs collection, then replace the lightweight starter pages with the twelve required public knowledge-base topics for Microsoft 365 governance, trust review, evidence, drift, recovery context, review packs, limitations, and FAQ.
|
|
|
|
The implementation stays inside `apps/website`, reuses the existing Astro + Starlight + MDX docs stack for the documentation pages, keeps navigation and footer links inside the current `siteCopy` plus locale helper pattern, and preserves public continuity by mapping the current starter docs routes and the legacy evidence-review docs page to the new docs IA instead of leaving broken public URLs behind.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: TypeScript 6.0.3, Astro 6.3.3, MDX content files rendered through Starlight 0.39.2
|
|
**Primary Dependencies**: Astro, `@astrojs/starlight`, `@astrojs/mdx`, Tailwind CSS v4 via `@tailwindcss/vite`, Playwright 1.59.1
|
|
**Storage**: N/A (static public website content only)
|
|
**Testing**: Playwright smoke tests in `apps/website/tests/smoke` plus `astro check` within the website `build` script
|
|
**Validation Lanes**: browser, confidence
|
|
**Target Platform**: Static bilingual website build rendered in desktop and mobile browsers
|
|
**Project Type**: Web application with Astro page routes plus a Starlight-backed docs surface
|
|
**Performance Goals**: Preserve static prerendered docs pages, readable desktop/mobile docs layouts, valid metadata, intentional links, no horizontal overflow, and no broken locale-aware routes
|
|
**Constraints**: `apps/website` only, preserve root workspace contracts (`package.json` scripts, `WEBSITE_PORT`, `apps/*` workspace layout), keep `apps/platform` untouched, keep DE as default locale with EN prefixed routes, avoid unsupported trust/provider/automation claims, and keep all docs links real
|
|
**Scale/Scope**: One new localized docs landing route family, twelve localized child pages, explicit sidebar ordering, nav/footer retargeting, selected public crosslinks, smoke inventory updates, and legacy docs-route continuity handling
|
|
|
|
## UI / Surface Guardrail Plan
|
|
|
|
- **Guardrail scope**: no operator-facing surface change
|
|
- **Native vs custom classification summary**: mixed public-site surface; Starlight for docs pages, existing Astro marketing pages for discovery teasers
|
|
- **Shared-family relevance**: public navigation, footer, metadata, Starlight docs sidebar, related-link cards, and smoke route inventory
|
|
- **State layers in scope**: shell and page
|
|
- **Audience modes in scope**: customer/read-only
|
|
- **Decision/diagnostic/raw hierarchy plan**: docs stay decision-first and buyer-readable; no operator diagnostics or raw evidence surfaces are introduced
|
|
- **Raw/support gating plan**: N/A
|
|
- **One-primary-action / duplicate-truth control**: the docs landing page keeps one clear start path into the IA, while each child page uses related links and at most one conversion-oriented handoff to avoid repeating the same CTA block on every section
|
|
- **Handling modes by drift class or surface**: report-only
|
|
- **Repository-signal treatment**: review-mandatory for route moves, claim language, and legacy URL continuity
|
|
- **Special surface test profiles**: N/A
|
|
- **Required tests or manual smoke**: manual-smoke and browser smoke
|
|
- **Exception path and spread control**: none
|
|
- **Active feature PR close-out entry**: Smoke Coverage
|
|
|
|
## Shared Pattern & System Fit
|
|
|
|
- **Cross-cutting feature marker**: yes
|
|
- **Systems touched**: `apps/website/astro.config.mjs`, `apps/website/src/content.config.ts`, `apps/website/src/content/docs/**`, `apps/website/src/data_files/site-copy.ts`, `apps/website/src/i18n.ts`, navbar/footer components, and smoke route helpers
|
|
- **Shared abstractions reused**: Starlight docs collection, Starlight sidebar configuration, custom Starlight shell overrides in `src/components/ui/starlight`, locale helpers in `src/i18n.ts`, and public route smoke helpers in `apps/website/tests/smoke/smoke-helpers.ts`
|
|
- **New abstraction introduced? why?**: none; the feature should stay inside the existing docs collection plus shared site copy and smoke helpers
|
|
- **Why the existing abstraction was sufficient or insufficient**: the repo already ships a bilingual Starlight docs surface and smoke coverage for docs routes, but the current IA is starter-like (`/welcome-to-docs/`, `/guides/*`) and does not match the required public knowledge-base structure
|
|
- **Bounded deviation / spread control**: no second docs system; the plan keeps docs pages in Starlight/MDX and marketing discovery links in existing Astro pages instead of introducing parallel content pipelines
|
|
|
|
## OperationRun UX Impact
|
|
|
|
- **Touches OperationRun start/completion/link UX?**: no
|
|
- **Central contract reused**: N/A
|
|
- **Delegated UX behaviors**: N/A
|
|
- **Surface-owned behavior kept local**: none
|
|
- **Queued DB-notification policy**: N/A
|
|
- **Terminal notification path**: N/A
|
|
- **Exception path**: none
|
|
|
|
## Provider Boundary & Portability Fit
|
|
|
|
- **Shared provider/platform boundary touched?**: yes
|
|
- **Provider-owned seams**: Microsoft 365 provider framing, permissions and data-access wording, consent/admin-role language, and trust references
|
|
- **Platform-core seams**: docs IA, policy evidence, drift detection, review-pack framing, limitations language, FAQ structure, and evaluation-readiness vocabulary
|
|
- **Neutral platform terms / contracts preserved**: provider connection, permissions and data access, policy evidence, drift detection, recovery context, findings, accepted risk, review packs, evaluation, known limitations, and FAQ
|
|
- **Retained provider-specific semantics and why**: Microsoft 365 stays explicit because it is the current public product focus and the docs must remain concrete for evaluators
|
|
- **Bounded extraction or follow-up path**: document-in-feature only; detailed permission matrices, multi-provider docs, localized slug alias systems, and search/versioning expansion remain follow-up work
|
|
|
|
## Constitution Check
|
|
|
|
GATE status before Phase 0 research: Pass for website-only scope.
|
|
|
|
- Inventory-first: N/A (no inventory/runtime change)
|
|
- Read/write separation: Pass (no write behavior)
|
|
- Graph contract path: N/A (no Graph/API runtime)
|
|
- Deterministic capabilities: N/A
|
|
- RBAC-UX and tenant/workspace isolation: N/A (public unauthenticated docs surface)
|
|
- Run observability / OperationRun UX: N/A
|
|
- TEST-GOV-001: Pass (browser lane explicit, existing smoke family reused, no fixture/helper cost expansion planned)
|
|
- PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001: Pass (no new persistence, runtime abstraction, enum, or semantic framework)
|
|
- XCUT-001: Pass (reuse Starlight docs infrastructure, shared nav/footer copy, and smoke helpers)
|
|
- PROV-001: Pass (provider-specific language remains bounded to current public Microsoft 365 scope)
|
|
- DECIDE-AUD-001: N/A for operator/status surfaces; this remains public docs copy only
|
|
|
|
Post-design re-check after Phase 1: Pass. The research, docs content model, route contract, and quickstart stay static public-site artifacts only, keep all runtime product behavior out of scope, and do not require any `apps/platform` touch.
|
|
|
|
## Test Governance Check
|
|
|
|
- **Test purpose / classification by changed surface**: Browser
|
|
- **Affected validation lanes**: browser, confidence
|
|
- **Why this lane mix is the narrowest sufficient proof**: the feature changes public routes, sidebar/nav/footer links, metadata, localized URLs, and claim-safe copy; those are best proven by the existing public route and interaction smoke suites plus the website build
|
|
- **Narrowest proving command(s)**:
|
|
- `corepack pnpm --filter @tenantatlas/website build`
|
|
- `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts`
|
|
- `corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts`
|
|
- **Fixture / helper / factory / seed / context cost risks**: none
|
|
- **Expensive defaults or shared helper growth introduced?**: no
|
|
- **Heavy-family additions, promotions, or visibility changes**: none
|
|
- **Surface-class relief / special coverage rule**: public website browser smoke only
|
|
- **Closing validation and reviewer handoff**: reviewers verify docs routes render in both locales, legacy docs URLs do not break silently, nav/footer and contextual links point at the new docs family, and no banned claims appear in source or build output
|
|
- **Budget / baseline / trend follow-up**: none expected
|
|
- **Review-stop questions**: lane fit, hidden route-migration cost, legacy-link continuity, and claim-boundary completeness
|
|
- **Escalation path**: document-in-feature
|
|
- **Active feature PR close-out entry**: Smoke Coverage
|
|
- **Why no dedicated follow-up spec is needed**: the work remains inside existing website docs infrastructure; future search/versioning/provider-expansion concerns are separate slices only if product truth changes
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/410-public-docs-ia/
|
|
├── plan.md
|
|
├── research.md
|
|
├── data-model.md
|
|
├── quickstart.md
|
|
├── contracts/
|
|
│ └── public-docs-routes.openapi.yaml
|
|
└── spec.md
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
apps/website/
|
|
├── astro.config.mjs
|
|
├── src/
|
|
│ ├── content.config.ts
|
|
│ ├── content/
|
|
│ │ └── docs/
|
|
│ │ ├── index.mdx
|
|
│ │ ├── getting-started.mdx
|
|
│ │ ├── microsoft-365-provider.mdx
|
|
│ │ ├── permissions-data-access.mdx
|
|
│ │ ├── data-processing-trust.mdx
|
|
│ │ ├── policy-evidence.mdx
|
|
│ │ ├── drift-detection.mdx
|
|
│ │ ├── backups-versioning-recovery.mdx
|
|
│ │ ├── findings-exceptions-accepted-risk.mdx
|
|
│ │ ├── review-packs-decisions.mdx
|
|
│ │ ├── evaluation-pilot.mdx
|
|
│ │ ├── known-limitations.mdx
|
|
│ │ ├── faq.mdx
|
|
│ │ └── en/
|
|
│ │ ├── index.mdx
|
|
│ │ ├── getting-started.mdx
|
|
│ │ ├── microsoft-365-provider.mdx
|
|
│ │ ├── permissions-data-access.mdx
|
|
│ │ ├── data-processing-trust.mdx
|
|
│ │ ├── policy-evidence.mdx
|
|
│ │ ├── drift-detection.mdx
|
|
│ │ ├── backups-versioning-recovery.mdx
|
|
│ │ ├── findings-exceptions-accepted-risk.mdx
|
|
│ │ ├── review-packs-decisions.mdx
|
|
│ │ ├── evaluation-pilot.mdx
|
|
│ │ ├── known-limitations.mdx
|
|
│ │ └── faq.mdx
|
|
│ ├── components/
|
|
│ │ ├── sections/
|
|
│ │ │ └── navbar&footer/
|
|
│ │ │ ├── FooterSection.astro
|
|
│ │ │ └── Navbar.astro
|
|
│ │ └── ui/
|
|
│ │ └── starlight/
|
|
│ ├── data_files/
|
|
│ │ └── site-copy.ts
|
|
│ └── i18n.ts
|
|
└── tests/smoke/
|
|
├── interaction.spec.ts
|
|
├── public-routes.spec.ts
|
|
└── smoke-helpers.ts
|
|
```
|
|
|
|
**Structure Decision**: Keep marketing pages as Astro routes and move the public docs IA deeper into the existing Starlight + MDX docs collection. Navigation/footer stay copy-driven in `site-copy.ts`; docs pages and sidebar stay content-driven in `src/content/docs/**` and `astro.config.mjs`.
|
|
|
|
## Documentation IA Decision
|
|
|
|
Selected IA shape:
|
|
|
|
- dedicated docs base route at `/docs/` and `/en/docs/`
|
|
- twelve required child pages below the docs base route
|
|
- stable English slugs for both locales
|
|
- localized visible labels in the Starlight sidebar and on page content
|
|
- explicit sidebar ordering instead of the current starter `guides` autogeneration
|
|
|
|
Reasoning:
|
|
|
|
- The repository already ships Starlight and a docs content collection, so nested docs routes are supported without inventing a new content stack.
|
|
- The spec explicitly prefers a `/docs` family, and the current root-mounted starter docs do not yet provide that public IA.
|
|
- The broader website already uses many English technical slugs (`/platform`, `/trust`, `/pricing`, `/contact`, `/use-cases/...`), so stable English docs slugs are the narrowest path and avoid expanding locale alias logic from one special case (`/evaluierung` <-> `/evaluation`) to twelve more route families.
|
|
- Explicit sidebar entries are safer than `guides/` autogeneration because the required docs order is fixed by the spec and mixes concept, trust, and readiness topics.
|
|
|
|
Rejected alternatives:
|
|
|
|
- Keep `/welcome-to-docs/` and `/guides/*` as the primary IA: misaligned with the spec and too starter-like for the required public knowledge base.
|
|
- Use `/dokumentation` and `/en/documentation`: adds another localized slug family when the existing public site already tolerates English route slugs.
|
|
- Landing-page-only fallback: unnecessary because Starlight nested docs infrastructure already exists in the repo.
|
|
|
|
## Docs Content System Decision
|
|
|
|
Selected content system:
|
|
|
|
- Starlight-backed MDX pages in `apps/website/src/content/docs/**`
|
|
- localized DE root files and EN mirror files under `apps/website/src/content/docs/en/**`
|
|
- current Starlight custom shell components retained
|
|
- page metadata and page body content authored in MDX frontmatter/content, not in `siteCopy.ts`
|
|
|
|
Reasoning:
|
|
|
|
- The current repo already validates docs content through `src/content.config.ts`, Starlight docs loader/schema, and the website build.
|
|
- The docs surface already ships Pagefind search assets in the generated build, so using the existing docs system keeps future expansion options open without adding work now.
|
|
- `siteCopy.ts` is the right place for nav/footer labels and marketing page copy, but not for twelve concept-heavy docs pages in two locales.
|
|
|
|
Rejected alternatives:
|
|
|
|
- Build the docs IA as custom Astro marketing pages under `src/pages/docs/**`: would duplicate a docs rendering system the repo already has.
|
|
- Keep the starter Starlight pages and only change sidebar labels: too weak for the required route and content restructuring.
|
|
- Create a second content collection just for docs IA: unnecessary while `src/content/docs/**` already exists.
|
|
|
|
## Legacy Route Continuity Decision
|
|
|
|
Selected continuity approach: preserve public continuity through redirects or equivalent route aliases from the current starter docs URLs to the new docs family.
|
|
|
|
Minimum legacy mapping to preserve:
|
|
|
|
- `/welcome-to-docs/` -> `/docs/`
|
|
- `/guides/intro/` -> `/docs/getting-started/`
|
|
- `/guides/getting-started/` -> `/docs/getting-started/`
|
|
- `/guides/first-project-checklist/` -> `/docs/evaluation-pilot/`
|
|
- `/platform/evidence-review/` -> `/docs/policy-evidence/`
|
|
- `/en/welcome-to-docs/` -> `/en/docs/`
|
|
- `/en/guides/intro/` -> `/en/docs/getting-started/`
|
|
- `/en/guides/getting-started/` -> `/en/docs/getting-started/`
|
|
- `/en/guides/first-project-checklist/` -> `/en/docs/evaluation-pilot/`
|
|
- `/en/platform/evidence-review/` -> `/en/docs/policy-evidence/`
|
|
|
|
Reasoning:
|
|
|
|
- The current public nav, footer, and smoke inventory already expose the starter docs URLs, so silently removing them would create regressions.
|
|
- The old evidence-review docs page is conceptually closest to the new `policy-evidence` topic and can hand off there without inventing a second evidence docs tree.
|
|
- Redirecting or aliasing the old docs URLs is narrower than permanently supporting two public docs IAs.
|
|
|
|
Rejected alternatives:
|
|
|
|
- Keep both the new `/docs` family and the old starter docs pages permanently: duplicate truth and split discoverability.
|
|
- Drop the old URLs without continuity handling: would break existing public links and smoke expectations.
|
|
|
|
## Discovery Strategy Decision
|
|
|
|
Selected minimum discovery surfaces:
|
|
|
|
- main navigation `Docs` link
|
|
- footer `Docs` link
|
|
- homepage teaser
|
|
- platform page teaser
|
|
- trust page crosslink
|
|
- evaluation page crosslink
|
|
|
|
Selected secondary surfaces when both checks pass:
|
|
|
|
- the destination route already exists in the local public IA
|
|
- the page can reuse an existing teaser or card slot without adding a new section or displacing its primary CTA
|
|
|
|
- review-packs page crosslink
|
|
- MSP use-case crosslink
|
|
- Mittelstand use-case crosslink
|
|
|
|
Reasoning:
|
|
|
|
- Navigation and footer already carry a docs entry today, so the simplest change is to retarget them from `/welcome-to-docs/` to `/docs/`.
|
|
- Homepage, platform, trust, and evaluation are the most direct adjacent public surfaces named in the spec.
|
|
- Review packs and use-case pages already sit in the public route inventory and can support docs discovery when the destination route exists and a docs handoff fits into an existing teaser or card slot without creating a second CTA hierarchy.
|
|
|
|
Rejected alternatives:
|
|
|
|
- Footer-only discoverability: too weak for a major public IA shift.
|
|
- Main-nav-only discoverability: insufficient without contextual handoff from trust, evaluation, and product-story pages.
|
|
- Add a second large navigation family just for docs topics: too broad for the current public site IA.
|
|
|
|
## Research-Driven Implementation Notes
|
|
|
|
- `apps/website/astro.config.mjs` currently mounts Starlight at the site root and uses a starter sidebar built from `guides/` plus one hardcoded `platform/evidence-review/` entry; implementation must replace that setup with the dedicated docs IA.
|
|
- `apps/website/src/i18n.ts` currently holds only one slug alias group for `/evaluierung` <-> `/evaluation`; the docs route family should avoid multiplying alias groups by keeping shared English docs slugs across locales.
|
|
- `apps/website/src/data_files/site-copy.ts` already owns nav and footer docs links; retarget those links rather than inventing a new nav config.
|
|
- current public metadata handling, including canonical tags where present, must be inspected and reused for the docs landing and child pages instead of introducing docs-only metadata rules.
|
|
- `apps/website/tests/smoke/smoke-helpers.ts` already keeps `renderedRoutes` and `docsRoutes`; treat those arrays as the source of truth for smoke-route inventory.
|
|
- `apps/website/tests/smoke/interaction.spec.ts` already asserts desktop keyboard reachability and mobile navigation visibility for the docs link; updating the docs href there is part of the route migration.
|
|
|
|
## Static Claim Scan Commands
|
|
|
|
- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'repo-real foundation' -e 'productization gap' -e 'capability registry' -e 'provider-neutral artifact taxonomy' -e 'source family' -e 'detector key' -e 'workspace-first cutover' -e 'route-owned context' -e 'implementation truth' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'NIS2-konform' -e 'in Deutschland gehostet' -e 'no customer data stored' -e 'keine Kundendaten' -e 'keine personenbezogenen Daten' -e 'Google supported' -e 'AWS supported' -e 'multi-cloud supported' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'one-click restore' -e 'immutable backups' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'guarantees audit success' -e 'makes you compliant' apps/website/src apps/website/public 2>/dev/null || true`
|
|
- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'repo-real foundation' -e 'productization gap' -e 'capability registry' -e 'provider-neutral artifact taxonomy' -e 'source family' -e 'detector key' -e 'workspace-first cutover' -e 'route-owned context' -e 'implementation truth' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'NIS2-konform' -e 'in Deutschland gehostet' -e 'no customer data stored' -e 'keine Kundendaten' -e 'keine personenbezogenen Daten' -e 'Google supported' -e 'AWS supported' -e 'multi-cloud supported' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'one-click restore' -e 'immutable backups' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'guarantees audit success' -e 'makes you compliant' apps/website/dist 2>/dev/null || true`
|
|
|
|
## Planned Validation Results Capture
|
|
|
|
Implementation must record:
|
|
|
|
- exact website commands run from the existing root and website package manifests
|
|
- the final docs route matrix for DE and EN
|
|
- whether the final implementation shipped the twelve child pages or a section-only fallback
|
|
- any legacy redirect or alias mapping shipped for the old docs URLs
|
|
- whether canonical metadata support exists and was reused for docs pages, or why FR-034 resolved as N/A
|
|
- nav/footer/docs crosslink changes and any intentionally omitted discovery surfaces
|
|
- static claim scan outcomes in source and generated output
|
|
- browser smoke pass/fail notes for docs landing, child pages, nav/footer links, and related public-page crosslinks on desktop and mobile
|
|
- confirmation that `apps/platform/**` remained untouched
|
|
|
|
### Validation Results
|
|
|
|
- Commands run:
|
|
- `corepack pnpm --filter @tenantatlas/website build`
|
|
- `WEBSITE_PORT=4325 corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts --reporter=dot`
|
|
- `corepack pnpm --filter @tenantatlas/website build && WEBSITE_PORT=4326 corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts -g 'sitemap exposes canonical routes and excludes redirect aliases'`
|
|
- `WEBSITE_PORT=4328 corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts -g '(answers reviewer-facing questions conservatively|explains technical governance concepts in public language)' --reporter=dot`
|
|
- `WEBSITE_PORT=4329 corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts --reporter=dot`
|
|
- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'repo-real foundation' -e 'productization gap' -e 'capability registry' -e 'provider-neutral artifact taxonomy' -e 'source family' -e 'detector key' -e 'workspace-first cutover' -e 'route-owned context' -e 'implementation truth' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'NIS2-konform' -e 'in Deutschland gehostet' -e 'no customer data stored' -e 'keine Kundendaten' -e 'keine personenbezogenen Daten' -e 'Google supported' -e 'AWS supported' -e 'multi-cloud supported' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'one-click restore' -e 'immutable backups' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'guarantees audit success' -e 'makes you compliant' apps/website/src apps/website/public 2>/dev/null || true`
|
|
- `grep -RIn -e 'href="#"' -e 'lorem ipsum' -e 'repo-real foundation' -e 'productization gap' -e 'capability registry' -e 'provider-neutral artifact taxonomy' -e 'source family' -e 'detector key' -e 'workspace-first cutover' -e 'route-owned context' -e 'implementation truth' -e 'DSGVO-konform' -e 'ISO-zertifiziert' -e 'NIS2-konform' -e 'in Deutschland gehostet' -e 'no customer data stored' -e 'keine Kundendaten' -e 'keine personenbezogenen Daten' -e 'Google supported' -e 'AWS supported' -e 'multi-cloud supported' -e 'real-time drift' -e 'automatic remediation' -e 'automatic restore' -e 'one-click restore' -e 'immutable backups' -e 'lueckenlose Evidence' -e 'lueckenlose Evidenz' -e 'gerichtsfeste Nachweise' -e 'guarantees audit success' -e 'makes you compliant' apps/website/dist 2>/dev/null || true`
|
|
- Final docs route matrix:
|
|
- DE: `/docs/`, `/docs/getting-started/`, `/docs/microsoft-365-provider/`, `/docs/permissions-data-access/`, `/docs/data-processing-trust/`, `/docs/policy-evidence/`, `/docs/drift-detection/`, `/docs/backups-versioning-recovery/`, `/docs/findings-exceptions-accepted-risk/`, `/docs/review-packs-decisions/`, `/docs/evaluation-pilot/`, `/docs/known-limitations/`, `/docs/faq/`
|
|
- EN: `/en/docs/` plus the same twelve child slugs under `/en/docs/`
|
|
- Shipped docs shape: full bilingual docs landing plus all twelve child pages shipped; no section-only fallback was used.
|
|
- Legacy alias behavior:
|
|
- `/welcome-to-docs/` -> `/docs/`
|
|
- `/guides/intro/` -> `/docs/getting-started/`
|
|
- `/guides/getting-started/` -> `/docs/getting-started/`
|
|
- `/guides/first-project-checklist/` -> `/docs/evaluation-pilot/`
|
|
- `/platform/evidence-review/` -> `/docs/policy-evidence/`
|
|
- `/en/welcome-to-docs/` -> `/en/docs/`
|
|
- `/en/guides/intro/` -> `/en/docs/getting-started/`
|
|
- `/en/guides/getting-started/` -> `/en/docs/getting-started/`
|
|
- `/en/guides/first-project-checklist/` -> `/en/docs/evaluation-pilot/`
|
|
- `/en/platform/evidence-review/` -> `/en/docs/policy-evidence/`
|
|
- Canonical metadata reuse: Starlight page metadata and canonicals are reused for all docs pages; the generated Astro redirect pages emit canonical links to their target docs routes and are excluded from the sitemap.
|
|
- Shipped discovery surfaces:
|
|
- nav `Docs`
|
|
- footer `Docs`
|
|
- homepage docs CTA
|
|
- platform docs CTA
|
|
- trust docs CTA
|
|
- evaluation docs CTA
|
|
- review-packs docs CTA
|
|
- DE and EN use-case docs CTAs
|
|
- contact-page docs handoff
|
|
- Starlight site-title docs link
|
|
- Intentionally omitted discovery changes: no second docs navigation system, no new standalone marketing sections, and no `apps/platform/**` changes.
|
|
- Static claim scan outcomes:
|
|
- `apps/website/src` and `apps/website/public`: no matches
|
|
- `apps/website/dist`: no matches
|
|
- Smoke Coverage close-out:
|
|
- `public-routes.spec.ts`: initial full run reached `540 passed / 2 failed`, then the sitemap exclusion rerun passed `2/2`; the remaining targeted EN claim-route rerun passed `24/24` after copy fixes.
|
|
- `interaction.spec.ts`: initial full run reached `106 passed / 28 failed / 6 skipped`; the targeted docs content rerun passed `44/44` after narrowing heading assertions to the `main` H1, and the final full rerun passed `134/140` with `6` intentional skips.
|
|
- `apps/platform/**` scope confirmation: `git diff --name-only -- apps/platform` returned no changed files.
|
|
|
|
### Success Criteria Proof Notes
|
|
|
|
- **SC-001**: `/docs/` and `/en/docs/` now open with a dedicated docs hero and one-click entry points to every required topic; interaction smoke asserts the landing-page topic links and public handoffs are visible.
|
|
- **SC-002**: each required category is reachable from the docs landing page in one click through the explicit topic card grid and sidebar order.
|
|
- **SC-003**: reviewer-oriented pages, technical-concept pages, nav/footer links, and contextual discovery CTAs are covered by route and interaction smoke without placeholder links or fake download artifacts.
|
|
- **SC-004**: source, public assets, rendered output, and browser smoke all passed the forbidden-claim and placeholder-link checks after copy hardening on recovery/drift phrasing.
|
|
- **SC-005**: desktop and mobile browser smoke passed for public routes and interactions, including docs landing, localized child pages, discovery CTAs, and legacy starter-route continuity.
|
|
- **SC-006**: implementation stayed inside `apps/website/**` plus feature-spec artifacts; `apps/platform/**` remained untouched.
|
|
|
|
### Quickstart Validation
|
|
|
|
- `quickstart.md` remained aligned with the implemented route family, validation commands, legacy alias expectations, and static scan command set.
|
|
- Local `WEBSITE_PORT=432x` overrides were used only to avoid preview port collisions during Playwright runs; no documentation drift or script-contract drift was introduced.
|
|
|
|
## Complexity Tracking
|
|
|
|
No constitutional violations and no bloat-triggering additions are planned for this feature.
|
|
|
|
## Proportionality Review
|
|
|
|
N/A for this implementation plan. The feature introduces no new enum/status family, DTO/presenter/envelope layer, persisted entity/table/artifact, interface/contract/registry/resolver, taxonomy system, or cross-domain UI framework. It only rehomes and expands the existing public docs surface inside the current website docs infrastructure. |