@nklisch/pi-enhanced 0.1.0

package/node_modules/@juicesharp/rpiv-ask-user-question/view/tab-content-strategy.ts

@@ -0,0 +1,250 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, type Input, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { t } from "../state/i18n-bridge.js";
+import { formatAnswerScalar } from "../tool/format-answer.js";
+import type { QuestionData } from "../tool/types.js";
+import type { PreviewPane, PreviewPaneProps } from "./components/preview/preview-pane.js";
+import {
+	type DialogState,
+	HINT_PART_CANCEL,
+	HINT_PART_COLLAPSE,
+	HINT_PART_ENTER,
+	HINT_PART_NAV,
+	HINT_PART_NOTES,
+	HINT_PART_TAB,
+	HINT_PART_TOGGLE,
+	INCOMPLETE_WARNING_PREFIX,
+	READY_PROMPT,
+	REVIEW_HEADING,
+} from "./dialog-builder.js";
+import type { StatefulView } from "./stateful-view.js";
+import type { TabComponents } from "./tab-components.js";
+
+const NOTES_HEADER = "Notes:";
+
+/**
+ * Single-row, width-clipped chrome cell. The footer row count is invariant
+ * (`QuestionTabStrategy.footerRowCount = 2`) — pi-tui's `Text` word-wraps when
+ * the styled hint exceeds `width`, inflating that row count and desyncing the
+ * `bodyHeight + footerRowCount` math in `DialogView.render`. Clipping with
+ * `truncateToWidth` (ANSI-aware, matches `multi-select-view.ts` usage) keeps
+ * the hint on one line; the collapse affordance falls off the right edge with
+ * `…` on terminals too narrow to advertise it.
+ */
+class OneLineClippedText implements Component {
+	constructor(
+		private readonly text: string,
+		private readonly paddingLeft: number = 0,
+	) {}
+
+	render(width: number): string[] {
+		const pad = " ".repeat(this.paddingLeft);
+		const avail = Math.max(0, width - this.paddingLeft);
+		return [pad + truncateToWidth(this.text, avail, "…", false)];
+	}
+
+	invalidate(): void {}
+
+	handleInput(_data: string): void {}
+}
+
+/**
+ * Per-tab content provider. Pure functional — closes over construction-time
+ * config; per-tick state threads through method args. The chrome wrapper
+ * enforces height equality across tabs via `bodyHeight + footerRowCount`.
+ */
+export interface TabContentStrategy {
+	/** Total RENDERED footer rows — MUST equal what `footerRows()` actually emits. Drives residual math. */
+	readonly footerRowCount: number;
+
+	/** Variable rows above the body, after top chrome (border + tabBar + Spacer). */
+	headingRows(state: DialogState): Component[];
+
+	/** Body Component placed at the body slot. */
+	bodyComponent(state: DialogState): Component;
+
+	/** Natural rendered height of `bodyComponent(state)` at given width. */
+	bodyHeight(width: number, state: DialogState): number;
+
+	/** Optional rows between body's trailing Spacer and the bottom border. */
+	midRows(state: DialogState): Component[];
+
+	/** Footer rows below the bottom border. Rendered row count MUST equal `footerRowCount`. */
+	footerRows(state: DialogState): Component[];
+
+	/** Row range of the focused item within the body's rendered output, or undefined if no interactive focus. */
+	focusedItemRowRange(width: number, state: DialogState): [number, number] | undefined;
+}
+
+export interface QuestionTabStrategyConfig {
+	theme: Theme;
+	questions: readonly QuestionData[];
+	getPreviewPane: () => StatefulView<PreviewPaneProps>;
+	tabsByIndex: ReadonlyArray<TabComponents>;
+	notesInput: Input;
+	isMulti: boolean;
+	getCurrentBodyHeight: (width: number) => number;
+}
+
+export class QuestionTabStrategy implements TabContentStrategy {
+	/** Spacer(1) + OneLineClippedText(hint, 1) = 2 rendered rows. */
+	readonly footerRowCount = 2;
+
+	constructor(private readonly config: QuestionTabStrategyConfig) {}
+
+	headingRows(state: DialogState): Component[] {
+		const out: Component[] = [];
+		const question = this.config.questions[state.currentTab];
+		// In multi-question mode the tab bar already shows the header; suppress the inline badge.
+		if (!this.config.isMulti && question?.header && question.header.length > 0) {
+			out.push(new Text(this.config.theme.bg("selectedBg", ` ${question.header} `), 1, 0));
+			out.push(new Spacer(1));
+		}
+		if (question) {
+			out.push(new Text(this.config.theme.bold(question.question), 1, 0));
+			out.push(new Spacer(1));
+		}
+		return out;
+	}
+
+	bodyComponent(state: DialogState): Component {
+		const question = this.config.questions[state.currentTab];
+		const mso = this.config.tabsByIndex[state.currentTab]?.multiSelect;
+		if (question?.multiSelect === true && mso) return mso;
+		return this.config.getPreviewPane();
+	}
+
+	bodyHeight(width: number, _state: DialogState): number {
+		return this.config.getCurrentBodyHeight(width);
+	}
+
+	midRows(state: DialogState): Component[] {
+		if (!state.notesVisible) return [];
+		return [
+			new Text(this.config.theme.fg("muted", t("notes.header", NOTES_HEADER)), 1, 0),
+			this.config.notesInput,
+			new Spacer(1),
+		];
+	}
+
+	footerRows(state: DialogState): Component[] {
+		const question = this.config.questions[state.currentTab];
+		// OneLineClippedText (not pi-tui `Text`) — `buildHintText` includes the collapse
+		// affordance, pushing the rendered string past 80 columns; `Text` would wrap and
+		// break the strategy's `footerRowCount = 2` invariant. Clipping on narrow terminals
+		// drops the trailing parts (collapse hint first, then cancel) with `…`.
+		return [
+			new Spacer(1),
+			new OneLineClippedText(this.config.theme.fg("dim", buildHintText(question, this.config.isMulti, state)), 1),
+		];
+	}
+
+	focusedItemRowRange(width: number, state: DialogState): [number, number] | undefined {
+		const question = this.config.questions[state.currentTab];
+		const mso = this.config.tabsByIndex[state.currentTab]?.multiSelect;
+		if (question?.multiSelect === true && mso) return mso.focusedItemRowRange(width);
+		return (this.config.getPreviewPane() as unknown as PreviewPane).focusedItemRowRange(width);
+	}
+}
+
+export interface SubmitTabStrategyConfig {
+	theme: Theme;
+	questions: readonly QuestionData[];
+	submitPicker: Component | undefined;
+}
+
+export class SubmitTabStrategy implements TabContentStrategy {
+	/** Spacer(1) + Text(prompt, 1) + Spacer(1) + submitPicker(2) = 5 rendered rows. Fallback path lands at 5 via 2 trailing Spacer(1)s. */
+	readonly footerRowCount = 5;
+
+	constructor(private readonly config: SubmitTabStrategyConfig) {}
+
+	headingRows(_state: DialogState): Component[] {
+		return [
+			new Text(this.config.theme.bold(this.config.theme.fg("accent", t("review.heading", REVIEW_HEADING))), 1, 0),
+			new Spacer(1),
+		];
+	}
+
+	bodyComponent(state: DialogState): Component {
+		const c = new Container();
+		for (let i = 0; i < this.config.questions.length; i++) {
+			const q = this.config.questions[i];
+			const a = state.answers.get(i);
+			if (!a) continue;
+			const label = q.header && q.header.length > 0 ? q.header : `Q${i + 1}`;
+			const answerText = formatAnswerScalar(a, "summary");
+			c.addChild(new Text(this.config.theme.fg("muted", ` ● ${label}`), 1, 0));
+			c.addChild(
+				new Text(`   ${this.config.theme.fg("muted", "→")} ${this.config.theme.fg("text", answerText)}`, 1, 0),
+			);
+			if (a.notes && a.notes.length > 0) {
+				c.addChild(new Text(this.config.theme.fg("dim", `     notes: ${a.notes}`), 1, 0));
+			}
+		}
+		return c;
+	}
+
+	bodyHeight(width: number, state: DialogState): number {
+		return this.bodyComponent(state).render(width).length;
+	}
+
+	midRows(_state: DialogState): Component[] {
+		return [];
+	}
+
+	footerRows(state: DialogState): Component[] {
+		const missing: string[] = [];
+		for (let i = 0; i < this.config.questions.length; i++) {
+			const q = this.config.questions[i];
+			if (!state.answers.has(i)) {
+				missing.push(q.header && q.header.length > 0 ? q.header : `Q${i + 1}`);
+			}
+		}
+		const promptText =
+			missing.length === 0
+				? this.config.theme.fg("muted", t("review.ready", READY_PROMPT))
+				: this.config.theme.fg(
+						"warning",
+						`${t("review.incomplete", INCOMPLETE_WARNING_PREFIX)} ${missing.join(", ")}`,
+					);
+		const out: Component[] = [new Spacer(1), new Text(promptText, 1, 0), new Spacer(1)];
+		if (this.config.submitPicker) {
+			out.push(this.config.submitPicker);
+		} else {
+			// Padding when the picker isn't wired — keeps rendered row count at footerRowCount=5.
+			out.push(new Spacer(1));
+			out.push(new Spacer(1));
+		}
+		return out;
+	}
+
+	focusedItemRowRange(_width: number, _state: DialogState): [number, number] | undefined {
+		return undefined;
+	}
+}
+
+/**
+ * Build the controls hint line. Order:
+ *   Enter · ↑/↓ [· Space toggle] [· n notes] [· Tab switch] · Esc · Ctrl+] collapse
+ *
+ * `NOTES` is now part of the resting (notes-closed) core — it renders on every
+ * question tab and drops when `state.notesVisible` flips the editor open OR while
+ * `state.inputMode` has the "Type something." row capturing text (`n` would insert
+ * a literal character there, so advertising it would lie). The collapse affordance
+ * is appended last so the resting core stays a contiguous substring even when the
+ * trailing part is clipped by `OneLineClippedText` on terminals < ~95 cols. This
+ * is the trade we picked over wrapping (which would inflate `footerRowCount` and
+ * desync the height math in `DialogView.render`).
+ */
+export function buildHintText(question: QuestionData | undefined, isMulti: boolean, state: DialogState): string {
+	const parts: string[] = [t("hint.enter", HINT_PART_ENTER), t("hint.navigate", HINT_PART_NAV)];
+	if (question?.multiSelect === true) parts.push(t("hint.toggle", HINT_PART_TOGGLE));
+	if (question && !state.notesVisible && !state.inputMode) {
+		parts.push(t("hint.notes", HINT_PART_NOTES));
+	}
+	if (isMulti) parts.push(t("hint.tab", HINT_PART_TAB));
+	parts.push(t("hint.cancel", HINT_PART_CANCEL));
+	parts.push(t("hint.collapse", HINT_PART_COLLAPSE));
+	return parts.join(" · ");
+}

