pi-note 0.15.1 → 0.16.1

package/README.md

@@ -9,10 +9,9 @@ The extension and Python app share a repository but install separately.
 
 Requires Pi 0.99.1+, Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
 From this checkout, install the extension with `pi install ./pi`, then run
-`/reload` in interactive Pi. Use `/pi-note-setup` if the CLI is missing, or the
-suggested `/pi-note-upgrade` if it is older than the bundled CLI. The planned npm package name is
-`pi-note`; after its first release use `pi install npm:pi-note` instead.
-It is not published yet. npm installation does not run Python installers.
+`/reload` in interactive Pi. The planned npm package name is `pi-note`; after its
+first release use `pi install npm:pi-note` instead. It is not published yet. npm
+installation does not run Python installers.
 
 ### CLI setup and upgrades
 
@@ -20,21 +19,19 @@ Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first and
 restart Pi with `uv` on PATH. At startup the extension checks `note --version`
 against its bundled CLI version (currently 0.4.0), without network requests:
 
-- Missing/unrecognized CLI: show `/pi-note-setup` in the slash-command menu.
-- Older CLI: show and suggest `/pi-note-upgrade`.
-- Equal/newer CLI: hide both commands; no upgrade notification.
+- Missing/unrecognized CLI: `/pi-note` opens Settings directly, where **Install CLI** is available.
+- Older CLI: `/pi-note` opens Settings directly, where **Upgrade CLI** is available.
+- Equal/newer CLI: neither installation action is shown; no upgrade notification.
 
-Both commands ask before installing into uv's isolated tool environment.
-The menu refreshes after setup/upgrade; restart Pi or `/reload` after external
-CLI changes. Manually typing either command rechecks the version and never
-reinstalls an equal/newer CLI or intentionally downgrades it.
+Install and upgrade recheck the CLI version and ask before installing into uv's
+isolated tool environment. Restart Pi or `/reload` after external CLI changes;
+installation actions never reinstall an equal/newer CLI or intentionally downgrade it.
 Python 3.11+ is required; uv can download a suitable interpreter when missing.
-The command downloads a pinned GitHub source archive and build dependencies,
+Installation downloads a pinned GitHub source archive and build dependencies,
 not a similarly named PyPI package. It does not install GTK dependencies, edit
 shell configuration, or change tasks. This checks the Python CLI bundled with
 the installed extension, not the latest npm/GitHub release. Update the extension
-first to receive a newer bundled CLI. `/pi-note-setup --upgrade` is replaced by
-`/pi-note-upgrade`.
+first to receive a newer bundled CLI.
 
 Back up your database before upgrading and update an optional GUI separately.
 For checkout development, use `uv tool install --reinstall .` at the repo root
@@ -45,7 +42,8 @@ put that directory before older `note` executables on PATH, and restart Pi.
 Check `note --version`, then restart Pi or `/reload`. Network/build failures and
 conflicting executables are reported without forcibly overwriting another
 installer's commands. Fix the reported cause and retry; installs time out after
