craftar 0.35.0 → 0.37.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`; 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.
+> 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; started with `--allow-writes`, it also syncs a workspace or discards one hand-edited file, each confirmed in the page and never with `--overwrite-drift`. `craftar init --clone` and `craftar repos clone` clone a profile's repositories (its `repos` list) into the workspace, and `craftar repos` lists them. `craftar init --new-profile` creates a profile in a Forge directory (one file, not committed) and starts the workspace on it. With `agents-md.primary`, in a Forge that declares `schema: 5`, an always-on rule lives in `AGENTS.md` alone, and the files that cite it follow it (see *Targets*).
 
 ## The idea in one paragraph
 
@@ -90,7 +90,7 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar explain <path>` | Which ingredient, recipe chain, target and origin produced a file and, for an ingredient with sections, which layer filled each one: `sections    flavors (profile globex), extra (default)` (`default`, `profile <p>` or `workspace`). For an ingredient whose files cite parameters, each cited key with the layer that filled it for this ingredient: `params      org (profile globex), port (default), root (unset)` — `default` (the ingredient's own), `recipe <name>`, `profile <p>`, `workspace` (either workspace file) or `unset`. `AGENTS.md` gets neither line: it is not one ingredient. |
 | `craftar ls` | Recipes and ingredients resolved for this workspace. |
 | `craftar workspaces [--fetch] [--json]` | Every workspace a writing `sync` registered on this machine, sorted by path: name, path, profile, stack (`slot=recipe`), targets, the Forge, the last sync, and a status computed now — `up to date`, `outdated` (`new`, `update` or `orphan` pending), `drift` (a `drift`, `orphan-drift` or `collision`), `no lock`, `missing` (directory or `craftar.yaml` gone) or `error` (it no longer loads, plans or reads its lock, or its `sync` would refuse for a declared parameter with no value — the reason is one of the row's warnings: `sync refused: declared parameter(s) with no value: <keys>`), plus `forge moved` when the Forge's commit differs from the lock's. Read without the network: a remote Forge comes from the cache; `--fetch` fetches first. Each row's warnings print after the table, prefixed with its path. Times are UTC. Writes nothing. Exits 0 whenever the table prints. Takes no `--workspace`. `--json` is a contract: `{registry, fetch, workspaces, warnings}`. |
-| `craftar doctor [--workspace <dir>] [--fetch] [--strict] [--json]` | Checks this machine — Node ≥ 22, `git`, `$CRAFTAR_HOME`, the registry (entries whose workspace is gone), the Forge cache (its size, entries nothing names, a fetch that never completed) — and, when run inside one (the current directory, or `--workspace`), this workspace: the configuration and its Forge (cached, fetched or pinned), whether the workspace sits inside its Forge, the plan's warnings, declared parameters with no value, the `${NAME}` variables a written MCP server expects and this environment lacks — `mcp-env` reads `authEnv` next to `${NAME}` (names only, never values), `templates` when the profile declares a `templates` block (an empty `templates:` line declares none), `dotnet` when that block is accepted and declares a `dotnet-new` entry (the .NET SDK answering `dotnet --version` at the workspace root); neither goes above `warn` — `agents-md-size` when the plan writes `AGENTS.md` (`ok` within the budget or with the budget off, `warn` over the default budget, `error` over an explicit one — the cause is reported there, not by the plan's warnings), the lock, `status`, and registration; in a workspace with a service: `docker` — Docker and its Compose plugin, 2.20.0 or later — and `services-env` — the variables a fragment needs. One line per finding — `ok`, `warn` or `error` — each problem with the command that fixes it; each cause is reported once. A declared parameter with no value is an `error` when a file the plan writes cites it (`sync` refuses that workspace) and a `warn` when nothing cites it. It only reports: nothing is written to a workspace, a lock or the registry, and the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Read without the network; `--fetch` fetches a remote Forge first. Exits 1 on an `error`, or on a `warn` under `--strict`; an explicit `--workspace` without `craftar.yaml` exits 1, while the current directory without one runs the machine checks only. `--json` is a contract: `{version, workspace, fetch, strict, checks: [{id, scope, level, message, fix}], summary}`. In a schema 4 Forge `mcp-env` reads the server as rendered, so a `${NAME}` a param brings into `env` is checked. |
+| `craftar doctor [--workspace <dir>] [--fetch] [--strict] [--json]` | Checks this machine — Node ≥ 22, `git`, `$CRAFTAR_HOME`, the registry (entries whose workspace is gone), the Forge cache (its size, entries nothing names, a fetch that never completed) — and, when run inside one (the current directory, or `--workspace`), this workspace: the configuration and its Forge (cached, fetched or pinned), whether the workspace sits inside its Forge, the plan's warnings, declared parameters with no value, the `${NAME}` variables a written MCP server expects and this environment lacks — `mcp-env` reads `authEnv` next to `${NAME}` (names only, never values), `templates` when the profile declares a `templates` block (an empty `templates:` line declares none), `dotnet` when that block is accepted and declares a `dotnet-new` entry (the .NET SDK answering `dotnet --version` at the workspace root); neither goes above `warn` — `agents-md-size` when the plan writes `AGENTS.md` (`ok` within the budget or with the budget off, `warn` over the default budget, `error` over an explicit one — the cause is reported there, not by the plan's warnings), under `agents-md.primary` `agents-md-primary` (a `CLAUDE.md` that keeps Claude Code from reading `AGENTS.md`, at the root or above it; at most `warn`) and `kiro-resources` (a hand-written Kiro agent `resources` entry the plan does not write: `error`, or `warn` when the file is only on disk), the lock, `status`, and registration; in a workspace with a service: `docker` — Docker and its Compose plugin, 2.20.0 or later — and `services-env` — the variables a fragment needs. One line per finding — `ok`, `warn` or `error` — each problem with the command that fixes it; each cause is reported once. A declared parameter with no value is an `error` when a file the plan writes cites it (`sync` refuses that workspace) and a `warn` when nothing cites it. It only reports: nothing is written to a workspace, a lock or the registry, and the Forge cache is used as every reader uses it (`.used` stamps, a rebuilt tree; under `--fetch`, a fetch and the cleanup of trees unused for 14 days). Read without the network; `--fetch` fetches a remote Forge first. Exits 1 on an `error`, or on a `warn` under `--strict`; an explicit `--workspace` without `craftar.yaml` exits 1, while the current directory without one runs the machine checks only. `--json` is a contract: `{version, workspace, fetch, strict, checks: [{id, scope, level, message, fix}], summary}`. In a schema 4 Forge `mcp-env` reads the server as rendered, so a `${NAME}` a param brings into `env` is checked. |
 | `craftar templates list [--json] [--workspace <dir>] [--offline]` | What the profile's `templates` block declares: one line per package — kind, package, version or `latest`, source or `default feeds` — and one per entry this craftar cannot install. Runs no program and does not know what is installed. `--json` is a contract: `{profile, templates: [{entry, kind, package, version, source, installable}], warnings}`. Exits 1 when the block is refused, naming the position and the rule, never a value. |
 | `craftar templates install [--dry-run] [--force] [--interactive] [--workspace <dir>] [--offline]` | Runs `dotnet new install <pkg>[::<version>]... [--add-source <source>]` once per `dotnet-new` entry, in the profile's order, at the workspace root. `--dry-run` prints the exact lines, needs no `dotnet` and exits 0 over an accepted block, even with a skipped entry. A real run exits 1 when the .NET SDK is not available. Both exit 1 when the block is refused or a package ID exists as a file or folder at the workspace root. `--force` and `--interactive` are passed to `dotnet` as typed, never otherwise; `--interactive` also gives `dotnet` the terminal's input. An entry that fails does not stop the others; a real run exits 1 when any failed or was skipped. When an entry declares a `source` and the workspace root has no `NuGet.Config`, a warning line is printed before the runs. Writes nothing in the workspace, the lock or the registry; nothing else (`sync`, `init`, `doctor`) runs it. See *Project templates*. |
 | `craftar mcp [--workspace <dir>] [--fetch] [--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*. |
@@ -98,7 +98,7 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `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. |
+| `craftar ui [--port <n>] [--allow-writes]` | 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 unless `--allow-writes`**: without the flag 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. With `--allow-writes` (typing it is the consent) the page also offers **Sync** for a workspace and **Discard edit** for one hand-edited file (`drift` or `orphan-drift`, from its open diff), each confirmed in the page: a sync that never passes `--overwrite-drift` — every hand edit and collision is skipped and listed — or a `craftar drift discard` of that one path; never for `.claude/settings.craftar.example.json`, never for a workspace whose Forge is remote, and refused when the workspace changed since the page showed it (refresh and confirm again). **Loopback only**: it listens on `127.0.0.1` (no `--host`; `localhost` is refused), answers `GET` only (and, with `--allow-writes`, `POST` to its two writing routes, with an `Origin` of its own address), 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. |
 | `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}`. |
 | `craftar ingredients [--recipe <name>] [--type <type>] [--forge <dir> [--profile <name>] \| --workspace <dir>] [--json]` | Every ingredient of the Forge, grouped by type: output name, targets, the recipes that list it, and whether the context uses it or the workspace disables it; a reference a recipe makes to an ingredient the Forge does not hold is listed under `missing`, never dropped. `--recipe <name>` lists what choosing that recipe brings, with the parents it extends, parents first; two of them on one slot is a warning. `--type` keeps one type. Read-only. `--json` is a contract: `{forge, context, recipe, ingredients, missing, warnings}`. |
 | `craftar targets [--workspace <dir>] [--json]` | The capability matrix (see *Targets*): what each target does with each ingredient type, the paths it writes and what changes. Needs no Forge; inside a workspace it marks the targets in use, and when that workspace does not load or resolve it prints the matrix unmarked with a warning. An explicit `--workspace <dir>` without a `craftar.yaml` exits 1; the current directory without one just prints the matrix unmarked. `--json` is a contract: `{ingredientTypes, targets, warnings}`. |
