DEPRECATED: Bridge SDK (moved into Adom Bridge)

@@ -170,6 +170,33 @@ Status as of 2026-08-15: **KiCad 0.9.105 implements all eight plus `kicad_state`  --- +## ⭐ REQUIRED: the background/foreground RESPONSE contract - one shape, canonicalized (wiki #82, 2026-08-19)++John's ruling on foreground etiquette (a window opens in the BACKGROUND by default; a foreground move needs a stated human reason and a 3s ab caption first) shipped in kicad 0.9.131 and fusion 1.9.51-52 within a day of each other. The ARGS agreed - `foreground: true` + `foregroundReason` + the caption - and that part is settled. The RESPONSE markers diverged, so a runner had to special-case each bridge. Canonicalizing now, before Altium and the next bridge copy whichever one they happened to read first.++**The rule: what a caller has to branch on is a CONTRACT and gets a stable, non-underscore key. What a caller merely reads is a HINT and keeps the `_` prefix.** That is the whole basis of the choices below, and it is the thing to apply when a future field is added.++| Semantics | CANONICAL | Was |+|---|---|---|+| where the window went | **`windowEtiquette: "background" \| "foreground"`** | kicad `openedInBackground: true` |+| a bare `foreground:true` was refused | **`errorCode: "foreground_reason_required"`** | kicad `_foregroundRefused` |+| the quietness audit log | **`<prefix>_state.focusEvents[]`** | kicad `kicad_state.focusEvents` (already right) |+| guidance for the AI | `_hint` (unchanged) | both |++**`windowEtiquette` over `openedInBackground`, because a boolean cannot grow.** The states are already three, not two (background, reason-gated foreground, refused), and a bool forces every later state into a second flag that can contradict the first. An enum also reads correctly on verbs that are not "open" - a raise, a close, a dialog dismissal all have etiquette, and none of them "opened in background". fusion's shape was the more durable one.++**`errorCode` over `_foregroundRefused`, because a runner must be able to BRANCH.** fusion asked for this explicitly and is right: a `_`-prefixed marker is by convention advisory text for the AI, so keying control flow off it makes a doc string load-bearing. `foreground_reason_required` is the stable code; keep the `_hint` alongside it explaining what to pass.++**`focusEvents` is blessed as the canonical name** (kicad's, unchanged) on the `<prefix>_state` verb: an append-only log of every focus change your bridge caused or observed, with a timestamp and a cause. An auditable quietness log is a real assert; "nobody complained" is not. fusion is adding it.++### ⛔ Never size a suppression envelope off an ESTIMATE - re-arm per step++fusion's lesson, and it is the one most likely to bite the next bridge, so it is a rule and not a footnote. fusion's tour armed ONE background-suppression envelope sized from an estimate of how long the run would take. Real runs blew through it - cold boots, dialog stalls - the guard expired mid-run, and a window escaped to the foreground. That was the exact foreground leak John caught live.++An estimate cannot bound a step whose duration you do not control. **Re-arm the envelope per step or per operation**, so the guard's lifetime is always shorter than the thing it is guarding, and an overrun costs you a re-arm rather than a leak. This is the same reasoning as the measured-progress rule above: do not let a number you guessed become a thing the system depends on.++Both existing shapes may be emitted together during a migration window (`windowEtiquette` plus the old key) so a pinned runner does not break, but the OLD keys are deprecated on sight and should be dropped once your consumers are on the new one.+ ## The rest of the SDK library  The SDK is a **skill library**, not one file, so you load only the phase you are in:

