gentle-shell-bridge 0.3.1 → 0.3.2

package/README.md

@@ -1,746 +1,115 @@
 # gentle-shell-bridge
 
-A shared, plugin-facing bridge between Pi plugins and gentle-shell's `/gentle:customize`
-menu. A plugin publishes a *row provider*; the bridge owns the single interception layer
-and fans out to every provider, so N plugins × M gentle-shell surfaces becomes N providers
-and one interception. Plugins stop wrapping `ctx.ui` themselves, and stop colliding with
-each other when more than one wants to add a settings row.
+One interception layer between gentle-shell and the plugins that want a line in its menus, a card
+in its rail, or a frame in the transcript.
 
-**Status: released as `0.3.0`.** The package exists and runs. It is a manifest-backed Pi
-package (`pi.extensions` → `./src/extension.ts`) loaded from TypeScript sources through
-jiti, so there is no build step and no `dist/`; it registers a `bridge-status` command and
-carries a `node --test` suite of 673 tests, 26 of them end-to-end through the public API and
-the real extension entry, a matrix driving the worked example through the real wiring (its design,
-the restored `plain` card style, the rail and its sections), and 22 pinning the publication
-announcement in both load orders. The capture
-technique was proven in the real TUI by a 76-line
-throwaway extension (`loon-customize-probe.ts`); the capture backend implements it, while
-the hook backend is implemented but **unverified** — no host has been observed emitting the
-registry it looks for. The sidebar surface is proven against a fake rail, not in a live TUI:
-what is not proven is listed under **Limits**.
+## What It Does
 
-- [PRD.md](PRD.md) — problem, users, requirements, success criteria
-- [docs/architecture.md](docs/architecture.md) — how the host menu is reached, with source citations
-- [docs/contract.md](docs/contract.md) — `registerRows`, provider and row shapes, diagnostics
-- [docs/state.md](docs/state.md) — ADR: stateless composition plus optional per-plugin store
+gentle-shell builds its `/gentle:customize` menu, its sidebar, and its card frames inside closures
+that no plugin can reach. A plugin that wants a settings row therefore has to wrap the host, patch
+it, and hopefully survive the next release. Two plugins doing that do not compose: the inner
+wrapper wins the capture, the outer one gets nothing, and the menu silently loses a plugin's rows.
 
-## Worked consumer
+This package owns that interception exactly once. A plugin registers what it contributes — settings
+rows, a sidebar section, a card style, a transcript transform, a card design for one tool, a keymap
+action, palette items — and the bridge turns those registrations into what the host draws. The
+plugin keeps its own state; the bridge keeps the only wrapper.
 
-[`examples/bash-card.ts`](examples/bash-card.ts) is a standalone Pi extension that demonstrates
-every surface this feature exists for: a **tool design** through `registerToolDesign`, a **card
-style** through `registerCardStyle`, a **`BASH CARD` sidebar section** through `registerSection`,
-and a **demo category** through `registerRows`. The section is toggled from **`Sections`** in
-`/gentle:customize` with no setting, row or store written by the plugin; the design and the style
-add their own values to the `Cards` page.
+What changes for a user: every installed plugin's settings appear in the one menu they already
+open, and a plugin whose surface cannot be reached says why in `/bridge-status` instead of
+disappearing.
 
-The design is the one the user asked for. gentle-shell draws a minimal bash card with just a `$`
-mark; the design heads that same card with the word `bash`, and nothing else:
+## Quick Start
 
