craftar 0.8.6 → 0.10.1

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*). 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. 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
 
@@ -55,14 +55,17 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `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` | 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`. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default). |
-| `craftar diff [path]` | Line diff between disk and what the Forge would generate. |
+| `craftar diff [path] [--exit-code]` | Line diff between disk and what the Forge would generate, for every file `sync --check` refuses: `update`, `drift`, `collision`, `new`, an `orphan` (shown as the removal of the whole file — the next `sync` deletes it) and an `orphan-drift` (a header and one line: `sync` keeps it). `[path]` limits it to the one file whose workspace-relative path, as `status` prints it, equals it. Exits 0 by default, differences or not. `--exit-code` exits 1 when there are differences — exactly when `sync --check` would — and makes a `[path]` that names no file craftar manages an error (exit 1, nothing on stdout); without the flag such a path prints `no differences`. |
 | `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 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}`. |
+| `craftar targets [--workspace <dir>] [--json]` | The capability matrix (see *Targets*): what each target does with each ingredient type, the paths it writes and what changes. Needs no Forge; inside a workspace it marks the targets in use, and when that workspace does not load or resolve it prints the matrix unmarked with a warning. An explicit `--workspace <dir>` without a `craftar.yaml` exits 1; the current directory without one just prints the matrix unmarked. `--json` is a contract: `{ingredientTypes, targets, warnings}`. |
 | `craftar forge variants [--forge <dir> \| --workspace <dir>] [--json]` | Lists ingredients that have variants, nearest first, with the profile each came from, its distance to the base and its hunks counted by suggested class (`[1 evolution · 2 block]`), then any variant whose base is missing from the Forge. Read-only; exits 0 either way. `--json` prints `{groups, orphans}`; each variant carries `classes: {evolution, value, block}`, which add up to `distance.hunks`. |
 | `craftar forge diff <type/name> [--against <profile>] [--forge <dir> \| --workspace <dir>] [--json]` | Shows the differences between a base ingredient and each of its variants: a header carrying the same distance `forge variants` reports, then hunk by hunk, each with a suggested class and reason — `evolution` (one side is newer text), `value` (an identifier-like token swapped in shared prose, with a suggested `param.<slug>`) or `block` (lines only one side has) — then the files that exist on only one side. A suggestion never decides anything. It compares the raw Forge text, section marker lines included, so a base with markers shows them as hunks against a variant that has none. Read-only. `--json` prints an array of `{ref, profile, distance, diff}`; each hunk carries `suggestion: {class, reason, tokens?}` next to its `kind`. |
 | `craftar forge unify <type/name> --profile <p> (--take base\|variant \| --plan <file> \| --save-plan <file>) [--forge <dir> \| --workspace <dir>] [--json]` | Resolves one variant back into its base, hunk by hunk. `--save-plan` writes a reviewable plan with every decision set to `keep`, each hunk annotated with its suggested class (which `--plan` ignores) and, for a `value` hunk, a pre-filled `params` list (`token` → suggested `key`); on a `block` hunk, a pre-filled `section: { name }` from the Markdown heading above (or `section-<n>`); and on a hunk touching a section the base already has, that section's name. It refuses a path that resolves inside the Forge (after `..` segments and symlinks) and a path that already exists, so it never overwrites a Forge file or a plan you already edited; it writes nothing else. A hunk set to `take: param` turns each listed token into `{{key}}` in the base, declares the base's text as the key's default in the base's `ingredient.yaml` and writes the variant's text into the variant profile's `profile.yaml` `params` — only after proving that both the base's and the variant's text render back exactly, and only when the same plan resolves the variant; it refuses (with the Forge untouched) a key another layer, profile or ingredient already uses, a variant another profile also uses, a whitespace-only difference, and a YAML file that would not round-trip unchanged. A hunk set to `take: section` (with `section: { name, lines? }`) wraps the base's lines in section markers as the default and writes the variant's lines into the variant profile's `sections` — consecutive hunks with one name form one section, `lines: "<from>-<to>"` widens it over equal base lines, and hunks inside a section the base already has only write the profile value; it is proved (both sides render back exactly) and needs the same plan to resolve the variant; `take: param` and `take: section` may share a plan, never a hunk. It refuses (Forge untouched) a `take: param` or `take: section` on a file no target emits, a variant that holds markers, a profile that already sets that section (another profile for a new section, or the variant's profile with other content), a span that cuts a hunk or crosses another section, a span that covers a hunk outside the run (including `take: base` on a hunk inside a section the plan fills), a hunk mixing lines inside and outside an existing section, and a span reaching a missing final newline; when it adds a section to a Forge still at `schema: 1` it sets `schema: 2` in `craftar.forge.yaml` in place (refused if the file does not round-trip). `--plan` applies an edited plan, refusing when it is not for this exact ingredient/profile or either side's fingerprint moved since it was saved. `--take base\|variant` resolves every decision to that side. Writes the merged base and, once every difference is resolved, removes the variant and rewrites every recipe reference to it (`ingredients`) to name the base. It never deletes a recipe and never edits an `extends`; it edits a profile only to write the values of a `take: param` or `take: section` extraction into the variant's own profile, and otherwise never: a `<recipe>--<profile>` left identical to `<recipe>` is reported as a warning, to be removed by hand after repointing the lists that name it — unify does not, because a workspace or an `extends` chain may also name `<recipe>` and the recipe order or param precedence would change. Unify cannot reach workspaces, so a removed variant is reported as a warning for any `craftar.yaml` that disables it in `overrides.ingredients.disable`. Every recipe rewrite is checked before the first write, so one that cannot land (a reference behind a YAML alias) is refused with the Forge untouched; a failure after writing began (an I/O error, a locked file) names the paths already touched and the `git checkout` / `git clean` commands that undo them. A merge never adds, removes or changes a section marker other than the sections the plan declares; a plan or `--take variant` that would is refused before the first write — take `base` for the marker lines, or `take: section` to fill the section; the citation checks of `take: param` also read the profiles' section values, which can cite `{{key}}`. `ingredient.yaml` is never merged: when the two sides' metadata differs (beyond `name`, `as` and `origin`), the variant stays unresolved and the differing fields are named — edit it by hand, or `--take base` to discard the variant, metadata included. Requires a clean git checkout in the Forge with at least one commit (`--save-plan` excepted) — the Forge has no lock, so git is the undo. It also refuses when any path it would overwrite or delete (the base, the variant, the recipe files it rewrites, the profile a parameter or section extraction edits, `craftar.forge.yaml` when it is bumped) is ignored, untracked, modified, or flagged skip-worktree or assume-unchanged in the index, since git could not restore it. `--json` prints `{base, profile, resolved, written, removed, unresolved, variantRemoved, recipes: {rewritten, identicalToSibling}, metaDiffers, params, profileEdited, sections, manifestEdited, warnings}` for `--take`/`--plan` (every key always present, `[]` when empty), or `{base, profile, plan, unresolved}` for `--save-plan`. |
 
-All commands take `--workspace <dir>` (default: current directory); the `forge` commands also take `--forge <dir>` as an alternative to it.
+All commands take `--workspace <dir>` (default: current directory); the `forge` commands, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it, and `targets` needs no Forge.
 
 ## Forge layout
 
@@ -184,6 +187,19 @@ Sections layer the same way, weakest → strongest: the body's default → the p
 
 ## Targets
 
+`craftar targets` prints this matrix from `src/core/capabilities.ts`; a test plans one ingredient of every type for each target and fails when a cell and its emitter disagree. **native** — written in the tool's own place for that type, as the Forge holds it; **converted** — written in another form (frontmatter or a banner added, references rewritten, another container format, or folded into a shared file); **unsupported** — not written: `sync` warns and names an ingredient aimed at that target.
+
+| type | `claude-code` | `kiro` | `agents-md` |
+|---|---|---|---|
+| `rule` | native | converted | converted |
+| `agent` | native | converted | unsupported |
+| `command` | native | converted | unsupported |
+| `skill` | native | converted | unsupported |
+| `mcp` | native | native | unsupported |
+| `script` | native | unsupported | unsupported |
+| `steering` | unsupported | native | unsupported |
+| `hook` | native | unsupported | unsupported |
+
 **claude-code** — emits `.claude/rules|agents|commands|skills|scripts|hooks` and `.mcp.json` verbatim from the Forge (frontmatter kept byte-for-byte). Each MCP server is written exactly as the Forge holds it, undeclared keys included, in its own key order. Existing files keep their line endings and BOM; new files are LF without a BOM. Steering is Kiro-only (its `targets` default to `[kiro]`); one aimed at `claude-code` explicitly (`targets: "*"` or a list naming it) is skipped with a warning.
 
 **kiro** — reproduces, then extends, the hand-written `sync-steering.ps1` script it replaces:
@@ -236,11 +252,23 @@ Copy a workspace with `.claude/` and `.kiro/` into `fixtures/` (keep `local-stac
 
 ## Roadmap (from the functional spec)
 
-Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans.
+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).
 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; remote Forge (git URL + ref); `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
 
 ## Upgrading
 
+### to 0.10.0
+
+- **`craftar diff` shows orphans.** A file the Forge no longer produces is printed as the removal of the whole file (`+++ <path> (forge: no longer produced — sync removes it)`), and a hand-edited one as a header and one line, since `sync` keeps it. Output changes only in a workspace that has an `orphan` or an `orphan-drift` — one whose only pending change was an orphan used to print `no differences`; elsewhere it is byte for byte 0.9.0's.
+- **`craftar diff --exit-code`** exits 1 when there are differences — exactly when `sync --check` would — and refuses a `[path]` that names no file craftar manages. Without the flag `diff` still exits 0.
+- **No byte change**: no emitter, `plan`, `status` or `sync` changed. No workspace sees `update`.
+
+### to 0.9.0
+
+- **Three new read-only commands**: `craftar recipes`, `craftar ingredients` and `craftar targets`. They write nothing — no generated file, no lock, no Forge file.
+- **No byte change**: no emitter changed, and `craftar ls` prints what it printed before. No workspace sees `update`.
+- Their `--json` output is a tooling contract, like `status --json`: removing or renaming a key, changing a value's type, or adding a capability state will be announced here.
+
 ### to 0.8.6
 
 - **A rule reference inside the text of a Markdown link is now resolved like any other**, in `AGENTS.md` and in the kiro files. Before, the text of a link that `AGENTS.md` or kiro rewrote was copied as the Forge held it, or blanket-rewritten to `.kiro/steering/`.

package/dist/cli.js

@@ -4,21 +4,23 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
-import { loadWorkspace, plan, readLock, status, apply, resolveForge } from "./core/sync.js";
-import { sectionKey } from "./core/resolve.js";
+import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
+import { resolve, sectionKey } from "./core/resolve.js";
+import { catalogueContext, listRecipes, listIngredients, checkType } from "./core/catalogue.js";
+import { listTargets } from "./core/capabilities.js";
 import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { hashNormalized, toLf, stripBom } from "./core/text.js";
-import { gitDirty, gitIsRepo, gitUnheld } from "./core/forge.js";
+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 { HUNK_CLASSES, UnifyPlanSchema } from "./schema/index.js";
+import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 process.stdout.on("error", (e) => { if (e.code === "EPIPE")
     process.exit(0); });
 const program = new Command();
-program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.8.6");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.10.1");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -118,28 +120,51 @@ program
 /* ---------------------------------------------------------------- diff */
 program
     .command("diff")
-    .description("Unified diff between the files on disk and what the Forge would generate")
+    .description("Unified diff between the files on disk and what the Forge would generate, orphans included (files the Forge no longer produces)")
     .option("--workspace <dir>", "workspace root", ".")
+    .option("--exit-code", "exit 1 when there are differences (exactly when `sync --check` would fail); a [path] that names no file craftar manages becomes an error", false)
     .argument("[path]", "limit to one file")
     .action(async (only, o) => {
     const ws = await loadWorkspace(o.workspace);
     const p = await plan(ws);
     const st = await status(ws, p, await readLock(ws.root));
+    // Spec 19 §3.3: under --exit-code a path nothing matches must not read as "clean" to a script
+    if (o.exitCode && only && !st.some((s) => s.path === only))
+        fail(`${only} is not a file craftar manages in this workspace — pass the workspace-relative path as \`craftar status\` prints it (forward slashes)`);
     let shown = 0;
