TenantAtlas/specs/401-tenantial-platform-page/plan.md

Implementation Plan: Tenantial Platform Page

Branch: feat/401-tenantial-platform-page | Date: 2026-05-18 | Spec: /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/spec.md

Summary

Create a canonical public Tenantial Platform page at /platform inside the standalone Astro website. The implementation should reuse the Spec 400 public visual direction and existing website shell/content primitives, move homepage/header/footer Platform links to /platform, and treat the current /product page as redirect-only compatibility to the canonical Platform page. The follow-up visual refactor tightens the page around the supplied mockup target: split hero with large static dashboard preview, compact connected Operating Model, central Governance Loop diagram, asymmetric Capabilities, visual Truth Layers, warmer Operator Workflows, clear Boundaries band, focused CTA, and quiet footer. The feature remains static website content with route smoke coverage; it introduces no Laravel platform runtime behavior, no backend API, no database changes, no authentication, and no Microsoft Graph integration.

Technical Context

Language/Version: TypeScript 5.9.3 and Astro 6.0.0 in apps/website; Node >=20.0.0 via workspace package metadata. Primary Dependencies: Astro, Tailwind CSS v4.2.2 through @tailwindcss/vite, astro-icon, @iconify-json/lucide, Playwright smoke tests. Storage: N/A - static website content only; no database, CMS, API, customer data, tenant data, or runtime persistence. Testing: Playwright smoke tests in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke; website build through root build:website. Validation Lanes: Browser lane plus static build and whitespace diff check. Target Platform: Static public Astro website under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website. Project Type: Monorepo with standalone website app and separate Laravel platform app; this feature is website-only. Performance Goals: Static page remains mostly HTML/CSS, uses no backend fetches, no platform API calls, no tracking scripts, and no unapproved large raster screenshots. Constraints: Preserve root pnpm script names, WEBSITE_PORT convention, internal package name, public Tenantial brand, Spec 400 visual system, mobile readability, keyboard access, and no body-level horizontal overflow. Scale/Scope: One canonical public route (/platform), one redirect-only compatibility route for /product, shared navigation/footer link updates, route metadata, focused smoke assertions, and website-only visual composition updates for /platform.

UI / Surface Guardrail Plan

• Guardrail scope: No operator-facing admin surface change; public website marketing surface only.
• Native vs custom classification summary: N/A for Filament/admin nativity. Website work should reuse existing Astro website primitives and section components where they fit.
• Shared-family relevance: None for shared operator interaction families.
• State layers in scope: Public website shell, page route, static page content, route metadata.
• Audience modes in scope: Public buyer/stakeholder audience only; no customer/read-only, operator/MSP admin mode, or support/platform mode.
• Decision/diagnostic/raw hierarchy plan: Public product explanation first; no diagnostics or raw evidence surfaces.
• Raw/support gating plan: N/A - no raw/support evidence is shown.
• One-primary-action / duplicate-truth control: "Book a demo" remains the dominant conversion CTA; "See the governance loop" is a subordinate in-page learning action.
• Handling modes by drift class or surface: N/A.
• Repository-signal treatment: Report-only for public website route/content smoke; no admin guardrail signals.
• Special surface test profiles: N/A.
• Required tests or manual smoke: Website smoke tests for /platform, homepage/header/footer route intent, /product compatibility, forbidden residue, visual structure signals, quiet footer behavior, and mobile overflow.
• Exception path and spread control: None.
• Active feature PR close-out entry: Smoke Coverage.

Shared Pattern & System Fit

• Cross-cutting feature marker: No for operator shared interaction classes.
• Systems touched: Public website shell, public navigation, public footer, page definitions, static content, and smoke tests.
• Shared abstractions reused: Existing website content modules in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/pages, shared shell in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components/layout, and page/section primitives in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/components.
• New abstraction introduced? why?: None planned. Page-local arrays and existing typed content shapes are sufficient.
• Why the existing abstraction was sufficient or insufficient: Existing PageShell, navigation, content modules, SEO helpers, primitives, and smoke helpers already support static public pages.
• Bounded deviation / spread control: If a new visual section is needed for the governance loop, keep it page-local or a narrow website section component; do not create a generic governance UI framework.

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: Runtime provider/platform contracts are untouched.
• Retained provider-specific semantics and why: Public copy may refer to Microsoft tenant environments because the product positioning requires it; this does not change runtime provider abstractions.
• Bounded extraction or follow-up path: None.

Constitution Check

GATE: Passed before Phase 0 research and re-checked after Phase 1 design, with explicit repository-wide PHP/Pest/Pint close-out commands documented for finalization.

• Inventory-first: N/A - no Inventory, snapshot, backup, or tenant runtime state changes.
• Read/write separation: Pass - public website content only; no write/change behavior.
• Graph contract path: Pass - no Microsoft Graph calls or contract registry changes.
• Deterministic capabilities: N/A - no capability derivation changes.
• RBAC-UX and workspace/tenant isolation: Pass - no /admin, /system, tenant, workspace, global search, policy, capability, or authorization changes.
• Destructive confirmations: N/A - no destructive actions.
• Run observability and OperationRun UX: Pass - no queued, scheduled, long-running, remote, or operational action.
• Automation: N/A - no queued or scheduled operations.
• Data minimization: Pass - no customer, tenant, Microsoft API, tracking, or runtime data is introduced.
• Test governance: Pass - Browser classification and smoke coverage are explicit, website-scoped, and avoid platform fixtures. Repository-wide Pest and Pint gates are covered as close-out commands, not as additional feature proof.
• Proportionality: Pass - one public route/content slice; no persisted truth, domain state, abstraction, enum, status, resolver, registry, or taxonomy.
• No premature abstraction / few layers: Pass - reuse existing website content/shell components; keep any new page sections narrow.
• Persisted truth / behavioral state: Pass - no persistence or behavioral state.
• UI semantics / badge semantics: Pass - no admin status semantics; public labels stay descriptive.
• Shared pattern first: Pass - no shared operator interaction family touched; website shell patterns are reused.
• Provider boundary: Pass - public Microsoft tenant wording does not touch platform-core seams.
• Filament-native UI and Filament Action Surface Contract: N/A - no Filament, Blade admin, Livewire, Resource, RelationManager, or Page changes.
• Decision-first / audience-aware operator disclosure: N/A - no operator-facing admin detail/status surface.
• UI review workflow: Pass - plan keeps the spec's no operator-facing surface change classification.

