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

Feature Specification: Tenantial Platform Page

Feature Branch: feat/401-tenantial-platform-page Created: 2026-05-18 Status: Draft Input: User description: "Spec 401 - Tenantial Platform Page. Create a dedicated public /platform page for Tenantial that explains the evidence-first governance operating model, core capabilities, governance loop, safe product boundaries, navigation consistency, Tenantial metadata, accessibility, responsiveness, conservative claims, and website-only runtime scope."

Visual Refactor Update: 2026-05-18 follow-up request: refactor /platform so it closely follows the provided Tenantial mockup as a target for composition, visual hierarchy, density, product expression, dashboard-preview hero, connected governance diagrams, asymmetric capability grouping, truth-layer visual, warmer operator workflow zone, clear boundaries band, focused CTA, and quiet footer.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: After the homepage rebuild, visitors have a stronger first impression but no dedicated page that explains what Tenantial governs, how the governance loop works, and how backup, restore, drift, findings, evidence, audit trails, exceptions, and reviews connect.
• Today's failure: A buyer can mistake Tenantial for a generic backup tool, helpdesk product, device action tool, or template site because the public website does not yet explain the product model beyond the homepage promise.
• User-visible improvement: The Platform page gives IT, MSP, security, and audit stakeholders a structured explanation of Tenantial's evidence-first governance model and clear next steps without unsupported security, compliance, customer, or runtime-data claims.
• Smallest enterprise-capable version: Add one canonical public Platform page, align public navigation and homepage CTA links to it, preserve or resolve /product compatibility if needed, provide Tenantial-specific metadata, include conservative product boundaries, and add website smoke coverage for the route and key claims.
• Explicit non-goals: No platform runtime changes, no admin UI, no Filament or Livewire changes, no authentication, no backend APIs, no Microsoft Graph calls, no real tenant data, no CMS, no i18n, no pricing page, no trust center, no demo-booking backend, and no customer logos or unsupported certifications.
• Permanent complexity imported: One public website page narrative, route and navigation expectations, static content sections, website-only smoke expectations, and ongoing responsibility to keep public Tenantial copy aligned with Spec 400.
• Why now: Spec 400 makes "Explore the platform" a natural next step; without a real Platform page, the primary homepage journey is incomplete and the public product story remains underexplained.
• Why not local: A homepage-only copy patch cannot answer product-model questions or resolve /platform versus /product navigation consistency across the public site.
• Approval class: Core Enterprise
• Red flags triggered: None. The feature introduces no persisted truth, domain state, runtime abstraction, provider contract, or cross-domain UI framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: Public website. This is outside workspace, tenant, and canonical admin scopes.
• Primary Routes: /platform; existing /product route must be retained only as redirect compatibility to /platform if present.
• Data Ownership: Static public website content only. No workspace-owned, tenant-owned, platform runtime, or persisted application data is introduced.
• RBAC: None. The Platform page is public and introduces no authorization behavior.

Relationship To Existing Specs

• Spec 400 establishes the Tenantial homepage direction, dark premium visual language, public brand copy, and the homepage "Explore the platform" journey.
• Spec 401 extends that direction into the first dedicated public product explanation page.
• Spec 223 remains historical website rebuild context if still present, but Spec 401 is the Tenantial-specific Platform page slice.
• If no local Spec 227 artifact exists, this spec does not create one. Any homepage/platform visual foundation overlap is treated as refined by Specs 400 and 401.

Visual Refactor Target

• /platform should read as a product-marketing page with governance-control-room density, not as a documentation page or a repeated stack of equal dark cards.
• The first viewport must use a split layout: concise positioning and CTAs on the left, a large static dashboard/product preview on the right.
• The Operating Model must render as a compact connected step chain: Snapshot, Drift, Finding, Review, Evidence, Audit trail.
• The Governance Loop must be a central visual diagram connecting Source of truth, Snapshot, Diff, Finding, Exception, Review, Evidence, and Audit trail.
• Capabilities must be visually grouped with a larger Backup & Restore primary block and secondary capability cards for Drift Detection, Findings, Evidence, Audit Trail, Exceptions, and Governance Reviews.
• Truth Layers must use a layer-stack or equivalent visual model for Execution truth, Artifact truth, Backup truth, Recovery evidence, and Operator next action.
• Operator Workflows should be compact, persona-oriented, and visually warmer than the control-room sections.
• Platform Boundaries must read as a trust/honesty band with short boundary statements rather than a defensive list.
• Final CTA and footer must avoid two equally heavy closing sections; the footer should be calmer after the focused CTA.
• The refactor remains website-only and must not change apps/platform, workspace contracts, packages, dependencies, or lockfiles.

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)

