decorated-pi 0.7.0 → 0.7.2

package/hooks/smart-at.ts

@@ -1,318 +1,176 @@
 /**
  * smart-at — high-speed file search autocomplete.
  *
- * Triggered on session_start by registering an autocomplete provider.
- * Uses git ls-files (in git repos) or fd (elsewhere) for candidates,
- * then fuzzy-matches with path penalties.
+ * Uses @ff-labs/fff-node (FFF) for cross-platform fuzzy file search.
+ * FFF maintains an in-memory index, scores files by fuzzy match +
+ * frecency + git status, and returns ranked results. We create one
+ * FileFinder per session and query it directly for every @ prefix.
+ *
+ * KNOWN FFF LIMITATION (v0.9.4):
+ * FFF only returns directories that directly contain files. Intermediate
+ * folders that only hold subdirectories (e.g. product/module/apmanage/ where
+ * all files live in product/module/apmanage/deep/) will not appear in
+ * mixedSearch/directorySearch results, even though the files underneath do.
+ * We intentionally do NOT synthesize these directories on the TypeScript side
+ * to avoid extra complexity/cost; the fix belongs upstream.
  */
 
-import { spawnSync } from "child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { FileFinder, type MixedItem } from "@ff-labs/fff-node";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Module, Skeleton } from "./skeleton.js";
 
-// ─── Types ────────────────────────────────────────────────────────────────
-
-type PenaltyTier = 0 | 1 | 2 | 3 | 4;
-
-interface FileCandidate {
-  path: string;
-  name: string;
-  isDir: boolean;
-  tier: PenaltyTier;
-  penalty: number;
-}
-
-// ─── Hard-exclude & penalty rules ────────────────────────────────────────
-
-const HARD_EXCLUDE_DIRS = new Set(["node_modules", ".git", ".pnpm", ".svn"]);
-
-const BAD_DIRS = new Set(["build", "dist", "coverage", "out", "target"]);
-
-const EXT_PENALTY: Record<string, number> = {
-  o: -150, obj: -150, a: -150, so: -150, dll: -150, exe: -150,
-  wasm: -150, class: -120, pyc: -120,
-  bmp: -100, png: -100, jpg: -100, gif: -100, ico: -100, svg: -80,
-  mp3: -100, wav: -100, mp4: -100, avi: -100,
-  pdf: -100, zip: -100, tar: -100, gz: -100,
-  lock: -80,
-};
-
-// ─── Penalty pre-compute ─────────────────────────────────────────────────
+// Characters that, when preceding an "@", allow us to start a smart-at
+// completion.
+const AT_BOUNDARY = new Set<string>([" ", "\t", "(", "["]);
 
-function computePenaltyMeta(filePath: string, isDir: boolean, gitIgnored: boolean): { tier: PenaltyTier; penalty: number } {
-  const parts = filePath.replace(/\/$/, "").split("/");
-  const name = parts[parts.length - 1] || filePath;
-  const ext = (!isDir && name.includes(".")) ? (name.split(".").pop()?.toLowerCase() || "") : "";
-  const depth = parts.length;
-  const dirSegments = isDir ? parts : parts.slice(0, -1);
-
-  let tier: PenaltyTier = 0;
-  let tierPenalty = 0;
-
-  if (gitIgnored) { tier = 1; tierPenalty = -400; }
-  else if (dirSegments.some(d => d.startsWith(".") || d.startsWith("__"))) { tier = 2; tierPenalty = -300; }
-  else if (dirSegments.some(d => BAD_DIRS.has(d))) { tier = 3; tierPenalty = -200; }
-  else if (!isDir && (EXT_PENALTY[ext] ?? 0) < 0) { tier = 4; tierPenalty = EXT_PENALTY[ext]!; }
-
-  const basePenalty = -(depth * 30) - name.length;
-  return { tier, penalty: tierPenalty + basePenalty };
-}
-
-function computePenalty(filePath: string, isDir: boolean, gitIgnored: boolean): number {
-  return computePenaltyMeta(filePath, isDir, gitIgnored).penalty;
-}
-
-// ─── Candidate collection ────────────────────────────────────────────────
-
-const SPAWN_OPTS = { timeout: 5000, encoding: "utf-8" as const, maxBuffer: 10 * 1024 * 1024 };
-
-function isGitWorkTree(cwd: string): boolean {
-  return spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { ...SPAWN_OPTS, cwd }).status === 0;
-}
+const AUTOCOMPLETE_LIMIT = 20;
+const FFF_SUPERSET = 100;
+const WIDGET_FOOTER = "\x1b[2mpowered by fff\x1b[0m";
 
