@groeponline/pi-wishcraft 0.20.0 → 0.22.0

package/docs/bash-mode.md

@@ -0,0 +1,46 @@
+# Bash mode
+
+Toggle bash mode with either:
+
+- `ctrl+shift+b`
+- `/bash-mode on`
+- `/bash-mode off`
+- `/bash-mode toggle`
+
+Reset the managed shell with `/bash-reset`.
+
+While bash mode is active:
+
+- Enter runs the current shell command
+- Right Arrow accepts ghost text into the editor without running it
+- Tab completes the ghost suggestion one token/segment at a time (repeat Tab to step through each further token); once the full suggestion is inserted it clears, otherwise Tab does nothing
+- Up and Down browse matching shell history
+- `escape` exits bash mode and returns to normal prompt mode
+- `ctrl+c` interrupts the active shell job before falling back to normal pi behavior
+
+The managed shell is persistent for the current pi session. Command output appears in a transcript below the editor, and shell cwd changes are reflected in the footer path and `shell_mode` segment.
+
+## Shell ghost suggestions
+
+Bash mode is ghost-first. Successful per-project shell history is the primary source, while deterministic path and git continuations can still extend an existing command. Shell-native completion probes are disabled so `!command` predictions never spawn interactive shell completion subprocesses.
+
+At command position, short stems first resolve from the newest successful local command, can use guarded global shell history for high-confidence heads like `git`, and finally fall back to a tiny curated default set when history is absent. Right now that curated set is `g` → `git status` and `c` → `cd ..`.
+
+If the bash prompt is empty, bash mode shows the newest successful project-history ghost suggestion immediately when one exists, including right after mode entry or after the prompt is cleared again. One-off `!command` and `!!command` prompts reuse the same shell prediction pipeline, including ghost text. Right Arrow or Tab accepts ghost text into the editor, and Enter runs the current shell command. Mode entry stays quiet: there is no automatic or manual dropdown completion surface, and ghost suggestions do not run shell-native completion probes.
+
+## Configuration
+
+In `~/.pi/agent/settings.json` (or under `PI_CODING_AGENT_DIR` when that environment variable is set):
+
+```json
+{
+  "bashMode": {
+    "toggleShortcut": "ctrl+shift+b",
+    "transcriptMaxLines": 2000,
+    "transcriptMaxBytes": 524288,
+    "initScript": "export NODE_ENV=development\nalias g='git status'"
+  }
+}
+```
+
+`initScript` is a project-scoped shell setup block: it is sourced once when the managed shell starts (before your first command), so a repo can export env vars, define aliases, or set shell options per project. Put it in the project-local `.pi/settings.json` to keep it repo-specific; omit it (or use a global `bashMode` entry) otherwise.

package/docs/commands.md