N/A - no shared operator interaction family touched. This feature changes public marketing navigation and content, not admin notifications, operator status messaging, operation links, dashboard signals, alerts, report viewers, or shared operator interaction contracts.

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)

N/A - no OperationRun start, completion, deduplication, resume, block, or link semantics touched.

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)

N/A - no shared provider/platform boundary touched. The page may describe Microsoft tenant governance at a public product level, but it does not change provider contracts, platform-core vocabulary, identity scope, compare strategy, governed-subject taxonomy, or runtime provider behavior.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no operator-facing admin surface change. This feature changes a public marketing page only and does not affect Filament/admin pages, tenant-scoped operator workflows, shared operator components, action surfaces, or governance decision surfaces.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: Yes, limited to public Platform page messaging and public route intent. No product runtime or tenant-governance truth is introduced.
• New persisted entity/table/artifact?: No.
• New abstraction?: No runtime abstraction. Any page sections are website-local presentation content for this public page.
• New enum/state/reason family?: No.
• New cross-domain UI framework/taxonomy?: No.
• Current operator problem: Prospective buyers and stakeholders cannot yet understand Tenantial's governance operating model from a dedicated public page.
• Existing structure is insufficient because: The homepage introduces the promise but cannot carry a full explanation of the platform model, capability relationships, route expectations, boundaries, and proof-safe positioning.
• Narrowest correct implementation: One static public Platform page with aligned navigation, route compatibility expectations, conservative copy, accessibility/responsive requirements, Tenantial metadata, and route smoke coverage.
• Ownership cost: Platform page copy, static section content, navigation labels, metadata, and smoke assertions must be maintained as later website pages are added.
• Alternative intentionally rejected: Building pricing, trust, solutions, resources, i18n, CMS, or live product-data integration in the same slice. Those would broaden scope before the core Platform explanation is stable.
• Release truth: Current public website truth, not platform runtime truth or future live data truth.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility for stale public /product copy is not preserved as a product requirement. If /product already exists, it must remain only as a redirect compatibility path to /platform. No public route may expose stale AstroDeck, TemplateDeck, TenantAtlas, TenantPilot, or TenantCTRL copy.

Internal package names, workspace scripts, and platform runtime contracts must not be renamed by this feature. In particular, an internal website package name may remain unchanged even if it includes a historical repository name.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Browser.
• Validation lane(s): browser.
• Why this classification and these lanes are sufficient: The feature changes a public static website route, navigation, content, metadata, responsive behavior, and copy safety. Website build and smoke checks are the narrowest honest proof.
• New or expanded test families: Platform route website smoke coverage only.
• Fixture / helper cost impact: None. No database, workspace, membership, provider, session, seed, or platform setup should be required.
• Heavy-family visibility / justification: Browser coverage is intentional and scoped to the public Platform route plus route compatibility where needed.
• Special surface test profile: N/A.
• Standard-native relief or required special coverage: Website smoke checks plus desktop/mobile visual review.
• Reviewer handoff: Reviewers must confirm browser coverage remains website-scoped, no hidden platform setup is introduced, and the proof checks visible content, metadata cleanup, navigation, and mobile overflow.
• Budget / baseline / trend impact: None expected beyond a small Platform route smoke addition.
• 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.

User Scenarios & Testing (mandatory)

User Story 1 - Understand The Platform Model (Priority: P1)

A first-time buyer or stakeholder opens the Platform page and understands that Tenantial is an evidence-first governance platform for Microsoft tenant environments, not only a backup tool or generic SaaS site.

Why this priority: This is the minimum viable Platform page outcome. If the page does not explain the product model, the homepage CTA journey remains incomplete.

Independent Test: Can be tested by opening /platform and verifying that the first viewport shows Tenantial Platform positioning, a clear governance headline, Microsoft tenant context, and a product-oriented explanation.

Acceptance Scenarios:

1. Given a visitor follows "Explore the platform" from the homepage, When /platform opens, Then they see Tenantial Platform branding and a headline about governing Microsoft tenants through evidence, drift context, and reviewable decisions.
2. Given a visitor reads the first viewport, When they scan the hero, Then they can identify backup records, configuration drift, findings, evidence, audit trails, and structured reviews as connected parts of the platform model, supported by a large static dashboard/product preview.
3. Given a visitor is deciding what to do next, When they inspect the page actions, Then "Book a demo" is available as the primary CTA and "See the governance loop" guides them deeper into the page.

---

User Story 2 - See How Governance Work Flows (Priority: P2)

An IT, MSP, security, or compliance stakeholder reviews the operating model and understands how raw tenant change becomes reviewable governance evidence.

