opendoor-plugin 0.2.0 → 0.5.0

package/README.md

@@ -1,300 +1,279 @@
 # opendoor — a Doorstop requirements-management plugin for PI WEB
 
-`opendoor` is a **paired** PI WEB plugin that surfaces
-[Doorstop](https://github.com/doorstop-dev/doorstop) requirements stored in
-the workspace next to the code they trace to: a **Requirements** workspace tab
-with the document tree, per-item state (reviewed/unreviewed changes, suspect
-links), validation findings, and one-click `doorstop` CLI actions (validate,
-publish, add/link/unlink, clear suspect links, review), plus agent prompts
-that insert requirement context into the session. When paired, the plugin's
-server entry runs the CLI headlessly and the captured output is displayed in
-the panel itself (a **status bar** at the bottom); when unpaired, every action
-falls back to the workspace terminal. The paired backend also recovers the
-reviewed version of an item file from git history, so the item detail pane
-can show a **Changes since review** diff — and Review can optionally record
-a pathspec-limited review commit (`commitAfterReview`).
+`opendoor` is a PI WEB plugin that surfaces
+[Doorstop](https://github.com/doorstop-dev/doorstop) requirements stored in the
+workspace in a **Requirements** workspace tab with
+the document tree, per-item state (reviewed/unreviewed changes, suspect links),
+validation findings and `doorstop` actions, plus agent prompts
+that insert requirement context into the session. 
+The paired backend also recovers an item file's reviewed version from git for 
+the **Changes since review** diff, and Review can opt in to a review commit 
+(`commitAfterReview`).
 
 Full feature spec: [`docs/feature-doorstop-plugin.md`](docs/feature-doorstop-plugin.md)
 (§5 architecture, §6 requirements state model, §7–§8 UI/actions).
 
 ## Status
 
-The plugin is fully wired and green, in two halves:
-
-- **Browser entry** (`src/pi-web-plugin.ts`, apiVersion 2, name `Opendoor`)
-  delegates to `createOpendoorBrowserContributions` in
-  `src/doorstop-contributions.ts`, which contributes:
-
-  - **panel** `workspace.doorstop` (title **Requirements**, order 60) — the Lit
-    body element `<pi-web-opendoor-panel-body>`, driven by the per-workspace
-    controller registry (`src/doorstop-panel.ts`): five vertical sections —
-    `project-actions` (title, Items/Findings toggle, Refresh / Run validation
-    / Publish HTML), `item-list` (filters row + item rows with state chips),
-    `item-details` (links in/out, references, extended attributes,
-    collapsible **Changes since review** diff), `item-action-palette`
-    (Review / Clear suspect links / Edit / Link / Unlink / Ask-agent menu,
-    sized to the host prompt footer), and `status-bar` (status badge,
-    duration, Dismiss button, and the auto-expanding stdout/stderr of the
-    latest CLI run, plus the review-commit outcome line when the review
-    requested a commit);
-  - **actions** `view.doorstop` (mod+7) and `workspace.refresh-doorstop`
-    (mod+shift+d);
-  - **label** `doorstop-status` — the informational requirement-health counts
-    (async-cache idiom, feature spec §7.4).
-
-- **Server entry** (`src/server-plugin.ts`, default export `PiWebServerPlugin`)
-  contributes a workspace provider that claims only projects whose root
-  contains a `.doorstop.yml` (cheap `fs.access` probe — everything else stays
-  with the bundled Git provider) and serves a six-operation backend:
-  `doorstop.run` runs one Doorstop CLI invocation — a review request carrying
-  the opt-in `commit: true` flag is followed by a pathspec-limited git commit
-  of the item file (`doorstop: review <uid>`) — the read-only
-  `doorstop.item-baseline` recovers the reviewed version of an item file from
-  git history, and the four git actions `doorstop.git-status`,
-  `doorstop.git-stage`, `doorstop.git-unstage`, and `doorstop.git-commit`
-  power the panel's git strip and stage/unstage/commit controls (see **Git
-  actions** below). `src/doorstop-backend.ts` validates each request, builds argv
-  server-side (the browser never sends shell strings), and runs through the
-  host's `execFile()` helper with `cwd` = the workspace path, timeouts
-  clamped to 8.5 s (the review+git pipeline shares one deadline budget under
-  the host's 10 s callback bound), and per-workspace run serialization.
-
-Dispatch (per action, in `src/doorstop-panel-elements.ts`): when the workspace
-is opendoor-owned with an active backend, the action sends a structured
-request via `context.backend.request("doorstop.run", …)` (the review-commit
-flag rides along when the setting is enabled; the "Changes since review"
-section fetches via `context.backend.request("doorstop.item-baseline", …)`)
-and the captured output appears in the panel's status bar (auto-expanded);
-the panel auto-rescans on completion. When the backend is absent (unpaired
-install, or a workspace the provider does not own), the action falls back to
-`terminal.runCommand()` with the same shell command, so output stays visible
-and auditable in the terminal.
-
-  `doorstop.run` and `doorstop.item-baseline`) shared by both halves, plus the
-  four git-action contracts (`doorstop.git-status`, `doorstop.git-stage`,
-  `doorstop.git-unstage`, `doorstop.git-commit`), live in
-  `src/doorstop-backend-contract.ts`. Later modules import these and must not
-  redefine them.
+Requires **pi-web 1.202611.1 or newer** (browser and server plugin API v5). 
+
+One package (`opendoor-plugin`) ships the PI WEB plugin (both entries below) 
+and the Pi extension (`/opendoor-review`).
+
+- **Browser entry** (`src/browser/pi-web-plugin.ts`, apiVersion 5, name
+  `Opendoor`) delegates to `createOpendoorBrowserContributions`
+  (`src/browser/doorstop-contributions.ts`): the **panel** `workspace.doorstop`
+  (title **Requirements**, order 5 — below the Files panel's order 10 so doorstop
+  item links reach its `fileOpenQuery` first, at the cost of the Requirements tab
+  preceding Files in the tab order; controller registry in
+  `src/browser/doorstop-panel.ts`, sections in **Using the panel**),
+  the **actions** `view.doorstop` (mod+7) and `workspace.refresh-doorstop`
+  (mod+shift+d), the **label** `doorstop-status` (requirement-health counts,
+  feature spec §7.4), and the **session-row label** `doorstop.review` (reopens the
+  Requirements tab from a row carrying public `opendoor` metadata, archived rows
+  included — feature spec, **Session metadata and session-list row labels**).
+- **Server entry** (`src/server-plugin.ts`, apiVersion 5, default export
+  `PiWebServerPlugin`) contributes a workspace provider for projects whose root
+  has a `.doorstop.yml` (cheap `fs.access` probe; everything else stays with the
+  bundled Git provider) and serves six operations: `doorstop.run` (one CLI
+  invocation; a review carrying the opt-in `commit: true` flag is followed by a
+  pathspec-limited `doorstop: review <uid>` commit), the read-only
+  `doorstop.item-baseline` (the reviewed version, from git history), and
+  `doorstop.git-status` / `-stage` / `-unstage` / `-commit` (see **Git
+  actions**). `src/doorstop-backend.ts` validates each request, builds argv
+  server-side (never a browser shell string) and runs it via `execFile()`; see
+  its header for timeouts and per-workspace serialization. The entry declares no
+  `requires` and no `start()`: the retired `doorstop.ask-agent` dispatch could
+  not live there (provider-cycle rule) — see `src/server-plugin.ts`.
+- **Pi extension** (`src/pi-extension/opendoor-review.ts`, bundled to
+  `dist/pi-extension/index.js`, declared by `pi.extensions`) registers
+  `/opendoor-review <UID> [instruction…]`: it publishes the public `opendoor`
+  metadata (`{ schema: 1, op: "review", uids }`) and asks PI WEB's per-session
+  dispatch bridge to start an independent conversation in the same project (the
+  `spawn_session` rules, model/thinking inherited), reporting every outcome in
+  the initiating conversation — the pathway **Start review session** drives.
+
+Dispatch (`src/browser/doorstop-panel-element.ts`) uses
+`context.peer.request("doorstop.run", …)` (the review-commit flag rides along
+when enabled; **Changes since review** uses `doorstop.item-baseline`) with the
+output in the auto-expanded status bar, or falls back to `terminal.runCommand()`
+with the same shell command when unpaired. Shared types and operation contracts
+live in `src/doorstop-contract.ts` and `src/doorstop-backend-contract.ts`.
 
 ## Workspace settings (`.pi-web/opendoor.json`)
 
-Optional per-workspace configuration, read by the plugin on every load
-(missing file → defaults; malformed or invalid values → warning diagnostics
-in the panel + defaults). Workspace-scoped settings cannot use pi-web's
-`plugins.<id>.settings` config (that is host-side and only reaches server
-entries), so this file plays the same role `.pi-web/tasks.json` plays for the
-bundled workspace-tasks plugin. The *server* entry's host-scoped knobs
-(CLI binary path, exec timeout) are configured through
-`plugins.opendoor.settings` instead — see **Host settings** below:
+Optional per-workspace configuration, read on every plugin load (missing file →
+defaults; malformed or invalid values → warning diagnostics + defaults). pi-web's
+`plugins.<id>.settings` is host-side and reaches only server entries, so this
+file plays the role `.pi-web/tasks.json` plays for the bundled workspace-tasks
+plugin; server-entry knobs are in **Host settings** below:
 
 ```json
 {
   "version": 1,
   "publish": { "target": "./public" },
   "discovery": { "excludedDirectories": ["published", "vendor"] },
+  "showAdditionalAttribute": ["text", "component"],
   "commitAfterReview": false
 }
 ```
 
-- `publish.target` — path passed to `doorstop publish all`. Must be a safe
+- `publish.target` — path passed to `doorstop publish all`; must be a safe
   workspace-relative path (no `..`, no absolute, no drive prefix, no leading
-  `-`). It is shell-quoted at the terminal-command boundary when it contains
-  characters outside the inert `\w./-` alphabet; on the backend path the
-  target is passed as an argv element, never through a shell.
+  `-`). Shell-quoted at the terminal-command boundary when it contains characters
+  outside the inert `\w./-` alphabet; on the backend path it is an argv element,
+  never a shell string.
 - `discovery.excludedDirectories` — additional directory names the
   `.doorstop.yml` walk never enters (merged with the built-in
   `.git`/`node_modules` skips, max 16 names).
