TenantAtlas/specs/396-system-panel-branding/spec.md

Feature Specification: Spec 396 - System Panel Branding and Productization Smoke Config v1

Feature Branch: 396-system-panel-branding Created: 2026-06-21 Status: Draft / Ready for preparation review Input: Direct user-provided candidate "Spec 396 - System Panel Branding & Productization Smoke Config v1", plus repo context from Specs 368, 376, 377, 391, and 395.

Candidate Selection And Completed-Spec Guardrail

• Selected candidate: System Panel Branding and Productization Smoke Config v1.
• Source: Direct user-provided full candidate in /Users/ahmeddarrazi/.codex/attachments/c71e0bc0-934c-482d-ac4d-65e86c55ca59/pasted-text.txt.
• Roadmap relationship: Matches the manual promotion item manual-system-panel-browser-fixture-or-audit-procedure in docs/product/roadmap.md and docs/product/spec-candidates.md, and the explicit deferred follow-up in Spec 395.
• Why selected: docs/product/spec-candidates.md reports no safe automatic next-best-prep target, but the user supplied a concrete P2 candidate. The candidate closes the remaining system-panel proof/productization gap without reopening broad UI productization.
• Smallest viable slice: Productize existing /system panel branding, page titles, navigation labels, top-level status vocabulary, smoke-login or smoke-auth configuration, focused /system browser smoke, and debug/runtime leak checks. Do not add new system features.
• Completed-spec check result:
  • No specs/396-* package existed before this preparation run.
  • Spec 376 is completed context for platform-guard Pest Browser proof of /system and /system/ops/runs; it must not be rewritten.
  • Spec 377 is completed close-out context and leaves manual in-app /system access as a P2 follow-up; it must not be rewritten.
  • Spec 391 is runtime stability/debug-safe context, not reopened except for direct /system smoke regressions.
  • Spec 395 is completed/current workflow-gate context and explicitly defers manual system-panel browser fixture work; it must not be rewritten.
• Close alternatives deferred:
  • Management Report PDF staging/runtime validation remains separate follow-through for Specs 378-380.
  • Governance Artifact Lifecycle and Retention runtime remains manual-promotion P2 scope.
  • Provider readiness/onboarding productization remains optional and evidence-triggered.
  • Cross-domain indicator runtime follow-through remains separate status/indicator scope.
  • Broad /system IA redesign, new dashboard cards, new metrics, and system feature expansion are out of scope.

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

• Problem: The /system surface is a platform-admin surface, but current repo truth still shows productization and smoke-proof gaps: system labels such as System dashboard, Healthy, Warning, OK, Warn, and All systems healthy; manual in-app /system browser access still redirects to /system/login; and smoke/debug suppression is centered on admin smoke routes.
• Today's failure: A reviewer can prove /system through Pest Browser platform guard fixtures, but cannot easily perform a manual productized browser smoke. Visible system labels can still read like framework/scaffold or ambiguous health copy rather than TenantPilot system language.
• User-visible improvement: Platform operators and reviewers see a TenantPilot-branded system panel with canonical status language, deterministic smoke access, and no debug/runtime artifacts on the focused /system smoke path.
• Smallest enterprise-capable version: A narrow productization and smoke-stability pass over existing system panel config, login, dashboard, operations/security/repair surfaces, status labels, local/test smoke access, and focused browser proof.
• Explicit non-goals: No new system features, no /system IA rebuild, no new product dashboard cards, no new readiness model, no production smoke-login route, no provider feature work, no Graph calls, no migrations, no new persisted entities, no compatibility aliases for old labels, and no broad Product Surface Contract enforcement beyond this active spec.
• Permanent complexity imported: Updated copy/status mappings, focused feature/browser tests, possibly one local/testing-only system smoke helper or documented audit procedure, and implementation-report artifacts. No new product table, enum family, source of truth, provider framework, or UI framework is approved.
• Why now: Spec 377 closed productization with this system-panel gap as the remaining follow-up, and Spec 395 added the Product Surface Contract gate. Preparing this spec lets the next implementation close that gap without reopening completed specs.
• Why not local: Manual notes and ad hoc browser sessions do not provide repeatable smoke proof, do not test production safety of fixture routes, and do not prevent default/framework branding from returning.
• Approval class: Core Enterprise.
• Red flags triggered: Multiple surfaces and browser fixture work. Defense: the slice is bounded to existing /system surfaces and local/test smoke proof, introduces no product truth, and explicitly forbids UI expansion.
• Score: Nutzen: 2 | Dringlichkeit: 1 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve as a narrow system-panel productization and smoke-stability slice.

