UI

Purpose

The v1 pain is invisibility: a case lives in one terminal, nobody else can watch, take over, or answer a gate (Platform Details PG-5). The UI is the one place where a case is visible to many, operated by one, and where every human decision the platform needs is asked and recorded. It is a section of serdica-ui administration, not a separate application — authentication, roles and deployment come with the host.

P The chat is the workspace (D119). A case is worked the way a coding assistant or a chat CLI is worked: one thread per case, in which the agent's steps, its tool calls, its questions, its plan and every human decision appear as cards in time order, and a person types into a composer at the bottom. Nothing about a case happens anywhere else — a decision taken outside the thread is invisible to the ledger and to the other viewers, which is v1's whole failure (PG-26). What makes it more than a chat is that every card says where it is about: environment · system · object, as a chip, so that a reader always knows what is where without opening a query.

P Two surfaces, one application. The operator surface is the administration section — eight workspaces behind role-dependent front doors (§ 1). The client surface is what the customer sees: their requests, one request in their own vocabulary, the acceptance gate their representative owns, and — as the target state — a self-service intake (§ 5b). Both are wireframed before build (PG-26):

Both files are self-contained HTML — open them in any browser. The screens are generated from one script (ui/gen_wireframes.py) so that every screen shares one shell, one palette and one vocabulary; amber marks a human decision, as in every diagram of this wiki, green a running or read-only thing, blue a parked thing, a link or the target state, red a refusal or failure.

0. Design principles

P Eight rules, in the order they were argued; every screen in § 5 can be checked against them.

1. Roles → front doors → workspaces

P The roles are those of Trust and Data § 3; the workspaces are the platform's, not a module's — a Support case and a Configuration case are worked in the same chat with a different stage ladder.

2. The case chat — the vocabulary

P Layout. Three columns. Left: the case header (id, state, type, contract class, clocks), the stage ladder of its module with the gate each stage carries, and the sessions (live · stopped · resumed) with the controller and the viewer count. Centre: the thread of cards, oldest first, a status line and the composer. Right: Where — source, systems touched with mode, papers, linked cases and knowledge, and — when the case is at a gate — the grant that an approval would issue.

P Card kinds. Eleven; the left colour bar names the kind, the small caps label repeats it for the colour-blind.

P Where-chips. ENV · SYSTEM · OBJECT in monospace, followed by a mode chip: read (green), write or send (amber — gated), ddl (red — HW-ddl). Objects are handles (policy ••••7731, annex ••••0028/3), never raw identifiers; the case keeps the mapping (Trust and Data § 4). Clicking any chip opens Where (screen 05): the full map by environment, system and mode of everything the case touched — the trace of what the agent actually did, typed by nobody.

P The plan gate follows the plan mode of the coding CLIs. The agent proposes a numbered plan — each step with its where-chips and the gate it will need — states why, and lists the alternatives it rejected. The person picks one of four: approve the plan (a write or send step asks again when it runs, and the grant is issued then); approve and pre-approve a step — one decision for plan and write where policy permits, and shown disabled with the reason where it does not (an approved shape, not irreversible, and never H5 on a customer-facing environment); reply with a different approach — free text to the agent, which re-plans and returns with the next plan version; refuse with a reason, which parks the case. A reply re-opens planning, not the gate. Evidence, the statement, reversibility, blast radius, policy checks, the shape's training count and the grant are one click deeper under Details.

P Composer and permission mode. The composer's second line always states the permission the typist has: you control session 3 · the agent asks, you decide for the controller; Approver(PROD, write) · read + decide for a role holder who is not controlling; viewers have no composer. Slash commands: /steer ⟨text⟩ (a steer to the running agent) · /answer (the open question) · /stop and /resume (the session) · /handover ⟨module⟩ (opens Hd) · /consult ⟨node⟩ (a read-only consult) · /park ⟨reason⟩ · /where and /papers (open the rail sections) · /try ⟨version⟩ (run this case on a draft prompt — how prompts are trained case by case, § 4 W9) · /help.