-- `commitAfterReview` — opt-in boolean (default `false`): when enabled on a
-  paired workspace, the **Review** action's `doorstop review <uid>` is
-  followed by a pathspec-limited git commit of the item file with the
-  conforming message `doorstop: review <uid>` (git `add` then
-  `commit -m … -- <path>` — other staged/unstaged work is left untouched).
-  Committing user content is strictly opt-in, and the status bar
-  narrates every commit outcome (`commit: <sha>` / `clean` (already
-  committed) / `skipped` (not a git repository | item file not found |
-  review failed | deadline) / `failed` — `<stderr>`). Under the default,
-  Review behaves exactly as before.
+- `showAdditionalAttribute` — attribute NAMES rendered in every item-list row as
+  `key: value` (values jsonish-quoted, joined with ` · `, in configured order);
+  any extended attribute key works, an attribute an item lacks is skipped, and no
+  unconfigured attribute ever appears. The modeled `text` is special-cased: the
+  body renders raw and unquoted on an indented second line below the row, clamped
+  to two lines with an ellipsis (the full body lives in the detail pane), skipped
+  when empty. Default `[]` leaves today's rows unchanged. Invalid entries are
+  dropped with a warning each, duplicates deduplicated, capped at 16 names;
+  unknown keys simply match nothing.
+- `commitAfterReview` — opt-in boolean (default `false`): on a paired workspace
+  the **Review** action's `doorstop review <uid>` is followed by a
+  pathspec-limited commit of the item file with the conforming message
+  `doorstop: review <uid>` (git `add` then `commit -m … -- <path>`; other
+  staged/unstaged work is untouched). Committing user content is strictly opt-in;
+  the status bar narrates every outcome (`commit: <sha>` / `clean` (already
+  committed) / `skipped` (not a git repository | item file not found | review
+  failed | deadline) / `failed` — `<stderr>`); Review is otherwise unchanged.
 
 ## Host settings (`plugins.opendoor.settings`)
 
