@guiho/xdocs 0.1.3 → 0.2.2

package/library/agents.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Agent skill installation and AGENTS.md instructions for xdocs.
+ *
+ * Two distinct things live here:
+ *  1. The small AGENTS.md section that tells any AI agent that xdocs structured
+ *     documentation exists and that it should load the guiho-as-xdocs skill.
+ *  2. The large guiho-as-xdocs skill file, installed (local or global) into the
+ *     skills directory of one or more AI tools.
+ */
+import type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsCliOptions, XDocsSkillInstallResult, XDocsSkillScope } from './types.js';
+/** Canonical name of the xdocs agent skill. */
+export declare const xdocsSkillName = "guiho-as-xdocs";
+/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+ * runtime (relative to this module) so the compiled library works under both
+ * Node and Bun. The file ships with the package in `skills/`. */
+export declare const xdocsSkillContent: string;
+/** All AI tools the skill can be installed for. `agents` is the standard. */
+export declare const xdocsAgentTools: readonly XDocsAgentTool[];
+/** The standard, always-default skill target (AGENTS.md + .agents/skills). */
+export declare const standardAgentTool: XDocsAgentTool;
+/** Parse an explicit `--tool` value into a list of tools (`all` expands to every tool). */
+export declare const parseAgentTools: (value: string | undefined) => XDocsAgentTool[];
+/**
+ * Detect which tools to install for when no `--tool` is given. The standard
+ * `agents` target is always included; non-standard targets are only added when
+ * their files are already present in the project (e.g. Claude Code).
+ */
+export declare const detectAgentTools: (cwd: string) => XDocsAgentTool[];
+/**
+ * Resolve the tools to install for: an explicit `--tool` value wins; otherwise
+ * fall back to detection (standard plus any detected non-standard tools).
+ */
+export declare const resolveInstallTools: (cwd: string, toolFlag: string | undefined) => XDocsAgentTool[];
+/** The small AGENTS.md section announcing xdocs and pointing to the skill. */
+export declare const xdocsAgentsSection = "<!-- BEGIN XDOCS \u2014 DO NOT EDIT THIS SECTION -->\n## XDocs Structured Documentation\n\nThis project uses **xdocs** (`@guiho/xdocs`) for structured, machine-readable\ndocumentation. Each module carries a `.docs.md` / `.xdocs.md` file with YAML\nfrontmatter (`subject`, `description`, `parent`, `children`, `files`), and the\nroot `XDOCS.md` is the top of the tree.\n\n**Load the `guiho-as-xdocs` agent skill** for any documentation work:\ncreating, updating, regenerating, scanning, merging, or navigating xdocs files.\nThe skill holds the full workflow, metadata schema, and CLI reference.\n\nBefore changing documentation, read `xdocs.config.toml` and respect `[ai].mode`:\n\n- **prompt** \u2014 announce which xdocs files need updating and wait for confirmation.\n- **auto** \u2014 update the relevant xdocs files immediately.\n\nUse the xdocs CLI for operations: `xdocs scan`, `xdocs tree`, `xdocs generate`,\n`xdocs list`, `xdocs merge`.\n<!-- END XDOCS -->";
+type SkillPathOptions = {
+    cwd?: string;
+    homeDirectory?: string;
+};
+type SkillInstallOptions = SkillPathOptions & {
+    overwrite?: boolean;
+};
+type AgentAutomationOptions = XDocsCliOptions & {
+    homeDirectory?: string;
+};
+/** Resolve the on-disk path of the skill file for a tool and scope. */
+export declare const resolveSkillPath: (tool: XDocsAgentTool, scope: XDocsSkillScope, options?: SkillPathOptions) => string;
+/** Whether the skill is already installed for a tool and scope. */
+export declare const isSkillInstalled: (tool: XDocsAgentTool, scope: XDocsSkillScope, options?: SkillPathOptions) => boolean;
+/** Install (or refresh) the skill for a single tool and scope. */
+export declare const installSkill: (tool: XDocsAgentTool, scope: XDocsSkillScope, options?: SkillInstallOptions) => Promise<XDocsSkillInstallResult>;
+/** Install the skill for several tools at once. */
+export declare const installSkills: (tools: readonly XDocsAgentTool[], scope: XDocsSkillScope, options?: SkillInstallOptions) => Promise<XDocsSkillInstallResult[]>;
+/**
+ * Ensure the xdocs section is present in AGENTS.md.
+ *
+ * - When the file is missing and `create` is false, nothing is written.
+ * - When the section markers exist, the block is replaced in place (idempotent).
+ * - When the markers are absent, the section is appended.
+ */
+export declare const ensureAgentsInstructions: (cwd: string, create?: boolean) => Promise<XDocsAgentsInstructionsResult>;
+/** Walk up from cwd to find the nearest AGENTS.md. */
+export declare const findAgentsFile: (cwd: string) => string | undefined;
+/** Resolve agent settings from the discovered xdocs config (defaults when absent). */
+export declare const resolveAgentSettings: (options: XDocsCliOptions) => Promise<XDocsAgentSettings>;
+/**
+ * Config-gated automation run by normal commands. Does nothing outside an xdocs
+ * project (no config discovered). When enabled, it keeps the AGENTS.md section
+ * fresh (only if AGENTS.md already exists) and installs the global skill for the
+ * configured tool when it is missing.
+ */
+export declare const runAgentAutomation: (options: AgentAutomationOptions, notify?: (message: string) => void) => Promise<XDocsAgentAutomationResult>;
+export {};
+//# sourceMappingURL=agents.d.ts.map

