# Operator UI Rebuild Backlog

## Purpose

Convert the protected `/console` prototype into a compact implementation backlog for the next Core Hub operator UI. This is not approval to rebuild every legacy Inter-Hub screen. The UI remains third in the sequence: API first, CLI second, web UI third.

The rebuild starts only after the deployed API smoke and operator CLI wrappers are stable enough for the UI to call the same resources and expose equivalent evidence. The first UI should stay read-heavy and operator-critical.

## Entry Gates

The first rebuild increment may start when all of these are true:

- `make deployed-smoke` has non-secret staging evidence for the target runtime;
- `make operator-cli` covers deployed smoke, ops-hub bootstrap status, migration validate/import, and readiness summary workflows;
- `make visual-check` passes for the protected prototype on desktop and mobile;
- every proposed screen has a named API resource and either an existing CLI equivalent or an explicit API/CLI gap item;
- secret custody remains outside the UI, DOM state, screenshots, State Hub notes, and workplan files.

## First Screens

| Priority | Screen | Operator job | API resources | CLI equivalent | First controls |
|---|---|---|---|---|---|
| P0 | Readiness overview | See whether Core Hub can replace Inter-Hub for the current stage. | `/healthz`, `/readyz`, `/api/v2/hub-registry`, `/api/v2/widgets`, `/api/v2/interaction-events` | `deployed-smoke`, `readiness-summary` | refresh, status filter, evidence link, source path label |
| P0 | Registry explorer | Inspect hubs, active manifests, widgets, and endpoint evidence. | `/api/v2/hubs`, `/api/v2/hub-capability-manifests`, `/api/v2/widgets`, `/api/v2/interaction-events`, `/api/v2/hub-registry` | `ops-bootstrap-status` | hub filter, status filter, manifest toggle, event drill-in |
| P0 | Evidence stream | Review recent non-secret operational evidence and smoke events. | `/api/v2/interaction-events`, deferred `/api/v2/outcome-signals`, deferred `/api/v2/deployment-records` | `deployed-smoke`, `readiness-summary` | type filter, time window, hub filter, copy evidence id |
| P0 | Migration and cutover | Review bundle validation/import evidence, dry-run status, and cutover gates. | API gap: expose migration runs before rebuilding beyond prototype DB reads. Current implementation has `MigrationRun` storage and migration import reports. | `migration validate`, `migration import`, `readiness-summary` | dry-run/import status, bundle hash, row counts, warning filter, rollback note |
| P1 | Action-required gates | Show only the operator actions that unblock replacement work. | `/api/v2/widgets`, `/api/v2/interaction-events`, deferred `/api/v2/decision-records`, deferred `/api/v2/deployment-records` | `readiness-summary` | severity filter, owner/source labels, open linked workplan/evidence |
| P1 | Access metadata panel | Confirm consumer/key-prefix state without credential exposure. | `/api/v2/api-consumers`; key creation remains an explicit operator action. | `ops-bootstrap-status`, `deployed-smoke` | consumer filter, status filter, key-prefix display, rotate action placeholder |

Access metadata is a support panel, not a primary expansion area. Mutating controls for key rotation, manifest activation, and task updates should wait until the read views are proven and the backing APIs have tests, CLI parity, and secret-custody review.

## Backlog Items

| Item | Scope | Done when |
|---|---|---|
| UI-RB-01 whynot asset decision | Choose deterministic static vendoring or package consumption for whynot-design CSS/custom elements and record the whynot-design git ref. | Rerunning the sync on unchanged whynot output produces no diff; drift note exists. |
| UI-RB-02 shell adapter | Replace inline prototype shell classes with whynot primitives for top nav, sidebar, page header, tags, tables, banners, empty states, field rows, and buttons. | `/console` still passes auth, non-secret, desktop, and mobile visual checks. |
| UI-RB-03 readiness overview | Build the first screen from API responses and evidence-report summaries, not direct database reads. | The screen names its source API paths and has a matching `readiness-summary` CLI evidence example. |
| UI-RB-04 registry explorer | Split registry state into a focused table/detail view for hubs, manifests, widgets, and events. | Data comes from protected `/api/v2` routes and `ops-bootstrap-status` reports the same readiness facts. |
| UI-RB-05 evidence stream | Add a dense interaction-event view with filter controls and stable evidence ids. | No secret fields render in DOM, screenshots, or test snapshots; event type and time filters are visual-checked. |
| UI-RB-06 migration API gap | Add a protected migration-run read API before a migration dashboard goes beyond prototype DB reads. | `/api/v2/migration-runs` or equivalent is tested, documented, and represented in OpenAPI. |
| UI-RB-07 migration dashboard | Build dry-run/import/cutover evidence view over migration reports and the migration-run API. | Dry-run reports stay visibly open; non-dry-run import evidence is required before cutover-ready. |
| UI-RB-08 action-required gates | Show a small gate list for readiness, registry, evidence, migration/cutover, and explicit human-action blockers. | Each gate has source evidence, owner/source label, and no free-form secret field. |
| UI-RB-09 visual and secret regression expansion | Extend `make visual-check` to every first-screen route and state. | Desktop/mobile screenshots, no-overlap checks, text overflow checks, protected-route checks, and full-key non-disclosure all pass. |

## whynot Consumption

Use whynot-design as the source of shared primitives rather than copying behavior by hand:

- application shell: `<wn-top-nav>` and `<wn-sidebar>`;
- headings and actions: `<wn-page-header>` and `<wn-button>`;
- dense data: `<wn-table>` or table classes from `components.css`;
- filters: `<wn-field-row>`, `<wn-input>`, `<wn-select>`, and `<wn-search-input>`;
- status: `<wn-tag>` and `<wn-stage-dot>`;
- blocked/degraded states: `<wn-banner>`;
- empty states: `<wn-empty-state>`;
- ordered migration stages: `<wn-pipeline>` only when the stage model is real.

Use the stable UI state vocabulary from `docs/specs/whynot-ui-adapter.md`: `draft`, `active`, `disabled`, `archived`, `superseded`, `wait`, `todo`, `progress`, `done`, `cancel`, `unverified`, `ready`, `degraded`, `blocked`, `fallback`, `validated`, `dry-run`, `imported`, `discrepancy`, `rolled-back`, `info`, `warn`, `fail`, and `critical`.

## Verification Rules

Every UI backlog item that reaches implementation must include:

- API tests for the backing route or fixture data;
- CLI parity evidence or a documented CLI gap;
- Playwright desktop and mobile screenshots;
- no horizontal page overflow;
- no overlap between major regions and first-order controls;
- text overflow checks for buttons, tags, navigation, counters, filters, and table headers;
- protected-route `401` verification;
- assertions that full API keys, bearer tokens, passwords, SSH material, provider tokens, and `fullKey` fields are absent from DOM and screenshots.

Generated screenshots and local evidence stay under `.local/` and are never committed.

## Explicit Non-Goals

Do not rebuild legacy Inter-Hub admin screens wholesale. Do not introduce a large SPA runtime until the thin server-rendered/custom-element route proves insufficient. Do not add bundle upload, secret entry, login, OIDC, MFA, SSH, provider-token, or database-password workflows to Core Hub UI; those belong to their owning custody systems and should surface only as non-secret routing/status references.