Problem Statement

TenantPilot's /system panel is intentionally technical and platform-admin-only. It still must look and behave like TenantPilot, not like a Laravel/Filament scaffold or an unfinished internal console.

Current repo anchors show the gap:

• apps/platform/app/Providers/Filament/SystemPanelProvider.php registers the system panel but has no explicit product brand name in the inspected provider.
• apps/platform/lang/en/localization.php and apps/platform/lang/de/localization.php use System dashboard / System-Dashboard.
• apps/platform/app/Filament/System/Widgets/ControlTowerHealthIndicator.php returns All systems healthy and Attention needed.
• apps/platform/app/Filament/System/Widgets/CustomerHealthKpis.php renders Healthy and Warning.
• apps/platform/app/Support/Badges/Domains/SystemHealthBadge.php maps system health to OK and Warn.
• apps/platform/tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php proves /system with actingAs($platformUser, 'platform'), while Spec 377 still records manual in-app browser access as not verified.
• apps/platform/app/Http/Middleware/SuppressDebugbarForSmokeRequests.php suppresses debugbar for admin smoke routes and smoke cookie/session, but the active spec must decide how /system smoke carries that protection.

This spec closes that productization and repeatable-proof gap without adding system capabilities.

Product / Business Value

The system panel is used by platform operators and reviewers. Productized system branding, canonical status labels, deterministic smoke access, and no debug/runtime leaks improve trust in TenantPilot's operational maturity without increasing product complexity.

Primary Users / Operators

• Platform/system operator using /system.
• Maintainer running focused browser smoke and productization checks.
• Product reviewer validating that /system is intentionally technical, not unfinished.
• Implementation agent needing a bounded task list for the system-panel follow-up.

Spec Scope Fields (mandatory)

• Scope: canonical-view / system-admin productization / browser-smoke stability.
• Primary Routes:
  • /system
  • /system/login
  • /system/ops/runs
  • /system/ops/failures
  • /system/ops/stuck
  • /system/ops/runbooks
  • /system/ops/controls
  • /system/directory/workspaces
  • /system/directory/workspaces/{workspace}
  • /system/directory/tenants
  • /system/directory/tenants/{tenant}
  • /system/security/access-logs
  • /system/ops/runs/{run}
  • /system/repair-workspace-owners
  • any local/testing-only system smoke helper added or documented by the implementation
• Data Ownership: No new persisted data. Existing PlatformUser, OperationRun, Workspace, ManagedEnvironment, OperationalControlActivation, and AuditLog truth remains authoritative.
• RBAC: /system remains platform-plane only. Tenant/admin web users must receive deny-as-not-found behavior for system routes. Platform users without required capabilities receive 403. Smoke users must be deterministic PlatformUser fixtures with explicit capabilities.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Tenant/admin context must not apply to /system. System pages remain platform-plane and tenantless unless a system detail page intentionally displays workspace/environment context.
• Explicit entitlement checks preventing cross-tenant leakage: System routes must use the platform guard and existing PlatformCapabilities; smoke helpers must not authenticate tenant users into /system.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

• Compatibility posture: canonical replacement.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no.
• Why clean replacement is safe now: No production deployment or customer data compatibility requirement exists for unfinished /system branding or smoke assumptions.

Implementation must not preserve:

• visible Laravel/default framework branding as product copy,
• old standalone Dashboard, Admin, Panel, OK, Warn, Healthy, or Warning labels where they are top-level system product states,
• old tests that assert unfinished branding,
• production-like smoke-login access,
• ambiguous system-health labels that conflict with the Product Surface Contract.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

Dangerous action changed means touched high-impact system actions must be reviewed for separation, confirmation, authorization, and audit behavior. This spec does not add new destructive actions. A local/testing-only smoke helper may be added only if existing Pest Browser platform-guard fixtures cannot satisfy the focused smoke and manual review need; it is tooling, not product navigation.

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

