craftar 0.28.2 → 0.29.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`. Everything else in the spec (`craftar ui`, `craftar mcp`) is not built yet.
+> 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. Everything else in the spec (`craftar ui`) is not built yet.
 
 ## The idea in one paragraph
 
@@ -82,6 +82,7 @@ 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` — 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 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 recipes [--forge <dir> [--profile <name>] \| --workspace <dir>] [--json]` | Every recipe of the Forge, sorted by name: slot, the parents it extends, the ingredients it lists itself and the profiles that reach it. In a workspace (or with `--forge <dir> --profile <name>`) each recipe says whether it is in use and why — `profile` (listed in `recipes` or selected by the profile's `integrations` block), `workspace` (`recipes.add`), `extends <child>` — and a recipe `recipes.remove` names reads `removed by this workspace`. A context that does not resolve (two recipes on one slot, an unknown recipe, a cycle) still lists everything, marks nothing and warns. Read-only: it resolves, never plans. `--json` is a contract: `{forge, context, recipes, warnings}`. |
@@ -372,7 +373,7 @@ They are generated files like any other: `status`, `diff`, `sync --check` and `-
 
 **The plan fails** when a fragment is not a YAML mapping, declares no service, declares a top-level `name` (the project name is craftar's) or `include` (every file of the stack is in the lock) — also when they arrive through a YAML merge key (`<<`): a fragment is checked as Compose reads it; when a service's `extends` names a `file` (it may extend a service of the same fragment), or when two fragments declare the same key under `services`, `volumes`, `networks`, `configs` or `secrets` — Compose would keep one silently. A file not listed in `binary` must be UTF-8 text. **It warns** when two fragments publish the same literal host port, and when a rendered file holds a secret-like value (the kind and the line, never the value): keep values out of the Forge and use `${NAME}`.
 
-**Running it.** `craftar services up` runs `docker compose up -d` on the stack, `services down` stops it and `services status` shows it (see *Commands*). They need Docker with its Compose plugin, found on `PATH` by the lookup that finds `dotnet` and `git` (see *Project templates*); `up` needs Compose **2.20.0 or later** (the first with `include`), while `down` and `status` work on an older one. `sync` needs no Docker. `up` reads the lock, not the Forge: it comes up on what the last `sync` wrote, and refuses a file that is missing or edited rather than run something the lock does not record. Nothing runs Docker implicitly — not `sync`, not `init`, and `doctor` only asks for the version. craftar adds no policy over what a fragment declares: a service runs with your Docker rights, as the hooks and scripts of a Forge run with yours.
+**Running it.** `craftar services up` runs `docker compose up -d` on the stack, `services down` stops it and `services status` shows it (see *Commands*). They need Docker with its Compose plugin, found on `PATH` by the lookup that finds `dotnet` and `git` (see *Project templates*); `up` needs Compose **2.20.0 or later** (the first with `include`), while `down` and `status` work on an older one. `sync` needs no Docker. `up` reads the lock, not the Forge: it comes up on what the last `sync` wrote, and refuses a file that is missing or edited rather than run something the lock does not record. Nothing runs Docker implicitly — not `sync`, not `init`, and `doctor` — the command, or the `doctor` tool of `craftar mcp` — only asks for the version. craftar adds no policy over what a fragment declares: a service runs with your Docker rights, as the hooks and scripts of a Forge run with yours.
 
 - **The project** is `craftar-<slug>-<hash>`: the workspace directory's name, lowercased, every character outside `a-z 0-9 _ -` replaced by `-`, cut at 40, then the first 8 hex digits of the SHA-256 of the workspace's real path. It is computed, never written, so the files under `.craftar/` are the same on every machine and two checkouts are two projects. `services status` prints it. Moving a workspace changes it: stop the old one with `docker compose -p <old name> down`. A name that leaves nothing but dashes gives `craftar--<hash>`.
 - **`${CRAFTAR_WORKSPACE}`** is set by `craftar services` to the workspace's real path, so a fragment can mount a repository of the workspace.
@@ -451,23 +452,57 @@ templates:
 A `kind` is a lowercase name (`dotnet-new`); a package is a NuGet ID, optionally with a version (`<id>::<version>`). A `source` is an `https://` URL with a host, in printable ASCII, and no user or password. There is no workspace layer: `craftar.yaml` and `craftar.local.yaml` cannot add or remove a template.
 
 - **The store is the user's** — one per machine user, shared by every workspace; the last install of a package ID wins. Remove one with `dotnet new uninstall <package>`.
-- **Feeds are additive** — a declared `source` is added to the feeds `dotnet` already uses, so an ID nobody reserved on a public feed can be served from there. Pin it with the team's own `NuGet.Config` at the workspace root (craftar looks there only, and generates none). `install` and `doctor` warn when an entry declares a `source` and the root has no `NuGet.Config`.
+- **Feeds are additive** — a declared `source` is added to the feeds `dotnet` already uses, so an ID nobody reserved on a public feed can be served from there. Pin it with the team's own `NuGet.Config` at the workspace root (craftar looks there only, and generates none). `install` and `doctor` — the command, or the `doctor` tool of `craftar mcp` — warn when an entry declares a `source` and the root has no `NuGet.Config`.
 - **Private feeds** — authentication is NuGet's (`NuGet.Config`, a credential provider, `--interactive`); craftar holds no token, and a `source` carrying a user or a password is refused and never printed. A `source` is printed as written by `list`, `--dry-run` and `install`: craftar refuses a user or a password in it, not a token in its path or query — keep those out of the profile.
-- **`dotnet` comes from `PATH`** — craftar looks for it itself, in the absolute entries of `PATH` only (on Windows, a `dotnet.exe` or `dotnet.com` in an entry with a drive or a UNC host), and never in the workspace root unless `PATH` names it: a `dotnet` committed in a repository is not run by `install` or by `doctor`'s probe, which both run there. An empty or relative entry, an unset `PATH` and a `.cmd` / `.bat` shim are not used, and neither is a `node_modules/.bin` of the directory craftar is started in or of a directory above it — the entries `npx` and `npm` put first. The same lookup finds `git` and `docker`.
+- **`dotnet` comes from `PATH`** — craftar looks for it itself, in the absolute entries of `PATH` only (on Windows, a `dotnet.exe` or `dotnet.com` in an entry with a drive or a UNC host), and never in the workspace root unless `PATH` names it: a `dotnet` committed in a repository is not run by `install` or by `doctor`'s probe (the command's, or that of the `doctor` tool of `craftar mcp`), all of which run there. An empty or relative entry, an unset `PATH` and a `.cmd` / `.bat` shim are not used, and neither is a `node_modules/.bin` of the directory craftar is started in or of a directory above it — the entries `npx` and `npm` put first. The same lookup finds `git` and `docker`.
 - **Unknown kind** — an entry of a kind this craftar cannot install (`npm-create`, `nx`) is listed, skipped and warned; `install` then exits 1 (`--dry-run` still exits 0).
 
