Skip to content

Humagen design requirements

This file tracks the console requirements agreed in the design review on October 25, 2026. Read it before changing presentation or integrations. Keep requirement IDs stable and update implementation evidence in the same change that satisfies a requirement.

The design boards were interaction references; they and their GitHub Pages site were removed on October 30, 2026, and the evidence below that names them records checks made at the time. The detailed control-plane spec, board rules, and gap analysis provide the larger design. The gap analysis records its own review revision; recheck code before treating it as current. Repository rules in AGENTS.md still govern implementation, including shared presentation and agent identity.

The workspace principles apply the designer and portfolio research: Harvey II for project structure, Codex for human control, Linear for restraint, and Dust for testing working interactions. These references inform Humagen's identity rather than replacing it. The task queue tracks the active delivery. The conversation-first design separates planned collections, browser, protocol and improvement work from this UI pass.

Requirements

ID Requirement Status
DES-069 Conversation overview and visible work controls Implemented: Overview, Workspace, Context and Activity header controls collapse into the menu below the conversation's 3xl breakpoint. The addressed overview folds environment, latest context, agents and run changes from existing APIs; delegated transcript calls share one collapsed disclosure. Evidence: conversation-overview.dom.test.tsx, timeline.dom.test.tsx and route round-trip tests. Live browser verification unavailable in this session.
DES-059 PR review evidence in two panes, with GitHub issue and pull request Workspace tabs Implemented: GitHubTab.tsx, github-ref.ts, tenant-scoped GET /api/github/pull and /api/github/issue, bounded repository/SHA patch cache, workflow status, labels and comments; unit, DOM and endpoint regressions added; conversation-review-workspace screen registered for CI.
DES-061 Automations gather schedules and signed GitHub event rules with agent instructions Implemented; focused Go/DOM tests and phone/desktop screen definitions; CI screens pending
DES-001 Integration controls use the existing system and report real results Slack/GitHub configuration form implemented; automated checks pass; live delivery pending
DES-002 Use spacing instead of dots between words in UI metadata All boards and touched console metadata implemented and checked; audit other console screens when changing them
DES-003 Reveal the message Fork action on hover and keyboard focus Native saved-fork API, immutable lineage, source checks and inspector built; shared action wiring pending
DES-004 Reveal full message date and time on hover and keyboard focus Human messages and announcements implemented, DOM-tested and browser-checked; agent-message timestamps pending
OPS-001 Durable assignments, scoped autonomy, agent pause and recorded coordination Domain stores, admission/tool guards, OpenAPI routes and console components implemented. Restart tests cover memory and Postgres; UI DOM tests cover saved and refused actions, inherited policy provenance, effective pause, typed contract inputs and reviewed deadlines. Native reminders survive restart on the same confined inbox item. Done checks and continuation are shown on the assignment's card, and its recorded run opens the message page of the run that answered, which shows the recorded answer when the run has no session trace: DOM tests cover a card with and without checks, and all eight light, dark, desktop and phone before and after captures of the card and the run page are in pull request 343. Not seen in a browser: a card without checks and a count above one. Global navigation, screenshots and source-health integration belong to the following stack layers.
DES-005 Keep this requirements record discoverable and accurate Documented; AGENTS.md references this file
DES-006 Keep sidebar and main content scrolling independent Implemented; Chromium wheel regression covers phone and desktop
DES-007 Agent badge text remains contained at narrow widths and enlarged text sizes Fixed; dark phone/desktop containment regression passes
DES-008 Agent/project discovery belongs in the new-conversation picker Implemented; search and selection preserve drafts/files and cannot submit work
DES-009 Use consistent action icons and readable inbox recovery groups Implemented; semantic shared icons, touch targets, collapsed companion diagnostics and native recovery captures
DES-010 Notifications consolidates actionable work and delivered updates Implemented; one Notifications feed, one status/type filter panel and a permission-aware Alert Rules companion tab
DES-011 Conversation drawers reflow desktop content, with a compact header and consistent controls Implemented; shared inspector dock, mobile native dialogs and responsive browser regressions
DES-012 Workspace search is a centered modal with indexed content and native destinations Implemented; permission-confined content indexes, API contract, replay and search interaction tests
DES-013 Project selection is directly editable before starting work; every starter suggestion remains available Implemented; stacked project glyph, searchable drawer, draft-preserving selection and wrapping starters
DES-014 Composer context choices use named categories and scoped subpanes Implemented; Agents, Projects and Skills preserve the draft, and channel choices stay inside their project
DES-015 Shared web controls use one semantic theme, font and responsive sizing Implemented; standard shadcn Radix controls, renderer adapters and foundation stories
DES-016 Skills packages and managed Memory chains have browsable, scoped files Implemented; immutable packages, folder import/editor, native memory review and private contextual chat
DES-017 Related destinations use tabs and compact operational screens Implemented; permission-aware Library, Agents and Operations hubs, bounded policy rows and actionable source health
DES-018 Motion and metadata make navigation changes easy to follow Implemented; Tailwind drawer/menu states, retained inert exits, reduced-motion behavior, named project pills and + New above search
DES-019 Project work has readable states, scoped filters and honest recovery Implemented; automated delivery checks pass; final browser/CI verification pending
DES-020 Workspace previews reuse console controls, fonts and consolidated navigation Implemented; automated delivery checks pass; final browser/CI verification pending
DES-021 Sidebar conversations show their title; projects and conversations can be pinned independently Implemented; saved preferences, access checks, restart and DOM regressions, and responsive sidebar captures
DES-022 Conversation actions support rename, archive and admin-reviewed deletion Included in the consolidated branch; bounded API, durable lifecycle and review UI checks
DES-023 A deployment and each workspace brand the console from the spec, without a fork or a rebuild Implemented; spec, server, API and console tests pass; browser check of a branded build pending
DES-024 An agent calling another agent reads as a message, nested under its caller Implemented in AgentMessage (AgentCall); checked live: @lead called researcher, then writer, with real providers
DES-025 Stop lives on the working agent's mark; the composer sends and queues Implemented: StoppableMark, useRunStop, queue adopt, Esc; room, core queue and web tests pass; live stop not yet tried on a long run
DES-026 Activity lists every agent run in time order, each opening a replayable conversation Implemented; activity.dom.test.tsx and ui.test.tsx pass; checked in the browser
DES-027 Drawer headers align with the page header Implemented with --humagen-header-h; measured equal in the browser at desktop width
DES-028 Share and People & Access are one panel Implemented: the Share drawer is People & Access; room tests pass
DES-029 A turn shows a status only when it adds information Implemented; checked in the browser
DES-030 One AI disclaimer, centered under the prompt bar Implemented in Composer; checked in the browser
DES-031 A message names no agent under it; a router's pick is a checkpoint Implemented: Checkpoint in Chat and Room for a run the dynamic router joined. In a root session a message gets one answer, and why it came from where it did (a mentioned agent, a search match) is in the answer's activity, never a line of the conversation (traceEvents in responseSource.ts, session-answers.dom.test.tsx, message-refs.dom.test.tsx); not rechecked in the browser since
DES-032 The conversation header shows which agents took part, not a count Implemented: Involved in ConversationShell.tsx; ui.test.tsx passes; checked in the browser
DES-033 A turn shows its thinking and steps inline, where they happened, with what each was given and returned Implemented in WorkSteps.tsx and render-web StepIO; web and core tests pass; checked live
DES-034 A finished turn says how long it worked Implemented: turn.completed carries durationMs, from the run's events or its record; adapter and core tests pass
DES-035 Agents are told apart by a bot in their color; a mention opens a profile on hover Implemented: AgentInitials (drawn by bot-avatars, initials where there is no canvas), MentionLink; ui.test.tsx passes; marks checked in the browser on /gallery.html, dark and light
DES-036 The composer holds what is picked, and the first message posts before anything else runs Implemented in Composer.tsx and Chat.tsx; web tests and the home screens pass
DES-037 Health is a status page of each model provider and dependency Implemented: GET /api/health, Health.tsx; health_test.go and health.test.tsx pass; checked live
DES-038 Screens open ready to read, filter once, and keep message actions quiet at rest Implemented in #112; web, core and Slack tests pass; phone and desktop screens pass
DES-039 Changing screens never blanks or jumps; chrome is glass on one app frame Implemented: transition.ts, delayed skeletons, frame and chrome glass; web tests and Console screens pass; navigation CLS measured 0 at no added latency
DES-040 The console works on a phone and installs as an app: touch targets, the keyboard, safe areas, a modal drawer, an Inspector sheet, an offline screen and a prompt for new versions Implemented: styles.css, viewport.ts, pwa.ts, sw.ts; web and Go tests pass; Console screens pass at 320, 375, 390, 430 and 844x390 with 44px touch targets and 16px fields; iOS keyboard and install need a real device
DES-041 Agents a message goes to are its @mentions, never chips beside the project; a message has no cap on mentioned agents Implemented: mentionsIn, withMention, withoutMention in tags.ts, mentionPicks in Plus.tsx; pkg/threads.Decide runs every tagged agent; web, tags and platform tests pass; chat-mentions, channel-plus and workspace-find-help-selection screens pass
DES-042 On a phone the console fills the installed app's screen, the drawer button floats instead of taking a row, and Home keeps the chat bar in reach of a thumb Implemented: viewport.ts, styles.css, HomePage.tsx; web tests pass; Console screens pass at 320x568, 390x844 and 844x390; the iOS height needs a real device
DES-043 The brand's colors edge the page round its corners and glow round the chat bar, turning while a reply is in flight Implemented: styles.css, Composer.tsx; web tests pass; screens pass light and dark at 1280x800 and 390x844
DES-044 A conversation has a wave down its left edge to scan and scrub through its turns, and the keyboard opens and closes cleanly on a phone Implemented: TurnRail.tsx, Thread.tsx, Chat.tsx, Room.tsx, viewport.ts; web tests pass (wave.dom.test.tsx, pwa.test.ts); screens pass at 390x844 and 1280x800; the keyboard on iOS needs a real device
DES-045 A phone reads like a native chat app: quiet message actions, a one-line chat bar and header, Chat and Work at the top of Home, a swipe from the edge for the drawer, and the installed app opening on Chat Implemented: theme.css, styles.css, Composer.tsx, ConversationShell.tsx, ModeSwitch.tsx, Sidebar.tsx, manifest.webmanifest; web tests pass; screens pass at 390x844 and 1280x800
DES-046 A structured review reads as a card with its evidence in place, the same in Slack Implemented: core readReview, components ReviewCard, the Review primitive in render-web and render-slack, GET /api/github/source; core, Slack, web DOM and Go tests pass; pnpm validate:slack passes; conversation-review-* screens pass at phone and desktop
DES-047 Skills are slash commands, the only way the console offers them: / opens a menu of the skills a message here can name, fuzzy filtered with the match highlighted; @ offers no skill or @skill:, $ opens nothing, and a posted $name or @skill:name shows as a /name chip Implemented: commands.ts, tags.ts, Composer.tsx, ui.tsx (Mentioned), pkg/threads/tags.go; web, threads and platform tests pass; chat-at, chat-slash, chat-slash-picked and composer-menu-skill-selection screens at 390x844 and 1280x800
DES-048 A turn reads as a transcript: words and runs of tool calls in the order they came, each run one line that names what it did, a file written opening in the Workspace, and the reader's messages on the right Implemented: packages/core/src/timeline.ts, packages/components/src/timeline.ts, WorkSteps.tsx, ToolLines for Slack, Room.tsx message sides; core, components, adapter, render-slack and web DOM tests pass; pnpm validate:slack passes; screen conversation-timeline passes at 390x844 and 1280x800
DES-049 The sidebar lists Recents newest first, Pinned on top, Projects and Archived as views; each row says its project, its age or an unread dot, and whether it waits on a person, runs or failed Implemented: conversationList.ts, marks.ts, Sidebar.tsx, pkg/marks, PATCH /api/threads/{id}/marks, waiting and last on thread summaries; Go, web and DOM tests pass; sidebar-recents, sidebar-row-actions, sidebar-projects and sidebar-archived screens pass at 390x844 and 1280x800
DES-049 A finished turn that changed files ends with a card of them: how many and their lines, a Review, and a row per file that opens its changes Implemented: core turnChanges, web TurnChanges; core and web DOM tests pass; screen conversation-timeline passes at 390x844 and 1280x800
DES-050 The Workspace is a pane of tabs beside the conversation: + opens items, tabs close, Expand and Show Two Tabs, tabs in the address, a full-screen sheet on a phone Implemented: Workspace.tsx, pane.ts, Inspector expanded; web, pane and route tests pass; workspace-pane-split, workspace-pane-expanded and the other Workspace screens pass at 390x844 and 1280x800
DES-051 Memories by scope: what a conversation, its session and each message used and wrote, read only Implemented: Memories.tsx, GET /api/threads/{id}/memory, Run.memory; web, route and Go tests pass; workspace-memories screens pass at 390x844 and 1280x800
DES-052 Conversation files, scratchpads, code editing, change review and artifact publication, in one Workspace panel opened from Conversation Settings beside a compact header Implemented: WorkspaceFiles.tsx, Workspace.tsx, ConversationShell.tsx, /api/threads/{id}/files, GET /api/threads/{id}/sandboxes; web, route, Go race and confinement suites pass; conversation-header, workspace-* and ide-* screens pass at 390x844 and 1280x800
DES-053 Notifications sort into the reader's own views: Inbox, Unread, Hidden and Done, with per-reader hide and delete Implemented; per-reader marks and counters, bulk API with isolation tests, DOM and route tests, phone/desktop captures
DES-060 Pull requests across workspace repositories, with board/list views and filters Implemented; pull_requests.go, History.tsx, endpoint and DOM tests; history-all and history-github screens registered for CI
DES-054 The sidebar lists Recents newest first, Pinned on top, Projects and Archived as views; each row says its project, its age or an unread dot, and whether it waits on a person, runs or failed Implemented: conversationList.ts, marks.ts, Sidebar.tsx, pkg/marks, PATCH /api/threads/{id}/marks, waiting and last on thread summaries; Go, web and DOM tests pass; sidebar-recents, sidebar-row-actions, sidebar-projects and sidebar-archived screens pass at 390x844 and 1280x800
DES-055 A sidebar row previews itself on hover or a long press, and the wave's preview carries its author's mark Implemented: RowPreview.tsx, peek.ts, TurnRail.tsx; web, DOM and screens pass (sidebar-preview, conversation-wave-preview) at 390x844 and 1280x800
DES-056 A one-time tip teaches search, dismissed once per person Evidence: sidebar-search checks the replacement Search navigation button; the tip card was removed
DES-057 Home files a new conversation from over its chat bar; a conversation's approval mode is a text control under the composer, Default or Approve for Me, within policy and audited Implemented: ApprovalModePicker.tsx, HomePage.tsx, pkg/threads/approval.go, internal/platform/approval_mode.go, PUT /api/threads/{id}/approval; Go, DOM and screens pass (home-project-above, composer-approval-mode). Per-message model and effort were removed (DES-067)
DES-053 Notifications sort into the reader's own views: Inbox, Unread, Hidden and Done, with per-reader hide and delete Implemented; per-reader marks and counters, bulk API with isolation tests, DOM and route tests, phone/desktop captures
DES-050 The Workspace is a pane of tabs beside the conversation: + opens items, tabs close, Expand and Show Two Tabs, tabs in the address, a full-screen sheet on a phone Implemented: Workspace.tsx, pane.ts, Inspector expanded; web, pane and route tests pass; workspace-pane-split, workspace-pane-expanded and the other Workspace screens pass at 390x844 and 1280x800
DES-051 Memories by scope: what a conversation, its session and each message used and wrote, read only Implemented: Memories.tsx, GET /api/threads/{id}/memory, Run.memory; web, route and Go tests pass; workspace-memories screens pass at 390x844 and 1280x800
DES-052 Conversation files, scratchpads, code editing, change review and artifact publication, in one Workspace panel opened from Conversation Settings beside a compact header Implemented: WorkspaceFiles.tsx, Workspace.tsx, ConversationShell.tsx, /api/threads/{id}/files, GET /api/threads/{id}/sandboxes; web, route, Go race and confinement suites pass; conversation-header, workspace-* and ide-* screens pass at 390x844 and 1280x800
DES-064 A connection maps its Slack members or GitHub logins to people, and a GitHub connection can be given its App's private key so the server mints installation tokens Implemented: ClientConnect.tsx, Clients.tsx, pkg/integrations/github/app_token.go, seeMapped in internal/platform/people.go; web DOM, pkg/integrations/github, pkg/people and platform tests pass; live GitHub minting not yet tried
DES-065 Sources shows the data catalog a reader sees: connectors, tables and columns, never data, with Crawl, Publish and Withdraw for the owner Implemented: CatalogBrowser in SourceCatalog.tsx, on GET /api/catalog and the connector routes; web DOM test passes; screens not yet captured
DES-066 A spend limit says what happens when it is reached, block or ask for approval with a grant cap, and the Directory names a person's projects Implemented: Billing.tsx (action, max_grant, max_grant_tokens), Directory.tsx (projects, projects_more); web typecheck and tests pass; screens not yet captured
DES-068 The agent editor controls the models and reasoning efforts people may choose per message Removed 2026-11-07: people pick agents, not models; see DES-067

