# Commands & interactivity

## Usage

Activates automatically. Toggle with `/signal` (alias `/powerline`). Switch layouts with `/signal <name>`. `/signal menu` opens Navigate / Configure / Status. `/wishcraft` opens the Deck; `/wishcraft settings` is the flat list. Move the primary row with `/signal 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 idea-review overlay (status, tags, run with skill)
- `/ideas next`: send the oldest active idea that is not review-done
- `/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`, optional `error`, and for ideas optional `reviewStatus` (`idea` | `in-progress` | `done`) and `tags`. Legacy lines without those fields still parse. 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. `/ideas` opens the review overlay (same chrome as `/skills`): set review status and tags, or **Run with skill X** to insert the skill body plus the idea into the editor. The welcome queue widget shows the next idea and `/ideas next`; welcome dismisses on any key, so that widget does not bind enter-to-send. `/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, breathing state rail, session age, TPS in/out, protocol-labelled open ports, generated tokens, cache, budget, subagent cost |

**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`: 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, 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

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).