package/library/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,eAAe,EACf,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAA;AAInB,+CAA+C;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAE9C;;iEAEiE;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAM5B,CAAA;AAEJ,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAyB,CAAA;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAA;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,cAAc,EAKzE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,cAAc,EAK5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAAc,EAChC,CAAA;AAkB9D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,08BAmBV,CAAA;AAErB,KAAK,gBAAgB,GAAG;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,mBAAmB,GAAG,gBAAgB,GAAG;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,sBAAsB,GAAG,eAAe,GAAG;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,MAG/G,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,MAAM,cAAc,EAAE,OAAO,eAAe,EAAE,UAAS,gBAAqB,KAAG,OAC5D,CAAA;AAEpD,kEAAkE;AAClE,eAAO,MAAM,YAAY,GACvB,MAAM,cAAc,EACpB,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,CAajC,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,aAAa,GACxB,OAAO,SAAS,cAAc,EAAE,EAChC,OAAO,eAAe,EACtB,UAAS,mBAAwB,KAChC,OAAO,CAAC,uBAAuB,EAAE,CAInC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,6BAA6B,CAkBjH,CAAA;AAgBD,sDAAsD;AACtD,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,kBAAkB,CAI/F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,sBAAsB,EAC/B,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,0BAA0B,CAkBpC,CAAA"}

package/library/agents.js