Post-Design Constitution Check

Phase 0 and Phase 1 design artifacts preserve the same decisions: static website-only scope, no backend/API/runtime coupling, no new persistence, no new abstractions, and browser smoke validation as the feature proof. Repository-wide Pest and Pint close-out commands are explicit, so no unresolved gate violations remain.

Test Governance Check

• Test purpose / classification by changed surface: Browser for public website route, navigation, metadata, copy safety, and responsive behavior.
• Affected validation lanes: browser.
• Why this lane mix is the narrowest sufficient proof: The feature is a static public page. Playwright route/content checks plus build validation prove user-visible route behavior without Laravel, database, workspace, tenant, provider, or session setup.
• Narrowest proving command(s): corepack pnpm build:website; WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke; git diff --check; desktop and mobile browser screenshot review.
• Repository-wide constitution close-out: Run cd /Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform && ./vendor/bin/sail artisan test --compact tests/Deprecation/IsPlatformSuperadminDeprecationTest.php and cd /Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform && ./vendor/bin/sail bin pint --dirty before finalizing. These commands satisfy the repository-wide gate without adding platform fixtures or treating Laravel behavior as the feature proof.
• Fixture / helper / factory / seed / context cost risks: None.
• Expensive defaults or shared helper growth introduced?: No.
• Heavy-family additions, promotions, or visibility changes: None beyond existing website smoke family.
• Surface-class relief / special coverage rule: N/A.
• Closing validation and reviewer handoff: Reviewers should confirm smoke coverage remains website-scoped and asserts /platform, homepage CTA route, header/footer route, /product compatibility, old public-brand residue absence, claim safety, and mobile overflow.
• Budget / baseline / trend follow-up: None expected.
• Review-stop questions: Stop if tests require platform services, hidden fixtures, backend auth, database, broad browser families, or unbounded visual regression scope.
• Escalation path: document-in-feature.
• Active feature PR close-out entry: Smoke Coverage.
• Why no dedicated follow-up spec is needed: The smoke expansion is feature-local and does not create recurring test-lane cost or new infrastructure.

Project Structure

Documentation (this feature)

/Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/
|-- plan.md
|-- research.md
|-- data-model.md
|-- quickstart.md
|-- contracts/
|   `-- public-routes.openapi.yaml
|-- checklists/
|   `-- requirements.md
`-- tasks.md               # created later by /speckit.tasks

Source Code (repository root)

/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/
|-- package.json
|-- src/
|   |-- components/
|   |   |-- content/
|   |   |-- layout/
|   |   |-- primitives/
|   |   `-- sections/
|   |-- content/pages/
|   |   |-- home.ts
|   |   |-- platform.ts        # static page content and visual-section copy
|   |   `-- product.ts         # planned stale-content retirement path
|   |-- lib/
|   |   |-- seo.ts
|   |   `-- site.ts
|   |-- pages/
|   |   |-- index.astro
|   |   |-- platform.astro     # canonical route and mockup-aligned visual composition
|   |   `-- product.astro      # planned redirect compatibility route
|   |-- styles/
|   `-- types/
`-- tests/smoke/
    |-- home-product.spec.ts   # planned update or split
    `-- smoke-helpers.ts       # planned route expectations update

Structure Decision: Use the existing standalone Astro website structure under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website. Keep content in typed page content modules, render through existing layout and section primitives, and extend existing smoke tests instead of adding a second website architecture.

Complexity Tracking

No constitution violations or BLOAT-001-triggering runtime complexity are introduced.

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

Proportionality Review

• Current operator problem: Public buyers and stakeholders cannot yet understand Tenantial's platform operating model from a dedicated page after the homepage.
• Existing structure is insufficient because: The homepage introduces the promise, while existing /product copy is not the canonical /platform journey and still leaves route confusion.
• Narrowest correct implementation: One canonical static /platform page, route/navigation alignment, /product redirect compatibility, metadata, and focused smoke checks.
• Ownership cost created: One additional public page, static content maintenance, route compatibility expectations, and a small smoke-test expansion.
• Alternative intentionally rejected: Build pricing, trust center, CMS, i18n, live screenshots, backend integration, or platform runtime hooks in this slice.
• Release truth: Current public website truth.

Phase 0 Research

See /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/research.md.

Phase 1 Design

See:

• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/data-model.md
• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/contracts/public-routes.openapi.yaml
• /Users/ahmeddarrazi/Documents/projects/wt-website/specs/401-tenantial-platform-page/quickstart.md

Phase 2 Planning Boundary

This /speckit.plan run stops after Phase 2 planning artifacts. Implementation tasks are intentionally left for /speckit.tasks.