+    const render = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
     for (const s of st) {
         if (only && s.path !== only)
             continue;
-        if (!["update", "drift", "collision", "new"].includes(s.state))
+        // Spec 19 §3.2: show the six states sync --check refuses (skip unchanged and adopt)
+        if (["unchanged", "adopt"].includes(s.state))
             continue;
         shown++;
+        if (s.state === "orphan-drift") {
+            // Header and one line, no body: sync keeps this file
+            console.log(pc.bold(`--- ${s.path} (disk, orphan-drift)`));
+            console.log(`  ${explainSkip(s)}`);
+            continue;
+        }
         const disk = await readText(path.join(ws.root, s.path));
-        const next = s.planned ? toLf(stripBom(s.planned.content.toString("utf8"))) : "";
-        console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
-        console.log(pc.bold(`+++ ${s.path} (forge)`));
-        console.log(renderDiff(disk ?? "", next, { paint: { same: pc.dim, del: pc.red, add: pc.green } }));
+        if (s.state === "orphan") {
+            // A removal: the file exists on disk but the Forge no longer produces it
+            console.log(pc.bold(`--- ${s.path} (disk, orphan)`));
+            console.log(pc.bold(`+++ ${s.path} (forge: no longer produced — sync removes it)`));
+            console.log(renderDiff(disk ?? "", "", render));
+        }
+        else {
+            const next = s.planned ? toLf(stripBom(s.planned.content.toString("utf8"))) : "";
+            console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
+            console.log(pc.bold(`+++ ${s.path} (forge)`));
+            console.log(renderDiff(disk ?? "", next, render));
+        }
     }
     if (!shown)
         console.log(pc.green("no differences"));