Why this priority: Tenantial's public promise depends on explaining the governance loop, not just listing features.

Independent Test: Can be tested by reviewing the operating model and governance loop sections for the required steps and conservative operator-led language.

Acceptance Scenarios:

1. Given a stakeholder reaches the operating model section, When they review the workflow, Then they see a compact connected sequence covering Snapshot, Drift, Finding, Review, Evidence, and Audit trail.
2. Given the governance loop is visible, When the visitor scans the section, Then they understand through a connected diagram that governance is about preserving context and reviewable decisions, not only knowing current configuration state.
3. Given the page describes findings and restore context, When a visitor reads the copy, Then it does not imply automatic remediation, guaranteed recovery, or device action workflows.

---

User Story 3 - Evaluate Capabilities And Boundaries (Priority: P3)

A stakeholder evaluates the page and can distinguish Tenantial's core capabilities from out-of-scope helpdesk, SIEM, device action, or Microsoft admin center replacement promises.

Why this priority: Product trust depends on explaining what the platform does and where its boundaries are.

Independent Test: Can be tested by reviewing capability, truth-layer, workflow, and boundary sections for required concepts and absence of unsupported claims.

Acceptance Scenarios:

1. Given a visitor reads the capability section, When they scan the grouped capability zone, Then they see Backup & Restore as the primary block plus Drift Detection, Findings, Evidence, Audit Trail, Exceptions, and Governance Reviews as supporting capabilities.
2. Given a visitor reads the platform boundaries section, When they compare Tenantial to other tools, Then they understand it is built for governance of record and recovery context, not helpdesk actions or live device operations.
3. Given a security or audit stakeholder reviews the page, When they inspect claims, Then the page contains no unsupported certifications, guarantees, customer logos, Microsoft endorsement, uptime promises, or blanket compliance statements.

---

User Story 4 - Navigate A Brand-Clean Public Site (Priority: P4)

A website owner reviews the public site journey and confirms that navigation, metadata, and compatibility routing support the Platform page without stale brand or template residue.

Why this priority: The Platform page should become the canonical next step after the homepage without introducing route confusion.

Independent Test: Can be tested through link review, metadata review, visible-copy review, and website smoke coverage for /platform plus redirect behavior from /product if /product remains.

Acceptance Scenarios:

1. Given the homepage is available, When a visitor activates "Explore the platform", Then they reach /platform.
2. Given the global header or footer includes Platform, When a visitor follows that link, Then it reaches the canonical Platform page.
3. Given /product exists before implementation, When route compatibility is reviewed, Then it redirects to /platform and exposes no stale public copy or conflicting metadata.

Edge Cases

• If /product already exists, it must redirect to /platform and must not remain a renderable primary public product route with inconsistent or stale content.
• If no dedicated demo-booking flow exists, "Book a demo" must point to an existing intentional contact path or use another explicitly documented non-dead destination.
• If no approved product screenshot exists, the page may use static diagrams, structured panels, or product-process visuals rather than fake live screenshots.
• If no customer logos, certifications, partnership proof, or compliance evidence are available, the page must use conservative product language instead of social proof.
• If a visitor uses a narrow mobile viewport, diagrams and card grids must simplify or stack without body-level horizontal overflow.
• If icons or visual diagrams are unavailable to assistive technology, adjacent text must communicate the same meaning.
• If status or capability meaning is shown with accent colors, the same meaning must be available through text labels.
• If Spec 400 components are not available in the current branch, the page must still follow the same visual direction rather than inventing a separate brand style.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no write/change behavior, no queued or scheduled work, no OperationRun, no AuditLog changes, no tenant isolation changes, and no platform runtime behavior.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces no persisted product truth, no domain abstraction, no enum/status/reason family, and no cross-domain UI framework. The only new source of truth is public Platform page messaging and route intent, bounded to the website.

Constitution alignment (XCUT-001): This feature does not touch shared operator interaction families. Public website navigation, CTAs, static diagrams, and marketing visuals must remain website-local.

Constitution alignment (DECIDE-AUD-001 / OPSURF-001): This feature does not change admin detail/status surfaces, audience modes, support/raw evidence disclosure, or operator next-action surfaces.

Constitution alignment (PROV-001): This feature does not change provider/platform seams. Microsoft tenant language is public positioning only and must not create runtime provider coupling.

Constitution alignment (TEST-GOV-001): Browser coverage is intentional, Platform-route-scoped, and must not introduce database, workspace, provider, membership, session, or platform defaults.

Constitution alignment (OPS-UX / OPS-UX-START-001): N/A - no OperationRun behavior is created, queued, completed, deduplicated, resumed, blocked, or linked.

