TenantAtlas/specs/129-workspace-admin-home/spec.md

Feature Specification: Workspace Home & Admin Landing

Feature Branch: 129-workspace-admin-home
Created: 2026-03-09
Status: Draft
Input: User description: "Spec 129 — Workspace Home & Admin Landing: Introduce a real workspace home at /admin and make the admin panel the canonical workspace-level entry point"

Spec Scope Fields

• Scope: canonical-view
• Primary Routes:
  • /admin as workspace-level home
  • /admin/choose-workspace as workspace selection gate
  • /admin/choose-tenant as explicit tenant drill-down entry
  • /admin/t/{tenant} as tenant dashboard destination after deliberate tenant choice
• Data Ownership:
  • Workspace-owned: workspace context, workspace-scoped navigation semantics, workspace overview aggregates, workspace-level recent activity surfaces
  • Tenant-owned but workspace-filtered: recent operations, alerts, findings, and tenant counts surfaced only as permitted workspace-scoped summaries
  • No new business data domain is introduced; this feature only adds a canonical workspace presentation layer over existing authorized data
• RBAC:
  • Workspace membership remains the access prerequisite for the admin panel home
  • Overview cards, counts, lists, and quick actions are further constrained by the user's existing workspace or tenant capabilities
  • Non-members or users outside the active workspace receive 404 deny-as-not-found behavior
  • In-scope members lacking a required capability for a linked action or data surface receive 403 on the protected target and do not see unauthorized shortcuts or aggregates on the overview itself

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: The workspace home remains workspace-scoped even if a tenant was selected earlier in the session. It must not silently prefilter itself into one tenant or impersonate tenant context. Tenant-aware links may preserve deliberate drill-down targets, but the overview itself stays tenantless.
• Explicit entitlement checks preventing cross-tenant leakage: Every aggregate or list on the workspace home must be derived from capability-aware query paths limited to the active workspace and the user's authorized tenant subset. Cross-plane and cross-workspace access remains deny-as-not-found.

User Scenarios & Testing

User Story 1 - Land on a real workspace home (Priority: P1)

As a workspace user, I want /admin to open a meaningful workspace overview so I always have a clear starting point and return target that is not tied to a tenant.

Why this priority: The feature only delivers value if the admin panel stops acting like a redirect shim and becomes a durable workspace-level home.

Independent Test: Can be fully tested by opening /admin with a selected workspace and verifying that the user lands on a workspace overview page instead of being pushed into a tenant dashboard.

Acceptance Scenarios:

1. Given a signed-in user with an already selected workspace, When they open /admin, Then they see the workspace overview page.
2. Given a signed-in user with an already selected workspace, When they click the admin-panel brand logo, Then they return to the workspace overview page.
3. Given a signed-in user with no selected tenant but a selected workspace, When they open /admin, Then the workspace overview still renders fully without requiring tenant selection.

---

User Story 2 - Reorient and continue work from workspace context (Priority: P2)

As a workspace user, I want the workspace home to show current context, important workspace-wide signals, and safe next actions so I can decide where to go next without guessing.

Why this priority: After landing semantics are fixed, the page must still be useful enough to justify becoming the canonical workspace home.

Independent Test: Can be fully tested by rendering the workspace home for a user with normal access and verifying that it shows workspace identity, bounded summary surfaces, recent operational visibility, and quick actions to existing destinations.

Acceptance Scenarios:

1. Given a user with authorized access to multiple workspace surfaces, When the workspace home loads, Then it shows workspace identity, summary cards, at least one recent or needs-attention surface, and quick actions to existing flows.
2. Given a workspace with little or no activity, When the workspace home loads, Then it shows intentional empty states instead of blank or broken sections.
3. Given a workspace where no tenant is active, When the workspace home loads, Then it still presents workspace-scoped orientation and tenant-selection as a deliberate next step rather than an automatic redirect.

---

User Story 3 - See only permitted workspace surfaces (Priority: P3)

As a minimally privileged workspace user, I want the workspace home to expose only the data and actions I am allowed to use so that the page remains safe, accurate, and non-misleading.

Why this priority: The overview becomes the canonical home, so it must uphold authorization boundaries and avoid leaking data through aggregates or shortcuts.

Independent Test: Can be fully tested by loading the workspace home under low-permission and non-member scenarios and verifying both safe rendering and deny-as-not-found behavior where required.

Acceptance Scenarios:

1. Given a workspace member with limited permissions, When they open the workspace home, Then unauthorized cards, counts, and shortcuts are hidden or replaced by safe empty states.
2. Given a user outside the active workspace, When they attempt to access /admin, Then access is denied with workspace-scope not-found semantics.
3. Given a user who may see some workspace-level content but not administrative workspace management, When the workspace home renders, Then “Switch workspace” may appear while “Manage workspaces” remains absent.

Edge Cases