@@ -346,6 +346,14 @@ steering = `inclusion` frontmatter + `GENERATED` banner + rule body, with `.clau
 
 **agents-md** — one `AGENTS.md` with the always-on rules concatenated and the scoped rules after them — each listed at the file a target of the workspace writes for it (`.claude/rules/<name>.md` when `claude-code` writes it, else `.kiro/steering/<name>.md` when `kiro` does), or, when no target writes it, embedded in full under a `> Scoped rule — <scope>` line, for tools that read the open standard (Codex, Cursor, Warp, Copilot, Kimi…). A `.claude/rules/<x>.md` reference inside a body follows the rule it names: it is kept when `claude-code` writes that rule, becomes `.kiro/steering/<x>.md` when only `kiro` writes that file (from the rule or from a `steering` ingredient of that name), becomes `AGENTS.md (rule: <x>)` when the rule's text is in this file, and otherwise becomes `<x> (rule not in this workspace)` with a warning (an unknown name is left as written when `claude-code` is a target); a reference inside a link's text is resolved the same way, and a link whose target reads "rule not in this workspace" and whose text is exactly its own path becomes `<x> (rule not in this workspace)` (backticks kept); without `claude-code`, the warning also names references to other `.claude/` files, which are left as written. Every other ingredient type aimed at `agents-md` — including through the default `targets: "*"` — has no `AGENTS.md` equivalent: it is skipped with a warning — one line per type, naming every skipped ingredient. The file keeps the line endings and BOM of the one it replaces; a new one is LF without a BOM. **A size budget, `agents-md.maxBytes`** (default 32768 — Codex's `project_doc_max_bytes`; `0` turns it off), set in one of the layers that give params: a recipe's `params` (its `default` counts as set), the profile's `params`, or `overrides.params` in `craftar.yaml` or `craftar.local.yaml`; a value that is not a whole number of bytes is a warning, and the default applies. The size is the planned `AGENTS.md` in bytes; each rule body the file holds — always-on, and a scoped one embedded because no target writes it — is counted as its UTF-8 bytes after reference resolution and the trailing-newline trim. Over the budget every plan warns, naming at most 5 rules by name and bytes, never their content: `AGENTS.md is N bytes, over the default budget of 32768 (agents-md.maxBytes) — largest rules: a (n bytes), b (scoped, n bytes)`, or, when the budget is set, `… over the budget of M set by agents-md.maxBytes; sync --check fails — …`. Only a budget that is set fails anything: `sync --check`, `status` (and `status --json`, whose keys do not change — the reason is that warning) and `diff --exit-code` with no `[path]` exit 1 and print `error: AGENTS.md is N bytes, over the budget of M set by agents-md.maxBytes` with its fix; a writing `sync` still writes — so it never turns a `craftar workspaces` row into `error` (the table lists the warning under the workspace's path), `forge impact` does not show it, and the `next sync:` line does not count it (`add recipe`, `remove recipe` and `init --no-sync` still print the warning beside it). `doctor` reports it once, as `agents-md-size`.
 
+**One home for the always-on rules, `agents-md.primary`** (a Forge at `schema: 5`). With `claude-code`, `kiro` and `agents-md` all targets, an always-on rule with the default `targets` is written three times — `.claude/rules/<x>.md`, `.kiro/steering/<x>.md` and its section of `AGENTS.md` — and Claude Code and Kiro each load two of them. Set the param `agents-md.primary: true` (a recipe default, the profile's `params` or `overrides.params`; a YAML boolean) in a Forge that declares `schema: 5` and a workspace whose targets include `agents-md`, and such a rule is written to `AGENTS.md` alone:
+- **Who follows it:** a rule with `inclusion: always` whose `targets` is the default (`"*"`, written or omitted). A rule with a `targets` list keeps it — list `targets: [claude-code, agents-md]` to keep a rule in `.claude/rules/` too. Scoped rules, `steering` and every other type are untouched. The files the mode stops writing become orphans: `sync` removes them (its line reads `orphan: written to AGENTS.md only (agents-md.primary)`, and `diff`'s header `(forge: written to AGENTS.md only — sync removes it)`), and a hand-edited one is kept as an `orphan-drift` until `drift discard` or a delete.
+- **References follow the rule:** in the `.claude/` files the `claude-code` emitter writes — a scoped rule's body, an agent's and a command's body and its `frontmatterRaw` (else its `description`), a skill's `.md` files — a `.claude/rules/<x>.md` reference is resolved as in `AGENTS.md`: `AGENTS.md (rule: <x>)` for a rule held there (a link loses its fragment), `.kiro/steering/<x>.md` for a rule only `kiro` writes. The `kiro` files reword such a reference to `AGENTS.md (rule: <x>)` too. Scripts, hooks and files copied as bytes are never rewritten: a reference there is warned with its file and line (`claude-code: … left as written in files craftar copies: .claude/scripts/lint.sh:2 (style)`), never with the line.
+- **Kiro `resources`:** a generated list names only the steering files the plan writes, and never `file://AGENTS.md` (a custom agent inherits `AGENTS.md` — measured with kiro-cli 2.29.1). A hand-written `file://` entry with no glob under `.kiro/steering/`, `.claude/rules/` or naming `AGENTS.md` is checked: one the plan does not write and the disk lacks fails `sync --check`, `status` and `diff --exit-code` (a writing `sync` still writes); one only on disk is a warning. Measured with kiro-cli 2.29.1: a missing entry is no error to Kiro, and a `manual` steering file is not loaded through `resources` — neither by the glob `file://.kiro/steering/**/*.md` nor named alone.
+- **`CLAUDE.md`:** Claude Code (2.1.277 or later) reads `AGENTS.md` only when no `CLAUDE.md` — at the root, in `.claude/`, or `CLAUDE.local.md` — is in the way, unless one imports it: a line `@AGENTS.md` (or `@./AGENTS.md`) in the root's `CLAUDE.md`, or `@../AGENTS.md` in `.claude/CLAUDE.md` (an import is relative to the file that holds it — measured with Claude Code 2.1.310). craftar never writes a `CLAUDE.md`; when the root holds one that blocks, every plan warns, naming the file and never a line of it. A Claude Code before 2.1.277 reads only `CLAUDE.md` and `.claude/rules/`, and loses the always-on rules without a word from craftar.
+- `doctor` gains `agents-md-primary` (a blocking `CLAUDE.md` at the root, or one in a directory above the workspace — never above `warn`) and `kiro-resources` (`error` for an unplanned entry, `warn` for one on disk only), both only under the mode. Over the `AGENTS.md` budget, the warning adds `these rules are in no other file`. `drift promote` refuses a file the mode reworded (`drift show`: `reworded by agents-md.primary`), and `import` into a Forge that sets the mode compares each base as the mode writes it.
+- Below `schema: 5` the key is not read (set to `true` it warns, and the mode is off); a value that is not a boolean, or the mode with no `agents-md` target, warns and leaves it off. **A workspace that does not set the key sees no change at all.** The key is reserved: `forge unify` never extracts into it and `import` never infers it.
+
 Conversion of hooks/subagents to other tools is out of scope here: the plan is to delegate that to [rulesync](https://github.com/dyoshikawa/rulesync) rather than reimplement it.
 
 ## Design rules learned from the previous generator
@@ -517,7 +525,7 @@ The server answers for the directory it is started in; a client that starts its
 
 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`); writing tools for `craftar mcp` (`--allow-writes`: `sync`, `add_recipe`, `remove_recipe`, behind a consent typed per workspace).
+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); writing actions in `craftar ui` (`--allow-writes`: Sync and Discard edit, confirmed in the page).
 
 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).
 
@@ -525,6 +533,19 @@ Later: rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`;
 
 ## Upgrading
 
+### to 0.37.0
+
+- **New flag: `craftar ui --allow-writes`** (see *Commands*). Without it, `craftar ui` is the read-only dashboard — the page, its script and stylesheet and the three terminal lines byte for byte, and every answer too except one: `GET /api/workspaces` gains the key `writes` (`false`). With it the terminal's first line reads `writes allowed` in place of `read-only`, a second line names the two actions, and the page offers Sync and Discard edit for a workspace with a path Forge.
+- **The `ui` command's `--help` description now reads `Reads only unless --allow-writes`.**
+- No emitted byte, lock, registry entry, `--json` shape or exit code of an existing command changes.
+
+### to 0.36.0
+
+- **A Forge can declare `schema: 5`**, which includes 4, 3 and 2. Every craftar before `0.36.0` refuses such a Forge at `craftar.forge.yaml`, so no older craftar writes the three copies of a rule the mode keeps in `AGENTS.md` alone. Upgrade every machine and CI that reads the Forge before setting it. Nothing changes for a Forge at 1 to 4.
+- **`agents-md.primary` is opt-in.** A workspace that does not set it sees no change: no byte, no lock entry, no warning, no exit code, `doctor --strict` included. Turning it on changes bytes by design: the `.claude/rules/` and `.kiro/steering/` files of the always-on rules with default targets become orphans that `sync` removes; the `.claude/`, `.kiro/` and `AGENTS.md` texts citing them are reworded; generated Kiro `resources` name only the steering files the plan writes.
+- **`doctor --json` gains the check ids `agents-md-primary` and `kiro-resources`** (additive, present only under the mode). `drift show --json` can give the reason `reworded by agents-md.primary`. The `sync` tool of `craftar mcp` can give the `removed` reason `orphan: written to AGENTS.md only (agents-md.primary)`, the words `craftar sync` prints.
+- **The key `agents-md.primary` is reserved** at every schema: `forge unify` never extracts a profile value into it and `import` never infers it.
+
 ### to 0.35.0
 
 - **New flag: `craftar mcp --allow-writes`**, and two commands, `craftar mcp allow-writes` and `craftar mcp revoke-writes` (see *Commands* and *Craftar inside the AI coder*). Without the flag, `craftar mcp` answers byte for byte as before — `initialize`, `tools/list` and every tool. Its `--help` description now reads `Reads only unless --allow-writes`.

package/dist/cli.js

@@ -17,14 +17,14 @@ 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, unsetDeclared, unsetRefusal, agentsMdOverBudget, agentsMdRefusal, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
+import { loadWorkspace, loadForgeSource, readWorkspaceConfig, plan, readLock, status, unsetDeclared, unsetRefusal, agentsMdOverBudget, agentsMdRefusal, kiroResourcesUnplanned, kiroResourcesRefusal, orphanReason, primaryOrphan, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
 import { sectionKey } from "./core/resolve.js";
 import { catalogueContext, listRecipes, listIngredients, checkType, withLoadWarnings } from "./core/catalogue.js";
 import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { preferredLine, renderImportReport } from "./core/import-report.js";
 import { driftList, unmanaged } from "./core/drift.js";
-import { EXAMPLE_CONTENT_HIDDEN, diffReport, explainFile, explainSkip, forgeLine, nextSyncLine, notProduced, readText, statusPath, statusReport, targetsReport } from "./core/report.js";
+import { diffReport, explainFile, explainSkip, forgeLine, nextSyncLine, notProduced, orphanDriftBody, 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";
@@ -40,10 +40,9 @@ import { findGit, cloneRepos, listRepos, planClone } from "./core/clone.js";
 import { byHand, profileRepos } from "./core/repos.js";
 import { readlineIo } from "./prompt.js";
 import { recipeDiffLine } from "./core/recipe-edit.js";
-import { syncWorkspace, editRecipes, confirmWrites } from "./core/write-actions.js";
+import { syncWorkspace, editRecipes, confirmWrites, DISCARDED_ORPHAN } 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";
 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";
@@ -59,7 +58,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.35.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.37.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
@@ -165,7 +164,7 @@ program
         console.log(JSON.stringify(report, null, 2));
         // exitCode, not process.exit: a piped object is not cut (spec 29 §4.1)
         // The object carries both reasons (unsetParams, the budget line in warnings): nothing on stderr
-        if (unset.length || agentsMdOverBudget(p))
+        if (unset.length || agentsMdOverBudget(p) || kiroResourcesUnplanned(p)?.length)
             process.exitCode = 1;
         return;
     }
@@ -192,7 +191,10 @@ function budgetRefusalBlock(p) {
     const over = agentsMdOverBudget(p);
     if (over)
         errorLine(agentsMdRefusal(over));
-    return over !== null;
+    const kiroUnplanned = kiroResourcesUnplanned(p);
+    if (kiroUnplanned)
+        errorLine(kiroResourcesRefusal(kiroUnplanned));
+    return over !== null || kiroUnplanned !== null;
 }
 /**
  * A writing sync on a planned workspace, then its report: `apply`, the registration of spec 21 (unless
@@ -208,7 +210,7 @@ async function applyAndReport(ws, p, st, lock, opts = {}) {
     for (const f of o.result.written)
         console.log(`  ${pc.green("+")} ${f}`);
     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"})`);
+        console.log(`  ${pc.magenta("-")} ${f}  (${opts.overwritePaths?.has(f) ? DISCARDED_ORPHAN : orphanReason(p, st, f)})`);
     for (const s of o.result.skipped)
         console.log(`  ${pc.yellow("!")} ${s.path}  ${explainSkip(s)}`);
     for (const w of p.warnings)
@@ -782,7 +784,8 @@ program
         if (only && s.path !== only)
             continue;
         // Spec 19 §3.2: the six states sync --check refuses are shown; which those are is diffReport's to say
-        if (await printFileDiff(ws.root, s))
+        const isPrimary = primaryOrphan(p, s);
+        if (await printFileDiff(ws.root, s, { isPrimary }))
             shown++;
     }
     if (!shown)
@@ -799,7 +802,7 @@ program
 });
 const DIFF_PAINT = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
 /** What `craftar diff` prints for one file `sync --check` refuses; `drift show <path>` prints the same for a drifted one. */
-async function printFileDiff(root, s) {
+async function printFileDiff(root, s, opts = {}) {
     // What to show is decided in the core (`diffReport`); the headers and the paint are this command's.
     const [row] = await diffReport({ root }, [s], { withholdMcp: false });
     // Nothing to show for `unchanged` and `adopt`: says so, for the caller's count
@@ -812,7 +815,8 @@ async function printFileDiff(root, s) {
     else if (s.state === "orphan") {
         // A removal: the file exists on disk but the Forge no longer produces it
         console.log(pc.bold(`--- ${s.path} (disk, orphan)`));
-        console.log(pc.bold(`+++ ${s.path} (forge: no longer produced — sync removes it)`));
+        const orphanReason = opts.isPrimary ? "written to AGENTS.md only — sync removes it" : "no longer produced — sync removes it";
+        console.log(pc.bold(`+++ ${s.path} (forge: ${orphanReason})`));
     }
     else {
         console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
@@ -854,7 +858,7 @@ drift
         // Below schema 3, providedRefs returns early (line "if (!eff.selected.length) return new Map()") before resolve(), so it cannot throw.
         providedWarnings.push(`profile ${ws.config.profile} does not resolve on its own (${e.message}) — what its integrations provide was not computed, and craftar drift promote will refuse`);
     }
-    const rows = driftList(named ? [named] : st, provided);
+    const rows = driftList(named ? [named] : st, provided, new Set(p.reworded));
     // Spec 30r5: drift show decides a refused sync as status does — unsetParams in --json, the refusal block on stderr, exit 1.
     const unset = unsetDeclared(p);
     if (o.json) {
@@ -890,12 +894,12 @@ drift
         // The whole file as a removal: what `drift discard` would do to it.
         console.log(pc.bold(`--- ${named.path} (disk, orphan-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}`);
+        const { body, note } = await orphanDriftBody(ws.root, named);
+        if (note) {
+            console.log(`  ${note}`);
         }
         else {
-            console.log(renderDiff((await readText(path.join(ws.root, named.path))) ?? "", "", DIFF_PAINT));
+            console.log(renderDiff(body ?? "", "", DIFF_PAINT));
         }
     }
     else
@@ -1247,8 +1251,9 @@ workspaces
 /* ---------------------------------------------------------------- ui */
 program
     .command("ui")
-    .description("A local dashboard: 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 — in a browser, on 127.0.0.1 only, behind an address that works for this run. Reads only — writes no workspace, lock, registry or Forge — and reaches no network; Ctrl-C stops it")
+    .description("A local dashboard: 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 — in a browser, on 127.0.0.1 only, behind an address that works for this run. Reads only unless --allow-writes — then a sync or the discard of one hand-edited file, confirmed in the page, never --overwrite-drift — and reaches no network; Ctrl-C stops it")
     .option("--port <n>", "the port to listen on, 0 to 65535; 0 takes a free one", "4747")
+    .option("--allow-writes", "serve Sync and Discard edit on the page — a sync of one workspace, or the discard of one hand-edited file, each confirmed in the page; workspaces with a path Forge only")
     .action(async (o) => {
     // Every refusal comes before the bind (spec 36 §4.2).
     const port = parsePort(o.port);
@@ -1263,10 +1268,11 @@ program
         fail(errorText(e));
     }
     const version = program.version() ?? "unknown";
+    const allowWrites = o.allowWrites === true;
     let ui;
     try {
         // The one line a failing request leaves in the terminal; nothing is printed per request otherwise.
-        ui = await startUi({ home: craftarHome(), version, port, onError: (line) => console.error(line) });
+        ui = await startUi({ home: craftarHome(), version, port, allowWrites, onError: (line) => console.error(line) });
     }
     catch (e) {
         // The code only, never the message.
@@ -1275,7 +1281,13 @@ program
             fail(`port ${port} is in use on 127.0.0.1 — pass --port <other>, or --port 0 for a free one`);
         fail(`cannot listen on 127.0.0.1:${port}: ${code ?? "unknown"}`);
     }
-    console.log(pc.bold(`craftar ui — craftar ${version} · read-only · ${reg.workspaces.length} registered`));
+    if (allowWrites) {
+        console.log(pc.bold(`craftar ui — craftar ${version} · writes allowed · ${reg.workspaces.length} registered`));
+        console.log("  writes allowed: sync, discard one hand-edited file");
+    }
+    else {
+        console.log(pc.bold(`craftar ui — craftar ${version} · read-only · ${reg.workspaces.length} registered`));
+    }
     console.log(`  open  ${ui.url}`);
     console.log("  the address works for this run only, on this machine — Ctrl-C stops it");
     // The first signal closes the listener and lets the process end; a second one, while closing, ends it at once.