@zosmaai/pi-llm-wiki 0.9.0 → 0.9.2

package/extensions/llm-wiki/lib/tools.ts

@@ -44,6 +44,55 @@ function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: st
   return { ok: true };
 }
 
+type WikiToolResult = {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+  isError?: boolean;
+};
+
+type ToolCtx = {
+  cwd?: string;
+  hasUI: boolean;
+  ui?: { notify: (message: string, type?: string) => void };
+};
+
+/**
+ * Dispatch a heavy mutating action to the background runtime and report its
+ * result (issue #77). The agent turn is never blocked: `work` runs off-thread
+ * and the returned one-line summary is surfaced to the user via
+ * `runtime.report()`. Returns an immediate, non-blocking tool result.
+ *
+ * When no runtime is available (unit tests / degraded mode), `work` runs
+ * synchronously and its summary is returned inline, preserving prior behavior.
+ * Retrieval tools (search/read/recall/status) never use this — the model needs
+ * their output inline.
+ */
+async function dispatchReported(
+  runtime: Runtime | undefined,
+  ctx: ToolCtx,
+  opts: {
+    label: string;
+    /** Immediate, non-blocking acknowledgement shown while work runs. */
+    started: string;
+    /** Off-thread work; resolves to the human-readable completion summary. */
+    work: () => Promise<string>;
+    details?: Record<string, unknown>;
+  },
+): Promise<WikiToolResult> {
+  if (!runtime) {
+    const summary = await opts.work();
+    return {
+      content: [{ type: "text", text: summary }],
+      details: { background: false, ...opts.details },
+    };
+  }
+  runtime.launchReported({ hasUI: ctx.hasUI, ui: ctx.ui }, opts.label, opts.work);
+  return {
+    content: [{ type: "text", text: opts.started }],
+    details: { background: true, ...opts.details },
+  };
+}
+
 // ─── 1. wiki_bootstrap ──────────────────────────────────
 
 export function registerWikiBootstrap(pi: ExtensionAPI): void {
@@ -381,14 +430,15 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
                 ];
                 launchEmbedPages(runtime, launchCtx, paths, pageIds, `embed:ingest:${s.id}`);
               }
+              const summary = committed
+                ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
+                : `LLM Wiki: ${s.id} produced no synthesis`;
               if (ctx.hasUI) {
-                ctx.ui.notify(
-                  committed
-                    ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
-                    : `LLM Wiki: ${s.id} produced no synthesis`,
-                  committed ? "info" : "warning",
-                );
+                ctx.ui.notify(summary, committed ? "info" : "warning");
               }
+              // Persistent, user-visible completion report (issue #77) in
+              // addition to the transient toast above. Notices-gated.
+              runtime.report(committed ? `✅ ${summary}` : `⚠️ ${summary}`);
             });
           }
           return {
@@ -463,7 +513,8 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
     ],
     parameters: Type.Object({
       type: Type.String({
-        description: "Page type: entity | concept | synthesis | analysis | requirement",
+        description:
+          "Page type: entity | concept | synthesis | analysis | requirement | skill | case",
       }),
       title: Type.String({ description: "Page title" }),
       content: Type.Optional(
@@ -481,7 +532,14 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
         };
       }
 
-      const type = params.type as "entity" | "concept" | "synthesis" | "analysis";
+      const type = params.type as
+        | "entity"
+        | "concept"
+        | "synthesis"
+        | "analysis"
+        | "requirement"
+        | "skill"
+        | "case";
       const slug = params.title
         .toLowerCase()
         .replace(/[^a-z0-9\s-]/g, "")
@@ -495,6 +553,8 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
         synthesis: "syntheses",
         analysis: "analyses",
         requirement: "requirements",
+        skill: "skills",
+        case: "cases",
       };
       const folder = folderMap[type] || "concepts";
       const pagePath = join(paths.wiki, folder, `${slug}.md`);
@@ -572,6 +632,76 @@ function buildPageTemplate(
       "Durable answer from a query.\n\n## Question\n\n[Original question]",
     );
   }