• Route/page/surface: /system, /system/login, /system/ops/runs, /system/ops/runs/{run}, /system/ops/failures, /system/ops/stuck, /system/ops/runbooks, /system/ops/controls, /system/directory/workspaces, /system/directory/workspaces/{workspace}, /system/directory/tenants, /system/directory/tenants/{tenant}, /system/security/access-logs, /system/repair-workspace-owners.
• Current or new page archetype: System Admin for dashboard/repair/directory/security/access-log surfaces; Technical Annex for operation detail/runbooks/diagnostics where technical detail is the point.
• Design depth: Internal/System Admin productization pass; no strategic redesign.
• Repo-truth level: repo-verified.
• Existing pattern reused: Filament v5 panel provider/pages/widgets/actions, PlatformUser + PlatformCapabilities, UseSystemSessionCookie, SuppressDebugbarForSmokeRequests, BadgeCatalog/BadgeRenderer, Spec 376 platform-guard browser smoke pattern, existing System Spec 113/114 tests.
• New pattern required: none by default. A system local/testing smoke helper is allowed only as a narrow fixture if platform-guard Pest Browser is insufficient for the selected proof path.
• Screenshot required: yes, focused /system desktop smoke screenshot at minimum; mobile screenshot only if the changed surface is layout-sensitive.
• Page audit required: no full audit. Focused smoke plus Human Product Sanity is sufficient.
• Customer-safe review required: no customer-facing surface changes.
• Dangerous-action review required: yes for touched break-glass and operational-control actions; no new destructive action is allowed.
• Coverage files to update during implementation or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md (implementation task)
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md (implementation task)
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - full page reports and strategic-surface artifacts are not required; active spec plus focused browser proof provide proportional coverage
• No-impact rationale when applicable: N/A.

Product Surface Impact (mandatory for UI-affecting specs)

Reference: docs/product/standards/product-surface-contract.md.

• Product Surface Contract applies?: yes. /system is a reachable product/admin surface.
• Page archetype: System Admin for /system; Technical Annex for system operations diagnostics/detail surfaces where technical proof is the product value.
• Primary user question: What is the platform/system state and what needs system-operator attention?
• Primary action: Navigate to the relevant system operation, repair, or control surface; no new dominant action is introduced.
• Surface budget result: pass by System Admin/Technical Annex classification, with visible complexity required to stay neutral or decrease.
• Technical Annex / deep-link demotion: Raw IDs and OperationRun links may remain in system operations where that is the Technical Annex purpose, but they must not become default branding or dashboard hero content. Debugbar, Vite overlays, exception pages, stack traces, and framework branding must not appear in focused smoke.
• Canonical status vocabulary: Map existing top-level system states without creating a new status family: ok, healthy, and All systems healthy -> Ready; warn, warning, Degraded, and ambiguous attention states -> Needs attention; critical remains Critical; execution-specific operation states may use Blocked, Running, or Failed only where they already represent OperationRun/control truth; unknown remains Unknown. Current OK, Warn, Healthy, Warning, and All systems healthy labels are in scope for replacement or explicit technical-detail confinement.
• Visible complexity impact: neutral or decreased.
• Product Surface exceptions: none. System Admin and Technical Annex allowances are classifications, not compatibility exceptions.

Browser Verification Plan (mandatory)

• Browser proof required?: yes.
• No-browser rationale: N/A.
• Focused path when required:
  • /system
  • /system/ops/runs
  • at least one system operations/security/repair page selected from current accessible routes
  • /system/login or local/testing smoke helper safety path as appropriate
  • a basic /admin route smoke if shared panel/provider branding changes
• Primary interaction to execute: authenticate as a deterministic platform user, load dashboard, verify navigation/sidebar/branding/status labels, open operations and one security/repair/control page, verify no debug/runtime leaks.
• Console, Livewire, Filament, network, and 500-error checks: required for focused browser smoke.
• Full-suite failure triage: Full browser suite failures are non-blocking only when focused /system and affected /admin proof is green, unrelated failures are listed, and no failure indicates system auth/navigation/debug leak regression.

Human Product Sanity Check (mandatory)

• Required?: yes.
• No-human-sanity rationale: N/A.
• Reviewer questions: Does /system feel like TenantPilot, not Laravel/Filament scaffolding? Are page titles/navigation clear? Are system statuses canonical? Are technical details intentional? Are destructive/high-impact actions separated? Are debug/dev artifacts absent? Did visible complexity stay neutral or decrease?
• Planned result location: specs/396-system-panel-branding/implementation-report.md.