@@ -0,0 +1,122 @@
+# Commands & interactivity
+
+## Usage
+
+Activates automatically. Toggle with `/powerline`, switch presets with `/powerline <name>`, and move the primary row with `/powerline placement above|below|toggle`.
+
+Use `/cd <path>` to continue the current conversation from another working directory. It supports relative paths, absolute paths, `~`, `~/...`, and directory completions. With no argument, `/cd` prints the current Pi session directory. The command switches into a cwd-updated session file so Pi tools and the footer path segment agree after the change.
+
+### Powerline Queue + Inbox
+
+Commands and capture shortcuts:
+
+- `# <text>`: capture an idea for the current project without sending it to the agent
+- `# @global <text>`: capture a global idea
+- `# @current <text>`: capture an idea targeted to the current session
+- `/queue alias <name> [path]`: save a project alias, defaulting to the current cwd when `path` is omitted
+- `# @name <text>`: capture an idea for a saved project alias
+- `/compact <text>`: compact now and queue `<text>` as the next prompt after successful compaction
+- `/idea [@target] <text>`: command form of idea capture, useful for scripts and users who disable the sigil
+- `/idea issue [id]`: hand the oldest active idea, or a specific idea, to the current agent for safe GitHub issue triage
+- `/ideas`: open the captured-ideas picker
+- `/ideas next`: send the oldest active idea to the current session
+- `/ideas issue [id]`: ask the current agent to dedupe and file a GitHub issue only when the target repo is clear and owned/controlled
+- `/ideas send <id>`: send an idea to the current session
+- `/queue`: open the queued-prompt picker
+- `/queue send [id]` / `/queue retry [id]`: deliver a queued item now
+- `/queue clear <id|all>`: clear queued prompt items
+- `/queue target <id> @name|global|current`: retarget a queued item
+- `/queue archive [hours]`: move completed items older than the retention window from `inbox.jsonl` into `inbox.archive.jsonl`
+
+The default capture sigil is `#`. When the editor text starts with `#` followed by a space, the prompt glyph changes to `#`; pressing Enter saves the idea, clears the editor, and leaves the original sigil text in editor history for quick recovery. Configure or disable this under `powerline.queue.captureSigil`:
+
+```json
+{
+  "powerline": {
+    "queue": {
+      "captureSigil": "#"
+    }
+  }
+}
+```
+
+Set `captureSigil` to `false` if you often submit markdown headings and prefer `/idea` instead.
+
+`powerline.queue.retentionHours` (default `24`) controls how long completed (sent) items stay in the inbox before `/queue archive` moves them to `inbox.archive.jsonl` and before the store prunes them on the next write:
+
+```json
+{
+  "powerline": {
+    "queue": {
+      "captureSigil": "#",
+      "retentionHours": 72
+    }
+  }
+}
+```
+
+Captured data is stored under the Pi agent directory in `powerline-footer/inbox.jsonl` and `powerline-footer/projects.json`. `inbox.jsonl` is a stable read surface for orchestrators and helper agents; each line is a queue item with `id`, `text`, `createdAt`, `updatedAt`, `source`, `target`, `intent`, `status`, and optional `error`. Writes should still go through Powerline commands or the store so locking and atomic writes are preserved. Ideas sent with `/ideas next` or `/ideas send <id>` include a small provenance header so the receiving agent can treat them as deferred captured context. `/idea issue` and `/ideas issue` do not file issues directly from the extension; they send a guarded handoff prompt that tells the current agent to dedupe open issues first, create a GitHub issue only for a clear owned/controlled repo, and ask before filing when the target is unclear.
+
+### Placement
+
+- `/powerline placement below`: move the primary powerline row below the editor
+- `/powerline placement above`: restore the default placement
+- `/powerline placement toggle`: switch between above and below
+
+You can also set it in the agent settings file (`~/.pi/agent/settings.json` by default, or under `PI_CODING_AGENT_DIR`) or project-local `.pi/settings.json`:
+
+```json
+{
+  "showLastPrompt": true,
+  "powerline": {
+    "preset": "default",
+    "placement": "below",
+    "welcome": true
+  }
+}
+```
+
+## Presets
+
+| Preset | Description |
+|--------|-------------|
+| `default` | Balanced daily driver: model, thinking, path (basename), git (branch + dirty + latest commit + ↑/↓ ahead-behind + host icon), session, queue, subagent cost, tokens in/out, cache-hit%, cost, context |
+| `minimal` | Just path (basename), git branch and context% (branch-only polling, no indicators/commit) |
+| `compact` | Model, git (short commit + ahead/behind), queue, cost, context%, session id |
+| `full` | Everything: hostname, model, path (abbreviated), full git incl commit + ↑/↓, totals, context total, elapsed + clock |
+| `nerd` | Maximum detail for Nerd Font users: qualified model, full tokens + cache, commit, totals, seconds clock |
+| `ascii` | Safe for any terminal: branch + short commit + ↑/↓, tokens, cost, context% (no Nerd glyphs) |
+| `chef` | Fork default: muted colors, slash separators, live TPS in/out + open-ports + subagent-cost segments |
+
+**Environment:** `POWERLINE_NERD_FONTS=1` to force Nerd Fonts, `=0` for ASCII.
+
+Preset selection is saved under `powerline` in the agent settings file and restored on startup. Run `/powerline default` to switch back to the default preset.
+
+## Interactivity
+
+Pi core renders the footer as static text, so live click is not possible; actions live in commands and a navigable overlay.
+
+- `/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
+- `/powerline doctor`: diagnostics overlay — settings file validity, unknown presets, Nerd Font detection, git polling, bash-mode status, and queue file health
+- `/powerline export`: export the current preset + effective layout + labels as a JSON snippet (Enter copies it to the clipboard)
+- `alt+p`: **powerline menu**: navigate the live segments (`↑`/`↓` + `enter`, `→`/`tab` opens a per-segment detail panel; values refresh every second while open), configure (preset / TPS / UDP / segment visibility / labels / build custom preset), or open the full ports list
+- `alt+i`: **powerline info**: full open-ports list
+
+Both `alt+p` and `alt+i` are rebindable (see Keybinds below); changes apply after `/reload`.
+
+## Keybinds
+
+The powerline menu and info shortcuts are configurable via `powerlineShortcuts` (same map as the other powerline shortcuts), with automatic conflict resolution. Set a binding to `null` to disable it.
+
+```json
+{
+  "powerlineShortcuts": {
+    "menu": "alt+p",
+    "info": "alt+i"
+  }
+}
+```
+
+Changes apply after `/reload` (the extension re-registers shortcuts on reload).

package/docs/configuration.md

@@ -0,0 +1,307 @@
+# Configuration
+
+## Custom items from extension statuses
+
+You can promote any extension status key into its own dedicated powerline item. This gives you a general way to register your own status items without changing this extension.
+
+1. Any extension can publish status text through `ctx.ui.setStatus("my-key", "...value...")`.
+2. Configure `powerline.customItems` to place those keys on the left, right, or secondary row.
+
+```json
+{
+  "powerline": {
+    "preset": "default",
+    "customItems": [
+      {
+        "id": "ci",
+        "statusKey": "ci-status",
+        "position": "right",
+        "prefix": "CI",
+        "color": "warning"
+      },
+      {
+        "id": "review",
+        "position": "secondary",
+        "hideWhenMissing": false,
+        "prefix": "review"
+      }
+    ]
+  }
+}
+```
+
+`customItems` fields:
+
+- `id` (required): unique item id (`a-z`, `A-Z`, `0-9`, `_`, `-`)
+- `statusKey` (optional): extension status key to read, defaults to `id`
+- `position` (optional): `left`, `right`, or `secondary` (default `right`)
+- `prefix` (optional): text shown before the live status value
+- `color` (optional): any Pi theme color (`warning`, `accent`, etc.) or hex (`#RRGGBB`)
+- `hideWhenMissing` (optional): hide item when no status is present (default `true`)
+- `excludeFromExtensionStatuses` (optional): omit this key from the aggregate `extension_statuses` segment (default `true`)
+
+### Auto-promote every status key (`customItems.auto`)
+
+Instead of listing each status key explicitly, set `powerline.customItems.auto: true` to turn every live extension status key into its own right-aligned segment. This is the ChefBar status bridge: any extension that calls `ctx.ui.setStatus("some-key", "value")` gets a matching segment automatically, without edits to this extension.
+
+```json
+{
+  "powerline": {
+    "customItems": {
+      "auto": true
+    }
+  }
+}
+```
+
+Auto items follow the same rules as explicit items: notification-style statuses, internal/excluded keys, and keys already claimed by an explicit item are skipped, and each auto item is excluded from the aggregate `extension_statuses` segment so a status renders exactly once. Mix `auto` with explicit entries by using the object form of `customItems`:
+
+```json
+{
+  "powerline": {
+    "customItems": {
+      "auto": true,
+      "ci": { "statusKey": "ci-status", "prefix": "CI", "color": "warning" }
+    }
+  }
+}
+```
+
+If you still prefer the older string preset config shape, `"powerline": "default"` continues to work. String preset shorthand keeps `welcome` enabled and uses the default shortcut/cost/model display settings.
+
+## Custom segments (computed, no code)
+
+Define your own segments directly in settings: run a command, read an env var, or show static text. No TypeScript needed.
+
+```json
+{
+  "powerline": {
+    "preset": "chef",
+    "segments": {
+      "battery": { "type": "command", "command": "cat /sys/class/power_supply/BAT0/capacity", "prefix": "batt", "cacheMs": 30000 },
+      "who":     { "type": "env", "env": "USER", "prefix": "u", "color": "#888888" },
+      "chef":    { "type": "static", "text": "CHEF", "color": "accent" }
+    }
+  }
+}
+```
+
+Each segment becomes usable in a preset as `custom:<id>` (e.g. `custom:battery`).
+
+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
+- `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.
+
+## Custom presets
+
+Define your own preset in settings; it merges over built-ins and is selectable via `powerline.preset` (or `/powerline <name>`).
+
+```json
+{
+  "powerline": {
+    "preset": "mine",
+    "segments": { "battery": { "type": "command", "command": "cat /sys/class/power_supply/BAT0/capacity", "prefix": "batt" } },
+    "presets": {
+      "mine": {
+        "left": ["hostname", "model", "custom:battery", "git"],
+        "right": ["tps", "open_ports", "cost", "time"],
+        "separator": "slash",
+        "colors": { "model": "text" },
+        "segmentOptions": { "path": { "mode": "basename" } }
+      }
+    }
+  }
+}
+```
+
+### Build a preset from the menu
+
+You don't have to edit JSON: `alt+p` → `Configure…` → `Build custom preset…` walks you through naming a preset, choosing a base preset (for its colors + segment options), picking left/right/secondary segments, and choosing a separator. It saves the result under `powerline.presets.<name>`, sets it as the active preset, and applies it immediately.
+
+## Segment labels (custom text)
+
+Rename the text shown for **any** segment via `powerline.segmentLabels` (a map of segment id → label). The label appears between the icon and the value. Works for built-in segments, custom segments, and custom items alike.
+
+```json
+{
+  "powerline": {
+    "segmentLabels": {
+      "tps": "speed",
+      "open_ports": "ports",
+      "time": "clock",
+      "git": "branch"
+    }
+  }
+}
+```
+
+## Segment templates (custom value format)
+
+Full control over the rendered value with `powerline.segmentOptions.<id>.template`. The placeholder `{value}` is replaced with the segment's value text (the icon and label, if any, stay in place).
+
+```json
+{
+  "powerline": {
+    "segmentOptions": {
+      "tps": { "template": "{value} tok/s" },
+      "open_ports": { "template": "{value} listeners" }
+    }
+  }
+}
+```
+
+## Disabling segments
+
+Set `powerline.disabledSegments` to hide built-in or configured custom segments from the active preset. You can also toggle segments live from the `alt+p` menu (`Configure…` → `Toggle segment visibility…`), which persists to `powerline.disabledSegments`:
+
+```json
+{
+  "powerline": {
+    "preset": "default",
+    "disabledSegments": ["cost", "extension_statuses", "custom:ci"]
+  }
+}
+```
+
+Built-in names are listed under Segments in [Segments & theming](./segments.md). Custom items use `custom:<id>`. Unknown names are ignored with a startup warning.
+
+## Open-ports host (fleet)
+
+Make `open_ports` probe a named SSH host instead of the laptop:
+
+```json
+{
+  "powerline": {
+    "segmentOptions": {
+      "openPorts": { "host": "sofie", "includeUdp": false }
+    }
+  }
+}
+```
+
+See [Segments & theming](./segments.md) for the probe's best-effort behavior and requirements.
+
+## Status bridge for other extensions
+
+Powerline publishes its own state under a stable key set so ChefBar and other extensions can read it without depending on powerline internals:
+
+| Status key | Value |
+|------------|-------|
+| `powerline.preset` | Active preset name (e.g. `chef`) |
+| `powerline.tps` | `POWERLINE_TPS` override, cleared when live rate is used |
+| `powerline.ports` | Open-port count (`?` when a fleet host probe fails) |
+
+The keys update on preset change, `/tps`, the open-ports list, and the UDP toggle. They are intentionally hidden from powerline's own `extension_statuses` segment (they exist for other extensions to consume).
+
+## Cost alert
+
+Set `powerline.costAlert` to a USD threshold to get a single warning notification per session when the running session spend (assistant + subagent cost) reaches it. Omit it or set `0` to disable.
+
+```json
+{
+  "powerline": {
+    "costAlert": 5
+  }
+}
+```
+
+## 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).
+
+Tool-input repairs apply to custom/extension tools only (`wishcraft.repairsEnabled`, default on). `/repairs` prints the counters.
+
+## Token budget
+
+`wishcraft.tokenBudget.daily` is a token count (input + output + cache). At 80% the cost segment turns warning-coloured; at 100% it turns red and welcome notifies. It never blocks a turn.
+
+```json
+{
+  "wishcraft": {
+    "tokenBudget": { "daily": 500000 }
+  }
+}
+```
+
+## Custom layout
+
+Use `powerline.layout` to override segment order and grouping while keeping the selected preset's colors and segment options. Set `powerline.separator` when you want a separator style independent of the preset:
+
+```json
+{
+  "powerline": {
+    "preset": "default",
+    "separator": "chevron",
+    "layout": {
+      "left": ["model", "thinking", "path", "git"],
+      "right": ["context_pct", "cost"],
+      "secondary": ["custom:ci"]
+    },
+    "customItems": [
+      { "id": "ci", "statusKey": "ci-status" }
+    ]
+  }
+}
+```
+
+A present `left`, `right`, or `secondary` array replaces that preset group exactly; an empty array clears it. Omitted groups keep the preset entries and automatically append custom items by their configured `position`. Explicitly listing a segment moves it out of omitted preset groups, and explicitly placed custom items are not auto-appended elsewhere. `disabledSegments` is applied after layout. `separator` accepts any style listed in [Segments & theming](./segments.md); omit it to keep the preset's separator.
+
+Responsive behavior is unchanged: these groups control ordering and overflow priority, not permanently pinned terminal rows. `right` means "later primary segments," not right-edge alignment. On wide terminals secondary entries can fit in the top bar; on narrow terminals primary overflow moves into the secondary line. Some segments are hidden when they have no value, so `thinking` appears only when the active session/model reports a non-`off` thinking level. Unknown entries are ignored with a startup warning. The old fixed `custom` preset has been removed; combine any preset with `layout` instead.
+
+## Demo settings
+
+For a compact current footer setup:
+
+```json
+{
+  "powerline": {
+    "preset": "default",
+    "path": { "mode": "basename" },
+    "model": { "display": "name" },
+    "cost": { "subscriptionDisplay": "subscription", "currency": "USD" }
+  }
+}
+```
+
+Use `"model": { "display": "qualified" }` when two providers expose models with the same display name.
+
+### Cost currency
+
+`cost.currency` accepts `USD`, `CNY`, `EUR`, `GBP`, `JPY`, `CAD`, `AUD`, `CHF`, `INR`, or `KRW`. Pi reports costs in USD; non-USD display uses a keyless USD FX rate fetched in the background and cached for 24 hours under the Pi agent directory. If no cached rate is available yet, the cost segment renders `-- CODE` until a later footer refresh can use the fetched rate.
+
+### Subscription cost display
+
+| Mode | Subscription + reported cost | Subscription + no reported cost |
+|------|------------------------------|----------------------------------|
+| `subscription` | `(sub)` | `(sub)` |
+| `reported-cost` | `$0.12` | `(sub)` |
+| `both` | `$0.12 (sub)` | `(sub)` |
+
+### Segment display formats
+
+Opt-in; defaults match the historical rendering.
+
+| Segment option | Values | Default | Effect |
+|---|---|---|---|
+| `"context": { "format" }` | `"full"` / `"percent"` | `"full"` | `"percent"` shows a bare rounded `83%` (threshold-colored, no icon) instead of `12k/200k (6.2%)` |
+| `"cache_read": { "format" }` | `"tokens"` / `"percent"` / `"both"` | `"tokens"` | `"percent"` shows the cache hit rate `cacheRead / (input + cacheRead)` instead of the raw token count; `"both"` shows raw tokens plus the hit rate, e.g. `cache in: 12k (80%)` |
+| `"tps": { "windowMs" }` | number, clamped to 500–5000 | `1000` | Length of the sliding rate window; widen it (e.g. `2000`) for a smoother read on very fast models |
+| `"<segment>": { "template" }` | string with `{value}` | — | Replaces the segment's value text; see Segment templates above |
+
+```json
+{
+  "powerline": {
+    "context": { "format": "percent" },
+    "cache_read": { "format": "both" }
+  }
+}
+```

package/docs/index.md

@@ -0,0 +1,18 @@
+# pi-wishcraft documentation
+
+This is the detailed documentation split out of the top-level `README.md`.
+The README stays a short landing page; everything below lives here.
+
+## 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.
+- [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 and inserting installed skills.
+- [Working vibes](./working-vibes.md) — themed loading messages, modes, and configuration.
+- [Segments & theming](./segments.md) — segment reference, separators, thinking/path/git options, and theme overrides.
+
+## Planning
+
+- [ROADMAP.md](../ROADMAP.md) — release campaigns and leftover 0.20 / 1.0 work.

package/docs/segments.md

@@ -0,0 +1,168 @@
+# Segments & theming
+
+## The `chef` preset
+
+`preset: "chef"` is the GroepOnline fork's default look: muted colors (no rainbow), slash separators, and two extra right-side segments:
+
+- `tps`: live tokens/sec over a rolling 1-second window (EMA-free, no spikes), now reporting **output and input** rates separately (`⇡out ⇣in`) so you can see generation speed and incoming prompt tokens at a glance. A rocket/bolt icon lights up while streaming (override with env `POWERLINE_TPS`).
+- `open_ports`: count of unique **TCP** listening ports (`ss` → `netstat` → `/proc/net` fallback, dedupes IPv4/IPv6). Set `segmentOptions.openPorts.includeUdp: true` to include noisy UDP (mDNS/DHCP/ephemeral).
+
+### Open-port process owners
+
+Open the segment detail view (`alt+p` → `Navigate segments` → `open_ports` → `→`) to see **which process owns each listening port**. It best-effort parses `ss -tulnp` (falling back to `netstat -tulnp`), so the row list shows `tcp:3000 → node (12345)` per port; a port without a visible owner is marked `(unknown)`. The result is cached for 2 seconds so the live navigator refresh stays cheap. The full `alt+i` ports list shows the raw `ss -p` process column as well.
+
+### Fleet open-ports (SSH probe)
+
+`open_ports` is laptop-local by default. Set `powerline.segmentOptions.openPorts.host` to probe a named fleet host over SSH instead:
+
+```json
+{
+  "powerline": {
+    "segmentOptions": {
+      "openPorts": { "host": "sofie" }
+    }
+  }
+}
+```
+
+`host` accepts a hostname, `user@host`, or IPv4 address (validated to prevent shell injection). The probe is best-effort: it runs `ssh` in `BatchMode` with a 3-second connect timeout, so it requires passwordless/agent SSH and the host to already be in `known_hosts`. When the probe can't run (no `ss`/`netstat` remotely, unreachable host, missing key), the segment shows `?` instead of a misleading `0`. The detail view and `alt+i` full list reuse the same remote probe.
+
+## Thinking level display
+
+The thinking segment shows live updates when you change thinking level:
+
+| Level | Display | Color |
+|-------|---------|-------|
+| off | `think:off` | gray |
+| minimal | `think:min` | purple-gray |
+| low | `think:low` | blue |
+| medium | `think:med` | teal |
+| high | `think:high` | rainbow |
+| xhigh | `think:xhigh` | rainbow |
+| max | `think:max` | rainbow |
+
+## Path display
+
+The path segment supports three modes:
+
+| Mode | Example | Description |
+|------|---------|-------------|
+| `basename` | `powerline-footer` | Just the directory name (default) |
+| `abbreviated` | `…/extensions/powerline-footer` | Full path with home abbreviated and length limit |
+| `full` | `~/.pi/agent/extensions/powerline-footer` | Complete path with home abbreviated |
+
+Configure via preset options: `path: { mode: "full" }`
+
+## Git polling
+
+By default the git segment polls both branch and dirty state. If background `git status --porcelain` calls interfere with your workflow, use branch-only polling:
+
+```json
+{
+  "powerline": {
+    "git": { "polling": "branch" }
+  }
+}
+```
+
+Use `"off"` to disable extension-owned git polling entirely and only show the branch reported by Pi when available.
+
+## Git host icon
+
+Set `git.hostIcon` to replace the branch icon with the origin remote's host logo:
+
+```json
+{
+  "powerline": {
+    "git": { "hostIcon": true }
+  }
+}
+```
+
+The origin remote is detected (SSH or HTTPS) and mapped to an icon: GitHub (`nf-fa-github`), GitLab (`nf-fa-gitlab`), Bitbucket (`nf-fa-bitbucket`), or a generic git logo (`nf-fa-git`) for any other remote (self-hosted, Gitea, Codeberg, …). Repositories without an origin remote keep the plain branch icon (`nf-fa-code_fork`), as do ASCII (non–Nerd Font) setups. The remote is read once and cached, so this adds no per-render cost. Default is `false` (branch icon unchanged).
+
+## Git status extras (commits, ahead/behind)
+
+The git segment can also show the last commit on `HEAD` (short hash + subject) and the upstream ahead/behind counts — handy for a quick "where am I relative to main" GitHub signal:
+
+- `git.showCommit` (`true` by default) — appends `#<hash> <subject>` for the latest commit.
+- `git.maxCommitSubjectLength` (`24`) — truncates the commit subject shown.
+- `git.showAheadBehind` (`true` by default) — appends `↑<n> ↓<n>` for commits ahead/behind the configured upstream (hidden when there is no upstream).
+
+```json
+{
+  "powerline": {
+    "git": { "showCommit": true, "showAheadBehind": true, "maxCommitSubjectLength": 24 }
+  }
+}
+```
+
+The `minimal` and `compact` presets keep these off to stay lean; set `showCommit: true`/`showAheadBehind: true` to enable them.
+
+## Segments
+
+`model` · `shell_mode` · `path` · `git` · `subagents` · `queue` · `token_in` · `token_out` · `token_total` · `cost` · `context_pct` · `context_total` · `time_spent` · `time` · `session` · `hostname` · `cache_read` · `cache_write` · `thinking` · `tps` · `open_ports` · `extension_statuses`
+
+## Separators
+
+`powerline` · `powerline-thin` · `slash` · `pipe` · `dot` · `chevron` · `star` · `block` · `none` · `ascii`
+
+## Theming
+
+Colors are configurable via pi's theme system. Each preset defines its own color scheme, and you can override individual colors and icons with a `theme.json` file in the extension directory.
+
+### Default colors
+
+| Semantic | Theme Color | Description |
+|----------|-------------|-------------|
+| `model` | `#d787af` | Model name |
+| `shellMode` | `accent` | Bash mode segment |
+| `path` | `#00afaf` | Directory path |
+| `gitClean` | `success` | Git branch (clean) |
+| `gitDirty` | `warning` | Git branch (dirty) |
+| `thinking` | `thinkingOff` | Thinking level (`off`) |
+| `thinkingMinimal` | `thinkingMinimal` | Thinking level (`minimal`) |
+| `thinkingLow` | `thinkingLow` | Thinking level (`low`) |
+| `thinkingMedium` | `thinkingMedium` | Thinking level (`medium`) |
+| `context` | `dim` | Context usage |
+| `contextWarn` | `warning` | Context usage >70% |
+| `contextError` | `error` | Context usage >90% |
+| `cost` | `text` | Cost display |
+| `tokens` | `muted` | Token counts |
+| `queue` | `accent` | Queue / ideas / blocked counts |
+| `separator` | `dim` | Segment separators and ahead/behind counts |
+| `border` | `borderMuted` | Panel/border chrome |
+
+### Custom theme override
+
+Create `extensions/powerline-footer/theme.json` in the agent dir (`~/.pi/agent` by default, or `PI_CODING_AGENT_DIR` when set):
+
+```json
+{
+  "colors": {
+    "model": "accent",
+    "shellMode": "accent",
+    "path": "#00afaf",
+    "gitClean": "success",
+    "thinking": "thinkingOff",
+    "thinkingMinimal": "thinkingMinimal",
+    "thinkingLow": "thinkingLow",
+    "thinkingMedium": "thinkingMedium"
+  },
+  "icons": {
+    "auto": "↯",
+    "warning": ""
+  }
+}
+```
+
+Colors can be:
+
+- **Theme color names**: `accent`, `muted`, `dim`, `text`, `success`, `warning`, `error`, `border`, `borderAccent`, `borderMuted`
+- **Hex colors**: `#ff5500`, `#d787af`
+
+Icons can be any string, including `""` when you want to suppress a specific glyph entirely.
+
+For npm package installs, this documented agent-dir file is separate from the package files under `~/.pi/agent/npm/node_modules`. The extension reads the agent-dir override first, then falls back to a `theme.json` colocated with the loaded extension file. Use `/reload` or restart Pi after creating or editing `theme.json`.
+
+See `theme.example.json` for all available options.

package/docs/skill-manager.md

@@ -0,0 +1,7 @@
+# Skill manager
+
+Browse and insert your installed skills (`SKILL.md` files and `*.md`/`*.txt` prompts) from an interactive TUI overlay:
+
+- **`/skills`** — open the skill manager. Filter with plain typing, `↑↓` to move, `enter` to open a skill's detail body, `↑↓` in the detail to scroll, `enter`/`tab` to insert the skill content into your prompt, `esc` to go back/close.
+
+The manager reuses the same skill discovery as inline `/command`/`$skill` triggers, so anything you can inline you can also browse and insert manually.