-```
-before   ▎ $ npm test (timeout 30s)          ctrl+o to expand
-after    ▎ bash npm test (timeout 30s)       ctrl+o to expand
-```
-
-The card is still the host's card. A design receives the lines the HOST's own renderer produced and
-returns the lines to draw, so whatever `Card style` is selected survives by construction: with
-`neon` the card stays neon, with `float` it stays float. The example changes exactly two things on
-the heading row — the mark, and the fill it gives back so the row keeps the host's width — and every
-other byte of every other row (ANSI, padding, hint, rails, body) comes back identical:
-`test/example-bash-identity.test.ts`, `test/example-neon-transform.test.ts` and
-`test/example-bash-matrix.test.ts` assert that byte for byte.
-
-### The whole matrix: every card style × every card content (S11)
-
-The user's requirement, verbatim:
-
-> tambien las tools redisenada (en este caso tool bash) personalizadas deberia ser compatibles con
-> card style float/neon (o agregados) y card content default/minimal
-
-`test/example-bash-matrix.test.ts` drives the registered design through the real bus over every cell,
-and every fixture it uses was produced by running the installed host's and pi's own code — the
-derivation, file and line per fixture, is the comment block in `test/fake-transcript.ts`:
-
-| card style | card content | the heading row the host draws | the design's row | reachable? |
-| ---------- | ------------ | ------------------------------ | ---------------- | ---------- |
-| `float` | `minimal` | ` ▎ $ npm test (timeout 30s) …… ctrl+o to expand   ` | ` ▎ bash npm test (timeout 30s) …… ctrl+o to expand   ` | yes — `extensions/quiet-tools.ts:910-914` |
-| `neon` | `minimal` | `╭─ $ npm test (timeout 30s) ────── ctrl+o to expand ╮` | `╭─ bash npm test (timeout 30s) ────── ctrl+o to expand ╮` | yes — same renderer, `lib/shell-card.ts:105-108` |
-| `float` | `default` | ` $ npm test (timeout 30s)` inside pi's `Box` | ` bash npm test (timeout 30s)` | yes — pi's native renderer (`core/tools/renderers/bash.js`) |
-| `neon` | `default` | identical to the cell above | identical | yes, and the same rows: nothing on pi's path reads `cardStyle()` |
-| ADDED (`registerCardStyle`) | `minimal` | the float rows, repainted by `src/card-style-transform.ts` | the design's word survives the repaint | yes |
-| ADDED (`registerCardStyle`) | `default` | pi's native rows | unchanged | **no** — the repaint's grammar is float's ` ▎ ` (`src/card-style-transform.ts:189-196`), so a registered style cannot reach pi's native card |
-
-How the design finds the heading, without parsing frame chrome it does not own:
-
-1. the heading is the component's first row that carries a letter, a digit or the mark;
-2. the mark must be the row's first non-decoration character, followed by a space — `PATH=$HOME` and
-   `$(date)` are never prompts;
-3. no blank row may precede it: pi's native RESULT component opens with a `Spacer` row, and that one
-   row is what tells a native result from a native call;
-4. the row may not begin with the outline frame's side or closing rule (`│`, `╰`): a heading is on
-   the card's top, so a `$` on an outline body row is output;
-5. the word's three extra columns come out of the row's widest padding/rule fill, so the row keeps
-   the host's width exactly; when no run is wide enough — a command the host already collapsed to
-   fill the row — the three columns come out of that HOST-MADE ABBREVIATION instead: only text the
-   host already shortened loses three more columns, at a grapheme boundary, keeping the `…`. A
-   command the host shows in full is never shortened, because a design must not hide what a command
-   does; that row is left as the host drew it and reported;
-6. the design acts on the CALL only, because the bridge tells it which half of the card it is drawing
-   (`ctx.part`). In the `float` cell the call and the result are separate components drawn with the
-   same chrome, so a RESULT whose first body row begins with `$ ` (a command echoing a prompt) sits
-   exactly where a heading sits — with `part` it is returned byte-identical, and the other two cells
-   exclude it independently (blank row / `│` side).
-
-**Limits, stated rather than hidden.** (a) A command containing a wider run of spaces than the
-frame's own fill would have those spaces shortened instead of the fill. (b) The heading must be in
-the first row of content: a host that puts a second row of chrome above its heading would be
-reported as unrecognised, not guessed at. (c) The abbreviation has to be able to pay exactly three
-columns in whole graphemes: a clipped run of two-column glyphs with no one-column glyph at its end
-is refused rather than widened or cut in half. And the rule that matters most: **an unabbreviated
-command with no fill is left as `$` and reported**, never shortened.
-
-**A frame the design cannot prove** comes back byte-identical and is reported once: the `CARD BASH`
-section carries an `unrecognised  <reason>` row (`none` until it happens) and the same reason is
-delivered once through `ctx.ui.notify`. That is the honest answer the earlier iterations were missing
-— a design that recognises nothing now says so instead of looking installed.
-
-The design is registered for the tool name `bash`, and the `Cards` line it produces appears with no
-extra wiring and is named after the `Cards` category, like `Card style` and `Card content`:
-`Card bash  ○ native  ○ bash heading`. The first value is the bridge's own `native` — the host's card,
-the default — so installing the file changes no rendering until the user picks the design. Choosing it repaints the bash cards already on screen, not only the next one, because the
-bridge reads the live selection on every render pass. A `read` card is never touched: designs are
-declared per tool name, and the bus has no bash-specific branch.
-
-The **`CARD BASH`** section is the second surface: the host draws the card and owns the collapse
-control, and the card's right-aligned `meta` is the live selection for `bash` — the surface that
-survives a collapse, and the only place the section shows it, so the value is never printed twice.
-The body reports whether this load's design reached the bridge (`resolver  registered` /
-`resolver  absent`), whether the restored `plain` style did (`card style  registered` /
-`absent`), and whether the design could recognise the frames it was handed
-(`unrecognised  none`, or the reason). It needs no
-extra wiring either: registering the section is what adds its `Sections` toggle; the section's row
-reads `card bash`, and the plugin's INTEGRATIONS line reads `Card bash`.
-
-### A card style of the example's own: `plain`
-
-The fourth surface is the bridge's oldest one, restored with the SAME id (`bash-card.plain`), label
-and literal preview it had before the design rewrite: `registerCardStyle` adds `plain` to the
-`Card style` line, so it reads `○ neon ○ float ○ plain`. Selecting it repaints every TOOL card the
-host drew with one gutter character per row, the heading as plain text and no box; selecting `neon`
-or `float` hands the host its own bytes back, because pressing a host value clears the bridge's
-selection to `native`.
-
-The style is chrome only — it never parses a card. The bridge measures the host's card, extracts the
-heading and the hint and hands them over. That is also why the two surfaces COMPOSE rather than
-compete: the design runs first, on the host's rows, and the style repaints those rows after. With
-`bash heading` selected the `plain` card still heads with the word `bash`:
-
-```text
-before   ▎ $ npm test (timeout 30s)          ctrl+o to expand
-         ▎
-         ▎ PASS 42 tests
-         ▎
-
-plain    ▌ bash npm test (timeout 30s)       ctrl+o to expand
-         ▌ PASS 42 tests
-         ▌
-```
-
-`test/example-plain-style.test.ts` drives the whole matrix through the real wiring — the bridge's
-own card-style transform, its rail wiring, the host's menu rows, the example's registration and the
-host's own `Card style` values — and pins the cells that are NOT reachable instead of pretending
-they are. In particular, card content `default` is pi's native card, not a float frame: neither a
-host style nor a registered one can reach it, and the test asserts that pass-through by array
-identity and in `/bridge-status`. The same file covers the rail (host sections such as `STATS`, the
-bridge's own sections and a section added by another plugin, collapsed and expanded), and that
-switching back to `neon`/`float` restores the host's exact bytes on every surface.
-
-### A category, a toggle and a button of the example's own
-
-The example also proves the third surface: through the bridge's public `registerRows`, ONE provider
-(stable id `bash-card.demo`, replaced in place on `/reload`) adds a **new category** that no host
-code had to know about — `Card bash` — holding exactly two rows as the user reads them:
-
-```text
-Card bash
-  Demo toggle          ● on   ○ off      ← two consecutive rows sharing one choice.setting
-  Demo button                             ← a plain action row, no choice
-```
-
-The toggle and the button are deliberately trivial, and their effect is visible without opening a
-file: the example's own store (plugin id `bash-card`, not the bridge's selection file) holds
-`demoToggle` (default `off`) and `demoPresses` (default `0`), and the `CARD BASH` section reads both
-live:
-
-```text
-demo toggle   on
-demo presses        3
-```
-
-`demo toggle` is an inert row. `demo presses` is a CLICKABLE action row, drawn the way the host draws
-its own: the label on the left and the count right-aligned. Clicking it increments the counter once,
-and hovering it paints it with the host's own hover role, exactly as `INTEGRATIONS` and `CHANGES` do —
-the worked example is how you check that the bridge's hover works in your terminal. Choosing `on`
-persists the toggle; Enter on `Demo button` in the demo category increments the same counter. Each
-demo row carries a
-short literal preview. A bridge old enough not to publish `registerRows` degrades without throwing:
-no demo category, while the design and the section keep working.
+Add the published package next to gentle-shell and restart Pi:
 
