TenantAtlas/specs/266-tenant-dashboard-productization-v1/spec.md

# Feature Specification: Tenant Dashboard Productization v1

**Feature Branch**: `266-tenant-dashboard-productization-v1`  
**Created**: 2026-05-02  
**Status**: Draft  
**Input**: User description: "Tenant Dashboard Productization v1 as a decision-first tenant governance overview that productizes the existing tenant dashboard into a calmer enterprise SaaS surface using repo-real data composition, progressive disclosure, and capability-safe actions without adding new backend foundations, fake data, or a mockup-driven redesign."

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: The existing tenant dashboard already exposes truthful governance, drift, recovery, review, evidence, and operations signals, but the surface still reads like a collection of admin widgets instead of a calm governance-of-record landing page.
- **Today's failure**: Operators can see the right building blocks, but they still have to reconstruct priority from separate widgets, tables, and utilities. That makes the first screen slower to trust, weaker as a sellable product surface, and noisier than the underlying repo-real foundations.
- **User-visible improvement**: An operator opens one tenant page and can immediately see tenant posture, what is critical, why it matters, what should happen next, and whether customer-safe output is ready, without being forced through tables, raw diagnostics, or dead-end actions.
- **Smallest enterprise-capable version**: Productize the existing tenant dashboard route into one decision-first overview with clear workspace and tenant context, up to four KPI cards, up to three prioritized next actions, compact governance status rows, recent operation truth, and honest aside readiness cards, all derived from existing tenant-scoped truth and existing destinations.
- **Explicit non-goals**: No new governance engine, no new evidence engine, no new review engine, no new OperationRun architecture, no new alerting foundation, no customer portal, no Microsoft Admin Center mirror, no fake data, no fake routes, no new design library, no full navigation rewrite, and no pixel-perfect mockup recreation.
- **Permanent complexity imported**: One bounded dashboard summary and prioritization layer derived from existing truth, one dashboard layout and card composition pass, tighter action hierarchy rules for the tenant landing page, and targeted feature plus browser coverage. No new persistence, provider seam, enum family, or generic dashboard framework is introduced.
- **Why now**: The repository already contains the foundations this page should compress. A stronger tenant landing surface is the next leverage point before broader governance inbox and customer-safe workflow slices can feel coherent and sellable.
- **Why not local**: Isolated copy or spacing cleanup would not solve fragmented prioritization, uneven action hierarchy, or the need to compress multiple repo-real truths into one calmer operator entry surface.
- **Approval class**: Workflow Compression
- **Red flags triggered**: Multi-surface operator-facing refactor touching shared dashboard signals, status semantics, action hierarchy, and several downstream deep links. Defense: the slice stays derived, uses existing tenant/admin surfaces, adds no new persistence, and explicitly refuses fake destinations or new backend foundations.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: tenant + canonical-view
- **Primary Routes**:
  - `/admin/t/{tenant}` as the existing tenant dashboard route served by `App\Filament\Pages\TenantDashboard` in the tenant panel
  - existing tenant-scoped findings, review, evidence snapshot, review-pack, restore-workflow, and required-permissions surfaces already available inside the tenant panel when the actor is entitled
  - `/admin/operations` as the canonical operations destination reached from recent-operation and follow-up links, with tenant-prefilter continuity from the dashboard
- **Data Ownership**:
  - Tenant-owned truth remains authoritative for findings, risk acceptance or exception state, evidence snapshots, review packs, tenant reviews, recovery posture signals, and operation runs shown on the dashboard
  - Workspace-owned but tenant-resolved truth remains authoritative for baseline profile or compare posture and any workspace-scoped configuration that shapes the selected tenant view
  - This feature introduces no persisted tenant-dashboard summary record; all cards remain derived from existing records and shared derived-state helpers
- **RBAC**:
  - The feature remains in the tenant/admin plane under `/admin/t/{tenant}` with workspace selection plus tenant entitlement required before the page resolves
  - Tenant membership and workspace membership remain isolation boundaries enforced before any data or downstream link is revealed
  - Existing capability checks continue to govern which destinations or mutation-capable actions are visible, enabled, or entirely absent
  - Dashboard summaries must never imply access to tenant-scoped follow-up routes the current actor cannot open

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Any canonical operations route reached from the dashboard opens already filtered to the active tenant so the operator lands in the same tenant world they clicked from.
- **Explicit entitlement checks preventing cross-tenant leakage**: Dashboard counts, readiness signals, and deep links are derived only after workspace membership and tenant entitlement checks. Canonical destinations opened from the dashboard must retain tenant-prefiltering and deny inaccessible tenant records as not found.