DES-001: Working integrations

The public-web profile in examples/public-web/claude-code.yaml enables the program's built-in WebSearch and WebFetch only; user hooks and plugins still load. Supporting URLs are model-reported answer text, not verified citations. Actual HTTP tool events and a separate official-source retrieval validate search/open/version agreement. See public-source research for identity, permissions and unsupported browser operations. No console connection control is implied.

  • Build on the existing client, connector, credentials, project-binding, and generated API client paths. Keep API calls and identity in surface hosts and the platform. Use the existing tenant and permission checks.
  • The console must display saved connection state, expose only actions backed by a supported API, show in-progress requests and actionable failures, and refresh the saved state after a successful mutation. A successful local UI update alone is not a successful connection.
  • Preserve credential references and secret storage conventions. Never return saved credentials to the browser or include secrets in logs or error text.
  • Existing GitHub and Slack connector behavior is described in integrations.md and clients.md. Automatic resource linking, Drive, Notion, live search, and other board features require their own implementation evidence before being offered as working capabilities.
  • Source lifecycle foundation: bounded durable refresh attempts, last-good copies, typed failures, stale stop rules and publication access predicates are implemented. Native Drive/Notion boundaries, personal reference resolution, scoped lifecycle APIs, source dependency views and connection controls are implemented. Automated transport tests, memory/Postgres replay, HTTP contract tests, source integration DOM states and phone/desktop source-state captures pass. Atomic scoped creation, real resource selection, frozen-copy replacement, sync settings, current-policy scheduled refresh and confined unsaved rule previews are implemented. Live provider accounts, verified connector rule application and durable link suggestions remain pending. See sources for supported formats and limits.
  • Per-installation event subscriptions and actual registered native actions now have versioned saved controls. They tighten current adapter and action-policy grants and are rechecked at execution. Slack bridge directions are durable: inbound mirrors mapped human messages without waking an agent; outcomes sends permitted final outcomes and decisions; two-way supports both. Activity and retained source metadata are withheld, and private-context delivery is refused by the server. Native-host, contract, confinement and memory/Postgres replay tests exercise these paths. Live external delivery remains unverified.
  • Acceptance: exercise each newly wired control through its real host/API boundary, including a saved success, a visible failure, and denied access. Distinguish automated or simulated API checks from a live external-service trial. Record which services and actions were actually verified.
  • Managed Slack and GitHub delivery now retain message handles, accumulated answers and sequence cursors across client rebuilds and replica takeover. TestClientDeliverySurvivesReseatingAndReplicaChanges passes with the race detector on memory and two Postgres pools, using simulated Slack/GitHub APIs. It checks full-answer recovery, duplicate events and tenant/client isolation. Live external failover remains unverified; an external create followed by a crash before the database commit can still duplicate a new message.

DES-002: No dots between words

  • Remove middle-dot or bullet punctuation used solely to separate titles, statuses, timestamps, source modes, counts, or other adjacent metadata. Use layout gaps and clear labels while retaining readable text order.
  • The review screenshot's evidence examples should read as separate spaced fields: Supplier ETA live 9:42, Launch plan v3 snapshot Oct 18, and Retail calendar live 9:30.
  • A semantic status indicator beside text, such as the green live-source indicator, may remain. This requirement concerns separators between words; it does not remove punctuation inside content, dates, or code.
  • Acceptance: evidence pills and message metadata have no decorative text separators; labels remain understandable at narrow widths and when read by assistive technology. This requirement replaces separator examples in older boards where they conflict.

DES-003: Fork on hover or focus

  • Working interpretation of the review note "fork/date time hovering": show the message-level Fork action when its message is hovered or keyboard focus is within the message. Keep the control available on touch devices through a visible action or an accessible message menu.
  • Use a native button for operations and a link for navigation, with an accessible name, visible focus, and adequate target size. Pointer movement from the message to the action must not hide the action. Do not depend on a tooltip to make the action usable.
  • A conversation fork must preserve history through the chosen message as read-only context and retain lineage to the original conversation, subject to the control-plane spec's access and policy rules. Regenerating a sibling answer is a different operation and must not be labelled as a completed fork.
  • Acceptance: pointer, keyboard, and touch can find and invoke the action; unsupported or denied operations cannot appear successful. A functional fork is verified against the saved new conversation and its lineage.

DES-004: Date and time on hover or focus

  • Under the same working interpretation, reveal the message's full date and time on hover or keyboard focus without crowding its resting presentation. Provide a touch-accessible equivalent.
  • Use the recorded message timestamp, not a fabricated or latest-render time. Make the date and timezone unambiguous and retain machine-readable time semantics. Assistive technology must have access to the same information.
  • Acceptance: the displayed detail matches the stored timestamp, works across date boundaries, and remains available without a mouse. Showing or hiding detail must not make the action target move away from the pointer.

DES-006: Independent sidebar scrolling

  • The console fills the dynamic viewport. Main content scrolls inside its own column without moving the sidebar or the document.
  • Navigation and conversations scroll inside the sidebar only when that area is scrolled. Reaching its boundary must not scroll the main content.
  • Keep the sidebar header and account controls visible while its lists scroll, including in the phone drawer.
  • Evidence: App.tsx, Sidebar.tsx, and styles.css constrain the shell and contain sidebar overscroll. scripts/screens/sidebar-scroll.ts, run through the sidebar-scroll screen fixture, checks real wheel input, long lists, fixed header/account geometry and independent content scroll in Chromium at phone and desktop widths. Long content is inserted only for the layout test.

DES-052: Conversation files, scratchpads and the Workspace

  • Give conversation files, scratchpads, previews and change review one native workbench with direct header access and reloadable selections.
  • Share the bounded scratch directory with agent file tools. Require current conversation access, explicit saves and content-hash conflict detection.
  • Preserve unsaved drafts across drawer changes. Show busy, denied, binary, stale and failed operations honestly. Explain scratch retention.
  • Support code editing, imported unified patches and contextual review comments that prepare the composer. Publish exact saved revisions as immutable deliverables, and edit saved text artifacts through a working copy.
  • Implementation: WorkspaceFiles.tsx, reusable CodeEditor and ChangeReview, and the confined /api/threads/{id}/files API. See conversation-workspace.md.
  • Evidence: 739 console tests pass, including editor shortcuts, selected-code feedback, unsaved draft navigation, immutable copies, active-run refusal, conflict recovery and scratch-only sharing consent. Platform race tests cover concurrent saves, isolated copyback and publication consent. Client typecheck and 21 transport tests pass. scripts/screens/ide.ts verifies five real API flows: editing/reload, patch comments, scratchpad publication, stale saves and inert HTML previews. All 27 light/dark captures pass at 320, 390, 768 and 1280px widths, with tablet and narrow-phone reflow. Captures are reproducible under .screens-ide/, .screens-ide-dark/ and .screens-ide-focused/. Full platform, HTTP, artifact and thread race suites pass, including the required-query confinement sweeps and real-file mutation canaries. Go lint reports zero issues; console, renderer, web and client typechecks and the production console build pass.

Save as Artifact and diffs

  • A message (a structured review kept as its JSON), a scratchpad or a file saves as a versioned artifact and opens in a Workspace tab. Artifact versions and a file's saved and edited state diff side by side on a desktop and in one column on a phone, with review findings pinned to their lines.
  • Evidence: TestSaveAsArtifactKeepsAnswersMessagesAndScratchpadsAsVersions, TestAStructuredReviewIsToldFromText, the HTTP contract, artifact-save.dom.test.tsx, review-pins.test.ts, code-diff.test.ts, and the workspace-diff and workspace-save-message screens.

Scratchpads

  • A conversation has up to 50 named scratchpads, created, renamed, deleted and edited in the Workspace, read by its agents as scratch:<name>.
  • Evidence: pkg/scratchpads store tests (versions, names, bounds, tenant and conversation isolation, deletion with the conversation), platform and HTTP contract and confinement tests, scratchpads.dom.test.tsx and the workspace-scratchpads screens.

One Workspace panel

  • Files, Context and Activity leave the conversation header for Conversation Settings. The header keeps the people facepile, Share and Conversation Settings: icon-sized controls, one 4px gap, no side padding, an accessible name and a tooltip on each, and Share's label only on a wide conversation.
  • Workspace holds the session's items as tabs: Sandboxes (the session sandbox and a nested sandbox per agent run), Files and Artifacts. Each section and run selection has an address. It is the shared inspector on a desktop and a sheet on a phone.
  • Evidence: workspace-hub.dom.test.tsx (sections, nesting, mounts, files a run left, refused copyback, empty and failed states, opening a file, a run and an artifact), workspace.dom.test.tsx (the menu), route.test.ts, pkg/runs/sandbox_test.go (merge, bounds, write-through, tenant), internal/platform/workspace_files_test.go (isolated copyback and unisolated writes are recorded; another tenant gets 404) and the HTTP contract and confinement sweeps. Screens: conversation-header, workspace-menu, workspace-sandboxes and workspace-artifacts.

| DES-058 | Replay a finished turn with a chosen agent in a saved fork | Implemented; replay unit and DOM tests; conversation-replay-agent screen registered for CI |

