@tolkbot/cli 0.8.0 → 0.9.0

package/dist/index.js

@@ -105,7 +105,7 @@ var require_path = __commonJS({
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.convertPosixPathToPattern = exports.convertWindowsPathToPattern = exports.convertPathToPattern = exports.escapePosixPath = exports.escapeWindowsPath = exports.escape = exports.removeLeadingDotSegment = exports.makeAbsolute = exports.unixify = void 0;
     var os3 = __require("os");
-    var path11 = __require("path");
+    var path12 = __require("path");
     var IS_WINDOWS_PLATFORM = os3.platform() === "win32";
     var LEADING_DOT_SEGMENT_CHARACTERS_COUNT = 2;
     var POSIX_UNESCAPED_GLOB_SYMBOLS_RE = /(\\?)([()*?[\]{|}]|^!|[!+@](?=\()|\\(?![!()*+?@[\]{|}]))/g;
@@ -117,7 +117,7 @@ var require_path = __commonJS({
     }
     exports.unixify = unixify;
     function makeAbsolute(cwd, filepath) {
-      return path11.resolve(cwd, filepath);
+      return path12.resolve(cwd, filepath);
     }
     exports.makeAbsolute = makeAbsolute;
     function removeLeadingDotSegment(entry) {
@@ -1416,7 +1416,7 @@ var require_braces = __commonJS({
 var require_constants2 = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/constants.js"(exports, module) {
     "use strict";
-    var path11 = __require("path");
+    var path12 = __require("path");
     var WIN_SLASH = "\\\\/";
     var WIN_NO_SLASH = `[^${WIN_SLASH}]`;
     var DEFAULT_MAX_EXTGLOB_RECURSION = 0;
@@ -1590,7 +1590,7 @@ var require_constants2 = __commonJS({
       /* | */
       CHAR_ZERO_WIDTH_NOBREAK_SPACE: 65279,
       /* \uFEFF */
-      SEP: path11.sep,
+      SEP: path12.sep,
       /**
        * Create EXTGLOB_CHARS
        */
@@ -1617,7 +1617,7 @@ var require_constants2 = __commonJS({
 var require_utils2 = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/utils.js"(exports) {
     "use strict";
-    var path11 = __require("path");
+    var path12 = __require("path");
     var win32 = process.platform === "win32";
     var {
       REGEX_BACKSLASH,
@@ -1646,7 +1646,7 @@ var require_utils2 = __commonJS({
       if (options && typeof options.windows === "boolean") {
         return options.windows;
       }
-      return win32 === true || path11.sep === "\\";
+      return win32 === true || path12.sep === "\\";
     };
     exports.escapeLast = (input2, char, lastIdx) => {
       const idx = input2.lastIndexOf(char, lastIdx);
@@ -3010,7 +3010,7 @@ var require_parse2 = __commonJS({
 var require_picomatch = __commonJS({
   "../../node_modules/.pnpm/picomatch@2.3.2/node_modules/picomatch/lib/picomatch.js"(exports, module) {
     "use strict";
-    var path11 = __require("path");
+    var path12 = __require("path");
     var scan = require_scan();
     var parse4 = require_parse2();
     var utils = require_utils2();
@@ -3095,7 +3095,7 @@ var require_picomatch = __commonJS({
     };
     picomatch.matchBase = (input2, glob, options, posix = utils.isWindows(options)) => {
       const regex = glob instanceof RegExp ? glob : picomatch.makeRe(glob, options);
-      return regex.test(path11.basename(input2));
+      return regex.test(path12.basename(input2));
     };
     picomatch.isMatch = (str, patterns, options) => picomatch(patterns, options)(str);
     picomatch.parse = (pattern, options) => {
@@ -3322,7 +3322,7 @@ var require_pattern = __commonJS({
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.isAbsolute = exports.partitionAbsoluteAndRelative = exports.removeDuplicateSlashes = exports.matchAny = exports.convertPatternsToRe = exports.makeRe = exports.getPatternParts = exports.expandBraceExpansion = exports.expandPatternsWithBraceExpansion = exports.isAffectDepthOfReadingPattern = exports.endsWithSlashGlobStar = exports.hasGlobStar = exports.getBaseDirectory = exports.isPatternRelatedToParentDirectory = exports.getPatternsOutsideCurrentDirectory = exports.getPatternsInsideCurrentDirectory = exports.getPositivePatterns = exports.getNegativePatterns = exports.isPositivePattern = exports.isNegativePattern = exports.convertToNegativePattern = exports.convertToPositivePattern = exports.isDynamicPattern = exports.isStaticPattern = void 0;
-    var path11 = __require("path");
+    var path12 = __require("path");
     var globParent = require_glob_parent();
     var micromatch = require_micromatch();
     var GLOBSTAR = "**";
@@ -3417,7 +3417,7 @@ var require_pattern = __commonJS({
     }
     exports.endsWithSlashGlobStar = endsWithSlashGlobStar;
     function isAffectDepthOfReadingPattern(pattern) {
-      const basename = path11.basename(pattern);
+      const basename = path12.basename(pattern);
       return endsWithSlashGlobStar(pattern) || isStaticPattern(basename);
     }
     exports.isAffectDepthOfReadingPattern = isAffectDepthOfReadingPattern;
@@ -3475,7 +3475,7 @@ var require_pattern = __commonJS({
     }
     exports.partitionAbsoluteAndRelative = partitionAbsoluteAndRelative;
     function isAbsolute(pattern) {
-      return path11.isAbsolute(pattern);
+      return path12.isAbsolute(pattern);
     }
     exports.isAbsolute = isAbsolute;
   }
@@ -3652,8 +3652,8 @@ var require_utils3 = __commonJS({
     exports.errno = errno;
     var fs10 = require_fs();
     exports.fs = fs10;
-    var path11 = require_path();
-    exports.path = path11;
+    var path12 = require_path();
+    exports.path = path12;
     var pattern = require_pattern();
     exports.pattern = pattern;
     var stream = require_stream();
@@ -3765,8 +3765,8 @@ var require_async = __commonJS({
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.read = void 0;
-    function read(path11, settings, callback) {
-      settings.fs.lstat(path11, (lstatError, lstat) => {
+    function read(path12, settings, callback) {
+      settings.fs.lstat(path12, (lstatError, lstat) => {
         if (lstatError !== null) {
           callFailureCallback(callback, lstatError);
           return;
@@ -3775,7 +3775,7 @@ var require_async = __commonJS({
           callSuccessCallback(callback, lstat);
           return;
         }
-        settings.fs.stat(path11, (statError, stat) => {
+        settings.fs.stat(path12, (statError, stat) => {
           if (statError !== null) {
             if (settings.throwErrorOnBrokenSymbolicLink) {
               callFailureCallback(callback, statError);
@@ -3807,13 +3807,13 @@ var require_sync = __commonJS({
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.read = void 0;
-    function read(path11, settings) {
-      const lstat = settings.fs.lstatSync(path11);
+    function read(path12, settings) {
+      const lstat = settings.fs.lstatSync(path12);
       if (!lstat.isSymbolicLink() || !settings.followSymbolicLink) {
         return lstat;
       }
       try {
-        const stat = settings.fs.statSync(path11);
+        const stat = settings.fs.statSync(path12);
         if (settings.markSymbolicLink) {
           stat.isSymbolicLink = () => true;
         }
@@ -3884,17 +3884,17 @@ var require_out = __commonJS({
     var sync = require_sync();
     var settings_1 = require_settings();
     exports.Settings = settings_1.default;
-    function stat(path11, optionsOrSettingsOrCallback, callback) {
+    function stat(path12, optionsOrSettingsOrCallback, callback) {
       if (typeof optionsOrSettingsOrCallback === "function") {
-        async.read(path11, getSettings(), optionsOrSettingsOrCallback);
+        async.read(path12, getSettings(), optionsOrSettingsOrCallback);
         return;
       }
-      async.read(path11, getSettings(optionsOrSettingsOrCallback), callback);
+      async.read(path12, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports.stat = stat;
-    function statSync2(path11, optionsOrSettings) {
+    function statSync2(path12, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
-      return sync.read(path11, settings);
+      return sync.read(path12, settings);
     }
     exports.statSync = statSync2;
     function getSettings(settingsOrOptions = {}) {
@@ -4112,16 +4112,16 @@ var require_async2 = __commonJS({
           return;
         }
         const tasks = names.map((name) => {
-          const path11 = common.joinPathSegments(directory, name, settings.pathSegmentSeparator);
+          const path12 = common.joinPathSegments(directory, name, settings.pathSegmentSeparator);
           return (done) => {
-            fsStat.stat(path11, settings.fsStatSettings, (error62, stats) => {
+            fsStat.stat(path12, settings.fsStatSettings, (error62, stats) => {
               if (error62 !== null) {
                 done(error62);
                 return;
               }
               const entry = {
                 name,
-                path: path11,
+                path: path12,
                 dirent: utils.fs.createDirentFromStats(name, stats)
               };
               if (settings.stats) {
@@ -4239,7 +4239,7 @@ var require_settings2 = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.scandir@2.1.5/node_modules/@nodelib/fs.scandir/out/settings.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    var path11 = __require("path");
+    var path12 = __require("path");
     var fsStat = require_out();
     var fs10 = require_fs4();
     var Settings = class {
@@ -4247,7 +4247,7 @@ var require_settings2 = __commonJS({
         this._options = _options;
         this.followSymbolicLinks = this._getValue(this._options.followSymbolicLinks, false);
         this.fs = fs10.createFileSystemAdapter(this._options.fs);
-        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path11.sep);
+        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path12.sep);
         this.stats = this._getValue(this._options.stats, false);
         this.throwErrorOnBrokenSymbolicLink = this._getValue(this._options.throwErrorOnBrokenSymbolicLink, true);
         this.fsStatSettings = new fsStat.Settings({
@@ -4274,17 +4274,17 @@ var require_out2 = __commonJS({
     var sync = require_sync2();
     var settings_1 = require_settings2();
     exports.Settings = settings_1.default;
-    function scandir(path11, optionsOrSettingsOrCallback, callback) {
+    function scandir(path12, optionsOrSettingsOrCallback, callback) {
       if (typeof optionsOrSettingsOrCallback === "function") {
-        async.read(path11, getSettings(), optionsOrSettingsOrCallback);
+        async.read(path12, getSettings(), optionsOrSettingsOrCallback);
         return;
       }
-      async.read(path11, getSettings(optionsOrSettingsOrCallback), callback);
+      async.read(path12, getSettings(optionsOrSettingsOrCallback), callback);
     }
     exports.scandir = scandir;
-    function scandirSync(path11, optionsOrSettings) {
+    function scandirSync(path12, optionsOrSettings) {
       const settings = getSettings(optionsOrSettings);
-      return sync.read(path11, settings);
+      return sync.read(path12, settings);
     }
     exports.scandirSync = scandirSync;
     function getSettings(settingsOrOptions = {}) {
@@ -4932,7 +4932,7 @@ var require_settings3 = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.walk@1.2.8/node_modules/@nodelib/fs.walk/out/settings.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    var path11 = __require("path");
+    var path12 = __require("path");
     var fsScandir = require_out2();
     var Settings = class {
       constructor(_options = {}) {
@@ -4942,7 +4942,7 @@ var require_settings3 = __commonJS({
         this.deepFilter = this._getValue(this._options.deepFilter, null);
         this.entryFilter = this._getValue(this._options.entryFilter, null);
         this.errorFilter = this._getValue(this._options.errorFilter, null);
-        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path11.sep);
+        this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path12.sep);
         this.fsScandirSettings = new fsScandir.Settings({
           followSymbolicLinks: this._options.followSymbolicLinks,
           fs: this._options.fs,
@@ -5004,7 +5004,7 @@ var require_reader2 = __commonJS({
   "../../node_modules/.pnpm/fast-glob@3.3.3/node_modules/fast-glob/out/readers/reader.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    var path11 = __require("path");
+    var path12 = __require("path");
     var fsStat = require_out();
     var utils = require_utils3();
     var Reader = class {
@@ -5017,7 +5017,7 @@ var require_reader2 = __commonJS({
         });
       }
       _getFullEntryPath(filepath) {
-        return path11.resolve(this._settings.cwd, filepath);
+        return path12.resolve(this._settings.cwd, filepath);
       }
       _makeEntry(stats, pattern) {
         const entry = {
@@ -5433,7 +5433,7 @@ var require_provider = __commonJS({
   "../../node_modules/.pnpm/fast-glob@3.3.3/node_modules/fast-glob/out/providers/provider.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    var path11 = __require("path");
+    var path12 = __require("path");
     var deep_1 = require_deep();
     var entry_1 = require_entry();
     var error_1 = require_error();
@@ -5447,7 +5447,7 @@ var require_provider = __commonJS({
         this.entryTransformer = new entry_2.default(this._settings);
       }
       _getRootDirectory(task) {
-        return path11.resolve(this._settings.cwd, task.base);
+        return path12.resolve(this._settings.cwd, task.base);
       }
       _getReaderOptions(task) {
         const basePath = task.base === "." ? "" : task.base;
@@ -5787,7 +5787,7 @@ var require_out4 = __commonJS({
 import { Command as Command10, CommanderError, Option as Option2 } from "commander";
 
 // package.json
-var version = "0.8.0";
+var version = "0.9.0";
 
 // src/commands/auth/index.ts
 import { Command } from "commander";
@@ -29199,8 +29199,8 @@ glossaryCommand.command("remove").description("Remove a glossary term").argument
 });
 
 // src/commands/init/index.tsx
-import { existsSync as existsSync4 } from "fs";
-import path9 from "path";
+import { existsSync as existsSync5 } from "fs";
+import path10 from "path";
 import { Box as Box10, render as render10, Text as Text10 } from "ink";
 
 // src/lib/telemetry.ts
@@ -29415,9 +29415,9 @@ function runtimeProperties(cliVersion) {
   };
 }
 var activeCommand = null;
-function beginCommand(path11, cliVersion) {
+function beginCommand(path12, cliVersion) {
   activeCommand = {
-    path: path11,
+    path: path12,
     startedAt: Date.now(),
     cliVersion,
     reported: false
@@ -29436,11 +29436,59 @@ function completeCommand(exitCode) {
   });
 }
 
-// src/commands/init/core.ts
-import { execSync as execSync2 } from "child_process";
-import { existsSync as existsSync3 } from "fs";
+// src/commands/init/agents-file.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import path8 from "path";
 
+// ../shared/src/agents/index.ts
+var AGENT_DOCS_URL = "https://docs.tolkbot.ai/docs/for-agents";
+var AGENT_BLOCK = `## Translations
+
+TolkBot translates this project. Run its commands in the directory that holds \`tolkbot.json\`.
+
+- Add new strings to the base locale file only. Never write the other locale files by hand.
+- After changing strings, run \`npx tolkbot status\` and \`npx tolkbot translate --all\`, then \`npx tolkbot validate\` before committing.
+- To correct a translation, run \`npx tolkbot set <key> --locale <locale> --value "<text>" --learn "<why>"\`. TolkBot keeps the value and learns from the note.
+- Leave every key alone that \`npx tolkbot status --keys\` lists as held by a person.
+- More: ${AGENT_DOCS_URL}`;
+var AGENT_BLOCK_START = "<!-- tolkbot:start -->";
+var AGENT_BLOCK_END = "<!-- tolkbot:end -->";
+var MARKED_AGENT_BLOCK = `${AGENT_BLOCK_START}
+${AGENT_BLOCK}
+${AGENT_BLOCK_END}`;
+function withAgentBlock(existing) {
+  if (existing === null) {
+    return {
+      ok: true,
+      change: "created",
+      content: `${MARKED_AGENT_BLOCK}
+`
+    };
+  }
+  const start = existing.indexOf(AGENT_BLOCK_START);
+  const end = existing.indexOf(AGENT_BLOCK_END);
+  if (start === -1 && end === -1) {
+    const trimmed = existing.replace(/\s+$/, "");
+    const content2 = trimmed === "" ? `${MARKED_AGENT_BLOCK}
+` : `${trimmed}
+
+${MARKED_AGENT_BLOCK}
+`;
+    return { ok: true, change: "added", content: content2 };
+  }
+  if (start === -1 || end === -1 || end < start) {
+    return { ok: false, reason: "unmatched_marker" };
+  }
+  const before = existing.slice(0, start);
+  const after = existing.slice(end + AGENT_BLOCK_END.length);
+  const content = `${before}${MARKED_AGENT_BLOCK}${after}`;
+  return {
+    ok: true,
+    change: content === existing ? "unchanged" : "updated",
+    content
+  };
+}
+
 // src/lib/repository-root.ts
 import { execFileSync } from "child_process";
 import fs7 from "fs";
@@ -29481,7 +29529,52 @@ function realpath(p) {
   }
 }
 
+// src/commands/init/agents-file.ts
+var AGENT_FILE_NAMES = ["AGENTS.md", "CLAUDE.md"];
+function defaultAgentsFile(cwd) {
+  const start = path8.resolve(cwd);
+  const root = gitToplevel(start) ?? start;
+  for (let dir = start; ; dir = path8.dirname(dir)) {
+    for (const name of AGENT_FILE_NAMES) {
+      const candidate = path8.join(dir, name);
+      if (existsSync3(candidate)) return candidate;
+    }
+    if (dir === root || path8.dirname(dir) === dir) break;
+  }
+  return path8.join(root, "AGENTS.md");
+}
+function resolveAgentsFile(cwd, requested) {
+  return requested === true ? defaultAgentsFile(cwd) : path8.resolve(cwd, requested);
+}
+function writeAgentsFile(file2) {
+  const existing = existsSync3(file2) ? readFileSync3(file2, "utf8") : null;
+  const edit = withAgentBlock(existing);
+  if (!edit.ok) {
+    throw new CliError(
+      `${file2} has a TolkBot block that is missing its start or end marker.`,
+      "Remove the half of the block that is left, or the marker, and run 'tolkbot init --agents-file' again."
+    );
+  }
+  if (edit.change !== "unchanged") writeFileSync2(file2, edit.content);
+  return { path: file2, change: edit.change };
+}
+function describeAgentsFile(result, shown) {
+  switch (result.change) {
+    case "created":
+      return `Wrote the agent instructions to ${shown}`;
+    case "added":
+      return `Added the agent instructions to ${shown}`;
+    case "updated":
+      return `Updated the agent instructions in ${shown}`;
+    case "unchanged":
+      return `${shown} already has the agent instructions`;
+  }
+}
+
 // src/commands/init/core.ts
+import { execSync as execSync2 } from "child_process";
+import { existsSync as existsSync4 } from "fs";
+import path9 from "path";
 var DETECTION_TIMEOUT_MS = 3 * 6e4;
 var DETECTION_POLL_MS = 1e3;
 function getRecommendedFramework(projectType) {
@@ -29588,7 +29681,7 @@ function ambiguousProjectError(candidates) {
 function configInDirectory(dir) {
   try {
     const found = readConfig(dir);
-    if (!found || path8.dirname(found.path) !== path8.resolve(dir)) {
+    if (!found || path9.dirname(found.path) !== path9.resolve(dir)) {
       return void 0;
     }
     return {
@@ -29601,7 +29694,7 @@ function configInDirectory(dir) {
   }
 }
 function newProjectName(repository, subpath) {
-  return subpath === "" ? repository : path8.posix.basename(subpath);
+  return subpath === "" ? repository : path9.posix.basename(subpath);
 }
 async function linkRepository(cwd, plan, opts = {}) {
   const { owner, name } = resolveRepoIdentity(cwd);
@@ -29682,14 +29775,14 @@ async function linkRepository(cwd, plan, opts = {}) {
     () => convexClient.query(api.projects.getProjectForCli, { projectId })
   );
   requireSourcePattern(project, `${owner}/${name}`);
-  const projectDir = path8.join(
+  const projectDir = path9.join(
     root,
     ...project.subpath.split("/").filter(Boolean)
   );
-  const configDir = opts.existingConfig?.projectId === projectId ? path8.dirname(opts.existingConfig.path) : (
+  const configDir = opts.existingConfig?.projectId === projectId ? path9.dirname(opts.existingConfig.path) : (
     // A checkout without the project's directory (a sparse one)
     // keeps the config where init ran.
-    existsSync3(projectDir) ? projectDir : cwd
+    existsSync4(projectDir) ? projectDir : cwd
   );
   return {
     projectId,
@@ -29719,8 +29812,8 @@ function writeProjectConfig(result, framework, opts) {
   );
 }
 function displayPath(cwd, file2) {
-  const relative = path8.relative(cwd, file2);
-  return relative.startsWith("..") || path8.isAbsolute(relative) ? file2 : relative;
+  const relative = path9.relative(cwd, file2);
+  return relative.startsWith("..") || path9.isAbsolute(relative) ? file2 : relative;
 }
 function isDetecting(project) {
   return project.initializationStatus === "pending" || project.initializationStatus === "initializing";
@@ -29793,6 +29886,7 @@ function friendlyProjectType(t) {
 function InitWizard({
   force,
   project,
+  agentsFile,
   onComplete,
   onFailure
 }) {
@@ -29807,6 +29901,27 @@ function InitWizard({
   });
   const [error62, setError] = React.useState(null);
   const [pendingChoice, setPendingChoice] = React.useState(null);
+  const agentsTarget = React.useMemo(
+    () => resolveAgentsFile(cwd, agentsFile ?? true),
+    [cwd, agentsFile]
+  );
+  function addAgentInstructions() {
+    try {
+      const result = writeAgentsFile(agentsTarget);
+      setSetupData((prev) => ({
+        ...prev,
+        agentsLine: describeAgentsFile(
+          result,
+          displayPath(cwd, result.path)
+        )
+      }));
+    } catch (err) {
+      setSetupData((prev) => ({
+        ...prev,
+        agentsLine: err instanceof Error ? err.message : String(err)
+      }));
+    }
+  }
   React.useEffect(() => {
     if (step === "detecting") {
       setTimeout(() => {
@@ -29862,7 +29977,12 @@ function InitWizard({
           createdProject: result.createdProject,
           organizationId: result.organizationId
         });
-        setStep("done");
+        if (agentsFile) {
+          addAgentInstructions();
+          setStep("done");
+        } else {
+          setStep("agentsOffer");
+        }
       } catch (err) {
         setError(err instanceof Error ? err.message : String(err));
         setStep("done");
@@ -30097,6 +30217,30 @@ function InitWizard({
       ] })
     ] }) });
   }
+  if (step === "agentsOffer") {
+    return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs9(Text9, { children: [
+        "Add TolkBot's instructions for coding agents to",
+        " ",
+        displayPath(cwd, agentsTarget),
+        "?"
+      ] }),
+      /* @__PURE__ */ jsx9(Text9, { dimColor: true, children: "They tell an agent to run tolkbot translate and validate instead of writing locale files by hand." }),
+      /* @__PURE__ */ jsx9(Box9, { marginTop: 1, children: /* @__PURE__ */ jsx9(
+        Select,
+        {
+          options: [
+            { label: "Yes", value: "yes" },
+            { label: "No", value: "no" }
+          ],
+          onChange: (value) => {
+            if (value === "yes") addAgentInstructions();
+            setStep("done");
+          }
+        }
+      ) })
+    ] });
+  }
   if (step === "done") {
     if (error62) {
       return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", children: [
@@ -30125,10 +30269,13 @@ function InitWizard({
         "Files: ",
         setupData.link?.sourcePattern
       ] }) }),
-      setupData.configPath && /* @__PURE__ */ jsx9(Box9, { marginTop: 1, children: /* @__PURE__ */ jsxs9(Text9, { children: [
-        "Wrote ",
-        displayPath(cwd, setupData.configPath)
-      ] }) }),
+      setupData.configPath && /* @__PURE__ */ jsxs9(Box9, { marginTop: 1, flexDirection: "column", children: [
+        /* @__PURE__ */ jsxs9(Text9, { children: [
+          "Wrote ",
+          displayPath(cwd, setupData.configPath)
+        ] }),
+        setupData.agentsLine && /* @__PURE__ */ jsx9(Text9, { children: setupData.agentsLine })
+      ] }),
       setupData.shouldInstall && /* @__PURE__ */ jsxs9(Box9, { marginTop: 1, flexDirection: "column", children: [
         /* @__PURE__ */ jsx9(Text9, { children: "Next steps:" }),
         /* @__PURE__ */ jsx9(Text9, { dimColor: true, children: "1. Import i18n in your app - see docs" }),
@@ -30195,7 +30342,8 @@ function resolvePlan(cwd, opts) {
 function SummaryUI({
   plan,
   result,
-  configPath
+  configPath,
+  agentsLine
 }) {
   return /* @__PURE__ */ jsxs10(Box10, { flexDirection: "column", children: [
     /* @__PURE__ */ jsxs10(Box10, { children: [
@@ -30233,10 +30381,13 @@ function SummaryUI({
         result.createdProject ? " (created)" : " (existing)"
       ] })
     ] }),
-    /* @__PURE__ */ jsx10(Box10, { marginTop: 1, children: /* @__PURE__ */ jsxs10(Text10, { children: [
-      "Wrote ",
-      configPath
-    ] }) })
+    /* @__PURE__ */ jsxs10(Box10, { marginTop: 1, flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs10(Text10, { children: [
+        "Wrote ",
+        configPath
+      ] }),
+      agentsLine && /* @__PURE__ */ jsx10(Text10, { children: agentsLine })
+    ] })
   ] });
 }
 async function runHeadless(cwd, opts) {
@@ -30260,6 +30411,7 @@ async function runHeadless(cwd, opts) {
   const configPath = writeProjectConfig(result, plan.framework, {
     force: opts.force
   });
+  const agents = opts.agentsFile ? writeAgentsFile(resolveAgentsFile(cwd, opts.agentsFile)) : null;
   track("cli_init_completed", {
     framework: plan.framework,
     framework_detected: detectedFramework,
@@ -30283,7 +30435,8 @@ async function runHeadless(cwd, opts) {
         baseLocale: result.baseLanguage,
         targets: result.targetLanguages,
         createdProject: result.createdProject,
-        installed: plan.install
+        installed: plan.install,
+        agentsFile: agents
       },
       0
     );
@@ -30295,7 +30448,8 @@ async function runHeadless(cwd, opts) {
       {
         plan,
         result,
-        configPath: displayPath(cwd, configPath)
+        configPath: displayPath(cwd, configPath),
+        agentsLine: agents ? describeAgentsFile(agents, displayPath(cwd, agents.path)) : null
       }
     )
   ).unmount();
@@ -30318,8 +30472,8 @@ async function requireLogin() {
 }
 function refuseExistingConfig(cwd, force) {
   if (force) return;
-  const existing = path9.join(cwd, "tolkbot.json");
-  if (existsSync4(existing)) {
+  const existing = path10.join(cwd, "tolkbot.json");
+  if (existsSync5(existing)) {
     throw new CliError(
       `${existing} already exists.`,
       "Run 'tolkbot init --force' to link again and refresh it."
@@ -30344,6 +30498,7 @@ async function runInteractive(opts) {
       {
         force: opts.force,
         project: opts.project,
+        agentsFile: opts.agentsFile,
         onComplete: (summary) => {
           setTelemetryOrganization(summary.organizationId);
           track("cli_init_completed", {
@@ -30440,7 +30595,7 @@ function describeLeftOut(plan) {
 
 // src/commands/translate/apply-core.ts
 import fs8 from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 
 // ../../node_modules/.pnpm/@noble+hashes@2.4.0/node_modules/@noble/hashes/_u64.js
 var fromNumH = (n) => n / 2 ** 32 | 0;
@@ -31009,7 +31164,7 @@ async function applyTasks(input2) {
     }
     const baseKeys = new Set(getKeys(source.data));
     const target = targetFileFor(sourceFile, dstLocale, files, scope);
-    const targetPath = path10.join(root, ...target.relativePath.split("/"));
+    const targetPath = path11.join(root, ...target.relativePath.split("/"));
     const existing = target.existing ? await readTranslationFile(target.existing.absolutePath, format) : void 0;
     if (existing?.error !== void 0) {
       for (const task of tasks) refuse(task, "target_unreadable");
@@ -31064,7 +31219,7 @@ async function applyTasks(input2) {
 async function writeTranslationFile(input2) {
   const { targetPath, data } = input2;
   const model = input2.existingContent ?? input2.sourceContent;
-  await fs8.mkdir(path10.dirname(targetPath), { recursive: true });
+  await fs8.mkdir(path11.dirname(targetPath), { recursive: true });
   if (input2.format === "json") {
     await fs8.writeFile(
       targetPath,
@@ -31861,10 +32016,10 @@ function serverMessage(message) {
 }
 function argumentError(message) {
   if (!message.includes("ArgumentValidationError")) return null;
-  const path11 = /Path: \.?(\S+)/.exec(message)?.[1];
+  const path12 = /Path: \.?(\S+)/.exec(message)?.[1];
   const value = /Value: (.+)/.exec(message)?.[1];
   return new UsageError(
-    path11 && value ? `TolkBot refused ${value} as ${path11}.` : "TolkBot refused the arguments.",
+    path12 && value ? `TolkBot refused ${value} as ${path12}.` : "TolkBot refused the arguments.",
     "Check the id or value passed; list ids with the command's list subcommand."
   );
 }
@@ -35168,7 +35323,7 @@ function buildProgram() {
   });
   program.command("init").description("Initialize TolkBot in the current repo").option("--force", "Overwrite existing config").option(
     "-y, --yes",
-    "Skip all prompts, accepting detected settings. Required outside a terminal."
+    "Skip all prompts, accepting detected settings (the default without a terminal)"
   ).option("--json", "Output the result as JSON (implies --yes)").option("--base <locale>", "Base locale (default: detected, else en)").option(
     "--targets <locales>",
     "Comma-separated target locales (default: detected)"
@@ -35181,6 +35336,9 @@ function buildProgram() {
   ).option(
     "--project <slug>",
     "Link this project. Default: the project whose directory you are in, else a new project here."
+  ).option(
+    "--agents-file [path]",
+    "Add TolkBot's instructions for coding agents to this file, by default the nearest AGENTS.md or CLAUDE.md. At a terminal init asks; otherwise it writes them only with this option"
   ).action((opts) => runInit(opts));
   program.command("validate").description("Validate translation files and configuration").option("--json", "Output the report as JSON").option(
     "--strict",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolkbot/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Command-line interface for TolkBot: AI translation for the i18n files in a GitHub repository.",
   "license": "UNLICENSED",
   "homepage": "https://tolkbot.ai",
@@ -66,6 +66,7 @@
     "typecheck": "tsc --noEmit --emitDeclarationOnly false",
     "test": "pnpm format && pnpm run lint && pnpm run typecheck && pnpm run test:unit",
     "test:unit": "vitest run --silent",
+    "docs:reference": "UPDATE_CLI_REFERENCE=1 vitest run cli-reference",
     "check:release": "node ../../scripts/check-cli-release.mjs",
     "with-env": "dotenv -e ../../.env --",
     "start": "pnpm with-env node dist/index.js"