package/node_modules/@juicesharp/rpiv-todo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@juicesharp/rpiv-todo/README.md

@@ -0,0 +1,122 @@
+# @juicesharp/rpiv-todo
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-todo.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-todo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<div align="center">
+  <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo">
+    <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-todo/docs/cover.png" alt="rpiv-todo — a persistent todo overlay for Pi Agent, showing a task panel with completed, in-progress, and pending rows" width="50%">
+  </a>
+</div>
+
+Give the model a task list you can see. `rpiv-todo` adds a `todo` tool, a
+`/todos` command, and a live panel above the editor to
+[Pi Agent](https://github.com/badlogic/pi-mono), so you always know what the
+agent is doing now, what it finished, and what is queued. The list is rebuilt
+from the conversation itself, so it survives `/reload` and compaction — useful
+on long research → design → implement sessions.
+
+## Install
+
+```sh
+pi install npm:@juicesharp/rpiv-todo
+```
+
+Restart your Pi session.
+
+## Quick start
+
+Run `/todos` after the restart to confirm the extension is loaded. On a fresh
+session it prints:
+
+```
+No todos yet. Ask the agent to add some!
+```
+
+Then ask for something with several steps — "add a repository layer with tests,
+and track it as todos". The model calls `todo` and the panel appears above your
+input box, updating as work moves:
+
+![Todo overlay panel: a Todos (2/7) heading above two struck-through completed rows, one in-progress row with its activity label, and four pending rows](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-todo/docs/overlay.jpg)
+
+Press `ctrl+shift+t` to collapse the panel to its heading plus a one-line hint,
+and again to expand it. Run `/todos` at any time to print the full list grouped
+by status.
+
+## What you get
+
+- **The plan stays on screen.** A panel above the editor shows every task with a
+  status glyph, the label of whatever is in progress, and a `Todos (done/total)`
+  heading — you never have to ask the agent where it is.
+- **Tasks survive `/reload` and compaction.** Each tool call carries the full
+  post-mutation snapshot, and the list is replayed from the session branch. No
+  disk writes, nothing to lose.
+- **Finished work gets out of the way.** Completed rows stay visible for the rest
+  of the turn, then drop at the start of the next one; the panel disappears
+  entirely when the list empties.
+- **The overlay never eats your terminal.** Past the row budget it drops
+  completed tasks first, truncates unfinished ones last, and tells you what it
+  hid with `+3 more (2 completed, 1 pending)`.
+- **The agent can sequence work, not just list it.** `blockedBy` dependencies are
+  validated before anything is written — dangling ids, deleted dependencies,
+  self-blocks, and cycles are all rejected.
+- **Parallel sessions stay separate.** Task state is keyed by session, so a
+  detached or child session can neither read nor overwrite the foreground list.
+- **Localized UI, no setup required.** Nine locales ship with the package and
+  activate when [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
+  is installed; without it, everything falls back to English.
+
+## Configuration
+
+Optional. Create `~/.config/rpiv-todo/config.json` (or
+`$XDG_CONFIG_HOME/rpiv-todo/config.json` if you set that variable):
+
+```json
+{
+  "maxWidgetLines": 8,
+  "collapseKey": "alt+t"
+}
+```
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `maxWidgetLines` | Content rows the overlay may use, heading included. Minimum `3`. Applies on the next repaint. | `12` |
+| `collapseKey` | Key that collapses and expands the panel, in Pi keybinding form (`alt+o`, `ctrl+shift+t`). Set `"off"` to register no shortcut. Needs `/reload` to rebind. | `"ctrl+shift+t"` |
+| `guidance` | Replaces the built-in instructions the extension gives the model about when and how to use the todo list. Needs `/reload`. | _(built-ins)_ |
+
+A missing or malformed file falls back to these defaults. `rpiv-todo` only reads
+this file — it never writes one. Full semantics:
+[Configuration](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-todo/docs/configuration.md).
+
+## Reference
+
+- [`todo` tool reference](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-todo/docs/tool-schema.md)
+  — every `todo` parameter, the status machine, the response envelope, and the
+  exact error strings.
+- [Configuration](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-todo/docs/configuration.md)
+  — config file resolution, option validation rules, and the accepted keybinding
+  grammar.
+- [Overlay and `/todos`](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-todo/docs/overlay.md)
+  — overlay lifecycle, glyphs, overflow behavior, `/todos` output, and
+  localization.
+
+## Requirements
+
+- A Pi Agent host. No API key, no model selection, no native dependencies.
+- An interactive session for the panel and `/todos`. Headless runs still get the
+  `todo` tool; nothing is rendered.
+- [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
+  is an optional peer — install it for a localized UI, skip it for English.
+
+## Related
+
+- [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
+  ([source](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-i18n))
+  — localizes this extension's UI chrome and adds a `/languages` picker.
+- [`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi)
+  ([source](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-pi))
+  — the umbrella package that installs this extension alongside its siblings.
+
+## License
+
+MIT — see [LICENSE](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-todo/LICENSE).

package/node_modules/@juicesharp/rpiv-todo/config.ts

@@ -0,0 +1,101 @@
+import type { GuidanceFields } from "@juicesharp/rpiv-config";
+import { loadJsonConfigWithLegacyFallback, validateGuidanceFields } from "@juicesharp/rpiv-config";
+
+interface TodoConfig {
+	guidance?: GuidanceFields;
+	maxWidgetLines?: number;
+	/**
+	 * Key spec for the overlay collapse/expand shortcut, in the same format as
+	 * pi-coding-agent keybinding ids (`modifier+key`, e.g. `ctrl+shift+t`, `alt+o`).
+	 * Defaults to `"ctrl+shift+t"`. Pass `"off"` to disable the collapse shortcut
+	 * entirely. Validation happens in `resolveCollapseKey`, not at load.
+	 */
+	collapseKey?: string;
+}
+
+/** Default content-row budget when the config is missing/invalid — the prior
+ *  hardcoded value, preserved as the fallback. */
+export const DEFAULT_MAX_WIDGET_LINES = 12;
+
+/** Key spec for the overlay collapse/expand shortcut, e.g. `"ctrl+shift+t"` or `"alt+o"`. */
+export type CollapseKeySpec = string;
+
+/** Default collapse/expand key when `collapseKey` is missing/empty/blank/invalid. */
+export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+shift+t";
+
+/** Sentinel value for `collapseKey` that disables the collapse shortcut entirely. */
+export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
+
+export function loadConfig(): TodoConfig {
+	return loadJsonConfigWithLegacyFallback<TodoConfig>("rpiv-todo");
+}
+
+/** Content-row budget for the overlay, read fresh on every call (per-render —
+ *  no `/reload`). Mirrors warp's getHeartbeatMs minus its `=== 0` disabled
+ *  sentinel: a non-number or a value below the floor of 3 falls back to the
+ *  default; no ceiling. */
+export function getMaxWidgetLines(): number {
+	const config = loadConfig();
+	const lines = config.maxWidgetLines;
+	if (typeof lines !== "number" || lines < 3) return DEFAULT_MAX_WIDGET_LINES;
+	return lines;
+}
+
+// Named keys accepted by pi-tui's `matchesKey` (keys.js switch on the parsed base key).
+// parseKeyId lowercases the id before matching, so lowercase spellings are canonical.
+const SPECIAL_KEYS = new Set([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+/** Validate a collapse-key spec against pi-tui's KeyId grammar (verbatim port from
+ *  rpiv-ask-user-question). Exported for unit tests. */
+export function isValidCollapseKeySpec(spec: string): boolean {
+	// Mirror pi-tui's KeyId grammar strictly: zero or more distinct modifiers, then a
+	// base key that is a single printable character or a named special key. A loose
+	// check is not enough — pi-tui's `parseKeyId` takes the LAST `+`-part as the key
+	// and ignores unknown parts, so a typo like `ctr+]` would silently match every
+	// bare `]` keypress (and the raw terminal listener would consume them globally).
+	if (!spec) return false;
+	if (spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+	const parts = spec.split("+");
+	const base = parts[parts.length - 1] ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (modifiers.length !== new Set(modifiers).size) return false;
+	if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+	return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+
+/** Resolve the collapse/expand key from config, read fresh on every call
+ *  (per-render / per-registration — no `/reload`); mirrors getMaxWidgetLines().
+ *  Returns DEFAULT_COLLAPSE_KEY when the field is missing/non-string/empty/blank/
+ *  invalid, COLLAPSE_KEY_OFF when set to the sentinel, or the lowercased validated
+ *  spec. */
+export function resolveCollapseKey(): CollapseKeySpec {
+	const config = loadConfig();
+	const raw = typeof config.collapseKey === "string" ? config.collapseKey.trim().toLowerCase() : undefined;
+	if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
+	if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+	return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+
+export { validateGuidanceFields };

package/node_modules/@juicesharp/rpiv-todo/docs/configuration.md

@@ -0,0 +1,108 @@
+# Configuration reference
+
+Every option
+[`@juicesharp/rpiv-todo`](https://www.npmjs.com/package/@juicesharp/rpiv-todo)
+reads, where the file lives, and exactly what happens when a value is wrong.
+
+## Where the file lives
+
+The config file is optional. It is resolved in this order:
+
+1. `$XDG_CONFIG_HOME/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is set
+   to an absolute path. A bare `~` or a leading `~/` is expanded first; a `~user`
+   form is not expanded and therefore falls through.
+2. `~/.config/rpiv-todo/config.json` — used when `XDG_CONFIG_HOME` is unset,
+   empty, whitespace-only, or relative.
+3. If the XDG file does not exist, the legacy `~/.config/rpiv-todo/config.json`
+   is read anyway, so a pre-XDG file is still found after you set
+   `XDG_CONFIG_HOME`. This fallback is one-way: if the XDG file exists but is
+   malformed, you get a warning and defaults — it does **not** quietly read the
+   legacy file instead.
+
+Both files missing means every default applies. Malformed JSON prints a
+`rpiv-config: invalid JSON at …` warning and is treated as `{}`. A JSON array or
+a non-object value (`null`, a string, a number, a boolean) is silently treated as
+`{}` — no warning.
+
+`rpiv-todo` never writes this file — you create and edit it yourself, and the
+extension only reads it.
+
+## Example
+
+```json
+{
+  "maxWidgetLines": 8,
+  "collapseKey": "alt+t",
+  "guidance": {
+    "promptSnippet": "Use the `todo` tool to track multi-step work before starting it.",
+    "promptGuidelines": [
+      "Create one task per discrete step.",
+      "Mark a task in_progress while working on it; completed when done."
+    ]
+  }
+}
+```
+
+## `maxWidgetLines`
+
+**Default `12`.** The content-row budget for the overlay — the heading row and,
+on overflow, the `+N more` summary row both count against it. Only the trailing
+blank spacer sits outside the budget, so `12` renders up to 13 terminal rows.
+
+- Floor of `3`. A number below `3` falls back to the default.
+- A non-number falls back to the default.
+- No ceiling.
+- Read fresh on every render, so a change takes effect on the next repaint —
+  no `/reload`.
+
+## `collapseKey`
+
+**Default `"ctrl+shift+t"`.** The shortcut that collapses and expands the
+overlay.
+
+The value is trimmed and lowercased, then matched against Pi's keybinding
+grammar: zero or more distinct modifiers joined by `+`, then a base key.
+
+| Part | Accepted |
+| --- | --- |
+| Modifiers | `ctrl`, `shift`, `alt`, `super` — each at most once |
+| Base key | one printable character (`a`, `7`, `]`, `/`, …) |
+| Base key | a named key: `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `f1`–`f12` |
+
+Examples: `alt+o`, `ctrl+shift+t`, `super+alt+f5`.
+
+- A missing, empty, blank, non-string, or ungrammatical value falls back to the
+  default. The grammar is checked strictly on purpose: Pi takes the last `+`-part
+  as the base key and ignores unknown parts, so a typo like `ctr+]` would
+  otherwise capture every bare `]` keypress globally.
+- `"off"` disables the feature — no shortcut is registered at all.
+- The binding is resolved **once at extension load**. After editing this value,
+  run `/reload` to rebind; until you do, the old key stays active even though the
+  collapsed panel's hint text (which is resolved per render) already shows the
+  new one.
+
+## Guidance
+
+`guidance.promptSnippet` (string) and `guidance.promptGuidelines` (array of
+strings) replace the prompt copy the `todo` tool advertises to the model. Both
+are absent by default, in which case the built-in snippet and the seven built-in
+guideline bullets are used.
+
+- `promptSnippet` must be a non-empty string; an empty string or a wrong type
+  falls back to the default.
+- `promptGuidelines` must be a non-empty array of non-empty strings. A non-array,
+  or an array containing an empty string, falls back to the default — the array
+  is all-or-nothing, not merged item by item.
+- Both are read at extension load, so `/reload` after editing them.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `XDG_CONFIG_HOME` | Relocates the config directory, as described above. |
+| `HOME` | Anchors `~/.config` when `XDG_CONFIG_HOME` does not apply. |
+
+`rpiv-todo` reads no environment variables of its own. If you have
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n)
+installed, that package has its own locale configuration and its own env-var
+chain — see its README.