## 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`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: dashboard signals and cards, status messaging, action links, header actions, navigation entry points, evidence and report viewers, and required-permissions follow-up links
- **Systems touched**: `App\Filament\Pages\TenantDashboard`, `DashboardKpis`, `NeedsAttention`, `BaselineCompareNow`, `RecentDriftFindings`, `RecentOperations`, `RecoveryReadiness`, existing tenant review and evidence surfaces, existing review-pack surfaces, existing required-permissions surfaces, and canonical operations routing
- **Existing pattern(s) to extend**: the current tenant dashboard widget shell, `App\Support\Baselines\TenantGovernanceAggregateResolver`, `App\Support\BackupHealth\BackupHealthDashboardSignal`, `App\Support\Links\RequiredPermissionsLinks`, existing tenant review and review-pack surfaces, and the current canonical operations prefilter path
- **Shared contract / presenter / builder / renderer to reuse**: `TenantDashboard` as the page shell, `TenantGovernanceAggregateResolver` for derived posture truth, `BackupHealthDashboardSignal` for recovery follow-up semantics, `RequiredPermissionsLinks` for required-permissions continuity, `OperationRunLinks` and the canonical operations page for operation drill-throughs, plus the current review, evidence snapshot, and review-pack surfaces for customer-safe output readiness
- **Why the existing shared path is sufficient or insufficient**: The underlying truth sources already exist and are authoritative. What is insufficient is the current page-level composition and decision hierarchy, not the underlying domain records or downstream routes.
- **Allowed deviation and why**: One bounded page-local summary or view-model layer may be introduced if it only composes existing tenant-scoped truth for this dashboard and does not become a reusable dashboard framework or a new persisted source of truth.
- **Consistency impact**: Status terms, primary action labels, fallback states, tenant-prefilter continuity, review and evidence readiness wording, and provider-permission follow-up language must remain consistent with current downstream surfaces and shared badge semantics.
- **Review focus**: Reviewers must block any new fake route, page-local status vocabulary, local badge family, or second dashboard-specific action language that diverges from the current findings, operations, review-pack, evidence, or required-permissions surfaces.

## 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`)*

- **Touches OperationRun start/completion/link UX?**: yes
- **Shared OperationRun UX contract/layer reused**: the canonical operations page at `/admin/operations`, existing tenant-prefilter continuity from dashboard links, and `OperationRunLinks` for tenant-safe deep links to operation detail
- **Delegated start/completion UX behaviors**: `Open operation` or `View run` links, tenant-safe URL resolution, and any existing queued-toast or terminal-notification behavior that belongs to already shipped mutation paths reused from the dashboard rather than reinvented locally
- **Local surface-owned behavior that remains**: The dashboard remains read-mostly. If a direct dashboard CTA reuses an existing review-pack or evidence generation path, the dashboard only provides the initiation affordance and reuses the existing mutation scope messaging, safety gates, audit behavior, and operation lifecycle contract unchanged.
- **Queued DB-notification policy**: existing shared policy only; the dashboard does not introduce a new queued database-notification override
- **Terminal notification path**: central lifecycle mechanism for any reused existing operation-start path; otherwise not applicable for pure navigation links
- **Exception required?**: none

## 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`)*