• A user with workspace membership but zero accessible tenants must still see a complete workspace home with tenant-related surfaces hidden or empty and a clear next action.
• A workspace with no recent operations, no urgent issues, and no alerts must still render a composed overview with intentional empty states.
• If a session is restored with a previously selected workspace, direct open of /admin must land on workspace home immediately rather than replaying an old tenant redirect path.
• Legacy redirect helpers that assume /admin means “enter tenant context now” must no longer force a tenant dashboard during normal admin-home access.
• If a user loses authorization between sessions, /admin must not reveal workspace identity or counts before authorization is re-evaluated.

Requirements

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no new write workflow, and no new queued or scheduled operation. It is a presentation and routing semantics feature over existing authorized workspace and tenant-scoped data. No new OperationRun or AuditLog contract is required beyond existing behavior for any linked destinations.

Constitution alignment (OPS-UX): Not applicable. The workspace home does not create or mutate OperationRun records. Existing operation data may be summarized or linked, but status transitions, progress handling, and terminal notifications remain owned by the existing operations implementation.

Constitution alignment (RBAC-UX): This feature changes authorization behavior in the admin workspace plane at /admin and consumes tenant-context data only as capability-safe summaries. Non-members or users outside the workspace remain 404 deny-as-not-found. In-scope members missing a capability for a protected destination or action receive 403 at that destination, while the overview must suppress unauthorized links and aggregates. Authorization remains server-side through existing Gates, Policies, and capability registry lookups. No raw capability strings or role-string checks may be introduced. If the overview links to any destructive flow in the future, that target must already enforce confirmation; this feature itself introduces no destructive action.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. No authentication-handshake or monitoring exception behavior is changed.

Constitution alignment (BADGE-001): If the overview reuses status-like badges for alerts, findings, or operations, it must consume the existing centralized badge semantics rather than introducing page-local mappings. Tests should verify any newly surfaced badge state remains consistent with existing platform meaning.

Constitution alignment (Filament Action Surfaces): This feature adds or modifies Filament page and panel chrome behavior, so the UI Action Matrix below applies. The Action Surface Contract remains satisfied because the page primarily exposes navigation and inspection affordances, introduces no destructive mutation, and keeps all actionable destinations behind their existing authorization rules.

Constitution alignment (UX-001 — Layout & Information Architecture): The new workspace home must comply with UX-001 using structured sections or cards for all content, a calm enterprise layout, explicit empty states, and no naked controls. It is a view-style overview surface, not a disabled edit form. Any reused tables or lists must keep search, sort, or filtering expectations only where they are core to the reused destination rather than overloaded into the home screen.

Functional Requirements

• FR-129-01 Canonical workspace home: The system must expose a canonical workspace-level home at /admin inside the existing admin panel.
• FR-129-02 Workspace selection gate preservation: If no workspace is established for the current request, direct open of /admin must continue through the canonical workspace selection flow rather than auto-branching into tenant context.
• FR-129-03 Selected-workspace landing: If a workspace is selected, opening /admin must render the workspace overview instead of redirecting to a tenant dashboard.
• FR-129-04 No implicit tenant requirement: The workspace overview must render and remain useful without an active tenant selection.
• FR-129-05 Stable landing semantics: Direct open of /admin, post-login landing into the admin panel, brand-logo navigation in the admin panel, and future explicit “Back to workspace” targets must all resolve to the workspace overview when a workspace is already selected.
• FR-129-06 Primary navigation entry: The admin panel must register a visible, stable primary navigation entry for the workspace home using an obvious label such as “Overview,” and it must appear as the first or first relevant workspace-level item.
• FR-129-07 Workspace identity visibility: The workspace overview must clearly show the active workspace identity, including workspace name and any cheap, already-available secondary metadata judged useful.
• FR-129-08 Capability-safe overview rendering: Every card, count, list item, widget, and quick action on the workspace home must be derived from data or routes the current user is authorized to access.
• FR-129-09 No unauthorized aggregate leakage: The overview must not show counts, summaries, or existence hints derived from tenants, alerts, findings, or operations outside the user's authorized scope.
• FR-129-10 Summary KPI set: The workspace home must expose a focused set of high-value, workspace-scoped summary cards that can include accessible tenant count, active operations count, alert summary count, and one needs-attention count, but only when each metric is safe and inexpensive to compute.
• FR-129-11 Bounded needs-attention surface: The workspace home must expose a bounded “Needs attention” surface for urgent, permitted workspace-level items and degrade cleanly to an empty state when none exist.
• FR-129-12 Bounded recent operations surface: The workspace home must expose a bounded recent operations surface showing only relevant, permitted operations with links to canonical destinations.
• FR-129-13 Quick actions to existing flows: The workspace home must provide quick actions to existing destinations such as choose tenant, operations, alerts, switch workspace, and manage workspaces when authorized.
• FR-129-14 Switch versus manage separation: The workspace home must keep “Switch workspace” distinct from “Manage workspaces” in label, purpose, and authorization behavior.
• FR-129-15 Brand-logo behavior: In the admin panel, brand-logo navigation must point to /admin, which now resolves to the workspace overview.
• FR-129-16 Redirect helper alignment: Existing admin-panel redirect helpers, home resolvers, and entry-point logic must be updated or constrained so /admin is no longer treated as an automatic jump into tenant context.
• FR-129-17 Intentional empty states: The workspace home must include useful empty states for no accessible tenants, no recent operations, no alerts or findings requiring attention, and minimal-permission users.
• FR-129-18 No cross-scope deception: The workspace home must make it visually clear that it is a workspace-level surface and must not imply an active tenant context when none is selected.
• FR-129-19 Explicit authorization: Access to the workspace overview page itself must be protected by explicit admin-panel and workspace membership authorization, not only by navigation visibility. Capability checks must gate sub-surfaces, aggregates, and linked actions, not page entry for an otherwise valid workspace member.
• FR-129-20 Canonical return target: The workspace overview must become the canonical destination for future workspace-return flows.
• FR-129-21 Performance discipline: Workspace-home queries must be bounded, eager-loaded where needed, and cheap enough for normal page load without uncontrolled polling or broad cross-workspace aggregation.
• FR-129-22 Conservative refresh behavior: If any live refresh is used, it must be conservative, justified, and limited to lightweight surfaces; default behavior should avoid polling entirely.
• FR-129-23 Canonical links only: Every clickable summary or action on the workspace home must route to an existing canonical destination instead of introducing ad-hoc alternate paths.
• FR-129-24 Low-permission resilience: A minimally privileged workspace member must still receive a meaningful workspace home, even if most data surfaces collapse to empty or hidden states.
• FR-129-25 Zero-tenant resilience: A workspace with zero accessible tenants must still present a complete workspace home and allow permitted workspace-level actions such as switching workspace.

