craftar 0.34.2 → 0.36.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 1 in progress** — phase 0, the foundations, is done. `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) and `forge promote` (a profile's variant becomes the base) 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` or above (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). `craftar forge impact` lists the workspaces registered on this machine that read a Forge (by path, by a git remote of the clone, or through another clone of the same remote) with what their next sync would do against it, and `forge unify` plans them before and after its writes, names the ones its warnings concern, and with `--prune-recipes` deletes a recipe left identical to its sibling once every one of them plans the same. `craftar doctor` reports, one line per finding, what is off on this machine and in this workspace. `craftar cache prune` removes the cache entries and trees nothing uses. An MCP ingredient can declare `authEnv`, the environment variables its server needs (names only, never a value), and `craftar doctor` checks them; with `claude-code`, `sync` writes an example file listing them. A recipe can bring **local services**: a `service` ingredient is a Docker Compose fragment that `sync` writes under `.craftar/`, and `craftar services up | down | status` run Compose on what the lock records (see *Local services*). A profile's `integrations` block can select recipes and give params in a Forge that declares `schema: 3` or above (see *Integrations*), since `0.27.0`. `craftar templates list | install` shows and runs the profile's `templates` block — `install` runs `dotnet new install` per entry into the user's template store; nothing installs implicitly. An MCP `server` takes the params its ingredient declares, in a Forge that declares `schema: 4` (see *Server params*), since `0.28.0`. `craftar mcp` serves a workspace to an AI coder over the Model Context Protocol — seven reading tools with the data of `status`, `diff`, `explain`, `recipes`, `ingredients`, `targets` and `doctor`; it reads only. `craftar ui` serves a local, read-only dashboard of every registered workspace — the table of `craftar workspaces`, and for one workspace its file states, a file's diff and explanation, and its Forge's recipes and ingredients — on `127.0.0.1` only. `craftar init --clone` and `craftar repos clone` clone a profile's repositories (its `repos` list) into the workspace, and `craftar repos` lists them. `craftar init --new-profile` creates a profile in a Forge directory (one file, not committed) and starts the workspace on it.
+> Status: **phase 1 in progress** — phase 0, the foundations, is done. `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) and `forge promote` (a profile's variant becomes the base) 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` or above (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). `craftar forge impact` lists the workspaces registered on this machine that read a Forge (by path, by a git remote of the clone, or through another clone of the same remote) with what their next sync would do against it, and `forge unify` plans them before and after its writes, names the ones its warnings concern, and with `--prune-recipes` deletes a recipe left identical to its sibling once every one of them plans the same. `craftar doctor` reports, one line per finding, what is off on this machine and in this workspace. `craftar cache prune` removes the cache entries and trees nothing uses. An MCP ingredient can declare `authEnv`, the environment variables its server needs (names only, never a value), and `craftar doctor` checks them; with `claude-code`, `sync` writes an example file listing them. A recipe can bring **local services**: a `service` ingredient is a Docker Compose fragment that `sync` writes under `.craftar/`, and `craftar services up | down | status` run Compose on what the lock records (see *Local services*). A profile's `integrations` block can select recipes and give params in a Forge that declares `schema: 3` or above (see *Integrations*), since `0.27.0`. `craftar templates list | install` shows and runs the profile's `templates` block — `install` runs `dotnet new install` per entry into the user's template store; nothing installs implicitly. An MCP `server` takes the params its ingredient declares, in a Forge that declares `schema: 4` (see *Server params*), since `0.28.0`. `craftar mcp` serves a workspace to an AI coder over the Model Context Protocol — seven reading tools with the data of `status`, `diff`, `explain`, `recipes`, `ingredients`, `targets` and `doctor`; started with `--allow-writes`, it also serves `sync`, `add_recipe` and `remove_recipe`, which write only in a workspace where a person typed `craftar mcp allow-writes` and never discard a hand edit. `craftar ui` serves a local, read-only dashboard of every registered workspace — the table of `craftar workspaces`, and for one workspace its file states, a file's diff and explanation, and its Forge's recipes and ingredients — on `127.0.0.1` only. `craftar init --clone` and `craftar repos clone` clone a profile's repositories (its `repos` list) into the workspace, and `craftar repos` lists them. `craftar init --new-profile` creates a profile in a Forge directory (one file, not committed) and starts the workspace on it. With `agents-md.primary`, in a Forge that declares `schema: 5`, an always-on rule lives in `AGENTS.md` alone, and the files that cite it follow it (see *Targets*).
 
 ## The idea in one paragraph
 
