core-hub/docs/specs/operator-ui-rebuild-backlog.md

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.