Constitution alignment (RBAC-UX): N/A - no authorization plane, capability, membership, global search, mutation, or destructive action behavior changes.

Constitution alignment (BADGE-001): N/A - no admin status badge semantics change. Public marketing labels must remain descriptive and not become a shared status taxonomy.

Constitution alignment (UI-FIL-001): N/A - no Filament, Blade admin, Livewire, Resource, RelationManager, or Page changes.

Constitution alignment (UI-NAMING-001 / DECIDE-001 / UI surface rules): N/A for operator-facing naming and action-surface contracts. Public Platform copy must still use precise user-facing language and avoid implementation-first labels.

Functional Requirements

• FR-001: The public website MUST provide a canonical Platform page at /platform.
• FR-002: The Platform page MUST present Tenantial as an evidence-first governance platform for Microsoft tenant environments.
• FR-003: The first viewport MUST include the eyebrow "TENANTIAL PLATFORM" or equivalent wording with the same meaning.
• FR-004: The first viewport MUST include a headline that communicates governing Microsoft tenants through evidence, drift context, and reviewable decisions.
• FR-005: The first viewport supporting copy MUST connect backup records, configuration drift, findings, evidence, audit trails, and structured reviews into one governance operating loop.
• FR-006: The first viewport MUST provide "Book a demo" as the primary CTA.
• FR-007: The first viewport MUST provide a secondary CTA that navigates to the governance loop section or equivalent in-page explanation.
• FR-008: The Platform page MUST include a large static dashboard/product preview in the hero that is clearly public marketing content and not live tenant data.
• FR-009: The Platform page MUST include a compact connected operating model overview showing the sequence: Snapshot, Drift, Finding, Review, Evidence, and Audit trail.
• FR-010: The Platform page MUST include a visually grouped capability section with Backup & Restore as the primary block plus Drift Detection, Findings, Evidence, Audit Trail, Exceptions, and Governance Reviews as supporting capabilities.
• FR-011: Capability descriptions MUST be concise, product-specific, and free of claims that imply guaranteed remediation, guaranteed compliance, or full automation.
• FR-012: The Platform page MUST include a governance loop section with a connected visual diagram explaining how source-of-truth context, snapshots, diffs, findings, exceptions, reviews, evidence, and audit trails connect.
• FR-013: The governance loop MUST make operator review and evidence preservation explicit.
• FR-014: The Platform page SHOULD include a truth-layers section with a visual layer-stack or equivalent model explaining execution truth, artifact truth, backup truth, recovery evidence, and operator next action in plain language.
• FR-015: The Platform page SHOULD include compact operator workflow examples for MSP operators, enterprise IT, security reviewers, and compliance or audit stakeholders, with a warmer visual treatment than the main control-room sections.
• FR-016: The Platform page MUST include a platform boundaries section stating that Tenantial is built for governance of record and recovery context, does not take actions on the customer's behalf, does not manage devices, does not replace ITSM/SIEM/ticketing/Microsoft admin centers, and supports reviewable decisions.
• FR-017: The Platform page MUST include a focused final CTA that invites visitors to see how evidence-first governance fits their Microsoft tenant operations, followed by a calmer footer.
• FR-018: "Book a demo" CTA destinations MUST be intentional and MUST NOT point to missing or stale template routes.
• FR-019: Homepage "Explore the platform" navigation MUST point to /platform.
• FR-020: Header and footer Platform navigation MUST point to /platform.
• FR-021: If /product exists, it MUST redirect to /platform and MUST NOT render stale, conflicting, or primary public product content.
• FR-022: No public route involved in this feature MAY expose stale AstroDeck, TemplateDeck, Open Source, MIT, TenantAtlas, TenantPilot, or TenantCTRL public copy.
• FR-023: The Platform page MUST use public Tenantial branding and MUST NOT rename internal package or workspace conventions.
• FR-024: The Platform page title MUST communicate "Tenantial Platform" and evidence-first governance for Microsoft tenants.
• FR-025: The Platform page description metadata MUST mention backup, restore, drift detection, findings, evidence, audit trails, exceptions, and reviews for Microsoft tenant governance.
• FR-026: Metadata MUST NOT contain AstroDeck, TemplateDeck, old public brand names, unsupported compliance claims, or unsupported security claims.
• FR-027: The Platform page MUST NOT claim SOC 2 certification, ISO certification, HIPAA compliance, blanket GDPR compliance, end-to-end encryption, guaranteed recovery, guaranteed compliance, zero drift, universal real-time coverage, named customer trust, Microsoft certification, or Microsoft partnership unless independently approved evidence exists.
• FR-028: The Platform page MUST use the Spec 400 public visual direction and the provided mockup target: dark premium background, warm light text, muted secondary text, restrained borders, mint/teal accents, strong product surfaces, subtle grid/wave/glow elements, enterprise calm, and higher visual density than the initial card-heavy implementation.
• FR-029: The Platform page MUST avoid generic bright startup gradients, cybersecurity cliche visuals, fake customer logos, and unapproved customer environment screenshots.
• FR-030: The Platform page MUST have exactly one primary h1.
• FR-031: Page sections MUST use a meaningful heading hierarchy and semantic structure.
• FR-032: Links and CTAs MUST be keyboard-accessible and have visible focus states.
• FR-033: Diagrams and icons MUST have text equivalents or adjacent explanatory text.
• FR-034: No meaning MAY be conveyed by color alone.
• FR-035: Text and controls MUST remain readable on mobile, tablet, desktop, and wide desktop viewports.
• FR-036: The page MUST NOT create body-level horizontal overflow on narrow mobile viewports.
• FR-037: The page MUST remain mostly static and MUST NOT introduce third-party tracking scripts, backend fetches, platform API calls, auth/session coupling, or live tenant-data dependencies.
• FR-038: Existing root workspace scripts, website port conventions, and platform runtime contracts MUST remain unchanged.