- **Shared provider/platform boundary touched?**: no
- **Boundary classification**: N/A
- **Seams affected**: The dashboard may consume existing provider-health and required-permissions summaries, but it does not change provider contracts, identity scope, compare semantics, or shared platform taxonomies.
- **Neutral platform terms preserved or introduced**: Existing neutral terms such as provider, operation, workspace, tenant, review, evidence, and required permissions remain the shared vocabulary.
- **Provider-specific semantics retained and why**: Provider display names may remain visible inside provider-health and permissions cards because they reflect the current entitled tenant context, but deeper provider-specific details stay inside provider-owned follow-up surfaces.
- **Why this does not deepen provider coupling accidentally**: The slice consumes existing provider-facing summaries and links without introducing new provider-shaped persistence, new provider-specific dashboard taxonomies, or new platform-core seams.
- **Follow-up path**: none

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

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Tenant dashboard landing page | yes | Native Filament dashboard page plus bounded custom summary composition | dashboard signals, header actions, navigation continuity | page, summary, context | existing dashboard-shell exemption may remain unless retired in-feature | Existing route is productized, not replaced by a new panel or portal |
| KPI row | yes | Native Filament stats or shared card primitives | dashboard signals, status messaging | summary | no | At most four top-level KPI cards |
| Recommended Next Actions card | yes | Bounded custom card using Filament actions or links | action links, status messaging, header-action discipline | summary, decision | no | At most three actions, each with one dominant CTA |
| Governance Status card | yes | Bounded custom card with shared badge semantics | status messaging | summary | no | Read-only status rows, no mutation affordance |
| Recent Operation Runs card | yes | Native Filament table or bounded recency list | action links, monitoring continuity | recency, navigation | no | Row or primary-link inspect model only |
| Current Review, Provider Health, Risk and Output aside cards | yes | Bounded custom cards with shared primitives | reports, evidence viewers, status messaging, action links | summary, readiness | no | Each card keeps one dominant action and honest fallback state |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| 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 |
|---|---|---|---|---|---|---|---|
| Tenant dashboard landing page | Primary Decision Surface | Operator opens one tenant and decides whether there is urgent governance work, blocked readiness, or no immediate action | workspace and tenant context, top posture signals, highest-priority next action, readiness blockers, and honest fallback states | findings detail, required-permissions matrix, review detail, evidence detail, operation detail, and support diagnostics stay secondary | Primary because this is the tenant entry surface operators hit first and it must answer what matters now | Follows tenant triage and governance decision flow instead of storage-object navigation | Replaces cross-widget reconstruction with one explicit priority order |
| Recommended Next Actions card | Primary Decision Surface | Operator chooses the first bounded follow-up action to take | title, reason, impact, and one primary CTA for each of up to three actions | deep evidence, full tables, and raw diagnostics stay on follow-up pages | Primary because it converts dashboard posture into the next executable step without opening several lists first | Keeps the operator in a decision-first queue rather than a table-first dashboard | Compresses several signals into one ordered action list |
| Recent Operation Runs card | Secondary Context Surface | Operator confirms recent execution context after deciding whether action is needed | operation label, status or outcome, relative time, and one short summary | operation detail, artifacts, run logs, and longer diagnostics remain secondary | Not primary because it explains recent context, not the tenant's highest-priority governance decision | Supports monitoring follow-through after the main dashboard decision is made | Prevents recent activity from taking over the primary decision layer |
| Current Review and Output readiness aside | Secondary Context Surface | Operator decides whether customer-safe output is already available or needs follow-up | active review status, evidence availability, review-pack readiness, and one safe next step | released review detail, evidence snapshot detail, and review-pack detail remain on demand | Not primary because it informs readiness after posture and next action are understood | Supports customer-safe follow-through without replacing tenant triage | Keeps review and evidence readiness visible without dominating the landing page |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| 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 |
|---|---|---|---|---|---|---|---|
| Tenant dashboard landing page | operator-MSP, manager, owner, support-platform in admin context | tenant posture, top risks, next action, readiness blockers, and honest unavailable states | compact governance rows, recent operations, and linked detail pages | support diagnostics modal, raw payloads, GUIDs, and low-level provider detail remain hidden or capability-gated | highest-priority recommended action | raw JSON, log bodies, provider dumps, and broad diagnostic matrices stay off the default landing page | the page states the tenant's main problem once at the top and uses secondary cards only to add context |
| Recent Operation Runs card | operator-MSP, support-platform | recent run labels, status or outcome, relative time, and short outcome summary | full canonical operation detail and tenant-prefiltered operations list | run payloads, artifacts, and logs stay on the operation detail surfaces | `View all operations` or the most relevant row-open action | run internals and artifacts stay out of the dashboard default | recency context never restates posture or top action claims at equal priority |
| Current Review and Output readiness aside | operator-MSP, manager, owner | current review status, evidence availability, review-pack readiness, and honest fallback text | review detail, evidence snapshot detail, and review-pack detail | raw evidence payloads and pack internals stay off the landing page | `Continue review`, `Open review pack`, or another single repo-real follow-up | proof internals, item-level evidence, and unavailable routes remain hidden or disabled | readiness is summarized once and detail pages deepen it instead of duplicating it |
| Provider Health and Required Permissions aside | operator-MSP, manager, owner | provider health label, missing permissions count, last check, and one follow-up action | required-permissions matrix and provider-health detail | provider-specific dumps and debug metadata stay off the landing page | `Open required permissions` or `Open provider health` | raw provider detail and non-entitled destinations remain gated | provider blockers appear once as either a next action or a compact status row, not in several conflicting cards |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard landing page | Dashboard / Landing / Summary | Decision-first tenant workbench | Review the top problem for the current tenant | one dominant CTA per decision card or one safe header action | forbidden | secondary links live inside supporting cards only when they reinforce the same tenant truth | none on the page shell; any reused mutation must follow the downstream safe-execution path | `/admin/t/{tenant}` | existing entitled findings, review, evidence, permissions, restore, or operations destinations | workspace, tenant, provider or sync context, and readiness chips | Tenant dashboard | posture, reason, impact, next action, and readiness blockers | existing dashboard-shell exemption may remain because the shell stays widget and summary owned |
| Recommended Next Actions card | Summary / Drill-in | Prioritized tenant work list | Open the most urgent follow-up surface | one button or link per action entry | forbidden | none beyond the one primary CTA per action | none | `/admin/t/{tenant}` | existing entitled follow-up route for each action | current tenant and current workspace remain explicit around the card | Governance actions / Action | why action is needed and what it affects | none |
| Governance Status card | Summary / Status | Read-only status digest | Open one status family only when more detail is needed | optional per-row support link; otherwise read-only | forbidden | per-row secondary link only when it does not compete with the main action card | none | `/admin/t/{tenant}` | existing entitled status detail route where applicable | tenant-scoped status rows and badges | Governance status | baseline, evidence, review, provider-permission, and restore-readiness posture | none |
| Recent Operation Runs card | Diagnostic / Table / Recency | Tenant activity recency list | Inspect the most relevant recent operation | full-row open or one row-primary link | required when table rows are used | `View all operations` lives in the card footer or header | none | `/admin/operations` with tenant prefilter | existing canonical operation detail route | tenant context preserved into the canonical monitoring route | Operations / Operation | execution status, outcome, timing, and short summary | none |
| Current Review and Output readiness aside | Summary / Readiness / Report | Customer-safe output readiness card family | Continue review or open the current output artifact | one primary CTA per card | forbidden | none | none | `/admin/t/{tenant}` | existing tenant review, evidence snapshot, or review-pack detail | tenant context and review or evidence freshness | Review / Evidence / Review pack | current readiness and honest fallback states | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard landing page | Tenant operator or MSP operator | Decide whether the tenant needs immediate governance follow-up and what should happen first | Decision-first dashboard | What is the tenant state right now, why does it matter, and where should I go next? | tenant and workspace context, posture signals, top action, readiness blockers, and honest fallback states | raw diagnostics, low-level provider details, operation payloads, and GUIDs stay secondary | governance result, readiness, provider posture, execution outcome, evidence and review readiness | none by default; any reused mutation must declare its existing scope before execution | the highest-priority action and at most one secondary header action | none on the landing shell |
| Recommended Next Actions card | Tenant operator or MSP operator | Start the next bounded governance follow-up | Prioritized work list | Which action should I take first? | title, reason, impact, and one primary CTA | underlying table views and raw evidence live on follow-up pages | governance priority, provider blockage, readiness gap, or execution follow-up | navigation only unless an existing start surface is reused unchanged | `Review findings`, `Review risks`, `Open required permissions`, or other single repo-real action | none |
| Recent Operation Runs card | Tenant operator or support-facing admin | Inspect recent execution truth after posture is known | Diagnostic recency list | Did a recent operation explain this state or require follow-up? | operation label, timing, status, outcome, and short summary | canonical operation detail and artifacts | execution status and outcome | none | open operation detail or `View all operations` | none |
| Current Review and Output readiness aside | Tenant operator or manager | Confirm whether customer-safe review and evidence output is ready | Readiness summary | Can I continue the current review or hand off a current artifact? | review status, evidence availability, output readiness, and one safe next step | detailed review narrative, evidence detail, and pack detail | review lifecycle, evidence freshness, output availability | navigation only unless a reused existing generation path is explicitly allowed | `Continue review`, `Open review pack`, or another single repo-real output action | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: The current tenant landing page makes operators gather posture, readiness, and next-action truth from several separate widgets and utilities, which weakens trust and slows triage.
- **Existing structure is insufficient because**: Existing widget-local logic is truthful but fragmented. It does not yet provide one explicit summary of priority, reason, impact, and safe next steps across findings, provider health, evidence, review, recovery, and operations.
- **Narrowest correct implementation**: A single bounded derived summary and prioritization layer that composes existing tenant-scoped truth for the dashboard only, plus a dashboard layout pass that reorders and compresses current surfaces into a decision-first hierarchy.
- **Ownership cost**: Moderate feature-local maintenance and regression coverage around action priority, capability gating, and fallback states. No new persistence, migration, or provider maintenance cost is created.
- **Alternative intentionally rejected**: Pure page-local copy or spacing polish was rejected because it would leave priority fragmented. A new persisted tenant dashboard aggregate or generic dashboard framework was rejected because the current-release problem is composition, not missing domain storage.
- **Release truth**: current-release truth

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

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

- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: confidence, browser
- **Why this classification and these lanes are sufficient**: Focused feature tests are the narrowest sufficient proof for summary scoping, action prioritization, fallback honesty, capability gating, and tenant-prefilter continuity. One bounded browser smoke is required because the slice materially changes dashboard information hierarchy, action density, and default-visible disclosure.
- **New or expanded test families**: expand tenant dashboard feature coverage and add exactly one explicit tenant dashboard browser smoke
- **Fixture / helper cost impact**: moderate. Reuse existing workspace selection, tenant entitlement, findings, governance aggregate, operation-run, evidence snapshot, review-pack, tenant review, and required-permissions fixtures instead of introducing provider HTTP, queue-heavy, or broad system defaults.
- **Heavy-family visibility / justification**: one browser smoke is justified because the primary outcome is a calmer operator-first landing page. No new heavy-governance family is introduced.
- **Special surface test profile**: global-context-shell
- **Standard-native relief or required special coverage**: ordinary Filament feature coverage plus one browser smoke are sufficient. No additional broad monitoring or heavy-governance lane is required.
- **Reviewer handoff**: Reviewers must confirm that the page stays tenant-scoped, never exceeds the action-density caps, shows honest fallback states, preserves tenant-prefilter continuity into canonical operations, keeps raw detail off the landing page, and does not add fake or dead-end actions.
- **Budget / baseline / trend impact**: low feature-local increase only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Dashboard/TenantDashboardProductizationSummaryTest.php tests/Feature/Dashboard/TenantDashboardProductizationActionsTest.php tests/Feature/Dashboard/TenantDashboardProductizationAuthorizationTest.php tests/Feature/Dashboard/TenantDashboardProductizationReadinessTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardDbOnlyTest.php tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Understand Tenant Posture Fast (Priority: P1)

