craftar 0.13.0 → 0.15.0

package/README.md

@@ -2,7 +2,7 @@
 
 Craft, sync and convert AI-coding workspace harnesses — rules, agents, commands, skills, MCP servers — across every client workspace you maintain and every AI coder each team uses.
 
-> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
+> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). `craftar doctor` reports, one line per finding, what is off on this machine and in this workspace. Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
 
 ## The idea in one paragraph
 
@@ -27,6 +27,17 @@ node bin/craftar.js --help
 npx tsx src/cli.ts --help
 ```
 
+## Quick start: start an empty workspace from a Forge
+
+```bash
+# Writes craftar.yaml (forge, profile) once it resolves and plans, then runs the first sync.
+craftar init --workspace C:/Projects/acme-portal-workspace \
+  --forge   C:/Projects/forge \
+  --profile acme-portal
+```
+
+The workspace follows the profile's recipes and targets; `--add-recipe` / `--remove-recipe` adjust the recipes, and `--targets` writes the targets into `craftar.yaml`. When the directory already holds a harness, files equal to the Forge's are adopted and different ones are left as they are and reported — `craftar import` (below) brings them into the Forge.
+
 ## Quick start: bring an existing workspace into a Forge
 
 ```bash
@@ -52,6 +63,7 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 
 | Command | What it does |
 |---|---|
