craftar 0.34.2 → 0.35.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.
 
 ## The idea in one paragraph
 
@@ -93,7 +93,9 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `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 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. |
@@ -507,20 +509,29 @@ 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.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, 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.35.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
@@ -197,35 +199,23 @@ function budgetRefusalBlock(p) {
  * `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)
+    for (const f of o.result.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 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`.
@@ -1131,43 +1121,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 +1423,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 +1452,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 +3066,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);