@@ -90,10 +90,12 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar explain <path>` | Which ingredient, recipe chain, target and origin produced a file and, for an ingredient with sections, which layer filled each one: `sections    flavors (profile globex), extra (default)` (`default`, `profile <p>` or `workspace`). For an ingredient whose files cite parameters, each cited key with the layer that filled it for this ingredient: `params      org (profile globex), port (default), root (unset)` — `default` (the ingredient's own), `recipe <name>`, `profile <p>`, `workspace` (either workspace file) or `unset`. `AGENTS.md` gets neither 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, or its `sync` would refuse for a declared parameter with no value — the reason is one of the row's warnings: `sync refused: declared parameter(s) with no value: <keys>`), plus `forge moved` when the Forge's commit differs from the lock's. Read without the network: a remote Forge comes from the cache; `--fetch` fetches first. Each row's warnings print after the table, prefixed with its path. Times are UTC. Writes nothing. Exits 0 whenever the table prints. Takes no `--workspace`. `--json` is a contract: `{registry, fetch, workspaces, warnings}`. |
-| `craftar doctor [--workspace <dir>] [--fetch] [--strict] [--json]` | Checks this machine — Node ≥ 22, `git`, `$CRAFTAR_HOME`, the registry (entries whose workspace is gone), the Forge cache (its size, entries nothing names, a fetch that never completed) — and, when run inside one (the current directory, or `--workspace`), this workspace: the configuration and its Forge (cached, fetched or pinned), whether the workspace sits inside its Forge, the plan's warnings, declared parameters with no value, the `${NAME}` variables a written MCP server expects and this environment lacks — `mcp-env` reads `authEnv` next to `${NAME}` (names only, never values), `templates` when the profile declares a `templates` block (an empty `templates:` line declares none), `dotnet` when that block is accepted and declares a `dotnet-new` entry (the .NET SDK answering `dotnet --version` at the workspace root); neither goes above `warn` — `agents-md-size` when the plan writes `AGENTS.md` (`ok` within the budget or with the budget off, `warn` over the default budget, `error` over an explicit one — the cause is reported there, not by the plan's warnings), the lock, `status`, and registration; in a workspace with a service: `docker` — Docker and its Compose plugin, 2.20.0 or later — and `services-env` — the variables a fragment needs. One line per finding — `ok`, `warn` or `error` — each problem with the command that fixes it; each cause is reported once. A declared parameter with no value is an `error` when a file the plan writes cites it (`sync` refuses that workspace) and a `warn` when nothing cites it. It only reports: nothing is written to a workspace, a lock or the registry, and the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Read without the network; `--fetch` fetches a remote Forge first. Exits 1 on an `error`, or on a `warn` under `--strict`; an explicit `--workspace` without `craftar.yaml` exits 1, while the current directory without one runs the machine checks only. `--json` is a contract: `{version, workspace, fetch, strict, checks: [{id, scope, level, message, fix}], summary}`. In a schema 4 Forge `mcp-env` reads the server as rendered, so a `${NAME}` a param brings into `env` is checked. |
+| `craftar doctor [--workspace <dir>] [--fetch] [--strict] [--json]` | Checks this machine — Node ≥ 22, `git`, `$CRAFTAR_HOME`, the registry (entries whose workspace is gone), the Forge cache (its size, entries nothing names, a fetch that never completed) — and, when run inside one (the current directory, or `--workspace`), this workspace: the configuration and its Forge (cached, fetched or pinned), whether the workspace sits inside its Forge, the plan's warnings, declared parameters with no value, the `${NAME}` variables a written MCP server expects and this environment lacks — `mcp-env` reads `authEnv` next to `${NAME}` (names only, never values), `templates` when the profile declares a `templates` block (an empty `templates:` line declares none), `dotnet` when that block is accepted and declares a `dotnet-new` entry (the .NET SDK answering `dotnet --version` at the workspace root); neither goes above `warn` — `agents-md-size` when the plan writes `AGENTS.md` (`ok` within the budget or with the budget off, `warn` over the default budget, `error` over an explicit one — the cause is reported there, not by the plan's warnings), under `agents-md.primary` `agents-md-primary` (a `CLAUDE.md` that keeps Claude Code from reading `AGENTS.md`, at the root or above it; at most `warn`) and `kiro-resources` (a hand-written Kiro agent `resources` entry the plan does not write: `error`, or `warn` when the file is only on disk), the lock, `status`, and registration; in a workspace with a service: `docker` — Docker and its Compose plugin, 2.20.0 or later — and `services-env` — the variables a fragment needs. One line per finding — `ok`, `warn` or `error` — each problem with the command that fixes it; each cause is reported once. A declared parameter with no value is an `error` when a file the plan writes cites it (`sync` refuses that workspace) and a `warn` when nothing cites it. It only reports: nothing is written to a workspace, a lock or the registry, and the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Read without the network; `--fetch` fetches a remote Forge first. Exits 1 on an `error`, or on a `warn` under `--strict`; an explicit `--workspace` without `craftar.yaml` exits 1, while the current directory without one runs the machine checks only. `--json` is a contract: `{version, workspace, fetch, strict, checks: [{id, scope, level, message, fix}], summary}`. In a schema 4 Forge `mcp-env` reads the server as rendered, so a `${NAME}` a param brings into `env` is checked. |
 | `craftar templates list [--json] [--workspace <dir>] [--offline]` | What the profile's `templates` block declares: one line per package — kind, package, version or `latest`, source or `default feeds` — and one per entry this craftar cannot install. Runs no program and does not know what is installed. `--json` is a contract: `{profile, templates: [{entry, kind, package, version, source, installable}], warnings}`. Exits 1 when the block is refused, naming the position and the rule, never a value. |
 | `craftar templates install [--dry-run] [--force] [--interactive] [--workspace <dir>] [--offline]` | Runs `dotnet new install <pkg>[::<version>]... [--add-source <source>]` once per `dotnet-new` entry, in the profile's order, at the workspace root. `--dry-run` prints the exact lines, needs no `dotnet` and exits 0 over an accepted block, even with a skipped entry. A real run exits 1 when the .NET SDK is not available. Both exit 1 when the block is refused or a package ID exists as a file or folder at the workspace root. `--force` and `--interactive` are passed to `dotnet` as typed, never otherwise; `--interactive` also gives `dotnet` the terminal's input. An entry that fails does not stop the others; a real run exits 1 when any failed or was skipped. When an entry declares a `source` and the workspace root has no `NuGet.Config`, a warning line is printed before the runs. Writes nothing in the workspace, the lock or the registry; nothing else (`sync`, `init`, `doctor`) runs it. See *Project templates*. |
-| `craftar mcp [--workspace <dir>] [--fetch]` | An MCP server (Model Context Protocol, revision `2025-06-18`) over stdin and stdout, started by an AI coder as a subprocess — not typed in a terminal, where it refuses to start. It serves **one workspace**, the one it was started in, through seven tools that only read: `status`, `diff` (the pending files; with a `path`, that file's diff), `explain`, `recipes`, `ingredients`, `targets` and `doctor` (the checks about this workspace, plus Node and `git`; like the command, it asks `docker compose` for its version when the workspace has a service and `dotnet` for its version when the profile declares a template it can install) — each answers with the data its command prints, as one JSON object. Nothing is written to the workspace, the lock, `craftar.yaml`, the registry or the Forge; there is no `sync` tool. The Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Without `--fetch` no tool touches the network: a remote Forge is read from the cached copy, and the answer says so — for `doctor` in its `forge` check, for the others but `targets` in `warnings` unless `ref` is a full commit SHA, which cannot go stale (`targets` reads only which targets the configuration resolves, never fetches and carries no such line). The `forge`, `ref` and `profile` of `craftar.yaml` / `craftar.local.yaml` are fixed when the server starts: after one of them changes, every tool but `targets` answers with an error until it is put back or the server is restarted (`targets` answers the matrix unmarked, with a warning). A hand-edited `.mcp.json`, `.kiro/settings/mcp.json` or `.claude/settings.craftar.example.json` is never returned — a note stands in for its diff. A line that is not JSON, or longer than 1 MiB, is not answered — the server reads on. Exits 0 when stdin closes; exits 1, with one line on stderr, in a terminal, without a `craftar.yaml`, or when the configuration does not read. See *Craftar inside the AI coder*. |
+| `craftar mcp [--workspace <dir>] [--fetch] [--allow-writes]` | An MCP server (Model Context Protocol, revision `2025-06-18`) over stdin and stdout, started by an AI coder as a subprocess — not typed in a terminal, where it refuses to start. It serves **one workspace**, the one it was started in, through seven tools that only read: `status`, `diff` (the pending files; with a `path`, that file's diff), `explain`, `recipes`, `ingredients`, `targets` and `doctor` (the checks about this workspace, plus Node and `git`; like the command, it asks `docker compose` for its version when the workspace has a service and `dotnet` for its version when the profile declares a template it can install) — each answers with the data its command prints, as one JSON object. Without `--allow-writes` nothing is written to the workspace, the lock, `craftar.yaml`, the registry or the Forge. With `--allow-writes` it also serves three writing tools — `sync` (a `craftar sync` that skips and lists every `drift`, `orphan-drift` and `collision`; a remote Forge needs `--fetch`), `add_recipe` and `remove_recipe` (an `add recipe` / `remove recipe`, which do not sync) — and each call writes only when this machine's registry holds the consent `craftar mcp allow-writes` recorded for this workspace, for the `forge`, `ref` and `profile` the server started with; otherwise the call is an error and nothing is written. A writing result carries what the command prints, never a file's content or the registry's path. The Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Without `--fetch` no tool touches the network: a remote Forge is read from the cached copy, and the answer says so — for `doctor` in its `forge` check, for the others but `targets` in `warnings` unless `ref` is a full commit SHA, which cannot go stale (`targets` reads only which targets the configuration resolves, never fetches and carries no such line). The `forge`, `ref` and `profile` of `craftar.yaml` / `craftar.local.yaml` are fixed when the server starts: after one of them changes, every tool but `targets` answers with an error until it is put back or the server is restarted (`targets` answers the matrix unmarked, with a warning). A hand-edited `.mcp.json`, `.kiro/settings/mcp.json` or `.claude/settings.craftar.example.json` is never returned — a note stands in for its diff. A line that is not JSON, or longer than 1 MiB, is not answered — the server reads on. Exits 0 when stdin closes; exits 1, with one line on stderr, in a terminal, without a `craftar.yaml`, or when the configuration does not read. See *Craftar inside the AI coder*. |
+| `craftar mcp allow-writes [--workspace <dir>]` | Records, in this machine's registry, the consent that lets `craftar mcp --allow-writes` write in this workspace. It runs only in a terminal (stdin and stdout), prints the workspace, the Forge, the ref and the profile the consent is for, and asks `Let craftar mcp --allow-writes write here [no]:` — only `y` / `yes` records it. Exits 1, writing nothing, outside a terminal, without a `craftar.yaml`, with `CRAFTAR_NO_REGISTRY` set, when the registry does not read or cannot be written, when `forge:` or `ref:` holds credentials, or on any other answer. The consent is bound to that `forge`, `ref` and `profile`: after one of them changes, a writing call is refused until the consent is given again. `craftar workspaces forget` and `prune` drop the consent of what they remove. |
+| `craftar mcp revoke-writes [--workspace <dir>]` | Removes that consent; needs no terminal; takes effect on the server's next call, without a restart. Exits 0 also when there was none (`no consent recorded for <path>`); exits 1 without a `craftar.yaml`, with `CRAFTAR_NO_REGISTRY` set, or when the registry does not read or cannot be written. |
 | `craftar cache prune [--dry-run] [--workspace <dir>] [--json]` | Removes the Forge cache entries nothing uses — no registered workspace (`missing` ones included until `craftar workspaces prune`) and not the current workspace — entries whose first fetch never completed (even when named), and trees unused for 14 days. Whole entries are kept with a warning when the registry is off or unreadable, or the current `craftar.yaml` does not read. Deletes by default; `--dry-run` shows. Never touches a workspace, a lock or the registry; no network. One removing prune at a time per `$CRAFTAR_HOME` (`forges/prune.lock`). An explicit `--workspace` without `craftar.yaml` exits 1. `--json` is a contract: `{home, dryRun, removed: [{path, kind, reason, bytes}], kept: [{path, reason, namedBy}], freedBytes, 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 ui [--port <n>]` | A local dashboard, in a browser: the table of `craftar workspaces` and, for a registered workspace, what `status`, `diff` and `explain` say about it and what `recipes` and `ingredients` say about its Forge. It prints one address and serves until interrupted (`Ctrl-C` exits 0). **Read-only**: nothing is written to a workspace, a lock, the registry or a Forge — the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; `git` runs as for `craftar workspaces`) — and the page never runs `sync` — it prints the command to copy. **Loopback only**: it listens on `127.0.0.1` (no `--host`; `localhost` is refused), answers `GET` only, and every answer that carries data needs a token generated for that run — it travels in the address's fragment, which the browser does not send, so open the address exactly as printed (pasted, not clicked from a web page; a reload keeps working, a new tab needs the address again); it stays in the terminal's scrollback (and in a file, if the output is redirected) and may stay in the browser's history, and is worth nothing once the command stops. **No network**: a remote Forge is read from the cached copy, never fetched, and the page says so. `--port` (default `4747`; `0` takes a free one); a taken port is refused, never replaced. A Forge URL the registry recorded with credentials is shown as `(a URL with credentials — not shown)`, with no cache key — as `craftar workspaces --json` gives it since `0.28.1` (see *Upgrading › to 0.28.1*). Takes no `--workspace`; exits 1 when the registry is off (`CRAFTAR_NO_REGISTRY`) or cannot be read. The page's routes are not a contract. |
@@ -344,6 +346,14 @@ steering = `inclusion` frontmatter + `GENERATED` banner + rule body, with `.clau
 
 **agents-md** — one `AGENTS.md` with the always-on rules concatenated and the scoped rules after them — each listed at the file a target of the workspace writes for it (`.claude/rules/<name>.md` when `claude-code` writes it, else `.kiro/steering/<name>.md` when `kiro` does), or, when no target writes it, embedded in full under a `> Scoped rule — <scope>` line, for tools that read the open standard (Codex, Cursor, Warp, Copilot, Kimi…). A `.claude/rules/<x>.md` reference inside a body follows the rule it names: it is kept when `claude-code` writes that rule, becomes `.kiro/steering/<x>.md` when only `kiro` writes that file (from the rule or from a `steering` ingredient of that name), becomes `AGENTS.md (rule: <x>)` when the rule's text is in this file, and otherwise becomes `<x> (rule not in this workspace)` with a warning (an unknown name is left as written when `claude-code` is a target); a reference inside a link's text is resolved the same way, and a link whose target reads "rule not in this workspace" and whose text is exactly its own path becomes `<x> (rule not in this workspace)` (backticks kept); without `claude-code`, the warning also names references to other `.claude/` files, which are left as written. Every other ingredient type aimed at `agents-md` — including through the default `targets: "*"` — has no `AGENTS.md` equivalent: it is skipped with a warning — one line per type, naming every skipped ingredient. The file keeps the line endings and BOM of the one it replaces; a new one is LF without a BOM. **A size budget, `agents-md.maxBytes`** (default 32768 — Codex's `project_doc_max_bytes`; `0` turns it off), set in one of the layers that give params: a recipe's `params` (its `default` counts as set), the profile's `params`, or `overrides.params` in `craftar.yaml` or `craftar.local.yaml`; a value that is not a whole number of bytes is a warning, and the default applies. The size is the planned `AGENTS.md` in bytes; each rule body the file holds — always-on, and a scoped one embedded because no target writes it — is counted as its UTF-8 bytes after reference resolution and the trailing-newline trim. Over the budget every plan warns, naming at most 5 rules by name and bytes, never their content: `AGENTS.md is N bytes, over the default budget of 32768 (agents-md.maxBytes) — largest rules: a (n bytes), b (scoped, n bytes)`, or, when the budget is set, `… over the budget of M set by agents-md.maxBytes; sync --check fails — …`. Only a budget that is set fails anything: `sync --check`, `status` (and `status --json`, whose keys do not change — the reason is that warning) and `diff --exit-code` with no `[path]` exit 1 and print `error: AGENTS.md is N bytes, over the budget of M set by agents-md.maxBytes` with its fix; a writing `sync` still writes — so it never turns a `craftar workspaces` row into `error` (the table lists the warning under the workspace's path), `forge impact` does not show it, and the `next sync:` line does not count it (`add recipe`, `remove recipe` and `init --no-sync` still print the warning beside it). `doctor` reports it once, as `agents-md-size`.
 
+**One home for the always-on rules, `agents-md.primary`** (a Forge at `schema: 5`). With `claude-code`, `kiro` and `agents-md` all targets, an always-on rule with the default `targets` is written three times — `.claude/rules/<x>.md`, `.kiro/steering/<x>.md` and its section of `AGENTS.md` — and Claude Code and Kiro each load two of them. Set the param `agents-md.primary: true` (a recipe default, the profile's `params` or `overrides.params`; a YAML boolean) in a Forge that declares `schema: 5` and a workspace whose targets include `agents-md`, and such a rule is written to `AGENTS.md` alone:
+- **Who follows it:** a rule with `inclusion: always` whose `targets` is the default (`"*"`, written or omitted). A rule with a `targets` list keeps it — list `targets: [claude-code, agents-md]` to keep a rule in `.claude/rules/` too. Scoped rules, `steering` and every other type are untouched. The files the mode stops writing become orphans: `sync` removes them (its line reads `orphan: written to AGENTS.md only (agents-md.primary)`, and `diff`'s header `(forge: written to AGENTS.md only — sync removes it)`), and a hand-edited one is kept as an `orphan-drift` until `drift discard` or a delete.
+- **References follow the rule:** in the `.claude/` files the `claude-code` emitter writes — a scoped rule's body, an agent's and a command's body and its `frontmatterRaw` (else its `description`), a skill's `.md` files — a `.claude/rules/<x>.md` reference is resolved as in `AGENTS.md`: `AGENTS.md (rule: <x>)` for a rule held there (a link loses its fragment), `.kiro/steering/<x>.md` for a rule only `kiro` writes. The `kiro` files reword such a reference to `AGENTS.md (rule: <x>)` too. Scripts, hooks and files copied as bytes are never rewritten: a reference there is warned with its file and line (`claude-code: … left as written in files craftar copies: .claude/scripts/lint.sh:2 (style)`), never with the line.
+- **Kiro `resources`:** a generated list names only the steering files the plan writes, and never `file://AGENTS.md` (a custom agent inherits `AGENTS.md` — measured with kiro-cli 2.29.1). A hand-written `file://` entry with no glob under `.kiro/steering/`, `.claude/rules/` or naming `AGENTS.md` is checked: one the plan does not write and the disk lacks fails `sync --check`, `status` and `diff --exit-code` (a writing `sync` still writes); one only on disk is a warning. Measured with kiro-cli 2.29.1: a missing entry is no error to Kiro, and a `manual` steering file is not loaded through `resources` — neither by the glob `file://.kiro/steering/**/*.md` nor named alone.
+- **`CLAUDE.md`:** Claude Code (2.1.277 or later) reads `AGENTS.md` only when no `CLAUDE.md` — at the root, in `.claude/`, or `CLAUDE.local.md` — is in the way, unless one imports it: a line `@AGENTS.md` (or `@./AGENTS.md`) in the root's `CLAUDE.md`, or `@../AGENTS.md` in `.claude/CLAUDE.md` (an import is relative to the file that holds it — measured with Claude Code 2.1.310). craftar never writes a `CLAUDE.md`; when the root holds one that blocks, every plan warns, naming the file and never a line of it. A Claude Code before 2.1.277 reads only `CLAUDE.md` and `.claude/rules/`, and loses the always-on rules without a word from craftar.
+- `doctor` gains `agents-md-primary` (a blocking `CLAUDE.md` at the root, or one in a directory above the workspace — never above `warn`) and `kiro-resources` (`error` for an unplanned entry, `warn` for one on disk only), both only under the mode. Over the `AGENTS.md` budget, the warning adds `these rules are in no other file`. `drift promote` refuses a file the mode reworded (`drift show`: `reworded by agents-md.primary`), and `import` into a Forge that sets the mode compares each base as the mode writes it.
+- Below `schema: 5` the key is not read (set to `true` it warns, and the mode is off); a value that is not a boolean, or the mode with no `agents-md` target, warns and leaves it off. **A workspace that does not set the key sees no change at all.** The key is reserved: `forge unify` never extracts into it and `import` never infers it.
+
 Conversion of hooks/subagents to other tools is out of scope here: the plan is to delegate that to [rulesync](https://github.com/dyoshikawa/rulesync) rather than reimplement it.
 
 ## Design rules learned from the previous generator
@@ -507,20 +517,36 @@ server:
 
 The server answers for the directory it is started in; a client that starts its servers elsewhere needs `args: [mcp, --workspace, <dir>]`. The server also sees only the environment the client starts it with: `git`, `dotnet` and `docker` are looked for in the absolute entries of that `PATH` (a `node_modules/.bin` of the directory the server is started in, or of one above it, aside — see *to 0.28.2*), and the variables `doctor` checks are read there — so a client that starts its servers with a reduced `PATH` gets `git not found` from `doctor` (its `dotnet` and `docker` checks warn too, when the workspace uses them and its Forge loads), no commit for a Forge that is a directory and, when the Forge is a git URL, an error from `status`, `diff`, `explain`, `recipes` and `ingredients` — `targets` then answers the matrix unmarked, with a warning, and `doctor` reports `git` as an `error` and, of the workspace's checks, runs only `lock`.
 
+**Letting it write.** Started with `--allow-writes` (`args: [mcp, --allow-writes]`), the server also lists `sync`, `add_recipe` and `remove_recipe`. The flag grants nothing by itself: each writing call reads this machine's registry and acts only when a person typed `craftar mcp allow-writes` in this workspace, in a terminal, for the Forge, ref and profile the server is pinned to — so a Forge that puts `--allow-writes` in its `craftar` ingredient makes the tools appear in every workspace that syncs it, and write in none until someone there consents. `craftar mcp revoke-writes` takes the consent back. The consent refuses to be recorded outside a terminal; the shell tools of Claude Code and Kiro run without one (measured on 2026-10-23: neither gives a program a terminal on stdin or stdout), so an agent cannot grant it through them — an agent that drives a real terminal could, and could type `craftar sync` there as well. `sync` never overwrites or removes a hand edit: a `drift`, an `orphan-drift` and a `collision` are skipped and listed, and a person resolves them with `craftar drift discard` or `craftar drift promote`. Writes are not locked against a `craftar sync` run at the same moment in a terminal; each re-reads the disk just before it writes.
+
 **What the results hold.** A tool result goes wherever the AI coder sends its context, and the tools return the commands' data with three things left out: `doctor`'s checks about the rest of the machine (`$CRAFTAR_HOME`, the registry, the Forge cache), the on-disk content of a hand-edited MCP configuration file, and — from `diff` without a path — the bodies (it lists counts). Nothing else is filtered. So a result can hold: the content of a generated file with its hand edits, or of a file craftar never wrote that sits where it would write one (`diff` with a path, on a `drift` or a `collision`) — a hand-edited service file under `.craftar/` included; values a profile or `overrides.params` put into a generated file; the Forge's path or URL as `craftar.yaml` names it; the absolute path of the workspace and of a path Forge, the Docker Compose and .NET SDK versions found on this machine and the names of the variables a service fragment expects — names, never values (`doctor`); and **the names of every profile of the Forge and the workspace an ingredient was imported from** — the profiles beside each recipe in `recipes`, the origin in `explain`. In a Forge shared across clients those names can be client names — register the server only where that is acceptable.
 
 ## Roadmap (from the functional spec)
 
 Phase 0 — foundations (done): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; `forge variants`, `forge diff` and `forge unify` (`take: param`, `take: section`); sections.
 
-Phase 1 — client profile (in progress). Shipped: the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock) and `craftar cache prune`; the workspace registry and `craftar workspaces`; `craftar add recipe` / `remove recipe`; `craftar init` with flags; `craftar doctor`; `craftar forge impact`, `forge unify --prune-recipes` and `forge promote`; an interactive `craftar init` (choose the Forge and the profile); `authEnv` on MCP ingredients (the environment variables a server needs, by name, and the generated `.claude/settings.craftar.example.json`); `craftar drift show` / `drift discard` / `drift promote` (list the files edited by hand, discard an edit, or carry one into the Forge as a profile value or a variant); a sync refused when a declared parameter has no value; `craftar import --report` (a Markdown report of an import, as paths and line counts) and `import --prefer-kiro` (a rule's source taken from its Kiro steering file); a profile's `integrations` block (PM tool and IDP as recipes selected by the profile); `{{param}}` inside an MCP server; `craftar mcp` (a read-only MCP server: seven reading tools for an AI coder, over stdin and stdout); `craftar ui` (a local, read-only dashboard of the registered workspaces, on `127.0.0.1` only); cloning a profile's repositories (`init --clone`, `craftar repos`); a new profile from `craftar init` (`--new-profile`, `--like`).
+Phase 1 — client profile (in progress). Shipped: the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock) and `craftar cache prune`; the workspace registry and `craftar workspaces`; `craftar add recipe` / `remove recipe`; `craftar init` with flags; `craftar doctor`; `craftar forge impact`, `forge unify --prune-recipes` and `forge promote`; an interactive `craftar init` (choose the Forge and the profile); `authEnv` on MCP ingredients (the environment variables a server needs, by name, and the generated `.claude/settings.craftar.example.json`); `craftar drift show` / `drift discard` / `drift promote` (list the files edited by hand, discard an edit, or carry one into the Forge as a profile value or a variant); a sync refused when a declared parameter has no value; `craftar import --report` (a Markdown report of an import, as paths and line counts) and `import --prefer-kiro` (a rule's source taken from its Kiro steering file); a profile's `integrations` block (PM tool and IDP as recipes selected by the profile); `{{param}}` inside an MCP server; `craftar mcp` (a read-only MCP server: seven reading tools for an AI coder, over stdin and stdout); `craftar ui` (a local, read-only dashboard of the registered workspaces, on `127.0.0.1` only); cloning a profile's repositories (`init --clone`, `craftar repos`); a new profile from `craftar init` (`--new-profile`, `--like`); writing tools for `craftar mcp` (`--allow-writes`: `sync`, `add_recipe`, `remove_recipe`, behind a consent typed per workspace).
 
 Phase 2 — environment (in progress). Shipped: local services (`service` ingredients, `.craftar/`, `craftar services up | down | status`); `craftar templates list | install` (`dotnet new` project templates declared in a profile).
 
-Later: rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; writing tools for `craftar mcp` (`sync`, `add recipe`) and its Claude Code / Agent Plugin packaging.
+Later: rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; the Claude Code / Agent Plugin packaging of `craftar mcp`.
 
 ## Upgrading
 
+### to 0.36.0
+
+- **A Forge can declare `schema: 5`**, which includes 4, 3 and 2. Every craftar before `0.36.0` refuses such a Forge at `craftar.forge.yaml`, so no older craftar writes the three copies of a rule the mode keeps in `AGENTS.md` alone. Upgrade every machine and CI that reads the Forge before setting it. Nothing changes for a Forge at 1 to 4.
+- **`agents-md.primary` is opt-in.** A workspace that does not set it sees no change: no byte, no lock entry, no warning, no exit code, `doctor --strict` included. Turning it on changes bytes by design: the `.claude/rules/` and `.kiro/steering/` files of the always-on rules with default targets become orphans that `sync` removes; the `.claude/`, `.kiro/` and `AGENTS.md` texts citing them are reworded; generated Kiro `resources` name only the steering files the plan writes.
+- **`doctor --json` gains the check ids `agents-md-primary` and `kiro-resources`** (additive, present only under the mode). `drift show --json` can give the reason `reworded by agents-md.primary`. The `sync` tool of `craftar mcp` can give the `removed` reason `orphan: written to AGENTS.md only (agents-md.primary)`, the words `craftar sync` prints.
+- **The key `agents-md.primary` is reserved** at every schema: `forge unify` never extracts a profile value into it and `import` never infers it.
+
+### to 0.35.0
+
+- **New flag: `craftar mcp --allow-writes`**, and two commands, `craftar mcp allow-writes` and `craftar mcp revoke-writes` (see *Commands* and *Craftar inside the AI coder*). Without the flag, `craftar mcp` answers byte for byte as before — `initialize`, `tools/list` and every tool. Its `--help` description now reads `Reads only unless --allow-writes`.
+- **`registry.json` may hold a top-level `writeConsent` list** (the consents of `craftar mcp allow-writes`); the registry stays `schema: 1`. A craftar from `0.12.0` on keeps the key when it rewrites the registry, and a registry that never held a consent is written as before (an empty list is omitted). `craftar workspaces --json` gains no key.
+- **A Forge may register the server with `--allow-writes`**: every workspace that syncs it then lists the writing tools, which refuse every call until a person in that workspace runs `craftar mcp allow-writes`. On a craftar before `0.35.0` the flag is an unknown option and the server fails to start — upgrade every machine before adding it to a shared Forge.
+- No emitted byte, lock, `--json` shape or exit code of an existing command changes.
+
 ### to 0.34.2
 
 - **`import` now creates one script/hook ingredient per base name**, listing every file that shares that name (e.g., `run-x.ps1` and `run-x.sh` become one `script/run-x` with `files: ["run-x.ps1", "run-x.sh"]`). A Forge imported before keeps its shape (a base with one file and a `<name>--<profile>` variant with the other); a re-import rewrites that variant with both files. Two files that differ only in case (on a case-insensitive checkout they would collide) are rejected and named; the rest of the import proceeds. A file left in a variant directory after a re-import that grouped it is warned. No emitted byte changes; a Forge with the old shape may be fixed with `forge promote` or by hand.

package/dist/cli.js

@@ -8,22 +8,23 @@ import { parsePreferKiro } from "./importers/prefer-kiro.js";
 import { planPromote, applyPromote, UnheldError } from "./importers/drift-promote.js";
 import { providedRefs } from "./importers/provided.js";
 import { holdsBaseCitations, rendersServers } from "./core/mcp-server.js";
-import { assertNotCacheTree, classifyForge } from "./core/remote.js";
-import { forget, listWorkspaces, prune, readRegistry, register, registryFile } from "./core/registry.js";
-import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState, countStates, countStatesObject, NEXT_SYNC_STATES } from "./core/impact.js";
+import { assertNotCacheTree, classifyForge, CREDENTIAL_HIDDEN, refHoldsCredentials } from "./core/remote.js";
+import { allowWrites, forget, listWorkspaces, prune, readRegistry, revokeWrites } from "./core/registry.js";
+import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState, countStatesObject, NEXT_SYNC_STATES } from "./core/impact.js";
 import { runDoctor } from "./core/doctor.js";
 import { launchRefusal, pinOf } from "./core/mcp-protocol.js";
 import { serve } from "./mcp.js";
+import { mcpWriters } from "./core/write-actions.js";
 import { pruneCache } from "./core/cache.js";
 import { resolveHome } from "./core/home-lock.js";
-import { loadWorkspace, loadForgeSource, readWorkspaceConfig, plan, readLock, status, apply, unsetDeclared, unsetRefusal, unsetRefused, agentsMdOverBudget, agentsMdRefusal, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
+import { loadWorkspace, loadForgeSource, readWorkspaceConfig, plan, readLock, status, unsetDeclared, unsetRefusal, agentsMdOverBudget, agentsMdRefusal, kiroResourcesUnplanned, kiroResourcesRefusal, orphanReason, primaryOrphan, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
 import { sectionKey } from "./core/resolve.js";
 import { catalogueContext, listRecipes, listIngredients, checkType, withLoadWarnings } from "./core/catalogue.js";
 import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { preferredLine, renderImportReport } from "./core/import-report.js";
 import { driftList, unmanaged } from "./core/drift.js";
-import { EXAMPLE_CONTENT_HIDDEN, diffReport, explainFile, explainSkip, notProduced, readText, statusPath, statusReport, targetsReport } from "./core/report.js";
+import { EXAMPLE_CONTENT_HIDDEN, diffReport, explainFile, explainSkip, forgeLine, nextSyncLine, notProduced, readText, statusPath, statusReport, targetsReport } from "./core/report.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { exists, gitDirty, gitIgnored, gitIsRepo, gitUnheld, loadForge, realpathOfNearest } from "./core/forge.js";
 import { applyBasePromotion, planBasePromotion, proveBasePromotion } from "./core/promote.js";
@@ -38,8 +39,9 @@ import { askInit, askClone, confirmInit, againLine, NOT_CLONED_REFUSED } from ".
 import { findGit, cloneRepos, listRepos, planClone } from "./core/clone.js";
 import { byHand, profileRepos } from "./core/repos.js";
 import { readlineIo } from "./prompt.js";
-import { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
-import { localKeys, readLocalFile } from "./core/workspace-yaml.js";
+import { recipeDiffLine } from "./core/recipe-edit.js";
+import { syncWorkspace, editRecipes, confirmWrites } from "./core/write-actions.js";
+import { readLocalFile } from "./core/workspace-yaml.js";
 import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 import { EXAMPLE_SETTINGS } from "./emitters/shared.js";
 import { YamlSyntaxError, parseYamlText } from "./core/yaml-read.js";
@@ -57,7 +59,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.34.2");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.36.0");
 const SAVE_PLAN_GATE = { what: "plan", who: "unify", outside: "save plans outside the Forge", never: "unify never overwrites" };
 const REPORT_GATE = { what: "report", who: "import", outside: "write the report outside the Forge", never: "import never overwrites" };
 program
@@ -163,7 +165,7 @@ program
         console.log(JSON.stringify(report, null, 2));
         // exitCode, not process.exit: a piped object is not cut (spec 29 §4.1)
         // The object carries both reasons (unsetParams, the budget line in warnings): nothing on stderr
-        if (unset.length || agentsMdOverBudget(p))
+        if (unset.length || agentsMdOverBudget(p) || kiroResourcesUnplanned(p)?.length)
             process.exitCode = 1;
         return;
     }
@@ -190,42 +192,33 @@ function budgetRefusalBlock(p) {
     const over = agentsMdOverBudget(p);
     if (over)
         errorLine(agentsMdRefusal(over));
-    return over !== null;
+    const kiroUnplanned = kiroResourcesUnplanned(p);
+    if (kiroUnplanned)
+        errorLine(kiroResourcesRefusal(kiroUnplanned));
+    return over !== null || kiroUnplanned !== null;
 }
 /**
  * A writing sync on a planned workspace, then its report: `apply`, the registration of spec 21 (unless
  * `CRAFTAR_NO_REGISTRY`), and the lines `sync` prints. `sync` and `init` both call it (spec 23 §5.2).
  */
 async function applyAndReport(ws, p, st, lock, opts = {}) {
-    const r = await apply(ws, p, st, opts);
-    // A writing sync records the workspace (spec 21 §4.1); the registry is an index, so a failure is a warning.
-    let registryWarning = null;
-    if (!opts.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 o = await syncWorkspace(ws, p, st, lock, { ...opts, home: craftarHome(), registryOff: registryOff() });
     const verb = opts.dryRun ? "would write" : "wrote";
     console.log(pc.bold(`craftar sync — profile ${ws.config.profile} · recipes ${p.resolution.recipes.join(" → ")} · targets ${p.resolution.targets.join(", ")}`));
-    const fl = forgeLine(ws, lock);
-    if (fl)
-        console.log(fl);
-    console.log(`  ${verb} ${pc.green(String(r.written.length))}, removed ${pc.magenta(String(r.removed.length))} orphan(s), skipped ${pc.yellow(String(r.skipped.length))}`);
-    for (const f of r.written)
+    if (o.forgeLine)
+        console.log(o.forgeLine);
+    console.log(`  ${verb} ${pc.green(String(o.result.written.length))}, removed ${pc.magenta(String(o.result.removed.length))} orphan(s), skipped ${pc.yellow(String(o.result.skipped.length))}`);
+    for (const f of o.result.written)
         console.log(`  ${pc.green("+")} ${f}`);
-    for (const f of r.removed)
-        console.log(`  ${pc.magenta("-")} ${f}  (${opts.overwritePaths?.has(f) ? "hand-edited orphan: discarded" : "orphan: no longer produced by the Forge"})`);
-    for (const s of r.skipped)
+    for (const f of o.result.removed)
+        console.log(`  ${pc.magenta("-")} ${f}  (${opts.overwritePaths?.has(f) ? "hand-edited orphan: discarded" : orphanReason(p, st, f)})`);
+    for (const s of o.result.skipped)
         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}`);
-    return r;
+    if (o.registry)
+        console.log(`  ${pc.yellow("warn")} registry not updated (${o.registry.file}): ${o.registry.message}`);
+    return o.result;
 }
 /**
  * Shared clone report for `craftar init --clone` and `craftar repos clone`.
@@ -792,7 +785,8 @@ program
         if (only && s.path !== only)
             continue;
         // Spec 19 §3.2: the six states sync --check refuses are shown; which those are is diffReport's to say
-        if (await printFileDiff(ws.root, s))
+        const isPrimary = primaryOrphan(p, s);
+        if (await printFileDiff(ws.root, s, { isPrimary }))
             shown++;
     }
     if (!shown)
@@ -809,7 +803,7 @@ program
 });
 const DIFF_PAINT = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
 /** What `craftar diff` prints for one file `sync --check` refuses; `drift show <path>` prints the same for a drifted one. */
-async function printFileDiff(root, s) {
+async function printFileDiff(root, s, opts = {}) {
     // What to show is decided in the core (`diffReport`); the headers and the paint are this command's.
     const [row] = await diffReport({ root }, [s], { withholdMcp: false });
     // Nothing to show for `unchanged` and `adopt`: says so, for the caller's count
@@ -822,7 +816,8 @@ async function printFileDiff(root, s) {
     else 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)`));
+        const orphanReason = opts.isPrimary ? "written to AGENTS.md only — sync removes it" : "no longer produced — sync removes it";
+        console.log(pc.bold(`+++ ${s.path} (forge: ${orphanReason})`));
     }
     else {
         console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
@@ -864,7 +859,7 @@ drift
         // Below schema 3, providedRefs returns early (line "if (!eff.selected.length) return new Map()") before resolve(), so it cannot throw.
         providedWarnings.push(`profile ${ws.config.profile} does not resolve on its own (${e.message}) — what its integrations provide was not computed, and craftar drift promote will refuse`);
     }
-    const rows = driftList(named ? [named] : st, provided);
+    const rows = driftList(named ? [named] : st, provided, new Set(p.reworded));
     // Spec 30r5: drift show decides a refused sync as status does — unsetParams in --json, the refusal block on stderr, exit 1.
     const unset = unsetDeclared(p);
     if (o.json) {
@@ -1131,43 +1126,20 @@ drift
     }
 });
 /* ---------------------------------------------------------------- add / remove recipe */
