@andares/pi-toolkits 0.5.0 → 0.7.0

package/src/features/autostart/autostart.test.ts

@@ -0,0 +1,315 @@
+/**
+ * autostart feature tests.
+ *
+ * Pure-logic coverage for parseAutostartConfig / commandNameOf, plus an
+ * integration pass over registerAutostart with a minimal mock of the pi
+ * extension surface (on/getCommands/sendUserMessage) and ExtensionContext
+ * (cwd/isProjectTrusted/ui.notify), using a temp directory for the config
+ * file.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	AUTOSTART_CONFIG_PATH,
+	AutostartParseError,
+	commandNameOf,
+	parseAutostartConfig,
+	RUNNABLE_REASONS,
+} from "./autostart.js";
+import { registerAutostart } from "./index.js";
+
+describe("parseAutostartConfig", () => {
+	it("parses a full config into the ordered command list", () => {
+		const text = [
+			"# project autostart",
+			"version = 1",
+			"",
+			"[command]",
+			'run = ["/add-dir ../shop-frontend", "/add-dir ../shop-api"]',
+		].join("\n");
+		expect(parseAutostartConfig(text)).toEqual([
+			"/add-dir ../shop-frontend",
+			"/add-dir ../shop-api",
+		]);
+	});
+
+	it("accepts a config without version (defaults to 1)", () => {
+		expect(parseAutostartConfig('[command]\nrun = ["/ask on"]')).toEqual([
+			"/ask on",
+		]);
+	});
+
+	it("returns empty for a config without [command] or run", () => {
+		expect(parseAutostartConfig("version = 1")).toEqual([]);
+		expect(parseAutostartConfig("[command]\n")).toEqual([]);
+	});
+
+	it("drops blank entries", () => {
+		expect(
+			parseAutostartConfig('[command]\nrun = ["/ask on", "  "]'),
+		).toEqual(["/ask on"]);
+	});
+
+	it("rejects [[command]] array tables instead of ignoring them", () => {
+		expect(() =>
+			parseAutostartConfig('[[command]]\nrun = ["/ask on"]'),
+		).toThrow(AutostartParseError);
+	});
+
+	it("normalizes whitespace out of commands", () => {
+		expect(
+			parseAutostartConfig('[command]\nrun = ["  /add-dir ../x  "]'),
+		).toEqual(["/add-dir ../x"]);
+	});
+
+	it("rejects version != 1", () => {
+		expect(() =>
+			parseAutostartConfig("version = 2\n[command]\nrun = []"),
+		).toThrow(AutostartParseError);
+	});
+
+	it("rejects invalid TOML", () => {
+		expect(() => parseAutostartConfig("[command\nrun = [")).toThrow(
+			AutostartParseError,
+		);
+	});
+
+	it("rejects [command].run that is not a string array", () => {
+		expect(() => parseAutostartConfig('[command]\nrun = "/ask on"')).toThrow(
+			AutostartParseError,
+		);
+		expect(() => parseAutostartConfig("[command]\nrun = [1, 2]")).toThrow(
+			AutostartParseError,
+		);
+	});
+});
+
+describe("commandNameOf", () => {
+	it("extracts the command name from a slash command with args", () => {
+		expect(commandNameOf("/add-dir ../shop-frontend")).toBe("add-dir");
+	});
+	it("tolerates missing slash, extra whitespace, and bare command", () => {
+		expect(commandNameOf("add-dir ../x")).toBe("add-dir");
+		expect(commandNameOf("  /add-dir   ../x  ")).toBe("add-dir");
+		expect(commandNameOf("/ask")).toBe("ask");
+	});
+	it("returns empty for blank input", () => {
+		expect(commandNameOf("   ")).toBe("");
+	});
+});
+
+describe("RUNNABLE_REASONS", () => {
+	it("replays startup/new/fork and not resume/reload", () => {
+		expect(RUNNABLE_REASONS.has("startup")).toBe(true);
+		expect(RUNNABLE_REASONS.has("new")).toBe(true);
+		expect(RUNNABLE_REASONS.has("fork")).toBe(true);
+		expect(RUNNABLE_REASONS.has("resume")).toBe(false);
+		expect(RUNNABLE_REASONS.has("reload")).toBe(false);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* registerAutostart integration (mocked pi surface)                   */
+/* ------------------------------------------------------------------ */
+
+type SessionStartHandler = (
+	event: { reason: string },
+	ctx: {
+		cwd: string;
+		isProjectTrusted: () => boolean;
+		ui: { notify: (message: string, type?: string) => void };
+	},
+) => Promise<void>;
+
+interface Harness {
+	cwd: string;
+	handler: SessionStartHandler;
+	sent: Array<{ command: string; options?: { expandPromptTemplates?: boolean } }>;
+	notifications: Array<{ message: string; type?: string }>;
+	commands: Array<{ name: string; source: string }>;
+	failCommands: Set<string>;
+	setTrusted(trusted: boolean): void;
+	start(reason: string): Promise<void>;
+}
+
+async function makeHarness(
+	config: string | null,
+	configAsDir = false,
+): Promise<Harness> {
+	const cwd = await mkdtemp(join(tmpdir(), "pi-autostart-test-"));
+	if (configAsDir) {
+		// EISDIR setup: the config path exists but is a directory.
+		await mkdir(join(cwd, ".pi"), { recursive: true });
+		await mkdir(join(cwd, AUTOSTART_CONFIG_PATH));
+	} else if (config !== null) {
+		await mkdir(join(cwd, ".pi"), { recursive: true });
+		await writeFile(join(cwd, AUTOSTART_CONFIG_PATH), config, "utf8");
+	}
+	let trusted = true;
+	let handler: SessionStartHandler = async () => {};
+	const sent: Harness["sent"] = [];
+	const notifications: Harness["notifications"] = [];
+	const commands: Harness["commands"] = [
+		{ name: "add-dir", source: "extension" },
+		{ name: "ask", source: "extension" },
+	];
+	const failCommands = new Set<string>();
+	const pi = {
+		on: (event: string, h: SessionStartHandler) => {
+			if (event === "session_start") handler = h;
+		},
+		getCommands: () => commands,
+		sendUserMessage: (
+			command: string,
+			options?: { expandPromptTemplates?: boolean },
+		) => {
+			sent.push({ command, options }); // records attempts, including failures
+			if (failCommands.has(command)) {
+				return Promise.reject(new Error("boom"));
+			}
+		},
+	} as unknown as ExtensionAPI;
+	registerAutostart(pi);
+	return {
+		handler,
+		sent,
+		notifications,
+		commands,
+		failCommands,
+		setTrusted(value: boolean) {
+			trusted = value;
+		},
+		async start(reason: string) {
+			await handler({ reason }, {
+				cwd,
+				isProjectTrusted: () => trusted,
+				ui: {
+					notify: (message: string, type?: string) => {
+						notifications.push({ message, type });
+					},
+				},
+			});
+		},
+		cwd,
+	};
+}
+
+let current: Harness | undefined;
+
+afterEach(async () => {
+	if (current) {
+		await rm(current.cwd, { recursive: true, force: true });
+		current = undefined;
+	}
+});
+
+async function harness(
+	config: string | null,
+	configAsDir = false,
+): Promise<Harness> {
+	const h = await makeHarness(config, configAsDir);
+	current = h;
+	return h;
+}
+
+describe("registerAutostart", () => {
+	const fullConfig =
+		'version = 1\n[command]\nrun = ["/add-dir ../frontend", "/add-dir ../api"]';
+
+	it("dispatches configured commands with expandPromptTemplates on startup", async () => {
+		const h = await harness(fullConfig);
+		await h.start("startup");
+		expect(h.sent).toEqual([
+			{ command: "/add-dir ../frontend", options: { expandPromptTemplates: true } },
+			{ command: "/add-dir ../api", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("reports parse errors and dispatches nothing", async () => {
+		const h = await harness("/[command]\nrun = [");
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("error");
+	});
+
+	it("replays on new and fork", async () => {
+		const h = await harness('[command]\nrun = ["/ask on"]');
+		await h.start("new");
+		await h.start("fork");
+		expect(h.sent).toEqual([
+			{ command: "/ask on", options: { expandPromptTemplates: true } },
+			{ command: "/ask on", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("does nothing on resume or reload", async () => {
+		const h = await harness(fullConfig);
+		await h.start("resume");
+		await h.start("reload");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("silently skips when no config file exists", async () => {
+		const h = await harness(null);
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("skips everything when the project is not trusted", async () => {
+		const h = await harness(fullConfig);
+		h.setTrusted(false);
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("skips unregistered commands instead of sending them to the model", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../x", "/not-a-command y"]',
+		);
+		await h.start("startup");
+		expect(h.sent).toEqual([
+			{ command: "/add-dir ../x", options: { expandPromptTemplates: true } },
+		]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("skips commands only registered as skill or prompt sources", async () => {
+		const h = await harness('[command]\nrun = ["/add-dir ../x"]');
+		h.commands.length = 0;
+		h.commands.push({ name: "add-dir", source: "skill" });
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+	});
+
+	it("warns when the config path cannot be read for a reason other than ENOENT", async () => {
+		const h = await harness(null, true); // .pi/autostart.toml is a directory → EISDIR
+		await h.start("startup");
+		expect(h.sent).toEqual([]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("keeps dispatching after one command fails", async () => {
+		const h = await harness(fullConfig);
+		h.failCommands.add("/add-dir ../frontend");
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual([
+			"/add-dir ../frontend",
+			"/add-dir ../api",
+		]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("error");
+	});
+});

package/src/features/autostart/autostart.ts

@@ -0,0 +1,108 @@
+/**
+ * autostart feature — pure config logic, no pi imports.
+ *
+ * Schema (`.pi/autostart.toml`, checked into the project):
+ *
+ * ```toml
+ * version = 1
+ *
+ * [command]
+ * run = [
+ *   "/add-dir ../shop-frontend",
+ *   "/add-dir ../shop-api",
+ * ]
+ * ```
+ *
+ * `version` is optional (defaults to 1) but must be 1 when present, so a
+ * future schema change can fail loudly instead of silently misreading.
+ */
+import { parse as parseToml } from "smol-toml";
+
+/** Project-relative location of the autostart config (`.pi/` is pi's
+ *  project-config convention, precedent: `.pi/mcp.json`). */
+export const AUTOSTART_CONFIG_PATH = ".pi/autostart.toml";
+
+/**
+ * session_start reasons that replay autostart commands:
+ *  - startup / new: fresh session in the project — replay
+ *  - fork: new branch of an earlier session — replay (the fork point may
+ *    predate the config)
+ *  - resume: the resumed branch already carries its /add-dir state —
+ *    replaying would at best duplicate work (pi-add-dir is idempotent) and
+ *    at worst re-add directories the user removed on that branch
+ *  - reload: extensions are being rebuilt — re-running commands would
+ *    duplicate side effects from the same session
+ */
+export const RUNNABLE_REASONS: ReadonlySet<string> = new Set([
+	"startup",
+	"new",
+	"fork",
+]);
+
+/** Parse/validation failure with a user-facing message. */
+export class AutostartParseError extends Error {}
+
+function errMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Parse autostart config text into the ordered command list.
+ * @throws AutostartParseError on invalid TOML, wrong shape, or version ≠ 1.
+ */
+export function parseAutostartConfig(text: string): string[] {
+	let doc: unknown;
+	try {
+		doc = parseToml(text);
+	} catch (err) {
+		throw new AutostartParseError(`invalid TOML: ${errMessage(err)}`);
+	}
+	if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+		throw new AutostartParseError("top-level value must be a table");
+	}
+	const { version, command } = doc as {
+		version?: unknown;
+		command?: unknown;
+	};
+	if (version !== undefined && version !== 1) {
+		throw new AutostartParseError(
+			`unsupported version ${String(version)} (expected 1)`,
+		);
+	}
+	if (command === undefined) return [];
+	if (Array.isArray(command)) {
+		throw new AutostartParseError(
+			"[[command]] array tables are not supported — use a single [command] table with a run array",
+		);
+	}
+	if (command === null || typeof command !== "object") {
+		throw new AutostartParseError("[command] must be a table");
+	}
+	const run = (command as { run?: unknown }).run;
+	if (run === undefined) return [];
+	if (
+		!Array.isArray(run) ||
+		run.some((entry) => typeof entry !== "string")
+	) {
+		throw new AutostartParseError(
+			"[command].run must be an array of command strings",
+		);
+	}
+	// Trim each entry: `prompt()` dispatches a command only when the text
+	// literally starts with "/", so a leading-space entry would silently fall
+	// through to the model as a plain message. Normalizing here keeps the
+	// "never sent to the model" guarantee (see index.ts).
+	return (run as string[])
+		.map((cmd) => cmd.trim())
+		.filter((cmd) => cmd !== "");
+}
+
+/**
+ * Extract the command name a slash command dispatches to:
+ * `"/add-dir ../x"` → `"add-dir"`, tolerant of leading whitespace and an
+ * optional slash. Empty for blank input.
+ */
+export function commandNameOf(command: string): string {
+	const stripped = command.trim().replace(/^\//, "");
+	return stripped.split(/\s+/)[0] ?? "";
+}

package/src/features/autostart/index.ts

@@ -0,0 +1,109 @@
+/**
+ * autostart feature — run project-declared slash commands at session start.
+ *
+ * Config lives at `<project root>/.pi/autostart.toml` (see autostart.ts for
+ * the schema). Execution gates, in order:
+ *
+ *  1. reason filter — only startup/new/fork replay (see RUNNABLE_REASONS)
+ *  2. config file exists — a missing file is a silent opt-in skip
+ *  3. `ctx.isProjectTrusted()` — an untrusted project never auto-executes
+ *  4. per-command pre-validation against `pi.getCommands()`: only commands
+ *     registered by an *extension* are dispatched. This is mandatory:
+ *     sendUserMessage with an unhandled "/x" falls through prompt() to the
+ *     model as a plain user message (pi agent-session.js), so an unknown
+ *     command must be skipped here, never sent.
+ *
+ * Dispatch uses `sendUserMessage(cmd, { expandPromptTemplates: true })` —
+ * that flag is what routes "/cmd args" through _tryExecuteExtensionCommand
+ * instead of the model prompt path. The wrapper defaults it to false
+ * (verified against pi 1.0.4 agent-session.js; see AGENTS.md host-compat
+ * discipline for the version matrix).
+ *
+ * Only extension commands can run this way. Built-in commands (/compact,
+ * /reload, /resume, …) are dispatched at the TUI layer and cannot be
+ * triggered from the extension layer; skill commands (/skill:name) expand
+ * into prompts rather than execute. First-party use case: `/add-dir`
+ * (pi-add-dir), which is idempotent ("Already added" check).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	AUTOSTART_CONFIG_PATH,
+	AutostartParseError,
+	commandNameOf,
+	parseAutostartConfig,
+	RUNNABLE_REASONS,
+} from "./autostart.js";
+
+export function registerAutostart(pi: ExtensionAPI): void {
+	pi.on("session_start", async (event, ctx) => {
+		if (!RUNNABLE_REASONS.has(event.reason)) return;
+
+		let text: string;
+		try {
+			text = await readFile(join(ctx.cwd, AUTOSTART_CONFIG_PATH), "utf8");
+		} catch (err) {
+			// Missing file = opt-in skip. Any other read failure (EACCES, EISDIR,
+			// …) is a misconfiguration the operator should hear about.
+			if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+				ctx.ui.notify(
+					`autostart: skipped — cannot read ${AUTOSTART_CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`,
+					"warning",
+				);
+			}
+			return;
+		}
+
+		let commands: string[];
+		try {
+			commands = parseAutostartConfig(text);
+		} catch (err) {
+			const message = err instanceof AutostartParseError ? err.message : String(err);
+			ctx.ui.notify(
+				`autostart: skipped — ${message} (${AUTOSTART_CONFIG_PATH})`,
+				"error",
+			);
+			return;
+		}
+		if (commands.length === 0) return;
+
+		if (!ctx.isProjectTrusted()) {
+			ctx.ui.notify(
+				`autostart: skipped — project not trusted (${AUTOSTART_CONFIG_PATH})`,
+				"warning",
+			);
+			return;
+		}
+
+		// Only extension-registered commands are dispatchable; skill and
+		// prompt-template entries expand rather than execute.
+		const dispatchable = new Set(
+			pi
+				.getCommands()
+				.flatMap((cmd) =>
+					cmd.source === "extension" ? [cmd.name.replace(/^\//, "")] : [],
+				),
+		);
+
+		for (const command of commands) {
+			const name = commandNameOf(command);
+			if (!name || !dispatchable.has(name)) {
+				ctx.ui.notify(
+					`autostart: skipped "${command}" — not a registered extension command`,
+					"warning",
+				);
+				continue;
+			}
+			// One failing command must not cancel the rest of the list.
+			try {
+				await pi.sendUserMessage(command, { expandPromptTemplates: true });
+			} catch (err) {
+				ctx.ui.notify(
+					`autostart: "${command}" failed — ${err instanceof Error ? err.message : String(err)}`,
+					"error",
+				);
+			}
+		}
+	});
+}

package/src/features/favorites/constants.ts

@@ -4,17 +4,47 @@
  * Keybindings are only active INSIDE the /model model selector (the
  * ModelSelectorComponent consumes input before the search box, see
  * patch-selector.ts). Outside the selector the default pi bindings are
- * untouched: ctrl+f stays "cursor right" in the editor, ctrl+j stays
- * "new line". ctrl+p/ctrl+shift+p keep their bindings — only the cycle
- * semantics change (patch-cycle.ts), so no keybinding conflicts arise.
+ * untouched: ctrl+j stays "new line". ctrl+p/ctrl+shift+p keep their
+ * bindings — only the cycle semantics change (patch-cycle.ts), so no
+ * keybinding conflicts arise.
+ *
+ * Verified against pi 0.86.0 / 0.87.0 / 0.99.0 / 1.0.2 / 1.0.4 keybinding
+ * tables + pi-tui input dispatch on WSL2 + Windows Terminal; re-run
+ * `pnpm check:keybindings` after every host upgrade before trusting this.
  */
 export const FAVORITES_STATUS_KEY = "favorites";
 
 /** State file, written next to the auto-naming-session config convention. */
 export const FAVORITES_FILE = "pi-toolkits-favorites.json";
 
-/** Selector-scoped keybindings (only honored while the model selector is open). */
-export const FAVORITE_TOGGLE_KEY = "ctrl+f";
+/**
+ * Selector-scoped keybindings (only honored while the model selector is open).
+ *
+ * Why ctrl+alt+f for the toggle (was ctrl+f through v0.6.0):
+ *  - ctrl+f is consumed by the host in fullscreen mode, which became pi's
+ *    default `tuiMode` in 1.0 (0.86–0.99 defaulted to `regular`, where the
+ *    binding is inert). On Windows/WSL `tui.altScreen.search` resolves to
+ *    ctrl+f, and `TuiAltScreen.handleViewportInput()` checks it before
+ *    `shouldDeferViewportInputToOverlay()`, so the keystroke opens transcript
+ *    search and the selector never sees it. Verified in pi-tui 1.0.4
+ *    `dist/tui-alt-screen.js` (search check is the first key branch and
+ *    returns `{ consume: true }` unconditionally).
+ *  - alt+f is taken by `tui.editor.cursorWordRight` and `app.tree.unfoldOrDown`.
+ *  - shift+f arrives as the literal character "F" without the kitty keyboard
+ *    protocol, i.e. it would steal a typed character from the selector's
+ *    search box.
+ *  - ctrl+shift+f collapses to ctrl+f on Windows/WSL terminals (the reason
+ *    pi itself binds search to ctrl+f there instead) and Windows Terminal
+ *    binds it to its own Find action.
+ *  - ctrl+alt+f is unclaimed across the whole 0.86–1.0 window (only
+ *    `ctrl+alt+]` is taken from that family) and is byte-distinguishable from
+ *    ctrl+f/alt+f without kitty (ESC + ctrl-f). Same family as the shipped
+ *    stash key ctrl+alt+y, which is proven to reach pi on this terminal.
+ *
+ * ctrl+j is kept: no host layer consumes it before the selector, so it only
+ * shadows `tui.input.newLine` inside the search box.
+ */
+export const FAVORITE_TOGGLE_KEY = "ctrl+alt+f";
 export const FAVORITES_ONLY_KEY = "ctrl+j";
 
 /**

package/src/features/favorites/favorites.test.ts

@@ -6,8 +6,8 @@
  *  - cycle patch: favorites-only cycling (fallback to stock when disabled or
  *    no favorites; favorites-only pick; single-favorite jump; not-a-favorite
  *    → forward first / backward last)
- *  - selector patches: ctrl+j favorites-only filter, ctrl+f toggle, hint
- *    injection, idempotent apply
+ *  - selector patches: ctrl+j favorites-only filter, ctrl+alt+f toggle, hint
+ *    injection, idempotent apply, plain ctrl+f left to the host
  *
  * The patches read the shared store via getFavoritesStore(); each test gets an
  * isolated store backed by a temp file via setSharedFavoritesStore(). The
@@ -408,18 +408,36 @@ describe("selector patches", () => {
 		expect(selector.filteredModels).toHaveLength(3);
 	});
 
-	it("ctrl+f toggles favorite for the selected model", () => {
+	it("ctrl+alt+f toggles favorite for the selected model", () => {
 		const selector = fakeSelector({
 			filteredModels: models.map(item),
 			selectedIndex: 1, // opus-4
 			activeModels: models.map(item),
 		});
-		selector.handleInput("\x06"); // ctrl+f
+		selector.handleInput("\x1b\x06"); // ctrl+alt+f (legacy ESC + ctrl-f)
 		expect(getFavoritesStore().has(models[1])).toBe(true);
-		selector.handleInput("\x06");
+		selector.handleInput("\x1b\x06");
 		expect(getFavoritesStore().has(models[1])).toBe(false);
 	});
 
+	it("does not intercept plain ctrl+f (host-owned in fullscreen mode)", () => {
+		const forwarded: string[] = [];
+		getFavoritesStore().toggle(models[1]);
+		const selector = fakeSelector({
+			filteredModels: models.map(item),
+			selectedIndex: 1,
+			activeModels: models.map(item),
+			searchInput: {
+				getValue: () => "",
+				handleInput: (d: string) => forwarded.push(d),
+			},
+		});
+		selector.handleInput("\x06"); // stock ctrl+f
+		// Reached the search box instead of our toggle, so the store is unchanged.
+		expect(forwarded).toEqual(["\x06"]);
+		expect(getFavoritesStore().has(models[1])).toBe(true);
+	});
+
 	it("injects the hint row once (children.length grows by exactly one)", () => {
 		const selector = fakeSelector({
 			children: [1, 2, 3, 4] as unknown[],

package/src/features/favorites/index.ts

@@ -4,11 +4,14 @@
  * What it does:
  *  - Inside the /model selector (opened via /model or ctrl+l):
  *      * a hint row at the top shows the keys and the favorites-only state
- *      * ctrl+f toggles favorite on the currently selected model
+ *      * ctrl+alt+f toggles favorite on the currently selected model
  *      * ctrl+j toggles the "only favorites" filter
  *      * favorited model ids render in bold bright yellow
  *    The keys are consumed by the selector component only, so pi's editor
- *    bindings (ctrl+f cursor-right, ctrl+j newline) are untouched elsewhere.
+ *    bindings (ctrl+j newline) are untouched elsewhere. (The toggle moved off
+ *    ctrl+f after v0.6.0: pi >= 1.0 defaults to fullscreen, where ctrl+f is
+ *    consumed by the alt-screen transcript search before the selector sees
+ *    it — see constants.ts for the full key audit.)
  *  - ctrl+p / ctrl+shift+p keep their bindings but, once favorites exist
  *    (and cycleOnlyFavorites is not false), cycle only among favorited
  *    models instead of all models. ctrl+l / /model remain the escape hatch
@@ -19,7 +22,7 @@
  * Implementation: pi's extension API has no hook to render inside the
  * built-in model selector and cannot rebind the reserved ctrl+p actions, so
  * the feature patches two built-in prototypes at runtime:
- *  - ModelSelectorComponent (hint row, ctrl+f/ctrl+j, styling, filter)
+ *  - ModelSelectorComponent (hint row, favorites keys, styling, filter)
  *  - AgentSession.cycleModel (favorites-only cycling)
  * Both patches are version-guarded (skip + warn if the API changed) and
  * idempotent across /reload.
@@ -91,13 +94,14 @@ export function registerFavorites(pi: ExtensionAPI): void {
 	applyCyclePatch();
 
 	pi.registerCommand("favorites", {
-		description: "List favorited models (add/remove with ctrl+F in /model)",
+		description:
+			"List favorited models (add/remove with ctrl+alt+F in /model)",
 		handler: async (_args: string, ctx: ExtensionContext) => {
 			captureTheme(ctx);
 			const list = getFavoritesStore().list();
 			if (list.length === 0) {
 				ctx.ui.notify(
-					"No favorited models. Open /model and press ctrl+F on a model to favorite it.",
+					"No favorited models. Open /model and press ctrl+alt+F on a model to favorite it.",
 					"info",
 				);
 				return;