VIEWS_BY_ROLE.md — h.work

Per-screen design specification for every role. Cross-reference: INFORMATION_ARCHITECTURE.md, USER_STORIES.md, IMPLEMENTATION_STATUS.md, GLOSSARY.md. Last updated: 2026-06-06.

Each screen follows the template:

### Screen: <route>
- Layout
- Sidebar / left rail / top nav (where applicable)
- Main area
- Key interactions
- User stories fulfilled
- Known gaps

1. Client (`/client/*`)

Route migration (complete): Client admin settings moved from /portal/admin/* (and its sibling /client/admin/*) to /client/settings/*. The /portal/* prefix is gone from the codebase; old in-app /client/admin/* paths redirect. New client work uses the /client/* prefix.

Client Roles

All client users have an orgRole in OrgMembership. This gates access within /client/settings/*.

Role	Who	Team view	Team manage	Channels	Billing	Transfer ownership
Owner	1 per client, invited by AM	✅	✅	✅	✅	✅
Admin	Set by owner/admin	✅	✅	✅	✅	❌
Billing	Set by admin	✅	❌	❌	✅	❌
Member	Default	✅ (read-only)	❌	❌	❌	❌

Team list is visible to all roles — team management (invite/remove/role change) is Admin and Owner only.
See GLOSSARY.md → Client Roles for full role definitions.

The client interacts with one consistent identity — the Specialist (e.g. "Bob"). Internal team composition (Humanity Protocol Experts + AI Agents) is invisible. Every view enforces this principle.

The client portal is intentionally minimal. Its job is: (1) let a client team chat with their Specialist, and (2) let the client admin manage their own team, channels, and billing. Service configuration (agent name, confidence threshold, slug, whitelist) is handled by the AM during onboarding — not by the client. There is no helpdesk, no ticket queue, no analytics dashboard, no support inbox for the client's own end-customers (Acme Financial does not have customers using h.work — Amy IS the end user).

Screen: `/client/chat` (and `/client/chat/[id]`)

Layout — Full-screen split: 256px sidebar on the left, flex chat panel on the right.

Sidebar (Sidebar inside PortalChat.tsx)

Workspace header (top, 44px) — Slug-letter avatar (claret square, 22px) + slug subdomain text (acme.h.work, the public-facing host per ADR-015; routing inside is path-based /client/* per CD-12). Border-bottom 1px subtle.
Your Specialists group — Section label "YOUR SPECIALISTS" (uppercase, 10px, muted). Each specialist row: 28px circular avatar (claret), name in 12px/600, role label ("Primary specialist" / "Specialist") in 11px/muted. Active row: 3px accent left border + accent-subtle bg. Hover: bg-hover. Click → expert profile preview pane in main area.
Your Threads group — Section label "YOUR THREADS" with + New Thread button on the right (claret text, 11px/600). Each thread row: 36px Specialist avatar with green online dot if status is active/open, thread label (12px/500), last-message snippet (11px/muted), relative time, unread count pill (claret). Inline rename pencil icon on hover. Active row: 3px accent left border + accent-subtle bg.
UserFooter (bottom) — avatar (claret, 32px), name + email, theme toggle (sun/moon, 16px), role-aware footer links ("Account Settings", "Billing"), "Sign out" button.

Main panel (ChatPanel inside PortalChat.tsx)

Header (53px) — hamburger to toggle sidebar (mobile), Specialist avatar + green online dot, Specialist name + status line ("Online · Support Specialist"), ChannelBadge (right). Status pill is read-only for clients ("Active" / "Resolved").
Empty state (no thread selected) — WorkforceEmptyState: section label "YOUR WORKFORCE", h2 "Ready to help", subtitle "Delegate work to your AI team — just like messaging a teammate." Below: a single Specialist card (avatar, name, "Support Specialist · h.work", "Online now" badge, claret "Message" button). When multiple specialists are configured, a stack of cards.
Message stream — Padded vertically (14px) and horizontally (16px), gap 10px between bubbles.
- Outgoing (user): claret background, 14px white text, 18px corner radius with 4px tail in the bottom-right corner (border-radius 18px 18px 4px 18px), aligned right, max 76% width.
- Incoming (Specialist): bg-surface, 1px subtle border, 14px primary text, 18px radius with 4px tail in the top-left (4px 18px 18px 18px), aligned left, max 76% width. Avatar (26px claret) + small "AI" / "Human review" badge inline above the bubble (see C-W5).
Composer (bottom) — Slack-style: attach button (paperclip, 17px, muted), auto-grow textarea (1–5 rows, max 120px, 20px pill radius, bg-canvas), send button (34px circle, claret when text present, bg-hover when empty).

Key interactions

Click + New Thread → POST /conversations → empty thread opens with composer focused.
Type and press Enter → optimistic message appended, then real message replaces optimistic. Shift+Enter for newline.
Click thread row → opens thread, marks all unread as read (clearThreadUnread), updates URL to /client/chat/[id], persists "last viewed thread" per user.
Hover thread row → ✏️ rename button appears. Click → inline input, Enter to commit (stored in localStorage hw_threadNames).
Hover sidebar specialist → click → expert profile preview pane (read-only) with claret "Message" button to start a thread with them.
Toggle theme via UserFooter → flips [data-theme], persists in localStorage.

User stories fulfilled — C-W1, C-W2 (partial), C-W4, C-W5 (AI/Human-review badge), C-W6 (search not surfaced in sidebar yet — see Gaps), C-CH1.

Known gaps

C-W8 (P2, deferred 2026-05-23) — high-stakes approval banner not surfaced in client view; only appears for experts (pendingApprovalMsg && isExpert). A client-facing "Awaiting your approval" banner with Approve / Reject controls is post-launch work. MVP handles client approval manually via the conversation channel.
C-W6 — search exists in API (GET /conversations/search), but no search input in the sidebar. Add a top-of-list search affordance.
C-W7 — agentic task progress: backend tracks but no inline progress timeline in the chat thread.
Real-time: Socket.io with Redis adapter cross-pod fan-out (verified via scripts/load/socketio-fanout-test.mjs); reconnect path on sustained drops; no polling fallback (removed in #843).

Retired: `/client/tickets/*`

The Tickets nav item was retired from the client portal. Conversations with the Specialist live in /client/chat as threads — there is no parallel "ticket inbox" surface for clients. (The legacy /client/admin/tickets route redirects to /client/chat. Ticket page files still exist under /client/tickets/* but are no longer linked from any nav.)

A trackable structured work-item concept may return for clients in the future to support multi-step agentic tasks (USER_STORIES.md C-W3, C-W7) but the design has not been redrawn.

Redirected: `/client/settings` → `/client/settings/profile`

The bare /client/settings route redirects to /client/settings/profile. See Screen: /client/settings/profile below.

Retired: `/client/admin/tickets`

Removed in the 2026-05-02 client portal refactor. Clients converse with the Specialist via threads in /client/chat; they do not triage a ticket queue — that's the operator (Expert) view at /workspace/queue. The legacy route now redirects to /client/chat.

Redirected: `/client/admin/team` → `/client/settings/team`

This route redirects to /client/settings/team. See Screen: /client/settings/team below.

Screen: `/client/settings/profile`

Layout — Settings shell (/client/settings/layout.tsx) with left sidebar nav + centered single-column form, max 720px.

Sidebar nav — Profile (always), Team (always), Channels (Admin/Owner only), Billing (Admin/Owner/Billing only).

Main content

Display name, avatar upload, phone, title, bio.
Preferences: theme toggle, time zone.
Notifications: email digest frequency, browser push (future).

Roles — All roles.

User stories fulfilled — C-O1 (profile completion follow-up).

Screen: `/client/settings/team`

Layout — Settings shell + main content area.

Main content (all roles — view)

Page header "Team".
Members table: avatar, name, email, role badge (Owner → gold, Admin → blue, Billing → purple, Member → gray), status (active / pending), joined date.
Self row highlighted with "(you)" label.

Admin/Owner only additions

"+ Invite Member" claret button → modal (email + role select).
Role <select> per row (inline edit; cannot exceed own role; cannot demote last admin/owner).
"Remove" button per row (confirm modal; cannot remove owner row).
Pending invites section with Resend / Revoke actions.

Owner-only section (bottom)

Transfer Ownership — select new owner from current members (Admin or above); confirm modal (destructive-level).

Non-owner section (bottom)

Leave team — stub UI; API pending issue #148.

Key API calls

GET /admin/members — list members
POST /admin/members/invite — invite
PATCH /admin/members/:id/role — role change
DELETE /orgs/:orgId/members/:userId — remove
POST /orgs/:orgId/transfer-ownership — transfer (owner only)

User stories fulfilled — C-T1 (✅ invite), C-T2 (✅ remove), C-T5 (✅ transfer ownership), C-T6 (⚠️ leave team — partial).

Known gaps — C-T6 leave workspace API (issue #148).

Redirected: `/client/admin/billing` → `/client/settings/billing`

This route redirects to /client/settings/billing. See Screen: /client/settings/billing below.

Screen: `/client/settings/billing`

Layout — Settings shell + main content.

Roles — Admin, Owner, Billing.

Billing model (2026-05-21). h.work invoices monthly for the sum of assigned Specialists. There are no self-service plan tiers and no upgrade flow. See docs/features/billing.md.

Main content (top to bottom)

Upcoming invoice card — next anchor day, total amount, currency, line items grouped by Specialist (Name — Role · $X,XXX.00). Each line item shows the active rate window for the current period (e.g. "Active Jun 3 – present"). Powered by GET /client/billing/upcoming (Lago-backed — #452).
Assigned Specialists — read-only summary echoing /client/chat Specialist roster, with the per-Specialist monthly rate and source (override / specialist catalog). Source label clarifies "set by your account manager" vs. "catalog default".
Invoice history — table of past invoices: invoice number, period, issued date, amount, status (paid / open / past due), "Download PDF" (link to Lago-hosted PDF).
Payment method — card last 4 / bank last 4, expiry, "Manage payment method" → Lago-hosted billing portal link.
Trial banner if in trial — "Trial — N days remaining" / "Trial expired". No "upgrade to keep service" CTA — Specialists and their rates are configured by the AM.

Key interactions

Click "Manage payment method" → Lago-hosted billing portal in a new tab.
Click "Download PDF" → opens the Lago-hosted invoice PDF.
No upgrade / change-plan action.

User stories fulfilled — C-B1 (Specialists + rates + period total), C-B5 (single Lago invoice per period), C-B6 (per-Specialist line items).

Known gaps

C-B2 — surface mid-cycle proration explanation when an AM adds/removes a Specialist within the current period (e.g. inline tooltip on the affected line item; backed by #514).
C-B3 — invoice history + PDF download depends on Lago landing (#452).
Stripe Checkout / Customer Portal references in older code (/client/settings/billing/upgrade*) are being removed in #527.

Redirected: `/client/admin/channels` → `/client/settings/channels`

This route redirects to /client/settings/channels. See Screen: /client/settings/channels below.

Screen: `/client/settings/channels` (and detail / new)

Roles — Admin, Owner only.

Formerly /client/admin/channels (renamed from /client/admin/integrations in the 2026-05-02 refactor). Legacy routes redirect here.

Layout — Admin sidebar + main content. Card grid of available channels.

Main content

Page title "Connected Channels".
Section "Connected": channel cards with status badge (green = healthy, amber = warn, red = error), "Manage" link.
Section "Available": uncolored cards for not-yet-connected channels with "Connect" button.
Cards: Email (always-on default), Slack, WhatsApp, Telegram, Microsoft Teams (greyed — "coming soon"), WeChat (greyed).

Detail view ([id])

Channel name + health badge.
Configuration: webhook URL (with copy button), inbound whitelist, test inbound button.
Last 10 inbound events (timestamps, status).
"Disconnect" button (destructive — confirm modal).

New view

Picker grid → OAuth flow per channel (Slack OAuth, Telegram bot token, etc.).

User stories fulfilled — C-O2 (Slack), C-O3 (Email), C-C1 (channel health), C-C2 (WhatsApp).

Known gaps — C-C3 (outbound webhooks), C-C4 (Teams).

Retired: `/client/admin/analytics`

Removed in the 2026-05-02 refactor. Clients do not currently get an analytics dashboard — the previous page was placeholder and risked exposing operator-side mechanics (AI-handled %, expert review rate). When a client-facing analytics surface is reintroduced (USER_STORIES.md C-V*), it will be a usage dashboard (volume vs. quota, response latency) rather than an operator dashboard. The legacy route now redirects to /client/settings/billing.

Retired: `/client/admin/settings`

Removed in the 2026-05-02 refactor. The page exposed configuration that clients should not control — agent name, confidence threshold, slug, whitelist. These are operator-only and are configured by the AM during onboarding (Phase 1.2 / 2.4) and editable post-onboarding by the AM/superadmin in /ops/clients/[id]. The legacy route now redirects to /client/settings/team.

If a client needs to change the threshold or whitelist, they contact their AM.

See OPEN_DECISIONS.md OD-12 for the open question on whether a read-only surface ("Your account is currently set to 'Always Reviewed by Expert'") should be reintroduced for client transparency.

2. Expert (`/workspace/*`)

The Expert workspace is Humanity Protocol's internal operations surface — used by HP employees (e.g. David Kim, Charlie Osei) who review AI drafts and respond as the Specialist persona to a client team. It is not visible to clients and is not a feature of the client-facing product. The architecture (queue / inbox / agentic-task plan review) is closer to Intercom-for-our-own-team than to anything a client sees.

The Expert's home is the queue. Every other route is reachable via the top nav but the queue is where work happens.

Screen: `/workspace/queue` and `/workspace/queue/[id]`

Layout — Split-pane:

Left rail (300px) — queue list with filters + SLA strip on top.
Right pane (flex) — currently selected ticket. The right pane is itself a 40/60 split: Client View (left, ~40%) over the customer thread, Expert Workspace (right, ~60%) for the AI draft + actions. The pane header reads "Client Conversation with {customer}".

On mobile (≤768px) the layout collapses to tabs (Queue / Detail) — queue-mobile-tabs class in globals.css.

Left rail (queue list)

Header — new-item count pill ("N new", claret) + pending count pill (right, danger). No standalone title row.
Client tabs — horizontal scrollable tabs (All Clients · Acme · …) when the expert serves multiple clients.
Status tabs — Pending · In Review · Resolved (40px tall, claret bottom-border on active).
SLA metrics strip — three metrics inline: Avg resolve, SLA met %, Resolved count. SLA % is colored success/warning/danger by threshold.
Risk filter pills — All · Critical · High · Medium. Sorting is always newest-first; there is no sort toggle.
Assignee filter pills — All · Mine · Unassigned.
Ticket rows (64px min height) — left risk bar (3px), customer name + relative time, 2-line message preview, badge row (risk badge with theme-aware bg/text token, confidence %, AssigneePill ("You" / "Assigned" / "Unassigned"), ChannelBadge).
Selected row: accent-subtle bg + accent left bar overrides risk bar. Hover: bg-hover.

Right pane (TicketDetail)

Header — #ticketId, risk badge, channel badge, customer name, status dropdown (pending / awaiting_client / resolved / snoozed — no archived, collapsed into resolved per #2002; see conversation-status-lifecycle), "Assign to me" button.
Customer thread — full message history with the customer (CustomerThread component or inline rendering).
AI suggestion panel — collapsible card: AI draft text (editable textarea), ConfidenceBar (0–100, color-coded), tools used (chips), data retrieved (collapsible), "Accept & Send", "Edit", "Ignore & Write" buttons.
Send-as-Specialist composer — textarea + "Send as [Specialist]" claret primary button.
Action bar — Resolve, Defer 24h (with custom-time picker), Reassign (Expert picker filtered by expert_access per ADR-007), "+ Internal note" (toggles dashed amber composer for internal-only messages).
Internal collab thread — inline below the customer thread, dashed amber border, only visible to experts. (REMOVED — see docs/features/collab.md. Team uses Slack for internal comms; only the "+ Internal note" composer above remains.)

Key interactions

Click Accept & Send → respond() API → message sent as Specialist → row marked resolved → next ticket auto-selected.
Edit AI draft → live textarea → click "Send as [Specialist]" → same flow.
Defer 24h → defer() → row removed from Pending, returns when deferred_until elapses.
Reassign → opens Expert picker (filtered by expert_access) → reassign() → row removed.
Add internal note → toggles composer to dashed-amber mode → POSTs with is_internal=true.
Status change → PATCH /conversations/:id/status.
Auto-refresh queue every 10s; new items animate in with the "N new" pill incrementing.

User stories fulfilled — E-R1 through E-R14, E-A1 through E-A4 (handoff to /workspace/tasks), E-L1. ~~(E-C1/C2 Collab tab cross-link)~~ — Collab removed.

Known gaps

E-R10 — defer UI not yet confirmed in the frontend (backend complete).
E-R11 — reassign UI not yet confirmed in the frontend (backend complete).
E-L2 — correction error-type tagging not in the resolve flow.
E-P3 — no push notifications when a critical item arrives.
~~E-C3 — no inline ticket-attached discussion thread; experts collaborate in /workspace/collab rooms but cannot anchor a discussion to a specific ticket.~~ (REMOVED — Collab gone, see docs/features/collab.md. Team uses Slack.)

Screen: `/workspace/collab` — REMOVED

⚠️ REMOVED. Collab (internal team chat) was removed from the product; the team uses Slack for internal communication. See docs/features/collab.md. The section below is retained as historical reference only — /workspace/collab no longer exists.

Layout — Split-pane: left rail rooms list (220px), right pane room thread.

Rooms list

Each room row: room name (e.g. "general", "kyc-pool"), unread count pill, last-message snippet, relative time.

Right pane

Header: room name, member count, settings icon.
Message stream: same bubble pattern as chat but without the AI/Human-review badge (experts only).
Composer: same Slack-style as chat with attach + send.

User stories fulfilled — E-C1, E-C2. (REMOVED)

Known gaps — E-C3 (no per-ticket inline discussion). (REMOVED)

Screen: `/workspace/tasks` (Agentic task plan review)

Layout — Split-pane: left task list, right task detail.

Task list

Filter pills: All · Pending Approval · Running · Failed · Done.
Row: task name, originating ticket link, status badge, # steps, # pending approvals, created time.

Task detail

Header: task name, originating customer thread link.
Step list (vertical timeline) — each step has: number, name, parameters (JSON / form preview), tool name, AI-confidence bar, status (queued / pending approval / approved / rejected / running / done / failed).
Step actions (when pending approval) — "Approve" (claret), "Reject" (with required textarea for feedback).
Bottom: "Approve all remaining" button (with confirm modal — destructive in spirit since it auto-approves).

User stories fulfilled — E-A1 through E-A4.

Known gaps

Tool execution itself is a stub (issue #29). UI ready, runtime not.

Screen: `/workspace/analytics`

Layout — Single-column dashboard with date-range picker top-right.

Sections

Stat cards: queue depth, avg resolve time, tickets handled (today / week / month), my SLA %.
Volume chart (per day, stacked by AI vs Expert).
Confidence histogram (AI confidence distribution for items I reviewed).
Top request types (bar chart).
Pool comparison: my metrics vs org average.

User stories fulfilled — E-P1 (assigned orgs), E-P2 (personal performance).

Known gaps — none for spec.

Screen: `/workspace/pools` — DEPRECATED

Removed 2026-05-03 / superseded 2026-06-05: Expert pool model deleted. Expert ↔ data access is now governed by the single expert_access table per ADR-007. The legacy org_experts table was dropped 2026-06-05 via PR #1711 PR 4 (commit 1a904fa5) — it is no longer present in the schema. This route is deprecated; the settings page no longer links here.

Layout — ~~Card grid, one card per pool.~~ (deprecated)

Status — The /workspace/pools route and this design spec are retained for archival purposes but should not be implemented. The Expert settings page at /workspace/settings now shows "Assigned Organizations" instead.

Screen: `/workspace/settings`

Layout — Single-column form.

Sections

Profile (name, email, avatar).
Skills / domains (tag input — pulls from User.skills array).
Assigned Organizations (read-only list of orgs this Expert handles).
Notification preferences (in-app, email, push when implemented).
Availability (on-call toggle, future).

User stories fulfilled — E-O2 (profile + tagging), E-O3 (assigned orgs).

Known gaps — E-O2 UI not yet built (backend supports skills array).

3. Account Manager (`/ops/*`)

Internal Humanity Protocol surface. AMs are HP staff. They onboard new clients (4-step wizard), assign Specialists from the platform pool, manage trial dates and members, and act as the named relationship owner for each assigned org. Not visible to clients.

Shared /ops/* surface. As of 2026-05-03, AMs and Superadmins share the same /ops/* routes. Superadmin is a strict superset — same routes and shell, with additional nav tabs (Queue, Analytics, Health, Billing, Team) and visibility across all orgs. AM-specific notes in this section apply equally to the SA experience for the same screens; SA-only screens are documented in Section 4.

Screen: `/ops/clients` (Clients list)

Layout — Ops top-nav (48px header: logo + role label + tab bar + user avatar at top-right) + main content. Same shell as the Experts workspace. AM tab bar: Clients · Inbox · Settings. SA tab bar: Clients · Inbox · Queue · Analytics · Health · Billing · Team · Settings.

Main content

Header: "Clients" + "+ New Client" claret button.
Filter strip: status (All / Trial / Active / Suspended / Archived), search by name or slug.
Table:
- Org name + slug
- Status pill (active / trial / pending_am_setup / archived)
- Trial end date (with days-remaining badge if in trial)
- Last activity (relative time)
- Specialist (avatar + name)
- Plan
- Actions menu (… → Open, Edit, Archive)

Key interactions

Click row → /ops/clients/[id].
Click "+ New Client" → /ops/clients/new (wizard step 1).

User stories fulfilled — SA-C2 (AM-scoped variant), SA-C3 entry point.

Screen: `/ops/clients/new` and `/ops/clients/[id]/setup/*` (4-step wizard)

Layout — Onboarding-style header (logo + breadcrumbs as a step indicator), centered card max-width 720px, single-column form, "Next" claret button bottom-right + "Back" link bottom-left.

The wizard has 4 user-facing steps (per ops/clients/[id]/setup/* and ops/clients/new):

Step 1 — Company Info (`/ops/clients/new`)

Fields
- Company name (required, min 2)
- Slug (SlugAvailabilityInput — real-time availability check, lowercase + hyphens, immutable post-confirm warning)
- Workspace URL preview: ``{slug}.h.work (live preview to the right of the slug field)
- Industry (dropdown)
- Company domains (multi-input with chip UI; blocks personal-email domains via BLOCKED_DOMAINS)
- Primary contact: admin email (validates against company domains), admin first/last name, optional phone
- Country (dropdown), Timezone (dropdown)
- Website (optional)
Validation
- Slug: unique, format-correct, not reserved.
- Admin email: must match one of the company domains (otherwise warn + block).
CTA — "Continue" → POST createAmOrg → on success, redirect to step2.

Step 2 — Assign Specialist(s) (`/ops/clients/[id]/setup/step2`)

Search box auto-focused with placeholder "Search specialists…".
Specialist pool grid — each card: avatar, name, email (bob@h.work), domain tags, current org count, "Primary?" toggle, "Threshold" slider (0–101).
Multi-select; first selected is auto-marked Primary.
"Selected (N)" stack at top showing chosen specialists with X to remove.
CTA — "Continue" (disabled until ≥1 specialist selected).

Step 3 — AM Profile (`/ops/clients/[id]/setup/step-3`)

Global AM profile (one-time, shared across all AM's orgs):
- Display name, avatar upload, email signature line, contact email, phone.
Note: "This profile is shown to all your clients. It's saved once and reused across every workspace you manage."
CTA — "Continue".

Step 4 — Send Invite (`/ops/clients/[id]/setup/step-4`)

Simplified UX (PRs #267-271): The onboarding wizard was reduced from 6 steps to 4. Client-facing Steps 2.4 (Channels) and 2.5 (Optional/Billing) were removed as dedicated wizard steps. Channels and Billing are now configured post-onboarding from /client/settings/*.

Phase 0 checklist (Phase0Status from API) — four items, each with ✓ or ⚠️:
1. Company info confirmed
2. Slug reserved
3. ≥1 Specialist assigned
4. AM profile complete
Trial end date field (default +30 days), editable.
"Invite preview" card — exact email body that will go to the client admin, with substituted variables.
CTA
- "Send invite" — claret primary, disabled until all Phase-0 checks pass.
- Shows current invite status if already sent (sent / accepted / expired). "Resend" / "Revoke" actions.

Key interactions

Each step persists progress server-side.
"Back" returns without unsaved-changes prompt unless edits in flight.

User stories fulfilled — SA-C1 (AM-scoped), C-O1 (invite-side trigger), supports Phase-0 gate model from PRD.

Known gaps

Step 4 trial date field is editable but no UI to extend trial post-invite (covered in Org Detail).
No bulk-import wizard for migrating existing clients.

Screen: `/ops/clients/[id]` (Client detail)

Layout — Ops top-nav + main content with tabs.

Tabs (AM and SA)

Overview — company info card (industry, timezone, invite/billing email, corporate domains, trial end, created), plus a "Continue setup" CTA when status is mid-onboarding.
Conversations — list of conversations for this org with status pill and relative-time, click → /ops/inbox?convId=….
Specialists — currently-assigned Specialist personas + reassign link to wizard step 2.
Team — client member table with name/email, org role pill, joined date.

Tabs (SA-only additions)

Tools — live per-org tool-permissions toggles, backed by GET/PUT /orgs/:orgId/tool-permissions.
Audit — placeholder card ("Audit log coming soon"). No GET /orgs/:id/audit endpoint yet.

SA action bar (above the tab bar, SA-only)

Impersonate — disabled stub ("Coming soon").
Reset password — disabled stub ("Coming soon").
Change plan — (removed 2026-05-21) No self-service plans under per-Specialist invoicing. Use the Specialists tab to add/remove Specialists or adjust rates.

SA additions inside the Team tab

Inline org-role <select> per member row (owner / admin / member / billing), wired to PATCH /admin/members/:id/role.
"Deactivate" stub button per row ("Coming soon").

Key interactions

"Edit client" link in the top bar → /ops/clients/[id]/edit.
"Continue setup" CTA on Overview when status is pending_am_setup or pending_client_confirmation.
"Reassign Specialists" link from Specialists tab.

User stories fulfilled — SA-C3, SA-C4 (assign experts via specialist team), SA-P5 (tool permissions — done).

Known gaps

SA-C9 — named lead UI is the gap; today's primary AM is implicit (whoever owns the org).
SA-C6/C7 — Impersonate, Reset password are scaffolded as disabled stubs (no API). The "Change plan" stub was removed 2026-05-21 (no plans under per-Specialist invoicing).
SA-C10 — Audit tab is a placeholder until GET /orgs/:id/audit is added.

Screen: `/ops/settings`

Layout — Single-column form.

Sections

Personal profile (name, avatar, signature) — for AM, same data as wizard Step 3 (one source).
Notification preferences.
Theme.

Roles — AM, Superadmin (same shape for both).

User stories fulfilled — supports SA-C9 (foundation for named-lead).

4. Superadmin (`/ops/*`)

Internal Humanity Protocol operations surface. Cross-org access for the HP operations team — full org list, global queue, platform analytics, service health, all-org billing, internal team management. Highest-privilege internal role. Not visible to clients.

Shared /ops/* surface. Superadmin uses the same /ops/* routes as the AM (see Section 3). SA is a strict superset — same shell, same Clients/Inbox/Settings screens, plus additional SA-only nav tabs documented below. SA also sees all orgs (vs. only assigned orgs for AM).

Screen: `/ops/clients` (SA view)

Same screen as the AM /ops/clients view (see Section 3) with SA-only additions:

Extra columns — primary AM, MRR, last incident. Row actions — Open, Impersonate (audit-logged), Suspend, Archive.

User stories — SA-C2, SA-C3 entry.

Screen: `/ops/clients/new` and `/ops/clients/[id]` (SA view)

Same wizard and detail as the AM views (Section 3). The detail page adds, for SA only:

Tools tab — live per-org tool-permissions toggles via /orgs/:orgId/tool-permissions (SA-P5 — done).
Audit tab — placeholder card; full filterable audit log requires GET /orgs/:id/audit (SA-P3 — backend gap).
SA action bar — Impersonate / Reset password rendered as disabled stubs ("Coming soon") since no API exists yet (SA-C6, SA-C7 — backend gap). The "Change plan" entry was removed 2026-05-21 (no plans under per-Specialist invoicing).
Team tab — inline org-role <select> per member, plus a disabled "Deactivate" stub.

Screen: `/ops/queue` (Global queue) — SA only

Same TicketDetail-style split-pane as /workspace/queue, but with org column visible by default in the list and the org filter prominent. Used for spotting cross-org surges.

User stories — SA-Q1, SA-Q2.

Screen: `/ops/pools` — REMOVED

Removed 2026-05-03 / superseded 2026-05-22 by ADR-007 (CD-22 closed). The Expert pool model is dead: Expert ↔ data access is governed by expert_access (Org × Specialist grants) via ExpertAccessService. The /ops/pools route is a 410 / redirect and the SA top-nav no longer shows a "Pools" tab. Pool admin replaced by per-client Expert assignment in /ops/clients/[id] → Specialists tab.

Screen: `/ops/analytics` — SA only

Layout — Single-column dashboard with date-range.

Stat cards — total tickets, auto-resolve %, active experts, MRR. Charts — volume over time, top request types, AI vs Expert split, resolution-time distribution. All metrics now driven by live data (SA-B4 closed).

User stories — SA-B3, SA-B4.

Known gaps — SA-B5 partial (per-org LLM cost + Expert workload shipped via PRs #3195/#3200; dollarized gross margin pending #3196). SA-E4 (leverage) shipped — /ops/analytics Expert leverage (#3199).

Screen: `/ops/health` — SA only

Layout — Service grid, one card per service (API, DB, Redis, each channel adapter).

Card — service name, status (green/amber/red), latency, last-error timestamp, link to logs / Grafana. Sticky banner at top if any service is in degraded or outage state.

User stories — SA-P1, SA-P2 (Prometheus metrics surfaced via deep-link).

Known gaps — SA-P4 (per-org channel adapter health).

Screen: `/ops/billing` — SA only

Repurposed (2026-05-21) from the legacy Stripe subscriptions table. Backed by Lago once the integration (#452) lands. See docs/features/billing.md.

Layout — Two stacked sections: org list table + drill-in panel.

Top row (KPI strip) — Total MRR (sum of organizations.metadata.total_monthly_rate across active orgs), upcoming-invoice total for the next 7 days, overdue invoice count.

Org table columns — org name, # assigned Specialists, current monthly rate (sum), next anchor day, last invoice (date · amount · status), outstanding balance, "View in Lago" link.

Row actions — open the per-org invoice/assignment-history drawer (read-only); jump to /ops/clients/[id] for assignment changes.

Drill-in drawer (per org)

Specialist assignment + rate history (table; one row per (specialist, rate window) segment with effective_from / effective_until).
Invoice history (Lago invoices for this org with PDF links).
Upcoming invoice preview (period, line items, total).
"Force regenerate draft invoice" button (calls POST /ops/billing/orgs/:orgId/invoices/regenerate) for use after a rate correction.

User stories — SA-B1 (all-org invoice/MRR table), SA-B2 (per-org Lago invoice management), SA-B8 (unresolvable-rate alert banner; tracked in #530).

Known gaps — banner + API surface for orgs with unresolvable Specialist rates before invoice issues (SA-B8, #530); per-org gross-margin view (SA-B5) — partial: per-org LLM cost + Expert workload on /ops/billing?org=<id> (PRs #3195/#3200); dollarized labour + infra cost pending (#3196).

Screen: `/ops/team` — SA only

Layout — Internal users table (AMs, experts, AI operators, other superadmins).

Columns — name, email, platform role, status (active / disabled), last sign-in, Specialist grants count (expert_access entries; replaces the legacy pool column).

User stories — SA-C6, SA-C7, SA-E2 (grant Expert access to a Specialist from here, via ExpertAccessService per ADR-007). Row actions — change platform role, deactivate, reset password.

Screen: `/ops/settings` (SA view)

Same shape as the AM /ops/settings (Section 3). Personal profile + theme.

5. Cross-role notes

The expert can also visit /client/chat. When they do, all expert-gated controls (status dropdown, assign button, internal note toggle, confidence scores, "Expert" sender label) appear. This is a support-tool affordance documented in frontend/FRONTEND_ARCHITECTURE.md (EXPERT_ROLES section).
AM and Superadmin share /ops/*. Superadmin sees all orgs; AM sees only assigned orgs (RLS-enforced). SA-only sub-routes (/ops/queue, /ops/pools, /ops/analytics, /ops/health, /ops/billing, /ops/team) gate on superadmin; AM hitting one is redirected to /ops/clients.
The client never sees /workspace/* or /ops/*. Layout guards redirect.
Legacy /am/* and /superadmin/* URLs redirect to the matching /ops/* route. Migration is complete — all internal routes use /ops/*.

Owner: Design + Platform team

Client Roles
Screen: /client/chat (and /client/chat/[id])
Retired: /client/tickets/*
Redirected: /client/settings → /client/settings/profile
Retired: /client/admin/tickets
Redirected: /client/admin/team → /client/settings/team
Screen: /client/settings/profile
Screen: /client/settings/team
Redirected: /client/admin/billing → /client/settings/billing
Screen: /client/settings/billing
Redirected: /client/admin/channels → /client/settings/channels
Screen: /client/settings/channels (and detail / new)
Retired: /client/admin/analytics
Retired: /client/admin/settings
Screen: /workspace/queue and /workspace/queue/[id]
~~Screen: /workspace/collab~~ — REMOVED
Screen: /workspace/tasks (Agentic task plan review)
Screen: /workspace/analytics
Screen: /workspace/pools — DEPRECATED
Screen: /workspace/settings
Screen: /ops/clients (Clients list)
Screen: /ops/clients/new and /ops/clients/[id]/setup/* (4-step wizard)
- Step 1 — Company Info (/ops/clients/new)
- Step 2 — Assign Specialist(s) (/ops/clients/[id]/setup/step2)
- Step 3 — AM Profile (/ops/clients/[id]/setup/step-3)
- Step 4 — Send Invite (/ops/clients/[id]/setup/step-4)
Screen: /ops/clients/[id] (Client detail)
Screen: /ops/settings
Screen: /ops/clients (SA view)
Screen: /ops/clients/new and /ops/clients/[id] (SA view)
Screen: /ops/queue (Global queue) — SA only
Screen: /ops/pools — REMOVED
Screen: /ops/analytics — SA only
Screen: /ops/health — SA only
Screen: /ops/billing — SA only
Screen: /ops/team — SA only
Screen: /ops/settings (SA view)

1. Client (/client/*)

Client Roles​

Screen: /client/chat (and /client/chat/[id])​

Retired: /client/tickets/*​

Redirected: /client/settings → /client/settings/profile​

Retired: /client/admin/tickets​

Redirected: /client/admin/team → /client/settings/team​

Screen: /client/settings/profile​

Screen: /client/settings/team​

Redirected: /client/admin/billing → /client/settings/billing​

Screen: /client/settings/billing​

Redirected: /client/admin/channels → /client/settings/channels​

Screen: /client/settings/channels (and detail / new)​

Retired: /client/admin/analytics​

Retired: /client/admin/settings​

2. Expert (/workspace/*)

Screen: /workspace/queue and /workspace/queue/[id]​

Screen: /workspace/collab — REMOVED​

Screen: /workspace/tasks (Agentic task plan review)​

Screen: /workspace/analytics​

Screen: /workspace/pools — DEPRECATED​

Screen: /workspace/settings​

3. Account Manager (/ops/*)

Screen: /ops/clients (Clients list)​

Screen: /ops/clients/new and /ops/clients/[id]/setup/* (4-step wizard)​

Step 1 — Company Info (/ops/clients/new)​

Step 2 — Assign Specialist(s) (/ops/clients/[id]/setup/step2)​

Step 3 — AM Profile (/ops/clients/[id]/setup/step-3)​

Step 4 — Send Invite (/ops/clients/[id]/setup/step-4)​

Screen: /ops/clients/[id] (Client detail)​

Screen: /ops/settings​

4. Superadmin (/ops/*)

Screen: /ops/clients (SA view)​

Screen: /ops/clients/new and /ops/clients/[id] (SA view)​

Screen: /ops/queue (Global queue) — SA only​

Screen: /ops/pools — REMOVED​

Screen: /ops/analytics — SA only​

Screen: /ops/health — SA only​

Screen: /ops/billing — SA only​

Screen: /ops/team — SA only​

Screen: /ops/settings (SA view)​

5. Cross-role notes

1. Client (`/client/*`)

Client Roles

Screen: `/client/chat` (and `/client/chat/[id]`)

Retired: `/client/tickets/*`

Redirected: `/client/settings` → `/client/settings/profile`

Retired: `/client/admin/tickets`

Redirected: `/client/admin/team` → `/client/settings/team`

Screen: `/client/settings/profile`

Screen: `/client/settings/team`

Redirected: `/client/admin/billing` → `/client/settings/billing`

Screen: `/client/settings/billing`

Redirected: `/client/admin/channels` → `/client/settings/channels`

Screen: `/client/settings/channels` (and detail / new)

Retired: `/client/admin/analytics`

Retired: `/client/admin/settings`

2. Expert (`/workspace/*`)

Screen: `/workspace/queue` and `/workspace/queue/[id]`

Screen: `/workspace/collab` — REMOVED

Screen: `/workspace/tasks` (Agentic task plan review)

Screen: `/workspace/analytics`

Screen: `/workspace/pools` — DEPRECATED

Screen: `/workspace/settings`

3. Account Manager (`/ops/*`)

Screen: `/ops/clients` (Clients list)

Screen: `/ops/clients/new` and `/ops/clients/[id]/setup/*` (4-step wizard)

Step 1 — Company Info (`/ops/clients/new`)

Step 2 — Assign Specialist(s) (`/ops/clients/[id]/setup/step2`)

Step 3 — AM Profile (`/ops/clients/[id]/setup/step-3`)

Step 4 — Send Invite (`/ops/clients/[id]/setup/step-4`)

Screen: `/ops/clients/[id]` (Client detail)

Screen: `/ops/settings`

4. Superadmin (`/ops/*`)

Screen: `/ops/clients` (SA view)

Screen: `/ops/clients/new` and `/ops/clients/[id]` (SA view)

Screen: `/ops/queue` (Global queue) — SA only

Screen: `/ops/pools` — REMOVED

Screen: `/ops/analytics` — SA only

Screen: `/ops/health` — SA only

Screen: `/ops/billing` — SA only

Screen: `/ops/team` — SA only

Screen: `/ops/settings` (SA view)