-/**
- * Spec 22's line: what the next sync would do (also `init --no-sync`, spec 23 §4.4).
- * Uses `countStates` from `src/core/impact.ts`; a new `FileState` does not compile until it is
- * placed in `FILE_STATE_ORDER_MAP` there. A plan with unset declared parameters has no next sync
- * to count: the line says it is refused (spec 29 §4.1).
- */
-function nextSyncLine(st, unset) {
-    if (unset.length)
-        return `next sync: ${unsetRefused(unset)}`;
-    const counts = countStates(st).map(([k, n]) => `${n} ${k}`);
-    return `next sync: ${counts.length ? `${counts.join(", ")} — run \`craftar sync\`` : "nothing to sync"}`;
-}
 function recipeCommand(op) {
     return async (names, o) => {
         const ws = await loadWorkspace(o.workspace, load(o, "read"));
         warnStderr(ws.warnings);
-        // R1: arrays replace across layers, so an edit of craftar.yaml would not take effect (spec 22 Ruling 1).
-        if ((await localKeys(ws.root)).includes("recipes"))
-            fail(`${LOCAL_FILE} sets recipes, which replaces ${WORKSPACE_FILE}'s lists — edit it by hand, or remove its recipes key and re-run`);
-        const edit = planRecipeEdit(ws.forge, ws.config, op, names, { replace: o.replace === true });
-        if (!edit.changed) {
-            console.log(`nothing to change${edit.reasons.length ? `: ${edit.reasons.join(", ")}` : ""}`);
+        const outcome = await editRecipes(ws, op, names, { replace: o.replace });
+        if (!outcome.changed) {
+            console.log(`nothing to change${outcome.reasons.length ? `: ${outcome.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 nextLine = nextSyncLine(st, unsetDeclared(p));
-        await fs.writeFile(file, content);
-        console.log(`${WORKSPACE_FILE}: ${recipeDiffLine(ws.config.recipes, edit.recipes)}`);
-        console.log(`recipes: ${p.resolution.recipes.join(" → ")}`);
-        console.log(nextLine);
+        console.log(`${WORKSPACE_FILE}: ${recipeDiffLine(outcome.before, outcome.after)}`);
+        console.log(`recipes: ${outcome.next.recipes.join(" → ")}`);
+        console.log(nextSyncLine(outcome.next.statuses, outcome.next.unset));
         // plan() already carries ws.warnings first, and they were printed on load.
-        warnStderr(p.warnings.slice(ws.warnings.length));
+        warnStderr(outcome.next.warnings);
     };
 }
 program
@@ -1456,11 +1428,12 @@ templates
         process.exitCode = 1;
 });
 /* ---------------------------------------------------------------- mcp */