As a tenant operator, I want the tenant landing page to tell me within seconds whether the tenant is healthy, blocked, or action-needed, so I can start the right governance work without reconstructing meaning from several widgets.

**Why this priority**: This is the first screen in tenant context. If it does not establish posture and priority clearly, every later follow-up becomes slower and less trustworthy.

**Independent Test**: Seed one tenant with posture issues, readiness blockers, and recent operations, open the dashboard, and confirm the operator can identify the current state and top action from the first screen without opening another page.

**Acceptance Scenarios**:

1. **Given** the current tenant has high-priority unresolved findings, **When** an entitled operator opens the tenant dashboard, **Then** the page immediately shows action-needed posture and the top follow-up action rather than a calm or ambiguous summary.
2. **Given** the current tenant has no high-priority action waiting, **When** the operator opens the tenant dashboard, **Then** the page shows calm fallback messaging without inventing missing data or hiding unavailable states.
3. **Given** the current tenant has provider or readiness blockers but few findings, **When** the dashboard renders, **Then** the page still surfaces that blocker in the top decision layer.

---

### User Story 2 - Follow One Safe Next Action (Priority: P1)

As a tenant operator, I want the dashboard to show only a small ordered set of next actions with reason and impact, so I can act without scanning several lists and without hitting fake or dead-end links.

**Why this priority**: Productization fails if the page still forces operators into table-driven triage or exposes actions that only make sense after several clicks.

**Independent Test**: Seed multiple issue combinations, render the dashboard, and verify that no more than three actions appear, that the highest-priority action is first, and that every visible action leads to a real entitled destination or a truthful disabled state.

**Acceptance Scenarios**:

1. **Given** the tenant has several open problem families, **When** the dashboard builds recommended actions, **Then** it shows at most three actions ordered by the declared priority model.
2. **Given** a recommended action points to a surface the current actor may not open, **When** the dashboard renders, **Then** the action is hidden or disabled with truthful helper text instead of appearing as a clickable dead end.
3. **Given** the tenant has no immediate governance action waiting, **When** the dashboard renders, **Then** the recommended-actions card shows a positive no-action state instead of an empty shell.

---

### User Story 3 - See Readiness Without Raw Detail (Priority: P2)

As a tenant operator, I want to see review, evidence, provider-health, and recent-operation readiness on the dashboard without raw payloads or diagnostic dumps, so I can decide whether customer-safe output or investigation is ready without losing the calmer landing experience.

**Why this priority**: The dashboard must stay decision-first while still exposing enough readiness truth to support review and handoff workflows.

**Independent Test**: Render tenants with and without current review, evidence snapshot, review pack, provider permission gaps, and recent operations, and verify that the dashboard shows compact readiness summaries plus honest fallback states without exposing raw detail by default.

**Acceptance Scenarios**:

1. **Given** the tenant has an active review and current evidence output, **When** the dashboard renders, **Then** the aside surfaces show readiness and one safe next step without overwhelming the primary triage layer.
2. **Given** no review, evidence snapshot, or provider-health detail is currently available, **When** the dashboard renders, **Then** it shows explicit unavailable or not-yet-ready states instead of implying healthy readiness.
3. **Given** recent operations exist, **When** the dashboard renders, **Then** recent execution truth appears as secondary context and does not replace the primary decision layer.

---

### User Story 4 - Respect Tenant and Capability Boundaries (Priority: P1)

As a workspace and platform owner, I want the productized dashboard to respect tenant isolation and capability boundaries, so the new surface does not leak data or expose actions outside the current actor's entitled scope.

**Why this priority**: The slice increases surface density and cross-links, so the security and isolation boundary must remain explicit and testable.

**Independent Test**: Render the dashboard for users with full access, partial follow-up access, and no tenant entitlement, then verify 404 vs 403 behavior, action visibility, and tenant-prefilter continuity.

**Acceptance Scenarios**:

1. **Given** a user is not entitled to the current tenant, **When** they request the tenant dashboard or one of its follow-up links, **Then** the route responds as not found and does not reveal tenant state.
2. **Given** a user may view the tenant dashboard but lacks a follow-up capability, **When** the dashboard renders, **Then** the summary may remain visible but the blocked follow-up action is not executable.
3. **Given** the dashboard opens a canonical operations destination, **When** the operator follows that link, **Then** the canonical page remains filtered to the originating tenant.

### Edge Cases

- The tenant may have healthy findings posture but a missing required-permissions blocker; the dashboard must still show that blocker as action-needed instead of implying overall health.
- The tenant may have recent successful operations only; the dashboard must show recency context without recasting it as governance risk.
- The tenant may have no baseline or insufficient compare data; the dashboard must show `Unavailable`, `Not configured`, or another honest fallback rather than a positive compare label.
- The tenant may have evidence or review-pack readiness gaps while review surfaces still exist; the dashboard must distinguish missing output readiness from missing route access.
- The tenant may have no current review or no stored report; the dashboard must not invent customer-safe maturity or show an `Open customer view` action unless a real entitled destination exists.
- The operator may lack one downstream capability while still being entitled to the tenant dashboard; the dashboard must not expose a clickable dead-end action.