Product Surface Merge Gate Checklist (mandatory)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed.
• Browser proof is completed for focused /system paths.
• Human Product Sanity is completed.
• Product Surface exceptions are documented as none or explicitly listed.
• Implementation report states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): branding, status messaging, navigation labels, auth/session smoke fixture, browser smoke, debug/runtime leak prevention, high-impact system action review.
• Systems touched: SystemPanelProvider, system pages/widgets/views, localization files, BadgeCatalog/SystemHealth mapper, smoke middleware/routes/tests, browser tests.
• Existing pattern(s) to extend: Filament panel provider branding, localization keys, BadgeCatalog / BadgeRenderer, Spec 376 browser actingAs(..., 'platform'), existing admin smoke-login safety model, SuppressDebugbarForSmokeRequests.
• Shared contract / presenter / builder / renderer to reuse: BadgeCatalog / BadgeRenderer for status-like badges; existing Filament actions and PlatformCapabilities for system actions.
• Why the existing shared path is sufficient or insufficient: Existing badge and panel patterns are sufficient for labels/status. Existing Pest Browser platform-guard auth is sufficient for automated browser proof; a separate local/testing route is only allowed if manual in-app smoke cannot otherwise be made deterministic.
• Allowed deviation and why: Local/testing-only system smoke helper, if needed, with environment guard, platform guard semantics, redirect safety, and no product navigation.
• Consistency impact: System status labels must align with Product Surface Contract vocabulary while preserving internal diagnostic detail when intentionally technical.
• Review focus: Verify no production auth weakening, no ad hoc badge/status mapping outside central badge paths, no UI expansion, no completed-spec rewrite.

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: Existing system operation pages may display OperationRun rows; this spec must not create, queue, deduplicate, resume, block, complete, or alter OperationRun start UX.
• 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 shared provider seam changes are planned.
• Boundary classification: platform-core for /system panel/auth/smoke; provider-owned diagnostics remain untouched if present on system pages.
• Seams affected: platform panel provider, platform auth/session, system status vocabulary, smoke fixture.
• Neutral platform terms preserved or introduced: system panel, platform operator, platform operations, workspace, managed environment, provider diagnostics.
• Provider-specific semantics retained and why: Existing provider diagnostics may remain technical details where they are already provider-owned; no new provider semantics are introduced.
• Why this does not deepen provider coupling accidentally: The spec forbids new Graph calls, provider framework changes, and provider feature work.
• Follow-up path: Provider readiness/onboarding productization remains a separate manual candidate.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
System panel branding/title	yes	Native Filament panel/provider/localization	navigation/branding	shell, page	no	canonical TenantPilot System naming
System dashboard status labels	yes	Native widgets plus shared badge semantics	status messaging	page, widget	no	map top-level states to canonical labels
System operations labels/empty states	yes	Native Filament table/page	operations registry	page, table	no	productize without changing behavior
System smoke auth/config	no product navigation	existing test/smoke fixture patterns	auth/session/browser smoke	route, session	no if local/test-only	tooling only
Debug/runtime leak checks	no product UI addition	middleware/browser assertions	smoke stability	request/session/browser	no	proof path only
Touched high-impact actions	yes if labels or placement touched	Filament Actions	action hierarchy	page/action	no new action	confirm existing confirmation/authorization/audit

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
/system dashboard	Secondary Context Surface / System Admin	Platform operator checks system state	TenantPilot System branding, one top-level status, attention counts	operations/detail pages	Not a customer decision page; it orients platform support	platform operations	removes scaffold/default ambiguity
/system/ops/runs	Tertiary Evidence / Diagnostics	Platform operator inspects run truth	run status/outcome, operation label, scope	run detail	Technical Annex style registry	system operations	keeps proof in one place
/system/ops/controls	System Admin / Controls	Platform operator pauses/resumes high-impact controls	control state, scope, confirmation	audit/history modal	high-impact platform controls	operational control	makes dangerous actions intentional
/system/login	System Admin auth surface	Platform operator signs in	TenantPilot System login context	N/A	required entry point	platform auth	avoids framework login feel

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
/system dashboard	support-platform	system state, items needing attention	operation widgets and status summaries	raw debug/runtime artifacts forbidden	inspect relevant system area	debug/runtime overlays, stack traces	one top-level system status
/system/ops/runs	support-platform	run list state	run status/outcome/type/scope	run detail and logs where already authorized	open run detail	unrelated product data	status/outcome remain separate
/system/ops/controls	support-platform	control state and impact	activation history	audit trail where authorized	pause/resume selected control	raw audit detail unless requested	effective state shown once

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
/system dashboard	Utility / System	System Admin Dashboard	Open attention area	page widgets/actions	N/A	header/nav/body links	confirmed actions only	/system	/system	System plane	TenantPilot System	system state and attention	none
/system/ops/runs	List / Table / Bulk	Monitoring / Queue / Technical Annex	Inspect operation	clickable row	required/current	header action to runbooks	none on list	/system/ops/runs	/system/ops/runs/{run}	System plane + row scope	Platform Operations	run status/outcome/type	System Admin technical allowance
/system/ops/controls	Utility / System	Settings / Operational Control	Pause/resume control	explicit action cards	N/A	history actions secondary	separated confirmed actions	/system/ops/controls	N/A	System/workspace scope	Operational Controls	effective state and scope	none
/system/login	Auth	System Admin Login	Sign in	form submit	N/A	N/A	N/A	/system/login	N/A	System plane	TenantPilot System	platform auth context	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
/system dashboard	Platform operator	decide where platform attention is needed	System Admin	Is the platform ready or does it need attention?	TenantPilot branding, status, attention widgets	run detail, raw diagnostics	readiness, operation outcome	TenantPilot system only	open relevant system area	break-glass enter/exit if enabled
/system/ops/runs	Platform operator	inspect platform operations	Technical Annex list	Which system runs need inspection?	run state, outcome, operation, scope	run detail/logs	execution status/outcome/freshness	TenantPilot system only	open run	none
/system/ops/controls	Platform operator	pause/resume high-impact controls	Settings/System Admin	Which control is enabled or paused?	effective control state and scope	activation/audit history	control lifecycle	TenantPilot system only	pause/resume with confirmation	pause/resume controls

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no database entity. The later implementation may create specs/396-system-panel-branding/implementation-report.md and screenshot artifacts as spec-local evidence only.
• New abstraction?: no by default. A local/testing-only smoke helper must remain a route/test fixture, not a product abstraction.
• New enum/state/reason family?: no. Existing system health/status values must map to canonical labels; do not create a new status family.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Platform operators and reviewers cannot rely on a productized, manually smokeable /system surface that is free of scaffold labels and debug/runtime leaks.
• Existing structure is insufficient because: Existing automated browser proof is separate from manual in-app review, and visible system labels still use ambiguous health/scaffold vocabulary.
• Narrowest correct implementation: Rename/relabel/map existing surfaces and smoke paths; reuse existing platform auth, badges, localization, smoke suppression, and browser tests.
• Ownership cost: Focused tests, one browser smoke family, and possible local/testing smoke helper upkeep.
• Alternative intentionally rejected: Broad /system redesign or a new system readiness model would add UI and semantic complexity without current operator need.
• Release truth: Current-release productization follow-up.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, old labels, smoke aliases, and transitional UI are out of scope.

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

