TenantAtlas/specs/404-public-content-messaging/plan.md

# Implementation Plan: Public Website Positioning & Content Architecture

**Branch**: `404-public-content-messaging` | **Date**: 2026-05-25 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/spec.md`

## Summary

Reposition the public Tenantial website from an Intune-only or backup-tool impression toward Policy Governance for Microsoft 365 and modern cloud environments, with Microsoft 365 as the first focus and provider-extensible language kept explicitly future-safe. The implementation will stay inside `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` and reuse the existing Astro route/content architecture: locale-keyed copy in `src/data_files/site-copy.ts`, thin route wrappers in `src/pages`, shared page components in `src/components/pages`, metadata through `MainLayout` and `Meta`, and the current Playwright smoke suite for route, link, claim, and metadata validation.

## Technical Context

**Language/Version**: TypeScript 6.0.3, Astro 6.3.3, Node.js >=20.0.0, pnpm 10.33.0
**Primary Dependencies**: Astro, `@astrojs/starlight`, `@astrojs/sitemap`, `@astrojs/mdx`, Tailwind CSS v4, `@tailwindcss/vite`, Preline 4, Lenis, GSAP, Sharp, Playwright
**Storage**: N/A - static website content and generated build output only; no database or product persistence
**Testing**: Astro build via `corepack pnpm build:website`, existing Playwright smoke tests under `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke`, targeted static claim scans
**Validation Lanes**: website build, public smoke, manual browser review, static claim scan, whitespace check, `apps/platform` scope check
**Target Platform**: Static Astro public website deployed from `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website`, with German default routes and `/en/...` mirrors
**Project Type**: Web - standalone Astro public website inside a monorepo
**Performance Goals**: No body-level horizontal overflow on validated desktop/mobile routes; primary navigation and CTAs stay readable and reachable; metadata and canonical routes stay intentional
**Constraints**: Runtime/source changes are scoped to `apps/website`; preserve root package script names, website package name `@tenantatlas/website`, `WEBSITE_PORT`, and `apps/*` workspace conventions; no `apps/platform` changes; no fake trust/provider claims; no placeholder links; no auth/API/database/runtime coupling
**Scale/Scope**: Core public pages `/`, `/platform`, `/pricing`, `/trust`, `/contact`, legal pages, exposed docs routes, locale mirrors, navigation/footer surfaces, route metadata, and smoke expectations

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change; public website positioning workflow only
- **Native vs custom classification summary**: custom Astro public website; no Filament/Blade/admin surface
- **Shared-family relevance**: public navigation, CTA language, metadata, docs exposure, and smoke helper patterns
- **State layers in scope**: localized static page content, navigation/footer data, route metadata, docs content, smoke expectations
- **Audience modes in scope**: public visitor, MSP evaluator, internal IT evaluator, DACH trust reviewer
- **Decision/diagnostic/raw hierarchy plan**: public copy stays decision-first for visitors; diagnostics and proof boundaries are explained plainly rather than exposed as raw runtime detail
- **Raw/support gating plan**: N/A - no operator support/raw evidence surface
- **One-primary-action / duplicate-truth control**: each primary route keeps one clear next step, typically contact or deeper product explanation, while repeated or competing CTA language is normalized
- **Handling modes by drift class or surface**: public claim, placeholder-link, and navigation drift are review-mandatory inside this feature; `apps/platform` drift is a hard stop
- **Repository-signal treatment**: website-source and website-smoke changes are expected; any platform/runtime drift is exception-required and out of scope
- **Special surface test profiles**: N/A - public website only
- **Required tests or manual smoke**: public smoke, static claim scan, and manual desktop/mobile browser review
- **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**: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts`, `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/constants.ts`, `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/pages`, `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/sections/navbar&footer`, `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/Meta.astro`, `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/docs`, and `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke`
- **Shared abstractions reused**: locale-keyed `siteCopy`, thin route wrappers in `src/pages`, `MainLayout.astro`, `Meta.astro`, `localizeHref()` and locale helpers, shared Navbar/Footer components, Playwright smoke helper patterns for forbidden claims and placeholder links
- **New abstraction introduced? why?**: none
- **Why the existing abstraction was sufficient or insufficient**: The current website already centralizes copy, navigation, metadata, and smoke assertions. Spec 404 needs a better narrative and stricter claim posture, not a new framework.
- **Bounded deviation / spread control**: no new abstraction; bounded cleanup of stale helpers such as German-only `navigation.ts` usage is allowed if needed to keep copy and route logic aligned

## 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**: N/A
- **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**: public Microsoft 365 wording, Intune as one example domain, any roadmap/provider-direction examples in public copy
- **Platform-core seams**: none; no runtime platform contracts, provider contracts, or shared persistence truth change
- **Neutral platform terms / contracts preserved**: policy governance, cloud policy governance, managed environment, provider connection, policy evidence, drift detection, findings, exceptions, accepted risks, decision summary, audit trail, controlled recovery, provider readiness
- **Retained provider-specific semantics and why**: Microsoft 365 remains the first public focus because that is current product truth; Intune is retained only as one Microsoft 365 policy domain and not the umbrella category
- **Bounded extraction or follow-up path**: follow-up-spec for a broader public provider/domain taxonomy if future route or copy work needs a richer current-versus-planned matrix

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS - no inventory, snapshots, backups, or source-of-truth runtime behavior changes
- Read/write separation: PASS - no write/change behavior is introduced
- Graph contract path: PASS - no Microsoft Graph calls or contract-registry changes
- Deterministic capabilities: PASS - no capability derivation or resolver changes
- RBAC-UX: PASS - no `/admin`, `/system`, tenant context, workspace context, authorization, or capability behavior changes
- Workspace isolation: PASS - no workspace data or workspace-scoped route behavior changes
- RBAC-UX destructive-like actions: PASS - no destructive actions
- RBAC-UX global search: PASS - no Filament or global-search changes
- Tenant isolation: PASS - no tenant data, tenant reads, or tenant routes
- Run observability: PASS - no long-running, remote, queued, or scheduled product work
- OperationRun start UX: PASS - no OperationRun behavior
- Ops-UX 3-surface feedback: PASS - no OperationRun notifications or lifecycle output
- Ops-UX lifecycle: PASS - no `OperationRun.status` or `OperationRun.outcome` changes
- Ops-UX summary counts: PASS - no summary-count semantics
- Ops-UX guards: PASS - no Ops-UX guard changes
- Ops-UX system runs: PASS - no system-run behavior
- Automation: PASS - no queue, retry, lock, idempotency, or backoff behavior
- Data minimization: PASS - public static copy and metadata only; no secrets, tokens, or tenant data
- Test governance (TEST-GOV-001): PASS - browser/static classification is explicit, uses existing website lanes, and introduces no hidden Laravel/Filament/provider/database setup cost
- Proportionality (PROP-001): PASS - website-local narrative and metadata updates only; no new product structure or semantic machinery
- No premature abstraction (ABSTR-001): PASS - no new factories, registries, resolvers, strategies, interfaces, or pipelines
- Persisted truth (PERSIST-001): PASS - no new persisted product truth or artifacts beyond existing static build output
- Behavioral state (STATE-001): PASS - no new product states, statuses, or reason families
- UI semantics (UI-SEM-001): PASS - public copy and labels remain local presentation, not a shared semantic framework
- Shared pattern first (XCUT-001): PASS - existing shared website copy, layout, metadata, navigation, and smoke helpers are reused
- Provider boundary (PROV-001): PASS - public provider vocabulary is explicitly bounded to positioning only; no platform-core coupling is added
- V1 explicitness / few layers (V1-EXP-001, LAYER-001): PASS - direct website-local edits only
- Spec discipline / bloat check (SPEC-DISC-001, BLOAT-001): PASS - no enum, DTO, presenter, persisted entity, interface, registry, resolver, or taxonomy is introduced
- Badge semantics (BADGE-001): PASS - no shared badge/status taxonomy changes
- Filament-native UI (UI-FIL-001): PASS - no Filament UI
- UI/UX surface taxonomy: PASS - no operator-facing surface
- Decision-first operating model: PASS - public visitor decision flow is improved, but no operator decision surface is added
- Audience-aware disclosure: PASS - trust/proof boundaries are stated conservatively without exposing operator/raw evidence surfaces
- UI/UX inspect model: PASS - no operator list/detail surface
- UI/UX action hierarchy: PASS - no Filament actions or admin action surfaces
- UI/UX scope, truth, and naming: PASS - public category language, provider posture, and CTA vocabulary stay honest and non-implementation-first
- UI/UX placeholder ban: PASS - placeholder links and fake pages are explicitly banned by this feature
- UI naming: PASS - public CTA labels map to real next steps and avoid unsupported workflow verbs
- Operator surfaces: PASS - no `/admin` surface changes
- Filament UI Action Surface Contract: PASS - no Filament Resource/RelationManager/Page changes
- Filament UI UX-001: PASS - no Filament screen changes
- Action-surface discipline: PASS - no operator action surface changes
- UI review workflow: PASS - website-specific shared patterns and public validation responsibilities stay explicit without widening into platform scope

**Initial Gate Result**: PASS - no constitution violations or unresolved clarifications.

## Test Governance Check

- **Test purpose / classification by changed surface**: Browser/static website
- **Affected validation lanes**: website build, public smoke, manual browser review, static claim scan, whitespace/scope checks
- **Why this lane mix is the narrowest sufficient proof**: The feature changes public copy, route metadata, CTA intent, navigation exposure, and claim discipline. Laravel/Pest/Filament lanes would not prove the changed behavior.
- **Narrowest proving command(s)**: `cd /Users/ahmeddarrazi/Documents/projects/wt-website && corepack pnpm build:website`; `cd /Users/ahmeddarrazi/Documents/projects/wt-website && WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke`; `cd /Users/ahmeddarrazi/Documents/projects/wt-website && grep -RIn -e 'href="#"' -e 'Intune Management Tool' -e 'Intune backup tool' -e 'DSGVO compliant' -e 'GDPR compliant' -e 'ISO certified' -e 'Google supported' -e 'AWS supported' -e 'automatic restore' -e 'autonomous remediation' -e 'neutral SaaS visual' -e 'lorem ipsum' apps/website/src apps/website/public 2>/dev/null || true`; `cd /Users/ahmeddarrazi/Documents/projects/wt-website && git diff --check`; `cd /Users/ahmeddarrazi/Documents/projects/wt-website && git status --short -- apps/platform`
- **Fixture / helper / factory / seed / context cost risks**: none - no database, provider, workspace, membership, session, queue, Sail, Laravel, Filament, or Livewire setup
- **Expensive defaults or shared helper growth introduced?**: no
- **Heavy-family additions, promotions, or visibility changes**: none - existing Playwright smoke remains explicit and website-local
- **Surface-class relief / special coverage rule**: N/A - public website
- **Closing validation and reviewer handoff**: Reviewers should rely on website build, Playwright smoke, static claim scan, desktop/mobile manual review, and `apps/platform` untouched confirmation. If copy changes add new public docs or navigation surfaces, smoke route allowlists and metadata expectations must be updated in the same feature.
- **Budget / baseline / trend follow-up**: none expected
- **Review-stop questions**: lane fit, claim drift, placeholder-link drift, route-exposure drift, hidden platform coupling
- **Escalation path**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Why no dedicated follow-up spec is needed**: The validation cost remains local to this public website positioning pass unless future website work creates a recurring release-governance problem.

## Project Structure

### Documentation (this feature)

```text
/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── public-content-contract.md
└── tasks.md
```

### Source Code (repository root)

```text
/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/
├── astro.config.mjs
├── package.json
├── playwright.config.ts
├── process-html.mjs
├── public/
├── src/
│   ├── components/
│   │   ├── pages/
│   │   └── sections/
│   ├── content/
│   │   ├── docs/
│   │   ├── blog/
│   │   ├── insights/
│   │   └── products/
│   ├── data_files/
│   ├── layouts/
│   ├── pages/
│   │   └── en/
│   └── utils/
└── tests/
    └── smoke/
```

**Structure Decision**: Use the existing `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` Astro application and its current localized route/component/content organization. Do not create new base folders and do not touch `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform`.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | N/A | N/A |

## Proportionality Review

- **Current operator problem**: Public evaluators and reviewers still receive the wrong product category and an incomplete governance narrative from the current website.
- **Existing structure is insufficient because**: The website foundation is already stable, but its public copy, metadata, navigation, and trust/provider boundaries do not yet express the intended policy-governance positioning.
- **Narrowest correct implementation**: Update the existing website-local copy system, page hierarchy, docs exposure, metadata, and smoke expectations inside `apps/website` only.
- **Ownership cost created**: Ongoing maintenance of public positioning copy, provider/trust claim guardrails, and smoke expectations for emitted public routes.
- **Alternative intentionally rejected**: A broad website redesign, a new content system, and any `apps/platform`-linked implementation or provider runtime work.
- **Release truth**: Current-release public website positioning truth.

## Phase 0 Research

Research output is captured in `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/research.md`.

**Resolved clarifications**:

- The active website remains the existing Astro 6 app in `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website`; no framework decision is needed.
- Core public routes are thin wrappers that delegate to shared page components in `src/components/pages`.
- The primary copy, navigation, CTA labels, and per-route metadata are centralized in `src/data_files/site-copy.ts`.
- German default routes and `/en/...` mirrors share the same content source through locale-keyed records rather than separate content systems.
- `/product` is a redirect alias to `/platform`, so the governance model should stay anchored to `/platform` and not a second product page.
- Existing Playwright smoke helpers already cover rendered routes, redirect aliases, placeholder-link bans, forbidden public residue, metadata, and mobile/keyboard/overflow checks.
- Public docs routes are intentionally emitted and must stay aligned with the same positioning/claim contract as the core marketing pages.
- No REST, GraphQL, database, queue, Laravel, Filament, Livewire, or provider-runtime contract is required for this feature.

## Phase 1 Design

Design output is captured in:

- `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/data-model.md`
- `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/contracts/public-content-contract.md`
- `/Users/ahmeddarrazi/Documents/projects/wt-website/specs/404-public-content-messaging/quickstart.md`

The design treats public route behavior, messaging claims, provider posture, CTAs, operating-model sections, and route metadata as the contract. No REST, GraphQL, database, Laravel, Filament, Livewire, Microsoft Graph, queue, job, RBAC, or runtime platform contract is introduced.

## Post-Design Constitution Check

**Post-Design Gate Result**: PASS

- Phase 1 remains website-local and scoped to `apps/website`.
- All clarification markers are resolved.
- No product persistence, abstraction, status family, provider runtime seam, OperationRun behavior, RBAC behavior, or Filament behavior is introduced.
- Shared-pattern reuse stays within the existing website copy/layout/metadata/smoke system.
- Provider vocabulary remains bounded to public positioning only.
- Validation remains explicit and limited to website build, smoke, claim scans, and scope checks.
- Agent context must be updated with the current plan outputs before implementation continues.