@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/README.md

@@ -27,13 +27,19 @@ See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Rele
 
 ## Latest Release Highlights
 
-- **Claude Opus 4.8 support** — Add the latest Claude model option to the generated model catalog.
-- **Better `/gsd` observability** — Add `/gsd usage` and `/gsd context` commands for inspecting session usage and context state.
-- **Sharper skill scoping** — Scope the skill catalog per unit, trim duplicate prompt surfaces, and apply unit-context manifest policy during auto-mode dispatch.
-- **Improved guided installs** — Redesign the `npx @opengsd/gsd-pi@latest` flow so first-time and scripted installs are clearer and more reliable.
-- **Smoother auto-mode progress** — Improve requirements backlog handling, completion summaries, quick branch inference, cleanup logic, and milestone closeout behavior.
-- **Cloud MCP gateway runtime** — Add the local cloud MCP gateway runtime with persisted auth state.
-- **More reliable installs** — Resolve native engine packages to the matching release version across npm installs and Docker images.
+<!-- release-highlights:start -->
+Latest release: **v1.3.0**
+
+- **update:** Reconcile stale PATH gsd-browser binary after install.
+- **gsd:** Route UAT sign-off and worktree-degradation blockers through the guidance catalog.
+- **gsd:** Fix shell-tool selection — uncapped sync bash, interruptible await, graceful kills.
+- **browser-tools:** Proven engine resolution — gsd-browser primary for web apps (ADR-037).
+- **gsd:** Add the Unit Closeout module with the Interactive Closeout adapter (ADR-032).
+- **gsd:** Tool Surface Readiness gate — verify live tool surface at SDK init before the first model turn.
+- **claude-code-cli:** Expose Claude Fable 5 as an Opus-tier model.
+- **pi-ai:** Add Claude Fable 5 with Opus-tier thinking.
+
+<!-- release-highlights:end -->
 
 ## Status
 

package/dist/cli-model-override.d.ts

@@ -0,0 +1,15 @@
+import type { ModelRegistry as ModelRegistryInstance } from '@gsd/pi-coding-agent';
+/**
+ * Apply the --model CLI flag override to the active session.
+ * Searches available models by exact id or provider/id pattern and warns
+ * on stderr when the requested model is not found in the registry.
+ *
+ * The setModel call is intentionally fire-and-forget: provider readiness
+ * checks run later in startup so --model does not block session creation.
+ */
+export declare function applyModelOverride(session: {
+    setModel(model: {
+        provider: string;
+        id: string;
+    }): unknown | Promise<unknown>;
+}, modelRegistry: ModelRegistryInstance, modelFlag: string | undefined): void;

package/dist/cli-model-override.js

@@ -0,0 +1,21 @@
+/**
+ * Apply the --model CLI flag override to the active session.
+ * Searches available models by exact id or provider/id pattern and warns
+ * on stderr when the requested model is not found in the registry.
+ *
+ * The setModel call is intentionally fire-and-forget: provider readiness
+ * checks run later in startup so --model does not block session creation.
+ */
+export function applyModelOverride(session, modelRegistry, modelFlag) {
+    if (!modelFlag)
+        return;
+    const available = modelRegistry.getAvailable();
+    const match = available.find((m) => m.id === modelFlag) ||
+        available.find((m) => `${m.provider}/${m.id}` === modelFlag);
+    if (match) {
+        void session.setModel(match);
+    }
+    else {
+        process.stderr.write(`[gsd] Warning: Model "${modelFlag}" not found. Using configured default.\n`);
+    }
+}

