| 1 | <!-- English translation of adr/0051-intent-based-attention-routing-toml.md. Canonical Russian: ../../adr/0051-intent-based-attention-routing-toml.md --> |
| 2 | |
| 3 | #ADR 0051: Intent-based attention routing (TOML) |
| 4 | |
| 5 | **Status:** Accepted · Implemented |
| 6 | **Date:** 2026-04-16 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | model of attention zones and their canonical ids | |
| 13 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | topology `presentation` | |
| 14 | | [0050](0050-declarative-instrument-zone-placement-toml.md) | declarative placement `instrument_id` by `surface_id+slot_id` | |
| 15 | |
| 16 | ## Summary |
| 17 | |
| 18 | - **Intent-based attention routing** in TOML - attention routing by intent. |
| 19 | - Communication with capabilities and zones [0021](0021-pfd-mfd-cockpit-attention-model.md). |
| 20 | |
| 21 | |
| 22 | ### Implementation snapshot |
| 23 | |
| 24 | | Element | Meaning | |
| 25 | |---------|----------| |
| 26 | | — | section `[attention_routing]` in bundle `UiModes/workspace.toml` and overlay `.cascade/workspace.toml`; intent-id - `AttentionRoutingIntentIds` | |
| 27 | |
| 28 | --- |
| 29 | ## Context |
| 30 | |
| 31 | In `UiModes/workspace.toml` and `.cascade/workspace.toml` today there is a map of the placement of UI panels by attention zones: the `[attention_zone_panels]` section specifies `panel_id -> attention_zone`. |
| 32 | |
| 33 | DX problem: |
| 34 | |
| 35 | - The user must know **internal identifiers** (which keys are valid). |
| 36 | - Names in the style of `attention_zones` / `attention_zone_panels` can easily be confused with another configuration axis: **placement of “which cockpit instrument”** in slots (see ADR [0050](0050-declarative-instrument-zone-placement-toml.md)). |
| 37 | |
| 38 | It is necessary to clearly separate two independent layers: |
| 39 | |
| 40 | 1. **Attention routing**: *where on the stage to direct the UI intent* (example: chat - in `mfd`, editor - in `forward`). |
| 41 | This is about **attention flow and geography** (`pfd/mfd/forward/hud/eicas`), but **not** about “what tool is in the slot”. |
| 42 | 2. **Instrument placement**: *which `instrument_id` is mounted in `surface_id+slot_id`* (ADR 0050). |
| 43 | This is about **cockpit slot content**, but **not** about panel/intent routing. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Solution |
| 48 | |
| 49 | Accept an intent-based attention routing configuration and **explicitly name** the section so that it does not overlap with instrument placement. |
| 50 | |
| 51 | ### 1) New section |
| 52 | |
| 53 | Replace `[attention_zone_panels]` with: |
| 54 | |
| 55 | - **`[attention_routing]`** |
| 56 | |
| 57 | Reasons: |
| 58 | |
| 59 | - the word *routing* directly indicates “routing/where to route”, and not “what is in the slot”; |
| 60 | - does not overlap in meaning with `[instrument_routing]` (ADR 0050). |
| 61 | |
| 62 | ### 2) Keys: “intents”, not internal panel ids |
| 63 | |
| 64 | Keys are human-readable intent ids (v1 match 1:1 with the current panels, but are treated as intent): |
| 65 | |
| 66 | - `solution_explorer` |
| 67 | - `chat` |
| 68 | - `git` |
| 69 | - `terminal` |
| 70 | - `editor` |
| 71 | |
| 72 | Values are canonical zone ids from ADR 0021: |
| 73 | |
| 74 | - `forward`, `pfd`, `mfd`, `hud`, `eicas` |
| 75 | |
| 76 | Example:```toml |
| 77 | [attention_routing] |
| 78 | solution_explorer = "pfd" |
| 79 | chat = "mfd" |
| 80 | git = "mfd" |
| 81 | terminal = "mfd" |
| 82 | editor = "forward" |
| 83 | ``` |
| 84 | ### 3) Link to implementation |
| 85 | |
| 86 | Inside runtime, routing remains implemented through the `panel_id -> AttentionZone` map, but TOML specifies **intent**: |
| 87 | |
| 88 | - intent id is normalized and translated into the corresponding `panel_id` (internal key). |
| 89 | - If the intent is unknown, an explicit diagnostic (log/status) is issued. |
| 90 | |
| 91 | ### 4) Layers merge (bundle/repo) |
| 92 | |
| 93 | As for the current `workspace.toml`: |
| 94 | |
| 95 | - bundle: `UiModes/workspace.toml` |
| 96 | - repo overlay: `.cascade/workspace.toml` |
| 97 | |
| 98 | Precedence rule: repo over bundle for matching keys. |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | ## Consequences |
| 103 | |
| 104 | - The config becomes clearer: the user sees **intents**, and not “magic ids”. |
| 105 | - Terminology does not conflict with ADR 0050 (instrument placement). |
| 106 | - The code model allows for further evolution: the emergence of new intents without disclosing internal panel ids. |
| 107 | - `editor_hud` is fixed as an invariant of the HUD layer inside `forward` and is not a custom intent in TOML. |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## Migration |
| 112 | |
| 113 | “replace” solution: |
| 114 | |
| 115 | - `[attention_zone_panels]` is deprecated and removed when `[attention_routing]` is implemented. |
| 116 | - Transition can support both, but in the v1 implementation it is preferable not to keep two parallel sources of truth. |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ## Open questions |
| 121 | |
| 122 | - Separate custom routing section in `%LocalAppData%\\CascadeIDE\\settings.toml`: is it needed in v1, or is bundle+repo enough? |