## Requirements *(mandatory)*

**Constitution alignment (required):** This slice is primarily read-only productization over existing tenant-scoped truth. If the final implementation reuses any existing mutation-capable action such as review-pack or evidence generation, it must reuse the current safety gates, audit logging, and OperationRun lifecycle rather than introducing a new dashboard-only mutation path.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The feature introduces no new persistence and no new state family. It may introduce one bounded derived summary and prioritization layer because current widget-local logic is insufficient to produce a calm decision-first landing page. That layer remains local, derived, and replace-before-layered; it does not become a generic dashboard framework.

**Constitution alignment (XCUT-001):** This is a cross-cutting dashboard and action-language slice. It must extend the existing tenant dashboard shell, shared derived-state helpers, required-permissions links, review and evidence surfaces, and canonical operations routing instead of introducing local dashboard-only status taxonomies or deep-link contracts.

**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** The tenant dashboard remains an operator-first admin surface. Default-visible content shows posture, reason, impact, next action, and compact readiness. Diagnostic tables, provider detail, evidence detail, pack detail, and support or raw evidence remain secondary and explicitly revealed on demand. Each card preserves one dominant next action and avoids repeating the same truth in parallel cards.

**Constitution alignment (PROV-001):** The dashboard may surface provider-health summaries and required-permissions follow-up, but it must not change shared provider contracts or turn provider-specific semantics into platform-core truth. Provider detail stays within existing provider-owned follow-up pages.

**Constitution alignment (TEST-GOV-001):** The change is proved by focused feature tests plus one explicit browser smoke. Fixture cost stays bounded by reusing existing tenant, workspace, findings, review, evidence, and operations fixtures. No hidden heavy test family or provider-setup default may be introduced by convenience.

**Constitution alignment (OPS-UX):** Recent-operation cards and any reused existing start-capable CTA must comply with the default shared operations feedback contract. The dashboard itself does not own `OperationRun.status` or `OperationRun.outcome` transitions and must continue to delegate lifecycle truth to existing services and canonical operation surfaces.

**Constitution alignment (OPS-UX-START-001):** Any reused existing start action must inherit queued-toast, tenant-safe link, and terminal-notification behavior from the existing shared start path. The dashboard may not create a dashboard-specific dedupe, blocked-state, or terminal-notification contract.

**Constitution alignment (RBAC-UX):** The feature remains in the tenant/admin plane. Non-members or non-entitled actors receive 404. In-scope members missing a follow-up capability receive 403 at the destination and must not see a misleading clickable dead-end on the dashboard. Server-side Gates and Policies remain the enforcement source. No raw capability strings or role-string checks may be introduced.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. This slice does not change login or authentication handshakes.

**Constitution alignment (BADGE-001):** Existing badge semantics for findings, operation status and outcome, review-pack readiness, evidence-snapshot status, provider-permission posture, and similar existing status families remain authoritative. The dashboard must not create ad-hoc local badge mappings that drift from those shared semantics.

**Constitution alignment (UI-FIL-001):** The page must stay Filament-native: existing dashboard page shell, native stats or widgets where practical, Filament actions for visible CTAs, shared badge primitives, and bounded Blade or Tailwind cards only where native widget composition is insufficient. Any local markup must preserve dark-mode correctness, spacing consistency, accessibility, progressive disclosure, and Filament visual language.

**Constitution alignment (UI-NAMING-001):** Operator-facing labels must stay calm and domain-first. Primary verbs stay within existing product language such as `Review findings`, `Review risks`, `Open required permissions`, `Continue review`, `Open review pack`, and `View all operations`. Implementation-first wording and fake customer-safe language are forbidden.

**Constitution alignment (DECIDE-001):** The tenant dashboard landing page and the recommended-actions card are the primary decision surfaces. Recent operations, review and output readiness, and provider-health summaries are secondary context. Raw or support-heavy evidence remains tertiary and on demand.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** The dashboard shell keeps one dominant primary action model per card, no redundant inspect buttons, no mixed catch-all action groups, and at most two visible header actions. Pure navigation and mutation-like actions must not compete on the same plane. Secondary links live only where they reinforce the same decision context.

**Constitution alignment (ACTSURF-001 - action hierarchy):** Header actions are capped at two and must remain decision-first. Card actions are capped at one dominant CTA per card. Dangerous or destructive behavior is not introduced on the dashboard shell. Any reused mutation-capable action must remain clearly separated from pure navigation and must keep its existing confirmation and safety semantics.