-Copy the file into `~/.pi/agent/extensions/` and `/reload` to load it; the `bash` line defaults to
-the host's own card, while the section is visible immediately (`defaultVisible: true`). It does not
-import the package and does not know where it is installed: the example and the bridge meet on
-`globalThis` behind one symbol (see **Reaching the bridge without importing it**). Global extensions
-load before configured packages, so the example does not assume the bridge got there first: it tries
-the symbol in its own `session_start` handler **and** listens for the bridge's
-`gentle-shell-bridge:ready` announcement, whichever comes first registering the same surfaces
-(registration replaces by stable id, so the second one adds nothing). When neither has happened yet,
-the notice says which state the load is in — waiting for an announcement on a Pi with an event bus,
-or nothing to wait for on one without — instead of claiming the bridge is not installed.
-
-A bridge that publishes something else — another major version, a partial object, another library's
-payload at the symbol — is treated as absent, never as an error: the example never calls an object it
-cannot trust, registers nothing, and says so once through `ctx.ui.notify`. An object published before
-`registerToolDesign` existed keeps the section and says `resolver  absent`; one published before
-`registerCardStyle` says `card style  absent`: the members are optional, and a surface the bridge
-never promised is never warned about. The bridge reports the version skew
-once per process.
-
-## Install
-
-The package is `0.3.0`. Load it from source as a Pi extension package alongside gentle-shell
-and Pi discovers `src/extension.ts` through the `pi` manifest. The shipped files are the
-TypeScript sources: Pi loads them through jiti, so there is no build step and no `dist/` to
-publish.
-
-For a plugin that imports the API, `exports` maps the package root to `src/index.ts`:
-
-```ts
-import {
-  BRIDGE_READY_EVENT,
-  bridgeApi,
-  createStore,
-  isBridgeApi,
-  onBridgeApi,
-  registerCardStyle,
-  registerRows,
-  registerSection,
-  registerTransform,
-  STORE_SCHEMA_VERSION,
-  VERSION,
-} from "gentle-shell-bridge";
+```bash
+pi install npm:gentle-shell-bridge
 ```
 
-Importing is optional: a plugin can reach the bridge through the runtime handshake below without
-resolving the package at all.
-
-`engines.node` is `>=22.18.0` because the test suite runs `.ts` files directly through
-Node's native type stripping, with no transpile step.
-
-## Quick start: a sidebar section
-
-The two quick starts below show the call itself. Make it from your extension's `session_start`
-handler — or, if your plugin may load before this package, through `onBridgeApi(handler, pi.events)`,
-which answers in both orders.
-
-The second surface needs no `Sections` row, no setting name and no store of its own — one call
-adds the card to the sidebar and its show/hide toggle to `/gentle:customize` → `Sections`.
-
-```ts
-import { registerSection } from "gentle-shell-bridge";
-
-const dispose = registerSection({
-  id: "loon.music",             // unique and stable: ordering, replacement, the toggle; internal
-  title: "MUSIC",               // card heading, framed by the host like AGENTS / STATS
-  rowLabel: "music",            // optional: the text the Sections row reads (derived from title)
-  meta: () => "1 playing",      // optional right-aligned count; read per frame, so it is live
-  lines: () => [                // per frame, live
-    "track  Blue in Green",     // a plain string is drawn byte for byte, exactly as before
-    {                           // a structured row is drawn like a native one
-      glyph: "▸",
-      label: "album",
-      meta: "Kind of Blue",
-      tone: "muted",
-      onClick: () => play(),    // only a row with onClick is clickable
-    },
-  ],
-  defaultVisible: true,
-  order: 10,                    // optional; unordered sections follow, in registration order
-});
-
-// dispose() removes the card and its toggle; other sections are untouched.
-```
-
-The card behaves like a host card. The HEADER is the host's own header — `▾ MUSIC`, the right-aligned
-`meta`, the hover accent — and clicking it folds the section (a folded body is not built at all, and
-the fold is remembered in the bridge's own store). A row with `onClick` is clickable and highlights
-under the pointer; a row without it is inert and never highlights. `meta` is read at render time and
-folded into the rail's digest, so a value that changes is repainted with no re-registration.
-
-The `tone` of a structured row names one of the host's own roles — `text`, `muted`, `dim`, `accent`,
-`success`, `error`, `warning` — never a colour, and anything else is rejected and reported.
-
-Where the header and rows are DRAWN is reported, not assumed: the host's own
-`renderPanelHeader`/`renderPanelRow` live in a module this package cannot import, so the bridge looks
-for them on every object it is handed, uses them when it finds them, and otherwise draws with a
-byte-identical port. `/bridge-status` says which it used and what remains unreachable
-(`section frame: host` or `section frame: fallback` plus a `section frame gap` line).
-
-The row is a **label**, never the id and never a prefix. The host's own `Sections` rows read
-`changes`, `stats`, `usageCost`; a plugin's section reads the same way:
-
-```text
-stats             ● shown  ○ hidden     ← the host's own row
-music             ● shown  ○ hidden     ← this plugin's section
-```
-
-`id` stays internal: it is the replacement, disposer and stored-visibility key, and it never
-appears in a row. With no `rowLabel`, the bridge derives one from `title` — lowercase words joined
-by spaces, dots and punctuation dropped, at most three words (`"CARD BASH"` → `"card bash"`,
-`"MUSIC PLAYER NOW PLAYING"` → `"music player now"`). Two sections whose labels would read the same
-are told apart deterministically (`music`, `music 2`, …) and `/bridge-status` says which one moved;
-the raw id is never the suffix. An explicit `rowLabel` obeys the same row-name shape described under
-"Row names" below — a name that breaks it is rejected and reported, never rewritten.
-
-What the bridge does with those fields, and what it will not do: the card is drawn by the
-host's own frame code, a plain string row is clipped to the rail width, and the body is capped at 8
-rows (with a `… +N more` marker). A row is measured the way the host measures it — `visibleWidth`:
-SGR ignored, a TAB is three columns, and a grapheme cluster is charged as a whole, so an emoji is two
-columns and a CJK glyph two. A contributed row is never wider than the width the host handed the
-part, padding included, so it cannot make the host drop the rail; `/bridge-status` reports that
-width and the widest row the bridge produced. A hidden section is not built at
-all (its `lines()`/`meta()` are not called), nor is a collapsed one, and a throwing section loses
-only its own body and is reported by `/bridge-status`.
-Sections always render **after** the native cards — interleaving is impossible because the
-host builds its status sections in a closure. Visibility and the fold live in
-`~/.pi/gentle-ai/gentle-shell-bridge/bridge-sections.json` as
-`{ "schemaVersion": 1, "values": { "sections": { "loon.music": true }, "collapsed": { "loon.music": true } } }`,
-deliberately not in the host's strictly validated `visual-customization.json`.
-
-## Quick start: a card style
-
-A plugin can add a third card style to gentle-shell's cards, on the host's own `Card style` line,
-without touching the host. The bridge owns detection; the style owns drawing. A style is one global
-choice, so it paints every card surface the host frames — the **conversation** and the fullscreen
-**rail** (host sections like `CHANGES` and contributed sections alike) — and `native` restores the
-host's own frames on both. The rail is covered by the same `transformCardLines` the conversation
-uses, so a plugin registers nothing extra for it.
-
-```ts
-import { registerCardStyle } from "gentle-shell-bridge";
-
-const dispose: () => void = registerCardStyle({
-  id: "loon.cute",  // unique; the stored value and the replacement key — internal, never a row
-  label: "cute",    // the line's value: Card style  ○ neon ● float ○ cute
-  rowLabel: "cute", // optional: what this style's row reads (derived from label when absent)
-  frame: {
-    top: (ctx) => `╭─ ${ctx.title ?? ""} ${"─".repeat(Math.max(0, ctx.width - 6))}╮`,
-    line: (ctx) => `│ ${ctx.text.padEnd(Math.max(0, ctx.width - 4))} │`,
-    bottom: (ctx) => `╰${"─".repeat(Math.max(0, ctx.width - 2))}╯`,
-  },
-  preview: () => ({ title: "Cute", sample: "╭─ read ─╮ │ config.ts │ ╰────────╯" }),
-});
-
-// The user picks `cute` on the host's own Card style line; pressing neon/float returns to the
-// host's rendering. dispose() removes the value and the chrome.
-```
-
-Rules the row cannot break: `id` and `label` are unique among the line's values (the host's
-`neon`/`float` and the bridge's `native` are taken), the visible text is a label (`label` on the
-line, `rowLabel` — or `label` made readable — for the row), the id never appears in a row, and the
-style only ever receives text and a width — it parses nothing. Full contract: [docs/contract.md](docs/contract.md) §12.
-
-## Quick start: a tool design
-
-A design decides how ONE tool's card is drawn, composed with the host's own card. You register it for
-a tool NAME; the bridge owns Pi's single `registerToolRenderer` resolver and hands your `apply` the
-rows the host itself drew:
-
-```ts
-import { registerToolDesign } from "gentle-shell-bridge";
-
-const dispose: () => void = registerToolDesign({
-  tool: "bash",                 // a tool name, present or future: no bash-specific branch anywhere
-  id: "loon.bash-heading",      // unique per tool; the stored value and the replacement key
-  label: "bash heading",        // the value on the Cards line: Card bash  ○ native  ○ bash heading
-  name: "Loon kit",             // optional: this plugin's INTEGRATIONS row
-  preview: () => ({ title: "Cards · bash heading", sample: "╭─ bash npm test ─╮" }),
-  apply(lines, ctx) {           // the HOST's rows in, the rows to draw out
-    // ctx is { width, tool, theme, part }; lines already carry the host's frame, ANSI and padding.
-    // `part` is "call" or "result", so a heading is only looked for on the call.
-    // Change only the mark the design is for, and keep every other row byte-identical:
-    if (ctx.part === "result") return [...lines];
-    return lines.map((line) => rewriteTheMarkOnly(line));
-  },
-});
-
-// The user picks `bash heading` on its Cards line; `native` (the host's own card) stays the default,
-// and the choice repaints cards already drawn. dispose() removes the value.
-```
-
-What the bridge guarantees:
-
-- **the frame is the host's**, so the card style is preserved by construction — `neon` stays neon,
-  `float` stays float, and every byte you do not change is returned as drawn;
-- the design's `Cards` line appears with no extra wiring, one line per tool, named `Card <tool>`
-  (`Card bash`, `Card lsp navigation`, `Card mem save` — `Card` plus at most two tool words, the
-  TAIL kept when a long name has to be clamped), whose values are `native` (the host's card, the
-  default) and every design registered for that tool;
-- the selection is persisted per tool in the bridge's own store, and changing it repaints the cards
-  already on screen, not only the next one;
-- a design declared for a tool with no card yet applies as soon as Pi builds one, because Pi resolves
-  renderers when the card is constructed;
-- a design that throws loses only its own card, and the host's rows are drawn instead.
-
-Full contract: [docs/contract.md](docs/contract.md) §14.
-
-## Quick start: a transcript transform
-
-A tool renderer resolves once, when a row is built. A transform runs on every frame the conversation
-component renders, which is the only way a rendering choice can reach rows that were already drawn.
-
-```ts
-// The context a transform receives: the host's width, and the optional telemetry channel.
-interface TransformContext {
-  width: number;
-  // Optional because an older published bridge has none: gate with typeof ctx.report === "function".
-  report?(counts: {
-    candidates: number;   // rows examined as a possible card head
-    recognised: number;   // candidates the grammar accepted
-    rewritten: number;    // cards actually rewritten this frame
-    shapes?: Record<string, number>;  // which shape matched, by name
-  }): void;
-}
-
-declare const registerTransform: (transform: {
-  id: string;
-  order?: number;
-  transform(lines: readonly string[], ctx: TransformContext): readonly string[];
-}) => () => void;
-
-const dispose = registerTransform({
-  id: "loon.gutter",   // unique: the ordering/replacement key and the /bridge-status name
-  order: 10,           // optional: ordered transforms run first, ascending
-  transform: (lines, ctx) => {
-    const kept = lines.map((line) => line.slice(0, ctx.width));
-    // Counts only — never a line of the conversation. This is what tells "the grammar matched
-    // nothing" apart from "the wrapper never ran" when a setting seems to do nothing.
-    ctx.report?.({ candidates: lines.length, recognised: kept.length, rewritten: lines.length });
-    return kept;
-  },
-});
-
-// The user sees the new rendering on the NEXT FRAME, for every row — including cards drawn before
-// the choice was made. dispose() removes this transform; other plugins' transforms keep running.
-```
-
-The pipeline is what the bridge's existing conversation wrapper runs after the card-style repaint:
-`lines` is the previous transform's output, and the first transform sees the card-style repaint of
-the host's own rows. What the bridge guarantees, and what the contract is:
-
-- what a transform returns is **clipped to `ctx.width`** (the width the host rendered at), so a
-transform can never make the frame wider than the terminal. The measure is the host's (`TAB` three
-columns, a grapheme cluster as a unit, an OSC-8 hyperlink contributes its text and not its URL), and
-a row that already fits is returned **byte-identical** — a transform that did not change a row cannot
-make the bridge cut it. A row that must be cut is cut between clusters, with an open hyperlink closed
-and an active SGR reset, so nothing leaks into the rows after it;
-- a transform that **throws**, or returns anything that is not an array of strings, loses only its
-own contribution for that frame; the lines in force are kept and the remaining transforms still run;
-- a transform that returns its input **unchanged** is recorded as `skipped` and the frame keeps its
-identity — with no transform registered, the wrapper returns the host's own array instance.
-
-`/bridge-status` lists the pipeline in order with the last frame's outcome per transform, then the
-counts that same frame recorded — lines received, and what the transform reported:
-
-```text
-transforms: 1 registered
-  - loon.bash-cards (order 10): applied, 13 lines, 4 candidates, 1 recognised, 1 rewritten, shapes: float 1
-```
-
-Those counts are the instrument, not decoration: `skipped` with `0 candidates` means the grammar
-found nothing card-shaped, candidates with `0 recognised` means it found the shape and rejected it,
-and recognised with `0 rewritten` means a setting decided the output. A shape name is the transform's
-own word for a frame it knows — a plugin that reads `float` and `neon` reports those names — so the
-report names which grammar matched. They are counts only — no line
-of the conversation is stored or displayed, a shape name must be a short lowercase name (anything
-else is dropped, never rewritten), and reporting cannot throw into the frame. Full contract:
-[docs/contract.md](docs/contract.md) §13.
-
-A tool design reports its own block, because "the design is selected but the card did not change" has
-exactly two useful answers: which design resolves now, and whether the one resolver has mounted a
-card at all.
-
-```text
-tool designs: 1 tools with designs
-  - bash: bash-card.bash-heading, wrapper mounted on 2 cards
-      bash-card.bash-heading "bash heading" — heads the card with bash instead of the host's $ mark
-tool design resolver: registered (1 registered)
-```
-
-## Reaching the bridge without importing it
-
-A plugin and the bridge are two independent projects, so a path to one checkout is not a contract.
-They meet on `globalThis`, behind one stable symbol:
-
-- `Symbol.for("gentle-shell-bridge/api/v1")` holds
-  `{ schema: "gentle-shell-bridge/api", version: 1, VERSION, registerRows, registerSection, registerCardStyle, registerTransform, registerToolDesign, requestRepaint, createStore }`.
-  It is frozen, first-wins (a valid object already there is kept, not replaced) and never reset.
-
-**Register at `session_start` if the package loaded first, otherwise when it announces itself.**
-The symbol is the authority; the announcement is the timing. Pi does not guarantee that this
-package loaded before your plugin: global extensions (`~/.pi/agent/extensions`) load, and receive
-`session_start`, before a configured package's module publishes — observed in a real TUI, where the
-worked example said "no compatible bridge" while a bridge was about to appear. So a plugin loaded
-early listens for one event:
-
-```ts
-pi.events?.on("gentle-shell-bridge:ready", ({ schema, version, VERSION }) => {
-  // the object is published now: read the symbol again and register
-});
-```
-
-The bridge emits it **once per process**, after a successful publish, and never when the slot holds
-an incompatible payload. It carries identity only — `{ schema, version, VERSION }` — because it is a
-notification, not a registry: the listener reads the symbol and applies the same gate. A Pi without
-`pi.events` emits nothing, and the symbol still works for anyone who reads it.
-
-Inline the gate (the example does), or import the package and let `onBridgeApi` handle both forms —
-handler called immediately when the object is already there, subscribed when it is not, detached
-after one delivery:
-
-```ts
-const KEY = Symbol.for("gentle-shell-bridge/api/v1");
-const isApi = (v: any) => typeof v === "object" && v !== null && v.schema === "gentle-shell-bridge/api" &&
-  v.version === 1 && typeof v.registerRows === "function" &&
-  typeof v.registerSection === "function" && typeof v.createStore === "function";
-
-const register = (): boolean => {
-  const api = (globalThis as any)[KEY];
-  if (!isApi(api)) return false;
-  api.registerSection({ id: "loon.music", title: "MUSIC", lines: () => ["…"] });
-  return true;
-};
-
-if (!register()) pi.events?.on("gentle-shell-bridge:ready", register);
-
-pi.on("session_start", (_event, ctx) => {
-  if (!register()) {
-    ctx.ui?.notify("my-plugin: waiting for gentle-shell-bridge to announce itself", "warning");
-  }
-});
-```
-
-A plugin that imports the package gets both forms in one call — the handler runs immediately when
-the object is published and when the announcement arrives otherwise, and the subscription detaches
-itself after one delivery:
-
-```ts
-import { onBridgeApi } from "gentle-shell-bridge";
-
-const dispose = onBridgeApi((api) => {
-  api.registerRows({ id: "loon.banner-source", category: "Cards", rows: () => [] });
-}, pi.events); // works in both load orders; `bridgeApi()` alone does not wait
-```
-
-Rules worth knowing: an object that fails the gate (wrong schema, `version !== 1`, a missing member)
-is **absent**, never an error — `bridgeApi()` returns `undefined`, one warning is emitted per
-process, and the slot is left exactly as it was. A breaking change takes a new `v2` symbol key
-rather than mutating `v1`. An older bridge publishes nothing at this key, so a newer plugin sees
-"absent" instead of being deferred silently; that compatibility cliff is intentional. The full rule
-and complete snippets are in [docs/contract.md](docs/contract.md) §9, with the surfaces documented in
-§9 (rows, sections, store), §12 (card styles) and §13 (transcript transforms).
-
-## Quick start: rows
-
-```ts
-import { createStore, registerRows } from "gentle-shell-bridge";
-
-const store = createStore("loon"); // ~/.pi/gentle-ai/gentle-shell-bridge/loon.json
-const read = () => store.get("bannerSource", "activity");
-
-const toggle = (value: string) => ({
-  category: "Banner" as const,
-  label: () => "Loon banner source",
-  choice: { setting: "Loon banner source", value, current: () => read() === value },
-  action: () => store.set("bannerSource", value), // persist first; the menu re-renders
-});
-
-const dispose = registerRows({
-  id: "loon.banner-source",
-  category: "Banner",
-  rows: () => [toggle("activity"), toggle("output")], // consecutive, same setting → one line
-});
-
-// dispose() removes every row this provider contributed; other providers are untouched.
-```
-
-### Row names
-
-`choice.setting` (the line's name) and `label` (the row's text) are read by a human, so both obey one
-shape: **one to three plain words**, title case like the host's own `Card style` / `Card content`,
-and **none of** `→ ← ↑ ↓ : . | / \ [ ] ( ) { }`. No trailing qualifier — the category says where the
-row lives and the values say what the choices are:
-
-```text
-Bash design                     OK    a row name, in the host's own vocabulary
-Bash heading → Bash rendering   BAD   an arrow and a repeated qualifier: reads as a breadcrumb
-Bash heading: rendering         BAD   a colon
-Section: bash-card.status       BAD   a prefix plus a dotted internal id
-```
-
-The bridge enforces this rather than trusting authors, and it never rewrites a name it refused:
-
-- a provider row whose line name or label breaks the shape is dropped from the menu build, so it
-  reaches neither the host's rows nor the rows `/bridge-status` compares;
-- a section or a card style whose `rowLabel` breaks it is not registered at all;
-- the offending string and the rule it broke are recorded verbatim and listed by `/bridge-status`
-  under `row rejections`.
-
-## Supported row kinds
-
-Every field below is already understood by gentle-shell's own renderer; the bridge carries rows
-as authored, with one deliberate exception: it sets `choice.applyOnMove: false` on every row it
-contributes, so a toggle is navigated and confirmed with Enter instead of switching as the cursor
-passes over it (the host's own rows keep their own field, so `Card style · neon/float` still
-applies on ←/→). While a bridge row is focused, the host's footer reads exactly
-`←/→ choose · Enter apply` instead of `←/→ change`, and a move writes nothing: no store update, no
-persisted value, no repaint. Enter applies once.
+Pi reads the `pi` manifest and loads `src/extension.ts`. The shipped artifact is the TypeScript
+source — Pi loads it through jiti, so there is no build step and no `dist/`.
 
-| Kind | Shape | Renders as |
-| --- | --- | --- |
-| Toggle | two or more consecutive rows sharing `choice.setting` | one line `Name ● current ○ other`; ←/→ moves the `›` cursor and the footer reads `←/→ choose · Enter apply`, Enter applies (the bridge always sets `applyOnMove: false`) |
-| Action | a row without `choice` | one line; Enter/Space runs `action(inline)` |
-| Gated | `visible()` returns `false` | row hidden; a throw fails closed and hides it |
-| Preview | `preview()` returns `{ title, sample }` | read-only preview for the focused row |
-| Inline editor | `action` calling `inline.input()`, `inline.confirm()`, `inline.capture()` | field, confirmation or key capture drawn inside the card |
-| Hint | `keyhint` | per-row footer hint instead of the category default |
+Two surfaces need a host that reads them: **keymaps** and **command palette**. They land only in a
+gentle-shell that includes the consumer side; the bridge publishes the contributions either way, and
+`resolveKeymap` reports the missing host instead of failing.
 
-`label` may be a string or a function, and is evaluated when the menu is built, so it can
-read live state. Full details, conflict policy and failure isolation:
-[docs/contract.md](docs/contract.md).
+Working from a checkout instead? Point Pi's package list at the directory; nothing else changes.
 
-## Diagnostics
+## Core Workflow
 
-The bridge registers one command, `/bridge-status`. It reports the registered providers (id
-and category, in subscription order), the active backend (`hook` or `capture`), the last
-capture outcome with the injected row count, the last provider failures, store problems and
-duplicate `category` + `setting` pairs across providers, and any row name the shape rule rejected —
-the surface, the registration id, the offending string verbatim and the rule it broke, under
-`row rejections` — so a missing row is an answer, not a silent no-op. Duplicates are computed
-from the rows the last menu build actually received, so before any build the report says
-`duplicate settings: no build yet` instead of claiming there are none. Diagnostics never run a
-provider's `rows()`.
+A plugin reaches the bridge from its own `session_start`, through the published object or through
+the announcement event if the bridge loaded later. It then registers what it contributes and keeps
+the disposer, so a `/reload` replaces its registration instead of stacking a second one.
 
-The first answer is whether the required host package is there: `gentle-pi: present`, or
-`gentle-pi: missing — <reason>` followed by one `bridge: disabled` line, because this bridge needs
-`gentle-pi` (it feeds `/gentle:customize`) and arms nothing without it — no rows, sections, card
-styles, tool designs or wrappers, and no per-surface block claiming work it is not doing.
+A registration is evaluated when a menu is built, not when it is made, so rows always reflect live
+state. Anything a registration throws is isolated to that registration and reported: one broken
+plugin costs its own rows, never the menu.
 
-It also answers the sidebar question: a `sections` table (id, title, the `row` label the menu
-reads plus a collision note when two labels wanted the same text, persisted visibility — and
-`collapsed` while the card is folded — and where the position comes from), the most recent frame's
-`section failures` (phase `lines`, `meta` or `onClick`), and a `sidebar` line —
-`intercepted (rail wrapped)`, `intercepted (rail pending)`, `no-sidebar-state`, or
-`not armed` with the reason the wiring could not acquire a `tui`. Three more lines say how the card
-is drawn and how the pointer reaches it: `section frame: host` or `fallback` with what was looked
-for and whether a theme had arrived, `section interaction:` with the pointer path and the hover
-claim, and — in the fallback case — a `section frame gap:` line naming what cannot be reached. Those
-blocks appear only when they have something to say, so a row-only install keeps the historical
-output. Diagnostics never run a section's `lines()`/`meta()` either; the rail's digest does, during a
-frame. The hook backend is reported as
-`hook` only when this process pushed its fan-out provider into a host registry. Ids stay in this
-report on purpose: it is for the plugin author diagnosing a registration, not for the user picking
-a toggle.
+Every call, its arguments and its guarantees live in the contract, linked below. The two newest
+surfaces — a plugin's keymapped action, and its items in the command palette — are the ones worth
+reading first, because they are what a plugin could not do at all before.
 
-For card styles it reports the line mode (`extended` when the host's own line was found,
-`separate` when the fallback line was used), the registered styles in order, the live selection
-(including a disposed one, as `missing`), what the last frame did (`transformed N cards`,
-`pass-through (native | missing | no card)`, or `failed` with the style and message), the per-style
-failures, whether the conversation component was wrapped, and the reminder that a downstream
-post-processor can override the frame. Per surface it also says whether the style reached it and what
-its last frame did there (`card style surface rail: reached (rail wrapped), last frame transformed 3
-cards`, or `not reached (no-layout-root)`), and it reports the last repaint a bridge-owned write
-requested — `last repaint: rail for section "loon.music" → hidden (repainted)` — including the reason
-when no frame could be asked for. A visibility toggle and a card-style selection repaint
-synchronously, before the action returns; nothing polls.
+## Key Features You Should Know About
 
-For transcript transforms it reports the registered pipeline in order — `order 10` or `registration
-order` — and what the last frame did with each one: `applied`, `skipped`, `failed` with the message,
-or `not run` for a transform registered after that frame. The block appears only when a transform is
-registered, so a session that never used the pipeline keeps the historical report byte for byte.
+- **Settings rows** for the host's categories, or a page of your own: toggles, button rows, and the
+  host's own `●`/`○` marker, arrow handling and footer for a focused row — `←/→ choose · Enter apply`
+  — so a plugin never draws chrome of its own.
+- **Sidebar sections** that join the rail after the native cards, each contributing its own
+  visibility toggle automatically.
+- **Card styles** and **transcript transforms**: the bridge rewrites frames the host already drew,
+  so the rest of the visual system stays the host's.
+- **Card designs per tool name**, behind one `pi.registerToolRenderer` resolver for the whole
+  process, so two plugins cannot stack wrappers on the same tool.
+- **Keymaps.** A plugin's action appears on the host's Keymaps page, is reassigned there with the
+  native gestures, and takes part in the same reserved-key and duplicate-key checks. The plugin
+  binds the shortcut itself and asks the shell which key to bind, so the row and the binding cannot
+  disagree. Like every native keymap, a change applies after `/reload`.
+- **Command palette items**, into a section the host already has or one of the plugin's own.
+- **A namespaced store** for whatever a plugin wants to persist, with the bridge's own files kept
+  apart from the host's.
 
-The bridge also sets **one INTEGRATIONS row per plugin** in Pi's footer, through
-`ctx.ui.setStatus(key, text)`, and reports it as a per-plugin list: the name and whether it was
-`derived from package "@acme/loon-kit"` or an `explicit name`, the registrations `accepted` and
-`rejected`, and whether the row is set — or `no line set` with the reason. The header says when the
-host's `setStatus` is unavailable at all. The rules that line obeys:
+## Documentation
 
-- **The row text is opaque.** The host renders the whole string as one row, so everything the row
-  says is inside it: `Loon kit · ready`. Its `sanitizeStatus` strips ANSI and collapses whitespace,
-  so **ANSI is not available** to a plugin, and any glyph must be part of the text
-  (`🧠 gentle-pi · ready` is the host's own fixture).
-- **Colour belongs to the host.** Every entry is painted with one shared role; a plugin chooses a
-  glyph, never a colour.
-- **One plugin means one line.** Ten rows, three sections, a card style, a transform and a tool
-  design still paint one row; later changes repaint the same key in place, and `session_shutdown`
-  clears it with `undefined`.
-- **The name is derived, or given once.** The bridge resolves the module that registered to its
-  owning `package.json` and derives one to three plain words (`@acme/loon-kit` → `Loon kit`); any
-  registration may pass `name`, and the first usable declaration fixes it for the plugin.
-- **Identity is the plugin; the name is sticky.** A plugin is its owning package root (or the module
-  when no package owns it), resolved once and keyed from that identity — never from the display
-  name, so a rename repaints the same row and never adds one. A single copied file with no owning
-  package gets **no row** (fail closed, the reason is in `/bridge-status`) unless it passes that
-  `name`. The Pi installation is never a plugin identity: a module owned by the package that
-  provides `pi` fails closed the same way, so its shared extensions directory cannot add a
-  `Pi coding agent` row. A later registration that declares a different name never renames the
-  row — the first name stays and `/bridge-status` reports the conflict. A rejected name is never
-  shown.
-- **`ready` is derived, never promised.** One rejected registration — an invalid id, a row label that
-  broke the shape rule — makes the same key read `degraded`, and the report names the rejected
-  items.
+| Your task | Start here |
+| --- | --- |
+| Call any `register*` correctly, and know what each one guarantees | [docs/contract.md](docs/contract.md) |
+| Understand how the bridge reaches a sealed host, and why it is done this way | [docs/architecture.md](docs/architecture.md) |
+| Know what the bridge persists, and where | [docs/state.md](docs/state.md) |
+| See a real consumer, end to end | [examples/bash-card.ts](examples/bash-card.ts) |
+| Read the requirements and the reason each one exists | [PRD.md](PRD.md) |
 
 ## Limits
 
-- **A new category is a page, with one reserved name.** The host derives its pages from the rows
-  (`lib/visual-customize-view.ts:387`) once, in the view's constructor, while the capture backend
-  used to inject rows after the factory returned. The bridge now appends the providers' rows from
-  inside the host's own `map`, provisionally and only on an array proven to be the menu's rows, and
-  takes them back out if the late decision picks another array, the build is ambiguous, the factory
-  returns a promise or it throws; so a brand-new category appears as a page after the host's own.
-  `Keymaps` is reserved (its rows capture keys and claim a footer): a provider or a row naming it,
-  in any case or with surrounding spaces, is refused and reported. `Keymap`, `Key maps`, `Cards`,
-  `Profiles` and `Reset` are ordinary names.
-- **No upstream hook exists.** The bridge depends on gentle-shell internals; the day
-  gentle-shell changes its menu construction, the fix is in one place, but it is still a
-  fix against internals rather than a supported extension point.
-- **The capture backend patches `Array.prototype.map`** for the duration of one
-  synchronous factory call. It is restored in a `finally` block, it never survives the
-  call, and it is only installed inside the customize-menu path.
-- **The capture is heuristic.** It recognises the row array by shape; a menu that builds
-  its rows differently produces no capture. That case is reported by `/bridge-status` instead of
-  passing silently.
-- **Card styles are a repaint, not a host feature.** The bridge rewrites the `float` frames
-  gentle-shell already drew, so it depends on that grammar, and a downstream post-processor that
-  re-frames the conversation and strips box chrome can override the result — the bridge
-  says so in `/bridge-status` instead of pretending otherwise. Detection is proven against a fake
-  conversation built from real `shell-card.ts` output, never in a running TUI, and a card with a
-  blank body row is detected as ending at that row.
-- **A transform is a per-frame pass, not a host feature either.** It runs inside the wrapper the
-  bridge already installs on the conversation component, so it depends on the same Pi tree the card
-  styles do, and a downstream post-processor can still override the frame. A transform sees lines,
-  not tool metadata: a plugin that needs the call's arguments or the result object still has to use
-  `pi.registerToolRenderer` for rows that are yet to be built. A throwing transform is isolated per
-  frame; a slow one runs on every frame, which the bridge cannot bound.
-- **Tests cover a fake host, not the real TUI.** 673 tests run under `node --test`; 26 of
-  them are end-to-end through the public API and the extension entry, against a fake host
-  that models `gentle-shell.ts:3550-3562` and a fake sidebar that models
-  `lib/shell-sidebar.ts` and the layout's card frame. The capture technique is verified in the
-  real TUI only by the reference probe, and the hook backend has never run against a real host.
-- **The sidebar has never been seen in a running TUI.** The rail interception, the section
-  cards and the automatic `Sections` rows are proven against the fake rail. In particular,
-  whether the widget Pi hands the `tui` through leaves the editor area visually untouched is
-  **unconfirmed** — the component renders no rows, which is the minimal guess.
-- **Sections render after the native cards, never between them.** The host's status sections
-  are built in a closure, so interleaving is not offered.
-- **The sidebar needs `ctx.ui.setWidget`.** Pi exposes no `tui` getter; without the widget
-  factory the rail cannot be reached, and `/bridge-status` reports `sidebar: not armed` with
-  the reason while the `Sections` toggle keeps working.
+- **No upstream hook exists.** The bridge depends on gentle-shell internals. The day the host
+  changes how it builds its menus, the fix belongs here in one place — but it is still a fix
+  against internals, not a supported extension point. If Pi or gentle-shell ever ships a
+  row-provider hook, this package should shrink to a thin adapter over it.
+- **The capture is heuristic.** Rows are recognised by shape, inside one synchronous factory call,
+  and the `Array.prototype.map` patch is restored in a `finally`. A menu built differently produces
+  no capture, and `/bridge-status` reports that instead of passing silently.
+- **`Keymaps` stays reserved for row providers.** The host's keymap page captures keys and claims a
+  footer, so rows there would be advertised as assignable and could never honour it. The supported
+  path is the explicit keymap registration, which the host owns end to end.
+- **Card styles and transforms are repaints, not host features.** They depend on the host's frame
+  grammar, and a downstream post-processor that re-frames the conversation can still override the
+  result.
+- **Tests run against a fake host.** The suite covers the public API and the extension entry
+  against a fake menu, a fake rail and a fake transcript that model the host's shapes; the real TUI
+  is where a change is finally seen.
+
+## Releasing
+
+Versions are cut from a tag: preflight checks that the tag equals the manifest version, runs the
+tests and the typecheck, and prints the exact tarball; publication goes through npm Trusted
+Publishing with no token anywhere; verification reads the registry back and fails if `latest` is
+not the version that was tagged. A published version is immutable, so a mistake is fixed forward
+with the next version.
+
+## Next Steps
+
+- Read the contract's first section, then register a row against the fake host in a scratch
+  extension before touching a real one.
+- If your plugin ships a keymap or palette items, check `/bridge-status` on a host without support
+  first: it tells you exactly which surface is missing, and that is the state you want to degrade
+  in gracefully.

package/docs/contract.md

@@ -7,7 +7,7 @@ What a plugin can rely on. The mechanism behind it is in
 
 ```ts
 const dispose: () => void = registerRows(provider);
