# Product Surface Contract > Canonical review and merge-gate contract for product-facing UI surfaces. > This is workflow and standards truth only. It is not a runtime framework, > database model, presenter layer, enum family, or component library. **Last reviewed**: 2026-06-21 ## Purpose TenantPilot product surfaces must help the current user make a safe decision. They must not expose everything the system knows by default. This contract applies when a spec adds, removes, renames, or materially changes any reachable product surface, including pages, routes, navigation entries, tables, forms, modals, drawers, wizard steps, actions, customer views, status/readiness/evidence presentation, downloads, reports, provider state, restore flows, or workspace/environment context presentation. Docs-only, template-only, tooling-only, and test-only changes may record `N/A - no rendered UI surface changed` when no reachable rendered UI changes. ## No Legacy Posture TenantPilot is pre-production for this contract. Future product-surface work must prefer clean canonical behavior over compatibility with old labels, action keys, local status wording, duplicated UI, hidden routes, fallback readers, or legacy fixtures unless an active spec explicitly approves a compatibility exception. Do not show old and new concepts together just to preserve pre-production UI behavior. ## Product Layers Every product-facing default view must separate these layers: - **Product Layer**: visible by default. Shows status, reason, impact, one dominant next action, compact business context, customer-safe evidence summary, and a small status summary when useful. - **Technical Evidence Layer**: hidden by default or moved to an internal technical/audit path. Holds OperationRuns, raw evidence IDs, source keys, detectors, fingerprints, UUIDs, payloads, provider payloads, diff internals, logs, and full audit trails. Product-facing default pages must not expose Technical Evidence Layer content by default. Use one secondary/internal action such as `View audit trail`, `View internal evidence details`, or `View technical details`, with appropriate authorization. ## Page Archetypes Every touched product page must declare exactly one primary archetype: - Dashboard Page: What needs attention now? - Receipt Page: What happened, when, and can I trust it? - Decision Page: What changed and what decision should I make? - Inbox Page: What work items need triage? - Wizard Page: What step am I on and what do I do next? - Report Page: What customer/operator summary can be consumed or exported? - Search/Index Page: How do I find a record? - Technical Annex Page: What are the internal technical details? - Settings Page: What behavior is configured? - System Admin Page: What is the platform/system state? If a page mixes archetypes, reduce it to one archetype, split the page, or document a temporary exception with a follow-up. ## Surface Budgets Product-facing pages must satisfy these budgets unless classified as Technical Annex or System Admin, or unless the active spec records an exception: - Max 1 primary user question. - Max 1 primary action. - Max 2 secondary actions. - Max 4 summary metrics above the fold. - Max 1 main table visible by default. - Max 8 visible rows before Show more, pagination, or full table. - Max 1 readiness/status model. - Max 1 decision flow. - Max 0 raw technical identifiers in the default view. - Max 0 OperationRun links in the default view. - Max 0 raw Evidence deep links in the default view. - Max 0 Source Key, Detector, or Technical Dimension blocks in the default view. - Max 0 repeated readiness/status summaries on the same page. Exceptions must include page, violated budget, reason, why the page is not customer/product-facing if applicable, and a follow-up when temporary. ## Canonical Status Vocabulary Allowed product-facing states: - Ready - Needs attention - Blocked - Running - Failed - Expired - Not configured - Unknown - Historical - Superseded Allowed severity states: - Critical - High - Medium - Low - Info Old or internal terms must be mapped before display. Do not expose `Healthy`, `OK`, `Warning`, `At risk`, `Degraded`, `Partially ready`, `Likely stale`, or similar terms as independent top-level product states unless an active spec records a mapping or exception. ## Readiness Truth A page may show only one top-level readiness/status truth for a concept. Required shape: ```text Provider readiness: Expired Reason: Verification is stale. Next action: Verify provider. ``` Forbidden shape: ```text Provider: Healthy Verification: Stale Permissions: Missing Readiness: Ready Action: Needs attention ``` Future readiness-producing specs must declare the canonical source, consumer pages, display state, blocking reasons, and whether the state is customer-safe. ## Deep-Link Demotion Default product views must not expose a graph of internal objects. Demote these links from default product views: - OperationRun. - Evidence Snapshot or Evidence Artifact. - Baseline Snapshot/Profile internals. - Detector, Source Key, raw Finding fingerprint. - Provider payload. - Raw report artifact. - Restore operation proof. - Technical logs. Allowed default product links include: - Open workspace. - Open environment. - Review blockers. - Open customer workspace. - Download customer output. - Compare to current. - Verify provider. - Resolve finding. - Open report. - Start restore. Internal/audit links are allowed as secondary/internal actions only. ## Table Caps Product-facing hot tables must default to: - Max 8 visible rows. - Pagination or Show all for more. - Clear row status. - One row primary action. - No raw IDs as primary labels. - No excessive inline links. Technical Annex and System Admin pages may show more rows, but they must be clearly technical/system-facing. ## Action Model Every product-facing page must define: - Primary action. - Secondary actions. - Danger/destructive actions. - Technical/audit actions. There may be only one primary action. Destructive or high-impact actions must be visually separated, authorization-checked, audit-logged when mutating, and confirmation-protected. ## Role And Audience Boundaries Customer/read-only default paths must not expose raw evidence, raw IDs, OperationRun proof, fingerprints, payloads, source keys, internal reason ownership, platform reason families, or debug semantics by default. Operator diagnostics may expose more detail through progressive disclosure. Support/raw evidence must be capability-gated where the audience model distinguishes support or platform users from ordinary operators. Provider-specific terms remain Technical Annex or provider diagnostics detail unless the immediate product decision requires them. ## Browser Verification Every implemented spec that changes rendered UI, routes, actions, authorization, downloads, reports, readiness, evidence, provider state, restore flows, customer output, or Product Surface Contract behavior must include focused browser verification. If no runtime UI files change, record browser proof as `N/A - no rendered UI surface changed`. If runtime UI changes, the implementation report must record affected routes, the focused browser path, primary interaction executed, expected state, console/runtime/network result, Livewire/Filament errors if any, and whether any full-suite browser failures are unrelated. ## Human Product Sanity A 5 to 15 minute human product sanity check is required for customer-facing surfaces, dashboards, readiness/status surfaces, review/report output, restore/wizard flows, provider onboarding/readiness, evidence/baseline pages, navigation changes, and Product Surface Contract changes. The reviewer must answer: - Does the page immediately communicate its purpose? - Is there exactly one dominant next action? - Are technical details demoted? - Are status labels understandable and canonical? - Does the page feel less complex or at least not worse? - Would a customer/operator trust the flow? For docs/template/test-only contract changes, record this as a workflow sanity check rather than a rendered-page review. ## Implementation Report Fields Every Product Surface Contract implementation close-out must state: - Active spec and selected slice. - Branch, HEAD, and dirty state. - Files changed. - Runtime UI files changed yes/no. - UI impact or no-impact decision. - Product Surface exceptions, if any. - Browser proof or `N/A - no rendered UI surface changed`. - Human product sanity result. - Visible complexity outcome. - No-legacy confirmation. - Completed-spec rewrite assertion. - Tests/checks run and results. - Livewire v4 compliance. - Provider registration location. - Global search posture. - Destructive/high-impact action posture. - Asset strategy and whether `filament:assets` is required. - Deployment impact for env vars, migrations, queues, scheduler, storage, and assets. - Unrelated failures and follow-up candidates. ## Completed Specs This contract applies to future and active specs. Completed historical specs must not be rewritten, normalized, reopened, or stripped of close-out, validation, task, smoke, browser, or review history just to satisfy new gate wording.