+| `craftar init --forge <dir\|url> --profile <name> [--ref <ref>] [--targets <a,b>] [--add-recipe <name>]... [--remove-recipe <name>]... [--replace] [--no-sync] [--offline] [--workspace .]` | Starts a workspace: writes a `craftar.yaml` holding `forge` (a directory as the path from the workspace, POSIX; a URL as given), `ref` (a remote Forge only), `profile`, `recipes` (only the lists the recipe flags leave non-empty) and `targets` (only with `--targets`; otherwise the workspace follows the profile's), then runs the first `sync` — which also registers the workspace. The file is written only once the configuration loads (a remote Forge is fetched as `sync` fetches it; `--offline` reads the cache), resolves and plans, and the sync applies that same plan. `--remove-recipe` and `--add-recipe` go through `remove recipe` / `add recipe`'s core (removes first, then adds; `--replace` swaps a slot holder); a call whose every name changes nothing prints its reasons as a `note`. `--workspace` is created when missing. Files already on disk and not in a lock are adopted when equal to the plan and skipped as a `collision` otherwise, never overwritten, with one warning pointing at `craftar import`. `--no-sync` writes `craftar.yaml` only and prints what the first `sync` would do. Refused, with nothing written and no directory created: an existing `craftar.yaml`; a `--workspace` that is a file; credentials in `--forge` (the value is never printed); `--ref` with a directory Forge; an unknown target; a recipe both added and removed, or any refusal of `add recipe` / `remove recipe`; a `craftar.local.yaml` that sets `forge` or `profile`, or a key a given flag would write (`ref`, `recipes`, `targets`) — its value would replace the flag's; a Forge, profile or plan that does not load. |
 | `craftar import --from claude-code --forge <dir> --profile <name> [--workspace .] [--write-config]` | Reads `.claude/{rules,agents,commands,skills,scripts,hooks}`, `.mcp.json` and, when present, `.kiro/steering` (for inclusion modes and hand-written steering). Creates ingredients, recipes (`base`, one `stack-*` per scoped rule, `<profile>-steering`) and a profile, or updates them. An ingredient already in the Forge is reused when the base, **rendered** for this profile (its declared defaults, the profile's `params`, the workspace's `overrides.params`), equals the workspace file; failing that, when a unique, proved assignment of the base's declared `{{keys}}` reproduces it, the values are **inferred** into the profile's `params` (one value per key per run; never a change another ingredient would feel). A base with section markers is rendered with the profile's `sections` and the workspace's `overrides.sections` first; when the workspace file differs from it only inside sections, the unique content that reproduces the file byte for byte is **inferred** into the profile's `sections` (tried after params, never combined with them; the report counts lines and never prints the content). An import that writes a section value, or compares a workspace file against a base holding markers, sets `schema: 2` in `craftar.forge.yaml`. A reused base takes the place its `<name>--<profile>` variant held: the profile moves to the shared recipe when that orders the base there, and an owned recipe gets the base in the variant's slot, so the rule order (and `AGENTS.md`) stays as it was. Anything else becomes a `<name>--<profile>` variant that emits under the original name, with the reason, so the workspace still round-trips while you decide what to unify. A shared recipe is never widened for one client: a profile whose ingredients differ from `base` or a `stack-*` gets its own `<recipe>--<profile>`. An existing profile is merged in place (`params`, `sections`, the recipes import owns, missing `targets`; every other field and comment kept, and an empty `{}` / `[]` it does not change stays on its line), as is a recipe the profile owns; `--write-config` merges an existing `craftar.yaml` (`forge`, `profile`, `targets`). The report adds `rendered` (with `sections <names>` when a section value filled the render), `inferred`, `sectioned`, `param <key>: <old> → <new>`, `section <key> <name>: <old> → <new>`, `forge craftar.forge.yaml edited (schema: 2)` and `profile … created\|edited\|unchanged` lines. It refuses, with the Forge untouched, a Forge that does not load, a profile or recipe or `craftar.yaml` that does not round-trip through the YAML writer, a misplaced profile, a recipe import writes whose file and `name` disagree, a workspace override that does not parse, a literal `{{key}}` the profile would render, changing a recipe or variant another profile uses, a workspace file holding a section marker at column 0 (sync would not reproduce it: indent it), a Forge base with malformed section markers, and a `craftar.forge.yaml` it needs to bump to `schema: 2` that does not round-trip (set it by hand). Ingredients holding a secret-like value (tokens, private keys, high-entropy MCP `env`/`args` values) are rejected and listed by location — the value is never printed. A UTF-16 file with a byte-order mark is decoded for the scan; UTF-16 without one is not detected. An ingredient that would not load back into the Forge (a name that is not slug-like, a non-string MCP `env` value) refuses the import, naming its source; so does an ingredient already in the Forge whose `ingredient.yaml` has an unknown key or a YAML syntax error, naming that file. Every read and check runs before the first write, so an import that fails leaves the Forge untouched and says so. |
 | `craftar status` | With a remote Forge, the header's second line names it — `forge <url> @ <ref \| <branch> (default branch)> <commit>`, plus `· lock <commit>` when the Forge moved since the last sync — and `--json` carries `forge: {kind, source, ref, defaultBranch, commit, lockCommit, fetched}` for every Forge. Classifies every file the Forge would produce: `new`, `update`, `unchanged`, `adopt`, `drift`, `collision`, `orphan`, `orphan-drift`. A `.json` file not yet in `craftar.lock` that parses to the planned value with its keys in the same order (it differs only in whitespace, escapes, number spelling or duplicate keys) is `adopt`, and the first `sync` rewrites it with the planned bytes — by design. For `claude-code`'s `.mcp.json` that is two-space JSON keeping the file's BOM and line endings; Kiro's JSON files become CRLF without a BOM, like every Kiro text file. A different key order is a `collision` — except for integer-like keys, which `JSON.parse` reorders. A locked JSON file reformatted by hand is `drift`, not `adopt`. `--json` for tooling. Exits 1 on malformed section markers and on a section marker in an ingredient the workspace resolves while `craftar.forge.yaml` declares `schema: 1` (or none), naming the Forge file and line, and when a rendered file would still hold a marker line, naming the ingredient, file and rendered line — as do `sync`, `diff`, `explain` and `ls`. Warns about a section value that names no ingredient, or no marker of an ingredient the workspace resolves, and about marker lines in an emitted file not every target renders as text (copied as they are). |
 | `craftar sync` | Renders sections (no rendered body holds a marker; an emitted file not every target renders as text keeps its markers, with a warning), then writes the plan and `craftar.lock` (schema 2: the Forge's source, requested `ref` and commit, the resolved recipes and targets — rewritten only when that content changes). With a remote Forge it fetches first and exits 1 when the fetch fails, `--dry-run` and `--check` included. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default). A writing `sync` (not `--dry-run`, not `--check`) also records the workspace in `$CRAFTAR_HOME/registry.json` (see *Workspace registry*); a registry it cannot write is a warning, never a failed `sync`. |
@@ -59,6 +71,7 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar explain <path>` | Which ingredient, recipe chain, target and origin produced a file and, for an ingredient with sections, which layer filled each one: `sections    flavors (profile globex), extra (default)` (`default`, `profile <p>` or `workspace`). `AGENTS.md` gets no sections line: it is not one ingredient. |
 | `craftar ls` | Recipes and ingredients resolved for this workspace. |
 | `craftar workspaces [--fetch] [--json]` | Every workspace a writing `sync` registered on this machine, sorted by path: name, path, profile, stack (`slot=recipe`), targets, the Forge, the last sync, and a status computed now — `up to date`, `outdated` (`new`, `update` or `orphan` pending), `drift` (a `drift`, `orphan-drift` or `collision`), `no lock`, `missing` (directory or `craftar.yaml` gone) or `error` (it no longer loads, plans or reads its lock), plus `forge moved` when the Forge's commit differs from the lock's. Read without the network: a remote Forge comes from the cache; `--fetch` fetches first. Each row's warnings print after the table, prefixed with its path. Times are UTC. Writes nothing. Exits 0 whenever the table prints. Takes no `--workspace`. `--json` is a contract: `{registry, fetch, workspaces, warnings}`. |
+| `craftar doctor [--workspace <dir>] [--fetch] [--strict] [--json]` | Checks this machine — Node ≥ 22, `git`, `$CRAFTAR_HOME`, the registry (entries whose workspace is gone), the Forge cache (its size, entries nothing names, a fetch that never completed) — and, when run inside one (the current directory, or `--workspace`), this workspace: the configuration and its Forge (cached, fetched or pinned), whether the workspace sits inside its Forge, the plan's warnings, declared parameters with no value, the `${NAME}` variables a written MCP server expects and this environment lacks (names only, never values), the lock, `status`, and registration. One line per finding — `ok`, `warn` or `error` — each problem with the command that fixes it; each cause is reported once. It only reports: nothing is written to a workspace, a lock or the registry, and the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Read without the network; `--fetch` fetches a remote Forge first. Exits 1 on an `error`, or on a `warn` under `--strict`; an explicit `--workspace` without `craftar.yaml` exits 1, while the current directory without one runs the machine checks only. `--json` is a contract: `{version, workspace, fetch, strict, checks: [{id, scope, level, message, fix}], summary}`. |
 | `craftar workspaces forget <dir>` / `craftar workspaces prune` | `forget` removes one entry (the directory is not touched; an unregistered path exits 1); `prune` removes every `missing` entry and never an `error` one. Nothing else removes an entry. |
 | `craftar recipes [--forge <dir> [--profile <name>] \| --workspace <dir>] [--json]` | Every recipe of the Forge, sorted by name: slot, the parents it extends, the ingredients it lists itself and the profiles that reach it. In a workspace (or with `--forge <dir> --profile <name>`) each recipe says whether it is in use and why — `profile`, `workspace` (`recipes.add`), `extends <child>` — and a recipe `recipes.remove` names reads `removed by this workspace`. A context that does not resolve (two recipes on one slot, an unknown recipe, a cycle) still lists everything, marks nothing and warns. Read-only: it resolves, never plans. `--json` is a contract: `{forge, context, recipes, warnings}`. |
 | `craftar ingredients [--recipe <name>] [--type <type>] [--forge <dir> [--profile <name>] \| --workspace <dir>] [--json]` | Every ingredient of the Forge, grouped by type: output name, targets, the recipes that list it, and whether the context uses it or the workspace disables it; a reference a recipe makes to an ingredient the Forge does not hold is listed under `missing`, never dropped. `--recipe <name>` lists what choosing that recipe brings, with the parents it extends, parents first; two of them on one slot is a warning. `--type` keeps one type. Read-only. `--json` is a contract: `{forge, context, recipe, ingredients, missing, warnings}`. |
@@ -275,11 +288,22 @@ A writing `sync` records the workspace in `$CRAFTAR_HOME/registry.json` (`~/.cra
 
 ## Roadmap (from the functional spec)
 
-Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock); the workspace registry and `craftar workspaces`.
-Next: `craftar init` from a profile; profile-driven integrations (PM tool → MCP, IDP → MCP); `service` ingredients with compose fragments (`craftar services up`); `dotnet new` template registration; rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
+Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock); the workspace registry and `craftar workspaces`; `craftar add recipe` / `remove recipe`; `craftar init` with flags; `craftar doctor`.
+Next: an interactive `craftar init` (choose the Forge and the profile); cloning a profile's repositories at init; profile-driven integrations (PM tool → MCP, IDP → MCP); `service` ingredients with compose fragments (`craftar services up`); `dotnet new` template registration; rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
 
 ## Upgrading
 
