TenantAtlas/specs/403-public-website-launch-readiness/spec.md

# Feature Specification: `apps/website` Public Website Launch Readiness

**Feature Branch**: `feat/403-public-website-launch-readiness`
**Created**: 2026-05-20
**Status**: Draft
**Input**: User description: "Make the current Tenantial public website release-ready after the Spec 402 ScrewFast-derived rebuild, scoped strictly to `apps/website`."

## Spec Candidate Check

- **Problem**: The public website now has the correct foundation, but it still needs a focused launch-readiness pass for message clarity, CTA integrity, route exposure, SEO metadata, trust/pricing claim safety, and browser review.
- **Today's failure**: A technically passing static build could still publish unclear positioning, unsupported claims, dead or misleading CTAs, route residue, or metadata that is not ready for public release.
- **User-visible improvement**: Visitors can quickly understand Tenantial in German by default or English under `/en`, follow honest contact/demo paths, review conservative trust and pricing language, and browse only intentional public routes.
- **Smallest enterprise-capable version**: Keep the Spec 402 ScrewFast-derived foundation, change only website-local copy, metadata, route exposure, CTA behavior, public assets, smoke checks, and launch-readiness notes.
- **Explicit non-goals**: No rebuild, no new design system, no backend contact workflow, no authentication, no billing, no Microsoft Graph calls, no Laravel/Filament/Livewire/admin behavior, and no `apps/platform` changes.
- **Permanent complexity imported**: Website-local launch copy, route/metadata hygiene, static preview framing, browser/static validation expectations, and a launch-readiness note. No new product runtime abstractions or persistence.
- **Why now**: Spec 402 intentionally solved the foundation; launch readiness is the next release gate before public exposure.
- **Why not local**: This is local to `apps/website`; the spec explicitly rejects broader platform/runtime changes.
- **Approval class**: Core Enterprise
- **Red flags triggered**: None. This is not a new foundation, framework, status taxonomy, persistence layer, or abstraction.
- **Score**: Nutzen 2 | Dringlichkeit 2 | Scope 2 | Komplexitaet 2 | Produktnaehe 2 | Wiederverwendung 1 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields

- **Scope**: N/A - public website only, strictly `apps/website`
- **Primary Routes**: `/`, `/platform`, `/pricing`, `/trust`, `/legal`, `/privacy`, `/terms`, `/imprint`, `/contact`, docs routes, `/en/*` localized route mirrors, redirect aliases, `/robots.txt`, `/sitemap-index.xml`
- **Data Ownership**: No workspace-owned or tenant-owned product records impacted; no persistence changes.
- **RBAC**: N/A - no authenticated/admin/platform runtime behavior, no tenant/workspace membership behavior, no authorization changes.

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: N/A - no canonical admin view or tenant context.
- **Explicit entitlement checks preventing cross-tenant leakage**: N/A - no tenant data or authenticated runtime.

## Cross-Cutting / Shared Pattern Reuse

- **Cross-cutting feature?**: no
- **Interaction class(es)**: N/A - public website navigation and CTAs only; no shared operator interaction family.
- **Systems touched**: `apps/website` static/public routes, metadata, navigation, footer, docs/legal/trust/pricing/contact surfaces, smoke checks.
- **Existing pattern(s) to extend**: Spec 402 ScrewFast-derived website structure.
- **Shared contract / presenter / builder / renderer to reuse**: N/A - no Laravel/Filament shared operator contract.
- **Why the existing shared path is sufficient or insufficient**: The website-local ScrewFast-derived structure is sufficient; this spec only hardens launch readiness.
- **Allowed deviation and why**: none
- **Consistency impact**: Public copy, CTAs, metadata, route exposure, sitemap, and browser review must stay aligned across the website.
- **Review focus**: Verify no `apps/platform` dependency or admin/runtime shared pattern is introduced.

## OperationRun UX Impact

- **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**: N/A
- **Queued DB-notification policy**: N/A
- **Terminal notification path**: N/A
- **Exception required?**: none