**Constitution alignment (OPSURF-001):** The page default must stay operator-first, not raw-detail-first. The dominant next action remains the recommended-actions card. Status dimensions remain separated across posture, readiness, provider blockage, and operation recency. Workspace and tenant context stay explicit in the page header and every downstream link.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** Direct widget-local truth mapping is already insufficient because it fragments priority across several surfaces. The feature may add one bounded summary layer, but it must not create redundant truth across models, wrappers, presenters, and persisted mirrors. Tests must focus on scoping, priority, fallback honesty, and action continuity rather than indirection alone.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied by preserving one primary inspect or open model per card or table surface, avoiding redundant view affordances, keeping empty action groups absent, and keeping destructive actions off the dashboard shell. The existing dashboard-shell exemption may remain if the final implementation still behaves as a widget-owned summary shell. `UI-FIL-001` remains satisfied.

**Constitution alignment (UX-001 — Layout & Information Architecture):** The productized dashboard uses explicit sections or cards, keeps table-like surfaces secondary, and provides specific empty states with title, explanation, and at most one CTA. No form or edit-screen rules are introduced because this remains a dashboard surface, not a create or edit workflow.

### Functional Requirements

- **FR-266-001**: The system MUST productize the existing tenant dashboard at `/admin/t/{tenant}` into a decision-first landing page for the current tenant.
- **FR-266-002**: The dashboard MUST show current workspace and tenant context prominently and MUST avoid displaying GUIDs or raw identifiers in the default-visible layer.
- **FR-266-003**: The dashboard MUST show no more than two visible header actions.
- **FR-266-004**: The dashboard MUST show no more than four top-level KPI cards in the first posture row.
- **FR-266-005**: The dashboard MUST derive posture, readiness, and next-action signals only from existing repo-real truth sources and explicit fallback states.
- **FR-266-006**: The dashboard MUST show no more than three recommended next actions and MUST order them by a documented priority model that prefers the most urgent tenant decision first.
- **FR-266-007**: Each recommended action MUST include a short title, a reason, an impact statement, and one primary CTA. Fake actions and fake routes are forbidden.
- **FR-266-008**: When the actor lacks the capability or route needed for a follow-up action, the dashboard MUST hide that action or render it as an honest unavailable or disabled state instead of a clickable dead end.
- **FR-266-009**: The dashboard MUST provide a compact governance-status digest that covers baseline or compare posture, evidence coverage, review freshness, provider-permission posture, and restore or recovery readiness, using honest `Unavailable` or `Not configured` states when data is missing.
- **FR-266-010**: The dashboard MUST provide a recent-operation context surface that shows at most four relevant recent runs, uses existing operation truth semantics, and links to the canonical operations experience with tenant-prefilter continuity.
- **FR-266-011**: The dashboard MUST provide compact review, risk or exception, provider-health, and customer-safe output summaries when repo-real data exists, and MUST provide truthful empty or unavailable states when it does not.
- **FR-266-012**: The dashboard MUST keep raw JSON, long logs, provider dumps, stack traces, and other technical payloads off the default-visible landing experience.
- **FR-266-013**: All dashboard queries and summaries MUST remain scoped to the current workspace and current tenant.
- **FR-266-014**: The dashboard MUST remain usable on narrower widths without horizontal scrolling and without losing the top decision hierarchy.
- **FR-266-015**: The dashboard MUST not introduce a new persisted dashboard summary model, a new provider abstraction, a new review engine, or a new governance engine.
- **FR-266-016**: If the dashboard exposes a direct action that reuses an existing mutation path, that action MUST reuse the existing confirmation, audit, and OperationRun semantics of the underlying surface.

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard page shell | `app/Filament/Pages/TenantDashboard.php` | max 2 decision-first actions; support utilities are not header-default in the productized state | n/a | none | none | none on the page shell | n/a | n/a | only when a reused existing mutation path already audits | existing dashboard-shell exemption may remain if the shell stays summary-owned rather than declaration-backed |
| KPI row and recommended-actions composition | `app/Filament/Widgets/Dashboard/*` and any bounded dashboard summary view | none beyond the page-shell cap | stat or card CTA only where the signal is actionable | none | none | one specific CTA only for honest empty-state follow-up | n/a | n/a | no new audit behavior for pure navigation | each card gets one dominant CTA and no mixed action groups |
| Governance Status card | bounded dashboard summary surface | none | optional per-row supportive link only when it does not compete with the main action | none | none | one specific CTA only when the entire card is empty or unavailable | n/a | n/a | no new audit behavior | read-only digest surface, no mutation affordance |
| Recent Operation Runs card | `app/Filament/Widgets/Dashboard/RecentOperations.php` or successor bounded surface | optional `View all operations` within card chrome, not as a competing page header action | `recordUrl()` or one row-primary open affordance | none | none | one specific CTA only when there are no visible runs and a follow-up route is meaningful | n/a | n/a | no new audit behavior | canonical operations detail remains the inspect model |
| Current Review and Output readiness aside | bounded dashboard summary surface plus existing review, evidence, and pack routes | none | card-primary CTA only | none | none | one specific CTA only when a repo-real preparation path exists; otherwise read-only fallback | n/a | n/a | only when a reused existing generation path already audits | no fake customer view or fake artifact route may appear |

