@groeponline/pi-wishcraft 1.16.0 → 1.23.0

package/AGENTS.md

@@ -44,7 +44,7 @@ Each domain operates through `RuntimeState` callbacks:
 Domain modules must not import back into the hub for callbacks. Shared types and constants live in `src/extension/core/`. Verify no circular imports:
 
 ```bash
-npm run circular
+bun run circular
 # → madge --circular src index.ts bash-mode queue
 ```
 
@@ -71,29 +71,43 @@ npm run circular
 
 ## Development Commands
 
+Bun is the package manager and script runner (`packageManager: bun@1.4.2`);
+the test suite still runs on Node's own runner because two suites depend on
+`node:test` timer/PTY semantics that `bun test` does not reproduce (see
+`docs/testing.md`).
+
 ```bash
-# Install dependencies
-npm ci
+# Install dependencies (frozen lockfile)
+bun install --frozen-lockfile
 
 # Type check (strict, no emit)
-npm run typecheck
+bun run typecheck
+
+# Lint (oxlint; warnings are errors)
+bun run lint
+
+# Run all tests (node:test, coverage thresholds)
+bun run test
 
-# Run all tests
-npm test
+# Typecheck + lint + tests in one go
+bun run check
 
 # Check for circular imports
-npm run circular
+bun run circular
 
 # Full package contract verification (for publish preparation)
-npm run verify:package
+bun run verify:package
 
 # Local preview server (Deck/Signal/motion surfaces)
-npm run preview
+bun run preview
+
+# Enable the pre-commit hook (typecheck + lint + staged tests)
+bun run hooks:install
 
 # Dockerized parallel testing (typecheck + test + circular)
 scripts/docker-test.sh [-n N]
 
-# Cloud agent bootstrap (Node 24, pi CLI install)
+# Cloud agent bootstrap (bun, Node 24, pi CLI install)
 scripts/cloud-agent-install.sh
 scripts/cloud-agent-start.sh
 ```
@@ -104,7 +118,7 @@ Releases are CI-driven via GitHub Actions:
 
 ```bash
 # Locally: bump version, rewrite CHANGELOG, tag, optional push
-node scripts/release.mjs          # or: npm run release
+bun scripts/release.mjs           # or: bun run release
 
 # Publish to npm (CI handles auth)
 scripts/npm-publish.sh
@@ -114,7 +128,7 @@ scripts/github-release.sh
 ```
 
 CI workflows (`.github/workflows/`):
-- `test.yml` — Node 24, typecheck, test, circular, verify:package, npm audit
+- `test.yml` — parallel lanes (whitespace, typecheck, lint, test, circular, package-contract, audit) with a `verify` aggregator that keeps the required check name
 - `release.yml` — reuses test.yml, prepares release-candidate branch, publishes on tag, attaches `npm pack` + `SHA256SUMS`
 - `promote-release-candidate.yml` — promotes verified SHA to main, tags, dispatches publish
 