-program
+const mcpCmd = program
     .command("mcp")
-    .description("Serve this workspace to an AI coder over the Model Context Protocol, on stdin and stdout: seven reading tools — status, diff, explain, recipes, ingredients, targets, doctor — with the data those commands print. Started by the AI coder, not typed. Reads only; reads without the network unless --fetch")
+    .description("Serve this workspace to an AI coder over the Model Context Protocol, on stdin and stdout: seven reading tools — status, diff, explain, recipes, ingredients, targets, doctor — with the data those commands print. Started by the AI coder, not typed. Reads only unless --allow-writes; reads without the network unless --fetch")
     .option("--workspace <dir>", "the workspace to serve", ".")
     .option("--fetch", "let a tool call fetch a remote Forge instead of reading the cached copy", false)
+    .option("--allow-writes", "enable the writing tools (sync, add_recipe, remove_recipe) for a workspace with consent", false)
     .action(async (o) => {
     // The bound workspace, resolved once: no tool takes a directory (spec 35 §4.1).
     const root = path.resolve(o.workspace);
@@ -1484,8 +1457,99 @@ program
         registryOff: registryOff(),
         env: process.env,
         pin: pinOf(merged),
+        writers: o.allowWrites ? mcpWriters(craftarHome(), registryOff()) : undefined,
     });
 });