+  if (type === "skill") {
+    return [
+      "---",
+      "type: skill",
+      `created: ${date}`,
+      `updated: ${date}`,
+      "status: draft",
+      "trajectories: []",
+      "tags: []",
+      "---",
+      "",
+      `# ${title}`,
+      "",
+      "_One-line summary of the reusable pattern this skill captures._",
+      "",
+      "## When to Use",
+      "",
+      "[Trigger conditions — when this pattern applies]",
+      "",
+      "## Procedure",
+      "",
+      "1. [Step 1]",
+      "2. [Step 2]",
+      "",
+      "## Pitfalls",
+      "",
+      "- [Known failure mode or caveat]",
+      "",
+      "## Distilled From",
+      "",
+      "_Trajectories this skill was generalized from._",
+      "",
+      "- [[trajectories/TRJ-...]]",
+      "",
+    ].join("\n");
+  }
+  if (type === "case") {
+    return [
+      "---",
+      "type: case",
+      `created: ${date}`,
+      `updated: ${date}`,
+      "status: draft",
+      "outcome: success",
+      "trajectory_id: ",
+      "tags: []",
+      "---",
+      "",
+      `# ${title}`,
+      "",
+      "_One-line summary of the specific task this case records._",
+      "",
+      "## Task",
+      "",
+      "[What was requested]",
+      "",
+      "## Approach",
+      "",
+      "[How the agent solved it — key steps and decisions]",
+      "",
+      "## Outcome",
+      "",
+      "[Result, and anything worth reusing or avoiding next time]",
+      "",
+      "## Trajectory",
+      "",
+      "- [[trajectories/TRJ-...]] — captured tool-call run",
+      "",
+    ].join("\n");
+  }
   if (type === "requirement") {
     return [
       "---",
@@ -672,7 +802,7 @@ export function registerWikiSearch(pi: ExtensionAPI): void {
 
 // ─── 6. wiki_lint ───────────────────────────────────────
 
-export function registerWikiLint(pi: ExtensionAPI): void {
+export function registerWikiLint(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_lint",
     label: "Wiki Lint",
@@ -699,138 +829,143 @@ export function registerWikiLint(pi: ExtensionAPI): void {
         };
       }
 
-      const pages = findWikiPages(paths.wiki);
-      const registry = buildRegistry(paths);
-      buildBacklinks(paths, registry); // ensures backlinks.json is current
-
-      const findings: string[] = [];
-      let orphans = 0;
-      let missingPages = 0;
-      let contradictions = 0;
-      const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
-
-      const allPageIds = new Set(pages.map((p) => p.relative));
-      const linkCounts: Record<string, number> = {};
-
-      for (const page of pages) {
-        const links = extractWikilinks(page.content);
-        for (const link of links) {
-          if (!allPageIds.has(link)) {
-            missingPages++;
-            findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
-            const existing = gaps.find((g) => g.topic === link);
-            if (existing) {
-              if (!existing.mentionedBy.includes(page.relative))
-                existing.mentionedBy.push(page.relative);
-            } else {
-              gaps.push({ topic: link, mentionedBy: [page.relative] });
-            }
-          } else {
-            linkCounts[link] = (linkCounts[link] || 0) + 1;
-          }
-        }
-      }
+      // Full-vault scan (+ optional auto-fix writes + reindex) is O(pages):
+      // run it in the background and report the health summary (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `lint:${paths.root}`,
+        started:
+          "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted when it completes.",
+        work: async () => runWikiLint(paths, params.auto_fix === true),
+      });
+    },
+  });
+}
 