• Test purpose / classification: Unit for badge/status mapping where changed, Feature for system auth/branding/smoke route safety, Browser for focused /system productization smoke.
• Validation lane(s): fast-feedback, confidence, browser.
• Why this classification and these lanes are sufficient: The feature changes rendered system UI labels and smoke/runtime proof, so unit/feature tests prove mappings/auth safety and browser tests prove actual rendered behavior/no leaks.
• New or expanded test families: one bounded Spec396 browser smoke and focused feature tests under existing System/Auth/Badges areas.
• Fixture / helper cost impact: deterministic PlatformUser fixture with PlatformCapabilities::ACCESS_SYSTEM_PANEL, CONSOLE_VIEW, OPERATIONS_VIEW, and relevant security/repair/control capabilities. Any smoke helper must remain opt-in and local/testing-only.
• Heavy-family visibility / justification: Browser coverage is explicit because the feature is smoke/productization-focused.
• Special surface test profile: System Admin / Technical Annex / browser-smoke-stability.
• Standard-native relief or required special coverage: Existing native Filament surfaces only; special proof is browser smoke and high-impact action review.
• Reviewer handoff: Confirm label/status replacements, no production smoke route, no tenant user can access /system, no debugbar/Vite/exception leak, no /admin regression if shared panel config changes.
• Budget / baseline / trend impact: bounded browser-lane addition; record runtime if material.
• Escalation needed: document-in-feature.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • git diff --check
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=SystemHealthBadgeSemanticsTest
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=SystemPanelAuthTest
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec396
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec396SystemPanelProductizationSmokeTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=AdminSmoke if shared panel/provider branding changed
  • cd apps/platform && ./vendor/bin/sail pint --dirty