## Provider Boundary / Platform Core Check

- **Shared provider/platform boundary touched?**: no
- **Boundary classification**: N/A
- **Seams affected**: N/A
- **Neutral platform terms preserved or introduced**: Public copy may mention Microsoft tenant configuration as product positioning only.
- **Provider-specific semantics retained and why**: Bounded public positioning for Microsoft tenant configuration; no runtime contracts, models, Graph calls, or platform-core taxonomy changes.
- **Why this does not deepen provider coupling accidentally**: The feature changes only static public website artifacts and does not alter product runtime boundaries.
- **Follow-up path**: none

## UI / Surface Guardrail Impact

`N/A - no admin/operator-facing product surface change. This spec changes public marketing website surfaces only.`

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Public website launch-readiness pass | no | ScrewFast-derived Astro website | none | static pages, route metadata, navigation, footer | no | Public website only; no Laravel/Filament/Livewire surface |

## Decision-First Surface Role

N/A - no admin/operator-facing product surface is added or changed.

## Audience-Aware Disclosure

N/A - no authenticated detail/status surface is added or changed. Static product previews must remain clearly illustrative/static/demo content.

## UI/UX Surface Classification

N/A - no Filament/operator list, detail, queue, audit, config, or report surface is added or changed.

## Operator Surface Contract

N/A - no admin/operator-facing product page is added or materially refactored.

## Proportionality Review

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no product runtime persistence. A website-local launch-readiness note may be added as a release handoff artifact.
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: Public launch review currently lacks a bounded, reviewable checklist for messaging, CTAs, claims, metadata, routes, and responsive behavior after the website foundation rebuild.
- **Existing structure is insufficient because**: Spec 402 established the substrate; it did not exhaustively certify public release quality or claim posture.
- **Narrowest correct implementation**: Website-local edits plus static/browser validation, no platform/runtime changes.
- **Ownership cost**: Maintaining website copy, metadata, smoke coverage, and the launch-readiness note.
- **Alternative intentionally rejected**: Rebuilding the website foundation again or introducing backend workflows for contact/demo/account behavior.
- **Release truth**: Current-release launch readiness for the public website.

### Compatibility posture

This feature assumes a pre-production environment for the public website. It introduces no product runtime compatibility, migration, legacy alias, or data-shape requirement.

## Testing / Lane / Runtime Impact

- **Test purpose / classification**: Browser/static website
- **Validation lane(s)**: website build, public smoke, browser review, whitespace/scope checks
- **Why this classification and these lanes are sufficient**: The feature changes static public website behavior, metadata, route exposure, CTAs, and responsive rendering rather than Laravel runtime behavior.
- **New or expanded test families**: May update website smoke checks if route/CTA/sitemap validation gaps are found.
- **Fixture / helper cost impact**: none expected; no provider, workspace, membership, database, session, Filament, Livewire, or Laravel setup.
- **Heavy-family visibility / justification**: Browser review is explicit and limited to public website pages.
- **Special surface test profile**: N/A - public website static/browser validation.
- **Standard-native relief or required special coverage**: N/A - no Filament surface.
- **Reviewer handoff**: Confirm lane fit, no hidden platform runtime cost, and exact validation commands listed in this spec.
- **Budget / baseline / trend impact**: none expected.
- **Escalation needed**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**:
  - `corepack pnpm build:website`
  - `WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke`
  - `git diff --check`
  - `git status --short -- apps/platform`

## Status

Draft

## Scope

Runtime/source implementation for this spec is strictly local to `apps/website`.

Spec Kit artifacts for planning, tasks, analysis, and launch handoff may live under `specs/403-public-website-launch-readiness/`.

It builds on Spec 402, where `apps/website` was replaced with a Tenantial-branded public website derived from the pinned ScrewFast foundation.

This spec does not rebuild the website foundation again. It does not replace the ScrewFast substrate. It focuses on launch-readiness of public copy, navigation, CTA flows, metadata, route exposure, trust wording, and browser review.