@@ -246,14 +260,16 @@ function createRuntimeState(hooks: {
 | Requirement | Detail |
 |---|---|
 | **Node** | ≥22.19 required (pi CLI floor, pinned via `engines`); Node 24 via nvm for CI and pi CLI |
-| **Package manager** | npm (lockfile v3) |
+| **Package manager** | Bun 1.4.2 (`bun.lock`, `bun install --frozen-lockfile`); the npm CLI is used only for registry operations (`npm pack`, `npm publish`, `npm dist-tag`) |
+| **Lint** | oxlint (`bun run lint`, `--deny-warnings`); config in `.oxlintrc.json`, `no-control-regex` off because ANSI SGR matching is the product |
+| **Pre-commit** | `.githooks/pre-commit` (typecheck + oxlint + staged test files), enabled with `bun run hooks:install` |
 | **TypeScript** | 5.9.3, strict mode, `NodeNext` module/resolution, `allowImportingTsExtensions`, no build step |
 | **Test runner** | Node built-in `node:test` with `--experimental-strip-types` type stripping |
-| **Circular import check** | `madge --circular src index.ts bash-mode queue` (via `npm run circular`) |
+| **Circular import check** | `madge --circular src index.ts bash-mode queue` (via `bun run circular`) |
 | **Import style** | `.ts` extensions on all imports, `node:`-prefixed builtins |
 | **Pi CLI** | Installed at `^0.99.2` (`pi-coding-agent`, `pi-ai`, `pi-tui` move together — the agent depends on matching `pi-ai`/`pi-tui`, so bumping one alone splits the tree); wrapped to run under Node 24 via nvm |
 | **Peer floor** | `peerDependencies` are `"*"` for the three Pi packages because Pi's own docs require it ("declare the host-provided packages listed above in peerDependencies with a `*` range"), and `scripts/verify-pi-package-contract.mjs` enforces it. `"*"` therefore cannot express a floor, so the real one is only enforced by the code using the SDK: `normalizeContext` (added in `pi-ai` 0.86.0, used by `src/working-vibes/provider.ts`) is the binding symbol — probed across every SDK release, all 12 runtime symbols resolve from 0.86.0 up. A consumer on 0.84.3 installs without warning, but the activation-time peer guard (`src/extension/core/peer-guard.ts`) names every missing symbol with its feature and floor, notifies at session start, and turns the `/vibe` failure into an actionable error; `tests/peer-guard.test.ts` keeps the guarded catalog in sync with the published import surface in both directions. |
-| **Dependency audit** | `npm run audit` (`scripts/audit-gate.mjs`) is the gate. `audit-baseline.json` lists accepted advisories, each pinned to its GHSA id **and** the install path(s) it covers, with a required written reason; new high/critical advisories fail even on an already-accepted package, a second vulnerable copy of an accepted package fails, a baselined advisory that stops reporting as high/critical also fails, an `npm audit` that errors out fails the gate instead of reading as "zero findings", and the baseline is excluded from the published tarball. |
+| **Dependency audit** | `bun run audit` (`scripts/audit-gate.mjs`) is the gate. `audit-baseline.json` lists accepted advisories, each pinned to its GHSA id **and** the install path(s) it covers, with a required written reason; new high/critical advisories fail even on an already-accepted package, a second vulnerable copy of an accepted package fails, a baselined advisory that stops reporting as high/critical also fails, an `npm audit` that errors out fails the gate instead of reading as "zero findings", and the baseline is excluded from the published tarball. |
 | **Docker** | `fuse-overlayfs` storage driver for nested VM testing |
 | **Compound Engineering** | `.compound-engineering/` overlay; portable skills via `~/.agents/skills/ce-*`; native Cursor plugin disabled |
 
@@ -264,7 +280,7 @@ function createRuntimeState(hooks: {
 - **Runner**: Node's built-in `node:test` (flat per-file suites)
 - **Assertions**: `node:assert/strict`
 - **Type stripping**: `--experimental-strip-types` (no `tsc` compilation in tests)
-- **Invocation**: `npm test` runs `node --experimental-strip-types --test tests/**/*.test.ts`
+- **Invocation**: `bun run test` runs `node --experimental-strip-types --test tests/**/*.test.ts` (bun owns install and script invocation; `bun test` itself is not used — see `docs/testing.md`)
 
 ### Test Organization
 
@@ -298,19 +314,23 @@ import { powerlineFooter } from "./index.ts";
 The `.github/workflows/test.yml` workflow enforces the full verification chain:
 
 ```bash
-npm run typecheck     # tsc --noEmit
-npm test              # node --test
-npm run circular      # madge --circular
-npm run verify:package # verify-package.mjs + verify-pi-package-contract.mjs
-npm audit             # security audit
+bun run typecheck      # tsc --noEmit
+bun run lint           # oxlint --deny-warnings
+bun run test           # node --test with coverage thresholds
+bun run circular       # madge --circular
+bun run verify:package # verify-package.mjs + verify-pi-package-contract.mjs
+bun run audit          # security audit gate
 ```
 
+Each gate is its own parallel job; the `verify` job aggregates them and stays
+the single required status check.
+
 ### Release Verification
 
 Before any publish, `prepublishOnly` runs the full chain:
 
 ```bash
-tsc --noEmit && verify-package.mjs && verify-pi-package-contract.mjs
+tsc --noEmit && oxlint --deny-warnings ... && verify-package.mjs && verify-pi-package-contract.mjs
 ```
 
 ### Dockerized Parallel Testing
@@ -322,3 +342,13 @@ scripts/docker-test.sh -n 4   # 4 parallel containers
 ```
 
 Each container runs `typecheck + test + circular` with a shared read-only `node_modules` bind mount.
+
+## Agent skills
+
+### Issue tracker
+
+Dual-tracker: Linear for planning/features, GitHub for bugs/triage. See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context. Current domain source: AGENTS.md. CONTEXT.md and docs/adr/ to be added via `/domain-modeling` when needed. See `docs/agents/domain.md`.

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-11-08
+
+### Fixed
+- **Releases reach npm again, with the token npm actually accepts.** Five tags — v1.18.0 through v1.22.0 — were cut but never published, so `npm install @groeponline/pi-wishcraft` still handed out 1.17.0 while the repository was at 1.22.0; the publish job of the v1.22.0 tag died with `ENEEDAUTH`. The pipeline assumed npm trusted publishing, and a probe run from this repository shows why that assumption was wrong: `id-token: write` is granted and the id token is present, but npm answers the OIDC token exchange for `@groeponline/pi-wishcraft` with **401**, so npmjs.com has no matching trusted publisher and npm fell back to "no credential at all". The `publish` job now carries the organisation `NPM_TOKEN` into `setup-node`'s `.npmrc` as `NODE_AUTH_TOKEN` (the probe confirms it authenticates as `chefgroeponline`), keeps `id-token: write` for the day the publisher is configured, and `RELEASE.md` records the measured state with the one-time npmjs.com steps to switch over. The version holes stay: npm versions need not be contiguous, so this is the first version on the registry since 1.17.0.
+
+### Changed
+- **CI can start again: every third-party action is pinned to a commit SHA.** The org policy *all actions must be pinned to a full-length commit SHA* rejects `actions/checkout@v7` at job setup, so typecheck, lint, test, circular, package-contract, whitespace and the `verify` aggregator all failed in about three seconds with `steps: 0` — which reads like broken code, not a policy. `checkout`, `setup-node`, `setup-bun` and `cache` are pinned in `test.yml`, `preview.yml`, `deprecate-old-name.yml` and the `bun-setup` composite action, and `tests/workflow-guards.test.ts` gained a third guard that fails on any third-party `uses:` without a 40-hex ref, so the next `@v7` is caught locally. The throwaway `npm-auth-probe.yml` is gone: its question is answered above. (#139)
+
+## [1.22.0] - 2026-11-05
+
+### Changed
+- **The workflow ordering rules are tested, not remembered.** Two release failures had the same shape — a job used a tool that was not set up yet, or that could not know its own context: `publish` called `bun` before `bun-setup` ran (`bun: command not found`), and `verify` called `gh workflow run` with no checkout to infer the repository from (`failed to run git: fatal: not a git repository`). `tests/workflow-guards.test.ts` now checks every workflow: a job that runs `bun` must install it first, and a job that calls `gh` without a checkout must pin `GH_REPO`. Both assertions were verified to fail against the pre-fix files. `RELEASE.md` also records that a stranded tag can only be replayed with the workflow file it was tagged with.
+
+## [1.21.0] - 2026-11-04
+
+### Fixed
+- **The publish job died with `bun: command not found` before it reached npm.** The bun migration (#128) rewrote `node scripts/verify-release-tag.mjs` to `bun scripts/...` in the `publish` job but left the `bun-setup` step below it, so v1.20.0's publish failed in its second step and never touched the registry. `bun-setup` now runs right after `setup-node` — which also satisfies the `prepublishOnly` gate `npm publish` triggers — and a test pins the order.
+
+## [1.20.0] - 2026-11-04
+
+### Fixed
+- **A verified release candidate can be promoted again.** The `verify` aggregator in `test.yml` has no checkout, so `gh workflow run promote-release-candidate.yml` could not resolve the repository and every dispatch died with `failed to run git: fatal: not a git repository` — since the parallel-CI rewrite (#128) no candidate was promoted at all, which is why `main` sat at 1.19.0 with two tags and no release. The step now pins `GH_REPO: ${{ github.repository }}`, and a test holds it there.
+- **Releases publish through npm trusted publishing, so no credential can expire.** v1.18.0 and v1.19.0 were tagged but never reached npm: the org `NPM_TOKEN` was a revoked 40-character classic token, and npm answers a PUT for a scoped package with 404 (not 403) when the caller may not publish, so the failure read like "package not found". `release.yml`'s `publish` job now grants `id-token: write` and lets the npm CLI exchange that GitHub OIDC identity for a short-lived publish token; `NPM_TOKEN` is no longer read, `scripts/npm-token-check.sh` and the `npm whoami` preflight are gone, and the manual `diagnose-npm.yml` workflow is deleted. `npm-publish.sh` drops the marker-tag + `npm dist-tag add latest` dance — it only existed to republish a version *below* `latest`, which OIDC does not cover; plain `npm publish` sets `latest` itself. Provenance attestations now come for free. `RELEASE.md` documents the one-time trusted-publisher configuration and replaces the token-rotation runbook.
+- **`RELEASE.md` describes the chain that actually runs.** The old text still promised `release.mjs auto --push` bumping and publishing in one job, a `package-lock.json` in the candidate and `npm ci` CI steps; it now documents verify → prepare candidate → Verify on the candidate ref → Promote → publish on the tag ref, with the two-file candidate (`package.json`, `CHANGELOG.md`).
+
+### Changed
+- **Bun replaces npm for the development loop.** `bun.lock` (with `packageManager: bun@1.4.2`) replaces `package-lock.json`, `bun install --frozen-lockfile` replaces `npm ci` in every workflow and bootstrap script, and the package scripts run through `bun run` (`scripts/*.mjs` execute directly, no `npx`). The npm CLI stays where the npm *registry* is the interface: `npm pack`, `npm publish`, `npm dist-tag`. The test runner stays `node:test`: measured on 1.4.2 against the 1037-test suite of that moment, `bun test` reported 1035 pass / 2 fail (fake-timer and PTY-timing divergence in two suites) while `node --test` reported 1037 pass / 0 fail, so `bun run test` invokes Node's runner and `docs/testing.md` records the measurement and the condition for revisiting it.
+- **oxlint is the lint gate.** The repository had no ESLint configuration, so this is a gate added rather than a linter swapped: `.oxlintrc.json` (correctness = error), `bun run lint` runs with `--deny-warnings`, CI fails on a single warning, and `bun run lint:fix` applies the automatic fixes. `no-control-regex` is off repo-wide because matching ANSI SGR sequences is the product. Getting to zero warnings removed 23 real findings: 21 unused imports/locals/parameters, one dead `readSkillBody()` call whose result nothing read, and one unsafe optional chain in a test assertion.
+- **CI runs in parallel.** `test.yml` is now seven independent lanes — `whitespace`, `typecheck`, `lint`, `test`, `circular`, `package-contract`, `audit` — each installing from the frozen lockfile via the `.github/actions/bun-setup` composite action, with a `verify` aggregator job that keeps the required check name and the release-candidate promotion dispatch. Pull-request runs cancel superseded pushes; release-driven candidate runs never do.
+- **Pre-commit hook.** `.githooks/pre-commit` (enable with `bun run hooks:install`) runs typecheck, oxlint and the test files the commit touches. The full suite stays CI's job.
+- **The dependency audit gate is bun-native.** `npm audit` needs `package-lock.json`, which no longer exists, so `scripts/audit-gate.mjs` reads `bun audit --json` plus `bun pm ls --all`. The guarantees are restated in bun's terms and pinned by tests: new high/critical advisories fail by GHSA id and package name, a baselined advisory whose vulnerable range moved fails, an installed version the baseline does not list fails (the "second vulnerable copy" case, now version-based instead of path-based), a baselined advisory that stops reporting as high/critical fails, and an audit that cannot run exits 2.
+- **Release candidates carry two files.** `bun.lock` stores no root version, so a bump changes exactly `package.json` and `CHANGELOG.md`; `release.mjs`, `promote-release-candidate.yml` and their tests no longer expect a lockfile rewrite. `bun install --frozen-lockfile` in the publish job proves the lock still matches the manifest.
+- `audit-baseline.json` and `.oxlintrc.json` are excluded from the published tarball; `bun.lock` never ships because `files` does not match it.
+
+## [1.19.0] - 2026-11-04
+
+### Fixed
+- **`/tps` reported near-zero averages and thousand-TPS peaks.** `pairwiseRates()` and `ratesFromRing()` treated `delta >= 0` as a rate, so every idle repaint pushed a `0` and dragged `avg` down; two samples a few ms apart straddling one token burst reported that burst as a spike. Idle deltas are now skipped (`> 0`), buckets under `TPS_MIN_PAIRWISE_DT_MS` (80 ms) are folded into the next one, and duplicate counts inside 40 ms are dropped at the door.
+- **`/tps` was empty unless the `tps` segment was in the active preset.** The ring was only filled while that segment rendered. `message_update` now samples it (`sampleTpsFromSession`, throttled to 30 ms); the segment keeps its passive sample as a fallback.
+- **Pi's own working spinner ignored `wishcraft.workingIndicatorStyle` and the motion policy.** The style was only used by status renderers. `before_agent_start` now hands Pi `ctx.ui.setWorkingIndicator({ frames, intervalMs })` once per run (Pi owns the timer, so there is no second clock), and `agent_end` restores the default. Reduced/off motion holds one frame, functional alternates two, ASCII glyph mode forces the ASCII set.
+- **Welcome overlay**: the boot reveal repainted once a second because only the countdown timer drove it; it now repaints on the same bounded heartbeat as the header, and keeps repainting while the lantern animates instead of freezing on the last frame once the reveal window closes (`revealElapsedForArt()`). The countdown timer is `unref`'d.
+- **`/tps` averaged cached prefill into the input rate and smoothed nothing.** Each turn is now measured from `agent_start` to its first new token (TTFT), the input rate counts only uncached tokens (`input - cacheRead`), and the output rate carries an EMA (α 0.32) next to the raw window rate. The `ttft` and `ema` overlay lines appear only when a turn could actually be measured; a turn whose prompt was fully cached reports `0`, not a division artefact.
+- Idea capture strips spinner noise for **every** indicator frame, not just braille, so the new native styles cannot leak into captured text. The prefix is now derived from the built-in frames *and* every Motion Catalog frame (whitespace-only rows included) at import time, so a new style cannot silently bypass it.
+- `segment-context.ts` lost its last `any`: `buildSegmentContext()` and `sampleTpsFromSession()` take a structural `SegmentSourceContext` instead of `ctx: any`, and the builder is split into `resolveContextMetrics()` / `resolveCustomItemState()` so its complexity drops below the CodeFactor threshold.
+
+### Added
+- Working-indicator styles `lantern` and `braille` (settings registry choices are now derived from `workingIndicatorStyles()` so the two cannot drift).
+- Working-indicator style `motion`: Pi's native spinner is fed from the Motion Catalog (`framesOf()` plus each definition's `generator.intervalMs`) instead of a fixed glyph set, so the working indicator moves like the motion assigned to `thinking`. It falls back to `lantern` for an unknown motion id, and reduced/off motion, functional motion and ASCII glyph mode still win over the catalog.
+- Welcome cockpit: `Tab`/`Shift+Tab` step between `What's new`, `Recent Crafts` and `Quick Launch`, ↑/↓ move inside the focused section and pause the countdown, and `Enter` (only once navigation has paused it) primes the prompt for the focused quick-launch row (`# `, `! `). Sessions stay read-only because Pi exposes no resume handle. Printable keys are still never captured: any letter dismisses, exactly as before.
+
+## [1.18.0] - 2026-11-03
+
+### Security
+- Pi peers bumped to 1.5.0 (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui` move together): undici is now 8.12.3, clearing GHSA-xjj6-f33q-929c, and the peer dropped its `npm-shrinkwrap.json`, so the two inherited brace-expansion advisories (GHSA-qhr7-859c-m2p7, GHSA-6j4f-fj2g-mc7p) resolve to the fixed 5.0.12 as well. `audit-baseline.json` is back to zero accepted entries.
+
+### Fixed
+- `before_agent_start` is a union in pi-coding-agent 1.5.0: the working-vibes prompt text now comes from `event.prompt` on user runs and from displayable custom-message content otherwise.
+
+## [1.17.0] - 2026-10-27
+
+### Fixed
+- Bash paste-while-running (issue #72): a bracketed paste performed while a command runs is stripped of its markers and forwarded to the child stdin — including split delivery across input chunks — instead of silently queuing in the editor buffer behind the command.
+- PTY/transcript memory bounds (from jan `fix/runtime-pty-bounds`): a single unterminated output line is capped at a 64 KiB UTF-8 tail with a one-time notice, the partial-escape tail is bounded, and the active transcript command trims head lines/bytes within limits instead of growing unbounded.
+- Segment-options spread hygiene (CodeFactor #86–89): `normalizeSegmentOptions` assigns fields imperatively instead of spreading conditional empty objects.
+
 ## [1.16.0] - 2026-10-03
 
 ### Known limitations

package/CONTRIBUTING.md

@@ -11,10 +11,21 @@ For PRs, keep the change narrow and include tests for behavior changes when poss
 Before opening a PR, run:
 
 ```bash
-npm test
+bun run check      # typecheck + oxlint + full test suite
 git diff --check
 ```
 
+Or enable the fast pre-commit hook once per clone — it runs typecheck, oxlint
+and only the test files you touched:
+
+```bash
+bun run hooks:install
+```
+
+Bun is the package manager (`bun install --frozen-lockfile`); the npm CLI is
+reserved for registry operations (`npm pack`/`npm publish`). The test runner
+stays Node's `node:test` — see `docs/testing.md` for why.
+
 ## Branching
 
 Trunk-based, with named prefixes. `main` is always releasable and protected; release tags are cut from it by `scripts/release.mjs`.

package/RELEASE.md

@@ -12,37 +12,48 @@ verify it.
 - **GitHub repo:** `GroepOnline/pi-wishcraft` (forked from `nicobailon/pi-powerline-footer`, independently maintained)
 - **npm package:** `@groeponline/pi-wishcraft` (scoped, `--access public`)
 - **Default branch:** `main`
-- **Local checkout:** `~/Documents/Github/GroepOnline/pi-wishcraft`
+- **Local checkout:** `/home/joep/Code/GroepOnline/pi-wishcraft/repo`
 - **Pi settings (`~/.pi/agent/settings.json`):** packages entry `npm:@groeponline/pi-wishcraft` and `"powerline": "chef"`. For active development, temporarily swap the entry to the local checkout path so edits are picked up on `/reload` — no reinstall needed; switch back to the npm name for the installed release.
 
 ## The release flow
 
-**Default:** every merge to `main` is a release. `.github/workflows/release.yml`
-runs `node scripts/release.mjs auto --push` on `main` and publishes in that
-same job (`scripts/npm-publish.sh`) with the GroepOnline org secret
-`NPM_TOKEN`, then creates a GitHub Release for the tag
-(`scripts/github-release.sh`) so the Releases page Latest matches npm. A tag
-pushed with `GITHUB_TOKEN` does **not** start another workflow, so publish
-cannot wait for the tag event. Manual SSH/PAT tag pushes still run the tag
-job. `auto` reads commit subjects since the last `v*` tag: `feat:` → minor,
+**Default:** every merge to `main` is a release, but no version is cut on the
+merge commit itself — `main` stays protected and the bump lands through a
+verified candidate.
+
+1. `verify` runs the same lanes as a PR (`.github/workflows/test.yml`).
+2. `prepare` confirms verified `main` is still the head of `main` (otherwise a
+   newer push owns the next candidate) and cuts an idempotent candidate branch
+   `release-candidate/v<next>-<base-sha12>` holding only the
+   `chore: release <next>` bump of `package.json` and `CHANGELOG.md`
+   (`bun.lock` stores no root version, so it never changes).
+3. `prepare` dispatches Verify on that exact candidate ref.
+4. The final step of that Verify run dispatches
+   `.github/workflows/promote-release-candidate.yml`, which re-validates the
+   candidate from GitHub metadata only (branch name, parent == `main`, commit
+   subject, exactly those two files, both versions, and the
+   `## [<version>] - <date>` heading), fast-forwards `main` to the candidate
+   SHA, and creates tag `v<version>` via the API.
+5. A tag created with `GITHUB_TOKEN` emits no `push` event, so Promote
+   explicitly dispatches `release.yml` on the tag ref. That run's `publish` job
+   is what publishes to npm and creates the GitHub Release.
+
+`auto` reads commit subjects since the last `v*` tag: `feat:` → minor,
 `feat!:` / `BREAKING CHANGE` → major, otherwise patch.
 
-The first merge after `v0.18.0` therefore becomes **0.19.0** (the 0.19
-`feat:` commits are already on `main`). Later docs/fix merges become
-`0.19.1`, `0.19.2`, …
-
-Put `[skip release]` in the merge-commit subject to opt out. The follow-up
-`chore: release X.Y.Z` commit does not tag again.
+Put `[skip release]` in the merge-commit subject to opt out; the follow-up
+`chore: release X.Y.Z` commit is skipped the same way. When `CHANGELOG.md` has
+no `## [Unreleased]` notes, `prepare` reports "nothing to release" and cuts no
+candidate.
 
 Manual still works when you want an explicit version before pushing tags:
 
 ```bash
-# 1. Make sure the working tree is clean and tests/typecheck pass (see Verification)
-npm run typecheck        # tsc --noEmit
-npm test                 # node --experimental-strip-types --test tests/**/*.test.ts
+# 1. Make sure the working tree is clean and the full chain passes (see Verification)
+bun run check            # typecheck + oxlint + tests
 
 # 2. Release (patch | minor | major | auto | explicit 1.2.3)
-npm run release minor    # = node scripts/release.mjs minor
+bun run release minor    # = bun scripts/release.mjs minor
 ```
 
 `scripts/release.mjs` (zero deps, node built-ins only) does:
@@ -53,8 +64,9 @@ npm run release minor    # = node scripts/release.mjs minor
 4. `git commit -m "chore: release <version>"`
 5. `git tag -a v<version> -m "Release <version>"`
 
-Locally it does **not** push unless you pass `--push` (CI does). Manual push
-uses the GroepOnline SSH identity (the laptop default SSH key is denied):
+Locally it does **not** push unless you pass `--push` (CI does not use `--push`
+anymore: `prepare` pushes only the candidate branch). Manual push uses the
+GroepOnline SSH identity (the laptop default SSH key is denied):
 
 ```bash
 GIT_SSH_COMMAND='ssh -F ~/.ssh/config-groeponline -o IdentityFile=~/.ssh/sheesh' \
@@ -64,28 +76,107 @@ GIT_SSH_COMMAND='ssh -F ~/.ssh/config-groeponline -o IdentityFile=~/.ssh/sheesh'
 - SSH host alias: `github.com-groeponline` (defined in `~/.ssh/config-groeponline` with `IdentityFile ~/.ssh/sheesh`, `IdentitiesOnly yes`).
 - Push actor: `chefadmin-netizen` (GroepOnline SSH). API/`gh` actor: `MisterWanted` (FG) via `chef-gh`.
 
-## CI publish
-
-`.github/workflows/release.yml` publishes from the **bump job** after tagging,
-and also from a tag push (manual SSH/PAT). `GITHUB_TOKEN` tag pushes do not
-start a second run.
-
-1. `actions/checkout@v4` (`fetch-depth: 0`, `fetch-tags: true`)
-2. `actions/setup-node@v4` (node 24, `registry-url: https://registry.npmjs.org`)
-3. Fetch and `git reset --hard origin/main` (bump job only; tests the tree that will be tagged)
-4. `npm ci --ignore-scripts` (installs devDependencies incl. `typescript`)
-5. `npm run typecheck` (tsc)
-6. `npm test` (node test runner)
-7. `npm run verify:package` (catalog contract gate — see `scripts/verify-package.mjs`)
-8. `node scripts/release.mjs auto --push` (main only)
-9. `sh scripts/npm-publish.sh` with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` (fail-closed `npm view`, idempotent skip, then the Pi catalog URLs)
-10. `sh scripts/github-release.sh` with `GITHUB_TOKEN` (idempotent: skip if that tag already has a Release; notes from `CHANGELOG.md`)
-
-`NPM_TOKEN` is the GroepOnline **org** Actions secret (publish rights to the
-`@groeponline` scope). This repo has no override; Actions inherits the org
-value. It is **not** readable after being set; verify it works by checking
-that the publish step on a real release succeeds and `npm view` resolves the
-new version (see below). The publish step fails closed if the secret is empty.
+## CI publish (tag ref only)
+
+`release.yml`'s `publish` job runs only when `github.ref` is a `v*` tag: the
+dispatch Promote fires, or a manual SSH/PAT tag push. It never runs on `main`.
+
+1. `actions/checkout` at the tag (`fetch-depth: 0`)
+2. `actions/setup-node` (node 24)
+3. Stamp `PI_WISHCRAFT_BUILD_SHA` and `build-stamp.json` from the tag commit only
+4. `bun scripts/verify-release-tag.mjs --tag <tag>` (tag == `package.json`, on `origin/main`)
+5. `bun install --frozen-lockfile --ignore-scripts` (devDependencies incl. `typescript`)
+6. `sh scripts/npm-publish.sh` (fail-closed `npm view`, idempotent skip, `npm publish --access public`)
+7. `sh scripts/github-release.sh` with `GITHUB_TOKEN` (idempotent: skip if that tag already has a Release; notes from `CHANGELOG.md`)
+8. `npm pack` + `SHA256SUMS`, uploaded as a run artifact and attached to the GitHub Release
+
+The lanes that need to prove the tree (typecheck, lint, tests, package contract)
+live in `test.yml` and run in `verify` — the tag commit already passed them as a
+candidate, so `publish` does not repeat them.
+
+## npm authentication: the org `NPM_TOKEN`, with trusted publishing prepared
+
+`release.yml` publishes with the organisation secret **`NPM_TOKEN`** (a classic
+token for the `chefgroeponline` account). `setup-node` writes it into `~/.npmrc`
+through `NODE_AUTH_TOKEN`, so the value lives only in the org secret store: not
+in the repo, not in a dispatch input, never printed by a run.
+
+Trusted publishing (OIDC) is wired but **not active**. The `publish` job still
+grants `id-token: write`, but npm answers the OIDC exchange for
+`@groeponline/pi-wishcraft` with **HTTP 401**, so npmjs.com carries no matching
+GitHub Actions publisher for this repo. With no publisher and no token, npm
+reports `ENEEDAUTH` — that is what kept v1.18.0–v1.22.0 off the registry.
+Measured from this repository on 2026-11-08:
+
+| probe | result |
+|---|---|
+| `npm whoami` with `secrets.NPM_TOKEN` | `chefgroeponline` — valid |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` in a job with `id-token: write` | present |
+| `POST /-/npm/v1/oidc/token/exchange/package/@groeponline%2fpi-wishcraft` | **401** |
+
+Two consequences: publishes carry no provenance attestation, and the token has
+to be replaced by hand when it expires. Switching to trusted publishing is a
+one-time npmjs.com change, after which the `NODE_AUTH_TOKEN` env comes out of
+the job:
+
+1. Sign in as the maintainer of `@groeponline/pi-wishcraft` (`chefgroeponline
+   <joep@chefgroep.online>` — `npm view @groeponline/pi-wishcraft maintainers`).
+2. Package → Settings → **Trusted publishing** → add a **GitHub Actions**
+   publisher with exactly these values (all fields case-sensitive):
+   - Organization or user: `GroepOnline`
+   - Repository: `pi-wishcraft`
+   - Workflow filename: `release.yml` (with `.yml`)
+   - Environment name: empty
+   - Allowed actions: **tick `npm publish`** — it is *not* on by default. A
+     configuration created after 2026-09-03 starts with staged publishing only,
+     so without this tick every `npm publish` is refused. Leave `npm dist-tag`
+     off; this repo does not use it.
+3. Verify before trusting it: the exchange line in the table above must answer
+   `200`, not `401`. Only then remove `NODE_AUTH_TOKEN` from the job and let OIDC
+   publish.
+
+Rules that follow from the current (token) configuration:
+
+- The credential must stay in the `publish` job of `release.yml`. Moving
+  `npm publish` into a reusable workflow (`workflow_call`) would break the OIDC
+  match if trusted publishing is switched on later, because npm validates the
+  *calling* workflow's filename.
+- Only GitHub-hosted runners can use OIDC; the token path works anywhere.
+- `npm-publish.sh` publishes with the default `latest` dist-tag, and versions
+  only ever increase here, so `npm dist-tag` is deliberately never used.
+
+### When publish fails: `E404 Not Found - PUT .../@groeponline%2fpi-wishcraft`
+
+For a scoped package npm answers a PUT with **404, not 403**, when the caller
+may not publish. That means the credential is missing, revoked, read-only or
+(`EOTP`) 2FA-blocked, or does not own the scope. It is not "package not found",
+and it is not a retryable transient. `ENEEDAUTH` instead means npm had no
+credential at all: `NODE_AUTH_TOKEN` was empty and the OIDC exchange refused.
+
+`scripts/npm-publish.sh` prints that diagnosis instead of the raw 404. Recovery:
+
+1. Check the credential before the workflow: `npm whoami` against the registry
+   with the same token, or rerun the exchange probe from the table above.
+2. Republish the tags that failed, without cutting new versions. A bare
+   dispatch on a `v*` tag ref runs verify + publish for that tag:
+
+   ```bash
+   gh workflow run release.yml --ref v1.19.0   # repeats for each failed tag
+   ```
+
+   Or re-run the failed job directly: `gh run rerun <run-id> --failed`.
+   A tag stranded this way keeps its GitHub Release missing until the publish
+   run succeeds; `workflow_dispatch` with `inputs.tag` only backfills the
+   release assets and never publishes to npm.
+3. A dispatch runs the workflow file **at that tag**, so a tag whose publish job
+   is broken by construction cannot be replayed at all: publish the newer tag
+   that carries the fix and leave the version hole, since npm versions need not
+   be contiguous. v1.20.0 is such a hole — it was tagged by a publish job that
+   called `bun` before installing it.
+
+The idempotent skip in `npm-publish.sh` makes a retry safe: a version that is
+already on the registry is skipped, so a partially successful run cannot
+double-publish.
 
 The package has no build step — `*.ts` files are shipped directly (`pi.extensions:
 ["./index.ts"]`), and Pi loads them with TypeScript stripping at runtime.
@@ -96,8 +187,8 @@ After a release, confirm each layer. Example for `0.15.0`:
 
 ```bash
 # 1. Local: typecheck + tests green BEFORE tagging
-npm run typecheck        # exit 0
-npm test                 # "ℹ pass 170", "ℹ fail 0"
+bun run typecheck        # exit 0
+bun run test             # "ℹ pass 170", "ℹ fail 0"
 
 # 2. Tag pushed
 git ls-remote --tags origin | grep v0.15.0   # shows v0.15.0 on origin
@@ -142,13 +233,15 @@ is that same tag.
 
 ## Versioning
 
-Feature PRs **do not bump** `package.json`. They stay on the last published npm
-version (today: `0.19.0`) and append under `## [Unreleased]` in `CHANGELOG.md`.
+Feature PRs **do not bump** `package.json`. They inherit whatever version
+`main` already carries and append under `## [Unreleased]` in `CHANGELOG.md`.
 The bump happens on `main` in the release workflow, not in the feature PR.
 
 Never bump in the same PR as the feature work. Never tag from a stacked
-feature branch. `0.19.0` exists only after `main` auto-tags (or a manual
-`npm run release` on `main`).
+feature branch. `v<version>` exists only after Promote tags the verified
+candidate (or a manual `bun run release` on `main`). `main` can be ahead of npm
+when a publish fails — compare `npm view @groeponline/pi-wishcraft version`
+with `bun scripts/release.mjs next auto` before assuming they agree.
 
 - **patch** (`0.18.0 → 0.18.1`): bug fixes, doc only; escape hatch if 0.19 slips.
 - **minor** (`0.18.x → 0.19.0`): new segments/presets, features, additive changes.

package/bash-mode/completion.ts

@@ -1,7 +1,7 @@
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from "@earendil-works/pi-tui";
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
 import { matchHistoryEntries, readGlobalShellHistory, readProjectHistory } from "./history.ts";
 import type { ExtendedCompletionItem, GhostSuggestion } from "./types.ts";
 
@@ -365,7 +365,7 @@ function boostValidatedItemsFromGlobalHistory(
 }
 
 export class BashCompletionEngine {
-  async getGhostSuggestion(line: string, cwd: string, shellPath: string, signal: AbortSignal): Promise<GhostSuggestion | null> {
+  async getGhostSuggestion(line: string, cwd: string, shellPath: string, _signal: AbortSignal): Promise<GhostSuggestion | null> {
     const projectHistoryEntries = readProjectHistory(cwd);
 
     if (line.trim().length === 0) {

package/build-stamp.json

@@ -1 +1 @@
-{"source_sha":"1957ea6e4334e28e25770cba4114e33c69062632"}
+{"source_sha":"a12a4900dbbf32823e1c2c6261c850eb21834d38"}

package/docs/agents/domain.md

@@ -0,0 +1,60 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`AGENTS.md`** at the repo root — the current domain documentation source with architecture, data flow, and conventions.
+- **`CONTEXT.md`** at the repo root, if it exists (currently absent).
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If `CONTEXT.md` or `docs/adr/` don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (this repo):
+
+**Current state:**
+- `AGENTS.md` — Primary domain documentation (architecture, data flow, conventions)
+- `docs/` — Operator guides and design specs (no ADRs currently)
+- `CONTEXT.md` — Not yet created (add via `/domain-modeling` when needed)
+
+**Target state (when CONTEXT.md exists):**
+
+```
+/
+├── AGENTS.md
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `AGENTS.md` (current domain source) or `CONTEXT.md` (if it exists). Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_