P Status line. State · stage → next stage · tool calls · elapsed · human minutes so far · runtime budget left (minutes). Hours and minutes only (D117); nothing on any screen is expressed in currency.

3. Intake — a brief before a case

P The Inbox is the first screen an Operator opens, and nothing in it is raw. An arrival from any door — the ticket system, the shared mailbox, the customer's help desk, the client app's Start a request, a monitor — is normalised by platform.intake (Agents § 5c, Stage Classification § 4) into a brief:

P Authorised intake opens automatically and records its H1 decision; clocks run from arrival. The operator may Open case, Correct & route (a revision and evaluation example), Merge into #… after confirming the same source request, or Dismiss policy noise. Missing initiation authority waits visibly. A shared policy handle alone does not make two different requests duplicates.

4. Workflows

P Thirteen workflows; each names its trigger, its actors, the screens it crosses and where it ends. Together they cover every human action the platform asks for — anything not listed here is either the agent's own work or a defect of this page.

P Three properties hold across all thirteen: every human action is a verdict or a human card in some case's thread (or a row in AUDIT_LEDGER for Control), so nothing is decided off-record; every workflow that changes an environment passes through a grant issued by a gate and executed by the write executor, never by the agent; and every workflow is role-checked by the front door, not by a hidden button.

5. Screen inventory

P Case content and response path. The 68 case journeys bind the existing screens to backend and agent work. One request uses its existing question/action card for external work: who must act, a plain-language instruction, when requested, the evidence needed, Report completed, Cannot perform and Add evidence. Reporting calls the scoped response API, not the acceptance API, and changes the display to “Checking your result”. An ordinary business answer uses the same API with response_kind=answer. A required action still waiting is waiting_for_you; an external organisation waiting is in_progress with the waiting party and age stated in the summary. Cases and Where show the full obligation/member matrix; Acceptance states instructions, preview or delivery scope. No new screen or client-visible technical transcript is introduced.

5a. The operator surface

5b. The client surface

P The customer is not a second class of operator; they see a different application built from the same case (D91). Four screens; What you may start is a panel of screen 18 (D91):

P Three fields the client surface carries that a channel cannot (D97). Origin — every request shows whether it arrived by mail, from the ticket system, from the customer's help desk, or was started in place; one case model, four doors, and the list reads the same whichever was used. Modules involved — the parts of the platform a request actually engaged, so a support case that grew a configuration sub-case says so instead of going quiet. Initiator — who started it and when, because a client who starts work is a different fact from a client who was written to.

P Screen 18 shows the initial client entitlement, so the wireframe fixes all three outcomes rather than the happy one: granted opens the case, may request opens an authorisation request that parks visibly, not granted refuses with the clause and keeps the description for the commercial counterpart (Agents § 5c, Trust and Data § 3b). The kind list offers only what this role may start or request, and a refusal is shown with its reason — never hidden, never silently re-routed to a module the person happens to be allowed to start.

P Screen 18 is the target state and is not the first build (D81, formerly non-goal N-9). What is excluded is building a self-service form before the operator surface and the gate protocol exist, because a form over gates no work type has earned puts a customer in front of an untrained system. The wireframe exists now so that the intake contract is designed for rather than discovered.

P What is deliberately absent from every client screen, and why the absence is a design rule and not an omission:

P The Customer representative role may start support, may request configuration, may not start the Development module (id source), and views and accepts through CG-11 (D97). Acceptance records the person's name and the artefact hash; a later change re-opens the acceptance rather than reusing it.

6. The screens, drawn

P Every screen below is a schematic wireframe — it fixes the shell, the regions, the vocabulary and the data each one renders, not the styling, which follows serdica-ui's administration shell (PG-26). The sample case is generic on purpose: a premium that differs between the two systems for one policy, a vehicle model missing in pricing, a transfer that fails for an annex — the screens are not built around any one of them. Sample people are named (Ablera operators, customer contacts) because a wireframe needs to show who waits on whom; they are illustrations, not role assignments (D107, D110). Click any of them to enlarge. The full annotated sets, with the data source under every screen, are the operator wireframes and the client wireframes.

Work — Inbox and Cases

Decide — Decisions and the packet

