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

Implementation Plan: Spec 396 - System Panel Branding and Productization Smoke Config v1

Branch: 396-system-panel-branding | Date: 2026-06-21 | Spec: spec.md Input: Feature specification from /specs/396-system-panel-branding/spec.md

Summary

Productize the existing /system Filament panel so platform operators and reviewers see TenantPilot-branded system surfaces, canonical status labels, and deterministic focused browser proof. The implementation must stay narrow: update existing system panel configuration, labels, status vocabulary, and smoke/debug suppression only where required. It must not add system features, persisted entities, Graph calls, migrations, new dashboards, or broad Product Surface Contract enforcement.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Laravel Sail 1.x, Pest 4.3.1, Tailwind CSS 4.2.2 Storage: PostgreSQL is the application database; this spec requires no schema or storage change Testing: Pest feature tests, Filament/Livewire action tests where touched, Pest Browser focused smoke, Pint for formatting Validation Lanes: fast-feedback for label/status/auth tests, confidence for focused system browser smoke, no broad full-browser-suite gate unless implementation touches shared panel/provider behavior Target Platform: apps/platform Laravel application deployed as containerized Dokploy staging/production runtime Project Type: Laravel monolith with Filament admin and system panels plus standalone website outside this scope Performance Goals: No new query-heavy widgets or polling; smoke/helper changes must not add user-visible latency Constraints: No migrations, models, Graph calls, jobs, queues, schedulers, provider framework changes, broad IA redesign, or production smoke-login bypass Scale/Scope: Existing /system panel routes only; focused proof of /system, /system/ops/runs, and one security/repair/control page

UI / Surface Guardrail Plan

