@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/commands/{init.js → init/init.js}

@@ -1,64 +1,18 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { CONFIG_FILENAME, findConfigPath, loadConfig, localConfigPath, saveConfig, } from "../core/config.js";
-import { emitJson, fail } from "../core/json.js";
-import { plannedDocsFiles, scaffoldDocs } from "../core/docs.js";
-import { agentsPath, docsRepoState, listServices } from "../core/repo.js";
-import { InvalidIdError, assertServiceId } from "../core/ids.js";
-import { AGENT_TOOLS, detectAgentTools, plannedCommandFiles, scaffoldAgentCommands, } from "../core/agent.js";
-/**
- * Resolve --tools to registry ids, or null after reporting the refusal. The
- * default (the cwd scan) lives at the call site, not in commander, so an
- * explicit `--tools` is distinguishable from none — which is what lets both the
- * autodetection fallback and the `--no-*` contradiction be decided instead of
- * silently arbitrated.
- */
-function resolveTools(raw, json) {
-    const supported = Object.keys(AGENT_TOOLS);
-    if (raw === "all")
-        return supported;
-    const ids = [...new Set(raw.split(",").map((t) => t.trim()).filter((t) => t !== ""))];
-    const unknown = ids.filter((t) => !(t in AGENT_TOOLS));
-    if (ids.length === 0 || unknown.length > 0) {
-        fail(json, "invalid-option", (ids.length === 0
-            ? "--tools names no tool."
-            : `--tools does not recognize: ${unknown.join(", ")}.`) +
-            ` Supported: ${supported.join(", ")} — or "all".`);
-        return null;
-    }
-    return ids;
-}
-/**
- * `--docs` exactly as the caller wrote it, with separators normalised.
- *
- * Stored verbatim on purpose. `init` used to resolve it and write the absolute
- * result, which meant a committed loam.json named a directory that existed on
- * one laptop: every teammate who cloned the service repo got a docsDir under
- * someone else's home directory, and `loam list` reported an empty fleet
- * instead of saying so. `loadConfig` resolves relative paths against the config
- * file's own directory, so `../docs` keeps meaning "next to this repo" wherever
- * the pair is checked out. An absolute `--docs` is still stored absolute — that
- * is the caller's explicit choice, and `loam doctor` warns about it.
- *
- * Backslashes become forward slashes so a config written on Windows resolves on
- * POSIX; a trailing separator is dropped so the stored spelling is stable.
- */
-function storedDocsDir(raw) {
-    const slashed = raw.split("\\").join("/");
-    if (slashed.length <= 1)
-        return slashed;
-    const trimmed = slashed.replace(/\/+$/, "");
-    return trimmed === "" ? "/" : trimmed;
-}
-/**
- * Does this directory already hold a docs repo? `services/` plus `AGENTS.md` —
- * the two things every docs repo has and no service repo does. The pair is the
- * whole point: a single marker would make `init --docs ../srv` (a typo for
- * `../docs`) look like a join and adopt the service repo as the fleet.
- */
-function isDocsRepo(dir) {
-    return docsRepoState(dir).kind === "ok" && existsSync(agentsPath(dir));
-}
+import { CONFIG_FILENAME, findConfigPath, loadConfig, localConfigPath, saveConfig, } from "../../core/envelope/config.js";
+import { docsDirOf } from "../../core/kernel/ids/dirs.js";
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { plannedDocsFiles, scaffoldDocs } from "../../core/docs.js";
+import { docsRepoState } from "../../core/repo/state.js";
+import { listServices } from "../../core/repo/repo.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { detectAgentTools, plannedCommandFiles, syncAgentCommands, updatedAgentFileManifest, } from "../../core/agent/scaffold.js";
+import { AGENT_TOOLS } from "../../core/agent/tools/registry.js";
+import { initExample } from "./example.js";
+import { firstHour } from "./first-hour.js";
+import { MCP_CONFIG_FILENAME, mcpConfigPath, mcpServerSnippet, writeMcpConfig } from "./mcp.js";
+import { isDocsRepo, resolveAgentProfile, resolveTools, storedDocsDir } from "./options.js";
 export function registerInit(program) {
     program
         .command("init")
@@ -69,12 +23,42 @@ export function registerInit(program) {
         .option("--force", `write ${CONFIG_FILENAME} here even though one governs a parent directory`)
         .option("--tools <ids>", "agent tools to generate for, overriding the scan of this directory: " +
         `comma-separated (${Object.keys(AGENT_TOOLS).join(", ")}) or "all"`)
+        .option("--agent-profile <profile>", "workflow set: full | service | docs")
+        .option("--example <dir>", "copy the packaged example fleet to <dir> and stop: no repository is bound, nothing is scaffolded")
         .option("--no-commands", "skip the slash commands for this repo entirely")
         .option("--no-skills", "skip the agent skills for this repo entirely")
+        .option("--mcp", `also write ${MCP_CONFIG_FILENAME} here, so an MCP host launches \`loam mcp\` for this repo`)
+        .option("--mcp-author", `write ${MCP_CONFIG_FILENAME} with the opt-in authoring profile`)
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts, command) => {
         const json = opts.json === true;
         const cwd = process.cwd();
+        // FIRST, before every guard below including the governing-config one:
+        // `--example` writes a fresh tree, it does not join a system. A
+        // loam.json in an ancestor governs the directories a repository is bound
+        // INTO, and this flag binds nothing — refusing here would be the tool
+        // declining to show itself working because of a config that has no
+        // bearing on the copy. Before the --service id check too, so a run
+        // combining the two answers the contradiction rather than grading an id
+        // it is about to refuse to use.
+        if (opts.example !== undefined) {
+            await initExample({
+                dir: opts.example,
+                conflicts: [
+                    // `--docs` carries a default, so only its SOURCE can say whether
+                    // anybody typed it — the same question the docsDir precedence
+                    // below asks, for the same reason.
+                    ...(command.getOptionValueSource("docs") !== "default" ? ["--docs"] : []),
+                    ...(opts.service !== undefined ? ["--service"] : []),
+                    ...(opts.create === true ? ["--create"] : []),
+                    ...(opts.tools !== undefined ? ["--tools"] : []),
+                    ...(opts.agentProfile !== undefined ? ["--agent-profile"] : []),
+                    ...(opts.mcpAuthor === true ? ["--mcp-author"] : []),
+                ],
+                json,
+            });
+            return;
+        }
         // The id becomes services/<id>/ in the shared repo, so it is validated
         // before anything is written — by the same rule adopt, vouch and gherkin
         // use, never by a guard invented here.
@@ -103,7 +87,12 @@ export function registerInit(program) {
         // Only THIS directory's config is spread forward. Under --force there is
         // a config in an ancestor too, and inheriting its `service` would bind
         // this repo to a service somebody else's repo declared.
-        const existing = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;
+        // `kind: "invalid"` reads as null on purpose: init REPAIRS a corrupt
+        // loam.json by rewriting it, so a config nobody can read is treated
+        // exactly like no config at all. The old stderr line about it was
+        // core's side effect, promised nowhere.
+        const load = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;
+        const existing = load?.kind === "loaded" ? load.config : null;
         // A re-run must not move a committed pointer. `--docs` has a default
         // (`.loam-docs`), so an init invoked for any OTHER reason — `--service`,
         // a new `--tools`, the fix `doctor.agent-files-missing` prints — used to
@@ -118,7 +107,11 @@ export function registerInit(program) {
         const docsTyped = command.getOptionValueSource("docs") !== "default";
         const docsSource = docsTyped ? "flag" : committedDocs === undefined ? "default" : "config";
         const docsOption = !docsTyped && committedDocs !== undefined ? committedDocs : opts.docs;
-        const docsDir = resolve(cwd, docsOption);
+        // Branded at the resolution, because the guards below are what validate
+        // it — the brand's provenance is "an explicit --docs a command
+        // validated", and this command is the one that does. The STORED spelling
+        // (`storedDocsDir` below) deliberately stays a plain string.
+        const docsDir = docsDirOf(resolve(cwd, docsOption));
         // The one predictable failure: --docs naming a file. Refused here so the
         // caller gets a clean envelope/message instead of mkdir's ENOTDIR throw.
         if (existsSync(docsDir) && !statSync(docsDir).isDirectory()) {
@@ -165,33 +158,72 @@ export function registerInit(program) {
         const tools = opts.tools === undefined ? scanned : resolveTools(opts.tools, json);
         if (tools === null)
             return;
-        // `skipped` is the other half of the never-overwrite contract: the
-        // scaffolds return only what they created, so what they left alone is
-        // probed here, before they run — in the order they would create it, so
-        // created + skipped is the same list on every repo. Both halves come from
-        // the scaffolds' own planned-file lists, so the probe cannot drift from
-        // what is actually written.
-        const agentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery) : [];
-        const candidates = [...plannedDocsFiles(docsDir), ...agentFiles.map((f) => f.path)];
-        const skipped = candidates.filter((p) => existsSync(p));
+        const profile = resolveAgentProfile(opts.agentProfile, existing?.agentProfile, json);
+        if (profile === null)
+            return;
+        // Probe the pre-existing paths in planned order. Managed files refreshed
+        // below are removed from `skipped`; custom and already-current files stay.
+        const plannedAgentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery, profile) : [];
+        // `.mcp.json` joins the same list rather than being reported on the side:
+        // it is a scaffolded path like any other, so it must appear in `created`
+        // or in `skipped` by the one rule that governs both. Last, because it is
+        // written last.
+        const candidates = [
+            ...plannedDocsFiles(docsDir),
+            ...plannedAgentFiles.map((f) => f.path),
+            ...(opts.mcp === true || opts.mcpAuthor === true ? [mcpConfigPath(cwd)] : []),
+        ];
+        let skipped = candidates.filter((p) => existsSync(p));
         // Joining touches the docs repo not at all: it is somebody's committed
         // repository, and "point at it" must never mean "write to it".
         const created = joining && opts.create !== true ? [] : (await scaffoldDocs(docsDir)).created;
         const generatedFor = delivery.length > 0 ? tools : [];
+        let refreshed = [];
+        let managedFiles = {};
         if (delivery.length > 0) {
-            created.push(...(await scaffoldAgentCommands(cwd, tools, delivery)));
+            const synced = await syncAgentCommands({
+                cwd,
+                toolIds: tools,
+                delivery,
+                profile,
+                known: existing?.agentFiles,
+            });
+            created.push(...synced.created);
+            refreshed = synced.refreshed;
+            managedFiles = synced.managed;
+            skipped = skipped.filter((path) => !refreshed.includes(path));
+        }
+        // The third delivery, and the only machine-readable one. It refuses out
+        // loud rather than being written best-effort: a `.mcp.json` half-landed
+        // is a host that starts a broken server, and the caller asked for it by
+        // name. Before saveConfig, so a run that cannot write this file has not
+        // yet moved the committed pointer either.
+        let mcpWritten = false;
+        if (opts.mcp === true || opts.mcpAuthor === true) {
+            const write = await writeMcpConfig(cwd, opts.mcpAuthor === true);
+            if (write.kind === "failed") {
+                fail(json, write.code, write.message);
+                return;
+            }
+            mcpWritten = write.kind === "created";
+            if (mcpWritten)
+                created.push(mcpConfigPath(cwd));
         }
         const stored = storedDocsDir(docsOption);
         // Union, not replacement: this run's files join the ones earlier runs left
         // on disk, and `agentTools` is a record of what the repo HOLDS. A run that
         // generated nothing adds nothing and erases nothing.
         const recordedTools = [...new Set([...(existing?.agentTools ?? []), ...generatedFor])];
+        const agentFileManifest = updatedAgentFileManifest(cwd, plannedAgentFiles, existing?.agentFiles, managedFiles);
         const config = {
             ...existing,
             docsDir: stored,
             ...(opts.service ? { service: opts.service } : {}),
             ...(recordedTools.length > 0 ? { agentTools: recordedTools } : {}),
+            agentProfile: profile,
         };
+        if (Object.keys(agentFileManifest).length > 0)
+            config.agentFiles = agentFileManifest;
         const configFile = await saveConfig(config, cwd);
         const serviceCount = (await listServices(docsDir)).length;
         if (json) {
@@ -204,6 +236,7 @@ export function registerInit(program) {
             // changing: an agent comparing the two learns whether its selection
             // matches the repo.
             emitJson({
+                command: "init",
                 docsDir,
                 docsDirStored: stored,
                 // Where the pointer came from: `flag` (a --docs somebody typed),
@@ -213,8 +246,10 @@ export function registerInit(program) {
                 docsRepo: joining ? "existing" : "created",
                 services: serviceCount,
                 created,
+                refreshed,
                 skipped,
                 tools: generatedFor,
+                agentProfile: profile,
                 detected,
             });
             return;
@@ -240,11 +275,51 @@ export function registerInit(program) {
             console.log(`  commands:  ${tools.join(", ")}`);
         if (opts.skills)
             console.log(`  skills:    ${tools.join(", ")}`);
+        console.log(`  profile:   ${profile}`);
         if (created.length > 0) {
             console.log("  scaffolded:");
             for (const c of created)
                 console.log(`    + ${c}`);
         }
+        if (refreshed.length > 0) {
+            console.log("  refreshed (unchanged since loam last wrote them):");
+            for (const path of refreshed)
+                console.log(`    ↻ ${path}`);
+        }
+        // The one skipped path that earns more than its line in `skipped`: loam
+        // will not merge into a `.mcp.json` a human owns, and the caller asked
+        // for this delivery by name — so they are handed the exact key to paste
+        // into their own `mcpServers` object. Nothing was read out of their file
+        // to produce it; the snippet is the same bytes a fresh write would have
+        // used, which is also why it names the launch form this install shape
+        // actually needs.
+        if ((opts.mcp === true || opts.mcpAuthor === true) && !mcpWritten) {
+            console.log(`  mcp:       ${MCP_CONFIG_FILENAME} is already here — left exactly as it is.`);
+            console.log(`             paste this into its "mcpServers" object:`);
+            for (const line of mcpServerSnippet(cwd, opts.mcpAuthor === true))
+                console.log(`               ${line}`);
+        }
+        // Printed ONLY for the single-repo trial composition: one run that both
+        // created the docs repo and left a service bound (the binding may
+        // predate the run — the config spread above carries an existing
+        // loam.json's `service` forward). `loam status` is NOT mute here — its
+        // first-hour ladder (core/status/fleet/next.ts) already answers
+        // `next.adopt-bound` in exactly this state — but status has to be run
+        // to say so, and no status rung ever names `loam vouch`, the one step
+        // of this loop that is a person's; init's output is already on screen,
+        // so it prints the whole hour once. A join stays silent on purpose: a
+        // joined fleet has other repositories already through this loop, and
+        // `loam status` in its docs repo is the working guide there. The --json
+        // path returned above, so the envelope is byte-identical to before
+        // this block existed.
+        if (!joining && config.service !== undefined) {
+            const steps = firstHour(config.service);
+            const width = Math.max(...steps.map(([command]) => command.length));
+            console.log("  next — the first hour:");
+            for (const [command, why] of steps) {
+                console.log(`    ${command.padEnd(width)}   # ${why}`);
+            }
+        }
     });
 }
 //# sourceMappingURL=init.js.map

package/dist/commands/init/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/init/init.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { existsSync, statSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport {\n  CONFIG_FILENAME,\n  findConfigPath,\n  loadConfig,\n  localConfigPath,\n  saveConfig,\n  type StoredConfig,\n} from \"../../core/envelope/config.js\";\nimport { docsDirOf } from \"../../core/kernel/ids/dirs.js\";\nimport { emitJson, fail } from \"../../core/envelope/json.js\";\nimport { plannedDocsFiles, scaffoldDocs } from \"../../core/docs.js\";\nimport { docsRepoState } from \"../../core/repo/state.js\";\nimport { listServices } from \"../../core/repo/repo.js\";\nimport { InvalidIdError, assertServiceId } from \"../../core/kernel/ids/service.js\";\nimport {\n  detectAgentTools,\n  plannedCommandFiles,\n  syncAgentCommands,\n  updatedAgentFileManifest,\n  type Delivery,\n} from \"../../core/agent/scaffold.js\";\nimport { AGENT_TOOLS } from \"../../core/agent/tools/registry.js\";\nimport { initExample } from \"./example.js\";\nimport { firstHour } from \"./first-hour.js\";\nimport { MCP_CONFIG_FILENAME, mcpConfigPath, mcpServerSnippet, writeMcpConfig } from \"./mcp.js\";\nimport { isDocsRepo, resolveAgentProfile, resolveTools, storedDocsDir } from \"./options.js\";\n\ninterface InitOptions {\n  docs: string;\n  service?: string;\n  /** --create: make a new docs repo at --docs instead of joining an existing one. */\n  create?: boolean;\n  /** --force: write loam.json here even though one already governs a parent directory. */\n  force?: boolean;\n  /** commander's --no-commands: true unless the flag is passed. */\n  commands: boolean;\n  /** commander's --no-skills: true unless the flag is passed. */\n  skills: boolean;\n  /**\n   * --mcp: also write the repo-root `.mcp.json`. Opt-in and default off — a\n   * third delivery, independent of the two `--no-*` flags rather than a\n   * variation on them, so it neither contradicts them nor is suppressed by\n   * either. See ./mcp.ts for why the file is opt-in at all.\n   */\n  mcp?: boolean;\n  mcpAuthor?: boolean;\n  /** --tools: comma-separated AGENT_TOOLS ids, or \"all\". Absent = autodetect. */\n  tools?: string;\n  /** Workflow subset to scaffold. */\n  agentProfile?: string;\n  /** --example: copy the packaged example fleet to this directory and do nothing else. */\n  example?: string;\n  json?: boolean;\n}\n\nexport function registerInit(program: Command): void {\n  program\n    .command(\"init\")\n    .description(\"Initialize loam: create/point at the shared docs repo and write local config\")\n    .option(\"--docs <dir>\", \"path to the shared docs repo (the source of truth)\", \".loam-docs\")\n    .option(\"--service <id>\", \"canonical id of the service in this repo\")\n    .option(\"--create\", \"create a new docs repo at --docs instead of joining an existing one\")\n    .option(\"--force\", `write ${CONFIG_FILENAME} here even though one governs a parent directory`)\n    .option(\n      \"--tools <ids>\",\n      \"agent tools to generate for, overriding the scan of this directory: \" +\n        `comma-separated (${Object.keys(AGENT_TOOLS).join(\", \")}) or \"all\"`,\n    )\n    .option(\"--agent-profile <profile>\", \"workflow set: full | service | docs\")\n    .option(\n      \"--example <dir>\",\n      \"copy the packaged example fleet to <dir> and stop: no repository is bound, nothing is scaffolded\",\n    )\n    .option(\"--no-commands\", \"skip the slash commands for this repo entirely\")\n    .option(\"--no-skills\", \"skip the agent skills for this repo entirely\")\n    .option(\n      \"--mcp\",\n      `also write ${MCP_CONFIG_FILENAME} here, so an MCP host launches \\`loam mcp\\` for this repo`,\n    )\n    .option(\"--mcp-author\", `write ${MCP_CONFIG_FILENAME} with the opt-in authoring profile`)\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: InitOptions, command: Command) => {\n      const json = opts.json === true;\n      const cwd = process.cwd();\n\n      // FIRST, before every guard below including the governing-config one:\n      // `--example` writes a fresh tree, it does not join a system. A\n      // loam.json in an ancestor governs the directories a repository is bound\n      // INTO, and this flag binds nothing — refusing here would be the tool\n      // declining to show itself working because of a config that has no\n      // bearing on the copy. Before the --service id check too, so a run\n      // combining the two answers the contradiction rather than grading an id\n      // it is about to refuse to use.\n      if (opts.example !== undefined) {\n        await initExample({\n          dir: opts.example,\n          conflicts: [\n            // `--docs` carries a default, so only its SOURCE can say whether\n            // anybody typed it — the same question the docsDir precedence\n            // below asks, for the same reason.\n            ...(command.getOptionValueSource(\"docs\") !== \"default\" ? [\"--docs\"] : []),\n            ...(opts.service !== undefined ? [\"--service\"] : []),\n            ...(opts.create === true ? [\"--create\"] : []),\n            ...(opts.tools !== undefined ? [\"--tools\"] : []),\n            ...(opts.agentProfile !== undefined ? [\"--agent-profile\"] : []),\n            ...(opts.mcpAuthor === true ? [\"--mcp-author\"] : []),\n          ],\n          json,\n        });\n        return;\n      }\n\n      // The id becomes services/<id>/ in the shared repo, so it is validated\n      // before anything is written — by the same rule adopt, vouch and gherkin\n      // use, never by a guard invented here.\n      if (opts.service !== undefined) {\n        try {\n          assertServiceId(opts.service);\n        } catch (err) {\n          if (!(err instanceof InvalidIdError)) throw err;\n          fail(json, \"invalid-option\", err.message);\n          return;\n        }\n      }\n\n      // A loam.json in an ancestor already governs this directory: every command\n      // run from here resolves to it. Writing a second one below it would shadow\n      // the first for this subtree only — the kind of split-brain nobody\n      // discovers until two commands disagree about which docs repo is the fleet.\n      const governing = findConfigPath(cwd);\n      if (governing !== null && governing !== localConfigPath(cwd) && opts.force !== true) {\n        fail(\n          json,\n          \"already-exists\",\n          `${governing} already governs this directory. ` +\n            `Run loam from ${resolve(governing, \"..\")}, or pass --force to give this ` +\n            `subdirectory its own ${CONFIG_FILENAME}.`,\n        );\n        return;\n      }\n\n      // Only THIS directory's config is spread forward. Under --force there is\n      // a config in an ancestor too, and inheriting its `service` would bind\n      // this repo to a service somebody else's repo declared.\n      // `kind: \"invalid\"` reads as null on purpose: init REPAIRS a corrupt\n      // loam.json by rewriting it, so a config nobody can read is treated\n      // exactly like no config at all. The old stderr line about it was\n      // core's side effect, promised nowhere.\n      const load = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;\n      const existing = load?.kind === \"loaded\" ? load.config : null;\n\n      // A re-run must not move a committed pointer. `--docs` has a default\n      // (`.loam-docs`), so an init invoked for any OTHER reason — `--service`,\n      // a new `--tools`, the fix `doctor.agent-files-missing` prints — used to\n      // arrive here carrying a docsDir nobody typed: the default then named no\n      // docs repo, the refusal steered the caller to `--create`, and `--create`\n      // rewrote `docsDir` in the committed loam.json to a freshly scaffolded\n      // empty one. `validate --all` went green over an empty fleet, which is\n      // the exact outcome `--create` exists to prevent. So the flag wins only\n      // when it was actually passed; otherwise the file this repo already\n      // committed does.\n      const committedDocs = existing?.docsDirAsWritten;\n      const docsTyped = command.getOptionValueSource(\"docs\") !== \"default\";\n      const docsSource: \"flag\" | \"config\" | \"default\" =\n        docsTyped ? \"flag\" : committedDocs === undefined ? \"default\" : \"config\";\n      const docsOption = !docsTyped && committedDocs !== undefined ? committedDocs : opts.docs;\n      // Branded at the resolution, because the guards below are what validate\n      // it — the brand's provenance is \"an explicit --docs a command\n      // validated\", and this command is the one that does. The STORED spelling\n      // (`storedDocsDir` below) deliberately stays a plain string.\n      const docsDir = docsDirOf(resolve(cwd, docsOption));\n\n      // The one predictable failure: --docs naming a file. Refused here so the\n      // caller gets a clean envelope/message instead of mkdir's ENOTDIR throw.\n      if (existsSync(docsDir) && !statSync(docsDir).isDirectory()) {\n        fail(json, \"invalid-option\", `--docs points at a file, not a directory: ${docsDir}`);\n        return;\n      }\n\n      // Joining an existing docs repo and creating a new one are different\n      // intentions, and `init` used to perform the second one whenever the first\n      // was misspelled: `--docs ../dcos` scaffolded a second, empty docs repo\n      // beside the real one, and the fleet quietly split in two. Creation is now\n      // something the caller asks for.\n      const joining = isDocsRepo(docsDir);\n      if (!joining && opts.create !== true) {\n        fail(\n          json,\n          \"invalid-option\",\n          docsRepoState(docsDir).kind === \"missing\"\n            ? `--docs points at a directory that does not exist: ${docsDir}. ` +\n              \"If that is a typo, fix it; to create a new docs repo there, pass --create.\"\n            : `--docs points at ${docsDir}, which is not a docs repo ` +\n              \"(a docs repo has services/ and AGENTS.md). \" +\n              \"Point --docs at the shared docs repo, or pass --create to make a new one here.\",\n        );\n        return;\n      }\n\n      // --tools selects the files to write; --no-commands and --no-skills each\n      // say write none of that kind. Together they contradict — refused, not\n      // arbitrated, in either combination.\n      const suppressed = [\n        ...(opts.commands ? [] : [\"--no-commands\"]),\n        ...(opts.skills ? [] : [\"--no-skills\"]),\n      ];\n      if (opts.tools !== undefined && suppressed.length > 0) {\n        fail(\n          json,\n          \"invalid-option\",\n          `--tools contradicts ${suppressed.join(\" and \")}: ` +\n            \"one selects the files to generate, the other suppresses them.\",\n        );\n        return;\n      }\n      const delivery: Delivery[] = [\n        ...(opts.commands ? ([\"commands\"] as const) : []),\n        ...(opts.skills ? ([\"skills\"] as const) : []),\n      ];\n\n      // Without --tools the repo decides: whichever tools have left their own\n      // dot-directories here. Falling back to claude keeps a bare repo behaving\n      // exactly as it did before the scan existed. `detected` is reported either\n      // way — what the scan saw is a fact about the repo, not about the flags.\n      const detected = detectAgentTools(cwd);\n      const scanned = detected.length > 0 ? detected : [\"claude\"];\n      const tools = opts.tools === undefined ? scanned : resolveTools(opts.tools, json);\n      if (tools === null) return;\n      const profile = resolveAgentProfile(opts.agentProfile, existing?.agentProfile, json);\n      if (profile === null) return;\n\n      // Probe the pre-existing paths in planned order. Managed files refreshed\n      // below are removed from `skipped`; custom and already-current files stay.\n      const plannedAgentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery, profile) : [];\n      // `.mcp.json` joins the same list rather than being reported on the side:\n      // it is a scaffolded path like any other, so it must appear in `created`\n      // or in `skipped` by the one rule that governs both. Last, because it is\n      // written last.\n      const candidates = [\n        ...plannedDocsFiles(docsDir),\n        ...plannedAgentFiles.map((f) => f.path),\n        ...(opts.mcp === true || opts.mcpAuthor === true ? [mcpConfigPath(cwd)] : []),\n      ];\n      let skipped = candidates.filter((p) => existsSync(p));\n\n      // Joining touches the docs repo not at all: it is somebody's committed\n      // repository, and \"point at it\" must never mean \"write to it\".\n      const created = joining && opts.create !== true ? [] : (await scaffoldDocs(docsDir)).created;\n      const generatedFor = delivery.length > 0 ? tools : [];\n      let refreshed: string[] = [];\n      let managedFiles: Record<string, string> = {};\n      if (delivery.length > 0) {\n        const synced = await syncAgentCommands({\n          cwd,\n          toolIds: tools,\n          delivery,\n          profile,\n          known: existing?.agentFiles,\n        });\n        created.push(...synced.created);\n        refreshed = synced.refreshed;\n        managedFiles = synced.managed;\n        skipped = skipped.filter((path) => !refreshed.includes(path));\n      }\n\n      // The third delivery, and the only machine-readable one. It refuses out\n      // loud rather than being written best-effort: a `.mcp.json` half-landed\n      // is a host that starts a broken server, and the caller asked for it by\n      // name. Before saveConfig, so a run that cannot write this file has not\n      // yet moved the committed pointer either.\n      let mcpWritten = false;\n      if (opts.mcp === true || opts.mcpAuthor === true) {\n        const write = await writeMcpConfig(cwd, opts.mcpAuthor === true);\n        if (write.kind === \"failed\") {\n          fail(json, write.code, write.message);\n          return;\n        }\n        mcpWritten = write.kind === \"created\";\n        if (mcpWritten) created.push(mcpConfigPath(cwd));\n      }\n\n      const stored = storedDocsDir(docsOption);\n      // Union, not replacement: this run's files join the ones earlier runs left\n      // on disk, and `agentTools` is a record of what the repo HOLDS. A run that\n      // generated nothing adds nothing and erases nothing.\n      const recordedTools = [...new Set([...(existing?.agentTools ?? []), ...generatedFor])];\n      const agentFileManifest = updatedAgentFileManifest(cwd, plannedAgentFiles, existing?.agentFiles, managedFiles);\n      const config: StoredConfig = {\n        ...existing,\n        docsDir: stored,\n        ...(opts.service ? { service: opts.service } : {}),\n        ...(recordedTools.length > 0 ? { agentTools: recordedTools } : {}),\n        agentProfile: profile,\n      };\n      if (Object.keys(agentFileManifest).length > 0) config.agentFiles = agentFileManifest;\n      const configFile = await saveConfig(config, cwd);\n\n      const serviceCount = (await listServices(docsDir)).length;\n\n      if (json) {\n        // `docsDir` stays the resolved absolute path — it is what a consumer\n        // needs to find the repo. `docsDirStored` is what was written to\n        // loam.json, which is the fact this command is now careful about.\n        // `tools` names what files were generated FOR — empty when every\n        // delivery was suppressed and none were. `detected` is the separate\n        // question of what the scan SAW, which `--tools` overrides without\n        // changing: an agent comparing the two learns whether its selection\n        // matches the repo.\n        emitJson({\n          command: \"init\",\n          docsDir,\n          docsDirStored: stored,\n          // Where the pointer came from: `flag` (a --docs somebody typed),\n          // `config` (the one this repo already committed — a re-run cannot\n          // move it), or `default` (nothing said, nothing committed).\n          docsDirSource: docsSource,\n          docsRepo: joining ? \"existing\" : \"created\",\n          services: serviceCount,\n          created,\n          refreshed,\n          skipped,\n          tools: generatedFor,\n          agentProfile: profile,\n          detected,\n        });\n        return;\n      }\n\n      console.log(\"loam initialized.\");\n      if (joining) {\n        console.log(`  docs repo: ${docsDir}`);\n        console.log(`             pointing at existing docs repo (${serviceCount} services)`);\n      } else {\n        console.log(`  docs repo: ${docsDir}  (created)`);\n      }\n      console.log(\n        `  docsDir:   ${stored}  (as stored in ${CONFIG_FILENAME}`\n        + (docsSource === \"config\" ? \" — kept; no --docs was passed\" : \"\") + \")\",\n      );\n      if (config.service) console.log(`  service:   ${config.service}`);\n      console.log(`  config:    ${configFile}`);\n      console.log(`             commit ${CONFIG_FILENAME} — docsDir is resolved relative to it`);\n      if (opts.tools === undefined && detected.length > 0) {\n        console.log(`  detected:  ${detected.join(\", \")}`);\n      }\n      if (opts.commands) console.log(`  commands:  ${tools.join(\", \")}`);\n      if (opts.skills) console.log(`  skills:    ${tools.join(\", \")}`);\n      console.log(`  profile:   ${profile}`);\n      if (created.length > 0) {\n        console.log(\"  scaffolded:\");\n        for (const c of created) console.log(`    + ${c}`);\n      }\n      if (refreshed.length > 0) {\n        console.log(\"  refreshed (unchanged since loam last wrote them):\");\n        for (const path of refreshed) console.log(`    ↻ ${path}`);\n      }\n\n      // The one skipped path that earns more than its line in `skipped`: loam\n      // will not merge into a `.mcp.json` a human owns, and the caller asked\n      // for this delivery by name — so they are handed the exact key to paste\n      // into their own `mcpServers` object. Nothing was read out of their file\n      // to produce it; the snippet is the same bytes a fresh write would have\n      // used, which is also why it names the launch form this install shape\n      // actually needs.\n      if ((opts.mcp === true || opts.mcpAuthor === true) && !mcpWritten) {\n        console.log(`  mcp:       ${MCP_CONFIG_FILENAME} is already here — left exactly as it is.`);\n        console.log(`             paste this into its \"mcpServers\" object:`);\n        for (const line of mcpServerSnippet(cwd, opts.mcpAuthor === true)) console.log(`               ${line}`);\n      }\n\n      // Printed ONLY for the single-repo trial composition: one run that both\n      // created the docs repo and left a service bound (the binding may\n      // predate the run — the config spread above carries an existing\n      // loam.json's `service` forward). `loam status` is NOT mute here — its\n      // first-hour ladder (core/status/fleet/next.ts) already answers\n      // `next.adopt-bound` in exactly this state — but status has to be run\n      // to say so, and no status rung ever names `loam vouch`, the one step\n      // of this loop that is a person's; init's output is already on screen,\n      // so it prints the whole hour once. A join stays silent on purpose: a\n      // joined fleet has other repositories already through this loop, and\n      // `loam status` in its docs repo is the working guide there. The --json\n      // path returned above, so the envelope is byte-identical to before\n      // this block existed.\n      if (!joining && config.service !== undefined) {\n        const steps = firstHour(config.service);\n        const width = Math.max(...steps.map(([command]) => command.length));\n        console.log(\"  next — the first hour:\");\n        for (const [command, why] of steps) {\n          console.log(`    ${command.padEnd(width)}   # ${why}`);\n        }\n      }\n    });\n}\n"]}

package/dist/commands/init/mcp.js

@@ -0,0 +1,131 @@
+/**
+ * `loam init --mcp`: the one MACHINE delivery `init` makes.
+ *
+ * Every other thing init writes is prose an agent reads — command files and
+ * Agent Skills, twenty tools' worth of dialects, all of them pointers at
+ * `loam instructions`. The MCP facade is the opposite: a typed read surface,
+ * four bounded authoring entries under `--author`, version-matched resources,
+ * and every result carrying the `--json` envelope as `structuredContent`. It
+ * was also the only delivery that required a human to hand-edit a JSON file
+ * before anything could reach it — the generated
+ * AGENTS.md said no more than "configure the host to launch `loam mcp` in the
+ * repository the tools should answer for", so a scaffolded repository reliably
+ * got the prose deliveries and never the typed one.
+ *
+ * OPT-IN, and that is not timidity. `.mcp.json` at the repo root is a file a
+ * host reads and then STARTS A PROCESS from, for everyone who checks the
+ * repository out. Writing one by default would mean `loam init` silently
+ * arranging for a binary to be launched on a teammate's machine, which is a
+ * decision that belongs to whoever runs the command, not to us.
+ *
+ * ## Why only the repo-root `.mcp.json`
+ *
+ * loam knows twenty agent tools and several of them read MCP configuration
+ * from a file of their own. None of the others is written here, and a future
+ * reader who wants to add them should meet the argument first:
+ *
+ *   - `.github/.mcp.json` is already in the registry as a Copilot DETECTION
+ *     marker (tools/registry.ts). Writing it would make the next `init` detect
+ *     Copilot in a repository that has none, because we put the marker there —
+ *     a scan reporting its own output back to itself.
+ *   - `.cursor/mcp.json` and `.vscode/mcp.json` carry different schemas
+ *     (`servers` rather than `mcpServers`, plus per-host keys), so a single set
+ *     of bytes cannot serve all three, and one template per host is one more
+ *     thing to keep true across releases of somebody else's product.
+ *   - `.gemini/settings.json` is a GENERAL settings file. Its MCP block is one
+ *     key among many, so loam could only land it by merging into a file the
+ *     user owns — and merging into a file a human owns is the one thing every
+ *     init delivery is built not to do.
+ *
+ * The repo-root `.mcp.json` is the form with none of those problems: it is a
+ * dedicated file, it is nobody's detection marker, and it is read by the hosts
+ * that matter without being owned by any of them.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { stageWrites } from "../../core/staging/commit.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import { planWrite } from "../../core/staging/writes.js";
+export const MCP_CONFIG_FILENAME = ".mcp.json";
+/** The one file this delivery writes, so init's `skipped` probe and the writer cannot disagree. */
+export function mcpConfigPath(cwd) {
+    return join(cwd, MCP_CONFIG_FILENAME);
+}
+/**
+ * How `loam` is launched HERE, decided from how it is installed here.
+ *
+ * A fixed `"command": "loam"` would be an unlaunchable entry in exactly the
+ * repositories README tells people to make: the documented install is a
+ * per-repo devDependency, which puts the binary in `node_modules/.bin/` and on
+ * no PATH an MCP host inherits. So the local bin decides — `npx --no` when it
+ * is there, the bare name when it is not.
+ *
+ * `--no` and not a bare `npx loam mcp`: without it npx will FETCH `loam` from
+ * the registry when the local resolution misses, which turns a stale checkout
+ * into a silent download of a package with a name loam does not own. With it,
+ * a missing local binary is an error the host reports.
+ *
+ * The probe is the extensionless name on both platforms deliberately: npm's
+ * shim writer lays down `loam`, `loam.cmd` and `loam.ps1` together on Windows,
+ * the first of them for the POSIX shells that run there, so its presence is the
+ * portable question "is loam installed into this project".
+ */
+export function mcpLaunch(cwd, author = false) {
+    const localBin = join(cwd, "node_modules", ".bin", "loam");
+    const args = ["mcp", ...(author ? ["--author"] : [])];
+    return existsSync(localBin)
+        ? { command: "npx", args: ["--no", "loam", ...args] }
+        : { command: "loam", args };
+}
+/** The whole file, exactly as it lands. */
+export function mcpConfigContent(cwd, author = false) {
+    return `${JSON.stringify({ mcpServers: { loam: mcpLaunch(cwd, author) } }, null, 2)}\n`;
+}
+/**
+ * The `"loam": { … }` entry alone, as lines — what init prints when the file
+ * is already there so a person can paste the one key into their own
+ * `mcpServers` object.
+ *
+ * Sliced out of the same object the file is made of rather than spelled a
+ * second time: a snippet that drifts from the bytes is worse than no snippet,
+ * because the reader has no way to tell which of the two is current.
+ */
+export function mcpServerSnippet(cwd, author = false) {
+    return JSON.stringify({ loam: mcpLaunch(cwd, author) }, null, 2)
+        .split("\n")
+        .slice(1, -1)
+        .map((line) => line.slice(2));
+}
+/**
+ * Write `.mcp.json`, or report why not.
+ *
+ * Through the journaled transaction every other loam writer uses, not a bare
+ * `writeFile`: the write is an exclusive create (the existsSync above proves
+ * the path is free), so two inits racing for the same repository serialise
+ * into the same "already there, left alone" answer instead of one of them
+ * silently burying the other's bytes. `root` is the repository being
+ * scaffolded, which is where a killed run's `.loam-commit` belongs — the same
+ * place `gherkin` journals its own writes into a service repo.
+ */
+export async function writeMcpConfig(cwd, author = false) {
+    const path = mcpConfigPath(cwd);
+    if (existsSync(path))
+        return { kind: "skipped" };
+    const staged = await stageWrites([planWrite(path, mcpConfigContent(cwd, author))]);
+    const committed = await commitStaged({
+        root: cwd,
+        command: "init",
+        rerun: author ? "loam init --mcp-author" : "loam init --mcp",
+        target: MCP_CONFIG_FILENAME,
+    }, staged, "written");
+    if (committed.ok)
+        return { kind: "created" };
+    // A lost exclusive create is the never-overwrite contract firing one layer
+    // down — somebody else's `.mcp.json` is there now, and "present, so skipped"
+    // is the answer the probe above would have given a moment later. Nothing of
+    // ours went in; there is no half-state to report.
+    if (committed.raced)
+        return { kind: "skipped" };
+    return { kind: "failed", code: committed.code, message: committed.message };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/init/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/commands/init/mcp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam init --mcp`: the one MACHINE delivery `init` makes.\n *\n * Every other thing init writes is prose an agent reads — command files and\n * Agent Skills, twenty tools' worth of dialects, all of them pointers at\n * `loam instructions`. The MCP facade is the opposite: a typed read surface,\n * four bounded authoring entries under `--author`, version-matched resources,\n * and every result carrying the `--json` envelope as `structuredContent`. It\n * was also the only delivery that required a human to hand-edit a JSON file\n * before anything could reach it — the generated\n * AGENTS.md said no more than \"configure the host to launch `loam mcp` in the\n * repository the tools should answer for\", so a scaffolded repository reliably\n * got the prose deliveries and never the typed one.\n *\n * OPT-IN, and that is not timidity. `.mcp.json` at the repo root is a file a\n * host reads and then STARTS A PROCESS from, for everyone who checks the\n * repository out. Writing one by default would mean `loam init` silently\n * arranging for a binary to be launched on a teammate's machine, which is a\n * decision that belongs to whoever runs the command, not to us.\n *\n * ## Why only the repo-root `.mcp.json`\n *\n * loam knows twenty agent tools and several of them read MCP configuration\n * from a file of their own. None of the others is written here, and a future\n * reader who wants to add them should meet the argument first:\n *\n *   - `.github/.mcp.json` is already in the registry as a Copilot DETECTION\n *     marker (tools/registry.ts). Writing it would make the next `init` detect\n *     Copilot in a repository that has none, because we put the marker there —\n *     a scan reporting its own output back to itself.\n *   - `.cursor/mcp.json` and `.vscode/mcp.json` carry different schemas\n *     (`servers` rather than `mcpServers`, plus per-host keys), so a single set\n *     of bytes cannot serve all three, and one template per host is one more\n *     thing to keep true across releases of somebody else's product.\n *   - `.gemini/settings.json` is a GENERAL settings file. Its MCP block is one\n *     key among many, so loam could only land it by merging into a file the\n *     user owns — and merging into a file a human owns is the one thing every\n *     init delivery is built not to do.\n *\n * The repo-root `.mcp.json` is the form with none of those problems: it is a\n * dedicated file, it is nobody's detection marker, and it is read by the hosts\n * that matter without being owned by any of them.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { planWrite } from \"../../core/staging/writes.js\";\n\nexport const MCP_CONFIG_FILENAME = \".mcp.json\";\n\n/** The one file this delivery writes, so init's `skipped` probe and the writer cannot disagree. */\nexport function mcpConfigPath(cwd: string): string {\n  return join(cwd, MCP_CONFIG_FILENAME);\n}\n\n/** What a host is told to run: the `command`/`args` pair of the `loam` server entry. */\nexport interface McpLaunch {\n  command: string;\n  args: string[];\n}\n\n/**\n * How `loam` is launched HERE, decided from how it is installed here.\n *\n * A fixed `\"command\": \"loam\"` would be an unlaunchable entry in exactly the\n * repositories README tells people to make: the documented install is a\n * per-repo devDependency, which puts the binary in `node_modules/.bin/` and on\n * no PATH an MCP host inherits. So the local bin decides — `npx --no` when it\n * is there, the bare name when it is not.\n *\n * `--no` and not a bare `npx loam mcp`: without it npx will FETCH `loam` from\n * the registry when the local resolution misses, which turns a stale checkout\n * into a silent download of a package with a name loam does not own. With it,\n * a missing local binary is an error the host reports.\n *\n * The probe is the extensionless name on both platforms deliberately: npm's\n * shim writer lays down `loam`, `loam.cmd` and `loam.ps1` together on Windows,\n * the first of them for the POSIX shells that run there, so its presence is the\n * portable question \"is loam installed into this project\".\n */\nexport function mcpLaunch(cwd: string, author = false): McpLaunch {\n  const localBin = join(cwd, \"node_modules\", \".bin\", \"loam\");\n  const args = [\"mcp\", ...(author ? [\"--author\"] : [])];\n  return existsSync(localBin)\n    ? { command: \"npx\", args: [\"--no\", \"loam\", ...args] }\n    : { command: \"loam\", args };\n}\n\n/** The whole file, exactly as it lands. */\nexport function mcpConfigContent(cwd: string, author = false): string {\n  return `${JSON.stringify({ mcpServers: { loam: mcpLaunch(cwd, author) } }, null, 2)}\\n`;\n}\n\n/**\n * The `\"loam\": { … }` entry alone, as lines — what init prints when the file\n * is already there so a person can paste the one key into their own\n * `mcpServers` object.\n *\n * Sliced out of the same object the file is made of rather than spelled a\n * second time: a snippet that drifts from the bytes is worse than no snippet,\n * because the reader has no way to tell which of the two is current.\n */\nexport function mcpServerSnippet(cwd: string, author = false): string[] {\n  return JSON.stringify({ loam: mcpLaunch(cwd, author) }, null, 2)\n    .split(\"\\n\")\n    .slice(1, -1)\n    .map((line) => line.slice(2));\n}\n\n/**\n * What happened to `.mcp.json` on this run. `skipped` is the never-overwrite\n * contract every other init delivery follows, and for the same reason: loam\n * does not merge into a file a human owns, so an existing `.mcp.json` is\n * reported and left byte-for-byte alone — no parse, no key merge, no rewrite.\n */\nexport type McpWrite =\n  | { kind: \"created\" }\n  | { kind: \"skipped\" }\n  | { kind: \"failed\"; code: \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * Write `.mcp.json`, or report why not.\n *\n * Through the journaled transaction every other loam writer uses, not a bare\n * `writeFile`: the write is an exclusive create (the existsSync above proves\n * the path is free), so two inits racing for the same repository serialise\n * into the same \"already there, left alone\" answer instead of one of them\n * silently burying the other's bytes. `root` is the repository being\n * scaffolded, which is where a killed run's `.loam-commit` belongs — the same\n * place `gherkin` journals its own writes into a service repo.\n */\nexport async function writeMcpConfig(cwd: string, author = false): Promise<McpWrite> {\n  const path = mcpConfigPath(cwd);\n  if (existsSync(path)) return { kind: \"skipped\" };\n\n  const staged = await stageWrites([planWrite(path, mcpConfigContent(cwd, author))]);\n  const committed = await commitStaged(\n    {\n      root: cwd,\n      command: \"init\",\n      rerun: author ? \"loam init --mcp-author\" : \"loam init --mcp\",\n      target: MCP_CONFIG_FILENAME,\n    },\n    staged,\n    \"written\",\n  );\n  if (committed.ok) return { kind: \"created\" };\n  // A lost exclusive create is the never-overwrite contract firing one layer\n  // down — somebody else's `.mcp.json` is there now, and \"present, so skipped\"\n  // is the answer the probe above would have given a moment later. Nothing of\n  // ours went in; there is no half-state to report.\n  if (committed.raced) return { kind: \"skipped\" };\n  return { kind: \"failed\", code: committed.code, message: committed.message };\n}\n"]}

package/dist/commands/init/options.js

@@ -0,0 +1,78 @@
+/**
+ * The three questions `loam init` answers before it writes anything: which
+ * agent tools were asked for, where the docs are being recorded, and whether a
+ * directory already IS a docs repo.
+ *
+ * They are here rather than inline because each one has a default that is a
+ * decision. `--tools` has no commander default on purpose, so an explicit flag
+ * stays distinguishable from none — which is what lets the autodetection
+ * fallback and the `--no-*` contradiction be decided rather than silently
+ * arbitrated.
+ */
+import { existsSync } from "node:fs";
+import { fail } from "../../core/envelope/json.js";
+import { agentsPath } from "../../core/repo/paths.js";
+import { docsRepoState } from "../../core/repo/state.js";
+import { AGENT_TOOLS } from "../../core/agent/tools/registry.js";
+import { AGENT_PROFILES, } from "../../core/agent/scaffold.js";
+export function resolveAgentProfile(raw, current, json) {
+    const value = raw ?? current ?? "full";
+    if (AGENT_PROFILES.includes(value))
+        return value;
+    fail(json, "invalid-option", `Unknown --agent-profile '${value}'. Expected: ${AGENT_PROFILES.join(" | ")}.`);
+    return null;
+}
+/**
+ * Resolve --tools to registry ids, or null after reporting the refusal. The
+ * default (the cwd scan) lives at the call site, not in commander, so an
+ * explicit `--tools` is distinguishable from none — which is what lets both the
+ * autodetection fallback and the `--no-*` contradiction be decided instead of
+ * silently arbitrated.
+ */
+export function resolveTools(raw, json) {
+    const supported = Object.keys(AGENT_TOOLS);
+    if (raw === "all")
+        return supported;
+    const ids = [...new Set(raw.split(",").map((t) => t.trim()).filter((t) => t !== ""))];
+    const unknown = ids.filter((t) => !(t in AGENT_TOOLS));
+    if (ids.length === 0 || unknown.length > 0) {
+        fail(json, "invalid-option", (ids.length === 0
+            ? "--tools names no tool."
+            : `--tools does not recognize: ${unknown.join(", ")}.`) +
+            ` Supported: ${supported.join(", ")} — or "all".`);
+        return null;
+    }
+    return ids;
+}
+/**
+ * `--docs` exactly as the caller wrote it, with separators normalised.
+ *
+ * Stored verbatim on purpose. `init` used to resolve it and write the absolute
+ * result, which meant a committed loam.json named a directory that existed on
+ * one laptop: every teammate who cloned the service repo got a docsDir under
+ * someone else's home directory, and `loam list` reported an empty fleet
+ * instead of saying so. `loadConfig` resolves relative paths against the config
+ * file's own directory, so `../docs` keeps meaning "next to this repo" wherever
+ * the pair is checked out. An absolute `--docs` is still stored absolute — that
+ * is the caller's explicit choice, and `loam doctor` warns about it.
+ *
+ * Backslashes become forward slashes so a config written on Windows resolves on
+ * POSIX; a trailing separator is dropped so the stored spelling is stable.
+ */
+export function storedDocsDir(raw) {
+    const slashed = raw.split("\\").join("/");
+    if (slashed.length <= 1)
+        return slashed;
+    const trimmed = slashed.replace(/\/+$/, "");
+    return trimmed === "" ? "/" : trimmed;
+}
+/**
+ * Does this directory already hold a docs repo? `services/` plus `AGENTS.md` —
+ * the two things every docs repo has and no service repo does. The pair is the
+ * whole point: a single marker would make `init --docs ../srv` (a typo for
+ * `../docs`) look like a join and adopt the service repo as the fleet.
+ */
+export function isDocsRepo(dir) {
+    return docsRepoState(dir).kind === "ok" && existsSync(agentsPath(dir));
+}
+//# sourceMappingURL=options.js.map

package/dist/commands/init/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/commands/init/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,EACL,cAAc,GAEf,MAAM,8BAA8B,CAAC;AAEtC,MAAM,UAAU,mBAAmB,CACjC,GAAuB,EACvB,OAAiC,EACjC,IAAa;IAEb,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,IAAI,MAAM,CAAC;IACvC,IAAI,cAAc,CAAC,QAAQ,CAAC,KAAqB,CAAC;QAAE,OAAO,KAAqB,CAAC;IACjF,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,4BAA4B,KAAK,gBAAgB,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7G,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,IAAa;IACrD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;IACvD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;YACf,CAAC,CAAC,wBAAwB;YAC1B,CAAC,CAAC,+BAA+B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YACvD,eAAe,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CACpD,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IACxC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACzE,CAAC","sourcesContent":["/**\n * The three questions `loam init` answers before it writes anything: which\n * agent tools were asked for, where the docs are being recorded, and whether a\n * directory already IS a docs repo.\n *\n * They are here rather than inline because each one has a default that is a\n * decision. `--tools` has no commander default on purpose, so an explicit flag\n * stays distinguishable from none — which is what lets the autodetection\n * fallback and the `--no-*` contradiction be decided rather than silently\n * arbitrated.\n */\nimport { existsSync } from \"node:fs\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { fail } from \"../../core/envelope/json.js\";\nimport { agentsPath } from \"../../core/repo/paths.js\";\nimport { docsRepoState } from \"../../core/repo/state.js\";\nimport { AGENT_TOOLS } from \"../../core/agent/tools/registry.js\";\nimport {\n  AGENT_PROFILES,\n  type AgentProfile,\n} from \"../../core/agent/scaffold.js\";\n\nexport function resolveAgentProfile(\n  raw: string | undefined,\n  current: AgentProfile | undefined,\n  json: boolean,\n): AgentProfile | null {\n  const value = raw ?? current ?? \"full\";\n  if (AGENT_PROFILES.includes(value as AgentProfile)) return value as AgentProfile;\n  fail(json, \"invalid-option\", `Unknown --agent-profile '${value}'. Expected: ${AGENT_PROFILES.join(\" | \")}.`);\n  return null;\n}\n\n/**\n * Resolve --tools to registry ids, or null after reporting the refusal. The\n * default (the cwd scan) lives at the call site, not in commander, so an\n * explicit `--tools` is distinguishable from none — which is what lets both the\n * autodetection fallback and the `--no-*` contradiction be decided instead of\n * silently arbitrated.\n */\nexport function resolveTools(raw: string, json: boolean): string[] | null {\n  const supported = Object.keys(AGENT_TOOLS);\n  if (raw === \"all\") return supported;\n  const ids = [...new Set(raw.split(\",\").map((t) => t.trim()).filter((t) => t !== \"\"))];\n  const unknown = ids.filter((t) => !(t in AGENT_TOOLS));\n  if (ids.length === 0 || unknown.length > 0) {\n    fail(\n      json,\n      \"invalid-option\",\n      (ids.length === 0\n        ? \"--tools names no tool.\"\n        : `--tools does not recognize: ${unknown.join(\", \")}.`) +\n        ` Supported: ${supported.join(\", \")} — or \"all\".`,\n    );\n    return null;\n  }\n  return ids;\n}\n\n/**\n * `--docs` exactly as the caller wrote it, with separators normalised.\n *\n * Stored verbatim on purpose. `init` used to resolve it and write the absolute\n * result, which meant a committed loam.json named a directory that existed on\n * one laptop: every teammate who cloned the service repo got a docsDir under\n * someone else's home directory, and `loam list` reported an empty fleet\n * instead of saying so. `loadConfig` resolves relative paths against the config\n * file's own directory, so `../docs` keeps meaning \"next to this repo\" wherever\n * the pair is checked out. An absolute `--docs` is still stored absolute — that\n * is the caller's explicit choice, and `loam doctor` warns about it.\n *\n * Backslashes become forward slashes so a config written on Windows resolves on\n * POSIX; a trailing separator is dropped so the stored spelling is stable.\n */\nexport function storedDocsDir(raw: string): string {\n  const slashed = raw.split(\"\\\\\").join(\"/\");\n  if (slashed.length <= 1) return slashed;\n  const trimmed = slashed.replace(/\\/+$/, \"\");\n  return trimmed === \"\" ? \"/\" : trimmed;\n}\n\n/**\n * Does this directory already hold a docs repo? `services/` plus `AGENTS.md` —\n * the two things every docs repo has and no service repo does. The pair is the\n * whole point: a single marker would make `init --docs ../srv` (a typo for\n * `../docs`) look like a join and adopt the service repo as the fleet.\n */\nexport function isDocsRepo(dir: DocsDir): boolean {\n  return docsRepoState(dir).kind === \"ok\" && existsSync(agentsPath(dir));\n}\n"]}