compose-agentsmd 3.5.1 → 5.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Compose AGENTS.md
 
-This repository contains CLI tooling for composing per-project `AGENTS.md` files from modular rule sets.
+This repository contains CLI tooling for composing repository-local and user-global agent instruction files from modular rule sets.
 
 ## Compatibility
 
@@ -24,7 +24,7 @@ This provides the `compose-agentsmd` command.
 
 ## Rules setup (this repository)
 
-The default ruleset for this repository is `agent-ruleset.json` and currently composes the `node` domain into `AGENTS.md` from the shared GitHub source.
+The default ruleset for this repository is `agent-ruleset.json` and currently composes the `node` domain into repository-local instructions from the shared GitHub source.
 
 ## Compose
 
@@ -34,14 +34,22 @@ From each project root, run:
 compose-agentsmd
 ```
 
-The tool reads `agent-ruleset.json` from the given root directory (default: current working directory), and writes the output file specified by the ruleset. If `output` is omitted, it defaults to `AGENTS.md`.
+The tool reads `agent-ruleset.json` from the given root directory (default: current working directory), and writes the repository-local output file specified by the ruleset. If `output` is omitted, it defaults to `AGENTS.md`.
 
 By default, compose also writes a `CLAUDE.md` companion file containing an `@...` import pointing to the primary output file. You can disable this with `claude.enabled: false` in the ruleset.
 
-The tool prepends a small "Tool Rules" block to every generated `AGENTS.md` so agents know how to regenerate or update rules.
-Each composed rule section is also prefixed with the source file path that produced it.
+By default, compose writes `rules/global` to these user-global instruction files with the same composed content:
 
-When the output file is `AGENTS.md`, the CLI also prints a unified diff for `AGENTS.md` when it changes (and prints `AGENTS.md unchanged.` when it does not). This works even when the project is not under git. `--quiet` and `--json` suppress this output.
+- `~/.codex/AGENTS.md`
+- `~/.claude/CLAUDE.md`
+- `~/.gemini/GEMINI.md`
+- `~/.copilot/copilot-instructions.md`
+
+Repository-local `AGENTS.md` contains the tool rules plus only the repository-facing rules (`domains` + `extra`). Global rules are no longer embedded into each repository output.
+
+Each composed rule section is prefixed with the source file path that produced it.
+
+When compose changes files, the CLI prints diffs for both repository outputs and global outputs. This works even when the project is not under git. `--quiet` and `--json` suppress this output.
 
 ## Setup (init)
 
@@ -56,11 +64,11 @@ Defaults:
 - `source`: `github:owner/repo@latest`
 - `domains`: empty
 - `extra`: empty
-- `global`: omitted (defaults to `true`)
+- `global`: omitted (defaults to `true`, meaning write user-global instruction files)
 - `claude`: `{ "enabled": true, "output": "CLAUDE.md" }`
 - `output`: `AGENTS.md`
 
-Use `--dry-run` to preview actions, `--force` to overwrite existing files, and `--compose` to generate `AGENTS.md` immediately.
+Use `--dry-run` to preview actions, `--force` to overwrite existing repository output files, and `--compose` to generate instruction files immediately.
 
 ## Updating shared rules
 
@@ -77,7 +85,7 @@ compose-agentsmd edit-rules
 compose-agentsmd apply-rules
 ```
 
-`edit-rules` clones the GitHub source into the workspace (or reuses it), then prints the workspace path, rules directory, and next steps. `apply-rules` pushes the workspace (if clean) and regenerates `AGENTS.md` by refreshing the cache. If your `source` is a local path, `edit-rules` points to the local workspace and `apply-rules` skips the push.
+`edit-rules` clones the GitHub source into the workspace (or reuses it), then prints the workspace path, rules directory, and next steps. `apply-rules` pushes the workspace (if clean) and regenerates repository/global instruction files by refreshing the cache. If your `source` is a local path, `edit-rules` points to the local workspace and `apply-rules` skips the push.
 
 ## Project ruleset format
 
@@ -91,12 +99,12 @@ Ruleset files accept JSON with `//` or `/* */` comments.
   "domains": ["node", "unreal"],
   // Additional local rule files to append.
   "extra": ["agent-rules-local/custom.md"],
-  // Optional Claude Code companion output.
+  // Optional Claude Code repository companion output.
   "claude": {
     "enabled": true,
     "output": "CLAUDE.md"
   },