-Optional, server-side only (requires the paired install and a sessiond
-restart to take effect). Parsed leniently; wrong types fall back to defaults:
+Optional, server-side only (needs the paired install and a sessiond restart);
+wrong types fall back to defaults:
 
 ```json
 { "doorstopPath": "/opt/venv/bin/doorstop", "gitPath": "git", "timeoutMs": 8000 }
 ```
 
-- `doorstopPath` — the Doorstop CLI binary. Defaults to `"doorstop"` resolved
-  on the **sessiond host PATH** (the daemon environment, not your login shell
-  — set this when the CLI lives in a venv or is not on the service PATH).
-- `gitPath` — the git binary used by the review→commit pipeline, the
-  `doorstop.item-baseline` fetch, and the four git actions (status strip,
-  Stage all, per-item Unstage, Git commit). Defaults to `"git"` resolved on the
-  **sessiond host PATH** — set it when git is not on the service PATH (the
-  same escape hatch as `doorstopPath`).
-- `timeoutMs` — per-run exec timeout in ms. May SHORTEN the 8 500 ms default
-  but never exceed it (the host bounds every provider callback at 10 s, so a
-  longer doorstop run would be killed by pi-web, not by the plugin). It also
-  bounds every git exec of the review→commit pipeline, the baseline fetch,
-  and the git actions, which share one deadline budget per callback.
+- `doorstopPath` — the Doorstop CLI binary, default `"doorstop"`, resolved on the
+  **sessiond host PATH** (the daemon environment, not your login shell — set it
+  when the CLI lives in a venv or is off the service PATH).
+- `gitPath` — the git binary for the review→commit pipeline, the
+  `doorstop.item-baseline` fetch and the four git actions. Default `"git"` on the
+  **sessiond host PATH** — the same escape hatch as `doorstopPath`.
+- `timeoutMs` — per-run exec timeout in ms. May SHORTEN the 8 500 ms default but
+  never exceed it (the host bounds every provider callback at 10 s, so a longer run
+  would be killed by pi-web, not by the plugin). It also bounds every git exec of
+  the review→commit pipeline, the `doorstop.item-baseline` fetch and the git
+  actions: one deadline budget per callback.
 
 ## Using the panel
 