-      for (const page of pages) {
-        if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
-          orphans++;
-          findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+/**
+ * Run the wiki health scan (issue #77 extracted it from the tool body so it can
+ * run off-thread via `dispatchReported`). Returns the human-readable summary.
+ */
+function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
+  const pages = findWikiPages(paths.wiki);
+  const registry = buildRegistry(paths);
+  buildBacklinks(paths, registry); // ensures backlinks.json is current
+
+  const findings: string[] = [];
+  let orphans = 0;
+  let missingPages = 0;
+  let contradictions = 0;
+  const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
+
+  const allPageIds = new Set(pages.map((p) => p.relative));
+  const linkCounts: Record<string, number> = {};
+
+  for (const page of pages) {
+    const links = extractWikilinks(page.content);
+    for (const link of links) {
+      if (!allPageIds.has(link)) {
+        missingPages++;
+        findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
+        const existing = gaps.find((g) => g.topic === link);
+        if (existing) {
+          if (!existing.mentionedBy.includes(page.relative))
+            existing.mentionedBy.push(page.relative);
+        } else {
+          gaps.push({ topic: link, mentionedBy: [page.relative] });
         }
+      } else {
+        linkCounts[link] = (linkCounts[link] || 0) + 1;
       }
+    }
+  }
 
-      for (const page of pages) {
-        if (page.content.includes("⚠️ **Contradiction")) {
-          contradictions++;
-          findings.push(`Contradiction flagged in [[${page.relative}]]`);
-        }
-      }
+  for (const page of pages) {
+    if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
+      orphans++;
+      findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+    }
+  }
 
-      let fixesApplied = 0;
-      if (params.auto_fix) {
-        for (const gap of gaps) {
-          if (gap.mentionedBy.length >= 2) {
-            const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
-            const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
-            const pagePath = join(paths.wiki, folder, `${name}.md`);
-            if (!existsSync(pagePath)) {
-              mkdirSync(join(paths.wiki, folder), { recursive: true });
-              writeFileSync(
-                pagePath,
-                `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
-                "utf-8",
-              );
-              fixesApplied++;
-            }
-          }
+  for (const page of pages) {
+    if (page.content.includes("⚠️ **Contradiction")) {
+      contradictions++;
+      findings.push(`Contradiction flagged in [[${page.relative}]]`);
+    }
+  }
+
+  let fixesApplied = 0;
+  if (autoFix) {
+    for (const gap of gaps) {
+      if (gap.mentionedBy.length >= 2) {
+        const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
+        const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
+        const pagePath = join(paths.wiki, folder, `${name}.md`);
+        mkdirSync(join(paths.wiki, folder), { recursive: true });
+        try {
+          // Atomic create-if-absent: the `wx` flag fails with EEXIST instead of
+          // overwriting, avoiding the existsSync→write TOCTOU race (CodeQL).
+          writeFileSync(
+            pagePath,
+            `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
+            { encoding: "utf-8", flag: "wx" },
+          );
+          fixesApplied++;
+        } catch (err) {
+          // Page already exists — nothing to fix. Re-throw anything else.
+          if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
         }
       }
+    }
+  }
 
-      writeJson(join(paths.discoveries, "gaps.json"), {
-        gaps,
-        generated: new Date().toISOString(),
-      });
-
-      const reportLines = [
-        "# Wiki Lint Report",
-        `Generated: ${fmtDate()}`,
-        "",
-        "## Summary",
-        `- Total pages: ${pages.length}`,
-        `- Orphans: ${orphans}`,
-        `- Missing pages: ${missingPages}`,
-        `- Contradictions: ${contradictions}`,
-        params.auto_fix ? `- Fixes applied: ${fixesApplied}` : "",
-        "",
-        "## Findings",
-        findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
-        "",
-      ].filter(Boolean);
-
-      const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
-      mkdirSync(paths.outputs, { recursive: true });
-      writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
-
-      appendEvent(paths, {
-        kind: "lint",
-        orphans,
-        missing_pages: missingPages,
-        contradictions,
-        auto_fix: params.auto_fix ?? false,
-      });
-
-      rebuildMetadataLight(paths);
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: [
-              "🧹 **Lint complete**",
-              "",
-              `- Pages: ${pages.length}`,
-              `- Orphans: ${orphans}`,
-              `- Missing: ${missingPages}`,
-              `- Contradictions: ${contradictions}`,
-              params.auto_fix ? `- Auto-fixes: ${fixesApplied}` : "",
-              "",
-              `📄 Report: \`${reportPath}\``,
-              gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
-            ]
-              .filter(Boolean)
-              .join("\n"),
-          },
-        ],
-        details: {
-          pages: pages.length,
-          orphans,
-          missingPages,
-          contradictions,
-          reportPath,
-          gaps: gaps.length,
-        } as Record<string, unknown>,
-      };
-    },
+  const reportLines = [
+    "# Wiki Lint Report",
+    `Generated: ${fmtDate()}`,
+    "",
+    "## Summary",
+    `- Total pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing pages: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Fixes applied: ${fixesApplied}` : "",
+    "",
+    "## Findings",
+    findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
+    "",
+  ].filter(Boolean);
+
+  const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
+  mkdirSync(paths.outputs, { recursive: true });
+  writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
+
+  appendEvent(paths, {
+    kind: "lint",
+    orphans,
+    missing_pages: missingPages,
+    contradictions,
+    auto_fix: autoFix,
   });