## Important Scope Clarification

In this feature, the word "platform" refers only to the public website route `/platform` inside `apps/website`.

It does not refer to the Laravel/Filament application in `apps/platform`.

`apps/platform` is completely out of scope:

- do not modify it
- do not import from it
- do not run platform-specific migrations, tests, providers, resources, policies, Livewire, Filament, Blade, jobs, queues, database, tenant/workspace, RBAC, or Microsoft Graph code
- only verify through `git diff` or `git status` that it remains untouched

Planning artifacts and the launch-readiness handoff note are allowed under `specs/403-public-website-launch-readiness/`; they must not introduce platform runtime behavior.

## Goal

Make the current Tenantial public website release-ready after the Spec 402 ScrewFast-derived rebuild.

The website should clearly communicate Tenantial's public product positioning, expose only intentional routes, avoid unsupported public claims, provide coherent CTAs, and pass manual/browser/static launch checks.

## Non-Goals

This spec does not:

- recreate `apps/website`
- replace the ScrewFast-derived foundation
- redesign the website from scratch
- remove unused vendored ScrewFast substrate files unless they are publicly emitted or create release risk
- add backend contact/demo workflow
- add authentication, login, customer portal, billing, subscription, or app access behavior
- introduce Microsoft Graph calls
- introduce platform/admin runtime behavior
- touch `apps/platform`
- change Filament, Livewire, Laravel, Blade, providers, policies, migrations, jobs, queues, database, tenant isolation, workspace behavior, RBAC, or AuditLog behavior

## Problem

Spec 402 established the correct website substrate and public route model.

However, a foundation replacement is not the same as launch readiness. Before release, the public website needs a focused pass over:

1. message clarity
2. CTA consistency
3. SEO metadata
4. route exposure
5. trust and pricing safety
6. docs/legal/contact completeness
7. mobile and keyboard usability
8. public claim discipline
9. deployment/reviewer handoff

Without this pass, the website may technically build and smoke-test while still being unclear, under-polished, incorrectly localized, or risky from a public-claims perspective.

## User Scenarios & Testing

### User Story 1 - Understand Tenantial Quickly (Priority: P1)

A first-time visitor opens the homepage and understands within one minute that Tenantial is an evidence-first governance product for Microsoft tenant configuration, with emphasis on backup, restore, drift detection, findings, evidence, auditability, exceptions, and reviews.

**Why this priority**: The homepage is the main conversion and positioning surface. If the message is unclear, the website is not launch-ready even if the build passes.

**Independent Test**: Open `/` in desktop and mobile widths and verify that the hero, section sequence, CTAs, and FAQ communicate the product category and core value without requiring platform knowledge.

**Acceptance Scenarios**:

1. **Given** a visitor opens `/`, **When** the hero loads, **Then** Tenantial's product category and primary value proposition are visible without scrolling.
2. **Given** a visitor scans the homepage, **When** they move through sections, **Then** they can identify at least three core capabilities.
3. **Given** a visitor reaches the final CTA, **When** they decide what to do next, **Then** the CTA path is clear and does not imply unsupported login, billing, or backend workflow behavior.

---

### User Story 2 - Evaluate The Public Product Route (Priority: P1)

A buyer opens `/platform` and understands Tenantial's public product model without confusing it with the internal Laravel/Filament app.

**Why this priority**: The `/platform` page is the primary product explanation route. It must explain the product clearly while staying within public website scope.

**Independent Test**: Open `/platform` and verify that the page explains the public product model, not internal implementation details.

**Acceptance Scenarios**:

1. **Given** a visitor opens `/platform`, **When** the page loads, **Then** the page explains backup, restore, drift detection, findings, evidence, audit trail, exceptions, and reviews.
2. **Given** the page uses product-like previews, **When** they are reviewed, **Then** they are clearly static/demo previews and do not imply live tenant data.
3. **Given** the page references Microsoft tenants, **When** copy is reviewed, **Then** the language remains public positioning and does not imply a runtime Microsoft Graph integration on the website.