-  // Output file name.
+  // Repository output file name.
   "output": "AGENTS.md"
 }
 ```
@@ -104,13 +112,18 @@ Ruleset files accept JSON with `//` or `/* */` comments.
 Ruleset keys:
 
 - `source` (required): rules source. Use `github:owner/repo@ref` or a local path.
-- `global` (optional): include `rules/global` (defaults to true). Omit this unless you want to disable globals.
+- `global` (optional): write `rules/global` to user-global instruction files (defaults to true). Set `false` to skip global writes.
 - `domains` (optional): domain folders under `rules/domains/<domain>`.
 - `extra` (optional): additional local rule files to append.
-- `claude` (optional): companion settings for Claude Code.
+- `budget` (optional): global-rule budget thresholds in `o200k_base` tokens.
+- `budget.totalTokens` (optional): total token budget for the composed global instruction output (defaults to `4500`).
+- `budget.moduleTokens` (optional): per-module token budget for each composed global rule section (defaults to `400`).
+- `claude` (optional): repository companion settings for Claude Code.
 - `claude.enabled` (optional): enable/disable companion generation (defaults to `true`).
 - `claude.output` (optional): companion file path (defaults to `CLAUDE.md`).
-- `output` (optional): output file name (defaults to `AGENTS.md`).
+- `output` (optional): repository output file name (defaults to `AGENTS.md`).
+
+When the composed global instruction output exceeds either budget, the CLI emits a warning to `stderr`. The machine-readable `--json` output includes the tokenizer name, total token count, and any over-budget modules.
 
 ### Ruleset schema validation
 