+
+  rebuildMetadataLight(paths);
+
+  return [
+    "🧹 **LLM Wiki lint complete**",
+    "",
+    `- Pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Auto-fixes: ${fixesApplied}` : "",
+    "",
+    `📄 Report: \`${reportPath}\``,
+    gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
 }
 
 // ─── 7. wiki_status ─────────────────────────────────────
@@ -912,7 +1047,7 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
 
 // ─── 8. wiki_rebuild_meta ───────────────────────────────
 
-export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
+export function registerWikiRebuildMeta(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_rebuild_meta",
     label: "Wiki Rebuild Meta",
@@ -931,24 +1066,23 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
         };
       }
 
-      rebuildMetadata(paths);
-      appendEvent(paths, { kind: "rebuild_meta" });
-
-      const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
-        version: "1.0",
-        last_updated: "",
-        pages: {},
+      // Heavy O(pages) rebuild — dispatch off the agent's critical path and
+      // report on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `rebuild_meta:${paths.root}`,
+        started:
+          "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported when it completes.",
+        work: async () => {
+          rebuildMetadata(paths);
+          appendEvent(paths, { kind: "rebuild_meta" });
+          const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
+            version: "1.0",
+            last_updated: "",
+            pages: {},
+          });
+          return `✅ LLM Wiki: metadata rebuilt — ${Object.keys(registry.pages).length} pages indexed.`;
+        },
       });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Metadata rebuilt. ${Object.keys(registry.pages).length} pages indexed.`,
-          },
-        ],
-        details: { pageCount: Object.keys(registry.pages).length } as Record<string, unknown>,
-      };
     },
   });
 }
@@ -998,28 +1132,24 @@ export function registerWikiReindexEmbeddings(pi: ExtensionAPI, runtime?: Runtim
         };
       }
 
-      const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });
-      appendEvent(paths, {
-        kind: "reindex_embeddings",
-        embedded: stats.embedded,
-        skipped: stats.skipped,
-        pruned: stats.pruned,
-        model: embedder.model,
+      // Embedding is network-bound and O(pages) — run it in the background and
+      // report the stats on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `reindex_embeddings:${paths.root}`,
+        started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported when it completes.`,
+        details: { enabled: true, model: embedder.model },
+        work: async () => {
+          const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });
+          appendEvent(paths, {
+            kind: "reindex_embeddings",
+            embedded: stats.embedded,
+            skipped: stats.skipped,
+            pruned: stats.pruned,
+            model: embedder.model,
+          });
+          return `✅ LLM Wiki: embeddings reindexed (${embedder.model}) — ${stats.embedded} embedded, ${stats.skipped} fresh, ${stats.pruned} pruned.`;
+        },
       });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Embeddings reindexed (${embedder.model}): ${stats.embedded} embedded, ${stats.skipped} fresh, ${stats.pruned} pruned.`,
-          },
-        ],
-        details: {
-          enabled: true,
-          ...stats,
-          model: embedder.model,
-        } as Record<string, unknown>,
-      };
     },
   });
 }
@@ -1067,10 +1197,12 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "wiki_watch",
     label: "Wiki Watch",
-    description: "Schedule automatic wiki updates (discover → ingest → lint) via pi's cron system.",
+    description:
+      "Print a ready-to-paste crontab line for scheduling automatic wiki updates (discover → ingest → lint). Does NOT schedule anything itself — it returns the command for the user to install.",
     promptSnippet: "Schedule auto-updates for the wiki",
     promptGuidelines: [
       "Use wiki_watch when the user wants the wiki to stay current automatically.",
+      "wiki_watch only PRINTS a cron line — surface the output to the user verbatim so they can install it. Do not claim the schedule is active.",
     ],
     parameters: Type.Object({
       interval: Type.String({ description: "daily, weekly, hourly, or stop" }),
@@ -1082,15 +1214,16 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
             {
               type: "text",
               text: [
-                "🛑 To stop wiki auto-updates:",
+                "🛑 To stop wiki auto-updates, remove the cron line you installed earlier:",
                 "",
+                "```bash",
+                "crontab -e   # then delete the line tagged '# llm-wiki-autoupdate'",
                 "```",
