TenantAtlas/specs/410-public-docs-ia/quickstart.md

# Quickstart: Public Docs & Knowledge Base IA

## 1. Confirm Scope And Current Docs Shape

Work from repository root:

```bash
cd /Users/ahmeddarrazi/Documents/projects/wt-website
pwd
git status --short --branch
cat package.json
cat pnpm-workspace.yaml 2>/dev/null || true
cat apps/website/package.json
find apps/website -maxdepth 4 -type f | sort | sed -n '1,320p'
```

Scope boundaries:

- Allowed: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/**`
- Allowed: `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/410-public-docs-ia/**`
- Forbidden: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform/**`
- Forbidden: root workspace script contract changes

## 2. Update The Docs Base Route

Current repo truth:

- Starlight is already enabled in `apps/website/astro.config.mjs`
- docs content already lives in `apps/website/src/content/docs/**`
- current public starter docs routes are rooted at `/welcome-to-docs/`, `/guides/*`, and `/platform/evidence-review/`

Target docs route family:

- `/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/docs/` plus the same child slugs under `/en/docs/`

Prefer shared English slugs in both locales; localize labels, not route names.

## 3. Replace The Starter Docs Content With The New IA

Expected docs content locations:

```text
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/index.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/getting-started.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/microsoft-365-provider.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/permissions-data-access.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/data-processing-trust.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/policy-evidence.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/drift-detection.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/backups-versioning-recovery.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/review-packs-decisions.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/evaluation-pilot.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/known-limitations.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/faq.mdx
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs/en/*.mdx
```

Each page must include:

- localized title and metadata
- short intro
- `What this page covers`
- 3-6 content sections
- real related links only
- bounded, claim-safe wording

## 4. Make Sidebar Ordering Explicit

Update `apps/website/astro.config.mjs` so the docs sidebar no longer depends on starter `guides/` autogeneration for the primary IA.

Requirements:

- expose the twelve required topic pages in the approved order
- keep DE/EN labels localized
- retain the existing custom Starlight shell components
- avoid inventing a second docs navigation system

## 5. Retarget Global Docs Entry Points

Update the existing global docs links in:

```text
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/sections/navbar&footer/Navbar.astro
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/sections/navbar&footer/FooterSection.astro
```

Expected result:

- nav `Docs` -> `/docs/` and `/en/docs/`
- footer `Docs` -> `/docs/` and `/en/docs/`
- homepage/platform/trust/evaluation crosslinks added where current sections support a real link cleanly
- review-packs and use-case crosslinks added only if they read clearly in the current layout

## 6. Preserve Legacy Public URLs

Ensure the current public docs routes keep working through redirects or equivalent aliases:

- `/welcome-to-docs/`
- `/guides/intro/`
- `/guides/getting-started/`
- `/guides/first-project-checklist/`
- `/platform/evidence-review/`
- English equivalents under `/en/...`

Map them to the new docs routes from the plan/data model. Do not keep the old and new docs trees as permanent duplicate truth.

## 7. Update Smoke Coverage

Expected files:

```text
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke/public-routes.spec.ts
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke/interaction.spec.ts
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke/smoke-helpers.ts
```

Cover:

- `/docs/` and `/en/docs/`
- all twelve localized docs topic routes
- metadata for docs landing and child pages
- nav/footer docs href migration
- legacy docs URL continuity if redirects or aliases ship
- homepage/platform/trust/evaluation crosslinks as implemented
- no placeholder links
- no forbidden public claims
- no horizontal overflow
- readable desktop/mobile layout

## 8. Run Validation

Run only scripts that currently exist:

```bash
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
```

Optional if formatting was touched broadly:

```bash
corepack pnpm --filter @tenantatlas/website format:check
```

Run the static scan from the plan against source:

```bash
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
```

If generated output is committed, scan `apps/website/dist` as well.

## 9. Browser Smoke

If local preview is available:

```bash
WEBSITE_PORT=${WEBSITE_PORT:-4321} corepack pnpm --filter @tenantatlas/website preview
```

Verify:

- `/docs/` loads
- `/en/docs/` loads
- all required child pages load
- nav/footer docs links work
- homepage/platform/trust/evaluation crosslinks work if implemented
- any review-packs/use-case docs teaser links work if implemented
- legacy docs URLs resolve intentionally
- permissions docs do not invent a permission matrix
- trust docs do not overclaim legal/security status
- policy evidence and drift docs stay public-facing
- backups/recovery docs do not imply one-click restore
- provider docs do not imply Google/AWS live support
- known limitations and FAQ remain clear and non-defensive
- desktop and mobile layouts remain readable