gsd-pi 2.50.0 → 2.51.0-dev.859cedb

package/README.md

@@ -19,6 +19,8 @@ One command. Walk away. Come back to a built project with clean git history.
 
 <pre><code>npm install -g gsd-pi@latest</code></pre>
 
+> GSD now provisions a managed [RTK](https://github.com/rtk-ai/rtk) binary on supported macOS, Linux, and Windows installs to compress shell-command output in `bash`, `async_bash`, `bg_shell`, and verification flows. GSD forces `RTK_TELEMETRY_DISABLED=1` for all managed invocations. Set `GSD_RTK_DISABLED=1` to disable the integration.
+
 > **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
 
 </div>
@@ -519,7 +521,7 @@ An auto-generated `index.html` shows all reports with progression metrics across
 
 ### Preferences
 
-GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project). Manage with `/gsd prefs`.
+GSD preferences live in `~/.gsd/PREFERENCES.md` (global) or `.gsd/PREFERENCES.md` (project). Manage with `/gsd prefs`.
 
 ```yaml
 ---
@@ -670,7 +672,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 
 ### Unique Milestone Names
 
-Create or amend your `.gsd/preferences.md` file within the repo to include `unique_milestone_ids: true` e.g.
+Create or amend your `.gsd/PREFERENCES.md` file within the repo to include `unique_milestone_ids: true` e.g.
 
 ```markdown
 ---
