gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -21,8 +21,38 @@ import { join } from "node:path";
 import { buildHttpTransportOpts } from "./auth.js";
 // ─── Connection Manager ───────────────────────────────────────────────────────
 const connections = new Map();
+const pendingConnections = new Map();
 let configCache = null;
 const toolCache = new Map();
+const trustedStdioServers = new Set();
+const CHILD_ENV_ALLOWLIST = new Set([
+    "PATH",
+    "Path",
+    "HOME",
+    "USER",
+    "USERNAME",
+    "USERPROFILE",
+    "SHELL",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SystemRoot",
+    "WINDIR",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+]);
+function stdioTrustKey(config) {
+    return JSON.stringify({
+        name: config.name,
+        sourcePath: config.sourcePath,
+        command: config.command,
+        args: config.args ?? [],
+        cwd: config.cwd,
+        env: config.env ?? {},
+    });
+}
 function readConfigs() {
     if (configCache)
         return configCache;
@@ -57,6 +87,7 @@ function readConfigs() {
                 servers.push({
                     name,
                     transport,
+                    sourcePath: configPath,
                     ...(hasCommand && {
                         command: config.command,
                         args: Array.isArray(config.args) ? config.args : undefined,
@@ -78,7 +109,45 @@ function readConfigs() {
     configCache = servers;
     return servers;
 }
-function getServerConfig(name) {
+export function _buildMcpChildEnvForTest(configEnv) {
+    const childEnv = {};
+    for (const key of CHILD_ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (typeof value === "string")
+            childEnv[key] = value;
+    }
+    return {
+        ...childEnv,
+        ...(configEnv ? resolveEnv(configEnv) : {}),
+    };
+}
+export function _buildMcpTrustConfirmOptionsForTest(signal) {
+    return signal ? { timeout: 120_000, signal } : { timeout: 120_000 };
+}
+async function assertTrustedStdioServer(config, ctx, signal) {
+    if (config.transport !== "stdio")
+        return undefined;
+    const trustKey = stdioTrustKey(config);
+    if (trustedStdioServers.has(trustKey))
+        return undefined;
+    if (!ctx?.hasUI) {
+        throw new Error(`MCP server "${config.name}" is a project-local stdio command from ${config.sourcePath}. ` +
+            "Run this from an interactive GSD session and approve the server before use.");
+    }
+    const commandLine = [config.command, ...(config.args ?? [])].filter(Boolean).join(" ");
+    const envKeys = Object.keys(config.env ?? {});
+    const envSummary = envKeys.length > 0
+        ? `\n\nConfigured environment keys: ${envKeys.join(", ")}`
+        : "\n\nNo explicit environment keys configured.";
+    const approved = await ctx.ui.confirm(`Trust MCP server "${config.name}"?`, `Project config ${config.sourcePath} wants to start:\n\n${commandLine}${envSummary}\n\nOnly approve MCP servers you trust.`, _buildMcpTrustConfirmOptionsForTest(signal));
+    if (!approved) {
+        throw new Error(`MCP server "${config.name}" was not approved by the user.`);
+    }
+    return trustKey;
+}
+// Exported for tests (see tests/server-name-spaces.test.ts).
+// Production call sites treat this as module-private.
+export function getServerConfig(name) {
     const trimmed = name.trim();
     return readConfigs().find((s) => s.name === trimmed ||
         s.name.toLowerCase() === trimmed.toLowerCase());
@@ -96,7 +165,7 @@ function resolveEnv(env) {
     }
     return resolved;
 }
-async function getOrConnect(name, signal) {
+async function getOrConnect(name, signal, ctx) {
     const config = getServerConfig(name);
     if (!config)
         throw new Error(`Unknown MCP server: "${name}". Use mcp_servers to list available servers.`);
@@ -105,13 +174,28 @@ async function getOrConnect(name, signal) {
     const existing = connections.get(config.name);
     if (existing)
         return existing.client;
+    const pending = pendingConnections.get(config.name);
+    if (pending)
+        return pending;
+    const connectionPromise = connectServer(config, signal, ctx);
+    pendingConnections.set(config.name, connectionPromise);
+    try {
+        return await connectionPromise;
+    }
+    finally {
+        pendingConnections.delete(config.name);
+    }
+}
+async function connectServer(config, signal, ctx) {
     const client = new Client({ name: "gsd", version: "1.0.0" });
     let transport;
+    let approvedTrustKey;
     if (config.transport === "stdio" && config.command) {
+        approvedTrustKey = await assertTrustedStdioServer(config, ctx, signal);
         transport = new StdioClientTransport({
             command: config.command,
             args: config.args,
-            env: config.env ? { ...process.env, ...resolveEnv(config.env) } : undefined,
+            env: _buildMcpChildEnvForTest(config.env),
             cwd: config.cwd,
             stderr: "pipe",
         });
@@ -127,9 +211,28 @@ async function getOrConnect(name, signal) {
     else {
         throw new Error(`Server "${config.name}" has unsupported transport: ${config.transport}`);
     }
-    await client.connect(transport, { signal, timeout: 30000 });
-    connections.set(config.name, { client, transport });
-    return client;
+    try {
+        await client.connect(transport, { signal, timeout: 30000 });
+        if (approvedTrustKey)
+            trustedStdioServers.add(approvedTrustKey);
+        connections.set(config.name, { client, transport });
+        return client;
+    }
+    catch (err) {
+        try {
+            await transport.close();
+        }
+        catch {
+            // Best-effort cleanup after a failed or aborted connection attempt.
+        }
+        try {
+            await client.close();
+        }
+        catch {
+            // Best-effort cleanup after a failed or aborted connection attempt.
+        }
+        throw err;
+    }
 }
 async function closeAll() {
     const closing = Array.from(connections.entries()).map(async ([name, conn]) => {
@@ -139,9 +242,17 @@ async function closeAll() {
         catch {
             // Best-effort cleanup
         }
+        try {
+            await conn.transport.close();
+        }
+        catch {
+            // Best-effort cleanup
+        }
         connections.delete(name);
     });
     await Promise.allSettled(closing);
+    pendingConnections.clear();
+    trustedStdioServers.clear();
     toolCache.clear();
 }
 // ─── Formatters ───────────────────────────────────────────────────────────────
@@ -249,7 +360,7 @@ export default function (pi) {
                 description: "MCP server name (from mcp_servers output), e.g. 'railway', 'twitter-mcp', 'linear'",
             }),
         }),
-        async execute(_id, params, signal) {
+        async execute(_id, params, signal, _onUpdate, ctx) {
             try {
                 // Return cached tools if available
                 const cached = toolCache.get(params.server);
@@ -265,7 +376,7 @@ export default function (pi) {
                         details: { server: params.server, toolCount: cached.length, cached: true },
                     };
                 }
-                const client = await getOrConnect(params.server, signal);
+                const client = await getOrConnect(params.server, signal, ctx);
                 const result = await client.listTools(undefined, { signal, timeout: 30000 });
                 const tools = (result.tools ?? []).map((t) => ({
                     name: t.name,
@@ -326,9 +437,9 @@ export default function (pi) {
                 description: "Tool arguments as key-value pairs matching the tool's input schema",
             })),
         }),
-        async execute(_id, params, signal) {
+        async execute(_id, params, signal, _onUpdate, ctx) {
             try {
-                const client = await getOrConnect(params.server, signal);
+                const client = await getOrConnect(params.server, signal, ctx);
                 const result = await client.callTool({ name: params.tool, arguments: params.args ?? {} }, undefined, { signal, timeout: 60000 });
                 // Serialize result content to text
                 const contentItems = result.content;

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

@@ -38,8 +38,12 @@ let providerRegistered = false;
 /**
  * Probe Ollama and register discovered models.
  * Safe to call multiple times — re-discovers and re-registers.
+ *
+ * Exported for tests (see ollama-auth-mode.test.ts, ollama-status-indicator.test.ts)
+ * so a fake HTTP endpoint can drive the registration/unregistration paths.
+ * Production callers always go through the session_start handler below.
  */
-async function probeAndRegister(pi) {
+export async function probeAndRegister(pi) {
     const running = await client.isRunning();
     if (!running) {
         if (providerRegistered) {

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

@@ -16,21 +16,27 @@ const COMMAND_POLLING_INTERVAL_MS = 5000;
  *
  * @param basePath - Project root, forwarded to command handlers (e.g. /status).
  * @param intervalMs - Polling interval in milliseconds (default 5 s).
+ * @param deps - Test-only overrides. Omit in production.
  * @returns A cleanup function that stops the polling interval.
  */
-export function startCommandPolling(basePath, intervalMs = COMMAND_POLLING_INTERVAL_MS) {
-    const config = resolveRemoteConfig();
+export function startCommandPolling(basePath, intervalMs = COMMAND_POLLING_INTERVAL_MS, deps = {}) {
+    const resolveConfig = deps.resolveConfig ?? resolveRemoteConfig;
+    const createAdapter = deps.createAdapter ??
+        ((c, b) => new TelegramAdapter(c.token, c.channelId, b));
+    const setIntervalFn = deps.setIntervalFn ?? setInterval;
+    const clearIntervalFn = deps.clearIntervalFn ?? clearInterval;
+    const config = resolveConfig();
     if (!config || config.channel !== "telegram") {
         // Non-Telegram channels have no command polling support — return a no-op cleanup.
         return () => { };
     }
-    const adapter = new TelegramAdapter(config.token, config.channelId, basePath);
-    const timer = setInterval(() => {
+    const adapter = createAdapter(config, basePath);
+    const timer = setIntervalFn(() => {
         void adapter.pollAndHandleCommands(basePath).catch(() => {
             // Non-fatal: network hiccup or rate-limit — best-effort polling
         });
     }, intervalMs);
-    return () => clearInterval(timer);
+    return () => clearIntervalFn(timer);
 }
 /**
  * Check whether a remote channel is configured without triggering any

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

@@ -7,7 +7,7 @@
  *
  * All provider logic lives in provider.ts (S01) — this is pure UI wiring.
  */
-import { isAnthropicApi } from '@gsd/pi-ai';
+import { supportsNativeWebSearch } from './native-search.js';
 import { getTavilyApiKey, getBraveApiKey, getOllamaApiKey, getSearchProviderPreference, setSearchProviderPreference, resolveSearchProvider, } from './provider.js';
 const VALID_PREFERENCES = ['tavily', 'brave', 'ollama', 'auto'];
 function keyStatus(provider) {
@@ -72,9 +72,10 @@ export function registerSearchProviderCommand(pi) {
             }
             setSearchProviderPreference(chosen);
             const effective = resolveSearchProvider();
-            // Gate on api (#4478 / ADR-012): covers claude-code, anthropic-vertex, and
-            // other Anthropic-fronting transports — not just the plain `anthropic` provider.
-            const isAnthropic = isAnthropicApi(ctx.model);
+            // Gate on api shape + provider allowlist: the info note must match the
+            // actual runtime behavior in native-search.ts. Claude served via copilot
+            // / minimax / kimi is anthropic-shaped but does NOT run native search.
+            const isAnthropic = supportsNativeWebSearch(ctx.model);
             const nativeNote = isAnthropic ? '\nNote: Native Anthropic web search is also active (automatic, no API key needed).' : '';
             ctx.ui.notify(`Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}${nativeNote}`, 'info');
         },

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

@@ -12,6 +12,38 @@ export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
 export const CUSTOM_SEARCH_TOOL_NAMES = ["search-the-web", "search_and_read", "google_search"];
 /** Thinking block types that require signature validation by the API */
 const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
+/**
+ * Providers whose Anthropic-Messages endpoint is known to accept the native
+ * `web_search_20250305` server tool. Anthropic-shaped transports NOT in this
+ * set (github-copilot, minimax, kimi-coding, opencode, vercel-ai-gateway,
+ * etc.) route Claude or Claude-compatible models through the Messages API
+ * but do NOT expose the server-side search tool — injecting it yields a
+ * 400 "unsupported_value" from their endpoints (regression from #4492).
+ *
+ * Keep this allowlist tight — err on the side of custom/Brave search rather
+ * than a runtime 400. Add a provider here only after confirming its endpoint
+ * accepts the tool type.
+ */
+const NATIVE_WEB_SEARCH_PROVIDERS = new Set([
+    "anthropic",
+    "claude-code",
+    "anthropic-vertex",
+    "vercel-ai-gateway",
+]);
+/**
+ * True when the model is an Anthropic-shaped transport AND the provider is
+ * known to accept the native `web_search_20250305` tool. Gate both on api
+ * shape (#4478 / ADR-012) and on provider identity (#444 regression guard
+ * and #4492 scope correction) — provider-level discrimination is legitimate
+ * per ADR-012 for credential/behavior differences that api shape can't
+ * express.
+ */
+export function supportsNativeWebSearch(model) {
+    if (!isAnthropicApi(model))
+        return false;
+    const provider = model?.provider;
+    return typeof provider === "string" && NATIVE_WEB_SEARCH_PROVIDERS.has(provider);
+}
 /**
  * Maximum number of native web searches allowed per session (agent unit).
  * The Anthropic API's `max_uses` is per-request — it resets on each API call.
@@ -76,10 +108,11 @@ export function registerNativeSearchHooks(pi) {
     pi.on("model_select", async (event, ctx) => {
         modelSelectFired = true;
         const wasAnthropic = isAnthropicProvider;
-        // Gate on `api` not `provider` (#4478 / ADR-012): covers claude-code OAuth,
-        // anthropic-vertex, and Vercel-gateway-hosted Anthropic — all serve the
-        // Messages API and accept the native web_search tool.
-        isAnthropicProvider = isAnthropicApi(event.model);
+        // Gate on api shape AND provider allowlist: direct Anthropic, claude-code
+        // OAuth, and anthropic-vertex accept `web_search_20250305`; copilot /
+        // minimax / kimi / opencode route Claude-compat models through the same
+        // wire protocol but reject the server-side tool (#4492 regression).
+        isAnthropicProvider = supportsNativeWebSearch(event.model);
         const hasBrave = !!process.env.BRAVE_API_KEY;
         // When Anthropic (and not preferring Brave): disable custom search tools —
         // native web_search is server-side and more reliable.
@@ -120,20 +153,19 @@ export function registerNativeSearchHooks(pi) {
         // modelsAreEqual suppresses model_select AND the SDK doesn't pass model.
         const eventModel = event.model;
         let isAnthropic;
-        if (eventModel?.api) {
-            // Preferred path: gate on wire protocol (#4478 / ADR-012).
-            isAnthropic = isAnthropicApi(eventModel);
-        }
-        else if (eventModel?.provider) {
-            // Fallback for event shapes that carry provider but not api — only plain
-            // `anthropic` maps unambiguously without the api field. Other Anthropic
-            // transports will arrive via the modelSelectFired or model-name branch.
-            isAnthropic = eventModel.provider === "anthropic";
+        if (eventModel?.api || eventModel?.provider) {
+            // Preferred path: gate on api shape + provider allowlist. Both fields
+            // are authoritative when present — do NOT fall back to the model-name
+            // heuristic, which would misclassify copilot-served Claude as Anthropic
+            // (#444 regression) or minimax-served Claude-compat as Anthropic (#4492).
+            isAnthropic = supportsNativeWebSearch(eventModel);
         }
         else if (modelSelectFired) {
             isAnthropic = isAnthropicProvider;
         }
         else {
+            // Last resort: session-restore paths where the SDK doesn't pass model.
+            // The model-name prefix is best-effort and assumes direct Anthropic.
             const modelName = typeof payload.model === "string" ? payload.model : "";
             isAnthropic = modelName.startsWith("claude-");
         }

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

@@ -0,0 +1,12 @@
+// GSD-2 — Shared cmux event channel contracts
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+/**
+ * Neutral event channel module for gsd<->cmux IPC.
+ * Both gsd and cmux import from here — neither imports the other directly.
+ * Per ADR-006 Phase 0: event-based decoupling.
+ */
+export const CMUX_CHANNELS = {
+    SIDEBAR: "cmux:sidebar",
+    LOG: "cmux:log",
+    LIFECYCLE: "cmux:lifecycle",
+};

package/dist/resources/extensions/shared/rtk-session-stats.js

@@ -1,7 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { gsdRoot } from "../gsd/paths.js";
 import { formatTokenCount } from "./format-utils.js";
 import { buildRtkEnv, isRtkEnabled, resolveRtkBinaryPath } from "./rtk.js";
 const SESSION_BASELINES_FILE = "rtk-session-baselines.json";
@@ -10,7 +9,7 @@ const CURRENT_SUMMARY_TIMEOUT_MS = 5_000;
 const MAX_BASELINE_SESSIONS = 200;
 let cachedSummary = null;
 function getRuntimeDir(basePath) {
-    return join(gsdRoot(basePath), "runtime");
+    return join(basePath, ".gsd", "runtime");
 }
 function getBaselinesPath(basePath) {
     return join(getRuntimeDir(basePath), SESSION_BASELINES_FILE);

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

@@ -0,0 +1,190 @@
+---
+name: api-design
+description: Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
+---
+
+<objective>
+Shape an HTTP or GraphQL API so callers get predictable, evolvable, and honest semantics. The deliverable is a concrete endpoint/schema sketch with: URL or operation names, method/verb, request shape, response shape, error shape, auth model, pagination strategy, and versioning stance. Optimize for "clients that exist in 2 years" over "client that's easy to write today".
+</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.
+
+Invocation points:
+- Adding a new public API endpoint
+- Redesigning an internal API boundary between services
+- Code review of a PR that introduces HTTP handlers
+- A slice whose acceptance criteria include "the API works"
+- A GraphQL schema change
+</context>
+
+<core_principle>
+**CALLERS OUTLIVE YOUR ASSUMPTIONS.** An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller.
+
+**HONEST STATUS CODES.** 200 OK with `{"error": "not found"}` is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them.
+
+**PAGINATION IS NON-OPTIONAL.** Any list endpoint that doesn't paginate will eventually get a request for "all records" that kills your database.
+</core_principle>
+
+<process>
+
+## Step 1: Gather the contract
+
+Answer, or ask (one round, 1–3 questions):
+
+1. **Who are the callers?** Internal service / mobile app / public third-party / same-repo frontend.
+2. **What's the versioning stance?** None / URL-path (`/v1/`) / header-based / GraphQL schema evolution.
+3. **Auth model?** Public / API key / OAuth / session cookie / mTLS / none-but-internal-only.
+4. **Idempotency expectation?** Is a retry safe? Required?
+5. **Consistency model?** Read-your-writes, eventual, serializable?
+
+## Step 2: Resource and operation naming
+
+### REST
+
+- Nouns not verbs in URLs: `POST /users`, not `POST /createUser`.
+- Plural resources: `/users/42`, not `/user/42`.
+- Nested only when the relationship is hierarchical and the child has no independent identity: `/users/42/sessions/3`. Otherwise flat: `/sessions/3?userId=42`.
+- Use subresources for actions that don't fit CRUD: `POST /users/42:deactivate` (colon syntax) or `POST /users/42/actions/deactivate`.
+
+### GraphQL
+
+- Queries are nouns; mutations are verbs: `user(id)`, `createUser(input)`, `deactivateUser(id)`.
+- Group related mutations under an input type: `createUser(input: CreateUserInput!)`.
+- Return the affected object plus any derived/computed fields from mutations — lets clients avoid a refetch.
+
+## Step 3: Methods and status codes
+
+### REST
+
+| Method | Intent | Idempotent? | Default success |
+|---|---|---|---|
+| GET | Read | Yes | 200, or 304 if conditional |
+| POST | Create or non-idempotent action | No | 201 with `Location` on create, 200 on action |
+| PUT | Replace (full-object) | Yes | 200 with body, or 204 |
+| PATCH | Partial update | No (usually) | 200 with body |
+| DELETE | Remove | Yes | 204 |
+
+Errors:
+- 400: caller screwed up the request shape
+- 401: no/invalid auth
+- 403: authed but not allowed
+- 404: resource doesn't exist
+- 409: conflict (version mismatch, unique constraint)
+- 410: gone (vs 404 when the resource previously existed and you want to signal that)
+- 422: validation failed
+- 429: rate-limited — include `Retry-After`
+- 500: genuinely unexpected server error
+- 503: service down or overloaded — include `Retry-After`
+
+Never 200-with-error-body. Never 500 for a 4xx cause.
+
+### GraphQL
+
+- Top-level errors (`errors[]`) for transport-level failures. Domain errors (validation, not-found, forbidden) go in the typed return — use a union or result type.
+- Partial results are expected; design the schema so `null` on a field is meaningful, not a signal of generic failure.
+
+## Step 4: Pagination
+
+- **Cursor-based by default.** Opaque cursor string, `limit`, return `nextCursor` when more exists. Scales, stable under writes.
+- **Offset-based only when:** dataset is small, user needs jump-to-page semantics (admin tables), and you're willing to accept stability drift.
+- **Never "return everything"** as default. Put a hard upper bound on `limit` (e.g., 200).
+- GraphQL: use Relay-style connections (`edges`, `pageInfo`) if the ecosystem expects it; otherwise a simpler `{items, nextCursor}` is fine.
+
+## Step 5: Error shape
+
+Standardize one shape and use it everywhere. Example REST:
+
+```json
+{
+  "error": {
+    "code": "user_not_found",
+    "message": "No user with id 42",
+    "details": { "userId": 42 },
+    "requestId": "req_abc123"
+  }
+}
+```
+
+- `code` is machine-readable; stable; documented.
+- `message` is human-readable; can change.
+- `details` carries structured context.
+- `requestId` lets callers report bugs.
+
+Errors don't leak stack traces, file paths, or internal queries.
+
+## Step 6: Idempotency, caching, concurrency
+
+- **Idempotency keys** for POST operations that mustn't double-execute on retry. Caller passes `Idempotency-Key: <uuid>`; server dedupes for a window.
+- **ETags** for GET + conditional updates (`If-Match` on PUT/PATCH).
+- **Cache-Control** on GETs that are safely cacheable.
+- **Optimistic concurrency:** when multiple writers collide, 409 with the current state. Don't silently clobber.
+
+## Step 7: Versioning and evolution
+
+- **Additive changes are free:** new optional fields, new endpoints, new optional query params.
+- **Breaking changes need a plan:** path-versioned (`/v2/`), sunset headers on `/v1/`, deprecation window communicated. Or, for GraphQL, `@deprecated` on fields with a migration note.
+- **Document the contract:** OpenAPI/GraphQL SDL. Keep it in the repo. Make it part of the PR that introduces the change.
+
+## Step 8: Review or write it up
+
+If this is a review, produce findings in the same shape as `security-review` / `review` — file:line, category, recommendation.
+
+If this is a new design, produce:
+
+```markdown
+## <API name>
+
+### Scope
+<what the API is for, who calls it>
+
+### Endpoints / Operations
+- `POST /users` — create user. Request: `{email, name}`. Response 201: `{id, email, name, createdAt}` + `Location: /users/<id>`. Errors: 409 email taken, 422 invalid.
+- ...
+
+### Auth
+<model + where to put the credential>
+
+### Pagination
+<cursor shape, max limit>
+
+### Error shape
+<one canonical shape>
+
+### Idempotency / concurrency
+<rules>
+
+### Versioning
+<stance + how breaking changes will be handled>
+
+### OpenAPI / SDL
+<link or inline>
+```
+
+Append architectural decisions to `.gsd/DECISIONS.md`.
+
+</process>
+
+<anti_patterns>
+
+- **200 OK with `{"error": "..."}`.** Lies to caches, proxies, retry libraries.
+- **Unbounded list endpoints.** `GET /users` without a `limit` cap will bite you.
+- **Offset pagination at scale.** Drifts under writes; slow at high offsets.
+- **Free-form error messages with no code.** Machine callers can't branch on prose.
+- **Breaking changes in-place.** Callers break; versioning exists for a reason.
+- **Ignoring idempotency on retriable POSTs.** Double-charges, duplicate records.
+- **Auth checks at the handler only, not the service layer.** Defense in depth.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every endpoint/operation has named request, response, and error shapes.
+- [ ] Status codes match HTTP semantics — no 200-with-error.
+- [ ] List endpoints paginate; max limit is documented.
+- [ ] A single error shape is used everywhere, with a machine-readable code.
+- [ ] Versioning stance is stated — even if the answer is "additive only for now."
+- [ ] OpenAPI/SDL reflects the design and lives in the repo.
+- [ ] Decisions appear in `.gsd/DECISIONS.md`.
+
+</success_criteria>