@opengsd/gsd-pi 1.0.1-dev.bf2899e → 1.0.2-dev.0ee79e5

package/dist/resources/extensions/gsd/watch/header-renderer.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Watch-mode terminal header and splash renderer for GSD project status.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";

package/dist/resources/extensions/gsd/watch/splash-palette.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Shared RGB palette for the pre-theme GSD watch splash.
 export const splashPalette = {
     accent: "#8db7ff",

package/dist/resources/extensions/gsd/workflow-manifest.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: State manifest snapshot and restore orchestration for GSD workflow data.
 import { _getAdapter, readTransaction, restoreManifest, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Projection renderers for GSD workflow database rows.
 // GSD Extension — Projection Renderers (DB -> Markdown)
 // Renders PLAN.md, ROADMAP.md, SUMMARY.md, and STATE.md from database rows.

package/dist/resources/extensions/gsd/workflow-protocol.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Shared capped workflow protocol and doctor-heal prompt payload helpers.
 const DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 4_000;
 const MIN_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 1_000;

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -70,6 +70,13 @@ function replayEvents(events) {
                     updateTaskStatus(milestoneId, sliceId, taskId, "in-progress", event.ts);
                     break;
                 }
+                case "skip_task": {
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    const taskId = p["taskId"];
+                    updateTaskStatus(milestoneId, sliceId, taskId, "skipped", event.ts);
+                    break;
+                }
                 case "report_blocker": {
                     const milestoneId = p["milestoneId"];
                     const sliceId = p["sliceId"];
@@ -199,6 +206,7 @@ export function extractEntityKey(event) {
     switch (cmd) {
         case "complete_task":
         case "start_task":
+        case "skip_task":
         case "report_blocker":
         case "record_verification":
         case "plan_task":

package/dist/resources/extensions/gsd/workflow-templates.js

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Workflow template registry loading, matching, and display helpers.
 /**
  * GSD Workflow Templates — Registry & Resolution

package/dist/resources/extensions/gsd/working-output-messages.js

@@ -1,4 +1,4 @@
-// GSD-2 + src/resources/extensions/gsd/working-output-messages.ts - Formats and audits user-facing working-state messages.
+// gsd-pi + src/resources/extensions/gsd/working-output-messages.ts - Formats and audits user-facing working-state messages.
 const ACTION_RE = /\b(?:wait|pause|paused|retry|retrying|recover|recovering|resume|stop|stopped|run|press|type|configure|restart)\b/i;
 export function formatAutoUnitWorkingMessage(unitType, unitId) {
     switch (unitType) {

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

@@ -1,4 +1,4 @@
-// GSD-2 + Workspace handle: single source of truth for path resolution per milestone
+// gsd-pi + Workspace handle: single source of truth for path resolution per milestone
 import { join, resolve } from "node:path";
 import { resolveGsdPathContract, normalizeRealPath } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";

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

@@ -1,4 +1,4 @@
-// GSD-2 — Worktree Lifecycle module: owns milestone entry/exit lifecycle behind a small, typed Interface.
+// gsd-pi — Worktree Lifecycle module: owns milestone entry/exit lifecycle behind a small, typed Interface.
 /**
  * Worktree Lifecycle module — first-class Module for worktree create/enter/exit/merge.
  *

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

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Creates, resolves, and reconciles GSD milestone worktrees.
 /**
  * GSD Worktree Manager

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

@@ -1,4 +1,4 @@
-// Project/App: GSD-2
+// Project/App: gsd-pi
 // File Purpose: Worktree Safety module contract for validating source-writing Unit roots.
 import { existsSync, lstatSync } from "node:fs";
 import { execFileSync } from "node:child_process";

package/dist/resources/extensions/gsd/worktree-state-projection.js

@@ -1,4 +1,4 @@
-// GSD-2 — Worktree State Projection module: directional state-flow rules between project root and auto-worktree.
+// gsd-pi — Worktree State Projection module: directional state-flow rules between project root and auto-worktree.
 /**
  * Worktree State Projection module — first-class Module for directional
  * state-file flow between the project root and the auto-worktree.

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

@@ -1,5 +1,5 @@
 /**
- * GSD-2 — Shared MCP connection management.
+ * gsd-pi — Shared MCP connection management.
  *
  * File Purpose: Reads, writes, and tests user-configured MCP server entries
  * for runtime tools, TUI commands, and app settings surfaces.

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

@@ -1,4 +1,4 @@
-// GSD2 — Ollama Extension: First-class local LLM support
+// gsd-pi — Ollama Extension: First-class local LLM support
 /**
  * Ollama Extension
  *

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

@@ -1,14 +1,21 @@
-// GSD2 — Known model capability table for Ollama models
+// gsd-pi — Known model capability table for Ollama models
 /**
  * Known model family capabilities.
  * Keys are matched as prefixes against the model name (before the colon/tag).
  * More specific entries should appear first.
  */
-// Note: ollamaOptions.num_ctx is set for known model families where the context
-// window is authoritative. For unknown/estimated models, num_ctx is NOT sent
-// to avoid OOM risk — Ollama uses its own safe default instead.
+// Note: ollamaOptions.num_ctx is set when the context window has an authoritative
+// source — either a KNOWN_MODELS table entry, or /api/show returning context_length
+// at runtime (ollama-discovery.ts syncs num_ctx with the /api/show value when present).
+// When neither source provides a context window, num_ctx is NOT sent and ollama
+// uses its own safe default to avoid OOM on constrained hosts.
 const KNOWN_MODELS = [
     // ─── Reasoning models ───────────────────────────────────────────────
+    // Long-variants listed before the bare `deepseek-v4` base to avoid prefix shadowing.
+    // Same invariant as qwen3-coder / glm / kimi / minimax families.
+    ["deepseek-v4-pro", { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
+    ["deepseek-v4-flash", { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
+    ["deepseek-v4", { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
     ["deepseek-r1", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }],
     ["qwq", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }],
     // ─── Vision models ──────────────────────────────────────────────────
@@ -63,10 +70,14 @@ const KNOWN_MODELS = [
     ["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.7:cloud reports 196608 via /api/show despite the M2 announcement
+    // quoting 1M context. Cloud deployment truncates / OOMs at the announced
+    // number; trust the deployed backend.
+    ["minimax-m2.7", { contextWindow: 196608, maxTokens: 16384, reasoning: true, ollamaOptions: { num_ctx: 196608 } }],
     ["minimax-m2.5", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
     ["minimax-m2", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
     // ─── Gemma family ───────────────────────────────────────────────────
+    ["gemma4", { contextWindow: 262144, reasoning: true, ollamaOptions: { num_ctx: 262144 } }],
     ["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
     ["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],
     // ─── Mistral family ─────────────────────────────────────────────────

package/dist/resources/extensions/ollama/ndjson-stream.js

@@ -1,4 +1,4 @@
-// GSD2 — Ollama Extension: NDJSON streaming parser
+// gsd-pi — Ollama Extension: NDJSON streaming parser
 /**
  * Parses a streaming NDJSON (newline-delimited JSON) response body into
  * typed objects. Used for Ollama's /api/chat and /api/pull endpoints.

package/dist/resources/extensions/ollama/ollama-chat-provider.js

@@ -1,4 +1,4 @@
-// GSD2 — Ollama Extension: Native /api/chat stream provider
+// gsd-pi — Ollama Extension: Native /api/chat stream provider
 /**
  * Implements the "ollama-chat" API provider, streaming responses directly
  * from Ollama's native /api/chat endpoint instead of the OpenAI compatibility
@@ -105,6 +105,12 @@ export function streamOllamaChat(model, context, options) {
                 output.stopReason = "toolUse";
             }
             for await (const chunk of chat(request, options?.signal)) {
+                // Native thinking field (ollama 0.4+ for reasoning models). Emit before
+                // content so blocks open in the natural reasoning-then-answer order.
+                const thinking = chunk.message?.thinking ?? "";
+                if (thinking) {
+                    emitDelta("thinking", thinking);
+                }
                 // Handle text content — process independently of tool_calls
                 // (a chunk may contain both content and tool_calls)
                 const content = chunk.message?.content ?? "";
@@ -144,7 +150,31 @@ export function streamOllamaChat(model, context, options) {
     return stream;
 }
 // ─── Request building ───────────────────────────────────────────────────────
-function buildRequest(model, context, options) {
+/**
+ * Map a SimpleStreamOptions.reasoning ThinkingLevel to ollama's `think` field.
+ *
+ * - Returns `undefined` when the model doesn't support reasoning, or when no
+ *   level was requested (preserving existing default behaviour: ollama uses
+ *   the model's built-in default).
+ * - `"minimal"` turns thinking off (`think: false`) — universally supported.
+ * - `"low" | "medium" | "high"` are passed through as strings; gpt-oss honors
+ *   them as strength levels, other thinking models treat any present value
+ *   as "thinking enabled".
+ * - `"xhigh"` is collapsed to `"high"` (ollama caps strength at high).
+ */
+export function buildThinkParam(model, options) {
+    if (!model.reasoning)
+        return undefined;
+    const level = options?.reasoning;
+    if (level === undefined)
+        return undefined;
+    if (level === "minimal")
+        return false;
+    if (level === "xhigh")
+        return "high";
+    return level;
+}
+export function buildRequest(model, context, options) {
     const ollamaOpts = (model.providerOptions ?? {});
     const request = {
         model: model.id,
@@ -191,6 +221,12 @@ function buildRequest(model, context, options) {
     if (context.tools?.length) {
         request.tools = convertTools(context.tools);
     }
+    // Thinking strength (ollama 0.4+). Only set when both the model is reasoning-capable
+    // and the caller explicitly requested a level — otherwise ollama uses its default.
+    const think = buildThinkParam(model, options);
+    if (think !== undefined) {
+        request.think = think;
+    }
     return request;
 }
 // ─── Message conversion ─────────────────────────────────────────────────────

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

@@ -1,4 +1,4 @@
-// GSD2 — HTTP client for Ollama REST API
+// gsd-pi — HTTP client for Ollama REST API
 import { parseNDJsonStream } from "./ndjson-stream.js";
 const DEFAULT_HOST = "http://localhost:11434";
 const DEFAULT_PROBE_TIMEOUT_MS = 1500;

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

@@ -1,4 +1,4 @@
-// GSD2 — Ollama slash commands
+// gsd-pi — Ollama slash commands
 import { Text } from "@gsd/pi-tui";
 import * as client from "./ollama-client.js";
 import { discoverModels, formatModelForDisplay } from "./ollama-discovery.js";

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

@@ -1,4 +1,4 @@
-// GSD2 — Ollama model discovery and capability detection
+// gsd-pi — Ollama model discovery and capability detection
 /**
  * Discovers locally available Ollama models and enriches them with
  * capability metadata (context window, vision, reasoning) from the
@@ -24,30 +24,51 @@ const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 async function enrichModel(info, deps) {
     const caps = getModelCapabilities(info.name);
     const parameterSize = info.details?.parameter_size ?? "";
-    // /api/tags doesn't include context length; /api/show does via "{arch}.context_length" in model_info.
+    // Always call /api/show — it carries two pieces of info absent from /api/tags:
+    // the per-architecture context_length, and (ollama 0.4+) a `capabilities` array
+    // like ["thinking", "completion", "tools"]. The capabilities array is the
+    // authoritative source for reasoning detection on cloud-routed models that
+    // don't appear in the static KNOWN_MODELS table.
     let showContextWindow;
-    if (caps.contextWindow === undefined) {
-        try {
-            const showData = await deps.showModel(info.name);
-            showContextWindow = extractContextFromModelInfo(showData.model_info);
-        }
-        catch (err) {
-            // non-fatal: fall through to estimate
-            if (process.env.GSD_DEBUG)
-                console.warn(`[ollama] /api/show failed for ${info.name}:`, err instanceof Error ? err.message : String(err));
-        }
+    let showCapabilities;
+    try {
+        const showData = await deps.showModel(info.name);
+        showContextWindow = extractContextFromModelInfo(showData.model_info);
+        showCapabilities = showData.capabilities;
     }
-    // Determine context window: known table > /api/show > estimate from param size > default
-    const contextWindow = caps.contextWindow ??
-        showContextWindow ??
+    catch (err) {
+        // non-fatal: fall through to table/estimate
+        if (process.env.GSD_DEBUG)
+            console.warn(`[ollama] /api/show failed for ${info.name}:`, err instanceof Error ? err.message : String(err));
+    }
+    // Determine context window: /api/show (authoritative ollama metadata) >
+    // known table (fallback for old ollama versions / network failure) >
+    // estimate from parameter size > default. Earlier priority order put
+    // known table first, but the table fell behind reality on several
+    // model families (deepseek-v4-* 131072 vs real 1048576; minimax-m2.7
+    // 1048576 vs real 196608). /api/show is the source of truth when
+    // reachable; the table only fills the gap when it isn't.
+    const contextWindow = showContextWindow ??
+        caps.contextWindow ??
         (parameterSize ? estimateContextFromParams(parameterSize) : 8192);
     // Determine max tokens: known table > fraction of context > default
     const maxTokens = caps.maxTokens ?? Math.min(Math.floor(contextWindow / 4), 16384);
-    // Detect vision from families or known table
-    const hasVision = caps.input?.includes("image") ??
+    // Detect vision: /api/show capabilities > known table > model families heuristic
+    const hasVision = showCapabilities?.includes("vision") ??
+        caps.input?.includes("image") ??
         (info.details?.families?.some((f) => f === "clip" || f === "mllama") ?? false);
-    // Detect reasoning from known table
-    const reasoning = caps.reasoning ?? false;
+    // Detect reasoning: /api/show capabilities (authoritative) > known table fallback
+    const reasoning = showCapabilities?.includes("thinking") ??
+        caps.reasoning ??
+        false;
+    // Sync num_ctx with the authoritative contextWindow. When /api/show
+    // wins, the table's static num_ctx would otherwise be stale and sent
+    // on every chat request — the very drift this commit's priority flip
+    // was designed to eliminate. Keep all other ollamaOptions (num_gpu,
+    // sampling params, keep_alive) from the table.
+    const ollamaOptions = showContextWindow !== undefined
+        ? { ...caps.ollamaOptions, num_ctx: showContextWindow }
+        : caps.ollamaOptions;
     return {
         id: info.name,
         name: humanizeModelName(info.name),
@@ -58,11 +79,19 @@ async function enrichModel(info, deps) {
         maxTokens,
         sizeBytes: info.size,
         parameterSize,
-        ollamaOptions: caps.ollamaOptions,
+        ollamaOptions,
     };
 }
 /**
  * Discover all locally available Ollama models with enriched capabilities.
+ *
+ * /api/show is now invoked for every model (capabilities + context_length
+ * both live there). Requests are dispatched concurrently here, but ollama's
+ * local server serializes model-metadata calls internally, so wall time
+ * scales linearly with model count — empirically ~50-100 ms/model on a warm
+ * ollama instance. A user with 30+ models pays ~3 s on app start. If this
+ * becomes a complaint, gate the call on `caps.contextWindow === undefined`
+ * and `caps.reasoning === undefined` (i.e., unknown-model fast path).
  */
 export async function discoverModels(deps = { listModels, showModel }) {
     const tags = await deps.listModels();

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

@@ -1,4 +1,4 @@
-// GSD2 — LLM-callable Ollama management tool
+// gsd-pi — LLM-callable Ollama management tool
 /**
  * Registers an ollama_manage tool that the LLM can call to interact
  * with the local Ollama instance — list models, pull new ones, check status.

package/dist/resources/extensions/ollama/thinking-parser.js

@@ -1,4 +1,4 @@
-// GSD2 — Ollama Extension: Stateful <think> tag stream parser
+// gsd-pi — Ollama Extension: Stateful <think> tag stream parser
 const OPEN_TAG = "<think>";
 const CLOSE_TAG = "</think>";
 const MAX_TAG_LEN = Math.max(OPEN_TAG.length, CLOSE_TAG.length);

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

@@ -1,2 +1,2 @@
-// GSD2 — Ollama API response types
+// gsd-pi — Ollama API response types
 export {};

package/dist/resources/extensions/shared/cmux-events.js

@@ -1,4 +1,4 @@
-// GSD-2 — Shared cmux event channel contracts
+// gsd-pi — Shared cmux event channel contracts
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 /**
  * Neutral event channel module for gsd<->cmux IPC.

package/dist/resources/extensions/shared/gsd-phase-state.js

@@ -1,5 +1,5 @@
 /**
- * GSD2 Phase State — cross-extension coordination
+ * gsd-pi Phase State — cross-extension coordination
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  *
  * Lightweight module-level state that GSD auto-mode writes to and the

package/dist/resources/extensions/shared/interview-ui.js

@@ -1,4 +1,4 @@
-// GSD2 — Shared interview round UI widget
+// gsd-pi — Shared interview round UI widget
 /**
  * Shared interview round UI widget.
  *

package/dist/resources/extensions/subagent/launch.js

@@ -1,4 +1,4 @@
-// GSD-2 + Subagent launch contract and child process safety helpers.
+// gsd-pi + Subagent launch contract and child process safety helpers.
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { SessionManager } from "@gsd/pi-coding-agent";

package/dist/resources/extensions/subagent/run-store.js

@@ -1,4 +1,4 @@
-// GSD-2 + Durable subagent run status, tracking names, and result artifact store.
+// gsd-pi + Durable subagent run status, tracking names, and result artifact store.
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomInt } from "node:crypto";

package/dist/resources/extensions/visual-brief/artifact-policy.js

@@ -1,4 +1,4 @@
-// GSD-2 + Visual Brief artifact policy
+// gsd-pi + Visual Brief artifact policy
 import { join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
 export function getVisualBriefOutputDir(agentDir = getAgentDir()) {

package/dist/resources/extensions/visual-brief/index.js

@@ -1,4 +1,4 @@
-// GSD-2 + Visual Brief bundled extension marker
+// gsd-pi + Visual Brief bundled extension marker
 export default function visualBrief(_pi) {
     // Visual Brief is invoked through /gsd brief. This module keeps the bundled
     // extension discoverable without adding a second top-level slash command.

package/dist/resources/extensions/visual-brief/page-contract.js

@@ -1,4 +1,4 @@
-// GSD-2 + Visual Brief page contract
+// gsd-pi + Visual Brief page contract
 export const VISUAL_BRIEF_PAGE_RULES = [
     "Use Mermaid for topology-heavy diagrams when it improves readability.",
     "Use semantic HTML tables for comparisons, audits, matrices, status reports, and dense lists.",

package/dist/resources/extensions/visual-brief/prompts.js

@@ -1,4 +1,4 @@
-// GSD-2 + Visual Brief prompt construction
+// gsd-pi + Visual Brief prompt construction
 import { createVisualBriefArtifactPolicy, formatArtifactPolicy, } from "./artifact-policy.js";
 import { formatPageRules, getVisualBriefModeProfile, } from "./page-contract.js";
 import { renderHtmlShellTemplate } from "../shared/html-shell.js";

package/dist/resources/skills/api-design/SKILL.md

@@ -8,7 +8,7 @@ Shape an HTTP or GraphQL API so callers get predictable, evolvable, and honest s
 </objective>
 
 <context>
-GSD-2 has `design-an-interface` for general module-interface design; this skill is the HTTP/GraphQL specialization. REST and GraphQL carry baggage — status codes, verbs, nullability, pagination — that a generic interface-design discussion glosses over.
+gsd-pi has `design-an-interface` for general module-interface design; this skill is the HTTP/GraphQL specialization. REST and GraphQL carry baggage — status codes, verbs, nullability, pagination — that a generic interface-design discussion glosses over.
 
 Invocation points:
 - Adding a new public API endpoint

package/dist/resources/skills/create-gsd-extension/SKILL.md

@@ -67,7 +67,7 @@ All domain knowledge in `references/`:
 **Infrastructure:** model-provider-management.md, remote-execution-overrides.md, packaging-distribution.md, mode-behavior.md
 **Spec:** `docs/extension-sdk/manifest-spec.md` — manifest format, tiers, validation
 **Testing:** `docs/extension-sdk/testing.md` — mock patterns, test conventions
-**SDK:** `docs/extension-sdk/` — the authoritative GSD-2 extension guide
+**SDK:** `docs/extension-sdk/` — the authoritative gsd-pi extension guide
 **Gotchas:** key-rules-gotchas.md
 </reference_index>
 

package/dist/resources/skills/create-mcp-server/SKILL.md

@@ -8,7 +8,7 @@ Produce a high-quality MCP server that an LLM can actually use — not one that
 </objective>
 
 <context>
-GSD-2 consumes MCP heavily — see `src/resources/extensions/mcp-client/`, `src/resources/extensions/gsd/mcp-project-config.ts`, `src/resources/extensions/gsd/workflow-mcp.ts`, and `/gsd mcp` commands. Users frequently want to extend GSD with project-specific MCP servers (internal APIs, data sources, domain tools). This skill fills the authoring gap between "MCP exists" and "I have a working server."
+gsd-pi consumes MCP heavily — see `src/resources/extensions/mcp-client/`, `src/resources/extensions/gsd/mcp-project-config.ts`, `src/resources/extensions/gsd/workflow-mcp.ts`, and `/gsd mcp` commands. Users frequently want to extend GSD with project-specific MCP servers (internal APIs, data sources, domain tools). This skill fills the authoring gap between "MCP exists" and "I have a working server."
 
 Invocation points:
 - User describes a service or API they want an LLM to reach

package/dist/resources/skills/create-skill/SKILL.md

@@ -88,9 +88,12 @@ Then proceed directly to the workflow.
 ## Skill Structure Quick Reference
 
 **Skill directories:**
+- Bundled/read-only: `~/.gsd/agent/skills/{skill-name}/`
 - Global: `~/.agents/skills/{skill-name}/`
 - Project-local: `.agents/skills/{skill-name}/`
 
+User-authored skills should target the global or project-local directories; GSD manages the bundled directory during install/update.
+
 **Simple skill (single file):**
 ```yaml
 ---

package/dist/resources/skills/create-skill/references/gsd-skill-ecosystem.md

@@ -3,7 +3,12 @@ GSD-specific skill ecosystem details: directory conventions, discovery mechanics
 </overview>
 
 <skill_directories>
-GSD supports two skill directories, checked in order:
+GSD supports these skill directories, checked in order:
+
+**Bundled (GSD-managed):** `~/.gsd/agent/skills/`
+- Synced by GSD during install/update
+- Highest priority when names collide
+- Not the target for user-authored skills
 
 **User-scope (global):** `~/.agents/skills/`
 - Available in every GSD session regardless of working directory
@@ -14,17 +19,21 @@ GSD supports two skill directories, checked in order:
 - Committable to version control so team members share the same skill set
 - Ideal for project-specific workflows, deploy scripts, or conventions
 
-Skills in both directories follow the same SKILL.md format and router pattern conventions.
+**Claude Code compatibility:** `~/.claude/skills/` and `.claude/skills/`
+- Read after the standard Agent Skills directories
+- Useful for compatibility with existing Claude Code skill installs
+
+Skills in all directories follow the same SKILL.md format and router pattern conventions.
 </skill_directories>
 
 <skill_discovery>
 GSD auto-discovers skills at session start and during auto-mode:
 
-**Session start:** All skills in both directories are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.
+**Session start:** All discovered skills are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.
 
 **Auto-mode discovery:** `skill-discovery.ts` takes a snapshot of the skills directory at auto-mode start. On each unit boundary it diffs against the snapshot. Any new skills found are injected via a `<newly_discovered_skills>` XML block so the LLM sees them without requiring `/reload`.
 
-**Manual reload:** Running `/reload` re-scans both directories and updates the available skills list mid-session.
+**Manual reload:** Running `/reload` re-scans the skill directories and updates the available skills list mid-session.
 </skill_discovery>
 
 <skill_validation>

package/dist/resources/skills/create-skill/workflows/create-new-skill.md

@@ -18,6 +18,8 @@
 1. **Global** (`~/.agents/skills/`) — Available in all GSD sessions
 2. **Project-local** (`.agents/skills/`) — Available only in this project
 
+Do not create user-authored skills under `~/.gsd/agent/skills/`; GSD owns that bundled skills directory.
+
 ## Step 2: Adaptive Requirements Gathering
 
 **If user provided context** (e.g., "build a skill for X"):

package/dist/resources/skills/dependency-upgrade/SKILL.md

@@ -8,7 +8,7 @@ Turn a pile of outdated packages into a series of small, verifiable upgrades wit
 </objective>
 
 <context>
-GSD-2 ships a `/gsd start dep-upgrade` workflow template (`src/resources/extensions/gsd/workflow-templates/dep-upgrade.md`) that structures the phases: assess → upgrade → fix breaks → verify. This skill is the execution-level detail inside the upgrade phase — how to batch, how to verify, how to recover from a breaking upgrade without losing the good ones.
+gsd-pi ships a `/gsd start dep-upgrade` workflow template (`src/resources/extensions/gsd/workflow-templates/dep-upgrade.md`) that structures the phases: assess → upgrade → fix breaks → verify. This skill is the execution-level detail inside the upgrade phase — how to batch, how to verify, how to recover from a breaking upgrade without losing the good ones.
 
 Invocation points:
 - `/gsd start dep-upgrade` workflow is running

package/dist/resources/skills/observability/SKILL.md

@@ -8,7 +8,7 @@ Instrument code so that a cold-start agent can understand what happened by readi
 </objective>
 
 <context>
-GSD-2's `VISION.md` lists "agent-first observability" as a principle, and the system prompt calls it out: "A future version of you will land in this codebase with no memory… you add observability because you're the one who'll need it at 3am." GSD-2 already exemplifies this — `activity/*.jsonl`, `journal/*.jsonl`, `metrics.json`, `doctor-history.jsonl` — but new code doesn't get that treatment automatically.
+gsd-pi's `VISION.md` lists "agent-first observability" as a principle, and the system prompt calls it out: "A future version of you will land in this codebase with no memory… you add observability because you're the one who'll need it at 3am." gsd-pi already exemplifies this — `activity/*.jsonl`, `journal/*.jsonl`, `metrics.json`, `doctor-history.jsonl` — but new code doesn't get that treatment automatically.
 
 This skill is the thinking process for adding it. Not "add logs everywhere" — add the *right* signals at the *right* decision points.
 
@@ -62,7 +62,7 @@ log.info({
 });
 ```
 
-Use the project's existing logger if one exists. In gsd-2, follow the patterns in `src/resources/extensions/gsd/activity-log.ts` and `src/resources/extensions/gsd/journal.ts` — structured JSONL, one event per line, with `ts`, `event`, and domain-specific fields.
+Use the project's existing logger if one exists. In gsd-pi, follow the patterns in `src/resources/extensions/gsd/activity-log.ts` and `src/resources/extensions/gsd/journal.ts` — structured JSONL, one event per line, with `ts`, `event`, and domain-specific fields.
 
 Avoid:
 - `console.log("here")` — what does "here" mean in six months?
@@ -86,14 +86,14 @@ await writeAtomically(
 );
 ```
 
-A fresh agent reading `.gsd/runtime/` sees what happened last, what was retried, and where the process stopped. Pattern exists already in gsd-2 — reuse the `atomic-write.ts` helpers and the `.gsd/runtime/` and `.gsd/forensics/` directories.
+A fresh agent reading `.gsd/runtime/` sees what happened last, what was retried, and where the process stopped. Pattern exists already in gsd-pi — reuse the `atomic-write.ts` helpers and the `.gsd/runtime/` and `.gsd/forensics/` directories.
 
 ## Step 4: Health and status surfaces
 
 For long-running processes:
 
 - **Health endpoint** (HTTP server) or **status file** (CLI tool). Cheap to call, no side effects. Returns current state: `{status: "healthy" | "degraded" | "down", ...diagnostics}`.
-- **Digest view** — a small representation of recent work. In gsd-2, this is `STATE.md` and the health widget. In a server, it's `/internal/status` with last 10 request summaries.
+- **Digest view** — a small representation of recent work. In gsd-pi, this is `STATE.md` and the health widget. In a server, it's `/internal/status` with last 10 request summaries.
 - **Minimal metrics** — counters for the 3–5 things that matter (requests, errors, active jobs). Not everything — just what drives alerts.
 
 Don't build a metrics empire. Build exactly what you'd check at 3am.

package/dist/resources/skills/security-review/SKILL.md

@@ -8,7 +8,7 @@ Produce a security review that names specific exploit paths through the actual c
 </objective>
 
 <context>
-GSD-2's general `review` skill covers security as one of several categories. This skill is the deeper pass — triggered deliberately when security is the primary concern. It complements v1's `/gsd-secure-phase` concept, adapted to the gsd-2 artifact model.
+gsd-pi's general `review` skill covers security as one of several categories. This skill is the deeper pass — triggered deliberately when security is the primary concern. It complements v1's `/gsd-secure-phase` concept, adapted to the gsd-pi artifact model.
 
 Invocation points:
 - Any change touching authentication, authorization, session handling