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

# Implementation Plan: `apps/website` Public Content Architecture & Messaging

**Branch**: `404-public-content-messaging` | **Date**: 2026-05-22 | **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

Stabilize Tenantial's public website messaging before later visual rhythm work. The implementation stays inside `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` and updates public copy, section intent, CTA language, route metadata, trust/pricing/contact wording, FAQ/footer messaging, and exposed docs navigation/content so the site communicates evidence-first Microsoft tenant governance without unsupported claims or runtime workflow implications.

## 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, docs content, route metadata, and generated build output only; no database or product persistence
**Testing**: Astro check/build plus Playwright smoke tests under `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke`
**Validation Lanes**: website build, public smoke, manual browser/content review, whitespace check, `apps/platform` scope check
**Target Platform**: Static Astro public website deployed from `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website`, with public site URL `https://tenantial.com`
**Project Type**: Web - standalone Astro public website inside monorepo
**Performance Goals**: Public routes remain static-buildable; validated desktop/mobile routes retain no body-level horizontal overflow; content remains understandable without requiring unavailable backend workflows
**Constraints**: Runtime/source changes are scoped to `apps/website`; Spec Kit artifacts live under `specs/404-public-content-messaging`; preserve Spec 402 ScrewFast-derived substrate and Spec 403 launch-readiness safety; do not add backend contact/demo workflow, authentication, billing, Microsoft Graph, Laravel, Filament, Livewire, database, queue, job, provider, policy, RBAC, or `apps/platform` changes
**Scale/Scope**: Public content architecture pass for homepage, `/platform`, `/pricing`, `/trust`, `/contact`, exposed docs routes, route metadata, navigation, FAQ, footer, CTA labels, static/demo preview framing, and claim-safety review

## UI / Surface Guardrail Plan

- **Guardrail scope**: no admin/operator-facing product surface change; public website content and messaging guardrail only
- **Native vs custom classification summary**: ScrewFast-derived Astro website; no Filament/Blade/admin surface
- **Shared-family relevance**: none for Laravel/Filament shared interaction families; website-local public navigation/CTA/content families remain in scope
- **State layers in scope**: static page content, docs content, public route metadata, navigation/footer link data, preview framing copy, Playwright smoke expectations
- **Audience modes in scope**: public visitor, buyer/reviewer, security-conscious evaluator, site owner/reviewer; no authenticated operator/MSP/support-platform modes
- **Decision/diagnostic/raw hierarchy plan**: public copy must be buyer-decision-first; internal implementation diagnostics stay out of visible copy; static/demo preview context is disclosed where needed
- **Raw/support gating plan**: N/A - no raw/support product evidence surface
- **One-primary-action / duplicate-truth control**: primary CTAs should stay contact-led; secondary CTAs should point to explanatory pages; repeated claims should be consolidated so each section adds new meaning
- **Handling modes by drift class or surface**: public copy/CTA/claim drift is review-mandatory inside this feature; platform/admin drift is a hard stop
- **Repository-signal treatment**: `apps/platform` changes are a hard stop; public website source/output changes are reviewed only inside website scope
- **Special surface test profiles**: N/A - not a Filament surface
- **Required tests or manual smoke**: public smoke plus manual review of homepage narrative, `/platform` product model, pricing/trust/contact claim posture, CTA targets, metadata, light/dark/mobile/desktop, and keyboard reachability
- **Exception path and spread control**: none
- **Active feature PR close-out entry**: Smoke Coverage

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, within public website content only
- **Systems touched**: `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` public pages, docs content, shared website copy/data files, navigation/footer helpers, metadata helpers, and smoke expectations as needed
- **Shared abstractions reused**: existing Spec 402/403 Astro website structure, Starlight docs, route metadata components, website data files, navigation utilities, and Playwright smoke helper patterns
- **New abstraction introduced? why?**: none planned
- **Why the existing abstraction was sufficient or insufficient**: The existing website structure can express the required copy and route metadata. The insufficiency is content architecture, not framework capability.
- **Bounded deviation / spread control**: no new content framework, design system, API contract, persisted state, or platform abstraction; any new helper must be website-local and justified by repeated existing website content usage

## 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?**: no
- **Provider-owned seams**: N/A
- **Platform-core seams**: N/A
- **Neutral platform terms / contracts preserved**: Governance, evidence, findings, drift, restore planning, auditability, exceptions, reviews, evaluation, and rollout remain public positioning terms only
- **Retained provider-specific semantics and why**: Microsoft tenant configuration remains in public product positioning because Tenantial's current public category is Microsoft tenant governance
- **Bounded extraction or follow-up path**: none; Spec 405 may use the stabilized content for visual polish

## Constitution Check

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

