From af5fa3034133942a4fcd43d5ba3cfdd975795869 Mon Sep 17 00:00:00 2001 From: ahmido Date: Sun, 31 May 2026 21:11:07 +0000 Subject: [PATCH] 410: add public docs information architecture (#412) 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 Reviewed-on: https://git.cloudarix.de/ahmido/TenantAtlas/pulls/412 --- .github/agents/copilot-instructions.md | 3 +- apps/website/astro.config.mjs | 47 ++- .../src/components/pages/HomePage.astro | 6 +- .../src/components/pages/PlatformPage.astro | 6 +- .../components/pages/ReviewPacksPage.astro | 6 +- .../src/components/pages/TrustPage.astro | 6 +- .../sections/misc/ContactSection.astro | 2 +- .../components/ui/starlight/SiteTitle.astro | 2 +- .../docs/backups-versioning-recovery.mdx | 40 ++ .../content/docs/data-processing-trust.mdx | 40 ++ .../src/content/docs/drift-detection.mdx | 40 ++ .../docs/en/backups-versioning-recovery.mdx | 40 ++ .../content/docs/en/data-processing-trust.mdx | 40 ++ .../src/content/docs/en/drift-detection.mdx | 40 ++ .../src/content/docs/en/evaluation-pilot.mdx | 40 ++ apps/website/src/content/docs/en/faq.mdx | 42 ++ .../en/findings-exceptions-accepted-risk.mdx | 38 ++ .../src/content/docs/en/getting-started.mdx | 41 ++ .../en/guides/first-project-checklist.mdx | 18 - .../docs/en/guides/getting-started.mdx | 21 - .../src/content/docs/en/guides/intro.mdx | 20 - apps/website/src/content/docs/en/index.mdx | 54 +++ .../src/content/docs/en/known-limitations.mdx | 40 ++ .../docs/en/microsoft-365-provider.mdx | 40 ++ .../docs/en/permissions-data-access.mdx | 40 ++ .../docs/en/platform/evidence-review.mdx | 19 - .../src/content/docs/en/policy-evidence.mdx | 40 ++ .../docs/en/review-packs-decisions.mdx | 40 ++ .../src/content/docs/en/welcome-to-docs.mdx | 31 -- .../src/content/docs/evaluation-pilot.mdx | 40 ++ apps/website/src/content/docs/faq.mdx | 42 ++ .../findings-exceptions-accepted-risk.mdx | 38 ++ .../src/content/docs/getting-started.mdx | 41 ++ .../docs/guides/first-project-checklist.mdx | 18 - .../content/docs/guides/getting-started.mdx | 21 - .../website/src/content/docs/guides/intro.mdx | 20 - apps/website/src/content/docs/index.mdx | 54 +++ .../src/content/docs/known-limitations.mdx | 40 ++ .../content/docs/microsoft-365-provider.mdx | 40 ++ .../content/docs/permissions-data-access.mdx | 40 ++ .../content/docs/platform/evidence-review.mdx | 19 - .../src/content/docs/policy-evidence.mdx | 40 ++ .../content/docs/review-packs-decisions.mdx | 40 ++ .../src/content/docs/welcome-to-docs.mdx | 31 -- apps/website/src/data_files/site-copy.ts | 68 +++- .../en/guides/first-project-checklist.astro | 3 + .../src/pages/en/guides/getting-started.astro | 3 + apps/website/src/pages/en/guides/intro.astro | 3 + .../pages/en/platform/evidence-review.astro | 3 + .../src/pages/en/use-cases/mittelstand.astro | 6 +- apps/website/src/pages/en/use-cases/msp.astro | 6 +- .../src/pages/en/welcome-to-docs.astro | 3 + .../guides/first-project-checklist.astro | 3 + .../src/pages/guides/getting-started.astro | 3 + apps/website/src/pages/guides/intro.astro | 3 + .../src/pages/platform/evidence-review.astro | 3 + .../src/pages/use-cases/mittelstand.astro | 6 +- apps/website/src/pages/use-cases/msp.astro | 6 +- apps/website/src/pages/welcome-to-docs.astro | 3 + apps/website/tests/smoke/interaction.spec.ts | 272 ++++++++++++- .../website/tests/smoke/public-routes.spec.ts | 279 +++++++++++-- apps/website/tests/smoke/smoke-helpers.ts | 103 ++++- .../checklists/requirements.md | 36 ++ .../contracts/public-docs-routes.openapi.yaml | 379 ++++++++++++++++++ specs/410-public-docs-ia/data-model.md | 154 +++++++ specs/410-public-docs-ia/plan.md | 375 +++++++++++++++++ specs/410-public-docs-ia/quickstart.md | 224 +++++++++++ specs/410-public-docs-ia/research.md | 96 +++++ specs/410-public-docs-ia/spec.md | 334 +++++++++++++++ specs/410-public-docs-ia/tasks.md | 252 ++++++++++++ 70 files changed, 3696 insertions(+), 296 deletions(-) create mode 100644 apps/website/src/content/docs/backups-versioning-recovery.mdx create mode 100644 apps/website/src/content/docs/data-processing-trust.mdx create mode 100644 apps/website/src/content/docs/drift-detection.mdx create mode 100644 apps/website/src/content/docs/en/backups-versioning-recovery.mdx create mode 100644 apps/website/src/content/docs/en/data-processing-trust.mdx create mode 100644 apps/website/src/content/docs/en/drift-detection.mdx create mode 100644 apps/website/src/content/docs/en/evaluation-pilot.mdx create mode 100644 apps/website/src/content/docs/en/faq.mdx create mode 100644 apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx create mode 100644 apps/website/src/content/docs/en/getting-started.mdx delete mode 100644 apps/website/src/content/docs/en/guides/first-project-checklist.mdx delete mode 100644 apps/website/src/content/docs/en/guides/getting-started.mdx delete mode 100644 apps/website/src/content/docs/en/guides/intro.mdx create mode 100644 apps/website/src/content/docs/en/index.mdx create mode 100644 apps/website/src/content/docs/en/known-limitations.mdx create mode 100644 apps/website/src/content/docs/en/microsoft-365-provider.mdx create mode 100644 apps/website/src/content/docs/en/permissions-data-access.mdx delete mode 100644 apps/website/src/content/docs/en/platform/evidence-review.mdx create mode 100644 apps/website/src/content/docs/en/policy-evidence.mdx create mode 100644 apps/website/src/content/docs/en/review-packs-decisions.mdx delete mode 100644 apps/website/src/content/docs/en/welcome-to-docs.mdx create mode 100644 apps/website/src/content/docs/evaluation-pilot.mdx create mode 100644 apps/website/src/content/docs/faq.mdx create mode 100644 apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx create mode 100644 apps/website/src/content/docs/getting-started.mdx delete mode 100644 apps/website/src/content/docs/guides/first-project-checklist.mdx delete mode 100644 apps/website/src/content/docs/guides/getting-started.mdx delete mode 100644 apps/website/src/content/docs/guides/intro.mdx create mode 100644 apps/website/src/content/docs/index.mdx create mode 100644 apps/website/src/content/docs/known-limitations.mdx create mode 100644 apps/website/src/content/docs/microsoft-365-provider.mdx create mode 100644 apps/website/src/content/docs/permissions-data-access.mdx delete mode 100644 apps/website/src/content/docs/platform/evidence-review.mdx create mode 100644 apps/website/src/content/docs/policy-evidence.mdx create mode 100644 apps/website/src/content/docs/review-packs-decisions.mdx delete mode 100644 apps/website/src/content/docs/welcome-to-docs.mdx create mode 100644 apps/website/src/pages/en/guides/first-project-checklist.astro create mode 100644 apps/website/src/pages/en/guides/getting-started.astro create mode 100644 apps/website/src/pages/en/guides/intro.astro create mode 100644 apps/website/src/pages/en/platform/evidence-review.astro create mode 100644 apps/website/src/pages/en/welcome-to-docs.astro create mode 100644 apps/website/src/pages/guides/first-project-checklist.astro create mode 100644 apps/website/src/pages/guides/getting-started.astro create mode 100644 apps/website/src/pages/guides/intro.astro create mode 100644 apps/website/src/pages/platform/evidence-review.astro create mode 100644 apps/website/src/pages/welcome-to-docs.astro create mode 100644 specs/410-public-docs-ia/checklists/requirements.md create mode 100644 specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml create mode 100644 specs/410-public-docs-ia/data-model.md create mode 100644 specs/410-public-docs-ia/plan.md create mode 100644 specs/410-public-docs-ia/quickstart.md create mode 100644 specs/410-public-docs-ia/research.md create mode 100644 specs/410-public-docs-ia/spec.md create mode 100644 specs/410-public-docs-ia/tasks.md diff --git a/.github/agents/copilot-instructions.md b/.github/agents/copilot-instructions.md index a9204ca1..06dc3844 100644 --- a/.github/agents/copilot-instructions.md +++ b/.github/agents/copilot-instructions.md @@ -270,6 +270,7 @@ ## Active Technologies - N/A - static website content and generated build output only; no database or product persistence (404-public-content-messaging) - TypeScript 6.0.3 and Astro 6.3.3 content/runtime files + Astro, Playwright, Tailwind CSS v4 (`@tailwindcss/vite`), Starlight docs stack (408-review-evidence-decision) - N/A (static public website content only) (408-review-evidence-decision) +- TypeScript 6.0.3, Astro 6.3.3, MDX content files rendered through Starlight 0.39.2 + Astro, `@astrojs/starlight`, `@astrojs/mdx`, Tailwind CSS v4 via `@tailwindcss/vite`, Playwright 1.59.1 (410-public-docs-ia) - PHP 8.4.15 (feat/005-bulk-operations) @@ -304,9 +305,9 @@ ## Code Style PHP 8.4.15: Follow standard conventions ## Recent Changes +- 410-public-docs-ia: Added TypeScript 6.0.3, Astro 6.3.3, MDX content files rendered through Starlight 0.39.2 + Astro, `@astrojs/starlight`, `@astrojs/mdx`, Tailwind CSS v4 via `@tailwindcss/vite`, Playwright 1.59.1 - 409-evaluation-procurement-rollout: Added TypeScript 6.0.3 and Astro 6.3.3 content/runtime files + Astro, Playwright, Tailwind CSS v4 (`@tailwindcss/vite`), Starlight docs stack - 408-review-evidence-decision: Added TypeScript 6.0.3 and Astro 6.3.3 content/runtime files + Astro, Playwright, Tailwind CSS v4 (`@tailwindcss/vite`), Starlight docs stack -- 404-public-content-messaging: Added TypeScript 6.0.3, Astro 6.3.3, Node.js >=20.0.0, pnpm 10.33.0 + Astro, `@astrojs/starlight`, `@astrojs/sitemap`, `@astrojs/mdx`, Tailwind CSS v4, `@tailwindcss/vite`, Preline 4, Lenis, GSAP, Sharp, Playwrigh ### Pre-production compatibility check diff --git a/apps/website/astro.config.mjs b/apps/website/astro.config.mjs index 7bf81bd2..dfb4b240 100644 --- a/apps/website/astro.config.mjs +++ b/apps/website/astro.config.mjs @@ -11,11 +11,21 @@ const redirectOnlyPaths = new Set([ '/services/', '/blog/', '/insights/', + '/welcome-to-docs/', + '/guides/intro/', + '/guides/getting-started/', + '/guides/first-project-checklist/', + '/platform/evidence-review/', '/en/product/', '/en/products/', '/en/services/', '/en/blog/', '/en/insights/', + '/en/welcome-to-docs/', + '/en/guides/intro/', + '/en/guides/getting-started/', + '/en/guides/first-project-checklist/', + '/en/platform/evidence-review/', ]); const isRedirectOnlySitemapPath = page => { @@ -67,19 +77,44 @@ export default defineConfig({ // https://starlight.astro.build/guides/sidebar/ sidebar: [ { - label: 'Evaluierungsleitfaeden', + label: 'Dokumentationsstart', translations: { - en: 'Evaluation Guides', + en: 'Documentation Start', }, - items: [{ autogenerate: { directory: 'guides' } }], + items: ['docs', 'docs/getting-started', 'docs/evaluation-pilot'], }, { - label: 'Plattform-Notizen', + label: 'Provider & Zugriff', translations: { - en: 'Platform Notes', + en: 'Provider & Access', }, items: [ - { label: 'Evidence Review', link: 'platform/evidence-review/' }, + 'docs/microsoft-365-provider', + 'docs/permissions-data-access', + 'docs/data-processing-trust', + ], + }, + { + label: 'Evidence & Recovery', + translations: { + en: 'Evidence & Recovery', + }, + items: [ + 'docs/policy-evidence', + 'docs/drift-detection', + 'docs/backups-versioning-recovery', + 'docs/findings-exceptions-accepted-risk', + ], + }, + { + label: 'Review & Grenzen', + translations: { + en: 'Review & Boundaries', + }, + items: [ + 'docs/review-packs-decisions', + 'docs/known-limitations', + 'docs/faq', ], }, ], diff --git a/apps/website/src/components/pages/HomePage.astro b/apps/website/src/components/pages/HomePage.astro index 1fdf0afa..a738e5ec 100644 --- a/apps/website/src/components/pages/HomePage.astro +++ b/apps/website/src/components/pages/HomePage.astro @@ -217,11 +217,15 @@ const copy = siteCopy[locale].home; > {siteCopy[locale].evaluation.discovery.homepageContent}

-
+
+
diff --git a/apps/website/src/components/pages/PlatformPage.astro b/apps/website/src/components/pages/PlatformPage.astro index 2137d400..5a3b926d 100644 --- a/apps/website/src/components/pages/PlatformPage.astro +++ b/apps/website/src/components/pages/PlatformPage.astro @@ -188,11 +188,15 @@ const canonicalPath = localizedPath('/platform', locale); > {siteCopy[locale].evaluation.discovery.platformContent}

-
+
+
diff --git a/apps/website/src/components/pages/ReviewPacksPage.astro b/apps/website/src/components/pages/ReviewPacksPage.astro index 86a3eb88..2673a3cf 100644 --- a/apps/website/src/components/pages/ReviewPacksPage.astro +++ b/apps/website/src/components/pages/ReviewPacksPage.astro @@ -533,11 +533,15 @@ const canonicalPath = localizedPath('/platform/review-packs', locale); > {siteCopy[locale].evaluation.discovery.reviewPackContent}

-
+
+
diff --git a/apps/website/src/components/pages/TrustPage.astro b/apps/website/src/components/pages/TrustPage.astro index b5264915..ba4a3c57 100644 --- a/apps/website/src/components/pages/TrustPage.astro +++ b/apps/website/src/components/pages/TrustPage.astro @@ -344,11 +344,15 @@ const statusLabel = (key: string) => statusByKey.get(key)?.label ?? key; > {siteCopy[locale].evaluation.discovery.trustContent}

-
+
+
diff --git a/apps/website/src/components/sections/misc/ContactSection.astro b/apps/website/src/components/sections/misc/ContactSection.astro index 356b5adf..11f6ea34 100644 --- a/apps/website/src/components/sections/misc/ContactSection.astro +++ b/apps/website/src/components/sections/misc/ContactSection.astro @@ -92,7 +92,7 @@ const copy = siteCopy[locale].contact; content={copy.blocks.docsContent} isLinkVisible={true} linkTitle={copy.blocks.docsLink} - linkURL={localizeHref('/welcome-to-docs/', locale)} + linkURL={localizeHref('/docs/', locale)} isArrowVisible={true} > diff --git a/apps/website/src/components/ui/starlight/SiteTitle.astro b/apps/website/src/components/ui/starlight/SiteTitle.astro index b0881f1d..e76d0a76 100644 --- a/apps/website/src/components/ui/starlight/SiteTitle.astro +++ b/apps/website/src/components/ui/starlight/SiteTitle.astro @@ -3,7 +3,7 @@ import { getLocaleFromPath, localizeHref } from '@/i18n'; const locale = getLocaleFromPath(Astro.url.pathname); const home = localizeHref('/', locale); -const docs = localizeHref('/welcome-to-docs/', locale); +const docs = localizeHref('/docs/', locale); --- diff --git a/apps/website/src/content/docs/backups-versioning-recovery.mdx b/apps/website/src/content/docs/backups-versioning-recovery.mdx new file mode 100644 index 00000000..0841517a --- /dev/null +++ b/apps/website/src/content/docs/backups-versioning-recovery.mdx @@ -0,0 +1,40 @@ +--- +title: Backups, Versionierung & Recovery-Kontext +slug: docs/backups-versioning-recovery +description: Wie Tenantial Backups, Versionierung und Recovery-Kontext als Grundlage für vorsichtige Entscheidungen beschreibt, ohne automatische Wiederherstellung zu versprechen. +editUrl: false +lastUpdated: false +--- + +Backups und Versionierung sind in Tenantial nicht Selbstzweck. Sie schaffen den Kontext, auf dessen Basis Teams verstehen können, welcher bekannte Zustand gesichert ist und wie defensiv eine Recovery-Frage bewertet werden sollte. + +## What this page covers + +- warum bekannte Zustände und Versionierung für Governance relevant sind +- wie Recovery-Kontext von einer eigentlichen Ausführung zu trennen ist +- welche Buyer-Fragen durch diese Einordnung früher beantwortet werden können + +## Warum Versionierung hier wichtig ist + +Wenn Teams nicht mehr wissen, welcher Konfigurationsstand zuletzt bewusst bewertet wurde, wird jede Diskussion über Change oder Recovery unsauber. Versionierung hält genau diese Referenzpunkte lesbar. + +## Was Recovery-Kontext bedeutet + +Recovery-Kontext heißt, dass Scope, bekannte Ausgangslage, Konflikte und Auswirkungen vor einer sensiblen Aktion verständlich werden. Die öffentliche Story verspricht daraus weder eine automatische Wiederherstellung noch eine risikofreie Abkürzung. + +## Sinnvolle Fragen für Buyer und Reviewer + +- Welche bekannten Stände sollten für Review oder Pilot nachvollziehbar bleiben? +- Welche Unterschiede machen Recovery-Fragen überhaupt relevant? +- Welche Rollen müssen vor einer sensiblen Entscheidung Scope und Auswirkungen verstehen? + +## Grenzen dieser Aussage + +Diese Seite beschreibt keine Ein-Klick-Wiederherstellung und keinen Erfolgsgarant. Sie erklärt nur, warum bekannte Zustände und Versionierung zu vorsichtigeren Entscheidungen führen können. + +## Related links + +- [Policy Evidence](/docs/policy-evidence/) +- [Drift Detection](/docs/drift-detection/) +- [Findings, Ausnahmen & Accepted Risk](/docs/findings-exceptions-accepted-risk/) +- [Evaluierung & Pilot](/docs/evaluation-pilot/) \ No newline at end of file diff --git a/apps/website/src/content/docs/data-processing-trust.mdx b/apps/website/src/content/docs/data-processing-trust.mdx new file mode 100644 index 00000000..9f5b764b --- /dev/null +++ b/apps/website/src/content/docs/data-processing-trust.mdx @@ -0,0 +1,40 @@ +--- +title: Datenverarbeitung & Trust +slug: docs/data-processing-trust +description: Öffentliche Einordnung von Datenschutz-, Dokumenten- und Trust-Fragen rund um Tenantial ohne unbestätigte Compliance- oder Hosting-Claims. +editUrl: false +lastUpdated: false +--- + +Trust-Fragen werden auf der öffentlichen Website bewusst konservativ beantwortet. Ziel ist nicht, jedes Detail vorwegzunehmen, sondern die richtigen Themen sichtbar zu machen: Dokumentenstatus, Datenkategorien, Support-Zugriff und sichere Handoffs. + +## What this page covers + +- welche Trust- und Datenschutzfragen heute öffentlich beantwortet werden +- wie Dokumentenstatus und Anfragepfade gerahmt werden +- warum sensible Aussagen lieber als Status statt als Marketingclaim formuliert werden + +## Welche Themen hier sinnvoll zusammenlaufen + +Datenschutz, Datenverarbeitung, Support-Zugriff und Dokumentenbereitschaft gehören in dieselbe Gesprächsfamilie. Wer einen Pilot vorbereitet, will wissen, welche Antworten schon dokumentiert sind und welche bewusst über echte Kontaktwege laufen. + +## Dokumente und Anfragepfade + +Tenantial verweist bei DPA, TOM, Subprozessoren oder tieferen Security-Fragen auf reale Handoffs. Das hält die öffentliche Story belastbar und verhindert, dass aus einer Marketingseite plötzlich eine Sammlung unbestätigter Dokumentversprechen wird. + +## Wie konservative Sprache hilft + +- dokumentiert, auf Anfrage oder in Vorbereitung ist hilfreicher als pauschale Zertifizierungsbehauptungen +- Statussprache macht Grenzen sichtbar, ohne das Gespräch abzuwürgen +- Procurement und Security können dieselbe Aussagebasis nutzen wie Buyer und Delivery + +## Grenzen dieser Seite + +Diese Seite ersetzt weder juristische Beratung noch ein formales Security-Review. Sie zeigt nur, wie Tenantial die relevanten Fragen öffentlich und nachvollziehbar einordnet. + +## Related links + +- [Berechtigungen & Datenzugriff](/docs/permissions-data-access/) +- [Bekannte Grenzen](/docs/known-limitations/) +- [FAQ](/docs/faq/) +- [Vertrauen, Datenschutz & Security](/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/drift-detection.mdx b/apps/website/src/content/docs/drift-detection.mdx new file mode 100644 index 00000000..5fc691d3 --- /dev/null +++ b/apps/website/src/content/docs/drift-detection.mdx @@ -0,0 +1,40 @@ +--- +title: Drift Detection +slug: docs/drift-detection +description: Wie Tenantial Drift Detection als lesbare Veränderung zwischen bekannten Zuständen erklärt, ohne daraus Live-Diagnostik oder automatische Korrektur zu versprechen. +editUrl: false +lastUpdated: false +--- + +Drift Detection bedeutet in Tenantial, dass relevante Veränderungen zwischen bekannten Zuständen sichtbar und besprechbar werden. Die öffentliche Story geht dabei bewusst von lesbarer Priorisierung aus, nicht von ununterbrochener Hintergrunddiagnostik. + +## What this page covers + +- wie Drift im Review- und Governance-Kontext verstanden wird +- welche Fragen Drift für Buyer, Operatoren und Reviewer beantwortet +- wo die Grenze zu Live-Monitoring oder automatischer Korrektur verläuft + +## Was Drift hier praktisch meint + +Drift macht sichtbar, wo Konfigurationen nicht mehr dem bekannten Referenzstand entsprechen. Das ist vor allem dann wertvoll, wenn Teams Reviews vorbereiten, Risiken priorisieren oder Recovery-Kontext sauber erklären müssen. + +## Welche Fragen dadurch leichter werden + +- Wo haben sich relevante Konfigurationen seit dem letzten bekannten Stand verändert? +- Welche Unterschiede verdienen eine Review- oder Management-Entscheidung? +- Wo braucht ein Team mehr Evidence oder klarere Begründung, bevor es weitergeht? + +## Warum die Formulierung bewusst vorsichtig bleibt + +Die öffentliche Website spricht nicht über sekundenaktuelle Live-Diagnostik. Sie beschreibt Drift als lesbare Veränderung zwischen bekannten Zuständen, damit keine Erwartung an permanente Echtzeitüberwachung oder autonome Remediation entsteht. + +## Grenzen dieser Seite + +Diese Seite erklärt keine Alerting-Engine und kein permanentes Monitoring-System. Sie beschreibt nur, wie Drift in Tenantial als Review-Arbeit verständlich wird. + +## Related links + +- [Policy Evidence](/docs/policy-evidence/) +- [Backups, Versionierung & Recovery-Kontext](/docs/backups-versioning-recovery/) +- [Findings, Ausnahmen & Accepted Risk](/docs/findings-exceptions-accepted-risk/) +- [Plattform](/platform) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/backups-versioning-recovery.mdx b/apps/website/src/content/docs/en/backups-versioning-recovery.mdx new file mode 100644 index 00000000..1ac2f75b --- /dev/null +++ b/apps/website/src/content/docs/en/backups-versioning-recovery.mdx @@ -0,0 +1,40 @@ +--- +title: Backups, Versioning & Recovery Context +slug: en/docs/backups-versioning-recovery +description: How Tenantial describes backups, versioning, and recovery context as support for cautious decisions without promising restore automation. +editUrl: false +lastUpdated: false +--- + +Backups and versioning are not an end in themselves in Tenantial. They create the context that helps teams understand which known state is protected and how defensively a recovery question should be evaluated. + +## What this page covers + +- why known states and versioning matter in governance work +- how recovery context should be separated from actual execution +- which buyer questions can be answered earlier through this framing + +## Why versioning matters here + +If teams no longer know which configuration state was last reviewed consciously, every change or recovery discussion becomes weaker. Versioning keeps those reference points readable. + +## What recovery context means + +Recovery context means that scope, known starting point, conflicts, and likely impact become understandable before a sensitive action is taken. The public story does not turn that into a promise of restore automation or a risk-free shortcut. + +## Useful questions for buyers and reviewers + +- Which known states should remain explainable for review or pilot work? +- Which differences make a recovery question relevant in the first place? +- Which roles need to understand scope and impact before a sensitive decision is made? + +## Boundaries of this page + +This page does not describe push-button restore and does not imply certain recovery outcomes. It only explains why known states and versioning can support more cautious decisions. + +## Related links + +- [Policy evidence](/en/docs/policy-evidence/) +- [Drift detection](/en/docs/drift-detection/) +- [Findings, exceptions & accepted risk](/en/docs/findings-exceptions-accepted-risk/) +- [Evaluation & pilot](/en/docs/evaluation-pilot/) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/data-processing-trust.mdx b/apps/website/src/content/docs/en/data-processing-trust.mdx new file mode 100644 index 00000000..0b47786c --- /dev/null +++ b/apps/website/src/content/docs/en/data-processing-trust.mdx @@ -0,0 +1,40 @@ +--- +title: Data Processing & Trust +slug: en/docs/data-processing-trust +description: Public framing for privacy, document readiness, and trust questions around Tenantial without unsupported compliance or hosting claims. +editUrl: false +lastUpdated: false +--- + +Trust questions are answered conservatively on the public website. The goal is not to pre-answer every detail, but to surface the right themes clearly: document status, data categories, support access, and safe handoff paths. + +## What this page covers + +- which privacy and trust questions are answered publicly today +- how document status and request paths are framed +- why sensitive statements are better expressed as status than as marketing claims + +## Which themes belong together here + +Privacy, data processing, support access, and document readiness all belong to the same conversation family. Anyone shaping a pilot needs to know which answers are already documented and which ones intentionally move through real contact paths. + +## Documents and request paths + +Tenantial points DPA, TOM, subprocessors, and deeper security questions toward real handoffs. That keeps the public story reliable and avoids turning a marketing page into a collection of unverified document promises. + +## Why conservative language helps + +- documented, on request, or in preparation is more useful than broad certification claims +- status language exposes boundaries without ending the conversation +- procurement and security can work from the same statement set as buyers and delivery teams + +## Boundaries of this page + +This page does not replace legal advice or a formal security review. It only shows how Tenantial frames the relevant questions publicly and credibly. + +## Related links + +- [Permissions & data access](/en/docs/permissions-data-access/) +- [Known limitations](/en/docs/known-limitations/) +- [FAQ](/en/docs/faq/) +- [Trust, privacy & security](/en/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/drift-detection.mdx b/apps/website/src/content/docs/en/drift-detection.mdx new file mode 100644 index 00000000..bdf90290 --- /dev/null +++ b/apps/website/src/content/docs/en/drift-detection.mdx @@ -0,0 +1,40 @@ +--- +title: Drift Detection +slug: en/docs/drift-detection +description: How Tenantial explains drift detection as readable change between known states without implying live diagnostics or self-directed correction. +editUrl: false +lastUpdated: false +--- + +In Tenantial, drift detection means making relevant change between known states visible and discussable. The public story intentionally focuses on readable prioritization rather than uninterrupted background diagnostics. + +## What this page covers + +- how drift is understood in the review and governance context +- which questions drift helps buyers, operators, and reviewers answer +- where the boundary to live monitoring or automatic correction sits + +## What drift means in practice here + +Drift shows where configuration has moved away from a known reference point. That matters most when teams prepare reviews, prioritize risk, or explain recovery context with more clarity. + +## Which questions become easier + +- Where has relevant configuration changed since the last known state? +- Which differences deserve review or management attention? +- Where does a team need more evidence or clearer rationale before moving on? + +## Why the wording stays careful + +The public website does not describe second-by-second live diagnostics. It describes drift as readable change between known states so that no expectation of permanent real-time monitoring or self-directed correction is created. + +## Boundaries of this page + +This page does not describe an alerting engine or always-on monitoring system. It only explains how Tenantial makes drift understandable as review work. + +## Related links + +- [Policy evidence](/en/docs/policy-evidence/) +- [Backups, versioning & recovery context](/en/docs/backups-versioning-recovery/) +- [Findings, exceptions & accepted risk](/en/docs/findings-exceptions-accepted-risk/) +- [Platform](/en/platform) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/evaluation-pilot.mdx b/apps/website/src/content/docs/en/evaluation-pilot.mdx new file mode 100644 index 00000000..55fbae35 --- /dev/null +++ b/apps/website/src/content/docs/en/evaluation-pilot.mdx @@ -0,0 +1,40 @@ +--- +title: Evaluation & Pilot +slug: en/docs/evaluation-pilot +description: How Tenantial demos, trust questions, and a bounded pilot can be turned into a short and credible evaluation path. +editUrl: false +lastUpdated: false +--- + +A good evaluation path does not try to answer everything at once. It shows product value early, surfaces trust and permission questions in time, and keeps the first pilot small enough to stay reviewable. + +## What this page covers + +- how Tenantial frames the path from demo to pilot publicly +- which questions should be answered before a pilot decision is made +- why a small, credible pilot is often better than a large pre-project scope + +## From conversation to a credible decision + +The value of a demo shows up when buyers, security, and delivery teams can see the same core questions: where governance value appears, which trust topics are critical, and which scope is small enough to keep the pilot honest. + +## What should be clear before the pilot + +- which Microsoft 365 areas belong in the first scope +- which permission and trust questions need an answer first +- which roles will evaluate review output, findings, and next steps + +## Why smaller can be stronger + +A focused pilot reduces friction. It allows evidence, drift, review context, and handoffs to be tested against one real question instead of turning evaluation into an early full rollout promise. + +## Boundaries of this page + +This page is not a rollout plan and not a project method. It only frames the public path to a credible pilot decision. + +## Related links + +- [Getting started](/en/docs/getting-started/) +- [Permissions & data access](/en/docs/permissions-data-access/) +- [Data processing & trust](/en/docs/data-processing-trust/) +- [Evaluation & rollout](/en/evaluation) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/faq.mdx b/apps/website/src/content/docs/en/faq.mdx new file mode 100644 index 00000000..e7bd53b6 --- /dev/null +++ b/apps/website/src/content/docs/en/faq.mdx @@ -0,0 +1,42 @@ +--- +title: FAQ +slug: en/docs/faq +description: Short answers to the most common public questions about Tenantial, Microsoft 365 governance, trust, review packs, and pilot preparation. +editUrl: false +lastUpdated: false +--- + +This FAQ gathers the most common public framing questions. It does not replace a deeper product review, but it helps point each reader toward the right next conversation. + +## What this page covers + +- the typical buyer and reviewer questions at a glance +- short framing answers on provider scope, trust, evidence, and pilot preparation +- links to the right deeper page in the docs hub + +## Which questions are answered quickly here + +- **Is Tenantial focused on Microsoft 365 today?** Yes. Additional policy domains remain direction, not confirmed delivery. +- **Are there public answers on permissions and trust?** Yes, in the relevant docs pages and on the trust page. +- **Should a pilot start broad or small?** Usually small, so value and open questions stay reviewable. + +## What this FAQ intentionally does not do + +It does not publish a full permissions matrix, broad certification claims, or restore automation or remediation guarantees. For deeper answers it points to the relevant topic or to a real handoff path. + +## Where to go next from here + +- Start with [Getting started](/en/docs/getting-started/) if you are still orienting yourself. +- Move to [Data processing & trust](/en/docs/data-processing-trust/) if procurement or security questions dominate. +- Use [Review packs & decisions](/en/docs/review-packs-decisions/) if you want to understand the buyer-readable output shape. + +## Boundaries of this page + +This FAQ is intentionally short. Its job is orientation, not to pre-answer every edge case. + +## Related links + +- [Getting started](/en/docs/getting-started/) +- [Evaluation & pilot](/en/docs/evaluation-pilot/) +- [Data processing & trust](/en/docs/data-processing-trust/) +- [Contact](/en/contact) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx b/apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx new file mode 100644 index 00000000..f30aed68 --- /dev/null +++ b/apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx @@ -0,0 +1,38 @@ +--- +title: Findings, Exceptions & Accepted Risk +slug: en/docs/findings-exceptions-accepted-risk +description: How Tenantial frames findings, exceptions, and accepted risk as readable governance work so important decisions do not disappear into side agreements. +editUrl: false +lastUpdated: false +--- + +Findings, exceptions, and accepted risk are where governance becomes concrete. They show whether a team merely notices differences or turns them into decisions that remain readable over time. + +## What this page covers + +- what findings, exceptions, and accepted risk mean in the public Tenantial language +- why these topics should stay connected to evidence and review context +- how buyers can judge pilot maturity from the way they are handled + +## Why findings should be more than a list + +A finding only becomes useful when it is clear why it matters, who is reviewing it, and which evidence or prioritization supports it. Otherwise review work turns into another list of unresolved items. + +## How exceptions stay understandable + +Exceptions need visible context: what was not brought to the target state, why that is acceptable for now, and which follow-up questions remain open. That makes decisions easier to understand for management and audit stakeholders as well. + +## Accepted risk as a conscious choice + +Accepted risk does not mean the risk disappears. It means a team has placed it in visible context with a rationale instead of letting it fade between tickets, screenshots, or private conversations. + +## Boundaries of this page + +This page is not a policy and not an approval workflow. It only explains how Tenantial translates these topics into readable governance language. + +## Related links + +- [Policy evidence](/en/docs/policy-evidence/) +- [Review packs & decisions](/en/docs/review-packs-decisions/) +- [Backups, versioning & recovery context](/en/docs/backups-versioning-recovery/) +- [Review packs](/en/platform/review-packs) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/getting-started.mdx b/apps/website/src/content/docs/en/getting-started.mdx new file mode 100644 index 00000000..9aa25c8c --- /dev/null +++ b/apps/website/src/content/docs/en/getting-started.mdx @@ -0,0 +1,41 @@ +--- +title: Getting Started +slug: en/docs/getting-started +description: How evaluators and buyers can use the Tenantial docs hub to shape a pilot, align stakeholders, and focus Microsoft 365 governance conversations. +editUrl: false +lastUpdated: false +--- + +When you first evaluate Tenantial, a long feature tour is rarely the best place to begin. It is usually more useful to clarify which governance questions are currently messy in Microsoft 365 and which stakeholders will later need to discuss evidence, risks, and next steps. + +## What this page covers + +- which questions should be answered before a demo or pilot +- which teams are typically involved in evaluation, review, and approval +- which information the public website intentionally does not collect or promise + +## Start with the right framing + +Tenantial is designed for readable governance work: known state, visible change, evidence, findings, and the next decision. A strong starting point is therefore a short discussion of which policy families, reviews, or recovery scenarios currently create decision pressure. + +## Useful preparation + +- Note which Microsoft 365 areas repeatedly require manual review work today. +- Capture which roles need to read evidence, weigh risks, and approve follow-up. +- Separate confirmed facts from open trust or security questions so the demo does not become overloaded with assumptions. +- Do not send credentials, secrets, or tenant exports through the public website. + +## What a good first pilot looks like + +A credible pilot stays small, clear, and reviewable. It proves one concrete governance value, answers the most important trust questions early, and leaves later rollout or architecture decisions where they belong. + +## Boundaries of this page + +This page does not replace a permission matrix or a rollout plan. It only helps frame the first decision and structure the next conversation. + +## Related links + +- [Evaluation & pilot](/en/docs/evaluation-pilot/) +- [Microsoft 365 Provider](/en/docs/microsoft-365-provider/) +- [Permissions & data access](/en/docs/permissions-data-access/) +- [Trust, privacy & security](/en/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/guides/first-project-checklist.mdx b/apps/website/src/content/docs/en/guides/first-project-checklist.mdx deleted file mode 100644 index 1e4e582a..00000000 --- a/apps/website/src/content/docs/en/guides/first-project-checklist.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Evaluation Checklist -description: A conservative checklist for early Tenantial evaluation. -sidebar: - label: Evaluation Checklist - order: 3 ---- - -Use this checklist before a product walkthrough: - -- Confirm which Microsoft tenant workflows are in scope. -- Confirm that Microsoft 365 is the current focus and any other providers are treated only as future direction. -- Separate read-only review needs from any future write or restore needs. -- Identify audit and approval expectations. -- Map backup, restore, drift, findings, evidence, auditability, exceptions, and reviews to the buyer questions that matter most. -- Keep trust, compliance, and recovery assumptions listed as items to verify rather than promises already made. -- Plan staging validation before production rollout. -- Keep private tenant data out of public website communication. diff --git a/apps/website/src/content/docs/en/guides/getting-started.mdx b/apps/website/src/content/docs/en/guides/getting-started.mdx deleted file mode 100644 index 7ef2c20f..00000000 --- a/apps/website/src/content/docs/en/guides/getting-started.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Getting Started -description: How evaluators should approach a Tenantial walkthrough. -sidebar: - label: Getting Started - order: 2 ---- - -Start with a scoped conversation about the tenant governance problem you want to solve. The focus is category, risk, decision paths, and review participants, not self-serve access. - -Useful preparation: - -- Identify the Microsoft tenant administration workflows that need review. -- Note which questions are clearly in current Microsoft 365 scope and which provider questions stay future direction. -- List which policy families, backup flows, or restore planning scenarios matter first. -- Decide who needs to participate in evidence review and approval. -- Note which findings, exceptions, or auditability expectations would carry the most decision value. -- Separate trust, compliance, and recovery questions into verified facts versus open review points. -- Avoid sending private tenant exports or credentials through public website contact paths. - -Tenantial walkthroughs should stay focused on review clarity, least-privilege rollout planning, and staging validation before production use. diff --git a/apps/website/src/content/docs/en/guides/intro.mdx b/apps/website/src/content/docs/en/guides/intro.mdx deleted file mode 100644 index 99a5b680..00000000 --- a/apps/website/src/content/docs/en/guides/intro.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Introduction to Tenantial -description: Public introduction to Tenantial's policy-governance model for Microsoft 365. -sidebar: - label: Introduction - order: 1 ---- - -Tenantial is positioned around policy governance for Microsoft 365. Public materials explain how observed state, policy evidence, drift, review, decisions, and audit trail fit together as one reviewable operating model. - -Microsoft 365 is the current public focus. Other providers may appear only as architecture or roadmap direction, not as live supported integrations. - -The website documentation is intentionally public and static. It does not expose live tenant data, operational evidence, private support material, credentials, or connected Microsoft accounts. - -## What to review first - -- How observed state and policy evidence are collected and normalized for review. -- How drift, findings, and review work lead into a traceable decision. -- How Microsoft 365 as the current focus is separated from provider-extensible future direction. -- How controlled recovery stays preview-first work with validation, selective scope, and explicit confirmation. diff --git a/apps/website/src/content/docs/en/index.mdx b/apps/website/src/content/docs/en/index.mdx new file mode 100644 index 00000000..ec87dc59 --- /dev/null +++ b/apps/website/src/content/docs/en/index.mdx @@ -0,0 +1,54 @@ +--- +title: Tenantial documentation +slug: en/docs +description: Tenantial documentation for evaluation, operations, and governance with entry points into provider access, permissions, evidence, drift, recovery context, review packs, and known limitations. +template: splash +editUrl: false +lastUpdated: false +hero: + title: Tenantial documentation + tagline: "Public guidance for evaluation, operations, and governance: from provider access and evidence to drift, review packs, recovery context, and known boundaries." + actions: + - text: Start with the basics + icon: right-arrow + variant: primary + link: /en/docs/getting-started/ + - text: Read the evaluation path + variant: secondary + link: /en/docs/evaluation-pilot/ +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +## Start with the right questions + +This documentation gathers Tenantial's public explanations for Microsoft 365 governance. It is meant to help buyers, reviewers, and technical stakeholders understand value, boundaries, and next-step handoffs before a demo, pilot, or procurement round. + +## What this documentation covers + +- the current Microsoft 365 focus and the provider boundary around it +- permissions, data access, privacy, and trust questions in conservative language +- evidence, drift, recovery context, review packs, and known limitations without inflated automation claims + + + + [Getting started](/en/docs/getting-started/), [Evaluation & pilot](/en/docs/evaluation-pilot/), and [FAQ](/en/docs/faq/) help frame the first conversation and a bounded pilot path. + + + [Microsoft 365 Provider](/en/docs/microsoft-365-provider/), [Permissions & data access](/en/docs/permissions-data-access/), and [Data processing & trust](/en/docs/data-processing-trust/) answer the most common trust and access questions. + + + [Policy evidence](/en/docs/policy-evidence/), [Drift detection](/en/docs/drift-detection/), and [Backups, versioning & recovery context](/en/docs/backups-versioning-recovery/) explain how known states stay readable. + + + [Findings, exceptions & accepted risk](/en/docs/findings-exceptions-accepted-risk/), [Review packs & decisions](/en/docs/review-packs-decisions/), and [Known limitations](/en/docs/known-limitations/) frame the actual review work. + + + +## Related public pages + +- [Platform](/en/platform) +- [Trust, privacy & security](/en/trust) +- [Evaluation & rollout](/en/evaluation) +- [Review packs](/en/platform/review-packs) +- [Contact](/en/contact) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/known-limitations.mdx b/apps/website/src/content/docs/en/known-limitations.mdx new file mode 100644 index 00000000..f10491b9 --- /dev/null +++ b/apps/website/src/content/docs/en/known-limitations.mdx @@ -0,0 +1,40 @@ +--- +title: Known Limitations +slug: en/docs/known-limitations +description: Which limitations Tenantial names clearly on the public website so evaluations do not rest on silent assumptions or inflated marketing claims. +editUrl: false +lastUpdated: false +--- + +Known limitations are not a weakness in themselves. They are part of a credible product story because they help evaluators understand which statements are dependable today and which topics are intentionally not claimed. + +## What this page covers + +- which boundaries Tenantial names explicitly in public language +- why those limitations are useful for buyers, security, and procurement reviewers +- how clearer limitations lead to better next questions + +## Typical boundaries worth naming openly + +Tenantial does not claim generic multi-provider support, autonomous correction, blanket compliance outcomes, or automatic recovery on the public website. Keeping those limits visible makes the story more concrete and testable. + +## Why this clarity helps + +Clear limitations stop a pilot from inheriting silent expectations. Instead, they create room for the right follow-up questions around scope, roles, trust requirements, and credible handoffs. + +## What buyers can infer from this + +- Which statements are dependable today for Microsoft 365? +- Which topics need a later product or architecture decision? +- Where is public documentation enough and where is a real conversation still required? + +## Boundaries of this page + +This page is not a roadmap and not a total exclusion list. It only highlights the main points where conservative language matters more than a broader claim. + +## Related links + +- [Data processing & trust](/en/docs/data-processing-trust/) +- [Microsoft 365 Provider](/en/docs/microsoft-365-provider/) +- [FAQ](/en/docs/faq/) +- [Trust page](/en/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/microsoft-365-provider.mdx b/apps/website/src/content/docs/en/microsoft-365-provider.mdx new file mode 100644 index 00000000..f3c5d888 --- /dev/null +++ b/apps/website/src/content/docs/en/microsoft-365-provider.mdx @@ -0,0 +1,40 @@ +--- +title: Microsoft 365 Provider +slug: en/docs/microsoft-365-provider +description: Why Tenantial currently speaks concretely about Microsoft 365 and keeps other policy domains framed as direction rather than confirmed delivery. +editUrl: false +lastUpdated: false +--- + +Tenantial deliberately speaks concretely about Microsoft 365 on the public website. That makes evaluations more grounded because provider access, policy examples, and buyer questions can all be explained against one real focus. + +## What this page covers + +- why Microsoft 365 is the clear product focus today +- how additional policy domains are positioned in public language +- what evaluators can infer from that for pilot scope and expectation setting + +## Why the focus is named clearly + +Microsoft 365 is the current reference point for provider access, evidence, drift, and review conversations. That keeps the docs concrete enough for buyers and reviewers instead of drifting into abstract multi-provider language. + +## How other domains are framed + +Additional policy domains may be mentioned as prepared direction or future extension. They are not described here as live integrations, complete workflows, or confirmed delivery scope. + +## Useful evaluation questions + +- Which Microsoft 365 areas matter for the first review context? +- Which provider questions need an answer today and which ones are explicitly future-facing? +- Where does your team need concrete trust or permission answers before a pilot is useful? + +## Boundaries of this page + +This page is not a roadmap and not a general platform catalog. It exists to keep the current focus explicit so unsupported provider expectations do not leak into an evaluation. + +## Related links + +- [Permissions & data access](/en/docs/permissions-data-access/) +- [Data processing & trust](/en/docs/data-processing-trust/) +- [Platform](/en/platform) +- [Evaluation & pilot](/en/docs/evaluation-pilot/) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/permissions-data-access.mdx b/apps/website/src/content/docs/en/permissions-data-access.mdx new file mode 100644 index 00000000..59d2a194 --- /dev/null +++ b/apps/website/src/content/docs/en/permissions-data-access.mdx @@ -0,0 +1,40 @@ +--- +title: Permissions & Data Access +slug: en/docs/permissions-data-access +description: Which questions about permissions, roles, and data access should be clarified early in a Tenantial evaluation. +editUrl: false +lastUpdated: false +--- + +Tenantial is not only about visible product surfaces. It also raises the question of which access patterns are actually needed for review, evidence, and governance work. This page helps frame those conversations early. + +## What this page covers + +- which access questions usually appear in trust and security conversations +- how Tenantial thinks about roles, purpose, and environment +- why conservative language is more useful than an invented full matrix + +## Important conversation points + +Buyers and reviewers usually want to know which activities are read-oriented, which are write-oriented, and which should only happen after explicit approval. For that reason, purpose, risk, and environment are more helpful than a flat list of claims. + +## How access is framed usefully + +- read-oriented access is explained by review, evidence, and visibility purpose +- write-oriented or execution steps are treated as deliberate actions that need separate evaluation +- roles, least privilege, and approval remain part of the product conversation instead of being reduced to a UI issue + +## What should be clarified in evaluation + +Identify early which buyer, security, and delivery roles need answers. That keeps the permissions topic from becoming a late blocker after the product value is already clear. + +## Boundaries of this page + +This page does not publish a full Microsoft permission matrix and does not replace a product-specific security review. It only provides the public frame for the right follow-up questions. + +## Related links + +- [Data processing & trust](/en/docs/data-processing-trust/) +- [Microsoft 365 Provider](/en/docs/microsoft-365-provider/) +- [FAQ](/en/docs/faq/) +- [Trust page](/en/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/platform/evidence-review.mdx b/apps/website/src/content/docs/en/platform/evidence-review.mdx deleted file mode 100644 index 7a6c0a30..00000000 --- a/apps/website/src/content/docs/en/platform/evidence-review.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Evidence Review -description: Public platform note for Tenantial evidence-review workflows inside the Microsoft 365 policy-governance model. -sidebar: - label: Evidence Review - order: 1 ---- - -Evidence review is the public framing for Tenantial's policy-governance model for Microsoft 365. This note describes static product concepts and no live tenant connection. - -Microsoft 365 is the current focus of this public story. Other providers may appear only as architecture or roadmap direction. - -The model is intentionally cautious: - -- Observed state is the starting point for review work. -- Policy evidence and snapshots become explicit records for comparison and planning. -- Drift and findings turn into visible review work instead of background diagnostics. -- Decisions, exceptions, and accepted risk stay attributable through audit trail. -- Recovery is planned through preview, validation, selective scope, and explicit confirmation without promising recovery success. diff --git a/apps/website/src/content/docs/en/policy-evidence.mdx b/apps/website/src/content/docs/en/policy-evidence.mdx new file mode 100644 index 00000000..6b745478 --- /dev/null +++ b/apps/website/src/content/docs/en/policy-evidence.mdx @@ -0,0 +1,40 @@ +--- +title: Policy Evidence +slug: en/docs/policy-evidence +description: How Tenantial frames policy evidence as readable review context and why evidence should be more than a loose collection of screenshots or exports. +editUrl: false +lastUpdated: false +--- + +In Tenantial, evidence is not decorative output. It is the part of the review story that makes clear what a finding, exception, or decision is actually grounded in. + +## What this page covers + +- what policy evidence means in the public Tenantial context +- how known states, observations, and review questions are tied together +- why evidence should not be mistaken for broad proof guarantees + +## What evidence means here + +Policy evidence ties together known configuration states, relevant changes, and explanatory context. Its job is to stabilize review conversations, not to dump raw material without framing. + +## What reviewers should be able to read from it + +- which known state acts as the reference point +- which observations or differences matter for the current question +- how findings, accepted risks, and next steps connect back to that basis + +## Why this matters for buyers + +When evidence only exists as a folder of screenshots, the next decision stays unclear. A readable evidence base shortens conversations between delivery, security, management, and audit stakeholders. + +## Boundaries of this page + +This page does not promise gapless or court-proof proof. It only explains how Tenantial frames evidence in its public product narrative as a review aid. + +## Related links + +- [Drift detection](/en/docs/drift-detection/) +- [Review packs & decisions](/en/docs/review-packs-decisions/) +- [Findings, exceptions & accepted risk](/en/docs/findings-exceptions-accepted-risk/) +- [Review packs](/en/platform/review-packs) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/review-packs-decisions.mdx b/apps/website/src/content/docs/en/review-packs-decisions.mdx new file mode 100644 index 00000000..d385bb39 --- /dev/null +++ b/apps/website/src/content/docs/en/review-packs-decisions.mdx @@ -0,0 +1,40 @@ +--- +title: Review Packs & Decisions +slug: en/docs/review-packs-decisions +description: How Tenantial explains review packs as readable decision material and why they should not collapse back into raw exports. +editUrl: false +lastUpdated: false +--- + +Review packs are the buyer-facing form of the same governance truth: known states, evidence, findings, accepted risks, and next steps are ordered so management, delivery, and security teams can work from the same material. + +## What this page covers + +- how review packs translate technical truth into readable decision support +- which building blocks are named publicly for that purpose +- why review packs should not become a second truth next to evidence and findings + +## What comes together in a review pack + +Review packs connect an executive summary, the evidence basis, prioritized findings, accepted risks, and a clear decision summary. Their purpose is to keep a conversation from starting with unframed raw material. + +## Why buyers benefit from this + +When teams only see the same governance state through different screenshots or exports, every decision takes longer. Structured review material makes status, impact, and next steps easier to read. + +## How decisions stay connected + +- evidence remains tied to what it is actually supporting +- findings and accepted risks stay attached to their review context +- the next step remains readable as a management and delivery question + +## Boundaries of this page + +This page does not promise a rigid report format and does not imply a guaranteed download path. It only explains why review packs can be a more useful public shape for the same governance truth. + +## Related links + +- [Policy evidence](/en/docs/policy-evidence/) +- [Findings, exceptions & accepted risk](/en/docs/findings-exceptions-accepted-risk/) +- [Review packs](/en/platform/review-packs) +- [FAQ](/en/docs/faq/) \ No newline at end of file diff --git a/apps/website/src/content/docs/en/welcome-to-docs.mdx b/apps/website/src/content/docs/en/welcome-to-docs.mdx deleted file mode 100644 index 71601374..00000000 --- a/apps/website/src/content/docs/en/welcome-to-docs.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tenantial Docs -head: - - tag: title - content: Tenantial Docs -description: Public notes for understanding Tenantial's policy-governance model for Microsoft 365. -editUrl: false -lastUpdated: false -next: false -hero: - title: Tenantial documentation - tagline: Public notes for observed state, evidence, drift, review, decisions, and audit trail with controlled recovery planning. - actions: - - text: Get started - icon: right-arrow - variant: primary - link: /en/guides/getting-started/ ---- - -import '@styles/starlight_main.css'; -import { Card, CardGrid } from '@astrojs/starlight/components'; - - - - Understand the sequence from observe to evidence, detect, review, decide, and audit before planning a rollout conversation. - - - - Review how Tenantial keeps Microsoft 365 as the current focus, treats other providers as future direction, and keeps trust claims conservative. - - diff --git a/apps/website/src/content/docs/evaluation-pilot.mdx b/apps/website/src/content/docs/evaluation-pilot.mdx new file mode 100644 index 00000000..aca85369 --- /dev/null +++ b/apps/website/src/content/docs/evaluation-pilot.mdx @@ -0,0 +1,40 @@ +--- +title: Evaluierung & Pilot +slug: docs/evaluation-pilot +description: Wie Tenantial-Demos, Trust-Fragen und ein begrenzter Pilot in einen kurzen, belastbaren Evaluierungspfad überführt werden können. +editUrl: false +lastUpdated: false +--- + +Ein guter Evaluierungspfad beantwortet nicht alles auf einmal. Er zeigt früh genug Produktnutzen, bringt Trust- und Berechtigungsfragen an die Oberfläche und hält den ersten Pilot bewusst klein und überprüfbar. + +## What this page covers + +- wie Tenantial den Weg von Demo zu Pilot öffentlich rahmt +- welche Fragen vor einer Pilot-Entscheidung geklärt sein sollten +- warum ein kleiner, glaubwürdiger Pilot oft besser ist als ein großer Vorab-Scope + +## Vom Gespräch zur belastbaren Entscheidung + +Der Nutzen einer Demo entsteht dann, wenn Buyer, Security und Delivery dieselben Kernfragen sehen: Wo entsteht Governance-Mehrwert, welche Trust-Themen sind kritisch und welcher Scope ist klein genug, um einen Pilot sinnvoll zu halten? + +## Was vor dem Pilot klar sein sollte + +- welche Microsoft-365-Bereiche im ersten Scope stehen +- welche Berechtigungs- und Trust-Fragen vorab beantwortet werden müssen +- welche Rollen Review-Ergebnisse, Findings und nächste Schritte bewerten + +## Warum klein besser sein kann + +Ein fokussierter Pilot reduziert Reibung. Er hilft, Evidence, Drift, Review-Kontext und Handoffs an einer realen Fragestellung zu prüfen, statt schon in der Evaluierung einen Vollausbau zu versprechen. + +## Grenzen dieser Seite + +Diese Seite ist kein Rollout-Plan und keine Projektmethodik. Sie rahmt nur den öffentlichen Weg zu einer glaubwürdigen Pilot-Entscheidung. + +## Related links + +- [Erste Schritte](/docs/getting-started/) +- [Berechtigungen & Datenzugriff](/docs/permissions-data-access/) +- [Datenverarbeitung & Trust](/docs/data-processing-trust/) +- [Evaluierung & Rollout](/evaluierung) \ No newline at end of file diff --git a/apps/website/src/content/docs/faq.mdx b/apps/website/src/content/docs/faq.mdx new file mode 100644 index 00000000..56872de9 --- /dev/null +++ b/apps/website/src/content/docs/faq.mdx @@ -0,0 +1,42 @@ +--- +title: FAQ +slug: docs/faq +description: Kurze Antworten auf die häufigsten öffentlichen Fragen zu Tenantial, Microsoft 365 Governance, Trust, Review Packs und Pilotvorbereitung. +editUrl: false +lastUpdated: false +--- + +Diese FAQ bündelt die häufigsten öffentlichen Einordnungsfragen. Sie ersetzt keine tiefe Produktprüfung, hilft aber dabei, den richtigen nächsten Gesprächsschritt zu wählen. + +## What this page covers + +- die typischen Buyer- und Reviewer-Fragen auf einen Blick +- kurze Einordnungen zu Provider, Trust, Evidence und Pilotvorbereitung +- Verweise auf die passende Vertiefung im Docs-Hub + +## Welche Fragen hier schnell beantwortet werden + +- **Ist Tenantial heute auf Microsoft 365 fokussiert?** Ja. Weitere Policy-Domänen bleiben Richtung, nicht bestätigter Lieferstand. +- **Gibt es öffentliche Antworten zu Berechtigungen und Trust?** Ja, in den entsprechenden Docs-Seiten und auf der Trust-Seite. +- **Ist ein Pilot eher groß oder klein zu denken?** Eher klein, damit Nutzen und offene Fragen sauber überprüfbar bleiben. + +## Was diese FAQ bewusst nicht tut + +Sie veröffentlicht keine Vollmatrix zu Berechtigungen, keine pauschalen Zertifizierungsbehauptungen und keine automatische Recovery- oder Remediation-Versprechen. Für tiefergehende Antworten führt sie an die passenden Themen oder an einen echten Handoff. + +## Wie Sie von hier weitergehen können + +- Starten Sie mit [Erste Schritte](/docs/getting-started/), wenn Sie Tenantial erst einordnen wollen. +- Wechseln Sie zu [Datenverarbeitung & Trust](/docs/data-processing-trust/), wenn Procurement- oder Security-Fragen im Vordergrund stehen. +- Nutzen Sie [Review Packs & Entscheidungen](/docs/review-packs-decisions/), wenn Sie die buyer-nahe Unterlagenform verstehen wollen. + +## Grenzen dieser Seite + +Die FAQ ist absichtlich kurz. Sie dient der Orientierung und verweist auf die passende Vertiefung statt jede Sonderfrage vorwegzunehmen. + +## Related links + +- [Erste Schritte](/docs/getting-started/) +- [Evaluierung & Pilot](/docs/evaluation-pilot/) +- [Datenverarbeitung & Trust](/docs/data-processing-trust/) +- [Kontakt](/contact) \ No newline at end of file diff --git a/apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx b/apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx new file mode 100644 index 00000000..8f2bc740 --- /dev/null +++ b/apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx @@ -0,0 +1,38 @@ +--- +title: Findings, Ausnahmen & Accepted Risk +slug: docs/findings-exceptions-accepted-risk +description: Wie Tenantial Findings, Ausnahmen und Accepted Risk als lesbare Governance-Arbeit einordnet, damit Risiken nicht in stillen Nebenabsprachen verschwinden. +editUrl: false +lastUpdated: false +--- + +Findings, Ausnahmen und Accepted Risk sind die Stellen, an denen Governance konkret wird. Genau dort zeigt sich, ob ein Team Unterschiede nur wahrnimmt oder daraus nachvollziehbare Entscheidungen macht. + +## What this page covers + +- was unter Findings, Ausnahmen und Accepted Risk öffentlich verstanden wird +- warum diese Themen nicht von Evidence und Review getrennt werden sollten +- wie Buyer die Entscheidungsreife eines Piloten daran erkennen können + +## Warum Findings mehr als eine Liste sind + +Ein Finding ist nur dann nützlich, wenn sichtbar bleibt, warum es relevant ist, wer es bewertet und welche Evidence oder Priorisierung dahintersteht. Sonst wird aus Review-Arbeit nur eine weitere Liste offener Punkte. + +## Wie Ausnahmen lesbar bleiben + +Ausnahmen gehören in einen klaren Kontext: Was wurde bewusst nicht auf den Sollzustand gebracht, warum ist das akzeptabel und welche Folgefragen bleiben offen? Dadurch bleiben Entscheidungen auch für Management und Audit nachvollziehbar. + +## Accepted Risk als bewusste Entscheidung + +Accepted Risk heißt nicht, dass ein Risiko verschwindet. Es heißt, dass ein Team es mit sichtbarer Begründung einordnet und nicht stillschweigend zwischen Tickets, Screenshots oder Einzelgesprächen verliert. + +## Grenzen dieser Seite + +Diese Seite ersetzt keine Policy oder Genehmigung. Sie erklärt nur, wie Tenantial diese Themen in eine lesbare Governance-Erzählung übersetzt. + +## Related links + +- [Policy Evidence](/docs/policy-evidence/) +- [Review Packs & Entscheidungen](/docs/review-packs-decisions/) +- [Backups, Versionierung & Recovery-Kontext](/docs/backups-versioning-recovery/) +- [Review Packs](/platform/review-packs) \ No newline at end of file diff --git a/apps/website/src/content/docs/getting-started.mdx b/apps/website/src/content/docs/getting-started.mdx new file mode 100644 index 00000000..20fa0552 --- /dev/null +++ b/apps/website/src/content/docs/getting-started.mdx @@ -0,0 +1,41 @@ +--- +title: Erste Schritte +slug: docs/getting-started +description: Wie Evaluatoren und Buyer den Tenantial-Dokumentationshub nutzen, um Pilot, Rollen und Prioritäten für Microsoft-365-Governance zu klären. +editUrl: false +lastUpdated: false +--- + +Wenn Sie Tenantial zum ersten Mal einordnen, starten Sie nicht mit einer langen Feature-Liste. Sinnvoller ist eine kurze Klärung, welche Governance-Fragen heute in Microsoft 365 ungeordnet bleiben und welche Beteiligten später über Evidence, Risiken und nächste Schritte sprechen müssen. + +## What this page covers + +- welche Fragen vor einer Demo oder einem Pilot zuerst beantwortet werden sollten +- welche Teams bei Evaluation, Review und Freigabe typischerweise beteiligt sind +- welche Informationen auf der öffentlichen Website bewusst nicht gesammelt oder versprochen werden + +## Mit der richtigen Fragestellung starten + +Tenantial ist für lesbare Governance-Arbeit gedacht: bekannter Zustand, sichtbare Abweichung, Evidence, Findings und nächste Entscheidung. Für den Einstieg reicht deshalb oft schon die Klärung, welche Policy-Familien, Reviews oder Recovery-Szenarien gerade Entscheidungsdruck erzeugen. + +## Sinnvolle Vorbereitung + +- Notieren Sie, welche Microsoft-365-Bereiche heute in Reviews immer wieder manuell aufbereitet werden. +- Halten Sie fest, welche Rollen Evidence lesen, Risiken bewerten und Entscheidungen freigeben. +- Trennen Sie bestätigte Fakten von offenen Trust- oder Security-Fragen, damit eine Demo nicht mit Vermutungen überladen wird. +- Senden Sie keine Credentials, Secrets oder Tenant-Exporte über die öffentliche Website. + +## Woran ein guter erster Pilot erkennbar ist + +Ein belastbarer Pilot bleibt klein, klar und überprüfbar. Er zeigt einen konkreten Governance-Nutzen, beantwortet die wichtigsten Trust-Fragen früh und hält offen, was erst später in Rollout- oder Architekturentscheidungen geklärt werden muss. + +## Grenzen dieses Einstiegs + +Diese Seite ersetzt weder eine Berechtigungsmatrix noch einen technischen Rollout-Plan. Sie hilft nur dabei, die erste Entscheidung sauber zu rahmen und den weiteren Gesprächsweg zu strukturieren. + +## Related links + +- [Evaluierung & Pilot](/docs/evaluation-pilot/) +- [Microsoft 365 Provider](/docs/microsoft-365-provider/) +- [Berechtigungen & Datenzugriff](/docs/permissions-data-access/) +- [Vertrauen, Datenschutz & Security](/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/guides/first-project-checklist.mdx b/apps/website/src/content/docs/guides/first-project-checklist.mdx deleted file mode 100644 index 7a78ef99..00000000 --- a/apps/website/src/content/docs/guides/first-project-checklist.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Evaluierungscheckliste -description: Eine konservative Checkliste für eine frühe Tenantial-Evaluierung. -sidebar: - label: Evaluierungscheckliste - order: 3 ---- - -Nutze diese Checkliste vor einem Produkt-Walkthrough: - -- Bestätige, welche Microsoft-Tenant-Workflows im Scope sind. -- Bestätige, dass Microsoft 365 der aktuelle Fokus ist und weitere Provider nur als Zukunftsrichtung behandelt werden. -- Trenne Read-only-Review-Bedarf von künftigem Write- oder Restore-Bedarf. -- Identifiziere Audit- und Approval-Erwartungen. -- Ordne Backup, Restore, Drift, Findings, Evidence, Auditability, Exceptions und Reviews den wichtigsten Buyer-Fragen zu. -- Halte Trust-, Compliance- und Recovery-Annahmen als zu prüfende Themen fest statt als gegebene Zusagen. -- Plane Staging-Validierung vor einem Produktionsrollout. -- Halte private Tenant-Daten aus öffentlicher Website-Kommunikation heraus. diff --git a/apps/website/src/content/docs/guides/getting-started.mdx b/apps/website/src/content/docs/guides/getting-started.mdx deleted file mode 100644 index eae3d79e..00000000 --- a/apps/website/src/content/docs/guides/getting-started.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Getting Started -description: Wie Evaluatoren einen Tenantial Walkthrough vorbereiten sollten. -sidebar: - label: Getting Started - order: 2 ---- - -Starte mit einem scoped Gespräch über das Tenant-Governance-Problem, das gelöst werden soll. Der Fokus liegt auf Kategorie, Risiko, Entscheidungswegen und Review-Beteiligten, nicht auf Self-Service-Zugang. - -Sinnvolle Vorbereitung: - -- Identifiziere die Microsoft-Tenant-Administrationsworkflows, die Review brauchen. -- Halte fest, welche Themen heute klar in Microsoft 365 liegen und welche Provider-Fragen nur Zukunftsrichtung bleiben. -- Liste die Policy-Familien, Backup-Flows oder Restore-Planungsszenarien, die zuerst relevant sind. -- Entscheide, wer an Evidence Review und Approval teilnehmen muss. -- Notiere, welche Findings, Exceptions oder Auditability-Erwartungen den größten Entscheidungswert hätten. -- Trenne Trust-, Compliance- und Recovery-Fragen in bestätigte Fakten versus offene Prüfpunkte. -- Sende keine privaten Tenant-Exporte oder Credentials über öffentliche Website-Kontaktpfade. - -Tenantial Walkthroughs sollten auf Review-Klarheit, Least-Privilege-Rollout-Planung und Staging-Validierung vor Produktionseinsatz fokussiert bleiben. diff --git a/apps/website/src/content/docs/guides/intro.mdx b/apps/website/src/content/docs/guides/intro.mdx deleted file mode 100644 index c0a41281..00000000 --- a/apps/website/src/content/docs/guides/intro.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Einführung in Tenantial -description: Öffentliche Einführung in Tenantials Policy-Governance-Modell für Microsoft 365. -sidebar: - label: Einführung - order: 1 ---- - -Tenantial ist auf Policy Governance für Microsoft 365 ausgerichtet. Öffentliche Materialien erklären, wie beobachteter Zustand, Policy-Evidence, Drift, Review, Entscheidung und Audit Trail als ein prüfbares Operating Model zusammenhängen. - -Microsoft 365 ist der aktuelle öffentliche Fokus. Weitere Provider dürfen nur als Architektur- oder Roadmap-Richtung erscheinen, nicht als live unterstützte Integrationen. - -Die Website-Dokumentation ist bewusst öffentlich und statisch. Sie legt keine Live-Tenant-Daten, operative Evidence, private Support-Materialien, Credentials oder verbundenen Microsoft-Konten offen. - -## Was zuerst geprüft werden sollte - -- Wie beobachteter Zustand und Policy-Evidence für Reviews gesammelt und normalisiert werden. -- Wie Drift, Findings und Review-Arbeit zu einer nachvollziehbaren Entscheidung führen. -- Wie Microsoft 365 als aktueller Fokus von provider-extensibler Zukunftsrichtung getrennt wird. -- Wie kontrollierte Recovery als preview-first Arbeit mit Validierung, selektivem Scope und expliziter Bestätigung behandelt wird. diff --git a/apps/website/src/content/docs/index.mdx b/apps/website/src/content/docs/index.mdx new file mode 100644 index 00000000..30e9f84d --- /dev/null +++ b/apps/website/src/content/docs/index.mdx @@ -0,0 +1,54 @@ +--- +title: Tenantial Dokumentation +slug: docs +description: Tenantial Dokumentation für Evaluation, Betrieb und Governance mit Einstiegen zu Provider, Berechtigungen, Evidence, Drift, Recovery, Review Packs und bekannten Grenzen. +template: splash +editUrl: false +lastUpdated: false +hero: + title: Tenantial Dokumentation + tagline: "Orientierung für Evaluation, Betrieb und Governance: von Provider-Zugang über Evidence und Drift bis zu Review Packs, Recovery-Kontext und bekannten Grenzen." + actions: + - text: Mit dem Einstieg beginnen + icon: right-arrow + variant: primary + link: /docs/getting-started/ + - text: Evaluierungspfad lesen + variant: secondary + link: /docs/evaluation-pilot/ +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +## Start mit den richtigen Fragen + +Diese Dokumentation bündelt die öffentlichen Tenantial-Erklärungen für Microsoft-365-Governance. Sie hilft dabei, Produktnutzen, Grenzen und Gesprächswege vor einer Demo, einem Pilot oder einer Procurement-Runde sauber einzuordnen. + +## Was diese Dokumentation abdeckt + +- den heutigen Microsoft-365-Fokus und die Provider-Grenzen +- Berechtigungen, Datenzugriff, Datenschutz- und Trust-Fragen in konservativer Sprache +- Evidence, Drift, Recovery-Kontext, Review Packs und bekannte Grenzen ohne überzogene Automatisierungsversprechen + + + + [Erste Schritte](/docs/getting-started/), [Evaluierung & Pilot](/docs/evaluation-pilot/) und [FAQ](/docs/faq/) helfen beim ersten Gespräch und bei einer belastbaren Pilot-Vorbereitung. + + + [Microsoft 365 Provider](/docs/microsoft-365-provider/), [Berechtigungen & Datenzugriff](/docs/permissions-data-access/) und [Datenverarbeitung & Trust](/docs/data-processing-trust/) beantworten die häufigsten Trust- und Zugriffsfragen. + + + [Policy Evidence](/docs/policy-evidence/), [Drift Detection](/docs/drift-detection/) und [Backups, Versionierung & Recovery-Kontext](/docs/backups-versioning-recovery/) erklären, wie bekannte Zustände lesbar bleiben. + + + [Findings, Ausnahmen & Accepted Risk](/docs/findings-exceptions-accepted-risk/), [Review Packs & Entscheidungen](/docs/review-packs-decisions/) und [Bekannte Grenzen](/docs/known-limitations/) rahmen die eigentliche Review-Arbeit. + + + +## Verwandte öffentliche Seiten + +- [Plattform](/platform) +- [Vertrauen, Datenschutz & Security](/trust) +- [Evaluierung & Rollout](/evaluierung) +- [Review Packs](/platform/review-packs) +- [Kontakt](/contact) \ No newline at end of file diff --git a/apps/website/src/content/docs/known-limitations.mdx b/apps/website/src/content/docs/known-limitations.mdx new file mode 100644 index 00000000..4a738162 --- /dev/null +++ b/apps/website/src/content/docs/known-limitations.mdx @@ -0,0 +1,40 @@ +--- +title: Bekannte Grenzen +slug: docs/known-limitations +description: Welche Grenzen Tenantial auf der öffentlichen Website bewusst klar benennt, damit Evaluierungen nicht auf stillen Annahmen oder Marketing-Übertreibung beruhen. +editUrl: false +lastUpdated: false +--- + +Bekannte Grenzen sind kein Nachteil, sondern Teil einer glaubwürdigen Produktstory. Sie helfen Evaluatoren zu verstehen, welche Aussagen heute belastbar sind und welche Themen bewusst nicht behauptet werden. + +## What this page covers + +- welche Grenzen Tenantial öffentlich klar benennt +- warum diese Grenzen für Buyer, Security und Procurement hilfreich sind +- wie aus klaren Grenzen bessere nächste Schritte entstehen + +## Typische Grenzen, die offen benannt werden sollten + +Tenantial verspricht auf der öffentlichen Website keine generische Multi-Provider-Abdeckung, keine autonome Korrektur, keine pauschale Compliance-Wirkung und keine automatische Recovery. Das hält die Story konkret und überprüfbar. + +## Warum diese Klarheit hilft + +Klare Grenzen verhindern, dass ein Pilot auf stillen Erwartungen basiert. Sie schaffen stattdessen Raum für die richtigen Folgefragen: Scope, Rollen, Trust-Anforderungen und belastbare Handoffs. + +## Was Buyer daraus ableiten können + +- Welche Aussagen sind heute für Microsoft 365 belastbar? +- Welche Themen brauchen einen späteren Produkt- oder Architekturentscheid? +- Wo genügt öffentliche Dokumentation und wo ist ein echter Gesprächspfad nötig? + +## Grenzen dieser Seite + +Diese Seite ist keine Roadmap und kein Ausschlusskatalog. Sie zeigt nur die wichtigsten Punkte, an denen konservative Sprache bewusst wichtiger ist als ein breiterer Claim. + +## Related links + +- [Datenverarbeitung & Trust](/docs/data-processing-trust/) +- [Microsoft 365 Provider](/docs/microsoft-365-provider/) +- [FAQ](/docs/faq/) +- [Trust-Seite](/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/microsoft-365-provider.mdx b/apps/website/src/content/docs/microsoft-365-provider.mdx new file mode 100644 index 00000000..8a323c87 --- /dev/null +++ b/apps/website/src/content/docs/microsoft-365-provider.mdx @@ -0,0 +1,40 @@ +--- +title: Microsoft 365 Provider +slug: docs/microsoft-365-provider +description: Warum Tenantial heute Microsoft 365 als konkreten Provider-Fokus nutzt und weitere Policy-Domänen nur als Richtung beschreibt. +editUrl: false +lastUpdated: false +--- + +Tenantial spricht auf der öffentlichen Website bewusst konkret über Microsoft 365. Das macht Evaluierungen belastbarer, weil Provider-Zugang, Policy-Beispiele und Buyer-Fragen an einem realen Fokus erklärt werden können. + +## What this page covers + +- warum Microsoft 365 heute der klare Produktfokus ist +- wie weitere Policy-Domänen sprachlich eingeordnet werden +- welche Rückschlüsse Evaluatoren daraus für Pilot und Scope ziehen können + +## Warum der Fokus heute klar benannt wird + +Microsoft 365 ist der derzeitige Referenzrahmen für Provider-Zugang, Evidence, Drift und Review-Gespräche. Dadurch bleiben die Docs konkret genug für Buyer und Reviewer, statt in abstrakter Multi-Provider-Sprache zu verschwimmen. + +## Wie weitere Domänen eingeordnet werden + +Weitere Policy-Domänen können als vorbereitete Richtung oder spätere Ausweitung erwähnt werden. Sie werden hier nicht als live unterstützte Integrationen, voll ausdefinierte Workflows oder nachgewiesene Lieferstände beschrieben. + +## Welche Fragen in einer Evaluierung sinnvoll sind + +- Welche Microsoft-365-Bereiche sind für den ersten Review-Kontext relevant? +- Welche Provider-Fragen müssen heute beantwortet werden und welche sind bewusst Zukunftsthema? +- Wo braucht Ihr Team konkrete Trust- oder Berechtigungsantworten, bevor ein Pilot sinnvoll wird? + +## Grenzen dieser Aussage + +Diese Seite ist keine vollständige Roadmap und kein generischer Plattformkatalog. Sie beschreibt einen klaren heutigen Fokus, damit keine falschen Erwartungen an nicht bestätigte Provider-Unterstützung entstehen. + +## Related links + +- [Berechtigungen & Datenzugriff](/docs/permissions-data-access/) +- [Datenverarbeitung & Trust](/docs/data-processing-trust/) +- [Plattform](/platform) +- [Evaluierung & Pilot](/docs/evaluation-pilot/) \ No newline at end of file diff --git a/apps/website/src/content/docs/permissions-data-access.mdx b/apps/website/src/content/docs/permissions-data-access.mdx new file mode 100644 index 00000000..da1683bf --- /dev/null +++ b/apps/website/src/content/docs/permissions-data-access.mdx @@ -0,0 +1,40 @@ +--- +title: Berechtigungen & Datenzugriff +slug: docs/permissions-data-access +description: Welche Fragen zu Berechtigungen, Rollen und Datenzugriff vor einer Tenantial-Evaluierung sauber geklärt werden sollten. +editUrl: false +lastUpdated: false +--- + +Bei Tenantial geht es nicht nur um sichtbare Produktflächen, sondern auch um die Frage, welche Zugriffe für Review, Evidence und Governance-Arbeit wirklich erforderlich sind. Diese Seite hilft, genau diese Gespräche vorzubereiten. + +## What this page covers + +- welche Zugriffsfragen typischerweise in Trust- und Security-Gesprächen auftauchen +- wie Tenantial zwischen Rollen, Zweck und Umgebung denkt +- warum konservative Formulierungen besser sind als eine erfundene Vollmatrix + +## Wichtige Gesprächspunkte + +Buyer und Reviewer wollen meist wissen, welche Aufgaben lesend, welche schreibend und welche nur nach expliziter Freigabe stattfinden. Relevanter als eine pauschale Liste ist deshalb die Einordnung nach Zweck, Risiko und Umgebung. + +## Wie Zugriff sinnvoll gerahmt wird + +- lesender Zugriff wird nach Review-, Evidence- und Sichtbarkeitszweck eingeordnet +- schreibende oder ausführende Schritte werden als bewusste, separat zu bewertende Aktionen behandelt +- Rollen, Least Privilege und Freigaben bleiben Teil des Gesamtbilds statt reine UI-Frage zu sein + +## Was in einer Evaluierung geklärt werden sollte + +Klären Sie früh, welche Rollen auf Buyer-, Security- und Delivery-Seite Antworten brauchen. So wird aus dem Berechtigungsthema kein später Blocker, wenn ein Pilot oder Review bereits inhaltlich überzeugt. + +## Grenzen dieser Seite + +Diese Seite veröffentlicht keine vollständige Microsoft-Permission-Matrix und ersetzt keine produktbezogene Sicherheitsprüfung. Sie bietet nur den öffentlichen Rahmen für die richtigen Rückfragen. + +## Related links + +- [Datenverarbeitung & Trust](/docs/data-processing-trust/) +- [Microsoft 365 Provider](/docs/microsoft-365-provider/) +- [FAQ](/docs/faq/) +- [Trust-Seite](/trust) \ No newline at end of file diff --git a/apps/website/src/content/docs/platform/evidence-review.mdx b/apps/website/src/content/docs/platform/evidence-review.mdx deleted file mode 100644 index 4f616044..00000000 --- a/apps/website/src/content/docs/platform/evidence-review.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Evidence Review -description: Öffentliche Plattform-Notiz für Tenantials Evidence-Review-Workflows im Policy-Governance-Modell für Microsoft 365. -sidebar: - label: Evidence Review - order: 1 ---- - -Evidence Review ist die öffentliche Rahmung für Tenantials Policy-Governance-Modell für Microsoft 365. Die Notiz beschreibt statische Produktkonzepte und keine Live-Tenant-Verbindung. - -Microsoft 365 ist der aktuelle Fokus dieser öffentlichen Story. Weitere Provider dürfen nur als Architektur- oder Roadmap-Richtung erscheinen. - -Das Modell ist bewusst vorsichtig: - -- Beobachteter Zustand ist der Ausgangspunkt für Review-Arbeit. -- Policy-Evidence und Snapshots werden als explizite Records für Vergleich und Planung festgehalten. -- Drift und Findings werden zu sichtbarer Review-Arbeit statt zu stiller Hintergrunddiagnose. -- Entscheidungen, Ausnahmen und akzeptierte Risiken bleiben über Audit Trail nachvollziehbar. -- Recovery wird über Preview, Validierung, selektiven Scope und explizite Bestätigung geplant, ohne Recovery-Erfolg zu versprechen. diff --git a/apps/website/src/content/docs/policy-evidence.mdx b/apps/website/src/content/docs/policy-evidence.mdx new file mode 100644 index 00000000..5902c6d0 --- /dev/null +++ b/apps/website/src/content/docs/policy-evidence.mdx @@ -0,0 +1,40 @@ +--- +title: Policy Evidence +slug: docs/policy-evidence +description: Wie Tenantial Policy Evidence als lesbare Review-Grundlage einordnet und warum Evidence mehr sein muss als eine lose Screenshot- oder Export-Sammlung. +editUrl: false +lastUpdated: false +--- + +Evidence ist in Tenantial keine dekorative Beilage. Sie ist der Teil der Review-Story, der nachvollziehbar macht, worauf sich ein Finding, eine Ausnahme oder eine Entscheidung tatsächlich stützt. + +## What this page covers + +- was mit Policy Evidence im öffentlichen Tenantial-Kontext gemeint ist +- wie bekannte Zustände, Hinweise und Review-Fragen zusammengeführt werden +- warum Evidence nicht mit pauschalen Nachweisversprechen verwechselt werden sollte + +## Was Evidence hier bedeutet + +Policy Evidence verbindet bekannte Konfigurationsstände, relevante Änderungen und erklärenden Kontext. Sie soll Review-Gespräche stabilisieren, nicht Rohdaten unkommentiert ausschütten. + +## Was Reviewer darin lesen können + +- welcher bekannte Zustand als Bezugspunkt dient +- welche Beobachtungen oder Unterschiede für die aktuelle Frage relevant sind +- wie Findings, Accepted Risks oder nächste Schritte an diese Basis zurückgebunden werden + +## Warum das für Buyer wichtig ist + +Wenn Evidence nur als Screenshot-Ordner existiert, bleibt unklar, welche Entscheidung daraus folgen soll. Eine lesbare Evidence-Basis verkürzt dagegen Gespräche zwischen Delivery, Security, Management und Audit. + +## Grenzen dieser Aussage + +Diese Seite verspricht keine lückenlose oder gerichtsfeste Beweisführung. Sie erklärt nur, wie Tenantial Evidence im öffentlichen Produktnarrativ als Review-Hilfe rahmt. + +## Related links + +- [Drift Detection](/docs/drift-detection/) +- [Review Packs & Entscheidungen](/docs/review-packs-decisions/) +- [Findings, Ausnahmen & Accepted Risk](/docs/findings-exceptions-accepted-risk/) +- [Review Packs](/platform/review-packs) \ No newline at end of file diff --git a/apps/website/src/content/docs/review-packs-decisions.mdx b/apps/website/src/content/docs/review-packs-decisions.mdx new file mode 100644 index 00000000..5aad190c --- /dev/null +++ b/apps/website/src/content/docs/review-packs-decisions.mdx @@ -0,0 +1,40 @@ +--- +title: Review Packs & Entscheidungen +slug: docs/review-packs-decisions +description: Wie Tenantial Review Packs als lesbare Unterlage für Entscheidungen erklärt und warum daraus keine rohe Export-Sammlung werden sollte. +editUrl: false +lastUpdated: false +--- + +Review Packs sind die buyer-nahe Form derselben Governance-Wahrheit: bekannte Zustände, Evidence, Findings, Accepted Risks und nächste Schritte werden so geordnet, dass Management, Delivery und Security über dieselbe Unterlage sprechen können. + +## What this page covers + +- wie Review Packs technische Wahrheit in eine lesbare Entscheidungsgrundlage übersetzen +- welche Bausteine dafür auf der öffentlichen Website genannt werden +- warum Review Packs keine zweite Wahrheit neben Evidence und Findings erzeugen sollen + +## Was in einem Review Pack zusammenkommt + +Review Packs verbinden Executive Summary, Evidence-Basis, priorisierte Findings, Accepted Risks und eine klare Decision Summary. Sie helfen dabei, dass ein Gespräch nicht erst bei Rohmaterial beginnt. + +## Warum Buyer davon profitieren + +Wenn Teams denselben Governance-Zustand nur in unterschiedlichen Screenshots oder Exporten sehen, verliert jede Entscheidung Zeit. Eine strukturierte Review-Unterlage macht Status, Auswirkung und nächsten Schritt schneller lesbar. + +## Wie Entscheidungen anschlussfähig bleiben + +- Evidence bleibt mit ihrer Aussage verknüpft +- Findings und Accepted Risks werden nicht aus dem Review-Kontext gelöst +- der nächste Schritt bleibt als Management- und Delivery-Frage nachvollziehbar + +## Grenzen dieser Seite + +Diese Seite verspricht kein starres Report-Format und keinen garantierten Download-Pfad. Sie erklärt nur, warum Review Packs für Buyer und Reviewer eine verständlichere Form derselben Governance-Wahrheit sein können. + +## Related links + +- [Policy Evidence](/docs/policy-evidence/) +- [Findings, Ausnahmen & Accepted Risk](/docs/findings-exceptions-accepted-risk/) +- [Review Packs](/platform/review-packs) +- [FAQ](/docs/faq/) \ No newline at end of file diff --git a/apps/website/src/content/docs/welcome-to-docs.mdx b/apps/website/src/content/docs/welcome-to-docs.mdx deleted file mode 100644 index 18877e58..00000000 --- a/apps/website/src/content/docs/welcome-to-docs.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tenantial Docs -head: - - tag: title - content: Tenantial Docs -description: Öffentliche Notizen zum Policy-Governance-Modell für Microsoft 365 von Tenantial. -editUrl: false -lastUpdated: false -next: false -hero: - title: Tenantial Dokumentation - tagline: Öffentliche Notizen zu beobachtetem Zustand, Evidence, Drift, Review, Entscheidung und Audit Trail mit kontrollierter Recovery-Planung. - actions: - - text: Starten - icon: right-arrow - variant: primary - link: /guides/getting-started/ ---- - -import '@styles/starlight_main.css'; -import { Card, CardGrid } from '@astrojs/starlight/components'; - - - - Verstehe die Abfolge aus beobachten, Evidence sammeln, Drift erkennen, Review, Entscheidung und Audit Trail, bevor ein Rollout-Gespräch geplant wird. - - - - Prüfe, wie Tenantial Microsoft 365 heute fokussiert, weitere Provider nur als Richtung rahmt und Trust-Claims bewusst konservativ hält. - - diff --git a/apps/website/src/data_files/site-copy.ts b/apps/website/src/data_files/site-copy.ts index 5c612dfa..a05d8a13 100644 --- a/apps/website/src/data_files/site-copy.ts +++ b/apps/website/src/data_files/site-copy.ts @@ -48,7 +48,7 @@ export const siteCopy: Record = { { name: 'Interne IT', url: '/use-cases/mittelstand' }, { name: 'Preise', url: '/pricing' }, { name: 'Vertrauen', url: '/trust' }, - { name: 'Docs', url: '/welcome-to-docs/' }, + { name: 'Docs', url: '/docs/' }, { name: 'Kontakt', url: '/contact' }, ], footer: { @@ -63,7 +63,7 @@ export const siteCopy: Record = { { name: 'Preise', url: '/pricing' }, { name: 'Vertrauen', url: '/trust' }, { name: 'Evaluierung', url: '/evaluierung' }, - { name: 'Docs', url: '/welcome-to-docs/' }, + { name: 'Docs', url: '/docs/' }, ], }, { @@ -85,6 +85,35 @@ export const siteCopy: Record = { auth: { walkthrough: 'Walkthrough anfragen', }, + docs: { + routePath: '/docs/', + discovery: { + homepage: { + label: 'Dokumentation öffnen', + href: '/docs/', + }, + platform: { + label: 'Dokumentation öffnen', + href: '/docs/', + }, + trust: { + label: 'Docs zu Datenschutz & Trust', + href: '/docs/data-processing-trust/', + }, + reviewPack: { + label: 'Docs zu Review Packs', + href: '/docs/review-packs-decisions/', + }, + useCase: { + label: 'Docs für Evaluierung & Einstieg', + href: '/docs/getting-started/', + }, + evaluation: { + label: 'Docs zur Pilot-Vorbereitung', + href: '/docs/evaluation-pilot/', + }, + }, + }, home: { pageTitle: 'Tenantial | Microsoft 365 Policies unter Kontrolle bringen', metaDescription: @@ -1604,6 +1633,7 @@ export const siteCopy: Record = { { label: 'Demo buchen', href: '/contact' }, { label: 'Trust-Grenzen ansehen', href: '/trust' }, { label: 'Plattform ansehen', href: '/platform' }, + { label: 'Docs zur Pilot-Vorbereitung', href: '/docs/evaluation-pilot/' }, ], discovery: { homepageEyebrow: 'Evaluierung & Pilot', @@ -1679,7 +1709,7 @@ export const siteCopy: Record = { { name: 'Internal IT', url: '/use-cases/mittelstand' }, { name: 'Pricing', url: '/pricing' }, { name: 'Trust', url: '/trust' }, - { name: 'Docs', url: '/welcome-to-docs/' }, + { name: 'Docs', url: '/docs/' }, { name: 'Contact', url: '/contact' }, ], footer: { @@ -1694,7 +1724,7 @@ export const siteCopy: Record = { { name: 'Pricing', url: '/pricing' }, { name: 'Trust', url: '/trust' }, { name: 'Evaluation', url: '/evaluation' }, - { name: 'Docs', url: '/welcome-to-docs/' }, + { name: 'Docs', url: '/docs/' }, ], }, { @@ -1716,6 +1746,35 @@ export const siteCopy: Record = { auth: { walkthrough: 'Request walkthrough', }, + docs: { + routePath: '/docs/', + discovery: { + homepage: { + label: 'Open documentation', + href: '/docs/', + }, + platform: { + label: 'Open documentation', + href: '/docs/', + }, + trust: { + label: 'Docs for privacy and trust', + href: '/docs/data-processing-trust/', + }, + reviewPack: { + label: 'Docs for review packs', + href: '/docs/review-packs-decisions/', + }, + useCase: { + label: 'Docs for onboarding and evaluation', + href: '/docs/getting-started/', + }, + evaluation: { + label: 'Docs for pilot readiness', + href: '/docs/evaluation-pilot/', + }, + }, + }, home: { pageTitle: 'Tenantial | Bring Microsoft 365 policies under control', metaDescription: @@ -3225,6 +3284,7 @@ export const siteCopy: Record = { { label: 'Book a demo', href: '/contact' }, { label: 'See trust boundaries', href: '/trust' }, { label: 'View platform', href: '/platform' }, + { label: 'Docs for pilot readiness', href: '/docs/evaluation-pilot/' }, ], discovery: { homepageEyebrow: 'Evaluation & pilot', diff --git a/apps/website/src/pages/en/guides/first-project-checklist.astro b/apps/website/src/pages/en/guides/first-project-checklist.astro new file mode 100644 index 00000000..b5890f12 --- /dev/null +++ b/apps/website/src/pages/en/guides/first-project-checklist.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/en/docs/evaluation-pilot/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/en/guides/getting-started.astro b/apps/website/src/pages/en/guides/getting-started.astro new file mode 100644 index 00000000..c4d083e5 --- /dev/null +++ b/apps/website/src/pages/en/guides/getting-started.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/en/docs/getting-started/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/en/guides/intro.astro b/apps/website/src/pages/en/guides/intro.astro new file mode 100644 index 00000000..c4d083e5 --- /dev/null +++ b/apps/website/src/pages/en/guides/intro.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/en/docs/getting-started/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/en/platform/evidence-review.astro b/apps/website/src/pages/en/platform/evidence-review.astro new file mode 100644 index 00000000..e8944cbb --- /dev/null +++ b/apps/website/src/pages/en/platform/evidence-review.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/en/docs/policy-evidence/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/en/use-cases/mittelstand.astro b/apps/website/src/pages/en/use-cases/mittelstand.astro index 939cb72f..80be5a2b 100644 --- a/apps/website/src/pages/en/use-cases/mittelstand.astro +++ b/apps/website/src/pages/en/use-cases/mittelstand.astro @@ -267,11 +267,15 @@ const canonicalPath = localizedPath('/use-cases/mittelstand', locale); > {siteCopy[locale].evaluation.discovery.useCaseContent}

-
+
+
diff --git a/apps/website/src/pages/en/use-cases/msp.astro b/apps/website/src/pages/en/use-cases/msp.astro index 7bcd092f..5f99bf7c 100644 --- a/apps/website/src/pages/en/use-cases/msp.astro +++ b/apps/website/src/pages/en/use-cases/msp.astro @@ -267,11 +267,15 @@ const canonicalPath = localizedPath('/use-cases/msp', locale); > {siteCopy[locale].evaluation.discovery.useCaseContent}

-
+
+
diff --git a/apps/website/src/pages/en/welcome-to-docs.astro b/apps/website/src/pages/en/welcome-to-docs.astro new file mode 100644 index 00000000..59456633 --- /dev/null +++ b/apps/website/src/pages/en/welcome-to-docs.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/en/docs/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/guides/first-project-checklist.astro b/apps/website/src/pages/guides/first-project-checklist.astro new file mode 100644 index 00000000..f022801d --- /dev/null +++ b/apps/website/src/pages/guides/first-project-checklist.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/docs/evaluation-pilot/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/guides/getting-started.astro b/apps/website/src/pages/guides/getting-started.astro new file mode 100644 index 00000000..827b647f --- /dev/null +++ b/apps/website/src/pages/guides/getting-started.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/docs/getting-started/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/guides/intro.astro b/apps/website/src/pages/guides/intro.astro new file mode 100644 index 00000000..827b647f --- /dev/null +++ b/apps/website/src/pages/guides/intro.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/docs/getting-started/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/platform/evidence-review.astro b/apps/website/src/pages/platform/evidence-review.astro new file mode 100644 index 00000000..1df56e74 --- /dev/null +++ b/apps/website/src/pages/platform/evidence-review.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/docs/policy-evidence/', 301); +--- \ No newline at end of file diff --git a/apps/website/src/pages/use-cases/mittelstand.astro b/apps/website/src/pages/use-cases/mittelstand.astro index 814afd92..41a1977d 100644 --- a/apps/website/src/pages/use-cases/mittelstand.astro +++ b/apps/website/src/pages/use-cases/mittelstand.astro @@ -267,11 +267,15 @@ const canonicalPath = localizedPath('/use-cases/mittelstand', locale); > {siteCopy[locale].evaluation.discovery.useCaseContent}

-
+
+
diff --git a/apps/website/src/pages/use-cases/msp.astro b/apps/website/src/pages/use-cases/msp.astro index 29f57482..d0d3360d 100644 --- a/apps/website/src/pages/use-cases/msp.astro +++ b/apps/website/src/pages/use-cases/msp.astro @@ -267,11 +267,15 @@ const canonicalPath = localizedPath('/use-cases/msp', locale); > {siteCopy[locale].evaluation.discovery.useCaseContent}

-
+
+
diff --git a/apps/website/src/pages/welcome-to-docs.astro b/apps/website/src/pages/welcome-to-docs.astro new file mode 100644 index 00000000..50ba96d8 --- /dev/null +++ b/apps/website/src/pages/welcome-to-docs.astro @@ -0,0 +1,3 @@ +--- +return Astro.redirect('/docs/', 301); +--- \ No newline at end of file diff --git a/apps/website/tests/smoke/interaction.spec.ts b/apps/website/tests/smoke/interaction.spec.ts index 54d1c57d..48de72f1 100644 --- a/apps/website/tests/smoke/interaction.spec.ts +++ b/apps/website/tests/smoke/interaction.spec.ts @@ -31,7 +31,7 @@ test('mobile navigation opens with vendored foundation behavior', async ({ ).toHaveAttribute('href', '/trust'); await expect( mobilePanel.getByRole('link', { name: 'Docs', exact: true }) - ).toHaveAttribute('href', '/welcome-to-docs/'); + ).toHaveAttribute('href', '/docs/'); await expect( mobilePanel.getByRole('link', { name: 'Walkthrough anfragen' }) ).toBeVisible(); @@ -162,6 +162,274 @@ test('homepage exposes localized buyer-path teasers', async ({ page }) => { } }); +for (const { route, heading, topicHrefs, publicHrefs } of [ + { + route: '/docs/', + heading: /Tenantial Dokumentation/i, + topicHrefs: [ + '/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/', + ], + publicHrefs: ['/platform', '/trust', '/evaluierung', '/platform/review-packs'], + }, + { + route: '/en/docs/', + heading: /Tenantial documentation/i, + topicHrefs: [ + '/en/docs/getting-started/', + '/en/docs/microsoft-365-provider/', + '/en/docs/permissions-data-access/', + '/en/docs/data-processing-trust/', + '/en/docs/policy-evidence/', + '/en/docs/drift-detection/', + '/en/docs/backups-versioning-recovery/', + '/en/docs/findings-exceptions-accepted-risk/', + '/en/docs/review-packs-decisions/', + '/en/docs/evaluation-pilot/', + '/en/docs/known-limitations/', + '/en/docs/faq/', + ], + publicHrefs: [ + '/en/platform', + '/en/trust', + '/en/evaluation', + '/en/platform/review-packs', + ], + }, +] as const) { + test(`${route} exposes the full docs hub and real public handoffs`, async ({ + page, + }) => { + await page.goto(route); + + await expect( + page.locator('main').getByRole('heading', { level: 1, name: heading }) + ).toBeVisible(); + + for (const href of topicHrefs) { + await expect(page.locator(`main a[href="${href}"]`).first()).toBeVisible(); + } + + for (const href of publicHrefs) { + await expect(page.locator(`main a[href="${href}"]`).first()).toBeVisible(); + } + + await expectNoHorizontalOverflow(page); + }); +} + +for (const { route, heading, terms, relatedHref } of [ + { + route: '/docs/getting-started/', + heading: /Erste Schritte/i, + terms: [/Demo|Pilot/i, /Governance/i, /Credentials|Secrets/i], + relatedHref: '/docs/evaluation-pilot/', + }, + { + route: '/en/docs/getting-started/', + heading: /Getting Started/i, + terms: [/demo|pilot/i, /governance/i, /credentials|secrets/i], + relatedHref: '/en/docs/evaluation-pilot/', + }, +] as const) { + test(`${route} makes the onboarding path readable`, async ({ page }) => { + await page.goto(route); + + await expect( + page.locator('main').getByRole('heading', { level: 1, name: heading }) + ).toBeVisible(); + + for (const term of terms) { + await expect(page.locator('main')).toContainText(term); + } + + await expect(page.locator(`main a[href="${relatedHref}"]`).first()).toBeVisible(); + await expectNoHorizontalOverflow(page); + }); +} + +for (const { route, heading, terms, relatedHref } of [ + { + route: '/docs/permissions-data-access/', + heading: /Berechtigungen|Datenzugriff/i, + terms: [/Les[t]?ender Zugriff|Least Privilege/i, /Rollen|Freigabe/i], + relatedHref: '/docs/data-processing-trust/', + }, + { + route: '/docs/data-processing-trust/', + heading: /Datenverarbeitung|Trust/i, + terms: [/DPA|TOM|Subprozessoren/i, /Statussprache|Handoffs/i], + relatedHref: '/trust', + }, + { + route: '/docs/review-packs-decisions/', + heading: /Review Packs|Entscheidungen/i, + terms: [/Executive Summary|Decision Summary/i, /Evidence|Accepted Risks/i], + relatedHref: '/platform/review-packs', + }, + { + route: '/docs/evaluation-pilot/', + heading: /Evaluierung|Pilot/i, + terms: [/Pilot/i, /Trust|Berechtigung/i], + relatedHref: '/evaluierung', + }, + { + route: '/docs/known-limitations/', + heading: /Bekannte Grenzen|Limitations/i, + terms: [/Microsoft 365/i, /autonome Korrektur|Compliance/i], + relatedHref: '/trust', + }, + { + route: '/docs/faq/', + heading: /FAQ/i, + terms: [/Microsoft 365/i, /Trust|Pilot/i], + relatedHref: '/contact', + }, + { + route: '/en/docs/permissions-data-access/', + heading: /Permissions|Data Access/i, + terms: [/read-oriented|least privilege/i, /roles|approval/i], + relatedHref: '/en/docs/data-processing-trust/', + }, + { + route: '/en/docs/data-processing-trust/', + heading: /Data Processing|Trust/i, + terms: [/DPA|TOM|subprocessors/i, /status|handoff/i], + relatedHref: '/en/trust', + }, + { + route: '/en/docs/review-packs-decisions/', + heading: /Review Packs|Decisions/i, + terms: [/executive summary|decision summary/i, /evidence|accepted risks/i], + relatedHref: '/en/platform/review-packs', + }, + { + route: '/en/docs/evaluation-pilot/', + heading: /Evaluation|Pilot/i, + terms: [/pilot/i, /trust|permission/i], + relatedHref: '/en/evaluation', + }, + { + route: '/en/docs/known-limitations/', + heading: /Known Limitations/i, + terms: [/Microsoft 365/i, /autonomous correction|compliance/i], + relatedHref: '/en/trust', + }, + { + route: '/en/docs/faq/', + heading: /FAQ/i, + terms: [/Microsoft 365/i, /trust|pilot/i], + relatedHref: '/en/contact', + }, +] as const) { + test(`${route} answers reviewer-facing questions conservatively`, async ({ + page, + }) => { + await page.goto(route); + + await expect( + page.locator('main').getByRole('heading', { level: 1, name: heading }) + ).toBeVisible(); + + for (const term of terms) { + await expect(page.locator('main')).toContainText(term); + } + + await expect(page.locator(`main a[href="${relatedHref}"]`).first()).toBeVisible(); + await expectNoHorizontalOverflow(page); + }); +} + +for (const { route, heading, terms, relatedHref } of [ + { + route: '/docs/microsoft-365-provider/', + heading: /Microsoft 365 Provider/i, + terms: [/Microsoft 365/i, /weitere Policy-Domänen|Zukunft/i], + relatedHref: '/docs/evaluation-pilot/', + }, + { + route: '/docs/policy-evidence/', + heading: /Policy Evidence|Evidence/i, + terms: [/Evidence/i, /Findings|Review/i], + relatedHref: '/platform/review-packs', + }, + { + route: '/docs/drift-detection/', + heading: /Drift Detection|Drift/i, + terms: [/bekannten Zuständen|Veränderung/i, /Review|Priorisierung/i], + relatedHref: '/platform', + }, + { + route: '/docs/backups-versioning-recovery/', + heading: /Backups|Versionierung|Recovery/i, + terms: [/Versionierung|bekannte Zustände/i, /Recovery/i], + relatedHref: '/docs/evaluation-pilot/', + }, + { + route: '/docs/findings-exceptions-accepted-risk/', + heading: /Findings|Ausnahmen|Accepted Risk/i, + terms: [/Accepted Risk|Ausnahmen/i, /Evidence|Management|Audit/i], + relatedHref: '/platform/review-packs', + }, + { + route: '/en/docs/microsoft-365-provider/', + heading: /Microsoft 365 Provider/i, + terms: [/Microsoft 365/i, /additional policy domains|future/i], + relatedHref: '/en/docs/evaluation-pilot/', + }, + { + route: '/en/docs/policy-evidence/', + heading: /Policy Evidence|Evidence/i, + terms: [/evidence/i, /findings|review/i], + relatedHref: '/en/platform/review-packs', + }, + { + route: '/en/docs/drift-detection/', + heading: /Drift Detection|Drift/i, + terms: [/known states|readable change/i, /review|prioritization/i], + relatedHref: '/en/platform', + }, + { + route: '/en/docs/backups-versioning-recovery/', + heading: /Backups|Versioning|Recovery/i, + terms: [/versioning|known states/i, /recovery/i], + relatedHref: '/en/docs/evaluation-pilot/', + }, + { + route: '/en/docs/findings-exceptions-accepted-risk/', + heading: /Findings|Exceptions|Accepted Risk/i, + terms: [/accepted risk|exceptions/i, /evidence|management|audit/i], + relatedHref: '/en/platform/review-packs', + }, +] as const) { + test(`${route} explains technical governance concepts in public language`, async ({ + page, + }) => { + await page.goto(route); + + await expect( + page.locator('main').getByRole('heading', { level: 1, name: heading }) + ).toBeVisible(); + + for (const term of terms) { + await expect(page.locator('main')).toContainText(term); + } + + await expect(page.locator(`main a[href="${relatedHref}"]`).first()).toBeVisible(); + await expectNoHorizontalOverflow(page); + }); +} + test('desktop keyboard reaches navigation, CTAs, footer, and contact controls', async ({ page, isMobile, @@ -207,7 +475,7 @@ test('desktop keyboard reaches navigation, CTAs, footer, and contact controls', expect([...reached].join('\n')).toContain('/use-cases/msp'); expect([...reached].join('\n')).toContain('/use-cases/mittelstand'); expect([...reached].join('\n')).toContain('/trust'); - expect([...reached].join('\n')).toContain('/welcome-to-docs/'); + expect([...reached].join('\n')).toContain('/docs/'); expect([...reached].join('\n')).toContain('Kontakt'); expect([...reached].join('\n')).toContain('/privacy'); expect([...reached].join('\n')).toContain('hs-firstname-contacts'); diff --git a/apps/website/tests/smoke/public-routes.spec.ts b/apps/website/tests/smoke/public-routes.spec.ts index 1a2e1a50..8bc4b6b1 100644 --- a/apps/website/tests/smoke/public-routes.spec.ts +++ b/apps/website/tests/smoke/public-routes.spec.ts @@ -80,25 +80,57 @@ const routeMetadata = { title: /Impressum \| Tenantial/i, description: /Veröffentlichungsinformationen/i, }, - '/welcome-to-docs/': { - title: /Tenantial Docs/i, - description: /Policy-Governance-Modell für Microsoft 365/i, + '/docs/': { + title: /Dokumentation|Tenantial Dokumentation/i, + description: /Evaluation|Betrieb|Governance|Provider|Evidence|Drift/i, }, - '/guides/intro/': { - title: /Einführung in Tenantial/i, - description: /Policy-Governance-Modell für Microsoft 365/i, + '/docs/getting-started/': { + title: /Erste Schritte|Getting Started/i, + description: /Evaluierung|Pilot|Ablauf|Microsoft 365/i, }, - '/guides/getting-started/': { - title: /Getting Started/i, - description: /Tenant-Governance-Problem|Tenantial Walkthrough/i, + '/docs/microsoft-365-provider/': { + title: /Microsoft 365 Provider/i, + description: /Microsoft 365|Provider|Grenzen|Zugriff/i, }, - '/guides/first-project-checklist/': { - title: /Evaluierungscheckliste/i, - description: /frühe Tenantial-Evaluierung|Checkliste/i, + '/docs/permissions-data-access/': { + title: /Berechtigungen|Datenzugriff/i, + description: /Berechtigungen|Datenzugriff|Rollen|Lesender Zugriff/i, }, - '/platform/evidence-review/': { - title: /Evidence Review/i, - description: /Policy-Governance-Modell|Evidence-Review-Workflows/i, + '/docs/data-processing-trust/': { + title: /Datenverarbeitung|Trust/i, + description: /Datenschutz|Trust|Dokumente|Grenzen/i, + }, + '/docs/policy-evidence/': { + title: /Policy Evidence|Evidence/i, + description: /Evidence|Konfigurationsstand|Review|Nachweise/i, + }, + '/docs/drift-detection/': { + title: /Drift Detection|Drift/i, + description: /Drift|Aenderungen|Review|Priorisierung/i, + }, + '/docs/backups-versioning-recovery/': { + title: /Backups|Versionierung|Recovery/i, + description: /Backups|Versionierung|Recovery|Wiederherstellung/i, + }, + '/docs/findings-exceptions-accepted-risk/': { + title: /Findings|Ausnahmen|Accepted Risk/i, + description: /Findings|Ausnahmen|Accepted Risks|Entscheidungen/i, + }, + '/docs/review-packs-decisions/': { + title: /Review Packs|Entscheidungen/i, + description: /Review Packs|Entscheidungen|Evidence|Follow-up/i, + }, + '/docs/evaluation-pilot/': { + title: /Evaluierung|Pilot/i, + description: /Evaluierung|Pilot|Readiness|Walkthrough/i, + }, + '/docs/known-limitations/': { + title: /Bekannte Grenzen|Limitations/i, + description: /Grenzen|Fokus|keine Zusagen|heute nicht/i, + }, + '/docs/faq/': { + title: /FAQ/i, + description: /FAQ|Fragen|Antworten|Einordnung/i, }, '/en/': { title: /Tenantial.*Bring Microsoft 365 policies under control/i, @@ -157,25 +189,57 @@ const routeMetadata = { title: /Imprint \| Tenantial/i, description: /public website publication information/i, }, - '/en/welcome-to-docs/': { - title: /Tenantial Docs/i, - description: /policy-governance model for Microsoft 365/i, + '/en/docs/': { + title: /Documentation|Tenantial documentation/i, + description: /evaluation|operations|governance|provider|evidence|drift/i, }, - '/en/guides/intro/': { - title: /Introduction to Tenantial/i, - description: /policy-governance model for Microsoft 365/i, - }, - '/en/guides/getting-started/': { + '/en/docs/getting-started/': { title: /Getting Started/i, - description: /Tenantial walkthrough|governance problem/i, + description: /evaluation|pilot|workflow|Microsoft 365/i, }, - '/en/guides/first-project-checklist/': { - title: /Evaluation Checklist/i, - description: /conservative checklist|early Tenantial evaluation/i, + '/en/docs/microsoft-365-provider/': { + title: /Microsoft 365 Provider/i, + description: /Microsoft 365|provider|boundaries|access/i, }, - '/en/platform/evidence-review/': { - title: /Evidence Review/i, - description: /policy-governance model|evidence-review workflows/i, + '/en/docs/permissions-data-access/': { + title: /Permissions|Data Access/i, + description: /permissions|data access|roles|read-oriented/i, + }, + '/en/docs/data-processing-trust/': { + title: /Data Processing|Trust/i, + description: /privacy|trust|documents|boundaries/i, + }, + '/en/docs/policy-evidence/': { + title: /Policy Evidence|Evidence/i, + description: /evidence|configuration state|review|proof points/i, + }, + '/en/docs/drift-detection/': { + title: /Drift Detection|Drift/i, + description: /drift|changes|review|prioritization/i, + }, + '/en/docs/backups-versioning-recovery/': { + title: /Backups|Versioning|Recovery/i, + description: /backups|versioning|recovery|restore context/i, + }, + '/en/docs/findings-exceptions-accepted-risk/': { + title: /Findings|Exceptions|Accepted Risk/i, + description: /findings|exceptions|accepted risks|decisions/i, + }, + '/en/docs/review-packs-decisions/': { + title: /Review Packs|Decisions/i, + description: /review packs|decisions|evidence|follow-up/i, + }, + '/en/docs/evaluation-pilot/': { + title: /Evaluation|Pilot/i, + description: /evaluation|pilot|readiness|walkthrough/i, + }, + '/en/docs/known-limitations/': { + title: /Known Limitations/i, + description: /limitations|focus|no promises|not today/i, + }, + '/en/docs/faq/': { + title: /FAQ/i, + description: /FAQ|questions|answers|framing/i, }, } as const; @@ -667,6 +731,149 @@ for (const { route, trustHref, label } of [ }); } +for (const { route, docsHref } of [ + { route: '/', docsHref: '/docs/' }, + { route: '/en/', docsHref: '/en/docs/' }, +] as const) { + test(`${route} exposes docs through global navigation and footer`, async ({ + page, + isMobile, + }) => { + await page.goto(route); + + if (isMobile) { + await page.getByLabel('Toggle navigation').click(); + } + + await expect( + page.locator('header').getByRole('link', { name: 'Docs', exact: true }) + ).toHaveAttribute('href', docsHref); + await expect( + page.locator('footer').getByRole('link', { name: 'Docs', exact: true }) + ).toHaveAttribute('href', docsHref); + await expect(page.locator(`footer a[href="${docsHref}"]`)).toBeVisible(); + await expectNoPlaceholderLinks(page); + }); +} + +for (const { route, links } of [ + { + route: '/', + links: [{ name: 'Dokumentation öffnen', href: '/docs/' }], + }, + { + route: '/platform', + links: [{ name: 'Dokumentation öffnen', href: '/docs/' }], + }, + { + route: '/trust', + links: [ + { + name: 'Docs zu Datenschutz & Trust', + href: '/docs/data-processing-trust/', + }, + ], + }, + { + route: '/evaluierung', + links: [ + { + name: 'Docs zur Pilot-Vorbereitung', + href: '/docs/evaluation-pilot/', + }, + ], + }, + { + route: '/platform/review-packs', + links: [ + { name: 'Docs zu Review Packs', href: '/docs/review-packs-decisions/' }, + ], + }, + { + route: '/use-cases/msp', + links: [ + { + name: 'Docs für Evaluierung & Einstieg', + href: '/docs/getting-started/', + }, + ], + }, + { + route: '/use-cases/mittelstand', + links: [ + { + name: 'Docs für Evaluierung & Einstieg', + href: '/docs/getting-started/', + }, + ], + }, + { + route: '/en/', + links: [{ name: 'Open documentation', href: '/en/docs/' }], + }, + { + route: '/en/platform', + links: [{ name: 'Open documentation', href: '/en/docs/' }], + }, + { + route: '/en/trust', + links: [ + { + name: 'Docs for privacy and trust', + href: '/en/docs/data-processing-trust/', + }, + ], + }, + { + route: '/en/evaluation', + links: [ + { + name: 'Docs for pilot readiness', + href: '/en/docs/evaluation-pilot/', + }, + ], + }, + { + route: '/en/platform/review-packs', + links: [ + { + name: 'Docs for review packs', + href: '/en/docs/review-packs-decisions/', + }, + ], + }, + { + route: '/en/use-cases/msp', + links: [ + { + name: 'Docs for onboarding and evaluation', + href: '/en/docs/getting-started/', + }, + ], + }, + { + route: '/en/use-cases/mittelstand', + links: [ + { + name: 'Docs for onboarding and evaluation', + href: '/en/docs/getting-started/', + }, + ], + }, +] as const) { + test(`${route} exposes contextual docs discovery`, async ({ page }) => { + await page.goto(route); + + for (const link of links) { + await expect( + page.getByRole('link', { name: link.name, exact: true }).first() + ).toHaveAttribute('href', link.href); + } + + await expectNoPlaceholderLinks(page); + }); +} + for (const { route, navLinks } of [ { route: '/', @@ -739,11 +946,13 @@ for (const route of redirectRoutes) { await page.goto(route); await expect(page).toHaveURL(new RegExp(`${expected.target}/?$`)); - await expect( - page.getByRole('heading', { - name: /Policy-Governance-Modell für Microsoft 365|Policy governance model for Microsoft 365/, - }) - ).toBeVisible(); + + const targetMetadata = + routeMetadata[expected.target as keyof typeof routeMetadata]; + + if (targetMetadata) { + await expectMetadataForRoute(page, expected.target, targetMetadata); + } }); } diff --git a/apps/website/tests/smoke/smoke-helpers.ts b/apps/website/tests/smoke/smoke-helpers.ts index 0f0d355c..c6b57e40 100644 --- a/apps/website/tests/smoke/smoke-helpers.ts +++ b/apps/website/tests/smoke/smoke-helpers.ts @@ -14,11 +14,6 @@ export const renderedRoutes = [ '/privacy', '/terms', '/imprint', - '/welcome-to-docs/', - '/guides/intro/', - '/guides/getting-started/', - '/guides/first-project-checklist/', - '/platform/evidence-review/', '/en/', '/en/use-cases/msp', '/en/use-cases/mittelstand', @@ -32,24 +27,61 @@ export const renderedRoutes = [ '/en/privacy', '/en/terms', '/en/imprint', - '/en/welcome-to-docs/', - '/en/guides/intro/', - '/en/guides/getting-started/', - '/en/guides/first-project-checklist/', - '/en/platform/evidence-review/', + '/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/', + '/en/docs/getting-started/', + '/en/docs/microsoft-365-provider/', + '/en/docs/permissions-data-access/', + '/en/docs/data-processing-trust/', + '/en/docs/policy-evidence/', + '/en/docs/drift-detection/', + '/en/docs/backups-versioning-recovery/', + '/en/docs/findings-exceptions-accepted-risk/', + '/en/docs/review-packs-decisions/', + '/en/docs/evaluation-pilot/', + '/en/docs/known-limitations/', + '/en/docs/faq/', ] as const; export const docsRoutes = [ - '/welcome-to-docs/', - '/guides/intro/', - '/guides/getting-started/', - '/guides/first-project-checklist/', - '/platform/evidence-review/', - '/en/welcome-to-docs/', - '/en/guides/intro/', - '/en/guides/getting-started/', - '/en/guides/first-project-checklist/', - '/en/platform/evidence-review/', + '/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/', + '/en/docs/getting-started/', + '/en/docs/microsoft-365-provider/', + '/en/docs/permissions-data-access/', + '/en/docs/data-processing-trust/', + '/en/docs/policy-evidence/', + '/en/docs/drift-detection/', + '/en/docs/backups-versioning-recovery/', + '/en/docs/findings-exceptions-accepted-risk/', + '/en/docs/review-packs-decisions/', + '/en/docs/evaluation-pilot/', + '/en/docs/known-limitations/', + '/en/docs/faq/', ] as const; export const redirectRouteExpectations = { @@ -63,6 +95,37 @@ export const redirectRouteExpectations = { '/en/services': { status: 301, target: '/en/platform' }, '/en/blog': { status: 302, target: '/en/platform' }, '/en/insights': { status: 302, target: '/en/platform' }, + '/welcome-to-docs/': { status: 301, target: '/docs/' }, + '/guides/intro/': { status: 301, target: '/docs/getting-started/' }, + '/guides/getting-started/': { + status: 301, + target: '/docs/getting-started/', + }, + '/guides/first-project-checklist/': { + status: 301, + target: '/docs/evaluation-pilot/', + }, + '/platform/evidence-review/': { + status: 301, + target: '/docs/policy-evidence/', + }, + '/en/welcome-to-docs/': { status: 301, target: '/en/docs/' }, + '/en/guides/intro/': { + status: 301, + target: '/en/docs/getting-started/', + }, + '/en/guides/getting-started/': { + status: 301, + target: '/en/docs/getting-started/', + }, + '/en/guides/first-project-checklist/': { + status: 301, + target: '/en/docs/evaluation-pilot/', + }, + '/en/platform/evidence-review/': { + status: 301, + target: '/en/docs/policy-evidence/', + }, } as const; export const redirectRoutes = Object.keys(redirectRouteExpectations) as Array< diff --git a/specs/410-public-docs-ia/checklists/requirements.md b/specs/410-public-docs-ia/checklists/requirements.md new file mode 100644 index 00000000..afabb9d8 --- /dev/null +++ b/specs/410-public-docs-ia/checklists/requirements.md @@ -0,0 +1,36 @@ +# Specification Quality Checklist: Public Docs & Knowledge Base IA + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-05-31 +**Feature**: [spec.md](/Users/ahmeddarrazi/Documents/projects/wt-website/specs/410-public-docs-ia/spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validation passed on the first review iteration. +- The spec keeps implementation verification expectations at the level of repository-truth obligations and validation outcomes, not framework-specific build instructions. +- Implementation close-out completed with fresh website build output, focused and full website smoke validation, source/dist forbidden-claim scans, and confirmation that `apps/platform/**` remained untouched. \ No newline at end of file diff --git a/specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml b/specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml new file mode 100644 index 00000000..4b97d0b5 --- /dev/null +++ b/specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml @@ -0,0 +1,379 @@ +openapi: 3.1.0 +info: + title: Tenantial Public Docs Routes + version: 0.1.0 + description: > + Static public website route contract for Spec 410. These routes return HTML + pages only and do not expose platform runtime APIs, authenticated docs, + customer portals, CMS workflows, provider runtime state, legal downloads, + or support-ticket behavior. +servers: + - url: http://127.0.0.1:4321 + description: Local website preview using WEBSITE_PORT default +paths: + /docs/: + get: + summary: German docs landing page + operationId: getGermanDocsLandingPage + tags: + - Public Website + - Docs + responses: + "200": + description: Static HTML docs landing page + content: + text/html: + schema: + type: string + examples: + page: + summary: Required visible content + value: "Tenantial Dokumentation fuer Evaluation, Betrieb und Governance. Einstieg in Provider, Berechtigungen, Evidence, Drift, Recovery, Review Packs und bekannte Grenzen." + "404": + description: Route not configured + x-content-requirements: + locale: de + mustInclude: + - Hero framing for documentation, evaluation, operations, and governance + - Twelve required docs category links + - Real links only + - Related handoffs to verified public routes where implementation ships them + mustNotInclude: + - href="#" + - repo-real foundation + - productization gap + - capability registry + - implementation truth + - DSGVO-konform + - ISO-zertifiziert + - NIS2-konform + - real-time drift + - automatic remediation + - automatic restore + - one-click restore + - Google supported + - AWS supported + /en/docs/: + get: + summary: English docs landing page + operationId: getEnglishDocsLandingPage + tags: + - Public Website + - Docs + responses: + "200": + description: Static HTML docs landing page + content: + text/html: + schema: + type: string + examples: + page: + summary: Required visible content + value: "Tenantial documentation for evaluation, operations, and governance. Start with provider access, evidence, drift, recovery context, review packs, and known limitations." + "404": + description: Route not configured + x-content-requirements: + locale: en + mustInclude: + - Hero framing for documentation, evaluation, operations, and governance + - Twelve required docs category links + - Real links only + - Related handoffs to verified public routes where implementation ships them + mustNotInclude: + - href="#" + - repo-real foundation + - productization gap + - capability registry + - implementation truth + - GDPR compliant + - ISO certified + - NIS2 compliant + - real-time drift + - automatic remediation + - automatic restore + - one-click restore + - Google supported + - AWS supported + /docs/{topic}/: + get: + summary: German docs topic page + operationId: getGermanDocsTopicPage + tags: + - Public Website + - Docs + parameters: + - in: path + name: topic + required: true + schema: + $ref: '#/components/schemas/DocsTopicSlug' + responses: + "200": + description: Static HTML docs topic page + content: + text/html: + schema: + type: string + "404": + description: Topic route not configured + x-content-requirements: + locale: de + pageShape: + - Title + - Intro paragraph + - What this page covers + - 3 to 6 ordered sections + - Related links + mustNotInclude: + - href="#" + - repo-real foundation + - productization gap + - capability registry + - implementation truth + - DSGVO-konform + - ISO-zertifiziert + - NIS2-konform + - in Deutschland gehostet + - keine Kundendaten + - keine personenbezogenen Daten + - Google supported + - AWS supported + - multi-cloud supported + - real-time drift + - automatic remediation + - automatic restore + - one-click restore + - immutable backups + - gerichtsfeste Nachweise + - guarantees audit success + /en/docs/{topic}/: + get: + summary: English docs topic page + operationId: getEnglishDocsTopicPage + tags: + - Public Website + - Docs + parameters: + - in: path + name: topic + required: true + schema: + $ref: '#/components/schemas/DocsTopicSlug' + responses: + "200": + description: Static HTML docs topic page + content: + text/html: + schema: + type: string + "404": + description: Topic route not configured + x-content-requirements: + locale: en + pageShape: + - Title + - Intro paragraph + - What this page covers + - 3 to 6 ordered sections + - Related links + mustNotInclude: + - href="#" + - repo-real foundation + - productization gap + - capability registry + - implementation truth + - GDPR compliant + - ISO certified + - NIS2 compliant + - hosted in Germany + - no customer data stored + - no personal data stored + - Google supported + - AWS supported + - multi-cloud supported + - real-time drift + - automatic remediation + - automatic restore + - one-click restore + - immutable backups + - court-proof evidence + - guarantees audit success + /welcome-to-docs/: + get: + summary: Legacy German docs landing alias + operationId: getLegacyGermanDocsLandingAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/docs/` + "200": + description: Acceptable only if implementation uses an equivalent alias and the rendered content matches `/docs/` + /en/welcome-to-docs/: + get: + summary: Legacy English docs landing alias + operationId: getLegacyEnglishDocsLandingAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/en/docs/` + "200": + description: Acceptable only if implementation uses an equivalent alias and the rendered content matches `/en/docs/` + /guides/intro/: + get: + summary: Legacy German intro docs alias + operationId: getLegacyGermanIntroDocsAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/docs/getting-started/` + /guides/getting-started/: + get: + summary: Legacy German getting-started docs alias + operationId: getLegacyGermanGettingStartedDocsAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/docs/getting-started/` + /guides/first-project-checklist/: + get: + summary: Legacy German evaluation checklist alias + operationId: getLegacyGermanEvaluationChecklistAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/docs/evaluation-pilot/` + /platform/evidence-review/: + get: + summary: Legacy German evidence review docs alias + operationId: getLegacyGermanEvidenceReviewAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/docs/policy-evidence/` + /en/guides/intro/: + get: + summary: Legacy English intro docs alias + operationId: getLegacyEnglishIntroDocsAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/en/docs/getting-started/` + /en/guides/getting-started/: + get: + summary: Legacy English getting-started docs alias + operationId: getLegacyEnglishGettingStartedDocsAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/en/docs/getting-started/` + /en/guides/first-project-checklist/: + get: + summary: Legacy English evaluation checklist alias + operationId: getLegacyEnglishEvaluationChecklistAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/en/docs/evaluation-pilot/` + /en/platform/evidence-review/: + get: + summary: Legacy English evidence review docs alias + operationId: getLegacyEnglishEvidenceReviewAlias + tags: + - Public Website + - Docs + - Legacy Alias + responses: + "301": + description: Permanent redirect or equivalent alias to `/en/docs/policy-evidence/` +components: + schemas: + DocsTopicSlug: + type: string + enum: + - getting-started + - microsoft-365-provider + - permissions-data-access + - data-processing-trust + - policy-evidence + - drift-detection + - backups-versioning-recovery + - findings-exceptions-accepted-risk + - review-packs-decisions + - evaluation-pilot + - known-limitations + - faq + DocsTopicPage: + type: object + required: + - slug + - title + - intro + - sections + properties: + slug: + $ref: '#/components/schemas/DocsTopicSlug' + title: + type: string + intro: + type: string + whatThisPageCovers: + type: string + sections: + type: array + minItems: 3 + maxItems: 6 + items: + $ref: '#/components/schemas/DocsSection' + relatedLinks: + type: array + items: + $ref: '#/components/schemas/RelatedLink' + DocsSection: + type: object + required: + - heading + - content + properties: + heading: + type: string + content: + type: string + RelatedLink: + type: object + required: + - label + - href + properties: + label: + type: string + href: + type: string + pattern: ^/(|en/).+ \ No newline at end of file diff --git a/specs/410-public-docs-ia/data-model.md b/specs/410-public-docs-ia/data-model.md new file mode 100644 index 00000000..687a721b --- /dev/null +++ b/specs/410-public-docs-ia/data-model.md @@ -0,0 +1,154 @@ +# Data Model: Public Docs & Knowledge Base IA + +This feature has no persisted runtime data model. The entities below are static website content structures used to render the public docs IA, its navigation, and its public route contract. They must remain content-only unless a later spec introduces authenticated docs, CMS behavior, or search/indexing changes beyond the current Starlight build. + +## Docs Home Page + +**Represents**: The localized landing page for the public knowledge base. + +**Fields**: + +- `locale`: `de` or `en` +- `slug`: `/docs/` or `/en/docs/` +- `pageTitle`: localized metadata title +- `metaDescription`: localized metadata description +- `heroTitle`: main H1 +- `heroSubtitle`: primary supporting paragraph +- `supportingLine`: audience and evaluation-readiness framing +- `primaryStartLink`: main route into the docs topic tree +- `categoryCards`: ordered topic-card list +- `relatedPublicLinks`: optional real links to trust, evaluation, platform, review-packs, or contact + +**Validation rules**: + +- The page must expose all twelve required topic categories. +- All links must resolve to real public routes. +- Metadata and body copy must avoid unsupported compliance, provider, hosting, or automation claims. + +## Docs Topic Page + +**Represents**: One localized docs topic page under the `/docs` route family. + +**Fields**: + +- `locale`: `de` or `en` +- `slug`: one of the required topic slugs +- `title`: localized H1 +- `metaTitle`: localized metadata title +- `metaDescription`: localized metadata description +- `intro`: short purpose paragraph +- `whatThisPageCovers`: short scope block +- `sections`: ordered 3-6 content sections +- `relatedLinks`: real public links to other docs pages or adjacent public pages +- `claimBoundaryNotes`: optional bounded-scope wording where completeness would be misleading + +**Slug enum**: + +- `getting-started` +- `microsoft-365-provider` +- `permissions-data-access` +- `data-processing-trust` +- `policy-evidence` +- `drift-detection` +- `backups-versioning-recovery` +- `findings-exceptions-accepted-risk` +- `review-packs-decisions` +- `evaluation-pilot` +- `known-limitations` +- `faq` + +**Validation rules**: + +- Each topic page must include title, intro, `what this page covers`, 3-6 sections, and related links. +- Topic pages must use public-facing language rather than internal architecture jargon. +- Topic pages must not invent a complete Microsoft permission matrix, legal downloads, or unsupported feature claims. + +## Category Card + +**Represents**: One topic entry on the docs home page. + +**Fields**: + +- `slug`: one of the docs topic slugs +- `label`: localized visible label +- `summary`: short public description +- `href`: real localized docs route + +**Validation rules**: + +- Card order must match the approved IA order in the plan/spec. +- Card text must describe user questions, not internal modules. + +## Sidebar Section + +**Represents**: One explicit grouping of docs topic links in the Starlight sidebar. + +**Fields**: + +- `key`: stable config key +- `label`: localized visible label +- `items`: ordered topic links + +**Validation rules**: + +- Sidebar order must stay explicit rather than implicit from directory autogeneration. +- Grouping may improve readability, but it must not hide or rename the required topic pages. + +## Related Public Link + +**Represents**: A public handoff from docs to another verified public route. + +**Fields**: + +- `label`: visible link label +- `href`: real localized route +- `placement`: docs-home, docs-topic, homepage, platform, trust, evaluation, review-packs, use-case, nav, or footer + +**Validation rules**: + +- Links must point only to routes that exist in the current site. +- No placeholder anchors or fake downloads are allowed. + +## Legacy Docs Alias + +**Represents**: A current public starter-docs route that must continue to resolve after the new docs IA ships. + +**Fields**: + +- `from`: current public URL +- `to`: new public docs URL +- `locale`: `de` or `en` +- `reason`: continuity rationale + +**Required mappings**: + +- `/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/` + +**Validation rules**: + +- Alias handling must preserve user-facing continuity for any currently exposed docs route. +- The project must not keep both old and new docs pages as permanent parallel truth. + +## Footer / Navigation Docs Link + +**Represents**: The global public-site docs entry point exposed through existing navigation and footer structures. + +**Fields**: + +- `label`: `Docs` or localized equivalent already used by the site +- `href`: `/docs/` or `/en/docs/` +- `surface`: `nav` or `footer` + +**Validation rules**: + +- The docs href must be localized via the existing locale helper path. +- Any previous `/welcome-to-docs/` references in navigation or footer must be migrated. \ No newline at end of file diff --git a/specs/410-public-docs-ia/plan.md b/specs/410-public-docs-ia/plan.md new file mode 100644 index 00000000..50b316fd --- /dev/null +++ b/specs/410-public-docs-ia/plan.md @@ -0,0 +1,375 @@ +# 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. \ No newline at end of file diff --git a/specs/410-public-docs-ia/quickstart.md b/specs/410-public-docs-ia/quickstart.md new file mode 100644 index 00000000..2287489a --- /dev/null +++ b/specs/410-public-docs-ia/quickstart.md @@ -0,0 +1,224 @@ +# 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 \ No newline at end of file diff --git a/specs/410-public-docs-ia/research.md b/specs/410-public-docs-ia/research.md new file mode 100644 index 00000000..e0ab8e42 --- /dev/null +++ b/specs/410-public-docs-ia/research.md @@ -0,0 +1,96 @@ +# 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. \ No newline at end of file diff --git a/specs/410-public-docs-ia/spec.md b/specs/410-public-docs-ia/spec.md new file mode 100644 index 00000000..bc23a60f --- /dev/null +++ b/specs/410-public-docs-ia/spec.md @@ -0,0 +1,334 @@ +# Feature Specification: Public Docs & Knowledge Base IA + +**Feature Branch**: `410-public-docs-ia` +**Created**: 2026-05-31 +**Status**: Draft +**Input**: User description: "Create the public documentation and knowledge-base information architecture for Tenantial so the website supports evaluation, Microsoft 365 provider understanding, permissions and data access transparency, trust and data-processing review, policy evidence, drift detection, backups and recovery semantics, findings and accepted risk, review packs, known limitations, and FAQ without any `apps/platform` runtime changes." + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: The public website explains positioning, trust, provider scope, use cases, review story, and evaluation readiness, but it still lacks one durable documentation destination for deeper buyer, operator, security, Datenschutz, and procurement questions. +- **Today's failure**: Prospects must reconstruct answers across multiple marketing pages or ask manual follow-up questions about provider connections, permissions, data categories, evidence, drift, recovery boundaries, review packs, and known limitations. +- **User-visible improvement**: A public visitor can find one coherent documentation area that answers deeper evaluation and governance questions in bounded, claim-safe language before a demo or pilot. +- **Smallest enterprise-capable version**: One public docs hub with durable categories, either real child pages or one well-structured landing page depending on current website IA, plus real discovery links, metadata, FAQ, and limitations coverage. +- **Explicit non-goals**: No `apps/platform` work, no contextual in-product help, no CMS, no search backend, no authenticated docs, no API docs, no support workflow, no fake downloads, no fake permission matrix, no fake compliance claims, and no placeholder links. +- **Permanent complexity imported**: One bounded public docs IA, up to twelve public documentation entry points or sections, related-link maintenance across existing public pages, metadata updates, and continuing copy-governance responsibilities. No models, persistence, runtime abstractions, or product-state machinery are introduced. +- **Why now**: Specs 404 through 409 established the public story for positioning, trust, provider scope, use cases, review/evidence, and evaluation. The next friction point is the absence of a durable public documentation surface that makes those stories explorable and reviewable. +- **Why not local**: Adding a few extra blurbs to existing pages would keep technical and procurement answers fragmented and would not create one inspectable documentation destination for evaluators. +- **Approval class**: Core Enterprise. +- **Red flags triggered**: IA touch across multiple public entry points, public overclaim risk, documentation taxonomy breadth, and Microsoft 365 permission wording that could drift into unverified detail. +- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12** +- **Decision**: approve. + +### Red Flag Defense + +This spec is intentionally limited to public website information architecture and claim-safe documentation copy. It does not add runtime help systems, product logic, provider capabilities, legal downloads, or search infrastructure. The value comes from making existing public product truth explorable without pretending that undocumented or unverified capabilities already exist. + +## Scope + +This spec defines the public documentation and knowledge-base IA for Tenantial so the website can answer deeper evaluation, governance, trust, and buyer-readiness questions in one coherent destination. + +- **Relevant application for later implementation**: public website only +- **Depends on**: Spec 404 - Public Website Sales Copy & Positioning Rewrite; Spec 405 - DACH Trust, Datenschutz & Security Website Surface; Spec 406 - Provider & Policy Domain Public Taxonomy; Spec 407 - MSP & Mittelstand Use-Case Pages; Spec 408 - Customer-safe Review, Evidence & Decision Story; Spec 409 - Evaluation, Procurement & Rollout Readiness Website Surface +- **Must not depend on**: `apps/platform` runtime changes +- **Primary audience**: MSP operators, IT admins, Microsoft 365 admins, security reviewers, Datenschutz stakeholders, procurement teams, DACH Mittelstand buyers, and enterprise IT evaluators +- **Public message**: Tenantial provides a public documentation surface that explains Microsoft 365 provider context, permissions and data access thinking, policy evidence, drift, backup and recovery semantics, findings and accepted risk, review packs, evaluation readiness, and known limitations in careful public language +- **Out of scope**: platform help center behavior, CMS workflows, authenticated docs, search backend, AI support, support ticketing, provider runtime logic, Microsoft Graph permission execution, review-pack generation, data export, fake AVV/TOM downloads, fake permission matrices, fake screenshots implying unavailable features, root workspace contract changes, and non-website implementation work + +## Goals + +- **G1**: Create one public documentation landing point that is easy to discover from the existing website. +- **G2**: Organize docs around durable buyer and operator questions rather than internal implementation modules. +- **G3**: Help security, Datenschutz, procurement, and technical evaluators understand provider access, data categories, trust boundaries, and governance concepts. +- **G4**: Explain evidence, drift, recovery context, findings, accepted risk, review packs, and evaluation scope in plain public language. +- **G5**: Keep the docs honest by avoiding fake completeness, fake downloadable artifacts, or unverified product, provider, compliance, or automation claims. +- **G6**: Leave space for future docs expansion such as detailed permission matrices, onboarding guides, localization, search, or versioning without requiring them now. + +## Non-goals + +- No `apps/platform` changes. +- No in-product contextual help. +- No CMS or editorial backend. +- No authenticated documentation area. +- No search backend or AI assistant. +- No support ticketing or customer portal workflow. +- No API documentation. +- No Microsoft Graph runtime logic or consent flow. +- No onboarding runtime. +- No RBAC runtime changes. +- No review-pack generation or export behavior. +- No real AVV, TOM, DPA, or compliance-document download unless those assets already exist as verified public truth. +- No fake PDFs, placeholder links, fake screenshots, or `href="#"`. +- No Google, AWS, or multi-cloud availability claims unless those providers are already verified public truth. + +## Spec Scope Fields *(mandatory)* + +- **Scope**: N/A - public website IA outside authenticated workspace, tenant, or canonical product flows +- **Primary Routes**: preferred public docs family `/docs`; German-first alternative `/dokumentation` only if current site conventions already support that route style; child routes only when the current website supports nested documentation pages cleanly +- **Data Ownership**: no workspace-owned, tenant-owned, provider-owned, or customer-owned product data is created, changed, or persisted by this feature +- **RBAC**: public read-only content only; no membership, role, capability, authorization, or authenticated product behavior changes + +For canonical-view specs, the spec MUST define: + +- **Default filter behavior when tenant-context is active**: N/A - no tenant-context or canonical product view is introduced +- **Explicit entitlement checks preventing cross-tenant leakage**: N/A - no authenticated tenant, workspace, provider, or customer data is involved + +## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)* + +- **Cross-cutting feature?**: yes +- **Interaction class(es)**: public navigation, footer links, homepage or platform teasers, trust and evaluation crosslinks, docs cards or section lists, FAQ entries, and metadata +- **Systems touched**: current public website shell, route conventions, navigation, footer, related public pages, reusable section or card components, and metadata helpers +- **Existing pattern(s) to extend**: existing public page layouts, card or grid patterns, teaser conventions, link conventions, and metadata conventions +- **Shared contract / presenter / builder / renderer to reuse**: current website content structures and reusable public presentation components +- **Why the existing shared path is sufficient or insufficient**: the site already contains adjacent public story surfaces; this feature needs one coherent documentation destination inside that shell rather than a separate docs product or a new design system +- **Allowed deviation and why**: a dedicated docs route family is allowed when the current IA supports it because the knowledge base must be inspectable as a distinct public destination rather than scattered across unrelated marketing sections +- **Consistency impact**: Microsoft 365-first language, provider-connection wording, permissions and data-access boundaries, trust references, evidence and drift language, and known-limitations posture must stay aligned across docs and the existing public pages that link into them +- **Review focus**: verify that docs add technical clarity beyond marketing pages, all links are real, categories stay understandable, and copy does not drift into unverified provider, compliance, permissions, automation, or download claims + +## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)* + +- **Touches OperationRun start/completion/link UX?**: no +- **Shared OperationRun UX contract/layer reused**: N/A +- **Delegated start/completion UX behaviors**: N/A +- **Local surface-owned behavior that remains**: none +- **Queued DB-notification policy**: N/A +- **Terminal notification path**: N/A +- **Exception required?**: none + +## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)* + +- **Shared provider/platform boundary touched?**: yes +- **Boundary classification**: mixed public vocabulary only +- **Seams affected**: provider-connection framing, permissions and data-access explanations, Microsoft 365-first scope language, policy evidence vocabulary, drift and recovery wording, and related trust references +- **Neutral platform terms preserved or introduced**: provider connection, permissions and data access, data categories, policy evidence, drift detection, review pack, accepted risk, recovery context, evaluation scope, and known limitations +- **Provider-specific semantics retained and why**: Microsoft 365 remains explicit because the current public scope is still Microsoft 365 governance and the docs must feel concrete for current evaluators +- **Why this does not deepen provider coupling accidentally**: the feature introduces no runtime provider contracts, capability registries, permission matrices, or shared product abstractions; it only explains current public scope in website copy +- **Follow-up path**: follow-up-spec only if later work adds verified multi-provider public truth or a detailed permission matrix + +## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)* + +N/A - public website documentation surface only; no authenticated operator-facing product surface is changed. + +## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing product surface change. + +## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)* + +N/A - public buyer-facing and evaluator-facing copy only; no operator diagnostics, support mode, or raw evidence surface is added. + +## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing product surface change. + +## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing product surface change. + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +- **New source of truth?**: no +- **New persisted entity/table/artifact?**: no +- **New abstraction?**: no +- **New enum/state/reason family?**: no +- **New cross-domain UI framework/taxonomy?**: no - the feature reuses the current public website shell and existing content patterns +- **Current operator problem**: public evaluators, security reviewers, and technical buyers still cannot self-serve deeper Tenantial questions without reconstructing answers across multiple pages or manual follow-up conversations +- **Existing structure is insufficient because**: the homepage, trust, provider, use-case, review, and evaluation pages answer adjacent questions, but they do not form a durable knowledge base with clear categories and bounded concept pages +- **Narrowest correct implementation**: one public docs hub plus either nested child pages or clearly separated landing-page sections, depending on the current website IA +- **Ownership cost**: public copy, metadata, and related-link accuracy must stay aligned with actual product scope, trust posture, and public route availability +- **Alternative intentionally rejected**: adding only incremental FAQ or teaser content to existing pages, because that would keep deeper answers fragmented and harder to review +- **Release truth**: current public website truth only; no runtime product promise or future abstraction is introduced + +### Compatibility posture + +This feature assumes a pre-production environment. + +Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec. + +Canonical replacement is preferred over preservation. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: Browser +- **Validation lane(s)**: browser, confidence +- **Why this classification and these lanes are sufficient**: public website quality is proven by reachable routes, understandable documentation IA, readable desktop and mobile layouts, real navigation and footer entry points, static claim scans, and any existing website build or check commands that validate the public site +- **New or expanded test families**: none beyond website-only static checks and any existing public-site smoke coverage +- **Fixture / helper cost impact**: none +- **Heavy-family visibility / justification**: none +- **Special surface test profile**: N/A - public website surface +- **Standard-native relief or required special coverage**: ordinary public-site coverage only; verify docs landing reachability, child-page reachability when implemented, crosslink integrity, claim-boundary compliance, and absence of placeholder links +- **Reviewer handoff**: confirm only website-facing files change, no `apps/platform` files change, the docs route follows current IA, categories and related links are real, and copy stays bounded around permissions, trust, evidence, drift, recovery, limitations, and FAQ +- **Budget / baseline / trend impact**: none expected +- **Escalation needed**: follow-up-spec only if later work introduces search, localization, authenticated docs, downloadable trust artifacts, or detailed provider-permission matrices +- **Active feature PR close-out entry**: Smoke Coverage +- **Planned validation commands**: + - inspect root and website package manifests before running website commands + - run only existing website `check`, `build`, or `test` commands if present + - run static scans for placeholder links, banned internal phrases, and unsupported public claims in website source and committed public assets + - run desktop and mobile browser smoke for the docs landing page, relevant child pages, and any homepage, platform, trust, provider, review, or evaluation crosslinks if local preview is available + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Evaluators Find A Coherent Docs Hub (Priority: P1) + +An MSP operator, Microsoft 365 admin, or technical evaluator opens the public docs and quickly understands where to start, which concepts are documented, and where to go for provider, permissions, evidence, drift, recovery, and review questions. + +**Why this priority**: The core value of the feature is creating one inspectable documentation destination instead of leaving deeper questions fragmented across marketing pages. + +**Independent Test**: Can be fully tested by opening the docs landing page and confirming that the hero, category structure, and real links make the knowledge base understandable without needing other pages first. + +**Acceptance Scenarios**: + +1. **Given** a first-time evaluator lands on the docs area, **When** they scan the hero and category grid or sections, **Then** they understand that the docs cover evaluation, provider context, permissions and data access, trust, evidence, drift, recovery, review packs, limitations, and FAQ. +2. **Given** a visitor wants to start with basics, **When** they choose the getting-started entry point, **Then** they find a concise explanation of what Tenantial is, what it is not, and how to approach an initial evaluation. +3. **Given** a visitor enters the docs from another public page, **When** they arrive at the docs landing page, **Then** the route, page title, and categories clearly identify the destination as documentation rather than another generic marketing section. + +--- + +### User Story 2 - Security, Datenschutz, And Procurement Reviewers Get Bounded Answers (Priority: P1) + +A security reviewer, Datenschutz stakeholder, or procurement contact can use the public docs to understand what kind of provider access, data-processing context, trust references, limitations, and review materials are relevant before deeper due diligence. + +**Why this priority**: Public trust and evaluation friction often appears in review and procurement conversations rather than in product positioning alone. + +**Independent Test**: Can be fully tested by reviewing the permissions, data-processing, trust, evaluation, limitations, and FAQ docs to confirm that they answer common review questions without overclaiming. + +**Acceptance Scenarios**: + +1. **Given** a security or Datenschutz stakeholder opens the docs area, **When** they review the permissions and data-processing topics, **Then** they can identify the relevant categories of questions without seeing an invented permission matrix or unverified compliance promise. +2. **Given** a procurement or vendor-management stakeholder looks for review readiness information, **When** they open the evaluation, review-pack, or FAQ pages, **Then** they understand which topics belong in a pilot or trust review and which artifacts depend on actual product scope. +3. **Given** a reviewer scans the docs for legal or security claims, **When** they read the trust and limitations language, **Then** they do not see fake certifications, fake downloads, or misleading statements about customer data, hosting, or automatic compliance. + +--- + +### User Story 3 - Technical Buyers Understand Provider, Evidence, Drift, And Recovery Concepts (Priority: P2) + +A technical owner can understand how Tenantial frames Microsoft 365 provider connections, permissions and data access, policy evidence, drift detection, backup context, recovery context, findings, accepted risk, and review packs without reading internal architecture language. + +**Why this priority**: The docs must deepen technical understanding, not just restate marketing claims. + +**Independent Test**: Can be fully tested by opening the concept pages and confirming that each topic explains practical meaning, boundaries, and related links in buyer-friendly public language. + +**Acceptance Scenarios**: + +1. **Given** a technical evaluator wants to understand provider access, **When** they open the provider or permissions docs, **Then** they see careful language about scope, consent, read-oriented access, and recovery-adjacent access without an unverified full permission list. +2. **Given** a visitor wants to understand evidence and drift, **When** they open the relevant docs pages, **Then** they see how those concepts relate to findings, reviews, and decision support without promises of real-time detection or automatic remediation. +3. **Given** a visitor wants to understand backups and recovery, **When** they open the relevant docs page, **Then** they learn that recovery depends on scope, dependencies, evidence, and review context rather than a one-click rollback promise. + +--- + +### User Story 4 - Visitors Reach Docs Through Real Information Architecture (Priority: P2) + +A visitor should be able to reach the docs from the public navigation, footer, homepage, platform page, trust page, evaluation page, or related concept pages wherever those entry points already exist and support a real link. + +**Why this priority**: The documentation only reduces evaluation friction if it is discoverable from the public pages where buyers already start. + +**Independent Test**: Can be fully tested by following every new teaser, nav link, footer link, or related link added by the feature on desktop and mobile and confirming that each destination is real. + +**Acceptance Scenarios**: + +1. **Given** a visitor uses a docs link from the homepage, platform, trust, evaluation, or another related public page, **When** they follow that link, **Then** they land on the docs hub or a real child page. +2. **Given** a visitor uses the footer or navigation to open docs, **When** they arrive on the destination, **Then** the route resolves cleanly and the docs IA is readable. +3. **Given** a related destination does not exist in the current site IA, **When** the implementation is completed, **Then** the missing link is omitted rather than replaced with a placeholder. + +### Edge Cases + +- What happens when the current website does not support nested docs routes cleanly? The implementation must deliver a single real docs landing page with internal sections instead of inventing fake child links. +- What happens when some related public pages from earlier specs are missing or renamed locally? Only real routes may be linked, and the IA decision must document which crosslinks are included or omitted. +- What happens when a detailed Microsoft 365 permission matrix is not verified as public truth? The docs must describe permission thinking and readiness at a bounded level and defer exact matrices. +- What happens when trust artifacts such as AVV, DPA, or TOM are not available as public downloads? The docs may reference their status or review path, but they must not imply self-service downloads. +- What happens when the current site language strategy is German-first, English-first, or mixed? The docs route, labels, and slugs must follow the existing site convention rather than introducing a new localization foundation. +- What happens when documentation copy starts to sound like internal specs or architecture notes? Public-facing language must win over internal jargon even when the underlying concept is technically complex. + +## Assumptions + +- The current public website can support one real documentation destination without changing root workspace contracts. +- Microsoft 365 remains the first public provider focus for current documentation scope. +- Related public pages from Specs 404 through 409 exist in some form, but any missing route may be omitted from crosslinks. +- Detailed permission matrices, downloadable trust packs, localization, search, and versioned docs are future expansions rather than required v1 scope. +- The current website has existing layout, link, and metadata conventions that the docs area should reuse rather than replace. + +## Requirements *(mandatory)* + +This feature introduces no Microsoft Graph calls, no write/change product behavior, no persistence, no OperationRun flow, no RBAC mutation, and no provider runtime capability. Its only additions are bounded public documentation routes or sections, discoverability links, metadata, and claim-safe copy that translate current public product truth into a durable docs IA. + +### Functional Requirements + +#### Documentation Destination And IA + +- **FR-001**: The implementation MUST remain public-website-only and MUST NOT require `apps/platform` runtime changes. +- **FR-002**: The public website MUST provide one dedicated documentation destination for deeper evaluation and governance questions. +- **FR-003**: The preferred route family MUST be `/docs`, with `/dokumentation` allowed only when the existing website conventions are German-first and route-compatible. +- **FR-004**: The implementation MUST follow current local route conventions rather than introducing a new routing foundation. +- **FR-005**: The implementation MUST document whether the site supports nested docs child pages or only a single landing page with category sections. +- **FR-006**: The documentation IA MUST be organized around durable user questions rather than internal implementation modules. + +#### Required Documentation Topics + +- **FR-007**: The docs landing experience MUST expose the following topic categories: Getting Started; Microsoft 365 Provider Connection; Permissions and Data Access; Data Processing and Trust; Policy Evidence; Drift Detection; Backups, Versioning and Recovery; Findings, Exceptions and Accepted Risk; Review Packs and Decisions; Evaluation and Pilot; Known Limitations; FAQ. +- **FR-008**: If nested routes are supported by the current website IA, each required topic MUST have its own real public child page. +- **FR-009**: If nested routes are not supported without broad refactoring, the landing page MUST present the required topics as clear sections and MUST NOT advertise fake child routes. +- **FR-010**: The docs landing page MUST explain that the area supports evaluation, provider understanding, trust review, governance concepts, and buyer readiness. + +#### Page And Section Content + +- **FR-011**: The Getting Started content MUST explain what Tenantial is, what it is not, why Microsoft 365 is the first public focus, and how a first evaluation can begin. +- **FR-012**: The Microsoft 365 Provider Connection content MUST explain provider connection concepts, scope, consent thinking, and the difference between read-oriented and recovery-adjacent scenarios without exposing internal platform implementation. +- **FR-013**: The Permissions and Data Access content MUST explain why permissions are discussed, how access depends on scope, and why exact permission matrices may be documented separately when verified. +- **FR-014**: The Data Processing and Trust content MUST explain relevant data categories, governance metadata versus productive content, trust references, and review boundaries without making unverified privacy or compliance claims. +- **FR-015**: The Policy Evidence content MUST explain evidence in relation to policy state, findings, reviews, and recovery context rather than reducing the concept to screenshots. +- **FR-016**: The Drift Detection content MUST explain expected versus observed state, why drift matters, how drift relates to findings and review, and what drift detection does not mean. +- **FR-017**: The Backups, Versioning and Recovery content MUST explain versioned policy-state thinking, backup context, recovery context, limitations, and the rejection of blind-restore framing. +- **FR-018**: The Findings, Exceptions and Accepted Risk content MUST explain those governance concepts, their review context, and their practical meaning without implying automatic approvals or legal determinations. +- **FR-019**: The Review Packs and Decisions content MUST explain review-pack structure, executive summary, evidence basis, findings, accepted risks, and decision summary in customer-safe terms. +- **FR-020**: The Evaluation and Pilot content MUST explain how an evaluation can start, who should be involved, what scope matters, and how trust and security review fit into the path. +- **FR-021**: The Known Limitations content MUST state clearly what Tenantial does not replace or automate and MUST do so in a confident, non-apologetic tone. +- **FR-022**: The FAQ content MUST answer recurring buyer questions about scope, permissions, automation, helpdesk expectations, admin-center replacement, review packs, evidence, drift, pilot readiness, and review materials. + +#### Claim Safety And Public Language + +- **FR-023**: Public docs copy MUST use buyer-friendly and operator-friendly language such as documentation, provider connection, permissions and data access, policy evidence, drift detection, recovery context, findings, accepted risk, review packs, evaluation, and known limitations. +- **FR-024**: Public docs copy MUST NOT use internal architecture or spec jargon as primary explanatory language. +- **FR-025**: The documentation MUST NOT invent a complete Microsoft permission list unless that list already exists as verified public truth. +- **FR-026**: The documentation MUST NOT claim DSGVO compliance, ISO certification, NIS2 compliance, Germany-only hosting, absence of customer data, absence of personal data, Google support, AWS support, multi-cloud support, real-time drift, automatic remediation, automatic restore, one-click restore, immutable backups, audit guarantees, or compliance guarantees unless explicitly verified public truth exists. +- **FR-027**: When product scope is still bounded or route-specific, the docs MUST use careful language such as scope-dependent, review-based, customer-safe, or available when supported by product scope. +- **FR-028**: The docs MUST avoid fake completeness; when a topic is not fully public yet, the page or section MUST still be useful and honest about scope boundaries. + +#### Navigation, Discovery, And Related Links + +- **FR-029**: The docs area MUST be reachable from at least one existing public-site entry point such as navigation, footer, homepage, platform, trust, provider, review, or evaluation surfaces. +- **FR-030**: Every teaser, related link, CTA, nav item, and footer item added by this feature MUST resolve to a real destination; placeholder links and `href="#"` are forbidden. +- **FR-031**: Related links inside docs pages MUST point only to public routes that actually exist in the current site. +- **FR-032**: If the current site supports a sidebar or secondary docs navigation pattern, it MAY be used, but only if it remains simple and consistent with current conventions. + +#### Metadata And Future Expansion + +- **FR-033**: The docs landing page and any real child pages MUST provide page-specific titles and descriptions that match the documentation topic and avoid unsafe claims. +- **FR-034**: If the current website supports canonical metadata, the docs landing page and child pages MUST reuse that support. +- **FR-035**: The docs IA MUST leave room for future additions such as permission matrices, onboarding guides, localization, search, review-pack examples, and versioned docs without requiring those capabilities in this feature. + +#### Verification Expectations + +- **FR-036**: Implementation work MUST verify current local website conventions for routing, navigation, footer, metadata, reusable content structures, and language strategy before choosing the final docs IA shape. +- **FR-037**: Implementation work MUST run only website commands that already exist in the repository. +- **FR-038**: Implementation work MUST statically scan website source and any committed public output for placeholder links, banned internal phrases, and unsupported claims introduced by this feature. +- **FR-039**: If local preview is available, implementation work MUST browser-smoke the docs landing page, relevant child pages, and the real crosslinks added by this feature on desktop and mobile. +- **FR-040**: Final implementation reporting MUST state the chosen docs route, whether child pages were created, which website commands were run, and confirm that `apps/platform` remained untouched. + +### Key Entities *(include if feature involves data)* + +- **Documentation Hub**: The primary public entry point for deeper Tenantial documentation, category discovery, and related public links. +- **Documentation Category**: A durable topic grouping such as permissions, trust, evidence, drift, recovery, or FAQ that reflects a user question rather than an internal module. +- **Documentation Page**: A bounded public concept page or section that explains one topic in claim-safe language and links to relevant adjacent public pages. +- **FAQ Entry**: A concise public answer to a recurring buyer, evaluator, or reviewer question. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: A first-time public evaluator can identify where to start and which documentation topic answers their question within 60 seconds of opening the docs landing page. +- **SC-002**: Each required documentation category is reachable in one click or one in-page jump from the docs landing experience. +- **SC-003**: Security, Datenschutz, procurement, and technical evaluators can each find at least one clearly relevant public docs path without encountering placeholder links or fake downloadable artifacts. +- **SC-004**: Static verification finds zero new placeholder links, banned internal phrases, or unsupported public claims introduced by this feature. +- **SC-005**: Desktop and mobile smoke checks confirm that the docs landing page and any real child pages remain readable and navigable. +- **SC-006**: The final implementation changes only website-facing files and leaves `apps/platform` untouched. \ No newline at end of file diff --git a/specs/410-public-docs-ia/tasks.md b/specs/410-public-docs-ia/tasks.md new file mode 100644 index 00000000..e97a3057 --- /dev/null +++ b/specs/410-public-docs-ia/tasks.md @@ -0,0 +1,252 @@ +# Tasks: Public Docs & Knowledge Base IA + +**Input**: Design documents from `/specs/410-public-docs-ia/` +**Prerequisites**: `plan.md` (required), `spec.md` (required), `research.md`, `data-model.md`, `quickstart.md`, `contracts/public-docs-routes.openapi.yaml` + +**Tests**: Runtime behavior changes are in scope for `apps/website`, so browser smoke, route and metadata assertions, legacy-route continuity checks, and static claim scans are required. + +## Test Governance Checklist + +- Lane assignment: `Browser` in `browser, confidence` remains the narrowest sufficient proof for this feature. +- New or changed tests stay inside the existing public-website smoke family in `apps/website/tests/smoke/`. +- Shared helpers and fixtures stay cheap by default; no new heavy helpers, factories, or setup layers are introduced. +- Planned validation commands remain limited to `build`, `public-routes.spec.ts`, and `interaction.spec.ts` from `apps/website/package.json`. +- Surface test profile stays `public website`, with `document-in-feature` as the escalation path recorded in `specs/410-public-docs-ia/plan.md`. + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: Confirm repo contracts, current Starlight ownership, and the exact public surfaces that the docs IA may touch. + +- [x] T001 Confirm active feature scope, user stories, docs route family, and legacy URL continuity decisions in `specs/410-public-docs-ia/spec.md` and `specs/410-public-docs-ia/plan.md` +- [x] T002 Verify root workspace contracts remain unchanged in `package.json` and `pnpm-workspace.yaml` +- [x] T003 Verify website validation scripts and docs stack packages in `apps/website/package.json` and `apps/website/astro.config.mjs` +- [x] T004 Map current docs collection, starter docs files, Starlight ownership, and existing metadata/canonical handling in `apps/website/src/content.config.ts`, `apps/website/src/content/docs/`, `apps/website/astro.config.mjs`, and `apps/website/src/pages/` +- [x] T005 [P] Map global docs entry-point ownership in `apps/website/src/data_files/site-copy.ts`, `apps/website/src/components/sections/navbar&footer/Navbar.astro`, `apps/website/src/components/sections/navbar&footer/FooterSection.astro`, and `apps/website/src/i18n.ts` +- [x] T006 [P] Map current docs smoke coverage, legacy docs routes, and discovery assertions in `apps/website/tests/smoke/smoke-helpers.ts`, `apps/website/tests/smoke/public-routes.spec.ts`, and `apps/website/tests/smoke/interaction.spec.ts` + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Establish the shared docs base route, route inventory, and content skeleton that every story depends on. + +**Critical**: No user story work should begin before this phase is complete. + +- [x] T007 Move the Starlight docs base route to `/docs` and replace starter sidebar autogeneration with the explicit topic IA in `apps/website/astro.config.mjs` +- [x] T008 Create the localized docs landing and child-page scaffolds in `apps/website/src/content/docs/index.mdx`, `apps/website/src/content/docs/getting-started.mdx`, `apps/website/src/content/docs/microsoft-365-provider.mdx`, `apps/website/src/content/docs/permissions-data-access.mdx`, `apps/website/src/content/docs/data-processing-trust.mdx`, `apps/website/src/content/docs/policy-evidence.mdx`, `apps/website/src/content/docs/drift-detection.mdx`, `apps/website/src/content/docs/backups-versioning-recovery.mdx`, `apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx`, `apps/website/src/content/docs/review-packs-decisions.mdx`, `apps/website/src/content/docs/evaluation-pilot.mdx`, `apps/website/src/content/docs/known-limitations.mdx`, `apps/website/src/content/docs/faq.mdx`, and matching files under `apps/website/src/content/docs/en/` +- [x] T009 Add baseline docs route inventory, docs-route metadata hooks, canonical-metadata reuse coverage, and localized docs coverage in `apps/website/tests/smoke/smoke-helpers.ts` and `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T010 Configure legacy docs URL continuity for `/welcome-to-docs/`, `/guides/*`, and `/platform/evidence-review/` in `apps/website/astro.config.mjs` +- [x] T011 Confirm the planned docs route matrix, child-page shape, and legacy alias mapping remain aligned between `specs/410-public-docs-ia/plan.md` and `specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml` + +**Checkpoint**: Foundation is ready for story implementation. + +--- + +## Phase 3: User Story 1 - Evaluators Find A Coherent Docs Hub (Priority: P1) 🎯 MVP + +**Goal**: Deliver the core docs landing experience and the first entry page so evaluators can understand the IA and begin with the right concepts. + +**Independent Test**: Open `/docs/`, `/en/docs/`, `/docs/getting-started/`, and `/en/docs/getting-started/`, then confirm the hero, category structure, category links, and getting-started content make the docs understandable without any other page first. + +### Tests for User Story 1 + +- [x] T012 [P] [US1] Add route title and description assertions for `/docs/`, `/en/docs/`, `/docs/getting-started/`, and `/en/docs/getting-started/` in `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T013 [P] [US1] Add docs landing IA, category-card, related-link, and getting-started readability assertions in `apps/website/tests/smoke/interaction.spec.ts` + +### Implementation for User Story 1 + +- [x] T014 [US1] Author the localized docs landing page content, category summaries, and related public handoffs in `apps/website/src/content/docs/index.mdx` and `apps/website/src/content/docs/en/index.mdx` +- [x] T015 [US1] Author the localized getting-started page content in `apps/website/src/content/docs/getting-started.mdx` and `apps/website/src/content/docs/en/getting-started.mdx` +- [x] T016 [US1] Keep the sidebar labels and docs-home category ordering aligned with the landing-page IA in `apps/website/astro.config.mjs`, `apps/website/src/content/docs/index.mdx`, and `apps/website/src/content/docs/en/index.mdx` + +**Checkpoint**: User Story 1 is independently functional and demonstrable. + +--- + +## Phase 4: User Story 2 - Security, Datenschutz, And Procurement Reviewers Get Bounded Answers (Priority: P1) + +**Goal**: Explain permissions, data processing, trust context, review-pack framing, evaluation readiness, limitations, and FAQ boundaries without fake legal or product claims. + +**Independent Test**: Open the reviewer-oriented docs pages and confirm they answer security, Datenschutz, procurement, and trust-readiness questions without overclaiming permissions, compliance, hosting, downloads, or automation. + +### Tests for User Story 2 + +- [x] T017 [P] [US2] Add route title and description assertions for `/docs/permissions-data-access/`, `/docs/data-processing-trust/`, `/docs/review-packs-decisions/`, `/docs/evaluation-pilot/`, `/docs/known-limitations/`, `/docs/faq/`, and English counterparts in `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T018 [P] [US2] Add permissions, trust, evaluation, limitations, and FAQ content assertions in `apps/website/tests/smoke/interaction.spec.ts` +- [x] T019 [P] [US2] Extend forbidden-claim and real-related-link coverage for reviewer docs pages in `apps/website/tests/smoke/smoke-helpers.ts` + +### Implementation for User Story 2 + +- [x] T020 [P] [US2] Author the localized permissions and data-processing pages in `apps/website/src/content/docs/permissions-data-access.mdx`, `apps/website/src/content/docs/data-processing-trust.mdx`, `apps/website/src/content/docs/en/permissions-data-access.mdx`, and `apps/website/src/content/docs/en/data-processing-trust.mdx` +- [x] T021 [P] [US2] Author the localized review-packs and evaluation-pilot pages in `apps/website/src/content/docs/review-packs-decisions.mdx`, `apps/website/src/content/docs/evaluation-pilot.mdx`, `apps/website/src/content/docs/en/review-packs-decisions.mdx`, and `apps/website/src/content/docs/en/evaluation-pilot.mdx` +- [x] T022 [P] [US2] Author the localized known-limitations and FAQ pages in `apps/website/src/content/docs/known-limitations.mdx`, `apps/website/src/content/docs/faq.mdx`, `apps/website/src/content/docs/en/known-limitations.mdx`, and `apps/website/src/content/docs/en/faq.mdx` + +**Checkpoint**: User Story 2 is independently functional and demonstrable. + +--- + +## Phase 5: User Story 3 - Technical Buyers Understand Provider, Evidence, Drift, And Recovery Concepts (Priority: P2) + +**Goal**: Explain provider connection, evidence, drift, recovery context, and findings concepts in public language without leaking internal architecture or unsupported automation claims. + +**Independent Test**: Open the technical concept pages and verify they explain practical meaning, boundaries, and related links for provider access, evidence, drift, findings, and recovery without publishing an unverified permission matrix or one-click restore promise. + +### Tests for User Story 3 + +- [x] T023 [P] [US3] Add route title and description assertions for `/docs/microsoft-365-provider/`, `/docs/policy-evidence/`, `/docs/drift-detection/`, `/docs/backups-versioning-recovery/`, `/docs/findings-exceptions-accepted-risk/`, and English counterparts in `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T024 [P] [US3] Add provider, evidence, drift, findings, and recovery content assertions in `apps/website/tests/smoke/interaction.spec.ts` +- [x] T025 [P] [US3] Extend provider-boundary, automation-overclaim, and recovery-boundary coverage for technical docs pages in `apps/website/tests/smoke/smoke-helpers.ts` + +### Implementation for User Story 3 + +- [x] T026 [P] [US3] Author the localized provider and policy-evidence pages in `apps/website/src/content/docs/microsoft-365-provider.mdx`, `apps/website/src/content/docs/policy-evidence.mdx`, `apps/website/src/content/docs/en/microsoft-365-provider.mdx`, and `apps/website/src/content/docs/en/policy-evidence.mdx` +- [x] T027 [P] [US3] Author the localized drift and recovery pages in `apps/website/src/content/docs/drift-detection.mdx`, `apps/website/src/content/docs/backups-versioning-recovery.mdx`, `apps/website/src/content/docs/en/drift-detection.mdx`, and `apps/website/src/content/docs/en/backups-versioning-recovery.mdx` +- [x] T028 [P] [US3] Author the localized findings and accepted-risk page in `apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx` and `apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx` + +**Checkpoint**: User Story 3 is independently functional and demonstrable. + +--- + +## Phase 6: User Story 4 - Visitors Reach Docs Through Real Information Architecture (Priority: P2) + +**Goal**: Make the new docs IA discoverable through the current public website without broken links, placeholder links, or silent regressions in the previous starter docs URLs. + +**Independent Test**: Reach `/docs/` and selected child pages from nav, footer, homepage, platform, trust, evaluation, and any shipped review-packs or use-case crosslinks, then confirm the legacy starter docs URLs resolve intentionally. + +### Tests for User Story 4 + +- [x] T029 [P] [US4] Extend localized docs route inventory and legacy docs URL coverage in `apps/website/tests/smoke/smoke-helpers.ts` +- [x] T030 [P] [US4] Add nav, footer, homepage, platform, trust, evaluation, and legacy starter-route docs assertions in `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T031 [P] [US4] Add mobile navigation, keyboard reachability, click-through, and docs-entry readability assertions in `apps/website/tests/smoke/interaction.spec.ts` + +### Implementation for User Story 4 + +- [x] T032 [US4] Retarget the global docs entry points from `/welcome-to-docs/` to `/docs/` in `apps/website/src/data_files/site-copy.ts`, `apps/website/src/components/sections/navbar&footer/Navbar.astro`, and `apps/website/src/components/sections/navbar&footer/FooterSection.astro` +- [x] T033 [US4] Add homepage, platform, trust, and evaluation docs discovery content in `apps/website/src/data_files/site-copy.ts`, `apps/website/src/components/pages/HomePage.astro`, `apps/website/src/components/pages/PlatformPage.astro`, `apps/website/src/components/pages/TrustPage.astro`, and `apps/website/src/components/pages/EvaluationPage.astro` +- [x] T034 [US4] Add review-packs and use-case docs discovery content only when the destination route exists and the page can reuse an existing teaser or card slot without adding a new section or displacing its primary CTA in `apps/website/src/data_files/site-copy.ts`, `apps/website/src/components/pages/ReviewPacksPage.astro`, `apps/website/src/pages/use-cases/msp.astro`, `apps/website/src/pages/use-cases/mittelstand.astro`, `apps/website/src/pages/en/use-cases/msp.astro`, and `apps/website/src/pages/en/use-cases/mittelstand.astro` +- [x] T035 [US4] Reconcile the shipped discovery surfaces, final docs route matrix, and legacy alias mappings between `specs/410-public-docs-ia/plan.md` and `specs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml` + +**Checkpoint**: User Story 4 is independently functional and demonstrable. + +--- + +## Phase 7: Polish & Cross-Cutting Concerns + +**Purpose**: Run the required validation, record proof, and close out claim-boundary and scope checks. + +- [x] T036 [P] Run static forbidden-term scans on `apps/website/src` and `apps/website/public` using the command set in `specs/410-public-docs-ia/plan.md` +- [x] T037 [P] If `apps/website/dist` is regenerated, run static forbidden-term scans on `apps/website/dist` using the command set in `specs/410-public-docs-ia/plan.md` +- [x] T038 Run build validation via `corepack pnpm --filter @tenantatlas/website build` using `apps/website/package.json` +- [x] T039 Run route smoke via `corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.ts` for `apps/website/tests/smoke/public-routes.spec.ts` +- [x] T040 Run interaction smoke via `corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.ts` for `apps/website/tests/smoke/interaction.spec.ts` +- [x] T041 Perform desktop and mobile docs IA smoke checks for `/docs/`, `/en/docs/`, selected child pages, nav/footer links, contextual crosslinks, and legacy starter routes, then record SC-001 through SC-006 proof notes in `specs/410-public-docs-ia/plan.md` +- [x] T042 Record validation commands, the final docs route matrix, whether the implementation shipped child pages or a section-only fallback, canonical-metadata reuse status, static scan outcomes, shipped discovery surfaces, legacy alias behavior, `Smoke Coverage` close-out, and `apps/platform/**` scope confirmation in `specs/410-public-docs-ia/plan.md` and `specs/410-public-docs-ia/checklists/requirements.md` +- [x] T043 Run quickstart validation against `specs/410-public-docs-ia/quickstart.md` and record any documentation drift in `specs/410-public-docs-ia/plan.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies; starts immediately. +- **Foundational (Phase 2)**: Depends on Setup completion and blocks all story work. +- **User Stories (Phases 3-6)**: Depend on Foundational completion. +- **Polish (Phase 7)**: Depends on all selected user stories being complete. + +### User Story Dependencies + +- **US1 (P1)**: Starts after Phase 2; no dependency on other stories. +- **US2 (P1)**: Starts after Phase 2; can overlap with US1 once the docs route, sidebar, and content scaffold exist. +- **US3 (P2)**: Starts after Phase 2; can overlap with US2 because the technical concept pages live in separate MDX files. +- **US4 (P2)**: Depends on the docs routes and at least one implemented docs landing/topic surface from US1-US3. + +### Within Each User Story + +- Smoke assertions should be added before or alongside implementation and must fail before final pass. +- Shared route migration and sidebar ordering complete before full page authoring begins. +- Content authoring completes before discovery-link rollout and final build/smoke validation. + +### Parallel Opportunities + +- Setup tasks marked `[P]` can run in parallel. +- US2 and US3 content-authoring tasks marked `[P]` can run in parallel after the foundational route move is complete. +- Phase 7 scan and validation tasks marked `[P]` can be split once implementation is frozen. + +--- + +## Parallel Example: User Story 1 + +```bash +Task: "Add route title and description assertions for the docs landing and getting-started routes in apps/website/tests/smoke/public-routes.spec.ts" +Task: "Add docs landing IA, category-card, related-link, and getting-started readability assertions in apps/website/tests/smoke/interaction.spec.ts" +``` + +## Parallel Example: User Story 2 + +```bash +Task: "Add route title and description assertions for the reviewer docs pages in apps/website/tests/smoke/public-routes.spec.ts" +Task: "Add permissions, trust, evaluation, limitations, and FAQ content assertions in apps/website/tests/smoke/interaction.spec.ts" +Task: "Extend forbidden-claim and real-related-link coverage for reviewer docs pages in apps/website/tests/smoke/smoke-helpers.ts" +Task: "Author the localized permissions and data-processing pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx" +Task: "Author the localized review-packs and evaluation-pilot pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx" +Task: "Author the localized known-limitations and FAQ pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx" +``` + +## Parallel Example: User Story 3 + +```bash +Task: "Add route title and description assertions for the technical concept docs pages in apps/website/tests/smoke/public-routes.spec.ts" +Task: "Add provider, evidence, drift, findings, and recovery content assertions in apps/website/tests/smoke/interaction.spec.ts" +Task: "Extend provider-boundary, automation-overclaim, and recovery-boundary coverage for technical docs pages in apps/website/tests/smoke/smoke-helpers.ts" +Task: "Author the localized provider and policy-evidence pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx" +Task: "Author the localized drift and recovery pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx" +Task: "Author the localized findings and accepted-risk page in apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx and apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx" +``` + +## Parallel Example: User Story 4 + +```bash +Task: "Extend localized docs route inventory and legacy docs URL coverage in apps/website/tests/smoke/smoke-helpers.ts" +Task: "Add nav, footer, homepage, platform, trust, evaluation, and legacy starter-route docs assertions in apps/website/tests/smoke/public-routes.spec.ts" +Task: "Add mobile navigation, keyboard reachability, click-through, and docs-entry readability assertions in apps/website/tests/smoke/interaction.spec.ts" +``` + +--- + +## Implementation Strategy + +### MVP First (P1 Slice: User Stories 1 and 2) + +1. Complete Phase 1 (Setup). +2. Complete Phase 2 (Foundational). +3. Complete Phase 3 (US1). +4. Complete Phase 4 (US2). +5. Validate the P1 slice independently with route metadata, interaction smoke, and static claim scans. +6. Demo or ship the first evaluator- and reviewer-facing docs slice. + +### Incremental Delivery + +1. Finish Setup plus Foundational once. +2. Deliver US1 and US2 as the P1 slice, then validate them independently. +3. Add US3 and validate the technical concept pages. +4. Add US4 and validate discovery plus legacy-route continuity. +5. Finish Phase 7 proof and close-out notes. + +### Parallel Team Strategy + +1. One implementer completes Setup plus Foundational. +2. After Phase 2: + - Implementer A: US1 docs landing and getting-started + - Implementer B: US2 reviewer and trust-oriented pages + - Implementer C: US3 technical concept pages +3. Fold US4 discoverability and IA integration in after the docs route family is stable. +4. Run Phase 7 validation together before merge. + +--- + +## Notes + +- `[P]` tasks touch different files or can be completed without waiting on another incomplete task in the same phase. +- `[US1]` to `[US4]` labels map directly to the user stories in `spec.md` for traceability. +- MVP scope is the P1 slice: User Stories 1 and 2. User Stories 3 and 4 layer on the same route family once the core docs IA is stable. \ No newline at end of file