@@ -132,11 +145,11 @@ Remote sources are cached under `~/.agentsmd/cache/<owner>/<repo>/<ref>/`. Use `
 - `--source <source>`: rules source for `init`
 - `--domains <list>`: comma-separated domains for `init`
 - `--extra <list>`: comma-separated extra rules for `init`
-- `--output <file>`: output filename for `init`
+- `--output <file>`: repository output filename for `init`
 - `--no-domains`: initialize with no domains
 - `--no-extra`: initialize without extra rule files
-- `--no-global`: initialize without global rules
-- `--compose`: compose output file(s) after `init`
+- `--no-global`: initialize without user-global rules
+- `--compose`: compose repository and user-global instruction files after `init`
 - `--dry-run`: show init plan without writing files
 - `--yes`: skip init confirmation prompt
 - `--force`: overwrite existing files during init

package/agent-ruleset.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Compose AGENTS.md ruleset",
+  "title": "Compose agent instruction files ruleset",
   "type": "object",
   "additionalProperties": false,
   "required": ["source"],
@@ -10,7 +10,8 @@
       "minLength": 1
     },
     "global": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "Write rules/global to user-global instruction files."
     },
     "output": {
       "type": "string",
@@ -47,11 +48,11 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "totalLines": {
+        "totalTokens": {
           "type": "integer",
           "minimum": 1
         },
-        "moduleLines": {
+        "moduleTokens": {
           "type": "integer",
           "minimum": 1
         }

package/dist/compose-agents.js

@@ -6,9 +6,15 @@ import { execFileSync } from "node:child_process";
 import readline from "node:readline";
 import { Ajv } from "ajv";
 import { createTwoFilesPatch } from "diff";
+import { countTokens } from "gpt-tokenizer";
+import { prepareGitFallbackDestination } from "./git-fallback.js";
 const DEFAULT_RULESET_NAME = "agent-ruleset.json";
 const DEFAULT_OUTPUT = "AGENTS.md";
 const DEFAULT_CLAUDE_OUTPUT = "CLAUDE.md";
+const DEFAULT_CODEX_GLOBAL_OUTPUT = path.join(os.homedir(), ".codex", "AGENTS.md");
+const DEFAULT_CLAUDE_GLOBAL_OUTPUT = path.join(os.homedir(), ".claude", "CLAUDE.md");
+const DEFAULT_GEMINI_GLOBAL_OUTPUT = path.join(os.homedir(), ".gemini", "GEMINI.md");
+const DEFAULT_COPILOT_GLOBAL_OUTPUT = path.join(os.homedir(), ".copilot", "copilot-instructions.md");
 const DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd", "cache");
 const DEFAULT_WORKSPACE_ROOT = path.join(os.homedir(), ".agentsmd", "workspace");
 const DEFAULT_INIT_SOURCE = "github:owner/repo@latest";
@@ -18,8 +24,10 @@ const RULESET_SCHEMA_PATH = new URL("../agent-ruleset.schema.json", import.meta.
 const PACKAGE_JSON_PATH = new URL("../package.json", import.meta.url);
 const TOOL_RULES_PATH = new URL("../tools/tool-rules.md", import.meta.url);
 const USAGE_PATH = new URL("../tools/usage.txt", import.meta.url);
-const DEFAULT_TOTAL_BUDGET = 350;
-const DEFAULT_MODULE_BUDGET = 30;
+const BUDGET_TOKENIZER = "o200k_base";
+const DEFAULT_TOTAL_BUDGET = 4500;
+const DEFAULT_MODULE_BUDGET = 400;
+const LINT_HEADER = "<!-- markdownlint-disable MD025 -->";
 const readValueArg = (remaining, index, flag) => {
     const value = remaining[index + 1];
     if (!value) {
@@ -182,6 +190,22 @@ const resolveFrom = (baseDir, targetPath) => {
     }
     return path.resolve(baseDir, targetPath);
 };
+const isSubPath = (baseDir, targetPath) => {
+    const relativePath = path.relative(path.resolve(baseDir), path.resolve(targetPath));
+    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+};
+const toDisplayPath = (rootDir, filePath) => {
+    if (isSubPath(rootDir, filePath)) {
+        const relativePath = path.relative(rootDir, filePath);
+        return normalizePath(relativePath || path.basename(filePath));
+    }
+    const homeDir = os.homedir();
+    if (isSubPath(homeDir, filePath)) {
+        const relativeToHome = normalizePath(path.relative(homeDir, filePath));
+        return relativeToHome ? `~/${relativeToHome}` : "~";
+    }
+    return normalizePath(path.resolve(filePath));
+};
 const ensureDir = (dirPath) => {
     fs.mkdirSync(dirPath, { recursive: true });
 };
@@ -420,7 +444,7 @@ const cloneAtRef = (repoUrl, ref, destination) => {
     execGit(["clone", "--depth", "1", "--branch", ref, repoUrl, destination]);
 };
 const fetchCommit = (repoUrl, commitHash, destination) => {
-    ensureDir(destination);
+    prepareGitFallbackDestination(destination);
     execGit(["init"], destination);
     execGit(["remote", "add", "origin", repoUrl], destination);
     execGit(["fetch", "--depth", "1", "origin", commitHash], destination);
@@ -530,94 +554,163 @@ const formatRuleSourcePath = (rulePath, rulesRoot, rulesetDir, source, resolvedR
     const result = normalizePath(path.relative(rulesetDir, rulePath));
     return result;
 };
+const getGlobalOutputPaths = () => [
+    DEFAULT_CODEX_GLOBAL_OUTPUT,
+    DEFAULT_CLAUDE_GLOBAL_OUTPUT,
+    DEFAULT_GEMINI_GLOBAL_OUTPUT,
+    DEFAULT_COPILOT_GLOBAL_OUTPUT
+];
 const resolveOutputPaths = (rulesetDir, projectRuleset) => {
     const primaryOutputPath = resolveFrom(rulesetDir, projectRuleset.output ?? DEFAULT_OUTPUT);
     const claude = projectRuleset.claude ?? {};
     const companionEnabled = claude.enabled !== false;
     const configuredCompanionPath = resolveFrom(rulesetDir, claude.output ?? DEFAULT_CLAUDE_OUTPUT);
+    const globalOutputPaths = projectRuleset.global === false ? [] : getGlobalOutputPaths();
     if (!companionEnabled ||
         path.resolve(primaryOutputPath) === path.resolve(configuredCompanionPath)) {
-        return { primaryOutputPath };
+        return { primaryOutputPath, globalOutputPaths };
     }
-    return { primaryOutputPath, companionOutputPath: configuredCompanionPath };
+    return {
+        primaryOutputPath,
+        companionOutputPath: configuredCompanionPath,
+        globalOutputPaths
+    };
 };
 const buildClaudeCompanionContent = (primaryOutputPath, companionOutputPath) => {
     const relativeImportPath = normalizePath(path.relative(path.dirname(companionOutputPath), primaryOutputPath));
     return `@${relativeImportPath}\n`;
 };
+const buildInstructionContent = (parts, includeToolRules) => {
+    const sections = includeToolRules ? [normalizeTrailingWhitespace(TOOL_RULES), ...parts] : parts;
+    if (sections.length === 0) {
+        return "";
+    }
+    return `${LINT_HEADER}\n${sections.join("\n\n")}\n`;
+};
+const countBudgetTokens = (content) => {
+    if (content.length === 0) {
+        return 0;
+    }
+    return countTokens(content);
+};
+const buildScopeDiff = (scope, targetPaths, desiredContent, rootDir) => {
+    if (targetPaths.length === 0) {
+        return undefined;
+    }
+    const displayTargets = targetPaths.map((filePath) => toDisplayPath(rootDir, filePath));
+    const changedTargetPath = targetPaths.find((filePath) => {
+        if (!fs.existsSync(filePath)) {
+            return true;
+        }
+        return fs.readFileSync(filePath, "utf8") !== desiredContent;
+    });
+    if (!changedTargetPath) {
+        return {
+            scope,
+            targets: displayTargets,
+            status: "unchanged"
+        };
+    }
+    const before = fs.existsSync(changedTargetPath) ? fs.readFileSync(changedTargetPath, "utf8") : "";
+    const displayPath = toDisplayPath(rootDir, changedTargetPath);
+    return {
+        scope,
+        targets: displayTargets,
+        status: "updated",
+        patch: createTwoFilesPatch(`a/${displayPath}`, `b/${displayPath}`, before, desiredContent, "", "", { context: 3 })
+    };
+};
 const composeRuleset = (rulesetPath, rootDir, options) => {
     const rulesetDir = path.dirname(rulesetPath);
     const projectRuleset = readProjectRuleset(rulesetPath);
-    const { primaryOutputPath, companionOutputPath } = resolveOutputPaths(rulesetDir, projectRuleset);
-    const composedOutputPath = normalizePath(path.relative(rootDir, primaryOutputPath));
+    const { primaryOutputPath, companionOutputPath, globalOutputPaths } = resolveOutputPaths(rulesetDir, projectRuleset);
+    const composedOutputPath = toDisplayPath(rootDir, primaryOutputPath);
     const { rulesRoot, resolvedRef } = resolveRulesRoot(rulesetDir, projectRuleset.source, options.refresh ?? false);
     const globalRoot = path.join(rulesRoot, "global");
     const domainsRoot = path.join(rulesRoot, "domains");
-    const resolvedRules = [];
-    const seenRules = new Set();
+    const resolvedGlobalRules = [];
+    const seenGlobalRules = new Set();
+    const resolvedRepositoryRules = [];
+    const seenRepositoryRules = new Set();
     if (projectRuleset.global !== false) {
-        addRulePaths(collectMarkdownFiles(globalRoot), resolvedRules, seenRules);
+        addRulePaths(collectMarkdownFiles(globalRoot), resolvedGlobalRules, seenGlobalRules);
     }
     const domains = Array.isArray(projectRuleset.domains) ? projectRuleset.domains : [];
     for (const domain of domains) {
         const domainRoot = path.resolve(domainsRoot, domain);
-        addRulePaths(collectMarkdownFiles(domainRoot), resolvedRules, seenRules);
+        addRulePaths(collectMarkdownFiles(domainRoot), resolvedRepositoryRules, seenRepositoryRules);
     }
     const extraRules = Array.isArray(projectRuleset.extra) ? projectRuleset.extra : [];
     const directRulePaths = extraRules.map((rulePath) => resolveFrom(rulesetDir, rulePath));
-    addRulePaths(directRulePaths, resolvedRules, seenRules);
-    const totalBudget = projectRuleset.budget?.totalLines ?? DEFAULT_TOTAL_BUDGET;
-    const moduleBudget = projectRuleset.budget?.moduleLines ?? DEFAULT_MODULE_BUDGET;
-    const normalizedGlobalRoot = normalizePath(path.resolve(globalRoot));
-    const globalRuleFiles = resolvedRules.filter((p) => normalizePath(p).startsWith(`${normalizedGlobalRoot}/`));
-    const moduleLineCounts = globalRuleFiles.map((filePath) => {
-        const content = fs.readFileSync(filePath, "utf8");
-        return { name: path.basename(filePath), lines: content.split("\n").length };
+    addRulePaths(directRulePaths, resolvedRepositoryRules, seenRepositoryRules);
+    const totalBudget = projectRuleset.budget?.totalTokens ?? DEFAULT_TOTAL_BUDGET;
+    const moduleBudget = projectRuleset.budget?.moduleTokens ?? DEFAULT_MODULE_BUDGET;
+    const buildRuleParts = (rulePaths) => rulePaths.map((rulePath) => {
+        const body = normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8"));
+        const sourcePath = formatRuleSourcePath(rulePath, rulesRoot, rulesetDir, projectRuleset.source, resolvedRef);
+        return {
+            name: path.basename(rulePath),
+            content: `Source: ${sourcePath}\n\n${body}`
+        };
     });
-    const totalLines = moduleLineCounts.reduce((sum, m) => sum + m.lines, 0);
-    const overBudgetModules = moduleLineCounts.filter((m) => m.lines > moduleBudget);
+    const repositoryParts = buildRuleParts(resolvedRepositoryRules);
+    const globalParts = buildRuleParts(resolvedGlobalRules);
+    const repositoryContentParts = repositoryParts.map((part) => part.content);
+    const globalContentParts = globalParts.map((part) => part.content);
+    const primaryOutputContent = buildInstructionContent(repositoryContentParts, true);
+    const globalOutputContent = buildInstructionContent(globalContentParts, false);
+    const moduleTokenCounts = globalParts.map((part) => ({
+        name: part.name,
+        tokens: countBudgetTokens(part.content)
+    }));
+    const totalTokens = countBudgetTokens(globalOutputContent);
+    const overBudgetModules = moduleTokenCounts.filter((module) => module.tokens > moduleBudget);
     const budgetResult = {
-        totalLines,
+        tokenizer: BUDGET_TOKENIZER,
+        totalTokens,
         totalBudget,
         moduleBudget,
         overBudgetModules,
-        exceeded: totalLines > totalBudget || overBudgetModules.length > 0
+        exceeded: totalTokens > totalBudget || overBudgetModules.length > 0
     };
-    const parts = resolvedRules.map((rulePath) => {
-        const body = normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8"));
-        const sourcePath = formatRuleSourcePath(rulePath, rulesRoot, rulesetDir, projectRuleset.source, resolvedRef);
-        return `Source: ${sourcePath}\n\n${body}`;
-    });
-    const lintHeader = "<!-- markdownlint-disable MD025 -->";
-    const toolRules = normalizeTrailingWhitespace(TOOL_RULES);
-    const primaryOutputContent = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
+    const repositoryOutputs = [toDisplayPath(rootDir, primaryOutputPath)];
+    const globalOutputs = globalOutputPaths.map((filePath) => toDisplayPath(rootDir, filePath));
     const composedFiles = [
         {
             absolutePath: primaryOutputPath,
-            relativePath: composedOutputPath,
-            content: primaryOutputContent
+            relativePath: toDisplayPath(rootDir, primaryOutputPath),
+            content: primaryOutputContent,
+            scope: "repository"
         }
     ];
     if (companionOutputPath) {
+        const companionDisplayPath = toDisplayPath(rootDir, companionOutputPath);
+        repositoryOutputs.push(companionDisplayPath);
         composedFiles.push({
             absolutePath: companionOutputPath,
-            relativePath: normalizePath(path.relative(rootDir, companionOutputPath)),
-            content: buildClaudeCompanionContent(primaryOutputPath, companionOutputPath)
+            relativePath: companionDisplayPath,
+            content: buildClaudeCompanionContent(primaryOutputPath, companionOutputPath),
+            scope: "repository"
         });
     }
-    let agentsMdDiff;
-    if (options.emitAgentsMdDiff && path.basename(primaryOutputPath) === DEFAULT_OUTPUT) {
-        const before = fs.existsSync(primaryOutputPath)
-            ? fs.readFileSync(primaryOutputPath, "utf8")
-            : "";
-        if (before === primaryOutputContent) {
-            agentsMdDiff = { status: "unchanged" };
+    for (const globalOutputPath of globalOutputPaths) {
+        composedFiles.push({
+            absolutePath: globalOutputPath,
+            relativePath: toDisplayPath(rootDir, globalOutputPath),
+            content: globalOutputContent,
+            scope: "global"
+        });
+    }
+    const outputDiffs = [];
+    if (options.emitDiffs) {
+        const repositoryDiff = buildScopeDiff("repository", [primaryOutputPath], primaryOutputContent, rootDir);
+        if (repositoryDiff) {
+            repositoryDiff.targets = repositoryOutputs;
+            outputDiffs.push(repositoryDiff);
         }
-        else {
-            agentsMdDiff = {
-                status: "updated",
-                patch: createTwoFilesPatch(`a/${composedOutputPath}`, `b/${composedOutputPath}`, before, primaryOutputContent, "", "", { context: 3 })
-            };
+        const globalDiff = buildScopeDiff("global", globalOutputPaths, globalOutputContent, rootDir);
+        if (globalDiff) {
+            outputDiffs.push(globalDiff);
         }
     }
     if (!options.dryRun) {
@@ -628,38 +721,53 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     }
     return {
         output: composedOutputPath,
-        outputs: composedFiles.map((file) => file.relativePath),
-        agentsMdDiff,
+        outputs: [...repositoryOutputs, ...globalOutputs],
+        repositoryOutputs,
+        globalOutputs,
+        outputDiffs,
         budgetResult
     };
 };
-const printAgentsMdDiffIfPresent = (result) => {
-    if (!result.agentsMdDiff) {
-        return;
+const printOutputDiffs = (result) => {
+    for (const diff of result.outputDiffs) {
+        const scopeLabel = diff.scope === "global" ? "Global outputs" : "Repository outputs";
+        if (diff.status === "unchanged") {
+            process.stdout.write(`${scopeLabel} unchanged.\n`);
+            continue;
+        }
+        process.stdout.write(`${scopeLabel} updated. ACTION (agent): refresh rule recognition from the diff below.\n`);
+        process.stdout.write(`Targets:\n${diff.targets.map((target) => `- ${target}`).join("\n")}\n`);
+        process.stdout.write(`--- BEGIN ${diff.scope.toUpperCase()} DIFF ---\n`);
+        if (diff.patch) {
+            process.stdout.write(diff.patch);
+            if (!diff.patch.endsWith("\n")) {
+                process.stdout.write("\n");
+            }
+        }
+        process.stdout.write(`--- END ${diff.scope.toUpperCase()} DIFF ---\n`);
     }
-    if (result.agentsMdDiff.status === "unchanged") {
-        process.stdout.write("AGENTS.md unchanged.\n");
-        return;
+};
+const formatComposedOutputs = (result) => {
+    const lines = ["Composed instruction files:"];
+    if (result.repositoryOutputs.length > 0) {
+        lines.push("Repository:");
+        lines.push(...result.repositoryOutputs.map((filePath) => `- ${filePath}`));
     }
-    process.stdout.write("AGENTS.md updated. ACTION (agent): refresh rule recognition from the diff below.\n");
-    process.stdout.write("--- BEGIN DIFF ---\n");
-    if (result.agentsMdDiff.patch) {
-        process.stdout.write(result.agentsMdDiff.patch);
-        if (!result.agentsMdDiff.patch.endsWith("\n")) {
-            process.stdout.write("\n");
-        }
+    if (result.globalOutputs.length > 0) {
+        lines.push("Global:");
+        lines.push(...result.globalOutputs.map((filePath) => `- ${filePath}`));
     }
-    process.stdout.write("--- END DIFF ---\n");
+    return `${lines.join("\n")}\n`;
 };
 const formatBudgetWarning = (result) => {
-    const totalInfo = result.totalLines > result.totalBudget
-        ? `: ${result.totalLines}/${result.totalBudget} lines`
+    const totalInfo = result.totalTokens > result.totalBudget
+        ? `: ${result.totalTokens}/${result.totalBudget} tokens`
         : "";
-    const lines = [`⚠ Global rules budget exceeded${totalInfo}`];
+    const lines = [`⚠ Global rules budget exceeded (${result.tokenizer})${totalInfo}`];
     if (result.overBudgetModules.length > 0) {
-        lines.push(`  Over-budget modules (>${result.moduleBudget} lines):`);
+        lines.push(`  Over-budget modules (> ${result.moduleBudget} tokens):`);
         for (const mod of result.overBudgetModules) {
-            lines.push(`    ${mod.name}: ${mod.lines} lines`);
+            lines.push(`    ${mod.name}: ${mod.tokens} tokens`);
         }
     }
     return `${lines.join("\n")}\n`;
@@ -704,7 +812,7 @@ const formatInitRuleset = (ruleset) => {
         `  "extra": ${extraValue},`
     ];
     if (ruleset.global === false) {
-        lines.push("  // Include rules/global from the source.");
+        lines.push("  // Write shared global rules to user-level instruction files.");
         lines.push('  "global": false,');
     }
     lines.push("  // Claude Code companion output settings.");
@@ -720,7 +828,7 @@ const formatInitRuleset = (ruleset) => {
 const formatPlan = (items, rootDir) => {
     const lines = items.map((item) => {
         const verb = item.action === "overwrite" ? "Overwrite" : "Create";
-        const relative = normalizePath(path.relative(rootDir, item.path));
+        const relative = toDisplayPath(rootDir, item.path);
         return `- ${verb}: ${relative}`;
     });
     return `Init plan:\n${lines.join("\n")}\n`;
@@ -768,19 +876,25 @@ const initProject = async (args, rootDir, rulesetName) => {
         extraToWrite.push(extraPath);
     }
     if (args.compose) {
-        const composedTargets = [outputPaths.primaryOutputPath];
+        const composedTargets = [
+            { path: outputPaths.primaryOutputPath, requireForce: true },
+            ...outputPaths.globalOutputPaths.map((outputPath) => ({
+                path: outputPath,
+                requireForce: false
+            }))
+        ];
         if (outputPaths.companionOutputPath) {
-            composedTargets.push(outputPaths.companionOutputPath);
+            composedTargets.push({ path: outputPaths.companionOutputPath, requireForce: true });
         }
         for (const composedTarget of composedTargets) {
-            if (fs.existsSync(composedTarget)) {
-                if (!args.force) {
-                    throw new Error(`Output already exists: ${normalizePath(composedTarget)} (use --force to overwrite)`);
+            if (fs.existsSync(composedTarget.path)) {
+                if (composedTarget.requireForce && !args.force) {
+                    throw new Error(`Output already exists: ${normalizePath(composedTarget.path)} (use --force to overwrite)`);
                 }
-                plan.push({ action: "overwrite", path: composedTarget });
+                plan.push({ action: "overwrite", path: composedTarget.path });
             }
             else {
-                plan.push({ action: "create", path: composedTarget });
+                plan.push({ action: "create", path: composedTarget.path });
             }
         }
     }
@@ -793,7 +907,7 @@ const initProject = async (args, rootDir, rulesetName) => {
                 dryRun: true,
                 plan: plan.map((item) => ({
                     action: item.action,
-                    path: normalizePath(path.relative(rootDir, item.path))
+                    path: toDisplayPath(rootDir, item.path)
                 }))
             }, null, 2) + "\n");
         }
@@ -813,28 +927,30 @@ const initProject = async (args, rootDir, rulesetName) => {
     if (args.compose) {
         composedOutput = composeRuleset(rulesetPath, rootDir, {
             refresh: args.refresh ?? false,
-            emitAgentsMdDiff: !args.quiet && !args.json
+            emitDiffs: !args.quiet && !args.json
         });
     }
     if (args.json) {
         process.stdout.write(JSON.stringify({
-            initialized: [normalizePath(path.relative(rootDir, rulesetPath))],
-            localRules: extraToWrite.map((filePath) => normalizePath(path.relative(rootDir, filePath))),
+            initialized: [toDisplayPath(rootDir, rulesetPath)],
+            localRules: extraToWrite.map((filePath) => toDisplayPath(rootDir, filePath)),
             composed: composedOutput ? composedOutput.outputs : [],
+            repositoryOutputs: composedOutput ? composedOutput.repositoryOutputs : [],
+            globalOutputs: composedOutput ? composedOutput.globalOutputs : [],
             dryRun: false,
             ...(composedOutput ? { budget: composedOutput.budgetResult } : {})
         }, null, 2) + "\n");
     }
     else if (!args.quiet) {
-        process.stdout.write(`Initialized ruleset:\n- ${normalizePath(path.relative(rootDir, rulesetPath))}\n`);
+        process.stdout.write(`Initialized ruleset:\n- ${toDisplayPath(rootDir, rulesetPath)}\n`);
         if (extraToWrite.length > 0) {
             process.stdout.write(`Initialized local rules:\n${extraToWrite
-                .map((filePath) => `- ${normalizePath(path.relative(rootDir, filePath))}`)
+                .map((filePath) => `- ${toDisplayPath(rootDir, filePath)}`)
                 .join("\n")}\n`);
         }
         if (composedOutput) {
-            process.stdout.write(`Composed AGENTS.md:\n${composedOutput.outputs.map((filePath) => `- ${filePath}`).join("\n")}\n`);
-            printAgentsMdDiffIfPresent(composedOutput);
+            process.stdout.write(formatComposedOutputs(composedOutput));
+            printOutputDiffs(composedOutput);
             if (composedOutput.budgetResult.exceeded) {
                 process.stderr.write(formatBudgetWarning(composedOutput.budgetResult));
             }
@@ -905,7 +1021,7 @@ const main = async () => {
             "Next steps:",
             `- Edit rule files under: ${rulesDirectory}`,
             "- If this source is GitHub, commit and push the workspace changes before apply-rules.",
-            "- Run compose-agentsmd apply-rules from your project root to apply updates and regenerate AGENTS.md."
+            "- Run compose-agentsmd apply-rules from your project root to apply updates and regenerate instruction files."
         ].join("\n") + "\n");
         return;
     }
@@ -921,14 +1037,20 @@ const main = async () => {
         const output = composeRuleset(rulesetPath, rootDir, {
             refresh: true,
             dryRun: args.dryRun,
-            emitAgentsMdDiff: !args.quiet && !args.json
+            emitDiffs: !args.quiet && !args.json
         });
         if (args.json) {
-            process.stdout.write(JSON.stringify({ composed: output.outputs, dryRun: !!args.dryRun, budget: output.budgetResult }, null, 2) + "\n");
+            process.stdout.write(JSON.stringify({
+                composed: output.outputs,
+                repositoryOutputs: output.repositoryOutputs,
+                globalOutputs: output.globalOutputs,
+                dryRun: !!args.dryRun,
+                budget: output.budgetResult
+            }, null, 2) + "\n");
         }
         else if (!args.quiet) {
-            process.stdout.write(`Composed AGENTS.md:\n${output.outputs.map((filePath) => `- ${filePath}`).join("\n")}\n`);
-            printAgentsMdDiffIfPresent(output);
+            process.stdout.write(formatComposedOutputs(output));
+            printOutputDiffs(output);
             if (output.budgetResult.exceeded) {
                 process.stderr.write(formatBudgetWarning(output.budgetResult));
             }
@@ -942,22 +1064,28 @@ const main = async () => {
     const outputs = rulesetFiles.sort().map((rulesetPath) => composeRuleset(rulesetPath, rootDir, {
         refresh: args.refresh,
         dryRun: args.dryRun,
-        emitAgentsMdDiff: !args.quiet && !args.json
+        emitDiffs: !args.quiet && !args.json
     }));
     if (args.json) {
         process.stdout.write(JSON.stringify({
             composed: outputs.flatMap((result) => result.outputs),
+            repositoryOutputs: outputs.flatMap((result) => result.repositoryOutputs),
+            globalOutputs: outputs.flatMap((result) => result.globalOutputs),
             dryRun: !!args.dryRun,
             budget: outputs[0].budgetResult
         }, null, 2) + "\n");
     }
     else if (!args.quiet) {
-        process.stdout.write(`Composed AGENTS.md:\n${outputs
-            .flatMap((result) => result.outputs)
-            .map((filePath) => `- ${filePath}`)
-            .join("\n")}\n`);
+        process.stdout.write(formatComposedOutputs({
+            output: outputs[0].output,
+            outputs: outputs.flatMap((result) => result.outputs),
+            repositoryOutputs: outputs.flatMap((result) => result.repositoryOutputs),
+            globalOutputs: outputs.flatMap((result) => result.globalOutputs),
+            outputDiffs: [],
+            budgetResult: outputs[0].budgetResult
+        }));
         for (const result of outputs) {
-            printAgentsMdDiffIfPresent(result);
+            printOutputDiffs(result);
         }
         for (const result of outputs) {
             if (result.budgetResult.exceeded) {

package/dist/git-fallback.js

@@ -0,0 +1,7 @@
+import fs from "node:fs";
+export const prepareGitFallbackDestination = (destination) => {
+    if (fs.existsSync(destination)) {
+        fs.rmSync(destination, { recursive: true, force: true });
+    }
+    fs.mkdirSync(destination, { recursive: true });
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "compose-agentsmd",
-  "version": "3.5.1",
-  "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
+  "version": "5.0.0",
+  "description": "CLI tools for composing repository-local and user-global agent instruction files from modular rule sets",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -62,10 +62,12 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "diff": "^8.0.3"
+    "diff": "^8.0.3",
+    "gpt-tokenizer": "^3.4.0"
   },
   "overrides": {
-    "minimatch": "^10.2.2"
+    "minimatch": "^10.2.4",
+    "rollup": "^4.59.0"
   },
   "lint-staged": {
     "**/*.ts": [

package/tools/usage.txt

@@ -12,11 +12,11 @@ Options:
   --source <source>    Rules source for init (default: github:owner/repo@latest)
   --domains <list>     Comma-separated domains for init (default: none)
   --extra <list>       Comma-separated extra rules for init
-  --output <file>      Output filename for init (default: AGENTS.md)
+  --output <file>      Repository output filename for init (default: AGENTS.md)
   --no-domains         Initialize with no domains
   --no-extra           Initialize without extra rule files
-  --no-global          Initialize without global rules
-  --compose            Compose output file(s) after init
+  --no-global          Initialize without user-global rules
+  --compose            Compose repository and user-global instruction files after init
   --dry-run            Show init plan without writing files
   --yes                Skip init confirmation prompt
   --force              Overwrite existing files during init