--- id: UI.1 status: ratified 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.