@groeponline/pi-wishcraft 1.13.0 → 1.14.0

package/AGENTS.md

@@ -52,7 +52,7 @@ npm run circular
 
 | Directory | Purpose |
 |---|---|
-| `src/` | Extension runtime, organized by domain (core, config, segments, render, signal, motion, theme, welcome, working-vibes, usage, studio, skills, hooks, settings, shortcuts, history, queue, contrib) |
+| `src/` | Extension runtime, organized by domain (core, config, segments, render, signal, motion, theme, welcome, working-vibes, usage, studio, skills, hooks, settings, shortcuts, history, queue, contrib, editor, paths, shell, tools, i18n) |
 | `src/extension/` | Pi extension runtime: `core/` (hub, types, constants), `session/` (activation, lifecycle), `ui/` (deck, layout), `commands/`, `shortcuts/`, `queue/`, `welcome/`, `skills/`, `hooks/`, `settings/`, `history/`, `contrib/` |
 | `src/config/` | Powerline config parsing, presets, settings registry, tokens |
 | `src/segments/` | Segment registry and builtin renderers (core, system, usage, custom) |
@@ -245,7 +245,7 @@ function createRuntimeState(hooks: {
 
 | Requirement | Detail |
 |---|---|
-| **Node** | v22.14 system default; Node 24 via nvm for CI and pi CLI (pi requires ≥22.19) |
+| **Node** | ≥22.19 required (pi CLI floor, pinned via `engines`); Node 24 via nvm for CI and pi CLI |
 | **Package manager** | npm (lockfile v3) |
 | **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 |

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-10-01
+
+### Added
+- **Configure from the prompt**: `/wishcraft get|set|unset <setting>` — every registered setting is readable and writable from the pi CLI, no editor involved. `get` reports stored value → owning file (project/global/default) → effective value, with a ⚠ explanation when validation discards it. `set` validates against the same registry the settings TUI and wizard use (unique choice prefixes: `set motion.level red` → `reduced`; toggles take `on`/`off`; numbers checked against declared `min`/`max`), applies immediately (status line repaints; shortcuts/bash settings after `/reload`), and writes to the file that already owns the key. `unset` (alias `reset`) returns to the default. Tab completes subcommands, all registered paths, and each setting's values. Structured values (layout, segments, policy) are refused with a pointer to settings.json rather than written in a broken shape; `get` works even with Signal disabled.
+- Settings registry +19 entries and a new **Shell & bash mode** group: the whole `bashMode.*` surface (toggle shortcut, transcript max lines/bytes, init script), the four missing `powerlineShortcuts` bindings (`copyEditor`, `cutEditor`, `editorStart`, `editorEnd`), `powerline.costAlert`, `powerline.stashSharpSShortcut`, `powerline.customItemsAuto`, `powerline.queue.retentionHours`, `wishcraft.policyEnabled`, git segment toggles (branch/staged/unstaged/untracked/polling/commit length), model segment options (thinking level, name style), and the fleet `openPorts.host`. All of them are now editable in `/wishcraft settings`, validated by the doctor, and covered by NL translations.
+- **Deck → Ports route** (`g p`, twelfth route): the same open-ports table `alt+i` shows, probed asynchronously off the render path and read from a shared 5s cache, so the route never spawns a process during a frame.
+- **Open-ports panel rebuild** (`alt+i`): leads with a summary (`21 tcp · 12 exposed · 9 loopback · local`), renders aligned `PROTO PORT ADDRESS OWNER` rows instead of raw `ss` output, filters as you type on port/address/owner, `r` re-probes, Enter copies the selected row, and fails soft with a readable reason instead of an error toast. Used by `alt+i`, the classic menu and the new Deck route.
+- Shared listening-ports parser (`src/segments/ports.ts`): one parse of `ss`/`netstat` output feeds the segment count, the segment detail, the panel and the Deck route, so they can no longer disagree. Dual-stack binds collapse to one row, IPv6 brackets are stripped (an `[::1]` bind previously would have been reported as *exposed*), and `ss`/`netstat`/macOS dotted-address variants are all handled. The pure parsing half (`ports-parse.ts`) and the `/proc/net` fallback (`ports-proc.ts`) are separate modules, so the render path has no synchronous filesystem or process access at all.
+- **Deck idea actions**: `enter` cycles the review status (idea → in-progress → done) and `d` removes the idea, straight from the Ideas route — the same states the `/ideas` overlay offers.
+- `/` now filters the Ideas list in place (it already filtered skills, appearance and motion).
+- Interface language: a new `Language` setting (`wishcraft.locale`, `en` | `nl`) localises the operator UI — Deck routes and chrome, the settings registry's labels/hints/group titles, the configuration overlay, the welcome overlay and its widgets, the setup wizard, and the diagnostics copy. English is compiled in at each call site (`tr(key, "English")`), so a missing or unknown locale can only ever fall back to English, never blank a surface; the default stays `en` and no existing golden output changes.
+- `/wishcraft setup` — first-run wizard: four questions (language, status preset, motion level, welcome overlay), a review screen, then one write to `settings.json`. The step model is pure and separately tested.
+- `/wishcraft doctor` — configuration diagnosis as a one-screen list, also rendered as a section of the Deck's Diagnostics route: which settings file is winning, values shadowed between global and project, near-miss keys with a "did you mean" suggestion, and every stored value that validation throws away — with an explanation of why and which default applies.
+- Live status-line preview inside the configuration overlay: every toggle/cycle/edit repaints the real status line under the list, so a setting's effect is visible instead of inferred.
+- Per-setting inline warning markers and contextual hints in the configuration overlay: an invalid stored value is flagged in place rather than silently replaced by its default.
+- Settings validation now reports *why* a value is rejected (`explainSettingValue`, `validationProblem`) with localised, actionable copy — including the valid choices and the default that is applied — instead of a bare boolean. Numeric settings gained declared `min`/`max` bounds.
+- First-run welcome: an operator who has never run Wishcraft sees three short next steps under a "Getting started" heading instead of a wall of changelog bullets; later sessions keep the changelog delta under its own heading.
+- **Hot-path regression guard** (`tests/hot-path-contract.test.ts`): the suite now walks the import graph from `src/render/v2-entry.ts` and fails if any reachable module makes a synchronous process spawn (`execSync`/`spawnSync`/`execFileSync`), plus a stricter sweep of all of `src/segments/` and `src/extension/ui/`. Synchronous filesystem reads on the paint path are allowed only via a named allowlist carrying a justification, so a new one has to be argued for rather than slipped in. The assertions are structural, so a blocking call hidden three layers behind helper modules still fails.
+- Coverage gate in CI and local `npm test`: the suite fails below 70% line / 60% function coverage (current baseline 84.7% / 82.6%), so coverage can no longer silently regress.
+- Release-path contract tests: `scripts/release.mjs` (semver bump, `[skip release]` guard, org bump policy, tag parsing/collisions, CHANGELOG roll and note extraction, lockfile rewrite, release-candidate metadata validation incl. every rejection path) and `scripts/verify-release-tag.mjs` (version sources, tag equality, argument parsing) — previously the least-covered, most operationally critical files in the repo.
+- Extension-layer tests: prompt-history (trim/dedupe/cap, snapshot/restore, tracker idempotence, session-JSONL parsing via `PI_CODING_AGENT_DIR` fixture), stash-history (normalize/push/preview semantics), shortcuts router (per-binding action resolution incl. kitty CSI-u forms and release filtering), bash-mode actions (shell path/cwd/history-merge), and stash shortcuts.
+- OMP-style boot reveal: the welcome header and startup overlay fade their art up from a faint ember over the first ~1.5s after mount (logarithmic ramp on a 90ms heartbeat, ember-noise flicker while catching), then settle into the steady layout — a bounded one-shot, zero timers afterwards. `WelcomeHeader`/`WelcomeComponent` arm it via `armBootReveal()`; pure frames via `renderWelcomeArtWithReveal`.
+- Settings appearance preview: the Deck's Appearance route now renders a live signal-rail preview of the structural preset under the cursor (the preset's own signal spec and animation, one row, deterministic per tick), so you see each base before Enter applies it.
+
+### Fixed
+- **CI and the release pipeline were silently dead.** A step name edited to `- name: Unit tests (coverage threshold: 70% lines / 60% functions)` contains an unquoted `: ` inside a plain YAML scalar, which YAML reads as a nested mapping — `.github/workflows/test.yml` became unparseable. GitHub's only signal is a run that fails in 0s with zero jobs and no logs, and because `release.yml` calls `test.yml` via `workflow_call`, the whole release pipeline failed the same way. The scalar is now quoted, all five workflows parse, and `tests/workflow-yaml.test.ts` fails locally — with a file:line reference — on any unquoted colon-space in a step scalar.
+- **Icon and colour resolution did synchronous filesystem work ~19x per paint.** `getIcons()` is called once per segment that renders an icon, and every call re-walked up to six parent directories looking for a `package.json` and then `statSync`'d each candidate `theme.json` — on the order of 170 blocking syscalls per frame while streaming. The package root is now resolved once per process and the icon set is memoised on the config object identity, cutting a paint's theme work by ~28% (61µs → 44µs per `getIcons()` call). The mtime identity check is deliberately kept *before* the TTL, so editing `theme.json` still lands on the very next paint rather than after the cache window.
+- **The status line could still spawn `ss` from a paint.** `open_ports` and its detail view each ran their own `execSync` with a 3s timeout, duplicating a ladder `src/segments/ports.ts` already owned — a violation of the package's own hot-path contract. Both now read the shared async probe cache (`readPorts()`), serve the last known value, schedule a background refresh, and repaint through a new `subscribePortsUpdates` listener. A stale-but-known count no longer flickers to `?`, and the status line has no blocking process spawn left on it at all. The `/proc/net` fallback moved into the async ladder too (with kernel hex addresses decoded, so an IPv6 loopback bind no longer reads as externally reachable).
+- **User-defined command segments ran `execSync` on every paint** — a custom `{"type": "command"}` segment without `cacheMs` respawned a shell every ~33ms, and one that hung blocked the event loop for up to 5s per paint. Command output now runs in the background behind a defaulted (1000ms) and clamped (100ms–300000ms) cache window, output is capped at 512 characters, the segment serves its last value while a refresh runs, and a repaint is requested when new output arrives. A failing command still surfaces as `!custom:<id>`, one frame later.
+- **`/open-ports` ran `execSync("ss")` with no timeout** — the last remaining copy of the old ports implementation — so a wedged `ss` could still freeze the whole TUI from the command line while the `alt+i` panel was already async. The command now opens the shared panel (bounded probe, parsed table, filter, `r` refresh).
+- **Toggling the ports UDP flag published a stale count**: the toggle changed the probe key, so the synchronous read had nothing cached and exported `?` until an unrelated render happened to refresh. It now awaits the probe before publishing.
+- **Configuration diagnosed as typos**: `wishcraft.hooks`, `wishcraft.policy` and the four editor shortcuts (`powerlineShortcuts.copyEditor`/`cutEditor`/`editorStart`/`editorEnd`) were reported by `/wishcraft doctor` as "no reader consumes this key" although every one of them has a live reader — the registry is the known-set, and they had no entry. The doctor now reads structured roots (`hooks`, `policy`) as known, and the shortcut entries come from the registry itself.
+- **`bashMode` conflicts were invisible**: the root was not managed, so global-vs-project divergence (e.g. different `transcriptMaxLines`) was never reported and typos under it never flagged. `bashMode` is now a managed root with its four known keys.
+- **Ports panel ignored its own segment config**: `alt+i` and `/open-ports` always probed TCP-local even when `powerline.segmentOptions.openPorts` set `includeUdp`/`host`, so the panel and the status segment could disagree about what they were counting. Options now default from the config with explicit overrides still winning.
+- **Settings edited from `/wishcraft settings` did nothing.** Every `status.*` setting writes to `powerline.segmentOptions.<segment>.<option>`, but `parsePowerlineConfig` only ever read the hand-edited top-level buckets (`powerline.tps.*`, `powerline.path.*`, …). A dozen settings — path mode and max length, time format/seconds, git host icons/ahead-behind/latest commit, context format, cache-read format, cost display/currency, UDP ports, TPS window/mode/label — were persisted and then silently ignored. The parser now merges both shapes per segment (nested wins), so the settings UI, hand-edited configs, and the menu's `openPorts` toggle all agree.
+- The coverage gate was not actually enforcing anything: `--test-coverage-lines`/`--test-coverage-functions` do nothing without `--experimental-test-coverage`, so `npm test` printed thresholds while collecting no coverage. The flag is now part of the script and a deliberately impossible threshold demonstrably fails the run.
+- `tr()` did not interpolate its English fallback, so the default locale printed raw `{route}` placeholders in Deck headings.
+- Dutch catalog drift: two message keys referenced from the configuration overlay had differently-named entries, and several entries had no caller.
+- Shortcuts router: a missing `ctx.ui` crashed `getCurrentEditorText` with a TypeError; the accessor now falls through safely to the editor text or an empty string.
+
+### Changed
+- The configuration overlay's three duplicated persist-and-notify blocks (typed edit, choice cycle, toggle) collapsed into one `persist` path, so locale sync, powerline reload and the save/failure toast can no longer drift apart between edit modes.
+- Motion engine (Mijlpaal B1): sub-tick interpolation — repaints between scheduler heartbeats move the travelling head smoothly instead of stepping one cell per tick. `SignalRuntime` records the heartbeat clock (`lastTickAt`) and `renderActivity` interpolates strictly within one interval, so hand-driven ticks (tests) and stale clocks keep exact integer rendering. Glyph frames stay tick-aligned via a fractional-safe `frameAt`.
+- Shared sweep geometry (`src/motion/sweep-cells.ts`): the status rail, gallery preview strip and composer preview now resolve head/trail/track cells through one `buildSweepCells` builder, so the gallery previews exactly what the rail paints. Rendered output is byte-identical to the previous inline loops (pinned by goldens).
+- Compact rail heads round to whole cells under fractional ticks; lab rails (fat-band) floor fractional ticks before painting.
+- Motion craft (Mijlpaal B2) — same surfaces, richer rendering, no new features or catalog entries:
+  - The travelling wake now rides a perceptual multi-stop ramp (hot → warm → cool → track) mixed in **Oklab** space, instead of a naive two-stop sRGB lerp that rendered muddy midpoints. The cool stop is derived by rotating the warm hue and dipping lightness, so every palette cools credibly without hardcoding a blue; a test pins that wake lightness falls strictly monotonically. Trail brightness decays with an ease-out glow falloff, so the wake cools like embers instead of stepping through tiers.
+  - wave/heat/liquid generator geometries render their wake as a rippling braille sub-cell curve (2×4 dot matrix per cell, still exactly one column) instead of four flat glyph steps; the gallery previews the same curve.
+  - Terminal events (success/warning/error) play a one-shot expanding ripple — two fading rings from the rail center — instead of a plain sweep; finite loop, zero frames once settled.
+  - Every event switch lands with an ignition punch (fast exponential brightness decay from `startedAt`).
+  - Ember/heat heads flicker with layered deterministic value noise (slow breathe + fast crackle, never repeats exactly) instead of two fixed sines.
+- **The Deck frame is bounded**: the center pane and right rail clip at a fixed row budget with an overflow count, and Ideas/Guardrails window around the cursor. A long queue or a large policy list previously grew the box past the bottom of the terminal.
+- **Right rail is now a decision aid**: leads with the latest activity, shows workload (ideas/queue, bash) and only spends space on an **ATTENTION** block when something is actually wrong (skill warnings, guardrails off, context ≥ 90%).
+- Deck home route body reworked into four scannable blocks — session (activity, context bar, look), right now (ideas/queue, bash and policy state, shell), next intent, and quick keys — instead of a thin session stub.
+- Welcome startup: skill/extension/session discovery now happens inside the overlay's delay instead of on the session-start critical path, and the panel heading/bullets resolve through one helper.
+- Deck copy is localised: route descriptions, body headings, list headers, alerts and the per-route footer hints now resolve through `tr()`, keeping their English wording as the fallback.
+- `sanitizeSshHost`/`sshCommand` moved to `src/segments/probe-shell.ts` (re-exported from `segments/system.ts`) so the ports parser and the segments can share them without an import cycle.
+- Dotted setting-path helpers moved to `src/extension/settings/config-paths.ts` so the wizard and diagnostics can share them without importing the overlay (keeps the dependency graph acyclic).
+- Housekeeping: removed the stray `bun.lock` (npm is the package manager of record), added `engines: node >=22.19` to `package.json`, untracked the local harness log `.auto/log.jsonl`, and corrected the Node-version line and `src/` directory list in AGENTS.md.
+
 ## [1.13.0] - 2026-09-25
 
 ### Added

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/GroepOnline/pi-wishcraft/main/banner.png" alt="Pi Wishcraft" width="100%">
+  <img src="https://raw.githubusercontent.com/GroepOnline/pi-wishcraft/main/banner.png" alt="Pi Wishcraft — operator cockpit for the Pi coding agent" width="100%">
 </p>
 
 <h1 align="center">Pi Wishcraft</h1>
 
-<p align="center"><strong>Your operator cockpit for Pi.</strong><br>See what the session is doing, park ideas without interrupting it, search skills, switch into Bash, and keep the important controls one keypress away.</p>
+<p align="center"><strong>Your operator cockpit for Pi.</strong><br>A live powerline status bar, idea queue, skill search, sticky Bash, hooks, policy controls and session UX — one keypress away, without leaving the terminal.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@groeponline/pi-wishcraft"><img src="https://img.shields.io/npm/v/@groeponline/pi-wishcraft.svg" alt="npm version"></a>
@@ -13,7 +13,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-555.svg" alt="MIT license"></a>
 </p>
 
-<p align="center"><img src="https://raw.githubusercontent.com/GroepOnline/pi-wishcraft/main/docs/images/wishcraft-cockpit-map.svg" alt="Wishcraft cockpit map showing Signal, Deck, idea capture, skills, managed shell and local guardrails around Pi" width="100%"><br><sub>A map of the shipped operator surfaces. Pi remains the agent runtime.</sub></p>
+<p align="center"><img src="https://raw.githubusercontent.com/GroepOnline/pi-wishcraft/main/docs/images/wishcraft-cockpit-map.svg" alt="Wishcraft cockpit map showing Signal, Deck, idea capture, skills, managed shell and local guardrails around Pi" width="100%"><br><sub>The shipped operator surfaces. Pi remains the agent runtime.</sub></p>
 
 ## Start in 10 seconds
 
@@ -21,24 +21,14 @@
 pi install npm:@groeponline/pi-wishcraft
 ```
 
-Reload Pi, then press `alt+p` to open the Deck.
-
-Try the two flows that make Wishcraft click fastest:
+Reload Pi, then press `alt+p` to open the Deck. Two flows make Wishcraft click fastest:
 
 ```text
 # remember to benchmark the new provider path
 /ideas
 ```
 
-The `#` line is captured as an idea instead of being sent as a prompt. Your active run keeps going.
-
-Then open the skill picker:
-
-```text
-/skills
-```
-
-Search, inspect and insert a skill without leaving the session.
+The `#` line is captured as an idea instead of being sent as a prompt — your active run keeps going. Then `/skills` opens the picker: search, inspect and insert a skill without leaving the session.
 
 ## Why Wishcraft
 
@@ -48,14 +38,12 @@ Kongming lanterns started as battlefield signals and later carried wishes. Wishc
 
 **Portfolio boundary:** Wishcraft owns the operator cockpit and lightweight idea capture. Promote durable work to [`pi-missions`](https://github.com/GroepOnline/pi-missions), then use [`pi-agent-orchestrator`](https://github.com/GroepOnline/pi-agent-orchestrator) when parallel or isolated execution adds value: `idea -> mission -> orchestration run`.
 
-Guides live in [`docs/`](docs/index.md).
-
 ## What you get
 
 | Surface | What it does |
 | --- | --- |
 | Signal | Motion-aware three-lane operator status: model/Git, live activity/tool state, and context/queue. Default placement is the editor top border; `/signal placement below` moves it. |
-| `alt+p` | Wishcraft Deck: session, Signal, skills, ideas, guardrails, appearance. `g` + jump. `/wishcraft settings` is the flat list. `/signal menu` is Navigate / Configure / Status. |
+| `alt+p` | Wishcraft Deck: session, Signal, skills, ideas, guardrails, shell, **ports**, usage, appearance, motion, shortcuts, diagnostics. `g` + jump key. `/wishcraft settings` is the flat list; `/signal menu` is Navigate / Configure / Status. |
 | `# <idea>` | File-backed inbox. Does not send the prompt. `/ideas` reviews status, tags, and skill insert. `/ideas next` feeds the oldest active idea into the session. |
 | `alt+s` | Stash the draft, ask something else, get it back when the run finishes. |
 | `/skills` | Overlay search on name, description, and path. Enter inserts. `/skills doctor` is the health table. `/skills new` writes a SKILL.md from a template. |
@@ -70,27 +58,29 @@ Pi owns the footer chrome, feed scrolling, and input. Wishcraft supplies widgets
 
 ## Daily commands
 
-Activates on load. `/signal` toggles it. `/signal <preset>` switches the information layout. `/signal menu` opens Navigate / Configure / Status. `/wishcraft` opens the Deck. Tab completes presets and `placement above|below|toggle`. `/powerline` remains a compatibility alias.
+Activates on load. `/signal` toggles it. `/signal <preset>` switches the information layout. `/wishcraft` opens the Deck. Tab completes presets, `placement above|below|toggle`, and every `/wishcraft` subcommand and setting path. `/powerline` remains a compatibility alias.
 
 ```text
 /signal doctor        settings, queue, git, bash, fonts
 /signal export        current preset + layout as JSON
 /tps                  live in/out overlay (same ring as the segment)
-/tps 40               override POWERLINE_TPS
-/usage                session / today / week from ~/.pi/agent/wishcraft-usage.json
+/usage                session / today / week token ledger
 /repairs              tool-input repair counters
-/skills               skill manager
-/skills doctor        health table (broken frontmatter, dupes, unused, budget)
-/skills new [name]    write a SKILL.md from a template
+/skills               skill manager  ·  /skills doctor  ·  /skills new [name]
 /ideas                idea review overlay (status, tags, skill insert)
 /wishcraft            Deck overlay (operator surface)
-/wishcraft settings   flat settings TUI
-/open-ports           listening sockets
+/wishcraft get <key>  one setting: stored → source → effective
+/wishcraft set <k> <v> validated write (Tab completes paths + values)
+/wishcraft unset <k>  remove a stored value, back to default
+/wishcraft settings   flat settings TUI  ·  setup  ·  doctor
+/open-ports           listening sockets (filter, r refresh, enter copy)
 /cd <path>            continue this conversation in another directory
 /bash-mode            sticky shell  (also ctrl+shift+b)
 /vibe star trek       themed working messages
 ```
 
+Configuration never needs an editor: `set` validates against the same registry the settings TUI and wizard use, applies immediately, and writes to the file that already owns the key. Structured values (layout, custom segments, policy) stay in `settings.json`. See [Configure from the prompt](docs/configuration.md#configure-from-the-prompt).
+
 Keybinds (`powerlineShortcuts`, applied after `/reload`; `null` disables):
 
 ```json
@@ -117,112 +107,22 @@ Keybinds (`powerlineShortcuts`, applied after `/reload`; `null` disables):
 }
 ```
 
-`chef` is muted colors, slash separators, live TPS in/out, and TCP port count. Built-in presets: `default`, `minimal`, `compact`, `full`, `nerd`, `ascii`, `chef`. Custom segments, labels, layout, and presets are documented in [docs/configuration.md](docs/configuration.md). For every setting at its default, see [`examples/settings.example.json`](examples/settings.example.json).
+`chef` is muted colors, slash separators, live TPS in/out, and TCP port count. Built-in presets: `default`, `minimal`, `compact`, `full`, `nerd`, `ascii`, `chef`. For every setting at its default, see [`examples/settings.example.json`](examples/settings.example.json).
 
 Daily token budget (never blocks a turn):
 
 ```json
-{
-  "wishcraft": {
-    "tokenBudget": { "daily": 500000 }
-  }
-}
+{ "wishcraft": { "tokenBudget": { "daily": 500000 } } }
 ```
 
 At 80% the cost segment warns; at 100% it goes red and welcome notifies. `/usage` shows the ledger.
 
-## Hooks
-
-Hooks are commands that read JSON on stdin. See [docs/configuration.md](docs/configuration.md) for examples.
-
-Definitions come from the **global** agent settings file only. Project `.pi/settings.json` cannot install new hook commands. `wishcraft.hooksEnabled: false` disables every hook without deleting the config.
-
-```json
-{
-  "wishcraft": {
-    "hooksEnabled": true,
-    "hooks": {
-      "preToolUse": [
-        { "matcher": "bash", "hooks": [{ "command": "~/.pi/agent/hooks/bash-guard.sh", "timeout": 5 }] }
-      ],
-      "postToolUse": [
-        { "matcher": "write", "hooks": [{ "command": "~/.pi/agent/hooks/write-audit.sh", "timeout": 5 }] }
-      ],
-      "sessionStart": [
-        { "hooks": [{ "command": "~/.pi/agent/hooks/session-git-status.sh", "timeout": 10 }] }
-      ]
-    }
-  }
-}
-```
-
-**Example hook** (exit 2 = deny):
-
-```bash
-#!/usr/bin/env bash
-payload=$(cat)
-cmd=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))')
-if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-r[a-zA-Z]*f|-fr[a-zA-Z]*|[[:space:]]/[[:space:]]*$'; then
-  printf '%s\n' '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"blocked destructive rm"}}'
-  echo "blocked destructive rm" >&2
-  exit 2
-fi
-exit 0
-```
-
-**Another example** (append-only, never blocks):
-
-```bash
-#!/usr/bin/env bash
-mkdir -p "$HOME/.pi/agent/logs"
-cat >> "$HOME/.pi/agent/logs/write-audit.jsonl"
-```
-
-**SessionStart example** (extra context, never blocks):
-
-```bash
-#!/usr/bin/env bash
-status=$(git status --short 2>/dev/null | head -n 40)
-CTX="$status" python3 - <<'PY'
-import json, os
-print(json.dumps({
-  "hookSpecificOutput": {
-    "additionalContext": "git status:\n" + os.environ.get("CTX", "")
-  }
-}))
-PY
-```
-
-Repairs run on custom/extension tools only, before hooks: drop null optionals, parse JSON-string arrays before wrapping, turn `{}` into `[]` on array keys, wrap bare strings, alias `filePath` / `absolutePath` / `target_file` to `path`, unwrap degenerate markdown auto-links. Core tools (`bash`, `read`, `edit`, `write`, `grep`, `find`, `ls`) are never rewritten. `/repairs` prints the counters.
-
-## Policy
-
-Declarative deny/inject rules live in the global settings file; see [docs/configuration.md](docs/configuration.md).
-No shell commands — pure in-process regex. Evaluated before command hooks. `wishcraft.policyEnabled: false` disables policy without deleting rules.
-
-```json
-{
-  "wishcraft": {
-    "policy": [
-      {
-        "action": "deny",
-        "tool": "bash",
-        "match": "sudo\\s+rm",
-        "reason": "destructive sudo rm"
-      },
-      {
-        "action": "inject",
-        "tool": "read",
-        "pathMatch": "\\.env",
-        "context": "Do not leak secrets from .env files into the conversation."
-      }
-    ]
-  }
-}
-```
+## Hooks, policy, and guardrails
 
+Hooks are commands that read JSON on stdin; policy is in-process regex evaluated before them. Definitions live in the **global** settings file only, and `wishcraft.hooksEnabled: false` / `wishcraft.policyEnabled: false` are the kill-switches. Full copy-paste examples — a destructive-`rm` deny hook, an append-only audit hook, a SessionStart git-status hook, and two policy rules — are in [docs/configuration.md](docs/configuration.md#hooks-and-repairs).
 
 Privacy/network boundary: ideas, settings, usage ledgers, and normal cockpit state stay local; there is no package-owned telemetry backend. Optional exchange-rate/DeepWiki features and operator-defined hooks cross the network/process boundary only when used.
+
 ## Limits
 
 - No mouse on the live footer. Pi core owns that surface.
@@ -231,18 +131,19 @@ Privacy/network boundary: ideas, settings, usage ledgers, and normal cockpit sta
 - The legacy `@groeponline/pi-powerline-footer` package is deprecated in favor of `@groeponline/pi-wishcraft`.
 - Tags are not rewritten. 0.19.x through current stay on the timeline.
 
-## vNext Direction
+## vNext direction
 
 Wishcraft is Pi's animated operator layer. See the [release plan](docs/design/vnext-release-plan.md) and [design corpus](docs/index.md#design-system--vnext-specifications).
+
 ## Docs
 
-- [Commands](docs/commands.md)
-- [Configuration](docs/configuration.md)
-- [Bash mode](docs/bash-mode.md)
-- [Stash and shortcuts](docs/stash-and-shortcuts.md)
-- [Skill manager](docs/skill-manager.md)
-- [Working vibes](docs/working-vibes.md)
-- [Segments and theming](docs/segments.md)
+- [Commands](docs/commands.md) — every slash command and keybind
+- [Configuration](docs/configuration.md) — settings, hooks, policy, custom segments
+- [Segments and theming](docs/segments.md) — presets, colors, separators
+- [Bash mode](docs/bash-mode.md) · [Stash and shortcuts](docs/stash-and-shortcuts.md)
+- [Skill manager](docs/skill-manager.md) · [Working vibes](docs/working-vibes.md)
 - [ROADMAP](ROADMAP.md)
 
+Guides live in [`docs/`](docs/index.md).
+
 MIT. Issues: [GroepOnline/pi-wishcraft](https://github.com/GroepOnline/pi-wishcraft/issues).

package/build-stamp.json

@@ -1 +1 @@
-{"source_sha":"394402d958799308f24ffc284a240b878588a931"}
+{"source_sha":"a7570d9c73e85d4553e6bfbba32e1c76c7d857b9"}

package/docs/commands.md

@@ -98,14 +98,20 @@ Pi core renders the footer as static text, so live click is not possible; action
 
 - `/tps`: overlay of the live 1s window (same ring as the segment). `/tps <value>` sets `POWERLINE_TPS`
 - `/usage`: session / today / week overlay from `~/.pi/agent/wishcraft-usage.json`
-- `/open-ports`: list listening ports and pick one
+- `/open-ports`: listening sockets in a parsed table — async probe with a bounded timeout, summary line, type to filter, `r` re-probe, Enter copies. Honours `powerline.segmentOptions.openPorts` (UDP + fleet host), so the command, `alt+i`, the classic menu and the Deck all probe the same target. `--udp` forces UDP on for one call
 - `/powerline doctor`: diagnostics overlay — settings file validity, unknown presets, Nerd Font detection, git polling, bash-mode status, queue file health, and `package.identity`
 - `/powerline version`: `{ version, source_sha }` from `package.json` (SHA only when release-stamped). See [release.md](./release.md).
 - `/powerline export`: export the current preset + effective layout + labels as a JSON snippet (Enter copies it to the clipboard)
-- `alt+p`: **Wishcraft Deck** — operator overlay (Home, Signal, Skills, Ideas, Guardrails, Appearance, …). `g` then a jump key (`h` home, `s` signal, `a` appearance). Escape closes. `/signal menu` still opens Navigate / Configure / Status.
-- `alt+i`: **powerline info**: full open-ports list
-- `/wishcraft [route]`: open the Deck at a named route (`appearance`, `skills`, …)
-- `/wishcraft settings`: flat settings TUI, including `powerline.appearance.base` and `powerline.motionLevel`
+- `alt+p`: **Wishcraft Deck** — operator overlay (Home, Signal, Skills, Ideas, Guardrails, Shell, Ports, Usage, Appearance, Motion, Shortcuts, Diagnostics). `g` then a jump key (`h` home, `s` signal, `a` appearance, `p` ports). Long lists window around the cursor (↑↓ scrolls, the frame never grows past the screen). On **Ideas**: `enter` cycles idea → in-progress → done, `d` removes, `/` filters. Escape closes. `/signal menu` still opens Navigate / Configure / Status.
+- `alt+i`: **powerline info** — the open-ports panel: async probe (bounded timeout, never blocks the UI), summary line, aligned `PROTO PORT ADDRESS OWNER` table, type to filter, `r` re-probe, Enter copies
+- `/wishcraft [route]`: open the Deck at a named route (`appearance`, `skills`, `ports`, …)
+- `/wishcraft get <setting>`: one line — stored value, which file owns it (project / global / default), the effective value, and a ⚠ explanation when the stored value fails validation. Accepts the dotted path (`powerline.preset`) or the setting id (`status.preset`)
+- `/wishcraft set <setting> <value>`: validated write from the prompt — choices accept a unique prefix (`set motion.level red` → `reduced`), toggles take `on`/`off` (not `true`/`false`), numbers are checked against the registry's bounds, and an empty value on a text setting clears the key. Tab completes subcommands, every registered path, and the values each setting accepts. Changes apply immediately (status line repaints; shortcuts and bash settings after `/reload`)
+- `/wishcraft unset <setting>`: remove the stored key so the default applies again (alias: `reset`)
+- `/wishcraft help`: the one-line grammar. Structured values (`powerline.layout`, `powerline.segments`, `wishcraft.policy`…) stay in settings.json — the CLI refuses them with a pointer instead of writing a broken shape
+- `/wishcraft settings`: flat settings TUI, including `powerline.appearance.base` and `powerline.motionLevel` — shows a live status-line preview, the current setting's hint, and a ⚠ marker on any stored value that fails validation
+- `/wishcraft setup`: first-run wizard — language, status preset, motion level, welcome overlay, then one write to `settings.json`
+- `/wishcraft doctor`: configuration diagnosis on one screen — which settings file wins, shadowed values, near-miss keys, and every value validation discarded (also a section of the Deck's Diagnostics route)
 - Deck **Motion**: gallery + composer. `t` picks the event, Enter applies, `e` opens the composer
 - Deck **Skills**: workbench list with health; Enter inserts the skill body
 

package/docs/configuration.md

@@ -92,14 +92,16 @@ Segment fields:
 
 - `type` (required): `command` | `env` | `static`
 - `command` (command type): shell command to run; output is trimmed
-- `cacheMs` (command type, optional): cache output for N ms to avoid re-spawning a shell every paint
+- `cacheMs` (command type, optional): how long to reuse the previous output before re-running. Defaults to `1000`ms; clamped to `100`–`300000`ms
 - `env` (env type): environment variable to read
 - `fallback` (env type, optional): text shown when the variable is unset (omit to hide the segment)
 - `text` (static type): fixed text
 - `prefix` (optional): text shown before the value
 - `color` (optional): Pi theme color (`warning`, `accent`, ...) or hex (`#RRGGBB`)
 
-If a command fails or an env var is unset without a fallback, the segment renders nothing.
+Command segments run **in the background**, never inside a paint: the status line shows the previous output (or nothing on the very first frame) and repaints when the command finishes. A hung command is capped at 5s and its output at 512 characters.
+
+If a command fails or an env var is unset without a fallback, the segment renders nothing. A failed command is reported as a fault marker (`!custom:<id>`) on the next paint rather than being silently hidden.
 
 ## Custom presets
 
@@ -281,11 +283,88 @@ Set `powerline.costAlert` to a USD threshold to get a single warning notificatio
 
 ## Hooks and repairs
 
-Command hooks live under `wishcraft.hooks` in the **global** agent settings file. `wishcraft.hooksEnabled: false` is the kill-switch. See the README Hooks section for three copy-paste examples (bash-guard, write-audit, SessionStart git-status).
+Command hooks live under `wishcraft.hooks` in the **global** agent settings file. `wishcraft.hooksEnabled: false` is the kill-switch. A hook is any command that reads JSON on stdin; exit code 2 denies the tool call, stdout may return a `hookSpecificOutput` payload. Definitions come from the global file only — project `.pi/settings.json` cannot install new hook commands.
+
+```json
+{
+  "wishcraft": {
+    "hooksEnabled": true,
+    "hooks": {
+      "preToolUse": [
+        { "matcher": "bash", "hooks": [{ "command": "~/.pi/agent/hooks/bash-guard.sh", "timeout": 5 }] }
+      ],
+      "postToolUse": [
+        { "matcher": "write", "hooks": [{ "command": "~/.pi/agent/hooks/write-audit.sh", "timeout": 5 }] }
+      ],
+      "sessionStart": [
+        { "hooks": [{ "command": "~/.pi/agent/hooks/session-git-status.sh", "timeout": 10 }] }
+      ]
+    }
+  }
+}
+```
+
+**Example hook** (exit 2 = deny):
+
+```bash
+#!/usr/bin/env bash
+payload=$(cat)
+cmd=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))')
+if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-r[a-zA-Z]*f|-fr[a-zA-Z]*|[[:space:]]/[[:space:]]*$'; then
+  printf '%s\n' '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"blocked destructive rm"}}'
+  echo "blocked destructive rm" >&2
+  exit 2
+fi
+exit 0
+```
+
+**Another example** (append-only, never blocks):
+
+```bash
+#!/usr/bin/env bash
+mkdir -p "$HOME/.pi/agent/logs"
+cat >> "$HOME/.pi/agent/logs/write-audit.jsonl"
+```
+
+**SessionStart example** (extra context, never blocks):
+
+```bash
+#!/usr/bin/env bash
+status=$(git status --short 2>/dev/null | head -n 40)
+CTX="$status" python3 - <<'PY'
+import json, os
+print(json.dumps({
+  "hookSpecificOutput": {
+    "additionalContext": "git status:\n" + os.environ.get("CTX", "")
+  }
+}))
+PY
+```
 
-Declarative policy rules (`wishcraft.policy`) live in the same global file. They run in-process before command hooks: **deny** blocks a tool call when input matches a regex; **inject** appends context after a matching read/write path. `wishcraft.policyEnabled: false` disables policy without deleting rules. See the README Policy section for two copy-paste examples.
+Repairs run on custom/extension tools only, before hooks: drop null optionals, parse JSON-string arrays before wrapping, turn `{}` into `[]` on array keys, wrap bare strings, alias `filePath` / `absolutePath` / `target_file` to `path`, unwrap degenerate markdown auto-links. Core tools (`bash`, `read`, `edit`, `write`, `grep`, `find`, `ls`) are never rewritten. `/repairs` prints the counters.
 
-Tool-input repairs apply to custom/extension tools only (`wishcraft.repairsEnabled`, default on). `/repairs` prints the counters.
+Declarative policy rules (`wishcraft.policy`) live in the same global file. They run in-process before command hooks: **deny** blocks a tool call when input matches a regex; **inject** appends context after a matching read/write path. `wishcraft.policyEnabled: false` disables policy without deleting rules. No shell commands — pure in-process regex.
+
+```json
+{
+  "wishcraft": {
+    "policy": [
+      {
+        "action": "deny",
+        "tool": "bash",
+        "match": "sudo\\s+rm",
+        "reason": "destructive sudo rm"
+      },
+      {
+        "action": "inject",
+        "tool": "read",
+        "pathMatch": "\\.env",
+        "context": "Do not leak secrets from .env files into the conversation."
+      }
+    ]
+  }
+}
+```
 
 ## Token budget
 
@@ -372,3 +451,72 @@ Opt-in; defaults match the historical rendering.
   }
 }
 ```
+
+## Where settings live
+
+Pi merges two files; the **project** file wins on any key it also defines in the global file.
+
+| Scope | Path | Wins over |
+|---|---|---|
+| Global | `~/.pi/agent/settings.json` | — |
+| Project | `<cwd>/.pi/settings.json` | global |
+
+`/wishcraft doctor` shows this on one screen: both files' health, every value shadowed by the other file, near-miss keys with a "did you mean" suggestion, and every stored value that validation discards (with the reason and the default that applies instead). The same report is rendered as a section of the Deck's **Diagnostics** route.
+
+## Configure from the prompt
+
+Every registered setting is readable and writable without leaving pi — no editor, no `settings.json` detour:
+
+```text
+/wishcraft get powerline.preset          # stored · global/project/default → effective
+/wishcraft set powerline.preset chef     # validated write, applies immediately
+/wishcraft set motion.level red          # unique prefix → reduced
+/wishcraft set powerline.welcome off     # toggles take on/off
+/wishcraft unset powerline.preset        # back to the default (alias: reset)
+/wishcraft help                          # the grammar, one line
+```
+
+Tab completes subcommands, every registered path, and the values a setting accepts (`choices` for selects, `on · off` for toggles). The same validation runs everywhere — the CLI, `/wishcraft settings`, the setup wizard and the doctor all read one registry, so a value the CLI accepts is a value the overlay accepts.
+
+Deliberate boundaries:
+
+- **Scalars only.** Structured values (`powerline.layout`, `powerline.segments`, `wishcraft.policy`, `powerline.presets`) stay in `settings.json`; the CLI refuses them with a pointer instead of writing a broken shape.
+- **Writes land where the key already exists** (project file if it defines the root, otherwise global) — the same precedence `readSettings` uses.
+- **`get` works even when Signal is disabled**; configuration never depends on the status line.
+
+Settings the CLI and overlay expose, beyond the presets and segment options: the whole `bashMode.*` group (toggle shortcut, transcript limits, init script), all nine `powerlineShortcuts` bindings, `powerline.costAlert`, `powerline.stashSharpSShortcut`, `powerline.customItemsAuto`, `powerline.queue.retentionHours`, `wishcraft.policyEnabled`, and the git/model/ports segment toggles. `examples/settings.example.json` remains the reference for every key at its default.
+
+## Interface language
+
+```json
+{ "wishcraft": { "locale": "nl" } }
+```
+
+`en` (default) or `nl`. The setting appears as **Language** under *Interface* in `/wishcraft settings`, and applies immediately — no restart. Anything unknown, malformed, or region-tagged (`nl-NL`, `en_US`) resolves safely, and a message with no translation falls back to its built-in English string, so switching locale can never blank a surface. Set `PI_WISHCRAFT_LOCALE` to pick a language before settings are read.
+
+Localised surfaces: Deck route names and chrome, settings labels/hints/group titles, the configuration overlay, the welcome overlay and its widgets, the setup wizard, and the diagnostics copy. Segment values, model names, branch names and other data are data — they stay as-is.
+
+## First-run setup
+
+```text
+/wishcraft setup
+```
+
+Four questions — language, status preset, motion level, welcome overlay — then a review screen and one write to `settings.json`. Every step is also editable later from `/wishcraft settings`.
+
+On the very first launch the welcome panel shows three next steps under **Getting started** instead of a changelog wall. Later launches show the usual changelog delta under **What's new**.
+
+## Segment options: two accepted shapes
+
+Segment options may be written either hand-edited at the top level of `powerline`, or nested under `powerline.segmentOptions` (the shape the settings UI writes):
+
+```json
+{
+  "powerline": {
+    "tps": { "windowMs": 2000 },
+    "segmentOptions": { "path": { "mode": "abbreviated" } }
+  }
+}
+```
+
+Both are read; when a segment appears in both places the nested `segmentOptions` copy wins for the keys it defines.

package/docs/index.md

@@ -4,8 +4,8 @@ This package is a Pi.dev extension, not a standalone website. The README is the
 
 ## Guides
 
-- [Commands & interactivity](./commands.md) — `/powerline`, `/tps`, `/usage`, `/queue`, `/idea`, placement, presets, keybinds, and the navigable overlay.
-- [Configuration](./configuration.md) — custom items, hooks, repairs, token budget, labels, templates, layout, cost alert, and display formats.
+- [Commands & interactivity](./commands.md) — `/powerline`, `/tps`, `/usage`, `/queue`, `/idea`, `/wishcraft` (get/set/unset, settings, setup, doctor), placement, presets, keybinds, and the navigable overlay.
+- [Configuration](./configuration.md) — configure from the prompt, where settings live, interface language, first-run setup, custom items, hooks, repairs, token budget, labels, templates, layout, cost alert, and display formats.
 - [Bash mode](./bash-mode.md) — sticky shell, ghost suggestions, and shell config.
 - [Stash & shortcuts](./stash-and-shortcuts.md) — editor stash, prompt history, clipboard/navigation shortcuts, and shortcut config.
 - [Skill manager](./skill-manager.md) — browsing, inserting, `/skills doctor`, and `/skills new` templates.