-The right-hand panel body is divided into five vertical sections, top to
-bottom:
-
-1. **`project-actions`** — the project heading (the workspace's root path,
-   basename shown, full path on hover), the **Items / Findings** toggle, the
-   project-scoped buttons **Refresh**, **Run validation**, and **Publish
-   HTML**, and — on paired installs — the **Git status** strip, the **Stage
-   all** button, and the **Git commit** control (message input + button); see
-   **Git actions** below.
-2. **`item-list`** — a filters row (document chips, state filter, search)
-   above the item rows.
-3. **`item-details`** — the selected item's full detail pane (unchanged).
-4. **`item-action-palette`** — the item actions (**Review**, **Clear suspect
-   links**, **Edit**, **Unlink**/**Link** + target UID inputs, **Ask agent**
-   menu), moved out of the detail pane so the row spans the panel at the same
-   height as the center-panel chat prompt footer. A muted "Select an item…"
-   placeholder keeps the palette at constant height while nothing is
-   selected; the palette is hidden in the Findings view.
-5. **`status-bar`** — the run status row (badge, duration, **Dismiss**),
-   sized like the center-panel status bar, plus the captured output.
-
-- **Items / Findings toggle** in the project-actions row. Findings lists all
-  plugin-computed findings and diagnostics (error > warning > info); a
-  finding's UID navigates back to the item. Findings are informational — run
-  the **Run validation** button for the authoritative `doorstop` output
-  (paired: rendered in the panel's status bar; unpaired: in the workspace
-  terminal).
-- **Status bar**: after a paired action completes, the bottom bar shows the
-  run's status (ok / failed / killed / error) and duration, and the panel
-  re-scans automatically. The captured stdout/stderr *auto-expands* whenever
-  a run produces a message to show (any output, an error message, or a
-  review-commit line) — no interaction needed; a run with nothing to display
-  stays collapsed to its status row. **Dismiss** clears the run and collapses
-  the bar; the next run with output re-expands it. Runs killed at the exec
-  timeout preserve and show partial output; prefer the workspace terminal for
-  long publishes. When a review ran with `commitAfterReview` enabled, the bar
-  adds a `commit: …` narration line (`commit: <short-sha>` /
-  `clean (already committed)` / `skipped (not a git repository | item file
-  not found | review failed | deadline)` / `failed — <stderr excerpt>`); a
-  failed or skipped commit never changes the run's ok/failed badge.
-- **State chips** per item (feature spec §6): inactive, non-normative,
-  reviewed / unreviewed changes, suspect links, no child links, no links,
-  unknown link, missing reference.
-- **Changes since review** (item detail pane, paired installs only): for an
-  item with unreviewed changes and a stored `reviewed` fingerprint, a
-  collapsed section shows what changed since the last review. Expanding it
-  lazily fetches the reviewed version of the item file from git history via
-  the `doorstop.item-baseline` backend operation, stamp-matches it against
-  the stored fingerprint, and renders a text line diff plus chips for
-  `ref`/`references`/link-UID/extended-attribute changes. When no baseline
-  can be recovered it says so honestly ("no git history", "could not locate
-  the reviewed version — history may have been rewritten"). The
-  `doorstop: review <uid>` commit message is the historical anchor that the
-  deferred browser-side git parsing of feature spec §12 could not give — the
-  recovery runs server-side, where git lives.
-- **Item actions** (item-action-palette): Review (`doorstop review UID` — with
-  `commitAfterReview` enabled and paired, followed by the pathspec-limited
-  review commit), Clear suspect links (`doorstop clear UID [parents…]`),
-  Edit (`doorstop edit UID`), Link/Unlink via inline UID input (validated
-  against the Doorstop UID grammar; shell metacharacters rejected), and — on
-  paired installs — Stage / Unstage for the selected item's own file
-  (`doorstop.git-stage` / `doorstop.git-unstage` with just that item's
-  path; see **Git actions** below). Each is independently disabled: Stage
-  when the file has no unstaged (`Y`) changes, Unstage when it has nothing
-  staged (`X`), and both while a run is in flight.
-- **Git actions** (paired installs only; every git control is hidden
-  without the paired backend — terminal-fallback users commit manually as
-  today):
-  - **Git status strip** — a compact readout above the item list:
-    `⎇ <branch> · <n> staged · <n> dirty · ↑<ahead> ↓<behind>` (zero/absent
-    parts omitted; `no git` outside a repository; a retry link on fetch
-    errors). The strip refreshes on panel load, after every run (a stage,
-    unstage, or commit invalidates the cache), and whenever you click it.
-    Outside a git repository the strip shows `no git` and the stage/unstage/
-    commit controls are no-ops that report `skipped`.
-  - **Stage all** — stages every Doorstop-managed file (the root
-    `.doorstop.yml`, each document's config file, each item file) via the
-    `doorstop.git-stage` backend operation. Staging is idempotent: a second
-    click over an already-staged set reports `clean — nothing to stage`
-    instead of a git error (staged deletions in particular are skipped
-    rather than fatal). Disabled while a run is in progress or when the
-    loaded index has no documents. Note: staging is only as fresh as the
-    loaded index — files created on disk after the last **Refresh** are
-    missed until you refresh and stage again.
-  - **Unstage (per item)** — while an item's file has staged (index)
-    changes, its list row shows a **minus** in place of the usual plus, and
-    the item palette enables an **Unstage** button, both served by the
-    `doorstop.git-unstage` operation (`git reset -q -- :(literal)<path>`
-    server-side). The row's pointer shortcut prefers the minus when a file
-    is both staged and further modified (`MM`), so "I staged by mistake"
-    always surfaces a minus; the palette shows Stage and Unstage as two
-    independently-disabled buttons in that case. Unstaging restores the
-    index entry but never touches the working tree: a staged addition
-    returns to `??` untracked, a staged deletion returns to an unstaged
-    deletion. It is idempotent — a second Unstage over an already-clean path
-    reports `clean — nothing to unstage`. Unmerged paths (`UU`, `AA`, `DD`,
-    `DU`, `AU`, `UD`, `UA`) are excluded — a `git reset` on an unmerged path
-    would silently resolve the conflict in the index. On unpaired installs no
-    git control is rendered at all; while a run is in flight no minus appears
-    and the palette buttons are disabled (the per-row affordance is also
-    suppressed when the status file list is truncated, so stale path data is
-    never acted on).
-  - **Git commit** — a single-line message input plus a **Commit** button,
-    served by the `doorstop.git-commit` operation. The commit records **the
-    staged index** (`git commit -m <message>` with no pathspec and no
-    add) — exactly like the git CLI. Consequences, all intended: unstaged
-    WIP is never swept into a commit; files you staged yourself (via the
-    git CLI or any other tool) are committed too; the strip's `staged`
-    count tells you what a commit will record before you click. Empty or
-    whitespace-only messages are rejected client-side (git with an empty
-    `-m` would open an editor and hang the exec). Committing with nothing
-    staged reports `clean — nothing staged`. Outcomes are narrated in the
-    status bar (`staged <n> paths` / `committed <sha>` / `clean — nothing
-    to stage` / `clean — nothing staged` / `skipped` / `failed — <stderr
-    excerpt>`); a failing pre-commit hook surfaces its stderr in the
-    expanded status bar body.
-- **Ask the agent** menu: inserts ready-made prompts (explain, fix suspect
-  links, draft child requirement, review readiness) into the session prompt
-  editor using the item's paths and state (feature spec §7.3).
-- Fingerprints and the requirement state are recomputed in the browser from
-  the YAML files; everything mutating goes through the visible `doorstop`
-  CLI — paired, headlessly via the server entry (output captured in the
-  panel), or in a workspace terminal when unpaired — plus, opt-in, the
-  narrated pathspec-limited review commit (`commitAfterReview`) — so all
-  effects stay auditable in git.
+Five vertical sections, top to bottom: `project-actions` (project heading — root
+path, basename shown, full path on hover — the Items/Findings toggle, Refresh, Run
+validation, Publish HTML, and on paired installs the Git strip, Stage all and
+Commit), `item-list` (filters row above rows showing level, UID, excerpt,
+`showAdditionalAttribute` values and state chips), `item-details` (Markdown item
+text, links in/out, references, extended attributes, the Changes diff),
+`item-action-palette` (Review, Clear suspect links, Link, Ask agent — spanning the
+panel at chat-prompt-footer height, with the muted "Select an item…" placeholder,
+hidden in the Findings view) and `status-bar` (see below).
+
+- **Items / Findings toggle**: Findings lists plugin-computed findings and
+  diagnostics (error > warning > info), and a finding's UID navigates back to the
+  item. They are informational — **Run validation** gives the authoritative
+  `doorstop` output (paired: status bar; unpaired: terminal).
+- **Status bar** (sized like the center-panel one): after a paired action it shows
+  status (ok / failed / killed / error) and duration, and the panel re-scans
+  automatically. Captured stdout/stderr *auto-expands* whenever there is something
+  to show (output, an error, a review-commit line); a run with nothing to display
+  stays collapsed. **Dismiss** clears the run and collapses the bar; the next run
+  with output re-expands it. Killed runs keep partial output (prefer the terminal
+  for long publishes). With `commitAfterReview` on, the bar adds the `commit: …`
+  line from **Workspace settings**; a failed or skipped commit never changes the
+  run's ok/failed badge.
+- **State chips** per item (feature spec §6): inactive, non-normative, reviewed /
+  unreviewed changes, suspect links, no child links, no links, unknown link,
+  missing reference.
+- **Changes since review** (item detail pane, paired installs only): an item with
+  unreviewed changes and a stored `reviewed` fingerprint gets a collapsed section;
+  expanding it fetches the reviewed item file from git history via
+  `doorstop.item-baseline`, stamp-matches it against the fingerprint and renders a
+  line diff plus chips for `ref`/`references`/link-UID/extended-attribute changes.
+  With no recoverable baseline it says so ("no git history", "could not locate the
+  reviewed version — history may have been rewritten"). The `doorstop: review
+  <uid>` message is the historical anchor feature spec §12's deferred browser-side
+  git parsing could not give; recovery runs server-side.
+- **Item actions** (item-action-palette): Review (`doorstop review UID`, plus the
+  review commit when `commitAfterReview` is on), Clear suspect links (`doorstop
+  clear UID [parents…]`), Edit (`doorstop edit UID`), Link/Unlink via inline UID
+  input (Doorstop UID grammar enforced; shell metacharacters rejected), and on
+  paired installs Stage / Unstage for the item's own file (`doorstop.git-stage` /
+  `doorstop.git-unstage`; see **Git actions**). Each disables independently: Stage
+  without unstaged (`Y`) changes, Unstage with nothing staged (`X`), both mid-run.
+- **Git actions** (paired only; otherwise every git control is hidden and you
+  commit manually):
+  - **Git status strip** — compact readout above the item list:
+    `⎇ <branch> · <n> staged · <n> dirty · ↑<ahead> ↓<behind>` (zero/absent parts
+    omitted, `no git` outside a repository, a retry link on fetch errors).
+    Refreshes on panel load, after every run (a stage, unstage or commit
+    invalidates the cache) and on click; outside a repository the other git
+    controls report `skipped`.
+  - **Stage all** — stages every Doorstop-managed file (root `.doorstop.yml`, each
+    document config, each item file) via `doorstop.git-stage`. Idempotent: a
+    second click over an already-staged set reports `clean — nothing to stage`
+    instead of a git error (staged deletions are skipped, not fatal). Disabled
+    during a run or with no documents in the loaded index, and only as fresh as
+    that index — files created after the last **Refresh** are missed until you
+    refresh and stage again.
+  - **Unstage (per item)** — a staged item file swaps its row's plus for a
+    **minus** and enables **Unstage** in the palette, both via
+    `doorstop.git-unstage` (`git reset -q -- :(literal)<path>` server-side). A file
+    both staged and further modified (`MM`) still shows the minus; the palette then
+    offers Stage and Unstage as two independently-disabled buttons. Unstaging
+    restores the index entry but never touches the working tree (a staged addition
+    returns to `??`, a staged deletion to an unstaged deletion); it is idempotent
+    (`clean — nothing to unstage`) and excludes unmerged paths (`UU`, `AA`, `DD`,
+    `DU`, `AU`, `UD`, `UA`), where `git reset` would silently resolve the conflict.
+    During a run no minus appears and the palette buttons are disabled; the per-row
+    affordance is also suppressed when the status file list is truncated, so stale
+    path data is never acted on.
+  - **Git commit** — a message input plus **Commit**, served by
+    `doorstop.git-commit`. It records **the staged index** (`git commit -m
+    <message>`, no pathspec, no add), exactly like the git CLI: unstaged WIP is
+    never swept in, files you staged yourself are included, and the strip's
+    `staged` count shows what a commit will record. Empty or whitespace-only
+    messages are rejected client-side (git would open an editor and hang the exec);
+    nothing staged reports `clean — nothing staged`. Outcomes are narrated in the
+    status bar (`staged <n> paths` / `committed <sha>` / `clean — nothing to stage`
+    / `clean — nothing staged` / `skipped` / `failed — <stderr excerpt>`), including
+    a failing pre-commit hook's stderr.
+- **Ask the agent** menu: inserts ready-made prompts (explain, fix suspect links,
+  draft child requirement, review readiness) into the session prompt editor from
+  the item's paths and state (feature spec §7.3). **Start review session**
+  composes `/opendoor-review <UID>` plus the item context there and needs no
+  paired backend: the extension starts an independent review conversation whose
+  row carries a **`firstUid +n` label** reopening the Requirements tab on that
+  workspace (unselected and archived rows included, no live Pi connection needed),
+  landing on the item detail pane. After the insert the status bar shows a quiet
+  `ok` **review dispatch** run row. Without the extension the inserted text is
+  still a self-sufficient review instruction, so the review happens in the current
+  conversation; a refused dispatch is reported in the chat by the extension (see
+  **Session metadata and session-list row labels** in the feature spec).
+- Fingerprints and requirement state are recomputed in the browser from the YAML
+  files; everything mutating goes through the visible `doorstop` CLI — paired,
+  headlessly via the server entry, or in a workspace terminal when unpaired —
+  plus, opt-in, the narrated review commit (`commitAfterReview`) — so all effects
+  stay auditable in git.
+
 
 ## Commands
 
 ```sh
-npm install        # install dependencies
-npm test           # vitest (unit tests under src/**/*.test.ts)
+npm install            # install dependencies
+npm test               # vitest (unit tests under src/**/*.test.ts)
 npm run test:coverage  # v8 coverage report