-three minutes. Setup/upgrade commands are hidden while installation runs.
+three minutes. Installation actions are unavailable while installation runs.
+Setup hints direct users to `/pi-note` → Settings.
 Missing uv is reported with its installation link, not installed
 automatically. The [GTK desktop app](../README.md#optional-gtk-checklist) is optional
 and still requires separate system dependencies.
@@ -56,15 +54,20 @@ standalone `settings/pi/extensions/pinote.ts` entry if installed; load only one
 
 ## Use
 
-`/pi-note` picks a task, marks it in progress, and adds this default prompt to the editor:
+When the CLI is ready and no task is selected, `/pi-note` opens the task picker.
+It marks the chosen task in progress and adds this default prompt to the editor:
 “Read the current Pinote task. Summarize your understanding, but don’t start work yet.”
+If the CLI is missing or older than the bundled version, `/pi-note` opens Settings
+directly so the relevant CLI installation action remains accessible. **Tab** opens
+Settings from the picker or task view; **Tab** from Settings returns to tasks.
 The agent fetches current task text and saved handoff fields when you submit;
 they are not copied into the draft. The default prompt asks for a summary, not implementation.
 Existing drafts are preserved; nothing is submitted automatically.
-With a selected task it offers **Continue**, **Done**, **Switch task**, and **Settings**.
-Press **Tab** from the task menu or picker to open global settings; Tab
-returns to tasks, keeping saved changes. Settings also lists fields found on the current
-task, so existing values can be configured without creating another task.
+With a selected task, `/pi-note` offers **Continue**, **Done**, **Switch task**, and
+**Settings**. Settings provides **Preview task**, **Complete task (new session)**,
+**Accept suggestion**, and **Dismiss suggestion** when applicable, plus
+**Install CLI** or **Upgrade CLI** only when needed. Settings also lists fields found
+on the current task, so existing values can be configured without creating another task.
 Type in the task picker to filter by text, ID, tag, or state (all words must match).
 Use ↑/↓ and Enter to select, or Esc to cancel. Rows show **●** for in progress or
 **○** for active, followed by the tag (`[Untagged]` when absent).
@@ -72,8 +75,8 @@ The normal Pi status area shows selected-task controls and title without replaci
 
 ### Display-only preview
 
-Run `/pi-note-preview` to print the selected task's full Markdown text and saved
-agent fields in the transcript. The preview is labeled **display only · not sent
+Use **Preview task** in Settings to print the selected task's full Markdown text
+and saved agent fields in the transcript. The preview is labeled **display only · not sent
 to model**: it is a local custom session entry, excluded from subsequent model
 requests, compaction and branch summaries. It survives session resume but does not
 modify the note, editor draft or task selection, and never starts a model call.
@@ -100,8 +103,8 @@ Reload Kitty with **Ctrl+Shift+F5**. In Pi's regular mode, click the task text;
 fullscreen mode, use **Ctrl+Shift+click** so Kitty handles the link instead of
 Pi's system URL opener. The helper sends only an authenticated selection
 identifier, never note content or a model prompt. Stale links after task switching, tree navigation, reload or session exit
-are rejected. Other terminals can use `/pi-note-preview`; if the socket cannot
-start, the task remains visible without a link and that command remains available.
+are rejected. The **Preview task** Settings action is also available when the
+socket cannot start; the task remains visible without a link.
 
 Each Pi session remembers its own task, including several sessions in one folder.
 Resume restores that session's task; a new session starts unselected and does not import
@@ -129,9 +132,16 @@ Configure `~/.pi/agent/pi-note.json` (or the agent directory set by
 
 `taskOfferPolicy` controls the agent's task-offer guidance:
 
-- `always` (default): offer a task when given work with no task selected.
-- `github-remote`: first verify with Git that the repository has an HTTPS or SSH
-  remote hosted on `github.com`; otherwise do not offer. Local paths and other
+With no selected task, suggest a note only when implementation is expected to
+span multiple turns. Skip questions, investigation, recon, and small edits (such
+as changing a few configuration lines). If investigation develops into substantial
+implementation, suggest then. No plan is required: a short title identifies the
+work. Explicit user requests to create a task remain allowed under every policy.
+
+- `always` (default): offer for qualifying implementation in any repository.
+- `github-remote`: for qualifying implementation, first verify with Git that the
+  repository has an HTTPS or SSH remote hosted on `github.com`; otherwise do not
+  offer. Local paths and other
   hosts do not qualify. This is agent guidance, not a network or PR-access check.
 - `never`: do not offer tasks; explicit requests to create one remain allowed.
 
@@ -152,8 +162,11 @@ field needs no `/reload`. Its value is literal text, not a prompt template; use
 `\n` in JSON strings for multiple lines. It must be a nonblank string without control
 characters other than tabs and newlines. A missing file or key uses the default.
 Invalid/unreadable configuration reports an error without starting/switching a
-task or changing the editor. **Done** and agent tools are unaffected. This is
-user-level configuration only; project-local files are not read.
+task or changing the editor. Menu **Done**, footer completion, and agent tools are
+unaffected. If configuration is invalid or unreadable, Settings shows only task,
+suggestion, and CLI actions; repair `pi-note.json` before editing preferences.
+Invalid configuration is never replaced with defaults. This is user-level
+configuration only; project-local files are not read.
 
 ### Agent tools
 
@@ -193,13 +206,13 @@ asking in chat. The pin footer shows a pending suggestion, distinct from a selec
 
 - Muted **✕** dismisses without creating a note; further offers are suppressed until a new session.
 - Accent **+** creates, starts, and selects the suggested task.
-- Green **✓** completes the selected task, starts a clean unselected session, and reloads Pi without a completion prompt. Menu **Done** and `/pi-note-done` do the same.
+- Green **✓** completes the selected task, starts a clean unselected session, and reloads Pi without a completion prompt. Menu **Done** and **Complete task** in Settings do the same.
 
 Done occupies the former ✕ position, not the + position, so clicking Add twice cannot accidentally complete the new task. The selected row removes the former + cell's padding. The selected task's title is a separate preview link.
 
 The configured `footer.titleWidth` bounds the entire row (default 60 columns). Controls stay first; the tag is dropped before truncating the first-line title with `...`. Tiny widths hide controls (pin only). Pi can still clip the combined status row on narrow terminals.
 
-Controls use the [Kitty preview handler](#display-only-preview), with no additional configuration. Fullscreen Kitty uses **Ctrl+Shift+click**. Keyboard alternatives are `/pi-note-no`, `/pi-note-yes`, and `/pi-note-done`. No action submits input or starts an agent turn. Add and Dismiss preserve editor drafts; Done clears the new session's editor, so save unfinished input before completing a task.
+Controls use the [Kitty preview handler](#display-only-preview), with no additional configuration. Fullscreen Kitty uses **Ctrl+Shift+click**. The Settings actions **Accept suggestion** and **Dismiss suggestion** perform the corresponding footer actions. No action submits input or starts an agent turn. Add and Dismiss preserve editor drafts; **Complete task** starts a clean session and reloads Pi, discarding the editor draft, so save unfinished input before completing a task.
 
 Completion requires an idle Pi session and no pending Pinote operation. It rejects stale selected-task links and externally changed revisions. Accepted mutations drain even if the helper disconnects. On an error, check `/pi-note` before retrying, because a write may already have committed. Failed or stale writes never restart Pi. If another extension cancels the new session, the task remains completed and Pi reports the cancellation. The reload runs through the new session's fresh context; retired contexts are not reused.
 

package/footer-settings.ts

@@ -4,6 +4,9 @@ import { defaultFooterField, parseFooterConfig, parseHandoffPrompt, type PinoteS
 
 type Matches = (data: string, action: string) => boolean;
 type Row = { label: string; action: () => void };
+export type SettingsAction = "preview" | "done" | "yes" | "no" | "setup" | "upgrade";
+export type SettingsResult = "tasks" | SettingsAction | undefined;
+export type SettingsOption = { label: string; result: SettingsAction };
 const isTab = (data: string) => matchesKey(data, "tab") || matchesKey(data, "shift+tab");
 const display = (value: string) => value.replace(/[\x00-\x1f\x7f-\x9f]/gu, " ");
 const actions = ["Continue", "Done", "Switch task", "Settings"];
@@ -44,7 +47,9 @@ export class FooterSettings {
   private knownFields: string[];
   private theme: Theme;
   private matches: Matches;
-  private done: (result: "tasks" | undefined) => void;
+  private done: (result: SettingsResult) => void;
+  private options: SettingsOption[];
+  private configurationError?: string;
   private save: (settings: PinoteSettings) => void;
   private requestRender: () => void;
   private index = 0;
@@ -54,8 +59,10 @@ export class FooterSettings {
   private hasFocus = false;
 
   constructor(config: PinoteSettings, knownFields: string[], theme: Theme, matches: Matches,
-    done: (result: "tasks" | undefined) => void, requestRender: () => void, createEditor: () => Editor,
-    save: (settings: PinoteSettings) => void) {
+    done: (result: SettingsResult) => void, requestRender: () => void, createEditor: () => Editor,
+    save: (settings: PinoteSettings) => void, options: SettingsOption[] = [], configurationError?: string) {
+    this.options = options;
+    this.configurationError = configurationError;
     this.draft = structuredClone(config.footer);
     this.prompt = config.handoffPrompt;
     this.createEditor = createEditor;
@@ -97,7 +104,12 @@ export class FooterSettings {
     this.field = structuredClone(this.draft.fields!.find((field) => field.name === name) ?? defaultFooterField(name));
     this.index = 0; this.error = "";
   }
+  private actionRows(): Row[] {
+    return [...this.options.map(({ label, result }) => ({ label, action: () => this.done(result) })),
+      { label: "Return to tasks", action: () => this.done("tasks") }];
+  }
   private rootRows(): Row[] {
+    if (this.configurationError) return this.actionRows();
     const rows: Row[] = (["titleWidth", "fieldWidth", "maxFields"] as const).map((key) => ({
       label: `${{ titleWidth: "Title width", fieldWidth: "Default field width", maxFields: "Max fields" }[key]}: ${this.draft[key]}`,
       action: () => this.ask(key, String(this.draft[key]), (value) => {
@@ -123,8 +135,8 @@ export class FooterSettings {
         this.persistField(field);
         this.index = 0;
       }
-    }) },
-    { label: "Return to tasks", action: () => this.done("tasks") });
+    }) });
+    rows.push(...this.actionRows());
     return rows;
   }
   private fieldRows(): Row[] {
@@ -183,6 +195,7 @@ export class FooterSettings {
   }
   render(width: number) {
     const lines = [this.theme.fg("accent", "Pinote — Global Settings"), this.theme.fg("dim", "Tasks (Tab) · Settings · Fields")];
+    if (this.configurationError) lines.push(this.theme.fg("warning", this.configurationError));
     if (this.editor) {
       lines.push(this.theme.fg("accent", "Task prompt"), ...this.editor.render(width),
         this.theme.fg("dim", "Enter save · Shift+Enter/Ctrl+J newline · Ctrl+C clear · Esc cancel edit"));
@@ -197,10 +210,11 @@ export class FooterSettings {
       lines.push(...rows.slice(start, start + 8).map((row, offset) => offset + start === this.index
         ? this.theme.fg("accent", `> ${row.label}`) : `  ${row.label}`));
       if (rows.length > 8) lines.push(this.theme.fg("dim", `${this.index + 1}/${rows.length}`));
-      lines.push(this.theme.fg("dim", "↑↓ navigate · Enter edit · Esc back"));
+      lines.push(this.theme.fg("dim", "↑↓ navigate · Enter select · Esc back"));
     }
     if (this.error) lines.push(this.theme.fg("error", this.error));
-    lines.push(this.theme.fg("dim", "Changes save automatically · Tab: tasks"));
+    lines.push(this.theme.fg("dim", this.configurationError
+      ? "Fix pi-note.json to edit settings · Tab: tasks" : "Changes save automatically · Tab: tasks"));
     return lines.map((line) => truncateToWidth(line, width));
   }
   invalidate() { this.input?.widget.invalidate(); this.editor?.invalidate(); }

package/index.ts

@@ -7,16 +7,17 @@ import { stripVTControlCharacters } from "node:util";
 import { Type } from "typebox";
 import { updateTaskFooter, clearTaskFooter } from "./footer-status.ts";
 import { defaultFooterConfig, defaultHandoffPrompt, effectiveFooterFields, loadFooterConfig, parseHandoffPrompt, readFooterDocument, saveFooterConfig, type FooterConfig, type PinoteSettings } from "./footer-config.ts";
-import { FooterSettings, TaskMenu, withSettingsTab } from "./footer-settings.ts";
+import { FooterSettings, TaskMenu, withSettingsTab, type SettingsOption, type SettingsResult } from "./footer-settings.ts";
 import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
-import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
+import { bundledCLIVersion, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
 import { createPreviewBridge } from "./preview-bridge.ts";
 import { renderSuggestion, renderSelectedTask } from "./task-suggestion.ts";
 
 const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep a GitHub pull request in the PR field. Read pinote_fields to learn the user's globally configured footer field names and presentation. Populate those fields with meaningful task values when relevant using pinote_update_current; fields without values stay hidden. Footer fields and widths are chosen by the user's pi-note.json config. Set configured fields with Markdown values; links are clickable. When footer.fields is unset, Bar selects labels, one per line. Do not list PR in Bar. Remove a field to hide it. Do not modify config without user approval.";
+const implementationOfferGuidance = "When no pinote task is selected, suggest one only when implementation is expected to span multiple turns. Skip suggestions for questions, investigation, recon, and small edits such as changing a few configuration lines. If investigation develops into substantial implementation, suggest then. No plan is required; use a short title describing the work. Explicit user requests to create one remain allowed.";
 const offerGuidance = {
-  always: "When the user gives work and no pinote task is selected, use pinote_propose to show one suggested `[tag] task` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it.",
-  "github-remote": "When the user gives work and no pinote task is selected, first verify with Git that the current repository has a remote whose URL host is github.com (HTTPS or SSH). Only then use pinote_propose to show one suggested `[tag] task` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it. Local paths, other hosts, and GitHub-looking URL paths do not qualify. If no GitHub remote is verified, do not offer a task; explicit user requests to create one remain allowed.",
+  always: `${implementationOfferGuidance} For eligible work, use pinote_propose to show one suggested \`[tag] task\` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it.`,
+  "github-remote": `${implementationOfferGuidance} For eligible work, first verify with Git that the current repository has a remote whose URL host is github.com (HTTPS or SSH). Only then use pinote_propose to show one suggested \`[tag] task\` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it. Local paths, other hosts, and GitHub-looking URL paths do not qualify. If no GitHub remote is verified, do not offer a task.`,
   never: "Do not offer to create a pinote task. Create one only when the user explicitly requests it.",
 };
 const consentGuidance = "The suggestion bar's plus creates, starts and selects the note; its cross dismisses it. Continue the requested work while the suggestion is pending; do not ask again in chat or create a note yourself. On a chat no, continue without a note; on a chat yes, call pinote_add with select true. Never add or select without consent. If a task is already selected, do not replace it unless the user asks to switch.";
@@ -179,7 +180,7 @@ export default function (pi: ExtensionAPI) {
     if (!alive || generation !== epoch || setupAbort) return;
     cliState = action;
     if (suggest && action === "upgrade") {
-      ctx.ui.notify(`Pinote CLI ${bundledCLIVersion} is bundled with this extension. Run /pi-note-upgrade to update your older CLI.`, "info");
+      ctx.ui.notify(`Pinote CLI ${bundledCLIVersion} is bundled with this extension. Open /pi-note → Settings → Upgrade CLI to update your older CLI.`, "info");
     }
   };
 
@@ -306,7 +307,7 @@ export default function (pi: ExtensionAPI) {
       if (alive && generation === epoch && serial === refreshSerial) {
         previewBridge?.invalidate();
         clearTaskFooter(ctx);
-        ctx.ui.setStatus("pinote", suggestionStatus(ctx) ?? `${ctx.ui.theme.bold(noteIcon)} Pinote unavailable · ${cliState === "upgrade" ? "/pi-note-upgrade" : cliState === "setup" ? "/pi-note-setup" : "/pi-note"}`);
+        ctx.ui.setStatus("pinote", suggestionStatus(ctx) ?? `${ctx.ui.theme.bold(noteIcon)} Pinote unavailable · /pi-note → Settings`);
       }
     }
   };
@@ -349,10 +350,10 @@ export default function (pi: ExtensionAPI) {
       };
       const timer = setTimeout(() => {
         finish(false);
-        if (alive && activeContext === ctx) ctx.ui.notify("Pinote completion could not start. Use /pi-note-done.", "warning");
+        if (alive && activeContext === ctx) ctx.ui.notify("Pinote completion could not start. Open /pi-note → Settings → Complete task.", "warning");
       }, 4000);
       completionDispatch = { token, selection, task: displayed, started: () => clearTimeout(timer), finish };
-      try { pi.sendUserMessage(`/pi-note-done ${token}`, { expandPromptTemplates: true }); }
+      try { pi.sendUserMessage(`/pi-note ${token}`, { expandPromptTemplates: true }); }
       catch { finish(false); }
     });
   };
@@ -404,18 +405,6 @@ export default function (pi: ExtensionAPI) {
       if (alive && generation === epoch) await refresh(ctx);
     }
   };
-  pi.registerCommand("pi-note-done", {
-    description: "Complete the selected task, start a clean session, and reload Pi",
-    handler: (args, ctx) => completeSelected(args, ctx),
-  });
-  pi.registerCommand("pi-note-preview", {
-    description: "Display the selected task locally without sending it to the model",
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI || ctx.mode !== "tui") return;
-      if (args.trim()) { ctx.ui.notify("Usage: /pi-note-preview", "warning"); return; }
-      if (!await preview(ctx)) ctx.ui.notify("Select a task with /pi-note and wait until Pi is idle before previewing.", "warning");
-    },
-  });
   pi.on("session_start", async (_event, ctx) => {
     setupAbort?.abort();
     cancelCompletionDispatch();
@@ -445,7 +434,6 @@ export default function (pi: ExtensionAPI) {
     cliState = undefined;
     if (ctx.hasUI && ctx.mode === "tui") {
       if (offerConfigError) ctx.ui.notify(`Pinote task offers disabled: ${clean(offerConfigError)} Fix the configuration and /reload.`, "warning");
-      ctx.ui.addAutocompleteProvider((current) => cliMenu(current, () => setupAbort ? undefined : cliState));
     }
     if (ctx.hasUI && ctx.mode === "tui") {
       const bridge = createPreviewBridge();
@@ -455,7 +443,7 @@ export default function (pi: ExtensionAPI) {
       } catch {
         await bridge.stop();
         if (previewBridge === bridge) previewBridge = undefined;
-        ctx.ui.notify("Pinote task link unavailable; use /pi-note-preview.", "warning");
+        ctx.ui.notify("Pinote task link unavailable; open /pi-note → Settings → Preview task.", "warning");
       }
     }
     if (!alive || generation !== epoch) return;
@@ -500,51 +488,49 @@ export default function (pi: ExtensionAPI) {
     if (bridge) await bridge.stop();
   });
 
-  const registerInstallCommand = (name: "pi-note-setup" | "pi-note-upgrade") => pi.registerCommand(name, {
-    description: name === "pi-note-setup" ? "Install the missing Python CLI with uv" : "Upgrade an older Python CLI to the bundled version",
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI || ctx.mode !== "tui") return;
-      if (args.trim()) {
-        ctx.ui.notify(`Usage: /${name}`, "warning");
-        return;
-      }
-      if (pending || !ctx.isIdle()) {
-        ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
-        return;
-      }
-      const operation = Symbol();
-      pending = operation;
-      const generation = epoch;
-      const controller = new AbortController();
-      setupAbort = controller;
-      clearTaskFooter(ctx);
-      const currentSession = () => alive && generation === epoch;
-      try {
-        await setupCLI(pi, ctx, name === "pi-note-upgrade",
-          () => currentSession() && ctx.isIdle(), controller.signal);
-      } catch (error) {
-        if (currentSession()) ctx.ui.notify(`Pinote setup: ${clean(String(error))}`, "error");
-      } finally {
-        if (pending === operation) pending = undefined;
-        if (setupAbort === controller) setupAbort = undefined;
-        const latestContext = activeContext ?? (currentSession() ? ctx : undefined);
-        if (alive && latestContext) {
-          const generation = epoch;
-          await checkCLI(latestContext, !currentSession());
-          if (!alive || generation !== epoch || setupAbort) return;
-          await refresh(latestContext);
-        }
+  const installCLI = async (upgrade: boolean, ctx: ExtensionCommandContext) => {
+    if (!ctx.hasUI || ctx.mode !== "tui") return;
+    if (pending || !ctx.isIdle()) {
+      ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
+      return;
+    }
+    const operation = Symbol();
+    pending = operation;
+    const generation = epoch;
+    const controller = new AbortController();
+    setupAbort = controller;
+    clearTaskFooter(ctx);
+    const currentSession = () => alive && generation === epoch;
+    try {
+      await setupCLI(pi, ctx, upgrade,
+        () => currentSession() && ctx.isIdle(), controller.signal);
+    } catch (error) {
+      if (currentSession()) ctx.ui.notify(`Pinote setup: ${clean(String(error))}`, "error");
+    } finally {
+      if (pending === operation) pending = undefined;
+      if (setupAbort === controller) setupAbort = undefined;
+      const latestContext = activeContext ?? (currentSession() ? ctx : undefined);
+      if (alive && latestContext) {
+        const generation = epoch;
+        await checkCLI(latestContext, !currentSession());
+        if (!alive || generation !== epoch || setupAbort) return;
+        await refresh(latestContext);
       }
-    },
-  });
-  registerInstallCommand("pi-note-setup");
-  registerInstallCommand("pi-note-upgrade");
+    }
+  };
 
   pi.registerCommand("pi-note", {
     description: "Continue, complete, switch tasks, or edit global settings (Tab)",
     handler: async (args, ctx) => {
       if (!ctx.hasUI || ctx.mode !== "tui") return;
-      if (args.trim()) { ctx.ui.notify("Usage: /pi-note", "warning"); return; }
+      // Footer completion needs a command context, but no extra slash command.
+      // Only the current one-use capability may dispatch; stale tokens remain inert.
+      const token = args.trim();
+      if (/^[a-f0-9]{32}:\d+:\d+:\d+:[a-f0-9]{16}$/u.test(token)) {
+        await completeSelected(token, ctx);
+        return;
+      }
+      if (token) { ctx.ui.notify("Usage: /pi-note", "warning"); return; }
       if (pending || !ctx.isIdle()) {
         ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
         return;
@@ -556,19 +542,46 @@ export default function (pi: ExtensionAPI) {
       const currentSession = () => alive && generation === epoch;
       const canAct = () => currentSession() && ctx.isIdle() && branch === branchEpoch;
       try {
-        const current = await selected(ctx);
+        await checkCLI(ctx);
         if (!canAct()) return;
-        let settings = false;
+        const current = cliState === "ready" ? await selected(ctx) : null;
+        if (!canAct()) return;
+        let settings = cliState !== "ready";
         while (canAct()) {
+          if (!settings && cliState !== "ready") {
+            ctx.ui.notify(setupHint, "warning");
+            return;
+          }
           if (settings) {
-            const document = readFooterDocument();
-            const root = document.raw === null ? {} : JSON.parse(document.raw);
-            const config: PinoteSettings = {
-              footer: { ...document.config, fields: effectiveFooterFields(document.config, current?.agent_notes) },
-              handoffPrompt: "handoffPrompt" in root ? parseHandoffPrompt(root.handoffPrompt) : defaultHandoffPrompt,
-            };
-            let expectedRaw = document.raw;
-            const edited = await ctx.ui.custom<"tasks" | undefined>((tui, theme, kb, done) =>
+            let config: PinoteSettings = { footer: { ...defaultFooterConfig, fields: [] }, handoffPrompt: defaultHandoffPrompt };
+            let expectedRaw: string | null = null;
+            let configurationError: string | undefined;
+            try {
+              const document = readFooterDocument();
+              const root = document.raw === null ? {} : JSON.parse(document.raw);
+              config = {
+                footer: { ...document.config, fields: effectiveFooterFields(document.config, current?.agent_notes) },
+                handoffPrompt: "handoffPrompt" in root ? parseHandoffPrompt(root.handoffPrompt) : defaultHandoffPrompt,
+              };
+              expectedRaw = document.raw;
+            } catch (error) {
+              // Broken preferences must not strand task actions or CLI recovery.
+              // Offer actions only; never save defaults over invalid user data.
+              configurationError = clean(error instanceof Error ? error.message : String(error));
+            }
+            const options: SettingsOption[] = [
+              ...(current ? [
+                { label: "Preview task", result: "preview" as const },
+                { label: "Complete task (new session)", result: "done" as const },
+              ] : []),
+              ...(suggestion ? [
+                { label: "Accept suggestion", result: "yes" as const },
+                { label: "Dismiss suggestion", result: "no" as const },
+              ] : []),
+              ...(cliState === "setup" ? [{ label: "Install CLI", result: "setup" as const }]
+                : cliState === "upgrade" ? [{ label: "Upgrade CLI", result: "upgrade" as const }] : []),
+            ];
+            const edited = await ctx.ui.custom<SettingsResult>((tui, theme, kb, done) =>
               new FooterSettings(config, Object.keys(current?.agent_notes ?? {}).filter((name) => name !== "Bar"),
                 theme, (data, action) => kb.matches(data, action as Keybinding), done, () => tui.requestRender(),
                 () => new Editor(tui, {
@@ -578,14 +591,22 @@ export default function (pi: ExtensionAPI) {
                     noMatch: (line) => theme.fg("warning", line) },
                 }), (updated) => {
                   if (!canAct()) throw new Error("This session changed. Reopen settings before editing.");
+                  if (configurationError) throw new Error(configurationError);
                   const saved = saveFooterConfig(updated.footer, expectedRaw, updated.handoffPrompt);
                   expectedRaw = saved.raw;
                   footerConfig = saved.config;
                   void refresh(ctx);
-                }));
+                }, options, configurationError));
             if (!canAct() || edited === undefined) return;
-            settings = false;
-            continue;
+            if (edited === "tasks") { settings = false; continue; }
+            if (!options.some((option) => option.result === edited)) return;
+            if (pending === operation) pending = undefined;
+            if (edited === "preview") {
+              if (!await preview(ctx)) ctx.ui.notify("The task is no longer available for preview.", "warning");
+            } else if (edited === "done") await completeSelected("", ctx, current ?? undefined);
+            else if (edited === "yes" || edited === "no") await respondToSuggestion(edited, ctx);
+            else await installCLI(edited === "upgrade", ctx);
+            return;
           }
           const action = current
             ? await ctx.ui.custom<string | undefined>((tui, theme, kb, done) =>
@@ -733,20 +754,6 @@ export default function (pi: ExtensionAPI) {
       if (alive && generation === epoch) await refresh(ctx);
     }
   };
-  pi.registerCommand("pi-note-yes", {
-    description: "Create, start and select the suggested task (same as +)",
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI || ctx.mode !== "tui") return;
-      if (args.trim() || !await respondToSuggestion("yes", ctx)) ctx.ui.notify("No available suggestion, or a Pinote operation is busy. Retry when it finishes.", "warning");
-    },
-  });
-  pi.registerCommand("pi-note-no", {
-    description: "Dismiss the suggested task without creating a note (same as ✕)",
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI || ctx.mode !== "tui") return;
-      if (args.trim() || !await respondToSuggestion("no", ctx)) ctx.ui.notify("No available suggestion. Usage: /pi-note-no", "warning");
-    },
-  });
   pi.registerTool({
     name: "pinote_propose",
     label: "Pinote suggest task",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",

package/setup.ts

@@ -1,11 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { stripVTControlCharacters } from "node:util";
-import type { AutocompleteProvider } from "@earendil-works/pi-tui";
 
 // Immutable source: the Python app is not yet published to PyPI.
 export const cliSource = "https://github.com/kvidzibo/pinote/archive/1597baf60bff8bc96893be40781f152a001623d1.tar.gz";
 export const bundledCLIVersion = "0.4.0";
-export const setupHint = "Use /pi-note-setup for a missing CLI or /pi-note-upgrade for an older CLI; note must be on PATH.";
+export const setupHint = "Open /pi-note → Settings to install or upgrade the CLI; note must be on PATH.";
 export type CLIAction = "setup" | "upgrade" | "ready";
 
 export function cliAction(version: string): CLIAction {
@@ -27,23 +26,6 @@ export async function detectCLI(pi: ExtensionAPI, signal?: AbortSignal): Promise
   } catch { return "setup"; }
 }
 
-export function cliMenu(current: AutocompleteProvider, action: () => CLIAction | undefined): AutocompleteProvider {
-  return {
-    triggerCharacters: current.triggerCharacters,
-    async getSuggestions(...args) {
-      const suggestions = await current.getSuggestions(...args);
-      if (!suggestions || !/^\/\S*$/u.test(suggestions.prefix)) return suggestions;
-      const items = suggestions.items.filter(({ value }) => {
-        const name = value.replace(/^\//u, "");
-        return name === "pi-note-setup" ? action() === "setup"
-          : name === "pi-note-upgrade" ? action() === "upgrade" : true;
-      });
-      return items.length ? { ...suggestions, items } : null;
-    },
-    applyCompletion: (...args) => current.applyCompletion(...args),
-    shouldTriggerFileCompletion: (...args) => current.shouldTriggerFileCompletion?.(...args) ?? true,
-  };
-}
 export function versionAtLeast(version: string, minimum: string): boolean {
   const match = /^pinote (\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
   if (!match) return false;
@@ -72,7 +54,7 @@ export async function setupCLI(
     ctx.ui.notify(`Pinote CLI is ready (bundled version ${bundledCLIVersion} or newer). Use /pi-note.`, "info");
     return;
   }
-  const command = action === "upgrade" ? "/pi-note-upgrade" : "/pi-note-setup";
+  const command = `/pi-note → Settings → ${action === "upgrade" ? "Upgrade CLI" : "Install CLI"}`;
   if (upgrade !== (action === "upgrade")) {
     ctx.ui.notify(`Use ${command} ${action === "upgrade" ? "to upgrade the older CLI" : "to install the missing CLI"}.`, "info");
     return;