Build — Studio and Knowledge

Observe and Control

The client surface

7. Rules the screens enforce

P Approval is a permission, not a second person (Trust and Data § 3). A decision card the viewer may decide shows the decision actions; one they may not shows who can, and a notify action. An Operator who holds the role for the gate and the target decides their own case in one action; where the organisation wants four eyes on a target it withholds the role from its operators — a role-set choice, not a platform rule. Nothing on screen lets a viewer widen their own role.

P Many viewers, one controller (Agent Runtime). The case header always shows the controller and the viewer count; Hand over is a recorded handover; Take over needs the operator role and notifies the previous controller. Viewers have no composer.

P The thread shows stated reasoning, not chain-of-thought — each agent's declared reasoning for a step, its tool calls and their result summaries, and every memory read and write (Architecture § 1). Raw model reasoning is neither a dependable API nor appropriate operational output.

P Every decision card is a packet, not a chat — the mechanism (with the verifier's verdict), the kind and the rejected alternatives, the exact change with expected counts, the revert path and effect classes, the replay, what remains uncertain (Stage Solution Take § 3). Approving binds a grant to the shown artefact hash; a changed artefact re-opens the gate. Result rows never appear in a card or a paper.

P Every card says where. A card without a where-chip is a defect of the card, not a style choice; the Where rail is derived from the cards, never typed.

P A brief before a case. No raw arrival reaches a person; the brief names its source and the Operator's one action is the H1 decision (SG-11).

P Held batches are cases so that their age is visible on the first screen — the direct answer to the 12-week HDesk plateau (Baseline § 5). They appear in Cases and in Decisions alike.

P Hours only. Human minutes, elapsed time, budgets in minutes, clocks in hours and business days; no currency on any screen (D117).

8. Realtime and auth

F SignalR is the estate's proven realtime transport — hub + one-use Redis ticket + HMAC group alias + Rabbit fan-out + transactional outbox, working tested code on the health path (verified 01.09.2026, Platform Details PG-5). P The case chat subscribes per case/session with its own ticket shape and role set; the list screens poll or subscribe to the workflow-generic change event. Authentication is Authority; the roles are the six LT_USER_ROLES rows, issued as role claims by Authority (Trust and Data § 3, D134).

Challenges

• P Visual design follows serdica-ui's administration look; the wireframes fix shell, regions, vocabulary and data, not styling — settled with the T1 skeleton.
• P Thread volume — a configuration stage runs for hours and produces thousands of events; the chat needs collapse-by-agent and follow-mode, and the SignalR payload must stay a reference to ledger rows, not the rows. Tool cards carry summaries; results stay one click deeper.
• P Where-chip resolution — a handle that does not resolve (a policy number with a typo, an object in an environment the connector cannot reach) must render as a red not found chip and park the brief as question, never as a silent blank.
• P The curator duty is a duty of the Operator role per branch of the tree, not a seventh role, until the measured proposal throughput (Metrics) says otherwise.
• P Control's policy tables render the catalogue rows retention.per_class, gates.auto_confirm, gates.escalation_intervals and budget.* (Whitelabel Catalogue § 5; D109 / D112 / D117); what stays open is where the T1 skeleton fixes their storage.

P Implementation alignment. Intake, classification and routing follow Agents § 5c. A permitted arrival opens before an operator clicks it; Inbox is an inspection/correction queue. Gate commands carry the shown artefact hash and expected version; stale decisions return conflict. The same Acceptance screen states preview or delivery, target and revision; preview acceptance cannot close outstanding deployment. Reconnection reloads committed resources by ledger cursor. The backend enforces customer/role filtering on every read and command.

P Client-led Configuration. Reuse the existing request/Acceptance card for H1 business scope and H3 business results when CASE_TYPES.GATE_PLAN assigns required_role=customer_representative. It shows the business projection and exact revision, never a technical SQL packet. The same card uses CG-11 for preview/delivery. Each command names the gate id, scope, hash and version. Scope/result/preview confirmation continues work; only completed-delivery acceptance closes the case. This removes a vendor queue without adding a screen or implying write authority.