@guiho/xdocs 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # GUIHO XDocs Changelog
 
+## 0.2.3
+
+- `xdocs agents instructions` and config-gated AGENTS.md automation now tolerate formatter-only blank lines and trailing whitespace inside the managed xdocs block, preserving the user's formatted block when the actual text is unchanged.
+- Update the managed AGENTS.md xdocs block wording to match the current repository model: one root `XDOCS.md` index and package/application root `.xdocs.md` files.
+
 ## 0.2.2
 
 - Fix: the published library crashed under Node (`ERR_UNKNOWN_FILE_EXTENSION` for `.md`) because the prompts and the `guiho-as-xdocs` skill were loaded with Bun-only text imports. They are now read from disk at runtime (`readFileSync` relative to `import.meta.url`), so the `xdocs` CLI and the library work under both Node and Bun.

package/DOCS.md

@@ -247,6 +247,12 @@ xdocs agents instructions             # insert/refresh the AGENTS.md section
 - `install global`: Writes the skill under the user home skills directory.
 - `instructions`: Creates or refreshes the xdocs section in `AGENTS.md`.
 
+When refreshing the `AGENTS.md` section, XDocs compares the existing section to
+the canonical section while ignoring blank-only lines and trailing whitespace.
+This means Markdown formatters that add blank lines around the section markers do
+not cause repeated rewrites. Real text changes are still replaced with the
+canonical section.
+
 Flags: `--tool <agents|claude|all>`, `--format <text|json>`, `--cwd`.
 
 When `--tool` is omitted, XDocs installs the standard target and adds the Claude target only when a `.claude/` directory or `CLAUDE.md` is detected in the project. Global skill installation uses the user home directory; tests and automation can override that home root with `XDOCS_AGENT_HOME`.
@@ -405,7 +411,7 @@ The API uses the same configuration discovery and validation as the CLI.
 - `source/flags.ts`: argument/flag parsing utilities.
 - `source/errors.ts`: `XDocsError` with stable exit codes and the `invariant` helper.
 - `source/types.ts`: public and internal TypeScript types.
-- `source/agents.ts`: agent skill installation (standard/claude, local/global), AGENTS.md section management, detection, and config-gated automation. Embeds `skills/guiho-as-xdocs/SKILL.md` via a Bun text import.
+- `source/agents.ts`: agent skill installation (standard/claude, local/global), AGENTS.md section management, detection, and config-gated automation. Reads `skills/guiho-as-xdocs/SKILL.md` from disk at runtime relative to `import.meta.url`.
 - `source/commands/*.ts`: one file per CLI command (`init`, `scan`, `generate`, `prompt`, `merge`, `tree`, `list`, `agents`).
 - `prompts/*.md`: prompt templates embedded at build time.
 - `skills/guiho-as-xdocs/SKILL.md`: bundled AI-agent skill installed by `xdocs agents` commands.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "exports": "./source/guiho-xdocs.ts",
   "publish": {
     "include": [

package/library/agents.d.ts

@@ -34,7 +34,7 @@ export declare const detectAgentTools: (cwd: string) => XDocsAgentTool[];
  */
 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 -->";
+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. The repository has one root `XDOCS.md` index (no frontmatter),\nand each package/application has a root `.xdocs.md` file. Each module carries a\n`.docs.md` / `.xdocs.md` file with YAML frontmatter (`subject`, `description`,\n`parent`, `children`, `files`).\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;

package/library/agents.d.ts.map

@@ -1 +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"}
+{"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,ohCAoBV,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;AA4BD,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

@@ -78,9 +78,10 @@ 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.
+documentation. The repository has one root \`XDOCS.md\` index (no frontmatter),
+and each package/application has a root \`.xdocs.md\` file. Each module carries a
+\`.docs.md\` / \`.xdocs.md\` file with YAML frontmatter (\`subject\`, \`description\`,
+\`parent\`, \`children\`, \`files\`).
 
 **Load the \`${xdocsSkillName}\` agent skill** for any documentation work:
 creating, updating, regenerating, scanning, merging, or navigating xdocs files.
@@ -149,12 +150,22 @@ 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 blockEnd = end + AGENTS_END_MARKER.length;
+        const currentBlock = content.slice(begin, blockEnd);
+        if (normalizeAgentsSection(currentBlock) === normalizeAgentsSection(xdocsAgentsSection))
+            return content;
         const before = content.slice(0, begin);
-        const after = content.slice(end + AGENTS_END_MARKER.length);
+        const after = content.slice(blockEnd);
         return `${before}${xdocsAgentsSection}${after}`;
     }
     return `${content.trimEnd()}\n\n${xdocsAgentsSection}\n`;
 };
+/** Ignore blank-only lines and trailing whitespace when comparing formatted sections. */
+const normalizeAgentsSection = (content) => content
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0)
+    .join('\n');
 /** Walk up from cwd to find the nearest AGENTS.md. */
 export const findAgentsFile = (cwd) => {
     let current = resolve(cwd);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",