@guillaumemeyer/dsh-plan-approval 0.1.8 → 0.1.10

package/README.md

@@ -9,7 +9,7 @@ review contract.
 
 ## Features
 
-- **Fullscreen review** in the frame-wide `shell.overlay` layer, now at **90vw × 90vh**.
+- **Fullscreen review** in the frame-wide `shell.overlay` layer, at **90vw × 90vh**.
 - **Line navigation** (vim-style): `j`/`k` move line-by-line, `gg` jump to top,
   `G` (Shift+g) jump to bottom, with a straight left highlight on the cursor line
   that auto-scrolls.
@@ -24,30 +24,83 @@ review contract.
 - **Actions**: `a` approve · `s` request changes · `y` copy plan · `q` quit plan.
 - A bottom **status line** lists every keyboard shortcut.
 
-## Install
-
-Install the package into the DSH deployment:
-
-```sh
-npm i @guillaumemeyer/dsh-plan-approval
-```
-
-Then add one row to the **web surface (browser roster)** composition — e.g. the
-deployment's `cordis.patch.yml` / web `cordis.yml`, alongside other `dsh.client`
-browser roster rows:
-
-```yaml
-- id: ui-plan-approval
-  name: '@guillaumemeyer/dsh-plan-approval'
-```
-
-Restart the DSH host. The modules node half re-scans loader entries, bundles
-`/plugins/@guillaumemeyer/dsh-plan-approval/client.js`, and the overlay
-appears on the next plan review.
-
-> The row must live in the **web-surface `dsh.client` roster** (a `dsh.client`
-> platform-`web` package). Placing it in an agent preset or a non-web composition
-> will not be scanned into `window.__DSH_BOOT__`.
+## Install (into a DSH deployment)
+
+This is a `dsh.client` browser plugin, so it must be installed and mounted where DSH
+composes its **web surface** (host/web composition), then the host restarted so the
+client-modules node half produces the bundle.
+
+1. **Install the package** into the DSH deployment's web app:
+
+   ```sh
+   npm i @guillaumemeyer/dsh-plan-approval
+   ```
+
+2. **Find the web-surface (browser roster) composition.** This is the `cordis.yml` /
+   `cordis.patch.yml` in the DSH web app that lists the other browser roster rows
+   (`ui-plan`, `ui-user-questions`, `ui-tool`, …). (The shipped `@deepseek-ai/dsh-web-app`
+   `cordis.patch.yml` is the reference for this "browser plugin roster" section.)
+
+3. **Add one row** to that roster:
+
+   ```yaml
+   - id: ui-plan-approval
+     name: '@guillaumemeyer/dsh-plan-approval'
+   ```
+
+4. **Restart the DSH host.** The `@deepseek-ai/dsh-client-modules` node half re-scans
+   loader entries for packages declaring `dsh.client`, bundles
+   `/plugins/@guillaumemeyer/dsh-plan-approval/client.js`, and the browser loads it.
+   (With a `pnpm run dev:web` watcher, the bundle is rebuilt automatically without a
+   restart; in a production/built deployment a host restart is required.)
+
+> The row **must** live in the **web-surface `dsh.client` roster** (a
+> `dsh.client` `platform: "web"` package). Placing it in an agent preset or a
+> non-web composition will **not** be scanned into `window.__DSH_BOOT__`.
+
+### Verify it's mounted
+
+After restart, the package's browser bundle is served under
+`/plugins/@guillaumemeyer/dsh-plan-approval/client.js`, and the plugin appears in the
+`shell.overlay` slot.
+
+## Use it from DSH
+
+1. **Enter plan mode** — switch the agent into plan mode (the `/plan` command or the
+   session's plan control) and ask it to plan.
+2. **Present a plan** — when the agent has the plan, it calls `exit_plan_mode` with the
+   plan markdown. The full-screen review overlay opens automatically.
+3. **Review the plan**:
+   - **Navigate**: `j`/`k` move the cursor line, `gg` jump to top, `G` (Shift+g) jump to
+     bottom; the plan auto-scrolls to follow the cursor.
+   - **Search**: `/` opens the search bar — type to highlight matches, `Enter`/`n` to
+     the next match, `N` (Shift+n) to the previous, `Esc` to close.
+   - **Comment**: `c` (or **click** any line) anchors an inline comment to that line;
+     type it and press `Enter` to add (`Esc` to cancel). Comments show as inline chips.
+   - **Copy**: `y` copies the plan, including any inline comments (the merged plan).
+4. **Decide**:
+   - `a` **approve** the plan.
+   - `s` **request changes** — the feedback box opens; submit your requested changes
+     (plus any inline comments) → the agent keeps planning and revises the plan.
+   - `q` **quit plan** — cancel the review and go talk instead.
+
+The status line at the bottom shows every shortcut: `a approve · s changes · c comment ·
+y copy · q quit · j/k move · gg/G ends · / search`.
+
+### Keyboard shortcuts
+
+| Key | Action |
+| --- | --- |
+| `a` | Approve the plan |
+| `s` | Request changes (opens feedback box; `Enter` submits) |
+| `c` | Add an inline comment at the current line (`Enter` add, `Esc` cancel) |
+| `y` | Copy the plan (merged with comments) |
+| `q` | Quit / cancel the plan review |
+| `j` / `k` | Move the cursor down / up one line |
+| `gg` | Jump to top |
+| `G` (Shift+g) | Jump to bottom |
+| `/` | Open search (type to highlight; `Enter`/`n` next, `N` prev, `Esc` close) |
+| `Esc` | Close the search/comment box, otherwise quit |
 
 ## How the review answers map
 
@@ -84,6 +137,23 @@ plus include it in the result `render` so the model sees the comments after appr
 This requires a host restart to take effect, and is a change to a shipped package that
 an upgrade would overwrite — ideally upstream it.
 
+## Publishing updates
+
+To publish a new version, ensure a local `.env` (untracked) holds your npm token, then:
+
+```sh
+cp .env.example .env   # once: edit to add NPM_TOKEN=...
+npm run release        # runs publish:check (preversion), bumps patch, publishes to npm
+```
+
+- The token is read from `.env` and referenced by the committed `.npmrc` via `${NPM_TOKEN}`,
+  so it is never tracked.
+- `preversion` runs `node --check client.js && npm pack --dry-run` automatically before
+  the version bump.
+- The script is named `release` because `publish` is a reserved npm lifecycle name: npm
+  auto-runs a `publish` script during `npm publish`. Naming it `publish` made `npm publish`
+  re-run the script, bumping and publishing a version on every loop.
+
 ## Notes
 
 - Client-only browser plugin; the node half (`index.js`) is an empty `apply`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaumemeyer/dsh-plan-approval",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Fullscreen, Grok-Build-style DSH plan-review overlay with vim navigation, inline search, inline comments, and comment integration into the plan.",
   "type": "module",
   "main": "index.js",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "scripts": {
-    "publish": "node scripts/publish.mjs",
+    "release": "node scripts/publish.mjs",
     "publish:dry": "npm pack --dry-run",
     "publish:check": "node --check client.js && npm pack --dry-run",
     "preversion": "npm run publish:check"