-npm run typecheck  # tsc --noEmit (strict)
-npm run build      # esbuild: dist/browser/pi-web-plugin.js + dist/server-plugin.js
-                   # (+ verbatim package.json manifest copy into dist/)
-npm run dev        # watch mode build
+npm run typecheck      # tsc --noEmit (strict)
+npm run build          # esbuild → dist/browser, dist/server, dist/pi-extension
+                       # + the dist-root manifest (see the build script header)
+npm run dev            # watch build
 ```
 
 ## Installing the plugin locally (id `opendoor`)
 
+The package carries two independently enabled halves: the **PI WEB plugin**
+(browser + server entries) and the **Pi extension** (`/opendoor-review`). The
+repository-root `package.json` is the npm-package-root manifest, so both halves
+come from ONE install through **Settings → Pi packages** (npm name, git/URL or a
+local source); the `ln -s dist` route below remains for plugin-only development.
+
+### PI WEB plugin (browser + server entries)
+
+Install the package once — **Settings → Pi packages** with source
+`opendoor-plugin` (or this repository's path / git URL) — then enable
+**Opendoor** under **Settings → PI WEB plugins**. Plugin-only local build:
+
 ```sh
 npm run build
 ln -s "$(pwd)/dist" ~/.pi-web/plugins/opendoor
 ```
 
 Then **restart the session daemon** (server entries load at sessiond startup
-only; the browser bundle hot-reloads on page reload) and reload the PI WEB
-page:
+only; the browser bundle hot-reloads on page reload) and reload the page:
 
 ```sh
 systemctl --user restart pi-web-sessiond.service
 curl -s http://127.0.0.1:8504/pi-web-plugins/manifest.json
 ```
 
-The manifest should list an `opendoor` plugin entry **with a
-`backendRevision`** (signing the paired server module). If `backendRevision`
-is missing, the server module failed to load — check the sessiond log; the
-plugin still works fully via the terminal fallback.
+The manifest should list an `opendoor` entry **with a `backendRevision`** (signing
+the paired server module); if it is missing, the server module failed to load
+(check the sessiond log) and the plugin works fully via the terminal fallback.
+
+### Review dispatch (Pi extension)
+
+Installing the package loads the extension; enabling the PI WEB plugin is a
+separate decision. After installing or updating the package, run `/reload` in
+each idle conversation so `/opendoor-review` is registered there (an ordinary
+Pi-resource change — no provider restart). The extension needs PI WEB's
+session-dispatch bridge (1.202610.x); on an older host it reports "requires PI
+WEB's session dispatch bridge" and starts nothing.
+