package/dist/cli-style.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Terminal presentation helpers for CLI-side notices on stderr — warnings,
+ * hints, and names. Pairs with the extension-side glyph set in
+ * resources/extensions/shared/ui.ts. Adopt incrementally: banner-shaped CLI
+ * surfaces (worktree banners today; update checks et al. as they're touched)
+ * should render through these instead of ad-hoc chalk.
+ */
+/** Dim "[gsd] " line tag that prefixes CLI banner lines. */
+export declare function gsdTag(): string;
+/** A yellow warning fragment. */
+export declare function warn(text: string): string;
+/** A dim "what to do next" hint fragment. */
+export declare function hint(text: string): string;
+/** A cyan user-supplied name (worktree, branch, file). */
+export declare function name(text: string): string;
+/** One banner line: tagged warning followed by a tagged hint line. */
+export declare function bannerLines(warning: string, hintText: string): string;

package/dist/cli-style.js

@@ -0,0 +1,28 @@
+/**
+ * Terminal presentation helpers for CLI-side notices on stderr — warnings,
+ * hints, and names. Pairs with the extension-side glyph set in
+ * resources/extensions/shared/ui.ts. Adopt incrementally: banner-shaped CLI
+ * surfaces (worktree banners today; update checks et al. as they're touched)
+ * should render through these instead of ad-hoc chalk.
+ */
+import chalk from 'chalk';
+/** Dim "[gsd] " line tag that prefixes CLI banner lines. */
+export function gsdTag() {
+    return chalk.dim('[gsd] ');
+}
+/** A yellow warning fragment. */
+export function warn(text) {
+    return chalk.yellow(text);
+}
+/** A dim "what to do next" hint fragment. */
+export function hint(text) {
+    return chalk.dim(text);
+}
+/** A cyan user-supplied name (worktree, branch, file). */
+export function name(text) {
+    return chalk.cyan(text);
+}
+/** One banner line: tagged warning followed by a tagged hint line. */
+export function bannerLines(warning, hintText) {
+    return gsdTag() + warning + '\n' + gsdTag() + hint(hintText) + '\n\n';
+}

package/dist/cli-web-branch.d.ts

@@ -20,6 +20,8 @@ export interface CliFlags {
     webPort?: number;
     /** Additional allowed origins for CORS: `--allowed-origins http://192.168.1.10:8080` */
     webAllowedOrigins?: string[];
+    /** Disable the web launcher's bearer token gate: `--no-auth` */
+    webNoAuth?: boolean;
     /** Set by `gsd sessions` when the user picks a specific session to resume */
     _selectedSessionPath?: string;
 }

package/dist/cli-web-branch.js

@@ -52,6 +52,9 @@ export function parseCliArgs(argv) {
             const origins = args[++i].split(',').map(o => o.trim()).filter(Boolean);
             flags.webAllowedOrigins = (flags.webAllowedOrigins ?? []).concat(origins);
         }
+        else if (arg === '--no-auth') {
+            flags.webNoAuth = true;
+        }
         else if (arg === '--model' && i + 1 < args.length) {
             flags.model = args[++i];
         }
@@ -232,14 +235,18 @@ export async function runWebCliBranch(flags, deps = {}) {
     const agentDir = deps.agentDir ?? defaultAgentDir;
     const projectSessionsDir = getProjectSessionsDir(currentCwd, baseSessionsDir);
     migrateLegacyFlatSessions(baseSessionsDir, projectSessionsDir);
-    const status = await (deps.runWebMode ?? launchWebMode)({
+    const launchOptions = {
         cwd: currentCwd,
         projectSessionsDir,
         agentDir,
         host: flags.webHost,
         port: flags.webPort,
         allowedOrigins: flags.webAllowedOrigins,
-    });
+    };
+    if (flags.webNoAuth !== undefined) {
+        launchOptions.noAuth = flags.webNoAuth;
+    }
+    const status = await (deps.runWebMode ?? launchWebMode)(launchOptions);
     if (!status.ok) {
         emitWebModeFailure(stderr, status);
     }

package/dist/cli.js

@@ -13,7 +13,8 @@ import { shouldRedirectAutoToHeadless } from './cli-auto-routing.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
-import { migrateAnthropicDefaultToClaudeCode } from './provider-migrations.js';
+import { migrateAnthropicDefaultToClaudeCode, migrateGeminiCliDefaultToAntigravity } from './provider-migrations.js';
+import { applyModelOverride } from './cli-model-override.js';
 import { buildHeadlessAutoArgs, parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
@@ -122,24 +123,6 @@ async function reapplyValidatedModelOnFallback(session, modelRegistry, settingsM
         // Provider not ready — leave session on its current model
     }
 }
-/**
- * Apply the --model CLI flag override to the active session.
- * Searches available models by exact id or provider/id pattern and warns
- * on stderr when the requested model is not found in the registry.
- */
-function applyModelOverride(session, modelRegistry, modelFlag) {
-    if (!modelFlag)
-        return;
-    const available = modelRegistry.getAvailable();
-    const match = available.find((m) => m.id === modelFlag) ||
-        available.find((m) => `${m.provider}/${m.id}` === modelFlag);
-    if (match) {
-        void session.setModel(match);
-    }
-    else {
-        process.stderr.write(`[gsd] Warning: Model "${modelFlag}" not found. Using configured default.\n`);
-    }
-}
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
 // `gsd [subcommand] --help` / `-h` — print help before any subcommand runs.
@@ -211,6 +194,14 @@ if (shouldBypassManagedResourceMismatchGate(cliFlags.messages[0])) {
     process.exit(0);
 }
 // ---------------------------------------------------------------------------
+// Hermes integration subcommand — `gsd hermes install`
+// ---------------------------------------------------------------------------
+if (cliFlags.messages[0] === 'hermes') {
+    const { runHermesIntegrationCommand } = await import('./hermes-integration-install.js');
+    const exitCode = await runHermesIntegrationCommand(process.argv);
+    process.exit(exitCode);
+}
+// ---------------------------------------------------------------------------
 // Graph subcommand — `gsd graph build|status|query|diff`
 // ---------------------------------------------------------------------------
 if (cliFlags.messages[0] === 'graph') {
@@ -308,6 +299,8 @@ const subcommandsExemptFromEarlyTtyCheck = new Set([
     'config',
     'graph',
     'headless',
+    'hermes',
+    'read',
     'install',
     'list',
     'remove',
@@ -426,6 +419,11 @@ if (cliFlags.messages[0] === 'sessions') {
     cliFlags.continue = true;
     cliFlags._selectedSessionPath = selected.path;
 }
+// `gsd read` — JSON read seam for integrations (Hermes 6c)
+if (cliFlags.messages[0] === 'read') {
+    const { runReadCli } = await import('./read-cli.js');
+    process.exit(await runReadCli(process.argv));
+}
 // `gsd headless` — run auto-mode without TUI
 if (cliFlags.messages[0] === 'headless') {
     await ensureRtkBootstrap();
@@ -524,7 +522,7 @@ const authStorage = AuthStorage.create(authFilePath);
 markStartup('AuthStorage.create');
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
-// Resolve models.json path with fallback to ~/.pi/agent/models.json
+// Resolve models.json path
 const { resolveModelsJsonPath } = await import('./models-resolver.js');
 const modelsJsonPath = resolveModelsJsonPath();
 const modelRegistry = ModelRegistry.create(authStorage, modelsJsonPath);
@@ -629,6 +627,12 @@ if (isPrintMode) {
         settingsManager,
         modelRegistry,
     });
+    migrateGeminiCliDefaultToAntigravity({
+        authStorage,
+        isAntigravityReady: () => modelRegistry.isProviderRequestReady('google-antigravity'),
+        settingsManager,
+        modelRegistry,
+    });
     const { session, extensionsResult, modelFallbackMessage } = await createAgentSession({
         authStorage,
         modelRegistry,
@@ -733,6 +737,12 @@ migrateAnthropicDefaultToClaudeCode({
     settingsManager,
     modelRegistry,
 });
+migrateGeminiCliDefaultToAntigravity({
+    authStorage,
+    isAntigravityReady: () => modelRegistry.isProviderRequestReady('google-antigravity'),
+    settingsManager,
+    modelRegistry,
+});
 markStartup('providerMigrations');
 const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({
     authStorage,

package/dist/headless-context.js

@@ -39,6 +39,5 @@ export async function loadContext(options) {
  */
 export function bootstrapGsdProject(basePath) {
     const gsdDir = join(basePath, '.gsd');
-    mkdirSync(join(gsdDir, 'milestones'), { recursive: true });
     mkdirSync(join(gsdDir, 'runtime'), { recursive: true });
 }

package/dist/headless-events.d.ts

@@ -5,6 +5,10 @@
  * and classifies commands as quick (single-turn) vs long-running.
  *
  * Also defines exit code constants and the status→exit-code mapping function.
+ *
+ * The stop/pause notice vocabulary itself (prefixes + message classifiers)
+ * lives in the Stop Notice module — the same module the emitters format with,
+ * so wording stays in lockstep with detection.
  */
 export declare const EXIT_SUCCESS = 0;
 export declare const EXIT_ERROR = 1;
@@ -42,8 +46,6 @@ export declare function mapStatusToExitCode(status: string): number;
  *
  * Blocked detection is separate — checked via isBlockedNotification.
  */
-export declare const PAUSED_PREFIXES: string[];
-export declare const TERMINAL_PREFIXES: string[];
 export declare const IDLE_TIMEOUT_MS = 15000;
 export declare const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120000;
 export declare function canonicalHeadlessToolName(toolName: string | undefined): string;
@@ -51,7 +53,22 @@ export declare function isTerminalNotification(event: Record<string, unknown>):
 export declare function isBlockedNotification(event: Record<string, unknown>): boolean;
 export declare function isMilestoneReadyNotification(event: Record<string, unknown>): boolean;
 export declare function isInteractiveHeadlessTool(toolName: string | undefined): boolean;
-export declare function shouldArmHeadlessIdleTimeout(toolCallCount: number, interactiveToolCount: number): boolean;
+/**
+ * Decide whether to arm the headless idle-completion timer.
+ *
+ * Arms once at least one tool call has started (and no interactive tool —
+ * ask_user_questions / secure_env_collect — is still awaiting a human answer),
+ * so a multi-step command that pauses between tool calls still resolves.
+ *
+ * Also arms for *quick commands* that are handled entirely in the extension
+ * layer (e.g. `/gsd status`, `/gsd history`, `/gsd help`). These never enter
+ * the LLM agent loop, so they emit no `agent_end` / `execution_complete` and
+ * make zero tool calls. Without this branch the idle timer never arms, the
+ * completion promise never resolves, and the process exits with a spurious
+ * "cancelled" (11) code once the event loop drains. See live-regression
+ * scenario `headless status exits 0 on a seeded project`.
+ */
+export declare function shouldArmHeadlessIdleTimeout(toolCallCount: number, interactiveToolCount: number, isQuickCommand?: boolean): boolean;
 export interface HeadlessTrackedEventLike {
     type: string;
     detail?: string;

package/dist/headless-events.js

@@ -5,7 +5,13 @@
  * and classifies commands as quick (single-turn) vs long-running.
  *
  * Also defines exit code constants and the status→exit-code mapping function.
+ *
+ * The stop/pause notice vocabulary itself (prefixes + message classifiers)
+ * lives in the Stop Notice module — the same module the emitters format with,
+ * so wording stays in lockstep with detection.
  */
+import { isBlockedNoticeMessage, isManualResolutionNotice, isPauseNotice, isTerminalNotice, } from './resources/extensions/gsd/stop-notice.js';
+import { canonicalToolName } from './resources/extensions/gsd/engine-hook-contract.js';
 // ---------------------------------------------------------------------------
 // Exit Code Constants
 // ---------------------------------------------------------------------------
@@ -65,40 +71,19 @@ export function mapStatusToExitCode(status) {
  *
  * Blocked detection is separate — checked via isBlockedNotification.
  */
-export const PAUSED_PREFIXES = ['auto-mode paused', 'step-mode paused'];
-export const TERMINAL_PREFIXES = [
-    'auto-mode stopped',
-    'step-mode stopped',
-    'auto-mode complete',
-    'no active milestone',
-    'auto-mode idle',
-];
 export const IDLE_TIMEOUT_MS = 15_000;
 // new-milestone is a long-running creative task where the LLM may pause
 // between tool calls (e.g. after mkdir, before writing files). Use a
 // longer idle timeout to avoid killing the session prematurely (#808).
 export const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
 const INTERACTIVE_HEADLESS_TOOLS = new Set(['ask_user_questions', 'secure_env_collect']);
+// Delegates to the shared normalizer seam (engine-hook-contract.ts) instead of
+// a hand-rolled parser. Behavior differs from the old parser only on malformed
+// MCP names: `mcp____tool` (empty server) and `mcp__server__` (empty tool) are
+// now returned unchanged rather than partially stripped — neither can match a
+// real tool name, so detection behavior is unaffected.
 export function canonicalHeadlessToolName(toolName) {
-    const name = String(toolName ?? '');
-    if (!name.startsWith('mcp__'))
-        return name;
-    const toolSeparator = name.indexOf('__', 'mcp__'.length);
-    return toolSeparator >= 0 ? name.slice(toolSeparator + 2) : name;
-}
-function isManualResolutionNotification(message) {
-    return (message.includes('resolve manually and re-run /gsd auto') ||
-        message.includes('resolve conflicts manually and run /gsd auto to resume') ||
-        message.includes('resolve and run /gsd auto to resume'));
-}
-function isNonBlockingPauseNotification(message) {
-    return message.includes('idempotent advance: unit already active');
-}
-function isPauseNotification(message) {
-    return PAUSED_PREFIXES.some((prefix) => message.startsWith(prefix));
-}
-function isPauseNotificationRequiringIntervention(message) {
-    return isPauseNotification(message) && !isNonBlockingPauseNotification(message);
+    return canonicalToolName(String(toolName ?? ''));
 }
 function getCommandBlockContent(event) {
     if (event.type !== 'message_start' && event.type !== 'message_end')
@@ -122,20 +107,15 @@ export function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
     const message = String(event.message ?? '').toLowerCase();
-    return (TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix)) ||
-        isPauseNotification(message) ||
-        isManualResolutionNotification(message));
+    return isTerminalNotice(message) || isPauseNotice(message) || isManualResolutionNotice(message);
 }
 export function isBlockedNotification(event) {
     if (isBlockingCommandBlock(event))
         return true;
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
-    const message = String(event.message ?? '').toLowerCase();
     // Recoverable pauses need operator intervention in headless mode.
-    return (message.includes('blocked:') ||
-        isPauseNotificationRequiringIntervention(message) ||
-        isManualResolutionNotification(message));
+    return isBlockedNoticeMessage(String(event.message ?? '').toLowerCase());
 }
 export function isMilestoneReadyNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
@@ -145,8 +125,25 @@ export function isMilestoneReadyNotification(event) {
 export function isInteractiveHeadlessTool(toolName) {
     return INTERACTIVE_HEADLESS_TOOLS.has(canonicalHeadlessToolName(toolName));
 }
-export function shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCount) {
-    return toolCallCount > 0 && interactiveToolCount === 0;
+/**
+ * Decide whether to arm the headless idle-completion timer.
+ *
+ * Arms once at least one tool call has started (and no interactive tool —
+ * ask_user_questions / secure_env_collect — is still awaiting a human answer),
+ * so a multi-step command that pauses between tool calls still resolves.
+ *
+ * Also arms for *quick commands* that are handled entirely in the extension
+ * layer (e.g. `/gsd status`, `/gsd history`, `/gsd help`). These never enter
+ * the LLM agent loop, so they emit no `agent_end` / `execution_complete` and
+ * make zero tool calls. Without this branch the idle timer never arms, the
+ * completion promise never resolves, and the process exits with a spurious
+ * "cancelled" (11) code once the event loop drains. See live-regression
+ * scenario `headless status exits 0 on a seeded project`.
+ */
+export function shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCount, isQuickCommand = false) {
+    if (interactiveToolCount > 0)
+        return false;
+    return toolCallCount > 0 || isQuickCommand;
 }
 function hasCancelledDetail(detail) {
     return /\bcancelled\b/i.test(String(detail ?? ''));

package/dist/headless.js

@@ -434,6 +434,13 @@ async function runHeadlessOnce(options, restartCount) {
     });
     // Idle timeout — fallback completion detection
     let idleTimer = null;
+    // Quick commands (status, history, help, …) are short extension-layer
+    // operations that never enter the LLM agent loop, so they emit no
+    // execution_complete and make no tool calls. The idle timer is what
+    // resolves them; without arming it for zero-tool quick commands the run
+    // hangs and exits with a spurious "cancelled" (11). See
+    // shouldArmHeadlessIdleTimeout.
+    const isQuickCmd = isQuickCommand(options.command, options.commandArgs);
     let effectiveIdleTimeout = isNewMilestone
         ? NEW_MILESTONE_IDLE_TIMEOUT_MS
         : isAutoMode
@@ -443,7 +450,7 @@ async function runHeadlessOnce(options, restartCount) {
         if (idleTimer)
             clearTimeout(idleTimer);
         if (effectiveIdleTimeout > 0 &&
-            shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCallIds.size)) {
+            shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCallIds.size, isQuickCmd)) {
             idleTimer = setTimeout(() => {
                 completed = true;
                 resolveCompletion();

package/dist/help-text.js

@@ -122,6 +122,34 @@ const SUBCOMMAND_HELP = {
         '  gsd graph query auth                   Find nodes related to "auth"',
         '  gsd graph diff                         Show changes since last snapshot',
     ].join('\n'),
+    hermes: [
+        'Usage: gsd hermes install [options]',
+        '',
+        'Install the bundled open-gsd-hermes plugin into Hermes Agent.',
+        '',
+        'Options:',
+        '  --hermes-home <path>    Hermes home (default: $HERMES_HOME or ~/.hermes)',
+        '  --project <path>        Default GSD project to write into gsd.yaml',
+        '  --plugin-source <path>  Override bundled integrations/hermes source',
+        '  --skip-pip             Copy plugin only; do not pip install editable package',
+        '  --skip-enable          Do not run hermes plugins enable',
+        '  --dry-run              Print intended actions without writing',
+        '',
+        'Examples:',
+        '  gsd hermes install --project ~/code/myapp',
+        '  HERMES_HOME=~/.hermes gsd hermes install --skip-enable',
+    ].join('\n'),
+    read: [
+        'Usage: gsd read <progress|roadmap|memory> --json --project <path>',
+        '',
+        'JSON read seam for external integrations (e.g. open-gsd-hermes).',
+        'Emits envelope: { integration_version, kind, projectDir, data }.',
+        '',
+        'Examples:',
+        '  gsd read progress --json --project ~/code/myapp',
+        '  gsd read roadmap --json --project ~/code/myapp --milestone M001',
+        '  gsd read memory --json --project ~/code/myapp --query auth',
+    ].join('\n'),
     headless: [
         'Usage: gsd headless [flags] [command] [args...]',
         '',
@@ -189,6 +217,11 @@ export function printHelp(version) {
     process.stdout.write('  --worktree, -w [name]    Start in an isolated worktree (auto-named if omitted)\n');
     process.stdout.write('  --model <id>             Override model (e.g. provider/model-id)\n');
     process.stdout.write('  --no-session             Disable session persistence\n');
+    process.stdout.write('  --web [path]             Start browser-only web mode\n');
+    process.stdout.write('  --host <host>            Web mode bind address\n');
+    process.stdout.write('  --port <port>            Web mode port\n');
+    process.stdout.write('  --allowed-origins <csv>  Additional allowed web origins\n');
+    process.stdout.write('  --no-auth                Disable web token auth; requires external access control\n');
     process.stdout.write('  --extension <path>       Load additional extension\n');
     process.stdout.write('  --tools <a,b,c>          Restrict available tools\n');
     process.stdout.write('  --list-models [search]   List available models and exit\n');
@@ -206,6 +239,7 @@ export function printHelp(version) {
     process.stdout.write('  auto [args]              Run auto-mode without TUI (pipeable)\n');
     process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
     process.stdout.write('  graph <subcommand>       Manage knowledge graph (build, query, status, diff)\n');
+    process.stdout.write('  hermes install           Install the Hermes Agent plugin\n');
     process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
 }
 export function printSubcommandHelp(subcommand, version) {

package/dist/hermes-integration-install.d.ts

@@ -0,0 +1,17 @@
+export interface HermesInstallOptions {
+    hermesHome: string;
+    pluginSource: string;
+    project?: string;
+    dryRun: boolean;
+    skipPip: boolean;
+    skipEnable: boolean;
+}
+export interface HermesInstallResult {
+    pluginTarget: string;
+    configPath: string;
+    actions: string[];
+    warnings: string[];
+}
+export declare function runHermesIntegrationCommand(argv: string[]): Promise<number>;
+export declare function parseHermesInstallArgs(args: string[]): HermesInstallOptions;
+export declare function installHermesPlugin(options: HermesInstallOptions): HermesInstallResult;