+### to 0.15.0
+
+- **New command `craftar doctor`**: reports, one line per finding, what is off on this machine and in this workspace. Its `--json` output is a tooling contract, like `status --json`.
+- **No byte change**: no emitter, `plan` output, `status` or lock changed. No workspace sees `update`.
+
+### to 0.14.0
+
+- **New command `craftar init`**: writes `craftar.yaml` in a workspace that has none, then runs the first `sync`. It never edits an existing `craftar.yaml`.
+- **A missing `craftar.yaml`** is now reported with `craftar init --workspace "<dir>" --forge <dir> --profile <name>` first and `craftar import … --write-config` second, by every command that reads the workspace. Only the message changes; the exit code does not.
+- **No byte change**: no emitter, `plan`, `status`, `sync` or lock changed. No workspace sees `update`.
+
 ### to 0.13.0
 
 - **New commands `craftar add recipe` and `craftar remove recipe`**: they edit `recipes.add` / `recipes.remove` in `craftar.yaml` and nothing else; they never sync.

package/dist/cli.js

@@ -6,6 +6,7 @@ import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
 import { classifyForge } from "./core/remote.js";
 import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.js";
+import { runDoctor } from "./core/doctor.js";
 import { resolveHome } from "./core/home-lock.js";
 import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
 import { resolve, sectionKey } from "./core/resolve.js";