@@ -170,6 +170,33 @@ Status as of 2026-08-15: **KiCad 0.9.105 implements all eight plus `kicad_state`  --- +## ⭐ REQUIRED: the background/foreground RESPONSE contract - one shape, canonicalized (wiki #82, 2026-08-19)++John's ruling on foreground etiquette (a window opens in the BACKGROUND by default; a foreground move needs a stated human reason and a 3s ab caption first) shipped in kicad 0.9.131 and fusion 1.9.51-52 within a day of each other. The ARGS agreed - `foreground: true` + `foregroundReason` + the caption - and that part is settled. The RESPONSE markers diverged, so a runner had to special-case each bridge. Canonicalizing now, before Altium and the next bridge copy whichever one they happened to read first.++**The rule: what a caller has to branch on is a CONTRACT and gets a stable, non-underscore key. What a caller merely reads is a HINT and keeps the `_` prefix.** That is the whole basis of the choices below, and it is the thing to apply when a future field is added.++| Semantics | CANONICAL | Was |+|---|---|---|+| where the window went | **`windowEtiquette: "background" \| "foreground"`** | kicad `openedInBackground: true` |+| a bare `foreground:true` was refused | **`errorCode: "foreground_reason_required"`** | kicad `_foregroundRefused` |+| the quietness audit log | **`<prefix>_state.focusEvents[]`** | kicad `kicad_state.focusEvents` (already right) |+| guidance for the AI | `_hint` (unchanged) | both |++**`windowEtiquette` over `openedInBackground`, because a boolean cannot grow.** The states are already three, not two (background, reason-gated foreground, refused), and a bool forces every later state into a second flag that can contradict the first. An enum also reads correctly on verbs that are not "open" - a raise, a close, a dialog dismissal all have etiquette, and none of them "opened in background". fusion's shape was the more durable one.++**`errorCode` over `_foregroundRefused`, because a runner must be able to BRANCH.** fusion asked for this explicitly and is right: a `_`-prefixed marker is by convention advisory text for the AI, so keying control flow off it makes a doc string load-bearing. `foreground_reason_required` is the stable code; keep the `_hint` alongside it explaining what to pass.++**`focusEvents` is blessed as the canonical name** (kicad's, unchanged) on the `<prefix>_state` verb: an append-only log of every focus change your bridge caused or observed, with a timestamp and a cause. An auditable quietness log is a real assert; "nobody complained" is not. fusion is adding it.++### ⛔ Never size a suppression envelope off an ESTIMATE - re-arm per step++fusion's lesson, and it is the one most likely to bite the next bridge, so it is a rule and not a footnote. fusion's tour armed ONE background-suppression envelope sized from an estimate of how long the run would take. Real runs blew through it - cold boots, dialog stalls - the guard expired mid-run, and a window escaped to the foreground. That was the exact foreground leak John caught live.++An estimate cannot bound a step whose duration you do not control. **Re-arm the envelope per step or per operation**, so the guard's lifetime is always shorter than the thing it is guarding, and an overrun costs you a re-arm rather than a leak. This is the same reasoning as the measured-progress rule above: do not let a number you guessed become a thing the system depends on.++Both existing shapes may be emitted together during a migration window (`windowEtiquette` plus the old key) so a pinned runner does not break, but the OLD keys are deprecated on sight and should be dropped once your consumers are on the new one.+ ## The rest of the SDK library  The SDK is a **skill library**, not one file, so you load only the phase you are in:

@@ -170,6 +170,33 @@ Status as of 2026-08-15: **KiCad 0.9.105 implements all eight plus `kicad_state`  --- +## ⭐ REQUIRED: the background/foreground RESPONSE contract - one shape, canonicalized (wiki #82, 2026-08-19)++John's ruling on foreground etiquette (a window opens in the BACKGROUND by default; a foreground move needs a stated human reason and a 3s ab caption first) shipped in kicad 0.9.131 and fusion 1.9.51-52 within a day of each other. The ARGS agreed - `foreground: true` + `foregroundReason` + the caption - and that part is settled. The RESPONSE markers diverged, so a runner had to special-case each bridge. Canonicalizing now, before Altium and the next bridge copy whichever one they happened to read first.++**The rule: what a caller has to branch on is a CONTRACT and gets a stable, non-underscore key. What a caller merely reads is a HINT and keeps the `_` prefix.** That is the whole basis of the choices below, and it is the thing to apply when a future field is added.++| Semantics | CANONICAL | Was |+|---|---|---|+| where the window went | **`windowEtiquette: "background" \| "foreground"`** | kicad `openedInBackground: true` |+| a bare `foreground:true` was refused | **`errorCode: "foreground_reason_required"`** | kicad `_foregroundRefused` |+| the quietness audit log | **`<prefix>_state.focusEvents[]`** | kicad `kicad_state.focusEvents` (already right) |+| guidance for the AI | `_hint` (unchanged) | both |++**`windowEtiquette` over `openedInBackground`, because a boolean cannot grow.** The states are already three, not two (background, reason-gated foreground, refused), and a bool forces every later state into a second flag that can contradict the first. An enum also reads correctly on verbs that are not "open" - a raise, a close, a dialog dismissal all have etiquette, and none of them "opened in background". fusion's shape was the more durable one.++**`errorCode` over `_foregroundRefused`, because a runner must be able to BRANCH.** fusion asked for this explicitly and is right: a `_`-prefixed marker is by convention advisory text for the AI, so keying control flow off it makes a doc string load-bearing. `foreground_reason_required` is the stable code; keep the `_hint` alongside it explaining what to pass.++**`focusEvents` is blessed as the canonical name** (kicad's, unchanged) on the `<prefix>_state` verb: an append-only log of every focus change your bridge caused or observed, with a timestamp and a cause. An auditable quietness log is a real assert; "nobody complained" is not. fusion is adding it.++### ⛔ Never size a suppression envelope off an ESTIMATE - re-arm per step++fusion's lesson, and it is the one most likely to bite the next bridge, so it is a rule and not a footnote. fusion's tour armed ONE background-suppression envelope sized from an estimate of how long the run would take. Real runs blew through it - cold boots, dialog stalls - the guard expired mid-run, and a window escaped to the foreground. That was the exact foreground leak John caught live.++An estimate cannot bound a step whose duration you do not control. **Re-arm the envelope per step or per operation**, so the guard's lifetime is always shorter than the thing it is guarding, and an overrun costs you a re-arm rather than a leak. This is the same reasoning as the measured-progress rule above: do not let a number you guessed become a thing the system depends on.++Both existing shapes may be emitted together during a migration window (`windowEtiquette` plus the old key) so a pinned runner does not break, but the OLD keys are deprecated on sight and should be dropped once your consumers are on the new one.+ ## The rest of the SDK library  The SDK is a **skill library**, not one file, so you load only the phase you are in: