craftar 0.11.0 → 0.13.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*). 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*). 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
 
@@ -54,18 +54,22 @@ 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` | 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). |
+| `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`. |
 | `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`. With a remote Forge, `--exit-code` also exits 1 when the fetch fails, as `sync --check` does; plain `diff` reads the cached copy with a warning. |
 | `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 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}`. |
 | `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 add recipe <name...> [--replace] [--workspace <dir>] [--offline]` | Adds recipes to the workspace's choice: deletes each from `craftar.yaml`'s `recipes.remove` when it is there, and appends it to `recipes.add` when the workspace does not resolve it yet. A recipe that would share a `slot` with another resolved one is refused, naming the holder; `--replace` removes every other holder in the same edit, as `remove recipe` would. Names apply in order, all or nothing, and the edit is written only once the workspace resolves and plans with it. Writes `craftar.yaml` only — in place, keeping its comments and style (a document the YAML writer does not reproduce byte for byte, such as `{ add: [] }` with inner spaces or a column-aligned comment, is refused: reformat it by hand) — and never syncs: it prints the net edit, the new recipe order and what the next `sync` would do (`next sync: 1 new, 1 orphan — run \`craftar sync\``), or `nothing to change`. Refused when `craftar.local.yaml` sets `recipes` (its lists would replace the edited ones). |
+| `craftar remove recipe <name...> [--workspace <dir>] [--offline]` | Removes recipes from the workspace's choice: deletes each from `recipes.add`, and appends a profile recipe to `recipes.remove`. A recipe another one still brings in through `extends` is refused, naming the top-level recipe to remove instead. A name the Forge does not hold is accepted only to clean it out of `recipes.add` or `recipes.remove`. Same output, refusals and all-or-nothing rule as `add recipe`. |
 | `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, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it — a directory: a URL there is refused — and `targets` needs no Forge. With a remote Forge (see *Remote Forge*), `status`, `sync`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `forge variants` and `forge diff` fetch first and take `--offline` to use the cached copy; `targets` never fetches; `forge unify` refuses a workspace whose Forge is remote — clone it and pass `--forge <dir>`; `import --write-config` keeps a remote `forge:` and sets only `profile` and `targets`.
+All commands but `workspaces` take `--workspace <dir>` (default: current directory); the `forge` commands, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it — a directory: a URL there is refused — and `targets` needs no Forge. With a remote Forge (see *Remote Forge*), `status`, `sync`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `add recipe`, `remove recipe`, `forge variants` and `forge diff` fetch first and take `--offline` to use the cached copy; `targets` never fetches; `forge unify` refuses a workspace whose Forge is remote — clone it and pass `--forge <dir>`; `import --write-config` keeps a remote `forge:` and sets only `profile` and `targets`.
 
 ## Forge layout
 
@@ -171,15 +175,15 @@ params: { angularVersion: { default: "20" } }
 Workspace `craftar.yaml`:
 
 ```yaml
-forge: ../forge                      # a path, or a git URL (see Remote Forge)
-ref: v1.4.0                          # optional, with a git URL: a branch, a tag or a full SHA
+forge: ../forge # a path, or a git URL (see Remote Forge)
+ref: v1.4.0 # optional, with a git URL: a branch, a tag or a full SHA
 profile: acme-portal
-targets: [claude-code, kiro]         # optional, overrides the profile
-recipes: { add: [], remove: [] }
+targets: [claude-code, kiro] # optional, overrides the profile
+recipes: {add: [], remove: []} # edited by craftar add recipe / remove recipe
 overrides:
-  params: { }
-  sections: { }                      # same shape as the profile's sections
-  ingredients: { disable: [] }
+  params: {}
+  sections: {} # same shape as the profile's sections
+  ingredients: {disable: []}
 ```
 
 Layer precedence, weakest → strongest: the ingredient's declared defaults (scoped to that ingredient) → recipe defaults → profile → `craftar.yaml` → `craftar.local.yaml` (personal, git-ignored). Bodies may use `{{param}}` placeholders; a placeholder in a file no target emits is never rendered, and only body files count as a citation for `forge unify` and `import`; a placeholder with no value in any layer is left untouched and reported as a warning by `status` and `sync` (Angular's `{{ 'X' | localize }}` does not look like a placeholder and passes silently). Between layers, objects merge key by key while arrays and scalars from the stronger layer replace the weaker one — `targets: [kiro]` in `craftar.local.yaml` means exactly `[kiro]`. Omit a key in `craftar.local.yaml` to inherit it — an empty list there means empty.
@@ -255,19 +259,39 @@ Copy a workspace with `.claude/` and `.kiro/` into `fixtures/` (keep `local-stac
 
 `forge:` may be a git URL — `https://…`, `ssh://…`, `file://…`, or the SCP-like `git@host:org/forge.git` (any SSH user) — with an optional `ref`: a branch (followed: its tip at each fetch), a tag or a full 40-hex SHA (fixed); `refs/heads/<x>` / `refs/tags/<x>` when a name is both; no `ref` follows the remote's default branch. Abbreviated SHAs are refused. A `ref` next to a path `forge:` is ignored, with a warning.
 
-- **The cache.** Each machine keeps one copy per URL in `$CRAFTAR_HOME/forges/` (`~/.craftar` by default): a bare repository and one tree per resolved commit, never written by Craftar, shared by every workspace on the machine. Each tree holds the commit's bytes on every platform: the host's `core.autocrlf`, `core.eol` and global attributes file do not apply to it; the Forge's own `.gitattributes` does. Trees unused for 14 days are removed after a fetch. It is the one place Craftar writes outside a workspace and a Forge on its own.
-- **The network.** `sync` (with `--check` and `--dry-run`) and `diff --exit-code` fetch first and exit 1 when they cannot; `status`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `forge variants` and `forge diff` fall back to the cached copy with a warning; `--offline` uses the cached copy on purpose; with no cached copy every one of them exits 1. `targets` never fetches: it reads the cached copy, and without one prints the matrix unmarked, with a warning. A full SHA already cached is not fetched again.
+- **The cache.** Each machine keeps one copy per URL in `$CRAFTAR_HOME/forges/` (`~/.craftar` by default): a bare repository and one tree per resolved commit, never written by Craftar, shared by every workspace on the machine. Each tree holds the commit's bytes on every platform: the host's `core.autocrlf`, `core.eol` and global attributes file do not apply to it; the Forge's own `.gitattributes` does. Trees unused for 14 days are removed after a fetch. The cache and the workspace registry (below) are the two places, both under `$CRAFTAR_HOME`, where Craftar writes outside a workspace and a Forge on its own.
+- **The network.** `sync` (with `--check` and `--dry-run`) and `diff --exit-code` fetch first and exit 1 when they cannot; `status`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `add recipe`, `remove recipe`, `forge variants` and `forge diff` fall back to the cached copy with a warning; `--offline` uses the cached copy on purpose; with no cached copy every one of them exits 1. `targets` never fetches: it reads the cached copy, and without one prints the matrix unmarked, with a warning. A full SHA already cached is not fetched again.
 - **Authentication belongs to git** (credential helper, SSH agent). A URL holding credentials (`https://user:token@…`, a password in any scheme) is refused in `craftar.yaml` and `craftar.local.yaml`, naming the file and never the value. In CI, configure git (e.g. a credential helper or an SSH deploy key), never a token in `forge:`; without a terminal, git does not prompt.
 - **Writing into the Forge** stays local: `import` and `forge unify` need a clone passed as `--forge <dir>`; Craftar never pushes. After importing into the clone, push it for `sync` to see the import.
 - **`craftar.local.yaml`** may override `forge:` (a local clone while you work on the Forge); every planning command then warns not to commit `craftar.lock` or the generated files.
 
+## Workspace registry
+
+A writing `sync` records the workspace in `$CRAFTAR_HOME/registry.json` (`~/.craftar` by default): its real path, profile, the Forge it used and where that Forge lives, the resolved recipes and targets, and when `sync` last ran there. It is an index, not the memory — `craftar.lock` stays that, and nothing in a workspace changes because of it. `craftar workspaces` prints it as a table with every status computed on the spot — `up to date`, `outdated`, `drift`, `no lock`, `missing` or `error` — read without the network (a remote Forge from the cache; `--fetch` fetches first); `forget` and `prune` remove entries, and a workspace that is gone stays listed as `missing` until you prune it.
+
+- **`CRAFTAR_NO_REGISTRY`** — read the name as "no registry", the way `NO_COLOR` means "no colour". Set to any non-empty value, it turns the registry off: `sync` neither reads nor writes it, and `craftar workspaces` exits 1. An empty value counts as unset. Set it on CI runners and throwaway checkouts, whose directories would only pile up as `missing`.
+- **A registry that cannot be written** (an unwritable `$CRAFTAR_HOME`, a busy lock after 60 s, a file this craftar cannot read) leaves `sync`'s files, lock and exit code as they would be, and adds one warning. Craftar never overwrites a registry it cannot read: repair or remove it yourself.
+- The registry is per machine: paths are native and absolute, and SSH and HTTPS spellings of one remote are two Forges in it, as they are two cache entries.
+
 ## 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).
+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.
 
 ## Upgrading
 
+### 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.
+- **A `recipes.add` name the Forge does not hold** now fails every resolving command with `recipe "<x>" not found (referenced by craftar.yaml recipes.add)` instead of `… (referenced by profile <name>)`, and `recipes` / `ingredients` show that text in their warnings (`--json` included). 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.12.0
+
+- **A writing `sync` now writes outside the workspace**: `$CRAFTAR_HOME/registry.json` (`~/.craftar` by default) gains or updates the workspace's entry. On CI runners and throwaway checkouts set `CRAFTAR_NO_REGISTRY=1`. A registry that cannot be written is a warning; the exit code of `sync` does not change.
+- **New command `craftar workspaces`** (with `forget` and `prune`). Its `--json` output is a tooling contract, like `status --json`.
+- **No byte change**: no emitter, `plan`, `status` or lock changed. No workspace sees `update`.
+
 ### to 0.11.0
 
 - **`craftar.lock` is schema 2**, written by the next `sync` of every workspace, path Forge or remote: it adds `forge.ref`, `recipes` and `targets`. **Once a schema 2 lock is committed, every craftar up to 0.10.1 stops on it** (a zod error on `schema`) until upgraded — upgrade the whole team, and CI, before committing it. This craftar reads schema 1 and 2, and refuses a later one by name.

package/dist/cli.js

@@ -5,7 +5,9 @@ import { promises as fs } from "node:fs";
 import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
 import { classifyForge } from "./core/remote.js";
-import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
+import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.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";
 import { catalogueContext, listRecipes, listIngredients, checkType } from "./core/catalogue.js";
 import { listTargets } from "./core/capabilities.js";
@@ -17,6 +19,8 @@ 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 { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
+import { parseWorkspaceYaml } 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); });
@@ -27,7 +31,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.11.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.13.0");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -99,7 +103,7 @@ program
 /* ---------------------------------------------------------------- sync */
 program
     .command("sync")
-    .description("Generate the harness for every target from the Forge and update craftar.lock")
+    .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)
@@ -121,6 +125,17 @@ program
         return;
     }
     const r = await apply(ws, p, st, { dryRun: o.dryRun, overwriteDrift: o.overwriteDrift });
+    // 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()) {
+        const home = craftarHome();
+        try {
+            await register(home, ws, p);
+        }
+        catch (e) {
+            registryWarning = `registry not updated (${registryFile(home)}): ${e instanceof Error ? e.message : String(e)}`;
+        }
+    }
     const verb = o.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);
@@ -135,6 +150,8 @@ program
         console.log(`  ${pc.yellow("!")} ${s.path}  ${explainSkip(s)}`);
     for (const w of p.warnings)
         console.log(`  ${pc.yellow("warn")} ${w}`);
+    if (registryWarning)
+        console.log(`  ${pc.yellow("warn")} ${registryWarning}`);
 });
 /* ---------------------------------------------------------------- diff */
 program
@@ -187,6 +204,62 @@ program
     else if (o.exitCode)
         process.exitCode = 1;
 });
+/* ---------------------------------------------------------------- add / remove recipe */
+/** 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);
+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`);
+        }
+        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(", ")}` : ""}`);
+            return;
+        }
+        const file = path.join(ws.root, WORKSPACE_FILE);
+        const content = editRecipesText(await fs.readFile(file, "utf8"), edit.recipes, `${op} recipe`);
+        // The report is computed before the write, so a plan that fails leaves craftar.yaml untouched (§5.2 step 4).
+        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}`);
+        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"}`);
+        // plan() already carries ws.warnings first, and they were printed on load.
+        warnStderr(p.warnings.slice(ws.warnings.length));
+    };
+}
+program
+    .command("add")
+    .description("Add to the workspace's choices in craftar.yaml")
+    .command("recipe")
+    .description("Add recipes to craftar.yaml's recipes.add (or cancel their recipes.remove entry), after proving the workspace still resolves; writes nothing else and does not sync — it says what the next sync would do")
+    .argument("<name...>", "the recipes to add, applied in order, all or nothing")
+    .option("--replace", "swap out every other recipe that holds the same slot", false)
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .action(recipeCommand("add"));
+program
+    .command("remove")
+    .description("Remove from the workspace's choices in craftar.yaml")
+    .command("recipe")
+    .description("Remove recipes through craftar.yaml's recipes.remove (or cancel their recipes.add entry); refuses one another recipe brings in through extends; writes nothing else and does not sync")
+    .argument("<name...>", "the recipes to remove, applied in order, all or nothing")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .action(recipeCommand("remove"));
 /* ---------------------------------------------------------------- explain */
 program
     .command("explain")
