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.

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.