+    // exitCode, not process.exit: exit drops a piped diff still queued for a slow reader (spec 19 §3.1)
+    else if (o.exitCode)
+        process.exitCode = 1;
 });
 /* ---------------------------------------------------------------- explain */
 program
@@ -187,6 +212,389 @@ program
     }
     console.log(`\n${p.files.length} files across targets ${p.resolution.targets.join(", ")}`);
 });
+/* ---------------------------------------------------------------- recipes */
+program
+    .command("recipes")
+    .description("List every recipe of the Forge — slot, parents, the profiles that use it — marked against this workspace or a profile. Read-only")
+    .option("--forge <dir>", "Forge directory (instead of --workspace)")
+    .option("--profile <name>", "with --forge: mark what this profile resolves")
+    .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    if (o.profile && !o.forge)
+        fail("--profile goes with --forge — inside a workspace the profile comes from craftar.yaml");
+    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace });
+    const source = workspace
+        ? { kind: "workspace", config: workspace.config }
+        : o.profile
+            ? { kind: "profile", profile: o.profile }
+            : null;
+    let context = null;
+    if (source) {
+        try {
+            context = catalogueContext(forg, source);
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    const r = listRecipes(forg, context);
+    if (o.json) {
+        return console.log(JSON.stringify(r, null, 2));
+    }
+    // Text mode
+    const ctxDesc = source
+        ? source.kind === "workspace"
+            ? `workspace profile ${source.config.profile}`
+            : `profile ${source.profile}`
+        : null;
+    console.log(pc.bold(`craftar recipes — forge ${forg.manifest.name} @ ${forg.commit?.slice(0, 8) ?? "no git"}${ctxDesc ? ` · ${ctxDesc}` : ""}`));
+    const resolves = context !== null && context.resolution !== null;
+    // Compute column widths for alignment
+    // Column 1: name[ [slot s]]
+    // Column 2: <N ingredient(s)>
+    // Column 3: ← parents (empty when none)
+    // Column 4: reason (empty when none)
+    const col1 = r.recipes.map((rec) => `${rec.name}${rec.slot ? ` [slot ${rec.slot}]` : ""}`);
+    const col2 = r.recipes.map((rec) => `${rec.ingredients.length} ingredient${rec.ingredients.length === 1 ? "" : "s"}`);
+    const col3 = r.recipes.map((rec) => rec.extends.length ? `← ${rec.extends.join(", ")}` : "");
+    const col4 = r.recipes.map((rec) => {
+        let reason = "";
+        if (rec.inUse) {
+            const byParts = [];
+            for (const b of rec.inUse.by) {
+                if (b === "extends")
+                    byParts.push(`extends ${rec.inUse.extendedBy.join(", ")}`);
+                else
+                    byParts.push(b);
+            }
+            reason = `in use (${byParts.join(", ")})`;
+        }
+        const removed = rec.removedByWorkspace ? (reason ? " · " : "") + "removed by this workspace" : "";
+        return reason + removed;
+    });
+    const w1 = Math.max(...col1.map((s) => s.length));
+    const w2 = Math.max(...col2.map((s) => s.length));
+    const w3 = Math.max(...col3.map((s) => s.length));
+    const w4 = Math.max(...col4.map((s) => s.length));
+    for (let i = 0; i < r.recipes.length; i++) {
+        const rec = r.recipes[i];
+        const desc = rec.description ? `— ${rec.description}` : "";
+        let line;
+        if (resolves) {
+            const mark = rec.inUse ? pc.green("●") : pc.dim("○");
+            line = [
+                `  ${mark} `,
+                col1[i].padEnd(w1),
+                "  ",
+                col2[i].padEnd(w2),
+                col3[i] ? "  " + col3[i].padEnd(w3) : (w3 > 0 ? "  " + "".padEnd(w3) : ""),
+                col4[i] ? "  " + col4[i].padEnd(w4) : (w4 > 0 ? "  " + "".padEnd(w4) : ""),
+                desc ? "  " + desc : "",
+            ].join("").trimEnd();
+        }
+        else {
+            // No context: no mark column, rows start with two spaces then the name
+            line = [
+                "  ",
+                col1[i].padEnd(w1),
+                "  ",
+                col2[i].padEnd(w2),
+                col3[i] ? "  " + col3[i].padEnd(w3) : (w3 > 0 ? "  " + "".padEnd(w3) : ""),
+                desc ? "  " + desc : "",
+            ].join("").trimEnd();
+        }
+        console.log(line);
+    }
+    // Count line
+    const inUseCount = r.recipes.filter((x) => x.inUse).length;
+    const profilesPart = r.recipes.length > 0
+        ? ` · used by profiles: ${r.recipes.map((x) => `${x.name} (${x.profiles.length ? x.profiles.join(", ") : "—"})`).join(", ")}`
+        : "";
+    const countLine = resolves
+        ? `${r.recipes.length} recipe${r.recipes.length === 1 ? "" : "s"}, ${inUseCount} in use${profilesPart}`
+        : `${r.recipes.length} recipe${r.recipes.length === 1 ? "" : "s"}${profilesPart}`;
+    console.log(`\n  ${countLine}`);
+    for (const w of r.warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+});
+/* ---------------------------------------------------------------- ingredients */
+program
+    .command("ingredients")
+    .description("List every ingredient of the Forge — its recipes and targets, references to missing ones — or what one recipe brings with its parents. Read-only")
+    .option("--recipe <name>", "only what this recipe brings, with the parents it extends, parents first")
+    .option("--type <type>", "only this ingredient type")
+    .option("--forge <dir>", "Forge directory (instead of --workspace)")
+    .option("--profile <name>", "with --forge: mark what this profile resolves")
+    .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    if (o.profile && !o.forge)
+        fail("--profile goes with --forge — inside a workspace the profile comes from craftar.yaml");
+    if (o.type) {
+        try {
+            checkType(o.type);
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace });
+    const source = workspace
+        ? { kind: "workspace", config: workspace.config }
+        : o.profile
+            ? { kind: "profile", profile: o.profile }
+            : null;
+    let context = null;
+    if (source) {
+        try {
+            context = catalogueContext(forg, source);
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    let result;
+    try {
+        result = listIngredients(forg, context, { recipe: o.recipe, type: o.type });
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    if (o.json) {
+        return console.log(JSON.stringify(result, null, 2));
+    }
+    // Text mode
+    const ctxDesc = source
+        ? source.kind === "workspace"
+            ? `workspace profile ${source.config.profile}`
+            : `profile ${source.profile}`
+        : null;
+    const recipeOpt = o.recipe ? ` --recipe ${o.recipe}` : "";
+    const typeOpt = o.type ? ` --type ${o.type}` : "";
+    console.log(pc.bold(`craftar ingredients${recipeOpt}${typeOpt} — forge ${forg.manifest.name} @ ${forg.commit?.slice(0, 8) ?? "no git"}${ctxDesc ? ` · ${ctxDesc}` : ""}`));
+    const resolves = context !== null && context.resolution !== null;
+    if (result.recipe) {
+        // --recipe mode: grouped by chain entry
+        // Compute column widths for alignment across the whole listing
+        // Column 1: ref[ → outputName]
+        const col1Recipe = [];
+        for (const entry of result.recipe.chain) {
+            for (const ref of entry.ingredients) {
+                const ing = result.ingredients.find((i) => i.ref === ref);
+                if (ing) {
+                    col1Recipe.push(ing.outputName !== ing.name ? `${ref} → ${ing.outputName}` : ref);
+                }
+                else {
+                    col1Recipe.push(ref);
+                }
+            }
+        }
+        const w1Recipe = Math.max(...col1Recipe.map((s) => s.length), 0);
+        for (const entry of result.recipe.chain) {
+            const rec = forg.recipes.get(entry.recipe);
+            const ext = rec?.extends.length ? `  ← ${rec.extends.join(", ")}` : "";
+            const slot = rec?.slot ? `  [slot ${rec.slot}]` : "";
+            console.log(`${entry.recipe}${ext}${slot}`);
+            for (const ref of entry.ingredients) {
+                const ing = result.ingredients.find((i) => i.ref === ref);
+                const miss = result.missing.find((m) => m.ref === ref);
+                if (ing) {
+                    const col1 = ing.outputName !== ing.name ? `${ref} → ${ing.outputName}` : ref;
+                    const disabled = ing.disabled ? "(disabled by this workspace)" : "";
+                    let line;
+                    if (resolves) {
+                        const mark = ing.disabled ? pc.dim("◌") : ing.inUse ? pc.green("●") : pc.dim("○");
+                        line = `  ${mark} ${col1.padEnd(w1Recipe)}${disabled ? "  " + disabled : ""}`.trimEnd();
+                    }
+                    else {
+                        line = `  ${col1.padEnd(w1Recipe)}`.trimEnd();
+                    }
+                    console.log(line);
+                }
+                else if (miss) {
+                    const line = `  ${pc.red("✗")} ${ref.padEnd(w1Recipe)}  not in this Forge`.trimEnd();
+                    console.log(line);
+                }
+            }
+        }
+        // Count line for --recipe
+        const countLine = `${result.recipe.chain.length} recipe${result.recipe.chain.length === 1 ? "" : "s"}, ${result.ingredients.length} ingredient${result.ingredients.length === 1 ? "" : "s"}${result.missing.length ? ` · ${result.missing.length} missing reference${result.missing.length === 1 ? "" : "s"}` : ""}`;
+        console.log(`\n  ${countLine}`);
+    }
+    else {
+        // No --recipe: grouped by type
+        // Spec 16 §4.3: rows print the bare `name`, not the `ref`, under their type heading
+        // Compute column widths across the whole listing (all types + missing)
+        // Column 1: name[ → outputName] (or ref for missing)
+        // Column 2: targets <...>
+        // Column 3: in <...>
+        const allCol1 = [];
+        const allCol2 = [];
+        const allCol3 = [];
+        for (const ing of result.ingredients) {
+            const col1 = ing.outputName !== ing.name ? `${ing.name} → ${ing.outputName}` : ing.name;
+            allCol1.push(col1);
+            allCol2.push(`targets ${ing.targets === "*" ? "*" : ing.targets.join(", ")}`);
+            allCol3.push(`in ${ing.recipes.length ? ing.recipes.join(", ") : "no recipe"}`);
+        }
+        for (const m of result.missing) {
+            allCol1.push(m.ref);
+        }
+        const w1 = Math.max(...allCol1.map((s) => s.length), 0);
+        const w2 = Math.max(...allCol2.map((s) => s.length), 0);
+        const w3 = Math.max(...allCol3.map((s) => s.length), 0);
+        const byType = new Map();
+        for (const ing of result.ingredients) {
+            if (!byType.has(ing.type))
+                byType.set(ing.type, []);
+            byType.get(ing.type).push(ing);
+        }
+        for (const type of INGREDIENT_TYPES) {
+            const ings = byType.get(type);
+            if (!ings?.length)
+                continue;
+            console.log(type);
+            for (const ing of ings) {
+                const col1 = ing.outputName !== ing.name ? `${ing.name} → ${ing.outputName}` : ing.name;
+                const col2 = `targets ${ing.targets === "*" ? "*" : ing.targets.join(", ")}`;
+                const col3 = `in ${ing.recipes.length ? ing.recipes.join(", ") : "no recipe"}`;
+                const desc = ing.description ? `— ${ing.description}` : "";
+                const disabled = ing.disabled ? "(disabled by this workspace)" : "";
+                let line;
+                if (resolves) {
+                    const mark = ing.disabled ? pc.dim("◌") : ing.inUse ? pc.green("●") : pc.dim("○");
+                    line = [
+                        `  ${mark} `,
+                        col1.padEnd(w1),
+                        "  ",
+                        col2.padEnd(w2),
+                        "  ",
+                        col3.padEnd(w3),
+                        desc ? "  " + desc : "",
+                        disabled ? "  " + disabled : "",
+                    ].join("").trimEnd();
+                }
+                else {
+                    // No context: no mark column, rows start with two spaces then the name
+                    line = [
+                        "  ",
+                        col1.padEnd(w1),
+                        "  ",
+                        col2.padEnd(w2),
+                        "  ",
+                        col3.padEnd(w3),
+                        desc ? "  " + desc : "",
+                    ].join("").trimEnd();
+                }
+                console.log(line);
+            }
+        }
+        if (result.missing.length) {
+            console.log("missing");
+            for (const m of result.missing) {
+                const line = `  ${m.ref.padEnd(w1)}  cited by ${m.recipes.join(", ")}, not in this Forge`.trimEnd();
+                console.log(line);
+            }
+        }
+        // Count line
+        const inUseCount = result.ingredients.filter((x) => x.inUse).length;
+        const disabledCount = result.ingredients.filter((x) => x.disabled).length;
+        const noRecipeCount = result.ingredients.filter((x) => x.recipes.length === 0).length;
+        const countParts = [`${result.ingredients.length} ingredient${result.ingredients.length === 1 ? "" : "s"}`];
+        if (resolves) {
+            countParts.push(`${inUseCount} in use`);
+            countParts.push(`${disabledCount} disabled`);
+        }
+        countParts.push(`${noRecipeCount} in no recipe`);
+        const missingPart = result.missing.length ? ` · ${result.missing.length} missing reference${result.missing.length === 1 ? "" : "s"}` : "";
+        console.log(`\n  ${countParts.join(", ")}${missingPart}`);
+    }
+    for (const w of result.warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+});
+/* ---------------------------------------------------------------- targets */
+program
+    .command("targets")
+    .description("Print the capability matrix: what each target does with each ingredient type (native, converted, unsupported), marking the targets this workspace uses. Read-only")
+    .option("--workspace <dir>", "workspace whose targets to mark (default: . when it holds a craftar.yaml)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    let inUse = null;
+    const warnings = [];
+    const root = o.workspace ?? ".";
+    if (!(await exists(path.join(root, WORKSPACE_FILE)))) {
+        // craftar.yaml does not exist
+        if (o.workspace !== undefined) {
+            // Explicit --workspace: exit 1 with loadWorkspace's message
+            try {
+                await loadWorkspace(root);
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e));
+            }
+        }
+        // No --workspace: just show unmarked, no warning
+    }
+    else {
+        // craftar.yaml exists, try to load
+        try {
+            const ws = await loadWorkspace(root);
+            inUse = resolve(ws.forge, ws.config).targets;
+        }
+        catch (e) {
+            // Load or resolve failed — warning, not error
+            warnings.push(`targets in use not shown: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const result = listTargets(inUse);
+    if (o.json) {
+        return console.log(JSON.stringify({ ...result, warnings }, null, 2));
+    }
+    // Text mode
+    const targetLine = result.targets
+        .map((t) => (t.inUse === true ? `${t.name} (in use)` : t.name))
+        .join(" · ");
+    console.log(pc.bold(`craftar targets — ${targetLine}`));
+    console.log();
+    // Matrix table
+    const colWidth = 14;
+    const typeColWidth = 10;
+    const header = "  " + " ".repeat(typeColWidth) + result.targets.map((t) => t.name.padEnd(colWidth)).join("");
+    console.log(header.trimEnd());
+    for (const type of result.ingredientTypes) {
+        const row = "  " + type.padEnd(typeColWidth) + result.targets.map((t) => {
+            const cap = t.capabilities[type];
+            return cap.state.padEnd(colWidth);
+        }).join("");
+        console.log(row.trimEnd());
+    }
+    console.log();
+    // Legend
+    console.log("  native       written in the tool's own place for that type, as the Forge holds it");
+    console.log("  converted    written in another form — see its line below");
+    console.log("  unsupported  not written; sync warns and names an ingredient aimed at this target");
+    console.log();
+    // Paths block — type-major (types outer, targets inner); align labels to widest
+    console.log("paths");
+    const pathLines = [];
+    for (const type of INGREDIENT_TYPES) {
+        for (const t of result.targets) {
+            const cap = t.capabilities[type];
+            if (cap.output.length > 0) {
+                const pathStr = cap.output.join(", ");
+                const note = cap.note ? ` — ${cap.note}` : "";
+                pathLines.push({ label: `${t.name} · ${type}`, content: `${pathStr}${note}` });
+            }
+        }
+    }
+    const maxLabelLen = Math.max(...pathLines.map((l) => l.label.length));
+    for (const line of pathLines) {
+        console.log(`  ${line.label.padEnd(maxLabelLen)}  ${line.content}`);
+    }
+    for (const w of warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+});
 /* ---------------------------------------------------------------- forge */
 const forge = program.command("forge").description("Operate on the Forge itself rather than on a workspace");
 forge