@@ -240,6 +313,38 @@ program
     }
     console.log(`\n${p.files.length} files across targets ${p.resolution.targets.join(", ")}`);
 });
+/* ---------------------------------------------------------------- workspaces */
+const workspaces = program
+    .command("workspaces")
+    .description("List every workspace a writing sync registered on this machine ($CRAFTAR_HOME/registry.json), with its status computed now: up to date, outdated, drift, no lock, missing or error — read without the network")
+    .option("--fetch", "fetch each remote Forge first instead of reading the cached copy", false)
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    registryGate();
+    const t = await listWorkspaces(craftarHome(), { fetch: o.fetch });
+    if (o.json)
+        return console.log(JSON.stringify({ registry: t.registry, fetch: o.fetch, workspaces: t.rows, warnings: t.warnings }, null, 2));
+    printWorkspaces(t.rows, t.warnings, o.fetch);
+});
+workspaces
+    .command("forget")
+    .description("Remove a workspace from the registry; the directory itself is not touched")
+    .argument("<dir>", "the workspace's directory, as registered")
+    .action(async (dir) => {
+    registryGate();
+    console.log(`forgot ${await forget(craftarHome(), dir)}`);
+});
+workspaces
+    .command("prune")
+    .description("Remove every registered workspace whose directory or craftar.yaml is gone")
+    .action(async () => {
+    registryGate();
+    const gone = await prune(craftarHome());
+    if (gone.length === 0)
+        console.log("nothing to prune");
+    for (const p of gone)
+        console.log(`pruned ${p}`);
+});
 /* ---------------------------------------------------------------- recipes */
 program
     .command("recipes")
@@ -997,6 +1102,53 @@ async function forgeFor(o) {
     warnStderr(workspace?.warnings ?? []);
     return forge;
 }
+/** `$CRAFTAR_HOME`, as the cache reads it (spec 13 §6.3). */
+function craftarHome() {
+    return resolveHome(process.env.CRAFTAR_HOME || undefined);
+}
+/** `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);
+}
+function registryGate() {
+    if (registryOff())
+        fail("the workspace registry is off (CRAFTAR_NO_REGISTRY is set)");
+}
+const ROW_WORDS = {
+    "up-to-date": "up to date",
+    outdated: "outdated",
+    drift: "drift",
+    "no-lock": "no lock",
+    missing: "missing",
+    error: "error",
+};
+/** The text table of `craftar workspaces` (spec 21 §4.2) — presentation, not contract. */
+function printWorkspaces(rows, warnings, fetched) {
+    if (rows.length === 0) {
+        console.log(pc.bold("craftar workspaces — no workspace registered (craftar sync registers one)"));
+        return;
+    }
+    const offline = !fetched && rows.some((r) => r.forge.kind === "remote") ? " (status read offline from the Forge cache)" : "";
+    console.log(pc.bold(`craftar workspaces — ${rows.length} registered${offline}`));
+    const width = Math.max(...rows.map((r) => r.name.length));
+    for (const r of rows) {
+        console.log(`  ${pc.cyan(r.name.padEnd(width))}  ${r.path}`);
+        const stack = Object.entries(r.stack).map(([slot, recipe]) => `${slot}=${recipe}`);
+        console.log(`      ${[`profile ${r.profile}`, ...(stack.length ? [stack.join(", ")] : []), ...(r.targets.length ? [r.targets.join(", ")] : [])].join(" · ")}`);
+        const synced = `synced ${r.lastSync.slice(0, 16).replace("T", " ")} UTC`;
+        const word = ROW_WORDS[r.status] + (r.forgeMoved ? ", forge moved" : "");
+        const painted = r.status === "drift" || r.status === "error" || r.status === "missing" ? pc.red(word) : r.status === "up-to-date" ? pc.dim(word) : pc.yellow(word);
+        if (r.status === "missing" || r.status === "error") {
+            console.log(`      ${synced} · ${painted}`);
+            continue;
+        }
+        const f = r.forge;
+        const at = f.kind === "remote" ? `${f.ref ?? `${f.defaultBranch} (default branch)`} ${f.commit?.slice(0, 8) ?? "no git"}` : (f.commit?.slice(0, 8) ?? "no git");
+        console.log(`      forge ${f.source}${f.fromLocalFile ? " (local override)" : ""} @ ${at} · ${synced} · ${painted}`);
+    }
+    for (const w of warnings)
+        console.log(`  ${pc.yellow("warn")} ${w}`);
+}
 /** Warnings of loading the workspace, for commands whose stdout is not a report (a diff, `explain`, `ls`, `--json`). */
 function warnStderr(warnings) {
     for (const w of warnings)