| 1 | # ADR 0120: Primary work surface — Intercom or Editor (Agent / Editor analogue) |
| 2 | |
| 3 | **Status:** Accepted · Implemented |
| 4 | **Date:** 2026-05-17 |
| 5 | |
| 6 | ## Related ADRs |
| 7 | |
| 8 | | ADR | Role | |
| 9 | |-----|------| |
| 10 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | PFD / Forward / MFD topology, `presentation`, multi-window | |
| 11 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | Attention anchors; Forward = forward field of view | |
| 12 | | [0010](0010-ui-modes-toml-configuration.md) | UI modes in TOML; place for “agent-central” preset | |
| 13 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | `%LocalAppData%\CascadeIDE\settings.toml` | |
| 14 | | [0080](0080-intercom-naming-and-multi-party-channel-model.md) | Intercom — session channel, not “chat widget” | |
| 15 | | [0098](0098-semantic-first-document-as-projection.md) | Editor — powerful channel, not sole truth | |
| 16 | | [0044](0044-avalonia-host-skia-agent-chat-surface.md) | Skia host for agent chat surface | |
| 17 | | [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md) | Topic cards in overview/detail | |
| 18 | | [0119](0119-chat-slash-commands-intercom-surface.md) | Slash commands in `ChatInput` — stronger when Intercom is central | |
| 19 | | [0121](0121-intent-oriented-programming-paradigm.md) | IOP: discipline of communication; Intercom as goal-centric hub; honest stream limits | |
| 20 | | [0074](0074-settings-ui-mfd-compact-layout-overflow.md) | MFD density in a narrow column | |
| 21 | |
| 22 | ### Outside ADR |
| 23 | |
| 24 | | Document | Role | |
| 25 | |----------|------| |
| 26 | | [ui-ux/README.md](../ui-ux/README.md) | Current Flight line; legacy Focus/Balanced/Power — archive | |
| 27 | | [iop-manifest-v1.md](../iop-manifest-v1.md) | IOP: Intercom communication hub; no promise to digest any inbound stream | |
| 28 | |
| 29 | ## Summary |
| 30 | |
| 31 | - New setting **`primary_work_surface`**: **`intercom`** | **`editor`** (analogue of **Agent / Editor** in Cursor). |
| 32 | - Defines **what occupies the Forward anchor** (forward field): full **Intercom** (chat + catalog + spine) or **code editor**. |
| 33 | - Secondary contour (MFD) shows the **other** surface (editor or shell pages) without losing features. |
| 34 | - **Do not** confuse with OS **primary monitor** ([0017 § primary vs Forward](0017-multi-window-workspace-and-agent-surfaces.md#adr0017-p5-primary-vs-forward)). |
| 35 | - Product default: **`editor`**; “like Cursor” preset — **`intercom`**. Ties to [0119](0119-chat-slash-commands-intercom-surface.md). |
| 36 | - With **`intercom`**, the forward anchor is not a “message feed” but the **communication hub around a goal** (people + agents → intent → implementation), see [0121](0121-intent-oriented-programming-paradigm.md), [iop-manifest-v1.md](../iop-manifest-v1.md). |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Context |
| 41 | |
| 42 | Some users (including when working **in Cursor** with chat on the **main screen**) spend most of the session in agent dialogue. For them the cockpit metaphor “Forward = editor, chat on MFD” is **inverted** relative to real attention: center is **thought and conversation**, code **on demand**. |
| 43 | |
| 44 | CIDE already has: |
| 45 | |
| 46 | - **three anchors** PFD / Forward / MFD ([0021](0021-pfd-mfd-cockpit-attention-model.md)); |
| 47 | - **Intercom** as product model ([0080](0080-intercom-naming-and-multi-party-channel-model.md), [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md), [0096](0096-intercom-topic-card-summary-and-product-spine.md)); |
| 48 | - **configurable screen topology** via `presentation` ([0017](0017-multi-window-workspace-and-agent-surfaces.md)); |
| 49 | - **UI modes** in TOML ([0010](0010-ui-modes-toml-configuration.md)). |
| 50 | |
| 51 | Missing: an **explicit “what is in the center” switch** without manual monitor rearrangement and without changing the whole `presentation` string. |
| 52 | |
| 53 | --- |
| 54 | |
| 55 | ## Problem |
| 56 | |
| 57 | 1. **Forward is mentally fixed as editor** in the default layout — agent-central users perceive chat **peripherally**. |
| 58 | 2. **Monitor confusion:** “center screen” ≠ OS **primary display** — see [0017](0017-multi-window-workspace-and-agent-surfaces.md); need a separate **`primary_work_surface`** axis. |
| 59 | 3. **0119 (slashes)** and **topic cards** win when Intercom is already in the forward anchor; without 0120 architecture stays “chat on the side”. |
| 60 | 4. **Risk of “removing the editor”:** product goal is **change default focus**, not abandon code ([0098](0098-semantic-first-document-as-projection.md)). |
| 61 | |
| 62 | --- |
| 63 | |
| 64 | ## Decision |
| 65 | |
| 66 | <a id="adr0120-p1"></a> |
| 67 | |
| 68 | ### 1. `primary_work_surface` axis |
| 69 | |
| 70 | Allowed values: |
| 71 | |
| 72 | | Value | **Forward** anchor | Typical editor placement | |
| 73 | |-------|-------------------|---------------------------| |
| 74 | | **`editor`** *(CIDE default)* | Code editor (AvaloniaEdit) | MFD: **Intercom** / chat shell page | |
| 75 | | **`intercom`** | **Intercom** (full `ChatPanel` + Skia: overview, spine, detail) | MFD: **Editor** as page or docked panel; PFD unchanged in meaning | |
| 76 | |
| 77 | **Invariant:** both surfaces **remain available**; only the **default attention anchor** changes, like Agent / Editor toggle in Cursor. |
| 78 | |
| 79 | <a id="adr0120-p2"></a> |
| 80 | |
| 81 | ### 2. Orthogonality to other axes |
| 82 | |
| 83 | | Axis | Question | Relation to `primary_work_surface` | |
| 84 | |------|----------|--------------------------------------| |
| 85 | | **`presentation`** ([0017](0017-multi-window-workspace-and-agent-surfaces.md)) | How many windows and P/F/M shares | Independent: `(P+F+M)` on one display **and** `intercom` in Forward | |
| 86 | | **OS primary monitor** | Where Windows puts taskbar | Does **not** set Forward; see [0017 §5](0017-multi-window-workspace-and-agent-surfaces.md#adr0017-p5-primary-vs-forward) | |
| 87 | | **UiMode / Flight** ([0010](0010-ui-modes-toml-configuration.md)) | Panel visibility, capabilities | May **narrow** chrome (Dark Cockpit); does not replace anchor | |
| 88 | | **Melody / Chords** ([0060](0060-keyboard-chord-stack-fms-tactical-strategic.md)) | M/P/F zone focus | Kept; `focus_forward` focuses **forward anchor** (chat or editor) | |
| 89 | |
| 90 | <a id="adr0120-p3"></a> |
| 91 | |
| 92 | ### 3. UX contract for switching |
| 93 | |
| 94 | - **Explicit toggle** in UI (toggle, menu item, optional hotkey) — labels **`Intercom`** / **`Editor`** or **`Agent`** / **`Editor`** (copy TBD in UX; data canon — `intercom` | `editor`). |
| 95 | - Switching does **not reset** chat session or **close** open files; only **Forward host** and **default MFD page** change. |
| 96 | - State **persisted** in `settings.toml` ([0028](0028-user-settings-toml-localappdata-and-secrets.md)). |
| 97 | |
| 98 | <a id="adr0120-p4"></a> |
| 99 | |
| 100 | ### 4. Configuration (target schema) |
| 101 | |
| 102 | ```toml |
| 103 | # settings.toml (fragment) |
| 104 | [workspace] |
| 105 | primary_work_surface = "intercom" # "editor" | "intercom" |
| 106 | ``` |
| 107 | |
| 108 | Optionally in **`UiModes/Flight.toml`** (or separate `AgentCentral.toml` preset): |
| 109 | |
| 110 | ```toml |
| 111 | primary_work_surface = "intercom" |
| 112 | # capabilities: wider chat, narrower IDE Health strip, … |
| 113 | ``` |
| 114 | |
| 115 | **Default when key missing:** `editor` (compatible with current CIDE). |
| 116 | |
| 117 | <a id="adr0120-p5"></a> |
| 118 | |
| 119 | ### 5. Relation to Intercom and [0119](0119-chat-slash-commands-intercom-surface.md) |
| 120 | |
| 121 | When **`primary_work_surface = intercom`**: |
| 122 | |
| 123 | - Forward shows **topic catalog**, spine, detail — [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md), [0096](0096-intercom-topic-card-summary-and-product-spine.md). |
| 124 | - **`ChatInput`** is the natural session **command line**; slash commands ([0119](0119-chat-slash-commands-intercom-surface.md)) become the **primary** path to `build` / `test` / `card`, not peripheral. |
| 125 | |
| 126 | When **`editor`** — behavior as today; 0119 remains useful but chat need not be central. |
| 127 | |
| 128 | <a id="adr0120-p5b"></a> |
| 129 | |
| 130 | #### 5.1. Intercom-central ≠ endless stream |
| 131 | |
| 132 | `primary_work_surface = intercom` does **not** mean “everything inbound in one feed” and does **not** promise that the product or agents will **handle any volume** of human messages — without structure, **people cannot either** ([0121](0121-intent-oriented-programming-paradigm.md) § “Risks and boundaries”, [iop-manifest-v1.md](../iop-manifest-v1.md) § “Honestly about human message volume”). |
| 133 | |
| 134 | What central Intercom is for: |
| 135 | |
| 136 | - **lines of work** (topic cards, spine) instead of chaotic chat; |
| 137 | - **clarification batches** and threads ([0031](0031-agent-chat-clarification-batches-and-threading.md)); |
| 138 | - **intent-first** and slash/MCP as one contract ([0119](0119-chat-slash-commands-intercom-surface.md)); |
| 139 | - the human in Forward is **arbiter of intent and delta**, not dispatcher of every message. |
| 140 | |
| 141 | 0120 changes the **attention anchor**; IOP and the topic catalog define **how** that anchor does not become noise. |
| 142 | |
| 143 | <a id="adr0120-p6"></a> |
| 144 | |
| 145 | ### 6. Editor when Intercom-central |
| 146 | |
| 147 | - Editor is **not removed**: move to MFD “Code” page / dock / split — layout detail in implementation. |
| 148 | - **Go to definition**, open file from chat, anchors [0080](0080-intercom-naming-and-multi-party-channel-model.md) — still move focus to **editor** (temporary or with surface switch), without breaking deep links. |
| 149 | - Semantic map / PFD **need not** move to Forward. |
| 150 | |
| 151 | --- |
| 152 | |
| 153 | ## Non-goals |
| 154 | |
| 155 | - Replacing the three-zone PFD / Forward / MFD model with “chat only”. |
| 156 | - Identifying `primary_work_surface` with OS **primary monitor**. |
| 157 | - Mandatory `presentation` string change on every Agent/Editor toggle. |
| 158 | - Removing **Editor** mode or abandoning AvaloniaEdit in Forward **forever**. |
| 159 | - **Endless feed** as the target UX for Intercom-central — contradicts [0080](0080-intercom-naming-and-multi-party-channel-model.md), [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md), [0121](0121-intent-oriented-programming-paradigm.md). |
| 160 | |
| 161 | --- |
| 162 | |
| 163 | ## Implementation anchors (plan) |
| 164 | |
| 165 | | Component | Role | |
| 166 | |-----------|------| |
| 167 | | `settings.toml` | `workspace.primary_work_surface` | |
| 168 | | `MainWindow` / `MainGrid` | conditional host in Forward column | |
| 169 | | `MfdShellView` / secondary pages | second surface when `intercom` | |
| 170 | | `MainWindowViewModel` | property + switch command; save to settings | |
| 171 | | `IdeCommands` *(optional)* | `set_primary_work_surface`, `toggle_primary_work_surface` for MCP | |
| 172 | | [0119](0119-chat-slash-commands-intercom-surface.md) | slash implementation — after or parallel with host swap | |
| 173 | |
| 174 | **Order:** |
| 175 | |
| 176 | 1. Setting + toggle + host swap in `MainWindow` (no `presentation` change). |
| 177 | 2. MFD editor page when `intercom`. |
| 178 | 3. TOML “agent-central” preset + UX docs. |
| 179 | 4. MCP / hotkey as needed. |
| 180 | |
| 181 | --- |
| 182 | |
| 183 | ## Open decisions (before Accepted) |
| 184 | |
| 185 | | # | Question | Direction | |
| 186 | |---|----------|-----------| |
| 187 | | 1 | UI labels: **Intercom** vs **Agent** | Product: Intercom ([0080](0080-intercom-naming-and-multi-party-channel-model.md)); Cursor users — alias “Agent” on toggle | |
| 188 | | 2 | Editor on MFD: separate **page** vs **dock** | Page v1 (simpler parity with current shell) | |
| 189 | | 3 | Auto-switch to Editor on go-to-definition | Optional v2; v1 — explicit transition | |
| 190 | |
| 191 | --- |
| 192 | |
| 193 | ## Diagram |
| 194 | |
| 195 | ```mermaid |
| 196 | flowchart LR |
| 197 | subgraph editor_mode [primary_work_surface = editor] |
| 198 | F1[Forward: Editor] |
| 199 | M1[MFD: Intercom page] |
| 200 | end |
| 201 | subgraph intercom_mode [primary_work_surface = intercom] |
| 202 | F2[Forward: Intercom] |
| 203 | M2[MFD: Editor page] |
| 204 | end |
| 205 | toggle[User toggle / settings.toml] |
| 206 | toggle --> editor_mode |
| 207 | toggle --> intercom_mode |
| 208 | ``` |
| 209 | |
| 210 | --- |
| 211 | |
| 212 | ## Rejected alternatives |
| 213 | |
| 214 | 1. **Only change `presentation`** without a separate key — insufficient for one monitor and quick Agent/Editor toggle. |
| 215 | 2. **Chat always in Forward, editor only in popup** — breaks MCP/debug parity and familiar MFD shell. |
| 216 | 3. **New fourth “Intercom” anchor** instead of Forward swap — bloats [0021](0021-pfd-mfd-cockpit-attention-model.md) without need. |
| 217 | |
| 218 | --- |
| 219 | |
| 220 | ## Change history |
| 221 | |
| 222 | <a id="adr0120-history"></a> |
| 223 | |
| 224 | | Date | Change | |
| 225 | |------|--------| |
| 226 | | 2026-05-17 | Proposed: `primary_work_surface` (intercom \| editor), Forward/MFD swap, link to 0119. | |
| 227 | | 2026-05-17 | §5.1: Intercom-central = goal-centric communication hub; stream boundaries (0121, IOP manifest). | |
| 228 | |