# operator-panel-navigation Specification

## Purpose
TBD - created by archiving change fix-operator-panel-tabs. Update Purpose after archive.
## Requirements
### Requirement: Operator panel groups capabilities under a three-layer information architecture

The operator panel SHALL organize all capabilities under exactly three conceptual groups: **Catalog**, **Runtime**, and **Integration**. Catalog contains configuration entities edited rarely with wide blast radius (`org_types`, `products`, `entitlement_sets`, `plan_ladders`). Runtime contains per-organization operational surfaces (organizations, persons, grants, billing read-views). Integration contains system-specific surfaces (FedWiki sites today; other integrations later).

The groups govern URL grouping, conceptual categorization, breadcrumb derivation, and the one-way `catalog → runtime → integration` dependency direction. Capabilities SHALL NOT appear at the operator panel's top level outside one of these three groups; the conceptual grouping is carried by each page's machine-readable IA-position declaration.

Sidebar **presentation** is a flat list of exactly eight section entries — no children, no indentation, no headed groups (maintainer decisions 2026-08-23: the sidebar names the sections; the sections navigate themselves; People joined as the eighth entry with the directory) — followed by exactly one non-section entry: the surface switch "Member dashboard", separated from the sections by the rail's border-top idiom, linking to `/`, never marked active (unify-shell; the only separated entry the rail may carry). The render order SHALL be: Overview, People, Organizations, Grants, Billing, Products, Domains, Integrations, then the surface switch. Second-level surfaces SHALL be reached in-page, not from the sidebar: person detail from the People directory's rows, `org_types` from the Organizations page's header affordance, the billing read-views from the Billing wrapper's in-page pill row, `entitlement_sets` and `plan_ladders` from the Products page's header affordances, and provider surfaces from the Integrations home's provider rows. The conceptual layer lives in the IA declarations; a second-level page SHALL mark its section's sidebar entry active. Below the `lg` breakpoint the same sidebar renders as a drawer opened from the shell's top bar (chrome-conventions, "One shell for both surfaces"); no other navigation to the sections exists.

#### Scenario: Catalog capabilities are reachable from within their task surfaces

- **WHEN** an operator views the Organizations page or the Products page
- **THEN** the Organizations page carries an affordance to `org_types`, and the Products page carries affordances to `entitlement_sets` and `plan_ladders`
- **AND** none of them appear in the sidebar
- **AND** their IA-position declarations still carry the Catalog conceptual group

#### Scenario: The sidebar is a flat list of section entries

- **WHEN** an operator views the operator panel sidebar
- **THEN** it renders exactly the eight entries Overview, People, Organizations, Grants, Billing, Products, Domains, Integrations in that order
- **AND** no child entries, indentation, or headed group blocks are rendered
- **AND** the only entry after the eight is the separated "Member dashboard" surface switch

#### Scenario: Sections navigate themselves