---

### User Story 3 - Follow A Safe CTA Path (Priority: P2)

A visitor who wants to evaluate Tenantial can follow a clear contact/demo path without encountering fake forms, dead links, fake account access, or unsupported self-serve purchase claims.

**Why this priority**: CTA integrity is essential for trust. Public CTAs must match what the website can actually support.

**Independent Test**: Click primary and secondary CTAs from homepage, `/platform`, `/pricing`, `/trust`, docs, and footer. Verify that each CTA leads to an intentional route or anchor.

**Acceptance Scenarios**:

1. **Given** a visitor clicks a demo/contact CTA, **When** the link resolves, **Then** it leads to `/contact` or an intentional page section.
2. **Given** a visitor sees pricing, **When** they review package language, **Then** the page avoids unsupported billing, checkout, plan entitlement, or self-serve subscription claims.
3. **Given** no backend form workflow exists, **When** a contact surface renders, **Then** it does not imply a guaranteed workflow, automated provisioning, or account creation.

---

### User Story 4 - Trust The Claims (Priority: P2)

A security-conscious buyer reads trust, legal, pricing, and product pages and sees conservative, proof-safe wording.

**Why this priority**: Tenantial is an enterprise governance product. Unsupported claims about compliance, certifications, Microsoft endorsement, uptime, recovery guarantees, or customer adoption would be risky.

**Independent Test**: Review visible copy and metadata on `/`, `/platform`, `/pricing`, `/trust`, `/legal`, `/privacy`, `/terms`, `/imprint`, and docs routes.

**Acceptance Scenarios**:

1. **Given** no verified certifications are supplied, **When** trust pages render, **Then** they do not claim SOC 2, ISO, Microsoft endorsement, guaranteed compliance, guaranteed uptime, or guaranteed recovery.
2. **Given** no customer proof is supplied, **When** social-proof areas render, **Then** they do not show fake customer logos, fake testimonials, or "trusted by" claims.
3. **Given** static product previews are shown, **When** reviewed, **Then** they are framed as illustrative/static/demo content rather than live tenant output.

---

### User Story 5 - Review Launch Metadata And Route Exposure (Priority: P3)

A site owner can review the public website output and confirm routes, metadata, sitemap, robots, and redirects are intentional.

**Why this priority**: Launch readiness includes not only visual pages, but also search engine exposure, route hygiene, and public metadata.

**Independent Test**: Run static route and metadata checks against the built website output.

**Acceptance Scenarios**:

1. **Given** the website builds, **When** sitemap output is inspected, **Then** only canonical renderable routes are included.
2. **Given** redirect aliases exist, **When** sitemap output is inspected, **Then** redirect-only routes are excluded.
3. **Given** `robots.txt` is opened, **When** reviewed, **Then** it points to the intended sitemap index.
4. **Given** public pages are opened, **When** metadata is reviewed, **Then** titles and descriptions are Tenantial-specific and route-appropriate.

### Edge Cases

- If a route is retained from ScrewFast but not ready for Tenantial content, it must be hidden from navigation, redirected intentionally, or given restrained placeholder content.
- If docs pages are exposed, they must not imply product behavior that does not exist yet.
- If pricing is not final, pricing must remain conservative and contact/demo-oriented.
- If trust/legal wording is not legally reviewed, pages must use restrained placeholder language.
- If a CTA cannot be backed by a real workflow, it must link to `/contact` or be removed.
- If product previews include status-like values, they must not become shared product taxonomy or imply runtime truth.
- If visual assets are retained from the vendored ScrewFast source but unused, they are not release blockers unless they are imported, emitted, linked, or visible.
- If localized or editorial routes are not ready, they must not appear in primary navigation.
- If localization is enabled, German must remain the unprefixed default and English must use `/en/...` route prefixes.
- If reduced-motion is enabled, content must remain understandable without animation.
- If JavaScript fails, primary content and links must remain usable where reasonably possible for a static marketing site.