@@ -679,7 +681,7 @@ unique_milestone_ids: true
 ---
 ```
 
-With the above `.gitignore` set up, the `.gsd/preferences.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
+With the above `.gitignore` set up, the `.gsd/PREFERENCES.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
 
 Milestone names will now be generated with a 6 char random string appended e.g. instead of `M001` you'll get something like `M001-ush8s3`
 
@@ -687,7 +689,7 @@ Milestone names will now be generated with a 6 char random string appended e.g.
 
 1. Ensure you are not in the middle of any milestones (clean state)
 2. Update the `.gsd/` related entries in your `.gitignore` to follow the `Suggested .gitignore setup` section under `Working in teams` (ensure you are no longer blanket ignoring the whole `.gsd/` directory)
-3. Update your `.gsd/preferences.md` file within the repo as per section `Unique Milestone Names`
+3. Update your `.gsd/PREFERENCES.md` file within the repo as per section `Unique Milestone Names`
 4. If you want to update all your existing milestones use this prompt in GSD: `I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .gsd file contents, file names and directory names. Validate your work once done to ensure referential integrity.`
 5. Commit to git
 

package/dist/cli.js

@@ -14,6 +14,8 @@ import { parseCliArgs as parseWebCliArgs, runWebCliBranch, migrateLegacyFlatSess
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
+import { bootstrapRtk, GSD_RTK_DISABLED_ENV } from './rtk.js';
+import { loadEffectiveGSDPreferences } from './resources/extensions/gsd/preferences.js';
 // ---------------------------------------------------------------------------
 // V8 compile cache — Node 22+ can cache compiled bytecode across runs,
 // eliminating repeated parse/compile overhead for unchanged modules.
@@ -114,6 +116,26 @@ if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listMode
     process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
     process.exit(1);
 }
+async function ensureRtkBootstrap() {
+    if (ensureRtkBootstrap._done)
+        return;
+    // RTK is opt-in via experimental.rtk preference. Default: disabled.
+    // Honor GSD_RTK_DISABLED if already explicitly set in the environment
+    // (env var takes precedence over preferences for manual override).
+    if (!process.env[GSD_RTK_DISABLED_ENV]) {
+        const prefs = loadEffectiveGSDPreferences();
+        const rtkEnabled = prefs?.preferences.experimental?.rtk === true;
+        if (!rtkEnabled) {
+            process.env[GSD_RTK_DISABLED_ENV] = "1";
+        }
+    }
+    const rtkStatus = await bootstrapRtk();
+    ensureRtkBootstrap._done = true;
+    markStartup('bootstrapRtk');
+    if (!rtkStatus.available && rtkStatus.supported && rtkStatus.enabled && rtkStatus.reason) {
+        process.stderr.write(`[gsd] Warning: RTK unavailable — continuing without shell-command compression (${rtkStatus.reason}).\n`);
+    }
+}
 // `gsd <subcommand> --help` — show subcommand-specific help
 const subcommand = cliFlags.messages[0];
 if (subcommand && process.argv.includes('--help')) {
@@ -161,6 +183,7 @@ if (cliFlags.messages[0] === 'web' && cliFlags.messages[1] === 'stop') {
 }
 // `gsd --web [path]` or `gsd web [start] [path]` — launch browser-only web mode
 if (cliFlags.web || (cliFlags.messages[0] === 'web' && cliFlags.messages[1] !== 'stop')) {
+    await ensureRtkBootstrap();
     const webFlags = parseWebCliArgs(process.argv);
     const webBranch = await runWebCliBranch(webFlags, {
         stderr: process.stderr,
@@ -220,6 +243,7 @@ if (cliFlags.messages[0] === 'sessions') {
 }
 // `gsd headless` — run auto-mode without TUI
 if (cliFlags.messages[0] === 'headless') {
+    await ensureRtkBootstrap();
     const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
     await runHeadless(parseHeadlessArgs(process.argv));
     process.exit(0);
@@ -348,6 +372,7 @@ if (!settingsManager.getCollapseChangelog()) {
 // Print / subagent mode — single-shot execution, no TTY required
 // ---------------------------------------------------------------------------
 if (isPrintMode) {
+    await ensureRtkBootstrap();
     const sessionManager = cliFlags.noSession
         ? SessionManager.inMemory()
         : SessionManager.create(process.cwd());
@@ -465,6 +490,7 @@ if (!cliFlags.worktree && !isPrintMode) {
 // ---------------------------------------------------------------------------
 // Interactive mode — normal TTY session
 // ---------------------------------------------------------------------------
+await ensureRtkBootstrap();
 // Per-directory session storage — same encoding as the upstream SDK so that
 // /resume only shows sessions from the current working directory.
 const cwd = process.cwd();

package/dist/headless-events.d.ts

@@ -3,7 +3,25 @@
  *
  * Detects terminal notifications, blocked notifications, milestone-ready signals,
  * and classifies commands as quick (single-turn) vs long-running.
+ *
+ * Also defines exit code constants and the status→exit-code mapping function.
+ */
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_BLOCKED = 10;
+export declare const EXIT_CANCELLED = 11;
+/**
+ * Map a headless session status string to its standardized exit code.
+ *
+ *   success   → 0
+ *   error     → 1
+ *   timeout   → 1
+ *   blocked   → 10
+ *   cancelled → 11
+ *
+ * Unknown statuses default to EXIT_ERROR (1).
  */
+export declare function mapStatusToExitCode(status: string): number;
 /**
  * Detect genuine auto-mode termination notifications.
  *

package/dist/headless-events.js

@@ -3,7 +3,43 @@
  *
  * Detects terminal notifications, blocked notifications, milestone-ready signals,
  * and classifies commands as quick (single-turn) vs long-running.
+ *
+ * Also defines exit code constants and the status→exit-code mapping function.
+ */
+// ---------------------------------------------------------------------------
+// Exit Code Constants
+// ---------------------------------------------------------------------------
+export const EXIT_SUCCESS = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_BLOCKED = 10;
+export const EXIT_CANCELLED = 11;
+/**
+ * Map a headless session status string to its standardized exit code.
+ *
+ *   success   → 0
+ *   error     → 1
+ *   timeout   → 1
+ *   blocked   → 10
+ *   cancelled → 11
+ *
+ * Unknown statuses default to EXIT_ERROR (1).
  */
+export function mapStatusToExitCode(status) {
+    switch (status) {
+        case 'success':
+        case 'complete':
+            return EXIT_SUCCESS;
+        case 'error':
+        case 'timeout':
+            return EXIT_ERROR;
+        case 'blocked':
+            return EXIT_BLOCKED;
+        case 'cancelled':
+            return EXIT_CANCELLED;
+        default:
+            return EXIT_ERROR;
+    }
+}
 // ---------------------------------------------------------------------------
 // Completion Detection
 // ---------------------------------------------------------------------------

package/dist/headless-types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Headless Types — shared types for the headless orchestrator surface.
+ *
+ * Contains the structured result type emitted in --output-format json mode
+ * and the output format discriminator.
+ */
+export type OutputFormat = 'text' | 'json' | 'stream-json';
+export declare const VALID_OUTPUT_FORMATS: ReadonlySet<string>;
+export interface HeadlessJsonResult {
+    status: 'success' | 'error' | 'blocked' | 'cancelled' | 'timeout';
+    exitCode: number;
+    sessionId?: string;
+    duration: number;
+    cost: {
+        total: number;
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    };
+    toolCalls: number;
+    events: number;
+    milestone?: string;
+    phase?: string;
+    nextAction?: string;
+    artifacts?: string[];
+    commits?: string[];
+}

package/dist/headless-types.js

@@ -0,0 +1,7 @@
+/**
+ * Headless Types — shared types for the headless orchestrator surface.
+ *
+ * Contains the structured result type emitted in --output-format json mode
+ * and the output format discriminator.
+ */
+export const VALID_OUTPUT_FORMATS = new Set(['text', 'json', 'stream-json']);

package/dist/headless.d.ts

@@ -6,13 +6,16 @@
  * progress to stderr.
  *
  * Exit codes:
- *   0 — complete (command finished successfully)
- *   1 — error or timeout
- *   2 — blocked (command reported a blocker)
+ *   0  — complete (command finished successfully)
+ *   1  — error or timeout
+ *   10 — blocked (command reported a blocker)
+ *   11 — cancelled (SIGINT/SIGTERM received)
  */
+import type { OutputFormat } from './headless-types.js';
 export interface HeadlessOptions {
     timeout: number;
     json: boolean;
+    outputFormat: OutputFormat;
     model?: string;
     command: string;
     commandArgs: string[];
@@ -25,6 +28,8 @@ export interface HeadlessOptions {
     responseTimeout?: number;
     answers?: string;
     eventFilter?: Set<string>;
+    resumeSession?: string;
+    bare?: boolean;
 }
 export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
 export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -6,16 +6,18 @@
  * progress to stderr.
  *
  * Exit codes:
- *   0 — complete (command finished successfully)
- *   1 — error or timeout
- *   2 — blocked (command reported a blocker)
+ *   0  — complete (command finished successfully)
+ *   1  — error or timeout
+ *   10 — blocked (command reported a blocker)
+ *   11 — cancelled (SIGINT/SIGTERM received)
  */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolve } from 'node:path';
 import { RpcClient } from '@gsd/pi-coding-agent';
 import { loadAndValidateAnswerFile, AnswerInjector } from './headless-answers.js';
-import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, } from './headless-events.js';
+import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, EXIT_SUCCESS, EXIT_ERROR, EXIT_BLOCKED, EXIT_CANCELLED, } from './headless-events.js';
+import { VALID_OUTPUT_FORMATS } from './headless-types.js';
 import { handleExtensionUIRequest, formatProgress, startSupervisedStdinReader, } from './headless-ui.js';
 import { loadContext, bootstrapGsdProject, } from './headless-context.js';
 // ---------------------------------------------------------------------------
@@ -25,6 +27,7 @@ export function parseHeadlessArgs(argv) {
     const options = {
         timeout: 300_000,
         json: false,
+        outputFormat: 'text',
         command: 'auto',
         commandArgs: [],
     };
@@ -44,6 +47,18 @@ export function parseHeadlessArgs(argv) {
             }
             else if (arg === '--json') {
                 options.json = true;
+                options.outputFormat = 'stream-json';
+            }
+            else if (arg === '--output-format' && i + 1 < args.length) {
+                const fmt = args[++i];
+                if (!VALID_OUTPUT_FORMATS.has(fmt)) {
+                    process.stderr.write(`[headless] Error: --output-format must be one of: text, json, stream-json (got '${fmt}')\n`);
+                    process.exit(1);
+                }
+                options.outputFormat = fmt;
+                if (fmt === 'stream-json' || fmt === 'json') {
+                    options.json = true;
+                }
             }
             else if (arg === '--model' && i + 1 < args.length) {
                 // --model can also be passed from the main CLI; headless-specific takes precedence
@@ -74,10 +89,16 @@ export function parseHeadlessArgs(argv) {
             else if (arg === '--events' && i + 1 < args.length) {
                 options.eventFilter = new Set(args[++i].split(','));
                 options.json = true; // --events implies --json
+                if (options.outputFormat === 'text') {
+                    options.outputFormat = 'stream-json';
+                }
             }
             else if (arg === '--supervised') {
                 options.supervised = true;
                 options.json = true; // supervised implies json
+                if (options.outputFormat === 'text') {
+                    options.outputFormat = 'stream-json';
+                }
             }
             else if (arg === '--response-timeout' && i + 1 < args.length) {
                 options.responseTimeout = parseInt(args[++i], 10);
@@ -86,6 +107,12 @@ export function parseHeadlessArgs(argv) {
                     process.exit(1);
                 }
             }
+            else if (arg === '--resume' && i + 1 < args.length) {
+                options.resumeSession = args[++i];
+            }
+            else if (arg === '--bare') {
+                options.bare = true;
+            }
         }
         else if (!positionalStarted) {
             positionalStarted = true;
@@ -106,7 +133,7 @@ export async function runHeadless(options) {
     while (true) {
         const result = await runHeadlessOnce(options, restartCount);
         // Success or blocked — exit normally
-        if (result.exitCode === 0 || result.exitCode === 2) {
+        if (result.exitCode === EXIT_SUCCESS || result.exitCode === EXIT_BLOCKED) {
             process.exit(result.exitCode);
         }
         // Crash/error — check if we should restart
@@ -216,6 +243,10 @@ async function runHeadlessOnce(options, restartCount) {
     if (injector) {
         clientOptions.env = injector.getSecretEnvVars();
     }
+    // Propagate --bare to the child process
+    if (options.bare) {
+        clientOptions.args = [...(clientOptions.args || []), '--bare'];
+    }
     const client = new RpcClient(clientOptions);
     // Event tracking
     let totalEvents = 0;
@@ -278,7 +309,7 @@ async function runHeadlessOnce(options, restartCount) {
     const timeoutTimer = options.timeout > 0
         ? setTimeout(() => {
             process.stderr.write(`[headless] Timeout after ${options.timeout / 1000}s\n`);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
             resolveCompletion();
         }, options.timeout)
         : null;
@@ -319,7 +350,7 @@ async function runHeadlessOnce(options, restartCount) {
             if (injector && !FIRE_AND_FORGET_METHODS.has(String(eventObj.method ?? ''))) {
                 if (injector.tryHandle(eventObj, stdinWriter)) {
                     if (completed) {
-                        exitCode = blocked ? 2 : 0;
+                        exitCode = blocked ? EXIT_BLOCKED : EXIT_SUCCESS;
                         resolveCompletion();
                     }
                     return;
@@ -343,7 +374,7 @@ async function runHeadlessOnce(options, restartCount) {
             }
             // If we detected a terminal notification, resolve after responding
             if (completed) {
-                exitCode = blocked ? 2 : 0;
+                exitCode = blocked ? EXIT_BLOCKED : EXIT_SUCCESS;
                 resolveCompletion();
                 return;
             }
@@ -361,7 +392,7 @@ async function runHeadlessOnce(options, restartCount) {
     const signalHandler = () => {
         process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
         interrupted = true;
-        exitCode = 1;
+        exitCode = EXIT_CANCELLED;
         client.stop().finally(() => {
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
@@ -411,7 +442,7 @@ async function runHeadlessOnce(options, restartCount) {
         if (!completed) {
             const msg = `[headless] Child process exited unexpectedly with code ${code ?? 'null'}\n`;
             process.stderr.write(msg);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
             resolveCompletion();
         }
     });
@@ -425,14 +456,14 @@ async function runHeadlessOnce(options, restartCount) {
     }
     catch (err) {
         process.stderr.write(`[headless] Error: Failed to send prompt: ${err instanceof Error ? err.message : String(err)}\n`);
-        exitCode = 1;
+        exitCode = EXIT_ERROR;
     }
     // Wait for completion
-    if (exitCode === 0 || exitCode === 2) {
+    if (exitCode === EXIT_SUCCESS || exitCode === EXIT_BLOCKED) {
         await completionPromise;
     }
     // Auto-mode chaining: if --auto and milestone creation succeeded, send /gsd auto
-    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === 0) {
+    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === EXIT_SUCCESS) {
         if (!options.json) {
             process.stderr.write('[headless] Milestone ready — chaining into auto-mode...\n');
         }
@@ -451,9 +482,9 @@ async function runHeadlessOnce(options, restartCount) {
         }
         catch (err) {
             process.stderr.write(`[headless] Error: Failed to start auto-mode: ${err instanceof Error ? err.message : String(err)}\n`);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
         }
-        if (exitCode === 0 || exitCode === 2) {
+        if (exitCode === EXIT_SUCCESS || exitCode === EXIT_BLOCKED) {
             await autoCompletionPromise;
         }
     }
@@ -471,7 +502,7 @@ async function runHeadlessOnce(options, restartCount) {
     await client.stop();
     // Summary
     const duration = ((Date.now() - startTime) / 1000).toFixed(1);
-    const status = blocked ? 'blocked' : exitCode === 1 ? (totalEvents === 0 ? 'error' : 'timeout') : 'complete';
+    const status = blocked ? 'blocked' : exitCode === EXIT_CANCELLED ? 'cancelled' : exitCode === EXIT_ERROR ? (totalEvents === 0 ? 'error' : 'timeout') : 'complete';
     process.stderr.write(`[headless] Status: ${status}\n`);
     process.stderr.write(`[headless] Duration: ${duration}s\n`);
     process.stderr.write(`[headless] Events: ${totalEvents} total, ${toolCallCount} tool calls\n`);

package/dist/help-text.js

@@ -87,9 +87,12 @@ const SUBCOMMAND_HELP = {
         'Run /gsd commands without the TUI. Default command: auto',
         '',
         'Flags:',
-        '  --timeout N          Overall timeout in ms (default: 300000)',
-        '  --json               JSONL event stream to stdout',
-        '  --model ID           Override model',
+        '  --timeout N            Overall timeout in ms (default: 300000)',
+        '  --json                 JSONL event stream to stdout (alias for --output-format stream-json)',
+        '  --output-format <fmt>  Output format: text (default), json (structured result), stream-json (JSONL events)',
+        '  --bare                 Minimal context: skip CLAUDE.md, AGENTS.md, user settings, user skills',
+        '  --resume <id>          Resume a prior headless session by ID',
+        '  --model ID             Override model',
         '  --supervised           Forward interactive UI requests to orchestrator via stdout/stdin',
         '  --response-timeout N   Timeout (ms) for orchestrator response (default: 30000)',
         '  --answers <path>       Pre-supply answers and secrets (JSON file)',
@@ -108,11 +111,19 @@ const SUBCOMMAND_HELP = {
         '  --auto               Start auto-mode after milestone creation',
         '  --verbose            Show tool calls in progress output',
         '',
+        'Output formats:',
+        '  text         Human-readable progress on stderr (default)',
+        '  json         Collect events silently, emit structured HeadlessJsonResult on stdout at exit',
+        '  stream-json  Stream JSONL events to stdout in real time (same as --json)',
+        '',
         'Examples:',
         '  gsd headless                                    Run /gsd auto',
         '  gsd headless next                               Run one unit',
-        '  gsd headless --json status                      Machine-readable status',
+        '  gsd headless --output-format json auto           Structured JSON result on stdout',
+        '  gsd headless --json status                      Machine-readable JSONL stream',
         '  gsd headless --timeout 60000                    With 1-minute timeout',
+        '  gsd headless --bare auto                        Minimal context (CI/ecosystem use)',
+        '  gsd headless --resume abc123 auto               Resume a prior session',
         '  gsd headless new-milestone --context spec.md    Create milestone from file',
         '  cat spec.md | gsd headless new-milestone --context -   From stdin',
         '  gsd headless new-milestone --context spec.md --auto    Create + auto-execute',
@@ -121,7 +132,7 @@ const SUBCOMMAND_HELP = {
         '  gsd headless --events agent_end,extension_ui_request auto   Filtered event stream',
         '  gsd headless query                              Instant JSON state snapshot',
         '',
-        'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
+        'Exit codes: 0 = success, 1 = error/timeout, 10 = blocked, 11 = cancelled',
     ].join('\n'),
 };
 // Alias: `gsd wt --help` → same as `gsd worktree --help`

package/dist/loader.js

@@ -61,6 +61,7 @@ if (firstArg === '--help' || firstArg === '-h') {
     }
 }
 import { agentDir, appRoot } from './app-paths.js';
+import { applyRtkProcessEnv } from './rtk.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled } from './extension-registry.js';
@@ -92,6 +93,9 @@ if (!existsSync(appRoot)) {
 }
 // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.gsd/agent/
 process.env.GSD_CODING_AGENT_DIR = agentDir;
+// RTK environment — make ~/.gsd/agent/bin visible to all child-process paths,
+// not just the bash tool, and force-disable RTK telemetry for GSD-managed use.
+applyRtkProcessEnv(process.env);
 // NODE_PATH — make gsd's own node_modules available to extensions loaded via jiti.
 // Without this, extensions (e.g. browser-tools) can't resolve dependencies like
 // `playwright` because jiti resolves modules from pi-coding-agent's location, not gsd's.

package/dist/onboarding.js

@@ -568,10 +568,11 @@ async function runToolKeysStep(p, pc, authStorage) {
 }
 // ─── Remote Questions Step ────────────────────────────────────────────────────
 async function runRemoteQuestionsStep(p, pc, authStorage) {
-    // Check existing config
-    const hasDiscord = authStorage.has('discord_bot') && !!authStorage.get('discord_bot')?.key;
-    const hasSlack = authStorage.has('slack_bot') && !!authStorage.get('slack_bot')?.key;
-    const hasTelegram = authStorage.has('telegram_bot') && !!authStorage.get('telegram_bot')?.key;
+    // Check existing config — use getCredentialsForProvider to skip empty-key entries
+    const hasValidKey = (provider) => authStorage.getCredentialsForProvider(provider).some((c) => c.type === 'api_key' && c.key);
+    const hasDiscord = hasValidKey('discord_bot');
+    const hasSlack = hasValidKey('slack_bot');
+    const hasTelegram = hasValidKey('telegram_bot');
     const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : hasTelegram ? 'Telegram' : null;
     const options = [];
     if (existingChannel) {

package/dist/remote-questions-config.js

@@ -14,7 +14,7 @@ import { appRoot } from "./app-paths.js";
 // boundary — this file is compiled by tsc, but preferences.ts is loaded
 // via jiti at runtime. Importing it as .js fails because no .js exists
 // in dist/. See #592, #1110.
-const GLOBAL_PREFERENCES_PATH = join(appRoot, "preferences.md");
+const GLOBAL_PREFERENCES_PATH = join(appRoot, "PREFERENCES.md");
 export function saveRemoteQuestionsConfig(channel, channelId) {
     const prefsPath = GLOBAL_PREFERENCES_PATH;
     const block = [

package/dist/resource-loader.d.ts

@@ -8,9 +8,12 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  *
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
- * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
  * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
  *
+ * Skills are NOT synced here. They are installed by the user via the
+ * skills.sh CLI (`npx skills add <repo>`) into ~/.agents/skills/ — the
+ * industry-standard Agent Skills ecosystem directory.
+ *
  * Skips the copy when the managed-resources.json version matches the current
  * GSD version, avoiding ~128ms of synchronous cpSync on every startup.
  * After `npm update -g @glittercowboy/gsd`, versions will differ and the