gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

package/dist/resources/extensions/gsd/worktree.js

@@ -11,11 +11,12 @@
  * Pure utility functions (detectWorktreeName, getSliceBranchName, parseSliceBranch,
  * SLICE_BRANCH_RE) remain for backwards compatibility with legacy branches.
  */
-import { existsSync, readFileSync, realpathSync, utimesSync } from "node:fs";
+import { existsSync, readFileSync, utimesSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { homedir } from "node:os";
 import { GitServiceImpl, writeIntegrationBranch } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { findWorktreeSegment, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+export { resolveWorktreeProjectRoot } from "./worktree-root.js";
 export { MergeConflictError } from "./git-service.js";
 // ─── Lazy GitServiceImpl Cache ─────────────────────────────────────────────
 let cachedService = null;
@@ -67,28 +68,6 @@ export function captureIntegrationBranch(basePath, milestoneId) {
     writeIntegrationBranch(basePath, milestoneId, current);
 }
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
-/**
- * Find the worktrees segment in a path, supporting both direct
- * (`/.gsd/worktrees/`) and symlink-resolved (`/.gsd/projects/<hash>/worktrees/`)
- * layouts.  When `.gsd` is a symlink to `~/.gsd/projects/<hash>`, resolved
- * paths contain the intermediate `projects/<hash>/` segment that the old
- * single-marker check missed.
- */
-function findWorktreeSegment(normalizedPath) {
-    // Direct layout: /.gsd/worktrees/<name>
-    const directMarker = "/.gsd/worktrees/";
-    const idx = normalizedPath.indexOf(directMarker);
-    if (idx !== -1) {
-        return { gsdIdx: idx, afterWorktrees: idx + directMarker.length };
-    }
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/<name>
-    const symlinkRe = /\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//;
-    const match = normalizedPath.match(symlinkRe);
-    if (match && match.index !== undefined) {
-        return { gsdIdx: match.index, afterWorktrees: match.index + match[0].length };
-    }
-    return null;
-}
 /**
  * Detect the active worktree name from the current working directory.
  * Returns null if not inside a GSD worktree (.gsd/worktrees/<name>/).
@@ -121,97 +100,7 @@ export function detectWorktreeName(basePath) {
  * operate against the real project root, not a worktree subdirectory.
  */
 export function resolveProjectRoot(basePath) {
-    // Layer 1: If the coordinator passed the real project root, use it.
-    if (process.env.GSD_PROJECT_ROOT) {
-        return process.env.GSD_PROJECT_ROOT;
-    }
-    const normalizedPath = basePath.replaceAll("\\", "/");
-    const seg = findWorktreeSegment(normalizedPath);
-    if (!seg)
-        return basePath;
-    // Candidate root via the string-slice heuristic
-    const sepChar = basePath.includes("\\") ? "\\" : "/";
-    const gsdMarker = `${sepChar}.gsd${sepChar}`;
-    const gsdIdx = basePath.indexOf(gsdMarker);
-    const candidate = gsdIdx !== -1
-        ? basePath.slice(0, gsdIdx)
-        : basePath.slice(0, seg.gsdIdx);
-    // Layer 2: Guard against resolving to the user's home directory.
-    // When .gsd is a symlink into ~/.gsd/projects/<hash>, the resolved path
-    // contains /.gsd/ at the user-level boundary. Slicing there yields ~ — wrong.
-    const gsdHome = normalizePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
-    const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
-    if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(gsdHome + "/")) {
-        // The candidate is the home directory (or within it in a way that .gsd
-        // maps to the user-level GSD dir). Try to recover the real project root
-        // from the worktree's .git file.
-        const realRoot = resolveProjectRootFromGitFile(basePath);
-        if (realRoot)
-            return realRoot;
-        // If git file resolution failed, return basePath unchanged rather than ~
-        return basePath;
-    }
-    return candidate;
-}
-/**
- * Recover the real project root from a worktree's .git file.
- *
- * Each git worktree has a `.git` file (not directory) containing:
- *   gitdir: /real/project/.git/worktrees/<name>
- *
- * Walking up from that gitdir gives us `/real/project/.git`, and its
- * parent is the real project root.
- */
-function resolveProjectRootFromGitFile(worktreePath) {
-    try {
-        // Walk up from the worktree path to find the .git file
-        let dir = worktreePath;
-        for (let i = 0; i < 30; i++) {
-            const gitPath = join(dir, ".git");
-            if (existsSync(gitPath)) {
-                const content = readFileSync(gitPath, "utf8").trim();
-                if (content.startsWith("gitdir: ")) {
-                    // gitdir points to: <real-project>/.git/worktrees/<name>
-                    const gitDir = resolve(dir, content.slice(8));
-                    // Walk up: .git/worktrees/<name> → .git/worktrees → .git → project root
-                    const dotGitDir = resolve(gitDir, "..", "..");
-                    // Verify this looks like a .git directory
-                    if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
-                        return resolve(dotGitDir, "..");
-                    }
-                    // Alternative: the commondir file inside the worktree gitdir
-                    // points to the main .git directory
-                    const commonDirPath = join(gitDir, "commondir");
-                    if (existsSync(commonDirPath)) {
-                        const commonDir = readFileSync(commonDirPath, "utf8").trim();
-                        const resolvedCommonDir = resolve(gitDir, commonDir);
-                        return resolve(resolvedCommonDir, "..");
-                    }
-                }
-                break;
-            }
-            const parent = resolve(dir, "..");
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    catch {
-        // Non-fatal — caller will use fallback
-    }
-    return null;
-}
-function normalizePathForCompare(path) {
-    let normalized;
-    try {
-        normalized = realpathSync(path);
-    }
-    catch {
-        normalized = resolve(path);
-    }
-    const slashed = normalized.replaceAll("\\", "/");
-    const trimmed = slashed.replace(/\/+$/, "");
-    return trimmed || "/";
+    return resolveWorktreeProjectRoot(basePath);
 }
 /**
  * Get the slice branch name, namespaced by worktree when inside one.

package/dist/resources/extensions/mcp-client/index.js

@@ -2,7 +2,8 @@
  * MCP Client Extension — Native MCP server integration for pi
  *
  * Provides on-demand access to MCP servers configured in project files
- * (.mcp.json, .gsd/mcp.json) using the @modelcontextprotocol/sdk Client
+ * (.mcp.json, .gsd/mcp.json) and the global ~/.gsd/mcp.json (or
+ * $GSD_HOME/mcp.json) using the @modelcontextprotocol/sdk Client
  * directly — no external CLI dependency required.
  *
  * Three tools:
@@ -19,6 +20,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { buildHttpTransportOpts } from "./auth.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 // ─── Connection Manager ───────────────────────────────────────────────────────
 const connections = new Map();
 const pendingConnections = new Map();
@@ -61,6 +63,7 @@ function readConfigs() {
     const configPaths = [
         join(process.cwd(), ".mcp.json"),
         join(process.cwd(), ".gsd", "mcp.json"),
+        join(gsdHome(), "mcp.json"),
     ];
     for (const configPath of configPaths) {
         try {
@@ -258,7 +261,7 @@ async function closeAll() {
 // ─── Formatters ───────────────────────────────────────────────────────────────
 function formatServerList(servers) {
     if (servers.length === 0)
-        return "No MCP servers configured. Add servers to .mcp.json or .gsd/mcp.json.";
+        return "No MCP servers configured. Add servers to .mcp.json, .gsd/mcp.json, or $GSD_HOME/mcp.json (default: ~/.gsd/mcp.json).";
     const lines = [`${servers.length} MCP servers configured:\n`];
     for (const s of servers) {
         const connected = connections.has(s.name) ? "✓" : "○";
@@ -306,7 +309,7 @@ export default function (pi) {
     pi.registerTool({
         name: "mcp_servers",
         label: "MCP Servers",
-        description: "List all available MCP servers configured in project files (.mcp.json, .gsd/mcp.json). " +
+        description: "List all available MCP servers configured in project files (.mcp.json, .gsd/mcp.json) or globally ($GSD_HOME/mcp.json, default: ~/.gsd/mcp.json). " +
             "Shows server names, transport type, and connection status. Use mcp_discover to get full tool schemas for a server.",
         promptSnippet: "List available MCP servers from project configuration",
         promptGuidelines: [
@@ -500,12 +503,6 @@ export default function (pi) {
         },
     });
     // ── Lifecycle ─────────────────────────────────────────────────────────────
-    pi.on("session_start", async (_event, ctx) => {
-        const servers = readConfigs();
-        if (servers.length > 0) {
-            ctx.ui.notify(`MCP client ready — ${servers.length} server(s) configured`, "info");
-        }
-    });
     pi.on("session_shutdown", async () => {
         await closeAll();
     });

package/dist/resources/extensions/ollama/index.js

@@ -103,19 +103,32 @@ export default function ollama(pi) {
         // In headless/auto mode, await the probe so the fallback resolver can
         // see Ollama before the first LLM call (#3531 race condition).
         // In interactive mode, keep it async for fast startup.
+        // Surface probe failures under GSD_DEBUG so users can diagnose silent
+        // "Ollama is missing from /model" reports without patching dist/. The
+        // probe still soft-fails (registration is best-effort) — we just stop
+        // dropping the error on the floor. See #4982.
+        const debugOllama = (where, error) => {
+            if (process.env.GSD_DEBUG) {
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[ollama] ${where} probe failed: ${msg}\n`);
+            }
+        };
         if (!ctx.hasUI) {
             try {
                 await probeAndRegister(pi);
             }
-            catch { /* non-fatal */ }
+            catch (error) {
+                debugOllama("headless", error);
+            }
         }
         else {
             probeAndRegister(pi)
                 .then((found) => {
                 ctx.ui.setStatus("ollama", found ? "Ollama" : undefined);
             })
-                .catch(() => {
+                .catch((error) => {
                 ctx.ui.setStatus("ollama", undefined);
+                debugOllama("interactive", error);
             });
         }
     });

package/dist/resources/extensions/ollama/model-capabilities.js

@@ -32,9 +32,40 @@ const KNOWN_MODELS = [
     ["llama3", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],
     ["llama2", { contextWindow: 4096, maxTokens: 4096, ollamaOptions: { num_ctx: 4096 } }],
     // ─── Qwen family ────────────────────────────────────────────────────
+    // Long-variant entries MUST appear before the bare `qwen3` base —
+    // `baseName.startsWith(pattern)` returns true for `qwen3.5`/`qwen3-coder`/
+    // `qwen3-next` against `qwen3`, and the first match wins (#4991).
+    // ref: qwen3-next 1M ctx — https://qwen.ai/blog?id=qwen3-next
+    ["qwen3-next", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+    // ref: qwen3-coder 256K ctx — https://qwenlm.github.io/blog/qwen3-coder/
+    ["qwen3-coder", { contextWindow: 262144, maxTokens: 32768, ollamaOptions: { num_ctx: 262144 } }],
+    // ref: qwen3.5 / qwen3.6 1M ctx — Ollama Cloud release notes
+    ["qwen3.6", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+    ["qwen3.5", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
     ["qwen3", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
     ["qwen2.5", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
     ["qwen2", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
+    // ─── GLM family (Z.ai, Ollama Cloud) ────────────────────────────────
+    // ref: glm 4.6 / 5.x 200K ctx — https://docs.z.ai/devpack/using5.1
+    // Long-variant entries before bare `glm-5` / `glm-4` would-be bases to
+    // avoid prefix shadowing (#4991).
+    ["glm-5.1", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+    ["glm-5", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+    ["glm-4.6", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+    ["glm-4", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
+    // ─── Kimi K2 (Moonshot, Ollama Cloud) ──────────────────────────────
+    // ref: kimi-k2 256K ctx — https://platform.moonshot.ai/docs
+    // Same shadowing concern: kimi-k2-thinking and kimi-k2.{5,6} must
+    // match before any future bare `kimi-k2` entry (#4991).
+    ["kimi-k2-thinking", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+    ["kimi-k2.6", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+    ["kimi-k2.5", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+    ["kimi-k2", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+    // ─── MiniMax M2 (Ollama Cloud) ─────────────────────────────────────
+    // ref: minimax-m2 1M ctx — https://www.minimax.io/news/minimax-m2
+    ["minimax-m2.7", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+    ["minimax-m2.5", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+    ["minimax-m2", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
     // ─── Gemma family ───────────────────────────────────────────────────
     ["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
     ["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],

package/dist/resources/extensions/ollama/ollama-client.js

@@ -1,8 +1,44 @@
 // GSD2 — HTTP client for Ollama REST API
 import { parseNDJsonStream } from "./ndjson-stream.js";
 const DEFAULT_HOST = "http://localhost:11434";
-const PROBE_TIMEOUT_MS = 1500;
-const REQUEST_TIMEOUT_MS = 10000;
+const DEFAULT_PROBE_TIMEOUT_MS = 1500;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Parse a positive integer from an environment variable, falling back to
+ * `fallback` when the var is unset, empty, non-numeric, zero, or negative.
+ *
+ * Defensive parsing: a typo like `OLLAMA_PROBE_TIMEOUT_MS=abc` or
+ * `OLLAMA_PROBE_TIMEOUT_MS=0` should not silently disable the timeout —
+ * fall back to the documented default instead.
+ */
+export function envPositiveInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(parsed, MAX_TIMER_DELAY_MS);
+}
+/**
+ * Effective probe timeout for the startup `isRunning()` health check.
+ * Override with `OLLAMA_PROBE_TIMEOUT_MS=<ms>` for slower networks (LAN
+ * Ollama hosts, cloud endpoints, contended cold starts).
+ *
+ * Resolved at call time — tests and downstream callers can mutate
+ * `process.env` between invocations and pick up the new value.
+ */
+export function getProbeTimeoutMs() {
+    return envPositiveInt("OLLAMA_PROBE_TIMEOUT_MS", DEFAULT_PROBE_TIMEOUT_MS);
+}
+/**
+ * Effective per-request timeout for REST calls. Override with
+ * `OLLAMA_REQUEST_TIMEOUT_MS=<ms>`.
+ */
+export function getRequestTimeoutMs() {
+    return envPositiveInt("OLLAMA_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS);
+}
 /**
  * Get the Ollama host URL from OLLAMA_HOST or default.
  */
@@ -38,7 +74,7 @@ function withAuth(options = {}) {
         headers: { ...authHeaders, ...(options.headers || {}) },
     };
 }
-async function fetchWithTimeout(url, options = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
+async function fetchWithTimeout(url, options = {}, timeoutMs = getRequestTimeoutMs()) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -58,7 +94,7 @@ export async function isRunning() {
         const host = getOllamaHost();
         const isCloud = host.includes("ollama.com") || host.includes("cloud");
         const probeUrl = isCloud ? `${host}/api/tags` : `${host}/`;
-        const timeout = isCloud ? REQUEST_TIMEOUT_MS : PROBE_TIMEOUT_MS;
+        const timeout = isCloud ? getRequestTimeoutMs() : getProbeTimeoutMs();
         const response = await fetchWithTimeout(probeUrl, isCloud ? { method: "GET" } : {}, timeout);
         return response.ok;
     }

package/dist/resources/extensions/remote-questions/remote-command.js

@@ -9,6 +9,7 @@ import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences } from "../gsd
 import { getRemoteConfigStatus, isValidChannelId, resolveRemoteConfig } from "./config.js";
 import { maskEditorLine, sanitizeError } from "../shared/mod.js";
 import { getLatestPromptSummary } from "./status.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 export async function handleRemote(subcommand, ctx, _pi) {
     const trimmed = subcommand.trim();
     if (trimmed === "slack")
@@ -291,7 +292,7 @@ async function promptSlackChannelId(ctx) {
     return channelId;
 }
 function getAuthStorage() {
-    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    const authPath = join(gsdHome(), "agent", "auth.json");
     mkdirSync(dirname(authPath), { recursive: true });
     return AuthStorage.create(authPath);
 }

package/dist/resources/extensions/remote-questions/status.js

@@ -3,13 +3,10 @@
  */
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
-function getGsdHome() {
-    return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
+import { gsdHome } from "../gsd/gsd-home.js";
 export function getLatestPromptSummary() {
-    const runtimeDir = join(getGsdHome(), "runtime", "remote-questions");
+    const runtimeDir = join(gsdHome(), "runtime", "remote-questions");
     if (!existsSync(runtimeDir))
         return null;
     const files = readdirSync(runtimeDir).filter((f) => f.endsWith(".json"));

package/dist/resources/extensions/remote-questions/store.js

@@ -3,12 +3,9 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
-function getGsdHome() {
-    return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
+import { gsdHome } from "../gsd/gsd-home.js";
 function runtimeDir() {
-    return join(getGsdHome(), "runtime", "remote-questions");
+    return join(gsdHome(), "runtime", "remote-questions");
 }
 function recordPath(id) {
     return join(runtimeDir(), `${id}.json`);

package/dist/resources/extensions/search-the-web/provider.js

@@ -9,14 +9,15 @@
  * @see S01-RESEARCH.md for the storage decision rationale (D002).
  */
 import { AuthStorage } from '@gsd/pi-coding-agent';
-import { homedir } from 'os';
 import { join } from 'path';
 import { resolveSearchProviderFromPreferences } from '../gsd/preferences.js';
-// Compute authFilePath locally instead of importing from app-paths.ts,
-// because extensions are copied to ~/.gsd/agent/extensions/ at runtime
-// where the relative import '../../../app-paths.ts' doesn't resolve.
-const gsdHome = process.env.GSD_HOME || join(homedir(), '.gsd');
-const authFilePath = join(gsdHome, 'agent', 'auth.json');
+import { gsdHome } from "../gsd/gsd-home.js";
+// Compute authFilePath lazily so GSD_HOME overrides (e.g. in tests) take effect.
+// Imported locally instead of from app-paths.ts because extensions are copied to
+// ~/.gsd/agent/extensions/ at runtime where '../../../app-paths.ts' doesn't resolve.
+function authFilePath() {
+    return join(gsdHome(), 'agent', 'auth.json');
+}
 const VALID_PREFERENCES = new Set(['tavily', 'brave', 'ollama', 'auto']);
 const PREFERENCE_KEY = 'search_provider';
 /** Returns the Tavily API key from the environment, or empty string if not set. */
@@ -46,7 +47,7 @@ export function getOllamaApiKey() {
  * @param authPath — Override auth.json path (for testing).
  */
 export function getSearchProviderPreference(authPath) {
-    const auth = AuthStorage.create(authPath ?? authFilePath);
+    const auth = AuthStorage.create(authPath ?? authFilePath());
     const cred = auth.get(PREFERENCE_KEY);
     if (cred?.type === 'api_key' && typeof cred.key === 'string' && VALID_PREFERENCES.has(cred.key)) {
         return cred.key;
@@ -61,7 +62,7 @@ export function getSearchProviderPreference(authPath) {
  * @param authPath — Override auth.json path (for testing).
  */
 export function setSearchProviderPreference(pref, authPath) {
-    const auth = AuthStorage.create(authPath ?? authFilePath);
+    const auth = AuthStorage.create(authPath ?? authFilePath());
     auth.remove(PREFERENCE_KEY);
     auth.set(PREFERENCE_KEY, { type: 'api_key', key: pref });
 }

package/dist/resources/extensions/slash-commands/create-extension.js

@@ -193,38 +193,35 @@ function sendPrompt(description, result, pi) {
         ? (Array.isArray(persistenceAnswer.selected) ? persistenceAnswer.selected[0] : persistenceAnswer.selected)
         : "";
     const docHints = [
-        "- `~/.gsd/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
-        "- `~/.gsd/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
-        "- `~/.gsd/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
-        "- `~/.gsd/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
-        "- `~/.gsd/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+        "- `docs/extension-sdk/README.md` — overview, quick start, directory layout",
+        "- `docs/extension-sdk/api-reference.md` — ExtensionAPI and ExtensionContext surfaces",
+        "- `docs/extension-sdk/building-extensions.md` — tools, commands, events, UI, state",
+        "- `docs/extension-sdk/rules.md` — non-negotiable rules and gotchas",
     ];
     if (uiSelected.includes("custom component")) {
-        docHints.push("- `~/.gsd/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide");
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls");
+        docHints.push("- `docs/extension-sdk/building-extensions.md#custom-components` — ctx.ui.custom() API");
+        docHints.push("- `docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — step-by-step component guide");
+        docHints.push("- `docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList");
+        docHints.push("- `docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey");
+        docHints.push("- `docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules");
     }
     else if (uiSelected.includes("Dialogs")) {
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor");
+        docHints.push("- `docs/extension-sdk/building-extensions.md#built-in-dialogs` — select, confirm, input");
     }
     else if (uiSelected.includes("Status")) {
-        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header");
+        docHints.push("- `docs/extension-sdk/building-extensions.md#persistent-ui-elements` — status, widgets");
     }
     if (uiSelected.includes("tool") || result.answers["purpose"]) {
-        docHints.push("- `~/.gsd/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult");
+        docHints.push("- `docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult");
     }
     if (eventsSelected && !eventsSelected.includes("standalone")) {
-        docHints.push("- `~/.gsd/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference");
+        docHints.push("- `docs/dev/extending-pi/07-events-the-nervous-system.md` — all events reference");
     }
     if (eventsSelected.includes("context / prompt")) {
-        docHints.push("- `~/.gsd/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks");
+        docHints.push("- `docs/dev/extending-pi/15-system-prompt-modification.md` — system prompt hooks");
     }
     if (persistenceSelected.includes("session")) {
-        docHints.push("- `~/.gsd/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state");
+        docHints.push("- `docs/extension-sdk/building-extensions.md#state-management` — state reconstruction, appendEntry");
     }
     const prompt = `Create a new pi extension based on this description:
 
@@ -238,13 +235,30 @@ ${docHints.join("\n")}
 
 ## Output
 
-Write the complete implementation as a single self-contained extension file:
+Write the complete implementation as a directory-based extension:
 
-\`~/.gsd/agent/extensions/<kebab-case-name>.ts\`
+\`~/.gsd/agent/extensions/<kebab-case-name>/index.ts\`
+\`~/.gsd/agent/extensions/<kebab-case-name>/extension-manifest.json\`
 
-Then register it in the main extensions index:
+The manifest must follow this format:
+\`\`\`json
+{
+  "id": "<kebab-case-name>",
+  "name": "<Human Name>",
+  "version": "1.0.0",
+  "description": "<one-line description>",
+  "tier": "community",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["<tool_names_registered>"],
+    "commands": ["<command_names_registered>"],
+    "hooks": ["<event_names_subscribed>"],
+    "shortcuts": ["<shortcut_keys_registered>"]
+  }
+}
+\`\`\`
 
-\`~/.gsd/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+Only include non-empty arrays in \`provides\`. See \`docs/extension-sdk/manifest-spec.md\` for the full spec.
 
 ## Rules you must follow exactly