-```
+```text
 
 Registers a row provider with the process-global bridge and returns a disposer
 unsubscribing exactly that provider — no other provider's rows and no bridge state are
@@ -35,7 +35,7 @@ interface RowProvider {
   name?: string;                               // optional: this plugin's INTEGRATIONS row (§8)
   rows(ctx: RowContext): CustomizeRow[];       // evaluated lazily, per menu build
 }
-```
+```text
 
 - `rows()` runs each time the menu is built, never at registration. That is what makes
   `current()` honest: the plugin reads its live state at build time, so the bullet matches
@@ -91,7 +91,7 @@ const toggle = (value: string) => ({
 });
 
 rows: () => [toggle("activity"), toggle("output")], // one rendered line
-```
+```text
 
 The renderer draws one line, `Name  ● current  ○ other`, and handles the keys itself: ←/→ moves
 the cursor inside the line and applies a value only when that row does not defer, Enter applies
@@ -151,7 +151,7 @@ Bash design                     OK    a row name: the host's own vocabulary
 Bash card → Bash rendering      BAD   arrow and a repeated qualifier: reads as a breadcrumb
 Bash card: rendering            BAD   colon
 Section: bash-card.status       BAD   prefix plus a dotted id
-```
+```text
 
 The bridge enforces the shape instead of trusting authors; it is never a silent rewrite:
 
