gsd-pi 2.78.0-dev.aeeb2ca00 → 2.78.1-dev.84a383f51

package/src/resources/extensions/mcp-client/tests/global-config.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Regression test for #4757 — readConfigs() must also read the global
+ * ~/.gsd/mcp.json (resolved as $GSD_HOME/mcp.json when GSD_HOME is set).
+ *
+ * Behaviour test against the exported getServerConfig — no source grep.
+ * The fixture is anchored via $GSD_HOME so the test never touches the
+ * developer's real ~/.gsd directory.
+ */
+
+import test, { before, after } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { getServerConfig } from "../index.js";
+
+let cwdDir: string;
+let gsdHomeDir: string;
+let originalCwd: string;
+let originalGsdHome: string | undefined;
+
+before(() => {
+	originalCwd = process.cwd();
+	originalGsdHome = process.env.GSD_HOME;
+
+	// realpathSync resolves any symlink in tmpdir() — on macOS /var → /private/var
+	// so process.cwd() after chdir matches what mkdtempSync returned.
+	cwdDir = realpathSync(mkdtempSync(join(tmpdir(), "mcp-cwd-")));
+	gsdHomeDir = realpathSync(mkdtempSync(join(tmpdir(), "mcp-gsdhome-")));
+
+	// Project-local fixture (also defines `shared-server` for the precedence test)
+	writeFileSync(
+		join(cwdDir, ".mcp.json"),
+		JSON.stringify({
+			mcpServers: {
+				"project-server": { command: "echo", args: ["proj"] },
+				"shared-server": { command: "echo", args: ["from-project"] },
+			},
+		}),
+		"utf-8",
+	);
+
+	// Global fixture rooted at $GSD_HOME (also defines `shared-server` to test
+	// that project-local takes precedence on name collision)
+	writeFileSync(
+		join(gsdHomeDir, "mcp.json"),
+		JSON.stringify({
+			mcpServers: {
+				"global-server": { command: "echo", args: ["glob"] },
+				"shared-server": { command: "echo", args: ["from-global"] },
+			},
+		}),
+		"utf-8",
+	);
+
+	process.chdir(cwdDir);
+	process.env.GSD_HOME = gsdHomeDir;
+});
+
+after(() => {
+	process.chdir(originalCwd);
+	if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+	else process.env.GSD_HOME = originalGsdHome;
+	try { rmSync(cwdDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+	try { rmSync(gsdHomeDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+});
+
+test("#4757: getServerConfig resolves servers declared in $GSD_HOME/mcp.json", () => {
+	const cfg = getServerConfig("global-server");
+	assert.ok(cfg, "server defined in $GSD_HOME/mcp.json must resolve");
+	assert.equal(cfg?.name, "global-server");
+	assert.equal(cfg?.sourcePath, join(gsdHomeDir, "mcp.json"));
+});
+
+test("#4757: project-local servers still resolve when global config exists", () => {
+	const cfg = getServerConfig("project-server");
+	assert.ok(cfg, "project-local server must continue to resolve");
+	assert.equal(cfg?.sourcePath, join(cwdDir, ".mcp.json"));
+});
+
+test("#4757: project-local config wins on server-name collision", () => {
+	const cfg = getServerConfig("shared-server");
+	assert.ok(cfg, "shared server must resolve");
+	assert.equal(
+		cfg?.sourcePath,
+		join(cwdDir, ".mcp.json"),
+		"project-local config must take precedence over $GSD_HOME on name collision",
+	);
+	assert.deepEqual(cfg?.args, ["from-project"]);
+});

package/src/resources/extensions/slash-commands/create-extension.ts

@@ -221,41 +221,38 @@ function sendPrompt(description: string, result: RoundResult, pi: ExtensionAPI):
 		: "";
 
 	const docHints: string[] = [
-		"- `~/.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:
@@ -270,13 +267,30 @@ ${docHints.join("\n")}
 
 ## Output
 
-Write the complete implementation as a single self-contained extension file:
-
-\`~/.gsd/agent/extensions/<kebab-case-name>.ts\`
-
-Then register it in the main extensions index:
+Write the complete implementation as a directory-based extension:
+
+\`~/.gsd/agent/extensions/<kebab-case-name>/index.ts\`
+\`~/.gsd/agent/extensions/<kebab-case-name>/extension-manifest.json\`
+
+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
 

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

@@ -19,8 +19,8 @@ Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from
 3. **Commands** — Give users slash commands (`pi.registerCommand()`). Users type `/mycommand`.
 
 **Non-negotiable rules:**
-- Use `StringEnum` from `@mariozechner/pi-ai` for string enum params (NOT `Type.Union`/`Type.Literal` — breaks Google's API)
-- Truncate tool output to 50KB / 2000 lines max (use `truncateHead`/`truncateTail` from `@mariozechner/pi-coding-agent`)
+- Use `StringEnum` from `@gsd/pi-ai` for string enum params (NOT `Type.Union`/`Type.Literal` — breaks Google's API)
+- Truncate tool output to 50KB / 2000 lines max (use `truncateHead`/`truncateTail` from `@gsd/pi-coding-agent`)
 - Store stateful tool state in `details` for branching support
 - Check `signal?.aborted` in long-running tool executions
 - Use `pi.exec()` not `child_process` for shell commands
@@ -34,10 +34,10 @@ Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from
 
 | Package | Purpose |
 |---------|---------|
-| `@mariozechner/pi-coding-agent` | `ExtensionAPI`, `ExtensionContext`, `Theme`, event types, tool utilities, `DynamicBorder`, `BorderedLoader`, `CustomEditor`, `highlightCode` |
+| `@gsd/pi-coding-agent` | `ExtensionAPI`, `ExtensionContext`, `Theme`, event types, tool utilities, `DynamicBorder`, `BorderedLoader`, `CustomEditor`, `highlightCode` |
 | `@sinclair/typebox` | `Type.Object`, `Type.String`, `Type.Number`, `Type.Optional`, `Type.Boolean`, `Type.Array` |
-| `@mariozechner/pi-ai` | `StringEnum` (required for string enums), `Type` re-export |
-| `@mariozechner/pi-tui` | `Text`, `Box`, `Container`, `Spacer`, `Markdown`, `SelectList`, `Input`, `matchesKey`, `Key`, `truncateToWidth`, `visibleWidth` |
+| `@gsd/pi-ai` | `StringEnum` (required for string enums), `Type` re-export |
+| `@gsd/pi-tui` | `Text`, `Box`, `Container`, `Spacer`, `Markdown`, `SelectList`, `Input`, `matchesKey`, `Key`, `truncateToWidth`, `visibleWidth` |
 | Node.js built-ins | `node:fs`, `node:path`, `node:child_process`, etc. |
 
 </essential_principles>
@@ -65,6 +65,9 @@ All domain knowledge in `references/`:
 **Capabilities:** custom-tools.md, custom-commands.md, custom-ui.md, custom-rendering.md
 **Patterns:** state-management.md, system-prompt-modification.md, compaction-session-control.md
 **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
 **Gotchas:** key-rules-gotchas.md
 </reference_index>
 
@@ -78,6 +81,7 @@ All domain knowledge in `references/`:
 
 <success_criteria>
 Extension is complete when:
+- `extension-manifest.json` exists with accurate `provides` listing all registered tools/commands/hooks/shortcuts
 - TypeScript compiles without errors (jiti handles this at runtime)
 - Extension loads on GSD startup or `/reload` without errors
 - Tools appear in the LLM's system prompt and are callable

package/src/resources/skills/create-gsd-extension/references/custom-commands.md

@@ -19,7 +19,7 @@ pi.registerCommand("deploy", {
 Add tab-completion for command arguments:
 
 ```typescript
-import type { AutocompleteItem } from "@mariozechner/pi-tui";
+import type { AutocompleteItem } from "@gsd/pi-tui";
 
 pi.registerCommand("deploy", {
   description: "Deploy to an environment",

package/src/resources/skills/create-gsd-extension/references/custom-rendering.md

@@ -6,8 +6,8 @@ Custom rendering for tools and messages — control how they appear in the TUI.
 Tools can provide `renderCall` (how the call looks) and `renderResult` (how the result looks):
 
 ```typescript
-import { Text } from "@mariozechner/pi-tui";
-import { keyHint } from "@mariozechner/pi-coding-agent";
+import { Text } from "@gsd/pi-tui";
+import { keyHint } from "@gsd/pi-coding-agent";
 
 pi.registerTool({
   name: "my_tool",
@@ -54,7 +54,7 @@ If you omit `renderCall`/`renderResult`, the built-in renderer is used. Useful f
 Key hint helpers for showing keybinding info in render output:
 
 ```typescript
-import { keyHint, appKeyHint, editorKey, rawKeyHint } from "@mariozechner/pi-coding-agent";
+import { keyHint, appKeyHint, editorKey, rawKeyHint } from "@gsd/pi-coding-agent";
 
 // Editor action hint (respects user keybinding config)
 keyHint("expandTools", "to expand")    // e.g., "Ctrl+O to expand"
@@ -69,7 +69,7 @@ rawKeyHint("Ctrl+O", "to expand")
 Register a renderer for custom message types:
 
 ```typescript
-import { Text } from "@mariozechner/pi-tui";
+import { Text } from "@gsd/pi-tui";
 
 pi.registerMessageRenderer("my-extension", (message, options, theme) => {
   const { expanded } = options;
@@ -92,7 +92,7 @@ pi.sendMessage({
 
 <syntax_highlighting>
 ```typescript
-import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+import { highlightCode, getLanguageFromPath } from "@gsd/pi-coding-agent";
 
 const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"
 const highlighted = highlightCode(code, lang, theme);

package/src/resources/skills/create-gsd-extension/references/custom-tools.md

@@ -5,7 +5,7 @@ Complete custom tools reference — registration, parameters, execution, output
 <registration>
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@gsd/pi-ai";
 
 pi.registerTool({
   name: "my_tool",                    // Unique identifier (snake_case)
@@ -60,7 +60,7 @@ pi.registerTool({
 **⚠️ MUST use `StringEnum` for string enum parameters:**
 
 ```typescript
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@gsd/pi-ai";
 
 // ✅ Correct — works with all providers including Google
 action: StringEnum(["list", "add", "remove"] as const)
@@ -77,7 +77,7 @@ Tools MUST truncate output to avoid context overflow. Built-in limit: 50KB / 200
 import {
   truncateHead, truncateTail, formatSize,
   DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES,
-} from "@mariozechner/pi-coding-agent";
+} from "@gsd/pi-coding-agent";
 
 async execute(toolCallId, params, signal, onUpdate, ctx) {
   const output = await runCommand();
@@ -129,7 +129,7 @@ Use `pi.setActiveTools(names)` to enable/disable tools at runtime.
 Register a tool with the same name as a built-in (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) to override it. **Must match exact result shape including `details` type.**
 
 ```typescript
-import { createReadTool } from "@mariozechner/pi-coding-agent";
+import { createReadTool } from "@gsd/pi-coding-agent";
 
 pi.registerTool({
   name: "read",

package/src/resources/skills/create-gsd-extension/references/custom-ui.md

@@ -277,7 +277,7 @@ bottom-left  bottom-center  bottom-right
 Replace the main input editor permanently:
 
 ```typescript
-import { CustomEditor } from "@mariozechner/pi-coding-agent";
+import { CustomEditor } from "@gsd/pi-coding-agent";
 
 class VimEditor extends CustomEditor {
   private mode: "normal" | "insert" = "insert";
@@ -307,7 +307,7 @@ ctx.ui.setEditorComponent(undefined);  // Restore default
 </custom_editor>
 
 <built_in_components>
-**From `@mariozechner/pi-tui`:**
+**From `@gsd/pi-tui`:**
 
 | Component | Constructor | Purpose |
 |-----------|-------------|---------|
@@ -352,7 +352,7 @@ const settings = new SettingsList(items, 15, getSettingsListTheme(),
 );
 ```
 
-**From `@mariozechner/pi-coding-agent`:**
+**From `@gsd/pi-coding-agent`:**
 
 | Component | Constructor | Purpose |
 |-----------|-------------|---------|
@@ -363,7 +363,7 @@ const settings = new SettingsList(items, 15, getSettingsListTheme(),
 
 <keyboard_input>
 ```typescript
-import { matchesKey, Key } from "@mariozechner/pi-tui";
+import { matchesKey, Key } from "@gsd/pi-tui";
 
 handleInput(data: string) {
   // Basic keys
@@ -403,7 +403,7 @@ handleInput(data: string) {
 **Cardinal rule: each line from render() must not exceed `width` visible characters.**
 
 ```typescript
-import { visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import { visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@gsd/pi-tui";
 
 visibleWidth("\x1b[32mHello\x1b[0m");  // Returns 5 (ignores ANSI codes)
 truncateToWidth("Very long text here", 10);         // "Very lo..."
@@ -470,7 +470,7 @@ Always use theme from callback params, never import directly.
 
 **Syntax highlighting:**
 ```typescript
-import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+import { highlightCode, getLanguageFromPath } from "@gsd/pi-coding-agent";
 const lang = getLanguageFromPath("/file.rs");  // "rust"
 const highlighted = highlightCode(code, lang, theme);
 ```

package/src/resources/skills/create-gsd-extension/references/events-reference.md

@@ -47,7 +47,7 @@ pi.on("before_agent_start", async (event, ctx) => {
 
 **tool_call** — Fired before tool executes. Can block.
 ```typescript
-import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@gsd/pi-coding-agent";
 
 pi.on("tool_call", async (event, ctx) => {
   if (isToolCallEventType("bash", event)) {
@@ -61,7 +61,7 @@ pi.on("tool_call", async (event, ctx) => {
 
 **tool_result** — Fired after tool executes. Can modify result. Handlers chain like middleware.
 ```typescript
-import { isToolResultEventType } from "@mariozechner/pi-coding-agent";
+import { isToolResultEventType } from "@gsd/pi-coding-agent";
 
 pi.on("tool_result", async (event, ctx) => {
   if (isToolResultEventType("bash", event)) {
@@ -105,7 +105,7 @@ pi.on("model_select", async (event, ctx) => {
 Built-in type guards for tool events:
 
 ```typescript
-import { isToolCallEventType, isToolResultEventType } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType, isToolResultEventType } from "@gsd/pi-coding-agent";
 
 // Tool calls — narrows event.input type
 if (isToolCallEventType("bash", event)) { /* event.input: { command, timeout? } */ }

package/src/resources/skills/create-gsd-extension/references/packaging-distribution.md

@@ -39,7 +39,7 @@ If no `pi` manifest exists, auto-discovers:
 </convention_directories>
 
 <dependencies>
-- List `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@sinclair/typebox` in `peerDependencies` with `"*"` — they're bundled by the runtime.
+- List `@gsd/pi-ai`, `@gsd/pi-coding-agent`, `@gsd/pi-tui`, `@sinclair/typebox` in `peerDependencies` with `"*"` — they're bundled by the runtime.
 - Other npm deps go in `dependencies`. The runtime runs `npm install` on package installation.
 </dependencies>
 

package/src/resources/skills/create-gsd-extension/references/remote-execution-overrides.md

@@ -6,7 +6,7 @@ Remote execution via pluggable operations, spawnHook for bash, and tool override
 Built-in tools support pluggable operations for SSH, containers, etc.:
 
 ```typescript
-import { createReadTool, createBashTool, createWriteTool } from "@mariozechner/pi-coding-agent";
+import { createReadTool, createBashTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 // Create tool with custom remote operations
 const remoteBash = createBashTool(cwd, {
@@ -37,7 +37,7 @@ const bashTool = createBashTool(cwd, {
 Full SSH pattern with flag-based switching:
 
 ```typescript
-import { createBashTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createBashTool, type ExtensionAPI } from "@gsd/pi-coding-agent";
 
 export default function (pi: ExtensionAPI) {
   pi.registerFlag("ssh", { description: "SSH target", type: "string" });
@@ -65,7 +65,7 @@ export default function (pi: ExtensionAPI) {
 Override built-in tools for logging/access control — omit renderCall/renderResult to keep built-in rendering:
 
 ```typescript
-import { createReadTool } from "@mariozechner/pi-coding-agent";
+import { createReadTool } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
 pi.registerTool({

package/src/resources/skills/create-gsd-extension/templates/extension-skeleton.ts

@@ -5,9 +5,9 @@
  * {{CAPABILITIES_LIST}}
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@gsd/pi-ai";
 
 export default function (pi: ExtensionAPI) {
   // === Events ===

package/src/resources/skills/create-gsd-extension/templates/stateful-tool-skeleton.ts

@@ -4,10 +4,10 @@
  * State is stored in tool result details for proper branching support.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
-import { Text, truncateToWidth, matchesKey, Key } from "@mariozechner/pi-tui";
+import { StringEnum } from "@gsd/pi-ai";
+import { Text, truncateToWidth, matchesKey, Key } from "@gsd/pi-tui";
 
 interface {{ItemType}} {
   id: number;

package/src/resources/skills/create-gsd-extension/templates/templates.test.ts

@@ -0,0 +1,58 @@
+// GSD-2 — Extension template import path validation
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillRoot = join(__dirname, "..");
+
+function walk(dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory()) {
+			out.push(...walk(full));
+		} else {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+describe("extension templates use @gsd/* imports", () => {
+	const templates = ["extension-skeleton.ts", "stateful-tool-skeleton.ts"];
+
+	for (const template of templates) {
+		it(`${template} uses @gsd/pi-coding-agent (not @mariozechner)`, () => {
+			const content = readFileSync(join(__dirname, template), "utf-8");
+			assert.ok(content.includes("@gsd/pi-coding-agent"), `Expected @gsd/pi-coding-agent import in ${template}`);
+			assert.ok(!content.includes("@mariozechner/"), `Found stale @mariozechner/ import in ${template}`);
+		});
+	}
+
+	it("extension-skeleton.ts uses @gsd/pi-ai for StringEnum", () => {
+		const content = readFileSync(join(__dirname, "extension-skeleton.ts"), "utf-8");
+		assert.ok(content.includes("@gsd/pi-ai"), "Expected @gsd/pi-ai import");
+	});
+
+	it("stateful-tool-skeleton.ts uses @gsd/pi-tui", () => {
+		const content = readFileSync(join(__dirname, "stateful-tool-skeleton.ts"), "utf-8");
+		assert.ok(content.includes("@gsd/pi-tui"), "Expected @gsd/pi-tui import");
+	});
+
+	it("no @mariozechner/ references anywhere in create-gsd-extension/", () => {
+		const offenders: string[] = [];
+		for (const file of walk(skillRoot)) {
+			if (file.endsWith("templates.test.ts")) continue;
+			const content = readFileSync(file, "utf-8");
+			if (content.includes("@mariozechner/")) {
+				offenders.push(relative(skillRoot, file));
+			}
+		}
+		assert.deepEqual(offenders, [], `Stale @mariozechner/ references found in: ${offenders.join(", ")}`);
+	});
+});

package/src/resources/skills/create-gsd-extension/workflows/create-extension.md

@@ -34,22 +34,19 @@ Identify what the extension needs from the user's description:
 
 ## Step 3: Choose Extension Structure
 
-**Single file** — for small extensions (1-2 tools/commands, simple hooks):
-```
-~/.pi/agent/extensions/my-extension.ts
-```
-
-**Directory with index.ts** — for multi-file extensions:
+**Directory with index.ts** — the standard pattern for all extensions:
 ```
 ~/.pi/agent/extensions/my-extension/
-├── index.ts
-├── tools.ts
-└── utils.ts
+├── extension-manifest.json   # Required — declares capabilities
+├── index.ts                  # Entry point (must export default function)
+├── tools.ts                  # Optional — tool implementations
+└── utils.ts                  # Optional — shared utilities
 ```
 
 **Package with dependencies** — when npm packages are needed:
 ```
 ~/.pi/agent/extensions/my-extension/
+├── extension-manifest.json
 ├── package.json
 ├── src/index.ts
 └── node_modules/
@@ -64,12 +61,34 @@ For packages, `package.json` needs:
 }
 ```
 
+## Step 3b: Create the Extension Manifest
+
+Every extension must include an `extension-manifest.json`:
+
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "version": "1.0.0",
+  "description": "What this extension does in one line",
+  "tier": "community",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["my_tool"],
+    "commands": ["mycommand"],
+    "hooks": ["session_start"]
+  }
+}
+```
+
+Only include non-empty arrays in `provides`. See `docs/extension-sdk/manifest-spec.md` for the full spec.
+
 ## Step 4: Write the Extension
 
 Start with the skeleton:
 
 ```typescript
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
 export default function (pi: ExtensionAPI) {
   // Register events, tools, commands here
@@ -81,7 +100,7 @@ Then add capabilities based on Step 2. Reference the appropriate reference files
 **Tool registration pattern:**
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@gsd/pi-ai";
 
 pi.registerTool({
   name: "my_tool",
@@ -144,7 +163,8 @@ Fix issues, add features, refine. Use `/reload` for hot-reload during developmen
 
 <success_criteria>
 Extension creation is complete when:
-- [ ] Extension file(s) written to correct location
+- [ ] Extension directory created with index.ts and extension-manifest.json
+- [ ] Manifest `provides` accurately lists all registered tools, commands, hooks, shortcuts
 - [ ] All imports resolve (TypeBox, pi-ai, pi-coding-agent, pi-tui as needed)
 - [ ] Tools use `StringEnum` for string enums (not `Type.Union`/`Type.Literal`)
 - [ ] Tool output is truncated if variable-length