User Scenarios & Testing (mandatory)

User Story 1 - System Panel Reads As TenantPilot (Priority: P1)

As a platform operator, I want /system login, dashboard, navigation, and page titles to clearly identify TenantPilot System, so I can trust that I am in the platform-admin surface and not a framework scaffold.

Why this priority: Branding/title trust is the core productization gap.

Independent Test: Sign in as a platform user and open /system; the rendered page title/heading/branding includes TenantPilot System or equivalent and does not show standalone Laravel/Filament/default scaffold branding.

Acceptance Scenarios:

1. Given an authorized platform user, When /system loads, Then TenantPilot system branding is visible in the panel, page title, or heading.
2. Given /system/login renders, When the login page is inspected, Then the system auth context is TenantPilot-specific.
3. Given system navigation renders, When labels are scanned, Then labels describe system workflows such as System Overview, Platform Operations, Repair Tools, Provider Diagnostics, System Settings, or equivalent productized names.

User Story 2 - System Status Vocabulary Is Canonical (Priority: P1)

As a platform operator, I want system-level status labels to use TenantPilot canonical vocabulary, so I do not have to interpret Healthy, OK, Warn, or Warning as separate product truths.

Why this priority: Product Surface Contract status vocabulary is mandatory and current repo anchors show divergent system-health labels.

Independent Test: Badge/status tests and focused dashboard assertions show top-level system states as Ready, Needs attention, Failed/Blocked, Unknown, or another allowed canonical state.

Acceptance Scenarios:

1. Given no failed or stuck runs, When the system dashboard health widget renders, Then the top-level state reads Ready or equivalent canonical wording, not All systems healthy.
2. Given failed or stuck system operations exist, When the health widget renders, Then the top-level state reads Needs attention, Failed, or Blocked according to current behavior, not Warning, Warn, or Degraded.
3. Given BadgeDomain::SystemHealth renders existing ok or warn values, When badge mapping is tested, Then labels use canonical vocabulary without creating a new badge domain.

User Story 3 - Focused System Smoke Is Deterministic And Debug-Safe (Priority: P1)

As a maintainer, I want a deterministic focused /system smoke that works with platform-plane auth and checks for debug/runtime leaks, so productization proof is repeatable.

Why this priority: Spec 377 left manual in-app /system access as the remaining follow-up, and the provided candidate specifically targets smoke config.

Independent Test: A focused browser test authenticates a deterministic platform user, visits /system, /system/ops/runs, and one security/repair/control page, and asserts no debugbar, Vite overlay, exception page, console error, Livewire error, or Filament runtime error.

Acceptance Scenarios:

1. Given a local/testing platform smoke user, When focused smoke opens /system, Then the dashboard loads with TenantPilot system branding and no debug/runtime leak.
2. Given the same smoke user, When focused smoke opens /system/ops/runs, Then the operations page loads or shows a productized empty state without JS/console errors.
3. Given a smoke-login/helper route is added or reused, When the route is requested outside local/testing, Then it returns 404 and does not authenticate any actor.
4. Given an ordinary tenant/admin user, When they request /system or a system smoke helper, Then they cannot access the system panel.

User Story 4 - High-Impact System Actions Stay Safe (Priority: P2)

As a platform operator, I want touched high-impact system actions to stay clearly separated, confirmed, authorized, and audited, so productization work does not make risky system controls casual.

Why this priority: The candidate mentions break-glass, repair, operational maintenance, and destructive/high-impact safety.

Independent Test: Existing or updated Feature/Livewire tests show touched break-glass and operational-control actions still use ->action(...), ->requiresConfirmation(), platform capability checks, and audit logging where they mutate state.

Acceptance Scenarios:

1. Given a high-impact system action is touched for copy/productization, When action tests run, Then confirmation and authorization behavior still pass.
2. Given a platform user lacks the required capability, When they open the touched surface or execute the action, Then access is denied according to existing 403/404 semantics.
3. Given the action mutates state, When it succeeds, Then existing audit truth remains intact.

Requirements (mandatory)

Functional Requirements