- **WHEN** an operator views an operator section with sub-surfaces
- **THEN** the sub-surfaces are reachable from within the section (the Billing wrapper's pill row, header affordances on the section's page, or the section's own rows)
- **AND** not from sidebar children

#### Scenario: Second-level pages mark their section active

- **WHEN** an operator is on a second-level page (for example person detail, org types, a billing view, or entitlement sets)
- **THEN** the sidebar marks that section's single entry (People, Organizations, Billing, or Products) as active, and no other

#### Scenario: The sidebar is reachable on phones

- **WHEN** an operator views any operator page below the `lg` breakpoint
- **THEN** the top bar's toggler opens the same sidebar as a drawer, sections first and the surface switch last

### Requirement: Operator panel exposes a curated landing surface at /operator

The operator panel SHALL render a curated landing surface at `/operator` that answers "what is this deployment doing right now?" rather than defaulting to the first capability tab. The landing surface SHALL be the default destination when an operator navigates to `/operator` without further path or query parameters. The surface SHALL present, coarsest-first: the setup banner while it applies (`operator-setup-checklist`), a lookup affordance, an at-a-glance overview region, a system-status region, and a recent-activity timeline (the order is the `Landing surface orders attention before totals` requirement's).

The landing-surface lookup affordance SHALL be a text input under the contract "every record that has a page of its own is findable by the identifier its page shows". The resolvers form one ordered registry in code, tried in order so a typed identifier wins over a substring: an exact key (organization, plan ladder, entitlement set, product); an exact invoice number; a person (name substring, email exact); an organization name (case-insensitive substring). Submitting the input SHALL resolve to the matched record's page (`/operator/persons/{personID}`, `/operator/organizations/{orgID}`, the keyed record's page, `/operator/billing/invoices/{invoiceID}`) when the match is unique, or to an inline disambiguation listing when several records match (persons by name substring; organizations by name; invoices sharing a number across billing accounts, each row showing number, organization, and date). Persons take precedence over organization names because every personal organization's name contains its owner's display name. The input's placeholder SHALL say what to type, not the record classes ("Find anything by its name, key, or number"); the no-match sentence SHALL name the classes, generated from the resolver registry so it cannot disagree with the code. A test SHALL assert that every detail route in the capture manifest has a resolver, so a record class joins the set when it gains a page. Resolution SHALL be performed server-side; no client-side autocomplete is required.

The at-a-glance region SHALL present three headline tiles: People, Team organizations, and Monthly recurring. The People tile SHALL count real people only, excluding the reserved system person the directory also hides, with its caption stating how many persons joined in the last 30 days. The organizations tile SHALL count deliberately created organizations: active organizations whose type is neither the auto-created `personal` type nor a reserved type. Personal orgs exist one-per-member by structural convention (an organizations count that includes them tracks the people count and reads as an error), and the negative-space predicate means `team`, `enterprise`, and deployment-defined types all count without code changes while the reserved system org never does. The Monthly recurring tile SHALL show the deployment's monthly recurring revenue in its largest currency bucket with its existing caption. The headline row is reserved for these three daily reads: open-invoice, delivery, and catalog counts SHALL NOT render as headline tiles (maintainer, 2026-09-02: "not that important"; the money tile stays), and per-feature counts (such as domain claims) SHALL NOT either — those surfaces are reached from the sidebar. Each tile SHALL link to its browse surface. Count sources SHALL degrade independently: a failed count query SHALL be logged and rendered as an explicit unavailable marker (an em dash) — NEVER as a zero, since a zero read off a broken query invites exactly the wrong operational conclusion — and SHALL NOT fail the page.

The recent-activity section SHALL be **a single unified timeline** that interleaves grant events, transition events, invoice events, and payment events from across the operator panel, ordered by event timestamp (newest first). Each rendered event row SHALL identify the organization (and person, where applicable) and link to the originating organization composite, the originating person detail, or the relevant billing page based on the event type. The section is one timeline because an operator's mental model of "what's been happening" is temporal, not domain-partitioned — an invoice payment that lands near the grant transition that triggered it is more useful adjacent than separated. Money amounts in event rows SHALL render as formatted currency (symbol/code and decimal placement per the console's standard money formatting), never as raw integer minor units. Tier events SHALL render in the vocabulary the organization composite's "Tier changes" list uses (humanized verbs and tier names, joined with a colon and "to": "Started: Basic", "Upgraded: Basic to Pro"), never as raw transition types, integer ranks, or em-dash separators.

The system-status region SHALL be one **Integrations** card, under a "System" section header whose single action is "Setup", linking to `/operator/setup`, always. The card SHALL list every registered provider, one row each in registry order, showing the provider's name as a link to its page (its admin page when it declares one; for Stripe, its provider page at `/operator/integrations/stripe`) and its single Status, the same three states the Integrations table shows (Disabled / Not configured / Configured, `integration-settings`). Stripe's row SHALL add, after its status, the mode ("Test mode" or "Live mode" from `stripe-mode`) and the queue ("n queued, n need attention" from the outbox), with alarm styling only when dead-lettered work exists. The region SHALL NOT carry the delivery-queue report, which lives on the Stripe provider page, and its copy SHALL NOT describe any state as "connected" or "read live" — the console performs no connectivity checks.

The landing surface's heading hierarchy SHALL descend without skipping levels (H1, then H2, …), and the surface's root page carries no location trail (`chrome-conventions`). The operator shell (page title, navbar brand) SHALL render the configured deployment name (`deployment-name`, defaulting to the generic product name), identically to the member surface, so the application presents one identity across surfaces; with the default value the shell remains deployment-neutral for screenshots and first impressions. The landing surface SHALL use the console's standard bordered-card presentation; it SHALL NOT introduce bespoke elevation or hover-motion card treatments absent from the rest of the console.

#### Scenario: Navigating to /operator shows the landing surface
- **WHEN** an authenticated operator navigates to `/operator`
- **THEN** the panel renders the curated landing surface
- **THEN** the landing surface includes the lookup entry point
- **THEN** the landing surface includes the at-a-glance region with the People, Team organizations, and Monthly recurring tiles
- **THEN** the landing surface includes the System section with its "Setup" action and the Integrations card
- **THEN** the landing surface surfaces a single recent-activity section interleaving grants, transitions, invoices, and payments

#### Scenario: Landing surface is the documented default
- **WHEN** an operator follows an internal link to `/operator` from anywhere in the panel
- **THEN** the landing surface renders instead of an arbitrary capability tab

#### Scenario: Lookup input resolves a unique person match
- **WHEN** an operator submits the lookup input with a value that matches exactly one person (by email or name substring) and no key or invoice number
- **THEN** the panel issues a 302 redirect to `/operator/persons/{personID}` for that match

#### Scenario: Lookup input resolves an organization by name
- **WHEN** an operator submits the lookup input with a value that matches no key, invoice number, or person and exactly one organization's name (case-insensitive substring)
- **THEN** the panel issues a 302 redirect to `/operator/organizations/{orgID}` for that organization

#### Scenario: Lookup input resolves an invoice number
- **WHEN** an operator submits the lookup input with a value equal to exactly one invoice's number
- **THEN** the panel issues a 302 redirect to `/operator/billing/invoices/{invoiceID}`
- **WHEN** several invoices across billing accounts carry that number
- **THEN** the panel renders a disambiguation listing showing each invoice's number, organization, and date, each linking to its detail

#### Scenario: Ambiguous organization names disambiguate
- **WHEN** an operator submits the lookup input with a value that matches no key, invoice number, or person and several organizations' names
- **THEN** the panel renders a disambiguation listing of those organizations, each linking to its composite

#### Scenario: Lookup input renders a disambiguation list on ambiguous match
- **WHEN** an operator submits the lookup input with a value that matches more than one person by name substring
- **THEN** the panel renders a disambiguation listing showing each candidate person
- **THEN** each candidate row links to `/operator/persons/{personID}` for that person

#### Scenario: Lookup input reports no match by naming what it searches
- **WHEN** an operator submits the lookup input with a value that matches nothing
- **THEN** the panel renders the landing surface with a visible no-match message that names every record class the registry resolves
- **THEN** no redirect occurs

#### Scenario: The placeholder names what to type
- **WHEN** an operator views the lookup input
- **THEN** its placeholder reads "Find anything by its name, key, or number" and lists no record classes

#### Scenario: Every page-bearing record class has a resolver
- **WHEN** the lookup registry test runs against the capture manifest's detail routes
- **THEN** each route's record class has a resolver in the registry

#### Scenario: Recent activity timeline interleaves event types
- **WHEN** an operator views `/operator` and any recent grant, transition, invoice, or payment events exist
- **THEN** the "Recent activity" section renders one row per event ordered by event timestamp (newest first), interleaving event types
- **THEN** each row identifies the organization (and person, where applicable) and its event type
- **THEN** each row links to the originating organization composite, person detail, or relevant billing page based on event type

#### Scenario: Tier events read as the composite reads them
- **WHEN** the timeline renders a transition event
- **THEN** the row uses the "Tier changes" vocabulary (for example "Started: Basic"), never a raw transition type, an integer rank, or an em-dash separator

#### Scenario: Activity money renders as formatted currency
- **WHEN** the recent-activity timeline renders an invoice or payment event carrying a money amount
- **THEN** the amount renders as formatted currency with its currency named
- **THEN** no row renders a raw integer of minor units (e.g. "3600 usd")

#### Scenario: Organizations headline excludes auto-created personal orgs
- **WHEN** an operator views `/operator` on a deployment holding personal orgs, team orgs, and the reserved system org
- **THEN** the organizations tile counts only active organizations that are neither `personal`-typed nor reserved-typed
- **THEN** its caption states the exclusion so the number is self-interpreting

#### Scenario: People counts real people only
- **WHEN** an operator views `/operator` on a deployment whose only person rows are the reserved system person and two members
- **THEN** the People tile reads 2, matching the directory's total

#### Scenario: People caption carries the 30-day trend
- **WHEN** an operator views `/operator`
- **THEN** the People tile's caption states how many persons joined in the last 30 days

#### Scenario: Headline row carries only the three daily reads
- **WHEN** an operator views `/operator`
- **THEN** the at-a-glance region renders the People, Team organizations, and Monthly recurring tiles and no open-invoice, delivery, catalog, or per-feature count
- **THEN** those surfaces remain reachable from the sidebar

#### Scenario: Landing cards use the console's standard idiom
- **WHEN** the landing surface renders
- **THEN** its cards render with the console's standard bordered-card treatment
- **THEN** no card carries a bespoke elevation (shadow) or hover-motion treatment

#### Scenario: A failed count degrades to an unavailable marker, not a zero
- **WHEN** an operator views `/operator` and one metric's backing query fails
- **THEN** that tile renders an em dash with an unavailable caption instead of a value
- **THEN** every other tile renders its real value
- **THEN** the page returns 200 and the failure is logged

#### Scenario: The Integrations card lists every provider with one status
- **WHEN** an operator views `/operator` with FedWiki, Discourse, and Stripe registered, Discourse unconfigured, and Stripe configured in test mode with two dead-lettered outbox entries
- **THEN** the Integrations card shows three rows: FedWiki with its status, Discourse reading "Not configured", and Stripe reading "Configured", "Test mode", and "2 queued, 2 need attention" with alarm styling
- **THEN** each provider's name links to its page, Stripe's to `/operator/integrations/stripe`
- **THEN** the card carries no dead-letter table and no operation identifiers

#### Scenario: The System header always offers Setup
- **WHEN** an operator views `/operator`, setup complete or not, banner dismissed or not
- **THEN** the System section header carries one action, "Setup", linking to `/operator/setup`

#### Scenario: Shell renders the configured deployment name
- **WHEN** any operator page renders
- **THEN** the page title and navbar brand render the configured deployment name, matching the member surface
- **THEN** with no name configured, the shell renders the generic product name and stays deployment-neutral

#### Scenario: Landing heading hierarchy has no skips
- **WHEN** an operator views `/operator`
- **THEN** the document outline descends H1 → H2 (→ H3) with no skipped levels

### Requirement: People caption counts the same population as the tile

The People tile's 30-day caption SHALL count the same population as its headline: active persons excluding the reserved system person, detected structurally as the owner of the reserved system organization, never by name or email. The exclusion SHALL be a parameter of the count query in the shape the people directory already uses, so the headline, the caption, and the directory total cannot diverge by the system person.

#### Scenario: Fresh deployment inside the window

- **WHEN** an operator views `/operator` on a deployment created within the last 30 days whose person rows are the reserved system person and thirteen members
- **THEN** the People tile reads 13
- **AND** its caption states that 13 persons joined in the last 30 days

#### Scenario: System person outside the window changes nothing

- **WHEN** the reserved system person was created more than 30 days ago and two members joined this month
- **THEN** the caption states that 2 persons joined in the last 30 days


### Requirement: Per-organization composite view is addressable at /operator/organizations/{orgID}

The operator panel SHALL provide a per-organization composite view at the route `/operator/organizations/{orgID}` that co-locates enrollment state, grant history, billing summary, member roster, and grant actions for one organization. The route SHALL be bookmarkable and reload-stable. The composite view SHALL be reachable from the Runtime group's organization browse surface.

The billing-summary section SHALL show: the current subscription status and plan (if any), the next renewal date (if any), the most recent invoice (date, amount, paid status), and the outstanding balance across unpaid invoices. The section SHALL link out to `/operator/billing/accounts` for the full billing view.

The members section SHALL list all persons enrolled at the organization, sorted alphabetically by display name. Each row SHALL link to the person's resolved-detail view at `/operator/persons/{personID}`.

#### Scenario: Per-org composite view is bookmarkable
- **WHEN** an operator loads `/operator/organizations/{orgID}` directly via URL
- **THEN** the page renders the composite view for that organization without requiring prior navigation through the panel

#### Scenario: Composite view co-locates runtime work
- **WHEN** an operator views `/operator/organizations/{orgID}`
- **THEN** the page surfaces the organization's enrollment state, grant history, billing summary, and member roster on the same page
- **THEN** grant actions (issue, extend, revoke) are reachable from the same page without navigating to a different top-level capability

#### Scenario: Composite view exposes a billing summary
- **WHEN** an operator views `/operator/organizations/{orgID}` for an organization with billing activity
- **THEN** the page renders a billing-summary section showing current subscription status, next renewal date, most recent invoice (date, amount, paid status), and outstanding balance
- **THEN** the section links to the full billing view at `/operator/billing/accounts`

#### Scenario: Composite view exposes a member roster
- **WHEN** an operator views `/operator/organizations/{orgID}` for an organization with enrolled members
- **THEN** the page renders a members section listing each enrolled person sorted alphabetically by display name
- **THEN** each member row links to `/operator/persons/{personID}` for that person

### Requirement: Per-organization composite view is the sole UI entry point for grant actions

The operator panel SHALL expose grant action affordances (issue, extend, revoke) only from the per-organization composite view. The global Grants surface in the Runtime group SHALL be read-only — it presents grants for browse/audit/lookup but exposes no action affordances. Underlying HTTP handlers (e.g. the simple `RevokeGrant`, the legacy `CreateGrant` issuance path) MAY remain reachable by direct URL for programmatic callers but SHALL NOT be surfaced as operator UI affordances.

Grant issuance SHALL be exposed as a single product-based form on the per-organization composite view. The form's product picker SHALL list published products available to the organization, including internal wrap products, which SHALL be visually marked as internal in the picker; the picker SHALL NOT be partitioned into intent-labeled variants by catalog shape (no separate "plan" picker and "non-plan" picker). Whether the resulting conferral is position-bearing (occupies a ladder rung) SHALL be derived by the `entitlement-conferral` capability's `confer` primitive from the product's catalog shape (`billing.product_conferral_shapes`) — the operator SHALL NOT select or declare this behavior on the form. The form SHALL carry uniform bounds — an optional `quantity` and an optional `valid_until` — available for any product regardless of catalog shape, and a `grant_reason` select restricted to the fixed domain excluding `'default'`. The full semantics of grant issuance (conferral derivation, the uniform-bounds contract, the `grant_reason` domain, and expiration scheduling) are specified by the `plan-enrollment-administration` capability's "Operator grant issuance" requirement; this requirement governs only the composite view's role as the sole UI entry point and the single-form shape of that entry point, not conferral behavior itself.

Grant revocation SHALL be enacted by the decree-first, source-resolved revoke behavior owned by the `plan-enrollment-administration` capability's "Operator grant revocation" requirement: the entry point sets the grant's `revoked_*` ledger fields and then calls `entitlements.end_conferral` resolved by the grant's own source, ending only the provision that grant itself delivered. Ending a provision SHALL NOT re-mint the org-type default as a side effect — re-application of the org default, when desired, is a separate `ReapplyDefaultsForPool` call (owned by `auto-provisioning`, per `plan-transitions`). This requirement governs only the composite view's role as the sole UI entry point for revocation, not the revoke semantics themselves; no Revoke affordance SHALL be surfaced outside the per-organization composite view.

#### Scenario: Per-org view exposes revoke using the source-resolved behavior
- **WHEN** an operator views `/operator/organizations/{orgID}`
- **THEN** each active grant for the organization has a Revoke affordance
- **THEN** invoking Revoke sets the grant's `revoked_*` fields and calls `end_conferral` resolved by the grant's source, ending only that grant's own provision (`end_conferral` itself never re-applies the org default; the entry point then performs the guarded baseline restoration owned by `plan-enrollment-administration`, which runs only when the default ladder is left vacant)

#### Scenario: Per-org view exposes a single issuance form for any published product
- **WHEN** an operator views `/operator/organizations/{orgID}`
- **THEN** the page exposes exactly one grant issuance form
- **THEN** the form's product picker lists published products available to the organization, with internal wrap products marked as internal
- **THEN** no separate plan-typed and non-plan-typed issuance forms exist
- **THEN** the form exposes uniform bounds (`quantity`, `valid_until`) and a `grant_reason` select over the fixed domain excluding `'default'`, regardless of which product is picked

#### Scenario: Per-org view exposes extension
- **WHEN** an operator views `/operator/organizations/{orgID}`
- **THEN** each active grant has an Extend affordance that issues an extend-as-replace with new bounds (a new lineaged grant consumed by `confer`, per the `plan-enrollment-administration` capability), never mutating the incumbent grant in place

#### Scenario: Global Grants surface exposes no action affordances
- **WHEN** an operator views the global Grants surface in the Runtime group
- **THEN** the grant rows render in a read-only listing
- **THEN** no Issue, Extend, or Revoke affordance appears on the surface

### Requirement: Every operator page declares its IA position for breadcrumb derivation

Every operator panel page SHALL declare its position in the IA as a positional tuple of the form `(group, capability)` or `(group, capability, instance)`, where `group` is one of `catalog`, `runtime`, or `integration`, `capability` is the capability slug (e.g. `products`, `organizations`), and `instance` is present when the page is scoped to one entity (e.g. an organization's composite view). The visual rendering of breadcrumbs is out of scope for this specification.

#### Scenario: Capability index page declares its IA position
- **WHEN** an operator loads `/operator/products`
- **THEN** the page declares its IA position as `(catalog, products)`

#### Scenario: Instance page declares its IA position
- **WHEN** an operator loads `/operator/organizations/{orgID}`
- **THEN** the page declares its IA position as `(runtime, organizations, {orgID})`

### Requirement: Browse routes reserve query-parameter real estate for filters

Browse routes under the operator panel (e.g. `/operator/organizations`, `/operator/products`, `/operator/plan-ladders`) SHALL reserve the query parameters `?q=<search>` and `?<facet>=<value>` (where `<facet>` is a capability-appropriate field such as `org_type`, `lifecycle_status`) as the canonical shape for future filter additions. Browse routes SHALL NOT use these parameter names for unrelated purposes. Implementing visible filter controls is out of scope for this specification; the reservation establishes URL contract only.

#### Scenario: Reserved parameter names are not reused
- **WHEN** a new feature is added to a browse route
- **THEN** the feature SHALL NOT use `q`, `org_type`, `lifecycle_status`, or other established facet parameter names for any purpose other than search and filtering

#### Scenario: Unknown filter params do not error
- **WHEN** an operator loads a browse route with a reserved-but-unimplemented filter param (e.g. `/operator/organizations?q=acme`)
- **THEN** the route renders without error
- **THEN** the unimplemented filter is ignored rather than rejected

### Requirement: Operator panel uses MPA routing with hx-boost for in-panel navigation

The operator panel SHALL serve each top-level capability at its own route under `/operator/<capability>` and return full HTML responses (not HTMX fragments) from those routes. In-panel navigation SHALL use `hx-boost` applied at the layout shell so navigations produce real browser history entries and bookmarkable URLs while avoiding full-document reparse. Under htmx 4's explicit inheritance, the shell SHALL mark the boost and the CSRF header for descendants (`hx-boost:inherited`, `hx-headers:inherited` on the shell `<body>`), and links that must not be boosted (the identity-provider handoff, sign-out) override with their own `hx-boost="false"`.

The set of top-level capability routes SHALL include:

- `/operator` (curated landing surface — see the landing-surface requirement)
- `/operator/persons` (runtime browse directory — see `operator-people-directory`) and `/operator/persons/{personID}` (per-person detail — see the person-detail requirement)
- `/operator/organizations` (runtime browse) and `/operator/organizations/{orgID}` (per-org composite — see the composite-view requirement)
- `/operator/grants` (runtime browse, read-only — see the grant-action-consolidation requirement)
- `/operator/billing/{accounts,subscriptions,invoices,payments}` (runtime read-views) and `/operator/billing/invoices/{invoiceID}` (per-invoice detail — see `operator-billing-views`)
- `/operator/org-types`, `/operator/products`, `/operator/entitlement-sets`, `/operator/plan-ladders` (catalog)
- `/operator/products/{productID}` (catalog, per-product composite — see the addressable-composite requirement)
- `/operator/plan-ladders/{ladderID}` (catalog, per-ladder composite — see the addressable-composite requirement)
- `/operator/entitlement-sets/{setID}` (catalog, per-entitlement-set composite — see the addressable-composite requirement)
- `/operator/integrations/fedwiki` (integration; the legacy `/operator/fedwiki-sites` path 301-redirects here)

#### Scenario: Top-level capability route is bookmarkable

- **WHEN** an operator loads any top-level capability route (e.g. `/operator/products`) directly via URL
- **THEN** the page renders the full capability surface
- **THEN** no prior navigation through `/operator` is required

#### Scenario: Unknown operator paths stay in the operator shell

- **WHEN** an operator loads a `/operator/*` path no page claims (e.g. a truncated or mistyped URL)
- **THEN** the response SHALL be HTTP 404 rendered inside the operator shell with a link back to the operator overview
- **AND** it SHALL NOT fall through to the member-facing dashboard

#### Scenario: In-panel navigation uses hx-boost

- **WHEN** an operator clicks any in-panel navigation link
- **THEN** the navigation is intercepted by `hx-boost` and the response replaces the layout's main content region
- **THEN** the browser's URL bar and history reflect the destination route
- **THEN** a manual page reload at that URL renders the same page

#### Scenario: A back navigation restores by re-fetching the full page

- **WHEN** an operator navigates or filters (pushing URLs into history) and presses the browser back button
- **THEN** htmx re-fetches the previous URL and receives the full page (the panel serves no fragments at pushed URLs)
- **THEN** the restored view renders correctly inside the shell with no cached-snapshot artifacts

#### Scenario: Toast container and modal survive boosted navigation

- **WHEN** an operator triggers a `HX-Trigger: showSuccessToast` response on a POST that redirects to a different capability
- **THEN** the success toast renders after the boosted navigation completes
- **THEN** the toast container and the confirm-action modal are outside the boost swap target so they are not destroyed by the swap

### Requirement: Legacy ?tab= URLs redirect for one release

The operator panel SHALL handle legacy `/operator?tab=<tab-id>` URLs by issuing a 301 redirect to the equivalent top-level capability route for the duration of one release. After that release the shim SHALL be removed and `/operator?tab=<anything>` SHALL render the landing surface (the unknown filter param is ignored per the reserved-filter-params requirement).

#### Scenario: Known ?tab= redirects to capability route

- **WHEN** an operator loads `/operator?tab=organizations`
- **THEN** the panel issues a 301 redirect to `/operator/organizations`

#### Scenario: ?tab=people redirects to the landing surface

- **WHEN** an operator loads `/operator?tab=people`
- **THEN** the panel issues a 301 redirect to `/operator` (since persons is lookup-only — no top-level browse exists)

#### Scenario: Unknown ?tab= renders landing

- **WHEN** an operator loads `/operator?tab=<unknown-id>` after the shim is removed
- **THEN** the landing surface renders without error
- **THEN** the `tab` parameter is ignored per the reserved-filter-params requirement

### Requirement: Operator panel exposes a plan-topology overview under the Catalog group

The plan-topology overview is no longer a separate destination: the Plan Ladders surface at `/operator/plan-ladders` SHALL open with the topology overview (the cross-ladder grid and structural-health strip, per the `operator-topology-overview` capability, whose requirements hold unchanged at this home) as its map-first view, with ladder management beneath it. The overview's IA position is the Catalog conceptual group via the Plan Ladders page's declaration. `/operator/plan-topology` SHALL NOT be a route: with no production deployments there is no old URL to stay compatible with, so no redirect exists and the path receives the operator panel's ordinary 404 handling.

#### Scenario: Ladders surface opens map-first

- **WHEN** an authenticated operator navigates to `/operator/plan-ladders`
- **THEN** the topology grid and health strip render as the surface's opening view
- **AND** ladder management (list, create) renders on the same surface beneath or behind the map

#### Scenario: The old topology URL is gone, not redirected

- **WHEN** an operator requests `/operator/plan-topology`
- **THEN** the panel answers with its ordinary 404 handling, not a redirect

### Requirement: Provider admin surfaces resolve from the registry, not a hardcoded map

The operator panel SHALL resolve a provider resource's admin surface from the provider registry rather than from a hardcoded resource-key→surface map. Adding or removing a provider SHALL NOT require editing a navigation map in code. Provider surfaces are presented within the dedicated Integrations section (see "Operator panel exposes a dedicated Integrations section"); this requirement governs only how each surface link is *resolved* (from the registry), not where the section lives.

#### Scenario: Provider surface is registry-resolved

- **WHEN** the operator panel renders the admin-surface link for a provisioning provider
- **THEN** the link URL SHALL be obtained from the provider registry
- **AND** SHALL NOT be obtained from a hardcoded resource-key→surface map

#### Scenario: Adding a provider requires no navigation-map edit

- **WHEN** a new provisioning provider is registered
- **THEN** its admin surface SHALL become reachable without editing any hardcoded resource-key→surface map in code

#### Scenario: FedWiki surface resolves under its provider identity

- **WHEN** an operator opens FedWiki's admin surface
- **THEN** it SHALL be resolved via the registry for provider `fedwiki` (resource `fedwiki_sites`)
- **AND** SHALL NOT be resolved via a literal `"sites"` map entry

### Requirement: Operator panel exposes a dedicated Integrations section

The operator panel SHALL present integrations as a dedicated, registry-driven section, distinct from the catalog and runtime groups. The sidebar SHALL render a single "Integrations" entry that links to a section landing at `/operator/integrations`; provider surfaces are reached from that landing's rows, not from sidebar children (maintainer decision 2026-08-23), and integration admin pages and settings pages SHALL mark the "Integrations" entry active. The landing SHALL be registry-driven and SHALL list every registered provider of every kind in one table — a payments provider appears alongside provisioning ones, never as a half-present entry — showing each provider's display name as the row's link to the provider's page (its admin surface when it declares one; for Stripe, its provider page at `/operator/integrations/stripe`, `integration-settings`), one Status column carrying the provider's single honest state (`integration-settings`), kind, declared lifecycle operations, owned resource keys, and one Settings action linking to `/operator/integrations/{integrationKey}/settings` (when the integration declares configuration — sourced from the adapter registry). No "Manage" control renders: navigation is the name link. Integration admin pages SHALL live under the `/operator/integrations/` URL namespace, SHALL open with a heading identifying the integration and, when the integration declares a description, that description as the page's lead, and SHALL cross-link to their settings page; settings pages SHALL cross-link back to the admin page. Adding or removing a provider, or an adapter with declared configuration, SHALL change the landing without any template or handler edit. Per-key configuration writes live on the linked settings pages, not on the landing; the landing's only write affordance is the unrecognized-override cleanup (see `integration-settings`), which SHALL be gated behind the shared confirm-action modal.

#### Scenario: Sidebar shows the Integrations section home

- **WHEN** an operator views any operator page
- **THEN** the sidebar SHALL include a single "Integrations" entry linking to `/operator/integrations`
- **AND** no per-provider sidebar entries render
- **AND** an integration admin page or settings page marks the "Integrations" entry active

#### Scenario: Integrations landing lists registered providers from the registry

- **WHEN** an operator opens `/operator/integrations`
- **THEN** the page SHALL list each registered provider of every kind with its display name, one Status, kind, declared lifecycle operations, and owned resource keys
- **AND** for FedWiki the display name SHALL link to `/operator/integrations/fedwiki`
- **AND** a payments provider (e.g. Stripe) SHALL have a row whose display name links to its provider page
- **AND** the listing SHALL be derived from the provider registry, not a hardcoded list

#### Scenario: Adding a provider populates the section without code edits

- **WHEN** a second conforming provisioning provider is registered
- **THEN** it SHALL appear on the `/operator/integrations` landing with its name link and Settings action
- **AND** no operator template or page handler SHALL require editing for it to appear

#### Scenario: Empty state when no provisioning providers are registered

- **WHEN** `/operator/integrations` is opened and no provisioning provider is registered
- **THEN** the page SHALL render an empty state rather than an error

#### Scenario: Settings links cover every configuring adapter

- **WHEN** an operator opens `/operator/integrations`
- **THEN** every registered integration adapter that declares configuration SHALL have a Settings action linking to `/operator/integrations/{integrationKey}/settings` on its row, and no other action
- **AND** an adapter that is not a provisioning provider (e.g. a payments integration) SHALL still get its link
- **AND** the links SHALL be derived from the adapter registry, not a hardcoded list

#### Scenario: A provider page leads with the integration's description

- **WHEN** an integration declares a description and an operator opens its page
- **THEN** the page header's lead is that description

### Requirement: Per-product, per-plan-ladder, and per-entitlement-set composite views are addressable

The operator panel SHALL provide a per-product composite view at `/operator/products/{productID}`, a per-plan-ladder composite view at `/operator/plan-ladders/{ladderID}`, and a per-entitlement-set composite view at `/operator/entitlement-sets/{setID}`. Each route SHALL render a full operator page (the operator shell), SHALL be bookmarkable and reload-stable, and SHALL be reachable from its capability's browse list via boosted in-panel navigation (a real `<a href>` under the shell's `hx-boost`), not via a fragment swap that leaves the URL unchanged. Each instance page SHALL declare its IA position as the `(group, capability, instance)` tuple — `(catalog, products, {productID})`, `(catalog, plan-ladders, {ladderID})`, and `(catalog, entitlement-sets, {setID})`.

The product composite SHALL co-locate, on the one URL, the product edit form, the product's prices view, and the purchasability/readiness panel including the Sync-to-Stripe action. The plan-ladder composite SHALL co-locate, on the one URL, the ladder edit form, the ladder's tier/rank manager, and the structural-invariant validation surface for that ladder. The entitlement-set composite SHALL co-locate, on the one URL, the entitlement-set edit form and the rules manager (rule list, add-rule form, and per-rule delete).

#### Scenario: Product composite is bookmarkable

- **WHEN** an operator loads `/operator/products/{productID}` directly via URL
- **THEN** the page renders the composite view for that product without requiring prior navigation through the panel

#### Scenario: Product composite is reachable from the browse list via boosted navigation

- **WHEN** an operator activates a product's link on the `/operator/products` browse list
- **THEN** the navigation targets `/operator/products/{productID}` as a real route under `hx-boost`
- **THEN** the browser URL and history reflect `/operator/products/{productID}`
- **THEN** a manual reload at that URL renders the same composite page

#### Scenario: Product composite co-locates editing, prices, and readiness

- **WHEN** an operator views `/operator/products/{productID}`
- **THEN** the page surfaces the product edit form, the product's prices view, and the purchasability/readiness panel (including the Sync-to-Stripe action when applicable) on the same page

#### Scenario: Plan-ladder composite is bookmarkable

- **WHEN** an operator loads `/operator/plan-ladders/{ladderID}` directly via URL
- **THEN** the page renders the composite view for that ladder without requiring prior navigation through the panel

#### Scenario: Plan-ladder composite is reachable from the browse list via boosted navigation

- **WHEN** an operator activates a ladder's link on the `/operator/plan-ladders` browse list
- **THEN** the navigation targets `/operator/plan-ladders/{ladderID}` as a real route under `hx-boost`
- **THEN** the browser URL and history reflect `/operator/plan-ladders/{ladderID}`

#### Scenario: Plan-ladder composite co-locates editing, tiers, and validation

- **WHEN** an operator views `/operator/plan-ladders/{ladderID}`
- **THEN** the page surfaces the ladder edit form, the tier/rank manager, and the structural-invariant validation surface for that ladder on the same page

#### Scenario: Entitlement-set composite is bookmarkable and co-locates editing and rules

- **WHEN** an operator loads `/operator/entitlement-sets/{setID}` directly via URL
- **THEN** the page renders the composite view for that entitlement set without requiring prior navigation through the panel
- **THEN** the page surfaces the entitlement-set edit form and the rules manager (rule list, add-rule form, and per-rule delete) on the same page

#### Scenario: Entitlement-set composite is reachable from the browse list via boosted navigation

- **WHEN** an operator activates an entitlement set's link on the `/operator/entitlement-sets` browse list
- **THEN** the navigation targets `/operator/entitlement-sets/{setID}` as a real route under `hx-boost`
- **THEN** the browser URL and history reflect `/operator/entitlement-sets/{setID}`

#### Scenario: Instance pages declare their IA position

- **WHEN** an operator loads `/operator/products/{productID}`
- **THEN** the page declares its IA position as `(catalog, products, {productID})`
- **WHEN** an operator loads `/operator/plan-ladders/{ladderID}`
- **THEN** the page declares its IA position as `(catalog, plan-ladders, {ladderID})`
- **WHEN** an operator loads `/operator/entitlement-sets/{setID}`
- **THEN** the page declares its IA position as `(catalog, entitlement-sets, {setID})`

### Requirement: Landing surface carries setup as a banner and a standing action

While any step of the operator setup checklist (see `operator-setup-checklist`) derives incomplete and the banner has not been dismissed, the curated landing surface at `/operator` SHALL render the getting-started banner above the lookup, linking to `/operator/setup`. The banner's copy, its close control, and the deployment-wide dismissal it records are `operator-setup-checklist`'s to define; this surface only places it. Once every step derives complete the banner SHALL NOT render. The checklist SHALL remain reachable whatever the banner does: the System section header SHALL always carry one action, "Setup", linking to `/operator/setup`. The banner and the header action derive from the same predicates as the checklist, so the landing surface and the checklist never disagree.

#### Scenario: Fresh instance leads with the banner, not zeros

- **WHEN** an operator visits `/operator` on a deployment where no checklist
step is complete and no dismissal is recorded
- **THEN** the getting-started banner renders above the lookup, ahead of the metric tiles
- **AND** it links to `/operator/setup`

#### Scenario: Configured instance shows no banner

- **WHEN** an operator visits `/operator` on a deployment where every
checklist step derives complete
- **THEN** the landing surface renders without the banner

#### Scenario: Setup stays reachable from the System header

- **WHEN** an operator visits `/operator` with the banner dismissed or every step complete
- **THEN** the System section header still carries its "Setup" action linking to `/operator/setup`

### Requirement: Landing surface orders attention before totals and links its content

The curated landing surface SHALL order its regions with the operator's daily reads first: the setup banner while it applies (`operator-setup-checklist`), then the lookup, then the at-a-glance metric tiles, then the system-status region (the Integrations card under the System header), then recent activity — the counts an operator checks every day outrank the system cards (maintainer decision 2026-08-23), and attention-shaped content is still never the page's last region. Activity-feed entries SHALL link to the subject's surface wherever an addressable one exists (the organization, invoice, or grant the entry describes), so no feed entry is a dead end when a destination exists.

#### Scenario: Metric tiles render ahead of the system cards

- **WHEN** an operator views `/operator`
- **THEN** the at-a-glance tiles render before the system-status region
- **AND** the system-status region renders before recent activity, so attention-shaped content (queued work needing attention, unconfigured integrations) is not the last region on the page

#### Scenario: Feed entries link to their subjects

- **WHEN** the recent-activity feed shows an entry about an entity with an addressable operator surface
- **THEN** the entry links to that surface

### Requirement: Person detail is addressable and cross-linked

The person-detail view at `/operator/persons/{personID}` SHALL be bookmarkable (no prior navigation required) and reachable from the People directory's rows, the landing-surface lookup affordance, and organization member tables. It SHALL include an organization-memberships section listing each organization the person belongs to, each row linking to that organization's composite view at `/operator/organizations/{orgID}`.

#### Scenario: Person detail is bookmarkable

- **WHEN** an operator loads `/operator/persons/{personID}` directly via URL
- **THEN** the page renders the resolved-detail view for that person

#### Scenario: Person detail is reachable from organization context

- **WHEN** an operator views an organization's member listing on `/operator/organizations/{orgID}`
- **THEN** each member row links to `/operator/persons/{personID}` for that member

#### Scenario: Person detail exposes organization memberships

- **WHEN** an operator views `/operator/persons/{personID}` for a person who belongs to one or more organizations
- **THEN** the page renders an organization-memberships section listing each organization the person belongs to
- **THEN** each row links to `/operator/organizations/{orgID}` for that organization

### Requirement: The surface switches name the panels

The operator rail's surface switch SHALL read "Member panel" and link to `/`; the member rail's surface switch SHALL read "Operator panel" and link to `/operator`, so the two switches name the two surfaces alike.

#### Scenario: The switches mirror each other

- **WHEN** an operator views the operator rail and the member rail
- **THEN** the operator rail's switch reads "Member panel" and the member rail's reads "Operator panel"

### Requirement: The landing surface's lookup is a search form

The landing surface's lookup affordance SHALL be a declared form of the search kind, rendered through the `form` part in the bar family (`form-library`, design D4, D20). It SHALL submit by GET, carry a native `action` naming its route, and send no CSRF header, so it keeps a true native fallback: without JavaScript the lookup navigates and resolves exactly as it does with JavaScript. It SHALL NOT be a POST, because a mutation form's request path (the `X-CSRF-Token` header) is the one the console reserves for writes, and a lookup writes nothing. Its input SHALL carry a label, visually hidden where the row has no room, and `autocomplete="off"`. It SHALL declare `Wide`, so the bar spans the content column rather than stopping at the width a list's own search takes: it is the landing surface's primary control and its width says so. Its button SHALL render `btn-outline-secondary` like every other search's, with no exception for this one (maintainer, 2026-09-04). The lookup SHALL take its row in the progressive-enhancement table in `docs/design-system.md` beside the operator list controls, as the search kind's second entry (`form-conventions`, "Every mutation form's no-JS behavior is a recorded decision"; finding FA-24, correction 8).

#### Scenario: The lookup resolves without JavaScript

- **WHEN** JavaScript is unavailable and an operator submits the lookup with a value that matches exactly one record
- **THEN** the browser performs the form's native GET and lands on that record's page, the same destination the scripted path reaches

#### Scenario: The lookup is a GET with a native action

- **WHEN** an operator views the landing surface
- **THEN** the lookup form renders `method="get"` with an `action` naming its route, and carries no CSRF header attribute

#### Scenario: The lookup is a wide bar with an outline button

- **WHEN** an operator views the landing surface
- **THEN** the lookup renders as one input group spanning the content column, with the magnifier, the control and a `btn-outline-secondary` "Look up" on one line

#### Scenario: The lookup's row is in the table

- **WHEN** a reader consults the progressive-enhancement table in the design system
- **THEN** the lookup appears there as a search-kind form with its native GET fallback recorded, beside the list controls

### Requirement: The landing surface is built from the parts

The landing surface's regions (At a glance, System, Recent activity) SHALL be titled through `sectionHeader`, `h2.h5` in normal case with the part's spacing; the System header's one action, "Setup", SHALL be the part's action. The at-a-glance tiles SHALL be `readout` parts inside linked cards (page-anatomy "A linked card is marked by a glyph and the row's hover"), each card the link to its browse surface, marked by the chevron glyph and the hover shade, the number at the readout's one size. The Integrations card SHALL carry no title of its own; its providers SHALL render as a flush list in the card's body, one row each, the same idiom the setup checklist uses. The recent-activity table SHALL be a boxed ledger like the organization composite's: inside the card's body, a record table with a plain header row, body-size cells, the event's summary as the row's primary cell and first column, and the time last (Summary, Event, Organization, Actor, When), paged through the list scaffold's pager with its own namespaced parameters so the lookup and the pager never disturb each other. The surface SHALL write no uppercase text and no `<h2>` of its own. Its title stays "Operator overview": a panel's home is titled for the panel, and its rail entry is the short name of the way back (maintainer, 2026-09-06, "Panel homes need no rail").

#### Scenario: The overview reads like its neighbours

- **WHEN** an operator views `/operator` beside `/operator/organizations/{orgID}` and the member dashboard
- **THEN** the section titles are the same size and case, the sections sit at the same rhythm, and no number on the overview is larger than its page title

#### Scenario: A tile is one link, marked

- **WHEN** an operator views `/operator`
- **THEN** each tile's card is the anchor to its browse surface, carries the chevron glyph, and nothing inside the tile is a link

#### Scenario: The feed pages like the composite's ledgers

- **WHEN** the deployment has more activity than one page of the feed holds
- **THEN** the feed shows its first page with the pager's "Showing" line and page controls under the table, and turning the page re-renders only the feed's panel