@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/help.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Custom help formatting for the CLI.
+ *
+ * Overrides commander's default help layout to show Commands before Options,
+ * and applies consistent conventions (short -h flag, no implicit help subcommand).
+ */
 import type { Command } from 'commander';
+/** Description of a named command group rendered as its own section in help output. */
+export interface CommandGroup {
+    /** Section heading, e.g. 'Bundle commands'. */
+    title: string;
+    /** Subcommand names (in desired display order) that belong to this group. */
+    names: readonly string[];
+}
+/**
+ * Register named groups for a parent command so its help output splits the
+ * Commands section into multiple labeled sections. Subcommands not listed in
+ * any group fall back to a plain "Commands:" section below the groups.
+ */
+export declare function registerCommandGroups(parent: Command, groups: readonly CommandGroup[]): void;
+/** Apply standardized help formatting to the root command and all subcommands. */
 export declare function applyGlobalHelpConventions(root: Command): void;
-//# sourceMappingURL=help.d.ts.map

package/dist/lib/help.js

@@ -1,3 +1,13 @@
+const commandGroupRegistry = new WeakMap();
+/**
+ * Register named groups for a parent command so its help output splits the
+ * Commands section into multiple labeled sections. Subcommands not listed in
+ * any group fall back to a plain "Commands:" section below the groups.
+ */
+export function registerCommandGroups(parent, groups) {
+    commandGroupRegistry.set(parent, groups);
+}
+/** Format help output with Commands listed before Options for better discoverability. */
 function formatHelpCommandsFirst(cmd, helper) {
     const termWidth = helper.padWidth(cmd, helper);
     const helpWidth = helper.helpWidth || 80;
@@ -24,11 +34,39 @@ function formatHelpCommandsFirst(cmd, helper) {
     if (argumentList.length > 0) {
         output = output.concat(['Arguments:', formatList(argumentList), '']);
     }
-    const commandList = helper.visibleCommands(cmd).map((subcommand) => {
-        return formatItem(helper.subcommandTerm(subcommand), helper.subcommandDescription(subcommand));
-    });
-    if (commandList.length > 0) {
-        output = output.concat(['Commands:', formatList(commandList), '']);
+    const visibleCommands = helper.visibleCommands(cmd);
+    const subcommandTermNoAlias = (sub) => {
+        // Mirror commander's default subcommandTerm but drop the |alias suffix.
+        const argList = sub.registeredArguments ?? [];
+        const args = argList
+            .map((a) => {
+            const n = a.name() + (a.variadic ? '...' : '');
+            return a.required ? `<${n}>` : `[${n}]`;
+        })
+            .join(' ');
+        return sub.name() + (sub.options.length > 0 ? ' [options]' : '') + (args ? ` ${args}` : '');
+    };
+    const renderCommand = (sub) => formatItem(subcommandTermNoAlias(sub), helper.subcommandDescription(sub));
+    const groups = commandGroupRegistry.get(cmd);
+    if (groups && groups.length > 0) {
+        const byName = new Map(visibleCommands.map((s) => [s.name(), s]));
+        const placed = new Set();
+        for (const { title, names } of groups) {
+            const subs = names
+                .map((n) => byName.get(n))
+                .filter((s) => s !== undefined);
+            if (subs.length === 0)
+                continue;
+            subs.forEach((s) => placed.add(s.name()));
+            output = output.concat([`${title}:`, formatList(subs.map(renderCommand)), '']);
+        }
+        const remaining = visibleCommands.filter((s) => !placed.has(s.name()));
+        if (remaining.length > 0) {
+            output = output.concat(['Commands:', formatList(remaining.map(renderCommand)), '']);
+        }
+    }
+    else if (visibleCommands.length > 0) {
+        output = output.concat(['Commands:', formatList(visibleCommands.map(renderCommand)), '']);
     }
     const optionList = helper.visibleOptions(cmd).map((option) => {
         return formatItem(helper.optionTerm(option), helper.optionDescription(option));
@@ -46,6 +84,7 @@ function formatHelpCommandsFirst(cmd, helper) {
     }
     return output.join('\n');
 }
+/** Recursively apply help conventions (-h flag, no help subcommand, custom formatter). */
 function applyHelpConventionsRecursive(cmd) {
     cmd
         .helpOption('-h, --help', 'Show help')
@@ -57,7 +96,7 @@ function applyHelpConventionsRecursive(cmd) {
         applyHelpConventionsRecursive(subcommand);
     }
 }
+/** Apply standardized help formatting to the root command and all subcommands. */
 export function applyGlobalHelpConventions(root) {
     applyHelpConventionsRecursive(root);
 }
-//# sourceMappingURL=help.js.map

package/dist/lib/hooks/match.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hook predicate evaluator.
+ *
+ * Evaluates the optional `matches:` block on a hook manifest entry against
+ * the runtime input passed by the agent CLI on a hook event. All declared
+ * predicates AND together — the hook fires only if every one passes.
+ *
+ * Empty/missing matches => always passes (backward compat with hooks
+ * authored before predicate support).
+ *
+ * Used at hook-fire time by either:
+ *   (a) generated hook wrappers we install alongside the script, or
+ *   (b) the script itself, by calling shouldFire() with parsed JSON input.
+ */
+import type { HookMatches } from '../types.js';
+/** Runtime context passed to a hook by the agent CLI. */
+export interface HookInput {
+    hook_event_name?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_args?: unknown;
+    cwd?: string;
+}
+/**
+ * Decide whether a hook with the given match config should fire on this input.
+ * Pure function — no side effects, no IO except git/cwd checks for predicates
+ * that explicitly require them.
+ *
+ * Returns true if the hook should fire (all declared predicates pass), false
+ * if it should be skipped.
+ */
+export declare function shouldFire(matches: HookMatches | undefined, input: HookInput): boolean;

package/dist/lib/hooks/match.js

@@ -0,0 +1,120 @@
+/**
+ * Hook predicate evaluator.
+ *
+ * Evaluates the optional `matches:` block on a hook manifest entry against
+ * the runtime input passed by the agent CLI on a hook event. All declared
+ * predicates AND together — the hook fires only if every one passes.
+ *
+ * Empty/missing matches => always passes (backward compat with hooks
+ * authored before predicate support).
+ *
+ * Used at hook-fire time by either:
+ *   (a) generated hook wrappers we install alongside the script, or
+ *   (b) the script itself, by calling shouldFire() with parsed JSON input.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+function arrayOf(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+function isGitDirty(cwd) {
+    try {
+        const out = execSync('git status --porcelain', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function findProjectRoot(start) {
+    let dir = path.resolve(start);
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Decide whether a hook with the given match config should fire on this input.
+ * Pure function — no side effects, no IO except git/cwd checks for predicates
+ * that explicitly require them.
+ *
+ * Returns true if the hook should fire (all declared predicates pass), false
+ * if it should be skipped.
+ */
+export function shouldFire(matches, input) {
+    if (!matches)
+        return true;
+    const cwd = input.cwd || process.cwd();
+    if (matches.prompt_contains !== undefined) {
+        const prompt = input.prompt ?? '';
+        if (!prompt.includes(matches.prompt_contains))
+            return false;
+    }
+    if (matches.prompt_matches !== undefined) {
+        const prompt = input.prompt ?? '';
+        let re;
+        try {
+            re = new RegExp(matches.prompt_matches);
+        }
+        catch {
+            return false;
+        }
+        if (!re.test(prompt))
+            return false;
+    }
+    if (matches.tool_name !== undefined) {
+        const allowed = arrayOf(matches.tool_name);
+        if (allowed.length > 0) {
+            if (!input.tool_name)
+                return false;
+            if (!allowed.includes(input.tool_name))
+                return false;
+        }
+    }
+    if (matches.tool_args_match !== undefined) {
+        const serialized = typeof input.tool_args === 'string'
+            ? input.tool_args
+            : JSON.stringify(input.tool_args ?? '');
+        let re;
+        try {
+            re = new RegExp(matches.tool_args_match);
+        }
+        catch {
+            return false;
+        }
+        if (!re.test(serialized))
+            return false;
+    }
+    if (matches.cwd_includes !== undefined) {
+        const needles = arrayOf(matches.cwd_includes);
+        if (needles.length > 0) {
+            const hit = needles.some((n) => cwd.includes(n));
+            if (!hit)
+                return false;
+        }
+    }
+    if (matches.project_has !== undefined) {
+        const root = findProjectRoot(cwd);
+        if (!root)
+            return false;
+        if (!fs.existsSync(path.join(root, matches.project_has)))
+            return false;
+    }
+    if (matches.git_dirty !== undefined) {
+        const dirty = isGitDirty(cwd);
+        if (matches.git_dirty !== dirty)
+            return false;
+    }
+    return true;
+}

package/dist/lib/hooks.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Hook management -- discovery, registration, and syncing of event hooks.
+ *
+ * Hooks are shell scripts in ~/.agents/hooks/ that fire on agent events
+ * (tool calls, session start, etc.). Each hook directory contains a manifest
+ * (agents.yaml) declaring events, matchers, and timeout. This module handles
+ * parsing those manifests, registering hooks into agent-native settings files,
+ * and syncing them across version switches.
+ */
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
@@ -93,12 +102,17 @@ export declare function installHooksCentrally(source: string): Promise<{
     errors: string[];
 }>;
 /**
- * List hooks from central ~/.agents/hooks/ directory.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse ~/.agents/hooks.yaml manifest.
- * Returns hook definitions with lifecycle event metadata.
+ * Parse hooks.yaml manifests. Reads BOTH system (~/.agents-system/hooks.yaml)
+ * and user (~/.agents/hooks.yaml), merging with user-wins-on-key-collision
+ * precedence. A user entry with `enabled: false` disables the system-shipped
+ * hook of the same name without forking the system file.
+ *
+ * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export declare function parseHookManifest(): Record<string, ManifestHook>;
 /**
@@ -113,4 +127,3 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
     registered: string[];
     errors: string[];
 };
-//# sourceMappingURL=hooks.d.ts.map

package/dist/lib/hooks.js

@@ -1,9 +1,21 @@
+/**
+ * Hook management -- discovery, registration, and syncing of event hooks.
+ *
+ * Hooks are shell scripts in ~/.agents/hooks/ that fire on agent events
+ * (tool calls, session start, etc.). Each hook directory contains a manifest
+ * (agents.yaml) declaring events, matchers, and timeout. This module handles
+ * parsing those manifests, registering hooks into agent-native settings files,
+ * and syncing them across version switches.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
 import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
-import { getAgentsDir, getHooksDir as getCentralHooksDir, getProjectAgentsDir } from './state.js';
+import { supports, explainSkip } from './capabilities.js';
+import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
+import { getAgentsDir, getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getProjectAgentsDir } from './state.js';
+function getCentralHooksDir() { return getUserHooksDir(); }
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
@@ -329,6 +341,10 @@ export function diffVersionHooks(agent, version) {
  * Install a single hook from central into a specific version home.
  */
 export function installHookToVersion(agent, version, hookName) {
+    const gate = supports(agent, 'hooks', version);
+    if (!gate.ok) {
+        return { success: false, error: explainSkip(agent, 'hooks', gate, version) };
+    }
     const central = listHookEntriesFromDir(getCentralHooksDir()).find((e) => e.name === hookName);
     if (!central) {
         return { success: false, error: `Hook '${hookName}' not found in central` };
@@ -464,28 +480,56 @@ export async function installHooksCentrally(source) {
     return { installed, errors };
 }
 /**
- * List hooks from central ~/.agents/hooks/ directory.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralHooks() {
-    return listHookEntriesFromDir(getCentralHooksDir());
+    const seen = new Set();
+    const results = [];
+    for (const dir of [getUserHooksDir(), getSystemHooksDir()]) {
+        for (const entry of listHookEntriesFromDir(dir)) {
+            if (!seen.has(entry.name)) {
+                seen.add(entry.name);
+                results.push(entry);
+            }
+        }
+    }
+    return results;
 }
 /**
- * Parse ~/.agents/hooks.yaml manifest.
- * Returns hook definitions with lifecycle event metadata.
+ * Parse hooks.yaml manifests. Reads BOTH system (~/.agents-system/hooks.yaml)
+ * and user (~/.agents/hooks.yaml), merging with user-wins-on-key-collision
+ * precedence. A user entry with `enabled: false` disables the system-shipped
+ * hook of the same name without forking the system file.
+ *
+ * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export function parseHookManifest() {
-    const manifestPath = path.join(getAgentsDir(), 'hooks.yaml');
-    if (!fs.existsSync(manifestPath)) {
-        return {};
-    }
-    try {
-        const content = fs.readFileSync(manifestPath, 'utf-8');
-        const parsed = yaml.parse(content);
-        return parsed || {};
+    const merged = {};
+    // System first (lower precedence), user second (overrides).
+    for (const dir of [getAgentsDir(), getUserAgentsDir()]) {
+        const manifestPath = path.join(dir, 'hooks.yaml');
+        if (!fs.existsSync(manifestPath))
+            continue;
+        try {
+            const content = fs.readFileSync(manifestPath, 'utf-8');
+            const parsed = yaml.parse(content);
+            if (!parsed)
+                continue;
+            for (const [name, def] of Object.entries(parsed)) {
+                merged[name] = def;
+            }
+        }
+        catch {
+            /* skip unreadable manifest, keep going */
+        }
     }
-    catch {
-        return {};
+    // Strip disabled hooks so they never reach the registrar.
+    for (const [name, def] of Object.entries(merged)) {
+        if (def.enabled === false)
+            delete merged[name];
     }
+    return merged;
 }
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.
@@ -510,8 +554,21 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'codex') {
         return registerHooksForCodex(versionHome, manifest, agentsDir);
     }
+    if (agentId === 'gemini') {
+        return registerHooksForGemini(versionHome, manifest, agentsDir);
+    }
     return { registered: [], errors: [] };
 }
+/**
+ * Gemini has no native UserPromptSubmit event — map it to BeforeAgent,
+ * the closest lifecycle phase that fires before the model sees the prompt.
+ * Note: gemini's BeforeAgent can only APPEND via additionalContext — it
+ * cannot replace the prompt. The hook script branches on caller to emit
+ * the correct protocol.
+ */
+const GEMINI_EVENT_MAP = {
+    UserPromptSubmit: 'BeforeAgent',
+};
 function registerHooksForClaude(versionHome, manifest, agentsDir) {
     const registered = [];
     const errors = [];
@@ -531,9 +588,33 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
         config.hooks = {};
     }
     const hooks = config.hooks;
-    for (const [name, hookDef] of Object.entries(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('claude'))
+    // Build set of all command paths the current manifest will register.
+    // Used to garbage-collect stale entries left behind after hook renames.
+    const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
+    const currentManifestPaths = new Set();
+    for (const hookDef of Object.values(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
             continue;
+        currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+    }
+    // Remove stale entries: any hook command under ~/.agents/hooks/ that isn't
+    // in the current manifest is a leftover from a renamed/deleted hook script.
+    for (const eventEntries of Object.values(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        for (const group of eventEntries) {
+            if (!group.hooks)
+                continue;
+            group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+        }
+    }
+    // Remove empty matcher groups left after cleanup
+    for (const [event, eventEntries] of Object.entries(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
+    }
+    for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
@@ -600,9 +681,26 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
             return { registered, errors };
         }
     }
-    for (const [name, hookDef] of Object.entries(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('codex'))
+    // Build set of current manifest command paths for codex to GC stale entries
+    const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
+    const currentManifestPaths = new Set();
+    for (const hookDef of Object.values(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
             continue;
+        currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+    }
+    // Remove stale entries from all event groups
+    for (const eventGroups of Object.values(hooksFile.hooks)) {
+        for (const group of eventGroups) {
+            if (!group.hooks)
+                continue;
+            group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+        }
+    }
+    for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
+        hooksFile.hooks[event] = eventGroups.filter((g) => g.hooks && g.hooks.length > 0);
+    }
+    for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
@@ -639,7 +737,6 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
             if (!group.hooks) {
                 group.hooks = [];
             }
-            // Add or update by exact command path — never removes other entries
             const existingIdx = group.hooks.findIndex((h) => h.command === commandPath);
             const hookEntry = { type: 'command', command: commandPath, timeout };
             if (existingIdx >= 0) {
@@ -682,4 +779,77 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
     }
     return { registered, errors };
 }
-//# sourceMappingURL=hooks.js.map
+function registerHooksForGemini(versionHome, manifest, agentsDir) {
+    const registered = [];
+    const errors = [];
+    const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
+    try {
+        updateGeminiSettings(settingsPath, (config) => {
+            setGeminiAutoUpdateDisabled(config);
+            if (!config.hooks || typeof config.hooks !== 'object') {
+                config.hooks = {};
+            }
+            const hooks = config.hooks;
+            const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
+            const currentManifestPaths = new Set();
+            for (const hookDef of Object.values(manifest)) {
+                if (!hookDef.events || hookDef.events.length === 0)
+                    continue;
+                currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+            }
+            for (const eventEntries of Object.values(hooks)) {
+                if (!Array.isArray(eventEntries))
+                    continue;
+                for (const group of eventEntries) {
+                    if (!group.hooks)
+                        continue;
+                    group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+                }
+            }
+            for (const [event, eventEntries] of Object.entries(hooks)) {
+                if (!Array.isArray(eventEntries))
+                    continue;
+                hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
+            }
+            for (const [name, hookDef] of Object.entries(manifest)) {
+                if (!hookDef.events || hookDef.events.length === 0)
+                    continue;
+                const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
+                if (!fs.existsSync(commandPath)) {
+                    errors.push(`${name}: script not found at ${commandPath}`);
+                    continue;
+                }
+                const timeoutMs = (hookDef.timeout || 600) * 1000;
+                for (const event of hookDef.events) {
+                    const geminiEvent = GEMINI_EVENT_MAP[event] ?? event;
+                    if (!hooks[geminiEvent]) {
+                        hooks[geminiEvent] = [];
+                    }
+                    const eventEntries = hooks[geminiEvent];
+                    const matcher = hookDef.matcher || '';
+                    let matcherGroup = eventEntries.find((e) => (e.matcher || '') === matcher);
+                    if (!matcherGroup) {
+                        matcherGroup = { matcher, hooks: [] };
+                        eventEntries.push(matcherGroup);
+                    }
+                    if (!matcherGroup.hooks) {
+                        matcherGroup.hooks = [];
+                    }
+                    const existingIdx = matcherGroup.hooks.findIndex((h) => h.command === commandPath);
+                    const hookEntry = { name, type: 'command', command: commandPath, timeout: timeoutMs };
+                    if (existingIdx >= 0) {
+                        matcherGroup.hooks[existingIdx] = hookEntry;
+                    }
+                    else {
+                        matcherGroup.hooks.push(hookEntry);
+                    }
+                    registered.push(`${name} -> ${geminiEvent}`);
+                }
+            }
+        });
+    }
+    catch (err) {
+        errors.push(`Failed to write gemini settings.json: ${err.message}`);
+    }
+    return { registered, errors };
+}

package/dist/lib/manifest.d.ts

@@ -1,8 +1,13 @@
 import type { Manifest } from './types.js';
+/** Canonical filename for the manifest in any agents repo or project root. */
 export declare const MANIFEST_FILENAME = "agents.yaml";
+/** Parse a YAML string into a typed Manifest object. */
 export declare function parseManifest(content: string): Manifest;
+/** Serialize a Manifest object to a YAML string with 2-space indentation. */
 export declare function serializeManifest(manifest: Manifest): string;
+/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export declare function readManifest(repoPath: string): Manifest | null;
+/** Write a Manifest object to agents.yaml in the given directory. */
 export declare function writeManifest(repoPath: string, manifest: Manifest): void;
+/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export declare function createDefaultManifest(): Manifest;
-//# sourceMappingURL=manifest.d.ts.map

package/dist/lib/manifest.js

@@ -1,26 +1,38 @@
+/**
+ * agents.yaml manifest reading, writing, and serialization.
+ *
+ * The manifest file (agents.yaml) is the central configuration for version defaults,
+ * repository overrides, dependencies, and MCP server declarations.
+ */
 import * as fs from 'fs';
-import * as path from 'path';
 import * as yaml from 'yaml';
+import { safeJoin } from './paths.js';
+/** Canonical filename for the manifest in any agents repo or project root. */
 export const MANIFEST_FILENAME = 'agents.yaml';
+/** Parse a YAML string into a typed Manifest object. */
 export function parseManifest(content) {
     return yaml.parse(content);
 }
+/** Serialize a Manifest object to a YAML string with 2-space indentation. */
 export function serializeManifest(manifest) {
     return yaml.stringify(manifest, { indent: 2 });
 }
+/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export function readManifest(repoPath) {
-    const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+    const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     if (!fs.existsSync(manifestPath)) {
         return null;
     }
     const content = fs.readFileSync(manifestPath, 'utf-8');
     return parseManifest(content);
 }
+/** Write a Manifest object to agents.yaml in the given directory. */
 export function writeManifest(repoPath, manifest) {
-    const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+    const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     const content = serializeManifest(manifest);
     fs.writeFileSync(manifestPath, content, 'utf-8');
 }
+/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export function createDefaultManifest() {
     return {
         agents: {},
@@ -33,4 +45,3 @@ export function createDefaultManifest() {
         },
     };
 }
-//# sourceMappingURL=manifest.js.map

package/dist/lib/markdown.d.ts

@@ -2,4 +2,3 @@
  * Render markdown content for terminal display.
  */
 export declare function renderMarkdown(content: string): string;
-//# sourceMappingURL=markdown.d.ts.map

package/dist/lib/markdown.js

@@ -1,3 +1,9 @@
+/**
+ * Terminal-aware Markdown rendering using marked and marked-terminal.
+ *
+ * Provides a single function for converting Markdown content into
+ * ANSI-formatted text suitable for terminal output.
+ */
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 // @ts-expect-error - marked-terminal types don't match marked's MarkedExtension
@@ -8,4 +14,3 @@ marked.use(markedTerminal());
 export function renderMarkdown(content) {
     return marked.parse(content);
 }
-//# sourceMappingURL=markdown.js.map

package/dist/lib/mcp.d.ts

@@ -61,4 +61,3 @@ export declare function writeMcpServerConfig(config: McpYamlConfig): string;
  * Remove an MCP server config from ~/.agents/mcp/.
  */
 export declare function removeMcpServerConfig(name: string): boolean;
-//# sourceMappingURL=mcp.d.ts.map