stack/docs/PRDs/2026-08-31_PRD_rev1/UI.1-webui-surfaces.md

id, status, ratified

id	status	ratified
UI.1	ratified	2026-09-01 (Jason Woltje; PRD rev1 ratification PR)

UI.1 — WebUI control-plane surfaces (all functions of the site)

The complete function inventory of the WebUI control plane. Every page obeys the governing rules; every control ultimately calls the same engine as the CLI.

Governing rules

1. Full CLI parity — every aspect of the mosaic CLI surfaces in the WebUI (CLI.1-parity carries the matrix obligation).
2. One canonical API (L2-D14; register OD-53) — CLI, TUI, WebUI, API, and automation share one CLI-backed schema, resolver, planner, authorization, transaction, validation, and audit engine. The WebUI holds no separate logic.
3. The webUI sits OVER official tooling (D8/D12 hard rule) — no page ever reaches the database or filesystem around the tooling; a missing tool means the gap is "blocked on tooling" and the tool is built first.
4. Strict surface separation — seat pages never modify role config; role pages never modify seat config (ROLE.1-role-governance).
5. No direct settings-file authorship — settings are generated projections (L2-D19; DATA.1-record-authority).
6. Agents can never reach these surfaces (L2-D13; the API refuses agent identity — the enforcement is not the page's absence).
7. WebUI drafts (register OD-54) — draft configuration is revisioned server-side desired-state; drafts have no effect until planned and applied.

Interaction conventions

Logically separated pages; dropdowns, activate/deactivate buttons, drag-drop actions performed on-page.

Page inventory

Page	Section doc	Functions
Seat configuration	SEAT.1-seat-profile	harness, model, reasoning, workdir, auth account, overlay; separated role-binding section
Role configuration	ROLE.1-role-governance	manifest editing, revision create/diff/activate/rollback, role links, projection status
Harness configuration	HARN.1-harness-config	install (button), enable/disable, available-models allowlist, reasoning defaults, provider link, linked accounts
Provider configuration	PROV.1-providers	provider dropdown, named instances, OAuth/API mode, local providers, activate/deactivate
Authentication	AUTHN.1-auth-accounts	in-browser OAuth establishment, account list, force renew, deactivate, allowed harnesses
Authorization audit	below	effective grants, escapation potential, drift

Page: Authorization audit (closes gap G3)

Surfaces, per seat, to the user:

• Effective capability grant — the live intersection (role ∩ assignment ∩ lease ∩ workflow ∩ target policy ∩ backend).
• Misdirection potential — which seats hold capabilities that would let another seat's work be routed around its own role lane.
• Escalation potential — any path that would add capability. Should be provably empty; the audit's job is proving it stays empty.
• Drift — seats whose on-disk projection diverges from their active role revision (role check class).
• Failure/blocked surfacing (register OD-64) — the canonical alert stream's WebUI adapter.

Implementation choice (dedicated auditor agent vs mechanical tooling) and the auditor-identity problem are on the grill: GOV.5-open-questions Q-A1/Q-A2.

Cross-cutting requirement

Every change made through these pages — or the CLI — automatically reconciles authentication, settings.json, and required symlinks (DATA.1-record-authority §reconciliation; removal-fast / addition-attested per L2-D17). The user never touches a file. Measured 2026-08-31 (CLI.1-parity Artifacts 2–3): the shipped WebUI already contains two D12 violations — the admin role/ban toggles and the stored harness/provider/model selection mutate state with no backing CLI command. Remediation, not precedent. The server-side hierarchy/grants CRUD surface (hierarchy.controller.ts) is the natural backing for the authorization audit page below, but needs a CLI face and an audit read-path first.

E2 inputs (triage 2026-08-31; see GOV.2-docs-inventory)

Canonical ground truth: USER-GUIDE/product/web-dashboard.md (route-by-route current state, incl. explicit gaps — no New Project/Task UI), webui/PHASE-P-STRUCTURE.md (Next→Vite SPA migration). Pending pulls: DRAFT S2 onboarding-wizard.md (D4/D11/D8), tool-gateway-mapping.md (the D8/D12 gate made concrete), api-artifacts.md.

S2 contract feed (extraction 2026-08-31)

Full extraction record: lane S2-EXTRACTION-2026-08-31.md (per-contract cores, dependency edges, ruling cross-checks). Pulls binding on this section:

• Contract 5 verbatim-affirms the parity rule: "The webUI is a Gateway client only"; "No webUI-only command exists; a Gateway command without CLI exposure is a conformance gap." "Blocked on tooling" closure is mandatory; UI workarounds (direct DB/filesystem, legacy endpoints, domain logic in the web app) are non-conformant. This is the ratifiable D8/D12 text this section's violation findings measure against.
• Legacy non-substitutes barred from backing any P1 surface, frozen for new consumers: /api/projects, /api/tasks CRUD, POST /api/workspaces, /api/teams reads, POST /api/bootstrap/setup, MCP brain_* mutations.
• Onboarding wizard (contract 3) is the reference pattern for every config page this section specifies: pure client-side composition of Gateway commands, exactly one disclosed server-side composed transaction (bootstrap finalize), wizard state always derived from canonical state — never a persisted answer file that can drift.
• Company visibility (private default vs directory) is a UI-facing disclosure control with a bounded existence-only carve-out.
• P1 build rank order (T10): hierarchy → hierarchy RBAC → typed kanban → agent enrollment → authorized roll-up → onboarding orchestration.