-                "schedule_prompt action=list",
-                "```",
-                "Find the wiki job IDs, then:",
                 "",
-                "```",
-                "schedule_prompt action=remove jobId=<id>",
+                "Or list current jobs to confirm:",
+                "",
+                "```bash",
+                "crontab -l | grep llm-wiki-autoupdate",
                 "```",
               ].join("\n"),
             },
@@ -1099,10 +1232,11 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
         };
       }
 
+      // 5-field POSIX crontab expressions (min hour dom month dow).
       const intervals: Record<string, { cron: string; label: string }> = {
-        daily: { cron: "0 0 8 * * *", label: "Daily at 8:00 AM" },
-        weekly: { cron: "0 0 9 * * 1", label: "Weekly on Monday at 9:00 AM" },
-        hourly: { cron: "0 0 * * * *", label: "Every hour" },
+        daily: { cron: "0 8 * * *", label: "Daily at 8:00 AM" },
+        weekly: { cron: "0 9 * * 1", label: "Weekly on Monday at 9:00 AM" },
+        hourly: { cron: "0 * * * *", label: "Every hour" },
       };
 
       const config = intervals[params.interval];
@@ -1119,18 +1253,37 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
         };
       }
 
+      // Robustness for global crontab environments:
+      //   * `/bin/bash -lc` runs a LOGIN shell that sources /etc/profile +
+      //     ~/.profile / ~/.bash_profile, so npm-global / bun / nvm PATH
+      //     additions are imported — cron's default PATH is only
+      //     `/usr/bin:/bin` and would not find `pi`.
+      //   * `mkdir -p` makes the log dir self-healing for users with only
+      //     a project vault (no `~/.llm-wiki/` yet).
+      //   * All `$HOME` references are double-quoted to survive paths with spaces.
+      //   * `# llm-wiki-autoupdate` tags the line so the user can find and
+      //     remove it via `crontab -e` later (see `interval=stop`).
+      const cronLine = `${config.cron} /bin/bash -lc 'mkdir -p "$HOME/.llm-wiki" && pi -p "/wiki-run" >> "$HOME/.llm-wiki/cron.log" 2>&1' # llm-wiki-autoupdate`;
+
       return {
         content: [
           {
             type: "text",
             text: [
-              `⏰ To set up ${config.label} wiki updates, run:`,
+              `⏰ To set up ${config.label} wiki updates, add this line to your crontab.`,
+              "**This tool only prints the line — it does not install it.**",
               "",
+              "```bash",
+              "crontab -e",
               "```",
-              `schedule_prompt action=add schedule="${config.cron}" prompt="Run /wiki:run for the LLM Wiki" name="llm-wiki-autoupdate"`,
+              "",
+              "Then append:",
+              "",
+              "```cron",
+              cronLine,
               "```",
               "",
-              "This will auto-discover, ingest, and lint on schedule.",
+              `The line uses \`/bin/bash -lc\` so your shell profile (and the \`pi\` binary on npm-global / bun PATH) is loaded. Output goes to \`~/.llm-wiki/cron.log\`. If your system has no \`/bin/bash\`, replace with \`/bin/sh -c\` and ensure \`pi\` is in cron's PATH yourself.`,
             ].join("\n"),
           },
         ],
@@ -1138,6 +1291,8 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
           interval: params.interval,
           cronSchedule: config.cron,
           label: config.label,
+          cronLine,
+          installed: false,
         } as Record<string, unknown>,
       };
     },