@@ -0,0 +1,202 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Agent skill installation and AGENTS.md instructions for xdocs.
+ *
+ * Two distinct things live here:
+ *  1. The small AGENTS.md section that tells any AI agent that xdocs structured
+ *     documentation exists and that it should load the guiho-as-xdocs skill.
+ *  2. The large guiho-as-xdocs skill file, installed (local or global) into the
+ *     skills directory of one or more AI tools.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { discoverConfig, normalizeAgentSettings } from './config.js';
+import { XDocsError } from './errors.js';
+/** Canonical name of the xdocs agent skill. */
+export const xdocsSkillName = 'guiho-as-xdocs';
+/** Raw contents of the bundled guiho-as-xdocs/SKILL.md, read from disk at
+ * runtime (relative to this module) so the compiled library works under both
+ * Node and Bun. The file ships with the package in `skills/`. */
+export const xdocsSkillContent = (() => {
+    try {
+        return readFileSync(new URL('../skills/guiho-as-xdocs/SKILL.md', import.meta.url), 'utf8');
+    }
+    catch {
+        return '';
+    }
+})();
+/** All AI tools the skill can be installed for. `agents` is the standard. */
+export const xdocsAgentTools = ['agents', 'claude'];
+/** The standard, always-default skill target (AGENTS.md + .agents/skills). */
+export const standardAgentTool = 'agents';
+/** Parse an explicit `--tool` value into a list of tools (`all` expands to every tool). */
+export const parseAgentTools = (value) => {
+    if (!value || value === standardAgentTool)
+        return [standardAgentTool];
+    if (value === 'all')
+        return [...xdocsAgentTools];
+    if (xdocsAgentTools.includes(value))
+        return [value];
+    throw new XDocsError(`Invalid --tool value: "${value}". Expected ${xdocsAgentTools.join(', ')}, or all.`);
+};
+/**
+ * Detect which tools to install for when no `--tool` is given. The standard
+ * `agents` target is always included; non-standard targets are only added when
+ * their files are already present in the project (e.g. Claude Code).
+ */
+export const detectAgentTools = (cwd) => {
+    const tools = [standardAgentTool];
+    const root = resolve(cwd);
+    if (existsSync(resolve(root, '.claude')) || existsSync(resolve(root, 'CLAUDE.md')))
+        tools.push('claude');
+    return tools;
+};
+/**
+ * Resolve the tools to install for: an explicit `--tool` value wins; otherwise
+ * fall back to detection (standard plus any detected non-standard tools).
+ */
+export const resolveInstallTools = (cwd, toolFlag) => toolFlag ? parseAgentTools(toolFlag) : detectAgentTools(cwd);
+/**
+ * Skill directory for each tool, relative to the scope root (project root for
+ * `local`, home directory for `global`). The skill is written to
+ * `<root>/<dir>/guiho-as-xdocs/SKILL.md`.
+ *
+ * `agents` is the cross-tool standard (OpenCode, Codex, Jules, and any AGENTS.md
+ * tool read it). `claude` is the non-standard Claude Code location.
+ */
+const skillDirectories = {
+    agents: '.agents/skills',
+    claude: '.claude/skills',
+};
+const AGENTS_BEGIN_MARKER = '<!-- BEGIN XDOCS — DO NOT EDIT THIS SECTION -->';
+const AGENTS_END_MARKER = '<!-- END XDOCS -->';
+/** The small AGENTS.md section announcing xdocs and pointing to the skill. */
+export const xdocsAgentsSection = `${AGENTS_BEGIN_MARKER}
+## XDocs Structured Documentation
+
+This project uses **xdocs** (\`@guiho/xdocs\`) for structured, machine-readable
+documentation. Each module carries a \`.docs.md\` / \`.xdocs.md\` file with YAML
+frontmatter (\`subject\`, \`description\`, \`parent\`, \`children\`, \`files\`), and the
+root \`XDOCS.md\` is the top of the tree.
+
+**Load the \`${xdocsSkillName}\` agent skill** for any documentation work:
+creating, updating, regenerating, scanning, merging, or navigating xdocs files.
+The skill holds the full workflow, metadata schema, and CLI reference.
+
+Before changing documentation, read \`xdocs.config.toml\` and respect \`[ai].mode\`:
+
+- **prompt** — announce which xdocs files need updating and wait for confirmation.
+- **auto** — update the relevant xdocs files immediately.
+
+Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs tree\`, \`xdocs generate\`,
+\`xdocs list\`, \`xdocs merge\`.
+${AGENTS_END_MARKER}`;
+/** Resolve the on-disk path of the skill file for a tool and scope. */
+export const resolveSkillPath = (tool, scope, options = {}) => {
+    const root = scope === 'local' ? resolve(options.cwd ?? process.cwd()) : resolveAgentHome(options.homeDirectory);
+    return resolve(root, skillDirectories[tool], xdocsSkillName, 'SKILL.md');
+};
+/** Whether the skill is already installed for a tool and scope. */
+export const isSkillInstalled = (tool, scope, options = {}) => existsSync(resolveSkillPath(tool, scope, options));
+/** Install (or refresh) the skill for a single tool and scope. */
+export const installSkill = async (tool, scope, options = {}) => {
+    const path = resolveSkillPath(tool, scope, options);
+    const exists = existsSync(path);
+    if (exists && options.overwrite === false)
+        return { tool, scope, path, installed: false, updated: false };
+    const current = exists ? await readFile(path, 'utf8') : undefined;
+    if (current === xdocsSkillContent)
+        return { tool, scope, path, installed: false, updated: false };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, xdocsSkillContent, 'utf8');
+    return { tool, scope, path, installed: !exists, updated: exists };
+};
+/** Install the skill for several tools at once. */
+export const installSkills = async (tools, scope, options = {}) => {
+    const results = [];
+    for (const tool of tools)
+        results.push(await installSkill(tool, scope, options));
+    return results;
+};
+/**
+ * Ensure the xdocs section is present in AGENTS.md.
+ *
+ * - When the file is missing and `create` is false, nothing is written.
+ * - When the section markers exist, the block is replaced in place (idempotent).
+ * - When the markers are absent, the section is appended.
+ */
+export const ensureAgentsInstructions = async (cwd, create = false) => {
+    const path = findAgentsFile(cwd) ?? resolve(cwd, 'AGENTS.md');
+    const exists = existsSync(path);
+    if (!exists && !create)
+        return { path, exists: false, changed: false };
+    if (!exists) {
+        await writeFile(path, `# Agent Instructions\n\n${xdocsAgentsSection}\n`, 'utf8');
+        return { path, exists: true, changed: true };
+    }
+    const content = await readFile(path, 'utf8');
+    const nextContent = upsertAgentsSection(content);
+    if (nextContent === content)
+        return { path, exists: true, changed: false };
+    await writeFile(path, nextContent, 'utf8');
+    return { path, exists: true, changed: true };
+};
+/** Replace the xdocs block between markers, or append it when absent. */
+const upsertAgentsSection = (content) => {
+    const begin = content.indexOf(AGENTS_BEGIN_MARKER);
+    const end = content.indexOf(AGENTS_END_MARKER);
+    if (begin !== -1 && end !== -1 && end > begin) {
+        const before = content.slice(0, begin);
+        const after = content.slice(end + AGENTS_END_MARKER.length);
+        return `${before}${xdocsAgentsSection}${after}`;
+    }
+    return `${content.trimEnd()}\n\n${xdocsAgentsSection}\n`;
+};
+/** Walk up from cwd to find the nearest AGENTS.md. */
+export const findAgentsFile = (cwd) => {
+    let current = resolve(cwd);
+    while (true) {
+        const path = resolve(current, 'AGENTS.md');
+        if (existsSync(path))
+            return path;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+/** Resolve agent settings from the discovered xdocs config (defaults when absent). */
+export const resolveAgentSettings = async (options) => {
+    const cwd = resolve(options.cwd);
+    const discovered = await discoverConfig(cwd, options.config);
+    return normalizeAgentSettings(discovered.raw?.agents);
+};
+/**
+ * Config-gated automation run by normal commands. Does nothing outside an xdocs
+ * project (no config discovered). When enabled, it keeps the AGENTS.md section
+ * fresh (only if AGENTS.md already exists) and installs the global skill for the
+ * configured tool when it is missing.
+ */
+export const runAgentAutomation = async (options, notify = () => { }) => {
+    const cwd = resolve(options.cwd);
+    const discovered = await discoverConfig(cwd, options.config);
+    if (!discovered.raw)
+        return { settings: { ...normalizeAgentSettings(undefined) } };
+    const settings = normalizeAgentSettings(discovered.raw.agents);
+    const result = { settings };
+    if (settings.autoAgentsMd)
+        result.agentsMd = await ensureAgentsInstructions(cwd, false);
+    if (settings.autoSkillInstall && !isSkillInstalled(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory })) {
+        const path = resolveSkillPath(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory });
+        notify(`notice: ${xdocsSkillName} skill not found globally; xdocs is installing it at ${path}`);
+        result.globalSkill = await installSkill(settings.skillTool, 'global', { cwd, homeDirectory: options.homeDirectory, overwrite: false });
+    }
+    return result;
+};
+const resolveAgentHome = (homeDirectory) => {
+    const value = homeDirectory ?? process.env['XDOCS_AGENT_HOME'] ?? homedir();
+    return isAbsolute(value) ? value : resolve(process.cwd(), value);
+};

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CAqDpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,4BAA4B;AAC5B,eAAO,MAAM,MAAM,GAAU,UAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA4DpF,CAAA;AAmBD,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAU,UAAU,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAiB9E,CAAA"}