- Inventory-first: PASS - no inventory, snapshot, or backup runtime behavior is changed.
- Read/write separation: PASS - no product write/change behavior is introduced.
- Graph contract path: PASS - no Microsoft Graph calls or contract registry changes.
- Deterministic capabilities: PASS - no capability resolver or capability derivation changes.
- RBAC-UX: PASS - no `/admin`, `/system`, tenant context, workspace context, capability, policy, or authorization behavior changes.
- Workspace isolation: PASS - no workspace data or routes.
- RBAC-UX destructive-like actions: PASS - no destructive actions.
- RBAC-UX global search: PASS - no Filament resources or global search changes.
- Tenant isolation: PASS - no tenant data, tenant routes, or cross-tenant views.
- Run observability: PASS - no long-running, remote, queued, scheduled, or security-relevant DB action.
- OperationRun start UX: PASS - no OperationRun behavior.
- Ops-UX 3-surface feedback: PASS - no OperationRun notifications.
- Ops-UX lifecycle: PASS - no OperationRun status/outcome transitions.
- Ops-UX summary counts: PASS - no summary counts.
- Ops-UX guards: PASS - no Ops-UX guard changes.
- Ops-UX system runs: PASS - no system runs.
- Automation: PASS - no queued/scheduled operations.
- Data minimization: PASS - public copy and static/demo preview content only; no secrets or tokens.
- Test governance (TEST-GOV-001): PASS - Browser/static website classification, explicit website smoke lane, no hidden Laravel/Filament/provider/database setup.
- Proportionality (PROP-001): PASS - local website content architecture, no new product runtime structure.
- No premature abstraction (ABSTR-001): PASS - no new factories, registries, resolvers, strategies, interfaces, or frameworks.
- Persisted truth (PERSIST-001): PASS - no persisted product truth.
- Behavioral state (STATE-001): PASS - no status/state/reason family.
- UI semantics (UI-SEM-001): PASS - static public copy and preview labels remain local and do not become product taxonomy.
- Shared pattern first (XCUT-001): PASS - cross-page website content reuses the existing website structure; no shared operator interaction family is touched.
- Provider boundary (PROV-001): PASS - public Microsoft wording only; no shared provider/platform seam changes.
- 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 new enum, DTO, presenter, persisted entity, interface, registry, resolver, taxonomy, or cross-domain framework.
- Badge semantics (BADGE-001): PASS - no product badge semantics; preview labels must not become shared status truth.
- 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 website copy is buyer-decision oriented; no operator surface.
- Audience-aware disclosure: PASS - no raw/support product detail surface.
- UI/UX inspect model: PASS - no list/detail operator surface.
- UI/UX action hierarchy: PASS - no Filament actions.
- UI/UX scope, truth, and naming: PASS - no admin scope labels; public copy must avoid implementation-first wording.
- UI/UX placeholder ban: PASS - no Filament action groups.
- UI naming: PASS - no operator-facing action labels, run titles, notifications, or audit prose.
- Operator surfaces: PASS - no `/admin` surface.
- Filament UI Action Surface Contract: PASS - no Filament Resource/RelationManager/Page.
- Filament UI UX-001: PASS - no Filament screen.
- Action-surface discipline: PASS - no operator action surface.
- UI review workflow: PASS - plan carries N/A decisions forward and keeps `apps/platform` as hard stop.

**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/content review, whitespace/scope checks
- **Why this lane mix is the narrowest sufficient proof**: The feature changes public static pages, docs content, route metadata, CTAs, and browser-rendered copy. Laravel/Pest/Filament lanes would not prove the changed behavior and would add hidden platform cost.
- **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 && 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**: Browser review remains explicit in website smoke/manual review; no heavy-governance lane
- **Surface-class relief / special coverage rule**: N/A - public website
- **Closing validation and reviewer handoff**: Reviewers should rely on website build, Playwright smoke, manual content review, no unsupported claims, intentional CTAs, no forbidden residue, and `apps/platform` untouched status.
- **Budget / baseline / trend follow-up**: none expected
- **Review-stop questions**: lane fit, browser breadth, hidden platform cost, CTA honesty, unsupported claim posture, route exposure
- **Escalation path**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Why no dedicated follow-up spec is needed**: The browser/static review cost is local to this content architecture pass unless repeated website release gates become a recurring process 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
├── checklists/
│   └── requirements.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/
│   ├── content/
│   ├── data_files/
│   ├── images/
│   ├── layouts/
│   ├── pages/
│   └── utils/
└── tests/
    └── smoke/
```

**Structure Decision**: Use the existing `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` Astro app from Specs 402 and 403. Do not create new base source 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 buyers do not yet get a crisp product story, and claim-sensitive pages need stronger content discipline before layout work.
- **Existing structure is insufficient because**: Specs 402 and 403 established the website foundation and launch-readiness guardrails, but they did not finalize public messaging hierarchy, CTA language, or proof-safe page-level copy.
- **Narrowest correct implementation**: Website-local copy, docs content, route metadata, CTA, trust/pricing/contact/FAQ/footer, and claim-safety updates inside `apps/website`.
- **Ownership cost created**: Future public website changes must preserve the documented claim-safety, CTA consistency, and content hierarchy rules.
- **Alternative intentionally rejected**: Starting with layout rhythm or introducing a broader content framework was rejected because the current need is stable copy and section intent, not new visual or runtime architecture.
- **Release truth**: Current-release public website messaging 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 feature uses the existing Astro 6 website and does not need a new framework or design-system decision.
- The public contract is route content, metadata, CTA behavior, docs exposure, and claim posture; there are no API endpoints or data entities to contract.
- The implementation must stabilize content before Spec 405 visual rhythm work.
- Public Microsoft tenant wording is allowed as product positioning but must not imply website runtime provider access, Microsoft endorsement, or Microsoft Graph execution.
- Validation stays in website build, public Playwright smoke, manual browser/content review, and `apps/platform` scope checks.

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

No REST, GraphQL, database, Laravel, Filament, Livewire, Microsoft Graph, queue, job, policy, RBAC, or product runtime contracts are introduced.

## Post-Design Constitution Check

**Post-Design Gate Result**: PASS

- The Phase 1 design remains website-local.
- All clarification markers are resolved.
- No product persistence, abstractions, state families, provider/platform seams, OperationRun behavior, RBAC behavior, Filament behavior, or Graph calls are introduced.
- Browser/static validation remains explicit and bounded to `apps/website`.
- `apps/platform` remains out of scope and must be verified by `git status --short -- apps/platform`.