core-hub/docs/specs/ui-operator-console.md

# UI and Operator Console Spec

## Purpose

Define the Core Hub operator interface without coupling the framework to one UI runtime.

## UI Direction

- Use whynot-design tokens and component semantics where possible.
- Prefer custom-element/Lit adapters for framework-neutral surfaces.
- Keep the canonical UI contract separate from generated or hand-authored implementation code.
- Use Playwright visual checks once UI components exist.
- Treat the console as an operational tool: dense, readable, stable, and built for repeated review.

## Console Information Architecture

The first console should use a persistent shell with top-level operational areas. Each area maps to Core Hub API/resources so the UI can be implemented as server-rendered HTML, HTMX fragments, Lit components, or another thin adapter without changing the framework contract.

| Area | Purpose | Primary resources | Expected actions |
|---|---|---|---|
| Overview | Show system health, open blockers, recent progress, and readiness gates. | health, workplans, tasks, progress, migration runs | refresh, filter by severity, open linked record |
| Hub registry | Inspect hubs, active manifests, declared capabilities, widgets, and events. | hubs, hub capability manifests, widgets, interaction events | register hub, activate manifest, inspect capability |
| Workplans | Review active workplans, tasks, status drift, and human-needed items. | workplans, tasks, consistency reports | change task status, mark human review, open file reference |
| Event stream | Read recent interaction events, progress notes, and operational evidence. | interaction events, progress, outcome signals | filter by hub, task, event type, time window |
| Decisions | Browse decisions, deployment records, requirements, and evidence links. | decision records, deployment records, requirements | record decision, link evidence, mark superseded |
| Access | Manage API consumers and non-secret key metadata. | API consumers, API keys, policy scopes | create consumer, rotate key, disable consumer |
| Migration | Track Inter-Hub import readiness, migration bundles, row counts, discrepancies, smokes, rollback state. | migration runs, compatibility fixtures, deployment records | validate bundle, inspect dry-run, mark staging import reviewed |
| Messages | Coordinate agents and operators without exposing credentials. | messages, inbox, progress notes | read, reply, mark read, link to workplan |

## Screen Model

Every screen should expose the same operational primitives:

- title and short status line;
- filter controls for status, severity, source hub, owner, and time window where relevant;
- dense table or list body with stable columns;
- detail drawer or detail page for long JSON, evidence, and history;
- explicit empty, loading, stale, degraded, and unauthorized states;
- last refreshed timestamp and source API path;
- links back to backing workplan files when a record originates in git.

## Initial Navigation

1. Overview
2. Registry
3. Workplans
4. Events
5. Decisions
6. Access
7. Migration
8. Messages
9. System

`System` holds health, OpenAPI, consistency, release, and deployment diagnostics. It should not become a dumping ground for ordinary operator workflows.

## Data Exposure Rules

- Never render full API keys, raw tokens, database passwords, SSH material, or provider credentials.
- Render API key prefix, hash custody status, scopes, consumer status, creation time, and rotation status only.
- For migration bundles, render source, bundle hash, counts, warnings, and relationship diagnostics; do not render secrets from rejected payloads.
- Distinguish current state from imported historical state.
- Make uncertainty explicit with status labels such as `unverified`, `stale`, `degraded`, `blocked`, and `fallback`.

## Workflow Priority

The first useful prototype should implement read-heavy surfaces before mutation-heavy ones:

1. Overview with active blockers and readiness gates.
2. Registry read model for hubs, manifests, widgets, and events.
3. Migration dashboard for validation/import reports.
4. Access read model for consumers and key prefixes.
5. Workplan/task status view with file links.
6. Mutations for task status, manifest activation, consumer/key lifecycle, and decision records.

## Visual Posture

Use whynot-design quiet, document-like operational language: mostly neutral surfaces, strong typography hierarchy through labels and tables, no marketing hero, no decorative imagery, no gradients, no animation beyond basic hover/focus feedback. The console should feel like a control room notebook rather than a product landing page.


## First Prototype

The first prototype is a protected server-rendered route at `/console`. It uses the existing FastAPI runtime, inline whynot-aligned tokens/classes, and the current SQLAlchemy read model to show:

- readiness gates;
- hub registry rows;
- migration run ledger rows;
- non-secret API consumer metadata;
- recent interaction events.

The route requires the same bearer-token authentication as protected `/api/v2` resources. It intentionally renders only API key prefixes and non-secret lifecycle metadata.

## Rebuild Backlog

The broader UI rebuild is gated behind deployed API evidence and CLI parity.
`docs/specs/operator-ui-rebuild-backlog.md` is the implementation backlog
extracted from the `/console` prototype: readiness overview, registry explorer,
evidence stream, migration/cutover, action-required gates, and access metadata
only. New screens must preserve the prototype's protected-route, desktop/mobile,
no-overlap, and non-secret assertions.

## Open Implementation Choice

The preferred first implementation is a thin FastAPI-served HTML/HTMX or static custom-element shell that consumes `/api/v2` and later Core Hub-native read endpoints. A heavier SPA should wait until the API and workflows prove the extra runtime is useful.