Non-Goals

• Introducing a new third business panel
• Performing tenant-panel navigation cleanup in this feature
• Moving or removing monitoring from tenant surfaces
• Hardening all resource discovery or global canAccess() behavior
• Refactoring middleware beyond what is minimally required to restore correct workspace-home landing semantics
• Introducing new backend operational features, reporting engines, or trend analytics
• Adding heavy charts, broad portfolio analytics, or high-frequency live dashboards

Assumptions

• The existing admin panel is the correct workspace-level panel and remains the only authenticated workspace panel in this scope.
• Current workspace selection and tenant selection flows already exist and remain canonical at /admin/choose-workspace and /admin/choose-tenant.
• Existing operations, alerts, and findings destinations already provide the canonical drill-down pages that overview cards and actions should link to.
• Some workspaces or users will have sparse data, so empty states are expected and must be treated as first-class outcomes.

Dependencies

• Existing workspace selection flow and session handling
• Existing admin panel branding and home-resolution configuration
• Existing authorized data sources for tenant counts, operations, alerts, and findings
• Existing workspace and tenant authorization rules plus capability registry
• Existing operations, alerts, and workspaces destinations used by overview quick actions

UI Action Matrix

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
Workspace Overview Page	Existing admin panel /admin home	None required beyond existing page chrome	KPI cards and bounded lists link to canonical destinations	Quick actions such as Choose Tenant and Open Operations	None	Exactly one CTA per empty section, tailored to the section	None required	N/A	No new audit event	This is a view-style overview page. It introduces no destructive action and no inline mutation.
Admin Panel Navigation	Existing admin panel primary navigation and brand logo	None	Primary Overview nav item and brand-logo home affordance	None	None	N/A	N/A	N/A	No	Navigation semantics change only: the canonical home becomes workspace overview.
Workspace Management Shortcut	Workspace overview quick actions	Manage Workspaces only when authorized	Linked action only	None	None	Manage Workspaces may serve as the single CTA for relevant empty states when permitted	None	N/A	Existing destination rules apply	The action remains distinct from Switch Workspace and must not appear for unauthorized users.

Key Entities

• Workspace Overview Surface: The canonical workspace-level home that communicates current workspace identity, top signals, and next actions without requiring a selected tenant.
• Workspace Summary Metric: A capability-safe aggregate that summarizes permitted workspace-wide information such as tenant count, active operations, or alerts.
• Workspace Attention Item: A bounded urgent item surfaced on the workspace home, ordered by recency or severity and linked to its canonical destination.
• Workspace Quick Action: A workspace-scoped shortcut to an existing flow such as choosing a tenant, opening operations, switching workspace, or managing workspaces when authorized.

Success Criteria

Measurable Outcomes

• SC-129-01 Stable home semantics: In acceptance testing, 100% of standard admin entry paths with a selected workspace resolve to the workspace overview instead of a tenant dashboard.
• SC-129-02 Workspace selection continuity: In acceptance testing, 100% of direct /admin visits without an established workspace context continue to the canonical workspace selection flow.
• SC-129-03 Tenantless usability: Users with a selected workspace and no selected tenant can successfully reach at least one valid next action from the workspace home without encountering a forced tenant redirect.
• SC-129-04 Authorization safety: In negative authorization tests, unauthorized users see zero unauthorized counts, links, or actions on the workspace home.
• SC-129-05 Low-data resilience: In empty-data test scenarios, the workspace home still renders a complete page with intentional empty states and at least one valid next step.
• SC-129-06 Query discipline: All overview list surfaces are capped to bounded result sizes, and no uncontrolled polling is introduced by default.