### Key Entities *(include if feature involves data)*

- **Tenant Dashboard Summary**: A derived tenant-scoped composition of posture, readiness, and action signals used only to render the dashboard without becoming persisted truth.
- **Recommended Tenant Action**: A bounded next-step record with priority, reason, impact, and one primary follow-up target derived from existing tenant truth.
- **Governance Status Row**: A compact tenant-scoped readiness line showing one status family, one explanation, and an optional supportive deep link.
- **Recent Operation Summary**: A compact tenant-scoped representation of a recent `OperationRun` using existing execution truth semantics.
- **Output Readiness Summary**: A compact tenant-scoped representation of review, evidence, review-pack, or related customer-safe output availability.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-266-001**: In seeded operator review, an entitled operator can identify within 10 seconds whether the current tenant needs immediate action and which action comes first.
- **SC-266-002**: In automated coverage and browser smoke, the dashboard never shows more than two visible header actions, four KPI cards, or three recommended next actions.
- **SC-266-003**: In regression coverage, dashboard summaries and links remain scoped to the current workspace and tenant in 100% of covered scenarios, and blocked follow-up actions are never rendered as executable dead ends.
- **SC-266-004**: In browser smoke at a common desktop viewport, the first screen presents decision-first summary cards and no raw JSON, log block, or GUID-heavy technical panel is visible by default.
- **SC-266-005**: The slice ships without adding a new persisted dashboard summary model, a fake route, or fabricated data.

## Scope Boundaries

### In Scope

- productize the existing tenant dashboard route and page hierarchy into a calmer decision-first tenant landing experience
- compress repo-real findings, baseline or compare posture, recovery readiness, provider blockage, review and evidence readiness, and recent operation truth into one ordered dashboard
- restructure header action hierarchy so the page keeps at most two visible header actions
- add honest empty and unavailable states for missing or not-yet-ready data
- keep review, evidence, review-pack, required-permissions, and canonical operations continuity truthful and capability-safe
- keep the attached mockup only as an information-architecture and density reference, not a pixel-perfect template

### Non-Goals

- a new governance engine, evidence engine, review engine, or OperationRun architecture
- a customer portal or new customer-only plane
- a new design library or global CSS redesign
- a fake governance inbox, fake customer view, fake provider-health route, or fake report path
- a full navigation restructure across the entire tenant panel
- a Microsoft Admin Center mirror or generic M365 object browser

## Dependencies

- `App\Filament\Pages\TenantDashboard` and its current dashboard widget family
- `App\Support\Baselines\TenantGovernanceAggregateResolver` and existing compare or posture truth
- existing findings workflow, risk acceptance or exception truth, and tenant-scoped follow-up routes
- existing review, evidence snapshot, and review-pack models, resources, policies, and routes
- existing canonical operations page and operation detail routing
- existing required-permissions links and provider-health truth
- existing capability registry, workspace selection, tenant selection, and deny-as-not-found enforcement

## Assumptions

- The existing tenant panel remains the correct panel for this surface and keeps serving the dashboard under `/admin/t/{tenant}`.
- The attached mockup is a visual target for calm hierarchy and density only. Repository truth wins over mockup symmetry.
- Existing downstream findings, review, evidence, review-pack, required-permissions, restore, and operations surfaces remain the correct destinations for dashboard follow-up.
- Some desired signals may not yet be available for every tenant. In those cases, honest unavailable states are preferred over derived guesswork.
- Existing support-request and diagnostics capabilities remain available elsewhere even if they no longer deserve primary header placement on this page.

## Risks

- Some tenants may have uneven readiness data across review, evidence, provider health, and recovery surfaces, which can expose more fallback states than the mockup suggests.
- If the implementation tries to keep every legacy utility visible on the page, action density could remain too high and defeat the productization goal.
- If follow-up links are not validated carefully, the productized page could accidentally surface actions that some in-scope dashboard viewers cannot actually execute.
- If the summary layer grows into a generic framework, the slice would violate the constitution's proportionality bias.

## Follow-up Candidates

- Governance Inbox Productization once the inbox becomes the canonical tenant decision queue
- Customer Review Workspace follow-through where dashboard output readiness needs a richer customer-safe handoff path
- Navigation convergence if the tenant panel still feels structurally fragmented after the dashboard landing surface is productized
- Localization v1 when the tenant dashboard copy needs full locale coverage rather than localized guardrails only

## Definition of Done

Spec 266 is complete when:

- the tenant dashboard is defined as a decision-first tenant landing page rather than a widget collection,
- workspace and tenant context are explicit,
- the header action cap, KPI cap, and recommended-action cap are explicit and testable,
- review, evidence, provider, recovery, and operation truth are represented through repo-real data or honest fallbacks,
- every visible follow-up action is repo-real and capability-safe,
- raw technical detail is explicitly pushed out of the default-visible landing layer,
- the slice stays bounded to derived composition over existing truth,
- and targeted feature coverage plus one browser smoke are defined as the proving path.