## Assumptions

- Spec 402 is already implemented and validated.
- `apps/website` is now ScrewFast-derived and Tenantial-branded.
- `apps/platform` is untouched and remains out of scope.
- No verified customer logos, testimonials, certifications, Microsoft endorsements, uptime guarantees, compliance guarantees, or recovery guarantees have been supplied.
- No self-serve billing or account provisioning workflow is available from the public website.
- The public domain is `tenantial.com`.
- The generated sitemap entrypoint is `/sitemap-index.xml`.
- German is the default public website locale at unprefixed routes.
- English is an additional public locale under `/en/...`.

## Requirements

### Scope And Architecture

- **FR-001**: Runtime/source implementation MUST remain strictly scoped to `apps/website`; Spec Kit artifacts and launch handoff notes MAY live under `specs/403-public-website-launch-readiness/`.
- **FR-002**: The implementation MUST NOT touch `apps/platform`.
- **FR-003**: The implementation MUST NOT replace or rebuild the ScrewFast-derived foundation again.
- **FR-004**: Changes SHOULD focus on copy, metadata, route exposure, CTA behavior, public assets, and launch documentation.
- **FR-005**: Unused vendored ScrewFast substrate files MAY remain if they are not publicly emitted or referenced.

### Public Positioning

- **FR-006**: The homepage MUST clearly position Tenantial as evidence-first governance for Microsoft tenant configuration.
- **FR-007**: The homepage MUST communicate backup, restore, drift detection, findings, evidence, auditability, exceptions, and reviews either directly or through linked product sections.
- **FR-008**: The `/platform` route MUST explain the public product model without referencing internal Laravel/Filament implementation details.
- **FR-009**: Public copy MUST avoid implementation-first labels where user-facing product language is clearer.

### CTA And Navigation

- **FR-010**: All public CTAs MUST resolve to intentional routes or anchors.
- **FR-011**: Public CTAs MUST NOT imply login, account creation, billing, checkout, backend submission, or automated onboarding unless such workflow exists.
- **FR-012**: Primary navigation MUST expose only intentional, release-ready public routes.
- **FR-013**: Footer navigation MUST expose legal, trust, contact, and core product routes intentionally.
- **FR-014**: Redirect aliases MUST remain intentional. Aliases that render HTML MUST be noindex; aliases implemented as pure redirects MUST be documented by redirect status/target and excluded from sitemap output.
- **FR-014a**: Language switching MUST keep German as the unprefixed default locale and English as prefixed `/en/...` routes.
- **FR-014b**: Navigation, footer links, CTAs, metadata, and docs links MUST resolve to the current locale where a localized route exists.

### Trust, Pricing, And Claims

- **FR-015**: Trust copy MUST avoid unsupported SOC 2, ISO, Microsoft endorsement, uptime, recovery, compliance, or customer adoption claims.
- **FR-016**: Pricing copy MUST avoid unsupported plan entitlement, self-serve subscription, billing, checkout, or purchase claims.
- **FR-017**: Static product previews MUST be framed as illustrative/static/demo content and MUST NOT imply live tenant data.
- **FR-018**: Public pages MUST NOT publish fake customer logos, fake testimonials, or fake "trusted by" claims.

### Metadata And SEO

- **FR-019**: Each canonical public route MUST have Tenantial-specific title and description metadata.
- **FR-020**: The generated sitemap MUST include only intentional canonical public routes.
- **FR-021**: Redirect-only aliases MUST be excluded from sitemap output.
- **FR-022**: `robots.txt` MUST point to `/sitemap-index.xml`.
- **FR-023**: Public metadata MUST NOT contain ScrewFast, construction/hardware, template, TenantAtlas, TenantPilot, or TenantCTRL residue.
- **FR-023a**: Public metadata MUST expose correct locale signals for German default pages, English `/en/...` pages, and alternate language URLs.