-function commandExists(command: string): boolean {
-  const result = spawnSync(
-    process.platform === "win32" ? "where" : (process.env.SHELL || "sh"),
-    process.platform === "win32" ? [command] : ["-lc", `command -v '${command.replace(/'/g, `'"'"'`)}'`],
-    SPAWN_OPTS,
-  );
-  return result.status === 0;
+interface AutocompleteItem {
+  value: string;
+  label: string;
+  description?: string;
 }
 
-function collectCandidates(cwd: string): FileCandidate[] {
-  const candidates: FileCandidate[] = [];
-  const isChildOfHardExclude = (p: string): boolean => {
-    const parts = p.replace(/\/$/, "").split("/");
-    for (let i = 0; i < parts.length - 1; i++) {
-      if (HARD_EXCLUDE_DIRS.has(parts[i]!)) return true;
-    }
-    return false;
-  };
-
-  const opts = { ...SPAWN_OPTS, cwd };
-  const isGit = isGitWorkTree(cwd);
-
-  if (isGit) {
-    const r1 = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], opts);
-    const visibleFiles = (r1.status === 0 && r1.stdout)
-      ? r1.stdout.trim().split("\n").filter(Boolean) : [];
-
-    const r2 = spawnSync("git", ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "--no-empty-directory"], opts);
-    const ignoredDirs = new Set<string>();
-    const ignoredFiles: string[] = [];
-    if (r2.status === 0 && r2.stdout) {
-      for (const raw of r2.stdout.trim().split("\n").filter(Boolean)) {
-        const entry = raw.replace(/^\.\//, "");
-        if (isChildOfHardExclude(entry)) continue;
-        if (entry.endsWith("/")) ignoredDirs.add(entry.replace(/\/$/, ""));
-        else ignoredFiles.push(entry);
-      }
-    }
-
-    const dirSet = new Set<string>();
-    for (const f of visibleFiles) {
-      if (isChildOfHardExclude(f)) continue;
-      const name = f.split("/").pop() || f;
-      const meta = computePenaltyMeta(f, false, false);
-      candidates.push({ path: f, name, isDir: false, tier: meta.tier, penalty: meta.penalty });
-      const parts = f.split("/");
-      let current = "";
-      for (let i = 0; i < parts.length - 1; i++) {
-        current = current ? `${current}/${parts[i]}` : parts[i]!;
-        dirSet.add(current);
-      }
-    }
-    for (const f of ignoredFiles) {
-      const name = f.split("/").pop() || f;
-      const meta = computePenaltyMeta(f, false, true);
-      candidates.push({ path: f, name, isDir: false, tier: meta.tier, penalty: meta.penalty });
-    }
-    for (const d of dirSet) {
-      const name = d.split("/").pop() || d;
-      const meta = computePenaltyMeta(d, true, false);
-      candidates.push({ path: d + "/", name, isDir: true, tier: meta.tier, penalty: meta.penalty });
-    }
-    for (const d of ignoredDirs) {
-      const name = d.split("/").pop() || d;
-      const meta = computePenaltyMeta(d, true, true);
-      candidates.push({ path: d + "/", name, isDir: true, tier: meta.tier, penalty: meta.penalty });
-    }
-    for (const hd of HARD_EXCLUDE_DIRS) {
-      if (!existsSync(join(opts.cwd, hd))) continue;
-      const meta = computePenaltyMeta(hd, true, false);
-      candidates.push({ path: hd + "/", name: hd, isDir: true, tier: meta.tier, penalty: meta.penalty });
-    }
-  } else {
-    const rel = (s: string) => {
-      let r = s.startsWith(cwd + "/") ? s.slice(cwd.length + 1) : s;
-      return r.startsWith("./") ? r.slice(2) : r;
-    };
-    const fdExcludes = [...HARD_EXCLUDE_DIRS].flatMap(d => ["--exclude", d]);
-    const fdOpts = { ...SPAWN_OPTS, cwd: undefined as string | undefined };
-
-    const r1 = spawnSync("fd", ["--type", "f", "--hidden", "--no-ignore", ...fdExcludes, ".", cwd], fdOpts);
-    if (r1.status === 0 && r1.stdout) {
-      for (const raw of r1.stdout.trim().split("\n").filter(Boolean)) {
-        const f = rel(raw);
-        const name = f.split("/").pop() || f;
-        const meta = computePenaltyMeta(f, false, false);
-        candidates.push({ path: f, name, isDir: false, tier: meta.tier, penalty: meta.penalty });
-      }
-    }
-    const r2 = spawnSync("fd", ["--type", "d", "--hidden", "--no-ignore", ...fdExcludes, ".", cwd], fdOpts);
-    if (r2.status === 0 && r2.stdout) {
-      for (const raw of r2.stdout.trim().split("\n").filter(Boolean)) {
-        const d = rel(raw).replace(/\/$/, "");
-        const name = d.split("/").pop() || d;
-        const meta = computePenaltyMeta(d, true, false);
-        candidates.push({ path: d + "/", name, isDir: true, tier: meta.tier, penalty: meta.penalty });
-      }
-    }
-    for (const hd of HARD_EXCLUDE_DIRS) {
-      if (!existsSync(join(cwd, hd))) continue;
-      const meta = computePenaltyMeta(hd, true, false);
-      candidates.push({ path: hd + "/", name: hd, isDir: true, tier: meta.tier, penalty: meta.penalty });
+function atPrefix(text: string): string | null {
+  for (let i = text.length - 1; i >= 0; i--) {
+    if (text[i] !== "@") continue;
+    const b = text[i - 1];
+    if (i === 0 || AT_BOUNDARY.has(b)) {
+      return text.slice(i);
     }
+    return null;
   }
-  return candidates;
+  return null;
 }
 
-// ─── Match scoring ───────────────────────────────────────────────────────
-
-function fuzzyScore(text: string, query: string): number {
-  let qi = 0, firstMatch = -1, lastMatch = -1;
-  for (let ti = 0; ti < text.length && qi < query.length; ti++) {
-    if (text[ti] === query[qi]) {
-      if (firstMatch < 0) firstMatch = ti;
-      lastMatch = ti;
-      qi++;
-    }
-  }
-  if (qi < query.length) return 0;
-  const span = lastMatch - firstMatch + 1;
-  return Math.max(10, 200 - span * 3 - text.length);
+function isGitIgnored(item: MixedItem): boolean {
+  return item.type === "file" && item.item.gitStatus === "ignored";
 }
 
-function computeMatchScore(candidate: FileCandidate, query: string): number {
-  const { path: filePath, name, isDir } = candidate;
-  const stem = name.replace(/\.[^.]+$/, "");
-  const parts = filePath.replace(/\/$/, "").split("/");
-  const inDir = parts.slice(0, -1).some(d => d.includes(query));
-
-  let s = 0;
-  if (stem === query) s = isDir ? 1500 : 1050;
-  else if (name.startsWith(query + ".") || name.startsWith(query + "_")) s = 1000;
-  else if (name.startsWith(query)) s = 900;
-  else if (name.includes(query)) s = 600;
-  else if (filePath.includes(query)) s = 300;
-  else s = fuzzyScore(name, query);
-
-  if (!s) return 0;
-  if (isDir) s += 100;
-  if (inDir) s += 50;
-  return s;
+function toAutocompleteItem(item: MixedItem): AutocompleteItem {
+  const path = item.item.relativePath;
+  const label = item.type === "file"
+    ? item.item.fileName
+    : path.replace(/\/+$/, "").split("/").pop() || path;
+  return {
+    value: "@" + path,
+    label,
+    description: path,
+  };
 }
 
-function smartSearch(candidates: FileCandidate[], query: string): string[] {
-  if (!query) {
-    const visible = candidates.filter(c => c.tier === 0 || c.tier === 3 || c.tier === 4);
-    return visible
-      .sort((a, b) => {
-        if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-        return b.penalty - a.penalty || a.path.localeCompare(b.path);
-      })
-      .slice(0, 20)
-      .map(c => c.path);
-  }
-  const tokens = query.split(/\s+/).filter(Boolean);
-  if (tokens.length === 1) {
-    const scored = candidates
-      .map(c => ({ path: c.path, total: computeMatchScore(c, tokens[0]!) + c.penalty, matchScore: computeMatchScore(c, tokens[0]!) }))
-      .filter(x => x.matchScore > 0);
-    return scored
-      .sort((a, b) => b.total - a.total || a.path.localeCompare(b.path))
-      .slice(0, 20)
-      .map(x => x.path);
-  }
-  const seen = new Set<string>();
-  for (const t of tokens) {
-    const scored = candidates
-      .map(c => ({ path: c.path, total: computeMatchScore(c, t) + c.penalty, matchScore: computeMatchScore(c, t) }))
-      .filter(x => x.matchScore > 0)
-      .sort((a, b) => b.total - a.total)
-      .slice(0, 20);
-    for (const { path } of scored) seen.add(path);
-  }
-  return [...seen].slice(0, 20);
+interface BuiltResult {
+  items: AutocompleteItem[];
 }
 
-function atPrefix(text: string): string | null {
-  for (let i = text.length - 1; i >= 0; i--) {
-    if (text[i] !== "@") continue;
-    const b = text[i - 1];
-    if (i === 0 || b === " " || b === "\t" || b === "(" || b === "[") return text.slice(i);
-    return null;
-  }
-  return null;
+/** Take FFF's ranked results, drop git-ignored files, and for non-empty
+ *  queries keep only paths that contain the query as a substring. This
+ *  stops FFF's loose fuzzy matching from ranking every file in a directory
+ *  that happens to share a few letters (e.g. "mm/" for query "mmc"). */
+function buildResult(items: MixedItem[], lowerQuery: string): BuiltResult | null {
+  const filtered = items
+    .filter((it) => !isGitIgnored(it))
+    .filter(
+      (it) =>
+        !lowerQuery || it.item.relativePath.toLowerCase().includes(lowerQuery),
+    )
+    .slice(0, AUTOCOMPLETE_LIMIT)
+    .map(toAutocompleteItem);
+  return filtered.length ? { items: filtered } : null;
 }
 
-export const __smartAtTest = {
-  computePenaltyMeta, computePenalty, fuzzyScore, computeMatchScore, smartSearch, atPrefix,
-};
+export const __smartAtTest = { atPrefix };
+
+/** Active FileFinder for the current session; freed in session_shutdown
+ *  to avoid leaking FFF's native handle + LMDB mmap regions. */
+let currentFinder: FileFinder | null = null;
 
 export const smartAtModule: Module = {
   name: "smart-at",
   hooks: {
     session_start: [
-      (_event: any, ctx: ExtensionContext) => {
+      async (_event: any, ctx: ExtensionContext) => {
         const cwd = String(ctx.cwd || "").trim();
-        let cache: FileCandidate[] | null = null;
+        const created = FileFinder.create({ basePath: cwd || "." });
+        if (!created.ok) {
+          // FFF not available on this platform; silently skip.
+          return;
+        }
+
+        const finder = created.value;
+        currentFinder = finder;
 
-        const getOrBuildCache = () => (cache ??= collectCandidates(cwd));
-        const clearCache = () => { cache = null; };
+        // Start the scan in the background. We don't wait for it here so
+        // session_start returns immediately; the provider queries the
+        // (possibly partial) index and FFF returns whatever it has indexed
+        // so far. Full results appear as the scan progresses.
+        void finder.waitForScan(60_000);
 
         ctx.ui.addAutocompleteProvider((orig: any) => ({
-          getSuggestions: (lines: any, cl: any, cc: any, opts: any) => {
+          getSuggestions: (
+            lines: string[],
+            cl: number,
+            cc: number,
+            opts?: { signal?: AbortSignal },
+          ) => {
             const prefix = atPrefix((lines[cl] || "").slice(0, cc));
             if (!prefix) {
-              clearCache();
               ctx.ui.setWidget("smart-at", undefined);
               return orig.getSuggestions(lines, cl, cc, opts);
             }
-            const candidates = getOrBuildCache();
-            const results = smartSearch(candidates, prefix.slice(1));
-            if (!results.length) {
+
+            if (currentFinder !== finder || finder.isDestroyed) {
               ctx.ui.setWidget("smart-at", undefined);
-              return null;
+              return orig.getSuggestions(lines, cl, cc, opts);
             }
-            ctx.ui.setWidget("smart-at", ["\x1b[2mpowered by decorated-pi\x1b[0m"]);
-            return Promise.resolve({
-              items: results.map((f: string) => ({
-                value: "@" + f,
-                label: f.replace(/\/$/, "").split("/").pop() || f,
-                description: f,
-              })),
-              prefix,
+
+            // Respect upstream cancellation so fast typing doesn't pile up
+            // expensive FFF queries.
+            if (opts?.signal?.aborted) {
+              return orig.getSuggestions(lines, cl, cc, opts);
+            }
+
+            const query = prefix.slice(1);
+            const lowerQuery = query.toLowerCase();
+            const r = finder.mixedSearch(lowerQuery, {
+              pageSize: lowerQuery ? FFF_SUPERSET : AUTOCOMPLETE_LIMIT,
             });
+            if (!r.ok) {
+              ctx.ui.setWidget("smart-at", undefined);
+              return null;
+            }
+
+            const result = buildResult(r.value.items, lowerQuery);
+            if (!result) {
+              ctx.ui.setWidget("smart-at", undefined);
+              return null;
+            }
+
+            ctx.ui.setWidget("smart-at", [WIDGET_FOOTER]);
+            return Promise.resolve({ ...result, prefix });
           },
           applyCompletion: (...args: any[]) => {
-            clearCache();
             ctx.ui.setWidget("smart-at", undefined);
             return orig.applyCompletion.apply(orig, args);
           },
-          shouldTriggerFileCompletion: orig.shouldTriggerFileCompletion?.bind(orig),
+          shouldTriggerFileCompletion:
+            orig.shouldTriggerFileCompletion?.bind(orig),
         }));
       },
     ],
+    session_shutdown: [
+      (_event: any, _ctx: ExtensionContext) => {
+        if (currentFinder && !currentFinder.isDestroyed) {
+          currentFinder.destroy();
+        }
+        currentFinder = null;
+      },
+    ],
   },
 };
 
 export function setupSmartAt(sk: Skeleton): void {
-  sk.declareDependency({
-    label: "fd",
-    check: () => commandExists("fd") || isGitWorkTree(process.cwd()),
-  });
   sk.register(smartAtModule);
 }

package/hooks/wakatime.ts

@@ -342,12 +342,13 @@ export function setupWakatimeWithApiKey(
 export function setupWakatime(sk: Skeleton, pi: ExtensionAPI): void {
   const apiKey = readWakatimeCfgApiKey();
   const cliPath = findWakatimeCli();
-  sk.declareDependency({
+  const ready = sk.declareDependency({
     label: "wakatime-cli",
+    module: "wakatime",
     check: () => findWakatimeCli() !== null,
     hint: "Install wakatime-cli to track coding activity.",
   });
-  if (!apiKey || !cliPath) return;
+  if (!apiKey || !cliPath || !ready) return;
 
   const sendHeartbeat: HeartbeatSender = (hb, cwd) => sendHeartbeatViaCli(hb, apiKey, cliPath, cwd);
 

package/index.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
 
 import { createSkeleton } from "./hooks/skeleton.js";
 
@@ -36,8 +37,9 @@ import { setupRtk } from "./hooks/rtk.js";
 import { registerPatchTool } from "./tools/patch/index.js";
 import { registerLspTools } from "./tools/lsp/tools.js";
 import { LspServerManager } from "./tools/lsp/manager.js";
+import { collectLspDependencyStatuses } from "./tools/lsp/servers.js";
 import { registerAskTool } from "./tools/ask/index.js";
-import { resolveMcpConfigs, migrateLegacyGlobalMcpConfig } from "./tools/mcp/config.js";
+import { resolveMcpConfigs, migrateLegacyGlobalMcpConfig, collectMcpDependencyStatuses } from "./tools/mcp/config.js";
 import { ensureMcpServerReady } from "./hooks/mcp.js";
 
 import { registerDpModelCommand } from "./commands/dp-model.js";
@@ -65,6 +67,71 @@ const BASE_GUIDANCE = [
   "- CAUTION: Do not perform write operations in the following directories unless explicitly instructed: `node_modules`, `venv`, `env`, `__pycache__`, `.git` or any other hidden directories.",
 ].join("\n");
 
+/** Remove the injected Pi documentation block from the base system prompt.
+ *  Matches a line containing "Pi documentation" and deletes it plus all
+ *  following non-empty lines, stopping at the first blank line. */
+export function stripPiDocsBlock(prompt: string): string {
+  const lines = prompt.split("\n");
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.includes("Pi documentation")) {
+      i++;
+      while (i < lines.length && lines[i].trim() !== "") i++;
+      // Drop the terminating blank line as well so we don't leave orphan whitespace.
+      if (i < lines.length && lines[i].trim() === "") i++;
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+  return out.join("\n");
+}
+
+/** Sort the <available_skills> block in the system prompt by skill name.
+ *  Pi core appends extension-provided skills after user/project skills and does
+ *  not sort the XML; this makes the final prompt stable and cache-friendly. */
+export function sortSkillsInSystemPrompt(prompt: string): string {
+  const startMarker = "\n<available_skills>";
+  const endMarker = "</available_skills>";
+  const startIdx = prompt.indexOf(startMarker);
+  if (startIdx === -1) return prompt;
+  const endIdx = prompt.indexOf(endMarker, startIdx);
+  if (endIdx === -1) return prompt;
+
+  const before = prompt.slice(0, startIdx + startMarker.length);
+  const after = prompt.slice(endIdx);
+  const inner = prompt.slice(startIdx + startMarker.length, endIdx);
+
+  const chunks: string[][] = [];
+  let current: string[] = [];
+  for (const line of inner.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "<skill>") {
+      current = [line];
+    } else if (trimmed === "</skill>") {
+      current.push(line);
+      chunks.push(current);
+      current = [];
+    } else if (current.length > 0) {
+      current.push(line);
+    }
+  }
+
+  const nameOf = (chunk: string[]) => {
+    const line = chunk.find((l) => l.trim().startsWith("<name>"));
+    if (!line) return "";
+    const t = line.trim();
+    return t.slice(6, t.indexOf("</name>"));
+  };
+
+  chunks.sort((a, b) => nameOf(a).localeCompare(nameOf(b)));
+
+  const sortedInner = "\n" + chunks.map((chunk) => chunk.join("\n")).join("\n") + "\n";
+  return before + sortedInner + after;
+}
+
 /** Build the list of guideline strings to inject, in prompt order.
  *  Always-on rules first, then per-module guidelines. REDACT_GUIDANCE is
  *  gated by the secretRedaction module; CodeGraph guidance follows the MCP
@@ -80,6 +147,26 @@ function buildGuidelines(): string[] {
   return out;
 }
 
+function canRegisterMcpServer(config: { name: string; command?: string }, deps: Array<{ module: string; state: string }>): boolean {
+  if (!config.command) return true;
+  const dep = deps.find((d) => d.module === `mcp:${config.name}`);
+  return dep ? dep.state === "ok" : true;
+}
+
+/** Absolute path to the plugin's builtin skills directory.
+ *  Used by `resources_discover` so the skill travels with the plugin
+ *  regardless of which project pi is running in. */
+export function getBuiltinSkillPaths(): string[] {
+  return [fileURLToPath(new URL("./skills", import.meta.url))];
+}
+
+/** Register the plugin's builtin skill paths with Pi core. */
+function installBuiltinSkills(pi: ExtensionAPI): void {
+  pi.on("resources_discover", async (_event: any) => ({
+    skillPaths: getBuiltinSkillPaths(),
+  }));
+}
+
 /** Install a single before_agent_start handler that appends every
  *  guideline in order, stripping the volatile "Current date: …" line
  *  for cache stability. Idempotent — re-injection is a no-op via marker. */
@@ -90,7 +177,9 @@ function installGuidelines(pi: ExtensionAPI): void {
 
   pi.on("before_agent_start", async (event: any) => {
     if (!event.systemPrompt) return undefined;
-    let prompt: string = event.systemPrompt.replace(/\nCurrent date: \d{4}-\d{2}-\d{2}/, "");
+    let prompt: string = stripPiDocsBlock(event.systemPrompt);
+    prompt = sortSkillsInSystemPrompt(prompt);
+    prompt = prompt.replace(/\nCurrent date: \d{4}-\d{2}-\d{2}/, "");
     if (prompt.includes(marker)) return undefined; // already injected this turn
     return { systemPrompt: `${prompt}\n\n${joined}` };
   });
@@ -130,7 +219,19 @@ export default async function (pi: ExtensionAPI) {
 
   // ── Tools (conditional on module switches) ────────────────────────────
   if (isModuleEnabled("patchOverrideEdit")) registerPatchTool(pi);
-  if (isModuleEnabled("lsp")) registerLspTools(pi, new LspServerManager());
+  if (isModuleEnabled("lsp")) {
+    const lspDeps = collectLspDependencyStatuses(process.cwd());
+    if (lspDeps.some((d) => d.state === "ok")) {
+      registerLspTools(pi, new LspServerManager());
+    }
+    for (const dep of lspDeps) {
+      sk.declareDependency({
+        label: `lsp:${dep.label}`,
+        module: `lsp:${dep.label}`,
+        check: () => collectLspDependencyStatuses(process.cwd()).some((s) => s.label === dep.label && s.state === "ok"),
+      });
+    }
+  }
   if (isModuleEnabled("ask")) registerAskTool(pi);
 
   // MCP: hook, tools, and /mcp command are gated together. Disabling the
@@ -142,16 +243,29 @@ export default async function (pi: ExtensionAPI) {
     // explicitly here so `loadGlobalMcpConfigs` stays pure.
     migrateLegacyGlobalMcpConfig();
     sk.register(mcpModule);
+    const mcpDeps = collectMcpDependencyStatuses(process.cwd());
+    for (const dep of mcpDeps) {
+      sk.declareDependency({
+        label: dep.module,
+        module: dep.module,
+        check: () => collectMcpDependencyStatuses(process.cwd()).some((s) => s.module === dep.module && s.state === "ok"),
+      });
+    }
     const configs = resolveMcpConfigs(process.cwd()).filter(s => s.enabled);
     // Per-server readiness: cache hit → register from cache (fast).
     // Cache miss → connect synchronously, write cache, then register
     // live tools. This blocks startup only for cache-miss servers.
+    // Skip servers whose binary is missing (dependency not met).
     for (const config of configs) {
+      if (!canRegisterMcpServer(config, mcpDeps)) continue;
       await ensureMcpServerReady(pi, config, process.cwd());
     }
     registerMcpStatusCommand(pi);
   }
 
+  // ── Builtin skills (travel with the plugin in every project) ─────────────
+  installBuiltinSkills(pi);
+
   // ── System-prompt guidelines (single handler, array order = prompt order) ──
   installGuidelines(pi);