@@ -304,7 +304,7 @@ told once, on Pi's cross-extension bus.
 Object.freeze({
   schema: "gentle-shell-bridge/api", // identity, so a foreign payload is never mistaken for ours
   version: 1,                        // the major; a breaking change is a NEW symbol key
-  VERSION: "0.3.1",                  // the publishing release; informational only
+  VERSION: "0.3.2",                  // the publishing release; informational only
   registerRows,
   registerSection,
   registerCardStyle,                 // since 0.2.0; optional on an older published object
@@ -313,7 +313,7 @@ Object.freeze({
   requestRepaint,                    // since 0.3.0; optional on an older published object
   createStore,
 });
-```
+```text
 
 Publication is **first wins**: a compatible object already in the slot is kept and never replaced,
 and the slot is never reset. A consumer gates on the schema string, `version === 1` and the three
@@ -359,7 +359,7 @@ pi.on("session_start", (_event, ctx) => {
     );
   }
 });
-```
+```text
 
 Or import the package and call `onBridgeApi(handler, pi.events)`, which does both forms for you: the
 handler runs immediately when the object is already published (and no listener is taken), otherwise
@@ -374,7 +374,7 @@ const register = (api: BridgeApi): void => {
 
 // Works in both orders: this package loaded first, or the plugin did.
 const dispose = onBridgeApi(register, pi.events);
-```
+```text
 
 `bridgeApi()` never waits, defers or retries: it answers about the slot as it is right now.
 
@@ -387,7 +387,7 @@ When this package publishes its object, it emits one event on Pi's cross-extensi
 pi.events.on("gentle-shell-bridge:ready", (payload) => {
   // { schema: "gentle-shell-bridge/api", version: 1, VERSION: "0.3.0" }
 });
-```
+```text
 
 - **Name:** `gentle-shell-bridge:ready`. Payload: `{ schema, version, VERSION }` — the same identity,
   major and release the published object carries, frozen. Informational only: the payload says
@@ -432,7 +432,7 @@ const dispose = api.registerRows({
   category: "Cards",
   rows: () => [toggle("activity"), toggle("output")], // consecutive rows → one line
 });
-```
+```text
 
 Nothing may sit between the two values or the renderer draws two lines. `current()` is evaluated
 when the menu is built, `action()` runs before the host's own repaint, and `preview()` replaces the
@@ -454,7 +454,7 @@ const dispose = api.registerSection({
   defaultVisible: true,         // absent means true
   order: 10,                    // optional integer
 });
-```
+```text
 
 The bridge generates the `Sections` rows for it: two consecutive rows sharing one label,
 values `shown` / `hidden`, with a live `current()` and a persist-first `action()`. The label — not
@@ -472,7 +472,7 @@ or writes that file.
 const store = api.createStore("loon");
 store.set("bannerSource", "activity");
 const value = store.get("bannerSource", "activity"); // caller's fallback when absent or unreadable
-```
+```text
 
 The document is `{ "schemaVersion": 1, "values": { … } }` at
 `<gentle config home>/gentle-shell-bridge/<pluginId>.json`. `values` is an envelope, so a plugin
@@ -548,7 +548,7 @@ const dispose: () => void = registerSection({
   defaultVisible: true,             // absent means true
   order: 10,                        // optional integer
 });
-```
+```text
 
 - `id` — registering an existing id **replaces** the previous section in place; a second
   card never appears. It is the toggle's identity (replacement, disposer and the persisted
@@ -582,7 +582,7 @@ A row is a plain **string** or a structured **row object**:
 
 ```ts
 { label: string; meta?: string; glyph?: string; tone?: Tone; onClick?: () => void }
-```
+```text
 
 - a plain string is drawn **byte for byte**: the author's characters, clipped to the width, no
   indent, no padding, no styling. Every section written before structured rows existed looks
@@ -626,7 +626,7 @@ child, and the conversation gets `columns - 53`. One decision IS made from a par
 
 ```text
 const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
-```
+```text
 (`lib/shell-sidebar-layout.ts:410`) — a single rail row wider than the content width drops the whole
 rail, and the conversation then takes every column: the layout's widths changed because of what a
 part returned.
@@ -706,7 +706,7 @@ label the user reads, never an id and never a prefix:
 ```text
 stats             ● shown  ○ hidden     ← the host's own row
 music             ● shown  ○ hidden     ← a plugin's section (id "loon.music", title "MUSIC")
-```
+```text
 
 For every registered section the bridge emits **two consecutive rows** in category `Sections`,
 sharing one label as their `choice.setting` (the host prints the setting as the line's name) with
@@ -752,7 +752,7 @@ one namespaced file:
     "collapsed": { "loon.music": true }
   }
 }
-```
+```text
 
 `sections` maps a section id to `true` (shown) / `false` (hidden); a missing id falls back to
 `defaultVisible`. `collapsed` maps a section id to `true` (folded) / `false` (open); a missing id is
@@ -781,7 +781,7 @@ const dispose: () => void = registerCardStyle({
   frame: { top, line, bottom }, // the three functions below; nothing else is called
   preview: () => ({ title: "Cute", sample: "○ cute  ╭─ welcome ─╮" }), // optional, literal
 });
-```
+```text
 
 The id never appears in a row: the host's line reads `Card style  ○ neon ● float ○ cute`, and the
 style's own row is labelled `cute` (or the author's `rowLabel`), exactly like a host row's visible
@@ -794,7 +794,7 @@ text. `label` stays the line's value — the text the host renders and the uniqu
 top(ctx: { width: number; title?: string; hint?: string }): string;
 line(ctx: { text: string; width: number; first: boolean }): string;
 bottom(ctx: { width: number }): string;
-```
+```text
 
 `width` is the width the host rendered at. `title` is the heading the host printed, without its
 glyph and without the right-aligned hint; `hint` is that hint when its style runs prove it is one
@@ -812,7 +812,7 @@ setting, so the user sees ONE line in the host's own position:
 
 ```text
 Card style  ○ neon ● float ○ cute
-```
+```text
 
 The host's own rows keep the host's `current()` and `action()`, wrapped in exactly two ways:
 `current()` reports `false` while a registered style is selected (one bullet at a time), and
@@ -868,7 +868,7 @@ The selection is the bridge's state, not the plugin's:
 
 ```json
 { "schemaVersion": 1, "values": { "cardStyle": "loon.cute" } }
-```
+```text
 
 `cardStyle` is a style id or `native`. A missing file, an unreadable one, an unknown
 `schemaVersion` or a non-string value reads as `native`. A stored id whose style was disposed
@@ -928,7 +928,7 @@ const dispose: () => void = registerTransform({
     return rows;
   },
 });
-```
+```text
 
 ### What the transform receives
 
@@ -1009,7 +1009,7 @@ keeps its report byte for byte:
 transforms: 2 registered
   - loon.bash-cards (order 10): applied, 13 lines, 4 candidates, 1 recognised, 1 rewritten, shapes: float 1
   - loon.strict (registration order): failed (definitions are missing), 13 lines, 0 candidates, 0 recognised, 0 rewritten
-```
+```text
 
 `applied` means the frame changed, `skipped` means the transform was called and left the rows as they
 were, `failed` carries its message, and `not run` means it was registered after the last frame. The
@@ -1034,7 +1034,7 @@ api.registerToolDesign({
     return lines.map((line) => rewriteTheMarkOnly(line));
   },
 });
-```
+```text
 
 ### The convention: lines in, lines out
 
@@ -1199,21 +1199,78 @@ The bridge registers exactly ONE `pi.registerToolRenderer` resolver for the whol
 out to these designs. That is why two plugins contributing designs for the same tool do not stack
 wrappers, and why a plugin must never call `pi.registerToolRenderer` itself for a design.
 
+## 15. Plugin keymaps and the command palette
+
+The bridge publishes what plugins contributed; the **host reads it per build**. The direction is the
+design: there is no registration handshake, no startup cache and no lifecycle in the host, so a
+registration made during `session_start` is visible at the next menu or palette open, in any load
+order.
+
+```text
+Symbol.for("gentle-shell-bridge/plugin-surface/v1") → { schema: 1, keymaps(), commands() }
+```text
+
+Both getters answer with a **copy**, never the live array, so a host that keeps one cannot mutate
+what the bridge owns.
+
+### `registerKeymap(registration): () => void`
+
+One action for the host's Keymaps page: `{ id, label, env?, defaultKey?, command? }`.
+
+- `id` and `label` must be non-empty strings; `env`, `defaultKey` and `command` are optional but,
+  when present, must be non-empty strings too. Validation happens here, where the plugin author sees
+  the error.
+- An `id` starting with `command:` is refused: those name palette command bindings, not plugin
+  actions.
+- The same `id` registered twice **replaces in place and is reported**, like every other
+  registration in this package. A silent takeover would be one plugin stealing another's row.
+- The disposer removes exactly the entry it created. A replaced entry is a different object, so
+  disposing the old registration never deletes its successor.
+- A contributed id can never shadow a built-in action or a `command:<name>` binding: the host keeps
+  its own ids.
+
+### `registerCommands(contribution | contribution[]): () => void`
+
+One palette item, or several: `{ id, label, command, section? }`.
+
+- An item joins the section it names, after that section's own entries, or opens a section of its
+  own after the host's catalog. Without `section` it lands in the shared `Plugins` page.
+- The host lists an item only while its command is registered, so a missing extension leaves no
+  dead row, and an own section that would be left empty does not appear at all.
+- An `id` twice **in one call** is refused whole: the batch would silently keep only the last one.
+  Across calls it replaces in place and is reported, exactly like keymaps.
+
+### `resolveKeymap(id): { key?; unavailable? }`
+
+The key an id currently uses, answered by the shell that owns the file, the environment override
+and the defaults — environment variable, then saved binding, then default. It never throws: no
+shell, an older shell or a throwing getter is an `unavailable` reason the caller reports.
+
+The plugin then binds the key itself with `pi.registerShortcut`. The bridge never binds for a
+plugin, and the shell never binds a plugin's key. That split is what keeps one implementation of the
+precedence: the row and the real binding cannot disagree.
+
+**A keymap change applies after `/reload`.** Pi reads extension shortcuts at startup and on reload,
+for native actions and contributed ones alike, and it exposes no way to re-register a shortcut while
+running. The Keymaps page says so, and its last row offers the reload.
+
 ## Limits
 
 - `registerRows`, `registerSection`, `registerCardStyle`, `registerTransform`,
-  `registerToolDesign`, `requestRepaint`, `createStore`, `bridgeApi`, `isBridgeApi`, `onBridgeApi`
+  `registerToolDesign`, `registerKeymap`, `registerCommands`, `resolveKeymap`, `requestRepaint`,
+  `createStore`, `bridgeApi`, `isBridgeApi`, `onBridgeApi`
   and the `gentle-shell-bridge:ready` event are the contract; anything a plugin does inside `action()` beyond
   calling inline helpers is the plugin's own business.
-- **`Keymaps` is reserved.** A provider registered with `category: "Keymaps"` is refused before
-  anything is stored, with an error naming the category and why (its own key capture and footer; not
-  open to plugins yet); the refusal is a rejected registration in the plugin's INTEGRATIONS line and in
-  `/bridge-status`. A single row whose own `category` is `Keymaps` is dropped and reported the same way,
-  and its siblings still render. The comparison is trimmed and case-insensitive: ` keymaps ` and
-  `KEYMAPS` are the same page; `Keymap` and `Key maps` are ordinary categories. `Profiles` and `Reset`
-  are not reserved: a plugin row there renders as an ordinary line. A refusal of one row is listed under
-  `row rejections` but is not counted in the plugin's INTEGRATIONS line (a build cannot reach it; only the
-  registration refusal does).
+- **`Keymaps` stays reserved for row providers.** A provider registered with `category: "Keymaps"` is
+  refused before anything is stored, with an error naming the category and why; the refusal is a rejected
+  registration in the plugin's INTEGRATIONS line and in `/bridge-status`. A single row whose own
+  `category` is `Keymaps` is dropped and reported the same way, and its siblings still render. The
+  comparison is trimmed and case-insensitive: ` keymaps ` and `KEYMAPS` are the same page; `Keymap` and
+  `Key maps` are ordinary categories. `Profiles` and `Reset` are not reserved: a plugin row there renders
+  as an ordinary line. A refusal of one row is listed under `row rejections` but is not counted in the
+  plugin's INTEGRATIONS line (a build cannot reach it; only the registration refusal does). The reason
+  is unchanged and now has a supported alternative: that page captures keys and claims a footer, so a
+  plain row would be advertised as assignable and could never honour it — a plugin uses §15 instead.
 - **A new category becomes a page.** The host computes its page list once, in the view's constructor
   (`lib/visual-customize-view.ts:387`), so the rows must be in the array before that `map` runs; see
   [architecture.md](architecture.md) "A brand-new page". The cost is stated there. The one residual
@@ -1261,6 +1318,6 @@ wrappers, and why a plugin must never call `pi.registerToolRenderer` itself for
   simply false) and keeps working.
 - A transform is a per-frame pass, so a slow transform is a slow frame; the bridge isolates its
   failures and clips its width, and can bound nothing else. It sees lines, never tool metadata.
-- The API is released (`0.3.0`). The `v1` symbol is the compatibility boundary: a breaking
+- The API is released (`0.3.2`). The `v1` symbol is the compatibility boundary: a breaking
   change takes a new key instead of mutating this one (§9). The `gentle-shell-bridge:ready` event is
   additive: a plugin that never subscribes loses nothing but the late-load case.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-shell-bridge",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Shared provider bus for gentle-shell's /gentle:customize settings rows: plugins register rows, the bridge owns the single interception layer.",
   "type": "module",
   "keywords": [

package/src/api.ts

@@ -67,7 +67,7 @@ import { createStore } from "./store.ts";
 import { registerToolDesign } from "./tool-designs.ts";
 
 /** The release that published the object; informational, never the compatibility check. */
-export const VERSION = "0.3.1";
+export const VERSION = "0.3.2";
 
 /** Identity of the object, so a foreign payload at the symbol is never mistaken for ours. */
 export const API_SCHEMA = "gentle-shell-bridge/api";