Key Entities

• Platform Page Message: The public brand, product category, governance promise, supporting explanation, and CTA hierarchy for /platform.
• Operating Model Step: A public explanation step in the governance flow, such as snapshot, drift detection, finding creation, review context, evidence attachment, decision, or audit trail.
• Capability: A concise public description of a Tenantial capability: Backup, Restore, Drift Detection, Findings, Evidence, Audit Trail, Exceptions, or Governance Reviews.
• Governance Loop: A visual and textual explanation of how configuration state, drift context, operator decisions, evidence, and auditability connect.
• Truth Layer: A plain-language distinction between execution truth, artifact truth, backup truth, recovery evidence, and operator next action.
• Operator Workflow: A short public persona workflow for MSP operators, enterprise IT, security reviewers, or compliance and audit stakeholders.
• Platform Boundary: A product expectation statement that clarifies what Tenantial is not intended to replace or claim.

Assumptions

• The public brand for this page is Tenantial.
• /platform is the canonical public route for this feature.
• /product currently exists in the website and is treated as redirect-only compatibility to /platform rather than the primary public route after this feature.
• "Book a demo" defaults to the existing contact destination unless a dedicated demo route is already present when implementation starts.
• No approved customer logos, certifications, Microsoft partnership proof, compliance guarantees, uptime guarantees, real tenant screenshots, or live product telemetry are available for this slice.
• Static diagrams or structured panels are acceptable substitutes for screenshots when no approved Tenantial product asset exists.
• Spec 400 is the visual and copy baseline for public Tenantial pages.
• This feature is website-only and does not change the Laravel platform, Filament admin, Livewire behavior, Microsoft Graph integration, database schema, queues, workers, sessions, or authentication.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In stakeholder review, at least 8 of 10 reviewers can identify Tenantial as an evidence-first Microsoft tenant governance platform within 5 seconds of viewing the Platform page first viewport.
• SC-002: 100% of required Platform page sections render on desktop and mobile review: hero, operating model overview, capability grid, governance loop, platform boundaries, final CTA, and footer.
• SC-003: At least 90% of reviewers can explain how backup records, drift, findings, evidence, audit trails, exceptions, and reviews connect after reading the page.
• SC-004: Visible copy and metadata review finds 0 occurrences of AstroDeck, TemplateDeck, Open Source, MIT, TenantAtlas, TenantPilot, TenantCTRL, or other stale public brand/template positioning.
• SC-005: Claims review finds 0 unsupported customer, certification, partnership, uptime, recovery, security, or blanket compliance claims.
• SC-006: Navigation review confirms the homepage "Explore the platform" CTA, header Platform link, and footer Platform link all reach /platform.
• SC-007: If /product remains available, route review confirms it redirects to /platform and does not expose inconsistent public content or conflicting metadata.
• SC-008: Desktop and mobile review confirms 0 body-level horizontal overflow issues at narrow mobile, tablet, desktop, and wide desktop widths.
• SC-009: Accessibility review confirms one primary heading, meaningful section headings, keyboard-accessible CTAs, visible focus states, readable contrast, and no color-only meaning.
• SC-010: Website smoke validation confirms /platform renders, required brand/capability/boundary copy is visible, old template/public brand residue is absent, and route compatibility behavior is covered if /product remains.