pi-editor-footer 0.1.0

package/AGENTS.md

@@ -0,0 +1,19 @@
+## Agent skills
+
+### Issue tracker
+
+Issues and specs live as GitHub issues, managed via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage roles use their default label names (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context — one `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+## Pi editor replacement — sync contract
+
+This extension **replaces pi's default input editor**: `TrackingEditor` (`src/tracking-editor.ts`) is the actual editor in the input box. It replicates pi's `CustomEditor` inline and observes the completion popup through two private pi-tui internals (`autocompleteList`, `applyAutocompleteSuggestions`).
+
+**Pi editor features are NOT inherited — on every pi update, or whenever pi changes or extends editor behaviour (keybindings, IME, autocomplete, border rendering), diff pi's `CustomEditor` and `Editor` against `src/tracking-editor.ts` and port the changes over.** The exact sources to diff, the internals to watch, and the pty verification loop are in `docs/reference/pi-tui-internals.md` ("Sync contract" section). Why the editor is replaced at all: ADR-0001 and ADR-0002.

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-20
+
+### Added
+
+- Full TUI theme `pi-editor-footer` rebuilt on `TrackingEditor`: project-aware footer (`cwd` · `git` • `runtime` left, `tokens` next to `context` right), model-info border glow top, live theme respect, detail window preserved
+- Cursor styles `block`/`bar`/`underline` with real-time preview and hardware cursor handling
+- Settings dialog `/pi-footer` (General/Appearance/Footer/Telemetry, `workspaceDisplay` path/name toggle, `enabled` restores default footer)
+- Git state engine (branch/ahead/behind + staged/modified/untracked/conflicted/stashed) and 10+ runtime detection via lockfiles
+- Telemetry bottom border (right-aligned, toggleable `tps`/`ttft`/`duration`/`tokens`/`stalls`/`cost`)
+- Bottom border clean (no `cwd`), footer single line with `•`/`·` separators
+
+### Changed
+
+- Renamed package `pi-skill-desc` → `pi-editor-footer` and `/pi-lsz-theme` → `/pi-footer` (removed `/theme` alias)
+- Footer now single line `cwd·git•runtime` left / `tokens·context` right; bottom border no longer shows `cwd`
+
+### Fixed
+
+- Cursor white background when switching styles and invisible cursor after switch — hardware cursor handling with `CURSOR_MARKER` preview
+- Footer `*` git icon removed, footer empty at startup until `readGitStatus` now populated, and disabled extension correctly restores default footer

package/CONTEXT.md

@@ -0,0 +1,29 @@
+# pi-skill-desc
+
+A pi coding-agent extension that augments the built-in slash-command completion with a full description preview for the highlighted candidate.
+
+## Language
+
+**Completion popup**:
+Pi's built-in slash-command tab-completion list (`/` + tab), which lists commands, tools, and skills with truncated descriptions.
+_Avoid_: autocomplete, picker
+
+**Candidate**:
+An item in the completion popup — a skill, a tool, or a slash command.
+_Avoid_: suggestion, entry, item
+
+**Detail window**:
+The extension's popup above the input box that mirrors the completion popup's highlight. Capped at 5 lines, scrollable with shift+up/down, showing the full description of the highlighted candidate.
+_Avoid_: description window, tooltip, preview
+
+**Highlight**:
+The row currently selected in the completion popup. The detail window mirrors it — cycling the highlight swaps the window's content.
+_Avoid_: selection, cursor
+
+**Editor slot**:
+The single custom-editor position in pi — the last `setEditorComponent` writer wins. pi-skill-desc must own it to observe the popup (ADR-0001, ADR-0002).
+_Avoid_: editor position, editor hook
+
+**TrackingEditor**:
+This extension's custom editor — the actual input editor in the box. Replaces pi's `CustomEditor` (replicated inline) and adds popup-highlight observation plus the model-info border glow.
+_Avoid_: custom editor, wrapper

package/README.md

@@ -0,0 +1,84 @@
+<h1 align="center">pi-editor-footer</h1>
+
+<p align="center">A pi TUI theme — project-aware footer, model border, and skill detail window.</p>
+
+A [pi](https://pi.dev) extension that turns the editor chrome into a project-aware theme while preserving the skill-description detail window. It owns pi's single custom-editor slot via `TrackingEditor` and renders entirely against pi's live theme (no hardcoded colors).
+
+## Features
+
+**Detail window** — bordered window above the input that mirrors the completion popup's highlight and shows the candidate's full description (wrapped at `width − 4`, cap 5 lines, `…` ellipsis, `offset/total` header, shrinks when empty). Lifecycle mirrors the popup (opens/closes with it); hidden for candidates without a description. Scroll with **shift+up/down** (fallback **alt+j/k**).
+
+**Model border** — top border shows `provider/model · thinking · contextWindow` with thinking-level glow via `getThinkingBorderColor`. Toggle with `/model-info` (off restores pi's stock border).
+
+**Footer** — single line below the input, responsive via `fitSegmentsByPriority` and `alignRight`:
+- Left: `cwd` (`·` `git branch` + status `[! ? + ↑↓]` + stashed/conflicted) `•` `runtime` (`node`/`python`/`rust`/`go`… + version) `•` `timer` (`working`/`done`)
+- Right: `tokens` (` input |  output |  $cost`) immediately next to `context` (` [bar] % · tokens/contextWindow`)
+- Separators: `·` between `cwd` and `git`, `•` as default between other left components; `tokens` sits directly left of the context bar
+- `cwd` respects `workspaceDisplay` (`~/development/ai/pi-skill-desc` vs `pi-skill-desc`, switchable in settings)
+- `context` bar uses `stressColor` and `renderBar` (12 cols max) with `•`/`·` handling
+- Extension statuses line (`wrapTextWithAnsi`) when `footerSegments.extensionStatuses`
+
+All segments are toggleable via `footerSegments` (`cwd`, `sessionName`, `gitBranch`, `gitStatus`, `gitCommit`, `runtime`, `context`, `tokens`, `cost`, `extensionStatuses`). Footer is installed via `ctx.ui.setFooter` when available, fallback to `setWidget("theme-footer", …, {placement:"belowEditor"})`, and is fully removed when the extension is disabled (`enabled: false` restores pi's default footer).
+
+**Cursor** — `block` (software reverse, `setShowHardwareCursor(false)`), `bar` (`\x1b[6 q`), `underline` (`\x1b[4 q`) with hardware cursor (`setShowHardwareCursor(true)`). Style is previewed in real time: when the settings overlay is open (`!focused` + `previewHardwareCursor`), the software cursor ` \x1b[7m…\x1b[0m` is replaced with `CURSOR_MARKER` so the layout shows the hardware shape instantly; when focused the software cursor is removed and the hardware sequence is written.
+
+**Input border** — bottom border is kept clean (no `cwd`); right side shows telemetry when `telemetry.enabled` (`TPS`, `TTFT`, `duration`, `tokens`, `stalls`, `cost` via `TurnTelemetryTracker`).
+
+**Config** — single JSON `~/.pi/agent/pi-skill-desc.json` (validated at load, `DEFAULT_CONFIG` with `enabled:true`, `workspaceDisplay:"path"`, `cursorStyle:"block"`, `icons:"auto"`, all `footerSegments`/`telemetry` on). Settings dialog `/pi-footer` (General/Appearance/Footer/Telemetry, English, `Tab`/`↑↓`/`Enter`/`Esc`) live-edits and persists via `saveConfig`, with `cursorStyle` and `enabled` applying instantly and `workspaceDisplay` switching `cwd` format.
+
+## Quick start
+
+```bash
+pi -e ./src/index.ts
+```
+
+Type `/` → popup opens, detail window appears above input, header shows model top, footer shows `cwd · git • runtime` left and `tokens  context` right. `/pi-footer` opens settings; `/model-info` toggles border glow.
+
+## Why you need this
+
+The native popup truncates long skill descriptions mid-sentence; the detail window shows the full text without guessing. The native footer shows only context; this footer adds the project context you actually need — which branch, how many files changed, which runtime, how many tokens — while keeping the context bar for the limit.
+
+## Breakage mode
+
+Highlight tracking observes two private `pi-tui` internals (`autocompleteList`, `applyAutocompleteSuggestions` per ADR-0001). At load it asserts both and warns `[pi-skill-desc] pi-tui internals changed…` if pi renames them; the window then never appears rather than showing wrong content. Single editor slot ownership is per ADR-0002.
+
+## Manual verification
+
+1. `pi -e ./src/index.ts` (or `pi -ne -e ./src/index.ts` to isolate)
+2. `/` → tab through candidates, detail window follows; `shift+down` scrolls long text
+3. Footer: `cwd` (`·` `git`) `•` `runtime` left, `tokens` right next to `[bar] %` right; `/pi-footer` → General → `Workspace display` toggles `~/…/pi-skill-desc` vs `pi-skill-desc`
+4. Cursor: `/pi-footer` → General → `Cursor style` cycles `block`/`bar`/`underline`, shape updates in real time (bar shows `|`, underline `_`)
+5. Disable: `/pi-footer` → General → `Enabled: Off` → footer reverts to pi's default (relative time / model); re-enable restores theme
+
+## Project structure
+
+```
+pi-editor-footer/
+├── src/
+│   ├── index.ts               # extension entry, widget/header/footer install, /model-info
+│   ├── tracking-editor.ts     # TrackingEditor (Editor slot, highlight, border, cursor)
+│   ├── footer.ts              # renderFooter / installFooter (cwd·git • runtime • tokens·context)
+│   ├── header.ts              # header disabled, cwd preserved in footer
+│   ├── detail-render.ts       # wrap/scroll/ellipsis (tested)
+│   ├── window-presentation.ts # bordered themed box (tested)
+│   ├── model-info.ts          # top border glow+label
+│   ├── git.ts                 # readGitStatus (branch/ahead/behind + staged/modified/...)
+│   ├── runtime.ts             # readRuntimeInfo (node/python/rust/go/… via lockfiles)
+│   ├── telemetry.ts           # TurnTelemetryTracker + formatTurnTelemetry
+│   ├── config.ts              # ThemeConfig + load/save
+│   ├── theme-settings.ts      # /pi-footer dialog
+│   └── state.ts               # FooterState
+├── test/
+└── docs/
+    ├── adr/0001-tracking-editor-for-skill-descriptions.md
+    └── adr/0002-own-editor-slot-port-model-info-glow.md
+```
+
+## Development
+
+- `npm test` — `node:test` + `tsx` (87 cases)
+- `npm run typecheck` — strict TS
+
+## License
+
+No license declared yet; all rights reserved. (Private repository.)

package/docs/adr/0001-tracking-editor-for-skill-descriptions.md

@@ -0,0 +1,18 @@
+# Track the native completion popup's highlight via a custom editor
+
+Pi's extension API exposes no event for which row is selected in the built-in slash-command completion popup, yet the goal is a detail window that mirrors that highlight as the user cycles. We install a custom editor — `TrackingEditor`, a subclass of pi-tui's exported `Editor` replicating the app's `CustomEditor` — that keeps the native popup untouched and observes its selection through `SelectList.onSelectionChange` (a public callback the editor leaves unwired), plus one instance-level patch on the private `applyAutocompleteSuggestions` to re-hook the list when suggestions refresh. The detail window renders via `setWidget(..., { placement: "aboveEditor" })`; `shift+up` / `shift+down` (unbound keys) scroll long descriptions.
+
+Status: accepted
+
+## Considered Options
+
+- **Own picker overlay** (`ctx.ui.custom` with a candidate list + detail pane): rejected — the user explicitly does not want a finder/picker; the native `/`+tab flow must be augmented, not replaced.
+- **Data-only autocomplete provider wrapper**: rejected — `addAutocompleteProvider` supplies items but no selection-change signal, so a detail window could not follow the highlight.
+- **Reading the selection via runtime casts into private fields**: chosen — the only path that preserves the native flow; the blast radius is two internals (`autocompleteList` field, `applyAutocompleteSuggestions` method), and failures are loud (the patch stops firing), never silently wrong.
+
+## Consequences
+
+- The extension reaches into two private pi-tui internals; a rename upstream breaks it loudly and needs a one-line fix.
+- Terminal support for modified-arrow sequences (Kitty protocol) is required for shift+up/down to be distinct from plain arrows; legacy terminals will alias them.
+- Tools are not covered — the `/` completion popup lists slash commands, templates, extension commands, and skills only.
+- Description data needs no catalog lookups: the popup's `SelectItem` carries the full (non-truncated) description.

package/docs/adr/0002-own-editor-slot-port-model-info-glow.md

@@ -0,0 +1,18 @@
+# Own the single editor slot; port model-info-widget's border glow
+
+Pi allows exactly one custom input editor — the last `setEditorComponent` writer wins. The user's `model-info-widget` extension also installs one on `session_start`, and its handler ran after ours, silently replacing the TrackingEditor and killing the detail window ("no popup" — the extension's render was never even called). We defer our install (`setTimeout 0`, after every other extension's synchronous `session_start` handler) plus a 1s watchdog that re-asserts ownership whenever the focused input editor is not ours, and we ported model-info-widget's border glow/label rendering into `src/model-info.ts` so its visual behavior survives even though its own editor install is now inert.
+
+Status: accepted
+
+## Considered Options
+
+- **Let model-info-widget keep the slot**: impossible — highlight tracking must live on the owning editor; there is no API to observe the popup from outside.
+- **Defer our install only**: fragile against other deferring extensions; the watchdog makes slot ownership self-healing.
+- **Watchdog only**: works, but the first second of every session would run with the wrong editor.
+- **Port the glow (chosen)**: keeps both features without touching model-info-widget's files; the port is self-contained (color math + label rendering, verbatim from the original).
+
+## Consequences
+
+- model-info-widget's editor install is now inert; its rendering lives in `src/model-info.ts`, and its `/model-info` toggle is reimplemented by pi-skill-desc's own `/model-info` command — so the widget can be deleted from `~/.pi/agent/extensions/`.
+- Intentional code duplication with model-info-widget; a future cleanup could merge the extensions.
+- The watchdog only fights input editors (CustomEditor duck-type: `actionHandlers` is a `Map`) — selectors, dialogs, and overlays are never disturbed.

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`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 any of these files 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 (most repos):
+
+```
+/
+├── 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 `CONTEXT.md`. 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…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/docs/reference/pi-tui-internals.md

@@ -0,0 +1,144 @@
+# pi-tui internals reference (verified against installed packages)
+
+Implementation reference for the Detail-window extension. All facts below were verified by reading the **installed** packages on 2026-08-16:
+
+- `@earendil-works/pi-coding-agent` — dist types + interactive-mode source
+- `@earendil-works/pi-tui` **v0.84.2** — dist source
+
+Pin dev dependency `@earendil-works/pi-tui@0.84.2` for types. The extension imports at runtime only from `@earendil-works/pi-tui` (pi provides it).
+
+## Extension model
+
+- Extensions are TypeScript modules with a **default-exported factory**: `export default function (pi: ExtensionAPI): void | Promise<void>`.
+- Auto-discovered from `~/.pi/agent/extensions/` or `.pi/extensions/` (project), or `pi -e ./path.ts`.
+- `ExtensionAPI` members used here: `registerShortcut(KeyId, {description?, handler(ctx)})`, `on(event, handler)`, `getAllTools()`, `getCommands()`.
+- Event handlers receive `ctx: ExtensionContext` with `ctx.ui: ExtensionUIContext` and `ctx.mode` (`"tui"` guards terminal-only UI).
+
+## ExtensionUIContext members (verified in dist/core/extensions/types.d.ts)
+
+- `setWidget(key, content, options?)` where `content` is `string[]` or a component factory `(tui, theme) => Component & {dispose?()}`; `options.placement: "aboveEditor" | "belowEditor"` (default aboveEditor).
+- `setStatus(key, text | undefined)` — status/footer text.
+- `custom<T>(factory, {overlay?, overlayOptions?, onHandle?})` — focus-taking overlay (not used by this extension).
+- `onTerminalInput(handler): unsubscribe` — raw keystrokes before the focused component; `{consume}` / `{data}`.
+- `setEditorComponent(factory | undefined)` where `factory = (tui, theme, keybindings) => EditorComponent`.
+- `addAutocompleteProvider(factory)` — stacks on the built-in provider (data only; no selection signal).
+
+## The editor contract (pi-tui EditorComponent)
+
+`EditorComponent` interface: `getText()/setText()/handleInput(data)/onSubmit?/onChange?/addToHistory?/insertTextAtCursor?/getExpandedText?/setAutocompleteProvider?/borderColor?/setPaddingX?/setAutocompleteMaxVisible?`.
+
+`Editor` class is **exported** from `@earendil-works/pi-tui`: `constructor(tui, theme, options?: EditorOptions)`; `EditorOptions = { paddingX?, autocompleteMaxVisible? }`. Public methods used: `getText()`, `setText()`, `isShowingAutocomplete()`, `onSubmit`, `onChange`, `setAutocompleteProvider`, `handleInput`.
+
+## How pi's CustomEditor works (replicate exactly)
+
+pi's interactive mode uses `CustomEditor extends Editor` (`dist/modes/interactive/components/custom-editor.js`). Full source:
+
+```ts
+import { Editor } from "@earendil-works/pi-tui";
+
+export class CustomEditor extends Editor {
+    keybindings;
+    actionHandlers = new Map();
+    onEscape;
+    onCtrlD;
+    onPasteImage;
+    /** Handler for extension-registered shortcuts. Returns true if handled. */
+    onExtensionShortcut;
+    constructor(tui, theme, keybindings, options) {
+        super(tui, theme, options);
+        this.keybindings = keybindings;
+    }
+    onAction(action, handler) { this.actionHandlers.set(action, handler); }
+    handleInput(data) {
+        if (this.onExtensionShortcut?.(data)) return;
+        if (this.keybindings.matches(data, "app.clipboard.pasteImage")) { this.onPasteImage?.(); return; }
+        if (this.keybindings.matches(data, "app.interrupt")) {
+            if (!this.isShowingAutocomplete()) {
+                const handler = this.onEscape ?? this.actionHandlers.get("app.interrupt");
+                if (handler) { handler(); return; }
+            }
+            super.handleInput(data);
+            return;
+        }
+        if (this.keybindings.matches(data, "app.exit")) {
+            if (this.getText().length === 0) {
+                const handler = this.onCtrlD ?? this.actionHandlers.get("app.exit");
+                if (handler) handler();
+                return;
+            }
+        }
+        if (this.keybindings.matches(data, "tui.editor.historyPrevious") ||
+            this.keybindings.matches(data, "tui.editor.historyNext")) {
+            super.handleInput(data);
+            return;
+        }
+        for (const [action, handler] of this.actionHandlers) {
+            if (action !== "app.interrupt" && action !== "app.exit" && this.keybindings.matches(data, action)) {
+                handler();
+                return;
+            }
+        }
+        super.handleInput(data);
+    }
+}
+```
+
+## setEditorComponent wiring (dist/modes/interactive/interactive-mode.js `setCustomEditorComponent`)
+
+The factory is called `factory(this.ui, getEditorTheme(), this.keybindings)`. After creation, interactive mode **duck-types**: if the new editor has an `actionHandlers` property that is a `Map`, it copies all app-level handlers onto it — `onEscape`, `onCtrlD`, `onPasteImage`, `onExtensionShortcut` (falling back to the default editor's), and every entry of the default editor's `actionHandlers` map. It also wires `onSubmit`, `onChange`, copies text and appearance, and calls `setAutocompleteProvider` when supported.
+
+→ A custom editor with `actionHandlers = new Map()` + `onAction(action, handler)` + the fields above behaves identically to the default editor.
+
+## The autocomplete popup internals (pi-tui components/editor.js + components/select-list.js)
+
+- The popup is a `SelectList` stored in the private field **`autocompleteList`**.
+- The list is (re)created in the private method **`applyAutocompleteSuggestions(suggestions, state)`** — the only construction site:
+
+  ```ts
+  applyAutocompleteSuggestions(suggestions, state) {
+      this.autocompletePrefix = suggestions.prefix;
+      this.autocompleteList = this.createAutocompleteList(suggestions.prefix, suggestions.items);
+      const bestMatchIndex = this.getBestAutocompleteMatchIndex(suggestions.items, suggestions.prefix);
+      if (bestMatchIndex >= 0) this.autocompleteList.setSelectedIndex(bestMatchIndex);
+      this.autocompleteState = state;
+  }
+  ```
+
+- `clearAutocompleteUi()` sets `autocompleteList = undefined`, `autocompleteState = null`.
+- Editor `handleInput` delegates to `this.autocompleteList.handleInput(data)` while the popup is open (up/down/tab/enter).
+- `SelectList` is exported from pi-tui. Public members: `onSelectionChange?: (item: SelectItem) => void` (**left unwired by the editor — ours to use**), `getSelectedItem(): SelectItem | null`, `setSelectedIndex(index)`, `handleInput(keyData)`, `render(width)`, `setFilter(filter)`.
+- `SelectList.handleInput` fires `notifySelectionChange()` on up/down (wraps around), which calls `onSelectionChange(selectedItem)`. Programmatic `setSelectedIndex` (initial best-match) does **not** fire it — read `getSelectedItem()` after wiring.
+- `SelectItem = { value, label, description? }` — the description is the **full, untruncated** text (truncation is display-only). Slash-command items carry `description`; file-completion items may not.
+
+**Tracking recipe**: subclass `Editor`; in the constructor, instance-patch `applyAutocompleteSuggestions` (cast to `any` — TS-private) so that after each `super.applyAutocompleteSuggestions(...)` call you wire `list.onSelectionChange` on the fresh list and emit the current `getSelectedItem()`; in an overridden `handleInput`, call `super.handleInput(data)` then read `(this as any).autocompleteList` — wire if new, and emit `getSelectedItem()` (or `null` when the popup is closed, i.e. the field is undefined). Emit through a public `onHighlight?: (item: SelectItem | null) => void` property.
+
+**Blast radius (ADR-0001)**: two internal names — `autocompleteList` (field) and `applyAutocompleteSuggestions` (method). Verify both exist at extension load and warn loudly if not.
+
+## Keybindings
+
+- `pi.registerShortcut(shortcut: KeyId, {description?, handler(ctx)})`; `KeyId` strings like `"shift+up"`, `"shift+down"`.
+- `shift+up` / `shift+down` are **unbound** in pi's defaults and not in the reserved list → free to register. (`ctrl+shift+up/down` = alt-screen prompt nav, `alt+up` = dequeue — avoid.)
+- Conflict policy: reserved keys are silently skipped with a warning; non-reserved bound keys are overridden with a warning; unbound keys are clean.
+- `matchesKey(data, "shift+up")` handles Kitty modified-arrow sequences (`\x1b[1;2A`). Terminals without modified-arrow reporting alias shift+arrows to plain arrows — scroll degrades to no-op.
+
+## Data
+
+- The completion popup lists slash commands, templates, extension commands, and skills (`skill:<name>`, description = SKILL.md frontmatter, prefixed with source info). **Tools never appear** — they are agent-invoked, not slash-invocable.
+- No catalog lookups needed: the highlighted `SelectItem` carries its own full description.
+
+## Sync contract — keeping the editor current with pi updates
+
+This extension **replaces pi's default input editor** via `setEditorComponent`. `TrackingEditor` (`src/tracking-editor.ts`) is the actual editor in the input box: it replicates pi's `CustomEditor` inline and reads two private pi-tui internals — so **pi editor changes are NOT inherited automatically.** On every pi update, and whenever pi adds or changes editor behaviour, sync manually:
+
+1. **Diff the replicated base.** Compare pi's `CustomEditor` (`dist/modes/interactive/components/custom-editor.js` in `@earendil-works/pi-coding-agent` — source in the "How pi's CustomEditor works" section above) and pi-tui's `Editor` (`components/editor.js` in `@earendil-works/pi-tui`) against `src/tracking-editor.ts`: port any new/changed app-keybinding branches, fields, or methods in `handleInput`; keep the highlight-sync additions after each `super.handleInput(data)`.
+2. **Check the private internals.** Confirm `autocompleteList` and `applyAutocompleteSuggestions` still exist with the same names on pi-tui's `Editor`. The load-time `assertInternals()` in `src/index.ts` warns if they vanish — if it warns, fix the tracking in `src/tracking-editor.ts`, don't silence the warning.
+3. **Verify live** with the scripted pty loop (the only seam for the editor wiring): from the repo root,
+   `(sleep 18; printf '/'; sleep 1.5; printf '\033[B'; sleep 2; printf '\033'; sleep 2) | timeout 45 script -q /tmp/psd.log pi -e ./src/index.ts --no-session`,
+   then grep `/tmp/psd.log` for the bordered detail window (`┌…┐`, `· command`/`· skill` rows) following the highlight. Add `sh -c 'stty cols 40; …'` around the command for a narrow terminal that triggers the scroll/ellipsis paths.
+4. **Regression:** `npm test` (renderer/presentation seams) and `npm run typecheck` must stay green.
+
+The replacement itself is deliberate — see ADR-0001 (why the popup internals are read) and ADR-0002 (why we own the editor slot).
+
+## Glossary / decisions
+
+See `CONTEXT.md` (Completion popup, Candidate, Detail window, Highlight) and `docs/adr/0001-tracking-editor-for-skill-descriptions.md` (accepted) before implementing.

package/docs/specs/01-config.md

@@ -0,0 +1,57 @@
+# Spec 01 — Config Schema & Persistence
+
+Ticket: #7 · Type: grilling (HITL) · Branch: `feat/config`
+
+## Question
+
+What is the single config contract every subsystem reads?
+
+## Decision
+
+- File: `~/.pi/agent/pi-skill-desc.json` (keep existing name for backward compat; identity rename may add alias — decide in #6).
+- Shape:
+
+```ts
+export type WorkspaceDisplay = "path" | "name";
+export type CursorStyle = "block" | "bar" | "underline";
+export type IconMode = "auto" | "nerd" | "ascii";
+
+export interface ThemeConfig {
+  enabled: boolean;
+  workspaceDisplay: WorkspaceDisplay;
+  cursorStyle: CursorStyle;
+  icons: { mode: IconMode };
+  telemetry: {
+    enabled: boolean;
+    tps: boolean;
+    ttft: boolean;
+    duration: boolean;
+    tokens: boolean;
+    stalls: boolean;
+    cost: boolean;
+  };
+  footerSegments: {
+    cwd: boolean;
+    sessionName: boolean;
+    gitBranch: boolean;
+    gitStatus: boolean;
+    gitCommit: boolean;
+    runtime: boolean;
+    context: boolean;
+    tokens: boolean;
+    cost: boolean;
+    extensionStatuses: boolean;
+  };
+}
+```
+
+- Defaults mirror `tmp/pi-open-tui` DEFAULT_CONFIG except `workspaceDisplay` defaults to `"path"`, `icons.mode` to `"auto"`.
+- Helpers: `loadConfig()`, `saveConfig(patch)`, `DEFAULT_CONFIG`, validation (Zod or manual) at admission boundary; typed inside.
+- Live reload: `saveConfig` writes file + notifies `requestRender` / re-apply cursor/style.
+
+## Acceptance
+
+- [ ] `src/config.ts` exists, typed, validated at load, with `loadConfig`/`saveConfig`/`DEFAULT_CONFIG`
+- [ ] Malformed file falls back to defaults with warning, never crashes
+- [ ] `workspaceDisplay` controls header/footer cwd rendering (consumers read it)
+- [ ] `npm run typecheck` passes, unit test for load/save + defaults

package/docs/specs/02-identity.md

@@ -0,0 +1,20 @@
+# Spec 02 — Theme Identity & Rename
+
+Ticket: #6 · Type: grilling · Branch: `feat/identity`
+
+## Question
+
+What does the renamed theme call itself and how does rename land?
+
+## Decision
+
+- Display name: `pi-tui-theme` (proposed) or keep `pi-skill-desc` with theme description — owner picks via grilling.
+- `package.json` `name` stays `pi-skill-desc` for now (avoid registry churn); `description` and README header change to theme framing.
+- Command: keep `/model-info` for compat, add `/theme` (lightweight English dialog) that subsumes it. Old command delegates to new.
+- Install path `~/.pi/agent/extensions/pi-skill-desc` unchanged; future rename is a symlink alias, not a break.
+
+## Acceptance
+
+- [ ] README header reflects theme identity, install still works via existing path
+- [ ] `/theme` command exists (even if dialog lands later — stub with notify)
+- [ ] No break for users symlinked to old path

package/docs/specs/03-border-telemetry.md

@@ -0,0 +1,48 @@
+# Spec 03 — Editor Border: Model-Label Top + Telemetry Bottom Right (+ Telemetry Engine + Cursor)
+
+Tickets: #8 (prototype), #12 (telemetry engine), #11 (cursor) · Branches: `feat/border-telemetry`, `feat/cursor` (may merge)
+
+## Questions
+
+- How do model label (top) and telemetry (bottom right) share the editor border?
+- What pi events produce the six measurements?
+- How do cursor styles fold into TrackingEditor?
+
+## Decisions
+
+### Border Layout
+
+- `TrackingEditor.render(width)` decorates `super.render(width)` lines:
+  - Top border hosts model-info label + thinking glow (`applyModelInfo` preserved, reads live `Theme` via `getLiveTheme()`).
+  - Bottom border hosts telemetry segment right-aligned, theme-respecting, truncated with `truncateToWidth`.
+  - Both survive narrow widths: left truncated first, right telemetry priority.
+- Model top and telemetry bottom do not collide — prototype sketch required for sign-off.
+
+### Telemetry Engine
+
+Rebuild `tmp/pi-open-tui/extensions/open-tui/telemetry.ts` bespoke:
+
+```ts
+class TelemetryTracker {
+  handle(event: TelemetryEvent): TurnTelemetry | undefined
+}
+```
+
+- Events: `agent_start`, `turn_start`, `message_start`, `message_update`, `message_end`, `turn_end`, `agent_settled`, `tool_execution_start`.
+- Metrics: `tps` (output tokens / generationMs), `ttftMs`, `totalMs`, `inputTokens/outputTokens`, `stallCount/stallMs` (stall = gap > 1000ms between updates), `costUsd` + `rateUsdPerMTokens` from `usage.cost.total`.
+- Provider seam: tracker exposes `getLastTelemetry(): TurnTelemetry | null` for border + footer.
+- Theme glyphs via `icons.mode` (`resolveGlyphs`).
+
+### Cursor Styles
+
+- Fold `tmp/pi-open-tui/.../editor.ts` cursor logic into `TrackingEditor`:
+  - `cursorStyle: "block"` (default, software cursor), `"bar"` (`\x1b[6 q`, hardware cursor), `"underline"` (`\x1b[4 q`).
+  - `setCursorStyle(style)` + `config.cursorStyle` wiring.
+  - Bar/underline suppress software cursor marker, enable `tui.setShowHardwareCursor(true)`, write sequence.
+
+## Acceptance
+
+- [ ] `src/telemetry.ts` pure tracker with unit tests (TPS/TTFT/stall maths, fixtures)
+- [ ] `TrackingEditor` supports `cursorStyle`, toggled via config, no break to highlight tracking
+- [ ] Border renders model top + telemetry bottom-right, respects live theme, truncates correctly
+- [ ] `npm run typecheck` + `npm test` pass

package/docs/specs/04-header.md

@@ -0,0 +1,30 @@
+# Spec 04 — Header: cwd + Hints (No Model)
+
+Ticket: #9 · Type: grilling · Branch: `feat/header`
+
+## Question
+
+What does the header contain and where does it sit, given the border already owns model/thinking and the detail window already lives above the editor?
+
+## Decision
+
+- Content: `cwd` (honouring `workspaceDisplay: "path" | "name"`) + slash-command hints. **No model/thinking** — border owns it.
+- `cwd`: `formatCwd(cwd)` when `workspaceDisplay==="path"`, `basenamePath(formatCwd(cwd))` when `"name"`. Truncated via `truncatePath` at narrow widths.
+- Hints: 2–3 slash-command tips (e.g. `/theme`, `/model-info`) via `pickSlashCommandTips` or static list; dimmed.
+- Placement: `setWidget("theme-header", ..., {placement:"aboveEditor"})`, always on when `config.enabled`. Must not overlap detail window: header renders first, detail window renders above editor but below header (or header is topmost). Use TUI widget ordering.
+- Theme: reads live `Theme`, glyphs via `icons.mode` (`resolveGlyphs`), respects `theme.fg("dim")` for hints.
+
+## Reference
+
+- `tmp/pi-open-tui/extensions/open-tui/header.ts` (~200 lines, logo + cwd + hints)
+- `tmp/pi-open-tui/extensions/open-tui/utils.ts` (`formatCwd`, `basenamePath`, `truncatePath`, `pickSlashCommandTips`)
+- `tmp/pi-open-tui/extensions/open-tui/icons.ts`
+
+Rebuild bespoke, simplify: no animated logo (defer to fog), just cwd + hints line(s).
+
+## Acceptance
+
+- [ ] `src/header.ts` exports `installHeader` / `renderHeader` with cwd + hints, workspaceDisplay-aware
+- [ ] Respects live theme + icon mode
+- [ ] No overlap with detail window when popup open
+- [ ] `npm run typecheck` + `npm test` pass (pure render unit test)