DES-064: People maps and GitHub App keys on a connection

  • The connection form takes an optional people map, one login=subject (or Slack member=subject) per line or separated by commas. Blank and malformed lines are left out, never sent. It is sent as slack.people or github.people, which the server already bounds and validates.
  • A connection's card says how many people it maps.
  • Saving a GitHub client records each subject it maps in the workspace's people with the source github, as a Slack client's map already did.
  • A GitHub token may be the App's private key PEM (PKCS#1 or PKCS#8). With identity.app_id and identity.installation the server signs an RS256 App JWT, exchanges it for an installation token and refreshes it two minutes before it expires. Without them the client is refused when it is created.
  • Evidence: settings.dom.test.tsx (maps a GitHub client's logins to people and counts them), TestAppTokenSourceMintsAndRefreshesInstallationTokens, TestAClientsPeopleAndThePolicysSubjectsAreRecorded, TestASightingIsValidated. A live installation has not been tried.

DES-065: The data catalog in Sources

  • With no source selected, Sources shows the catalog of connected systems the reader sees (GET /api/catalog): each connector with its system, whether it is published, how many tables it holds, when it was crawled and its last error; and each entry by title or path, opening to its columns.
  • Only a connector's owner (mine) sees Crawl and Publish or Withdraw. Withdraw is DELETE /api/catalog/connectors/{name}/publish. A refusal is said in words. Nothing renders while the reader sees no connector.
  • Evidence: integrations.dom.test.tsx (the data catalog lists what the reader sees). Screens are not yet captured.

DES-066: Approval limits and a person's projects

  • A spend limit's form sets what happens when it is reached: Block, or Ask for approval with an optional dollar and token grant cap, sent as action, max_grant and max_grant_tokens. The summary line says it.
  • The Directory's person row names the projects the server lists for them, and how many more there are.
  • Evidence: web typecheck and the console suite. Screens are not yet captured.

DES-067: Model and effort for one message

Removed 2026-11-07: people pick agents, not models. Each agent's definition sets its model chain, and nothing overrides it per message. The picker, model and effort on posted messages, and choices on agent specs are gone.

Review and implementation evidence

The approved implementation pass covers supported Slack and GitHub workspace connection controls through the existing clients API, removal of separator dots in the boards and touched console metadata, accessible native human-message timestamps, and Fork hover/focus behavior in the board. Native conversation forking now has a persisted operation, bounded passive history, source-chain confinement, selected sources applied to real turns, and an explicit bring-back action that posts without executing tags or tools. Shared message action wiring remains tracked separately. Creating a configured client is not evidence that external credentials work or that a live Slack or GitHub delivery has succeeded. For GitHub default-agent routing, configure the app's own bot login so native mentions reach that agent. The form requires the login when a default agent is supplied; naming an agent explicitly remains a separate routing path.

Requirement Implementation and evidence Remaining work
DES-001 apps/web/src/ClientConnect.tsx, Clients.tsx, and api.ts use the existing POST /api/clients contract, including slack.people and github.people maps (DES-064). Settings DOM tests cover Slack values, GitHub references and routing, server refusal, permission gating, secret clearing, and default-deny reach. Reproducible phone/desktop captures cover Slack and GitHub forms, pending requests and server refusal; new copy lives in packages/components/src/copy.ts. Supply installed-app credentials and a reachable signed webhook listener, then observe real replies. Native Slack/GitHub installation backend and offline API tests now pass, with disabled clients and pinned credentials. Live registration, consent and delivery trials remain pending.
DES-002 All 26 board HTML files render in Chromium without separator dots. Main evidence fields wrap without horizontal overflow at 390px. ConversationShell.tsx, Room.tsx, Clients.tsx, and web AgentMessage.tsx use gaps or readable phrases. The Mailbox.tsx row says "N to decide" as its own label beside the preview (DES-038). Older untouched console and shared presentation copy needs review as it changes.
DES-003 boards/ForkConversation.html and assets/boards.css reveal actions on hover/focus, retain touch availability, and navigate to the existing prototype panel. Chromium checked hover, focus, target focus, and stable message dimensions. A native fork needs a saved conversation operation, lineage, permissions, routes, and isolation tests. The board action is a prototype.
DES-004 Human messages and announcements in Room.tsx use recorded timestamps with full local date, time, and timezone on hover, focus, and tap. Room DOM tests cover the recorded instant, accessible description, and dismissal. A Chromium phone regression reproduced tooltip overflow before the fix; phone and desktop captures verify placement through the existing panel-gutter helper. Carry real recorded timestamps through agent-message presentation.
DES-005 Root AGENTS.md links this record and requires keeping it current. Update evidence with each subsequent implementation.

Validation for this pass: console production build, workspace typechecks and JavaScript tests, phone and desktop screen checks, and git diff --check. DOM tests and connection screen fixtures use simulated API responses; the board and console layout checks use local Chromium. Neither establishes live external delivery.

The screenshot supplied in this review is the source for DES-002. The hover behavior in DES-003 and DES-004 is an explicit working interpretation of the review note and can be refined here as the interaction is reviewed.

ChatGPT and Claude may be consulted as interaction references when accessible. No inspection of those sites is claimed by this document, and they are not integration providers or a new dependency of the console.

For each implementation, record the relevant requirement ID, code paths, automated checks, manual interaction checks, and any remaining external setup. Mark a requirement verified only when its acceptance evidence is recorded. Keep docs/architecture/overview.md current when a capability lands. The documentation entry for DES-005 does not imply DES-001 through DES-004 have been implemented or live-validated.

Built-in handles and Slack conversation navigation

New agent choices and starter actions use humagen-analyst, humagen-writer and humagen, the entry agent, which builds agents. code-reviewer, security-reviewer, architect-reviewer and qa-reviewer review in an ordinary conversation. Every workspace has humagen and approver; the writer and the analyst come with the Core package and the reviewers with the Review package, which a workspace installs from the Store tab under Agents. A starter is offered only for an agent the workspace has. Compatibility registry definitions preserve saved revisions, old schedules and existing grants. The humagen-builtins screen checks all three names at phone and desktop widths.

A Slack task card exposes Open Conversation when the host has configured HUMAGEN_PUBLIC_URL. It points to the run's conversation, including a later run in an existing conversation, and remains attached throughout streaming and settlement. Adapter and Slack rendering regressions cover the link.

DES-007: Agent badge containment

Agent names and status badges wrap as whole items, and badge height follows its text. Long scope labels truncate within the badge without losing their accessible text. The agent-status-badges browser state makes the analyst the workspace default and checks both badges in dark mode with enlarged text. The containment assertion reproduces the reported failure before the fix.

Library subsystem implementation evidence

  • pkg/audit, internal/platform/audit_view.go: durable pending/succeeded/failed change attempts, bounded redacted snapshots, retained legacy adapters and exact-owner personal filtering.
  • pkg/memory, internal/httpapi/personal_memory.go: private personal owner namespace, reviewed kind/provenance, expiry at composition, immediate audited forget and persisted use counts.
  • pkg/prefs/personal.go: persisted briefing, notification delivery policy, midnight/DST quiet hours and privacy choices. Native delivery is implemented in pkg/notifications and the authenticated console worker, with restart/dedupe, current-reader confinement, hourly digests, quiet hours and projection-only acknowledgements. Email remains unavailable.
  • apps/web/src/Audit.tsx, MemoryLibrary.tsx, PersonalPreferences.tsx: standalone views for shared navigation integration. Versioned skill draft/test/publish/promotion workflows use real configured agents and the existing pinned runtime, with explicit tool intersections and forced Ask on tests.

DES-008: Contextual agent and project discovery

Offer Find an Agent or Project inside the new-conversation composer's picker. Home keeps its message composer and actual updates. Searching matches readable projects and available agents through the existing bounded API. Choosing a match updates the current selection, preserving the draft and attached files; an empty draft receives the search description. Search Enter does not send a message. Escape returns to the picker before closing it. Existing conversations keep their fixed project and have no global discovery action.

The composer DOM regressions cover search, selection, attachment preservation, explicit submission, empty-draft seeding and keyboard focus. The native workspace-find-help and workspace-find-help-selection screen states exercise matching and selection without creating a conversation.

DES-009: Action vocabulary and inbox recovery

Message actions use the shared 24px-grid icon set, with a reply arrow for Reply and semantic glyphs beside Fork, Bring Back, skill, memory and Redirect labels. Footer icons share a 16px size and coarse-pointer targets are at least 44px. Existing callbacks, action names and keyboard behavior are preserved.

An inbox failure groups its callout, recovery actions and reference using the shared stack layout. Alert diagnostics that accompany an actionable failure sit under Technical Details; standalone alert bodies remain visible. Titles, metadata and About links wrap with separate spacing for each section. Render regressions cover the failing layout and native inbox-alert-recovery states capture collapsed and expanded diagnostics on phone and desktop. The native conversation-feedback-reasons state captures the turn footer's Not helpful prompt with its quick reasons (FEEDBACK_REASONS), a picked reason and a comment on phone and desktop, and fails if the prompt leaves the viewport.

DES-010: Top-level notifications

Notifications has one bell navigation entry and a single feed of requests and updates. There is no Needs You or Updates tab or separate list section. The feed starts with all messages; one Filter popover combines status (All, Open, Resolved) and type, with an active-filter count and Reset. Search stays in the same toolbar. Filtering preserves the selected reading pane and server paging. Alert Rules is the only companion tab, visible with alerts:read, and uses the existing native rule editor without another Overview/Rules strip.

Both /notifications and existing /inbox links open the same feed. Message, alert and kind selections remain addressable. The navigation badge counts actionable work and always opens Notifications. Machine readers with runs:read use the same feed without human delivery polling. Notification preferences remain at /you/notifications.

The host retains one authenticated delivery reader. Projection acknowledgements remain separate from resolving the original message and never add duplicate feed rows. Reader changes clear stale delivery rows; polling and acknowledgement failures retain recovery. A delivery-status failure leaves the feed usable. The Workspace/Notifications Storybook stories exercise the real feed, combined filters, empty/failure states, phone layout and Alert Rules navigation. Validation: 30 route/navigation checks and 43 focused DOM checks pass. Both production builds and console/Storybook typechecks pass. The Notifications browser journey passes 20 light/dark states at 320, 390, 768 and 1440 pixels, including the combined filter panel, Alert Rules, errors, empty states, message dismissal and a selected reader retained outside the filtered list. That journey ran against the Storybook stories, which were removed on October 30, 2026. The concurrent full console run reports 636/637 passing; its remaining failure is the tree at depth 4 indents one level at 390px, and deeper rows say where they sit (ok(indents.length > 0)) in the other session's project layout work.

DES-053: Notification views and a reader's own marks

Every notification stays in one list no longer. The page opens on Inbox, what is open for the reader and not hidden by them, read or not, unread rows with a dot and stronger weight. A segmented control beside it switches to Unread, Hidden (the hidden box) and Done (resolved or dismissed for everyone), each with its count; Done is not counted, since no counter keeps what is settled. The view is in the address (/notifications?view=hidden; the Inbox is left out). Rows carry no state word: the view says it.

Opening a message marks it read. Each row offers Mark Read or Unread, Hide or Unhide and Delete on hover and keyboard focus, and the reading pane offers the same. Rows are picked with a checkbox, or x on the focused row, and the toolbar then marks them read or unread, hides, unhides or deletes them; with nothing picked it offers Mark All Read for the view. Hide and Delete ask no confirmation: a toast says what moved and offers Undo for eight seconds.

Each mark is the reader's own (pkg/inbox: mark.Hide, mark.Deleted): nobody else's inbox, views or counts change, and a shared message is never removed from the record. Delete takes it out of every view of the reader's; Restore brings it back. A run's open question can be hidden but not deleted. The sidebar badge is the Unread view's count, announcements included, and what was hidden or deleted leaves Home's and Slack Home's Needs you and its total, which read the same open state. API: view on GET /api/inbox, POST /api/inbox/marks (1 to 200 ids), POST /api/inbox/read-all (the newest 600), with inbox and hidden in the counts. Acceptance: TestViewsArePerReader, TestMarksStayInTheirTenant, TestViewsAreBounded, TestCountsAgreeWithAScan (hides, deletes and restores among its random steps), TestInboxMarksArePerReader, notification-views.dom.test.tsx, the route tests for view, and the notifications-inbox, notifications-hidden and notifications-bulk captures at phone and desktop width.

DES-011: Docked conversation workspace

Context, People & Access, Activity, Share and Deliverables use the shared inspector dock. At 1024px and above the drawer occupies its own flex column, reflowing the conversation and composer. At smaller widths it is a native modal edge drawer with contained focus. Closing returns focus and restores the main column. The header has one left-aligned title, project/channel metadata and a compact action row. Share owns project placement; People & Access lists and changes participants and can make a shared conversation private, but does not offer a second Share. More contains Activity and Deliverables. Control geometry uses the existing shared icon family. Message actions below a message are icon-only, with the action's name as their accessible name and hover label.

Dark console surfaces use neutral charcoal planes, IBM Plex Sans for reading and headings, with IBM Plex Mono for editors and technical text. Agent hues and focus use the existing accent tokens. The conversation-drawer-reflow browser state asserts geometry and desktop/mobile modality. Existing DES-010 removes the boxed Notifications disclosure and retains the canonical bell destination.

Search Workspace opens a centered native modal from navigation or Cmd/Ctrl+K. Filters cover projects, agents, conversations, messages, files and sources. Results keep native links, contextual excerpts and keyboard navigation; Escape restores the opener. Pending requests clear previous results, and failures show an explicit error. Search never starts an agent.

GET /api/discovery?content=true adds saved human messages and original agent requests/answers, published file text and authored local source passages. Current permissions, project placement and private/fork access confine every result. Message/run search covers the past year, at most 1000 matching candidates per kind; the modal returns 20 results. File text is capped at 65536 characters at publication. Older files retain title, description and existing preview lookup until republished. Source search uses the existing BM25 index, at most 50 readable local sources. Retained external source passages are withheld pending current-reader file authorization. Private prepared context, reasoning and tool payloads are excluded. Live providers are not queried on each keystroke. This does not rewrite previously retained conversation text; its existing access rules continue to apply.

Indexes derive from authoritative records and rebuild after restart. Go tests cover indexing, replay, tenant confinement, current file versions and deletion; platform tests exercise readable and hidden content. Console DOM tests exercise native result destinations and request failures. The workspace-search-modal browser state checks centering, keyboard traversal and focus return.

DES-013: Project selection and starter suggestions

Projects use a folder with a small second edge underneath. The composer footer opens a searchable project drawer directly, including when Personal is selected. Personal and Company remain explicit homes; selecting another project resets only the channel. Draft text and attachments stay in the mounted composer. Existing conversations retain their fixed placement and Share review.

Starter suggestions wrap with consistent marks and touch targets. They stay visible while the person edits a draft and change context only when the project changes. No action is hidden at phone widths. A suggestion fills an editable draft with its agent @mentioned first while retaining the project (DES-041); sending remains explicit. DOM regressions cover Personal selection, preserved drafts and project-aware starters. The home-project-picker screen exercises the complete selection flow and checks all three suggestion buttons fit within the phone viewport.

Validation for DES-011 through DES-013: production build; 15 workspace typechecks; 593 console tests; complete text-index, thread, run and artifact store suites with -race; focused platform access/projection/replay and HTTP contract tests; shared Slack validation (79 tests). Dark Chromium captures passed 18 phone/desktop states and 12 states at 320, 390 and 1280px, including project switching, all starter suggestions, search focus return and drawer reflow. Local captures live under .screens/ui-cleanup and .screens/project-selection in the cleanup worktree. No live deployment is claimed. This layer builds on main after PR #91 and retains the merged stack's action, notification, native-file, source and fork-lock changes.

DES-014: Hierarchical composer context

The plus menu has consistent root actions for files, Agents, Projects and Skills. Each category opens a named pane with Back and predictable keyboard focus. Agent search and discovery stay in Agents. Project choices include Personal, Company and readable projects, with the existing project lock for started conversations. A lone internal General channel does not appear as a loose control. Real channel choices use full-width selected rows within their project context.

Skills come from the existing project-scoped completion resolver. Choosing one prepends its normal skill tag to the current draft, preserving text and files, and sends nothing. A project change immediately withholds old skill rows and completion options while the new project loads; refused reads offer no skill. DOM and native browser states cover root categories, nested choices, keyboard Back/Escape, draft and file preservation, and explicit message submission.

Validation: 607 console tests passed; all 292 phone/desktop screen captures passed, plus 15 dark captures at 320, 768 and 1440px. The eight showcase images were refreshed from the reproducible screen fixtures.

DES-015: Shared web component foundation

Keep React, Vite and Tailwind. Standard shadcn Radix controls belong in packages/render-web/src/ui, with one semantic theme and the actual bundled IBM Plex Sans Variable font for reading and headings. IBM Plex Mono serves file editors and technical text. Both fonts are self-hosted with their licenses. Neutral light and charcoal surfaces use red as the default interaction accent, with real yellow and green presets. Existing purple, blue and teal preferences remain valid. Gold attention, green success and agent identity colors retain their separate meanings. Glass and a thin static color streak belong to chrome; content and popovers keep opaque readable surfaces with restrained bevel/shadow. Existing button and field helpers share the same variants and sizing. Wrapped inline code repeats its padding and rounded background for each fragment, and long tokens stay inside the text column. The session-inline-code browser fixture replays the confirmed message and a long path, checking every fragment. Web-only resource browsers remain controlled presentation components; the shared surface-neutral contracts and Slack renderer remain intact.

Acceptance: production builds, workspace typechecks, standard format/lint checks, dense shared controls, correct loaded font, keyboard focus, reduced motion and phone/desktop reflow. The Controls and ResourceWorkspace stories provide a repeatable design review surface.

DES-016: Skills packages and managed Memory chains

Skills is a folder manager with import, file navigation, preview/source editing, new immutable drafts and ZIP download. SKILL.md and resource bytes use the native library revision store and saige's parser/snapshot. Existing testing, publication, promotion and agent bindings remain. Frontmatter grants no tools; supporting files are read only from the exact package pinned to a run.

Memory is organized by real authorized owners. Retained entries have file addresses, projected provenance and native review/correction/forget operations. Management status reflects actual configuration. Chat opens a private native conversation draft without putting note text in the URL. Pending and expired memory remain excluded from automatic context. Searching a scope rail preserves the current chain and any correction draft. Dirty Skills drafts require Save or explicit Discard before changing scope.

Acceptance: package bounds, malformed paths, immutable versions, replay, tenant and personal boundaries, current promotion capabilities, separate failure/empty states, native folder import/save/download, scoped deep links, draft preservation and private chat placement. Details and limits: managed Library.

DES-017: Consolidated navigation and compact operational screens

Library is one sidebar link with Sources, Skills, Memory and Deliverables tabs. Agents groups directory, network, assignments and controls. Operations groups context health, integrations, action policies, schedules, usage and audit. Notifications combines requests and updates in one feed, with Alert Rules as its only companion tab and one status/type filter panel. Native routes remain usable, and permissions control destinations and tabs through one shared definition. Search and a single status/type Filter popover replace the long inbox category strip; local search covers loaded updates and states when older pages need to be loaded.

Action policy uses a readable width, compact labeled rows, descriptions, inherited/effective values and one aligned save action. Context Health replaces zero-filled dashboards with one source action when empty; populated views have aligned filters, a compact status strip and details after selection. Development fixture disclaimers are kept out of product copy.

Profile, Notifications, Privacy and workspace administration share compact SettingsFormRow controls. Privacy uses icons and labeled switches with hints, a direct Memory link and one aligned save action. Audit uses a shared Radix/react-day-picker calendar with local date/time inputs, host conversion to ISO timestamps and positive-range validation capped at 31 days. Compact event rows expand retained details; resource, Refresh and Export actions carry icons. Announcements use a compact card, one Open Announcement action and a labeled eye-with-slash Hide button with a busy guard.

Acceptance: route and permission regressions, existing operational mutations, phone/desktop navigation, policy and Context Health captures, narrow reflow and keyboard selection. Automated delivery checks pass; final browser/CI verification for DES-015 through DES-018 remains pending. Current evidence is recorded below.

DES-018: Motion, visibility and named project metadata

Native drawers and the search modal enter and exit with short Tailwind transitions. Outgoing content is inert and hidden from assistive technology immediately; its visual shell survives only long enough to finish leaving. Reopening cancels pending removal. Desktop drawer width animates while the panel keeps its width, so the conversation reflows without scaling text. Nested composer panes have directional reveals and Radix folders expand and collapse. Reduced motion removes travel and delays. Waiting states remain still.

Project rows show up to two named agent pills and useful nonzero activity. Descriptions and additional agents expand under Details; long names wrap. The sidebar starts with + New, followed by Search Work, with appropriate workspace/operations separators. Home's project control opens a drawer using its project icon and name, with no dropdown caret.

Acceptance: rapid drawer close/reopen, immediate focus return, nested keyboard navigation, reduced motion, desktop dock reflow and narrow project metadata.

Conversation pin writes are serialized while the display updates optimistically. Confirmed saves replay later pending operations; a refused save rolls back only its own operation. Focus recovery and visibility of the active older conversation are preserved after unpinning. Focused concurrency and recovery regressions cover these cases.

Source access in the current delivery

New Source distinguishes native text, Drive and Notion paths from providers that need a connector. Configuration saves refresh cadence with project scope. Live query, collected copy and copy plus live query describe acquisition, not a broader reader grant. Selected resources constrain fresh provider reads. Frozen snapshots and external saved variants fail closed rather than query a broader or newer collection. External retained content and per-file metadata remain withheld without current-file authorization; provider failures never fall back to retained external text.

New evidence records native source authority. Network-free reader projections withhold external, unknown and missing-source citations pending an authorizer. This does not erase historical conversation text. See sources.md for that limitation and the separate reviewed-summary publication path. Source access and final integration checks remain in the active task queue until their regressions pass.

DES-019: Readable project work

The overview uses apps/web/src/ProjectWork.tsx for the real paged conversation records. Rows keep agent, title, last activity and explicit state together. All, In progress, Needs attention and Finished filters describe the loaded rows only; when an older page exists, that boundary is stated beside the list. Failure counts are not described as approval counts or outcomes awaiting review. Metadata uses gaps rather than separator dots. On phones, status moves below the title and filters wrap. Supporting notes and schedules share a quiet plane.

ProjectTasks in Projects.tsx owns the API requests. Initial read failures offer Try Again instead of appearing as an empty project. Pagination failures retain the current rows and offer See More again. Responses from a previous scope cannot overwrite the current list. DOM tests cover filtering and native conversation selection, failure/retry and obsolete-scope responses.

DES-020: Shared workspace design previews

The Storybook app this requirement used was removed on October 30, 2026. The evidence below records checks made before then; make screens checks the console itself.

The newer consolidated Library, Agents, Notifications and Operations hubs remain owned by the shared permission-aware navigation definition. This pass does not restore the older expanded sidebar. The console and Storybook share the native navigation item renderer and the same semantic controls and fonts.

The workspace principles and reference research record the adopted direction and public portfolio credits. Workspace/Project work in Storybook renders production ProjectWork, navigation, Page and Tabs components with isolated fixtures, the shared renderer font entry and console CSS. Its workbench mounts the console's own Sidebar (New, Search Work and Notifications above the grouped sections, pinned projects and conversations, conversations grouped by project with agent and people participants), the phone DrawerButton, and the project header with Lead, breadcrumb, More menu and every project tab. The sidebar's one conversation-list request is answered from the story fixtures. Overview, light, phone, empty, loading, read failure, paging failure, filter/open and navigation stories exercise the design. Story actions are local previews, not saved workspace mutations.

Integration evidence: all 619 console tests pass on the committed managed-library base. The active branch's project-work filter, read-retry and stale-scope tests also pass, as do console and Storybook typechecks, both builds and 20 light/dark Storybook browser states with the newer shared typography and controls.

Current delivery checks pass: all 15 workspace typechecks; all nine workspace test tasks, including 647 console, 18 client, 193 Slack, 58 adapter, eight screen helper and 46 core tests; the full Go suite with -race; Go lint with zero issues; Biome; API lint with five existing ignored findings; and production and Storybook builds. Earlier focused calendar/preferences and source-access regressions also pass. All 74 focused native browser captures pass with zero layout findings across dark phone/desktop and light 320px/desktop. The complete CI matrix and merge status are tracked in PR #99. Live provider-account trials and a production deployment are not claimed here.

DES-021: Conversation participants and independent pins

A conversation's row is its title alone. Who took part shows in the conversation: its agents in the header (DES-032) and its people as overlapping faces on Share. A project group is a disclosure; collapsed, it still marks the conversation that is open.

Project headings and individual conversations each have a pin control. A project's actions menu also offers Pin Project, including before it has any recent conversations. Both appear under Pinned and save independently through personal preferences. The pinned_projects API field holds up to 50 project addresses, most recently pinned first; the workspace is ~. New pins require project read access. Existing unreadable shortcuts stay hidden without blocking changes to other pins. Pin controls remain visible when pinned, on keyboard focus and on touch pointers. Save failures restore the previous list and report the failure beside its row.

Evidence: Sidebar.tsx, Projects.tsx, preferences.ts, pkg/prefs, the preferences HTTP route and the regenerated client contract. DOM tests cover participants, pin/unpin, reopening, concurrent saves and refusal. Store tests cover bounded private lists, memory restart, older records and write failure. HTTP tests cover unreadable projects, revoked access and independent conversation pins. The sidebar-participants browser fixture checks save/reload, independent unpinning, rows that name no participants, and touch targets at 320, 390 and 1280px in dark mode. Its multi-person roster is a simulated list response; pin persistence uses the native API. The open drawer uses its own bounds checks rather than page-content gutters.

DES-022: Conversation lifecycle in the consolidated workspace

Conversation actions offer Pin, Rename, Archive and Delete. Since DES-054 the sidebar's Archive is the reader's own and is undone from its Archived view; Delete still queues the conversation for an admin. Existing participant identity, project pins and keyboard focus are retained when rows move or disappear. An archive is hidden from conversation lists and becomes eligible for deletion after 30 days. Delete requests immediate eligibility; neither action removes messages before admin approval. Settings > Deletion queue offers Restore and Approve Deletion, with approval disabled until due. The API requires workspace governance and confines every row and mutation to the current reader.

The server returns at most 100 queued conversations, due ones first, and the console refreshes the batch after each review. Approval atomically removes stored messages and search entries, retaining a hidden tombstone. Run journals retain their existing history; this feature does not erase journal retention.

Evidence: pkg/threads/archive.go, internal/platform/thread_archive.go, the archive/deletion HTTP routes, DeletionQueue.tsx and sidebar actions. Store regressions cover restart and tombstones; API regressions cover admin authority, eligibility, queue bounds and batch refill. DOM regressions cover explicit approval, disabled early approval, restoration, refusal and the combined menu.

DES-023: Branding from the spec

  • The console's name, tab title, sidebar logo and wordmark, icons, installable app manifest, palette and typefaces come from branding in the spec (spec.md): the System document's for the deployment and what is served before sign-in, and a Platform document's for its workspace once its people sign in. Everything left out stays Humagen's.
  • The server writes the deployment's branding into the page and manifest it serves, and serves replaced icons by the console's own names, so a branded deployment needs no rebuild and leaves the checkout clean.
  • Colors are checked when the spec is: text at 4.5:1 and the accent at 3:1 on their surface in each theme. The accent is the console's default, workspace in a person's settings, and a person may still pick their own.
  • Files are read at start. A missing file, an SVG with a script and an icon under an unknown name fail the start.
  • The text is the spec's too: the welcome announcement, the suggestions on an empty conversation, notification emails and any of the console's own text by key (branding.copy, keys from humagen config copy-keys). Humagen's own welcome and email text say the product's name in place of Humagen.
  • The console reads the workspace's branding before its modules load, so its text, tab titles and logo are in place from the first frame and one brand never flashes in for another. The product's own inbox messages are shown from its name.
  • Fonts may be files the server serves (fonts.files), the deployment's in public like its icons and a workspace's behind sign-in.
  • Evidence: TestBrandingReads, TestBrandingRefuses (pkg/spec), TestLoadReadsFilesAndMergesWorkspaces, TestLoadRefusesWhatCannotBeServed (internal/branding), TestTheConsoleIsServedBranded, TestAWorkspaceSeesItsOwnBranding (internal/httpapi), TestBrandingTextReads, TestBrandingTextRefuses (pkg/spec), TestTheWelcomeIsTheBrandings, TestNotificationEmailsSayTheBrandingsWords, TestTheProductsOwnSenderIsShownByItsBrandedName, TestFontFilesAreServedAndNamedInTheStylesheet (internal/platform) and apps/web/src/branding.test.ts.

DES-024: Agent calls read as messages

  • A call from one agent to another (subagent, handoff or delegation, all through pkg/call) is drawn as a message: the caller's mark, an arrow, the callee's mark and the text the callee was given. The callee's answer follows as its own message.
  • Calls nest under the caller's turn, not flat in the thread. While a call works it is open; once it ends it collapses to one line, which opens again on click or Enter.
  • A call is not drawn as a task row with a work step count.
  • Acceptance: a turn with a subagent shows the call as a message with both agents' marks and the prompt, the answer under it, and collapses when ended.

DES-025: Stop on the agent's mark

  • While an agent works, its mark animates. Hover, keyboard focus or a tap shows a stop square in its place. The mark is a button named Stop <agent>, at least 24px, with visible focus.
  • Stopping asks the runtime (POST /api/runs/{id}/stop). The mark shows stopping until the run ledger records an end; it never claims the run ended first. Fiber stops runs attached to it; runs it delegated keep going.
  • A run waiting on a person is not working: its mark is still and offers no stop by hover. Anything waiting on a person must not animate.
  • The composer only sends. While the reply to the last message works, a new message queues behind it and the queue shows above the composer. Esc in an empty composer stops the agents the last message started.
  • There is no separate Stop Turn button on an answer.
  • Acceptance: a working run's mark stops it with the pointer, the keyboard and touch; the composer queues a message sent while a reply works and sends it when the reply ends.

DES-026: Activity is every agent run, in time order

  • The Activity drawer opens on every agent run in the conversation, oldest first, one row each: the agent's mark (stoppable as DES-025), its name, who asked it, the last thing it said and when. There is no count line, no filter (All, Handoffs, Tool Calls, Decisions) and no Hide Tools.
  • A row opens that agent's conversation, replayed as a chat in time order: each message it was given and by whom, the exact input a helper was given, its answers, its tool steps as one line each that open on click, and its calls to other agents as messages that open that agent's conversation. Several calls to one agent read as one conversation with a divider for each call, scrolled to the call picked.
  • A trail at the top names the path (All runs › lead › researcher); each part opens its level. Each level has an address in route.ts.
  • One Copy Conversation in the header copies what is on screen as Markdown. There is no per-item Copy As.
  • Acceptance: from the list, a reader reaches any run's conversation and back by the trail, and Copy Conversation copies what is on screen.

DES-027: Drawer headers align

  • A drawer's header has the page header's height and divider, so their lines meet. Controls in a drawer header never wrap to a second line; what does not fit goes below the line.
  • Acceptance: at desktop width with a drawer open, the divider under the page title and the divider under the drawer header are at the same height.

DES-028: Share is People & Access

  • The header's Share opens the People & Access panel: who is in the conversation, its visibility and its project, with the audience review inline. There is no separate Share dialog. The old address /conversations/{id}/share opens the panel.
  • Acceptance: one Share control, one panel; the old link opens it.

DES-029: Status only when it adds information

  • A turn that completed shows no status chip: a still mark and an answer say it. Status shows for working (the mark moves), waiting on a person, failed and stopped.
  • Acceptance: a completed turn has no Done label; the other states still read.

DES-030: One disclaimer under the prompt bar

  • The AI disclaimer is one centered line under the prompt bar, the same before and after the first message. It names the product, from the spec's branding.
  • An agent's answer does not repeat it.
  • Acceptance: a conversation shows the disclaimer once, under the composer, on a new conversation and on one with answers.

DES-031: Checkpoints, not agent lines

  • A person's message has no line under it naming the agent: the answer below names it.
  • When a router picked the agent, or one of several joined, a checkpoint says so between the message and the answer: a rule, a small route icon, the agent's mark and why. Nothing else is drawn for a plain answer.
  • Acceptance: a direct answer has no line under the message; a routed one has one checkpoint naming the agent and the reason.

DES-032: Who took part, by name

  • The conversation header shows the first three agents that took part, each by mark and name, then +N for the rest. It does not say a count such as "1 agent took part". Every name is in the group's label and on hover.
  • Acceptance: one agent shows its mark and name; five show three and +2.

DES-033: Thinking and steps inline

  • A turn reads in the order it happened: words, thinking, steps and calls to other agents, each where it began in the answer (Task.at, Thought.at). Steps recorded before they had a place follow the answer.
  • A run of steps is one quiet line with an icon that says what they did ("Read plan.md", "Searched the web, read files"). Open, each step shows the input it was given and the output it returned. A step waiting on a person keeps its group open; a failed one is counted in the line (DES-048).
  • A finished turn folds its steps under one "Worked" line.
  • Acceptance: a turn that read, wrote, then answered shows the read and the write between the words they came between, each with its input and output.

DES-034: How long a turn worked

  • The Worked/tools control has a minimum 44px touch target on a coarse pointer. The canonical session browser state scrolls it into view, measures it and opens/closes Details before capture.
  • A finished turn's "Worked" line says how long it worked: "Worked for 32s". The time runs from the run's acceptance to its completion on the stream, or from the run record's creation to its last change when the stream is gone.
  • Acceptance: a run accepted at 0s and completed at 32s reads "Worked for 32s".

DES-035: Initials and mention profiles

  • An agent's mark at 16px or more is a small bot in its color, its shape drawn from its name. A working agent's bot hops, and from 24px the orb on its corner moves with what it is doing. Where there is no canvas the mark is its initials on its color: two words give two letters, one word adds A for agent ("LA" for lead).
  • A mention of an agent is a link to its profile. Hover or focus shows a card with its initials, name, model or model policy and description.
  • Acceptance: @lead in a message links to lead, and hovering it shows lead's description and policy.

DES-036: The composer holds the pick; the first message goes first

  • A project picked from the plus menu shows inside the prompt bar, not under it, so the bar keeps its height. Only the disclaimer is below it. An agent picked there is a mention in the box (DES-041).
  • Starter suggestions are centered. When they overflow, they scroll sideways with fades and chevrons at the ends.
  • A new conversation's first message posts before anything queued behind it. If it fails, its words return to the composer and nothing queued is sent.
  • Binary image, PDF, Office, audio and video files travel as bounded uploads, with original bytes and names retained through queue editing, waiting and retry. A failed first send restores its files beside its text. MIME types are sniffed on the server; metadata never grants a model a modality it cannot read.
  • Posted messages retain a file reference for each upload, for the author and other readers, after reloading the conversation. A file without a name uses its alternative text or media type. These references describe retained files; they do not imply a preview or download is available.
  • Acceptance: a failed first message leaves its text and files in the composer and an empty queue. Evidence: attachments.test.ts, queue regression tests, TestUploadedImageReachesModelAndLaterHistory, and the phone/desktop composer-attachments screen. Live model and connected browser acceptance are tracked separately in the session audit ledger.
  • Retained upload references are checked for both message authors and other readers in room.dom.test.tsx, and from actual session API records by the session-uploads browser state at phone and desktop widths in both themes.

DES-037: Health

  • The Health tab (/monitor/health, behind alerts:read) is a status page: a banner for the whole deployment, then each model provider and dependency by group, with its status, latency, a bar per recent check and its uptime.
  • With no model provider configured, the deployment reads as down.
  • The page asks again every 30 seconds; the server reuses a report for 30 seconds.
  • Acceptance: with Anthropic, OpenAI and Gemini keys set, each reads operational; with none, the banner says the deployment is down.

DES-038: Ready to read, quiet at rest

  • Notifications on a wide screen shows the first message in the reading pane instead of an empty one (Mailbox previewFirst, set only by the Notifications page). A preview is not a read: ActionId.read is sent only when a row is picked or deep linked. Narrow screens keep the list until a row is picked.
  • A row that asks for more than one decision says "N to decide" as its own label, with a gap and no dot before the preview (DES-002).
  • A screen filters one way. Context Health keeps its count-bearing status pills, labelled as one group, and drops the dropdown that repeated them. Agents puts its state filter and search on one row, and the header holds only actions: Review Drafts is the filter's Drafts option.
  • Message action rows (MessageActionRow) rest at 40% opacity on a fine pointer and come up when their message (group/message on Room.tsx MessageView and web AgentMessage) is hovered or holds focus. Touch, keyboard focus and a pressed control keep the row at full strength. Only opacity changes, so the thread never shifts. This is the reveal DES-003 needs; the Fork action itself is still pending there.
  • Home's Needs you box opens Notifications and says so (Open Notifications, copy key home.openInbox kept). Its urgency word keeps coming first, in words, with the same tint as the Notifications list.
  • Acceptance: /notifications at 1280px shows a message without a click and sends no read; Context Health has no Filter Sources select; home.test.tsx checks the tinted urgency word before the time.

DES-039: Smooth screen changes and a glass frame

Owner feedback: moving between pages made "big jumps without loading". The content blanked or snapped when a route changed and its data loaded, and the sidebar looked like a separate block beside the page.

Found before the change (desktop 1280px, dev server, make dev):

  • Opening a conversation replaced the whole screen with three bars and no header or composer (Chat.tsx reading branch), then snapped the header, messages and composer in: layout shift 0.04 on every open.
  • Home said "An agent needs to be configured" until the agents were read (hasAgents={agents.length > 0}), then swapped in the composer, the suggestions, the welcome banner and the Home boxes one by one around a vertically centered column: 0.09 to 0.11 on load.
  • The session read drew a centered "Loading" on a blank page before the console appeared all at once (App.tsx).
  • Every route change was an instant swap with nothing to bridge it, and SkeletonRows showed on the first frame, so a fast read flashed a skeleton.
  • An agent opened before the agents were read showed the title Agents, then the agent's name.

Rules:

  • A change of screen (screenOf in route.ts: a page and the one thing it is about) runs through swap in transition.ts. The current screen stays on view while the next one's reads are in flight, up to HOLD_MS (320ms), then the content area cross-fades and rises into place with the View Transitions API. The sidebar (humagen-sidebar) and the page's title (humagen-title) are named, so only the content moves. A tab, a filter or anything written with replace changes in place, and the address changes in the same step as the screen. Without view transitions the swap is instant.
  • Reads are counted where they are made (call in api.ts, mail.ts, storage.ts). The first screen is drawn hidden until they land, up to FIRST_HOLD_MS, then fades in once; the session read draws the empty frame, not a blank page.
  • A skeleton has the shape of what it stands for and is shown only after --aui-skeleton-delay (150ms), with its space held from the first frame. A conversation being read draws its header with the title the sidebar knows, message-shaped rows and the composer's height (--humagen-composer-h). Home holds the composer until the agents are read. Home's boxes keep their still "Loading" text: they wait on a person.
  • On a tablet or desktop the sidebar sits on the app frame (--humagen-plane) and the page is one opaque panel inset in it, edged with a hairline (--aui-stroke); a docked Inspector is a panel on the same frame, with its header level with the page's (DES-027).
  • Glass (aui-chrome: translucent surface, blur and saturation, a sheen and a soft shadow) is limited to chrome: the sidebar, sticky tabs, the sidebar's sticky Conversations header, the search modal and the Inspector (aui-glass). Menus and popovers keep the opaque surface DES-015 requires, with a hairline edge and shadow. Without backdrop-filter, or with prefers-reduced-transparency, glass is solid.
  • The durations, rise, skeleton delay, hairline and glass tokens are in packages/render-web/src/theme.css, shared with the product site. Reduced motion turns the transition into a short fade with no travel. Nothing that waits on a person animates.

Evidence: navigation through Home, a conversation, Library, Agents and Projects, recorded with Playwright, with layout shift summed from PerformanceObserver:

Case Before After
Navigation, no added latency CLS 0.08; 2 blank frames CLS 0; 0 blank frames
Navigation, 300ms per read CLS 0.10; 38 blank frames CLS 0.006; 0 blank frames
Load /, no added latency 0.106 0
Load /, 300ms per read 0.090 0
Load a conversation 0.04 0

The remaining 0.006 at 300ms per read is the Agents roster's state chip, which arrives after two sequential reads, past the hold. cd apps/web && pnpm test and make screens pass.

DES-040: A phone, and an installed app

Owner request: the console should work well on a phone and behave like an installed app.

Found before the change (Playwright, Chromium phone emulation with touch, the make screens fixtures at 320x568, 375x667, 390x844, 430x932 and 844x390):

  • 1,257 controls were under 44 by 44px at 390px: the drawer button (36px), the composer's +, Dictate and Send, every tab strip (36px), starters, message actions and list links (24px). The screens checked only 24px.
  • Every field drew 13 or 14px text, so Safari zooms the page when one takes focus.
  • The phone drawer (Sidebar.tsx) had no Escape, did not take focus or return it, and left the page under it reachable by Tab. Opening it saved "open" (App.tsx toggle), so the next launch on a phone opened with the drawer over the page (sidebarState.ts).
  • The viewport did not resize for the on-screen keyboard: on iOS the composer sat under the keyboard. Nothing kept clear of the home indicator or of a notch on a phone held sideways.
  • The Inspector on a phone was a 24rem panel from the right, 6px short of the screen's width at 390px.
  • At 320px a starter wider than the screen could not be scrolled into view: the row snapped back to its first item (Scroller.tsx), and its smooth scroll ignored reduced motion.
  • There was no service worker: no offline screen, nothing to install beyond the manifest, and the page and the manifest were served without a cache rule, so a browser could keep an old page after a deploy.

Rules:

  • On a touch screen (pointer: coarse) every control is at least 44 by 44px (WCAG 2.5.5). A small control keeps its look and gets an invisible margin (::after in styles.css, in the base layer so a control's own ::after wins); where a scrolling or clipping parent would cut the margin (tab strips, starters, truncated links) the control is drawn 44px tall. Fields have 16px text and are at least 44px tall. scripts/screens/checks.ts measures the margin too and fails a phone screen on a target under 44px or field text under 16px.
  • The phone drawer is modal: it takes focus, the page under it is inert, Escape or a swipe toward the left edge closes it, and focus returns to the drawer button. A phone always starts with it closed; only a wide window remembers the sidebar's state.
  • The console is as tall as what shows of the window. index.html sets interactive-widget=resizes-content for Chrome; for Safari, viewport.ts writes the height the keyboard covers to --humagen-keyboard and the root subtracts it, so the composer stays above the keyboard.
  • Chrome that meets an edge keeps clear of the safe areas: the drawer, the drawer button, the page's foot, the Inspector sheet, the update prompt, and the frame on a phone held sideways.
  • On a phone the Inspector is a sheet from the bottom, as tall as its contents up to the top safe area, and scrolls inside itself.
  • The installed app: sw.ts (built to /sw.js by vite.config.ts) precaches the build's scripts and styles and an offline screen made from the copy table. A page is always fetched from the network; offline, the offline screen answers instead. /api, /auth, /branding, /connectors and /healthz are never touched. The server sends the page, /sw.js and the manifest with Cache-Control: no-cache.
  • A new version installs and waits. "A new version is ready" (UpdatePrompt) offers Reload and Later; only Reload activates it and reloads. It waits on a person, so it does not animate. The console checks for a version hourly and when it is shown again.
  • The manifest has an id, a scope, shortcuts and install screenshots taken from the console; a branded deployment's manifest drops the screenshots. The status bar follows the theme the person picked (standalone.ts). The page never rubber-bands or pulls to refresh.

Evidence: cd apps/web && pnpm test covers the worker's rules (swPolicy.ts), registration and the update flow (pwa.ts), the keyboard inset, the status bar, the offline screen, the drawer (Escape, focus, inert, swipe) and the prompt; go test ./internal/httpapi ./internal/branding covers the cache headers and the branded manifest. make screens passes at 390x844 and 1280x800, and with SCREENS_VIEWPORTS=320x568,375x667,430x932,844x390. Offline: the production build served by humagen serve, loaded once, then the network cut: a reload shows the offline screen, and Try Again with the network back loads the console.

Needs a real device: Safari's keyboard (the visual viewport inset), Add to Home Screen on iOS, the standalone status bar, and the install prompt on Android.

DES-041: Agents are mentioned, not chips

  • The plus menu, a starter suggestion, Find Help's choice and an agent link (?agent=) write @name into the box, at the cursor or at the start of an empty draft, as @ completion writes it. Nothing about agents shows in the row under the box: only where the conversation is filed.
  • The draft is the one place a message's agents are kept. The plus menu checks the agents the draft mentions; deleting a mention's words takes the agent off, and picking a mentioned agent again takes its mention out.
  • A message is sent as its text. Its mentions route it by the platform's tag rule: every agent it tags answers, with no per-message cap. Budgets, admission and room limits still bound what the runs spend. Agent tags are resolved in one bounded read of the tenant's agents, so they hold no place and only the text's length bounds them; people, experts, roles and skills, which each need a lookup, hold at most 10 places (threads.MaxMentions). There is no Each Decides or All of Them toggle in the composer.
  • An untagged follow-up runs nothing. A thread's saved agents and mode from before keep routing its untagged messages; the console no longer changes them.
  • In the box a mention is the plain @name text the completion writes; in a posted message it renders as MentionLink with the agent's hue (DES-035).
  • Acceptance: picking two agents from the plus menu leaves @helper @lead in the box and no chip or routing control; sending it posts the text alone, and each mentioned agent answers.

Evidence: cd apps/web && pnpm test (tags.test.ts for the helpers; chat.dom.test.tsx and room.dom.test.tsx for each entry point, removal by editing the words, and the posted body); go test -race ./pkg/threads ./internal/platform ./internal/httpapi (TestEveryAgentAMessageTagsAnswers, TestEveryAgentAConsoleMessageTagsAnswers, TestABudgetStillRefusesTagsPastItsLimit); make screens with chat-mentions (was chat-chips), channel-plus, chat-plus, home-project-picker and workspace-find-help-selection.

DES-042: A phone, closer to a native app

Owner request: improve the console on a phone, after a screenshot of the installed app on an iPhone showed an empty strip under the composer.

Found before the change (the make screens fixtures at 390x844):

  • Installed on an iPhone with the status bar drawn over the page, Safari sizes 100dvh short by the status bar's height, so the console ended that far above the bottom of the screen.
  • The drawer button took a row of its own at the top of every page: 48px holding one 44px button, above a conversation's own header.
  • Home put the chat bar in the upper middle of the screen, out of a thumb's reach, with the bottom half empty before the first message.

Rules:

  • Installed on iOS, viewport.ts writes the screen's height to --humagen-app-height, which the console, the drawer and the Inspector sheet are sized from. While the keyboard is up it hands back to 100dvh, which the keyboard's height is measured against.
  • On a phone the drawer button is round, on glass, and floats over the top left corner. A conversation's header and a hub's tabs start beside it; a page's title starts just under it. Anything else keeps the reserved row.
  • On a phone Home keeps the chat bar at the bottom with its suggestions above it, and centers the greeting in the space left. The boxes scroll under the bar. A wide window is unchanged.

Evidence: cd apps/web && pnpm test covers the installed-app height and the handover to the keyboard (pwa.test.ts). make screens passes with SCREENS_VIEWPORTS=390x844,320x568,844x390.

Needs a real device: the installed app's height on an iPhone.

DES-043: The brand's glow

Owner request: the colored streak along the top had rough ends at the rounded corners; carry it round, and into the chat bar, so the system reads as glowing.

Found before the change: the streak was a 1px background line along the sidebar's top only. It stopped where the page's rounded panel began and did not follow any corner.

Rules:

  • Wider than a phone, the page's border is the streak: the brand's red, yellow and green along the top, bending with the 0.75rem corners and fading into the neutral rule down the sides. The phone drawer, square at the top, keeps its flat streak.
  • The chat bar has a 1px ring in the brand's sweep (red, yellow, green, the accent) and a soft halo under it: quiet at rest, brighter while the person writes. While a reply is in flight the sweep turns round the bar, by transform only; reduced motion stills it. Nothing waiting on a person moves.

DES-044: The conversation's wave, and the keyboard

Owner request: a sound-wave strip down the left of a conversation, with previews of what was said, to scan through it on the web and on a phone; and the keyboard's open and close fixed on a phone.

Found before the change: TurnRail in @humagen/web drew such a rail, but no conversation passed it any turns, it was hidden on a phone, and each tick was an 8px button. After the keyboard closed, Safari could leave the page panned up, with a strip of nothing under the console, and the message list did not keep the latest message in view as the keyboard shrank it.

Rules:

  • A conversation of two or more turns has a wave down its left edge: a tick per message and per answer, longer the more it says, swelling near the turn in view or under the pointer. The turn in view is drawn in the brand's sweep. It rests faint and brightens while the reader scrolls or reaches for it.
  • It is one vertical slider. Hover previews a turn: a person's own words, an answer's first line. Press, or on a touch screen press and drag, to scrub through the conversation; arrows, Home and End step through it. On a phone the ticks stay in the thread's gutter and the rail is 44px wide.
  • Whenever the keyboard opens or closes, the page's pan is undone, and the height is checked again once focus settles. The list keeps the latest message in view as it shrinks. While the keyboard is up the chat bar sits right on it and the disclaimer is hidden; it returns when the keyboard closes.

DES-045: A phone that reads like a native chat app

Owner request: carry out the design follow-ups (quiet message actions, a one-line chat bar, a one-line header, Chat and Work, a swipe for the drawer), put the wave at the far left, clear of the messages, and open the installed app on Chat.

Rules:

  • Message actions: the latest message in a thread keeps its row. An earlier one shows its row while hovered, focused or tapped (a tap focuses the message), or while one of its actions is pressed. On a phone an earlier row takes no room until then; with a mouse it keeps its room.
  • The wave sits at the conversation pane's far left: the message list spans the pane and its messages read in a centered column (Thread's column). On a phone the rail stays in the 16px gutter at the screen's edge.
  • On a phone the chat bar is one line: +, the project picker as its folder, the field and Dictate or Send. Agents are @mentions in the field (DES-041). A conversation's fixed project is in its header's menu.
  • On a phone a conversation's header is one line: its title and its Share and menu controls. Its project, who is in it and Context are in the menu.
  • On a phone Home's top center has Chat and Work, on glass beside the drawer button: Chat is the new conversation, Work the person's Notifications, with how many wait on them.
  • On a phone a swipe from within 24px of the left edge, at least 56px right and more sideways than up or down, opens the drawer. A touch on the wave waits to see which way it goes: down scrubs, a tap jumps, sideways is left to the swipe.
  • The installed app opens on /, the new conversation. Notifications stays a shortcut.

DES-046: A structured review reads as a card

Owner request: an agent's humagen.github.review.v1 answer showed in the console as raw JSON, and its evidence links were bare URLs. Only the GitHub sink turned it into Markdown.

Rules:

  • An answer that is a valid report (the GitHub formatter's checks) is a card: the pull request and the reviewed commit, the summary, counts per severity computed by the client, findings grouped as errors, warnings and info, each with its suggestion, evidence and follow-up, then notes and related links. Anything else, including a report that does not parse once the run ends, is the text it was.
  • While a review streams, the card shows its summary once it has arrived and holds still. Slack holds the JSON back and posts the card at the end.
  • Ask Follow-up puts @<agent> <prompt> in the composer through the mention seed the composer already takes, and sends nothing. Where the reader may not ask the agent, and on Slack, the prompt is shown as words.
  • Copy as Markdown copies the layout the GitHub sink posts, computed in the client, since the API does not expose the formatter's output. The answer's Copy as menu does the same for a review.
  • Evidence pinned to lines at a full commit SHA reads as path:a-b and opens those lines in place with context, line numbers, simple highlighting and Open on GitHub, read through GET /api/github/source with the token kept on the server (docs/reference/github.md#reviews-in-the-console-and-slack).

Evidence: cd packages/core && pnpm test (review.test.ts: fenced, unfenced, streaming and invalid reports, sources, commit and pull request); cd packages/render-slack && pnpm test (review.test.tsx); cd apps/web && pnpm test (chat.dom.test.tsx review tests, copyas.test.ts); go test -race ./internal/platform ./internal/httpapi -run GitHubSource; pnpm validate:slack; make screens with conversation-review-card, conversation-review-follow-up and conversation-review-source.

DES-047: Skills are slash commands

Owner request: invoke skills the way Copilot does, with / in the composer, in place of remembering $name; then make / the only way skills are offered, with no @skill and no $ menu.

Rules:

  • / at the start of a message or after a space opens the command menu. It lists the skills a message here can name, from GET /api/skills. A slash inside a word, a path, a URL or code opens nothing.
  • / is the only way the console offers a skill. @ offers agents, people and mention kinds over people or roles: never a skill, never @skill: or another kind that resolves to skills. $ opens nothing. The + menu's Skills write /name.
  • Each row is /name, the skill's one-line description and, on the right, its kind (Skill). Typing filters the list: a name that starts with the query first, then one with a word that does, then one that holds it, then one with its letters in order, then a description that holds it. The matched letters are highlighted in the name and the description.
  • The arrow keys move, Enter or Tab picks, Esc closes, and a tap picks on a phone. A command that cannot be picked here is greyed with the reason in place of its description and the highlight skips it: a skill the message already names ("Already in this message"), and every other once the message names 4 (threads.MaxSkills).
  • A pick writes /name into the box, drawn as a token behind its words. The message is sent as its text. The platform reads /name as a skill in a message posted through the API or the console, at the start or after a space, before a skill's whole name that is on the chain. Anything else after a / is text and refuses nothing.
  • $name and @skill:name stay quiet aliases on the server, so older messages, Slack and GitHub text and agents' instructions keep working. A posted message in the console shows each skill it names as a /name chip, however it was written. Slack and GitHub read a / only as one of their client's commands.
  • No built-in commands. /new would need the conversation's navigation and /review <PR URL> an agent name that differs per workspace, so neither maps cleanly to existing behavior yet. The kind label is there for them.
  • Acceptance: typing /rev lists /review then /security-review with rev highlighted; Enter leaves /review in the box as a token; sending /review the launch pins the review skill on the runs it starts; typing @ lists no skill and $ opens nothing; a posted $review reads /review.

Evidence: cd apps/web && pnpm test (commands.test.ts for matching, greying, tokens and chips; tags.test.ts for @ without skills; slash-commands.dom.test.tsx, chat.dom.test.tsx and room.dom.test.tsx for the menu, keys, tap, greyed rows, $ and @, the + menu's pick, chips and the posted text); go test -race ./pkg/threads ./internal/platform (TestASlashCommandNamesASkill, TestSlashCommandsCostBoundedLookups, TestASlashCommandIsPinnedAsItsSkill, TestASlackCommandNamedForASkillUsesIt, TestSkillsAndMentionKinds for the aliases); make screens with chat-at, chat-slash, chat-slash-picked and composer-menu-skill-selection.

DES-054: Recents, Pinned, Projects and Archived

Owner request: a flat list of conversations across projects, each row its title, its project under it and its age or an unread dot, with Pinned on top; Projects kept as another view; pin and archive from the row; an Archived view; and dots for what is running and what needs the reader.

Rules:

  • The list's views are picked from its filter menu: Recents (the default: every project, newest first), Projects (the conversations under folders, open and closed folder icons) and Archived. Pinned sits above whichever view is on and holds pinned projects and conversations.
  • A row is its title, then its project ("Personal", the workspace's name or the project's title) on a second line, and on the right how long ago it moved (now, 5m, 3h, 2d, 3w, 9mo, 2y) or an unread dot. Inside a project's group the project line is left out.
  • One dot before the title, most urgent first: needs you (a run is parked on a person, an approval or a question: colored and still, since it waits on a person), running (a ring that breathes slowly, still with reduced motion) and a reply failed (solid). Unread is the accent dot in place of the age. A screen reader hears each as words.
  • Unread: an agent said the last thing, after the reader last opened the conversation. Opening a conversation reads it, and so does staying in it while it moves. Before a reader's first mark nothing reads as unread, so the first release does not light up every older conversation.
  • Hover or focus trades the age for Pin, Archive and the ⋮ menu (Pin, Rename, Archive, Delete). On a touch screen the ⋮ menu stays and holds them all; every control is at least 32px, 44px on a touch screen.
  • Archive is the reader's own: the conversation leaves their Pinned and Recents and is listed under Archived, where Unarchive brings it back. Anyone else still sees it. A note offers Undo. Delete still asks once more and queues it for an admin (DES-022).
  • In Projects, a project with nothing loaded starts folded and opens to "No conversations"; a group shows five rows, then See All (N) and Show Fewer. The reader's projects beyond those with conversations are listed, at most 12.
  • The server keeps each person's marks per request on pkg/state, tenant scoped: at most 500 archived, the last read of 500 conversations (the oldest is forgotten) and 32 dismissed tips. GET /api/marks and PATCH /api/threads/{id}/marks take runs:read; a conversation the caller cannot read is not found. A thread summary carries waiting (runs parked on a person) and last, last_by and last_agent (the first line of the latest message or answer, at most 160 bytes, and who said it, a person by handle).

Evidence: go test -race ./pkg/marks ./pkg/runs ./internal/httpapi (TestArchiveIsPerPersonAndReversible, TestArchivedIsBounded, TestReadKeepsTheLatestAndForgetsTheOldest, TestMarksOutliveAProcess on memory and Postgres, TestAThreadSaysWhatWaitsAndWhatWasSaidLast, TestMarksArePerPersonAndConfined, TestMarksTakeRunsRead, the contract tests); cd apps/web && pnpm test (conversationList.test.ts, sidebar-views.dom.test.tsx, preferences.dom.test.tsx); make screens with sidebar-recents, sidebar-row-actions, sidebar-projects, sidebar-archived and sidebar-participants.

DES-055: Previews of a conversation and of a turn

Owner request: a preview card when hovering a sidebar row (title, project, updated time), as Antigravity does, and on the conversation's turn rail, as ChatGPT does.

Rules:

  • Resting a mouse on a row for 450ms opens a card beside it: the title, its project and "Updated" with a time today or a date before, then the first line of the latest thing said, after its author's mark (an agent's initials in its ring, a person's initial). Leaving, scrolling or Escape closes it. The row names the card with aria-describedby while it shows.
  • On a touch screen a 500ms hold opens the card under the row, across the screen, or over it near the bottom. The hold does not also open the conversation, and the browser's own menu does not open; the next tap does.
  • The card is drawn over the page, so the sidebar's scrolling list never clips it, and it is kept inside the window.
  • The wave's preview of a turn (DES-044) leads with its author's mark: a person's initial for a message, an agent's initials for an answer.
  • Hovering a row on a wide screen keeps its title clear of its actions.

Evidence: cd apps/web && pnpm test (peek.test.ts, sidebar-peek.dom.test.tsx, wave.dom.test.tsx); make screens with sidebar-preview (a hover on desktop, a held finger on a phone) and conversation-wave-preview.

Owner request: a dismissible tip card for search across conversations, as Antigravity shows once.

Rules:

  • The sidebar shows "Search across conversations" above Pinned, with Search (opens search and dismisses it) and Dismiss, both text controls.
  • It waits for the person's marks to be read, so a tip already dismissed never flashes in, and once dismissed it stays away on every device: POST /api/marks/tips keeps the name in the person's marks (DES-054).

Evidence: sidebar-search checks the replacement Search navigation button and sidebar destinations; the tip card was removed.

DES-048: A turn as a transcript

  • A turn is an ordered list of segments built from the stream (timeline in @humagen/core): text, thinking, runs of tool calls between two pieces of text, and calls to other agents. Order comes from Task.at and Thought.at, set by the reducer when each first appears, so it holds across model steps and across a replay from the journal.
  • A run of tool calls is one muted line, written from the calls' names and arguments alone (toolsLine): a lone call says what it was pointed at ("Read docker.go", "Checked urmzd/humagen#178", "Ran go test ./..."), one kind counts ("Read 3 files", "Ran 2 commands"), a mix names each kind in order ("Read 2 files, ran a command"), and more than three kinds count calls ("Used 6 tools"). A failed call adds "1 failed" in the same tone. A call waiting on a person adds "waiting for you" and does not animate.
  • While a call runs, its run says "Running ".
  • Open, each call is one compact row: an icon for its kind, its name, and its command or target in muted monospace, cut with an ellipsis, then its duration. A row opens to its arguments (the command, or indented JSON) and its result, cut to ten lines with Show More.
  • A call that writes a workspace file reads "Updated +a -b", "Created +a" or, when the earlier content is not known, "Wrote +a". It links to /conversations/<id>/workspace?file=<path>&tab=changes.
  • A connector action the runtime hands back to the model as "action failed:" text is a failed call.
  • Slack draws each run as one context line, in order, at most eight a message, the rest counted in the last.
  • In a conversation the reader's own messages sit on the right as a compact bubble without a mark, decided by comparing the author with the signed-in person, so another person's are on the left under their mark and name. A person's consecutive messages show their name once.
  • Acceptance: a turn of words, two reads, words, a file written, an answer shows those in that order, the reads as "Read 2 files", the file as a link to its Changes, and Slack shows the same runs as context lines.

DES-049: What a turn changed

  • A finished turn that created or edited workspace files ends with a card under it: "N files changed +a −b", open by default and folding to that line.
  • Each file is one row: an icon for its type, its name, its folder in muted text cut from the start, and its lines added and removed. A row opens the file's Changes in the Workspace (/conversations/<id>/workspace?file=<path>&tab=changes).
  • Review opens the Workspace at the turn's first changed file, since the Workspace reviews one file at a time.
  • The totals come from the same detection as each call's own line (fileEdits), one row per path: a file written whole more than once counts from what the turn started with to what it left; edits add up.
  • No card while the turn runs, or when it changed no file.
  • The chat bar's prompt is "Ask anything, @ to mention, / for actions".

DES-057: The composer's chrome: project, approvals

Owner request: a project picker over the composer on Home ("No project" is personal), a model and effort picker for agents that allow an override, and an approval mode per conversation, Default or Approve for Me, as Antigravity and ChatGPT show them.

Rules:

  • Home holds its project picker in the composer toolbar at every width. The person's own project reads No project on desktop and uses its folder on a phone (DES-045). One picker is drawn at a time.
  • A conversation's composer has Approvals: Default or Approve for Me, a text control before Send. Its menu says what each does. Someone else's choice reads "Approved for ". A refused change puts it back and says so.
  • Approve for Me answers, as the person who chose it, an approval of a tool action the policy asks about, through the path every answer takes: the approvers the question names, self-approval and the runtime's checks all hold, so it never approves what that person could not. It never answers a budget request or any other question, an action the agent's own spec always asks about, a run forced to ask, or an action the policy refuses. What it may not approve stays in the inbox for a person.
  • It answers with the roles the person held when they chose it, less any they no longer hold when last seen. Each automatic approval is audited as approval.auto, naming the tool and who enabled it; each change of mode as conversation.approval_mode. Only a person may choose it, and only one who may post in the conversation; a read-only or archived conversation keeps asking.
  • No model or effort picker: an agent spec has no field that allows a per-message override, and the runtime takes none, so the control stays hidden until one does.
  • The placeholder stays in copy (chat.placeholder).

Evidence: go test -race ./pkg/threads ./internal/platform ./internal/httpapi (TestApprovalModeIsSetOnItsOwnAndKept on memory and Postgres, TestAutoApprovableIsOnlyAPolicyAskAboutATool, TestApproveForMeAnswersAPolicyAskAndIsAudited, TestApproveForMeLeavesWhatTheAgentAlwaysAsksAbout, TestOnlyAPersonChoosesApproveForMe, the contract tests); cd apps/web && pnpm test (approval-mode.dom.test.tsx, chat.dom.test.tsx); make screens with home-project-above and composer-approval-mode.

DES-059: Review GitHub changes in context

A finished review opens a Workspace review tab with its findings pinned to changed lines. Changes and findings share two columns on a desktop; phone tabs select one column. Findings jump to their file and line. The pane shows the reviewed summary, head revision's workflow results, GitHub description and bounded comments. The + picker accepts a public GitHub issue or pull URL, or #number with a repository. Issue tabs render Markdown, labels and comments. Repository access is checked through an enabled workspace client before reading or consulting the immutable patch cache. Pages hold at most 30 files/comments and requests stop at page 10. Large patches are unavailable rather than silently shown as complete.

Evidence: github-ref.test.ts, github-tab.dom.test.tsx, TestGitHubPullEvidenceAndTenantBounds, TestGitHubItemsAreTenantScopedPermissionCheckedAndBounded, TestConsoleLabelsUseServerTokenAndBoundedRead; screenshot fixture conversation-review-workspace runs in CI at phone and desktop sizes.

DES-060: Pull requests across repositories

A top-level Pull requests page collects agent review answers visible to the reader in the last 30 days. Board and list views preserve search, status, repository and agent filters in the route. Cards open the conversation with its pull tab selected, using the DES-059 tab reference.

Evidence: History.tsx, pull_requests.go, scoped endpoint and DOM tests; history-all and history-github check the History heading and review row link.

DES-059: Review GitHub changes in context

A finished review opens a Workspace review tab with its findings pinned to changed lines. Changes and findings share two columns on a desktop; phone tabs select one column. Findings jump to their file and line. The pane shows the reviewed summary, head revision's workflow results, GitHub description and bounded comments. The + picker accepts a public GitHub issue or pull URL, or #number with a repository. Issue tabs render Markdown, labels and comments. Repository access is checked through an enabled workspace client before reading or consulting the immutable patch cache. Pages hold at most 30 files/comments and requests stop at page 10. Large patches are unavailable rather than silently shown as complete.

Evidence: github-ref.test.ts, github-tab.dom.test.tsx, TestGitHubPullEvidenceAndTenantBounds, TestGitHubItemsAreTenantScopedPermissionCheckedAndBounded, TestConsoleLabelsUseServerTokenAndBoundedRead; screenshot fixture conversation-review-workspace runs in CI at phone and desktop sizes.

DES-058: Replay with an agent

  • A completed turn's message actions include Replay With, opening an agent picker with AgentMark. The agent that answered is listed last.
  • Picking an agent saves a fork through that finished turn using the existing Fork API, then posts the same prompt addressed to the chosen agent and opens the new conversation. First turns also keep their fork lineage. Earlier turns and answers remain passive context; no prior tools execute again.
  • Posting permission is required; read-only conversations have no replay action. A refused fork or post reports an error and does not navigate. The picker blocks repeat submissions while a replay is in flight.

Evidence: replay.test.ts, replay.dom.test.tsx; the phone and desktop conversation-replay-agent screen is registered in scripts/screens for CI.

DES-061: Automations

  • /automations is a permission-aware sidebar destination. Schedules reuse the existing schedule form and CRUD API; existing GitHub label triggers are listed beside signed webhook rules.
  • A rule names its installation, repository, event, action, optional conclusion or label, target agent and plain-language instructions. Rules may be paused and edited. They use the installation's existing client API and state store.
  • At most 50 rules per client, 64 bytes per name and 16,000 bytes of instructions. Repository owners and target agents must be granted to that installation. Event capabilities remain enforced. Hidden agents and their rules are filtered by the existing client visibility boundary.
  • Only signature-verified webhooks dispatch a rule. Delivery IDs deduplicate retries through the existing run ledger. Rule runs act for nobody and file in the installation's home through the standard stamping path.
  • Own bot events and bot-authored commits are ignored. Push and check-run events missing commit author evidence fail closed. Only bounded identifiers accompany instructions; webhook body text is never injected into prompts.
  • Evidence: TestAutomationsMatchOnlyTheirInstallationConditions, TestAutomationBoundsAndCopies, automations.dom.test.tsx, route round-trip tests and the scheduled and automation-builder screen definitions. Full screens run in CI.

DES-062: Customize and personal tool servers

The native Mac connection in examples/desktop/ pins an explicit tool set with foreground authority for the named fixture. docs/guides/desktop.md documents worker placement, permissions, exact window/snapshot targeting, and an opt-in native fixture test. A locked session is a connection blocker, not a successful desktop-control result.

The browser worker configuration and connection instructions are in examples/browser/ and docs/guides/browser.md. Browser tool schemas are pinned; navigation and interaction require a write grant. The real connector acceptance is opt-in (TestBrowserLive). The separate Claude Code/CDP helper verifies an actual model using the same signed-in local fixture tab, screenshot pixels, an authorized action and selected CSV read at both widths and themes. Actual wire receipts check PNG blocks; restricted file-tool refusal and separated artifact and download directories are exercised. Existing tabs require an explicit extension or CDP connection; third-party SSO/MFA and extension handoff remain unverified. The CLI profile uses its own tool permissions, not native grants. No console control implies an authenticated browser connection.

  • Customize groups the existing Agents, Skills, Connected Accounts and Your tool servers sections at /customize/{section}, with permission-filtered tabs.
  • Personal MCP clients run in the trusted worker using the existing credential resolver and person-scoped MCP session path. Agents need an explicit person_tools registry grant. Workspace and project host ceilings still apply.
  • A person previews and approves the exact tool list. Schema, description, tool additions/removals or readOnlyHint changes stop the server's tools until approved again. Revocation also stops admitted runs. Only a readOnlyHint classifies a tool as read; every other tool requires that person's approval.
  • Evidence: customize.test.ts, tool-servers.dom.test.tsx, internal/platform/person_tools_test.go, and the Customize states in scripts/screens/library.ts. Screens are judged in CI.

DES-063: Connectors and catalog

The managed BigQuery backend now saves private bounded definitions, verifies metadata through an explicit crawl, and binds renewed consent to the same owned configuration. API/platform race tests and actual PostgreSQL name-reservation and cross-process catalog tests pass. The dedicated OAuth mode exposes metadata only; connection-form browser validation belongs to the console layer.

Browse and search warehouse and object metadata in Library > Catalog. Search text has an address. Show columns and descriptions without copying rows or file content. Owners can crawl, publish metadata to the connector's project, and withdraw it. Readers do not receive owner controls. New Source groups collection, storage collection/catalog, and warehouse catalog/live capabilities, and storage collection requires the reader's own credential.

Implemented in Catalog.tsx, SourceCatalog.tsx, and the connector kinds in pkg/catalog. Evidence: catalog DOM tests, route round-trip regression, Snowflake/object-storage race tests, and library-catalog phone/desktop screen fixture. The Catalog and New Source captures pass at phone and desktop widths (4 captures). The full screen suite is intentionally deferred to CI.

DES-068: Agent message choices

Removed 2026-11-07 with DES-067: agents no longer offer per-message choices.

November 7 console design review

DES-017 and DES-062 retain page h1 headings across Customize, Library and Operations; the current hub link is visually hidden until focused, retaining its accessible name and destination. Agent metrics have one shared header. DES-013 and DES-057 keep starters immediately after the composer, with the disclaimer at Home's bottom and the project picker inside the toolbar. DES-069 groups sandbox workspace links under each agent without raw IDs and shows context percentage once. Thread content reserves space beneath the jump control and its gradient scrim. Evidence: console DOM and usage tests, hub title regression; console typecheck and 883 tests pass. Seven focused screens pass at phone and desktop widths (14 captures): customize-agents, library-catalog, operations-context-health, home-project-above, home-project-picker, conversation-overview and conversation-jump-latest. Overview captures Environment, Context and Agents with Changes collapsed; its existing small file-link target remains outside this review's fixes.

DES-070: One connections page with truthful authorization states

The Connections page lists service presets and reuses the existing personal credential, tool-review and workspace-integration flows without nested page titles. OAuth accounts have Connect/Reconnect, explicit tool review and Disconnect. A preset explains why secure authorization or host access is unavailable. Saved messaging credentials remain visibly unverified. Refused forms keep their input and show errors next to the submit control. Tool forms show allowed hosts and report an empty submission.

Implemented by Connections.tsx, ConnectionSection.tsx, ToolServers.tsx, ClientConnect.tsx, and pkg/connectionauth. OAuth unit/race evidence covers identity, replay, expiry, encryption, refresh and unsafe discovery metadata. Other supports an issuer-bound registered application when DCR is unavailable. The connection detail shows actual reported scopes and authorized configuration mappings. Check observations persist and are invalidated by renewed consent; confirmed credential rejection marks Reconnect required and targets a private owner alert. Five connection DOM checks cover input retention, explicit source consent, native setup, persisted observation display and actual scope mapping. Native failure regressions cover Slack HTTP 200 authentication errors, exact token/consent rejection fences and GitHub mint HTTP 401 attention to the current verified consenting person. Delayed failures after reconnect and ordinary permission/network failures do not raise reconnect attention. Real OAuth, browser layout and full end-to-end delivery remain unverified.

The BigQuery preset obtains dedicated Google read-only consent, saves a bounded private connector, verifies metadata through owner-only crawl, and offers separate publication. Definitions survive restart without operator handoff. Failed verification retains the last successful count/time. Renewed Google consent is explicitly rebound to the existing connector. ADC/reference fallback is administrator-only and remains within deployment or personal reference grants. OAuth connectors expose metadata only, not unsupported live SQL. Evidence: bigqueryConnection.test.ts, bigquery-connection.dom.test.tsx, managed catalog and platform setup race tests; no live BigQuery or visual validation. See the BigQuery guide.

DES-071: Sessions and a single alert center

The primary navigation is New, Sessions, Alerts, Agents, Connections, Artifacts and Settings. Sessions reads /api/sessions?mine=true&roots=true, expands children under their parent, and keeps state, project and agent filters in the address. Canonical details use /sessions/{id}?panel=files|sources|steps|sessions; old conversation paths retain their selections. Project inbox, history and channel addresses migrate to project context or filtered Sessions.

Agents groups the directory, Skills, Knowledge and Memory while retaining their existing addresses. Connections groups Agent tools, Data sources and permitted Workspace apps. Artifacts opens published work at /artifacts. Generic network and controls addresses open Agents; addressed handoffs and agent-filtered assignments retain their specific decisions and filters.

The alert center reads session alerts, with Mine/Everyone, priority, state and source filters, bulk Resolve/Snooze, and Undo for successful changes. The backend filters source by alert kind and orders sessions using only visible open attention. Per-priority preferences govern delivery; an unset preference grants no delivery. Recorded answers settle question alerts, while reading or a terminal run without an answer does not. Connection authentication failures join a private owner session with sanitized reconnect attention. See session alerts. Watching lists standing rules with Pause/Resume and confirmed Delete. The shared badge counts only the person's open Urgent and Normal alerts. Home puts its disclaimer directly under the composer; what it shows beneath is DES-075. Sidebar hover controls contain one menu.

Evidence: session-center.dom.test.tsx checks the seven destinations, attention priority and three-row cap, resolve/undo, and nested child reads. route.test.ts checks canonical paths, old panel aliases and project migration. The connection HTTP contract test uses an offline OAuth transport and passes with -race. Visual responsive checks and real provider authorizations remain unverified. Session summaries carry the retained conversation's origin, last-message author and last agent message. Sidebar unread dots use that metadata and do not infer an agent reply from a generic session update.

DES-072: Builder sessions and evaluation health

New Agent opens a session with humagen, the entry agent, which took over from humagen-builder. An existing agent's Manage with builder action resumes its labeled management session, without sending another prompt merely to open it. Compatibility setup addresses provide the same explicit builder entry. The directory has one creation action, with no separate Pause All or Build With the Builder controls.

The directory includes actual evaluation health and keeps its state filter in the URL. Needs review includes failed operational runs and eval regressions; inactive setup agents read as Draft. Agent detail shows recent failed checks, retained before/after suite scores and recorded override reasons. Missing health is not presented as healthy. The operational panel reads draft state from the roster instead of probing a setup endpoint that returns 404 for ordinary agents.

A recorded preview_agent_change or preview_workspace_prompt result renders a shared change card: the web shows a prompt diff, while native surfaces show explicit before/after prompts. Both show proposed tools and per-suite scores. Incomplete evaluation is blocked; regression requires an authorized override reason. The card has no independent Apply operation: the runtime's governed approval remains authoritative. Optional authorized connection and listening summaries show current routing, not proposed installation or live health. Omitted metadata reads as not included; an empty authorized list means none. Configured or disabled status is preserved.

Evidence: agent-builder.dom.test.tsx covers accepted session creation, management-session reuse without another message, refused health reads and refresh, actual eval regression filtering, and gated change previews. agents.dom.test.tsx covers the single creation action and existing permissions. packages/render-slack/src/agent-change.test.tsx checks both preview tools, prompt evidence, score regressions, placement status and the absence of an independent Apply action. Native preview JSON is replaced by the structured card. Live responsive acceptance remains unverified.

DES-073: Session continuation, attention and management

Selecting an agent with an existing session offers Continue or Start fresh before sending. The choice stays attached to its queued message through wait/retry; removing its mention drops the draft choice. Canonical sessions use the generated post contract.

Session alerts render beside their recorded message or above loaded history when the anchor is absent. Reading does not resolve them. Resolve and Snooze are permission-gated and offer Undo. Known actions lead to existing approval, answer, retry or connection controls; unknown actions open the session. A reviewed fix request carries source_alert, uses a permitted agent, and inherits its source audience. Alert-only sessions render before their first human message. An addressed older message uses a bounded around page read and scrolls only the transcript once, without pulling a reader back on later stream updates.

The header has stable People and Details controls. Its action menu offers Share, Rename, personal Archive/Undo and governed deletion according to access. Rename preserves routing; Delete requests administrator review and does not remove the record directly. Canonical sharing uses project access without a channel picker. Bring Back is offered inside Fork for a completed fork result and retains the existing consent review. Approval controls say Ask a question and Decline action. Failure debug references are kept out of the everyday response and remain in the explicit issue-report draft.

Evidence: session-ux.dom.test.tsx covers continuation metadata, header writes, archive synchronization, explicit deletion review, alert resolution/undo, fix review, canonical sharing and bounded old-anchor reads. wave.dom.test.tsx checks that addressed history scrolls only the transcript once. Existing fork, share, room and Slack interaction suites retain their governed approval checks. Browser host access was unavailable; real responsive layout, live OAuth and user-visible provider behavior are not claimed by these automated tests.

DES-074: Navigation recovery, readable context and priority preferences

Unknown addresses stay on a Page not found screen with a Home link; compatibility routes retain their canonical destination. New and Search stay outside the sidebar's scrolling session list. Recents, Projects and Archived are directly selectable, and Failed has the same meaning in the sidebar and Sessions. A touch row reveals its menu when selected or previewed; keyboard focus keeps it usable. Appearance owns theme changes; the account menu links there. Normal navigation counts use neutral color, while Urgent alerts retain their priority mark.

Session and alert cards retain native destination links, including opening in a new tab, with explicit touch targets. Sidebar filter choices return focus to their disclosure. Connection details return focus to the provider opener and show review or approval errors inside the active sheet. A pending tool review stays bound to its provider when the reader changes or closes that sheet.

Search and session rows show project titles or Personal, preserving opaque IDs only in addresses. Sessions retains the age at narrow widths; Home Continue adds project and state. Schedules uses one label and links to Sessions. Empty Catalog links to Connections. Missing-provider health guidance names Models in Settings and the administrator who can configure it. Access shows human capabilities, with technical permission names in a disclosure. Workspace default appearance explains that it follows the workspace brand; fixed color choices do not. Agent Access distinguishes revision saves from independent immediate saves. Its Personal connections capability starts off and is saved only with the next agent revision, using requester-approved tools under existing workspace policy. Built-in agents and readers cannot grant it. Existing tools are preserved, and the grant is described as Personal connection tools in both preview renderers.

Alert source filters are sent to the server. Delivery preferences use Urgent, Normal and Low keys; unset preferences remain off, and existing legacy keys are preserved during saves. Canonical pages no longer poll the dormant legacy notification feed.

Evidence: route tests cover unknown-path retention and canonical aliases; workspace-search checks readable context with exact destinations; session-center checks server source filtering and context/age; sidebar/preferences tests cover visible view selection, independent scroll regions and keyboard pin/archive focus; catalog and automations tests cover next-step links; email-preferences checks priority defaults and saved quiet hours. Browser checks were unavailable during source validation. Phone, short-screen and split-pane visual acceptance, live provider behavior and measured browser request totals remain open.

DES-075: A calm Home and states that say whose move it is

Home under the chat bar is one quiet line and one strip. The line says how many of the person's Urgent and Normal alerts are waiting ("2 waiting on you") and opens Alerts; it lists none of them and offers no decision. The strip, Recently made, shows the three newest artifacts the person may read from the existing GET /api/artifacts, each card opening it at /artifacts/{id}, with All artifacts beside the heading. With nothing waiting and nothing made, Home is the greeting and the chat bar. Home no longer lists alerts or recent sessions: sessions are in the sidebar's Recents and on Sessions.

An alert is named by whose move it is: Waiting, Snoozed or Done, with Mark Done in place of Resolve, in the alert center, on a session's alert card and in bulk actions. A project's inbox switch reads Waiting, Done and All. The API, the stored states and the addresses keep open, snoozed and resolved, so existing links hold. The words are in copy.ts (attention, show, home).

Evidence: session-center.dom.test.tsx checks the single waiting link, the three-card strip and its destinations, and that nothing is drawn or asked for when there is nothing to show or no permission; session-ux.dom.test.tsx and roles.dom.test.tsx check the new words. Console screens new and alerts and home-made pass at 1280x800 and 390x844 in light and dark. Artifact cards show no preview of their content. A strip that cannot be read says so in one line.