@guiho/xdocs 0.1.3 → 0.2.2

package/library/guiho-xdocs.d.ts

@@ -2,13 +2,14 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 export { XDocsError, invariant } from './errors.js';
-export type { XDocsAiMode, XDocsCliOptions, XDocsCommand, XDocsConfig, XDocsFile, XDocsFormat, XDocsMetadata, XDocsParsedArgs, XDocsPrompt, XDocsPromptName, XDocsRawConfig, XDocsScanResult, XDocsTreeNode, XDocsTreeValidation, } from './types.js';
+export type { XDocsAgentAutomationResult, XDocsAgentSettings, XDocsAgentTool, XDocsAgentsInstructionsResult, XDocsAiMode, XDocsCliOptions, XDocsCommand, XDocsConfig, XDocsFile, XDocsFormat, XDocsMetadata, XDocsParsedArgs, XDocsPrompt, XDocsPromptName, XDocsRawConfig, XDocsScanResult, XDocsSkillInstallResult, XDocsSkillScope, XDocsTreeNode, XDocsTreeValidation, } from './types.js';
 export { parseArgs, stringFlag, booleanFlag, listFlag } from './flags.js';
-export { createDefaultConfigContent, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
+export { createDefaultConfigContent, DEFAULT_AGENT_SETTINGS, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeAgentSettings, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
 export { isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
 export { extractFrontmatter, parseXDocsFile, validateMetadata } from './metadata.js';
 export { buildTree, renderTree, renderTreeMarkdown, validateTree } from './tree.js';
 export { readPackageVersion, showCommandHelp, showHelp, showVersion } from './help.js';
 export { getPrompt, getPromptNames, prompts } from './prompts.js';
+export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, parseAgentTools, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, } from './agents.js';
 export { runCli, runCliWithErrorHandling } from './cli.js';
 //# sourceMappingURL=guiho-xdocs.d.ts.map

package/library/guiho-xdocs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5F,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"guiho-xdocs.d.ts","sourceRoot":"","sources":["../source/guiho-xdocs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGnD,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,6BAA6B,EAC7B,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5F,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAGpF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGtF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA"}

package/library/guiho-xdocs.js

@@ -6,7 +6,7 @@ export { XDocsError, invariant } from './errors.js';
 // Flags
 export { parseArgs, stringFlag, booleanFlag, listFlag } from './flags.js';
 // Config
-export { createDefaultConfigContent, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
+export { createDefaultConfigContent, DEFAULT_AGENT_SETTINGS, defaultConfig, discoverConfig, loadConfig, loadConfigOrDefaults, normalizeAgentSettings, normalizeConfig, resolvePath, writeDefaultConfig, } from './config.js';
 // Discovery
 export { isXDocsFile, listDirectoryFiles, scanDirectory, scanProject } from './discovery.js';
 // Metadata
@@ -17,5 +17,7 @@ export { buildTree, renderTree, renderTreeMarkdown, validateTree } from './tree.
 export { readPackageVersion, showCommandHelp, showHelp, showVersion } from './help.js';
 // Prompts
 export { getPrompt, getPromptNames, prompts } from './prompts.js';
+// Agents
+export { detectAgentTools, ensureAgentsInstructions, findAgentsFile, installSkill, installSkills, isSkillInstalled, parseAgentTools, resolveAgentSettings, resolveInstallTools, resolveSkillPath, runAgentAutomation, standardAgentTool, xdocsAgentsSection, xdocsAgentTools, xdocsSkillContent, xdocsSkillName, } from './agents.js';
 // CLI
 export { runCli, runCliWithErrorHandling } from './cli.js';

package/library/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAO,MAQrC,CAAA;AAED,qCAAqC;AACrC,eAAO,MAAM,WAAW,QAAO,MAAyC,CAAA;AAExE,+BAA+B;AAC/B,eAAO,MAAM,QAAQ,QAAO,MA6BpB,CAAA;AAER,wCAAwC;AACxC,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAIjD,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAO,MAQrC,CAAA;AAED,qCAAqC;AACrC,eAAO,MAAM,WAAW,QAAO,MAAyC,CAAA;AAExE,+BAA+B;AAC/B,eAAO,MAAM,QAAQ,QAAO,MAgCpB,CAAA;AAER,wCAAwC;AACxC,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAIjD,CAAA"}

package/library/help.js

@@ -29,6 +29,7 @@ Commands:
   merge [path]          Merge xdocs files from a directory into one file
   tree                  Display the project hierarchy tree
   list [path]           List files with descriptions
+  agents                Install the guiho-as-xdocs skill and AGENTS.md instructions
 
 Global Flags:
   -h, --help            Show help for a command
@@ -45,6 +46,8 @@ Examples:
   xdocs merge ./src/domain
   xdocs tree
   xdocs list ./src/auth
+  xdocs agents install local
+  xdocs agents instructions
 `.trim();
 /** Show help for a specific command. */
 export const showCommandHelp = (command) => {
@@ -57,15 +60,21 @@ const commandHelpMap = {
     init: `
 xdocs init - Initialize xdocs in a project
 
-Usage: xdocs init
+Usage: xdocs init [--tool <agents|claude|all>] [--global]
 
 Creates:
   - XDOCS.md              Root documentation file
   - xdocs.config.toml     Configuration with defaults
-  - Updates AGENTS.md     Adds xdocs instructions for AI agents
-  - Installs agent skills Prompts for AI tool and skill directory
+  - Updates AGENTS.md     Adds the xdocs section pointing AI at the skill
+  - Installs the skill    guiho-as-xdocs into .agents/skills (standard, local)
+
+By default the skill is installed for the standard target (AGENTS.md +
+.agents/skills). The non-standard claude target (.claude/skills) is added only
+when a .claude directory or CLAUDE.md is detected, or when requested via --tool.
 
 Flags:
+  --tool <tool>           agents (default/standard), claude, or all
+  --global                Install the skill in the user home skills directory
   --cwd <path>            Target directory (default: current directory)
   --verbose               Show detailed output
 `.trim(),
@@ -161,5 +170,31 @@ Flags:
   --cwd <path>            Target directory (default: current directory)
   --config <path>         Path to xdocs.config.toml
   --verbose               Show detailed output
+`.trim(),
+    agents: `
+xdocs agents - Install the guiho-as-xdocs skill and AGENTS.md instructions
+
+Usage:
+  xdocs agents install <local|global> [--tool <tool>]
+  xdocs agents instructions
+
+Subcommands:
+  install local           Install the skill under the current project
+  install global          Install the skill under the user home directory
+  instructions            Insert or refresh the xdocs section in AGENTS.md
+
+Skill locations:
+  agents (standard)       <root>/.agents/skills/guiho-as-xdocs/SKILL.md
+  claude (non-standard)   <root>/.claude/skills/guiho-as-xdocs/SKILL.md
+
+<root> is the project for local scope, or the user home directory for global.
+Without --tool, the standard agents target is installed, plus claude when a
+.claude directory or CLAUDE.md is detected. Codex, Jules, and other AGENTS.md
+tools read the standard target and the AGENTS.md instructions.
+
+Flags:
+  --tool <tool>           agents (default/standard), claude, or all
+  --format <format>       Output format: text, json (default: text)
+  --cwd <path>            Target directory (default: current directory)
 `.trim(),
 };

package/library/prompts.d.ts

@@ -1,9 +1,11 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  *
- * Prompt loader. Each .md file in prompts/ is imported as text at build time
- * so that `bun build --compile` embeds them in the binary. Adding a new prompt
- * requires two steps: create the .md file, then add an import here.
+ * Prompt loader. Prompt `.md` files are read from disk at runtime (relative to
+ * this module via import.meta.url) so the compiled library works under both
+ * Node and Bun. Each `.md` file ships with the package in `prompts/`. Adding a
+ * new prompt requires creating the `.md` file and adding its name to
+ * PROMPT_NAMES.
  */
 import type { XDocsPrompt } from './types.js';
 /** All available prompts, keyed by name. */

package/library/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA0B7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CASjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../source/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmC7C,4CAA4C;AAC5C,eAAO,MAAM,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAWjD,CAAA;AAEJ,gDAAgD;AAChD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,SACpC,CAAA;AAEnB,4BAA4B;AAC5B,eAAO,MAAM,cAAc,QAAO,MAAM,EACnB,CAAA"}

package/library/prompts.js

@@ -1,20 +1,24 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  *
- * Prompt loader. Each .md file in prompts/ is imported as text at build time
- * so that `bun build --compile` embeds them in the binary. Adding a new prompt
- * requires two steps: create the .md file, then add an import here.
+ * Prompt loader. Prompt `.md` files are read from disk at runtime (relative to
+ * this module via import.meta.url) so the compiled library works under both
+ * Node and Bun. Each `.md` file ships with the package in `prompts/`. Adding a
+ * new prompt requires creating the `.md` file and adding its name to
+ * PROMPT_NAMES.
  */
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import writeRaw from '../prompts/write.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import updateRaw from '../prompts/update.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import agentsRaw from '../prompts/agents.md' with { type: 'text' };
-// @ts-expect-error -- Bun text import, no TS declaration needed
-import generateRaw from '../prompts/generate.md' with { type: 'text' };
+import { readFileSync } from 'node:fs';
 import { extractFrontmatter } from './metadata.js';
-const rawFiles = [writeRaw, updateRaw, agentsRaw, generateRaw];
+const PROMPT_NAMES = ['write', 'update', 'agents', 'generate'];
+/** Read a prompt file's raw contents, or undefined when it cannot be read. */
+const readPromptFile = (name) => {
+    try {
+        return readFileSync(new URL(`../prompts/${name}.md`, import.meta.url), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
 /** Parse a raw prompt file into an XDocsPrompt. */
 const parsePrompt = (raw) => {
     const { frontmatter, body } = extractFrontmatter(raw);
@@ -37,7 +41,10 @@ const parsePrompt = (raw) => {
 /** All available prompts, keyed by name. */
 export const prompts = (() => {
     const map = new Map();
-    for (const raw of rawFiles) {
+    for (const name of PROMPT_NAMES) {
+        const raw = readPromptFile(name);
+        if (!raw)
+            continue;
         const prompt = parsePrompt(raw);
         map.set(prompt.name, prompt);
     }

package/library/types.d.ts

@@ -6,7 +6,15 @@ export type XDocsFormat = 'text' | 'json' | 'markdown';
 /** AI behavior mode for documentation updates. */
 export type XDocsAiMode = 'prompt' | 'auto';
 /** Command names recognized by the CLI. */
-export type XDocsCommand = 'init' | 'scan' | 'generate' | 'prompt' | 'merge' | 'tree' | 'list';
+export type XDocsCommand = 'init' | 'scan' | 'generate' | 'prompt' | 'merge' | 'tree' | 'list' | 'agents';
+/** AI tools the guiho-as-xdocs skill can be installed for.
+ *
+ * `agents` is the standard target (AGENTS.md + .agents/skills) and the default.
+ * `claude` is a non-standard target (.claude/skills) used only when explicitly
+ * requested or auto-detected. */
+export type XDocsAgentTool = 'agents' | 'claude';
+/** Scope of an agent-skill installation. */
+export type XDocsSkillScope = 'local' | 'global';
 /** Raw configuration as parsed from xdocs.config.toml. */
 export type XDocsRawConfig = Partial<{
     schema: number;
@@ -22,6 +30,11 @@ export type XDocsRawConfig = Partial<{
     project: Partial<{
         name: string;
     }>;
+    agents: Partial<{
+        auto_agents_md: boolean;
+        auto_skill_install: boolean;
+        skill_tool: string;
+    }>;
 }>;
 /** Normalized, validated configuration. */
 export type XDocsConfig = {
@@ -40,6 +53,13 @@ export type XDocsConfig = {
     project: {
         name: string;
     };
+    agents: XDocsAgentSettings;
+};
+/** Normalized agent automation settings. */
+export type XDocsAgentSettings = {
+    autoAgentsMd: boolean;
+    autoSkillInstall: boolean;
+    skillTool: XDocsAgentTool;
 };
 /** YAML frontmatter metadata from an xdocs file. */
 export type XDocsMetadata = {
@@ -105,4 +125,24 @@ export type XDocsPrompt = {
     description: string;
     body: string;
 };
+/** Result of installing the guiho-as-xdocs skill for one tool/scope. */
+export type XDocsSkillInstallResult = {
+    tool: XDocsAgentTool;
+    scope: XDocsSkillScope;
+    path: string;
+    installed: boolean;
+    updated: boolean;
+};
+/** Result of ensuring the xdocs section exists in AGENTS.md. */
+export type XDocsAgentsInstructionsResult = {
+    path: string;
+    exists: boolean;
+    changed: boolean;
+};
+/** Result of the config-gated agent automation that runs on normal commands. */
+export type XDocsAgentAutomationResult = {
+    settings: XDocsAgentSettings;
+    agentsMd?: XDocsAgentsInstructionsResult;
+    globalSkill?: XDocsSkillInstallResult;
+};
 //# sourceMappingURL=types.d.ts.map

package/library/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;AAEtD,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE3C,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;AAE9F,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAC;QAClB,SAAS,EAAE,MAAM,EAAE,CAAA;KACpB,CAAC,CAAA;IACF,EAAE,EAAE,OAAO,CAAC;QACV,IAAI,EAAE,MAAM,CAAA;KACb,CAAC,CAAA;IACF,IAAI,EAAE,OAAO,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,CAAA;KAClB,CAAC,CAAA;IACF,OAAO,EAAE,OAAO,CAAC;QACf,IAAI,EAAE,MAAM,CAAA;KACb,CAAC,CAAA;CACH,CAAC,CAAA;AAEF,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,CAAC,CAAA;IACT,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;IACD,EAAE,EAAE;QACF,IAAI,EAAE,WAAW,CAAA;KAClB,CAAA;IACD,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,EAAE,CAAA;KAClB,CAAA;IACD,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF,CAAA;AAED,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAA;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,QAAQ,EAAE,aAAa,EAAE,CAAA;CAC1B,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,4BAA4B;AAC5B,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAA;CACnD,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,CAAA;IACxB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,oBAAoB,EAAE,MAAM,CAAA;IAC5B,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAA;AAExE,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.1.3",
+  "version": "0.2.2",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -18,11 +18,12 @@
     "README.md",
     "library/",
     "prompts/",
+    "skills/",
     "docs/",
     "jsr.json",
     "CHANGELOG.md",
     "LICENSE.md",
-    "docs.md"
+    "DOCS.md"
   ],
   "keywords": [
     "ai",
@@ -71,7 +72,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@guiho/mirror": "^3.0.0",
+    "@guiho/mirror": "^3.1.2",
     "@types/bun": "1.3.14",
     "typescript": "6.0.3"
   }

package/skills/guiho-as-xdocs/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: guiho-as-xdocs
+description: Use this skill whenever the user works with xdocs (`@guiho/xdocs`) structured documentation, AND proactively whenever you create a new module or subdirectory or add/change/remove files in a directory of an xdocs project, so you create or update that directory's `.xdocs.md` as part of the change. This includes creating, updating, or regenerating `.docs.md` / `.xdocs.md` files, the root `XDOCS.md`, the project tree, scanning documentation coverage, merging docs, or maintaining xdocs metadata and AGENTS.md guidance, even when the user only says "document this module", "update the docs", or "what does this folder do" without naming xdocs.
+---
+
+# GUIHO XDocs
+
+GUIHO XDocs is a deterministic CLI and TypeScript library for **structured documentation of codebases**. It lets an AI agent understand a project without reading every source file: each directory carries a small Markdown file with YAML frontmatter that describes its subject, purpose, files, and place in a parent-child hierarchy.
+
+```text
+source tree -> xdocs files (.docs.md / .xdocs.md) -> tree + metadata -> AI-readable map
+```
+
+Use xdocs for documentation work instead of ad hoc README sprawl or re-reading the whole codebase. The value of xdocs is that the structure (subjects, descriptions, files, parent/child links) is machine-readable and stays close to the code it describes.
+
+## Command Selection
+
+Choose the xdocs command in this order:
+
+1. Use `bun @guiho/xdocs` when the package is installed locally and Bun is available.
+2. Use `xdocs` when a global binary is available.
+3. Use `bunx @guiho/xdocs` when running without installation.
+
+When unsure, run a cheap availability check (`bun @guiho/xdocs --help`, `xdocs --help`, or `bunx @guiho/xdocs --help`) and then reuse the working command consistently. Run `xdocs --help` or `xdocs <command> --help` for command-specific details when needed.
+
+xdocs is a Bun/TypeScript ESM tool. Bun is the recommended runtime. The CLI never bumps versions or mutates `package.json` — it only reads and writes documentation files. (Versioning is a separate concern handled by GUIHO Mirror.)
+
+## Core Concepts
+
+- **xdocs file**: a Markdown file with YAML frontmatter that documents one directory/module. Default extensions are `.docs.md` and `.xdocs.md`. Extensions are configurable in `xdocs.config.toml`.
+- **Repository root index**: there is exactly one `XDOCS.md` per repository, at the repo root. It has **no frontmatter** — it is a plain index that lists the repository's packages and applications, and it is not itself a tree node.
+- **Package/application root**: each package or application has its own root `.xdocs.md` file (with frontmatter and `parent: null`) that is the top of that package's documentation tree. `XDOCS.md` lists these package roots.
+- **Tree**: a parent-child **containment** hierarchy (not a dependency graph), assembled from each `.xdocs.md` / `.docs.md` file's `subject` / `parent` / `children` fields. A module's `parent` is the `subject` of the module that contains it; a package/application root uses `parent: null`.
+- **AI mode**: `xdocs.config.toml` `[ai].mode` is either `"prompt"` (announce the documentation updates, then write them) or `"auto"` (write immediately). It governs *how* you write docs, not *whether* — documenting a changed module is always required (see Automatic Documentation Maintenance).
+
+### Metadata schema (YAML frontmatter)
+
+Every `.xdocs.md` / `.docs.md` file carries frontmatter with these fields. The repository's single `XDOCS.md` is the exception: it has no frontmatter and is just an index.
+
+| Field         | Type                  | Meaning                                                       |
+| ------------- | --------------------- | ------------------------------------------------------------ |
+| `subject`     | string                | Unique identifier/name of this module in the tree.           |
+| `description` | string                | One-line summary of what the module does.                    |
+| `parent`      | string \| null        | `subject` of the containing module; `null` for a package/application root. |
+| `children`    | string[]              | `subject`s of directly contained modules.                    |
+| `files`       | map<string,string>    | Filename -> short description of each significant file.      |
+| `tags`        | string[]              | Free-form classification labels.                             |
+| `flags`       | string[]              | Behavioral markers for tools/agents.                         |
+| `status`      | string (optional)     | Lifecycle marker (e.g. `stable`, `draft`, `deprecated`).     |
+
+Keep `subject` values unique across the project, keep `parent`/`children` consistent in both directions, and keep `files` in sync with what is actually on disk.
+
+## Automatic Documentation Maintenance (core responsibility)
+
+Maintaining xdocs files is an **automatic, built-in responsibility — not a task the user has to request.** Treat it as part of the definition of done for every code change in an xdocs project. The user should never have to ask you to document a module; you do it as a reflex whenever you touch one.
+
+**Trigger.** Whenever you, as the agent, do any of the following, you must create or update the affected directory's xdocs file in the *same unit of work*, before you consider the task finished:
+
+- Create a new directory, module, or subpackage.
+- Add, rename, move, or delete significant files in a directory.
+- Change what a module does, what it exposes, or how it relates to its parent or children.
+
+**Action.**
+
+- If the directory has **no** xdocs file, create one (for example `<name>.xdocs.md`) in that directory.
+- If it **already** has one, update it so it matches the new reality.
+- Then fix the parent/child links and verify with `<xdocs> tree`.
+
+**What every module's xdocs file must capture:**
+
+- `subject` — the module's unique name in the tree.
+- `description` — the module's **purpose**: what it is for and what it does.
+- `files` — each significant file in the directory mapped to a short description of its responsibility, **including the key functions/exports it provides**.
+- `parent` — the `subject` of the containing module (and add this module to that parent's `children`).
+- `children` — the `subject`s of the modules contained inside this one.
+
+**Do not wait to be asked.** After you finish creating or modifying a module or directory, create or update its xdocs file as part of the same change. A code change that adds or alters a module is **not complete** until its xdocs file and the affected parent/child links are updated.
+
+**How `[ai].mode` applies.** The mode controls only *how* you write the docs, never *whether* you write them and never whether the user must ask first:
+
+- `auto` — create/update the xdocs files immediately as part of the change, then report what changed.
+- `prompt` — state exactly which xdocs files you are creating or updating, then write them (honoring any pending confirmation). Announcing is for transparency; it does not make documentation optional and the user never has to request it.
+
+### Example: documenting a new module
+
+Suppose you just created `src/auth/` with `login.ts` and `session.ts`. As part of that work, create `src/auth/auth.xdocs.md`:
+
+```markdown
+---
+subject: auth
+description: Authentication and session handling for the API.
+parent: src
+children: []
+files:
+  login.ts: Email/password login flow; exports `login()` and `verifyPassword()`.
+  session.ts: Session lifecycle; exports `createSession()` and `validateSession()`.
+tags:
+  - security
+flags: []
+status: stable
+---
+
+Auth validates credentials and issues sessions. `login()` delegates password
+checks to `verifyPassword()`; sessions are created and validated in `session.ts`.
+```
+
+Then add `auth` to the `children` list of the `src` module's xdocs file so the tree stays consistent.
+
+If the directory you are documenting is the **root of a package or application** (not a sub-module), set `parent: null` instead, and list that package's root `.xdocs.md` in the repository's single `XDOCS.md` index rather than in a parent module's `children`.
+
+## Onboarding Workflow (entering a project)
+
+When you start working in a project that uses xdocs:
+
+1. Read the root `XDOCS.md` to learn the project's top-level subject and structure.
+2. Run `<xdocs> tree` to see the module hierarchy.
+3. Run `<xdocs> scan` to see documentation coverage and which directories are missing xdocs files.
+4. Read `xdocs.config.toml` and note `[ai].mode`, the supported `[extensions]`, and `[scan].exclude`.
+5. When you navigate into a module, read that module's xdocs file (frontmatter first, body only if you need more) instead of reading every source file.
+
+## Documentation Workflow (writing and updating)
+
+Follow this whenever the automatic trigger above fires, or when the user asks to document a directory:
+
+1. Determine the target directory and whether it already has an xdocs file (`<xdocs> scan` or `<xdocs> list <path>`).
+2. Read the directory's actual files so the documentation reflects reality. Never invent files, modules, or behavior that is not present.
+3. Respect `[ai].mode` (it controls how you write, not whether you write):
+   - **prompt mode**: state exactly which xdocs files you are creating or updating, then write them (honor a pending confirmation, but never skip the documentation).
+   - **auto mode**: create or update the xdocs files immediately, then report what changed.
+4. Write or update the xdocs file with correct frontmatter:
+   - Set `subject` (unique), `description` (the module's purpose), and `files` (each real file -> short purpose, including key functions/exports).
+   - Set `parent` to the containing module's `subject`, and add this `subject` to that parent's `children`.
+   - Use `tags`/`flags`/`status` where useful.
+5. Keep the tree consistent: if you add a module, update its parent's `children`; if you remove one, update both sides.
+6. Validate with `<xdocs> tree` (it reports duplicate subjects, orphans, and missing children) and fix any reported issues.
+
+When generating from scratch, prefer `<xdocs> generate <path>` (one directory) or `<xdocs> generate` (whole project) to produce a starting draft, then refine the content by hand.
+
+## Command-to-Task Mapping
+
+- "Set up xdocs here" -> `<xdocs> init`
+- "What is documented / what is missing" -> `<xdocs> scan`
+- "Show me the structure" -> `<xdocs> tree`
+- "What is in this folder" -> `<xdocs> list <path>`
+- "Draft docs for this module / project" -> `<xdocs> generate [path]`
+- "Give me one combined document" -> `<xdocs> merge [path]`
+- "Give me the AI instructions for writing/updating docs" -> `<xdocs> prompt --name=<write|update|agents|generate>`
+- "Install the xdocs skill / update AGENTS.md" -> `<xdocs> agents install <local|global>` / `<xdocs> agents instructions`
+
+## Safety Rules
+
+- Never leave a new or changed module undocumented. Creating or updating its xdocs file is part of finishing the work, not a separate request the user must make.
+- Never fabricate files, modules, descriptions, or relationships. Documentation must match the repository.
+- Never edit generated or build outputs (`library/`, `bundle/`, `bin/`, `*.tgz`). They are ignored and regenerated.
+- In prompt mode, announce the xdocs changes you will make and honor a pending confirmation — but still treat documenting the change as required, never optional.
+- Do not break tree integrity: every `child` must have a matching `parent`, and every `subject` must be unique.
+- Do not silently change a module's `subject` — it is the identity used by `parent`/`children` links across the project.
+- When `<xdocs> tree` or `<xdocs> scan` reports warnings, resolve them rather than ignoring them.
+
+## Configuration Reference
+
+xdocs searches for configuration via `--config <path>`, `./xdocs.config.toml`, or `./config/xdocs.config.toml`.
+
+```toml
+schema = 1
+
+[extensions]
+supported = [".docs.md", ".xdocs.md"]
+
+[ai]
+mode = "prompt"            # "prompt" (announce and wait) or "auto" (update immediately)
+
+[scan]
+exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
+
+[project]
+name = "my-project"
+
+[agents]
+auto_agents_md = true      # keep the xdocs section in AGENTS.md up to date on normal commands
+auto_skill_install = true  # install the guiho-as-xdocs skill globally when missing
+skill_tool = "agents"      # default tool for auto-install: agents (standard) or claude
+```
+
+Agent automation options default to true. Set `auto_agents_md = false` to stop xdocs from touching AGENTS.md, and `auto_skill_install = false` to stop xdocs from installing `guiho-as-xdocs` globally when it is missing.
+
+## CLI Reference
+
+```bash
+xdocs init                     # create XDOCS.md + xdocs.config.toml, update AGENTS.md, install the skill
+xdocs scan                     # report xdocs coverage across the project
+xdocs tree                     # print the module hierarchy
+xdocs list <path>              # list files in a scope with descriptions
+xdocs generate [path]          # draft documentation for a directory or the whole project
+xdocs merge [path]             # merge a directory's xdocs files into one document
+xdocs prompt --name=<name>     # print a ready-made AI prompt (write|update|agents|generate)
+xdocs agents install local     # install guiho-as-xdocs into this project (.agents/skills/...)
+xdocs agents install global    # install guiho-as-xdocs into the user home skills directory
+xdocs agents instructions      # insert/refresh the xdocs section in AGENTS.md
+```
+
+Global flags: `--help`, `--version`, `--cwd <path>`, `--config <path>`, `--format <text|json|markdown>`, `--verbose`. The `agents install` command also accepts `--tool <agents|claude|all>`.
+
+## Agent Skill Installation
+
+xdocs ships this `guiho-as-xdocs` skill. The **standard** target is `AGENTS.md`
+plus `.agents/skills`, which OpenCode, Codex, Jules, and any AGENTS.md-aware tool
+read. A **non-standard** Claude Code target exists and is used only when it is
+explicitly requested (`--tool claude`) or detected (a `.claude` directory or
+`CLAUDE.md` in the project).
+
+| Target                  | Skill location (local)                      |
+| ----------------------- | ------------------------------------------- |
+| **agents** (standard)   | `.agents/skills/guiho-as-xdocs/SKILL.md`    |
+| **claude** (non-standard) | `.claude/skills/guiho-as-xdocs/SKILL.md`  |
+
+`local` scope installs under the current project; `global` scope installs under
+the user home directory (`~/.agents/skills/...`). The small section in `AGENTS.md`
+written by `xdocs agents instructions` is the standard pointer that tells any
+agent to load this skill.
+
+Default to the standard target. Only install or write non-standard files
+(`.claude`, `CLAUDE.md`, etc.) when the user asks for them or when those files
+already exist in the project.
+
+## TypeScript API
+
+When the user wants automation code rather than CLI usage, use the typed API:
+
+```ts
+import { loadConfigOrDefaults, scanProject, buildTree, renderTree } from '@guiho/xdocs'
+
+const config = await loadConfigOrDefaults({ cwd: process.cwd(), format: 'text', verbose: false })
+const scan = await scanProject(config)
+const tree = buildTree(scan.xdocsFiles)
+
+console.log(renderTree(tree))
+```
+
+For agent-skill and AGENTS.md automation:
+
+```ts
+import { installSkill, ensureAgentsInstructions } from '@guiho/xdocs'
+
+await installSkill('agents', 'local', { cwd: process.cwd() })
+await ensureAgentsInstructions(process.cwd(), true)
+```
+
+## Response Style
+
+When reporting an xdocs result, include:
+
+- The command that ran and the target path.
+- Which xdocs files were created or changed, if any.
+- Tree/coverage status (subjects added, orphans or duplicates resolved).
+- The configured AI mode, and — in prompt mode — exactly what you are waiting to write.
+
+Keep the explanation short and operational. The user usually needs to know which docs changed, whether the tree is still consistent, and what (if anything) remains for them to confirm.