@@ -19,8 +20,9 @@ import { exists, gitDirty, gitIsRepo, gitUnheld } from "./core/forge.js";
 import { fingerprintDir } from "./core/fingerprint.js";
 import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, } from "./core/unify.js";
 import { checkParamWrites, writeParamFile } from "./core/param-writes.js";
+import { planInit } from "./core/init.js";
 import { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
-import { parseWorkspaceYaml } from "./core/workspace-yaml.js";
+import { localKeys } from "./core/workspace-yaml.js";
 import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 process.stdout.on("error", (e) => { if (e.code === "EPIPE")
     process.exit(0); });
@@ -31,7 +33,7 @@ process.stdout.on("error", (e) => { if (e.code === "EPIPE")
  */
 const DIFF_EXIT_CODE_FETCH_MODE = "sync";
 const program = new Command();
-program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.13.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.15.0");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -100,34 +102,15 @@ program
         return console.log(JSON.stringify({ forge: forgeJson(ws, lock), statuses: st.map(({ planned, ...s }) => s), warnings: p.warnings }, null, 2));
     printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, false, forgeLine(ws, lock));
 });
-/* ---------------------------------------------------------------- sync */
-program
-    .command("sync")
-    .description("Generate the harness for every target from the Forge and update craftar.lock; a writing sync also records the workspace in $CRAFTAR_HOME/registry.json (see craftar workspaces)")
-    .option("--workspace <dir>", "workspace root", ".")
-    .option("--check", "exit 1 when the workspace is out of date or has drift (CI mode)", false)
-    .option("--dry-run", "show the plan, write nothing", false)
-    .option("--overwrite-drift", "regenerate files that were hand-edited (their edits are lost)", false)
-    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
-    .action(async (o) => {
-    const ws = await loadWorkspace(o.workspace, load(o, "sync"));
-    const p = await plan(ws);
-    const lock = await readLock(ws.root);
-    const st = await status(ws, p, lock);
-    if (o.check) {
-        const bad = st.filter((s) => !["unchanged", "adopt"].includes(s.state));
-        printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, true, forgeLine(ws, lock));
-        if (bad.length) {
-            console.log(pc.red(`\n${bad.length} file(s) out of sync`));
-            process.exit(1);
-        }
-        console.log(pc.green("\nworkspace in sync"));
-        return;
-    }
-    const r = await apply(ws, p, st, { dryRun: o.dryRun, overwriteDrift: o.overwriteDrift });
+/**
+ * A writing sync on a planned workspace, then its report: `apply`, the registration of spec 21 (unless
+ * `CRAFTAR_NO_REGISTRY`), and the lines `sync` prints. `sync` and `init` both call it (spec 23 §5.2).
+ */
+async function applyAndReport(ws, p, st, lock, opts = {}) {
+    const r = await apply(ws, p, st, opts);
     // A writing sync records the workspace (spec 21 §4.1); the registry is an index, so a failure is a warning.
     let registryWarning = null;
-    if (!o.dryRun && !registryOff()) {
+    if (!opts.dryRun && !registryOff()) {
         const home = craftarHome();
         try {
             await register(home, ws, p);
@@ -136,7 +119,7 @@ program
             registryWarning = `registry not updated (${registryFile(home)}): ${e instanceof Error ? e.message : String(e)}`;
         }
     }
-    const verb = o.dryRun ? "would write" : "wrote";
+    const verb = opts.dryRun ? "would write" : "wrote";
     console.log(pc.bold(`craftar sync — profile ${ws.config.profile} · recipes ${p.resolution.recipes.join(" → ")} · targets ${p.resolution.targets.join(", ")}`));
     const fl = forgeLine(ws, lock);
     if (fl)
@@ -152,6 +135,92 @@ program
         console.log(`  ${pc.yellow("warn")} ${w}`);
     if (registryWarning)
         console.log(`  ${pc.yellow("warn")} ${registryWarning}`);
+    return r;
+}
+/* ---------------------------------------------------------------- init */
+program
+    .command("init")
+    .description("Start a workspace from a Forge and a profile: write a craftar.yaml proved to resolve and plan, then run the first sync; refused when craftar.yaml already exists")
+    .requiredOption("--forge <dir|url>", "the Forge: a directory (written relative to the workspace) or a git URL")
+    .requiredOption("--profile <name>", "the client profile in the Forge")
+    .option("--ref <ref>", "branch, tag or full SHA of a remote Forge")
+    .option("--targets <a,b>", "targets to write in craftar.yaml (claude-code, kiro, agents-md); omitted, the workspace follows the profile's")
+    .option("--add-recipe <name>", "add a recipe to the profile's (repeatable)", collect, [])
+    .option("--remove-recipe <name>", "remove a recipe of the profile's (repeatable)", collect, [])
+    .option("--replace", "let --add-recipe take a slot another recipe holds", false)
+    .option("--no-sync", "write craftar.yaml only, and say what the first sync would do")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .option("--workspace <dir>", "workspace root, created when missing", ".")
+    .action(async (o) => {
+    const root = path.resolve(o.workspace);
+    const n1 = () => fail(`${WORKSPACE_FILE} already exists in ${root} — change recipes with craftar add recipe / remove recipe, or edit it`);
+    const file = path.join(root, WORKSPACE_FILE);
+    if (await exists(file))
+        n1();
+    const st = await fs.stat(root).catch(() => null);
+    if (st && !st.isDirectory())
+        fail(`cannot use ${root} as a workspace: it is not a directory`);
+    const init = await planInit(root, {
+        forge: o.forge,
+        profile: o.profile,
+        ref: o.ref,
+        targets: o.targets === undefined ? undefined : o.targets.split(",").map((t) => t.trim()),
+        addRecipes: o.addRecipe,
+        removeRecipes: o.removeRecipe,
+        replace: o.replace,
+    }, load(o, "sync"));
+    const { ws, plan: p } = init;
+    // Every refusal is above: only now does the directory, and craftar.yaml, come to exist (§13 items 1, 9).
+    await fs.mkdir(root, { recursive: true });
+    try {
+        await fs.writeFile(file, init.text, { flag: "wx" });
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            n1();
+        throw e;
+    }
+    const from = { flag: "", local: ` (from ${LOCAL_FILE})`, profile: " (from the profile)" }[init.targetsFrom];
+    console.log(pc.bold(`craftar init — wrote ${WORKSPACE_FILE} in ${root}`));
+    console.log(`  forge ${ws.config.forge} · profile ${ws.config.profile} · recipes ${p.resolution.recipes.join(" → ")} · targets ${p.resolution.targets.join(", ")}${from}`);
+    for (const n of init.notes)
+        console.log(`  note ${n}`);
+    if (!o.sync) {
+        console.log(nextSyncLine(init.statuses));
+        for (const w of p.warnings)
+            console.log(`  ${pc.yellow("warn")} ${w}`);
+        return;
+    }
+    const r = await applyAndReport(ws, p, init.statuses, init.lock);
+    const collisions = r.skipped.filter((s) => s.state === "collision").length;
+    if (collisions)
+        console.log(`  ${pc.yellow("warn")} ${collisions} file(s) already in the workspace differ from the Forge and were left as they are — to bring them into the Forge, run craftar import`);
+});
+/* ---------------------------------------------------------------- sync */
+program
+    .command("sync")
+    .description("Generate the harness for every target from the Forge and update craftar.lock; a writing sync also records the workspace in $CRAFTAR_HOME/registry.json (see craftar workspaces)")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--check", "exit 1 when the workspace is out of date or has drift (CI mode)", false)
+    .option("--dry-run", "show the plan, write nothing", false)
+    .option("--overwrite-drift", "regenerate files that were hand-edited (their edits are lost)", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .action(async (o) => {
+    const ws = await loadWorkspace(o.workspace, load(o, "sync"));
+    const p = await plan(ws);
+    const lock = await readLock(ws.root);
+    const st = await status(ws, p, lock);
+    if (o.check) {
+        const bad = st.filter((s) => !["unchanged", "adopt"].includes(s.state));
+        printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, true, forgeLine(ws, lock));
+        if (bad.length) {
+            console.log(pc.red(`\n${bad.length} file(s) out of sync`));
+            process.exit(1);
+        }
+        console.log(pc.green("\nworkspace in sync"));
+        return;
+    }
+    await applyAndReport(ws, p, st, lock, { dryRun: o.dryRun, overwriteDrift: o.overwriteDrift });
 });
 /* ---------------------------------------------------------------- diff */
 program
@@ -208,17 +277,20 @@ program
 /** The states `next sync:` counts, in `FileState` declaration order (spec 22 §14 item 6); a new state does not compile until it is placed here. */
 const NEXT_SYNC = { new: true, update: true, drift: true, adopt: true, collision: true, orphan: true, "orphan-drift": true };
 const NEXT_SYNC_STATES = Object.keys(NEXT_SYNC);
+/** Spec 22's line: what the next sync would do, over `NEXT_SYNC_STATES` (also `init --no-sync`, spec 23 §4.4). */
+function nextSyncLine(st) {
+    const counts = NEXT_SYNC_STATES.map((k) => [k, st.filter((s) => s.state === k).length])
+        .filter(([, n]) => n > 0)
+        .map(([k, n]) => `${n} ${k}`);
+    return `next sync: ${counts.length ? `${counts.join(", ")} — run \`craftar sync\`` : "nothing to sync"}`;
+}
 function recipeCommand(op) {
     return async (names, o) => {
         const ws = await loadWorkspace(o.workspace, load(o, "read"));
         warnStderr(ws.warnings);
         // R1: arrays replace across layers, so an edit of craftar.yaml would not take effect (spec 22 Ruling 1).
-        const localFile = path.join(ws.root, LOCAL_FILE);
-        if (await exists(localFile)) {
-            const local = parseWorkspaceYaml(LOCAL_FILE, await fs.readFile(localFile, "utf8"));
-            if (local !== null && typeof local === "object" && "recipes" in local)
-                fail(`${LOCAL_FILE} sets recipes, which replaces ${WORKSPACE_FILE}'s lists — edit it by hand, or remove its recipes key and re-run`);
-        }
+        if ((await localKeys(ws.root)).includes("recipes"))
+            fail(`${LOCAL_FILE} sets recipes, which replaces ${WORKSPACE_FILE}'s lists — edit it by hand, or remove its recipes key and re-run`);
         const edit = planRecipeEdit(ws.forge, ws.config, op, names, { replace: o.replace === true });
         if (!edit.changed) {
             console.log(`nothing to change${edit.reasons.length ? `: ${edit.reasons.join(", ")}` : ""}`);
@@ -230,13 +302,11 @@ function recipeCommand(op) {
         const next = { ...ws, config: { ...ws.config, recipes: edit.recipes } };
         const p = await plan(next);
         const st = await status(next, p, await readLock(ws.root));
-        const counts = NEXT_SYNC_STATES.map((k) => [k, st.filter((s) => s.state === k).length])
-            .filter(([, n]) => n > 0)
-            .map(([k, n]) => `${n} ${k}`);
+        const nextLine = nextSyncLine(st);
         await fs.writeFile(file, content);
         console.log(`${WORKSPACE_FILE}: ${recipeDiffLine(ws.config.recipes, edit.recipes)}`);
         console.log(`recipes: ${p.resolution.recipes.join(" → ")}`);
-        console.log(`next sync: ${counts.length ? `${counts.join(", ")} — run \`craftar sync\`` : "nothing to sync"}`);
+        console.log(nextLine);
         // plan() already carries ws.warnings first, and they were printed on load.
         warnStderr(p.warnings.slice(ws.warnings.length));
     };
@@ -345,6 +415,40 @@ workspaces
     for (const p of gone)
         console.log(`pruned ${p}`);
 });
+/* ---------------------------------------------------------------- doctor */
+program
+    .command("doctor")
+    .description("Check this machine (Node, git, $CRAFTAR_HOME, the registry, the Forge cache) and, inside one, this workspace (configuration and Forge, plan, declared parameters, MCP environment variables, lock, status, registration): one line per finding — ok, warn or error — each with its fix. Reports only; reads without the network unless --fetch")
+    // No commander default: an explicit --workspace without craftar.yaml exits 1, the current directory without one runs the machine checks (spec 24 §4.1).
+    .option("--workspace <dir>", "the workspace to check (default: the current directory, when it holds craftar.yaml)")
+    .option("--fetch", "fetch a remote Forge first instead of reading the cached copy", false)
+    .option("--strict", "exit 1 on a warn too, not only on an error", false)
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    let workspace = null;
+    if (o.workspace !== undefined) {
+        if (!(await exists(path.join(o.workspace, WORKSPACE_FILE))))
+            fail(`no ${WORKSPACE_FILE} in ${path.resolve(o.workspace)} — run doctor inside a workspace, or without --workspace for the machine checks`);
+        workspace = o.workspace;
+    }
+    else if (await exists(path.join(process.cwd(), WORKSPACE_FILE)))
+        workspace = process.cwd();
+    const report = await runDoctor({
+        version: program.version() ?? "unknown",
+        home: craftarHome(),
+        workspace,
+        fetch: o.fetch,
+        strict: o.strict,
+        registryOff: registryOff(),
+    });
+    if (o.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        printDoctor(report);
+    // exitCode, not process.exit: a piped --json is never cut (spec 24 §5.1).
+    if (report.summary.error > 0 || (o.strict && report.summary.warn > 0))
+        process.exitCode = 1;
+});
 /* ---------------------------------------------------------------- recipes */
 program
     .command("recipes")
@@ -1102,10 +1206,24 @@ async function forgeFor(o) {
     warnStderr(workspace?.warnings ?? []);
     return forge;
 }
+/** A repeatable option's values, in the order given. */
+function collect(value, previous) {
+    return [...previous, value];
+}
 /** `$CRAFTAR_HOME`, as the cache reads it (spec 13 §6.3). */
 function craftarHome() {
     return resolveHome(process.env.CRAFTAR_HOME || undefined);
 }
+/** The text report of `craftar doctor` (spec 24 §4.4) — presentation, not contract. */
+function printDoctor(r) {
+    console.log(pc.bold(`craftar doctor — craftar ${r.version} · ${r.workspace ?? "no workspace (machine checks only)"}`));
+    const paint = (l) => (l === "error" ? pc.red : l === "warn" ? pc.yellow : pc.dim)(l.padEnd(6));
+    // A message that already ends in its fix (a refused schema says "— upgrade craftar") is not suffixed twice.
+    const suffix = (c) => (c.fix && c.level !== "ok" && !c.message.endsWith(c.fix) ? ` — ${c.fix}` : "");
+    for (const c of r.checks)
+        console.log(`  ${paint(c.level)} ${c.id.padEnd(13)} ${c.message}${suffix(c)}`);
+    console.log(`summary: ${r.summary.ok} ok, ${r.summary.warn} warn, ${r.summary.error} error`);
+}
 /** `CRAFTAR_NO_REGISTRY` — "no registry", read like NO_COLOR: any non-empty value turns it off (spec 21 §4.1). */
 function registryOff() {
     return Boolean(process.env.CRAFTAR_NO_REGISTRY);