• Guardrail scope: Changed operator-facing system panel surfaces and workflow-only browser-smoke guardrail.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • /system
  • /system/login
  • /system/ops/runs
  • /system/ops/failures
  • /system/ops/stuck
  • /system/ops/runbooks
  • /system/ops/controls
  • /system/ops/runs/{run}
  • /system/directory/workspaces
  • /system/directory/workspaces/{workspace}
  • /system/directory/tenants
  • /system/directory/tenants/{tenant}
  • /system/security/access-logs
  • /system/repair-workspace-owners
  • apps/platform/app/Providers/Filament/SystemPanelProvider.php
  • apps/platform/app/Filament/System/Pages/**
  • apps/platform/app/Filament/System/Widgets/**
  • apps/platform/app/Support/Badges/Domains/SystemHealthBadge.php
• No-impact class, if applicable: N/A because visible labels and smoke proof are in scope.
• Native vs custom classification summary: Native Filament pages, panels, widgets, notifications, and actions. Smoke helper, if required, must be a local/testing-only route helper, not a product UI surface.
• Shared-family relevance: Badge/status vocabulary and system smoke/debug-suppression pattern.
• State layers in scope: Shell, page, detail, navigation, and local/testing smoke request context.
• Audience modes in scope: Support-platform/system operator only.
• Decision/diagnostic/raw hierarchy plan: Keep /system intentionally technical, but make top-level labels decision-first; keep diagnostics and raw details in their existing technical pages.
• Raw/support gating plan: Capability-gated platform panel remains required; no tenant session access.
• One-primary-action / duplicate-truth control: Preserve existing page actions; do not add duplicate CTA cards or new dashboards.
• Handling modes by drift class or surface: Existing product-surface drift on system branding/status copy is review-mandatory and fixed within this feature. Unrelated full-suite browser noise is report-only unless directly caused by this spec.
• Repository-signal treatment: Existing Spec 376/377/395 evidence is context only; completed specs are not rewritten.
• Special surface test profiles: Technical Annex, system-admin surface, focused browser smoke, native Filament panel.
• Required tests or manual smoke: Feature/status/auth tests, action posture verification for any touched high-impact actions, focused Pest Browser smoke, human product sanity on the system panel.
• Exception path and spread control: None planned. Any local/testing-only helper is explicitly not a Product Surface exception if hidden from production navigation and guarded by environment.
• Active feature PR close-out entry: Must report Product Surface Impact, UI Surface Impact, no-legacy posture, browser proof, human sanity result, Livewire v4, provider registration, global search, destructive/high-impact actions, asset strategy, and deployment impact.
• UI/Productization coverage decision: Durable coverage registry artifacts plus this active spec and implementation report must be updated.
• Coverage artifacts to update: docs/ui-ux-enterprise-audit/route-inventory.md, docs/ui-ux-enterprise-audit/design-coverage-matrix.md, and specs/396-system-panel-branding/implementation-report.md during implementation.
• No-impact rationale: N/A.
• Navigation / Filament provider-panel handling: Provider-panel handling is in scope; registration location must remain apps/platform/bootstrap/providers.php.
• Screenshot or page-report need: Focused browser proof and screenshots/log evidence are required because this is a visible productization spec.

Product Surface Contract Plan

• Product Surface Contract reference: docs/product/standards/product-surface-contract.md reviewed before preparation.
• No-legacy posture: Canonical replacement. Old scaffold/default labels are not preserved as compatibility aliases in active UI.
• Page archetype and surface budget plan: System Admin / Technical Annex. The budget is existing system panel surfaces only; no new cards, metrics, navigation groups, or workflows.
• Technical Annex and deep-link demotion plan: Existing operations, repair, control, runbook, failure, and stuck-run pages may remain technical. Raw IDs/source keys/payloads stay in existing detail/technical views and are not promoted onto primary system dashboard copy.
• Canonical status vocabulary plan:
  • ok, healthy equivalents, and All systems healthy: Ready
  • warn, warning equivalents, Degraded, and ambiguous attention states: Needs attention
  • critical: Critical
  • operation/control execution states: preserve existing Blocked, Running, or Failed wording only where they already represent OperationRun/control truth
  • unknown: Unknown
  • Do not introduce a new status family; map existing states to canonical presentation labels.
• Product Surface exceptions: None.
• Browser verification plan: Focused platform-guard browser smoke for /system, /system/ops/runs, and one security/repair/control page; assert no debugbar, Vite overlay, exception page, Livewire/Filament console/runtime errors, or default framework branding.
• Human Product Sanity plan: Review /system and /system/ops/runs as a platform operator and record whether visible complexity stayed neutral or decreased.
• Visible complexity outcome target: Neutral or decreased.
• Implementation report target: specs/396-system-panel-branding/implementation-report.md.

Filament / Livewire / Deployment Posture

• Livewire v4 compliance: Livewire 4.1.4 confirmed; no Livewire v3 APIs or references allowed.
• Panel provider registration location: Existing Laravel provider registration remains apps/platform/bootstrap/providers.php; no provider registration change is planned.
• Global search posture: No Filament Resource or global-search behavior is changed. If implementation unexpectedly touches a globally searchable resource, it must either have Edit/View page support or disable global search.
• Destructive/high-impact action posture: No new destructive action is planned. Existing break-glass and operational-control actions must retain ->action(...), ->requiresConfirmation(), platform capability checks, and audit logging if touched.
• Asset strategy: No new assets by default. Existing panel-only theme asset remains the strategy. php artisan filament:assets is not newly required unless implementation registers or changes Filament assets.
• Testing plan: Cover status/badge vocabulary, system panel auth/smoke safety, touched high-impact actions, and focused browser smoke through Pest/Pest Browser.
• Deployment impact: No env vars, migrations, queues, schedulers, storage, workers, Graph scopes, or Dokploy runtime changes planned.

Shared Pattern & System Fit

• Cross-cutting feature marker: Yes, because status vocabulary and smoke/debug suppression are shared patterns.
• Systems touched:
  • Filament system panel provider.
  • System pages and widgets.
  • Badge/status rendering.
  • Local/testing browser smoke support if required.
  • Platform auth/capability tests.
• Shared abstractions reused:
  • SystemHealthBadge / badge-rendering patterns.
  • Existing platform guard and capability policies.
  • Existing smoke/debug-suppression middleware where possible.
  • Existing localization files.
• New abstraction introduced? why?: None approved. A local/testing helper route is allowed only if existing Pest Browser platform guard is insufficient for manual in-app proof.
• Why the existing abstraction was sufficient or insufficient: Existing panel/pages/widgets already own the visible surfaces; existing badge and localization layers can carry the label changes. Existing browser test evidence proves platform-guard access, so any new smoke helper must justify itself as manual proof support only.
• Bounded deviation / spread control: Any smoke helper must be environment-gated, unlinked, platform-guarded, and covered by route safety tests.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: No.
• Central contract reused: N/A.
• Monitoring/deduplication semantics preserved: Yes. This spec only productizes visible system surfaces and smoke proof.
• User-facing run state copy changed?: Only if existing system status labels on operations pages use scaffold/default copy; no OperationRun status semantics change is approved.
• Required tests: Existing OperationRun authorization/listing tests continue to pass; no new run lifecycle tests unless implementation touches operation actions.

Provider Boundary Impact

• Touches Graph/provider identity or contract boundary?: No.
• Provider-specific semantics introduced into platform-core?: No.
• Governed-subject taxonomy affected?: No.
• Cross-provider readiness or compare strategy affected?: No.
• Contract fixtures required?: No.
• Boundary note: This is a system-panel productization and smoke-proof feature, not a provider-readiness or Graph-contract feature.

Constitution Check

GATE: Must pass before implementation. Re-check after implementation design.

• SPEC-GATE-001: Passed. Candidate scored 10/12 and is direct user-provided P2 follow-up.
• Product Surface Contract Gate: Passed for preparation. The spec states no-legacy posture, Product Surface Impact, UI Surface Impact, archetype, surface budget, Technical Annex stance, canonical status vocabulary, exception posture, browser proof, human sanity target, and implementation-report fields.
• Completed-spec guardrail: Passed. Specs 376, 377, 391, and 395 are context only and not reopened.
• BLOAT-001: Passed. No new persisted entity, enum/status family, taxonomy/framework, provider abstraction, or cross-domain UI framework is approved.
• RBAC/Audit: Passed. Platform guard and capability enforcement remain required. High-impact actions retain confirmation, authorization, and audit.
• Data isolation: Passed. No tenant/customer data model change.
• Test governance: Passed. Tasks require focused feature/action/browser tests before implementation close-out.
• Deployment safety: Passed. No runtime infrastructure change planned.

Test Governance

• Tests to add/update:
  • Status/badge vocabulary tests for canonical system labels.
  • System panel auth/smoke helper safety tests if a helper is added.
  • Focused Pest Browser smoke for /system, /system/ops/runs, and one system security/repair/control page.
  • Action posture tests or reflection assertions if high-impact actions are touched.
  • /admin regression smoke only if a shared provider/config change can affect the tenant admin panel.
• Commands expected during implementation:
  • 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 pint --dirty
  • Browser command to follow the repo's Pest Browser setup for focused Spec 396 proof.
• No verification scripts: Do not add ad hoc verification scripts when Pest/Pest Browser tests can prove the behavior.

Project Structure

Documentation (this feature)

specs/396-system-panel-branding/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── implementation-report.md   # created during implementation

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   └── System/
│   │       ├── Pages/
│   │       │   ├── Auth/Login.php
│   │       │   ├── Dashboard.php
│   │       │   ├── Directory/
│   │       │   ├── Ops/
│   │       │   ├── RepairWorkspaceOwners.php
│   │       │   └── Security/
│   │       └── Widgets/
│   ├── Http/Middleware/SuppressDebugbarForSmokeRequests.php
│   ├── Providers/Filament/SystemPanelProvider.php
│   └── Support/Badges/Domains/SystemHealthBadge.php
├── lang/
│   ├── de/localization.php
│   └── en/localization.php
├── routes/web.php
└── tests/
    ├── Browser/
    └── Feature/

Structure Decision: Use existing apps/platform Filament, localization, badge, route, middleware, and Pest/Pest Browser structure. No new base folders are approved.

Complexity Tracking

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

Proportionality Review

• Current operator problem: /system can still expose default/scaffold-like branding and inconsistent health labels, and focused manual browser smoke is not deterministic enough for productization review.
• Existing structure is insufficient because: Labels and smoke proof are spread across provider config, localization, widgets, badge mapping, and existing browser fixtures. They need coordinated preparation, but not new product infrastructure.
• Narrowest correct implementation: Update existing copy/mapping/config/tests and add only focused smoke support if existing platform-guard browser proof cannot serve manual sanity.
• Ownership cost created: A few focused tests and an implementation report. No schema, model, enum family, provider contract, or new UI framework cost.
• Alternative intentionally rejected: Full /system redesign or new system dashboard cards, because the current problem is productization and proof, not missing capability.
• Release truth: Current-release follow-up from completed productization and gate specs.

Implementation Phases

Phase 1 - Inventory And Contract Lock

Inventory every visible system label/status/action in scope and record the exact current surfaces. Confirm no completed spec artifacts need rewriting.

Phase 2 - Tests First

Add or update focused tests for canonical status vocabulary, system auth/smoke safety, action posture, and browser proof before or alongside behavior changes.

Phase 3 - Productized System Branding

Apply TenantPilot system branding through existing provider/localization/page paths. Keep the technical system-admin character but remove default or ambiguous visible copy.

Phase 4 - Canonical Status Vocabulary

Map existing system health/status states to canonical labels through existing badge/widget/localization paths.

Phase 5 - Smoke And Debug-Safe Proof

Reuse the existing platform-guard browser path where possible. Add a local/testing-only smoke helper only if required for manual in-app sanity, with route safety coverage.

Phase 6 - Close-Out Evidence

Run focused tests, capture browser proof, complete implementation-report.md, and document deployment impact as none unless implementation changes assets.

Risk And Rollback Plan

• Rollback: Revert label/config/test changes in the feature branch. No database rollback is required.
• Staging validation: Run focused test lane and browser smoke before production promotion.
• Production risk: Low if no smoke helper is exposed outside local/testing and no shared provider config changes affect /admin.
• Forward fix path: If shared branding affects /admin, add a focused /admin regression fix and proof within this spec before close-out.