+mcpCmd
+    .command("allow-writes")
+    .description("Let craftar mcp --allow-writes write in this workspace — sync, add_recipe, remove_recipe — for the Forge, ref and profile it names now; asks a person in a terminal and records the consent in this machine's registry")
+    // No default here: `mcp` holds `--workspace` too, and commander gives the value to the parent when both declare it.
+    .option("--workspace <dir>", 'workspace root (default: ".")')
+    .action(async (o) => {
+    const workspace = o.workspace ?? mcpCmd.opts().workspace ?? ".";
+    if (mcpCmd.opts().fetch)
+        fail("craftar mcp allow-writes takes only --workspace");
+    if (mcpCmd.opts().allowWrites)
+        fail("craftar mcp allow-writes takes only --workspace");
+    const root = path.resolve(workspace);
+    if (!(await exists(path.join(root, WORKSPACE_FILE)))) {
+        fail(`no craftar.yaml in ${root} — the consent is given for one workspace; type it in one, or pass --workspace`);
+    }
+    if (registryOff())
+        fail("the consent is recorded in the registry, and CRAFTAR_NO_REGISTRY is set — unset it to allow writes");
+    const home = craftarHome();
+    try {
+        await readRegistry(home);
+    }
+    catch (e) {
+        fail(`cannot read the registry: ${errorText(e)}`);
+    }
+    // a forge: holding credentials is refused here, before anything prints it
+    let merged;
+    try {
+        merged = await readWorkspaceConfig(root);
+    }
+    catch (e) {
+        fail(errorText(e));
+    }
+    // before anything prints or records it (and before the terminal check)
+    if (merged.config.ref && refHoldsCredentials(merged.config.ref)) {
+        fail(`ref holds ${CREDENTIAL_HIDDEN} — remove the credentials before allowing writes`);
+    }
+    if (!(process.stdin.isTTY === true && process.stdout.isTTY === true)) {
+        fail("craftar mcp allow-writes asks a person in a terminal — type it in one; it cannot be run from a script or an AI coder's shell tool");
+    }
+    const realRoot = await fs.realpath(root);
+    const refLine = merged.config.ref ?? "(the Forge's default)";
+    console.log(`craftar mcp allow-writes — ${realRoot}`);
+    console.log(`  forge    ${merged.config.forge}`);
+    console.log(`  ref      ${refLine}`);
+    console.log(`  profile  ${merged.config.profile}`);
+    console.log(`  tools    sync, add_recipe, remove_recipe — sync never discards a hand edit`);
+    if (!(await confirmWrites(readlineIo(process.stdin, process.stdout, { terminal: true }))))
+        fail("allow-writes cancelled — nothing written");
+    try {
+        const consent = await allowWrites(home, root, {
+            forge: { source: merged.config.forge, ref: merged.config.ref ?? null },
+            profile: merged.config.profile,
+        });
+        console.log(`write consent recorded for ${consent.path} — craftar mcp --allow-writes may sync and edit recipes here; craftar mcp revoke-writes takes it back`);
+    }
+    catch (e) {
+        fail(`consent not recorded: ${errorText(e)}`);
+    }
+});
+mcpCmd
+    .command("revoke-writes")
+    .description("Take back the consent of craftar mcp allow-writes for this workspace; needs no terminal")
+    // No default here: `mcp` holds `--workspace` too, and commander gives the value to the parent when both declare it.
+    .option("--workspace <dir>", 'workspace root (default: ".")')
+    .action(async (o) => {
+    const workspace = o.workspace ?? mcpCmd.opts().workspace ?? ".";
+    if (mcpCmd.opts().fetch)
+        fail("craftar mcp revoke-writes takes only --workspace");
+    if (mcpCmd.opts().allowWrites)
+        fail("craftar mcp revoke-writes takes only --workspace");
+    const root = path.resolve(workspace);
+    if (!(await exists(path.join(root, WORKSPACE_FILE)))) {
+        fail(`no craftar.yaml in ${root} — the consent is given for one workspace; type it in one, or pass --workspace`);
+    }
+    if (registryOff())
+        fail("the consent is recorded in the registry, and CRAFTAR_NO_REGISTRY is set — nothing to revoke here");
+    const home = craftarHome();
+    try {
+        const result = await revokeWrites(home, root);
+        if (result.removed) {
+            console.log(`write consent removed for ${result.path}`);
+        }
+        else {
+            console.log(`no consent recorded for ${result.path}`);
+        }
+    }
+    catch (e) {
+        fail(`consent not removed: ${errorText(e)}`);
+    }
+});
 /* ---------------------------------------------------------------- recipes */
 program
     .command("recipes")
@@ -3007,16 +3071,6 @@ function matchSuffix(ws) {
         suffix += `, pins ${ws.ref}`;
     return suffix;
 }
-/** The header line naming a remote Forge (spec 13 §4.1); null for a path Forge, whose headers keep their shape. */
-function forgeLine(ws, lock) {
-    const o = ws.origin;
-    if (o.kind !== "remote")
-        return null;
-    const commit = ws.forge.commit;
-    const at = o.ref ?? `${o.defaultBranch} (default branch)`;
-    const moved = lock?.forge.commit && commit && lock.forge.commit !== commit ? ` · lock ${lock.forge.commit.slice(0, 8)}` : "";
-    return `  forge ${o.source} @ ${at} ${commit?.slice(0, 8) ?? "no git"}${moved}`;
-}
 /** One line on stderr with the `error: ` prefix, without exiting — `fail()` is this, then exit 1. */
 function errorLine(msg) {
     console.error(pc.red("error: ") + msg);