### Accessibility And Responsive Review

- **FR-024**: Public pages MUST remain usable on representative mobile and desktop viewport sizes.
- **FR-025**: Body-level horizontal overflow MUST NOT occur on validated public routes.
- **FR-026**: Keyboard users MUST be able to reach primary navigation, CTAs, footer links, and visible form controls.
- **FR-027**: Focus-visible states MUST be visible for interactive elements.
- **FR-028**: Reduced-motion preferences MUST be respected for retained animations.
- **FR-029**: Status or preview meaning MUST NOT rely on color alone.

### Validation

- **FR-030**: Build validation MUST pass with `corepack pnpm build:website`.
- **FR-031**: Public smoke validation MUST pass with `WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke`.
- **FR-032**: Whitespace/conflict validation MUST pass with `git diff --check`.
- **FR-033**: Scope validation MUST confirm `git status --short -- apps/platform` is empty.
- **FR-034**: A launch-readiness note MUST document route exposure, CTA assumptions, trust/pricing claim posture, sitemap behavior, and deployment expectations.

## Constitution Alignment

- This feature introduces no Microsoft Graph calls.
- This feature introduces no product write/change behavior.
- This feature introduces no queued or scheduled work.
- This feature introduces no OperationRun behavior.
- This feature introduces no AuditLog behavior.
- This feature introduces no tenant/workspace isolation behavior.
- This feature introduces no RBAC behavior.
- This feature introduces no Laravel/Filament/Livewire/admin behavior.
- This feature introduces no database or persisted product truth.
- This feature introduces no shared product status taxonomy.
- This feature introduces no provider/platform seam.
- This feature is limited to public website artifacts and public website validation.
- Livewire v4.0+ compliance: N/A for implementation because no Livewire code is in scope; the platform remains on Livewire v4 per application info.
- Provider registration location: N/A for implementation because no Laravel providers are added or changed; Laravel 11+/12 provider registration remains outside scope.
- Globally searchable resources: N/A because no Filament resources are added or changed.
- Destructive actions: none.
- Asset strategy: website-local Astro/ScrewFast assets only; no Filament assets are registered, so `filament:assets` is not part of this feature's deploy path.
- Testing plan: website build, public smoke validation, browser review, `git diff --check`, and `apps/platform` untouched scope check.

## Success Criteria

- **SC-001**: 100% of canonical public routes render successfully during smoke validation.
- **SC-002**: 100% of redirect-only aliases redirect intentionally and are excluded from sitemap output.
- **SC-003**: 0 public `href="#"` placeholders remain in source or emitted HTML.
- **SC-004**: 0 forbidden public residue terms appear in visible copy or metadata across validated public routes.
- **SC-005**: 100% of public CTAs resolve to intentional routes or anchors.
- **SC-006**: 100% of trust, pricing, and preview claims are conservative or backed by supplied proof.
- **SC-007**: 100% of validated mobile and desktop review sizes show no body-level horizontal overflow.
- **SC-008**: Primary navigation, CTAs, footer links, and visible controls are reachable by keyboard.
- **SC-009**: `corepack pnpm build:website` passes.
- **SC-010**: `WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke` passes.
- **SC-011**: `git diff --check` passes.
- **SC-012**: `git status --short -- apps/platform` returns empty.

## Reviewer Notes

Reviewers should focus on launch quality, not on replacing the website foundation again.

The main review questions are:

1. Does the homepage explain Tenantial clearly?
2. Does `/platform` explain the public product model without touching or implying `apps/platform` implementation details?
3. Are CTAs honest and usable?
4. Are trust and pricing claims conservative?
5. Are sitemap, robots, metadata, and route exposure intentional?
6. Is the website still ScrewFast-derived rather than a new custom design system?
7. Is `apps/platform` untouched?

## Suggested Validation Commands

```bash
corepack pnpm build:website
WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke
git diff --check
git status --short -- apps/platform
```