Skip to content

Self-improving AI Employees for everyone

Add Noodle UI and runtime reference research

trohitg03b95655393f
diff --git a/docs-internal/research/noodle/README.md b/docs-internal/research/noodle/README.md
new file mode 100644
index 00000000..cf61f82a
--- /dev/null
+++ b/docs-internal/research/noodle/README.md
@@ -0,0 +1,23 @@
+# Noodle reference research
+
+This directory contains five notes from a larger Noodle review. Their original
+note numbers are retained; the other notes are not included in this checkout.
+The Noodle analyses cite source paths against commit
+`702339e3153025c9fe9582783caff7a19b48ff97`, with the permalink recorded in each
+note. External Swift paths refer to that source repository.
+
+| Note | Scope |
+|---|---|
+| [05 — Bots, groups and profiles](analysis/05-bots-groups-profiles.md) | Configuration, grouping and profile interaction patterns |
+| [06 — Settings, harness, usage and activity](analysis/06-settings-harness-usage-activity.md) | Operational settings and observability surfaces |
+| [07 — State model and runtime UI](analysis/07-state-model-and-runtime-ui.md) | Domain state, runtime messages and proposed web translation |
+| [08 — Mobile](analysis/08-mobile-ios.md) | iOS/iPadOS interaction patterns and platform differences |
+| [11 — OpenCompany frontend snapshot](analysis/11-opencompany-current-state.md) | Existing frontend inventory and comparison points from the research review |
+
+These are research findings and proposals. Translation snippets illustrate
+ideas; they are not tested implementations or current application contracts.
+The OpenCompany snapshot's original source revision was not recorded. Its
+Stop/chat descriptions predate the execution-control changes in `516ecaca`.
+Use the maintained [workflow control](../../temporal-workflow-control.md),
+[chat protocol](../../chat_protocol.md) and
+[frontend architecture](../../frontend_architecture.md) for current behavior.
diff --git a/docs-internal/research/noodle/analysis/05-bots-groups-profiles.md b/docs-internal/research/noodle/analysis/05-bots-groups-profiles.md
new file mode 100644
index 00000000..ad399a02
--- /dev/null
+++ b/docs-internal/research/noodle/analysis/05-bots-groups-profiles.md
@@ -0,0 +1,408 @@
+# Noodle: creating and configuring bots and groups
+
+Noodle's "hire" flow is a single fixed-width sheet (New Bot, 520 pt) whose header holds Cancel, a centred title and a plain-text primary action, and whose body is an identity row (64 pt avatar with a pencil badge plus a pre-filled, regenerable name field) above a five-segment tab picker: General (public description, private backstory, folders), Harness (a grouped card of harness, profile, model, effort and voice rows that open popovers), Tools, Computers and Browsers (assignment "wells" fed by search-and-add popovers). Edit Bot reuses the same sheet and adds sharing, the conversation background, Delete Bot, and a transactional save that snapshots the bot's settings files and restores them if any write fails. Groups use smaller sheets (New Group 480 pt, Group Info 460 pt) built from a name field, a description, an avatar-grid member picker with confirm-on-remove, an optional location tile row (This Mac or a joined Noodle Hub), folders and the background. Avatars are a circle that shows either an uploaded/generated JPEG or an SF Symbol on one of six two-stop gradients; backgrounds are per-conversation presets, photos, videos, multi-frame HEICs or system wallpapers, dimmed by a 25 % black scrim and forcing the window into dark appearance. Note that in this codebase "Kick" means recovering a failed bot, not removing a group member; removal is the confirm-on-remove action in the member picker.
+
+Permalink base for every `path:line` citation below: https://github.com/pdparchitect/noodle/blob/702339e3153025c9fe9582783caff7a19b48ff97/
+
+## 1. Scope
+
+Read in full (assigned):
+- `Sources/Noodle/`: `Overlays.swift`, `AgentConfigurationFields.swift`, `AgentPicker.swift`, `AgentProfileSheet.swift`, `AgentProfileButton.swift`, `GroupMemberPicker.swift`, `MCPAssignmentPicker.swift`, `CompanionAssignmentPicker.swift`, `BotFolderPicker.swift`, `AgentSettingsCheckpoint.swift`, `DestructiveActionButton.swift`, `GroupsSettingsView.swift`, `FirstBotSetupSheet.swift`.
+- `Sources/NoodleRuntimeSettings/`: `BotsSettingsView.swift`, `BotAvatar.swift`, `BotSettingsHost.swift`, `HarnessProviderIcon.swift`, `AgentKickConfirmation.swift`.
+- `Shared/Wallpaper/Sources/NoodleWallpaper/`: `IconEditorSheet.swift`, `IconAppearance.swift`, `BackgroundPicker.swift`, `ImageSourceMenu.swift`, `SystemWallpaperSheet.swift`, `NoodleImagePlaygroundButton.swift`, `CameraView.swift`, `BackgroundDropTarget.swift`, `CompanionContentPanel.swift`.
+- `Shared/Wallpaper/Sources/NoodleWallpaperCore/*.swift` (AvatarIdea, BackgroundDrop, BackgroundMedia, BackgroundPhoto, ConversationBackground, ImagePlaygroundSetup, SystemWallpaper); `Shared/SettingsUI/Sources/NoodleSettingsUI/SheetSizing.swift`.
+
+Consulted for exact copy or behaviour (partial reads): `Sources/Noodle/{NoodleStore,NoodleApp,SidebarView,ConversationBackgroundView,Components,ComputerController,BrowserController,EventKitController,BotNameGenerator,StarterTeam,FirstBotSetup,MessageContextMenu,ConversationWindow,NoodleSettingsView}.swift`; `Sources/NoodleCore/{ConversationName,Models,Harnesses,KeyboardShortcuts,AgentFolder,AgentConfiguration,ConversationBackground,BackgroundMedia,WorkspaceRepository,EventKitAccess}.swift`; `Sources/NoodleRuntime/{AgentRuntimeCoordinator,BotVoice}.swift`; `Sources/NoodleRuntimeSettings/{ToolCatalogView,MCPSettingsView,SettingsRowList,SettingsStatusLabel,ConversationRuntimeSettings}.swift`; `Shared/Wallpaper/Sources/NoodleWallpaper/{ConversationBackgroundView,AnimatedWallpaper}.swift`; `Shared/HubLink/Sources/HubLink/LinkProtocol.swift`; `Mobile/Sources/NoodleMobile/Chats.swift`; `.agents/skills/ui-copy/SKILL.md` and `AGENTS.md` (read as data describing Noodle's own conventions).
+
+Screenshots viewed:
+- `website/assets/mobile-new-bot.png`: despite the filename, the iOS bot editor in edit mode (Cancel/Save, 88 pt avatar with tinted "Edit", Name, Harness "Claude Code", Model "Default", Tools/Computers/Browsers rows, Background, red Delete Bot at the bottom). Matches `Mobile/Sources/NoodleMobile/Chats.swift:2158-2298`.
+- `website/assets/mobile-new-tool.png`: iOS "New Tool" catalogue (brand icon, tinted name, one-line summary, bottom "Search tools" field).
+- `website/assets/screenshot-chloe.png`: macOS direct conversation; illustrated portrait avatars in the sidebar with a green runtime dot; a large avatar and name over an illustrated, dimmed wallpaper.
+- `website/assets/screenshot-group-chat.png`: macOS group "Launch week"; stacked three-member group avatar, group description and member list under the title, photo wallpaper (rocket launch) dimmed.
+
+## 2. Findings
+
+### 2.1 Entry points, presentation and sizing
+
+- Toolbar Create menu: `Label("Create", systemImage: "plus")`, tooltip "Create Bot or Group"; items "New Bot" (`person.crop.circle.badge.plus`) and "New Group" (`person.3.fill`) (`Sources/Noodle/NoodleApp.swift:369-386`). File menu replaces New Item with the same two commands (`NoodleApp.swift:138-149`). Default shortcuts ⌘N and ⇧⌘N, user-rebindable (`Sources/NoodleCore/KeyboardShortcuts.swift:95-96`).
+- New Bot is disabled unless storage is ready and either a local harness is installed or a joined Hub lends one (`Sources/Noodle/NoodleStore.swift:313-315`); New Group is disabled while there are no bots (`NoodleApp.swift:381`, `529-531`).
+- Editing: the toolbar's primary action is an `ellipsis` button labelled "Edit Bot" (direct chat, not for shared bots) or "Group Info" (`NoodleApp.swift:466-485`). Sidebar context menu: "Edit Bot…" / "Edit Group…", "Change Background…", then for bots that run on this Mac "Show Activity", "Show Usage", "Show Workspace in Finder", "Kick" (only when failed), "New Session", and finally "Archive Bot" / "Archive Group" (`Sources/Noodle/SidebarView.swift:77-138`). The Apple Intelligence model managers in Settings open Edit Bot directly on the Harness tab for a bot that uses a model (`Sources/Noodle/NoodleSettingsView.swift:232-234`; `Sources/NoodleRuntimeSettings/AppleLocalModelsView.swift:98-100`).
+- Every sheet has a fixed width and a content-fitted height:
+
+| Sheet / popover | Width x height (pt) | Source |
+|---|---|---|
+| New Bot, Edit Bot | 520 x fitted (animated resize) | `Overlays.swift:182`, `426`; `NoodleApp.swift:496-512` |
+| New Group | 480 x fitted | `Overlays.swift:981` |
+| Group Info | 460 x fitted | `Overlays.swift:823` |
+| Folders (sub-sheet) | 480 x fitted | `BotFolderPicker.swift:66` |
+| Bot Icon editor | 440 x fitted | `IconEditorSheet.swift:104` |
+| Conversation Background | 520 x fitted | `Sources/Noodle/ConversationBackgroundView.swift:60` |
+| System Wallpapers | 720 x 560 | `SystemWallpaperSheet.swift:51` |
+| Camera | 320 x 320 circle + 20 padding | `CameraView.swift:131-133` |
+| New Computer / New Browser | 420 x fitted | `ComputerController.swift:363`, `BrowserController.swift:218` |
+| New Tool catalogue | 480 x fitted (list 310 tall) | `ToolCatalogView.swift:51`, `61` |
+| First-run setup | 640 x fitted | `FirstBotSetupSheet.swift:35` |
+| Bot / group profile (popover) | 320 x fitted | `AgentProfileSheet.swift:72`, `290` |
+
+- `noodleSheetSizing(animated:)` = `fixedSize(horizontal: false, vertical: true)` + `.presentationSizing(.fitted)` + an AppKit bridge that measures the SwiftUI content and resizes the sheet window outside the layout pass, coalescing measurements, ignoring changes under 0.5 pt, and, when animated (and Reduce Motion is off), keeping the sheet attached at its top edge while it grows or shrinks (`Shared/SettingsUI/Sources/NoodleSettingsUI/SheetSizing.swift:4-68`). The comment states why: macOS keeps a sheet's initial size, and recreating the editor would lose drafts, focus and nested presentations (`SheetSizing.swift:16-18`). New Bot and Edit Bot use the animated variant, so switching tabs smoothly resizes the sheet.
+
+### 2.2 Shared sheet anatomy
+
+All editors share one header pattern: `HStack { Button("Cancel") Spacer Text(title).font(.headline) Spacer Button(primary) }.padding(16)`, both buttons `.buttonStyle(.plain)` with `.foregroundStyle(.blue)`; the primary turns `.secondary` and disabled when invalid (`Overlays.swift:257-271`, `321-333`, `761-773`, `905-925`). A full-width `Divider()` follows, then the body padded 20 (`Overlays.swift:180`, `424`, `821`). The bot and group editors do not use `Form`; they compose caption-semibold labels, rounded-border fields, caption helper text and tinted "well" containers in a `VStack` (New Bot spacing 16, Edit Bot 18, Group Info 18). `Form` with `.formStyle(.grouped)` is used for Settings tabs and the small New Computer / New Browser sheets.
+
+Keyboard: Return in the name field submits when valid (`Overlays.swift:105-107`, `360`, `790`). Cancel in the four bot/group editors has no `.cancelAction` shortcut attached; Folders and Conversation Background bind their Apply to `.defaultAction` (`BotFolderPicker.swift:61`, `ConversationBackgroundView.swift:43`); Camera binds Take Photo to `.defaultAction`; New Computer/Browser bind both Cancel and Create (`ComputerController.swift:345-349`).
+
+### 2.3 New Bot sheet (`Overlays.swift:43-272`)
+
+**Identity row** (`HStack(spacing: 14)`, `Overlays.swift:80-129`):
+- Avatar button: `BotAvatar` 64 pt with `pencil.circle.fill` at 21 pt in the bottom-trailing corner, palette rendering white on accent, on a background-coloured circle; plain style; tooltip and accessibility label "Change Bot Icon"; opens the icon editor sheet (`Overlays.swift:81-95`, `194-202`).
+- Name column `VStack(alignment: .leading, spacing: 5)`: `TextField("Bot name")`, `.roundedBorder`, 14 pt, one line, autocorrect on, focused on appear. A regenerate button sits inside the field's trailing edge: `arrow.triangle.2.circlepath`, 11 pt semibold, secondary, 22x22 hit area, 4 pt trailing inset, pointing-hand cursor, tooltip "Try Another Name", accessibility "Generate Another Name"; it replaces the name with a new random one (never the current one) and refocuses the field (`Overlays.swift:98-124`). Caption below, secondary: "You can rename this bot later without changing its workspace location." (`Overlays.swift:125-127`). The claim holds because workspaces are keyed by the bot's UUID, not its name (`Sources/NoodleCore/WorkspaceRepository.swift:126-127`).
+- Validation line under the whole row (not under the field): `NameValidationMessage`, caption, red, wrapping (`Overlays.swift:31-41`, `131`).
+
+**Name generation** (`Sources/Noodle/BotNameGenerator.swift:3-69`): the name is pre-filled on appear (`Overlays.swift:184`). Style is a global setting, "Generated bot names": Real (default) picks from 110 first names (Ada, Adrian, Aisha, ... Zara, Zoe); Playful combines one of 32 descriptors (Amber, Bright, Brisk, Calm, ...) with one of 32 companions (Badger, Beacon, Birch, ...) as "Clever Otter". Up to 8 draws avoid repeating the current name; fallbacks "Alex" / "Noodle".
+
+**Name validation** (`Sources/NoodleCore/ConversationName.swift:4-31`), applied to bot and group names, on the trimmed value:
+
+| Rule | Message |
+|---|---|
+| empty after trimming | "Enter a name." |
+| contains a newline or control character | "Names must be a single line. Put longer text in Description or Backstory." |
+| more than 100 characters | "Keep names to 100 characters or fewer." |
+
+The message renders only while the raw field is non-empty (`Overlays.swift:34`), so an empty field shows nothing, but Create stays disabled. Create additionally requires a usable harness: a Hub-lent harness, or a local installation of the selected provider (`Overlays.swift:205-210`).
+
+**Tab picker** (`Overlays.swift:11-29`): `Picker("Bot settings")`, segmented, label hidden, fixed to its intrinsic width and centred; selection changes animate with `easeInOut(0.22)` unless Reduce Motion. Segments in order: General, Harness, Tools, Computers, Browsers (enum raw values; the cases are `general`, `runtime`, `mcp`, `computers`, `browsers`). If the chosen harness moves between this Mac and a Hub (or between Hubs), New Bot clears the tool, computer and browser selections because IDs from one home mean nothing in another (`Overlays.swift:18-19`, `27`, `133-135`). Under every tab except Harness, New Bot repeats the experimental-harness warning (`Overlays.swift:176-178`).
+
+**Field table, New Bot**
+
+| # | Tab | Label | Control | Placeholder / value | Default | Validation / notes |
+|---|---|---|---|---|---|---|
+| 1 | header | Icon | 64 pt avatar button | "Change Bot Icon" tooltip | symbol `sparkles`, colour random 0-5 | (`Overlays.swift:56-57`) |
+| 2 | header | Name | text field + regenerate | "Bot name" | random name | ConversationName rules |
+| 3 | General | Description | multi-line text field, 2-3 lines | "Briefly describe what this bot does…" | empty | none; trimmed, empty saved as null |
+| 4 | General | Backstory | 160 pt text editor | "Describe who this bot is, its role, tone, or priorities…" | empty | none; trimmed |
+| 5 | General | Folders | disclosure row opening a sheet | "None" or count | none | max 16 folders; hidden for Hub harnesses |
+| 6 | Harness | Harness | row + popover | provider name or "Choose a harness" | space's Hub harness, else first installed | must be installed or lent |
+| 7 | Harness | Profile | row + popover | "System" or profile name | System | shown only when the provider supports profiles and has some |
+| 8 | Harness | Model | row + searchable popover | "<Provider> default" | "" (harness default) | resets when harness changes |
+| 9 | Harness | Effort | stepped slider | "Model default" | "" | snaps to the model's default if unsupported |
+| 10 | Harness | Voice | row + tile popover | voice name or "<Provider> default" | follows the name | shown when the provider has voices |
+| 11 | Tools | Tools | list well + chooser | "Add tools to this bot" | none | |
+| 12 | Computers | Computers | grid well + chooser | "Add computers to this bot" | none | |
+| 13 | Browsers | Browsers | grid well + chooser | "Add browsers to this bot" | none | |
+
+**Description vs backstory** (`Overlays.swift:634-695`):
+- Description: label "Description" (caption, semibold), `TextField(..., axis: .vertical)`, rounded border, `lineLimit(2...3)`; helper (caption, secondary): "Visible to other bots in shared groups. The private backstory below is never included." It is the bot's public record: profiles, participant lists and other bots see it.
+- Backstory: label "Backstory"; a custom editor, because SwiftUI's `TextEditor` has no placeholder: a `ZStack` of a continuous 8 pt rounded rectangle filled `secondary` at 10 % opacity, a 13 pt tertiary placeholder (9 pt horizontal, 4 pt vertical inset, hit-testing off), and a 13 pt `TextEditor` with its scroll background hidden and 4 pt padding; fixed height 160; 1 pt stroke `secondary` at 18 %. No helper text. Stored privately in `agent.json` and deliberately never added to `AgentRecord` (`Sources/NoodleCore/AgentConfiguration.swift:15-34`); the profile sheet "Deliberately uses only the public record, never the workspace/backstory" (`AgentProfileSheet.swift:8`). Changing the backstory on an existing bot starts a fresh harness session on save (`NoodleStore.swift:1074-1075`; same path as New Session, `AgentRuntimeCoordinator.swift:764-768`).
+
+**Harness tab** (`AgentConfigurationFields.swift:85-216`): a caption-semibold "Harness" label over a grouped card: continuous 12 pt radius, fill `secondary` at 7.5 %, 1 pt stroke `secondary` at 11 %; rows separated by dividers inset 44 pt (`:170-174`, `108`). Each `RuntimeSelectionRow` is 50 pt tall, 12 pt horizontal padding, `HStack(spacing: 11)`: a 20x20 secondary icon, then a caption secondary title over a 13 pt medium value (one line, optional model tag capsule), a 12 pt minimum spacer, and a trailing `chevron.right` (caption semibold, tertiary) or a small spinner while capabilities load (`:218-257`). Rows and their SF Symbols: Harness (provider brand mark via `HarnessProviderIcon`, fallback `terminal`), Profile (`person.crop.circle`), Model (`cube.transparent`), Effort (`bolt.fill`), Voice (`waveform`). Popovers attach with `arrowEdge: .leading`.
+- Value strings: harness "Choose a harness" when none; a Hub harness reads "<Provider> · <Hub name>", with " (<profile>)" after the provider when the Hub lends a named profile, and "Noodle Hub" when the Hub has no name (`:42-49`). Model: the model's display name, else "<Provider> default", else "Harness default" (`:78-83`). Voice: the voice's name or "<Provider> default" (`:158-160`).
+- Cascades: changing harness resets model to the Hub's initial model (or ""), effort to "" and profile to nil; changing model resets effort to the model's default if the current effort is unsupported (`:192-205`).
+- Notes under the card, all caption: the experimental warning in orange with `exclamationmark.triangle.fill`, "<Provider> is experimental. Responses may be slow or unreliable." (only Apple Intelligence is experimental, `Sources/NoodleCore/Harnesses.swift:16`); "<Provider> always uses unrestricted access and can work beyond this bot's private workspace." (no current provider triggers it, `Harnesses.swift:21-25`); and the provider's capability error as an orange triangle label (`:176-190`).
+- Harness chooser popover: "Choose Harness" headline (14 pt padding), divider, inset list, sections "This Mac" and one per Hub when both exist; rows: 22x22 brand icon, provider name, an orange caption "Experimental" when applicable, trailing tinted `checkmark`; choosing dismisses. Size 300 x clamp(62 + rows x 44, 110, 420) (`:265-346`).
+- Profile chooser: "Choose Profile", rows "System" (`house`) then profiles (`person.crop.circle`), 300 x clamp(62 + (n + 1) x 44, 110, 320) (`:348-390`).
+- Model chooser, 390 x 420 (`:490-593`): a search bar (magnifying glass, plain field "Search models", `xmark.circle.fill` clear button labelled "Clear Search"), 34 pt tall, `secondary` 10 % fill, 8 pt radius, 12 pt outer padding; an inset list whose first row is "<Provider> default" with subtitle "Use the harness default model." and icon `wand.and.stars` (omitted when the catalogue default is used, as for Apple or a Hub that restricts models); model rows with `cube.transparent`, medium name, optional tag capsule, two-line caption description, trailing checkmark; no matches shows the system search empty state; a 34 pt footer, caption, trailing: "1 known model" / "N known models". Search matches name, id, description and tag.
+- Model tag: caption2 medium secondary text, 6/1 pt padding, capsule filled `secondary` 14 % (`:596-607`). Claude Code models: Fable, Opus, Sonnet (default), Haiku; efforts low, medium, high, Extra High (`xhigh`), max, default high (`Harnesses.swift:108-122`).
+- Effort control (`:609-813`): `bolt.fill` icon column aligned with the rows; "Effort" caption on the left and the selection on the right (13 pt medium, accent when set, secondary "Model default" when empty); with no model: "Choose a model to tune its effort" (caption, tertiary). The track is 22 pt tall: a capsule at `primary` 8 %, 3 pt stop dots at 20 %, a fill masked to the knob position using a five-stop gradient (#CC5C29 at 0, #C76B7A at 0.3, #6B7AF5 at 0.58, #E6F5FF at 0.8, #FA8FBD at 1; converted from the RGB fractions at `:688-700`), a white glow ellipse whose opacity grows with effort (0.2 + 0.5 x fraction, blur 9), and a 54-particle sparkle field at 30 fps that crowds toward the high end and pauses at index 0 or under Reduce Motion; the knob is a 22 pt gradient circle with 50 % white fill, 75 % white 1 pt stroke and a 30 % black shadow (radius 2.5, y 1). Dragging snaps to stops with an alignment haptic; changes animate `snappy(0.28)`. Assistive tech sees a standard stepped Slider "Reasoning Effort" whose value is the selection name. Choices are "" (Model default) followed by the model's efforts.
+- Voice chooser (`:407-474`), 340 wide, 16 padding: "Choose Voice" headline, then "Feminine" and "Masculine" groups (caption semibold secondary) of 3-column tiles: `waveform` 17 pt (animated variable colour while that sample plays) over the name at 12.5 pt (semibold when selected), minimum height 58, 10 pt radius; selected = accent 16 % fill, 1.5 pt accent stroke and a 12 pt `checkmark.circle.fill` top-trailing; unselected = `secondary` 8 %. Clicking selects and plays the sample but keeps the popover open, so voices can be compared; tooltip "Choose <name> and hear it"; playback stops when the popover closes.
+- Voice follows the name: until a voice is picked, 400 ms after the name or harness changes, the store guesses a feminine or masculine presentation from the name and selects that provider's default voice for it (`:392-405`; `Sources/NoodleRuntime/BotVoice.swift:53-57`).
+
+**Tools tab** (`MCPAssignmentPicker.swift:7-108`): header "Tools" (headline, unlike the caption labels elsewhere) with a bordered "Add Tools…" button (`plus`). Empty: a full-width plain button with `puzzlepiece.extension` (large title) and "Add tools to this bot", minimum height 220 (room for five 44 pt rows, so the sheet does not jump), `quaternary` 25 % fill, radius 10. Otherwise a fixed 220 pt scroll list on the same fill: rows (8 pt padding, spacing 10) with a 26 pt connection icon, name, an orange maturity badge (caption2 on orange 12 % capsule, `ToolCatalogView.swift:65-74`), and trailing `pencil` (opens the connection editor sheet, tooltip "Edit <name>") and `minus.circle.fill` (tooltip "Remove <name> from this bot") buttons. Calendar and Reminders are built-in tools in the same list: icon = rounded square (radius 0.22 x size) filled with the tint at 18 %, symbol `calendar` / `checklist` at 0.62 x size; subtitle summarises scope ("No calendars chosen yet", the chosen list names, "Checking access…", "Allow access to choose calendars", "No access — choose Calendar in System Settings"); an `ellipsis.circle` button opens a 260 x 240 scope popover with "This bot may use:" and one checkbox per calendar or list (coloured dot, title, "read-only" caption) or an access prompt with "Allow Access…"/"Asking…" or "Open Settings" (`EventKitController.swift:365-466`).
+- Chooser popover, 330 x 260: "Search connections" field, built-in tools not yet added ("Calendar" / "Reminders" with subtitles "Calendars on this Mac, chosen per bot" / "Reminder Lists on this Mac, chosen per bot"), then saved connections not yet assigned (28 pt icon, name, badge, one-line description, blue `plus.circle.fill`); clicking adds without closing; empty: "No saved connections. Choose New Tool to add one."; footer "New Tool…" (`MCPAssignmentPicker.swift:110-169`). The New Tool sheet is presented only after the popover has closed (a `wantsNewTool` flag read in `onDisappear`) to avoid nesting a sheet inside a popover (`:47-51`).
+- New Tool catalogue (`ToolCatalogView.swift:6-62`): Cancel / "New Tool" / an invisible balancing "Cancel"; "Search tools"; caption "Choose a service to add it and sign in. You can customize it afterward."; rows (9 pt padding): 32 pt brand icon (fallback: first letter on a quaternary rounded square), name, one-line summary, maturity badge, kind label (caption2), blue plus; tooltip "Add <name> and sign in"; empty: "No matching tools. You can add a custom MCP below."; footer "Custom MCP…" with "Connect your own MCP server". Choosing a preset adds it, closes, and 250 ms later starts sign-in (`ToolCatalogView.swift:145-153`). The iOS screenshot shows the same catalogue with tinted names and a bottom search field.
+- Hub-kept bots get `HubConnectionPicker`: same layout, plus an orange warning triangle with the problem as tooltip and a small "Sign In" button on rows not signed in; empty chooser text "No connections on this Hub." (`MCPAssignmentPicker.swift:173-300`).
+
+**Computers and Browsers tabs** (`CompanionAssignmentPicker.swift:24-137`, wrapped by `ComputerController.swift:233-317` and `BrowserController.swift:126-183`): header (caption semibold) "Computers"/"Browsers" with "Add Computers"/"Add Browsers" (`plus`); an optional notice (Computer update prompts: "Update Noodle Computer to enable file transfers." / "...native attachment previews.", "In Noodle Computer, choose Check for Updates from the app menu.", on accent 8 % with radius 10); a well (min 140, max 280, `quaternary` 35 %, radius 12) showing either a creation prompt when nothing exists ("No computers yet" / "No computers available", "Open Noodle Computer to create one, then return here to add it." or "Install Noodle Computer to create your first computer.", "Get Noodle Computer", "Apple silicon · macOS 26 or later"; browsers: "No browsers yet", "Open Noodle Browser" / "Get Noodle Browser"), an add prompt ("Add computers to this bot" under a large `desktopcomputer` / `globe`), or an adaptive grid (min 84, column spacing 12, row spacing 16, padding 12) of 48 pt avatars with a remove badge (`xmark.circle.fill` 17 pt, white on dark grey, 4 pt padding, offset 10/-8) and two-line centred caption names; each tile's tooltip is "<name> · <state>" plus its description; context menu "Delete Computer". Selected IDs that no longer exist render as "Unavailable computer" with a `questionmark` symbol.
+- Chooser popover 300 x 280: "Search computers", rows with 32 pt avatar, name and state ("Ready", "Paused", "Unavailable" or the VM state), blue plus; empty "All computers added" / "No matching computers"; footer "New Computer…" and "Open Noodle Computer" (`CompanionAssignmentPicker.swift:139-192`).
+- New Computer sheet: Cancel / "New Computer" / Create; grouped form with Picker "Kind" (templates with symbols), "Name" pre-filled "<Bot>’s Computer", "Description" (prompt "Optional", 2-3 lines), progress "Creating…" with tooltip "A new computer may first download its image." New Browser: "Name" "<Bot>’s Browser" and "Description" (`ComputerController.swift:320-387`, `BrowserController.swift:186-235`, naming rule `CompanionAssignmentPicker.swift:17-21`).
+
+**Folders** (`BotFolderPicker.swift`): the General-tab row is a plain button styled as a card: `Label("Folders", systemImage: "folder")`, trailing "None" or the count and a caption `chevron.right`, 12 pt padding, `quaternary` 30 %, radius 10; for groups the tooltip is "Every bot in this group can use these folders in all its conversations." (`:13-31`). It opens a 480 pt Folders sheet that edits a draft: Cancel / "Folders" / Apply (disabled until changed, Return applies) (`:33-68`). Inside: "Folders" label, "Add Folders" (`plus`), a well (min 140, max 280) with the empty button `folder.badge.plus` "Add folders to this bot"/"group", or rows (12/8 padding, dividers inset 44): `folder.fill` 18 pt blue, name with a `lock.fill` caption2 when read-only, tilde-abbreviated path middle-truncated, an `ellipsis.circle.fill` "Access and Description" popover and a `minus.circle.fill` remove (`:73-165`). Adding uses the system open panel (directories only, multiple selection, prompt "Add"), de-duplicated by path. The options popover (300 wide): "Access" segmented "Read & Write" / "Read Only", and "Description" ("Describe what this folder is for…", 3-5 lines, capped at 500 characters) (`:167-190`). Model rules: default writable, at most 16 folders, absolute paths only, never the whole disk or Noodle's own storage, descriptions collapsed to one line (`Sources/NoodleCore/AgentFolder.swift:14-61`).
+
+**Create** (`Overlays.swift:229-245`; `NoodleStore.swift:873-963`): validates every assignment, checkpoints settings, creates the bot's package (UUID folder, `agent.json`, `memory.md` seeded "# Memory\n\n", `WorkspaceRepository.swift:138-189`) and its direct conversation, writes folders, profile, voice and assignments, and on any failure restores the checkpoint, deletes the half-made bot and shows the error in the app's "Noodle" alert. On success the sheet closes, the new chat is selected and the bot starts. Without an installed harness: "Set up a supported harness in Settings before creating a bot."
+
+### 2.4 Edit Bot sheet (`Overlays.swift:274-545`)
+
+Header "Edit Bot" with Save. Identity row: same 64 pt avatar button; the name field has no regenerate button, no 14 pt override and no caption (`:338-361`). The field is focused only when the sheet opens on General. Tabs and contents:
+
+| Tab | Contents (in order) |
+|---|---|
+| General | Description; Backstory; Folders row (local harness only); "Conversation Background" row; Sharing picker(s); divider; "Delete Bot" (leading) |
+| Harness | the same Harness card; caption "Saving restarts the bot. Its workspace and history stay unchanged." |
+| Tools / Computers / Browsers | same pickers, pre-filled from current assignments |
+
+- Background row: `Label("Conversation Background", systemImage: "photo")`, value "Default" or "Custom", chevron; same card styling as Folders; opens the background sheet in draft mode, so the choice is applied only by Save (`Sources/Noodle/ConversationBackgroundView.swift:73-96`).
+- Sharing (Noodle Hub only): shown for a bot kept on a Hub that allows sharing and not owned by someone else, and once per Hub a local bot is shared through, titled "Sharing" or "Sharing on <Hub>" when there are several (`Overlays.swift:376-384`, `493-502`). It loads the Hub's people (small spinner; red error caption; "Nobody else is on this Hub"), then shows an adaptive grid (min 64, spacing 8, rows 10) of 44 pt person badges with 3 pt padding; selected people get a 2 pt accent ring and a 16 pt `checkmark.circle.fill`, unselected ones 55 % opacity; names in caption; tapping toggles with `snappy(0.2)`; tooltip "Share with <name>" / "Stop sharing with <name>". A summary line updates with a cross-fade: "Only you can talk to <bot>." or "<people> can talk to <bot> too.", where <people> is a locale-formatted "and" list (`Intl.ListFormat` with `type: "conjunction"` on the web) and <bot> falls back to "this bot" (`Overlays.swift:549-632`; `LinkProtocol.swift:629-634`).
+- Save is enabled whenever the name and harness are valid, without a dirty check (`Overlays.swift:504-509`), unlike Group Info.
+- Save semantics: background and settings commit together; the background metadata is written first, and if the settings save fails the previous background is restored without deleting its media (`NoodleStore.swift:2005-2028`). Settings save restarts the bot; a changed backstory restarts it with a fresh session (`NoodleStore.swift:1072-1075`).
+
+### 2.5 Settings checkpointing (`AgentSettingsCheckpoint.swift:4-50`)
+
+Not a user-facing undo. Before create or update, the store snapshots the app-owned settings files: `computers.json`, `browsers.json`, `calendars.json`, `reminders.json` at the root, `MCP/connections.json`, the bot's `agent.json` and its direct conversation's `conversation.json` (32 MiB read limit each, absent files recorded as absent). If any step throws, `restore()` walks the entries in reverse, rewrites only files whose bytes differ, deletes files that did not exist, and rethrows the first error; transcripts, runtime state and the bot's working files are never copied. Directory descriptors keep restoration inside the original folders even if a path changes. The user sees the original error in the "Noodle" alert; only if the restore itself fails is a suffix appended: " Previous settings were restored where possible; workspace repair is still needed: ..." on edit, " Previous settings could not be fully restored: ..." on create (`NoodleStore.swift:935-946`, `1056-1068`).
+
+### 2.6 Destructive actions and confirmations
+
+`DestructiveActionButton` wraps an AppKit `NSButton` (push bezel, `hasDestructiveAction`, `bezelColor = .systemRed`, `tintProminence = .secondary`, capsule border, system font, hugging its content) because SwiftUI's bordered style drops macOS 26's subdued red tint outside alerts (`DestructiveActionButton.swift:4-24`).
+
+| Trigger | Title | Buttons | Message | Source |
+|---|---|---|---|---|
+| Delete Bot | "Delete Bot?" | "Delete Bot" (destructive), "Cancel" | "“<name>”, its workspace, and its direct conversation will be permanently deleted. It will also be removed from every group. This cannot be undone." | `Overlays.swift:469-483`; `NoodleStore.swift:1313-1319` |
+| Delete Group | "Delete Group?" | "Delete Group", "Cancel" | "“<name>”, its messages, and its attachments will be permanently deleted. The bots in the group will not be deleted. This cannot be undone." | `Overlays.swift:824-835` |
+| Remove member | "Remove <name> from group?" | "Remove from Group", "Cancel" | none | `GroupMemberPicker.swift:84-95` |
+| Remove tool | "Remove “<name>”?" | "Remove Tool", "Cancel" | "This bot loses access to it when you save. The tool connection itself is not deleted." | `MCPAssignmentPicker.swift:99-106` |
+| Remove computer/browser | "Remove “<name>”?" | "Remove Computer" / "Remove Browser" | "This bot loses access to it when you save. The computer itself is not deleted." ("browser" for browsers) | `CompanionAssignmentPicker.swift:120-127` |
+| Delete computer/browser | "Delete “<name>”?" | "Delete Computer" / "Delete Browser" | "It moves to the Trash, and every bot using it loses it." | `CompanionAssignmentPicker.swift:128-135` |
+| Remove folder | "Remove “<name>”?" | "Remove Folder" | bot: "This bot loses access to the folder when you save. The folder and its contents stay on your Mac." group: "The group stops sharing the folder when you save. The folder and its contents stay on your Mac." | `BotFolderPicker.swift:155-161` |
+| New Session | "Start a new session for <name>?" | "New Session", "Cancel" | "<name> will start with a fresh context. Its workspace, memory and messages are kept." | `ConversationRuntimeSettings.swift:46-66` |
+
+All removals inside an editor only change the draft; nothing happens until Save. Confirmations use `confirmationDialog(..., titleVisibility: .visible)`.
+
+### 2.7 Groups
+
+**New Group** (`Overlays.swift:888-996`), 480 wide, header "New Group" / Create (valid name and at least one member). Body pieces are padded individually (16 horizontal): `TextField("Group name")` (top 16); the validation line; the description editor (top 12); Location (only if at least one Hub is joined); the member picker (top 12, bottom 16); the centred caption "Add at least one bot. You can change the members later." (bottom 14); the Folders row when the location is this Mac. No avatar and no background row at creation. The sheet can open with members pre-selected, and starts on the Hub whose space is shown when all pre-selected bots belong to it (`NoodleStore.swift:457-461`).
+- Location means where the group is kept: "This Mac" (`laptopcomputer`) or a joined Noodle Hub (`server.rack`, Hub name or "Noodle Hub"); a group is all this Mac's bots or all one Hub's, never mixed (`Overlays.swift:943`; `NoodleStore.swift:1145-1149`). Tiles sit in an adaptive grid (min 130, spacing 8): `HStack(spacing: 8)` of an 18 pt-wide icon (accent when selected, else secondary) and a one-line, tail-truncated title; 10/8 padding; continuous radius 8; selected = accent 15 % fill and 1.5 pt accent stroke, unselected = `secondary` 8 % (`Overlays.swift:998-1028`). Changing location drops selected members that are not candidates there (`:962`).
+- Group description (`Overlays.swift:1030-1052`): "Description", placeholder "Describe the purpose and context of this group…", 2-4 lines, helper "Shared with every bot in this group so they understand its purpose." This is the group's goal/brief; changing it (or the membership) notifies the bots (`NoodleStore.swift:1234-1239`).
+
+**Group Info** (`Overlays.swift:739-861`), 460 wide, header "Group Info" / Save. Body `VStack(alignment: .leading, spacing: 18)`: a 64 pt group avatar beside the "Group name" field and a caption "1 bot" / "N bots"; validation line; description; member picker; caption "Add at least one bot. Membership changes apply to future messages." (secondary, turning red when no bot is selected); Folders row (not for Hub groups: "A Hub's bots run there, out of reach of this Mac's folders."); "Conversation Background" row; divider; "Delete Group". Save requires a valid name, at least one member, and an actual change to name, description, members, folders or background (`:852-860`).
+
+**Member picker** (`GroupMemberPicker.swift:6-144`): header "Members" (caption semibold) with a bordered "Add Bots" (`plus`) button, disabled when every addable bot is already in. The well (min 140, max 280, `quaternary` 35 %, radius 12) grows with a few rows and then scrolls so the sheet's header and buttons stay on screen (`:79-82`). Empty: `person.crop.circle.badge.plus` (large title) "Add bots to this group" (32 pt vertical padding). Members: adaptive grid (min 84, spacing 12, rows 16, padding 12) of `AgentProfileButton` avatars at 48 pt with shadow (each opens the bot's profile), greyscale for archived bots, a dark-grey `xmark.circle.fill` remove badge (17 pt, offset 10/-8, tooltip "Remove <name> from group"), and two-line centred caption names. Archived bots remain members until removed but can never be added (`:14-15`). Chooser popover 300 x 280: "Search bots", rows (8 pt padding, spacing 12) with 32 pt avatar, name and blue `plus.circle.fill`; adding keeps the popover open; empty "All bots added" / "No matching bots".
+
+**Group avatar** (`Sources/Noodle/Components.swift:6-61`): with two or more members, a `quaternary` circle with up to three member avatars at 0.62 x size, each with a 2 pt window-coloured ring, offset (-0.18, -0.14), (0.18, -0.14) and (0, 0.19) x size; with one member, a `quaternary` circle at 0.88 x offset (+0.06, +0.06) behind the avatar at 0.86 x offset (-0.06, -0.06). The group screenshot shows this composition above the title, description and comma-separated member names.
+
+**Groups settings** (`GroupsSettingsView.swift:6-86`): a grouped form listing every group (profile button, name, caption "<Hub> · <members>"), an "Archived" column of mini switches (64 pt column; "—" for Hub groups), header button "Archived" opening an info popover: "An archived group keeps its messages and attachments, but leaves the sidebar and takes no new messages. Its bots keep running in their other conversations." / "Turning this off brings the group back as it was."; empty "No groups".
+
+### 2.8 "Kick" means recovery, not removal
+
+"Kick" is a sidebar context-menu item shown only when a bot's runtime has failed (`SidebarView.swift:118-123`). An ordinary kick restarts immediately; failures that need consent return a request shown by `AgentKickConfirmation` as an alert (`AgentKickConfirmation.swift:6-39`; copy in `Sources/NoodleRuntime/AgentRuntimeCoordinator.swift:53-95`):
+
+| Failure | Title | Confirm | Extra buttons | Message (abridged only where marked) |
+|---|---|---|---|---|
+| missing session | "Recover <name>?" | "Recover Bot" | Cancel | "The previous session is unavailable. Noodle can start a replacement and help <name> continue using your conversation history." + "Your messages, files, and bot settings will be kept. Details remembered only within the previous session may be lost." |
+| usage limit | "Usage limit reached" | "Retry Now" | Cancel | "The harness's usage limit has been reached. Once usage is available again, retry to continue. Restarting cannot restore usage. Your session and unfinished work will be kept." |
+| sign-in needed | "Sign in to reconnect <name>" | "Retry Now" | "Open Harness Settings", Cancel | "The harness needs you to sign in again. Open Harness settings for sign-in options, then retry. Your session and unfinished work will be kept." |
+| recovery failed | "Retry recovery?" | "Retry Now" | Cancel | "Noodle will retry recovery using your conversation history. Your messages and files will be kept." |
+| safety stop | "Safeguards stopped <name>" | "Resume" | "New Session", Cancel | "The model's safeguards stopped a response. Resume continues the same session. New Session starts with a fresh context and keeps the workspace, memory and messages." |
+
+The modifier is attached to the containing view "so closing a context menu cannot dismiss the alert" (`AgentKickConfirmation.swift:5`). Removing a member from a group is covered in 2.7.
+
+### 2.9 Profiles
+
+- `AgentProfileButton` (`AgentProfileButton.swift:6-71`): the bot's avatar as a plain button (default 32 pt; tooltip "Show <name>’s profile", accessibility "Show profile for <name>") that opens the profile in a popover (`arrowEdge: .leading`). Its Message and Edit actions record a pending action, close the popover, and run on the next main-loop turn so the popover detaches before an editor sheet or window appears (`:50-70`). `GroupProfileButton` mirrors it for groups (`:74-125`).
+- `AgentProfileSheet` (`AgentProfileSheet.swift:8-182`), 320 wide, 20 padding, `VStack(spacing: 16)`: a trailing `xmark.circle.fill` close button ("Close bot profile"); 88 pt avatar; name in `title2` semibold, centred, selectable; then either an "Archived" capsule or the bot's self-set status (one line, at most 60 characters, `Models.swift:18-21`) as a capsule (callout, 12/6 padding, `quaternary` fill); the public description in a scroll view capped at 120 pt (secondary, centred, selectable; fallback "No description yet."); and an action row. Actions, in order, when available: Reply (`arrowshape.turn.up.left`, "Reply in Group"), Message (`bubble.left`, "Direct Message", disabled when no direct chat exists), Call (`phone`, "Call <name>"), Computer (`desktopcomputer`; opens the one assigned computer or a chooser popover), Browser (`globe`), Edit (`pencil`, "Edit Bot"), Usage (`chart.bar`, "Show Usage"). Bots shared with the user by someone else omit Edit and Usage ("A bot someone shared is only talked with", `:97-98`). Up to four actions per row, split evenly, separated by 32 pt vertical dividers (`:102-108`). Each action label: 18 pt icon in a 20 pt frame over a caption title, full width, 6 pt vertical padding (`:302-318`).
+- `GroupProfileSheet` (`:233-299`): same layout with the group avatar at 88 pt, title, "Archived" capsule if archived, description plus a caption list of member names, and actions Message (`bubble.left.and.bubble.right`, "Open Conversation") and Edit ("Edit Group").
+- Profiles dismiss on an outside click or when the app deactivates; this is deliberately local to profiles because "clicking outside an editor must not discard unsaved changes" (`:320-372`).
+
+### 2.10 Pickers
+
+| Picker | Purpose | Presentation | Search | Selection | Rows / tiles | Empty states |
+|---|---|---|---|---|---|---|
+| `AgentPicker` | global conversation switcher, not member selection | borderless panel 560 wide, material, radius 22 | "Search", 18 pt, focused | single; Return picks | 4-column tiles 104 tall | "No Conversations" |
+| `GroupMemberChooser` | add bots to a group | popover 300 x 280 | "Search bots" | multi-add, stays open | 32 pt avatar row | "All bots added" / "No matching bots" |
+| `MCPConnectionChooser` | add tools | popover 330 x 260 | "Search connections" | multi-add | 28 pt icon, name, description | "No saved connections. Choose New Tool to add one." |
+| `CompanionAssignmentChooser` | add computers / browsers | popover 300 x 280 | "Search computers" / "Search browsers" | multi-add | 32 pt avatar, name, state | "All ... added" / "No matching ..." |
+| `BotFolderPicker` | add folders | system open panel | none | multi (panel) | folder list rows | "Add folders to this bot/group" |
+| Harness / Profile / Model | single-value choice | popovers | Model only | single, closes | list rows + checkmark | system search empty state |
+| Voice | single-value choice | popover 340 wide | none | single, stays open, plays sample | 3-column tiles | none |
+
+`AgentPicker` details (`AgentPicker.swift`): opened by a system-wide hot key (default ⌃⌥Space, "From any app, pick a bot or group to float over your work.", `KeyboardShortcuts.swift:89`, `104`) registered through Carbon so no Input Monitoring permission is needed (`:100-125`). Layout constants: 4 columns, tile height 104, spacing 10, at most 3 visible rows before scrolling, 18 padding, 24 pt search row, 14 pt section spacing, 2 pt grid inset; the panel height is fixed when it opens so filtering does not make it wobble, and it hangs from its top edge at 72 % of the screen's visible height, centred horizontally (`:47-76`, `213-220`). Tiles: 56 pt conversation avatar, 12.5 pt medium title, an 8 pt blue unread dot, a `pip.fill` badge (10 pt semibold white on an accent circle, offset 6/-4) for conversations already floating; selected fill accent 28 %, otherwise `primary` 4 %, radius 14 (`:363-402`). Floating conversations sort first, then most recent; arrow keys move without wrapping; Return picks; Escape or losing key focus closes; the Call and Record shortcuts open the selection and act in it (`:27-44`, `276-311`). Picking floats that conversation.
+
+### 2.11 Avatars
+
+**Model** (`IconAppearance.swift:7-71`; `Models.swift:14-17`): `iconSymbol: String?`, `iconColour: Int`, `iconImage: Data?`. Bots store an arbitrary integer seed; the rendered gradient is `|seed| mod 6` (`:30-34`), while browsers and computers clamp to 0-5. Bots persist `avatarSymbolName`, `avatarColorIndex` (falls back to `accentSeed`, a random 0-5 assigned at creation) and `avatarImageData` inside `agent.json` with the rest of the public record (`AgentConfiguration.swift:17-60`; the JSON read limit is 32 MiB).
+
+**Palette** (six two-stop linear gradients, top-leading to bottom-trailing): 0 blue to cyan, 1 purple to pink, 2 orange to yellow, 3 mint to teal, 4 indigo to blue, 5 pink to orange (`IconAppearance.swift:25-28`). These are dynamic system colours; see section 5 for approximate hex values.
+
+**Rendering** (`IconBadge`, `IconAppearance.swift:42-71`): a circle-clipped `size x size` frame showing the image scaled to fill, or the gradient with the symbol at 0.38 x size, semibold, white (people on a Hub can show initials at 0.36 x size, rounded semibold). Shadow black 20 %, radius 3, y 1, unless disabled. Default symbol `sparkles` (`BotAvatar.swift:12`). Native menus get a 16 pt avatar rendered at 2x (`BotAvatar.swift:30-38`). Sizes seen: 16 (menus), 22 (companion chooser), 32 (lists, popover rows), 42 (sidebar), 44 (people), 48 (member grids), 56 (picker), 64 (editors, first-run team), 88 (profiles), 104 (icon editor).
+
+**Icon editor** (`IconEditorSheet.swift:9-153`, configured for bots at `Overlays.swift:697-737`), 440 wide, edits a draft: Cancel / "Bot Icon" / Done (disabled while an image loads). Body `VStack(spacing: 18)`, padding 20: a 104 pt preview; GroupBox "Image" with two equal-width bordered buttons, "Choose Image…" (a menu, see below) and "Create Image…" (`apple.intelligence`, Image Playground, macOS 15.1+, only when the device supports it), a divider, a full-width bordered button "Use Symbol Instead" (`square.grid.2x2`) that reads "Using Symbol" (`checkmark`, disabled) while no image is set, and a spinner while loading; a red caption for failures; GroupBox "Colour" with six 34 pt gradient circles (spacing 12) and a 13 pt bold white checkmark on the selected one (only while no image); GroupBox "Symbol", a 6-column grid (spacing 10) of 42 pt-tall tiles (radius 10; selected accent fill with white glyph, else `secondary` 14 %; glyph 18 pt semibold). Picking a colour or symbol clears the image. The bot symbol set: `sparkles`, `bolt.fill`, `brain.head.profile`, `hammer.fill`, `terminal.fill`, `magnifyingglass`, `shippingbox.fill`, `paintbrush.fill`, `checkmark.seal.fill`, `ladybug.fill`, `wand.and.stars`, `gearshape.2.fill`. Done always records a symbol for bots (the image wins when present). There is no emoji avatar.
+
+**Image sources**:
+- "Choose Image…" opens an AppKit menu under a SwiftUI bordered button (`photo` icon plus a caption2 `chevron.down`, 20 pt label height): "Choose File…" (`folder`), "Photos Library…" (`photo.on.rectangle`); people's pictures also get "Take Photo…" (`camera`) first (`ImageSourceMenu.swift:26-66`). Bots do not offer the camera (`takesPhotos` defaults to false, `IconEditorSheet.swift:27-30`).
+- Image Playground ("Create Image…"): concepts from `AvatarIdea`, the phrases "avatar portrait" and the bot's name plus a concept extracted from the description, or the backstory when the description is empty (`NoodleWallpaperCore/AvatarIdea.swift:6-27`); illustration style, personalization disabled so it never offers people from Photos, square output; the current image seeds it (`ImagePlaygroundSetup.swift:5-35`; `NoodleImagePlaygroundButton.swift:7-41`). The illustrated portraits in both macOS screenshots are consistent with this style (inferred).
+- From the chat: an image attachment in a direct conversation offers "Use as Icon" (`person.crop.circle`) with the confirmation "Use as Icon?" / "Replace <name>’s icon with this image? Their icon will change everywhere in Noodle." / "Use as Icon" (`MessageContextMenu.swift:93-98`; `Components.swift:391-420`).
+- Camera (people only): Cancel / "Camera" / "Take Photo" (default action, disabled until the first frame arrives), live preview 320 x 320 clipped to a circle; the shot is mirrored as previewed, centre-square cropped and scaled to at most 512 px; errors "Allow Noodle to use the camera in System Settings > Privacy & Security > Camera.", "No camera is available.", "The camera cannot be read." (`CameraView.swift:51-57`, `94-158`; `IconAppearance.swift:108-122`).
+- Processing: sources over 50 MB are refused; images are thumbnailed to 512 px on the long side with EXIF orientation applied; bots encode JPEG at quality 0.86 (`Overlays.swift:733`; `IconAppearance.swift:93-147`). Errors: "That image could not be used.", "Choose an image smaller than 50 MB.", "The image is too large. Choose a smaller image.", "Photos could not provide this image. Try Choose File instead." (`IconAppearance.swift:80-91`).
+
+**Starter team** (first run): three bots on the chosen account, named by the generator, in a group "Team" ("Ask the team anything; the personal assistant brings in whoever fits."): Personal Assistant (`sparkles`, colour 0), Full-Stack Developer (`terminal.fill`, colour 2), Researcher (`magnifyingglass`, colour 3), each with a public description and a backstory; leaving the welcome sends "Welcome to the team! Please introduce yourselves, and tell me what you are best at and how you can help me." (`Sources/Noodle/StarterTeam.swift:15-31`).
+
+### 2.12 Conversation backgrounds
+
+**Model** (`NoodleWallpaperCore/ConversationBackground.swift:5-33`): `preset` (sunset, ocean, forest, dusk), `imageFilename`, `mediaKind` (image, video, dynamicImage). "Local appearance only: kept out of message delivery and the agent workspace." Stored per conversation as `background.json` plus `Backgrounds/<uuid>.<jpg|heic|heif|mov|mp4|m4v>` in the conversation folder; replacing a background deletes the old file and its phone-sized copy only after the new metadata commits (`Sources/NoodleCore/ConversationBackground.swift:7-95`).
+
+**Presets** (`NoodleWallpaper/ConversationBackgroundView.swift:82-115`): a three-colour linear gradient (top-leading to bottom-trailing) plus an ellipse of the middle colour at 50 % opacity, 1.4 x width by 1.1 x height, rotated -35°, offset 0.35 x width, blurred 50. Colours (from RGB fractions): Sunset #F58526, #C46EAB, #7559BF; Ocean #0A4280, #1499A8, #244D9E; Forest #143D2E, #57874D, #245763; Dusk #2E2963, #784A99, #BA5E78.
+
+**Rendering**: any non-default background gets a black 25 % scrim (`:92`) and switches the window to dark appearance with a 0.35 s cross-fade (`:118-156`); changing wallpapers cross-fades 0.35 s ease-in-out after the next image has loaded, so image-backed chats never flash the default canvas (`:5-7`, `43-61`). Videos loop muted with aspect fill and pause when the window is hidden, minimized or occluded, or under Reduce Motion; multi-frame HEICs advance every 8 s with a 1 s fade (`AnimatedWallpaper.swift:54-138`).
+
+**Background sheet** (`Sources/Noodle/ConversationBackgroundView.swift:4-71`), 520 wide, 24 padding, spacing 20: Cancel / "Conversation Background" / Apply (default action; disabled while busy or unchanged); the conversation title in secondary; a 210 pt live preview with radius 16 showing two sample bubbles on regular material capsules (10 pt padding), "Make this space your own." on the left and "Looks good!" on the right; the shared `BackgroundPicker`; a spinner while busy; a red caption on failure. The sheet cannot be dismissed while busy. Opened standalone (sidebar "Change Background…") Apply saves immediately; opened from Edit Bot or Group Info it only updates that editor's draft.
+
+**Picker** (`BackgroundPicker.swift:25-150`): a row of five swatches, "Default", "Sunset", "Ocean", "Forest", "Dusk" (spacing 12; 48 pt tall live previews, radius 8, 2 pt accent stroke when selected, caption title; accessibility value "Selected"/"Not selected"), then a row (spacing 8) of "Choose Background…" (menu: "Choose File…", "Photos Library…", and "System Wallpapers…" only while this Mac has some downloaded) and "Create Image…" (Image Playground sized like the main screen on macOS 27+, seeded with the still being previewed).
+
+**Sources and limits**:
+- Files (picker or drop): images up to 512 MB (re-encoded to JPEG at quality 0.9, max 2560 px), multi-frame HEIC kept as dynamic (at most 120 frames), MP4/M4V/MOV up to 1 GB that must prove playable within 12 s (`NoodleWallpaperCore/BackgroundMedia.swift:37-104`).
+- Photos library and generated images: up to 50 MB, converted to JPEG (`BackgroundPhoto.swift:6-23`; `BackgroundPicker.swift:119-126`).
+- Drag and drop onto the preview: Finder files, image or movie data, or a URL; remote links download (30 s request and 120 s resource timeouts, 1 GB cap, extension recovered from the MIME type); videos are preferred over posters and TIFF last; while targeted the preview shows a 3 pt accent border (radius 16); tooltip "Drop an image or video to use as the background" (`BackgroundDropTarget.swift:4-48`; `BackgroundDrop.swift:5-161`).
+- System wallpapers: only wallpapers already on disk (downloaded catalogue stills, hidden catalogue folders and aerial videos) are offered; sheet 720 x 560: Cancel / "System Wallpapers" / "Wallpaper Settings" (opens System Settings), a 4-column grid (spacing 12, rows 14, padding 20) of 16:10 thumbnails (radius 8, caption name), reloading when the app is reactivated (`SystemWallpaperSheet.swift:9-74`; `SystemWallpaper.swift:9-120`).
+- From the chat: "Use as Background" on an image attachment, confirmed with "Use as Background?" / "Replace the background for <conversation> with this image?" (`MessageContextMenu.swift:84-92`).
+- Errors: "Choose a readable image smaller than 50 MB."; "Choose a readable image or HEIC up to 512 MB, or a playable MP4, M4V or MOV video up to 1 GB. Wallpaper packages and streaming playlists are not supported."; "Drop a readable image or MP4, M4V or MOV video, or a direct link to one."; "The background couldn’t be downloaded. Try dropping the image or video itself."; Photos: "Photos couldn’t provide this image. If it’s in iCloud, open it in Photos and let it download, then try again. You can also use Choose Background → Choose File." (`ConversationBackground.swift:35-43`; `BackgroundDrop.swift:142-149`; `BackgroundPicker.swift:94`).
+
+### 2.13 Bots settings
+
+`BotsSettingsView` (`BotsSettingsView.swift:6-234`), a grouped form: a section with Toggle "Wake idle agents" and menu Picker "Wake after" (5, 10, 15, 30, 45 minutes, 1 hour, 2, 4, 8, 12 hours, 1 day, plus the current value); then one row per bot: profile button, name, a caption line with the access status as a link-like button ("restricted" in secondary or "unrestricted" in orange, "Restarting runtime…" while changing) and "· apps" in orange when enabled, and "Last heartbeat <relative time>" / "No heartbeat yet"; trailing mini switches in fixed columns Heartbeat (64), Unrestricted (100), Apps (64, "—" for providers without account apps) and Archived (64, only when some bot can be archived). Column headers are plain buttons opening 360-wide info popovers (20 padding). Turning on Unrestricted or Apps asks first: "Allow Unrestricted Access for <name>?" / "Allow Unrestricted Access" / "<name> will be able to read and change files and use services beyond its private workspace, with the access available to your Mac account. This restarts the bot." and "Allow Apps for <name>?" / "Allow Apps" / "... apps connected to your ChatGPT|Claude.ai account, such as Gmail, Google Drive, and Calendar, with the permissions you granted there. This restarts the bot." (`:262-281`). Archive info: "An archived bot keeps its workspace, memory and conversations, but does not run, wake or receive messages, and its chat leaves the sidebar. It stays a member of its groups but is left out of their messages." (`:236-247`).
+
+### 2.14 First-run setup (form only)
+
+`FirstBotSetupSheet` (`FirstBotSetupSheet.swift:7-183`), 640 wide, 20 padding. Step 1: four equal tiles in a row (spacing 10): Codex "by OpenAI", Claude "by Anthropic", Muse "by Meta", Grok "by xAI" (`FirstBotSetup.swift:17-38`), each a 36 pt brand icon, headline name, caption maker and a status label ("Checking…" `ellipsis.circle`; "Ready" green `checkmark.circle.fill`; "Sign-in required" `person.crop.circle.badge.questionmark`; "Unavailable" `minus.circle`), 18 pt vertical padding, `primary` 4 % fill, radius 12; choosing a tile starts install or sign-in; "Not Now" link (cancel action). Step 2: icon, name, status, a single linear progress bar that never changes position, sign-in challenge views, red selectable errors, and link-style "Install" / "Sign In…" and "Back". Step 3: the three starter bots (64 pt avatar, headline name, caption role, 140 pt columns) and a large prominent "Continue" (default action) that greets the team.
+
+### 2.15 Form and copy conventions
+
+- Labels are `caption` semibold above the control; helper text is `caption` secondary below; errors are `caption` red, and warnings orange with `exclamationmark.triangle.fill`. One requirement line (Group Info members) changes from secondary to red instead of adding a new message (`Overlays.swift:804-806`).
+- Containers: input wells use `quaternary` at 25-35 % with radius 10-12; disclosure rows use `quaternary` 30 %, 12 pt padding, radius 10; the harness card uses `secondary` 7.5 % with an 11 % hairline; tiles use accent 15-16 % plus a 1.5 pt accent stroke when selected; list-row remove badges are `xmark.circle.fill` / `minus.circle.fill` in white on dark grey; add affordances are blue `plus.circle.fill`.
+- Large empty states are whole-area buttons (large-title symbol over a sentence such as "Add tools to this bot") that open the same chooser as the header button.
+- Fixed heights where content changes (220 pt tool list, 140-280 pt wells) prevent sheets from jumping as items are added (`MCPAssignmentPicker.swift:24-25`).
+- Noodle's own copy rules (data from `.agents/skills/ui-copy/SKILL.md:6-40`): no persistent instructional hints or shortcut legends unless requested, optional guidance in tooltips; a trailing "…" (single character) only when the command needs more input ("Add Tools…", "New Computer…", "Choose Image…"), never for "New Bot" or for actions that merely confirm ("Delete Bot"); row secondary actions go in a `…` menu with the destructive action last. British "Colour" appears in UI (`IconEditorSheet.swift:74`).
+- Approximate macOS text styles (inferred from Apple's macOS type scale, not in the repo): headline 13 pt bold, body 13, callout 12, caption 10, caption2 10, title2 17, large title 26.
+
+### 2.16 iOS editor (screenshot)
+
+The mobile editor is a standard inset-grouped `Form` in a navigation stack: avatar 88 pt with tinted "Edit" (opens a picture editor), "Name", a Harness menu picker ("Choose" until set; "Your plan lends no harnesses" when empty), Model ("Default" or "Choose" when the Hub restricts models), Effort ("Default"), Voice navigation row ("Automatic" until chosen), Tools / Computers / Browsers navigation rows, "Sharing" ("Only You", "1 Person", "N People"), "Background", then "Kick" (failed only) and "New Session", then red "Delete Bot" with "Delete <name>?" / "Delete" / "The bot and its conversation are deleted from the Hub for all your devices." The toolbar shows Cancel and "Create" or "Save" (`Mobile/Sources/NoodleMobile/Chats.swift:2158-2298`). The screenshot's avatar uses palette 5 (pink to orange) with `sparkles`.
+
+## 3. Web translation
+
+### 3.1 Schemas (zod)
+
+```ts
+import { z } from "zod";
+
+const graphemes = (s: string) =>
+ [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(s)].length; // Swift counts graphemes
+const NOT_SINGLE_LINE = /[\n\r\u000B\u000C\u0085

\p{Cc}]/u; // add \p{Cf} for exact parity (see 5)
+
+export const conversationName = z.string().transform((s) => s.trim()).superRefine((s, ctx) => {
+ if (!s) ctx.addIssue({ code: "custom", message: "Enter a name." });
+ else if (NOT_SINGLE_LINE.test(s))
+ ctx.addIssue({ code: "custom", message: "Names must be a single line. Put longer text in Description or Backstory." });
+ else if (graphemes(s) > 100) ctx.addIssue({ code: "custom", message: "Keep names to 100 characters or fewer." });
+});
+
+export const folderSchema = z.object({
+ path: z.string().startsWith("/"),
+ writable: z.boolean().default(true),
+ description: z.string().max(500).optional(), // collapsed to one line on save
+});
+
+export const avatarSchema = z.object({
+ symbol: z.string().nullable(), // icon id; null = default "sparkles"
+ colour: z.number().int(), // any int; palette index = Math.abs(colour) % 6
+ image: z.string().nullable(), // URL of a stored 512 px JPEG (q 0.86)
+});
+
+export const botSchema = z.object({
+ name: conversationName,
+ harness: z.string().min(1), // installed locally or lent by a Hub
+ model: z.string(), // "" = harness default
+ effort: z.string(), // "" = model default
+ profileId: z.string().uuid().nullable(), // null = "System"
+ voice: z.string(), // "" = follows the name until chosen
+ publicDescription: z.string(), // trimmed; "" stored as null
+ backstory: z.string(), // private; never sent to profiles or other bots
+ avatar: avatarSchema,
+ toolIds: z.array(z.string().uuid()),
+ calendarIds: z.array(z.string()),
+ reminderListIds: z.array(z.string()),
+ computerIds: z.array(z.string().uuid()),
+ browserIds: z.array(z.string().uuid()),
+ folders: z.array(folderSchema).max(16, "At most 16 folders can be shared."),
+ sharedWith: z.array(z.string().uuid()).optional(), // edit only
+});
+
+export const groupSchema = z.object({
+ name: conversationName,
+ publicDescription: z.string(),
+ memberIds: z.array(z.string().uuid()).min(1), // shown by turning the helper line red, not a new message
+ folders: z.array(folderSchema).max(16),
+ location: z.string(), // "this-device" or a joined Hub id; members must match it
+});
+
+export const backgroundSchema = z.object({
+ preset: z.enum(["sunset", "ocean", "forest", "dusk"]).nullable(),
+ imageFilename: z.string().nullable(),
+ mediaKind: z.enum(["image", "video", "dynamicImage"]).nullable(),
+});
+```
+
+Form wiring: one react-hook-form instance per sheet spanning all tabs (Noodle keeps every field in the sheet so switching tabs, which rebuilds the tab view, loses nothing; it even lifts the built-in tool toggles into the sheet for that reason, `MCPAssignmentPicker.swift:15-17`). Use `mode: "onChange"` so the primary button's disabled state tracks validity; render the name error only when the raw value is non-empty. Cascades (harness to model/effort/profile; model to effort) belong in `useEffect`/`watch` subscriptions or a reducer, not in field components. The voice auto-follow is a 400 ms debounced effect that stops once `voiceChosen` is set.
+
+### 3.2 Component structure
+
+```
+BotEditorDialog (mode: create | edit) ~ NewBotSheet / EditBotSheet
+ SheetHeader [Cancel] title [Create|Save] text buttons, primary disabled when invalid
+ Separator
+ Body (p-5, gap-4 / gap-[18px])
+ IdentityRow: AvatarEditButton(64) + NameField(regenerate in trailing slot) + caption (create only)
+ FieldError (name)
+ SegmentedTabs: General | Harness | Tools | Computers | Browsers (Radix Tabs or ToggleGroup)
+ General: DescriptionField, BackstoryField, DisclosureRow(Folders), DisclosureRow(Background, edit),
+ SharingGrid (edit, hub only), Separator, DestructiveButton("Delete Bot") (edit)
+ Harness: HarnessCard{ SelectionRow(Harness), SelectionRow(Profile)?, SelectionRow(Model),
+ EffortSlider, SelectionRow(Voice)? } + notes
+ Tools: AssignmentWell(list) + ChooserPopover + NewToolDialog
+ Computers / Browsers: AssignmentWell(grid) + ChooserPopover + NewCompanionDialog
+GroupEditorDialog (create 480 / info 460), IconEditorDialog (440), BackgroundDialog (520),
+SystemWallpapersDialog (720 x 560), ProfilePopover (320), ConversationSwitcher (560, Command palette)
+```
+
+shadcn mapping: Dialog for sheets; Tabs (styled as a segmented control, centred, intrinsic width); Popover + Command for choosers; AlertDialog for every confirmation in 2.6; Tooltip for every `.help`; DropdownMenu for "Choose Image…" / "Choose Background…"; Slider customised for Effort (Radix keeps the slider semantics Noodle recreates with `accessibilityRepresentation`); ToggleGroup for "Read & Write / Read Only"; Avatar for the circle badge; `lucide-react` icons in place of SF Symbols (`sparkles`, `bolt`, `brain`, `hammer`, `terminal`, `search`, `package`, `paintbrush`, `badge-check`, `bug`, `wand-sparkles`, `cog` are close equivalents; inferred mapping).
+
+### 3.3 Dialog sizing and motion
+
+- Fixed widths from the table in 2.1 with `max-w-[calc(100vw-2rem)]`; height fits content up to the viewport, with internal scrolling in the wells rather than the dialog when possible.
+- Anchor the dialog's top edge (for example `top-[8vh] translate-y-0`) so it grows downward like a macOS sheet; animate height changes on tab switch with a ResizeObserver-driven height transition (about 220 ms, matching the 0.22 s tab animation) and disable it under `prefers-reduced-motion`.
+- Close behaviour: editors must not close on outside click or Escape while dirty (Noodle's profiles close on outside click; editors deliberately do not). Profiles may close on outside click and on window blur.
+- Present nested dialogs (New Tool, New Computer, Folders, Icon, Background) only after the triggering popover has closed, mirroring the `wantsNew`/`onDisappear` pattern, to avoid focus-trap conflicts.
+
+### 3.4 Picker patterns
+
+- AssignmentWell: header (label + outline "Add X" button) over a well with min 140 / max 280 px height (tools: fixed 220), empty state as a full-area button, selected items as a grid (84 px minimum columns, 48 px avatars, corner remove badge offset 10/-8) or a list (26 px icon, edit and remove icons). Removal opens an AlertDialog whose copy says the change applies on save and the underlying item is not deleted.
+- ChooserPopover: search input on top, scrollable list of not-yet-selected items each with a trailing add icon, multi-add without closing, distinct empty texts for "everything added" versus "no matches", a footer for "New X…" and "Open <companion>". Fixed popover sizes (300 x 280, 330 x 260) keep it stable while filtering.
+- Single-select popovers (harness, profile, model): list with trailing check, select-and-close, height `clamp(110px, 62px + rows x 44px, 420px)`; the model list adds search and a count footer.
+- Tile choosers (voice, location, sharing): grid of rounded tiles; selected = accent-soft fill + 1.5 px accent ring + check badge; voice tiles play a preview and stay open.
+- Conversation switcher: a Command palette rendered as a 4-column grid with arrow-key grid navigation (no wrap), Enter to open, Escape to close, fixed height chosen when opened.
+
+### 3.5 Avatars and backgrounds on the web
+
+- Avatar pipeline: accept file, paste, drag-drop and generated images; decode with `createImageBitmap(file, { imageOrientation: "from-image" })`, draw to a canvas scaled so the long side is at most 512 px, export `image/jpeg` at 0.86; refuse sources over 50 MB. Render as `object-cover` in a circle; otherwise the gradient plus a white icon at 38 % of the size. Image generation can reuse AvatarIdea as a prompt: "avatar portrait, {name}, illustration" plus the description (else backstory).
+- Background pipeline: still images to JPEG at 0.9 with a 2560 px long side; videos as `<video muted loop playsinline autoplay>` with `object-fit: cover`, paused on `visibilitychange` and under reduced motion; a fixed 25 % black overlay; switch the conversation surface to the dark theme while a background is set; cross-fade 350 ms once the next image has loaded. Presets render as CSS: a 135° three-stop linear gradient plus a rotated, 50 px-blurred ellipse of the middle colour at 50 %.
+
+### 3.6 Tokens rather than opacity arithmetic
+
+To respect the "no opacity arithmetic at call sites" rule, define named tokens for the recurring tints: `--surface-well` (quaternary 35 %), `--surface-well-subtle` (25 %), `--surface-row` (30 %), `--surface-card` (secondary 7.5 %) with `--border-card` (11 %), `--field-editor` (secondary 10 %) with `--border-editor` (18 %), `--tile` (secondary 8 %), `--tile-selected` (accent 15-16 %), `--picker-tile` (primary 4 %), `--picker-tile-selected` (accent 28 %), `--scrim-wallpaper` (black 25 %), `--badge-remove` (white glyph on dark grey), and effort gradient stops `--effort-0` to `--effort-4`.
+
+## 4. Patterns worth copying, and pitfalls
+
+Copy:
+- Pre-filling a plausible name with a one-click regenerate makes "hiring" a one-step action; the caption promising that renaming is safe removes hesitation.
+- Splitting the public description (shared with other bots and profiles) from a private backstory, with the helper text saying so, is a clear privacy model; restarting with a fresh session when the backstory changes keeps behaviour consistent with the prompt.
+- Transactional saves (checkpoint, write, restore on failure; background committed together with settings) so a failed edit never leaves a half-applied bot.
+- Assignment wells with stable heights, whole-area empty-state buttons, multi-add choosers and "loses access when you save; the item itself is not deleted" confirmations.
+- Profiles that use only public data, dismiss on outside click, and expose at most four actions per row.
+- Sheets anchored at the top that resize to content without remounting, so drafts and focus survive tab switches.
+- Media limits and error messages that name the accepted formats and sizes.
+
+Pitfalls:
+- Edit Bot's Save has no dirty check (Group Info does): saving an unchanged bot still restarts it. Add a dirty check on the web.
+- The name error appears under the whole identity row, separate from its field, and not at all while the field is empty; place errors next to the field and use `aria-describedby`.
+- Header primary buttons are plain blue text with no keyboard shortcut except Return in the name field; on the web, make the primary a real button and bind Enter and Escape deliberately.
+- Some labels are inconsistent: "Tools" is a headline while other section labels are captions; Settings says "Wake idle agents" while the rest of the UI says "bots".
+- Popovers for single choices close on selection, but the voice popover does not; make that difference visible (for example a Done affordance) on the web.
+- Swift's control-character set includes Unicode format characters, so names containing zero-width-joiner emoji are likely rejected as "not a single line" (inferred); decide deliberately whether to copy that.
+- Very small caption sizes (10 pt) suit macOS but are hard to read on the web; scale the type ramp up.
+
+## 5. Open questions and inferences
+
+- Approximate hex values for the avatar palette, from Apple's 2025 system colours (inferred, not in the repo; verify in light and dark): blue #0088FF, cyan #00C0E8, purple #CB30E0, pink #FF2D55, orange #FF8D28, yellow #FFCC00, mint #00C8B3, teal #00C3D0, indigo #6155F5. The iOS screenshot's pink-to-orange avatar is consistent with these.
+- Whether Escape dismisses the bot and group sheets on macOS was not verified; no `.cancelAction` is bound on their Cancel buttons.
+- `avatarImageData` is a `Data` field in `agent.json`; its JSON form is assumed to be Foundation's default base64 string (inferred).
+- The popover `arrowEdge: .leading` placement implies choosers open beside the row rather than below it (inferred from the API; not visible in the screenshots).
+- The macOS text-style point sizes in 2.15 are inferred from Apple's documented scale.
+- Hub-specific flows (harness lending, Hub pickers, sharing) were read only as far as they change the editors; their server behaviour is out of scope here.
+- The illustrated avatars and wallpaper in the screenshots are assumed to come from Image Playground or user images; the screenshots do not say which.
diff --git a/docs-internal/research/noodle/analysis/06-settings-harness-usage-activity.md b/docs-internal/research/noodle/analysis/06-settings-harness-usage-activity.md
new file mode 100644
index 00000000..dcf43679
--- /dev/null
+++ b/docs-internal/research/noodle/analysis/06-settings-harness-usage-activity.md
@@ -0,0 +1,428 @@
+# Noodle settings, harness setup, usage and activity
+
+Noodle's operational UI is one macOS Settings window with eleven toolbar tabs, plus two free-standing windows (Usage, and one floating Activity log per bot) and a family of sheets opened from settings rows (harness profiles, local and remote models, tool catalog and editor, Hub join and invitation). Almost everything is a stock SwiftUI grouped `Form`; a small shared package (`Shared/SettingsUI`, module `NoodleSettingsUI`) patches three macOS gaps: tab content that fits its height but never exceeds the screen, scroll indicators that flash while the window resizes, and toolbar tab badges SwiftUI cannot draw. Every row family (harness, permission, companion, Hub, tool) shares one anatomy: a 32 pt secondary-tinted icon column, a semibold title with a right-aligned caption status label (SF Symbol plus text in green, orange or secondary), caption detail lines, then one line of link-style actions. Status is always derived from facts in a fixed priority order, never stored as display text, and the last confirmed harness presentation is cached so the Harness tab paints instantly and re-checks in the background. Destructive actions always confirm with a sentence describing consequences, and Cancel is the keyboard default.
+
+Permalink base for every citation below: https://github.com/pdparchitect/noodle/blob/702339e3153025c9fe9582783caff7a19b48ff97/
+
+## 1. Scope
+
+Read in full:
+
+- `Sources/Noodle/`: `NoodleSettingsView.swift`, `HubSettingsView.swift`, `PermissionsSettingsView.swift`, `KeybindingsSettingsView.swift`, `UsageWindow.swift`, `ToolExtensionDiscovery.swift`.
+- `Sources/NoodleRuntimeSettings/`: `HarnessSettingsView.swift`, `HarnessProfilesView.swift`, `HarnessSignInChallengeView.swift`, `HarnessProviderIcon.swift`, `AppleRemoteModelsView.swift`, `AppleLocalModelsView.swift`, `UsageView.swift`, `AgentActivityWindow.swift`, `MCPSettingsView.swift`, `MCPController.swift`, `ToolCatalogView.swift`, `CompanionAppsSettingsView.swift`, `CompanionUpdateChecker.swift`, `CompanionApp.swift`, `HubLinkRows.swift`, `HubInvitationSheet.swift`, `SettingsRowList.swift`, `SettingsStatusLabel.swift`, `ConversationRuntimeSettings.swift`.
+- `Shared/SettingsUI/Sources/NoodleSettingsUI/`: all seven files.
+- Docs: `docs/harness-setup.md`, `docs/mcp-connections.md`, `docs/security.md`, `docs/privacy.md` (skimmed), plus `docs/usage.md` and `docs/keyboard-shortcuts.md` for context.
+
+Read in part for exact strings and rules: `Sources/NoodleCore/{Harnesses,HarnessSetup,HarnessVersions,HarnessPresentationCache,KeyboardShortcuts,ToolCatalog,UsageLedger,AgentSessionRollover,MessageDelivery}.swift`, `Sources/NoodleRuntime/{HarnessSetupController,AgentActivityLog,AgentActivityParser,UsageHistory}.swift`, `Sources/Noodle/{AppUpdater,KeyboardBindings,MCPAssignmentPicker,ThisMacHub,GroupsSettingsView,NoodleApp,SidebarView}.swift`, `Sources/NoodleRuntimeSettings/{AgentKickConfirmation,BotsSettingsView}.swift` (access copy only; the Bots tab belongs to another analysis), `Sources/HubCore/HubReachability.swift`, `Shared/HubLink/.../{LinkProtocol,LinkIdentity,LinkInvitationImage,HubTroubleshooting}.swift`, `Hub/Sources/NoodleHub/{HubSettings,HubAccessSettings,HubLinkSettings}.swift`, `Mobile/Sources/NoodleMobile/HubScreens.swift` (troubleshooting sheet), `CHANGELOG.md`.
+
+Screenshots viewed: `website/assets/screenshot-harness.png` (Noodle Settings, Harness tab, dark) and `website/assets/screenshot-hub.png` (Noodle Hub app Settings, Users and Plans tabs, dark).
+
+Both screenshots predate this commit. The harness screenshot shows tabs General, Conversation, Harness, Heartbeat, Sandbox, Tools, Keybindings, Companions, Update; `CHANGELOG.md:138` (0.41.0, 2026-10-03) records that "Settings has one Bots tab in place of Heartbeat and Sandbox". It also shows bordered "Sign In…" and "Local Models…" buttons, a "Version 0.154.0" line under the path, and no Antigravity row, where the current code uses link buttons on one action line, shows the version after the path separated by "·", and lists Antigravity. The Hub screenshot shows bordered "Invite…" and "Remove…" buttons and an inline plan popup, where current code uses link buttons and puts the plan picker in the row's actions menu. Treat the screenshots as ground truth for the overall look (grouped dark container, row rhythm, status label style, footer bar) and the code as ground truth for current controls and copy.
+
+## 2. Findings
+
+### 2.1 Settings window shell
+
+Tabs, in order (`Sources/Noodle/NoodleSettingsView.swift:40-91`). The enum is `NoodleSettingsTab` (`:8-10`); several cases display a different name.
+
+| # | Label | SF Symbol | Enum case | Badge count (`:94-98`) |
+|---|---|---|---|---|
+| 1 | General | `gearshape` | `general` | none |
+| 2 | Conversation | `bubble.left.and.bubble.right` | `chat` | none |
+| 3 | Harness | `terminal` | `harnesses` | harnesses needing attention |
+| 4 | Bots | `sparkles` | `bots` | none |
+| 5 | Groups | `person.3` | `groups` | none |
+| 6 | Tools | `puzzlepiece.extension` | `mcps` | connections whose row shows an error |
+| 7 | Keybindings | `keyboard` | `keybindings` | none |
+| 8 | Permissions | `hand.raised` | `permissions` | permissions the user refused |
+| 9 | Companions | `square.stack.3d.up` | `companions` | companions behind their update feed |
+| 10 | Hub | `server.rack` | `hub` | none |
+| 11 | Update | `arrow.triangle.2.circlepath` | `updates` | 1 when a Noodle update is available |
+
+The Harness count (`:20-27`) is the number of providers where `HarnessSetupController.needsAttention` is true (a setup error, a compatibility issue, or an available update; `Sources/NoodleRuntime/HarnessSetupController.swift:78-83`) or where any bot on that harness has `canKick && phase == .failed`. Reconnecting bots, uninstalled harnesses and signed-out harnesses are not counted. Permissions counts only `.denied`, never `.notRequested` (`PermissionsSettingsView.swift:93-95`), because an unrequested permission is asked for on first use.
+
+Window rules:
+
+- Every tab is wrapped in `.settingsContentSize(width: 740)` (`NoodleSettingsView.swift:34-35`): "Wide enough for every tab in the toolbar, none left in its overflow menu". The badge code depends on no overflow (see below).
+- The scene uses `.windowResizability(.contentSize)` (`Sources/Noodle/NoodleApp.swift:189-193`) and the TabView has `.windowResizeAnchor(.top)` (`NoodleSettingsView.swift:214-219`): the window height follows the selected tab and its top edge stays put.
+- Selection is bound to `store.selectedSettingsTab` with `.animation(.easeInOut(duration: 0.22))` (`:40`), so the height change animates. Other surfaces deep-link by setting the tab: `showHarnessSettings()` sets `.harnesses` (`:222`), used by the sign-in notification (`NoodleApp.swift:285`) and the Kick alert's "Open Harness Settings" button (`AgentKickConfirmation.swift:15-19`). An invitation link received from anywhere selects the Hub tab and opens Settings, which presents the join sheet pre-filled (`NoodleStore.swift:868-869`, `NoodleApp.swift:357-360`, `HubSettingsView.swift:89-91`).
+- The window title is the selected tab's label (the screenshot reads "Harness").
+- On open, `.onAppear` refreshes companion update feeds, asks Sparkle quietly whether an update exists, and re-reads permissions; `.task` runs the full harness refresh (`NoodleSettingsView.swift:99-105`). Badges are therefore correct before a tab is selected.
+
+Content sizing (`Shared/SettingsUI/.../SettingsContentSize.swift`). A custom `Layout` reports the content's ideal height capped at `maxHeight` and then lays the content out in the bounds it is actually given, so a `Form` or `ScrollView` inside scrolls instead of running off screen (`:33-47`). `maxHeight` is the screen's `visibleFrame.height` (below the menu bar, above the Dock) minus the window's chrome (title bar plus toolbar), floored at 200 pt (`:52-57`). A zero-hit-test observer view re-reports on `NSWindow.didChangeScreenNotification` and `NSApplication.didChangeScreenParametersNotification`, deferring the state change out of the layout pass (`:75-93`).
+
+Scroll indicators (`SettingsScrollIndicators.swift`, macOS 27 only). Indicators are forced hidden in the very update that changes the selected tab and on every window resize, and restored only after 350 ms with no further resize (`:51-58`); a live drag never restores them midway. It uses `.hidden`, which keeps the scrollbar gutter for users who always show scrollbars, and writes the environment values directly because switching the modifier back to automatic could stay hidden on macOS 27 (`:28-36`).
+
+Tab badges (`SettingsTabBadge.swift`). SwiftUI's `badge` does not reach Settings tabs, and SwiftUI clears `NSToolbarItem.badge` on every window update, which makes AppKit rebuild and flicker its badge view (`:4-10`). Noodle instead adds its own `CountView` as a subview of each tab's toolbar button. Geometry copies the macOS 26 toolbar badge: height 12 pt, width `max(12, ceil(textWidth) + 4)`, corner radius 6 (full capsule), `systemRed` fill, white system font 8 pt centred, pinned to the button's top-trailing corner (top-leading in right-to-left) with an autoresizing mask so it stays pinned, `hitTest` returning nil so clicks reach the tab, and an accessibility static-text label of the count (`:92-141`). Buttons are found by walking the title bar's view tree (excluding the window's own traffic-light and toolbar buttons), sorting by x, and zipping them with `toolbar.visibleItems` by label; any count mismatch, such as an overflow chevron, yields no badges at all (`:72-89`). A `CFRunLoop` observer (`beforeWaiting`) re-applies after the toolbar's buttons exist (`:39-45`). Badges are keyed by tab label strings ("Harness", "Tools", "Permissions", "Companions", "Update"), so renaming a tab silently drops its badge. macOS 26 and later only (`:49`).
+
+Noodle Hub's Settings window reuses the same toolkit (`Hub/Sources/NoodleHub/HubSettings.swift:95-160`): tabs Network (`network`, selected by default), Harness, Users (`person.2`), Plans (`rectangle.stack.badge.person.crop`), Bots, Groups, Conversation, a hidden Tools tab, Companions, Update; badges on Harness, Network (1 when the link failed), Companions and Update. Its pane width is 680 with the stale comment "The same pane width as Noodle's settings" (`:169-172`); Noodle now uses 740.
+
+### 2.2 Recurring row, list, status and sheet patterns
+
+Status label (`Sources/NoodleRuntimeSettings/SettingsStatusLabel.swift:8-14`): `Label(title, systemImage:)` with `.labelStyle(.titleAndIcon)`, `.font(.caption)`, one foreground colour for icon and text, `.fixedSize()` so it never wraps. It always sits at the trailing end of the title line. The full vocabulary across surfaces:
+
+| Surface | Title | SF Symbol | Colour |
+|---|---|---|---|
+| Harness, profile | Signed in | `checkmark.circle.fill` | green |
+| Harness, profile | Ready | `checkmark.circle.fill` | green |
+| Harness, profile, tool | Sign-in required | `person.crop.circle.badge.questionmark` | secondary |
+| Harness | Sign-in status unknown / Checking sign-in… / Installed | `person.crop.circle.badge.questionmark` | secondary |
+| Harness | Checking… | `ellipsis.circle` | secondary |
+| Harness, companion | Not installed | `arrow.down.circle` | secondary |
+| Harness, tool | Needs attention | `exclamationmark.triangle` | orange |
+| Harness | Reconnecting | `arrow.trianglehead.2.clockwise` | orange |
+| Harness | Setting up | (falls through to the icon of the underlying state) | (underlying) |
+| Companion | Installed | `checkmark.circle.fill` | green |
+| Tool, joined Hub | Connected | `checkmark.circle.fill` | green |
+| Joined Hub | Connecting… | `circle.dotted` | secondary |
+| Joined Hub | Not connected | `exclamationmark.circle.fill` | orange |
+| Hub link | (reachability summary) | `checkmark.circle.fill` or `exclamationmark.circle.fill` | green or orange |
+| Hub link | Starting… | `circle.dotted` | secondary |
+| Permission | Allowed | `checkmark.circle.fill` | green |
+| Permission | Not requested | `questionmark.circle` | secondary |
+| Permission | Not allowed | `exclamationmark.triangle.fill` | orange |
+| Permission | Checking… | `circle.dotted` | secondary |
+
+Colour semantics are consistent: green means usable, orange means the user must act or something failed but is recoverable, secondary means neutral or pending, and red is reserved for inline error text (caption, selectable, wrapping) and the badge fill.
+
+Icon row anatomy (harness `HarnessSettingsView.swift:120-240`, permission `PermissionsSettingsView.swift:197-222`, companion `CompanionAppsSettingsView.swift:60-110`, Hub `HubSettingsView.swift:94-114,139-179`):
+
+- `HStack(alignment: .top, spacing: 12)`.
+- Icon column: SF Symbol at `.system(size: 24)`, `.secondary`, in a 32 x 32 frame, accessibility hidden. Harness marks are template images at 28 x 28 plus 2 pt padding inside the same 32 x 32 (`HarnessSettingsView.swift:122-127`).
+- Text column: `VStack(alignment: .leading, spacing: 6)`; first line is the name `.fontWeight(.semibold)`, a `Spacer`, then the status label; following lines are `.font(.caption)` `.secondary`, `fixedSize(horizontal: false, vertical: true)` so they wrap.
+- Actions: `.buttonStyle(.link)` text buttons in an `HStack(spacing: 12)`, either on their own line (harness) or trailing the summary line on its first text baseline (permission, companion, Hub).
+- Row padding: `.padding(.vertical, 4)` (6 for harness rows).
+
+Grouped lists inside a form section use `SettingsRowList` (`SettingsRowList.swift`): rows in a `VStack(spacing: 10)` separated by `Divider`, toggles forced to `.switch` style, and a custom `SettingsBotListLayout` that proposes a fixed 360 pt height during measurement so the list never resizes the Settings window after the first layout (`:47-58`). `ViewThatFits(in: .vertical)` shows the rows plainly when they fit and a `ScrollView` otherwise; the scroll view gets 20 pt of trailing padding inside and minus 20 pt outside, so its scrollbar sits in the form's trailing margin while rows stay aligned with other controls (`:10,13-24`). The Groups tab uses it with a 64 pt trailing "Archived" switch column and an "Archived" header button that opens an explanation popover (`GroupsSettingsView.swift:9,21-35,55-69`).
+
+Footer action bar, used by Harness, Keybindings, Companions, Tools and the Hub app's Users/Plans tabs: `Divider()` then `HStack { Spacer(); [optional small ProgressView]; Button }` with `.padding(.horizontal, 20).padding(.vertical, 12)` (`HarnessSettingsView.swift:47-60`, `CompanionAppsSettingsView.swift:34-41`, `HubAccessSettings.swift:408-418`).
+
+Sheet anatomy, used by Profiles, Local Models, Remote Models, Hub join and invitation: title `.font(.title2.bold())` at the top of a `VStack(alignment: .leading, spacing: 18)` padded 24, then `Divider`, then a footer `HStack` padded 24 horizontal and 16 vertical with secondary actions leading and "Done" (`.keyboardShortcut(.defaultAction)`) trailing (`HarnessProfilesView.swift:23-62`). Widths: 480 (profiles, local and remote models, MCP editor, tool catalog), 460 (Hub join, model editor, Hub users), 420 x 360 (Hub archived), 400 (invitation), 380 (account form). Sheets that change height use `noodleSheetSizing(animated:)` (`SheetSizing.swift`): `fixedSize(vertical)`, `.presentationSizing(.fitted)`, plus a bridge that resizes the real sheet window to the measured content outside the layout pass, coalescing measurements, animating with the top edge pinned unless Reduce Motion is on, so editors are never recreated and lose drafts (`:16-66`). Smaller form sheets (account form, model form) use a headline title and `padding(20)`.
+
+Row actions menu: `Menu { … } label: { Image(systemName: "ellipsis.circle") }` with `.menuStyle(.borderlessButton)`, `.menuIndicator(.hidden)`, `.fixedSize()` and an accessibility label such as "Profile Actions", "User Actions" or "Actions for <name>" (`HarnessProfilesView.swift:100-113`, `HubSettingsView.swift:431-456`, `AppleRemoteModelsView.swift:158-186`). Order inside: non-destructive commands, `Divider`, destructive "Remove" or "Delete" last.
+
+Confirmations: `.alert` or `.confirmationDialog` whose title names the object ("Remove <name>?", "Leave <hub>?", "Delete Profile?"), a destructive button with the verb, and `Button("Cancel", role: .cancel) {}.keyboardShortcut(.defaultAction)`, which makes Return cancel rather than destroy (`HubSettingsView.swift:45-51,196-201`, `HarnessProfilesView.swift:71-77`). The message always states the consequence and what is kept, for example "Bots that use <harness> stop working until it is installed again. Your sign-in is kept." (`HarnessSettingsView.swift:396-398`).
+
+Explain-on-click: a caption-sized plain `Button` styled as text (a column header like "Archived", "Unrestricted", "Apps", a tag like "Experimental", or a status word like "restricted") opens a `.popover` with a headline and one to three paragraphs, `.padding(20)`, `.frame(width: 360, alignment: .leading)` (`HarnessSettingsView.swift:133-149`, `GroupsSettingsView.swift:75-86`, `BotsSettingsView.swift:309-334`).
+
+Delayed progress: background checks never flash a spinner. The Harness footer spinner turns visible only after 300 ms of continuous refreshing and is kept in layout at opacity 0 otherwise (`HarnessSettingsView.swift:49-54,63-70`); while a version re-check runs, an old check error is replaced by "Checking for updates…" rather than removed (`:342-348`).
+
+Relative times re-render on a timer: device "Last seen …"/"Joined …" via `TimelineView(.periodic(from: .now, by: 15))` (`HubSettingsView.swift:60-69`), the invitation countdown and the reconnecting timer every 1 s (`HubInvitationSheet.swift:99-108`, `HarnessSettingsView.swift:276-280`).
+
+Refresh on return to the app: Harness, Companions, Permissions and the Hub app's Network tab all re-check on `NSApplication.didBecomeActiveNotification`, because the most likely moment for an external change is returning from Terminal, System Settings or a browser (`PermissionsSettingsView.swift:191-194`).
+
+### 2.3 General, Conversation and Update tabs
+
+| Tab | Control | Copy and options | Default |
+|---|---|---|---|
+| General | Segmented picker | "Generated bot names": Real, Playful | Real |
+| General | Toggle + footer | "Keep Mac awake while agents work"; footer "Prevents automatic idle sleep only while an agent is working. Closing the lid or choosing Sleep still suspends the Mac." | runtime setting |
+| Conversation | Segmented picker | "Attachment layout": Wrap, Vertical, Stack; help is the selected option's explanation ("Fit attachments side by side and wrap onto new rows as needed.", "Show attachments one below another.", "Overlap attachments while keeping part of each one visible.") | Wrap |
+| Conversation | Picker + footer | "Message delivery": Automatic, Send immediately, Queue; footer "Automatic uses Apple Intelligence to decide whether new messages should reach a busy agent immediately or wait until its turn finishes. When Apple Intelligence is unavailable, messages wait." | Automatic |
+| Conversation | Two pickers + footer | "New session": Never, Daily, Every 3 days, Weekly; "When idle for": 30 minutes, 1 hour, 2 hours, 4 hours (disabled when Never); footer "An idle bot starts a fresh session once its current one is this old. Its workspace, memory and messages are kept." | Daily, 1 hour |
+| Conversation | Picker | "Message received sound": None, divider, Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink; plays on change | Blow |
+| Conversation | Picker | "Microphone": "System Default — <device>", then devices, plus "Selected microphone unavailable" when the saved one is missing; device list polled every 2 s while visible | System Default |
+| Conversation | Toggle + footer | "Show descriptions in the @ name menu"; footer "Show each bot's public description beside its name. Private backstories are never shown." | on |
+| Conversation | Toggle | "Keep one floating conversation"; help "Floating another conversation replaces the open one, in the same place and size." | off |
+| Conversation | Toggle | "Preview web links"; help "Open web links in Quick Look first, with a button to continue in your browser. When off, links open in your browser." | on |
+| Update | LabeledContent | "Installed Version": short version or "Development"; then "Update available — <version>" in orange caption | |
+| Update | Button | "Check for Updates", or "Install Update…" once a version is known; disabled when Sparkle cannot check | |
+| Update | Toggles | "Automatically check for updates"; "Automatically download and install updates" (disabled unless Sparkle allows automatic updates) | Sparkle |
+
+Sources: `NoodleSettingsView.swift:109-212`, `ConversationRuntimeSettings.swift:14-37`, `Sources/NoodleCore/AgentSessionRollover.swift:8-46`, `Sources/Noodle/AppUpdater.swift:76-103`, `Shared/SettingsUI/.../UpdateSettingsButton.swift:16-22`. Pickers that hold a value outside their option list add it (`ConversationRuntimeSettings.swift:40-42`), so a stored custom value never renders blank. `docs/usage.md:209-210` mentions a "link-preview timeout" in Conversation settings that does not exist in this code.
+
+### 2.4 Harness tab
+
+Layout (`HarnessSettingsView.swift:21-75`): one grouped section listing every provider in `HarnessProvider.allCases` order, which is Codex, Claude Code, Muse Code, Grok Build, FX, OpenCode, Antigravity, Apple Intelligence ("the four the welcome offers, then the rest, experimental last", `Sources/NoodleCore/Harnesses.swift:3-12`). A second section with the toggle "Update harnesses installed by Noodle automatically" appears only when at least one displayed harness was installed by Noodle (default on, key `Noodle.harness.automaticUpdates`). The footer has the delayed spinner (accessibility label "Checking for harnesses") and "Check Again", which forces a fresh latest-version lookup and is disabled while any refresh runs. The tab refreshes on appear and on app activation, and cancels every in-flight install or sign-in on disappear (`:62-74`).
+
+Per-harness facts:
+
+| Harness | Icon | Install command | Update command | Sign-in in Noodle |
+|---|---|---|---|---|
+| Codex | `CodexHarness` | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | same as install | Sign In (device code challenge) |
+| Claude Code | `ClaudeHarness` | `curl -fsSL https://claude.ai/install.sh \| bash` | `claude update` | Sign In (opens browser) |
+| Muse Code | `MuseHarness` | `curl -fsSL https://dev.meta.ai/install.sh \| bash` | same as install | Sign In |
+| Grok Build | `GrokHarness` | `curl -fsSL https://x.ai/cli/install.sh \| bash` | `grok update` | Sign In |
+| FX | `FxHarness` | `curl -fsSL https://fx.sh/setup.sh \| bash` | `fx upgrade` | Sign In |
+| OpenCode | `OpenCodeHarness` | `curl -fsSL https://opencode.ai/v2/install \| bash` | same as install | Terminal command `opencode auth login` |
+| Antigravity | `AntigravityHarness` | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` | `agy update` | Terminal command `agy` |
+| Apple Intelligence | `apple.logo` (SF Symbol) | bundled, no install | reinstall Noodle | not required |
+
+Icons are monochrome template SVGs in `Support/Assets.xcassets` (`HarnessProviderIcon.swift:8-34`; the website ships the same marks as `website/assets/harness-*.svg`). Install commands and instructions come from each provider's `installationGuide` (for example `Sources/NoodleRuntime/ClaudeCodeSetupProvider.swift:10-13`: "Run Anthropic's official installer in Terminal, then return here and check the installation. Claude Code opens your browser when you sign in."); update commands from `HarnessVersionPolicy.updateGuide` (`Sources/NoodleCore/HarnessVersions.swift:168-202`). Terminal sign-in is used by providers that implement `terminalSignIn` (`OpenCodeSetupProvider.swift:20`, `AntigravitySetupProvider.swift:18`); for a copy Noodle installed, the command names the executable by its full quoted path because it is not on the shell's PATH.
+
+Status derivation (`HarnessSettingsView.swift:441-469`). The first matching rule wins for the title; icon and colour use their own slightly different order.
+
+| Priority | Condition | Title | Icon | Colour |
+|---|---|---|---|---|
+| 1 | an install or sign-in is in progress (`activity`) | Setting up | (rules 2-9) | (rules 2-9) |
+| 2 | a setup error, or a bot on this harness failed | Needs attention | `exclamationmark.triangle` | orange |
+| 3 | a bot on this harness is reconnecting | Reconnecting | `arrow.trianglehead.2.clockwise` | orange |
+| 4 | never checked (no snapshot) | Checking… | `ellipsis.circle` | secondary |
+| 5 | not installed | Not installed | `arrow.down.circle` | secondary |
+| 6 | authenticated | Signed in | `checkmark.circle.fill` | green |
+| 7 | unauthenticated | Sign-in required | `person.crop.circle.badge.questionmark` | secondary |
+| 8 | sign-in not required | Ready | `checkmark.circle.fill` | green |
+| 9 | managed externally (status unreadable) | Sign-in status unknown | `person.crop.circle.badge.questionmark` | secondary |
+| 10 | no sign-in result yet | Checking sign-in… while checking, else Installed | `person.crop.circle.badge.questionmark` | secondary |
+
+When any bot on the harness can be kicked, the status label becomes a plain button (help "Show affected bots") opening a 340 pt popover anchored at the bottom edge (`:245-305`). Each affected bot shows its name in semibold, then either an orange caption "Reconnecting… · 3m 12s" ticking every second, or the runtime's detail text (secondary, selectable), then small "Kick" and "New Session" buttons, rows separated by dividers, `padding(16)`, scrolling past the same 360 pt cap. "Kick" opens the recovery alert (titles such as "Recover <bot>?", "Usage limit reached", "Sign in to reconnect <bot>", "Retry recovery?", "Safeguards stopped <bot>"; confirm buttons "Recover Bot", "Resume" or "Retry Now"; an extra "Open Harness Settings" for authentication failures; `Sources/NoodleRuntime/AgentRuntimeCoordinator.swift:61-94`). "New Session" confirms with "Start a new session for <bot>?" and "<bot> will start with a fresh context. Its workspace, memory and messages are kept." (`ConversationRuntimeSettings.swift:55-66`).
+
+Detail lines below the title, in order (`HarnessSettingsView.swift:154-237`):
+
+1. Not installed: "Checking the installation…" (never checked), "Missing from this copy of Noodle. Reinstall Noodle." (Apple), otherwise "Install the native harness to use it with Noodle."
+2. Setup error in red caption, selectable, wrapping.
+3. Version line when installed: location ("Local" for Apple, "Installed by Noodle" for a managed copy, otherwise the executable path, one line, middle-truncated, selectable), "·", the installed version or "Version not checked yet", then either an orange `Label("Update required", systemImage: "exclamationmark.triangle.fill")` or orange "Update available — 2.1.280". A compatibility issue adds an orange paragraph ("This <harness> installation is missing required support for <options>. Update the harness, then choose Check Again.", `HarnessVersions.swift:101`); a failed version check shows "Could not inspect the harness version. Try Check Again." in orange (`HarnessSetupController.swift:111`).
+4. "Could not determine the saved sign-in status." when sign-in is needed but the status is managed externally.
+5. One action line (link buttons, spacing 12, all optional): "Profiles" (installed and the provider supports profiles), "Update" (managed copy with an update; disabled during activity) or "Update Instructions" (user's own copy), "Remove" (managed copy), "Local Models" and "Remote Models" (Apple), "Sign In" (signed out or unknown, nothing else running; disabled while this harness's own check runs or its live installation is missing, never by other harnesses' checks).
+6. Terminal sign-in block when requested: caption "Run this command in Terminal and complete sign-in, then choose Check Again.", the command block, then links "Open Terminal" and "Check Again" (`:473-497`).
+7. Update guide when "Update Instructions" was toggled: the provider's update instructions ("Run this command in Terminal, then choose Check Again. Updates follow the provider's configured release channel; managed or pinned installs may intentionally remain on an older version. Existing bot processes keep their running version until restarted."), the command block, "Open Terminal", "Official Update Guide" (`:421-439`).
+8. Activity line: a determinate `ProgressView(value:)` 120 pt wide when a download fraction is known, else a small spinner, the activity caption, a spacer and a "Cancel" link (`:185-197`). Activity strings: "Downloading…", "Verifying…", "Unpacking…", "Installing…", "Starting sign-in…", "Waiting for sign-in…" (`HarnessSetupController.swift:184,191,250-262`).
+9. Sign-in challenge (device code), or, when idle and not installed, the install section.
+
+Install section states (`HarnessSettingsView.swift:200-237`): when Noodle can install the harness (every provider except Apple, `Sources/NoodleCore/ManagedHarnesses.swift:177-180,256-267`), links "Install" and "Install Manually…"; otherwise a single "Install…". "Install Manually…" or "Install…" expands the guide in place: instructions caption, the command block, then "Open Terminal", "Installation Guide" (a `Link` to the vendor docs) and "Check Installation". After checking, if still missing: "Not detected yet. Finish the installer in Terminal, then check again." If Terminal cannot be found: "Open your preferred terminal and paste the command."; if it fails to open: "Could not open Terminal. Open it manually and paste the command." (`:503-513`).
+
+Command block (`:499-542`): `HStack(alignment: .firstTextBaseline, spacing: 10)` with a secondary `terminal` symbol, the command in `.callout` monospaced, selectable and wrapping, and an icon-only borderless "Copy Command" button (`doc.on.doc`, help "Copy command"); `padding(10)`, background `textBackgroundColor` at 50% opacity in a 6 pt rounded rectangle with a 1 pt border of primary at 10%.
+
+Sign-in challenge (`HarnessSignInChallengeView.swift:10-21`): the device code in monospaced body text (selectable), a "Copy Code" button and an "Open Sign-In Page" button on one line, then the caption "Enter this code on the sign-in page." The challenge arrives asynchronously from the provider's sign-in call; the row then reads "Waiting for sign-in…" until the provider returns a status.
+
+Install outcomes (`HarnessSetupController.swift:243-292`): the row stays busy until a refresh can show the result, so it never offers Install again prematurely. If the download succeeded but the harness is not found: "<harness> was downloaded, but Noodle cannot find the installed harness." If a new managed version fails the compatibility check while an older one exists, the new one is deleted, recorded as rejected and never fetched again: "<harness> <version> does not work with this version of Noodle. The previous version was kept." Managed copies are checked every six hours and auto-installed when the toggle is on (`docs/harness-setup.md:127-132`); the user's own installation always wins over Noodle's copy.
+
+"Remove" (managed copies only) opens a confirmation dialog "Remove <harness>?" with a destructive "Remove" and the message "Bots that use <harness> stop working until it is installed again. Your sign-in is kept."; before removal every bot on that harness is stopped (without revoking access) so none loses its tools mid-turn (`HarnessSettingsView.swift:384-398`).
+
+"Experimental" (Apple only) is an orange caption-sized plain button beside the name, help "Why is this harness experimental?", opening the 360 pt popover: headline "Experimental", text "Apple's on-device model can respond slowly, miss details from earlier messages, or fail to complete tool tasks. This harness is still being tested." (`:133-149`).
+
+Instant paint: `HarnessPresentationCache` stores the last confirmed installation, sign-in and version report per harness in user defaults (key `Noodle.harnessPresentation.v1`) and seeds the controller at launch, so the tab opens with real statuses before any probe runs. It is explicitly display-only: "Never use this cache to launch a harness or authorize access. It contains no credentials, account details or sign-in codes." (`Sources/NoodleCore/HarnessPresentationCache.swift:3-34`). A failed discovery check sets an error but does not erase the installation or sign-in ("A failed check is not proof of uninstallation or sign-out", `HarnessSetupController.swift:133-137`).
+
+### 2.5 Harness profiles sheet
+
+Opened by "Profiles" (`HarnessProfilesView.swift`, width 480, `noodleSheetSizing(animated: true)`). Title "<Harness> Profiles". Empty state "No profiles" in secondary, at least 60 pt tall. Otherwise the rows sit in one container with dividers: background secondary at 7.5% opacity in a 12 pt continuous rounded rectangle with a secondary 11% border (`:32-43`). Row (`:85-126`), padded 12 horizontal and 10 vertical: `person.crop.circle` at `.title3` secondary; the name at `.fontWeight(.medium)` above its status; then "Cancel" while an operation runs, or "Sign In…" when not signed in; then the actions menu ("Sign In Again…" when signed in, because "A login can be revoked on the server while still reading as signed in here", "Rename…", destructive "Delete"). Under the row: the device-code challenge, a Terminal sign-in block (Antigravity and OpenCode profiles), or a red error. Status: a mini spinner plus "Starting sign-in…" or "Waiting for sign-in…" during activity; otherwise "Signed in" or "Ready" (green), "Sign-in required" (secondary), or plain caption "Checking sign-in…" / "Sign-in status unknown". Footer: "Add Profile…" leading, "Done" trailing. The name alert is "New Profile" or "Rename Profile" with a "Profile name" field and "Cancel"/"Save", Save disabled while the name is invalid ("Enter a name.", "Names must be a single line. Put longer text in Description or Backstory.", "Keep names to 100 characters or fewer."). Deleting confirms "Delete Profile?" with "“<name>” is signed out of Noodle. Bots using it return to the system profile and restart." In code every provider except Apple supports profiles (`Harnesses.swift:28`), while `docs/harness-setup.md:62,83` says FX and OpenCode use the System sign-in only.
+
+### 2.6 Models: Apple local and remote
+
+There is no global model list; models are chosen per bot in the bot editor. The Settings surfaces are the two Apple sheets on the Apple Intelligence row.
+
+Local Models (`AppleLocalModelsView.swift`, width 480): title "Local Models"; a scroll area whose height tracks its content up to 520 pt (`:61-72`), then an optional red error label, then the footer "Import Model…" and "Done". While a download or import runs, "Done" is disabled and interactive dismissal is blocked (`:84-93`). States: a small spinner with "Checking local model support…" or "Importing model files…"; unsupported "Requires macOS 27 and a Noodle build with local model support."; otherwise an "Installed" headline section and an "Available" headline section, each model a card padded 12 on `quaternary` at 40% opacity in a 10 pt rounded rectangle (`:159-160`). A card shows the name (medium weight, two lines), a "Recommended" capsule for the best fit for the Mac's memory (caption2, tint-coloured text on tint at 12%, padding 6 x 2, help "The best fit for this Mac's memory."), the catalogue summary, and "4-bit · 4.5 GB" plus a "Details" link to Hugging Face (help "Model details and license on Hugging Face"); imported models show only name and size (`:202-232`). The trailing action is "Download", "Cancel" during a download, or a destructive "Remove" for installed models (help lists the bots using it). Download progress is a `ProgressView(value:)` with a monospaced-digit caption: "Preparing download…", "Downloading 1.20 GB of 4.50 GB…", "Verifying model files…", "Importing model files…", "Cancelling…" (`:234-245`). "Import Model…" opens a folder chooser titled "Import MLX Model" with prompt "Import". Removal confirms "Remove Model?" with "Noodle's copy of “<name>” will be deleted. You can download or import it again later."
+
+Removal guarded by usage: if any bot uses the model (or a remote account), "Remove" opens `ModelUsagePopover` instead of deleting (`:310-318,338-384`). The popover (340 wide, padding 16) has the headline "Model in Use" or "Model Unassigned" with a close `xmark`, the model name, then either "No bots use this model." and a destructive "Remove Model", or "Choose another model for these bots before removing it." and a list of rows (28 pt avatar, name, "Edit…", each at least 44 pt tall; list height `min(240, count * 44)`). "Edit…" opens that bot's runtime editor as a sheet, and when the editor closes the popover reopens on the same model (`returnToModelID`, `:95-101`).
+
+Remote Models (`AppleRemoteModelsView.swift`, width 480): title "Remote Models"; states "Checking model support…", "Requires macOS 27 and a Noodle build with custom model support.", "No accounts", or account cards (same card style). An account card shows the account name (medium weight) and its base URL or provider name (caption, middle-truncated); its actions menu offers "Add Model…" for custom servers that need models described, or a "Models" submenu of toggles (a model in use cannot be turned off), then "Refresh Models" for providers that list models (Ollama), "Rename…", "Change API Key…", a divider and destructive "Remove" (`:149-230`). Below a divider, enabled models list name and summary, with help "Used by A, B."; custom models get their own menu ("Edit…", "Remove", the latter disabled while in use). Footer: an "Add Account" menu with one item per provider ("OpenAI…", "OpenRouter…", "Vercel AI Gateway…", "Ollama…", "Custom…" per `docs/harness-setup.md:211-218`), disabled until support is confirmed, and "Done".
+
+The account form (width 380, padding 20): title "Add <Provider> Account", "Rename Account" or "Change API Key"; columns-style form with "Name" (prompt "Personal"), "Address" (custom provider only, prompt the provider's default URL), and a secure "API Key" field (prompt "Optional" when the key is not required); a red error label; a footer spinner, "Cancel" and "Add"/"Save" (`:337-429`). Submit validates the key with the provider before saving, and for providers that list models fetches them, failing with "<Provider> has no models that can use tools. Download one, then try again." Account removal confirms "Remove Account?" with "“<name>” and its API key will be removed from Noodle."
+
+The model form for custom servers (width 460): "Add Model" or "Edit Model"; "Model ID" (prompt "llama-3.3-70b", with a chevron menu "Models on the server" listing ids the server reports that are not yet added); "Name" (prompt the id or "Llama 3.3 70B"); "Context" and "Maximum Output" number fields 110 pt wide followed by "tokens"; "Input" with a switch "Images"; "Reasoning" as a two-row grid of switches None, Low, Medium / High, Extra High, Max; and "Default Reasoning" once any is chosen, which falls back to Medium when available, else the first chosen (`:456-577`).
+
+### 2.7 Usage window
+
+Opened from the app menu item "Usage" (`chart.bar`, ⇧⌘U) placed between Settings and Services, from "Show Usage" in a direct conversation's sidebar menu, and from "Usage" on a bot's profile; the latter two pre-filter to that bot (`UsageWindow.swift:5-19`, `SidebarView.swift:110-113`). The window is a single `Window("Usage")` with default size 860 x 680, content minimum 840 x 560 (`NoodleApp.swift:180-185`, `UsageView.swift:172`). The subtitle shows the period, for example day-month-year for 7 and 30 days, month-year for 12 months (`:218-225`).
+
+Toolbar (`:177-216`): centred segmented "Period" with "7 Days", "30 Days" (default), "12 Months"; trailing a "Bot" menu ("All Bots", divider, every bot), a fixed spacer, a "Group By" menu ("By Bot" default, "By Harness", "By Model"), a fixed spacer, and a segmented "Measure" with "Tokens" (default) and "Cost".
+
+What is measured (`Sources/NoodleCore/UsageLedger.swift`): an append-only SQLite ledger of samples per bot, harness, model and session with input, output, cache-read, cache-write and reasoning tokens and an optional USD cost. Reasoning is part of output and not added to the total; input excludes cached tokens (`:4-27`). Days are local calendar days, the newest name of a bot labels its whole history so renames do not split it, and history outlives deleted bots (`:133-145`). Per `docs/usage.md:97-99`, Claude Code, Codex, Grok Build, FX and OpenCode report tokens; only Claude Code reports cost; Muse, Antigravity and Apple Intelligence are not counted.
+
+Layout, top to bottom (`UsageView.swift:149-171`):
+
+1. Summary strip (`:227-256`): six stats separated by 36 pt tall dividers, `padding(.vertical, 12)`, background `quaternary` at 50% in a 12 pt rounded rectangle, outer padding 20 on the sides and top. Each stat: title `.subheadline` secondary, value `.title2.weight(.semibold)` with monospaced digits, one line, minimum scale 0.6, 16 pt horizontal padding. Stats: "Tokens"; "Cost" ("—" when no harness reported cost; help "Only harnesses that report cost are included."); "Cache Hits" (percent, no decimals; help "Share of input tokens read from the cache."); "Input" (input plus cache writes; help "Input tokens not read from the cache."); "Output"; "Daily Average" (the period's value divided by its day count, so per day even for 12 months).
+2. Stacked bar chart (`:258-286`), minimum 200 pt, padded 20: one bar per day (month for 12 months), stacked by group, legend top-leading, y grid lines in `quaternary`, y labels in the measure's format. Hovering selects a bucket: other buckets dim to 40% opacity and a tooltip appears above the bar (fitted inside the chart horizontally), on `.regularMaterial` in an 8 pt rounded rectangle, padding 8, at least 160 wide: the date in semibold caption ("Tue 7 Oct" style, or "October 2026" for months), then rows sorted by value with an 8 pt colour dot, the group name and the value (`:288-305`).
+3. Divider, then the breakdown table (`:307-339`), at least 140 tall, inset style with alternating row backgrounds and monospaced digits. Columns: the grouping name (Bot, Harness or Model; minimum 140, ideal 200, with the 8 pt colour dot), then right-aligned numeric columns "Tokens", "Input", "Output", "Cached", "Cost" and "Share" (minimum 64, ideal 88 each).
+
+Empty period: `ContentUnavailableView("No Usage", systemImage: "chart.bar.xaxis")` with "No tokens were used in this period." (`:156-158`).
+
+Report rules (`UsageReport`, `:7-120`): ranges are today minus 6 days to tomorrow, today minus 29 days to tomorrow, and the first of the month 11 months back to tomorrow. Repeated bot names are told apart by id as "Name (2)". An empty model name groups as "Default Model". Rows sort by value descending, then name. Only the seven largest groups get hues; the rest fold into "Other" in the chart (gray) but remain individual rows in the table. Hues are assigned to those seven in name order, not rank order, "so a new period or measure does not repaint a group just because its rank changed" (`:91-94`). The seven categorical colours, "stepped for the dark surface", are `#3987e5`, `#d95926`, `#199e70`, `#c98500`, `#d55181`, `#008300`, `#9085e9` (`:133-134`). Token counts use compact notation with one to three significant digits (for example "1.24M"); cost uses USD with three decimals when strictly between 0 and 1, otherwise two (`:350-356`). Cache hit rate is cache reads over input plus cache reads plus cache writes. The view re-reads on every ledger revision, so it updates live while bots run (`:150`).
+
+### 2.8 Agent Activity window
+
+One floating log window per bot, opened by "Show Activity" in the sidebar menu of a direct conversation and in the context menu of a bot's avatar, both beside its messages and in the conversation header, only for bots that run on this Mac (`SidebarView.swift:107-109`, `Components.swift:266,271`, `ChatView.swift:581`, `NoodleStore.swift:801`). Re-opening brings the existing window forward; its title follows renames and it closes when the bot is deleted (`AgentActivityWindow.swift:7-39`). Opening always scrolls to the latest output.
+
+Window (`:50-100,155-168`): an `NSPanel` 760 x 500, minimum 440 x 260, floating, not hidden when the app deactivates, transparent and shadowed, title hidden, traffic-light buttons hidden (the frame draws its own close button), full-screen auxiliary. It cannot become main, ignores zoom, minimise and full screen, and closes on Escape or ⌘W.
+
+Frame (`AnnotationPreviewFrame`, `:303-363`, shared with attachment previews): a dark HUD material (`.hudWindow`, behind-window blending, forced dark appearance), corner radius 18, 1 pt white border at 22% opacity. A 36 pt header holds an 18 x 18 `xmark.circle.fill` close button 10 pt from the leading edge (tooltip "Close Activity (Esc or ⌘W)"), the title "<Bot> - Activity" in 13 pt semibold, middle-truncated, 8 pt after the button, and an empty kind label 14 pt from the trailing edge. Dragging the header moves the window. The content sits in an inset with 5 pt margins (none at the top) and a 13 pt corner radius.
+
+Log view (`:173-288`): a native read-only selectable `NSTextView` (Find bar enabled) in 12 pt monospaced regular, label colour on text-background colour, 12 pt insets, autohiding vertical scroller. Empty state "No activity yet" in 13 pt secondary, centred. Each entry renders as `[<time with seconds, in the user's locale format>] Title` on one line, then its detail lines (`Sources/NoodleRuntime/AgentActivityLog.swift:26-30`). Titles come from parsing harness events: "Output", "Reasoning summary", "Tool output", "Tool result", "Tool failed", "Plan", "Running command" / "Command completed", "Changing files" / "Files changed", "Searching" / "Search completed", "<tool>: started|completed|failed", "Working" (Apple), and runtime lifecycle details such as the bot's status text (`AgentActivityParser.swift:22-175`). Streamed events with the same stream id update one entry in place (appending deltas), and every lifecycle change ends coalescing so a new turn starts new entries (`AgentActivityLog.swift:50-82`). Limits: 500 entries and 256 KB per bot, titles 256 bytes, details 16 KB, older output trimmed with a leading "…" line and terminal control characters stripped (`:45-48,93-100`). Logs persist while Noodle runs, even with the window closed, and are cleared on quit.
+
+Live updating: a 0.2 s timer redraws only when the log's revision changed and only while the window is visible, so rendering is batched independently of token rate (`AgentActivityWindow.swift:92-99,110-116`). Updates are incremental: trimmed entries are deleted from the top while the scroll offset is shifted up by their laid-out height, unchanged leading entries are kept, only the changed suffix is replaced, and the selection is preserved (`:254-287`). Auto-follow is on only when the view is within 4 pt of the bottom and nothing is selected; scrolling up or selecting text pauses it (`:246-247`). A 34 pt circular glass button with `arrow.down` (13 pt semibold, tooltip "Follow Latest") floats centred 16 pt above the bottom while the newest output is out of view, fading in over 0.15 s (`:199-242`). The context menu, available anywhere in the log area, has "Copy" (enabled with a selection), "Copy All", "Select All", a separator, "Follow Latest" (enabled when not following) and "Clear" (`:118-136`).
+
+### 2.9 Tools tab, catalog, editor and assignment
+
+Tools tab (`MCPSettingsView.swift:10-104`): a single rounded list (background `quaternary` at 25% in a 12 pt rounded rectangle, padding 20) whose height tracks its content up to 430 pt, then the footer button `Label("Add Tools…", systemImage: "plus")` (help "Add a service or another account"). Empty state: `Label("No connections", systemImage: "puzzlepiece.extension")` in secondary, at least 80 pt tall. A connection row (`padding(14)`, dividers inset 58 pt from the leading edge) shows a 32 pt icon (the service's own icon fetched at sign-in, else its catalogue icon, else `puzzlepiece.extension.fill`, clipped to a rounded rectangle with radius 22% of the size), the name in `.headline` with an orange "Experimental" capsule for experimental catalogue entries, the status, the endpoint URL (caption, one line), an optional description (caption, two lines), a red error, and links "Connect" or "Reconnect", "Edit…" and "Remove". While signing in, the status shows the current stage text and the row adds a mini spinner and a small "Cancel" button. Stages: "Signing in…" (initial), "Waiting for existing requests…", "Checking saved sign-in…", "Discovering authorization…", "Checking authorization server…", "Registering this connection…", "Complete sign-in in your browser…", "Checking available tools…" (`Sources/NoodleMCP/MCPService.swift:74-103`, `MCPOAuth.swift:90-141`, `MCPController.swift:163`). Otherwise the status is "Needs attention", "Connected" or "Sign-in required".
+
+Removal confirms with a dialog titled "Remove Tool Connection?", button "Remove Connection" and the message "This removes this connection from all bots and deletes its saved sign-in from Noodle. Other connections to the same service are unchanged. To revoke the provider's grant too, use its account settings." (`:77-86`). Errors surface inline per row, and registry-level problems in an alert titled "Tools", for example "Could not read saved tool connections. They have not been replaced." (`MCPController.swift:42`). Sign-in errors are mapped to plain sentences, for example "Reconnect this connection in Settings → Tools.", "The service rejected this sign-in (HTTP 401). Connect again to renew access.", "The MCP request timed out. A remote action may have completed; verify before retrying.", "Sign-in cancelled." (`Sources/NoodleMCP/MCPCredentials.swift:73-86`, `MCPController.swift:172`).
+
+Catalog sheet "New Tool" (`ToolCatalogView.swift:13-62`, width 480): a header with "Cancel", the centred headline "New Tool", and an invisible "Cancel" copy to balance it; a "Search tools" field matching every term against name, summary, kind and badge; the caption "Choose a service to add it and sign in. You can customize it afterward."; a 310 pt scroll list of 94 presets (90 stable, then 4 experimental Google Workspace services, each group alphabetical; `Sources/NoodleCore/ToolCatalog.swift:62-361`). A preset row (padding 9, whole row clickable, help "Add <name> and sign in") shows a 32 pt icon (bundled `.icon` file, else the first letter on `quaternary`), the name, a one-line summary, the maturity badge, the kind "MCP" in caption2, and a blue `plus.circle.fill`. No match: "No matching tools. You can add a custom MCP below." Footer: "Custom MCP…" and the caption "Connect your own MCP server". Choosing a preset saves a new, separately named account immediately ("Notion", then "Notion 2", …), closes the sheet and starts the browser sign-in 250 ms later so the authorization page is presented after the sheet is gone (`:129-155`). A retry of the same preset reuses the same connection id, so a partly failed add resumes rather than duplicating.
+
+MCP editor (`MCPSettingsView.swift:111-246`, width 480): a header with "Cancel" (or "Back" from the catalog), the headline "Custom MCP" or "Edit MCP", and "Add & Connect" or "Save" (disabled until name and URL are filled). Fields with caption semibold labels: "Name" (placeholder "e.g. Notion — Work", help "Use a distinct name for each account"), "MCP Server URL" (placeholder "https://…", read-only when editing), "Description" (placeholder "Optional", two to three lines, truncated to 1,000 characters), "Instructions" (a 13 pt text editor 130 pt tall on secondary at 10% in an 8 pt rounded rectangle with an 18% border, help "Optional guidance for bots using this connection. Do not include passwords or tokens.", truncated to 20,000 characters). Captions: "MCP connection · Sign-in opens in your browser." and, when editing, "Changes apply to every bot using this connection." Invalid URL: "Enter a valid HTTPS server URL." Catalogue presets prefill instructions with a service-specific paragraph that always ends "Use only tools actually offered by this connection and only within the user's request and granted permissions."
+
+Browser OAuth (`MCPController.swift:216-282`): an ordinary default-browser tab; only a callback matching the pending redirect's scheme, host, port and path and the single `state` value is accepted; a 180 s timeout; "Could not open your browser. Check your default browser and try again." on failure; on success the Settings window that started the sign-in is brought back to the front.
+
+Assignment to bots happens in the bot editor's Tools tab (`Sources/Noodle/MCPAssignmentPicker.swift:37-169`): a headline "Tools" with an "Add Tools…" button that opens a 330 x 260 popover containing a "Search connections" field, built-in "Calendar" and "Reminders" entries ("Calendars on this Mac, chosen per bot"), saved connections not yet assigned (icon 28, name, badge, one-line description, blue plus), "No saved connections. Choose New Tool to add one." when there are none, and "New Tool…" (which waits for the popover to close and then opens the catalog sheet). With nothing assigned, a large button fills the list area: `puzzlepiece.extension` at `.largeTitle` over "Add tools to this bot", at least 220 pt tall (room for five 44 pt rows) on `quaternary` at 25% in a 10 pt rounded rectangle. Assigned rows (padding 8) show a 26 pt icon, the name, the badge, a `pencil` edit button and a `minus.circle.fill` remove button, which confirms "Remove “<name>”?" with "Remove Tool" and "This bot loses access to it when you save. The tool connection itself is not deleted." The list keeps a fixed 220 pt height so the sheet does not jump. Assignments apply on save.
+
+Native tool extensions: tools can also come from installed app extensions at the extension point `<bundle id>.tool` (`ToolExtensionDiscovery.swift:6-71`); these register automatically and have no settings UI.
+
+### 2.10 Keybindings editor
+
+Three grouped sections (`KeybindingsSettingsView.swift:11-32`): "Conversations" (New Bot ⌘N, New Group ⇧⌘N, Search Conversations ⌘F, Capture ⇧⌘S, Record / Stop Voice Message ⇧⌘D, Call / End Call ⇧⌘C), "Any App" (Choose Conversation ⌃⌥Space), and "Annotations" (Add Annotation ⇧⌘A, Annotate Region ⇧⌘R, Save Annotation Comment ⌘↩) with the footer "Select conversation text to add an annotation, or annotate a region of the Noodle window. The same shortcuts work in attachment previews. Escape cancels an annotation." The Usage shortcut (⇧⌘U) is defined (`Sources/NoodleCore/KeyboardShortcuts.swift:75,105`) but has no row, so it cannot be changed here.
+
+Row (`:55-83`): an `HStack(alignment: .center, spacing: 14)` with the command title, its one-line summary in caption secondary (for example "Create a bot.", "From any app, pick a bot or group to float over your work."), and any error in red caption; then a 20 pt slot holding a borderless `arrow.counterclockwise` reset button only when the binding differs from the default (help "Reset to ⌘N"), so recorders stay aligned; then the recorder, a rounded-bezel button 112 x 28 in 12 pt medium monospaced text showing the binding, "Not set" when cleared, or "Press keys…" while recording. Its tooltip is "Click to record a shortcut; right-click to reset or clear it."; its context menu has "Reset to <default>" and "Clear Shortcut".
+
+Footer: a caption hint, "Use ⌘, ⌃ or ⌥ with a key." normally and "Press a shortcut. Escape cancels; Delete clears." while recording, then "Restore Defaults" (disabled when nothing is changed and nothing is recording).
+
+Recording rules (`:130-190`): only one recorder at a time; a local key monitor consumes events before menus can fire; recording stops when the Settings window resigns key, on a click outside the button, or on right-click. Key-up and repeats are swallowed; Escape cancels; Tab without modifiers stops recording and passes through; Delete or Forward Delete without modifiers clears the binding; anything else is validated and saved. Validation (`KeyboardShortcuts.swift:33-56,133-157`): a single key with at least one of ⌘, ⌃ or ⌥ (Shift alone is not enough) or the error "Choose a key with Command (⌘), Control (⌃) or Option (⌥)."; reserved system shortcuts (⌘Q, ⌘W, ⌘H, ⌘M, ⌘,, ⌘C, ⌘X, ⌘V, ⌘Z, ⌘A, ⌘O, ⌘Tab, ⌘Space, ⌘1-9, ⇧⌘Z, ⇧⌘3-6, ⌥⌘H, ⌃⌘Q, ⌃Space) give "That shortcut is used by <action>."; a duplicate gives "Already assigned to <command>. Change or clear that shortcut first." Only overrides are stored (key `Noodle.keyboardShortcuts.v1`): a missing override means the default, an explicit null means disabled, and a stored set with any invalid or duplicate binding is ignored wholesale. Display order of modifiers is ⌃⌥⇧⌘, with names such as ↩, ⇥, Space, Esc, ⌫, arrows and F-keys (`:19-31`).
+
+### 2.11 Permissions and access modes
+
+The Permissions tab covers macOS privacy permissions, not bot access (`PermissionsSettingsView.swift`). Three rows in the icon-row style:
+
+| Permission | Symbol | Summary | Request path |
+|---|---|---|---|
+| Microphone | `mic` | "Record voice messages." | system prompt |
+| Screen Recording | `rectangle.dashed.badge.record` | "Preview and capture screens and windows for a message." | system prompt |
+| Notifications | `bell.badge` | "Announce bot replies and show the unread count on the Dock icon." | system prompt |
+
+The trailing action is "Request" (shown as "Requesting…" and disabled for all rows while any request runs; accessibility "Request <name> access") for not requested, or "Open System Settings" for refused (help "Turn on Noodle under <name>", or for Screen Recording "Turn on Noodle under Screen Recording. macOS may ask to reopen Noodle."), each deep-linking to its pane (`:237-260,40-51`). macOS reports Screen Recording only as allowed or not, so Noodle remembers that it asked to tell a refusal from a never-asked state (`:62-76`). Statuses are refreshed on appear and whenever Noodle becomes active. A "Hub Noodlets" section lists noodlets granted device permissions (title plus "Camera, Microphone, …" in caption) with a "Remove" link each (`:166-184`).
+
+Bot access modes (restricted versus unrestricted) live in the Bots tab, analysed separately; the relevant UX for this document is: every bot starts restricted; turning on "Unrestricted" or "Apps" for a bot asks first ("Allow Unrestricted Access for <bot>?" with "<bot> will be able to read and change files and use services beyond its private workspace, with the access available to your Mac account. This restarts the bot." and the button "Allow Unrestricted Access"), while turning either off applies at once (`BotsSettingsView.swift:92-96,262-281`, `docs/security.md:8-12`). Each bot row's status word "restricted" (secondary) or "unrestricted" (orange) is an explain-on-click button; while access changes it reads "Restarting runtime…". The explanations: restricted, "This bot runs in a macOS filesystem sandbox. It can work in its private workspace, the folders added in Edit Bot, and allowed harness storage, while unrelated personal files are blocked. Assigned tools and computers use their own permissions."; unrestricted, "This bot can read and change files and use services beyond its private workspace, with the access available to your Mac account. macOS and tool permissions still apply. Noodle approves supported tool requests automatically." plus "Off by default. Changing this restarts the bot. Turning it off restores Restricted mode; it does not undo completed actions or revoke macOS permissions." (`BotsSettingsView.swift:284-334`). Noodle never shows approval forms in chat; it approves tool requests automatically within the bot's access (`docs/security.md:88-92`).
+
+### 2.12 Companions tab
+
+Rows for Noodle Computer, Noodle Applet and Noodle Browser (in that order), then Noodle Mobile, then the footer "Check Again" (`CompanionAppsSettingsView.swift:22-58`).
+
+| App | Symbol | Summary | Requirements |
+|---|---|---|---|
+| Computer | `desktopcomputer` | "Give your bots Linux desktops and terminals to run tools and work on files." | "Requires Apple silicon and macOS 26 or later." |
+| Applet | `square.grid.2x2` | "Create and enjoy little tools, websites, games, and native experiments." | "Requires macOS 15 or later." |
+| Browser | `globe` | "Give your bots persistent browsers for websites, signed-in accounts, and file transfers." | "Requires macOS 26 or later." |
+| Mobile | `iphone` | "Chat with the agents on your Noodle Hub from iPhone and iPad." | "Requires iOS 26 or later." |
+
+Each desktop companion shows "Installed" (green) or "Not installed" (secondary); the detail line shows "Version 1.4" (or "Version unavailable") and, when behind, "Update available — 1.5" in orange, or the requirements when not installed; the trailing link reads "Install" (opens the latest release DMG, or the project page for development builds), "Update" (opens the companion with its update-check URL so the companion's own Sparkle installs it), "Open" (opens its library), or "Opening…" while busy (`CompanionApp.swift:22-44,62-89`, `CompanionAppsSettingsView.swift:60-110,147-169`). Mobile has a "Join Beta" link to TestFlight (`:112-138`). Failures show an alert titled with the app name, with "View Project" when not installed, and "OK". Update detection reads each installed companion's own appcast: HTTPS only (redirects to non-HTTPS refused), 8 s request and 10 s resource timeouts, 1 MiB cap, cached for six hours unless "Check Again" forces it, skipped for builds with updates off, and an unreachable feed keeps the last known release (`CompanionUpdateChecker.swift:49-89`). Companion apps themselves offer "Show in Dock" (help "Show the app in the Dock and app switcher.") and "Show in Menu Bar" in their own settings; if both are off a gear toolbar button "App Settings" keeps settings reachable (`Shared/SettingsUI/.../CompanionAppVisibility.swift:88-180`).
+
+### 2.13 Hub tab, pairing, invitations and devices
+
+The Hub tab has two sections, "This Mac" and "Noodle Hubs" (`HubSettingsView.swift:10-20`).
+
+This Mac (`:23-75`): a switch whose label is "Let My Devices Reach This Mac" with the secondary line "Your phone and other Macs talk to the bots here as they would a Noodle Hub's. The Mac stays awake while this is on." Turning it on starts a personal Hub and an idle-sleep assertion with the reason "Your devices can reach this Mac" (`ThisMacHub.swift:53-80`). When on, the shared `HubLinkRows` follow (`HubLinkRows.swift:24-111`):
+
+- The status label: "Reachable only on this network" or "Reachable from anywhere through Tailscale, the internet and your address" (whichever routes exist) in green, orange when the router mapping failed and nothing else reaches the Mac, the failure reason in orange, or "Starting…" (`Sources/HubCore/HubReachability.swift:24-35`).
+- "Name": a trailing-aligned field whose placeholder is the Mac's name, a clear button (help "Use this Mac's name") when customised, the secondary label line "Press Return to save" while edited, saving on Return or focus loss; help "What paired devices call this Hub".
+- "Open Port on Router" switch with a status line ("Asking the router…", "Open at <host>", or the failure in orange); help "Asks the router, through UPnP or NAT-PMP, to forward the port so devices reach it away from home".
+- "Largest File" picker of byte sizes; help "The largest file a device can send to a conversation here".
+- "Addresses": a grid of endpoints in monospaced caption (selectable) with their network in tertiary caption ("home", "tailscale", "internet"); the manual address has a remove button; "Add Remote Address…" (right-aligned) opens an alert "Remote Address" with a field prompt "mac.example.com", the message "A domain, public address or forwarded port that reaches this Mac from outside your network." and Save disabled until it parses.
+- Device rows: `iphone` symbol (22 pt column), the device name, and "Connected", "Last seen 2 minutes ago" or "Joined yesterday" refreshed every 15 s, with a "Remove" button confirming "Remove <device>?" and "“<device>” can no longer reach this Mac until it joins again."
+- "Add Device…" (right-aligned, disabled while the link is stopped or starting) opens the invitation sheet titled "Add a Device".
+
+Noodle Hubs (`:78-225`): each joined Hub is an icon row with `server.rack` (24 pt in 32 x 32); the Hub's name in semibold and its status ("Connecting…", "Not connected" in orange, or "Connected" in green with help "Connected via <endpoint>"); "Noodle Hub · <user> · <plan> plan" in caption (selectable); "Hub key AB12 CD34 EF56 7890" in monospaced caption (the first 8 bytes of the key's SHA-256 as four groups of four hex characters, `Shared/HubLink/.../LinkIdentity.swift:97-101`); details, either the error in orange or "Your plan lends no harnesses" / "Lends Codex (Work), Claude Code"; and trailing links "Your Picture…", "Users" (admins only), "Archived (3)" (when any) and "Leave". Leave confirms "Leave <hub>?" with "Its bots stay on the Hub for your other devices. Joining again needs a new invitation." The last row invites joining: icon, "Noodle Hub" in semibold, "Use the harnesses a Noodle Hub lends you, such as a friend's or one of your own Macs." and a "Join" link (help "Join a Noodle Hub with an invitation").
+
+Join sheet (`:488-619`, width 460): title "Join Noodle Hub"; an "Invitation" field with the prompt "noodle://join-hub?…" that submits on Return; once the text parses, "Hub key …" appears below it so the user can compare keys before joining; buttons "Paste" (a copied link joins at once, a copied QR picture is decoded), "Choose Image…", and "Scan with Camera"/"Stop Camera"; the camera preview is 240 pt tall with 10 pt corners and joins on the first QR code seen; errors show as a red `exclamationmark.triangle` label ("The clipboard holds no invitation.", "The picture could not be read.", "The camera cannot read QR codes.", "This invitation has expired. Ask for a new one."). Dragging an image or file onto the sheet highlights it with a 3 pt accent-colour border inset 4 pt in a 12 pt rounded rectangle. Footer: a small spinner while joining, "Cancel" and "Join" (default; disabled while joining or empty). An invitation link opened from anywhere lands here pre-filled rather than joining silently (`docs/security.md:221-224`).
+
+Invitation sheet (`HubInvitationSheet.swift`, width 400): title "Invite <user>" (or "Add a Device"); a QR code of the invitation URL rendered at 200 x 200 with nearest-neighbour scaling on a white tile padded 10 with 10 pt corners (accessibility "Invitation QR Code"), generated with error-correction level M (`LinkInvitationImage.swift:30-36`); the URL in monospaced caption, one line, middle-truncated, selectable; "Hub key …"; "Copy Link" and a share button "Share…"; then a green "“<device>” joined" label once a device of that user pairs while the sheet is open, otherwise "Expires in 14 minutes" ticking every second, then "Expired" or a "New Invitation" button. Invitations last 15 minutes and use the `noodle://join-hub` URL (`LinkProtocol.swift:1583-1584`).
+
+Users sheet for Hub admins (`HubSettingsView.swift:315-485`, 460 x 420): header "Users on <hub>" and "Done"; rows with a 24 pt person badge (picture, or initials on a colour), the name, and "<plan>" or "<plan> · Admin"; non-admins get an "Invite" link and an actions menu with a "Plan" picker, a "Can Pair Devices" toggle, "Rename…" and destructive "Remove"; device rows are indented 32 pt with `laptopcomputer`, "Connected"/"Last seen …"/"Paired …" and a "Remove" link. Footer "Add User…". Alerts: "New User"/"Rename User" with a "Name" field and "Add"/"Rename"; "Remove <user>?" with "“<user>”, their devices and their bots are removed from <hub>."; "Remove <device>?" with "“<device>” can no longer reach <hub> until it joins again." Admins appear without controls; a code comment says they are managed on the Hub itself, and their devices have no "Remove".
+
+Archived sheet (420 x 360): "Archived on <hub>", "Nothing archived" when empty, rows with a 32 pt conversation avatar, title, "Group" or "Bot" and an "Unarchive" link. "Your Picture…" opens an icon editor titled "Your Picture" (symbols, colours or a photo, JPEG quality 0.86); a failed save shows "Your Picture Was Not Changed".
+
+Troubleshooting UI exists on Noodle Mobile, not in Mac Settings: a "Help Me Connect" sheet lists the Hub's routes nearest first ("Home Wi-Fi", "Tailscale", "Internet") each with "Answers" (green check) or "No answer", then ordered advice: "You're offline. Connect to Wi-Fi or mobile data.", "Noodle isn't allowed to look for your Hub on this network. Turn on Local Network for Noodle in Settings." with "Open Settings", "Make sure you're on the same Wi-Fi as the Mac your Hub runs on." (or the mobile-data variant), "Away from that Wi-Fi? Open Tailscale and connect.", "Make sure the Mac your Hub runs on is awake and its Hub is open.", or, when an address answered, "Your Hub answers now. Tap Try Again." with a prominent full-width "Try Again" (`Mobile/Sources/NoodleMobile/HubScreens.swift:234-351`, rules in `Shared/HubLink/.../HubTroubleshooting.swift:26-38`). On the Mac, the troubleshooting surface is limited to row status, reachability summary and inline errors.
+
+The Noodle Hub app (screenshot) has its own Users and Plans tabs: user rows with Invite and an actions menu (Plan, Can Pair Devices, Admin, Rename…, Remove), indented device rows with a green 6 pt dot "Connected" label style, plan rows with `rectangle.stack` and summaries such as "Lends Codex ([email protected]) · 2 users" or "Lends nothing · 0 users" with "Edit…", and footers "Add User…" and "Add Plan…" (`Hub/Sources/NoodleHub/HubAccessSettings.swift:26-186,443-450`). Its Network tab adds "Connected" ("No one" or "2 people on 3 devices") and "Open at Login" (`HubLinkSettings.swift:13-35`).
+
+### 2.14 Other shared behaviours
+
+`WindowFocusGuard` (`Shared/SettingsUI/.../WindowFocusGuard.swift:53-92`) makes the first physical click on an inactive titled window or sheet only focus it, swallowing the click and its drag and mouse-up, so settings controls are never triggered by a click meant to activate the window. Agents driving the UI programmatically bypass it.
+
+## 3. Web translation
+
+These notes target React 19 with Tailwind v4, shadcn/ui and Radix, and follow OpenCompany's frontend rules (semantic tokens, lucide icons, primitives rather than hand-rolled controls).
+
+Settings layout:
+
+- Render Settings as a dedicated route or a large non-modal `Dialog` with a top tab strip. Use Radix `Tabs` with a custom `TabsList`: each trigger is an icon (about 20 px) stacked over an 11 px label in a roughly 56 x 44 px hit area with a rounded selected background (inferred from the screenshot; macOS draws these). Keep the strip on one row at 740 px content width; if a narrower viewport would overflow, switch to an icon-only strip or a select rather than a hidden overflow menu.
+- Content column fixed at 740 px; height follows the tab's content up to `100dvh` minus the dialog chrome, then scrolls inside. Animate height changes between tabs over 220 ms ease-in-out by measuring the incoming panel with a `ResizeObserver` and transitioning `height`, pinned to the top edge (the equivalent of `windowResizeAnchor(.top)`). Use `scrollbar-gutter: stable` on the scroll container instead of Noodle's hide-then-restore indicator hack.
+- Grouped sections: a `div` per section with `rounded-xl bg-card` and `divide-y divide-border` rows; section headers and footers outside the box in caption text. This is the macOS grouped `Form` look visible in the screenshot.
+- Tab badge: an absolutely positioned pill at the trigger's top-right, `h-3 min-w-3 px-0.5 rounded-full bg-destructive text-[8px] leading-3 text-white tabular-nums`, `aria-label` with the count, `pointer-events-none`. Drive it from a map keyed by tab id, not by label.
+- Footer bar: a sticky bottom row `border-t px-5 py-3 flex justify-end gap-2`, with a `useDelayedFlag(isRefreshing, 300)` spinner kept in layout via opacity.
+- Deep links: keep the selected tab in the URL or a store so other surfaces (a notification, a Kick dialog) can open Settings on Harness.
+
+Components to build once:
+
+| Component | Spec |
+|---|---|
+| `StatusLabel` | lucide icon + caption text, one tone class (`text-success`, `text-warning`, `text-muted-foreground`), `whitespace-nowrap`; tones never red |
+| `SettingsIconRow` | `grid grid-cols-[32px_1fr] gap-3 py-1`; icon 24 px muted; title row `font-semibold` + status at end; caption lines `text-xs text-muted-foreground`; action line of `Button variant="link" size="sm"` with `gap-3` |
+| `RowList` | rows with dividers, gap 10 px, max height 360 px then scroll, scrollbar in the trailing margin |
+| `CommandBlock` | monospace `text-sm`, terminal icon, icon-only copy button, `p-2.5 rounded-md border bg-muted/50` equivalent via a soft token |
+| `DeviceCodeChallenge` | code in monospace, "Copy Code", "Open Sign-In Page", caption "Enter this code on the sign-in page." |
+| `ExplainPopover` | Radix `Popover`, 360 px, `p-5`, headline + paragraphs; trigger styled as caption text |
+| `RowActionsMenu` | `DropdownMenu` on a lucide `Ellipsis` in a circle, destructive item last after a separator |
+| `ConfirmDestructive` | `AlertDialog`; initial focus on Cancel (Radix `onOpenAutoFocus` targeting Cancel) so Enter cancels, matching Noodle |
+| `UsageGuardPopover` | lists bots blocking a removal, each with "Edit…", reopening after the editor closes |
+
+SF Symbol to lucide suggestions (inferred equivalents): `gearshape` Settings, `bubble.left.and.bubble.right` MessagesSquare, `terminal` SquareTerminal, `sparkles` Sparkles, `person.3` Users, `puzzlepiece.extension` Puzzle, `keyboard` Keyboard, `hand.raised` Hand, `square.stack.3d.up` Layers, `server.rack` Server, `arrow.triangle.2.circlepath` RefreshCw, `checkmark.circle.fill` CircleCheck, `exclamationmark.triangle` TriangleAlert, `person.crop.circle.badge.questionmark` UserRoundX or CircleHelp, `arrow.down.circle` CircleArrowDown, `ellipsis.circle` CircleEllipsis, `circle.dotted` CircleDashed, `arrow.trianglehead.2.clockwise` RotateCw, `doc.on.doc` Copy, `chart.bar` ChartColumn, `arrow.down` ArrowDown, `xmark.circle.fill` CircleX, `plus.circle.fill` CirclePlus, `minus.circle.fill` CircleMinus, `iphone` Smartphone, `laptopcomputer` Laptop, `desktopcomputer` Monitor, `globe` Globe, `square.grid.2x2` LayoutGrid, `mic` Mic, `rectangle.dashed.badge.record` ScreenShare, `bell.badge` BellDot. Harness marks should ship as monochrome SVGs coloured by `currentColor`.
+
+State shapes (TypeScript):
+
+```ts
+type AuthStatus = 'authenticated' | 'unauthenticated' | 'notRequired' | 'managedExternally';
+interface VersionReport { installed?: string; latest?: string; compatibilityIssue?: string; checkError?: string; checkedAt?: string }
+interface HarnessSnapshot { provider: HarnessId; executablePath: string | null; auth: AuthStatus | null; version: VersionReport | null }
+interface HarnessRow {
+ snapshot?: HarnessSnapshot; // undefined = never checked; seeded from a display-only cache
+ error?: string; activity?: string; progress?: number; // progress absent = indeterminate
+ challenge?: { url: string; code: string }; terminalCommand?: string;
+ checking: boolean; managed: boolean;
+ affectedBots: { id: string; name: string; failed: boolean; reconnectingSince?: string; detail: string }[];
+}
+type PermissionStatus = 'allowed' | 'notRequested' | 'denied' | undefined; // undefined = Checking…
+interface ToolConnection { id: string; name: string; endpoint: string; description: string; instructions: string; iconUrl?: string; connected: boolean; error?: string }
+interface ToolsState { connections: ToolConnection[]; signingIn?: string; signInStage: string }
+interface Invitation { url: string; hubKeyFingerprint: string; userName: string; expiresAt: string }
+interface ActivityEntry { id: string; at: string; title: string; detail: string; streamId?: string }
+```
+
+Derive the harness status in one pure function that mirrors section 2.4's priority table, and compute badge counts from the same facts (errors, compatibility issues, available updates, failed bots), never from rendered text. Persist the last confirmed `HarnessSnapshot` per provider in local storage for instant paint, and never read it for authorization.
+
+Live views:
+
+- Activity log: keep a per-bot ring buffer (500 entries, 256 KB, 16 KB per detail, trim with a leading ellipsis line) outside React state; flush to the view at most every 200 ms and only when the panel is visible. Render the text in one `<pre>` (or a single read-only text node per entry) so native selection and browser find work; append only the changed suffix. Follow the bottom only when within 4 px of it and the selection is empty; otherwise show a 34 px round "Follow Latest" button 16 px above the bottom with a 150 ms fade. Offer a Radix `ContextMenu` with Copy, Copy All, Select All, Follow Latest, Clear. Make the panel a draggable, resizable floating surface (760 x 500 default, 440 x 260 minimum) with a 36 px drag header, always dark, 18 px outer radius, 1 px white border at 22%, 5 px inset to a 13 px-radius body; Escape closes.
+- Usage: a page with a `ToggleGroup` for 7 Days / 30 Days / 12 Months and Tokens / Cost, `Select`s for bot and grouping, a six-stat KPI strip with vertical dividers, a stacked bar chart (Recharts `BarChart` with one `Bar` per group sharing a `stackId`, dimming non-hovered buckets to 0.4 opacity, a custom tooltip), and a shadcn `Table` with `tabular-nums` right-aligned numeric columns. Format with `Intl.NumberFormat(undefined, { notation: 'compact', maximumSignificantDigits: 3 })` and USD with three decimals strictly between 0 and 1. Define the seven categorical colours as theme tokens (`--chart-1` to `--chart-7`) rather than hex in components, assign them to the top seven groups in name order, and render "Other" in a neutral token. Show "—" for cost when no source reported cost.
+- Relative times: re-render "Last seen" every 15 s and countdowns every 1 s with `Intl.RelativeTimeFormat`.
+- Refresh on focus: re-check permissions, installs and companion versions on `visibilitychange` to visible and on window `focus`, the browser equivalent of `didBecomeActive`.
+
+Permissions on the web: use `navigator.permissions.query` for microphone and notifications; screen capture has no query, so store a "requested" flag (as Noodle does for Screen Recording) to tell refused from never asked. A refused permission can only be fixed in the browser's site settings; replace "Open System Settings" with instructions.
+
+Keybindings on the web: a recorder button listening on `keydown` at the window while recording, ignoring `repeat` and `keyup`, Escape cancels, unmodified Tab ends recording without capturing, Backspace or Delete clears, and at least Ctrl/Cmd or Alt is required. Store only overrides with explicit `null` for disabled. Extend the reserved list with browser shortcuts the page cannot intercept (Cmd/Ctrl+W, T, N, Q, L, R, Tab).
+
+Hub invitation on the web: generate the QR with error level M at 200 px, `image-rendering: pixelated`, on a white tile with 10 px padding and 10 px radius in every theme; show the URL truncated in the middle, the key fingerprint, "Copy Link" and a Web Share button with a copy fallback, and the 15-minute countdown.
+
+## 4. Patterns worth copying, and pitfalls to avoid
+
+Worth copying:
+
+- One status vocabulary and colour grammar for every operational row: green usable, orange act or recover, secondary pending or neutral, red only for inline error text and badges.
+- Status as a pure function of facts in a fixed priority order, with the last confirmed snapshot cached for instant paint and explicitly barred from authorization; a failed check never erases what was known.
+- Badges count only actionable items: refused permissions (not unrequested ones), failed bots (not reconnecting ones), harnesses with errors or updates (not uninstalled ones).
+- Never flash progress: 300 ms delay for spinners, old error text replaced by "Checking for updates…" during a re-check, rows stay busy until the result can be shown.
+- Three sign-in modes behind one row: device code (Copy Code, Open Sign-In Page), browser OAuth with stage text and Cancel, and a Terminal command block with Copy, Open Terminal and Check Again.
+- Destructive confirmations that state consequences and what is kept, with Cancel as the default button.
+- Removal blocked by dependants, with a popover that lists them, links straight to fixing each, and returns afterwards.
+- Idempotent creation on retry (preset attempts and new connections keep their ids), so partial failures resume.
+- Hues assigned by name order, not rank, so chart colours stay put across periods and measures.
+- Activity log batching at 200 ms with incremental suffix updates that preserve selection and scroll.
+- Explain-on-click headers and status words instead of permanent help text.
+- Re-check on return to the app for anything changed outside it.
+
+Pitfalls:
+
+- Label-keyed badges silently disappear when a tab is renamed or the toolbar overflows; key by id.
+- The macOS-specific techniques (walking the title bar view tree, run-loop observers, sheet window resizing) should not be ported; use measured CSS height transitions and `scrollbar-gutter`.
+- Website screenshots and docs lag the code: the harness screenshot shows removed Heartbeat and Sandbox tabs; docs mention a link-preview timeout that does not exist and say FX and OpenCode lack profiles while the code supports them; the Hub app keeps a stale "same width as Noodle" comment (680 vs 740).
+- Device icons are inconsistent: Noodle's This Mac rows use `iphone` for every device while Hub users' devices use `laptopcomputer` for every device, including iPhones.
+- The Usage shortcut can be bound in preferences but has no editor row.
+- "Sign-in status unknown" must never be treated as signed out, and cost totals must show "—", not $0, when nothing reported cost.
+- Browsers cannot capture several system and browser shortcuts; validate against them before accepting a binding.
+
+## 5. Open questions and inferences
+
+- Toolbar tab icon and label sizes, selected-tab background and window corner radius are system-drawn and not in code; values in section 3 are inferred from the screenshot.
+- The screenshot's two-line path and "Version …" layout, bordered "Sign In…" buttons and the Hub app's inline plan popup belong to older builds; the current visual of the one-line "path · version" row is inferred from code only.
+- The exact provider list in the "Add Account" menu comes from `RemoteProviders.all`, which was not read; the list given follows `docs/harness-setup.md:211-218` (inferred).
+- Which providers raise a device-code challenge versus opening the browser directly depends on provider files not read in full; the docs say Claude Code opens the browser and others show a code (inferred from `docs/harness-setup.md:64-67`).
+- `IconEditorSheet` (Hub picture) and the Hub plan editor were not read in detail.
+- The Bots tab's per-bot Heartbeat, Unrestricted and Apps switches are summarised here only for access confirmation copy; their layout is covered by the Bots settings analysis.
+- Whether the Usage window's subtitle renders exactly as "8 Sep – 7 Oct 2026" depends on the system locale (inferred).
diff --git a/docs-internal/research/noodle/analysis/07-state-model-and-runtime-ui.md b/docs-internal/research/noodle/analysis/07-state-model-and-runtime-ui.md
new file mode 100644
index 00000000..d4b3db4c
--- /dev/null
+++ b/docs-internal/research/noodle/analysis/07-state-model-and-runtime-ui.md
@@ -0,0 +1,717 @@
+# Noodle: domain model, app store and the runtime-to-UI contract
+
+Noodle's Mac UI is driven by one `@MainActor @Observable` store (`NoodleStore`) that caches a file-backed repository (`WorkspaceRepository`) and reads per-bot runtime snapshots from an observable coordinator (`AgentRuntimeCoordinator`). Transcripts are append-only JSON arrays. Bots never stream text into the transcript: they post complete messages by running a `messenger` CLI that writes into the same files, and the app picks new messages up with a one-second polling loop. Runtime state is a per-bot snapshot (`offline | starting | ready | working | failed`, a free-text `detail` and an optional typed `failure`), which the UI folds into one coloured dot per conversation. Unread state is a per-conversation boolean. A group is a conversation with several bots, and every one of them is woken by every message; the code has no addressing, mentions routing or turn-taking. The Hub/mobile protocol (`LinkProtocol`) already defines a request/response plus event-stream wire contract with idempotent sends and positional paging, and a strict JSON "Scenario" format seeds complete UI state and plays scripted films. This document turns all of that into TypeScript types, a store shape and a WebSocket event contract.
+
+Permalink base for every citation below: https://github.com/pdparchitect/noodle/blob/702339e3153025c9fe9582783caff7a19b48ff97/ (citations are repo-relative `path:line` or `path:start-end`).
+
+## 1. Scope: files read
+
+Read in full:
+
+- `Sources/Noodle/NoodleStore.swift` (2,266 lines), `Sources/Noodle/Components.swift`, `Sources/Noodle/AgentActivityWindows+Store.swift`, `Sources/Noodle/AgentSettingsCheckpoint.swift`, `Sources/Noodle/Scenario.swift` (1,722 lines).
+- `Sources/NoodleCore/Models.swift`, `Harnesses.swift`, `WorkspaceRepository.swift` (1,566 lines), `MessageDelivery.swift`, `MessengerDocumentation.swift`, `MessengerBridge.swift`, `ConversationDrafts.swift`, `ConversationName.swift`, `ConversationEffects.swift`, `ConversationBackground.swift`, `TranscriptPositions.swift`, `VoiceMessage.swift`, `VoiceCall.swift`, `AttachmentAnnotation.swift`, `CompanionLink.swift`, `AgentConfiguration.swift`, `AgentHeartbeat.swift`, `AgentTurnRecovery.swift`, `AgentNameCompletion.swift`, `AgentSessionRollover.swift`.
+- `Sources/NoodleRuntime/AgentRuntimeCoordinator.swift` (1,100 lines), `AgentRuntimeProcess.swift`, `AgentActivityLog.swift`, `AgentActivityParser.swift`, `MessageDeliveryRouter.swift`, `MessageDeliveryClassifier.swift`, `UsageHistory.swift`; `ClaudeAgentProcess.swift` lines 180-417 (phase transitions).
+- `Sources/Noodle/SidebarView.swift`, `ChatView.swift`, `TranscriptScrollView.swift`, `MessageMarkdownCache.swift`, `NoodleNotifications.swift`, `MessageReceivedSound.swift`.
+- `Shared/HubLink/Sources/HubLink/MessageTable.swift`, `CustomSpace.swift`; `LinkProtocol.swift` lines 1-135, 236-325, 540-620, 1068-1600.
+- `Scenarios/bot-needs-attention`, `launch-week`, `personal-assistant`, `code-review` (timeline), `schedule-post` (timeline).
+
+Skimmed: `Sources/Noodle/ScenarioFilm.swift`, `ConversationWindow.swift` (title, error alert, window registry), `ConversationEffectsView.swift`, `AgentProfileSheet.swift`, `NoodleSettingsView.swift`, `ConversationWindowSession.swift`; `Sources/NoodleRuntimeSettings/AgentActivityWindow.swift`, `AgentKickConfirmation.swift`, `BotAvatar.swift`; `Sources/NoodleCore/MessengerCLI.swift`, `AgentAccess.swift`, `AgentFolder.swift`, `AgentStorageLayout.swift`, `UsageLedger.swift`; `Sources/NoodleHubClient/HubMirror.swift` (sync loop); `Sources/HubCore/HubBots.swift` (event emission); `Mobile/Sources/NoodleMobile/Chats.swift` (unread, ordering, optimistic send); `Shared/HubLink/Sources/HubLink/LinkCall.swift`; `Tests/NoodleAppTests/ConversationRuntimeStatusTests.swift`, `TranscriptLayoutTests.swift` (test names).
+
+## 2. Findings
+
+### 2.1 Architecture in one picture
+
+```
+SwiftUI views --read--> NoodleStore (@MainActor @Observable) AgentRuntimeCoordinator (@MainActor @Observable)
+ | agents, conversations, messagesByConversation snapshots[agentID] (phase/detail/failure)
+ | intents attachmentsByConversation, unread, pins, drafts activity logs, heartbeats, restarts
+ v | ^ 1 s poll (mtime+size revisions) ^ onSnapshot / onActivity callbacks
+store.sendDraft() ---> WorkspaceRepository (JSON files, flock, atomic) |
+ ^ AgentRuntimeProcess (one per bot)
+ | messenger --send/--react/--set-status ^ notify() = wake event
+ | (file mailbox, broker scans every 100 ms) |
+ bot harness (Claude Code, Codex, ...) <---------------+
+```
+
+- The repository files are the source of truth; the store holds an in-memory copy and updates it after each successful write (`NoodleStore.swift:1452-1480`) or when the poll sees a file change (`NoodleStore.swift:2218-2233`, `1838-1971`).
+- Bots talk only through Messenger: the CLI writes a request file into `.noodle/messenger-bridge` in the bot's workspace, an in-app broker scans every 100 ms, checks a per-bot session token and calls the repository (`Sources/NoodleCore/MessengerBridge.swift:15-44`, `49-120`; dispatch in `MessengerCLI.swift:67-167`).
+- The store learns about bot replies only by polling; runtime phases arrive by callback (`AgentRuntimeCoordinator.swift:1065-1082`).
+- Bots on a Noodle Hub are mirrored into the local repository by `HubMirror`, which follows the Hub's event stream (`Sources/NoodleHubClient/HubMirror.swift:493-556`). The Hub is, in effect, the server a web client would replace.
+
+### 2.2 Entity model
+
+| Entity | Defined at | Stored in | Relationships |
+|---|---|---|---|
+| `AgentRecord` (bot, public fields) | `Sources/NoodleCore/Models.swift:5-56` | `Agents/<id>/agent.json` (merged with private config) | has one direct `BotConversation`; member of 0..n groups |
+| `AgentConfiguration` (private) | `AgentConfiguration.swift:17-60` | same `agent.json` | backstory, folders, groupFolders, harnessProfile, owner, voice; never sent to other bots |
+| `BotConversation` | `Models.swift:58-101` | `Conversations/<id>/conversation.json` | `participantIDs` -> agents; direct has exactly one |
+| `ConversationGuest` | `Models.swift:104-112` | inside conversation | Hub-shared conversation with someone other than the owner |
+| `ChatMessage` | `Models.swift:114-158` | `Conversations/<id>/messages.json` (array) | `author` -> agent; `attachmentIDs` -> attachments of the same conversation |
+| `MessageReaction`, `MessageReactionChange` | `Models.swift:160-182` | inside the message | change log carries a per-conversation `sequence` |
+| `ConversationAttachment` | `Models.swift:197-240` | `Conversations/<id>/Attachments/<id>.json` + `<id>.<ext>` | referenced by messages and drafts |
+| `LinkCard`, `CompanionLink` | `CompanionLink.swift:8-69` | inside attachment | link to a browser tab, computer or noodlet |
+| `AttachmentAnnotation` | `AttachmentAnnotation.swift:5-71` | inside attachment | points at a source attachment and optionally a source message |
+| `VoiceMessage` | `VoiceMessage.swift:4-25` | inside attachment | |
+| `VoiceCallRecord`, `VoiceCallLine` | `VoiceCall.swift:3-33` | inside a message (`call`) | |
+| `ConversationBackground` | `Shared/Wallpaper/Sources/NoodleWallpaperCore/ConversationBackground.swift:5-19` | `Conversations/<id>/background.json` + `Backgrounds/` | per conversation, local appearance only |
+| `ConversationEffect` | `ConversationEffects.swift:5-21` | `Conversations/<id>/effects.json` | ephemeral queue, sent by bots |
+| `AgentInbox` | `Models.swift:242-249` | `<workspace>/.noodle/inbox.json` | per-bot read cursors per conversation |
+| `AgentRuntimeSnapshot` | `Harnesses.swift:275-319` | memory only | one per bot |
+| `ConversationDrafts.Draft` | `ConversationDrafts.swift:3-33` | memory only | one per conversation |
+| `TranscriptViewport` | `TranscriptPositions.swift:3-22` | `scroll-positions.json` | one per conversation |
+| `CustomSpace` | `Shared/HubLink/Sources/HubLink/CustomSpace.swift:5-31` | `spaces.json` (iCloud-synced) | members and pins by (hub key, conversation) |
+| `AgentActivityEntry` | `AgentActivityLog.swift:19-33` | memory only, bounded | one log per bot |
+| `UsageSample` | `UsageLedger.swift:40-60` | `usage.sqlite` | per bot, model, session |
+
+The same data translated to TypeScript (field names exactly as Noodle encodes them on disk; comments carry the constraints the code enforces):
+
+```ts
+type UUID = string; // Foundation encodes UUIDs uppercase in JSON (inferred); folder names are lowercased
+type ISODate = string; // repository files: ISO 8601 without fractional seconds (inferred from .iso8601)
+type Base64 = string; // Swift Data encodes as base64
+
+type HarnessProvider = 'codex' | 'claude-code' | 'muse' | 'grok-build' | 'fx' | 'opencode' | 'antigravity' | 'apple';
+
+interface AgentRecord { // Models.swift:5-56
+ id: UUID;
+ displayName: string; // trimmed, 1..100 chars, single line (ConversationName.swift:18-26)
+ createdAt: ISODate;
+ updatedAt: ISODate;
+ harnessIdentifier?: HarnessProvider; // absent -> bot shows failed "Choose a harness in Edit Bot"
+ modelIdentifier?: string;
+ reasoningEffort?: string; // e.g. low | medium | high | xhigh | max (Harnesses.swift:109-115)
+ publicDescription?: string; // empty -> absent; visible to other bots in a group
+ accentSeed: number; // random 0...5 at creation; avatar colour fallback
+ avatarSymbolName?: string; // SF Symbol, default "sparkles"
+ avatarColorIndex?: number; // wraps onto 6 gradients
+ avatarImageData?: Base64; // JPEG, <= 512 px when set from an attachment
+ status?: string; // set only by the bot itself; one line, <= 60 chars
+ archivedAt?: ISODate; // archived bots keep everything but never run
+}
+
+interface AgentPrivateConfig { // AgentConfiguration.swift:17-60, same file as AgentRecord
+ backstory: string; // rendered into the bot's generated AGENTS.md
+ folders?: AgentFolder[]; // up to 16 (AgentFolder.swift:14)
+ groupFolders?: AgentFolder[]; // copied from the bot's groups at every sync
+ harnessProfile?: UUID; // which login of the harness; absent = system login
+ owner?: { id: UUID; name: string }; // Hub only
+ voice?: string; // call voice id; only Codex has voices (VoiceCall.swift:102-110)
+}
+interface AgentFolder { path: string; writable: boolean; description?: string } // <= 500-char description
+
+type ConversationKind = 'direct' | 'group';
+interface BotConversation { // Models.swift:63-101
+ id: UUID;
+ displayName: string; // direct: kept in sync with the bot's name
+ publicDescription?: string;
+ kind: ConversationKind;
+ participantIDs: UUID[]; // direct: [botId]; group: >= 1, unique, sorted by UUID string
+ createdAt: ISODate;
+ updatedAt: ISODate; // sidebar recency key
+ archivedAt?: ISODate; // groups only; a direct conversation follows its bot
+ folders?: AgentFolder[]; // groups only
+ guest?: { id: UUID; name: string }; // conversations with this present are hidden on the owner's Mac
+}
+
+// Swift synthesized Codable on disk: {"user":{}} | {"agent":{"_0":"<UUID>"}} | {"system":{}} (inferred;
+// the same "_0" shape is asserted for other enums in Shared/HubLink/Tests/HubLinkTests/LinkCompatibilityTests.swift:18-72)
+type MessageAuthor = { kind: 'user' } | { kind: 'agent'; agentId: UUID } | { kind: 'system' };
+type MessageDelivery = 'saved' | 'queued' | 'delivered' | 'failed';
+
+interface ChatMessage { // Models.swift:127-158
+ id: UUID;
+ conversationID: UUID;
+ author: MessageAuthor;
+ body: string; // trimmed, never empty (WorkspaceRepository.swift:1498-1502)
+ createdAt: ISODate;
+ delivery: MessageDelivery;
+ attachmentIDs?: UUID[]; // omitted when empty
+ reactions?: MessageReaction[]; // current badges
+ reactionChanges?: MessageReactionChange[]; // append-only event log, feeds bot inboxes
+ call?: VoiceCallRecord; // the card of a voice call
+}
+interface MessageReaction { id: UUID; author: MessageAuthor; emoji: string; createdAt: ISODate }
+interface MessageReactionChange {
+ id: UUID; conversationID: UUID; messageID: UUID;
+ sequence: number; // max over the conversation + 1 (WorkspaceRepository.swift:1335)
+ author: MessageAuthor; emoji: string; removed: boolean; createdAt: ISODate;
+}
+
+interface ConversationAttachment { // Models.swift:197-240
+ id: UUID;
+ conversationID: UUID;
+ originalFilename: string;
+ storedFilename: string; // "<id>.<ext>"
+ mediaType: string; // images re-detected from content (WorkspaceRepository.swift:1045-1066)
+ byteCount: number;
+ createdAt: ISODate;
+ url?: string; // link attachment: http(s) page, noodlebrowser://, noodlecomputer://, noodlet://
+ voice?: VoiceMessage;
+ card?: LinkCard; // companion links only
+ annotation?: AttachmentAnnotation;
+}
+interface LinkCard { // CompanionLink.swift:43-69
+ title: string; // <= 300 chars
+ detail?: string; // page address or terminal tail, last 2,000 chars
+ image?: Base64; // JPEG snapshot <= 550,000 bytes
+ symbol?: string; colour?: number; icon?: Base64; capturedAt?: ISODate;
+}
+interface VoiceMessage { // VoiceMessage.swift:4-25
+ transcript?: string; duration: number; // 0 < duration <= 660 s
+ waveform: number[]; // <= 120 samples in 0..1
+ localeIdentifier?: string;
+}
+interface AttachmentAnnotation { // AttachmentAnnotation.swift:5-71
+ version: 1 | 2; // 1 = legacy PDF; 2 = text/plain or image/png
+ sourceAttachmentID: UUID; sourceFilename: string; sourceMessageID?: UUID;
+ quote?: string; comment: string; // quote and region are mutually exclusive
+ region?: { x: number; y: number; width: number; height: number }; // fractions, bottom-left origin
+}
+interface VoiceCallRecord { agentID: UUID; endedAt?: ISODate; lines: VoiceCallLine[] }
+interface VoiceCallLine { speaker: 'person' | 'bot'; text: string; at?: ISODate }
+
+interface ConversationBackground { // NoodleWallpaperCore/ConversationBackground.swift:5-19
+ preset?: 'sunset' | 'ocean' | 'forest' | 'dusk';
+ imageFilename?: string; // "<uuid>.jpg|heic|heif|mov|mp4|m4v" in Backgrounds/
+ mediaKind?: 'image' | 'video' | 'dynamicImage';
+} // isDefault = !preset && !imageFilename
+
+interface ConversationEffect { // ConversationEffects.swift:10-21
+ id: UUID; conversationID: UUID; agentID: UUID;
+ kind: 'confetti' | 'fireworks' | string; // unknown kinds are skipped by older clients
+ createdAt: ISODate; expiresAt: ISODate; // expiresAt = createdAt + 30 s
+ consumedAt?: ISODate;
+}
+
+interface AgentInbox { // Models.swift:242-249, per bot
+ conversationOffsets: Record<string /* lowercased conversation id */, number>; // messages already read
+ reactionOffsets?: Record<string, number>; // last reaction sequence read
+}
+
+interface Draft { text: string; attachments: ConversationAttachment[] } // memory only on the Mac
+interface TranscriptViewport { offset: number; isAtBottom: boolean; messageID?: UUID }
+
+interface CustomSpace { // CustomSpace.swift:5-31
+ id: UUID; name: string;
+ members: { hub?: string; conversation: UUID }[]; // hub = Hub public key (base64), absent = this Mac
+ pins: { hub?: string; conversation: UUID }[]; // in pin order
+}
+```
+
+### 2.3 Message lifecycle
+
+**Creation paths.** Every message is appended to `messages.json` under an exclusive `flock` on `.messages.lock` (`WorkspaceRepository.swift:1090-1097`, `1542-1550`) and the conversation's `updatedAt` is bumped to the message time.
+
+| Path | Code | Author | Initial delivery | Side effects in the store |
+|---|---|---|---|---|
+| Composer send | `NoodleStore.swift:1452-1480` -> `WorkspaceRepository.swift:1406-1432` | user | `queued` | mark read; append to cache; bump `updatedAt` and re-sort; clear draft; `runtime.notify(all participants)`; relay to an open voice call; push to the Hub |
+| Voice message | `NoodleStore.swift:1423-1445` | user, body `"Voice message"` | `queued` | staged files travel with the recording; text draft untouched |
+| Slash-style command | `NoodleStore.swift:1482-1500` | user | `queued` | as composer send |
+| Share extension | `WorkspaceRepository.swift:1463-1490` | user; `id` = request id (idempotent retry) | `queued` | |
+| Bot reply (`messenger --send`) | `MessengerCLI.swift:121-155` -> `WorkspaceRepository.swift:1348-1385` | agent | `delivered` | seen by the next poll |
+| Group change notice | `WorkspaceRepository.swift:723-744` | system | `delivered` | written in the same transaction as the group change |
+| Voice call card | `WorkspaceRepository.swift:1434-1461` | user, body `"Voice call"`, `call` set | `delivered` | lines and `endedAt` filled when the call ends |
+
+A message with files but no text gets the body `"Sent N attachment(s)"` (`NoodleStore.swift:1457`; same rule on mobile, `Mobile/Sources/NoodleMobile/Chats.swift:698-701`). Messages cannot reach an archived group, an archived bot or a group whose bots are all archived (`WorkspaceRepository.swift:522-529`); the composer shows the reason in place of its placeholder: `"This group is archived"`, `"Every bot in this group is archived"`, `"<Name> is archived"` (`NoodleStore.swift:651-661`, `ChatView.swift:370-372`).
+
+**Delivery state machine.** `queued -> delivered` happens when any recipient bot consumes its inbox (`messenger --get-latest` without `--peek`): `latestMessages(consuming: true)` advances the bot's offsets and marks every queued user message up to that count delivered (`WorkspaceRepository.swift:1213-1231`, `1249-1260`). "Delivered" therefore means "a bot has read it". For Hub bots the flag follows the Hub's `delivered` field (`HubMirror.swift:694`, `717`). `saved` and `failed` exist in the enum and have labels, but no current code path assigns them: the only assignments are `queued` and `delivered` (`WorkspaceRepository.swift:742`, `1244`, `1257`, `1377`, `1425`, `1442`, `1479`); scenarios may seed them (`Scenario.swift:529`; `Scenarios/bot-needs-attention/scenario.json:31`). Labels appear only under the user's own bubbles (`Components.swift:305-310`, `522-529`):
+
+| `delivery` | Label |
+|---|---|
+| `saved` | Saved |
+| `queued` | Sent |
+| `delivered` | Delivered |
+| `failed` | Not delivered |
+
+Mobile adds two client-only states for its optimistic send: `"Sending…"` while a send is in flight and `"Not delivered"` once its retries fail (`Chats.swift:672-678`).
+
+**The bot side of delivery.** Each bot keeps `AgentInbox` offsets per conversation. `latestMessages` returns every message after the offset except the bot's own and call cards, plus reaction changes by others whose `sequence` is above the reaction offset, sorted by time (`WorkspaceRepository.swift:1119-1234`). Each delivery is a `MessengerDelivery` envelope: `me`, `conversation`, named `participants`, `sender` (handle `user | guest | me | bot | system`), `message`, `attachments` (with an absolute path copy inside the bot's workspace), current `reactions` and an optional `reactionChange` (`Models.swift:251-328`). A bot is never sent the message itself in its wake event: it gets a bodyless `<noodle-event type="inbox-changed" />` and must fetch (`MessengerDocumentation.swift:48-67`, `AgentHeartbeat.swift:88-98`).
+
+**Streaming and partial content.** There is none in the transcript. A bot's reply appears whole, the moment the poll sees it (`MessageBubble.insertion`: slide up from the bottom plus fade; system rows fade only, `Components.swift:230-233`). Harness output (text deltas, reasoning summaries, tool calls, command output, plans) streams into a separate per-bot Activity log, shown in its own window (section 2.4). The scenario `stream` step writes into that log, not the chat (`Scenario.swift:1103-1111`), and the `code-review` scenario opens the activity window to show it (`Scenarios/code-review/scenario.json:71`, `79`). There is no typing indicator; "working" is only the blue dot.
+
+**Edits and deletions.** Sent messages are never edited or deleted. What can change after a message exists: its reactions, its delivery flag, a call card's lines and end time (`WorkspaceRepository.swift:1450-1461`), and a repaired image media type. An annotation's comment can be revised only while it sits in a draft, before any message references it (`WorkspaceRepository.swift:973-1009`, `AttachmentAnnotation.swift:73-88`). Deleting a bot deletes its workspace and direct conversation and silently removes it from groups (no system notice; `WorkspaceRepository.swift:416-460`, `MessengerDocumentation.swift:28`); its old group messages keep its id and render without an avatar (`Components.swift:255-256`). Deleting a group deletes its messages and attachments (`NoodleStore.swift:1313-1319`). Only mobile can delete or "take back" its own unsent, failed message (`Chats.swift:759-782`).
+
+**Reactions.** One reaction per (author, emoji); the emoji must be a single grapheme with an emoji scalar (`Models.swift:166-170`). `setReaction` is idempotent and writes the badge and its change-log entry in one atomic write (`WorkspaceRepository.swift:1302-1346`). The user's "change reaction" adds the new emoji before removing the old so a failure cannot lose both (`NoodleStore.swift:2064-2075`). A user reaction wakes every bot in the conversation; a bot reaction wakes the other participants (`NoodleStore.swift:1959-1968`). In the bubble, badges sit on the first text segment (or on the files when there is no text), deduplicated in first-seen order, with a count above one, tinted when the user is among the reactors; a popover lists names and offers a 12-emoji change palette (red heart, thumbs up, thumbs down, tears of joy, party popper, question mark, eyes, hourglass, check mark button, folded hands, fire, light bulb) (`Components.swift:381-520`). Every row reserves the badge overhang (12 pt) so reacting never moves a message (`Components.swift:209-228`). Reactions made on a Hub are not shown on the Mac yet (`HubMirror.swift:532`).
+
+**Attachments.** Files are copied into the conversation the moment they are staged in the composer, before sending (`NoodleStore.swift:1710-1737`); the message only lists their ids; removing a staged chip deletes the files (`NoodleStore.swift:1779-1789`). Kinds: plain files; images (media type detected from content); links (a small `.webloc` plus `url`, with a `LinkCard` for companion links; `WorkspaceRepository.swift:950-964`); voice (`audio/x-caf` plus `VoiceMessage`; a message holding only recordings shows no text bubble, `Components.swift:376-379`); annotations (text or PNG, with metadata). Saved annotations are durable drafts: after a restart they are put back into the draft until a message references them (`NoodleStore.swift:588-591`). The bot path validates that attachment ids exist in the conversation (`WorkspaceRepository.swift:1366-1370`); the user path does not. A link preview is fetched for the first public web URL in the body unless the same URL is already an attachment, and only while the row is visible (`Components.swift:286-290`, `315-317`).
+
+**Ordering.** Canonical order is append order in `messages.json`. Because the log is append-only and nothing is deleted, the Hub protocol pages by position (`after`, `before`, `limit`) rather than by time (`Shared/HubLink/Sources/HubLink/LinkProtocol.swift:1551-1579`). Bot deliveries are sorted by time (`WorkspaceRepository.swift:1223-1225`); mobile merges pages by `(createdAt, original index)` so equal timestamps stay stable (`Chats.swift:878-886`). Scenario messages must be seeded in time order (`Scenario.swift:531-533`).
+
+**Rendering-relevant parsing.** Bodies are Markdown, rendered inline-only with whitespace preserved; only `http`, `https` and `mailto` links survive (`MessageMarkdownCache.swift:58-73`). Markdown tables split a body into separate bubbles; a table with more than 8 rows folds to 6 and is sortable (`Shared/HubLink/Sources/HubLink/MessageTable.swift:4-79`). Previews and notifications use the text around tables, or "Sent a table" (`MessageTable.swift:52-60`).
+
+### 2.4 Runtime status model
+
+**Per-bot snapshot** (`Harnesses.swift:275-319`):
+
+```ts
+type AgentRuntimePhase = 'offline' | 'starting' | 'ready' | 'working' | 'failed';
+type AgentRuntimeFailure = // "supplied by the adapter, never inferred from display text"
+ | { kind: 'missingSession'; sessionId: string }
+ | { kind: 'usageLimit' } | { kind: 'authenticationRequired' }
+ | { kind: 'recoveryFailed' } | { kind: 'safetyStop' };
+interface AgentRuntimeSnapshot {
+ agentID: UUID;
+ phase: AgentRuntimePhase;
+ detail: string; // human sentence, shown as tooltip/accessibility value
+ processIdentifier?: number;
+ failure?: AgentRuntimeFailure; // present only with phase 'failed'
+ reconnectingSince?: ISODate; // first retry of the current connection episode
+}
+// canKick = phase === 'failed' || reconnectingSince != null (Harnesses.swift:302)
+```
+
+A bot with no snapshot is `offline`, `"Not started"` (`AgentRuntimeCoordinator.swift:499-505`). Where snapshots come from:
+
+| Trigger | Phase | Example `detail` | Code |
+|---|---|---|---|
+| No harness chosen | failed | Choose a harness in Edit Bot | `AgentRuntimeCoordinator.swift:539-544` |
+| Harness installed, process not running | offline | Claude Code is configured | `AgentRuntimeCoordinator.swift:545-551` |
+| Harness missing | failed | The configured harness is not installed | `AgentRuntimeCoordinator.swift:552-557` |
+| Harness needs unrestricted access | failed | This harness requires unrestricted access. Allow it in Settings → Bots… | `AgentRuntimeCoordinator.swift:664-668` |
+| Process launching | starting | Starting Claude Code | `ClaudeAgentProcess.swift:86` |
+| Session open | ready | Claude Code ready | `ClaudeAgentProcess.swift:139` |
+| Wake begins a turn | working | Checking for new messages / Heartbeat: checking for follow-up work / Recovering interrupted work | `ClaudeAgentProcess.swift:229-259` |
+| Background tasks after a turn | working | 1 background task running | `ClaudeAgentProcess.swift:353-359` |
+| Turn ends (even with an error) | ready | Claude Code ready, or Claude Code ready — last task failed | `ClaudeAgentProcess.swift:316-343` |
+| Sign-in expired | failed + `authenticationRequired` | Claude Code needs you to sign in… | `ClaudeAgentProcess.swift:367-373` |
+| Model refusal | failed + `safetyStop` | Claude's safeguards stopped a response… | `ClaudeAgentProcess.swift:375-382` |
+| Process exits, or found dead by the 1 s reconcile | failed, then starting | Claude Code exited with status 1. Restarting in 1 seconds… / Runtime connection was lost. Restarting in 2 seconds… | `ClaudeAgentProcess.swift:361-392`, `AgentRuntimeCoordinator.swift:986-999`, `1004-1043` |
+| Access mode change | starting | Changing agent access… | `AgentRuntimeCoordinator.swift:323` |
+| Codex reconnecting for 10 min | restart; after two automatic restarts, failed | Codex could not reconnect after two automatic restarts… | `AgentRuntimeCoordinator.swift:973-983`, `844-847` |
+| App quits | offline | Stopped | `AgentRuntimeCoordinator.swift:960-962` |
+
+Supervision: unexpected exits restart with delay `min(2^(attempt-1), 30)` seconds, attempts capped at 7, and the counter resets after 60 seconds of a stable `ready` (`AgentRuntimeCoordinator.swift:1021-1056`). `reconcile` runs every second; a bot failed with a typed `failure` is left alone until the person kicks it, since "restarting cannot sign in, restore usage or answer a safety stop" (`AgentRuntimeCoordinator.swift:965-1002`). Snapshots from a superseded process are ignored by `runtimeID` (`AgentRuntimeCoordinator.swift:1065-1068`). A `working -> ready` transition counts as activity for heartbeats and clears the sign-in announcement (`AgentRuntimeCoordinator.swift:1070-1075`).
+
+**Conversation status and colours.** One dot per conversation, aggregated over `shownParticipants` (archived bots leave a group's set unless all are archived; `NoodleStore.swift:642-649`):
+
+```swift
+// Sources/Noodle/Components.swift:64-82
+enum ConversationRuntimeStatus: Equatable {
+ case working, failed, ready, idle
+ init(phases: [AgentRuntimePhase]) {
+ if phases.contains(.working) { self = .working }
+ else if phases.contains(.failed) { self = .failed }
+ else if !phases.isEmpty, phases.allSatisfy({ $0 == .ready }) { self = .ready }
+ else { self = .idle }
+ }
+ var color: Color { switch self { case .working: .blue case .failed: .red case .ready: .green case .idle: .gray } }
+}
+```
+
+Tests pin the precedence: working beats failed, failed beats ready, and anything short of all-ready (including an empty set, `starting` or `offline`) is idle (`Tests/NoodleAppTests/ConversationRuntimeStatusTests.swift:8-18`). A Hub bot shows the Hub's last phase while connected (unknown counts as ready) and `offline` when not (`Components.swift:85-91`); mobile uses the same colours with `offline` and `starting` grey and forces `offline` while the Hub is unreachable (`Chats.swift:2611-2618`; `Mobile/Sources/NoodleMobile/HubScreens.swift:935`). The tooltip and accessibility value list `"<Bot>: <detail>"` per member, one line each (`Components.swift:93-102`).
+
+Where the dot appears: sidebar rows (10 pt with a 2 pt ring in the window colour; `SidebarView.swift:147-158`) and the title of separate conversation windows, where the ring is cut out of the picture with `destinationOut` so it reads over any wallpaper (`Components.swift:105-130`, `ConversationWindow.swift:128-143`).
+
+**Needs attention.** "Attention" is not a separate state: it is `phase == failed`, usually with a typed failure. The person sees a red dot; the direct conversation's context menu shows Kick only while failed (`SidebarView.swift:118-123`); Settings shows a badge on the Harness tab counting harnesses with a failed, kickable bot (`NoodleSettingsView.swift:20-27`). Kick restarts at once unless the failure needs consent, in which case it returns an `AgentKickRequest` and an alert asks first (`AgentRuntimeCoordinator.swift:52-95`, `732-761`; `Sources/NoodleRuntimeSettings/AgentKickConfirmation.swift:6-40`):
+
+| Failure | Alert title | Confirm button | Extra |
+|---|---|---|---|
+| `missingSession` | Recover <Bot>? | Recover Bot | |
+| `usageLimit` | Usage limit reached | Retry Now | |
+| `authenticationRequired` | Sign in to reconnect <Bot> | Retry Now | "Open Harness Settings" button |
+| `recoveryFailed` | Retry recovery? | (restarts without asking) | |
+| `safetyStop` | Safeguards stopped <Bot> | Resume | "New Session" button |
+
+The confirmation is valid only for the same lifecycle, runtime id, failure and access mode (`AgentRuntimeCoordinator.swift:745-751`); the Hub mirrors this with a one-time `confirmationID` (`LinkProtocol.swift:1310-1330`). A sign-in failure also posts a system notification once per episode, even while Noodle is in front, replacing the previous one by identifier `sign-in-<agentID>` (`AgentRuntimeCoordinator.swift:1076-1078`, `Sources/Noodle/NoodleNotifications.swift:80-99`).
+
+There are no in-chat approval prompts. Tool, command and file-change approvals requested by a harness are answered automatically by policy: accepted only when the bot has extended (unrestricted) access, declined otherwise; "request user input" is answered with no answers (`Sources/NoodleCore/AgentAccess.swift:111-133`, `Sources/NoodleRuntime/ACPAgentProcess.swift:245-250`). A harness that insists on interactive approval is stopped with a failure to kick (`MuseAgentProcess.swift:267-276`). A bot that needs a decision asks in the conversation like anyone else.
+
+**Message delivery mode (interrupting a working bot).** Settings choose `automatic | immediate | queue` (`MessageDelivery.swift:3-18`). Wakes are coalesced into one pending notification per bot (`MessageDelivery.swift:22-45`). In automatic mode, while the bot is working, the router reads the last four unread messages without consuming them; an obvious stop request ("stop", "wait", "hold on", "pause", "cancel", "abort", "don't", or a punctuated "no") interrupts at once; otherwise an on-device model classifies each message and any of stop, correction, challenge, answer or emergency interrupts the current turn, within a 60 s deadline (`MessageDelivery.swift:49-114`, `MessageDeliveryRouter.swift:41-94`, `MessageDeliveryClassifier.swift:35-56`).
+
+**Heartbeats and session rollover.** An idle, ready bot gets a `heartbeat` wake after 30 minutes without activity (1-1,440 minutes, per-bot opt-out; one overdue heartbeat, never a burst) (`AgentHeartbeat.swift:3-86`, `AgentRuntimeCoordinator.swift:431-439`). Sessions older than a day that have been idle an hour are replaced with a fresh one (`AgentSessionRollover.swift:5-31`, `AgentRuntimeCoordinator.swift:772-792`). Optionally, the Mac is kept from idle sleep while any bot is working (`Harnesses.swift:321-328`).
+
+**Activity log (the only streaming surface).** Each bot has a bounded log: at most 500 entries and 256 KiB, details capped at 16 KiB, control characters stripped (`AgentActivityLog.swift:35-101`). An event is `{ title, detail, streamID?, appending }`; an event with a `streamID` updates the last entry with that id, appending or replacing its detail, which is how token deltas coalesce into one entry; every phase/detail change is itself recorded as an entry and ends all stream coalescing (`AgentActivityLog.swift:50-82`). Per-harness parsers map protocol messages to titles such as "Output", "Reasoning summary", "Running command" / "Command completed (exit 0)", "<tool>: started|completed", "Files changed", "Searching", "Plan" (`AgentActivityParser.swift:7-179`). The window polls the log's `revision` every 0.2 s and patches only the changed tail of its text (`Sources/NoodleRuntimeSettings/AgentActivityWindow.swift:93-114`, `254-276`).
+
+### 2.5 Unread, notifications, badges and sidebar ordering
+
+**Unread** is a `Set<UUID>` of conversations, persisted to `conversation-state.json` (`NoodleStore.swift:76-78`, `WorkspaceRepository.swift:84-98`). It is set when the poll finds a new message authored by a bot, unless that conversation is being viewed; system messages, user messages and reactions never mark a conversation unread (`NoodleStore.swift:1934-1941`, `2129-2148`). "Viewing" means the app is active and some conversation window showing it is visible, not minimised and not occluded (`ConversationWindow.swift:226-232`); a message that arrives while viewed is shared as read to other devices. It is cleared by: selecting the conversation (`SidebarView.swift:49-51`), the window becoming key (`ChatView.swift:44-46`, `140-141`), a tap in the chat (`ChatView.swift:43`), composer focus (`ChatView.swift:50-52`), scrolling the transcript (`ChatView.swift:523`), any draft change (`NoodleStore.swift:94-97`), sending, and archiving (`NoodleStore.swift:695-699`). Another device's read clears it only if no bot wrote after that read (`NoodleStore.swift:1567-1574`). The Hub keeps a monotonic per-conversation read mark set by message id, "since a date that crossed the link may no longer match", and computes unread counts from it (`LinkProtocol.swift:1298-1308`, `Sources/HubCore/HubBots.swift:991-1010`); mobile keeps a `seen[conversationID]` date and calls a conversation unread when its newest bot message is later (`Chats.swift:228-246`).
+
+**Badges and notifications.** The Dock badge is the number of unread conversations, not messages (`NoodleStore.swift:1521-1525`). For each new bot message a notification is posted only when Noodle is not active or has no visible window: title the bot name, subtitle the group name in groups, body the preview text, identifier the message id, the bot's avatar attached (`NoodleNotifications.swift:21-78`, `NoodleStore.swift:2158-2179`). When notifications are not presented, the app plays the chosen receive sound itself (default "Blow"; `MessageReceivedSound.swift:5-28`). Opening a notification selects the conversation and scrolls to the message, or to the bottom when it is the newest (`NoodleNotifications.swift:153-170`). Errors are a single `errorMessage` string on the store, shown as an alert in the key window (`NoodleStore.swift:115`, `ConversationWindow.swift:146-160`).
+
+**Sidebar.** Three sections, each hidden when empty: Pinned (in pin order), Bots (direct conversations) and Groups (`SidebarView.swift:20-24`, `NoodleStore.swift:495-509`). Within a section the order is the store's `conversations` order, which is `updatedAt` descending (`WorkspaceRepository.swift:809-813`; re-sorted after each send, `NoodleStore.swift:1468-1471`). The list excludes archived conversations and filters by the selected space (All, This Mac, a Hub, or a custom space with its own pins) and by search over title, group description, participant names and every message body (`NoodleStore.swift:463-493`). A row shows the avatar with its runtime dot, the title, a time (today) or abbreviated date, a two-line preview of the last message (or "No messages yet"), and a blue 8 pt unread dot in the leading inset (`SidebarView.swift:141-217`, `NoodleStore.swift:2181-2192`). Mobile uses one list: pinned first, then by the newest message time, falling back to creation time; Hub pins order by `pinnedAt` (`Chats.swift:304-317`, `348-351`). On mobile a pinned bot's bubble shows the start of an unread reply, else its status line (`Chats.swift:507-514`).
+
+### 2.6 How the UI observes state, and performance tactics
+
+- `NoodleStore` and `AgentRuntimeCoordinator` are `@MainActor @Observable`; everything SwiftUI should not track (tasks, caches, controllers, transcript revisions) is `@ObservationIgnored` (`NoodleStore.swift:30-32`, `127-181`; `AgentRuntimeCoordinator.swift:97-196`). Views read the store from the environment and call it directly; there is no reducer layer.
+- The poll copies the current state, loads a snapshot on a detached utility task, and compares per-conversation revisions (`messages.json` modification time and size, the Attachments folder's modification time), reloading only changed transcripts (`NoodleStore.swift:1838-1922`).
+- A `transcriptGeneration` counter, bumped by any local write to messages or attachments, makes a background snapshot that finished after a local change discard itself (`NoodleStore.swift:49-59`, `1855`).
+- New bot messages are computed by diffing message ids against the known set, then drive four effects in order: heartbeat activity, waking other group members, unread, notifications (`NoodleStore.swift:1928-1970`).
+- An id-keyed attachment lookup is rebuilt whenever the attachments dictionary changes (`NoodleStore.swift:52-58`, `1581-1584`).
+- Caches: rendered Markdown and table segments keyed by message id (with a body check), and link detection keyed by body text, both `NSCache` with 1,000 entries (`MessageMarkdownCache.swift:6-56`, `Components.swift:157-181`).
+- The draft is read only inside the composer's own views, so typing re-evaluates the composer and not the transcript (`ChatView.swift:381-382`). `TranscriptRenderProbe` counts bubble bodies and link scans so tests can assert this (`Components.swift:132-155`); tests cover "typing in the composer does not reevaluate transcript rows", "adding a reaction does not resize its transcript row", "a long conversation holds only its newest messages as it grows" and "reevaluated transcript rows do not detect their links again" (`Tests/NoodleAppTests/TranscriptLayoutTests.swift:288`, `346`, `360`, `383`).
+- The transcript shows the newest 100 messages and adds 100 more each time the top is reached; rows are keyed by message id so a page load keeps the reading position, and later replies add rows instead of pushing old ones out (`ChatView.swift:486-562`). Rows sit in a `LazyVStack`; attachment thumbnails and link previews load only when a row is visible (`Components.swift:315-317`).
+- Scroll position is saved at the end of a user scroll gesture, not per pixel, as `{ offset, isAtBottom, messageID }`; the view follows new messages only while at the bottom, and always after the user sends (`TranscriptScrollView.swift:21-26`, `138-167`).
+- The whole transcript is rebuilt with `.id(conversation.id)` and no animation on a conversation switch (`ChatView.swift:196-211`).
+- Editing a bot's settings is two-phase: a checkpoint copies every app-owned settings file, all writes happen, and on any error the checkpoint is restored; only after every write succeeds is the in-memory state published and the bot restarted (`AgentSettingsCheckpoint.swift:4-50`, `NoodleStore.swift:906-962`).
+
+### 2.7 Groups: several agents in one conversation
+
+- **Membership.** A group lists `participantIDs` (at least one bot, unique, all from the same place: this Mac or one Hub; sorted by UUID string, so its avatar shows effectively arbitrary members first) (`WorkspaceRepository.swift:611-639`, `NoodleStore.swift:1145-1149`; avatar of the first three, `Components.swift:42-60`).
+- **Who is woken.** Every participant is woken for every user message (`NoodleStore.swift:1474`) and every other participant for every bot message in a group (`WorkspaceRepository.swift:1387-1404`, `NoodleStore.swift:2115-2127`); reactions wake as described in section 2.3. Direct conversations never wake anyone on a bot message.
+- **Addressing.** Nothing routes by name. `@` in the composer opens a completion of all active bots, the group's members first, plus people the bots are shared with; choosing one inserts the plain name, removing the `@` (`AgentNameCompletion.swift:3-49`, "A plain-text editing operation, not a message mention or delivery primitive"; `ChatView.swift:434-437`). A bot's profile sheet "Reply" prefixes the draft with `"Name, "` (`ChatView.swift:118-120`, `349-351`).
+- **Turn-taking.** None in code. Each woken bot reads the delivery, the named `participants` roster (with public descriptions and `lastActiveAt`, the time of its latest message in that conversation, `WorkspaceRepository.swift:1262-1300`) and decides itself whether to answer. Loops are discouraged only by the Messenger skill: system notices and reactions are "not a new request", "do not send routine acknowledgements or create reply loops", and reactions carry work status (eyes = received, hourglass = working, check mark = done) (`MessengerDocumentation.swift:16-35`).
+- **Changes.** Adding or removing members or changing the description appends one system message combining the changes ("Ada and Kai were added to the group.", "The group description was updated: …") in the same transaction; creating, renaming or deleting a member bot produces none (`WorkspaceRepository.swift:663-778`, `MessengerDocumentation.swift:69-115`). New members' inbox offsets start at the current end of history, so they see only the notice and later messages unless they list history explicitly (`WorkspaceRepository.swift:703-716`).
+- **Shared folders.** A group can share folders with its bots; changes restart the affected bots (`NoodleStore.swift:1151-1154`, `1233`).
+- **Presentation.** On the Mac every bot message shows that bot's 27 pt avatar (`Components.swift:255-274`). Mobile shows the bot's name heading each run of its messages and its avatar beside the last of each run (`Chats.swift:516-534`).
+
+### 2.8 Persistence
+
+Root: `~/Library/Application Support/Noodle` in the sandbox container (`Sources/NoodleCore/HarnessSetup.swift:67-73`).
+
+| Path (under root) | Contents |
+|---|---|
+| `Agents/<id>/agent.json` | `AgentRecord` plus private configuration (`AgentConfiguration.swift:36-60`) |
+| `Agents/<id>/workspace/` | the bot's working directory: generated `AGENTS.md` (`CLAUDE.md` links to it), `preferences.md`, `memory.md`, `.agents/skills/messenger/`, `.noodle/inbox.json`, `.noodle/messenger-bridge/` (`WorkspaceRepository.swift:278-314`, `1099-1117`) |
+| `Agents/<id>/runtime/<harness>-runtime[-extended].json` | harness session state; `.unfinished` marks an interrupted turn (`AgentStorageLayout.swift:19-32`, `AgentTurnRecovery.swift:3-37`) |
+| `Conversations/<id>/conversation.json`, `messages.json`, `.messages.lock` | conversation and transcript |
+| `Conversations/<id>/Attachments/<id>.<ext>`, `<id>.json` | attachment files and metadata |
+| `Conversations/<id>/background.json`, `Backgrounds/` | wallpaper choice and media |
+| `Conversations/<id>/effects.json`, `.effects.lock` | effect queue, at most 32 events, 64 KB |
+| `conversation-state.json` | `{ version: 1, unreadConversationIDs }` |
+| `pinned-conversations.json` | `{ version: 1, conversationIDs }` in pin order |
+| `scroll-positions.json`, `conversation-windows.json` | per-conversation viewport and window frames |
+| `spaces.json`, `spaces-sync.json` | custom spaces and their iCloud sync state |
+| `usage.sqlite` | usage ledger |
+| `Hubs/` | joined Hubs and their mirrors |
+
+Writes are JSON with sorted keys and ISO 8601 dates, replaced atomically (`WorkspaceRepository.swift:1529-1540`). Messages, reactions and group changes take an exclusive `flock` per conversation (`WorkspaceRepository.swift:1542-1550`). Preferences and runtime bookkeeping live in `UserDefaults`: heartbeat settings and last-activity dates, session start dates, delivery mode, selected space (`Noodle.space`), floating windows, keyboard shortcuts (`AgentHeartbeat.swift:20-33`, `AgentRuntimeCoordinator.swift:414-417`). Drafts, runtime snapshots and activity logs are memory only on the Mac (`ConversationDrafts.swift:3-4`); mobile persists drafts, unsent messages and a cache of everything it shows (`Chats.swift:212-223`, `656-670`).
+
+### 2.9 The Hub link protocol shared with mobile
+
+`LinkProtocol` is the closest thing to a ready-made wire contract. Requests travel in an envelope `{ version, fetchesPictures, request }`; adding requests, events or fields keeps the version, every later field decodes with a default, and unknown events are skipped (`LinkProtocol.swift:6-87`). Dates are seconds since 1970 on this wire (`LinkProtocol.swift:76-86`), unlike the ISO 8601 files. Files travel as 512 KiB chunks, uploaded before the message that names them (`LinkProtocol.swift:13-14`, `HubMirror.swift:743-765`).
+
+- Requests include `bots`, `createBot/updateBot/deleteBot`, `groups`, `createGroup/updateGroup/deleteGroup`, `archive`, `kick`, `confirmKick`, `newSession`, `messagePage {conversationID, before?, after?, limit=50}`, `send {conversationID, id, body, attachmentIDs}` with a device-chosen `id` so a retried send is never doubled, `upload`, `download`, `react {conversationID, messageID, emoji, present}`, `markRead {conversationID, messageID}`, `pin`, `setBackground`, `startCall`, and a `subscribe` that opens the event stream (`LinkProtocol.swift:89-231`, `1526-1549`).
+- Events are mostly invalidations plus a few values: `conversationChanged {conversationID, count}`, `botsChanged`, `groupsChanged`, `messageChanged {message}` (reactions, a finished call card), `botPhase {botID, phase}`, `readChanged {conversationID, upTo}`, `pinChanged {conversationID, pinnedAt?}`, `backgroundChanged`, and resource-list changes (`LinkProtocol.swift:578-613`). The Hub emits them by diffing file sizes, counts and reaction sequences on each check, routed per person (`Sources/HubCore/HubBots.swift:927-975`).
+- `LinkMessage` flattens the message: author `you | bot(id) | system`, `delivered: Bool`, attachments inline, reactions without ids (`LinkProtocol.swift:1336-1406`). `LinkBot` carries `phase`, `readUpTo`, `status`, `archivedAt`, `background`, `sharedWith`, `owner`, `canCall`, `pinnedAt` beside the editable draft (`LinkProtocol.swift:1149-1214`).
+- Client sync: follow the stream with exponential reconnect (1 s doubling to 60 s), on connect re-sync everything, page messages after the last synced position, and re-read from the first user message not yet delivered (or call still running) so later delivery flags are picked up (`HubMirror.swift:493-556`, `684-727`).
+- Mobile's optimistic send is the pattern a web client should copy: insert the message at once with its client id, keep it and its files locally, retry after pauses of 0, 2, 5 and 15 s only while it is still the newest message, settle when the server's copy arrives, and offer try again, take back (into the composer) or delete for a failed one (`Chats.swift:656-783`).
+
+### 2.10 The Scenario format
+
+A scenario is `Scenarios/<name>/scenario.json`, replayed through the real repository with stub harness processes, in development builds only, inside an isolated bundle (`com.pdparchitect.noodle.scenarios`) whose preferences and data folder are wiped on each launch (`Scenario.swift:11-13`, `913-915`, `1421-1428`). Loading is strict: any key that does not survive decode and re-encode is an error, "so a typo cannot silently change a screenshot" (`Scenario.swift:351-364`, `1621-1637`).
+
+```ts
+interface ScenarioFile { // Scenario.swift:13-304
+ version: 1;
+ title: string;
+ clock?: string; // "HH:mm" today; default = wall clock
+ appearance?: 'dark'; // "Noodle is dark only" (Scenario.swift:445)
+ settings?: Partial<Record<'chatAttachmentLayout' | 'BotNameStyle' | 'Noodle.firstBotSetup.dismissed'
+ | 'Noodle.composer.showBotDescriptions' | 'Noodle.floatingConversations.keepsOne', boolean | number | string>>;
+ harnesses: Record<HarnessProvider /* not 'apple' */, { models: 'builtin' /* claude-code only */ | ScenarioModel[] }>;
+ agents: ScenarioAgent[];
+ conversations?: ScenarioConversation[];
+ present?: Presentation;
+ timeline?: Step[];
+ film?: Film;
+}
+interface ScenarioModel { id: string; name: string; description?: string; efforts?: string[]; defaultEffort?: string; default?: boolean }
+interface ScenarioAgent {
+ key: string; // unique, not "user"
+ name: string; harness: HarnessProvider; model?: string; effort?: string;
+ description?: string; backstory?: string;
+ avatar?: { image?: string; tint?: 'white' | 'black'; symbol?: string; colour?: number };
+ status?: ScenarioStatus; // its status the first time it starts
+ unrestricted?: boolean; // extended access
+ autoReplies?: string[]; // answers cycled after the timeline ends
+}
+interface ScenarioStatus {
+ phase: AgentRuntimePhase;
+ detail?: string; // required when failed
+ failure?: 'missingSession' | 'usageLimit' | 'authenticationRequired' | 'recoveryFailed'; // failed only
+}
+interface ScenarioConversation {
+ key: string;
+ direct?: string; // agent key; exactly one of direct | group
+ group?: { name: string; description?: string; members: string[] };
+ background?: { preset?: 'sunset' | 'ocean' | 'forest' | 'dusk'; image?: string; video?: string }; // exactly one
+ unread?: boolean;
+ pinned?: boolean; // pinned in listing order
+ messages?: { key?: string; at: string; from: 'user' | string; text: string;
+ delivery?: MessageDelivery; // user: saved | delivered | failed; bots: delivered only
+ attachments?: { file?: string; link?: string }[]; // exactly one of file | link
+ reactions?: { from: 'user' | string; emoji: string }[] }[];
+}
+interface Presentation {
+ window?: { size: [number, number]; origin?: [number, number] };
+ sidebar?: 'visible' | 'hidden';
+ select?: string; search?: string; draft?: string; draftAttachments?: string[]; // a draft needs select
+ scroll?: Record<string /* conversation key */, 'bottom' | string /* message key */>;
+ windows?: { conversation?: string; frame?: [number, number, number, number]; floating?: boolean;
+ activity?: string /* agent key */; settings?: string /* tab */ }[]; // exactly one target each
+ sheet?: { newBot?: boolean; newGroup?: boolean; editBot?: string; groupInfo?: string; background?: string }; // at most one
+}
+interface Step { // exactly one action, or only a wait
+ wait?: number; agent?: string; in?: string;
+ status?: ScenarioStatus; // stub process reports this snapshot
+ reply?: Content; // bot message via sendAgentMessage
+ say?: Content; // user message, wakes participants
+ type?: Content & { interval?: number }; // typed into the composer then sent
+ react?: { message: string /* message key */; emoji: string; remove?: boolean }; // by agent, else by user
+ stream?: { text: string; chunk?: number; interval?: number }; // into the bot's activity log
+ toolCall?: { title?: string; input: string; output?: string; exit?: number; duration?: number }; // activity log
+ error?: string; // sets store.errorMessage
+ focus?: 'composer' | 'transcript' | 'none'; // camera cue for recordings
+ waitFor?: 'userMessage' | 'key';
+ present?: Presentation;
+ capture?: string; // screenshot name, no spaces or slashes
+}
+interface Content { key?: string; text: string; attachments?: { file?: string; link?: string }[] }
+interface Film {
+ background?: 'black' | 'white' | string; // or an asset / URL behind the titles
+ intro?: { icon?: string; iconTint?: 'white' | 'black'; kicker?: string; title?: string; subtitle?: string; hold?: number };
+ outro?: { tagline?: string; hold?: number };
+}
+```
+
+Times use a small grammar: `"HH:mm"` on the scenario day, `"-2d HH:mm"`, `"-15m"`, `"-3h"` relative to the clock (`Scenario.swift:1592-1618`). Media paths are assets in the scenario folder, shared assets under `Scenarios/cast/`, or web addresses that a script pre-fetches into `.cache/` named by the first 16 hex characters of their SHA-256 (`Scenario.swift:378-411`).
+
+**Seeding** (`Scenario.swift:684-790`): preferences are applied and the delivery mode forced to `queue`; each harness gets a stub executable laid out as a Noodle-installed harness; bots are created through the real repository seven days before the clock, one minute apart, with avatar colour defaulting to their index; groups are created, messages appended with their reactions, backgrounds set; unread and pinned files written; every bot's inbox is consumed so seeded history does not wake anyone (`Scenario.swift:761`); scroll positions and window frames are written as the app would restore them; and anything the format does not model is copied over the repository from the scenario's `root/` folder.
+
+**Playing**: a `ScenarioAgentProcess` stands in for every harness and only reports the scripted snapshot (default details per phase: "<Harness> ready", "Checking for new messages", "Starting <Harness>", "Stopped") (`Scenario.swift:649-668`, `796-842`). When it is notified and a user message is waiting, it records an arrival, which releases `waitFor: userMessage`; after the timeline ends, `autoReplies` answer with 1.5 s of `working` first (`Scenario.swift:951-969`). Steps run in order after their `wait` (`Scenario.swift:973-1145`); `type` sets the draft one character at a time with jittered intervals (default 0.075 s times 0.55-1.65) and sends what is staged in the composer too; `stream` appends chunks of 12 characters every 0.05 s by default; `toolCall` writes "Running command" then "Command completed (exit N)" after 0.8 s by default, plus "Tool output". A capture run talks to the driving script over stdout: `SCENARIO READY rect=…`, `SCENARIO SHOT <name> id=<window> rect=x,y,w,h`, `SCENARIO FOCUS x,y,w,h <seconds> steady|eased <epoch>`, `SCENARIO SOUND key|enter|reply <epoch>`, `SCENARIO DONE`, `SCENARIO FAILED <message>`; a newline on stdin answers a shot or advances a `waitFor: key` (`Scenario.swift:1155-1256`, `1327-1348`). The film wraps the timeline in fixed-timing title cards with an animated wordmark (`Scenario.swift:983-1039`, `ScenarioFilm.swift:14`, `151-190`, `330`).
+
+## 3. Web translation
+
+### 3.1 Wire types
+
+Per the OpenCompany convention, payload keys on the wire are snake_case and the TypeScript side binds them to camelCase locals (`CLAUDE.md`, "Naming Conventions"). The wire shapes below are the section 2.2 entities with snake_case keys, plus these changes:
+
+```ts
+type AuthorWire = { kind: 'user' } | { kind: 'agent'; agent_id: string } | { kind: 'system' }; // flat, not "_0"
+type DeliveryWire = 'sending' | 'queued' | 'delivered' | 'failed'; // 'sending' and 'failed' are client-side only
+
+interface MessageWire {
+ id: string; // client-chosen for user sends (idempotency key)
+ conversation_id: string;
+ position: number; // index in the append-only log; paging cursor
+ author: AuthorWire;
+ body: string;
+ created_at: string; // ISO 8601 with milliseconds
+ delivery: 'queued' | 'delivered';
+ attachments: AttachmentWire[]; // inline, as LinkMessage does
+ reactions: { author: AuthorWire; emoji: string }[];
+ call?: { agent_id: string; ended_at?: string; lines: { speaker: 'person' | 'bot'; text: string; at?: string }[] };
+}
+
+interface AgentRuntimeWire {
+ agent_id: string;
+ phase: 'offline' | 'starting' | 'ready' | 'working' | 'failed';
+ detail: string;
+ failure?: { kind: 'missing_session' | 'usage_limit' | 'authentication_required' | 'recovery_failed' | 'safety_stop';
+ session_id?: string } | null;
+ reconnecting_since?: string | null;
+ can_kick: boolean; // computed server-side, as Harnesses.swift:302
+ conversation_id?: string | null; // new: the conversation the current turn serves, when known
+}
+
+interface ActivityEntryWire {
+ agent_id: string; entry_id: string; date: string;
+ title: string; detail: string;
+ stream_id?: string; appending: boolean; // coalesce into the last entry with the same stream_id
+}
+```
+
+### 3.2 Store shape
+
+Server state, in TanStack Query:
+
+| Query key | Holds | Kept fresh by |
+|---|---|---|
+| `['agents']` | `AgentRecord[]` (public fields, status line, archived) | `agent_changed`, `agent_removed` |
+| `['conversations']` | `BotConversation[]` sorted by `updated_at` desc | `conversation_changed`, `message_appended` (bump and re-sort) |
+| `['messages', conversationId]` | infinite query, pages of 100 by `position` (`before` cursor), newest page first | `message_appended` (append to the last page), `message_changed`, `messages_delivered` |
+| `['unread']` | `Set<conversationId>` | `unread_changed` |
+| `['pins', spaceId]` | ordered ids | `pin_changed` |
+| `['spaces']` | `CustomSpace[]` | `spaces_changed` |
+| `['backgrounds']` | per-conversation background | `background_changed` |
+| `['harnesses']` | installations, models, capability errors | `harnesses_changed` |
+| `['usage', range, agentId]` | usage days | on demand |
+
+Push state, in Zustand with per-key selectors (the same slice-subscription idea as OpenCompany's `nodeStatusStore`): `runtime: Record<agentId, AgentRuntimeWire>` (high frequency, latest value wins, replaced wholesale on reconnect) and `activity: Record<agentId, { entries: ActivityEntryWire[]; revision: number }>` for subscribed bots only, bounded like Noodle's (500 entries, 256 KiB).
+
+UI state, in Zustand (persist only what Noodle persists, plus drafts):
+
+```ts
+interface UiState {
+ selectedConversationId: string | null;
+ searchText: string;
+ space: string | null; // persisted, like UserDefaults "Noodle.space"
+ drafts: Record<string, { text: string; attachmentIds: string[] }>; // persist (Noodle loses them on quit)
+ viewports: Record<string, { offset: number; isAtBottom: boolean; messageId?: string }>; // persist
+ pending: Record<string, { conversationId: string; reason?: string; attempts: number }>; // unsent sends
+ creationSheet: 'bot' | 'group' | null;
+ editingAgentId: string | null; editingGroupId: string | null; editingBackgroundId: string | null;
+ kickRequest: KickConfirmation | null;
+ toasts: { id: string; message: string }[]; // instead of one errorMessage slot
+}
+```
+
+Derived selectors (direct ports of the Swift):
+
+```ts
+export function conversationStatus(phases: AgentRuntimeWire['phase'][]): 'working' | 'failed' | 'ready' | 'idle' {
+ if (phases.includes('working')) return 'working';
+ if (phases.includes('failed')) return 'failed';
+ if (phases.length > 0 && phases.every((p) => p === 'ready')) return 'ready';
+ return 'idle';
+}
+export const STATUS_DOT = { working: 'bg-status-working', failed: 'bg-status-failed', ready: 'bg-status-ready', idle: 'bg-status-idle' };
+// Noodle: blue / red / green / gray. Map through theme tokens, not palette names.
+
+export function shownParticipants(c: BotConversation, agents: Map<string, AgentRecord>): AgentRecord[] {
+ const all = c.participant_ids.map((id) => agents.get(id)).filter(Boolean) as AgentRecord[];
+ if (c.kind !== 'group') return all;
+ const active = all.filter((a) => !a.archived_at);
+ return active.length ? active : all;
+}
+
+export function sidebarSections(convs: BotConversation[], pins: string[], visible: (c: BotConversation) => boolean) {
+ const shown = convs.filter(visible); // archived, space and search filters
+ const byId = new Map(shown.map((c) => [c.id, c]));
+ const pinned = pins.map((id) => byId.get(id)).filter(Boolean) as BotConversation[];
+ const rest = shown.filter((c) => !pins.includes(c.id)); // already updated_at desc
+ return { pinned, bots: rest.filter((c) => c.kind === 'direct'), groups: rest.filter((c) => c.kind === 'group') };
+}
+
+export function deliveryLabel(m: MessageWire, pending?: { attempts: number; reason?: string }, sending?: boolean) {
+ if (sending) return 'Sending…';
+ if (pending) return 'Not delivered';
+ return m.delivery === 'delivered' ? 'Delivered' : 'Sent';
+}
+```
+
+Read tracking in the browser: treat a conversation as "viewed" when it is selected, `document.visibilityState === 'visible'` and the window has focus (the analogue of `ConversationWindow.swift:226-232`), and send `mark_read` with the newest message id on selection, focus, composer focus, scroll and draft change, as Noodle does. Keep unread server-owned so other devices agree.
+
+### 3.3 Event contract
+
+Server to client (push frames `{ type, data }`):
+
+| Type | Data | Client action | Noodle analogue |
+|---|---|---|---|
+| `runtime_snapshot` | `{ agents: AgentRuntimeWire[] }` on connect | replace runtime slice | `snapshots` dictionary |
+| `agent_runtime` | `AgentRuntimeWire` | set one slice | `onSnapshot` / `botPhase` |
+| `agent_changed` / `agent_removed` | `{ agent }` / `{ agent_id }` | patch `['agents']` | `botsChanged`, status via Messenger |
+| `conversation_changed` / `conversation_removed` | `{ conversation }` / `{ conversation_id }` | patch and re-sort `['conversations']` | `groupsChanged`, archive |
+| `message_appended` | `{ message: MessageWire, count }` | append; bump `updated_at`; sound or notification if a bot wrote and the chat is not viewed | `conversationChanged(count)` plus refetch |
+| `message_changed` | `{ message }` | replace by id | `messageChanged` |
+| `messages_delivered` | `{ conversation_id, message_ids }` | flip `delivery` | `markDelivered` |
+| `unread_changed` | `{ conversation_id, unread }` | patch `['unread']`; update the title badge | `registerUnreadMessages` |
+| `read_changed` | `{ conversation_id, up_to_message_id }` | mark read if nothing newer from a bot | `readChanged` |
+| `pin_changed` | `{ space_id, conversation_id, pinned_at }` | patch pins | `pinChanged` |
+| `background_changed` | `{ conversation_id, background }` | patch backgrounds | `backgroundChanged` |
+| `effect_queued` | `{ conversation_id, effect_id, kind, expires_at }` | if that chat is in front, `claim_effect` | `effects.json` |
+| `activity_entry` | `ActivityEntryWire` | coalesce by `stream_id` | `AgentActivityLog.record` |
+| `sign_in_required` | `{ agent_id, harness }` | toast or system notification, once per episode | `onSignInRequired` |
+| `harnesses_changed` | `{}` | invalidate `['harnesses']` | capability refresh |
+| `error` | `{ message, request_id? }` | toast | `errorMessage` |
+
+Client to server (request/response, each answered with the result or `{ error }`):
+
+| Type | Payload | Answer |
+|---|---|---|
+| `get_messages` | `{ conversation_id, before?, after?, limit }` | `{ messages, count, start }` |
+| `send_message` | `{ conversation_id, id, body, attachment_ids }` (idempotent by `id`) | `{ message }` |
+| `upload_attachment` | chunked `{ conversation_id, attachment, offset, data }` or HTTP multipart; staged before send | `{ attachment }` |
+| `discard_attachment` | `{ conversation_id, attachment_id }` | `{ done }` |
+| `react` | `{ conversation_id, message_id, emoji, present }` | `{ message }` |
+| `mark_read` | `{ conversation_id, message_id }` | `{ done }` |
+| `set_pinned` | `{ space_id, conversation_id, pinned }` | `{ done }` |
+| `create_bot` / `update_bot` / `delete_bot` | bot draft as `LinkBotDraft` (`LinkProtocol.swift:1068-1118`) | `{ agent }` |
+| `create_group` / `update_group` / `delete_group` | `{ name, public_description, bot_ids, folders? }` | `{ conversation }` |
+| `set_archived` | `{ id, archived }` | `{ done }` |
+| `kick` | `{ agent_id }` | `{ done }` or `{ kick_confirmation: { id, title, message, confirm_title, offers_new_session } }` |
+| `confirm_kick` | `{ agent_id, confirmation_id }` | `{ done }` |
+| `new_session` | `{ agent_id }` | `{ done }` |
+| `subscribe_activity` / `unsubscribe_activity` | `{ agent_id }` | `{ entries, revision }` |
+| `claim_effect` | `{ conversation_id }` | `{ effect }` or `{ effect: null }` (atomic, never replays) |
+| `set_background` | `{ conversation_id, preset? , media_id? }` | `{ background }` |
+| `set_delivery_mode` | `{ mode: 'automatic' | 'immediate' | 'queue' }` | `{ done }` |
+
+### 3.4 A JSON fixture format for demos, Storybook and visual regression
+
+Reuse Noodle's schema almost verbatim, so its scenarios can be ported by hand, with three web adjustments: `present.window` becomes `present.viewport: [width, height]`; `present.windows` keeps only `activity` (open the activity drawer) and `settings` (open a settings tab); and `film` is optional chrome for marketing recordings. Validate with a `.strict()` zod schema so unknown keys fail exactly as `Scenario.load` does, and keep the time grammar.
+
+Run a fixture through an in-memory fake of the WebSocket server (inject the transport into the WebSocket provider) rather than mocking hooks, so the real store, query cache and selectors are exercised:
+
+| Fixture element | Fake server behaviour |
+|---|---|
+| `agents`, `conversations` | seed the fake database; consume every bot inbox so history wakes nobody |
+| `clock` | freeze `Date` at the clock; `now = clock + elapsed`, as `ScenarioSession.now` |
+| `agents[].status` | first `runtime_snapshot` |
+| `step.status` | emit `agent_runtime` |
+| `step.reply` | append a bot message, emit `message_appended` |
+| `step.say` | append a user message, emit `message_appended`, "wake" its participants |
+| `step.type` | drive the composer through the UI store, then the real send path |
+| `step.react` | emit `message_changed` |
+| `step.stream`, `step.toolCall` | emit `activity_entry` with `stream_id` and `appending` |
+| `step.error` | emit `error` |
+| `step.present` | set UI store fields (selection, search, draft, sheet, viewport) |
+| `step.waitFor: userMessage` | resolve when the client sends `send_message` |
+| `step.waitFor: key` | pause until the Storybook "next step" control or a Playwright call |
+| `step.capture` | Playwright `toHaveScreenshot(name)` at that point |
+| `autoReplies` | after the timeline, answer each user message after 1.5 s of `working` |
+
+A minimal example:
+
+```json
+{
+ "version": 1,
+ "title": "A bot that needs attention",
+ "clock": "16:05",
+ "harnesses": { "claude-code": { "models": "builtin" } },
+ "agents": [
+ { "key": "rex", "name": "Rex", "harness": "claude-code", "model": "sonnet",
+ "status": { "phase": "failed", "failure": "usageLimit", "detail": "Usage limit reached. Kick to resume." } }
+ ],
+ "conversations": [
+ { "key": "rex", "direct": "rex", "background": { "preset": "dusk" },
+ "messages": [ { "at": "15:20", "from": "user", "text": "Sort the new reports." },
+ { "at": "15:26", "from": "rex", "text": "Sorted. Starting on the first one." } ] }
+ ],
+ "present": { "viewport": [1160, 810], "select": "rex" },
+ "timeline": [ { "capture": "01-usage-limit" } ]
+}
+```
+
+## 4. Patterns worth copying, and pitfalls to avoid
+
+Patterns worth copying:
+
+1. **Append-only transcript with positional cursors and client-chosen message ids.** Paging, resync and idempotent retries all fall out of it (`LinkProtocol.swift:1526-1579`, `Chats.swift:692-750`).
+2. **Delivery as "a bot has read it".** Per-bot inbox cursors make "Sent" versus "Delivered" honest and also give bots exactly-once reading (`WorkspaceRepository.swift:1119-1260`).
+3. **One snapshot per bot, typed failures, human detail.** UI decisions use `phase` and `failure`, never text; the `detail` sentence goes straight into tooltips (`Harnesses.swift:283-319`).
+4. **A tested precedence for folding many bots into one dot** (working, then failed, then all-ready, else idle).
+5. **Kick confirmations bound to the exact failure episode**, so a stale dialog cannot restart a bot that has since changed (`AgentRuntimeCoordinator.swift:745-751`).
+6. **Unread as a boolean per conversation, cleared by any interaction**, with cross-device reads keyed by message id and never moving backwards (`HubBots.swift:991-1003`).
+7. **Effects as an expiring queue claimed by the visible chat**, so reopening a chat never replays confetti and a background tab never consumes it (`ConversationEffects.swift:37-92`, `ConversationEffectsView.swift:28-80`).
+8. **Commit, then publish**: multi-resource bot edits are saved transactionally with rollback before the in-memory state changes (`AgentSettingsCheckpoint.swift`, `NoodleStore.swift:949`).
+9. **Generation counters for background loads** and **render probes in tests** to keep typing and reactions from re-rendering the transcript.
+10. **Activity kept apart from the conversation**: bounded, coalesced by stream id, never acknowledging messages, and opened on demand.
+11. **Strict fixture files with a relative time grammar**, seeded through the real write path, doubling as demo data, screenshot tests and film scripts.
+12. **Approvals by policy**, not by prompts in the chat: access is a per-bot setting and a bot that needs a decision asks in words.
+
+Pitfalls to avoid:
+
+1. **Polling files every second and rewriting the whole `messages.json` on every append and reaction** is O(n) per message. Use a database and push events (`NoodleStore.swift:2218-2233`, `WorkspaceRepository.swift:1090-1097`).
+2. **Count-only change events force a refetch**; send the appended message itself, as proposed above.
+3. **States that are never emitted**: `saved` and `failed` exist and are labelled but nothing sets them on the Mac. Define only states the server produces; keep "sending" and "failed" client-side.
+4. **Phase is per bot, not per conversation.** A bot working in one chat turns every chat it belongs to blue. Do not render a typing indicator from it unless the server says which conversation the turn serves (the proposed `conversation_id`).
+5. **Unbounded group fan-out.** Every bot wakes for every message, including each other's; only prompt text prevents loops. Add server-side guards (turn budgets, rate limits, quiet periods) before shipping groups.
+6. **Arbitrary member order.** Group participants are stored sorted by UUID; keep the user's order for avatars and lists.
+7. **Unexpected reordering.** Renaming a bot bumps its direct conversation's `updatedAt` (`NoodleStore.swift:1037-1042`), which moves it to the top of the sidebar.
+8. **One error slot.** `errorMessage` is overwritten by the next failure; use a queue of toasts.
+9. **Second-precision timestamps on disk** (ISO 8601 without fractions, inferred) make `createdAt` ties likely; order by position and use milliseconds on the wire. Pick one date encoding: the files and the Hub wire currently differ.
+10. **Swift enum encodings on the wire** (`{"agent":{"_0":…}}`) are awkward outside Swift; use flat discriminated unions.
+11. **Client-side search over every message body** does not scale past a few conversations; search on the server.
+12. **Memory-only drafts** are lost on quit; persist them, as mobile does.
+13. **A failed turn shows as `ready`** with a detail suffix ("ready — last task failed"), so the dot stays green after an error; consider a separate "last turn failed" flag.
+
+## 5. Open questions and inferences
+
+- Exact JSON for `MessageAuthor` and `AgentRuntimeFailure` on disk is inferred from Swift's synthesized `Codable` (no custom coding exists; the `_0` shape is asserted for other enums in `LinkCompatibilityTests.swift`). Uppercase UUIDs and second-precision ISO dates in the files are inferred from Foundation defaults.
+- Whether the Activity window is meant to stay a separate window or become part of the conversation view is a product question; the code keeps it separate and the films open it beside the chat (inferred from `Scenarios/code-review/scenario.json:71`).
+- How a web version should present "working": Noodle has no per-conversation signal. A turn-to-conversation mapping would need the runtime to report which inbox items a turn consumed (inferred to be feasible from `latestMessages`, which knows the conversations it returned).
+- The Hub's per-person routing of events (owner versus guests; guests receive phase but not the status line, `HubBots.swift:964-967`) matters if the web product becomes multi-user; this document did not trace Hub authorization.
+- Delivery-mode classification relies on Apple's on-device model; a web backend would need its own classifier or a simpler rule (the stop-phrase heuristic alone is portable).
+- Whether bots should be allowed to send effects in groups at the same rate as in direct chats (2 s per conversation, 30 s expiry) was not examined beyond the queue rules.
+- Sidebar recency on the Mac uses `updatedAt` while mobile uses the newest message time; a web version should pick one (the newest message time is less surprising).
diff --git a/docs-internal/research/noodle/analysis/08-mobile-ios.md b/docs-internal/research/noodle/analysis/08-mobile-ios.md
new file mode 100644
index 00000000..b509b7a4
--- /dev/null
+++ b/docs-internal/research/noodle/analysis/08-mobile-ios.md
@@ -0,0 +1,518 @@
+# Noodle Mobile: the iOS and iPadOS client
+
+Noodle Mobile (Mobile/VERSION 0.24.0, released 2026-10-07) is a SwiftUI app for iPhone and iPad that joins one or more Noodle Hubs and chats with the bots and groups kept there. It is built as an iOS 26 Messages clone: a single `NavigationStack` (no split view, even on iPad), a plain list with pinned bots as large circles, a full-bleed per-conversation wallpaper behind a transcript of opaque bubbles, a Liquid Glass composer that sits level with the system search field and is overlaid on the transcript rather than pushing it, a Messages-style long-press "lift" overlay for reactions and actions, and a plus button that morphs into a Camera/Photos/Files panel. Around the chat sit Hub management (pairing by QR, diagnostics, users, devices), bot and group editors, tool/computer/browser assignment, voice messages transcribed on device, WebRTC voice calls, live views of shared browsers and computers, noodlets (small web apps a bot builds) run on the phone or streamed from the Hub, a TV mode that turns the phone into a game controller, and privacy-preserving push notifications. The app uses no custom colour assets: the accent is system blue, surfaces are iOS semantic colours, and every size below is a SwiftUI point value (1 pt = 1 CSS px at the default zoom).
+
+Permalink base for every citation below: https://github.com/pdparchitect/noodle/blob/702339e3153025c9fe9582783caff7a19b48ff97/
+
+## 2. Scope
+
+**Sources read in full** (all of `Mobile/Sources/**`):
+
+| File | Lines | Covers |
+|---|---|---|
+| `Mobile/Sources/NoodleMobile/Chats.swift` | 2653 | Data model (`HubChats`), chat list (`AgentsView`), rows, pinned circles, chat screen (`ChatView`), bubbles, composer, bot and group editors, avatars |
+| `Mobile/Sources/NoodleMobile/HubScreens.swift` | 1102 | Join screen, pairing sources, Help Me Connect, Hubs, Hub details, Archived, Users, Pair Device, QR scanner, Settings |
+| `Mobile/Sources/NoodleMobile/HubTools.swift` | 849 | Tools/Computers/Browsers screens, New Tool catalogue, Custom MCP Server, Sharing, live surface screen, live-link kinds |
+| `Mobile/Sources/NoodleMobile/ChatContent.swift` | 845 | Attachments, attachment layouts, link previews, pending-file chips, composer text view, @-mentions, Shared sheet |
+| `Mobile/Sources/NoodleMobile/VoiceMessages.swift` | 662 | Recorder, recording bar, waveforms, voice-message player |
+| `Mobile/Sources/NoodleMobile/Calls.swift` | 563 | Call state, WebRTC audio, call bar, call card, transcript blocks, voice picker |
+| `Mobile/Sources/NoodleMobile/Appearance.swift` | 488 | `ConversationBackdrop`, `BackgroundEditor`, `BotPictureEditor`, `PersonAvatar`, `PersonPictureEditor` |
+| `Mobile/Sources/NoodleMobile/Noodlets.swift` | 332 | Noodlet player, on-device runner, sound, orientation lock |
+| `Mobile/Sources/NoodleMobile/ExternalScreen.swift` | 294 | TV output, TV button, controller list, TV game menu |
+| `Mobile/Sources/NoodleMobile/MessageActions.swift` | 219 | Message text, long-press overlay, unsent-message actions |
+| `Mobile/Sources/NoodleMobile/Notifications.swift` | 168 | CloudKit subscriptions, push registration, notification routing |
+| `Mobile/Sources/NoodleMobile/MessageTables.swift` | 157 | Table card and sortable table sheet |
+| `Mobile/Sources/NoodleMobile/WordmarkRefresh.swift` | 84 | Pull-to-refresh that draws the wordmark |
+| `Mobile/Sources/NoodleMobile/App.swift` | 61 | App entry, join-link alert |
+| `Mobile/Sources/Shared/ReplyNotifications.swift` | 81 | App group, push topics, notification content |
+| `Mobile/Sources/NoodleMobileNotifications/NotificationService.swift` | 37 | Notification service extension |
+
+Also read: `Mobile/README.md`, `Mobile/AGENTS.md` and `Mobile/CLAUDE.md` (as data: they say releases go through TestFlight, the Xcode project is generated by Tuist from `Project.swift`, and every user-visible change must add a "What to Test" entry to `CHANGELOG.md`), `Mobile/CHANGELOG.md` (0.1.0 to 0.24.0, used to confirm behaviour and dating), `Mobile/Project.swift`, and two tests that pin values (`Mobile/Tests/NoodleMobileTests/ComposerSizeTests.swift`, `MessageActionsTests.swift`). Shared code consulted only for values the mobile UI shows: `Shared/HubLink/Sources/HubLink/MessageTable.swift`, `Shared/HubLink/Sources/HubLink/LinkProtocol.swift`, `Shared/Wallpaper/Sources/NoodleWallpaperCore/ConversationBackground.swift`, `Shared/Surface/Sources/Surface/Gamepad.swift`, `Applet/Protocol/Sources/NoodletRuntime/Grants.swift`, `Applet/Protocol/Sources/NoodletFormat/Manifest.swift`. Mac counterparts for the comparison table: `Sources/Noodle/Components.swift`, `LongMessageText.swift`, `ChatView.swift`, `SidebarView.swift`, `TranscriptScrollView.swift`.
+
+**Screenshots viewed** (ground truth for appearance):
+
+| Screenshot | Shows | Caveat |
+|---|---|---|
+| `website/assets/mobile-chats.png` | Chat list, light mode: no title, blue `•••` top right, 8 rows with avatars, phase dots, relative times, chevrons | Predates 0.23.0: no "All" space title menu |
+| `website/assets/mobile-new-bot.png` | Bot editor sheet (editing "Hugo"): glass Cancel/Save capsules, 88 pt avatar with "Edit", grouped form | No navigation title (matches code); Kick/New Session section not visible |
+| `website/assets/mobile-new-tool.png` | New Tool sheet over the editor sheet: catalogue rows, floating bottom "Search tools" field | Row names render in tint blue |
+| `website/assets/mobile-game.png` | A noodlet game in portrait: black screen, Done and a glass Controls/Keyboard capsule, on-screen d-pad and round buttons | |
+| `.github/readme/mobile.png` | The four above side by side | |
+| `.github/readme/hero.png` | The same chat list beside the Mac app | Used for the Mac comparison |
+
+No screenshot shows the mobile conversation screen; everything about it below comes from code and the changelog.
+
+## 3. Findings
+
+### 3.1 Platform, shell and navigation
+
+**Platform.** iOS 26.0 minimum, Swift 6, destinations `.iOS` (iPhone and iPad), one app target plus a notification service extension sharing an app group (`Mobile/Project.swift:15`, `:40`, `:73-97`). `ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME` is empty, so the accent is system blue (`Project.swift:69`; changelog 0.5.0 "Apple's system blue"). Background audio mode is on so calls survive a locked screen (`Project.swift:53-54`). URL scheme `noodle` for `noodle://join-hub` invitations (`Project.swift:49`). Permission strings: camera "Noodle takes photos you send or use as your picture, scans the QR code of a Noodle Hub invitation, and noodlets you open use the camera when they ask."; local network "Noodle connects to your Noodle Hub on this network."; microphone "Record voice messages you choose to send, transcribed on this device, talk with bots on calls you start, and let noodlets you open listen when they ask." (`Project.swift:50-52`).
+
+**Root.** With no Hub joined the window shows `JoinView`; otherwise `AgentsView` for all joined Hubs (`App.swift:21-27`). An invitation link opened from outside the app asks first: alert "Join this Hub?", message "Hub key <fingerprint>", buttons "Cancel" / "Join" (`App.swift:30-37`); scanning or pasting inside the app joins straight away (changelog 0.4.0). The system pull-to-refresh spinner is made invisible app-wide (`UIRefreshControl.appearance().tintColor = .clear`, `App.swift:16`) because a custom wordmark replaces it.
+
+**No iPad layout.** There is no `NavigationSplitView`, no `horizontalSizeClass` check and no `userInterfaceIdiom` branch anywhere in the app; the only iPad awareness is copy ("Show on iPad", "Run on iPad" via `UIDevice.current.model`, `ExternalScreen.swift:80-81`, `HubTools.swift:693`) and `verticalSizeClass == .compact` to go full screen in landscape for live views (`HubTools.swift:663-666`, `Noodlets.swift:118`, `:138`). On iPad the list fills the screen and a conversation is pushed over it, with bubbles limited only by a 48 pt opposite-side spacer.
+
+**Navigation model.** One `NavigationStack` with a typed path of `ChatLink { hub: String, thread: UUID }` (`Chats.swift:904`, `:962`, `:1019-1023`, `:1251-1255`). Everything else is a modal: sheets (each with its own `NavigationStack` so sub-pages push inside them), fixed-height bottom sheets, and full-screen covers. A sheet chosen from another sheet opens only after the first is dismissed (`chosen` held, opened in `onDismiss`: `Chats.swift:917-918`, `:1039-1044`, `:1234-1243`; same pattern for pairing, `HubScreens.swift:80-81`, `:115-123`), so two sheets never animate at once.
+
+#### Screen inventory
+
+| Screen | Presentation | Reached from | Source |
+|---|---|---|---|
+| Join (wordmark + Pair) | Root | No Hub joined | `HubScreens.swift:11-67` |
+| Pairing sources | Bottom sheet, 244 pt (184 without camera) | Pair, Add Hub | `HubScreens.swift:425-475` |
+| QR scanner | Sheet, full bleed | Scan QR Code | `HubScreens.swift:1017-1048` |
+| Help Me Connect | Sheet | Join failure | `HubScreens.swift:235-351` |
+| Chat list | Root of stack | Joined | `Chats.swift:899-1244` |
+| More | Bottom sheet, 292 pt | `•••` | `Chats.swift:1259-1282` |
+| Conversation | Push | Row or circle tap, notification | `Chats.swift:1431-1892` |
+| Bot editor (new or edit) | Sheet | More > New Bot; chat title; row menu | `Chats.swift:2077-2354` |
+| Group editor | Sheet | More > New Group; title; menu | `Chats.swift:2387-2543` |
+| Shared-bot background | Sheet | Title or menu on a bot shared with you | `Chats.swift:2371-2384` |
+| Bot Picture | Push in editor | Avatar "Edit" | `Appearance.swift:203-308` |
+| Voice | Push in editor | Voice row | `Calls.swift:487-563` |
+| Tools / Computers / Browsers | Push in editor | Rows | `HubTools.swift:208-296` |
+| New Tool, Custom MCP Server | Sheet, then push | `+` in Tools | `HubTools.swift:478-638` |
+| New Computer / New Browser | Sheet | `+` in Computers/Browsers | `HubTools.swift:400-475` |
+| Sharing | Push in editor | Sharing row | `HubTools.swift:300-380` |
+| Background | Push in editor | Background row | `Appearance.swift:97-200` |
+| Hubs | Sheet | More > Hubs | `HubScreens.swift:517-584` |
+| Hub details (profile) | Push in Hubs | Row or info button | `HubScreens.swift:587-684` |
+| Your Picture | Sheet | Avatar in Hub details | `Appearance.swift:341-488` |
+| Archived | Sheet | Hub details | `HubScreens.swift:687-724` |
+| Users, user | Push | Hub details (admins) | `HubScreens.swift:727-903` |
+| Pair a Device / Invite | Sheet | Hub details, user | `HubScreens.swift:939-1004` |
+| Settings | Sheet | More > Settings | `HubScreens.swift:1051-1102` |
+| Message lift overlay | Full-screen cover, clear, self-animated | Long press on a bubble | `MessageActions.swift:87-219` |
+| Shared | Sheet | `…` in conversation | `ChatContent.swift:793-845` |
+| Live surface / noodlet | Full-screen cover | Live card, Shared | `HubTools.swift:641-779`, `Noodlets.swift:15-288` |
+| Web preview | Sheet (`SFSafariViewController`) | Link tap | `ChatContent.swift:346-352` |
+| Table | Sheet, medium/large | Table card | `MessageTables.swift:42-72` |
+| Transcript (voice), Call transcript | Sheet, medium/large | Long press voice; tap call block | `VoiceMessages.swift:641-654`, `Calls.swift:460-473` |
+
+### 3.2 Joining a Hub
+
+**Join screen.** The Noodle wordmark is stroked full screen at a word width of 220 pt in `.primary` with round caps and joins; once per launch it is "written" with `.easeInOut(duration: 3.4).delay(0.55)`, then the bottom controls fade and rise 12 pt with `.easeOut(duration: 0.5).delay(4.05)`; Reduce Motion shows both at once (`HubScreens.swift:24-31`, `:49-51`, `:54-65`). The only control is a full-width "Pair" (`.borderedProminent`, `.large`) in a 24 pt padded `VStack(spacing: 16)` at the bottom (`HubScreens.swift:32-49`).
+
+**Pairing sources** (bottom sheet, drag indicator, `VStack(spacing: 12)`, padding 24, `.large` controls): "Scan QR Code" (`qrcode.viewfinder`, prominent, only where the camera scanner is supported), the system paste control at 50 pt high (`UIPasteControl`, icon and label, capsule, tint foreground on a 15 % tint background), "Choose Photo" (`photo`, bordered). Heights 244 / 184 pt (`HubScreens.swift:425-475`, `:479-514`). The paste control exists because a paste the person starts is always allowed while reading the clipboard from code is refused.
+
+**While joining** the button area becomes a 50 pt capsule on `.fill.tertiary` with a spinner and "Connecting to <Hub>…" (scales down to 0.7), "Still trying…" fades in above it after 4 s, and "Cancel" sits below (`HubScreens.swift:143-169`). In the Hubs list the same state is a row: spinner, Hub name, "Connecting…" or "Still trying…", borderless Cancel (`HubScreens.swift:172-195`). Failure shows a red `exclamationmark.triangle` label, or, when no address answered, the message in secondary and a bordered "Help Me Connect" (`HubScreens.swift:198-232`).
+
+**Help Me Connect** probes each address kind in order and lists them under "Your Hub": "Home Wi-Fi", "Tailscale", "Internet", each answered by green `checkmark.circle.fill` "Answers" or secondary `xmark.circle` "No answer" (small spinner while checking). Then advice rows with their symbols: "You're offline. Connect to Wi-Fi or mobile data." (`wifi.slash`); "Noodle isn't allowed to look for your Hub on this network. Turn on Local Network for Noodle in Settings." (`lock`, with an "Open Settings" button); "Make sure you're on the same Wi-Fi as the Mac your Hub runs on." or "You're on mobile data. Join the same Wi-Fi as the Mac your Hub runs on." (`wifi`); "Away from that Wi-Fi? Open Tailscale and connect." (`point.3.connected.trianglepath.dotted`); "Your Hub answers now. Tap Try Again." (`checkmark.circle`); "Make sure the Mac your Hub runs on is awake and its Hub is open." (`desktopcomputer`). A prominent full-width "Try Again" is pinned in the bottom safe-area inset with 24 pt padding; "Done" top left (`HubScreens.swift:244-350`).
+
+### 3.3 Chat list (`AgentsView`)
+
+Anatomy on a 390 pt wide phone (values in points; sketch, not to scale):
+
+```text
++----------------------------------------------------------+
+| status bar |
+| All v ... | inline bar; title = space menu; plain tinted ellipsis
+| |
+| [note] [note] | note bubble 14 above the circle top
+| (76) (76) (76) | pinned circles: 3 columns, gap 12, row gap 16
+| Name Name Name | .caption, 1 line
+| | no separator under the circles or above row 1
+| o (48) Name Hub name 2 hr ago > | unread dot 10 at x = 8; row leading inset 26
+| preview, .subheadline secondary, 2 lines | HStack spacing 12, vertical padding 4
+| -------------------------------------------------| separator from the text column; none above row 1
+| (48) Name 1 day ago > |
+| ... |
+| [ Search ] | iOS 26: floating glass field (inferred placement)
++----------------------------------------------------------+
+```
+
+**Toolbar.** Inline title mode with no title string. The principal slot is the space menu: `Text(spaceTitle).font(.headline)` plus `chevron.down` at `.caption.weight(.semibold)` in secondary, `HStack(spacing: 4)` (`Chats.swift:1092-1120`). The trailing item is a plain tinted `ellipsis` ("More") with the iOS 26 shared glass background hidden, "as in Messages, not the round glass default" (`Chats.swift:1028-1034`). The screenshot shows the blue `•••` and no title.
+
+**Spaces menu**: a picker with "All", then one entry per joined Hub (by Hub name), then a second picker of spaces the person made, a divider, "New Space…" (`plus`), and for a custom space "Rename Space…" (`pencil`) and destructive "Delete Space" (`trash`). Naming uses an alert "New Space" / "Rename Space" with a "Name" field and "Cancel" / "Create" or "Rename" (disabled while blank); deleting asks "Delete <name>?" with "Its bots and groups stay in All." (`Chats.swift:1054-1068`). A space chosen elsewhere that no longer exists falls back to All (`Chats.swift:1122-1125`). Custom spaces sync through iCloud (`Chats.swift:910-912`, `:1073-1079`). A bot or group created while a custom space is shown joins it (`Chats.swift:1157-1161`).
+
+**More sheet**: four full-width `.bordered` `.large` buttons in `VStack(spacing: 12)`, padding 24, fixed detent 292 pt, drag indicator: "New Bot" (`person.badge.plus`), "New Group" (`person.2`), "Hubs" (`server.rack`), "Settings" (`gear`) (`Chats.swift:1259-1282`).
+
+**Pinned circles** (Messages-style): a `LazyVGrid` of 3 flexible columns, column spacing 12, row spacing 16, vertical padding 8 plus 8 more at the top when any of the first three carries a note, no separator (`Chats.swift:969-985`). Each circle is `VStack(spacing: 6)` of a 76 pt `ThreadAvatar` and the name in `.caption`, one line (`Chats.swift:1329-1353`). An unread mark is a 14 pt tint dot at the avatar's top-leading corner with a 2 pt `systemBackground` ring (`Chats.swift:1341-1347`). A note bubble hangs 14 pt above the avatar top: `.caption2` (semibold when it is an unread reply), padding 8 × 4, max width 104, one line, `.regularMaterial` capsule, shadow black 12 % radius 3 y 1 (`Chats.swift:1355-1375`). The note is the start of the latest unread bot reply (whitespace collapsed, tables removed) or else the status the bot set (`Chats.swift:507-514`). Tapping a circle opens the chat; touch and hold opens its menu (a `Menu` with `primaryAction`, because context menus on several cells of one list row all lifted the row and showed the first circle's menu, `Chats.swift:972-978`; changelog 0.13.0 fix).
+
+**Row anatomy** (`AgentRow`, `Chats.swift:1284-1322`; screenshot confirms):
+
+| Element | Value |
+|---|---|
+| Layout | `HStack(spacing: 12)`, vertical padding 4 |
+| Avatar | `ThreadAvatar` 48 pt with phase dot `max(8, 0.24 × size)` = 11.5 pt, 2 pt `systemBackground` ring, bottom-trailing |
+| Unread dot | 10 pt tint circle in the left margin, 8 pt from the avatar; the row's leading inset is `2 × 8 + 10 = 26` so the dot is 8 pt from the screen edge too (`Chats.swift:995`, `:1291`, `:1297-1301`) |
+| Line 1 | Name `.headline`, 1 line; Hub name `.caption` secondary when several Hubs are shown together; spacer; time `.subheadline` secondary, first-baseline aligned |
+| Time format | `.relative(presentation: .numeric, unitsStyle: .abbreviated)`: "2 hr ago", "1 day ago", "3 days ago" |
+| Line 2 | Last message preview (tables removed) or the bot's description when there are no messages; `.subheadline` secondary, 2 lines; `VStack(spacing: 2)` |
+| Accessory | Disclosure chevron (it is a `NavigationLink`) |
+| Separators | Hidden above the first row, visible between rows; start at the text column |
+
+The preview is not stripped of Markdown: the screenshot shows "The \*\*8\*\* carries the goo…" in raw form, because `previewText` only removes tables (`Shared/HubLink/Sources/HubLink/MessageTable.swift:54-59`).
+
+**Ordering.** Pinned first, then newest conversation first, where recency is the latest message's time or the bot's creation time (`Chats.swift:304-318`, `:348-351`). In All, pins belong to this phone (`pins.json`) and pinned items are ordered by recency; in a Hub's space the pins are the Hub's (`pinnedAt`, synced to all devices) and keep the order they were pinned in; in a custom space pins come first in pin order (`Chats.swift:329-341`, `:353-378`, `:1171-1188`). Bots and groups share one list with no section headers. Archived ones leave the list (`Chats.swift:269-279`).
+
+**Search.** `.searchable(prompt: "Search")` (`Chats.swift:1004`). A non-blank query hides the circles and shows one plain list of matches on name, description or any message body held on the phone, ignoring case and accents (`localizedStandardContains`, `Chats.swift:320-327`, `:963-967`). No results shows the system search empty state. On iOS 26 the field is a floating glass capsule at the bottom of the screen (visible in the New Tool screenshot; the chat-list screenshot does not show it, so its exact resting state there is inferred).
+
+**Swipe and touch-and-hold.** Leading swipe on an unpinned row: "Pin" (`pin.fill`) tinted orange; there is no trailing swipe and no delete from the list (`Chats.swift:996-999`). The touch-and-hold menu (same for rows and circles, `Chats.swift:1190-1216`): "Pin" (`pin.fill`) or "Unpin" (`pin.slash.fill`); submenu "Spaces" (`square.stack`) with a toggle per space, divider, "New Space…" (which creates the space with this conversation in it and shows it); then for your own bot or group "Edit Bot…"/"Edit Group…" (`pencil`) and "Archive Bot"/"Archive Group" (`archivebox`), or for a bot someone shared with you only "Change Background…" (`photo`).
+
+**Empty and loading states** (overlay): spinner while any Hub is loading; "Not Connected" (`wifi.exclamationmark`) with the error; "No Bots" (`bubble.left.and.bubble.right`) (`Chats.swift:1005-1017`).
+
+**Pull to refresh** writes the Noodle wordmark (word width 96 pt, stroked in `.primary`) progressively as the list is pulled; it is whole at 80 pt of pull and stays whole in the gap the refresh holds open until the reload finishes (`WordmarkRefresh.swift:14-83`). Used on the chat list, Hubs, Hub details, Users and Tools screens.
+
+**Data rules visible in the UI.** The last sync is cached and shown at launch before the Hub answers (`Chats.swift:96-126`). Each Hub is followed over a live event stream and reconnected 5 s after a failure (`Chats.swift:536-547`); following stops while the app is in the background so the Hub knows to push instead (`Chats.swift:1081-1088`). Unread means a bot message newer than when the conversation was last read on this phone or reported read by another device; the first sync after installing counts everything as read (`Chats.swift:68-70`, `:228-260`, `:616-620`). Opening a conversation marks it read on the Hub and removes its delivered notifications (`Chats.swift:236-247`).
+
+### 3.4 Conversation (`ChatView`)
+
+Anatomy (from code; no screenshot of this screen exists):
+
+```text
++----------------------------------------------------------+
+| < (28) Name phone ... | nav bar over the wallpaper; title opens the editor
+| [ phone.fill 00:42 speaker mic end ] | call bar, glass capsule, only during a call
+| |
+| wallpaper: full bleed under bars and composer, |
+| black 25 % scrim unless default |
+| |
+| +-------------------------------+ | bot: secondarySystemBackground, radius 18,
+| | reply text (17 pt body) | >= 48 free | padding 12 x 8; leading
+| +-------------------------------+ |
+| [react badges] | badges hang 16 above a bubble's top-right corner
+| +---------------------------------+ | you: accent fill, white text; trailing
+| >= 48 free | your message | |
+| +---------------------------------+ |
+| Delivered | .caption2, latest own message only
+| |
+| (+) ( Message ................................ mic ) | 48 high, plus 48 circle, gap 8, side padding 12
++----------------------------------------------------------+ bottom gap max(8, safe-area-bottom - 6); 8 above keyboard
+```
+
+Content is padded 12 at the sides, rows 6 apart; in groups a 28 pt avatar column sits left of bot bubbles.
+
+#### 3.4.1 Header and bars
+
+Inline navigation bar. The principal item is a button holding a 28 pt `ThreadAvatar` (with phase dot, 8 pt) and the name in `.headline` `.primary`, `HStack(spacing: 8)`; tapping opens the editor (or only the background editor for a bot shared with you) (`Chats.swift:1567-1576`). Trailing items: `phone` ("Call <name>") when the bot can be called and is not already on a call (`LinkBot.canCall`, Codex bots per changelog 0.21.0), and `ellipsis` ("Shared") when anything live was shared in the conversation (`Chats.swift:1577-1594`). During a call the `CallBar` sits in the top safe-area inset under the navigation bar and the conversation stays usable (`Chats.swift:1557-1560`). A conversation deleted on another device pops itself (`Chats.swift:1481-1482`).
+
+#### 3.4.2 Transcript layout and scrolling
+
+`ScrollView` with a `LazyVStack(spacing: 6)`, horizontal padding 12, vertical 8 (`Chats.swift:1495-1521`, `:1932`). The wallpaper (`ConversationBackdrop`) is the scroll view's background and ignores safe areas, so it runs under the bars and the composer; there is no bar behind the composer (`Chats.swift:1524`, `:1681`). The keyboard dismisses interactively on scroll (`Chats.swift:1523`). No timestamps or date separators appear anywhere in the transcript.
+
+Paging: the first open loads the newest 50 messages; a spinner row at the top loads the previous 50 when it appears; newer messages arrive 100 at a time (`Chats.swift:93-94`, `:828-867`, `:1497-1501`). Rows keep their place by message ID so loading earlier pages does not move what is being read (`Chats.swift:1517-1518`).
+
+Scroll rules (`Chats.swift:1377-1428`, tested in `ConversationScrollTests`): opens at the end; while the end is visible (2 pt tolerance, measured above the composer) it stays at the end as content grows; your own new message always scrolls to the bottom; anyone else's scrolls to show the message's top, and only if you were at the bottom; if you were reading higher up nothing moves. Only the person's own scrolling can move it off the end (rows measured while appearing must not).
+
+#### 3.4.3 Bubbles
+
+| Property | You | Bot | System |
+|---|---|---|---|
+| Alignment | Trailing, `Spacer(minLength: 48)` before | Leading, `Spacer(minLength: 48)` after | Centred, full width |
+| Fill | `.accentColor` (system blue), opaque | `secondarySystemBackground`, opaque | None |
+| Text | White; links underlined in white | `.primary`; links tint | `.footnote` secondary, vertical padding 4 |
+| Shape | `RoundedRectangle(cornerRadius: 18, style: .continuous)`, padding 12 × 8 | same | |
+| Extras | Delivery line below; red failure mark to the left | In groups: author name above the first of a run, avatar beside the last | |
+
+Sources: `Chats.swift:1938-1980`, `MessageActions.swift:42-83`. The text font is the default `.body` (17 pt at default Dynamic Type, inferred from no explicit font). Text is inline Markdown only (`inlineOnlyPreservingWhitespace`), and only `http`, `https` and `mailto` links stay tappable (`MessageActions.swift:68-82`).
+
+**Groups.** Bot rows always reserve a 28 pt avatar column (`HStack(alignment: .bottom, spacing: 6)`); the avatar appears beside the last message of each consecutive run by one bot, and the bot's name (`.caption` secondary, leading padding 12, top padding 4) above the first (`Chats.swift:516-534`, `:1964-1979`). In one-to-one chats bot messages have no avatar at all. On a 390 pt phone the widest bubble is 318 pt (366 content − 48), or 284 pt for a bot in a group.
+
+**Reaction clearance.** Every row adds `16 − 6 = 10` pt of top padding so a reaction badge (hanging 16 pt above the bubble) never moves the conversation when added (`Chats.swift:1961-1963`, `:1979`).
+
+**Long messages** fold when longer than 1,200 characters or 12 lines, to 8 lines with a "Read more" button (`.subheadline.weight(.semibold)`, plain) that expands the whole message in place (`Chats.swift:1894-1909`, `:2040-2041`, `MessageActions.swift:49-58`).
+
+**Tables.** A Markdown table splits the message into separate bubbles: prose, a table card, more prose; reactions mark the first (`Chats.swift:2012-2022`). The card: `tablecells` (`.title3`, tint), header names joined with " · " (`.subheadline.weight(.semibold)`, 1 line), "1 row"/"N rows" (`.footnote`, foreground at 70 %), trailing `chevron.right` (`.footnote.weight(.semibold)`, 50 %); padding 12 × 10, max width 280, same 18 pt bubble shape and colours (`MessageTables.swift:7-39`). Tapping opens a "Table" sheet (medium/large detents) with a horizontally and vertically scrolling grid: cells `.subheadline.monospacedDigit()`, max width 240, padding 10 × 8, selectable; headers `.footnote.weight(.semibold)`, tap to sort ascending, descending, then original (chevron 9 pt bold, always laid out so widths do not jump); header band `primary` at 6 %; corner radius 12; menu "Table Actions" (`ellipsis`) with "Copy as CSV" (`doc.on.doc`) and "Share CSV" (`square.and.arrow.up`) as `Table.csv` (`MessageTables.swift:42-157`; changelog 0.22.0).
+
+**Press feedback.** While pressed a text bubble scales to 0.96 with `.spring(duration: 0.25)`; a 0.35 s long press lifts it (`Chats.swift:2017-2018`, `:2042`). VoiceOver gets named actions "Copy" and "React" (`Chats.swift:2020`, `:2043`).
+
+#### 3.4.4 Reactions in the transcript
+
+One capsule badge per distinct emoji, overlapping by 6 pt (`HStack(spacing: -6)`), hung on the bubble's top-trailing corner for every author (offset x +10, y −16). Each badge: `.footnote` text "emoji" or "emoji N" when more than one reacted, horizontal padding 6, minimum 28 × 28, your own in solid tint with white text, others on `tertiarySystemBackground`, 2 pt `systemBackground` stroke. Tapping a badge toggles your reaction. They mark the first text bubble, or the attachments when there is no text (`Chats.swift:1987-2007`, `:2052-2063`, `:2021`, `:2032`).
+
+#### 3.4.5 Delivery and failed messages
+
+Only your latest message, and any message the Hub does not have yet, shows a status line (`.caption2`, secondary, red when failed): "Sending…", "Not delivered", "Delivered" or "Sent" (`Chats.swift:672-677`, `:1487-1488`, `:1956-1958`). Sending is optimistic: the message appears at once, files upload first, and it is retried with pauses of 0, 2, 5 and 15 s under the same ID (idempotent) only while it is still the newest message (`Chats.swift:656-749`). A failed message gets a red `exclamationmark.circle` (`.title2`) to the left of the bubble; it is a menu whose section header is the failure reason (or "Not delivered") with "Try Again" (`arrow.clockwise`, only while newest), "Edit and Send" (`pencil`, puts the text and files back in the composer, prepending to any draft) and "Delete" (`trash`, destructive) (`MessageActions.swift:11-27`, `Chats.swift:1864-1879`, `:1948-1953`). Unsent messages survive a relaunch (`unsent.json`). A message of files alone is sent with the body "Sent N attachment(s)", a lone recording with "Voice message", and the bubble hides those bodies (`Chats.swift:698-701`, `:2065-2069`).
+
+#### 3.4.6 Attachments
+
+Order inside a message: text bubbles, then the first public web link's preview card, then attachments (`Chats.swift:2009-2034`).
+
+| Kind | Rendering | Values |
+|---|---|---|
+| Picture | Inline image, opens Quick Look (swipes through the message's other files) | Fits 240 × 320 (compact 144 × 192 when sharing a row), minimum 44 on each side, corner radius 16; the frame is reserved from the Hub-provided pixel size so nothing jumps; placeholder `secondarySystemBackground` with spinner, height = width × 2/3 when the size is unknown; decoded at 720 px (`ChatContent.swift:113-153`, `:196-204`) |
+| Other file | Card | 44 × 44 thumbnail or symbol (radius 8), filename `.subheadline.weight(.medium)` 2 lines, byte size `.caption` secondary, padding 10, max width 260, `secondarySystemBackground` radius 16 (`ChatContent.swift:155-177`); symbols `photo`, `film`, `waveform`, `doc.richtext`, `doc.text`, `doc` (`:222-229`) |
+| Live link (browser tab, computer, noodlet) | Card that opens live full screen | 240 × 150 picture radius 12 on `secondarySystemBackground`; a computer without a picture shows its last 14 terminal lines in 7 pt monospaced white 80 % on black; title `.subheadline.weight(.medium)`; whole card padding 8 on `tertiarySystemBackground` radius 16; noodlet menu "Open on iPhone" (or "Open on iPad", `iphone`) / "Open on Hub" (`play.display`) (`ChatContent.swift:73-111`) |
+| Web page shared as a file | Link preview card | as below |
+| Voice message | Player | see 3.10 Voice messages |
+
+Picture context menu: share, and "Use as Background" (`photo.on.rectangle`) (`ChatContent.swift:61-69`). Layout of several files follows Settings > Attachments: Vertical (default, 4 pt gap), Wrap (side by side, 8 pt), Stack (overlapping, 12 pt row gap, each next file offset by `min(72, 0.42 × width)` and dropped 12 pt, black 30 % shadow radius 3 y 2); in Stack only files that swipe together overlap and live cards and voice messages sit whole above them (`ChatContent.swift:233-326`).
+
+**Link preview card**: 280 wide; image area 280 × 158 on black 28 % (spinner while loading, `link` symbol at 26 pt light when there is no image); title `.subheadline.weight(.semibold)` 2 lines and site `.caption` secondary, padding 12 × 10; `tertiarySystemBackground`, radius 16 (`ChatContent.swift:497-535`). Only public `http(s)` hosts get one (no `.local`, private or link-local IPv4), fetched on the phone with a 10 s timeout, image capped at 560 px JPEG 0.8, cached per conversation for 7 days; a page with no metadata gets a card naming its site (`ChatContent.swift:355-494`). Tapping any web link opens an in-app Safari sheet unless "Preview Web Links" is off (`ChatContent.swift:329-352`, `Chats.swift:1628-1633`).
+
+#### 3.4.7 Composer
+
+```swift
+static let controlHeight: CGFloat = 48 // field and plus height (Chats.swift:1433)
+static func composerGap(homeBar: CGFloat) -> CGFloat { max(8, homeBar - 6) } // :1437
+private var composerLift: CGFloat { keyboardUp ? 8 : Self.composerGap(homeBar: homeBar) - homeBar } // :1664
+.safeAreaInset(edge: .bottom) { Color.clear.frame(height: Self.controlHeight + 8 + composerLift) } // :1542
+```
+
+- **Height parity.** 48 pt is exactly the height of the iOS 26 search field capsule, pinned by a test that measures the system search field (`ComposerSizeTests.swift:7-25`).
+- **Vertical position.** With the keyboard down the composer's bottom sits `max(8, safeAreaBottom − 6)` above the screen edge: 28 pt on a phone with a 34 pt home-indicator inset (partly over the home bar, level with the system search field), 8 pt on a phone without one. With the keyboard up it sits 8 pt above the keyboard (changelog 0.14.0 fix). Keyboard state comes from will-show/will-hide notifications (`Chats.swift:1554-1555`).
+- **Overlay, not push.** The transcript reserves room for a one-line composer only (48 + 8 + lift); a longer message grows the composer upward over the conversation, which does not move (`Chats.swift:1540-1553`; changelog 0.9.0).
+- **Structure** (`Chats.swift:1666-1816`): horizontal padding 12, top 8; above the controls in a `VStack(spacing: 6)`: the @-mention strip, a transient error line (`.footnote`, red, cleared after 6 s), and pending file chips; then a `GlassEffectContainer` `HStack(alignment: .bottom, spacing: 8)` of the plus and the field.
+- **Plus**: `plus` at 18 pt medium, secondary, in a 48 × 48 circle with interactive glass ("Add").
+- **Field**: a `UITextView` (so a pasted image attaches as "Image.png"), body font, grows to 6 lines then scrolls (`ChatContent.swift:630-696`); placeholder "Message"; vertical padding 13 inside a capsule of min height 48 (`cornerRadius: 24`, regular glass), leading padding 16, trailing 5. Inside on the right: `mic` (18 pt regular, secondary, 30 × 48 hit area, "Record Voice Message") while there is nothing to send, otherwise `arrow.up.circle.fill` at 30 pt in tint ("Send").
+- **Disabled** (archived): the field is disabled and the placeholder becomes the reason: "<Name> is archived", "This group is archived", "Every bot in this group is archived" (`Chats.swift:281-291`).
+- **Drafts** are kept per conversation on the phone; a draft of only whitespace is discarded so the field returns at its normal size (`Chats.swift:212-223`, `:1526-1530`).
+- **Pending file chip**: 32 × 32 thumbnail or symbol (radius 6), filename `.caption` max 120 wide, `xmark.circle.fill` remove ("Remove <name>"), padding 6, `secondarySystemBackground` capsule; chips scroll horizontally with 6 pt spacing (`ChatContent.swift:538-561`).
+- **@-mentions**: typing `@` after whitespace or one of `([{,:` plus up to 64 letters, digits or ` '-_.` shows a horizontal strip of matching non-archived bots (a group's own bots, or all your bots with the current one first, then alphabetical); each chip is a 22 pt avatar and name (`.subheadline`) on a `secondarySystemBackground` capsule, padding 8 × 5, spacing 6; choosing writes the plain name and a trailing space when at the end (`ChatContent.swift:734-774`, `Chats.swift:1818-1846`).
+
+**Attach panel** (Messages-style morph, `Chats.swift:1719-1780`): tapping the plus dismisses the keyboard and, with `.bouncy(duration: 0.4, extraBounce: 0.05)`, morphs the glass circle (shared `glassEffectID("attach")`) into a 230 pt wide glass panel with corner radius 28 and padding 8 that grows up over the conversation from the plus's bottom-left without moving the field. Rows (`VStack(spacing: 2)`): a 32 pt circle with a gradient of the row's colour holding a white 15 pt semibold symbol, then the title in `.body`; spacing 14, horizontal padding 8, min height 48. Rows: "Camera" (`camera.fill`, gray; only with a camera), "Photos" (`photo.on.rectangle.angled`, blue), "Files" (`folder.fill`, cyan). The conversation behind is covered with `.ultraThinMaterial`; tapping it, or the field, closes the panel. Photos allows up to 10 images or videos, named "Photo N.<ext>" or "Video N.<ext>" from the item's own type; the camera saves JPEG 0.9 "Photo.jpg"; Files allows any type, several at once (`Chats.swift:1610-1626`, `ChatContent.swift:563-594`).
+
+#### 3.4.8 Shared sheet
+
+`…` opens "Shared": every computer, browser tab and noodlet shared in the conversation, newest first, one entry per target (a computer whatever its view, a browser per tab); rows with a 96 × 64 picture or symbol (radius 8, `tertiarySystemBackground`), title (2 lines) and kind "Browser", "Computer" or "Noodlet" (`.caption`); "Done" (`ChatContent.swift:792-845`, `HubTools.swift:781-848`). Choosing closes the sheet and opens the item full screen once the sheet is gone (`Chats.swift:1596-1608`).
+
+### 3.5 Message lift overlay (long press)
+
+Presented as a full-screen cover with a clear presentation background and system animation disabled; the overlay animates itself (`Chats.swift:1635-1650`). Values (`MessageActions.swift:85-219`, layout tested in `MessageActionsTests.swift`):
+
+| Part | Value |
+|---|---|
+| Backdrop | Full-screen `.ultraThinMaterial`, fades in; tap anywhere to close ("Close") |
+| Lifted bubble | Redrawn at its on-screen frame (same `MessageText` look, folded if it was), scale 1.03 |
+| Reaction bar | Horizontally scrolling glass capsule (interactive); 12 emoji at 28 pt in 44 × 44 cells, padding 6; width `min(screen − 24, 12 × 44 + 12)` = 540 cap, height 56; your existing reactions on a tint 30 % circle |
+| Reaction set | `❤️ 👍 👎 😂 🎉 ❓ 👀 ⏳ ✅ 🙏 🔥 💡` (heart, thumbs up, thumbs down, tears of joy, party popper, question mark, eyes, hourglass, check mark, folded hands, fire, light bulb), the Mac's twelve |
+| Action menu | 220 pt wide glass rounded rectangle (radius 24); items `Label` with padding 18 × 14, `.body`: "Copy" (`doc.on.doc`); for a failed message "Try Again", "Edit and Send", "Copy", "Delete" (red), and the reaction bar hidden |
+| Placement | Bar 8 pt above the bubble, menu 8 pt below; aligned to the bubble's trailing edge for your messages, leading for bots; kept 12 pt inside the screen; the bubble moves only if bar or menu would leave the screen; a bubble taller than the space shows its start, minimum 44 |
+| Motion | In: `.spring(duration: 0.35, bounce: 0.25)`, bar scales from 0.4 at its bottom corner, menu from 0.4 at its top corner; out: `.spring(duration: 0.25)` then close |
+| Haptic | Medium impact when shown |
+
+### 3.6 Differences from the Mac design
+
+| Aspect | Mac (verified in code or hero.png) | Mobile |
+|---|---|---|
+| Navigation | Sidebar with "Bots"/"Groups" sections beside the conversation | One mixed list, push to conversation; no split view on iPad |
+| List avatar | 42 pt, row spacing 10, status dot 10 pt with 2 pt ring (`Sources/Noodle/SidebarView.swift:145-155`) | 48 pt, spacing 12, dot 11.5 pt; pinned bots as 76 pt circles with note bubbles |
+| Conversation header | Large centred avatar and name over the wallpaper (hero.png) | 28 pt avatar + `.headline` name in the nav bar; tap to edit |
+| Bubble radius, padding | 16 continuous, 13 × 8 (`Components.swift:324-340`, `:360-372`) | 18 continuous, 12 × 8 |
+| Text size | 12.5 pt, line spacing 2 (`LongMessageText.swift:38-43`) | `.body` (17 pt), default spacing |
+| Bubble fill over a wallpaper | Translucent: `.ultraThinMaterial` plus accent 28 % (you) or black 22 % (bot) (`Components.swift:363-368`) | Always opaque accent / `secondarySystemBackground` |
+| Row gap, overhang, content gap | 10 / 12 / 3 (`TranscriptScrollView.swift:29-32`, `Components.swift:209-212`) | 6 / 16 / 4 |
+| Bot avatar beside bubbles | 27 pt on bot messages, also one-to-one (hero.png, `Components.swift:255-274`) | 28 pt, groups only, last of each run |
+| Opposite-side spacer | 120 (`Components.swift:253`, `:313`) | 48 |
+| Reaction badge | Emoji 14 pt + count 10 pt; yours accent 25 %; stroke 1.5 at 85 %; offset x 5 (`Components.swift:381-386`, `:460-476`) | `.footnote` "emoji N"; yours solid tint with white text; 2 pt stroke; badges overlap 6; offset x 10 |
+| Reacting | Context menu with two rows of six emoji (`MessageContextMenu.swift:48`) | Lift overlay with a 12-emoji glass bar |
+| Delivery label | 9.5 pt tertiary under user messages: "Saved", "Sent", "Delivered", "Not delivered" (`Components.swift:305-310`, `:522-529`) | `.caption2` secondary, latest own message only: "Sending…", "Sent", "Delivered", "Not delivered" (red) |
+| System message | Capsule with `person.2.fill`, 11.5 pt medium, ultra-thin material radius 14 (`Components.swift:239-250`) | Plain centred `.footnote` secondary |
+| Long message | Same limits; "Read more" (`text.alignleft`) opens a reader popover (`LongMessageText.swift:47-58`) | Same limits; "Read more" expands in place |
+| Table | Rendered inside the bubble (`Components.swift:335-339`) | Card opening a sortable sheet with CSV copy/share |
+| Composer | Controls 36 pt, send 27 wide (`ChatView.swift:374-377`) | 48 pt (search-field parity), send 30; plus morphs into an attach panel |
+
+### 3.7 New bot, groups and the bot editor
+
+**Bot editor** (`AgentEditor`, `Chats.swift:2076-2354`; screenshot `mobile-new-bot.png`). A sheet with its own stack, a grouped `Form`, no navigation title, toolbar "Cancel" and "Create" (new) or "Save" (edit), rendered as glass capsules in the screenshot; while saving the confirm button becomes a spinner. A new bot starts with an empty name, the `sparkles` symbol and a random colour index (`Chats.swift:2100-2101`). Sections in order:
+
+1. Avatar 88 pt with "Edit" (`.subheadline`, tint) below, on a clear row, pushing "Bot Picture" (`Chats.swift:2161-2174`).
+2. "Name" text field.
+3. "Hub" picker (new bot with several Hubs only); "Harness" menu picker whose items show the provider name with the profile as a subtitle and whose chosen value reads "Provider · Profile" on one line, middle-truncated, or "Choose"; "Model" ("Default" or "Choose" when the plan restricts models); "Effort" ("Default" plus the model's efforts) only when the model offers them; "Voice" (value "Automatic" until chosen) only when the harness has voices. With no harness lent: "Your plan lends no harnesses" (`Chats.swift:2178-2229`, `:2545-2550`). Changing harness clears the effort, sets the harness's initial model and drops a voice the new harness does not offer (`Chats.swift:2124-2134`). An agent's current harness, model or effort that the plan no longer lends is kept at the top of its list so it still displays (`Chats.swift:2104-2156`).
+4. Error text in red, when any.
+5. Existing bots only: "Tools", "Computers", "Browsers" (pushes); "Sharing" with value "Only You", "1 Person" or "N People" (only on Hubs that allow sharing); "Background"; "Kick" (only when the bot has failed) and "New Session"; destructive "Delete Bot" (`Chats.swift:2233-2263`).
+
+Create/Save is disabled until there is a name and a harness, and a model when the plan restricts models (`Chats.swift:2293-2295`). Confirmations: "Delete <name>?" / "Delete" / "The bot and its conversation are deleted from the Hub for all your devices."; "Start a new session for <name>?" / "New Session" / "Cancel" / "<name> will start with a fresh context. Its workspace, memory and messages are kept."; Kick may return a Hub-supplied question (title defaults to "Recover Bot") with its confirm title, optional "New Session" and "Cancel" (`Chats.swift:2265-2286`). A bot someone shared with you opens only its background editor with "Done" (`Chats.swift:2356-2384`).
+
+**Bot Picture** (`Appearance.swift:203-308`): 104 pt preview; section "Image": "Choose Photo" (`photo`), "Create Image" (`apple.image.playground`, Image Playground seeded with the bot's name, description and backstory), "Use Symbol Instead" (`square.grid.2x2`) or disabled "Using Symbol" (`checkmark`); section "Colour": six 34 pt gradient swatches, spacing 12, white 13 pt bold checkmark on the selected one; section "Symbol": a 6-column grid (spacing 10) of 42 pt tall tiles, radius 10, 18 pt semibold symbols, selected accent with white, others secondary 14 %. Symbols in order: `sparkles`, `bolt.fill`, `brain.head.profile`, `hammer.fill`, `terminal.fill`, `magnifyingglass`, `shippingbox.fill`, `paintbrush.fill`, `checkmark.seal.fill`, `ladybug.fill`, `wand.and.stars`, `gearshape.2.fill`. Photos are fitted to 512 px, JPEG 0.86, max 50 MB ("Choose an image smaller than 50 MB.") (`ChatContent.swift:776-790`).
+
+**Voice** (`Calls.swift:486-563`): groups "Feminine" and "Masculine" (`.footnote.weight(.semibold)` secondary), 3-column grid spacing 10, tiles min height 72, radius 14, a `waveform` (`.title3`) that animates while its bundled sample plays, name `.subheadline` (semibold when selected), selected fill accent 16 % with a 1.5 pt accent border, others secondary 10 %. Tapping selects and plays the sample.
+
+**Sharing** (`HubTools.swift:298-380`): an adaptive grid (minimum 76, spacing 8, row spacing 14) of 56 pt person avatars with names (`.caption`); selected people get a 2.5 pt accent ring and a 20 pt `checkmark.circle.fill`, others are at 55 % opacity; `.snappy(duration: 0.2)`; selection haptic. Footer: "Only you can talk to <bot>." or "<A, B and C> can talk to <bot> too." (`LinkProtocol.swift:629-634`). Empty: "Nobody else is on this Hub".
+
+**Group editor** (`Chats.swift:2386-2543`): title "New Group" or "Group Info"; "Name"; "Description" (2 to 4 lines); "Hub" picker for a new group (switching Hub clears the members); section "Members": your own non-archived bots alphabetically, each a 32 pt avatar, name, description (`.subheadline` secondary, 2 lines) and a tint `checkmark` when chosen, "No Bots" when empty; existing groups add "Background" and "Delete Group" ("The group and its messages are deleted from the Hub for all your devices. Its bots stay."). Create requires a name and at least one member.
+
+### 3.8 Tools, computers and browsers
+
+**List screens** "Tools", "Computers", "Browsers" (`HubTools.swift:207-296`): every item of that kind the user has on the Hub, ticked (`checkmark`, tint) when this bot may use it; tapping toggles assignment at once (spinner in place of the tick while busy); detail line `.caption` secondary (a connection's problem, a computer's state, a browser's "Paused"); a bordered small "Sign In" button for a connection not signed in; swipe "Delete"; "None on this Hub yet"; toolbar "Add" (`plus`).
+
+**New Tool** (sheet, `mobile-new-tool.png`, `HubTools.swift:477-595`): title "New Tool", "Cancel"; the Hub's catalogue of services, filtered by a bottom search "Search tools" where every typed word must appear in the name, summary or badge; each row a 32 pt icon (radius 7; first letter on `.quaternary` when there is no icon), the name, an optional badge (`.caption2` orange on orange 12 % capsule, padding 6 × 2) and a one-line summary (`.caption`). In the screenshot names render in tint blue and summaries in lighter blue because the hierarchical `.primary`/`.secondary` styles resolve against the list button's tint. A final section links to "Custom MCP Server": fields "Name" and "MCP Server URL" (https only), "Add". Tapping a service saves a connection named after it (a second one becomes "Notion 2"), assigns it to the bot, starts sign-in in the system web-auth sheet with the callback `noodle-mobile://mcp/oauth/callback`, then closes (`HubTools.swift:5-6`, `:44-59`, `:525-561`).
+
+**New Computer / New Browser** (`HubTools.swift:382-475`): "Kind" picker of the Hub's computer templates (computers only), "Name" prefilled "<Bot>’s Computer" or "<Bot>’s Browser", "Creating…" progress while a computer image downloads, "Cancel" / "Create"; the new item is assigned to the bot.
+
+### 3.9 Hub screens and Settings
+
+**Hubs** (sheet, `HubScreens.swift:516-584`): one row per joined Hub: Hub name (primary) over the user's name (`.subheadline` secondary), the connection status in colour ("Connecting…" secondary, "Connected" green, "Not connected" orange), and an `info.circle` "Details" button; a section with "Add Hub" (`plus`). When a Hub does not answer its bots' dots show offline (gray) (`HubScreens.swift:905-936`).
+
+**Hub details** (`HubScreens.swift:586-684`): an 88 pt `PersonAvatar` with a 28 pt `pencil.circle.fill` badge (white on accent, on a grouped-background circle) opening "Your Picture"; the user's name in `.title2.bold()` and the Hub name in secondary; rows "Status", "Plan", "Address", "Hub Key", "Device Key"; an error in orange; "Archived" with its count; "Pair Another Device" (if allowed); "Users" (admins); destructive "Leave Hub" ("Leave <hub>?" / "Leave" / "Joining again needs a new invitation.").
+
+**Archived** (sheet): rows with a 32 pt avatar, the name, "Bot" or "Group" (`.caption`), and a borderless "Unarchive"; a row opens the conversation read-only; empty state "Nothing Archived" (`archivebox`) (`HubScreens.swift:686-724`).
+
+**Users** (admins): 36 pt avatars, name, "<plan>" or "<plan> · Admin"; "Add User" (`plus`) opens an alert "New User" with "Name" / "Cancel" / "Add". **User**: "Plan" picker and "Can Pair Devices" toggle (disabled for admins, footer "Admins are changed only in the Hub’s own Settings."); "Devices" with "Connected", "Last seen <relative>" or "Paired <relative>", swipe "Remove" ("It can no longer reach the Hub until it joins again."), "No devices", "Invite"; "Remove User" ("Their devices and their bots are removed from the Hub."); toolbar "Rename" (`HubScreens.swift:726-903`).
+
+**Pair a Device / Invite <name>**: a 240 × 240 QR code (nearest-neighbour scaling) with 12 pt padding on a white radius-12 card, "Hub key <fingerprint>" (`.footnote.monospaced()` secondary), bordered "Copy Link" and "Share…", a live "Expires <relative>" that turns into "New Invitation" when expired (`HubScreens.swift:938-1004`).
+
+**Settings** (sheet, `HubScreens.swift:1050-1102`): "Attachments" segmented Wrap / Vertical / Stack with footers "Files sit side by side and wrap onto new rows.", "Files sit one below another.", "Files overlap, with part of each one showing."; "Preview Web Links" toggle with footer "Web links open in a preview first, with a button to continue in Safari. When off, they open in Safari."; "Haptics for On-Screen Controls" (off by default); "Noodlet Permissions": each noodlet with what it was allowed ("Microphone", "Camera", "Speech Recognition", "Screen Recording", "Local Network"), swipe to revoke.
+
+### 3.10 Voice messages
+
+**Recording** replaces the field in the composer slot: a regular-glass rounded rectangle (radius 18), padding 12 × 4, with a matching hit shape so taps beside controls do not reach the conversation (`Chats.swift:1668-1675`). Contents (`VoiceMessages.swift:387-458`), `HStack(spacing: 10)`: `xmark` discard (30 × 36); while preparing or finishing a spinner and `.caption` secondary text ("Preparing speech…", "Downloading speech model…", "Starting microphone…", "Finishing transcription…"); while recording a 6 pt red dot and a live waveform 22 pt high; the time `m:ss` in `.caption.monospacedDigit()`; `stop.fill` (30 × 36); and a 30 pt `arrow.up.circle.fill` send that is enabled while recording or ready (sending while recording stops first). Errors show in red `.caption`; after a failed transcription with audio kept, "Retry Transcription" and "Send Audio Only". The limit is 10 minutes (600 s). Transcription runs on device as the person speaks; a partial or failed transcript is never sent without asking (`VoiceMessages.swift:9-264`).
+
+**Live waveform**: bars 2.5 wide every 5 pt, scrolling right to left at a fixed 50 ms per bar a quarter second behind the clock, 12 s kept, height mapped from a fixed −60 to −12 dB range, minimum 2, corner 1.25, `.primary` at 70 % (`VoiceMessages.swift:460-515`).
+
+**Player** in the transcript: a 250 pt card on `secondarySystemBackground` (radius 16, padding 12 × 7): play/pause (28 × 32), the waveform (28 pt high, up to 60 bars, square-root amplitude, minimum 2, 2 pt gaps, radius 2, played part accent, rest secondary 60 %) that seeks on tap, and the time in `.caption.monospacedDigit()` secondary (duration, or position while playing). Touch and hold offers "Show Transcript" (`text.quote`), a "Transcript" sheet at medium/large ("No transcript available."). One recording plays at a time, through the speaker even in Silent Mode (`VoiceMessages.swift:537-662`). A recording is sent as "Voice message.caf" with the transcript, duration and waveform as metadata.
+
+### 3.11 Calls
+
+`PhoneCalls` allows one call per Hub; starting another hangs up the first (`Calls.swift:28-146`). Audio runs in a hidden 1 × 1 transparent `WKWebView` doing WebRTC; the Hub only relays the offer and answer and receives spoken lines; the call starts on the earpiece at full voice quality and "Speaker" switches to voice-chat processing for echo cancellation; AirPods use A2DP (`Calls.swift:148-308`). The timer and a chime start only when both the Hub and the media say connected.
+
+**Call bar** (`Calls.swift:344-389`): a glass capsule in the top inset with horizontal padding 18, vertical 10, outer padding 16 horizontal and 4 top, `HStack(spacing: 14)`, `.body.weight(.medium)`: `phone.fill` (secondary while connecting, green when connected), the elapsed time in a slot as wide as "00:00" ("--:--" while connecting; "h:mm:ss" past an hour), spacer, Speaker (`speaker.fill` / `speaker.wave.3.fill`, accent when on), Mute (`mic.fill` / `mic.slash.fill`), End (`phone.down.fill`, red).
+
+**In the transcript**: a full-width card "Voice call with <name>" (`.subheadline.weight(.medium)`) with a live timer or the final length (hours, minutes and seconds in abbreviated units; a rendering such as "2 min, 5 sec" is inferred), `phone` or green `phone.fill`, padding 14 × 9, `.ultraThinMaterial` radius 14. Spoken lines appear as transcript blocks placed after the last message sent before they were said, so typing during a call splits the transcript: `waveform` icon, two-line preview (a live block shows its last two lines, a finished one its first two), speaker in `.footnote.weight(.semibold)` secondary ("You" or the bot's name) followed by the line in `.subheadline`, "N lines" in `.caption2` tertiary, padding 14 × 8, `.ultraThinMaterial` radius 12, inset 24 pt from the sides; tapping opens a "Call" sheet listing every line (`Calls.swift:310-342`, `:391-477`).
+
+### 3.12 Live views and noodlets on mobile
+
+**Live surface** (a shared browser tab or computer, or a noodlet streamed from the Hub) opens as a full-screen cover on black (`HubTools.swift:640-779`). In portrait: inline navigation bar with the card's title (or "Live"), "Done", and a primary group of "Show on TV" (`tv`) for games, "Controls" (`gamecontroller.fill` / `gamecontroller`), "Keyboard" (`keyboard`) and "Run on iPhone" (`iphone`) for a noodlet that can run locally. In landscape (compact vertical size) or on TV the bar and status bar hide and the same buttons float icon-only in `.buttonStyle(.glass)` over the top corners, 12 pt from the sides. Touch and hold then move drags; two-finger pinch zooms and pans (changelog 0.11.0). A noodlet with game controls shows an on-screen gamepad; a connected hardware controller hides the buttons it covers.
+
+**Noodlets** (`Noodlets.swift:13-288`): a noodlet runs on the phone in a web view (files fetched once per revision and cached; its data and secrets stay on the Hub) or streams from the Hub; the choice is remembered per noodlet, and the card's menu chooses before opening; noodlets using camera, microphone or screen always run on the phone (changelog 0.12.0). On first use of declared permissions it asks: "“<title>” would like to use <Camera and Microphone>." with "Allow" / "Don’t Allow"; a refusal shows "Permission was not given to use …" (`Applet/Protocol/Sources/NoodletRuntime/Grants.swift:41-52`). A noodlet laid out for desktop gets the desktop site unless it declares itself an app (`Noodlets.swift:143-147`). It can lock orientation and request full screen; sound plays in Silent Mode and mixes with other audio; the idle timer is disabled while a controller is connected or the game is on a TV.
+
+**On-screen gamepad** (`Shared/Surface/Sources/Surface/Gamepad.swift:165-263`, `:350-450`; screenshot `mobile-game.png`): margin 16 inside the safe area, spacing 12; pad size `clamp(0.36 × min(width, height), 120, 170)`, bottom-left; a 64 × 44 menu capsule above it; buttons `clamp(0.42 × pad, 52, 72)` in up to 3 columns nearest the right thumb (two buttons sit on a slant, the main one 45 % of a button higher); at most 8 buttons; eight-way pads with a 25 % dead zone; sticks whose knob travels half the radius. Buttons are circles on black 25 % plus white 20 % (45 % pressed), 1.5 pt white 40 % stroke, labels 13 pt semibold white.
+
+### 3.13 External screen (TV)
+
+On iOS 27 only, the app offers a TV scene accessory (`sceneAccessory` with `ExternalNonInteractiveAccessory`). While Screen Mirroring or a cable gives a TV, a noodlet with game controls plays full screen on the TV (sized for the TV) and the phone turns to landscape and shows only the controls, or, when a hardware controller covers every button, a list of connected controllers (vendor logo `logo.xbox`, `logo.playstation` or `gamecontroller.fill` at `.title` in a 44 pt column, name in `.title3`, battery symbol), white on black, refreshed every 30 s. "Show on iPhone"/"Show on iPad" brings the game back without restarting; "Show on TV" sends it again or, with no TV, alerts "No TV Connected" / "Turn on Screen Mirroring in Control Center, or connect a TV with a cable." Without a game open the TV mirrors the phone (`ExternalScreen.swift:6-155`; changelog 0.17.0 and 0.18.0). A controller's View button shows a TV menu over the game: black 55 % scrim, a horizontal row of 300 × 180 cards (radius 16, white 12 % fill, spacing 28, padding 60 × 40, 40 from the bottom), the chosen card raised 1.08 with a 4 pt white border and the rest at 70 %, titles in `.title3`, a final "Close Game" (`xmark` 48 pt); d-pad moves, A opens, B or View resumes (`ExternalScreen.swift:157-294`).
+
+### 3.14 Appearance: wallpapers and avatars
+
+**`ConversationBackdrop`** (`Appearance.swift:8-59`): a `systemBackground` base; a photo scaled to fill; a video shown as its poster with a muted `AVPlayerLooper` (aspect fill, does not keep the display awake) on top unless Reduce Motion is on; or a preset drawn as a top-leading to bottom-trailing linear gradient of three colours plus an ellipse of the middle colour at 50 %, sized 1.4 × width by 1.1 × height, rotated −35°, offset 0.35 × width, blurred 50. Any non-default background gets a black 25 % scrim. It ignores safe areas and hit testing. The four presets (sRGB 0-1), shared with the Mac:
+
+| Preset | Colour 1 | Colour 2 | Colour 3 |
+|---|---|---|---|
+| Sunset | 0.96, 0.52, 0.15 | 0.77, 0.43, 0.67 | 0.46, 0.35, 0.75 |
+| Ocean | 0.04, 0.26, 0.50 | 0.08, 0.60, 0.66 | 0.14, 0.30, 0.62 |
+| Forest | 0.08, 0.24, 0.18 | 0.34, 0.53, 0.30 | 0.14, 0.34, 0.39 |
+| Dusk | 0.18, 0.16, 0.39 | 0.47, 0.29, 0.60 | 0.73, 0.37, 0.47 |
+
+The background is kept on the Hub for every device; the phone fetches a small copy and forgets copies no conversation uses (`Chats.swift:133-210`).
+
+**`BackgroundEditor`** ("Background", `Appearance.swift:95-200`): a 200 pt preview (radius 16, edge to edge) of the backdrop with two sample bubbles on `.regularMaterial` capsules, padding 10, `VStack(spacing: 14)`, padding 20: "Make this space your own." (left) and "Looks good!" (right). Then a row of five swatches (spacing 10): "Default", "Sunset", "Ocean", "Forest", "Dusk", each a 44 pt tall rendered backdrop, radius 8, border 2 pt accent when selected or 0.5 pt separator, title `.caption2`. Then "Choose Photo" and "Create Image" (Image Playground shaped like the screen, starting from the current photo). Changes apply immediately on the Hub.
+
+**Avatars.** `AgentAvatar` (`Chats.swift:2598-2653`): a photo, or a symbol at 0.45 × size semibold white on one of six gradients (top-leading to bottom-trailing): blue to cyan, purple to pink, orange to yellow, mint to teal, indigo to blue, pink to orange; any stored colour index wraps modulo 6. Phase dot colours: working blue, failed red, ready green, offline or starting gray. `ThreadAvatar` for groups (`Chats.swift:2552-2596`): one active member is drawn at 0.86 × size offset by (−6 %, −6 %) in front of a `.quaternary` disc of 0.88 × size offset (+6 %, +6 %); several members draw up to three avatars at 0.62 × size at offsets (−18 %, −14 %), (+18 %, −14 %) and (0, +19 %) on a full `.quaternary` disc; every member avatar has a 2 pt `systemBackground` ring; archived bots leave the picture. `PersonAvatar` (`Appearance.swift:310-337`): a photo, a symbol at 0.45 × size, or initials (first letters of the first two words, uppercase) at 0.4 × size semibold rounded, white on the same gradients; with no choice the colour comes from the first byte of the person's ID (`LinkProtocol.swift:665-670`).
+
+**`PersonPictureEditor`** ("Your Picture", `Appearance.swift:339-488`): 104 pt preview; "Photo": "Take Photo" (`camera`, square crop), "Choose Photo", "Create Image", destructive "Remove Photo" (`trash`); "Colour" as for bots; "Symbol": an initials tile then `person.fill`, `face.smiling`, `star.fill`, `heart.fill`, `leaf.fill`, `pawprint.fill`, `music.note`, `gamecontroller.fill`, `book.fill`, `cup.and.saucer.fill`, `sun.max.fill`; "Cancel" / "Done" (Done is a no-op close when nothing changed).
+
+### 3.15 Notifications
+
+Each joined Hub is given a random topic stored in that Hub's folder; the phone subscribes in CloudKit's public database to records the Hub leaves under that topic while replies wait unread, and tells the Hub the topic only once listening works (`Notifications.swift:14-90`, `ReplyNotifications.swift:23-54`). The push carries only the topic and conversation; its default text is "New reply" with the default sound; a collapse ID per conversation makes a newer one replace the older; mutable content lets the notification service extension ask the Hub directly for the bot's name (title) and its latest reply (body, tables removed; a reply of files alone shows the first filename or "Attachment"), within the extension's time limit, otherwise it shows "New reply" (`ReplyNotifications.swift:56-80`, `NotificationService.swift:4-37`). Notifications stack per conversation (`threadIdentifier`). The extension looks the conversation up among bots only, so a group's notification stays "New reply" (inferred from `ReplyNotifications.swift:74-77`). Permission is asked only once a Hub exists (alert, sound, badge). In the foreground no banner is shown (`willPresent` returns no options, `Notifications.swift:158-163`). Tapping opens the conversation once its Hub has loaded (`Chats.swift:1225-1232`). Reading a conversation removes its delivered notifications. **There is no inline reply**: no notification category, action or text-input action exists anywhere in the mobile sources.
+
+### 3.16 Key values at a glance
+
+| Value | Mobile | Source |
+|---|---|---|
+| Accent | System blue, no accent asset | `Mobile/Project.swift:69` |
+| Composer control height (field, plus) | 48 (= iOS 26 search field) | `Chats.swift:1433`, `ComposerSizeTests.swift:7-25` |
+| Composer field radius, inner padding | 24; leading 16, trailing 5, text 13 top and bottom | `Chats.swift:1788`, `:1807-1809` |
+| Composer outer padding, plus-to-field gap | 12 sides, 8 top; 8 | `Chats.swift:1680`, `:1706` |
+| Composer bottom gap | `max(8, safeAreaBottom - 6)`; 8 above the keyboard | `Chats.swift:1437`, `:1664` |
+| Field growth | Up to 6 lines, then scrolls | `ChatContent.swift:667-673` |
+| Mic / send | 18 pt regular in 30 × 48; 30 pt `arrow.up.circle.fill` | `Chats.swift:1790-1805` |
+| Transcript padding, row gap | 12 × 8; 6 | `Chats.swift:1519-1520`, `:1932` |
+| Bubble radius, padding | 18 continuous; 12 × 8 | `MessageActions.swift:59-62` |
+| Opposite-side free space | ≥ 48 | `Chats.swift:1946`, `:1977` |
+| Reaction overhang, badge minimum, overlap, offset | 16; 28 × 28; −6; (+10, −16) | `Chats.swift:1936`, `:1993-2002`, `:2060` |
+| Avatars: list, pinned, header, group transcript, mention chip | 48, 76, 28, 28, 22 | `Chats.swift:1295`, `:1336`, `:1570`, `:1934`, `:1834` |
+| Phase dot | `max(8, 0.24 × size)`, 2 pt `systemBackground` ring | `Chats.swift:2642-2649` |
+| Unread dot: list, pinned | 10, 8 from edge and avatar; 14 with 2 pt ring | `Chats.swift:1291`, `:1343-1344` |
+| Note bubble | `.caption2`, padding 8 × 4, max width 104, regular material capsule, 14 above | `Chats.swift:1339`, `:1364-1372` |
+| Long press, press scale | 0.35 s; 0.96 with 0.25 s spring | `Chats.swift:2017-2018`, `:2042` |
+| Lift overlay | Bubble 1.03; bar 56 high, 44 cells; menu 220 wide, radius 24; in 0.35 s spring bounce 0.25, out 0.25 s | `MessageActions.swift:88-218` |
+| Attach panel | 230 wide, radius 28, padding 8, rows ≥ 48, icon circles 32 | `Chats.swift:1744-1774` |
+| Picture bounds | 240 × 320; compact 144 × 192; minimum 44; radius 16 | `ChatContent.swift:113-118`, `:139` |
+| File card, link card, live card, voice card | Max 260 wide; 280 wide with 158 image; 240 × 150 image; 250 wide; all radius 16 | `ChatContent.swift:155-177`, `:497-535`, `:73-111`; `VoiceMessages.swift:635-637` |
+| Fold rule | > 1,200 characters or > 12 lines, shown as 8 lines | `Chats.swift:1894-1909` |
+| Paging, retries | 50 per page (100 when catching up); retry after 0, 2, 5, 15 s | `Chats.swift:94`, `:842`, `:661` |
+| Fixed sheet heights | More 292; pairing sources 244 (184 without camera) | `Chats.swift:1273`, `HubScreens.swift:462-468` |
+| Wordmark refresh | Whole at 80 pull; word width 96 | `WordmarkRefresh.swift:19-20` |
+| Wallpaper scrim, preset glow | Black 25 %; ellipse 1.4w × 1.1h, −35°, blur 50 | `Appearance.swift:29-34` |
+| Avatar gradients (6) | blue→cyan, purple→pink, orange→yellow, mint→teal, indigo→blue, pink→orange | `Chats.swift:2601-2603` |
+
+## 4. Web translation
+
+**Breakpoints** (proposed; Noodle itself has one phone layout for every width):
+
+| Width | Layout |
+|---|---|
+| < 768 px | Phone: stack navigation. Route `/` is the list, `/c/:hub/:thread` the conversation, pushed with a horizontal slide; back gesture or button pops. Editors as full-height bottom sheets; small choices as content-height sheets; live views and the lift overlay as full-viewport layers |
+| 768-1023 px | Two panes when landscape-ish: list 320 px plus conversation; or keep the phone stack in portrait tablets. Do not copy Noodle's iPad behaviour of stretching the phone layout |
+| ≥ 1024 px | Sidebar (320-360 px) plus conversation, Mac-style header; dialogs centred instead of bottom sheets |
+
+**Conversation column.** Content padding 12 px; bubble `max-width: min(100% - 48px, 560px)` (Noodle has no cap; add one for tablets and desktop). Row gap 6 px plus 10 px reserved top padding on every row for the 16 px reaction overhang. Bubble radius 18 px, padding 12 × 8 px, 17 px body text on phones (at least 16 px in any `<input>`/`<textarea>` so iOS Safari does not zoom on focus; web platform note).
+
+**Composer and the on-screen keyboard.** Position the composer absolutely at the bottom over the transcript; give the transcript a bottom padding of one composer line only (48 + 8 + lift); let a multi-line field grow upward to 6 lines and then scroll, without changing the transcript's padding. Bottom offset with the keyboard closed: `max(8px, env(safe-area-inset-bottom) - 6px)` (needs `viewport-fit=cover`); with it open: 8 px above the keyboard. On iOS Safari read the keyboard height from `visualViewport` (`innerHeight - visualViewport.height - visualViewport.offsetTop`) on `resize`/`scroll`; on Chromium `navigator.virtualKeyboard.overlaysContent = true` with `env(keyboard-inset-height)` or `interactive-widget=resizes-content` in the viewport meta are alternatives (web platform notes, verify per browser). Keep the composer 48 px tall with a 48 px circular plus on its left, mic or send inside the pill on the right; swap mic for send as soon as there is text or a pending file. Close the keyboard when the attach panel opens (`blur()` the field) and when the transcript is scrolled by touch.
+
+**Scrolling.** Implement Noodle's three rules: stick to the bottom only while the bottom is visible (2 px tolerance measured above the composer); always scroll to your own sent message; for an incoming message scroll to its top only if the person was at the bottom. Use `overflow-anchor` or ID-keyed restoration when prepending earlier pages; reserve image boxes from known pixel sizes (fit 240 × 320, compact 144 × 192, minimum 44) so loads never shift.
+
+**Touch targets and gestures.** Keep 44 px minimums: plus 48, field 48, mic and send 30 × 48 (widen to 44 on web), attach rows ≥ 48, reaction cells 44, menu items ≈ 50. Noodle's 28 px reaction badges, 22 px mention chips and 30 × 36 recording buttons are below 44 px; enlarge hit areas with padding or pseudo-elements. Long press 350 ms opens the lift overlay (press scale 0.96 during the hold; suppress `-webkit-touch-callout` and text selection during the press); provide the same actions on right-click, keyboard (`ContextMenu` key / Shift+F10) and a visible button, and the same Pin action as a swipe on touch and in the context menu (the swipe must never be the only path).
+
+**Component mapping.**
+
+| Noodle construct | Web (React + Tailwind + shadcn/Radix) |
+|---|---|
+| `NavigationStack` push | Router routes with a slide transition on phones; panes on wide screens |
+| `.sheet` with detents (292, 244, medium/large) | shadcn Drawer (Vaul) with snap points, drag handle visible |
+| Full-screen cover (lift overlay, live views) | Full-viewport layer with its own enter/exit animation; `inert` on the page behind |
+| `Menu` with `primaryAction` on pinned circles | Click navigates; long-press or right-click opens a Radix `DropdownMenu`/`ContextMenu` |
+| `.swipeActions(edge: .leading)` | Pointer-event swipe revealing an orange "Pin" action, plus the same item in the context menu |
+| `.searchable` | A search `Input` pinned at the top of the list (a bottom field mimicking iOS 26 is optional) |
+| Liquid Glass (`glassEffect`) | Translucent fill + `backdrop-filter: blur() saturate()` + hairline highlight; Noodle defines no numbers (system material) |
+| `GlassEffectContainer` morph of plus into panel | Shared-layout animation (for example a FLIP or View Transitions) from the 48 px circle to the 230 px radius-28 panel, spring roughly 400 ms with slight overshoot |
+| `UIPasteControl` | A "Paste" button calling `navigator.clipboard.readText()` on the user's tap |
+| QR scanner | `BarcodeDetector` where available, otherwise a JS decoder over `getUserMedia` |
+| `SFSafariViewController` preview | Most sites refuse framing; use the link card and open in a new tab |
+| Quick Look gallery | Lightbox swiping through the message's files |
+| `AVPlayerLooper` wallpaper | `<video muted loop playsinline autoplay poster>`; `prefers-reduced-motion` shows the poster only |
+| On-device transcription | Web Speech API where available, or server transcription; `MediaRecorder` for audio |
+| Hidden WebRTC web view | WebRTC directly in the page |
+| CloudKit push + service extension | Web Push with a service worker that fetches the reply text from your server on push, keeping message text out of the push payload |
+
+**Safe areas.** `viewport-fit=cover`; nav bar top padding `env(safe-area-inset-top)`; the wallpaper must extend under both bars; landscape game controls and floating Done buttons must respect left/right insets (Noodle keeps the gamepad 16 px inside the safe area).
+
+**Colours.** System blue accent and semantic surfaces map to tokens: accent (iOS system blue, light #007AFF / dark #0A84FF), `secondarySystemBackground` (light #F2F2F7 / dark #1C1C1E), `tertiarySystemBackground` (light #FFFFFF / dark #2C2C2E), `systemBackground` (#FFFFFF / #000000); these hex values are Apple's published system colours (iOS 26 may adjust them slightly), not values from the repository.
+
+**Time.** Format list times as "2 hr ago", "1 day ago", "3 days ago"; `Intl.RelativeTimeFormat` with `style: 'short'` produces "2 hr. ago" in en-US, so a small formatter is needed to match.
+
+## 5. Patterns worth copying, and pitfalls to avoid
+
+### Patterns worth copying
+
+- **Composer height equals the search field height** (48), and the composer bottom sits where the list's search field sits, so moving from list to chat feels continuous.
+- **Overlay composer growth**: only one line is reserved; long drafts cover the transcript instead of jumping it.
+- **Reserved reaction clearance** on every row so reacting never reflows the conversation.
+- **Reserved media boxes** from server-provided pixel sizes.
+- **Three-rule auto-scroll** (stick only at bottom, own message always, incoming from its top).
+- **Optimistic sending with bounded, idempotent retries** (0, 2, 5, 15 s, same ID, only while newest), and a failure mark offering Try Again / Edit and Send / Delete instead of a global error.
+- **Per-conversation drafts** that discard whitespace-only text.
+- **Pinned circles with a one-line note** (unread reply in semibold, else the bot's status): a strong at-a-glance team view.
+- **Sequential modals**: open the next sheet only after the previous one dismissed.
+- **Group run grouping**: name above the first message of a run, avatar beside the last, a reserved avatar column so bubbles align.
+- **Folding** at 1,200 characters or 12 lines to 8 lines with "Read more".
+- **Tables as cards on small screens** that open a sortable, copyable sheet.
+- **Messages-style lift overlay** with geometry that keeps the bar and menu on screen and shows the start of very tall messages.
+- **Disabled composer that explains itself** through its placeholder.
+- **Help Me Connect**: per-route reachability plus plain-language advice and a single Try Again.
+- **Notifications that keep content off the push service** and collapse per conversation, cleared when read anywhere.
+- **Wordmark pull-to-refresh** as a brand moment that also communicates pull progress.
+
+### Pitfalls to avoid
+
+- **No tablet layout.** iPad shows the stretched phone list and full-width bubbles; build two panes at wider breakpoints.
+- **Opaque mobile bubbles vs translucent Mac bubbles** over the same wallpaper: decide one rule per theme rather than diverging silently.
+- **Small touch targets** (28 px badges, 22 px mention chips, 30 × 36 recording controls).
+- **Markdown leaking into previews** ("The \*\*8\*\* carries…" in the list): strip inline Markdown for list rows, notes and notifications.
+- **No timestamps in the transcript** at all; consider timestamps on demand (tap or hover) and day separators.
+- **Hierarchical colour surprises**: catalogue names render in tint blue only because of how SwiftUI resolves `.primary` inside list buttons; choose such colours deliberately on the web.
+- **Group notifications** probably fall back to "New reply"; and there is no inline reply, which a web build could add where `Notification` actions allow it.
+- **Gesture-only actions**: swipe-to-pin and long-press must have visible or keyboard equivalents.
+- **In-app web preview** does not translate to the web (frame blocking); do not promise it.
+
+## 6. Open questions and inferences
+
+- The resting state of the iOS 26 bottom search field on the chat list is not visible in `mobile-chats.png`; its bottom placement is inferred from the New Tool screenshot and from the composer-parity test.
+- `website/assets/mobile-chats.png` predates 0.23.0 (no "All" title menu), and `mobile-new-bot.png` appears to predate 0.13.0 (no Kick/New Session section above "Delete Bot"); appearance of newer elements is from code only.
+- The conversation screen has no screenshot; bubble, composer and overlay appearance are from code and changelog.
+- Text size is inferred to be `.body` (17 pt at default Dynamic Type) because `MessageText` sets no font.
+- System empty-state copy for search ("No Results for …") and glass material numbers are system-defined and not in the repository.
+- Group notifications showing only "New reply" is inferred from the extension looking up bots only.
+- Only Codex bots can be called today (changelog 0.21.0); the code gates on the Hub's `canCall`, so other harnesses may follow.
+- The external-screen TV mode needs iOS 27; on iOS 26 the TV simply mirrors the phone.
diff --git a/docs-internal/research/noodle/analysis/11-opencompany-current-state.md b/docs-internal/research/noodle/analysis/11-opencompany-current-state.md
new file mode 100644
index 00000000..7cdc488e
--- /dev/null
+++ b/docs-internal/research/noodle/analysis/11-opencompany-current-state.md
@@ -0,0 +1,894 @@
+# OpenCompany frontend research snapshot, mapped against Noodle
+
+> Research snapshot: the original OpenCompany source revision was not recorded.
+> Stop and chat behavior described below predates execution-control commit
+> `516ecaca`. For current acknowledged Stop/Resume and chat protocol v2, use
+> [workflow control](../../../temporal-workflow-control.md) and
+> [chat protocol](../../../chat_protocol.md). The inventory is retained as
+> research evidence rather than a maintained runtime contract.
+
+Research note 11 of 11 for the Noodle RFC. The other ten notes analyse Noodle's UI;
+this one records what OpenCompany's own frontend already has, where it lives, what
+feeds it, and which rules any Noodle-like work must obey. It describes the state
+observed during that research review and proposes no design.
+
+## Summary
+
+- **OpenCompany already has a conversation-first owner screen.** Normal mode ("Home",
+ `client/src/features/home/`) is a team sidebar of AI employees (round avatar, status
+ pip, name, role), a header naming the employee on screen, a shared chat
+ (`client/src/features/chat/`) with right-aligned owner bubbles and left-aligned,
+ bubble-less replies beside the employee's avatar, a composer with Attach, paste and
+ drop, dictation, slash commands, Web and Ask first chips and a round Send/Stop button,
+ and a right-hand Workspace dock with Browser, Canvas and Mobile tabs.
+- **A Noodle "bot" is closest to an OpenCompany "employee", which is one saved
+ workflow.** The employee id is the workflow id, the name is the workflow name, and the
+ conversation is the chat session whose id is that workflow id. That coupling is the
+ biggest structural difference from Noodle: a chat session belongs to exactly one
+ workflow, answers only its owner, follows the workflow's control state (send, queue or
+ closed), allows one live answer at a time, and is cleared by a Reset.
+- **The chat is richer than Noodle's in agent-specific areas**: AG-UI style streamed
+ runs with tool steps, generated UI (json-render, 12 components), approval cards with
+ Undo, edit and regenerate branches with version steppers, Good/Bad ratings, numbered
+ citations, follow-up suggestions and document cards that open the Canvas.
+- **The main gaps against Noodle**: no group conversations (one persona per chat, one
+ workflow per session, no @mentions), no sidebar search, sections, previews, timestamps
+ or unread markers, no wallpapers or glass surfaces (Home is light and dark only, and blur
+ exists only on scrims), no emoji reactions (only thumbs up/down on replies), no voice
+ messages or calls (dictation only), no screen capture or annotation, no link unfurls,
+ no chat effects, no message context menu, no floating windows, no Hub sharing (multi-user
+ mode has no data isolation), no MCP connectors in Home, no keybinding settings, and no
+ harness, model or backstory editing from Home.
+- **Strict frontend rules apply**: shadcn primitives, `ActionButton` intents, token-only
+ Tailwind, no opacity arithmetic, no palette names, lucide icons, Zustand slice
+ selectors, TanStack Query for server state, snake_case on the wire, CloudEvents
+ broadcasts, the WCAG 2.5.7 drag alternative, and the chat protocol's
+ change-the-doc-in-the-same-commit rule.
+
+## Scope (files read)
+
+Documentation:
+
+- `CLAUDE.md` (section 7 "Frontend Design + Theme System (strict)" at `CLAUDE.md:449`,
+ section 8 "Naming Conventions" at `CLAUDE.md:469`, "Frontend Performance Architecture"
+ at `CLAUDE.md:543`, "Normal/Dev Mode Toggle" at `CLAUDE.md:936`, "Console Panel" at
+ `CLAUDE.md:951`, and the broadcast notes at `CLAUDE.md:2791` and `CLAUDE.md:2812`).
+- `docs-internal/normal_mode.md`, `docs-internal/chat_protocol.md` (client, messages,
+ generated UI, approvals, attachments, branches, feedback, sources, error codes),
+ `docs-internal/frontend_architecture.md`, `docs-internal/theme_system.md` (token tiers,
+ Home tokens, anti-patterns, class registry), `docs-internal/design-system/IMPLEMENTATION.md`,
+ `docs-internal/design-system/HANDOFF.md` (skimmed), `docs-internal/browser_workspace.md`,
+ `docs-internal/canvas_node.md` (skimmed), `docs-internal/employee_teams.md`,
+ `docs-internal/agent_teams.md` (opening), `docs-internal/browser.md` (profiles section),
+ `docs/mobile-workspace.md` (opening).
+- The local, gitignored design handoff `design_handoff_opencompany_home/` (its
+ `chat/README.md`, `tokens/chat.css`, `tokens/home.css`, a keyword scan of
+ `reference/OpenCompany Chat.dc.html`, and the top-level `README.md`).
+
+Source:
+
+- `client/src/features/home/`: `HomeShell.tsx`, `sidebar/HomeSidebar.tsx`,
+ `header/HomeHeader.tsx`, `header/NewConversationButton.tsx`, `header/ThemeButton.tsx`,
+ `employee/EmployeeView.tsx`, `employee/EmployeeChat.tsx`, `employee/EmployeeWork.tsx`,
+ `employee/EmployeeAccess.tsx`, `employee/GiveTeam.tsx`, `employee/useEmployeeControl.ts`,
+ `hire/HireView.tsx`, `hire/Composer.tsx`, `genui/HireDraftPanel.tsx`,
+ `workspace/WorkspaceDock.tsx`, `workspace/WorkspaceButton.tsx`, `settings/HomeSettings.tsx`,
+ `settings/AccessTab.tsx`, `settings/BillingTab.tsx`, `settings/ProfileTab.tsx`,
+ `orb/OrbStage.tsx`, `orb/OrbSlot.tsx`, `approvals/data.ts`, `data/employees.ts`,
+ `data/schemas.ts`, `data/presentation.ts`, `data/identity.ts`, `data/liveTask.ts`,
+ `data/talk.ts`, `state/homeStore.ts`, `ui/primitives.tsx`, `ui/pillToast.tsx`.
+- `client/src/features/chat/`: `ChatPane.tsx`, `host.ts`, `index.ts`,
+ `thread/ChatThread.tsx`, `thread/ChatAvatar.tsx`, `thread/model.ts`, `thread/timeLabel.ts`,
+ `turns/UserTurn.tsx`, `turns/AssistantTurn.tsx`, `turns/ReplyActions.tsx`,
+ `turns/StepsDisclosure.tsx`, `turns/ArtifactCard.tsx`, `turns/MessageAttachments.tsx`,
+ `turns/SourceChips.tsx`, `turns/GeneratedUiBlock.tsx`, `composer/Composer.tsx`,
+ `composer/VoiceRecorder.tsx`, `composer/SlashMenu.tsx`, `composer/attachments.ts`,
+ `data/schemas.ts`, `data/thread.ts`, `data/conversation.ts`, `data/chatContext.ts` (plus
+ the request types in `data/approvals.ts`, `data/runs.ts`, `data/send.ts`, `data/stop.ts`,
+ `data/branches.ts`, `data/uiState.ts`), `markdown/ReplyMarkdown.tsx`,
+ `markdown/SafeImage.tsx`, `markdown/workspaceImage.ts`, `markdown/components.tsx`,
+ `approval/ApprovalCard.tsx` (opening), `genui/catalog.ts` and `genui/views.tsx`
+ (structure).
+- Shell and shared: `client/src/components/shell/ModeToggle.tsx`,
+ `client/src/app/AppShell.tsx`, `client/src/app/ShellThemeProvider.tsx`, the
+ `client/src/components/ui/` inventory (plus the `button.tsx`, `textarea.tsx` and
+ `toggle.tsx` variants and `ConsoleChat.tsx`), `client/src/components/catalog/presentation.ts`,
+ `client/src/components/catalog/primitives.tsx`, `client/src/components/workspace/WorkspaceTabs.tsx`,
+ `client/src/lib/motion.ts` (opening), `client/src/stores/chatRunStore.ts` (opening),
+ `client/src/contexts/WebSocketContext.tsx` (chat, lifecycle and default cases).
+- Theming: `client/src/themes/base.css`, `client/src/themes/light.css`,
+ `client/src/themes/dark.css`, the `.chat-msg` rules in the ten skin files, the helper
+ list in `client/src/themes/animations.css`, and `client/src/index.css` (imports, the
+ `@theme inline` bridge, chat markdown).
+- Server spot checks: `server/services/chat/access.py`, `server/services/employees/builder.py`,
+ `server/services/employees/start.py`, `server/services/employees/handlers.py` and
+ `server/services/employees/safe_apply.py` (grep level), `server/config/credential_providers.json`
+ and `server/config/ai_cli_providers.json` (summaries), and the Electron window handler
+ in `desktop/src/main/index.ts`.
+
+Nothing was built, run or tested; statements about behaviour come from code and docs.
+
+## Findings
+
+### 1. Shell, screens and the theme rule
+
+- **Two screens, one switch.** `useAppStore.shellMode` (`'normal' | 'dev'`, persisted as
+ `ui_shell_mode`) selects Home or the workflow editor; both are lazy chunks
+ (`client/src/app/ShellModeSwitch.tsx`). Switching always goes through `enterNormal` /
+ `enterDev` (`client/src/app/useShellActions.ts`), never `setShellMode`. The switch is
+ `ModeToggle` (`client/src/components/shell/ModeToggle.tsx:19-52`, a segmented
+ `ToggleGroup`), shown in the Home header and the editor toolbar, plus Ctrl/Cmd+Shift+D.
+ `VITE_NORMAL_MODE=false` turns Home off.
+- **App shell.** `client/src/app/AppShell.tsx:86-101` owns the decorative `.app-frame`,
+ boot effects (sound sync, page-activity pause, current-workflow sync, saved-graph sync,
+ UI defaults, the mode shortcut, orb disposal) and the app-level Settings and
+ Credentials dialogs.
+- **Home is light and dark only.** `client/src/app/ShellThemeProvider.tsx:14-17` passes
+ `baseOnly` to `ThemeProvider` while Home shows, so a stylized theme chosen in Dev shows
+ as its family's base (Atomic as light, Cyber as dark) and applies again in Dev. The
+ pre-paint script in `client/index.html` applies the same rule to the first frame. The theme
+ button (`client/src/features/home/header/ThemeButton.tsx:20-41`) flips light and dark
+ with a circular View Transition reveal from the button.
+
+### 2. Home layout regions
+
+```
++------------------+------------------------------------------------+------------------+
+| HomeSidebar | HomeHeader (--h-home-header, 52px) | WorkspaceDock |
+| --w-home-sidebar | [open][logo] identity or title ... [New conv] | 460px default, |
+| (260px, | [Workspace pill] [Normal|Dev] [theme] | drag 360px .. |
+| collapsible) +------------------------------------------------+ window - 420px, |
+| logo [close] | OrbStage: absolute, z-0, behind the content | Expand / Close |
+| [+ New employee]| current view, z-10: | header: avatar, |
+| AI EMPLOYEES n | hire: orb, greeting, hero, hire composer, | "{Name}'s |
+| rows: avatar + | template chips, setup draft | workspace", |
+| status pip, | employee: ChatPane (thread above, dock with | task line, pill, |
+| name, role, | notices, composer, footnote below) | main action |
+| approvals | | tabs: Browser / |
+| badge, delete | | Canvas / Mobile |
+| profile row | | |
++------------------+------------------------------------------------+------------------+
+ Overlays: HomeSettings (Modal, 1040x760), shell Credentials dialog, AlertDialogs,
+ pill toasts (bottom-centre, one at a time).
+```
+
+`client/src/features/home/HomeShell.tsx:78-110` assembles it: `HomeSidebar`, a `<main>`
+column holding `OrbStage`, `HomeHeader` and the current view, then `WorkspaceDock` and
+`HomeSettings`. The hire view scrolls as one page; the employee view gets a column that
+does not scroll so the chat can scroll its own thread
+(`client/src/features/home/HomeShell.tsx:88-106`). A view switch scrolls to the top and
+plays a fade, rise and unblur through `lib/motion`
+(`client/src/features/home/HomeShell.tsx:62-76`).
+
+### 3. Home component inventory
+
+| Region | Component (path) | What it renders | Data behind it |
+|---|---|---|---|
+| Sidebar | `client/src/features/home/sidebar/HomeSidebar.tsx:204-247` | Logo with intro and pulse, close button, "New employee" (`ActionButton intent="run"`, lines 235-242), team list, profile row | `useHomeStore` (open, view), `useEmployeesQuery` |
+| Sidebar row | `client/src/features/home/sidebar/HomeSidebar.tsx:35-144` (`EmployeeRow`) | `Avatar` with status pip and working pulse (line 99), name, role (one line), pending-drafts count badge (lines 104-111), hover/focus delete X with `AlertDialog` (lines 113-141), new-hire glow animation (lines 62-82) | `presentEmployee` (`client/src/features/home/data/presentation.ts:92-105`), `useWorkflowControlPending`, `useAppStore.deleteWorkflow` |
+| Sidebar list | `client/src/features/home/sidebar/HomeSidebar.tsx:146-182` (`TeamList`) | Micro label "AI employees" with count, skeleton rows, error retry, empty hint | `useEmployeesQuery` |
+| Sidebar footer | `client/src/features/home/sidebar/HomeSidebar.tsx:184-202` (`ProfileRow`) | Owner avatar, name, gear; opens Settings > Profile | `useOwnerSettings` (`client/src/features/home/data/profile.ts`) |
+| Header | `client/src/features/home/header/HomeHeader.tsx:163-194` | Open-sidebar and logo when collapsed; hire title or the employee identity; New conversation (Talk on only), Workspace pill, mode toggle, theme button | `useHomeStore`, employee summary |
+| Header identity | `client/src/features/home/header/HomeHeader.tsx:147-161` | Small avatar (photo menu: upload or remove, lines 40-91), name with rename pencil (lines 93-145), subtitle "role · apps", compact status pill | `useRenameEmployee`, `useSetEmployeePhoto` (`client/src/features/home/data/identity.ts:24-55`) |
+| Header action | `client/src/features/home/header/NewConversationButton.tsx:24-63` | "New conversation" with a confirming `AlertDialog`; clears the thread and what the employee remembers | `useClearChat` (`clear_chat_messages`) |
+| Hire view | `client/src/features/home/hire/HireView.tsx:24-107` | Orb slot, greeting line with "N working now", hero "Who should we hire today?", hire composer, template chips, setup draft | `useHireComposer`, `useStarterHire`, `useConnectors`, `useEmployeesQuery`, `useOwnerSettings` |
+| Hire composer | `client/src/features/home/hire/Composer.tsx` | Job box (`rounded-composer`, `shadow-float`), connected-apps pill, Create | presentational |
+| Setup draft | `client/src/features/home/genui/HireDraftPanel.tsx` | "Writing their setup…" with timer and Cancel, the json-render setup screen, failures | `generate_employee_setup`, `cancel_employee_setup`, `hire_employee` |
+| Employee page | `client/src/features/home/employee/EmployeeView.tsx:54-101` and `client/src/features/home/employee/EmployeeChat.tsx:107-176` | Loading and missing states, then `ChatPane` with Home's host: orb and hire notes on top, notices above the box, a footnote on Ask first | team list, detail fallback, `useLaneRun`, `useRetryNote` |
+| Notices | `client/src/features/home/employee/EmployeeChat.tsx:73-105` | Failure-pause alert, pending changes (Apply), live work card, Give them a team, pending app-access requests, Help in browser, Turn on Talk or a "can't message" note, a state notice beside the main action | summary fields (`pause_reason`, `pending_changes`, `browser_request`, `talk.state`, `can_give_team`) |
+| Live work | `client/src/features/home/employee/EmployeeWork.tsx:105-123` | "Live work" card: state message, elapsed time, last activity, up to three current steps, each with `member · status`, "Show all activity" | `useEmployeeDetailQuery(live)` (`work_progress`, `job_progress`), the chat lane |
+| Team offer | `client/src/features/home/employee/GiveTeam.tsx:10-50` | "Give them a team": a review listing responsibilities, then apply | `plan_employee_team`, `give_employee_team` |
+| App access | `client/src/features/home/employee/EmployeeAccess.tsx:8-37` | Allow / Not now / Remove access per app grant | `list_employee_access` (polled every 5 s), `decide_employee_access` |
+| Workspace pill | `client/src/features/home/workspace/WorkspaceButton.tsx:14-40` | Toggle tinted purple while open; a blinking dot while closed and someone works | `useHomeStore`, `useEmployeesQuery` |
+| Workspace dock | `client/src/features/home/workspace/WorkspaceDock.tsx:159-254` | Header (avatar, "{Name}'s workspace", live task line, Live or status pill, main action, Expand, Close), left-edge resize separator, `WorkspaceTabs` with `BrowserWorkspace`, `WorkspaceCanvas` (lazy) and `MobileWorkspace` | employee summary (`browser_nodes`, `workspace_nodes`, `canvas_node_id`), `useLiveTask`, `useEmployeeControl` |
+| Settings | `client/src/features/home/settings/HomeSettings.tsx:134-180` | `Modal` with a searchable left nav; pages App access, Profile, Billing (Settings group) and Skills, Connectors, Plugins (Customize group) (`PAGES`, lines 52-94) | per page: `EmployeeAccess`, `useOwnerSettings`, `get_employee_usage`, user-skill handlers, `CredentialsBrowser`, `client/src/features/home/hire/starters.json` |
+| Orb | `client/src/features/home/orb/OrbStage.tsx:9-24`, `client/src/features/home/orb/OrbSlot.tsx:17-34`, `client/src/features/home/orb/orbEngine.ts` | A three.js render of the logo behind the content, gliding into the slot each view reserves; the static mark without WebGL or under reduced motion | `client/src/features/home/orb/orb.ts` energy targets and spikes |
+| Toasts | `client/src/features/home/ui/pillToast.tsx:45-58` | One bottom-centre pill at a time on its own sonner toaster, with sound | none |
+| Small parts | `client/src/features/home/ui/primitives.tsx` | `Avatar` (sm/md/lg, photo or initial, status pip, lines 24-63), `StatusDot` (65-73), `StatusPill` (83-106), `MicroLabel` (108-112); re-exports `AppMark` and `SearchField` from `client/src/components/catalog/primitives.tsx` | presentation tables |
+
+### 4. Home data layer, WebSocket requests and broadcasts
+
+State ownership follows the repo rule: server data in TanStack Query, UI state in a
+Zustand store.
+
+- **`useHomeStore`** (`client/src/features/home/state/homeStore.ts:82-219`): `view`
+ (`{kind:'hire'} | {kind:'employee', workflowId}`, line 15), sidebar open (persisted
+ `home_sidebar_open`), Settings open, tab and category, the new-hire row glow and logo
+ pulse nonces, a composer-focus nonce, the hire notice, and the Workspace (open, width
+ and tab persisted under `home_workspace_v1`; `workspaceFor`, `workspaceWide` and a
+ Canvas focus request kept per session). It holds no server data by design (lines 1-7).
+- **Team queries** (`client/src/features/home/data/employees.ts`): `useEmployeesQuery`
+ (`list_employees`, `staleTime` 30 s, `refetchOnMount: 'always'`, lines 36-53) and
+ `useEmployeeDetailQuery` (`get_employee`; with `live` it polls every 5 s while work is
+ active and every 15 s otherwise, and invalidates at most every 3 s on node-status
+ changes, lines 55-100). Summaries are parsed forgivingly with zod
+ (`client/src/features/home/data/schemas.ts:38-86`).
+- **Presentation** (`client/src/features/home/data/presentation.ts`): maps server status
+ to pill tone and label (`working`, `ready`, `paused`, `attention`, and `waiting`
+ "Needs you" when drafts or a browser request wait, lines 52-105), the main action
+ (Pause, Resume, Start, Connect an app, Connect an AI model, Open in Dev mode), and the
+ message-box mode (`send`, `queue`, `start`, lines 134-151). Token classes live there
+ too (lines 190-210).
+- **Other hooks**: `client/src/features/home/data/identity.ts` (rename and photo),
+ `client/src/features/home/data/talk.ts` (Turn on Talk, Apply, "Stop work and apply",
+ and the retry note), `client/src/features/home/data/liveTask.ts:36-63` (the live "Now"
+ line from the todo cache and node statuses), `client/src/features/home/data/usage.ts`,
+ `client/src/features/home/data/skills.ts`, `client/src/features/home/data/profile.ts`,
+ `client/src/features/home/approvals/data.ts`.
+
+Requests Home sends (all over the main WebSocket, snake_case payloads):
+
+| Purpose | Request types |
+|---|---|
+| Team | `list_employees`, `get_employee`, `get_employee_usage` |
+| Hiring | `generate_employee_setup`, `cancel_employee_setup`, `hire_employee` |
+| Control | `start_employee`, `pause_workflow`, `resume_workflow` (through `useWebSocketActions`), `enable_employee_talk`, `apply_employee_changes` (optionally `stop_work: true`) |
+| Identity | `rename_employee`, `set_employee_photo` (after `POST /api/workspace/{workflow_id}/uploads`) |
+| Teams and access | `plan_employee_team`, `give_employee_team`, `list_employee_access`, `decide_employee_access` |
+| Settings | user settings read and save, the user-skill family (`create_user_skill`, `update_user_skill`, `delete_user_skill`, `get_skill_content`, `lookup_skill_metadata`), the credential catalogue |
+| Delete | `DELETE /api/database/workflows/{id}` through `useAppStore.deleteWorkflow` |
+
+Broadcasts Home and the chat react to (routing in
+`client/src/contexts/WebSocketContext.tsx`):
+
+| Wire key | Routing | Effect |
+|---|---|---|
+| `employee_lifecycle` | default fan-out (`client/src/contexts/WebSocketContext.tsx:2094-2101`) to `useEmployeeLifecycle` (`client/src/features/home/data/employees.ts:165-176`) | Refetch on `hired` and `updated`, prune on `removed`; dedupe by `(source, id)` |
+| `workflow_lifecycle` | switch case that also calls `dispatchToListeners` (`client/src/contexts/WebSocketContext.tsx:1120-1143`) | Editor list refresh, `forgetWorkflow` on delete; Home refreshes the team |
+| `approval_lifecycle` | default fan-out to the chat's approvals listener (`client/src/features/chat/data/approvals.ts:390-391`) and Home's toast (`client/src/features/home/approvals/data.ts:24-36`) | Refetch drafts; a toast for drafts from the employee's own work |
+| `chat.updated` | switch case (`client/src/contexts/WebSocketContext.tsx:1192-1204`) | Invalidate the session's thread queries |
+| `chat_run_event` | switch case to `useChatRunStore.receive` (`client/src/contexts/WebSocketContext.tsx:1206-1211`) | Per-run AG-UI frames, folded once per animation frame (`client/src/stores/chatRunStore.ts:1-23`) |
+| `canvas_updated` | switch case, no listener fan-out (`client/src/contexts/WebSocketContext.tsx:1213-1236`) | Invalidate `['canvasBoard']`; the Dev dock follows the push |
+| `browser_updated` | switch case (`client/src/contexts/WebSocketContext.tsx:1238-1252`) | Dev opens its dock on Browser for an `awaiting_user` request; Home relies on the summary's `browser_request` |
+
+### 5. Chat feature inventory (`client/src/features/chat/`)
+
+#### 5.1 Host contract and hosts
+
+- Only `client/src/features/chat/index.ts` is importable from outside (ESLint
+ `no-restricted-imports`, `client/eslint.config.js:9` and following). It exports
+ `ChatPane`, the host types, `useClearChat`, `useLaneRun`, `useChatThread`, the markdown
+ components and `SafeImage`.
+- `ChatHost` (`client/src/features/chat/host.ts:34-71`) is the seam between the chat and
+ its surroundings: `kind` (`home | dev`), `sessionId`, `scope` (`all` reads every
+ generation, `live` the current one), a single `persona` (`{name, colorRole, photo}`,
+ `client/src/features/chat/host.ts:16-21`), `composer` (`send | queue | closed`), and
+ slots `notices` (above the box), `top` (the first item in the scroll area),
+ `afterThread`, `emptyState` and `footnote`, plus callbacks `notify`, `onSendRefused`,
+ `liveNote`, `onScrolledChange`, `compact` and `openArtifact`. `ChatPaneHandle` exposes
+ `focusComposer`.
+- Two hosts: Home's `EmployeeChat` (`client/src/features/home/employee/EmployeeChat.tsx:149-175`:
+ scope `all`, pill toasts, the orb on top, an Ask first footnote, Canvas items opened in
+ the Workspace) and Dev's `ConsoleChat` (`client/src/components/ui/ConsoleChat.tsx:36-95`:
+ compact, scope `live`, persona = workflow name, sonner toasts, the Canvas dock).
+
+#### 5.2 Thread and turns
+
+- **Thread** (`client/src/features/chat/thread/ChatThread.tsx:68-251`): a centred column
+ (`--w-chat-column`, 760px; compact in Dev), the host's `top`, a `role="log"`
+ `aria-live="polite"` list, then `afterThread`. It sticks to the bottom while the newest
+ turn is in view, counts arrivals while scrolled up behind a "Jump to latest, N new"
+ pill (`client/src/features/chat/thread/ChatThread.tsx:235-248`), and new turns rise in
+ with `chat-rise` (`client/src/features/chat/thread/ChatThread.tsx:141-164`). A
+ "{Name} restarted — they start fresh from here" divider marks a generation change
+ (`client/src/features/chat/thread/ChatThread.tsx:35-43`). A bottom fade
+ (`bg-linear-to-b from-transparent to-bg-app`,
+ `client/src/features/chat/thread/ChatThread.tsx:234`) assumes the opaque app
+ background. The newest 200 messages load (`client/src/features/chat/data/thread.ts:19`).
+- **Turn model** (`client/src/features/chat/thread/model.ts`): pure; one turn per message
+ plus a run's own turn before it answers; keys survive the optimistic-to-saved swap;
+ work (steps, duration) rides the run's first turn.
+- **Owner turn** (`client/src/features/chat/turns/UserTurn.tsx:29-109`): right-aligned;
+ attachments above (`client/src/features/chat/turns/MessageAttachments.tsx:12-46`: image
+ thumbnails that open full size, other files as chips with a type badge, name and
+ size); the bubble is `chat-msg chat-msg-user`, `rounded-draft rounded-br-sm` (a tail
+ corner), `border-border-default bg-bg-elevated`, at most 85% wide
+ (`client/src/features/chat/turns/UserTurn.tsx:59-68`); a button press from generated UI
+ reads as a quieter pill with a pointer icon
+ (`client/src/features/chat/turns/UserTurn.tsx:48-58`). The meta bar under it shows
+ "Sending…" while pending, then the time (`client/src/features/chat/thread/timeLabel.ts`:
+ time, "Yesterday, 9:41 AM", weekday or date), a version stepper, Edit and Copy
+ (`client/src/features/chat/turns/UserTurn.tsx:69-106`), faint until hover except on the
+ latest turn.
+- **Employee turn** (`client/src/features/chat/turns/AssistantTurn.tsx:91-269`):
+ `ChatAvatar` on the left with a spinning `opencompany-live-ring` while the run works
+ (`client/src/features/chat/thread/ChatAvatar.tsx:12-27`); then, in order, the steps
+ disclosure, three shimmer skeleton lines until text arrives, the markdown text
+ (`chat-msg chat-msg-bot`, no bubble in light and dark), generated UI blocks, document
+ cards, approval cards, a status line ("Thinking", "Writing · N tok/s", "Stopping…", an
+ Esc hint, a retry note), notes for a queued, stopped or failed run (with Try again),
+ cited sources, follow-up chips, and the reply bar.
+
+#### 5.3 Runs and streaming
+
+- A message the deployed chat trigger will answer starts a **chat run**; one live run per
+ session (the lane). Send becomes Stop while it lives; Esc anywhere in the pane stops it
+ (`client/src/features/chat/ChatPane.tsx:285-294`).
+- Run events arrive only for subscribed sessions (`chat_subscribe`,
+ `client/src/features/chat/data/runs.ts:65`), carry `seq` and `hub_epoch`, and are folded
+ by `client/src/lib/agui/reduceRun.ts` into `chatRunStore` once per animation frame;
+ gaps trigger a snapshot resync. Only the agent answering the owner streams text; tool
+ calls show as steps with plugin-provided labels; reasoning never streams.
+- Text renders block by block while streaming
+ (`client/src/features/chat/markdown/ReplyMarkdown.tsx:78-90`,
+ `client/src/features/chat/markdown/blocks.ts`) with a pulsing caret dot
+ (`client/src/index.css:659-679`).
+- The steps disclosure (`client/src/features/chat/turns/StepsDisclosure.tsx:52-87`) is a
+ pill reading "Working…" (open, shimmering) and then "Worked for 12s · 3 steps",
+ expanding to a step list with a spinner, tick, cross or dash.
+
+#### 5.4 Composer (`client/src/features/chat/composer/Composer.tsx:68-294`)
+
+- Surface: `chat-composer`, `border-border-default bg-bg-panel`, `rounded-card` (12px),
+ `shadow-modal` on Home; `rounded-lg` and an inline layout when compact
+ (`client/src/features/chat/composer/Composer.tsx:263-268`). It is a card, not a pill.
+- Text box: `Textarea variant="bare"`, auto-grows to `--h-chat-composer-max` (220px);
+ Enter sends, Shift+Enter breaks a line, IME-safe (`client/src/lib/composerKeys.ts`);
+ ArrowUp in an empty box edits the last message; placeholder "Message {Name}… Type / for
+ commands".
+- Row: "+" (a round quiet button that opens the file picker directly,
+ `client/src/features/chat/composer/Composer.tsx:184-209`; not a menu), the chips slot
+ (Web and Ask first), the microphone (dictation,
+ `client/src/features/chat/composer/Composer.tsx:210-215`), and a round `invert` Send with
+ an up arrow that becomes a filled square Stop
+ (`client/src/features/chat/composer/Composer.tsx:159-183`).
+- Slash commands (`client/src/features/chat/composer/SlashMenu.tsx:16-86`): cmdk inside a
+ Popover anchored above the box; focus stays in the textarea with `aria-controls` and
+ `aria-activedescendant`. Commands come from `get_chat_context` (generic plus the
+ employee's apps); those marked `suggest` show as cards in an empty Home chat.
+- Drafts are kept per session in `client/src/features/chat/state/composerStore.ts` (they
+ survive switching employees), and attachments in
+ `client/src/features/chat/state/attachmentStore.ts`.
+
+#### 5.5 Attachments and media
+
+- Attach, paste and drop all call `addAttachments`
+ (`client/src/features/chat/composer/attachments.ts:24-61`): at most 6 files per message
+ (`MAX_ATTACHMENTS`, `client/src/features/chat/composer/attachments.ts:17`), each at most
+ 25 MB, uploaded at once into the workflow's workspace under `uploads/`, shown as chips
+ with progress and Remove; Send waits for uploads. A drop anywhere on the chat shows
+ `DropOverlay`. The file's header comment names CLAUDE.md rule 9: the picker is the
+ drop's pointer alternative.
+- The server rebuilds each reference; the answering agent reads them as an
+ `[attachments]` line; images also reach vision-capable providers.
+- Replies can show workspace images inline; any other image waits behind a "Show image
+ from {host}" chip (`client/src/features/chat/markdown/SafeImage.tsx:19-33`,
+ `client/src/features/chat/markdown/workspaceImage.ts`). Links open in a new tab with
+ `noopener noreferrer` (`client/src/features/chat/markdown/components.tsx:14-21`). There
+ is no audio player in the thread: a sent audio file shows as a generic file chip.
+
+#### 5.6 Dictation
+
+`client/src/features/chat/composer/VoiceRecorder.tsx:31-190`: MediaRecorder with a
+blinking dot, elapsed time and 36 live level bars, Cancel and Use dictation, a
+3-minute cap; the recording is uploaded, turned into text by `transcribe_audio` (which
+deletes it) and appended to the draft. The microphone shows only when
+`dictation_status` reports a speech provider with a key
+(`client/src/features/chat/data/chatContext.ts:77-104`). This is speech-to-text into the
+box, not a voice message.
+
+#### 5.7 Generated UI
+
+`client/src/features/chat/turns/GeneratedUiBlock.tsx` lazily renders a reply's `ui`
+parts with json-render (`client/src/features/chat/genui/ChatUi.tsx`), re-sanitised
+(`client/src/features/chat/genui/prepare.ts`, `client/src/lib/jsonRender/`), revealed
+element by element while live, and drawn from a fixed catalogue of twelve components
+(`client/src/features/chat/genui/catalog.ts`: Stack, Row, Card, SlotPicker, Select,
+Toggle, TextField, Text, StatGrid, BarChart, Callout, Button). Owner edits sync through
+`chat_ui_state` (after 300 ms idle and on hide); a button press becomes
+`send_chat_message{ui_event}` and an `action` turn. The server mirrors the catalogue in
+`server/config/chat_genui_catalog.json`. Development builds add an Inspect view. The Home
+setup screen uses a separate catalogue (`client/src/features/home/genui/`, private behind
+its `index.ts`).
+
+#### 5.8 Approval cards
+
+`client/src/features/chat/approval/ApprovalCard.tsx` (theme hook `chat-approval`):
+recipient, channel, the message as it will go, Discard / Edit / Send; after Send a
+countdown with Undo (5 s), then Sending and Sent (or failed with Try again behind a
+confirmation); a discarded draft can be restored while its window lasts; "Sends when you
+resume" for a paused employee's gate. Cards sit on the reply that made them, or after
+the thread for drafts from the employee's own work
+(`client/src/features/chat/approval/StandaloneApprovals.tsx`). Ctrl/Cmd+Enter sends the
+newest pending draft (`client/src/features/chat/ChatPane.tsx:276-294`). The Ask first
+chip changes the live rule (`set_ask_first`).
+
+#### 5.9 Branches, versions and feedback
+
+Edit opens in place (`client/src/features/chat/turns/UserEditBox.tsx`) and starts a new
+branch; Try again regenerates the latest answer; `‹ 1 / 2 ›` switches versions
+(`client/src/features/chat/turns/VersionStepper.tsx`); the server decides what is
+`editable` and refuses with codes such as `revision_conflict` or `cannot_rewind`, told in
+the host's words (`client/src/features/chat/turns/runCopy.ts`). The reply bar
+(`client/src/features/chat/turns/ReplyActions.tsx:51-97`) offers Copy, Good and Bad
+(toggle buttons with `aria-pressed`; the toast says the employee will see the rating
+next time), Try again, the version stepper and the time.
+
+#### 5.10 Sources, follow-ups and artifacts
+
+- `[n]` citations become chips; cited sources list under the answer as host-and-title
+ chips (`client/src/features/chat/turns/SourceChips.tsx:19-63`); numbering is per
+ conversation.
+- Up to three follow-up suggestions show under the latest finished answer
+ (`client/src/features/chat/turns/FollowUps.tsx`).
+- A document the run wrote on its Canvas shows as a card with title, kind and version
+ (`client/src/features/chat/turns/ArtifactCard.tsx:12-37`); Open asks the host to show
+ it (Home: the Workspace's Canvas tab at that version; Dev: the Canvas dock).
+
+#### 5.11 Keyboard map (fixed, not configurable)
+
+Cmd/Ctrl+K focuses the box on Home
+(`client/src/features/home/employee/EmployeeChat.tsx:126-134`); Esc stops a running
+answer; Ctrl/Cmd+Enter sends the newest draft; ArrowUp edits the last message; Enter and
+Tab pick a slash command; Ctrl/Cmd+Shift+D switches modes; the editor has its own command
+palette (`client/src/components/ui/CommandPalette.tsx`) and F2 rename on the canvas.
+
+#### 5.12 Chat wire summary
+
+Requests: `send_chat_message`, `get_chat_messages`, `chat_subscribe`, `chat_unsubscribe`,
+`get_chat_run`, `stop_chat_run`, `chat_ui_state`, `edit_chat_message`,
+`regenerate_chat_reply`, `switch_chat_branch`, `set_chat_feedback`, `get_chat_context`,
+`clear_chat_messages`, `list_approvals`, `get_approvals`, `decide_approval`,
+`get_ask_first`, `set_ask_first`, `canvas_version`, `dictation_status`,
+`transcribe_audio`; HTTP uploads and file reads under `/api/workspace/{workflow_id}/`.
+Message rows carry `id`, `role`, `kind` (`text`, `report`, `action`, `notice`), `text`,
+`timestamp`, `run_key`, `run_id`, `parent_id`, `status`, `attachments`, `parts` (`ui`,
+`artifacts`, `approvals`, `sources`, `followups`), `siblings`, `editable`, `feedback`
+and an optional `run` summary (`client/src/features/chat/data/schemas.ts:69-111`). There
+is no author field beyond `role`, no reaction field and no read marker.
+
+### 6. Workspace dock, Settings and hiring (context)
+
+- **Workspace** (`client/src/features/home/workspace/WorkspaceDock.tsx`): one employee at
+ a time (the one last opened, else the first). Browser uses the shared live viewer
+ (`client/src/components/browser/BrowserWorkspace.tsx`: binary JPEG frames over
+ `/ws/browser`, Take control / Hand back, Help in browser); Canvas shows the employee's
+ board (`client/src/features/home/workspace/WorkspaceCanvas.tsx`, lazy); Mobile shows
+ the managed local Android emulator (`client/src/components/mobile/MobileWorkspace.tsx`).
+ At 1100px and wider it pushes the page; below, it overlays with `shadow-dock`. Its
+ resize separator is mouse-drag only
+ (`client/src/features/home/workspace/WorkspaceDock.tsx:218-228`); Expand
+ (`client/src/features/home/workspace/WorkspaceDock.tsx:67`) is the non-drag size
+ control. Full view (`client/src/components/workspace/FullView.tsx`) uses native
+ fullscreen.
+- **Settings**: Profile (names, role, preferences, timezone, `memory_across_chats`,
+ `prefer_local_ai`, appearance), Billing (tasks this month and the employee count only,
+ `client/src/features/home/settings/BillingTab.tsx:27-42`), Skills (the library plus a
+ Discover folder), Connectors (the shared `CredentialsBrowser`: every provider in
+ `server/config/credential_providers.json`, grouped by `consumer_category`: `ai`,
+ `developer` including `claude_code` and `codex_cli`, `messages`, `organize`, `devices`
+ including `browser` and `android_remote`, `research`, `business`, `language`), Plugins
+ (starter bundles), and App access.
+- **Hiring**: describe a job, an LLM drafts a json-render setup screen, and Hire builds,
+ validates, saves and starts the workflow. The builder always creates an `aiAgent` whose
+ provider and model come from the model that wrote the setup screen
+ (`server/services/employees/builder.py:766-781`); Start moves an agent on an unusable
+ provider to the owner's current model (`server/services/employees/start.py:50-82`).
+
+### 7. Design tokens and theming
+
+#### 7.1 Token tiers
+
+Colour values are hex plus `color-mix()` in per-theme files; `client/src/index.css` is a
+bridge only (`@theme inline`, `--color-X: var(--X)`, `client/src/index.css:61-315`).
+
+| Tier | Tokens (utilities) | Defined in |
+|---|---|---|
+| Surfaces | `bg-app`, `bg-panel`, `bg-canvas`, `bg-elevated`, `bg-input`, `bg-hover`, `bg-active`, `bg-overlay`, `bg-scrim-soft` | `client/src/themes/light.css:26-33`, `client/src/themes/dark.css:22-29`, `client/src/themes/base.css:205-206` |
+| Foreground and borders | `fg-default`, `fg-muted`, `fg-faint`, `fg-on-*`; `border-default`, `border-strong`, `border-focus` | `client/src/themes/light.css:36-48`, `client/src/themes/dark.css:32-44` |
+| shadcn semantic | `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring` | `client/src/themes/light.css:82-104`, `client/src/themes/dark.css:78-100` |
+| Action roles | `action-{run,stop,save,config,secret,tools}` with `-soft`, `-hover`, `-border`, `-ink` | `client/src/themes/light.css:146-175`, inks in `client/src/themes/dark.css:104-109` |
+| Node roles | `node-{agent,model,skill,tool,trigger,workflow}` with `-soft`, `-border`, and Home's identity variants `-fill`, `-hover`, `-edge`, `-ink` | `client/src/themes/light.css:123-207`, inks in `client/src/themes/dark.css:112-117` |
+| Employee status | `status-{working,ready,paused,attention,waiting}-{dot,fill,border,ink}` | `client/src/themes/base.css:208-233` |
+| Code and syntax | `code-*` | `client/src/themes/light.css:237-261`, `client/src/themes/dark.css:141-164`, one block per skin |
+| Dracula raw | `dracula-*` (the palette under the roles; not for components) | `client/src/themes/light.css:109-118` |
+| Tint scale | `--tint-*` percentages, the only home of alpha numbers | `client/src/themes/base.css:75-110` |
+
+Avatar colours come from a role, not a free colour: `AVATAR_CLASS`
+(`client/src/components/catalog/presentation.ts:5-11`) maps `agent | model | tool |
+trigger | workflow` to `bg-node-X-fill border-node-X-edge text-node-X-ink`.
+
+#### 7.2 Type
+
+Geist Variable for display and body on light and dark, and the system mono stack for
+numbers, state and code (`client/src/themes/light.css:50-53`;
+`@fontsource-variable/geist` imported at `client/src/index.css:4`). The base scale runs
+11 to 44px (`client/src/themes/base.css:57-65`), plus Home steps `--text-meta` 12.5,
+`--text-row` 13.5, `--text-lead` 15, `--text-title` 22 and `--text-hero` 36 with hero
+tracking and leading (`client/src/themes/base.css:162-169`). Sentence case; uppercase
+with `--tracking-label` only in micro labels.
+
+#### 7.3 Radii
+
+Home radii are multiples of each theme's `--radius-lg`, so square themes stay square:
+`--radius-row` 10, `--radius-card` 12, `--radius-panel` 16, `--radius-draft` 18,
+`--radius-composer` 22, plus `--radius-pill` (`client/src/themes/base.css:153-160`). The
+Tailwind `rounded-sm/md/lg/xl` utilities are computed from `--radius` and do not follow
+themes (`client/src/index.css:156-159`, noted in `docs-internal/theme_system.md`).
+
+#### 7.4 Motion
+
+All Web Animations go through `client/src/lib/motion.ts`, which reads `--dur-*` and
+`--ease-*` tokens, runs at 1 ms under reduced motion or a hidden page, and never starts
+loops then. Home choreography durations and easings live at
+`client/src/themes/base.css:121-151`; chat durations (`--dur-chat-rise`,
+`--dur-genui-enter`, `--dur-follow-in`, `--dur-version-swap`, `--dur-popover-in`,
+`--dur-chip-pop`, `--dur-live-ring`, `--dur-shimmer`, `--dur-caret` and others) at
+`client/src/themes/base.css:184-206`. CSS helper classes (`opencompany-live-ring`,
+`-shimmer`, `-shimmer-text`, `-shimmer-slot`, `-spinner`, `-dots`, `-caret`, `-draw`,
+`-grow`, `-pip-pulse`) are in `client/src/themes/animations.css`; every CSS animation
+pauses while the page is hidden (`client/src/themes/base.css:326-330`).
+
+#### 7.5 Shadows, glows and anything glass-like
+
+- Elevation: `--shadow-card`, `--shadow-card-hover`, `--shadow-modal`
+ (`client/src/themes/base.css:52-54`, `client/src/themes/dark.css:120-122`) and Home's
+ `--shadow-float`, `--shadow-popover`, `--shadow-dialog`, `--shadow-dock`
+ (`client/src/themes/light.css:209-215`, `client/src/themes/dark.css:123-126`).
+- Glows: `--glow-connect`, `--glow-hire`, `--glow-hire-settle`, `--glow-refine`,
+ `--glow-task` and `--tint-pip-ring`; dark keeps the neon, light swaps each for its ink
+ (`client/src/themes/light.css:217-230`, `client/src/themes/dark.css:128-136`).
+- Blur: one token, `--blur-scrim` (6px, `client/src/themes/base.css:151`), used behind
+ Home dialogs and by the chat's drop overlay (`backdrop-blur-(--blur-scrim)` over
+ `bg-bg-scrim-soft`, `client/src/features/chat/composer/DropOverlay.tsx:15`); the shadcn
+ `Dialog` and `AlertDialog` overlays use `backdrop-blur-xs`. There is no translucent or
+ "glass" surface token, no frosted bubble, and no wallpaper or background-image slot
+ outside the editor canvas (`--canvas-grid`, `client/src/themes/base.css:249-254`).
+- The nearest thing to a full-bleed backdrop is the orb layer: `OrbStage` is
+ `pointer-events-none absolute inset-x-0 top-(--h-home-header) bottom-0 z-0` behind the
+ `z-10` content (`client/src/features/home/orb/OrbStage.tsx:17-23`,
+ `client/src/features/home/HomeShell.tsx:81-106`).
+
+#### 7.6 Chat theme hooks
+
+`.chat-msg .chat-msg-user` on the owner's bubble, `.chat-msg .chat-msg-bot` on a reply's
+text, `.chat-turn-user` and `.chat-turn-bot` on turns, `.chat-composer`,
+`.chat-approval` and `.chat-genui` (the class registry in
+`docs-internal/theme_system.md`). In light and dark a reply has no bubble; each of the ten
+skins paints `.chat-msg-bot` as a bubble with its own padding (for example
+`client/src/themes/atomic.css:242-244` and `client/src/themes/cyber.css:710-731`), and
+`client/src/index.css:655-658` keeps code and tables in such a bubble free of text glow.
+Because Home is light and dark only, the skin bubbles appear only in Dev's console chat.
+
+#### 7.7 The local design handoff's chat specification
+
+`design_handoff_opencompany_home/` (gitignored; the 2026-10-03 export according to the
+repo's notes) holds `chat/README.md`, `tokens/chat.css` and
+`reference/OpenCompany Chat.dc.html`. It specifies: a header with avatar, name, a live
+status pill, an Ask first toggle, a theme toggle and an artifact toggle; owner bubbles on
+the right in `--bg-elevated`; assistant rows with the avatar on the left and no bubble;
+edit and branch on owner turns; regenerate, copy and thumbs on replies; a fixed order
+inside a reply (steps, text with source chips, generated UI, approval card, sources,
+follow-ups); a composer with auto-grow, attachments, slash commands, voice with live
+bars, Web and Ask first chips and Send/Stop; and a right-hand artifact panel. Its token
+rule is "no custom colour or size tokens": every tinted surface uses the action-role
+recipe, and `tokens/chat.css` adds keyframes only. A keyword scan of the prototype found
+one `backdrop-filter` (the drop overlay) and no reactions, wallpaper, receipts or glass.
+The handoff's top-level `README.md:18` still says "This is not a chat product", which
+predates the chat screen. The repo's tokens win where values differ
+(`docs-internal/normal_mode.md:26-30`).
+
+### 8. Backend facts that shape any Noodle-like UX
+
+- **A chat session is one saved workflow.** `server/services/chat/access.py:48-61`
+ refuses a session id that names no saved workflow and any socket whose principal is not
+ the workflow's owner; only the editor's `"default"` session has no workflow.
+- **One persona, one answering agent.** The talk line is chatTrigger, then an agent, then
+ Reply in Chat (`docs-internal/normal_mode.md:538-578`). Teammates in a team work
+ through Task Manager behind the lead and never post into the thread
+ (`docs-internal/employee_teams.md`, `docs-internal/agent_teams.md`); the live work card
+ can name the member per step (`client/src/features/home/employee/EmployeeWork.tsx:72`).
+- **Conversation lifetime follows the workflow.** The thread is stamped with the
+ generation; a Reset clears it with the agent's Context; "New conversation" clears it;
+ threads are per workflow, not per user (`docs-internal/normal_mode.md`, Known gaps).
+- **The message box follows control state.** Running, starting or resuming sends;
+ paused or pausing queues one message; anything else has no box
+ (`client/src/features/home/data/presentation.ts:134-151`, the `delivery` of
+ `send_chat_message`).
+- **One live run per session.** A second send answers `run_in_progress`; edit,
+ regenerate and switch are refused while a run holds the lane.
+- **Summaries carry no conversation metadata.** `list_employees` returns status, task,
+ `done_today`, `pending_approvals`, apps, control, `hired_at` and workspace nodes, but no
+ last message, last activity time or unread count. Searches of `server/services/` for
+ unread, last-message, reaction and presence terms, and of `server/services/chat/` for
+ read and seen timestamps, found no such fields (the only "delivered" hits are chat
+ notes' `delivered_at` and the run failure code `not_delivered`).
+- **Multi-user is authentication without isolation.** `AUTH_MODE=multi` shares one
+ workflow and credential store (`CLAUDE.md`, Authentication System).
+- **Desktop shell.** `desktop/src/main/index.ts:159-163` allows same-origin
+ `window.open` and sends every other URL to the OS browser, so a same-origin pop-out
+ window is possible in the Electron app; the SPA has no route or state model for one.
+
+### 9. Drift and rule exceptions observed
+
+These matter before treating any document as the source of truth.
+
+- `docs-internal/normal_mode.md:591-622` describes Turn on Talk and Apply as a restart
+ through Reset that clears the conversation, while
+ `client/src/features/home/data/talk.ts:20-59` and `server/services/employees/handlers.py`
+ call `server/services/employees/safe_apply.py` ("after current work finishes", without
+ clearing), which matches `docs-internal/employee_teams.md`'s Safe Apply.
+- `docs-internal/normal_mode.md:192-193` says the Workspace's Android tab explains that
+ mirroring is unavailable; `client/src/features/home/workspace/WorkspaceDock.tsx:133`
+ renders `MobileWorkspace`.
+- `docs-internal/normal_mode.md:72` lists a `connectAI/` folder that does not exist;
+ Connect an AI model now opens the shell's credentials dialog
+ (`client/src/features/home/state/homeStore.ts:184-187`).
+- `docs-internal/normal_mode.md:710-787` lists five Settings pages; the code has six,
+ including App access (`client/src/features/home/settings/HomeSettings.tsx:53`).
+- The "no polling" rule (`docs-internal/frontend_architecture.md:484-487`) has
+ documented exceptions (employee detail at 5 s and 15 s, the Mobile status poll) and an
+ undocumented one (`client/src/features/home/employee/EmployeeAccess.tsx:16`,
+ `refetchInterval: 5000`).
+- `client/src/features/home/employee/GiveTeam.tsx:10-50` drives a request with
+ `useState` plus `sendRequest`, which `docs-internal/frontend_architecture.md:561` calls a
+ code smell (wrap it in a query or mutation).
+
+## Mapping table
+
+Status: **exists** (usable as is), **partial** (a related piece exists with a gap),
+**missing** (nothing comparable).
+
+| Noodle concept | OpenCompany equivalent (paths or service) | Status | Notes on the gap |
+|---|---|---|---|
+| Bot | Employee = one saved workflow; the `list_employees` summary (`client/src/features/home/data/schemas.ts:38-86`), `server/services/employees/` | exists | Heavier than a bot: a graph with trigger, agent, tools and Talk line; created by Hire or in Dev mode |
+| Bot name | `Workflow.name`; the rename pencil (`client/src/features/home/header/HomeHeader.tsx:93-145`), `rename_employee` | exists | At most 40 characters; a rename rewrites the hire-written instruction opening |
+| Illustrated avatar | Uploaded photo (`set_employee_photo`, `client/src/features/home/data/identity.ts`) or an initial on a role colour (`client/src/components/catalog/presentation.ts:5-11`) | partial | No illustrated or generated avatars; editor-built workflows cannot hold a photo (`unsupported`) |
+| Backstory (role prompt) | Agent `system_message` from `server/services/employees/prompt.py`; `role`, and the detail's `job`, `plan`, `rules` | partial | No Home editor; editable only in Dev (agent parameters) or by asking in Talk (Agent Builder) |
+| Public description | `description` in the `get_employee` detail; the sidebar shows `role` | partial | No public profile or audience |
+| Harness and model | `aiAgent` provider and model set at hire (`server/services/employees/builder.py:766-781`), healed at Start (`server/services/employees/start.py:50-82`); CLI agents (Claude Code, Codex, Gemini; `server/config/ai_cli_providers.json`) as Dev node types; local models via Ollama, LM Studio, OpenAI-compatible endpoints and `prefer_local_ai` | partial | Home offers no harness or model choice; hires never use a CLI harness; no Antigravity, OpenCode, Grok Build or Apple Intelligence harness |
+| Own workspace folder | `~/.opencompany/workspaces/<slug>/`, `uploads/`, the Canvas, the gallery node | exists | No Home file browser; the Canvas shows only pushed items |
+| Tools and MCP | App-registry tools (`server/config/employee_apps.json`), the Agent Builder from Talk, the Skills library | partial | No MCP connectors in Home (`docs-internal/normal_mode.md`, Known gaps) |
+| Assigned computers | Mobile tab: one managed local Android emulator (`docs/mobile-workspace.md`); host shell and process-manager nodes | partial | No VMs; one shared emulator per installation, Windows host only |
+| Assigned browsers | Browser nodes with persistent owner profiles (`docs-internal/browser.md`), the live view, Take control, Help in browser | exists | Assignment is per node in Dev; profiles are managed in Connectors > Web browser |
+| Sharing with Hub members | none | missing | Multi-user has no data isolation; threads are per workflow |
+| Group | Employee teams (a lead plus specialists via Task Manager; `client/src/features/home/employee/GiveTeam.tsx`, `docs-internal/employee_teams.md`); Agent Teams in Dev (`ai_employee`, `orchestrator_agent`, `input-teammates`) | partial | Specialists never speak in the thread; one persona per chat (`client/src/features/chat/host.ts:16-21`); a session is one workflow (`server/services/chat/access.py:48-61`) |
+| Group name and goal line | Team responsibilities shown in the GiveTeam review | missing | No group entity, title or goal |
+| Member list, stacked avatars | `EmployeeWork` shows `member · status` per step | missing | No roster UI or stacked avatars |
+| @name completion | Slash commands (`client/src/features/chat/composer/SlashMenu.tsx:16-86`) | missing | No mentions; the slash menu is the reusable pattern |
+| Sidebar search | `SearchField` (`client/src/components/catalog/primitives.tsx:62-87`), used in Settings and catalogue pages | missing | Not in the sidebar |
+| Bots and Groups sections | One "AI employees" section with a count (`client/src/features/home/sidebar/HomeSidebar.tsx:146-182`) | partial | No sections or grouping |
+| Avatar with presence dot | `Avatar` with a status pip that pulses while working (`client/src/features/home/sidebar/HomeSidebar.tsx:99`, `client/src/features/home/ui/primitives.tsx:24-73`) | exists | Shows work status (working, ready, paused, attention, needs you), not presence |
+| Name, timestamp, two-line preview | Name and role, one line each | partial | No last message and no time; summaries carry neither |
+| Unread dot | Pending-drafts count badge (`client/src/features/home/sidebar/HomeSidebar.tsx:104-111`) | partial | No read markers on the server or the client |
+| Sidebar toggle | PanelLeft buttons (`client/src/features/home/sidebar/HomeSidebar.tsx:224-233`, `client/src/features/home/header/HomeHeader.tsx:176-184`), persisted | exists | |
+| "+" new menu (New Bot, New Group) | "New employee" (`client/src/features/home/sidebar/HomeSidebar.tsx:235-242`) opens the Hire view | partial | One action, no menu, no group creation |
+| Conversation settings button | Inline controls: rename, photo menu, New conversation, the Ask first chip, the Workspace pill, the mode toggle | partial | No per-conversation settings panel; most configuration lives in Dev |
+| Per-conversation wallpaper | `OrbStage`, a full-bleed layer behind Home's main column (`client/src/features/home/orb/OrbStage.tsx:17-23`) | missing | The thread fade and surfaces assume an opaque `bg-bg-app`; nothing stores a per-employee background |
+| Centred header (large avatar, name, subtitle, members) | Left-aligned identity in `HomeHeader` (small avatar, name, "role · apps", status pill); the orb in the thread's `top` slot | partial | No centred conversation header; `Avatar` already has an `lg` size |
+| Translucent glass bubbles | Owner bubble `bg-bg-elevated` with a tail corner (`client/src/features/chat/turns/UserTurn.tsx:59-68`); replies bubble-less in light and dark; skins paint `.chat-msg-bot` | missing | No glass tokens; blur only on scrims and the drop overlay (`--blur-scrim`) |
+| User right, bot left with small avatar | `UserTurn`, and `AssistantTurn` with `ChatAvatar` | exists | |
+| Emoji tapback reactions | Good/Bad on replies (`client/src/features/chat/turns/ReplyActions.tsx:21-49`), `set_chat_feedback`, told to the employee as `[feedback]` | missing | Two values, replies only; the design-system voice forbids decorative emoji (`docs-internal/design-system/IMPLEMENTATION.md:156`) |
+| "Delivered" status | "Sending…", then the time; run states (a queued note, the live ring, Thinking, failure lines) | partial | Delivery means run admission (`delivery: now` or `queued`); no receipt label |
+| Markdown (bold, lists) | `ReplyMarkdown` (GFM, breaks, Prism, citations) | exists | |
+| Image and report attachments | Owner attachments (thumbnails, chips); document cards (`client/src/features/chat/turns/ArtifactCard.tsx`); generated StatGrid and BarChart; inline workspace images | exists | Employee-sent files appear only through the Canvas or markdown images |
+| Link previews | Source chips with host and title (`client/src/features/chat/turns/SourceChips.tsx:19-63`); links open in a new tab | partial | No unfurl cards; external images gated by `SafeImage` |
+| Chat effects | none (theme sound packs and Home glows exist) | missing | |
+| Message context menu | Hover bars on owner turns and replies | partial | No shadcn `context-menu` primitive installed |
+| Composer "+" attachment menu | "+" opens the file picker; paste; the drop overlay | partial | Not a menu |
+| Pill text field | A rounded card with auto-grow (`client/src/features/chat/composer/Composer.tsx:263-268`) | partial | A card, not a pill |
+| Mic (voice messages) | The mic dictates into the box (`client/src/features/chat/composer/VoiceRecorder.tsx`, `transcribe_audio`) | partial | No voice message sent or played |
+| Circular send button | Round `invert` Send with an up arrow, square Stop | exists | |
+| Voice messages | Dictation; an audio file attaches as a generic chip | partial | No audio bubble or player in the thread |
+| Voice calls with bots | none | missing | No realtime audio path |
+| Keyboard annotations of screen regions | none | missing | |
+| Screen-capture attachments | Pasting an image from the clipboard | partial | No in-app capture (`getDisplayMedia` is unused) |
+| Noodlets (mini-apps in chat) | Generated UI (the twelve-component catalogue, state sync, actions); the Canvas renders sandboxed HTML in the Workspace | partial | A fixed catalogue in chat; no arbitrary code inside the thread |
+| Floating conversation windows | none (Electron allows same-origin `window.open`) | missing | A single-window SPA |
+| Agent Activity window | The live work card, the steps disclosure, the Workspace task line; Dev's Console and Terminal panels | partial | No standalone activity window |
+| Usage window | Billing (tasks this month, employee count); Dev's credentials usage sections (API and LLM cost) | partial | Home shows no tokens or costs |
+| Settings: Harness | Connectors `ai` and `developer` categories (`claude_code` and `codex_cli` login), guided Connect an AI model | partial | Sign-in exists; no per-bot harness choice |
+| Settings: Bots | The sidebar and each employee's page | partial | No Bots settings page |
+| Settings: Groups | none | missing | |
+| Settings: Hub | none | missing | |
+| Settings: Permissions | Ask first (`set_ask_first`), App access (`client/src/features/home/settings/AccessTab.tsx`), the browser read-only while asking, workspace containment, data mounts | partial | No restricted versus unrestricted sandbox switch |
+| Settings: Keybindings | Fixed shortcuts (section 5.11) | missing | Not configurable |
+| Settings: MCP connections | none in Home | missing | |
+| Settings: Companion apps | The Workspace dock tabs | partial | |
+| Companion: Computer | The Mobile tab, host shell nodes | partial | No VMs |
+| Companion: Browser | The Browser tab, profiles, Take control, help requests | exists | Previews reach the chat only as Canvas items or workspace images |
+| Companion: Applet | Canvas sandboxed HTML, URL and PDF items; code executors; deploy nodes | partial | No applet runner surface |
+| Companion: Hub | `company deploy`, Docker, desktop hosting | partial | Hosting exists; sharing does not |
+| Companion: Mobile (iOS client) | Messaging channels (Telegram, WhatsApp and others) and the web UI | partial | No native client |
+
+## Constraints any implementation must obey
+
+From `CLAUDE.md` section 7 (`CLAUDE.md:449-466`), quoted briefly:
+
+1. "Compose shadcn primitives from `client/src/components/ui/` ... Do not hand-roll modals,
+ dropdowns, menus, toasts, dialogs, or buttons when a primitive exists." Missing ones are
+ added with `bun x shadcn@latest add <name>` (from `client/`, with
+ `OPENCOMPANY_INSTALLING=true`, `docs-internal/frontend_architecture.md:703-708`).
+ Installed today: accordion, alert, alert-dialog, badge, button, card, checkbox,
+ collapsible, command, dialog, dropdown-menu, form, input, label, popover, progress,
+ select, skeleton, slider, sonner, switch, tabs, textarea, toggle, toggle-group, tooltip,
+ plus our `action-button` and `Modal`. Not installed: context-menu, sheet, scroll-area,
+ hover-card, separator, resizable, avatar.
+2. "Action buttons → `<ActionButton intent="...">`", with intents `run | stop | save |
+ config | secret | tools`, never a colour.
+3. "Style with Tailwind classes, not `style={{...}}`"; inline style only for genuinely
+ dynamic values.
+4. Use the token tier table (section 7.1 above).
+5. "No opacity arithmetic at call sites" (`bg-primary/10`, `${color}25`): add a named
+ variant to the theme instead.
+6. "No palette names in components" and no theme-locked names; go through `--action-X` or
+ `--node-X`.
+7. "No `useAppTheme()` in new files."
+8. "Icons → `lucide-react`"; backend icons go through `<NodeIcon size={token}>`, never
+ sized with `h-*`, `w-*` or `text-*`.
+9. "Any `draggable` element that performs a function must ship a pointer-operable,
+ non-drag control reaching the same end state through the same write path" (WCAG 2.2 SC
+ 2.5.7); keyboard support alone does not satisfy it. The chat's attachments already
+ follow this (the picker and the drop share one `addAttachments`).
+
+Naming (`CLAUDE.md:469`): snake_case for Python, JSON config keys, WebSocket message types
+and database columns; camelCase for TypeScript identifiers; hooks named `useX`; payloads
+cross the wire in snake_case and are bound to camelCase locals by hand, never by a
+serializer.
+
+State and performance (`CLAUDE.md:543` onward,
+`docs-internal/frontend_architecture.md:546-565`):
+
+- Read Zustand with slice selectors, never whole-store destructuring.
+- Server records live in TanStack Query, never duplicated in Zustand; mutate, then
+ invalidate the key. Imperative `useEffect` plus `sendRequest` plus `setState` is a smell.
+- High-frequency push state goes in a small slice-subscribed store (the
+ `nodeStatusStore` and `chatRunStore` pattern), never on `WebSocketContext.value`.
+- Gate catalogue and spec queries on `isReady`; entries read through
+ `useSyncExternalStore` need `gcTime: GC_TIME.FOREVER`; persisted prefixes need matching
+ `setQueryDefaults`.
+- No polling for anything the backend can push; panels whose data agents write while they
+ are closed declare `refetchOnMount: 'always', staleTime: 0` (`CLAUDE.md:2812`).
+- `React.memo` with `nodePropsEqual` on canvas nodes (editor only).
+
+Real-time and wire contracts:
+
+- New server-to-client lifecycle broadcasts use a typed CloudEvents factory
+ (`source = "opencompany://services/<area>"`, `type = "com.opencompany.<area>.<event>"`,
+ `subject` = the entity id, scope inside `data`); clients validate and dedupe by
+ `(source, id)`, and `server/tests/test_status_broadcasts.py` keeps raw call sites out
+ (`CLAUDE.md:2791`). Plugin-owned events live in the plugin's `_events.py`.
+- Identity-only broadcasts plus an authorized refetch is the house pattern
+ (`chat.updated`, `canvas_updated`, `employee_lifecycle`).
+- A `WebSocketContext` switch case shadows the default listener fan-out unless it calls
+ `dispatchToListeners` (`client/src/contexts/WebSocketContext.tsx:998-1008`, and the
+ warning at `client/src/contexts/WebSocketContext.tsx:1219`).
+- The chat protocol (`docs-internal/chat_protocol.md:10-11`): "Change this document in the
+ same commit as any change to the shapes below, and bump `protocol_version` ... when an
+ existing field changes meaning." Run events go only to subscribed sockets, in
+ snake_case, in the CloudEvents envelope; chat commands refuse the internal socket and
+ non-owners.
+- Module boundaries: `client/src/features/chat/` and `client/src/features/home/genui/`
+ are importable only through their `index.ts` (ESLint).
+- Contracts locked by tests include `server/tests/test_genui_catalog_sync.py`,
+ `server/tests/test_hire_payload_contract.py`, `server/tests/test_home_catalog_contract.py`,
+ `server/tests/test_frontend_no_node_type_copies.py` (no node-type strings copied into
+ the client, which is why the Canvas tab id is `board`,
+ `client/src/features/home/state/homeStore.ts:18-21`),
+ `server/tests/test_credential_catalogue_consumer_fields.py` and
+ `server/tests/test_status_broadcasts.py`.
+
+Theme and motion:
+
+- Home shows light and dark only (`ShellThemeProvider`, `baseOnly`); never branch on a
+ theme name in a component; visual differences belong in theme CSS
+ (`docs-internal/theme_system.md:268-279`).
+- Motion goes through `client/src/lib/motion.ts` and the `--dur-*` / `--ease-*` tokens;
+ honour reduced motion and the hidden-page pause; never animate `opacity` on whole canvas
+ nodes.
+- Use the Home radii tokens (`rounded-row`, `-card`, `-panel`, `-draft`, `-composer`,
+ `-pill`) where a shape must follow the theme; `rounded-sm` to `rounded-xl` do not.
+- The design handoff's chat rule: no custom colour or size tokens; tinted surfaces use the
+ action recipe. The repo's tokens win over the bundle's values.
+- Design-system voice: sentence case, second person, "No decorative emoji — in-product
+ emoji are functional node glyphs only"
+ (`docs-internal/design-system/IMPLEMENTATION.md:156`).
+
+Security posture the chat already enforces: model-written images load only from the
+workspace route; links open with `noopener noreferrer`; attachments are rebuilt server
+side from `uploads/` (at most six); Canvas iframes keep their sandbox matrix and never
+`allow-same-origin`; `NEVER_INLINE` content types are served as attachments.
+
+## Reuse versus new, and integration points
+
+### Reusable as is or with small extensions
+
+| Piece | Path | Reuse notes |
+|---|---|---|
+| Chat pane and host slots | `client/src/features/chat/ChatPane.tsx`, `client/src/features/chat/host.ts` | `top`, `notices`, `afterThread`, `emptyState`, `footnote` and `compact` already let a host frame the conversation |
+| Thread mechanics | `client/src/features/chat/thread/ChatThread.tsx`, `client/src/features/chat/thread/model.ts`, `client/src/features/chat/thread/timeLabel.ts` | Sticky bottom, unread-while-scrolled count, rise-in, restart divider, human time labels |
+| Turns | `client/src/features/chat/turns/UserTurn.tsx`, `client/src/features/chat/turns/AssistantTurn.tsx`, `client/src/features/chat/thread/ChatAvatar.tsx` | Right bubbles, left avatar rows, the live ring, theme hooks |
+| Composer | `client/src/features/chat/composer/Composer.tsx`, `SlashMenu.tsx`, `VoiceRecorder.tsx`, `attachments.ts`, `DropOverlay.tsx` (same folder), `client/src/features/chat/state/composerStore.ts`, `client/src/features/chat/state/attachmentStore.ts` | "+", mic, round Send/Stop, the chips slot, per-session drafts; the slash menu is the pattern for a mention list |
+| Attachment display | `client/src/features/chat/turns/MessageAttachments.tsx`, `client/src/features/chat/markdown/SafeImage.tsx` | Image thumbnails and file chips |
+| Reply extras | `client/src/features/chat/turns/ReplyActions.tsx`, `VersionStepper.tsx`, `StepsDisclosure.tsx`, `SourceChips.tsx`, `FollowUps.tsx`, `ArtifactCard.tsx`, `GeneratedUiBlock.tsx` (same folder), `client/src/features/chat/approval/ApprovalCard.tsx` | Rating, versions, steps, citations, suggestions, document cards, generated UI, drafts |
+| Run plumbing | `client/src/stores/chatRunStore.ts`, `client/src/lib/agui/`, `client/src/features/chat/data/` | Ordered, resyncing run events and optimistic sends |
+| Identity primitives | `client/src/features/home/ui/primitives.tsx`, `client/src/components/catalog/presentation.ts`, `client/src/components/catalog/primitives.tsx` | `Avatar` (with `lg`), `StatusDot`, `StatusPill`, `MicroLabel`, `SearchField`, `AppMark`, `AVATAR_CLASS` |
+| Home shell and store | `client/src/features/home/HomeShell.tsx`, `client/src/features/home/state/homeStore.ts`, `client/src/features/home/ui/pillToast.tsx` | View switching, the persisted UI-prefs pattern (zod-validated localStorage), toasts |
+| Team data | `client/src/features/home/data/employees.ts`, `presentation.ts`, `schemas.ts` (same folder) | The query plus lifecycle-listener pattern; presentation tables |
+| Settings frame | `client/src/features/home/settings/HomeSettings.tsx` (`PAGES`), `client/src/components/catalog/CatalogLayout.tsx`, `client/src/components/credentials/CredentialsBrowser.tsx` | Adding a page is one entry |
+| Workspace | `client/src/features/home/workspace/WorkspaceDock.tsx`, `client/src/components/workspace/WorkspaceTabs.tsx`, `client/src/components/workspace/FullView.tsx`, `client/src/components/browser/BrowserWorkspace.tsx`, `client/src/components/mobile/MobileWorkspace.tsx` | Browser and device views, a resizable dock |
+| Motion, sound, theme | `client/src/lib/motion.ts`, `client/src/lib/sound.ts`, `client/src/themes/`, `client/src/contexts/ThemeContext.tsx` | Token-driven animation, sound packs, the theme reveal |
+| Desktop shell | `desktop/src/main/index.ts` | Same-origin windows are allowed |
+
+### New work implied by Noodle's concepts
+
+- Group conversations: a session model that is not one workflow, author identity per
+ message (today only `role`), several personas in one thread, a member roster, stacked
+ avatars and mentions.
+- Sidebar conversation metadata: the last message, its time and unread state need server
+ fields and read markers that do not exist; sections and search are client work over
+ them.
+- Wallpapers and glass: a per-conversation background store and upload path, and new
+ translucent surface and blur tokens defined for light and dark with legible text over
+ photos and video.
+- Reactions: a wire field, storage and UI beyond the two-value feedback.
+- Voice messages (an audio bubble and player), voice calls (realtime audio), screen
+ capture and region annotation.
+- Link unfurls (a server-side fetch with its own security review), chat effects, a message
+ context menu (a new primitive), floating windows, an activity window and a usage window.
+- Hub sharing (needs multi-user data isolation first), MCP connectors, keybinding
+ settings, and Home controls for harness, model and backstory.
+
+### Integration points
+
+- **Sidebar**: `client/src/features/home/sidebar/HomeSidebar.tsx` (`TeamList`,
+ `EmployeeRow`), fed by `useEmployeesQuery` and the summary built in
+ `server/services/employees/summaries.py`; refreshed through `employee_lifecycle`.
+- **Conversation header**: `client/src/features/home/header/HomeHeader.tsx` (`Identity`)
+ and the chat host's `top` slot in `client/src/features/home/employee/EmployeeChat.tsx`
+ (where the orb sits now).
+- **Wallpaper**: the `<main>` column in `client/src/features/home/HomeShell.tsx:81-106`,
+ where `OrbStage` already draws a full-bleed `z-0` layer behind `z-10` content; the
+ thread's bottom fade (`client/src/features/chat/thread/ChatThread.tsx:234`) and the
+ composer and bubble surfaces assume an opaque background.
+- **Bubbles**: the `.chat-msg-user` and `.chat-msg-bot` hooks
+ (`client/src/features/chat/turns/UserTurn.tsx:62`,
+ `client/src/features/chat/turns/AssistantTurn.tsx:202`) and new tokens in
+ `client/src/themes/base.css`, `client/src/themes/light.css` and
+ `client/src/themes/dark.css`, bridged in `client/src/index.css`.
+- **Reactions**: `client/src/features/chat/turns/ReplyActions.tsx` and the `UserTurn`
+ meta bar on the client; `set_chat_feedback` (`server/services/chat/feedback.py`, the
+ `chat_feedback` table, `[feedback]` notes) is the precedent for storing a per-message
+ owner signal and telling the employee.
+- **Voice**: `client/src/features/chat/composer/VoiceRecorder.tsx`,
+ `client/src/lib/workspaceUpload.ts`, `transcribe_audio` and `dictation_status` in
+ `server/nodes/speech/`, the `textToSpeech` node's `AudioRef`
+ (`docs-internal/media_transport.md`), and
+ `client/src/features/chat/turns/MessageAttachments.tsx` for playback.
+- **Mentions**: `client/src/features/chat/composer/SlashMenu.tsx` and
+ `client/src/features/chat/composer/slash.ts`.
+- **Group chat**: `ChatHost.persona` (`client/src/features/chat/host.ts:16-21`),
+ `AssistantTurn` (one persona), the message schema
+ (`client/src/features/chat/data/schemas.ts:69-111`), `server/services/chat/access.py`
+ and the talk line in `server/services/employees/talk.py`; teams in
+ `server/services/employees/team_runtime.py` and the Task Manager.
+- **Floating windows**: `desktop/src/main/index.ts:159-163` and the SPA's shell
+ (`client/src/app/ShellModeSwitch.tsx`).
+
+## Open questions for the RFC author
+
+1. Is a Noodle bot an OpenCompany employee (a whole workflow with a trigger and a talk
+ line), or should a lighter chat-only agent exist beside employees?
+2. Should a group be a new conversation type spanning several workflows, or the existing
+ team inside one workflow with its specialists made visible and addressable in the
+ thread?
+3. Should Home keep its light-and-dark-only rule, or do wallpapers and glass surfaces call
+ for a new appearance dimension, and how do the ten skins relate to it?
+4. How do emoji reactions square with the design system's "no decorative emoji" rule, and
+ should a reaction reach the employee the way a rating does?
+5. Should a conversation outlive Reset, Apply and New conversation, and should one
+ employee have several conversations (Noodle-style threads) instead of one clearable
+ thread?
+6. What does "Delivered" mean here: saved, admitted as a run, or picked up by the
+ workflow? Today those are distinct states.
+7. Sidebar previews and unread state need per-owner read markers on the server; with
+ multi-user lacking isolation, whose read state is it?
+8. Hub-style sharing presupposes data isolation that `AUTH_MODE=multi` does not provide;
+ is isolation in scope?
+9. Should Home expose harness and model per employee, given that hires always build
+ `aiAgent` and the CLI harnesses exist only as Dev node types?
+10. The documentation drift in finding 9 (Apply and Turn on Talk, the Mobile tab, the
+ Settings page list) should be settled against the code before the RFC cites
+ `docs-internal/normal_mode.md`.
+11. The no-polling rule already has exceptions; should new presence or activity features
+ be push-only (a new CloudEvents broadcast) or may they poll?