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:

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:

/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:

/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:

/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:

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:

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

Run the static scan from the plan against source:

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:

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