• FR-396-001: The system panel MUST use TenantPilot-specific branding in visible system panel context, page title, heading, or login title.
• FR-396-002: The system dashboard title MUST be productized as TenantPilot System, TenantPilot System Dashboard, System Overview, or equivalent TenantPilot system language.
• FR-396-003: System navigation labels and page titles MUST describe workflows or system areas rather than framework/resource scaffolding.
• FR-396-004: Standalone visible Laravel, Filament, Laravel Application, Admin, Panel, and ambiguous standalone Dashboard MUST NOT appear as primary product branding in the focused /system smoke path.
• FR-396-005: Top-level system status vocabulary MUST map ambiguous existing labels (OK, Warn, Healthy, Warning, Degraded, All systems healthy) to Product Surface Contract canonical labels or confine them to clearly technical detail where justified.
• FR-396-006: BadgeDomain::SystemHealth MUST remain the central path for system-health badges; implementation MUST NOT add page-local status mappings for the same values.
• FR-396-007: Focused /system smoke MUST authenticate a deterministic PlatformUser with explicit platform capabilities and MUST NOT authenticate ordinary tenant/admin users into /system.
• FR-396-008: Any local/testing-only system smoke helper MUST be disabled outside local and testing, return 404 in production-like environments, validate redirects to local app paths, set debugbar-suppression context if needed, and be absent from product navigation.
• FR-396-009: Focused browser smoke MUST cover /system, /system/ops/runs, and at least one current system security/repair/control page when the current actor has capability.
• FR-396-010: Focused browser smoke MUST assert no debugbar UI, no Vite/dev overlay, no Laravel exception/debug page, no obvious Livewire/Filament runtime error, and no console errors where the harness supports it.
• FR-396-011: If shared panel/provider branding is changed, focused /admin smoke MUST confirm the admin panel did not regress.
• FR-396-012: Touched high-impact system actions MUST keep confirmation, platform capability authorization, and audit behavior where they mutate state.
• FR-396-013: The implementation MUST NOT add new system cards, metrics, tables, navigation groups, OperationRun types, provider features, Graph calls, migrations, models, or product runtime behavior beyond the productization/smoke scope.
• FR-396-014: Generated browser screenshots, failure snapshots, debug HTML, and temporary artifacts MUST be cleaned or intentionally retained under this spec package with an implementation-report note.
• FR-396-015: The implementation report MUST include files changed, branding/title/navigation changes, smoke route/config safety verification, status vocabulary changes, tests, browser smokes, /admin regression status when applicable, debug/runtime leak result, visible complexity outcome, and no completed-spec rewrite assertion.

Non-Functional Requirements

• NFR-396-001: Visible complexity on /system MUST remain neutral or decrease.
• NFR-396-002: Smoke setup MUST be deterministic, local/test-only, and independent of external provider APIs, queue workers, scheduled jobs, or live network calls.
• NFR-396-003: Tests MUST avoid brittle broad string scans over vendor code or historical specs; assertions should target rendered system UI/config and changed application paths.
• NFR-396-004: Any new smoke helper must be narrowly named and documented as smoke-only, not a compatibility login path.
• NFR-396-005: Runtime labels should use existing localization structure where visible copy already lives in localization.

RBAC / Security Requirements

• SEC-396-001: Customer/workspace/admin users authenticated on web MUST NOT access /system and must continue receiving deny-as-not-found where existing tests require it.
• SEC-396-002: Platform users without required capabilities MUST receive 403 for system pages/actions according to existing semantics.
• SEC-396-003: Smoke users must be deterministic PlatformUser records with explicit platform capabilities.
• SEC-396-004: Smoke helpers must not bypass environment guards, platform guard separation, CSRF/session safety expectations, or capability checks for product pages.
• SEC-396-005: No secrets, credentials, raw token payloads, or provider secrets may appear in screenshots, logs, smoke artifacts, or implementation reports.

Auditability / Observability Requirements

• AUD-396-001: Touched state-changing system actions must retain existing audit logging.
• AUD-396-002: Browser smoke and human sanity results must be recorded in specs/396-system-panel-branding/implementation-report.md.
• AUD-396-003: The implementation report must distinguish execution truth, rendered UI truth, smoke/auth truth, debug/runtime leak truth, and known unrelated browser-suite failures.

Data / Truth Source Requirements