+## Craftar inside the AI coder
+
+An AI coder working in a generated workspace does not know the files are generated. `craftar mcp` tells it: registered as an MCP server, it lets the agent ask what is pending, why a file exists and what the Forge offers — and say "run `craftar sync`" instead of editing a generated file.
+
+Register it by hand, in the AI coder's own MCP configuration — a file `sync` does not write (the user's own, not a generated `.mcp.json` or `.kiro/settings/mcp.json`):
+
+```json
+{ "mcpServers": { "craftar": { "command": "craftar", "args": ["mcp"] } } }
+```
+
+or for a whole team, as an ordinary `mcp` ingredient in the Forge, which `sync` writes to `.mcp.json` and `.kiro/settings/mcp.json` like any other server:
+
+```yaml
+# ingredients/mcp/craftar/ingredient.yaml
+type: mcp
+name: craftar
+server:
+  command: craftar
+  args: [mcp]
+```
+
+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`.
+
+**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. Next: cloning a profile's repositories at init.
+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). Next: cloning a profile's repositories at init.
 
 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`; `craftar ui`; `craftar mcp` + 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`; `craftar ui`; writing tools for `craftar mcp` (`sync`, `add recipe`) and its Claude Code / Agent Plugin packaging.
 
 ## Upgrading
 
+### to 0.29.0
+
+- **New command: `craftar mcp`**, a read-only MCP server over stdin and stdout, started by an AI coder (see *Commands* and *Craftar inside the AI coder*). It writes nothing to a workspace, its lock or `craftar.yaml`, the registry or the Forge — the Forge cache is used as every reader uses it — and there is no `sync` tool.
+- **Nothing that exists changes**: no emitted byte, no lock, no Forge schema; `status`, `diff`, `explain`, `recipes`, `ingredients`, `targets` and `drift show` print what they printed before, with the same `--json` keys and exit codes — their builders moved into the core, and their output is pinned by tests.
+- **New tooling contracts**: the seven tool names and their arguments; the `diff` tool's result (`{files: [{path, state, added, removed, diff, note}], warnings, unsetParams}`); the `explain` tool's (`{path, target, ingredient, origin, via, sections, params, profile, recipes, hash, warnings}`); and the `doctor` tool's, which is `doctor --json` narrowed to the workspace's checks plus `node` and `git`, its summary recounted. The `status`, `recipes`, `ingredients` and `targets` tools answer with the shapes of those commands' `--json`, which now bind the tools too.
+- **Upgrade every machine before adding the server to a shared Forge.** A Forge can register `craftar mcp` as an ordinary `mcp` ingredient, and `sync` on any version that reads the Forge writes it to `.mcp.json` / `.kiro/settings/mcp.json` for the targets a workspace uses (its workspaces see `new` or `update` on those files); an AI coder on a machine with a craftar before `0.29.0` then starts `craftar mcp`, an unknown command, and the server fails to start.
+- **The server runs in its client's environment**: the programs it runs (`git`, and for the `doctor` tool `docker` and `dotnet`) are looked for in the `PATH` the client gives it, by the lookup of *to 0.28.2*, and the `forge`, `ref` and `profile` it was started with stay fixed: after one of them changes, every tool but `targets` answers with an error until it is restarted.
+- **A result can carry what the reading commands print** — the names of the Forge's profiles and of the workspace an ingredient was imported from, absolute paths, and the parameter values a generated file holds (at Forge `schema: 4`, also those rendered into an MCP server; a value that looks like a credential still refuses the plan, and the tool then answers with the plan's line, never the value). Register the server only where that is acceptable.
+
 ### to 0.28.2
 
 - **A program is no longer looked for in a `node_modules/.bin` of the current directory or of a directory above it.** `npx craftar` — and an `npm` script — puts those entries first on `PATH`, as absolute ones, so a `git`, a `dotnet` or a `docker` committed there was the program craftar ran. They are now skipped, in the lookup and in the `PATH` the program gets, so what it starts in turn (`ssh`, a credential helper) is not found there either. The current directory is the one craftar is started in, whatever `--workspace` names. The entries are compared as written — `.`, `..` and repeated separators resolved, no link followed, without case on Windows. A `node_modules/.bin` anywhere else on `PATH` (npx's own cache, a global prefix) is looked in as before.

package/dist/cli.js

@@ -12,18 +12,19 @@ import { classifyForge } from "./core/remote.js";
 import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.js";
 import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState, countStates, 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 { pruneCache } from "./core/cache.js";
 import { resolveHome } from "./core/home-lock.js";
-import { loadWorkspace, plan, readLock, status, apply, unsetDeclared, unsetRefusal, unsetRefused, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
-import { resolve, sectionKey } from "./core/resolve.js";
-import { catalogueContext, listRecipes, listIngredients, checkType } from "./core/catalogue.js";
-import { listTargets } from "./core/capabilities.js";
+import { loadWorkspace, readWorkspaceConfig, plan, readLock, status, apply, unsetDeclared, unsetRefusal, unsetRefused, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_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 { diffIngredients, listVariants, profileOf } from "./core/variants.js";
-import { hashNormalized, toLf, stripBom } from "./core/text.js";
 import { exists, gitDirty, gitIgnored, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
 import { applyBasePromotion, planBasePromotion, proveBasePromotion } from "./core/promote.js";
 import { fingerprintDir } from "./core/fingerprint.js";
@@ -37,7 +38,7 @@ import { localKeys, 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";
-import { recordedServices, pendingLine, upRefusal, composeArgv, downArgv, readPs, dockerVersion, dockerFault, dockerRunner, projectName, statusReport } from "./core/services.js";
+import { recordedServices, pendingLine, upRefusal, composeArgv, downArgv, readPs, dockerVersion, dockerFault, dockerRunner, projectName, statusReport as servicesStatusReport } from "./core/services.js";
 import { errorText } from "./core/schema-fault.js";
 import { declaredTemplates, DOTNET_MISSING, DOTNET_MISSING_FIX, dotnetVersion, feedMessage, installReport, installTemplates, profileLabel, templateRows, unpinnedSources } from "./core/templates.js";
 import { capture, spawnInherited } from "./core/proc.js";
@@ -50,7 +51,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.28.2");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.29.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
@@ -148,9 +149,10 @@ program
     const p = await plan(ws);
     const lock = await readLock(ws.root);
     const st = await status(ws, p, lock);
-    const unset = unsetDeclared(p);
+    const report = statusReport(ws, p, lock, st);
+    const unset = report.unsetParams;
     if (o.json) {
-        console.log(JSON.stringify({ forge: forgeJson(ws, lock), statuses: st.map(({ planned, ...s }) => s), warnings: p.warnings, unsetParams: unset }, null, 2));
+        console.log(JSON.stringify(report, null, 2));
         // exitCode, not process.exit: a piped object is not cut (spec 29 §4.1)
         if (unset.length)
             process.exitCode = 1;
@@ -406,11 +408,9 @@ program
     for (const s of st) {
         if (only && s.path !== only)
             continue;
-        // Spec 19 §3.2: show the six states sync --check refuses (skip unchanged and adopt)
-        if (["unchanged", "adopt"].includes(s.state))
-            continue;
-        shown++;
-        await printFileDiff(ws.root, s);
+        // 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))
+            shown++;
     }
     if (!shown)
         console.log(pc.green("no differences"));
@@ -424,36 +424,31 @@ 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) {
+    // 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
+    if (!row)
+        return false;
     if (s.state === "orphan-drift") {
         // Header and one line, no body: sync keeps this file
         console.log(pc.bold(`--- ${s.path} (disk, orphan-drift)`));
-        console.log(`  ${explainSkip(s)}`);
-        return;
     }
-    const disk = await readText(path.join(root, s.path));
-    if (s.state === "orphan") {
+    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)`));
-        console.log(renderDiff(disk ?? "", "", DIFF_PAINT));
     }
     else {
-        const next = s.planned ? toLf(stripBom(s.planned.content.toString("utf8"))) : "";
         console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
         console.log(pc.bold(`+++ ${s.path} (forge)`));
-        // Spec 27 §4.2, Ruling 4: do not print on-disk content of the example file for drift/collision
-        if (s.path === EXAMPLE_SETTINGS && (s.state === "drift" || s.state === "collision")) {
-            console.log(EXAMPLE_CONTENT_HIDDEN);
-        }
-        else {
-            console.log(renderDiff(disk ?? "", next, DIFF_PAINT));
-        }
     }