package/library/cli.js

@@ -5,6 +5,7 @@ import { resolve } from 'node:path';
 import { XDocsError } from './errors.js';
 import { parseArgs, booleanFlag, stringFlag } from './flags.js';
 import { showHelp, showCommandHelp, showVersion } from './help.js';
+import { runAgentAutomation } from './agents.js';
 import { runInit } from './commands/init.js';
 import { runScan } from './commands/scan.js';
 import { runGenerate } from './commands/generate.js';
@@ -12,7 +13,10 @@ import { runPrompt } from './commands/prompt.js';
 import { runMerge } from './commands/merge.js';
 import { runTree } from './commands/tree.js';
 import { runList } from './commands/list.js';
-const validCommands = new Set(['init', 'scan', 'generate', 'prompt', 'merge', 'tree', 'list']);
+import { runAgents } from './commands/agents.js';
+const validCommands = new Set(['init', 'scan', 'generate', 'prompt', 'merge', 'tree', 'list', 'agents']);
+/** Commands that run the config-gated agent automation before executing. */
+const automationCommands = new Set(['scan', 'generate', 'merge', 'tree', 'list']);
 /** Main CLI entry point. */
 export const runCli = async (rawArgs = process.argv.slice(2)) => {
     const parsed = parseArgs(rawArgs);
@@ -38,6 +42,9 @@ export const runCli = async (rawArgs = process.argv.slice(2)) => {
     }
     const options = resolveOptions(parsed.flags);
     const command = parsed.command;
+    if (automationCommands.has(command)) {
+        await runAgentAutomation(options, (message) => process.stderr.write(message + '\n'));
+    }
     switch (command) {
         case 'init':
             await runInit(options, parsed);
@@ -60,6 +67,9 @@ export const runCli = async (rawArgs = process.argv.slice(2)) => {
         case 'list':
             await runList(options, parsed);
             break;
+        case 'agents':
+            await runAgents(options, parsed);
+            break;
     }
 };
 /** Build XDocsCliOptions from parsed flags. */

package/library/commands/agents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
+/** Run the agents command. */
+export declare const runAgents: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
+//# sourceMappingURL=agents.d.ts.map

package/library/commands/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../source/commands/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAA4C,MAAM,aAAa,CAAA;AAS7G,8BAA8B;AAC9B,eAAO,MAAM,SAAS,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAe/F,CAAA"}

package/library/commands/agents.js

@@ -0,0 +1,64 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { XDocsError } from '../errors.js';
+import { stringFlag } from '../flags.js';
+import { ensureAgentsInstructions, installSkills, resolveInstallTools, xdocsSkillName } from '../agents.js';
+const USAGE = `Usage:
+  xdocs agents install <local|global> [--tool <agents|claude|all>]
+  xdocs agents instructions`;
+/** Run the agents command. */
+export const runAgents = async (options, parsed) => {
+    const sub = parsed.positionals[0];
+    if (sub === 'install') {
+        await runInstall(options, parsed);
+        return;
+    }
+    if (sub === 'instructions') {
+        await runInstructions(options);
+        return;
+    }
+    if (!sub)
+        throw new XDocsError(`Missing agents subcommand.\n\n${USAGE}`);
+    throw new XDocsError(`Unknown agents subcommand: "${sub}"\n\n${USAGE}`);
+};
+/** Install the guiho-as-xdocs skill for one or more tools. */
+const runInstall = async (options, parsed) => {
+    const scope = parseScope(parsed.positionals[1]);
+    const tools = resolveInstallTools(options.cwd, stringFlag(parsed.flags, 'tool'));
+    const results = await installSkills(tools, scope, { cwd: options.cwd });
+    if (options.format === 'json') {
+        process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+        return;
+    }
+    for (const result of results) {
+        process.stdout.write(formatInstall(result));
+    }
+};
+/** Insert or refresh the xdocs section in AGENTS.md. */
+const runInstructions = async (options) => {
+    const result = await ensureAgentsInstructions(options.cwd, true);
+    if (options.format === 'json') {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(`agents_md: ${result.path}\n`);
+    process.stdout.write(`exists: ${result.exists}\n`);
+    process.stdout.write(`changed: ${result.changed}\n`);
+};
+const parseScope = (value) => {
+    if (value === 'local' || value === 'global')
+        return value;
+    if (!value)
+        throw new XDocsError(`Missing install scope.\n\n${USAGE}`);
+    throw new XDocsError(`Invalid install scope: "${value}". Expected local or global.`);
+};
+const formatInstall = (result) => [
+    `skill: ${xdocsSkillName}`,
+    `tool: ${result.tool}`,
+    `scope: ${result.scope}`,
+    `path: ${result.path}`,
+    `installed: ${result.installed}`,
+    `updated: ${result.updated}`,
+    '',
+].join('\n');

package/library/commands/init.d.ts

@@ -3,5 +3,5 @@
  */
 import type { XDocsCliOptions, XDocsParsedArgs } from '../types.js';
 /** Run the init command. */
-export declare const runInit: (options: XDocsCliOptions, _parsed: XDocsParsedArgs) => Promise<void>;
+export declare const runInit: (options: XDocsCliOptions, parsed: XDocsParsedArgs) => Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/library/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../source/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AA8BnE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAqC9F,CAAA"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../source/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAyBnE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,QAAQ,eAAe,KAAG,OAAO,CAAC,IAAI,CAiD7F,CAAA"}

package/library/commands/init.js

@@ -2,36 +2,31 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { existsSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { basename, relative, resolve } from 'node:path';
 import { writeDefaultConfig } from '../config.js';
-const ROOT_XDOCS_CONTENT = `
-# GUIHO XDocs Documentation
-
-## Files
-
-## Directories
-`.trim() + '\n';
-const AGENTS_XDOCS_BLOCK = `
-<!-- BEGIN XDOCS — DO NOT EDIT THIS SECTION -->
-## XDocs
-
-This project uses xdocs for structured documentation. xdocs files describe
-modules, their purpose, files, and hierarchy.
+import { booleanFlag, stringFlag } from '../flags.js';
+import { ensureAgentsInstructions, findAgentsFile, installSkill, resolveInstallTools, xdocsSkillName } from '../agents.js';
+/**
+ * Build the root XDOCS.md content. There is exactly one `XDOCS.md` per
+ * repository, at the repo root. It does NOT use frontmatter; it is a plain
+ * index that lists the repository's packages and applications. Each package or
+ * application has its own root `.xdocs.md` file (with frontmatter) that is the
+ * top of that package's documentation tree.
+ */
+const createRootXDocsContent = (projectName) => `# ${projectName} -- XDocs Root
 
-- Configuration: \`xdocs.config.toml\`
-- Root documentation: \`XDOCS.md\`
-- File extensions: \`.docs.md\`, \`.xdocs.md\`
+The single root index for this repository. There is exactly one \`XDOCS.md\` per
+repository and it does not use frontmatter. List the packages and applications
+in the repo below; each one has its own root \`.xdocs.md\` file (with frontmatter)
+that is the top of that package's documentation tree.
 
-When modifying code, check the xdocs configuration for AI behavior mode.
-In "prompt" mode, announce documentation updates and wait for confirmation.
-In "auto" mode, update documentation immediately.
+## Packages
 
-Use the xdocs CLI for operations: \`xdocs scan\`, \`xdocs generate\`, \`xdocs tree\`, etc.
-<!-- END XDOCS -->
-`.trim();
+## Applications
+`;
 /** Run the init command. */
-export const runInit = async (options, _parsed) => {
+export const runInit = async (options, parsed) => {
     const cwd = options.cwd;
     // 1. Create xdocs.config.toml
     const configPath = resolve(cwd, 'xdocs.config.toml');
@@ -48,24 +43,37 @@ export const runInit = async (options, _parsed) => {
         process.stdout.write(`exists: XDOCS.md\n`);
     }
     else {
-        await writeFile(xdocsPath, ROOT_XDOCS_CONTENT, 'utf8');
+        await writeFile(xdocsPath, createRootXDocsContent(basename(cwd)), 'utf8');
         process.stdout.write(`created: XDOCS.md\n`);
     }
-    // 3. Update AGENTS.md
-    const agentsPath = resolve(cwd, 'AGENTS.md');
-    if (existsSync(agentsPath)) {
-        const content = await readFile(agentsPath, 'utf8');
-        if (content.includes('<!-- BEGIN XDOCS')) {
-            process.stdout.write(`exists: AGENTS.md (xdocs section already present)\n`);
+    // 3. Update AGENTS.md (announce xdocs + point AI at the guiho-as-xdocs skill)
+    const agentsExisted = findAgentsFile(cwd) !== undefined;
+    const agentsResult = await ensureAgentsInstructions(cwd, true);
+    if (!agentsExisted) {
+        process.stdout.write(`created: AGENTS.md\n`);
+    }
+    else if (agentsResult.changed) {
+        process.stdout.write(`updated: AGENTS.md (xdocs section)\n`);
+    }
+    else {
+        process.stdout.write(`exists: AGENTS.md (xdocs section already present)\n`);
+    }
+    // 4. Install the guiho-as-xdocs agent skill (standard by default; non-standard
+    //    tools only when explicitly requested via --tool or detected in the project)
+    const scope = booleanFlag(parsed.flags, 'global') ? 'global' : 'local';
+    const tools = resolveInstallTools(cwd, stringFlag(parsed.flags, 'tool'));
+    for (const tool of tools) {
+        const result = await installSkill(tool, scope, { cwd });
+        const where = scope === 'local' ? relative(cwd, result.path) || result.path : result.path;
+        if (result.installed) {
+            process.stdout.write(`installed: ${xdocsSkillName} skill (${tool}, ${scope}) -> ${where}\n`);
+        }
+        else if (result.updated) {
+            process.stdout.write(`updated: ${xdocsSkillName} skill (${tool}, ${scope})\n`);
         }
         else {
-            await writeFile(agentsPath, content.trimEnd() + '\n\n' + AGENTS_XDOCS_BLOCK + '\n', 'utf8');
-            process.stdout.write(`updated: AGENTS.md (added xdocs section)\n`);
+            process.stdout.write(`exists: ${xdocsSkillName} skill (${tool}, ${scope})\n`);
         }
     }
-    else {
-        await writeFile(agentsPath, '# Agent Instructions\n\n' + AGENTS_XDOCS_BLOCK + '\n', 'utf8');
-        process.stdout.write(`created: AGENTS.md\n`);
-    }
     process.stdout.write(`\nxdocs initialized.\n`);
 };

package/library/commands/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../source/commands/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAoD9F,CAAA"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../source/commands/scan.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAInE,4BAA4B;AAC5B,eAAO,MAAM,OAAO,GAAU,SAAS,eAAe,EAAE,SAAS,eAAe,KAAG,OAAO,CAAC,IAAI,CAqD9F,CAAA"}

package/library/commands/scan.js

@@ -33,7 +33,8 @@ export const runScan = async (options, _parsed) => {
     if (result.xdocsFiles.length > 0) {
         process.stdout.write(`\nfiles:\n`);
         for (const file of result.xdocsFiles) {
-            const status = file.valid ? 'valid' : 'incomplete';
+            const isRootIndex = file.relativePath === 'XDOCS.md' && !file.metadata;
+            const status = isRootIndex ? 'root index' : (file.valid ? 'valid' : 'incomplete');
             const subject = file.metadata?.subject ? ` (${file.metadata.subject})` : '';
             process.stdout.write(`  ${file.relativePath} [${status}]${subject}\n`);
             if (options.verbose && file.errors.length > 0) {

package/library/config.d.ts

@@ -1,7 +1,11 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-import type { XDocsCliOptions, XDocsConfig, XDocsRawConfig } from './types.js';
+import type { XDocsAgentSettings, XDocsCliOptions, XDocsConfig, XDocsRawConfig } from './types.js';
+/** Default agent automation settings when no [agents] section is configured. */
+export declare const DEFAULT_AGENT_SETTINGS: XDocsAgentSettings;
+/** Normalize the raw [agents] config section into validated settings. */
+export declare const normalizeAgentSettings: (raw: XDocsRawConfig["agents"]) => XDocsAgentSettings;
 /** Discover the xdocs.config.toml file. */
 export declare const discoverConfig: (cwd: string, explicitPath?: string) => Promise<{
     path?: string;

package/library/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAe,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAQ3F,2CAA2C;AAC3C,eAAO,MAAM,cAAc,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,CAaxH,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,UAAU,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAS9E,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAOxF,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,GAAI,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,aAAa,MAAM,KAAG,WA6BvF,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,WAO1C,CAAA;AAEF,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,GAAI,KAAK,MAAM,KAAG,MAiBxD,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,GAAU,KAAK,MAAM,EAAE,mBAAiB,KAAG,OAAO,CAAC,MAAM,CASvF,CAAA;AAuBD,sDAAsD;AACtD,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WACP,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAA+B,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAU/H,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAE,kBAIpC,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,GAAI,KAAK,cAAc,CAAC,QAAQ,CAAC,KAAG,kBAgBtE,CAAA;AAQD,2CAA2C;AAC3C,eAAO,MAAM,cAAc,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAAE,CAaxH,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,UAAU,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAS9E,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,GAAU,SAAS,eAAe,KAAG,OAAO,CAAC,WAAW,CAOxF,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,GAAI,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,aAAa,MAAM,KAAG,WA8BvF,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,WAQ1C,CAAA;AAEF,sDAAsD;AACtD,eAAO,MAAM,0BAA0B,GAAI,KAAK,MAAM,KAAG,MAsBxD,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,GAAU,KAAK,MAAM,EAAE,mBAAiB,KAAG,OAAO,CAAC,MAAM,CASvF,CAAA;AAuBD,sDAAsD;AACtD,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WACP,CAAA"}

package/library/config.js

@@ -10,6 +10,36 @@ const DEFAULT_EXTENSIONS = ['.docs.md', '.xdocs.md'];
 const DEFAULT_EXCLUDE = ['node_modules', '.git', 'dist', 'build', 'library', 'bin', 'bundle'];
 const DEFAULT_AI_MODE = 'prompt';
 const CONFIG_FILENAME = 'xdocs.config.toml';
+const AGENT_TOOLS = new Set(['agents', 'claude']);
+/** Default agent automation settings when no [agents] section is configured. */
+export const DEFAULT_AGENT_SETTINGS = {
+    autoAgentsMd: true,
+    autoSkillInstall: true,
+    skillTool: 'agents',
+};
+/** Normalize the raw [agents] config section into validated settings. */
+export const normalizeAgentSettings = (raw) => {
+    if (raw === undefined)
+        return { ...DEFAULT_AGENT_SETTINGS };
+    const autoAgentsMd = optionalBoolean(raw.auto_agents_md, 'agents.auto_agents_md');
+    const autoSkillInstall = optionalBoolean(raw.auto_skill_install, 'agents.auto_skill_install');
+    const skillTool = raw.skill_tool;
+    if (skillTool !== undefined && (typeof skillTool !== 'string' || !AGENT_TOOLS.has(skillTool))) {
+        throw new XDocsError(`Invalid agents.skill_tool: "${String(skillTool)}". Expected agents or claude.`);
+    }
+    return {
+        autoAgentsMd: autoAgentsMd !== false,
+        autoSkillInstall: autoSkillInstall !== false,
+        skillTool: skillTool ?? DEFAULT_AGENT_SETTINGS.skillTool,
+    };
+};
+const optionalBoolean = (value, key) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new XDocsError(`Invalid ${key}. Expected true or false.`);
+    return value;
+};
 /** Discover the xdocs.config.toml file. */
 export const discoverConfig = async (cwd, explicitPath) => {
     if (explicitPath) {
@@ -66,6 +96,7 @@ export const normalizeConfig = (raw, cwd, configPath) => {
         ai: { mode: aiMode ?? DEFAULT_AI_MODE },
         scan: { exclude },
         project: { name: raw.project?.name ?? basename(cwd) },
+        agents: normalizeAgentSettings(raw.agents),
     };
 };
 /** Create a default config object for a given cwd. */
@@ -76,6 +107,7 @@ export const defaultConfig = (cwd) => ({
     ai: { mode: DEFAULT_AI_MODE },
     scan: { exclude: DEFAULT_EXCLUDE },
     project: { name: basename(cwd) },
+    agents: { ...DEFAULT_AGENT_SETTINGS },
 });
 /** Generate the default xdocs.config.toml content. */
 export const createDefaultConfigContent = (cwd) => {
@@ -93,6 +125,11 @@ exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
 
 [project]
 name = "${name}"
+
+[agents]
+auto_agents_md = true
+auto_skill_install = true
+skill_tool = "agents"
 `;
 };
 /** Write the default xdocs.config.toml to disk. */

package/library/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../source/flags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmBjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,KAAG,eA4D7C,CAAA;AAUD,gDAAgD;AAChD,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAGrG,CAAA;AAED,oCAAoC;AACpC,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,OAE7F,CAAA;AAED,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,GAAG,SAGrG,CAAA"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../source/flags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,KAAG,eA4D7C,CAAA;AAUD,gDAAgD;AAChD,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAGrG,CAAA;AAED,oCAAoC;AACpC,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,OAE7F,CAAA;AAED,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,GAAG,SAGrG,CAAA"}

package/library/flags.js

@@ -6,6 +6,7 @@ const booleanFlags = new Set([
     'help',
     'version',
     'verbose',
+    'global',
 ]);
 const shortFlagMap = {
     '-h': '--help',