• DATA-396-001: No new database truth is introduced.
• DATA-396-002: System status truth remains derived from existing OperationRun, customer-health, control, or badge sources.
• DATA-396-003: Productized labels are presentation truth only and must not create a new status family.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
System Dashboard	apps/platform/app/Filament/System/Pages/Dashboard.php	Time window, break-glass enter/exit if enabled	N/A	N/A	N/A	N/A	N/A	N/A	yes for break-glass	no new action; verify confirmation/authorization
System Operations	apps/platform/app/Filament/System/Pages/Ops/Runs.php	Go to runbooks	clickable row to detail	none	none	Go to runbooks	detail page owns actions	N/A	N/A	existing technical-annex list
Operational Controls	apps/platform/app/Filament/System/Pages/Ops/Controls.php	pause/resume/history actions	N/A	N/A	N/A	N/A	N/A	N/A	yes for mutations	verify confirmation/authorization/audit if touched
System Login	apps/platform/app/Filament/System/Pages/Auth/Login.php	N/A	N/A	N/A	N/A	N/A	N/A	login submit	audit login attempts	productize branding only

Key Entities (include if feature involves data)

• PlatformUser: Existing platform-plane actor used for /system auth and smoke fixtures.
• PlatformCapabilities: Existing platform capability registry used for system access, operations, controls, directory, and repair pages.
• OperationRun: Existing operation truth displayed on system operations pages; not changed by this spec.
• SystemHealth badge state: Existing badge-domain mapping that must use canonical labels without creating a new status family.
• Smoke context: Local/testing-only request/session/cookie context used to suppress debugbar and make focused browser smoke deterministic.

Success Criteria (mandatory)

Measurable Outcomes

• SC-396-001: Focused /system browser smoke renders TenantPilot system branding on /system and no primary Laravel/Filament/default framework branding.
• SC-396-002: Focused /system browser smoke opens /system/ops/runs and one security/repair/control page without 500, Livewire, Filament, console, debugbar, Vite overlay, or exception-page leaks.
• SC-396-003: System health badge/status tests prove existing ok and warn states display canonical labels.
• SC-396-004: Feature/auth tests prove any system smoke helper is local/testing-only and unavailable in production-like environments, or the implementation report states that no helper was added.
• SC-396-005: Existing /system tenant-session deny-as-not-found and platform-missing-capability forbidden tests continue to pass.
• SC-396-006: No new UI cards, metrics, tables, navigation groups, migrations, models, Graph calls, or system features are introduced.
• SC-396-007: The implementation report confirms visible complexity stayed neutral or decreased and no completed specs were rewritten.

Out Of Scope

• New system-admin product capabilities.
• Full /system IA redesign.
• New system dashboard widgets, metrics, status models, or readiness framework.
• New provider diagnostics feature or provider onboarding productization.
• Graph contract changes or Graph calls.
• Migrations, models, jobs, OperationRun types, schedulers, or queues.
• Customer-facing surfaces.
• Reopening completed Specs 376, 377, 391, or 395.
• Broad browser-suite stabilization beyond focused /system proof.

Risks

• Shared Filament branding affects /admin: Mitigate with focused /admin smoke if shared provider/config changes.
• Smoke helper weakens auth: Mitigate with local/testing environment guard, platform guard only, route tests, and no product navigation.
• Status label changes break existing tests: Mitigate by updating tests to canonical vocabulary and avoiding vendor/historical-doc scans.
• System panel loses useful technical detail: Mitigate by keeping Technical Annex pages intentionally technical while removing scaffold/default/debug labels from product surfaces.
• Browser suite remains noisy: Mitigate by making focused /system smoke blocking and documenting unrelated full-suite failures separately.

Assumptions

• Current branch 396-system-panel-branding is created by the repository Spec Kit script from clean platform-dev.
• The implementation will use Laravel Sail for PHP/Pest/Pint commands.
• Existing Spec 376 browser platform-guard fixture is usable unless implementation proves manual smoke needs a local/testing helper.
• The system panel remains platform-plane only and separate from /admin.
• Productized labels can be adjusted through existing localization, panel provider, widget, and badge mapper paths.

Open Questions

• None blocking preparation.
• Non-blocking implementation decision: use existing Pest Browser actingAs(..., 'platform') only, or add a local/testing-only system smoke helper if manual in-app product sanity requires one.

Follow-Up Spec Candidates

• Manual system-panel audit procedure documentation if implementation chooses automated platform-guard proof only and product wants a manual support runbook later.
• Provider readiness/onboarding productization if current operator evidence shows provider diagnostics still feel unfinished.
• Cross-domain indicator runtime follow-through if status vocabulary drift remains outside /system.