+    // Spec 27 §4.2, Ruling 4: a note stands in for the on-disk content of the example file in drift / collision
+    if (row.note !== null)
+        console.log(`  ${row.note}`);
+    else
+        console.log(renderDiff(row.disk ?? "", row.forge ?? "", DIFF_PAINT));
+    return true;
 }
-/** Spec 27 Ruling 4: the on-disk content of the example file is never printed. */
-const EXAMPLE_CONTENT_HIDDEN = "  content not shown: an example file may hold a value typed by hand";
-/** A path as the user may type it, to the spelling `status` prints: forward slashes, no leading `./`. */
-const statusPath = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
 /* ---------------------------------------------------------------- drift */
 const drift = program.command("drift").description("Hand-edited generated files: show them, discard the edit, or promote it to the Forge");
 drift
@@ -521,7 +516,7 @@ drift
         console.log(pc.bold(`+++ ${named.path} (forge: no longer produced — \`craftar drift discard\` removes it)`));
         // Spec 27 Ruling 4: the on-disk content of the example file is never printed.
         if (named.path === EXAMPLE_SETTINGS) {
-            console.log(EXAMPLE_CONTENT_HIDDEN);
+            console.log(`  ${EXAMPLE_CONTENT_HIDDEN}`);
         }
         else {
             console.log(renderDiff((await readText(path.join(ws.root, named.path))) ?? "", "", DIFF_PAINT));
@@ -819,29 +814,26 @@ program
     const ws = await loadWorkspace(o.workspace, load(o, "read"));
     warnStderr(ws.warnings);
     const p = await plan(ws);
-    const f = p.files.find((x) => x.path === file.replace(/\\/g, "/"));
+    const f = explainFile(ws, p, file.replace(/\\/g, "/"));
     if (!f)
-        fail(`${file} is not produced by the Forge for profile ${ws.config.profile}`);
-    const ing = p.resolution.ingredients.find((i) => i.ref === f.ingredient);
+        fail(notProduced(file, ws.config.profile));
     console.log(pc.bold(f.path));
     console.log(`  target      ${f.target}`);
-    console.log(`  ingredient  ${f.ingredient}${ing?.meta.origin ? pc.dim(`  (imported from ${ing.meta.origin.workspace}:${ing.meta.origin.path})`) : ""}`);
-    if (ing)
-        console.log(`  via recipes ${ing.via.join(" → ")}`);
+    console.log(`  ingredient  ${f.ingredient}${f.origin ? pc.dim(`  (imported from ${f.origin.workspace}:${f.origin.path})`) : ""}`);
+    if (f.via)
+        console.log(`  via recipes ${f.via.join(" → ")}`);
     // Spec 11 §4.2 (Ruling 15): which layer filled each section. AGENTS.md (rule/*) is not one ingredient.
-    const sections = p.sections.get(f.ingredient);
-    if (sections?.length) {
+    if (f.sections.length) {
         const layer = (l) => (l === "profile" ? `profile ${p.resolution.profile.name}` : l);
-        console.log(`  sections    ${sections.map((x) => `${x.name} (${layer(x.layer)})`).join(", ")}`);
+        console.log(`  sections    ${f.sections.map((x) => `${x.name} (${layer(x.layer)})`).join(", ")}`);
     }
     // Spec 29 §4.1: which layer filled each parameter the file's ingredient cites — or `unset`.
-    const params = p.params.get(f.ingredient);
-    if (params?.length) {
+    if (f.params.length) {
         const layer = (l) => (typeof l === "string" ? l : "recipe" in l ? `recipe ${l.recipe}` : `profile ${l.profile}`);
-        console.log(`  params      ${params.map((x) => `${x.key} (${layer(x.layer)})`).join(", ")}`);
+        console.log(`  params      ${f.params.map((x) => `${x.key} (${layer(x.layer)})`).join(", ")}`);
     }
-    console.log(`  profile     ${ws.config.profile}  (recipes: ${p.resolution.recipes.join(", ")})`);
-    console.log(`  hash        ${hashNormalized(f.content)}`);
+    console.log(`  profile     ${f.profile}  (recipes: ${f.recipes.join(", ")})`);
+    console.log(`  hash        ${f.hash}`);
 });
 /* ---------------------------------------------------------------- forge ls */
 program
@@ -1029,6 +1021,37 @@ templates
     if (report.exitCode)
         process.exitCode = 1;
 });
+/* ---------------------------------------------------------------- mcp */
+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")
+    .option("--workspace <dir>", "the workspace to serve", ".")
+    .option("--fetch", "let a tool call fetch a remote Forge instead of reading the cached copy", false)
+    .action(async (o) => {
+    // The bound workspace, resolved once: no tool takes a directory (spec 35 §4.1).
+    const root = path.resolve(o.workspace);
+    const refusal = launchRefusal(process.stdin.isTTY === true, await exists(path.join(root, WORKSPACE_FILE)), root);
+    if (refusal !== null)
+        fail(refusal);
+    // The configuration must read at launch — its forge, ref and profile are the pin. The Forge need not load: each call says so.
+    let merged;
+    try {
+        merged = await readWorkspaceConfig(root);
+    }
+    catch (e) {
+        fail(errorText(e));
+    }
+    // From here stdout carries protocol lines only, and stderr nothing (spec 35 §4.1, §7). Stdin ending ends the process, exit 0.
+    await serve(process.stdin, process.stdout, {
+        root,
+        fetch: o.fetch,
+        home: craftarHome(),
+        version: program.version() ?? "unknown",
+        registryOff: registryOff(),
+        env: process.env,
+        pin: pinOf(merged),
+    });
+});
 /* ---------------------------------------------------------------- recipes */
 program
     .command("recipes")
@@ -1059,7 +1082,7 @@ program
     const r = listRecipes(forg, context);
     // Loading the workspace may warn (spec 13 §4.2); those come first, as in `plan()`.
     if (workspace)
-        r.warnings.unshift(...workspace.warnings);
+        withLoadWarnings(r, workspace.warnings);
     if (o.json) {
         return console.log(JSON.stringify(r, null, 2));
     }
@@ -1184,7 +1207,7 @@ program
         fail(e instanceof Error ? e.message : String(e));
     }
     if (workspace)
-        result.warnings.unshift(...workspace.warnings);
+        withLoadWarnings(result, workspace.warnings);
     if (o.json) {
         return console.log(JSON.stringify(result, null, 2));
     }
@@ -1344,36 +1367,32 @@ program
     .option("--workspace <dir>", "workspace whose targets to mark (default: . when it holds a craftar.yaml)")
     .option("--json", "machine-readable output", false)
     .action(async (o) => {
-    let inUse = null;
-    const warnings = [];
     const root = o.workspace ?? ".";
+    let input = null;
     if (!(await exists(path.join(root, WORKSPACE_FILE)))) {
-        // craftar.yaml does not exist
+        // Explicit --workspace without craftar.yaml: exit 1 with the load's own message. No --workspace: unmarked, no warning.
         if (o.workspace !== undefined) {
-            // Explicit --workspace: exit 1 with loadWorkspace's message
             try {
-                await loadWorkspace(root, load({}, "no-fetch"));
+                await readWorkspaceConfig(root);
             }
             catch (e) {
                 fail(e instanceof Error ? e.message : String(e));
             }
         }
-        // No --workspace: just show unmarked, no warning
     }
     else {
-        // craftar.yaml exists, try to load
+        // craftar.yaml exists: a configuration that does not read is a warning, as a Forge that does not load is
         try {
-            const ws = await loadWorkspace(root, load({}, "no-fetch"));
-            inUse = resolve(ws.forge, ws.config).targets;
+            input = { merged: await readWorkspaceConfig(root) };
         }
         catch (e) {
-            // Load or resolve failed — warning, not error
-            warnings.push(`targets in use not shown: ${e instanceof Error ? e.message : String(e)}`);
+            input = { reason: e instanceof Error ? e.message : String(e) };
         }
     }
-    const result = listTargets(inUse);
+    const result = await targetsReport(root, { home: load({}, "no-fetch").home }, input);
+    const warnings = result.warnings;
     if (o.json) {
-        return console.log(JSON.stringify({ ...result, warnings }, null, 2));
+        return console.log(JSON.stringify(result, null, 2));
     }
     // Text mode
     const targetLine = result.targets
@@ -2328,7 +2347,7 @@ services
             else
                 psFault = `docker compose ps failed — ${r.stderr.trim().split("\n")[0] || `exit ${r.code}`}`;
         }
-        const report = statusReport(real, recorded, docker, ps, psFault);
+        const report = servicesStatusReport(real, recorded, docker, ps, psFault);
         if (o.json)
             console.log(JSON.stringify(report, null, 2));
         else {
@@ -2554,19 +2573,6 @@ function forgeLine(ws, lock) {
     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}`;
 }
-/** `status --json`'s `forge` key, for every Forge (spec 13 §4.1). */
-function forgeJson(ws, lock) {
-    const o = ws.origin;
-    return {
-        kind: o.kind,
-        source: o.source,
-        ref: o.ref,
-        defaultBranch: o.defaultBranch,
-        commit: ws.forge.commit,
-        lockCommit: lock?.forge.commit ?? null,
-        fetched: o.fetched,
-    };
-}
 /** 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);
@@ -2612,26 +2618,6 @@ function color(state) {
             return pc.dim;
     }
 }
-function explainSkip(s) {
-    switch (s.state) {
-        case "drift":
-            return "hand-edited since last sync — `craftar drift show <path>`, then `craftar drift discard` or `craftar drift promote`";
-        case "collision":
-            return "exists but was never generated by craftar and differs from the Forge — rename it or import it";
-        case "orphan-drift":
-            return "no longer produced by the Forge but hand-edited — kept; `craftar drift discard <path>` removes it, or delete it yourself";
-        default:
-            return "";
-    }
-}
-async function readText(p) {
-    try {
-        return toLf(stripBom(await fs.readFile(p, "utf8")));
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * The real path of `abs`, resolved through its nearest existing ancestor: `fs.realpath` needs the
  * path to exist, and a plan target usually does not yet — so the part that exists is resolved