craftar 0.9.0 → 0.11.0

package/README.md

@@ -2,7 +2,7 @@
 
 Craft, sync and convert AI-coding workspace harnesses — rules, agents, commands, skills, MCP servers — across every client workspace you maintain and every AI coder each team uses.
 
-> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too. Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
+> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
 
 ## The idea in one paragraph
 
@@ -52,10 +52,10 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 
 | Command | What it does |
 |---|---|
-| `craftar import --from claude-code --forge <dir> --profile <name> [--workspace .] [--write-config]` | Reads `.claude/{rules,agents,commands,skills,scripts,hooks}`, `.mcp.json` and, when present, `.kiro/steering` (for inclusion modes and hand-written steering). Creates ingredients, recipes (`base`, one `stack-*` per scoped rule, `<profile>-steering`) and a profile, or updates them. An ingredient already in the Forge is reused when the base, **rendered** for this profile (its declared defaults, the profile's `params`, the workspace's `overrides.params`), equals the workspace file; failing that, when a unique, proved assignment of the base's declared `{{keys}}` reproduces it, the values are **inferred** into the profile's `params` (one value per key per run; never a change another ingredient would feel). A base with section markers is rendered with the profile's `sections` and the workspace's `overrides.sections` first; when the workspace file differs from it only inside sections, the unique content that reproduces the file byte for byte is **inferred** into the profile's `sections` (tried after params, never combined with them; the report counts lines and never prints the content). An import that writes a section value, or compares a workspace file against a base holding markers, sets `schema: 2` in `craftar.forge.yaml`. A reused base takes the place its `<name>--<profile>` variant held: the profile moves to the shared recipe when that orders the base there, and an owned recipe gets the base in the variant's slot, so the rule order (and `AGENTS.md`) stays as it was. Anything else becomes a `<name>--<profile>` variant that emits under the original name, with the reason, so the workspace still round-trips while you decide what to unify. A shared recipe is never widened for one client: a profile whose ingredients differ from `base` or a `stack-*` gets its own `<recipe>--<profile>`. An existing profile is merged in place (`params`, `sections`, the recipes import owns, missing `targets`; every other field and comment kept, and an empty `{}` / `[]` it does not change stays on its line), as is a recipe the profile owns; `--write-config` merges an existing `craftar.yaml` (`forge`, `profile`, `targets`). The report adds `rendered` (with `sections <names>` when a section value filled the render), `inferred`, `sectioned`, `param <key>: <old> → <new>`, `section <key> <name>: <old> → <new>`, `forge craftar.forge.yaml edited (schema: 2)` and `profile … created|edited|unchanged` lines. It refuses, with the Forge untouched, a Forge that does not load, a profile or recipe or `craftar.yaml` that does not round-trip through the YAML writer, a misplaced profile, a recipe import writes whose file and `name` disagree, a workspace override that does not parse, a literal `{{key}}` the profile would render, changing a recipe or variant another profile uses, a workspace file holding a section marker at column 0 (sync would not reproduce it: indent it), a Forge base with malformed section markers, and a `craftar.forge.yaml` it needs to bump to `schema: 2` that does not round-trip (set it by hand). Ingredients holding a secret-like value (tokens, private keys, high-entropy MCP `env`/`args` values) are rejected and listed by location — the value is never printed. A UTF-16 file with a byte-order mark is decoded for the scan; UTF-16 without one is not detected. An ingredient that would not load back into the Forge (a name that is not slug-like, a non-string MCP `env` value) refuses the import, naming its source; so does an ingredient already in the Forge whose `ingredient.yaml` has an unknown key or a YAML syntax error, naming that file. Every read and check runs before the first write, so an import that fails leaves the Forge untouched and says so. |
-| `craftar status` | Classifies every file the Forge would produce: `new`, `update`, `unchanged`, `adopt`, `drift`, `collision`, `orphan`, `orphan-drift`. A `.json` file not yet in `craftar.lock` that parses to the planned value with its keys in the same order (it differs only in whitespace, escapes, number spelling or duplicate keys) is `adopt`, and the first `sync` rewrites it with the planned bytes — by design. For `claude-code`'s `.mcp.json` that is two-space JSON keeping the file's BOM and line endings; Kiro's JSON files become CRLF without a BOM, like every Kiro text file. A different key order is a `collision` — except for integer-like keys, which `JSON.parse` reorders. A locked JSON file reformatted by hand is `drift`, not `adopt`. `--json` for tooling. Exits 1 on malformed section markers and on a section marker in an ingredient the workspace resolves while `craftar.forge.yaml` declares `schema: 1` (or none), naming the Forge file and line, and when a rendered file would still hold a marker line, naming the ingredient, file and rendered line — as do `sync`, `diff`, `explain` and `ls`. Warns about a section value that names no ingredient, or no marker of an ingredient the workspace resolves, and about marker lines in an emitted file not every target renders as text (copied as they are). |
-| `craftar sync` | Renders sections (no rendered body holds a marker; an emitted file not every target renders as text keeps its markers, with a warning), then writes the plan and `craftar.lock`. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default). |
-| `craftar diff [path]` | Line diff between disk and what the Forge would generate. |
+| `craftar import --from claude-code --forge <dir> --profile <name> [--workspace .] [--write-config]` | Reads `.claude/{rules,agents,commands,skills,scripts,hooks}`, `.mcp.json` and, when present, `.kiro/steering` (for inclusion modes and hand-written steering). Creates ingredients, recipes (`base`, one `stack-*` per scoped rule, `<profile>-steering`) and a profile, or updates them. An ingredient already in the Forge is reused when the base, **rendered** for this profile (its declared defaults, the profile's `params`, the workspace's `overrides.params`), equals the workspace file; failing that, when a unique, proved assignment of the base's declared `{{keys}}` reproduces it, the values are **inferred** into the profile's `params` (one value per key per run; never a change another ingredient would feel). A base with section markers is rendered with the profile's `sections` and the workspace's `overrides.sections` first; when the workspace file differs from it only inside sections, the unique content that reproduces the file byte for byte is **inferred** into the profile's `sections` (tried after params, never combined with them; the report counts lines and never prints the content). An import that writes a section value, or compares a workspace file against a base holding markers, sets `schema: 2` in `craftar.forge.yaml`. A reused base takes the place its `<name>--<profile>` variant held: the profile moves to the shared recipe when that orders the base there, and an owned recipe gets the base in the variant's slot, so the rule order (and `AGENTS.md`) stays as it was. Anything else becomes a `<name>--<profile>` variant that emits under the original name, with the reason, so the workspace still round-trips while you decide what to unify. A shared recipe is never widened for one client: a profile whose ingredients differ from `base` or a `stack-*` gets its own `<recipe>--<profile>`. An existing profile is merged in place (`params`, `sections`, the recipes import owns, missing `targets`; every other field and comment kept, and an empty `{}` / `[]` it does not change stays on its line), as is a recipe the profile owns; `--write-config` merges an existing `craftar.yaml` (`forge`, `profile`, `targets`). The report adds `rendered` (with `sections <names>` when a section value filled the render), `inferred`, `sectioned`, `param <key>: <old> → <new>`, `section <key> <name>: <old> → <new>`, `forge craftar.forge.yaml edited (schema: 2)` and `profile … created\|edited\|unchanged` lines. It refuses, with the Forge untouched, a Forge that does not load, a profile or recipe or `craftar.yaml` that does not round-trip through the YAML writer, a misplaced profile, a recipe import writes whose file and `name` disagree, a workspace override that does not parse, a literal `{{key}}` the profile would render, changing a recipe or variant another profile uses, a workspace file holding a section marker at column 0 (sync would not reproduce it: indent it), a Forge base with malformed section markers, and a `craftar.forge.yaml` it needs to bump to `schema: 2` that does not round-trip (set it by hand). Ingredients holding a secret-like value (tokens, private keys, high-entropy MCP `env`/`args` values) are rejected and listed by location — the value is never printed. A UTF-16 file with a byte-order mark is decoded for the scan; UTF-16 without one is not detected. An ingredient that would not load back into the Forge (a name that is not slug-like, a non-string MCP `env` value) refuses the import, naming its source; so does an ingredient already in the Forge whose `ingredient.yaml` has an unknown key or a YAML syntax error, naming that file. Every read and check runs before the first write, so an import that fails leaves the Forge untouched and says so. |
+| `craftar status` | With a remote Forge, the header's second line names it — `forge <url> @ <ref \| <branch> (default branch)> <commit>`, plus `· lock <commit>` when the Forge moved since the last sync — and `--json` carries `forge: {kind, source, ref, defaultBranch, commit, lockCommit, fetched}` for every Forge. Classifies every file the Forge would produce: `new`, `update`, `unchanged`, `adopt`, `drift`, `collision`, `orphan`, `orphan-drift`. A `.json` file not yet in `craftar.lock` that parses to the planned value with its keys in the same order (it differs only in whitespace, escapes, number spelling or duplicate keys) is `adopt`, and the first `sync` rewrites it with the planned bytes — by design. For `claude-code`'s `.mcp.json` that is two-space JSON keeping the file's BOM and line endings; Kiro's JSON files become CRLF without a BOM, like every Kiro text file. A different key order is a `collision` — except for integer-like keys, which `JSON.parse` reorders. A locked JSON file reformatted by hand is `drift`, not `adopt`. `--json` for tooling. Exits 1 on malformed section markers and on a section marker in an ingredient the workspace resolves while `craftar.forge.yaml` declares `schema: 1` (or none), naming the Forge file and line, and when a rendered file would still hold a marker line, naming the ingredient, file and rendered line — as do `sync`, `diff`, `explain` and `ls`. Warns about a section value that names no ingredient, or no marker of an ingredient the workspace resolves, and about marker lines in an emitted file not every target renders as text (copied as they are). |
+| `craftar sync` | Renders sections (no rendered body holds a marker; an emitted file not every target renders as text keeps its markers, with a warning), then writes the plan and `craftar.lock` (schema 2: the Forge's source, requested `ref` and commit, the resolved recipes and targets — rewritten only when that content changes). With a remote Forge it fetches first and exits 1 when the fetch fails, `--dry-run` and `--check` included. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default). |
+| `craftar diff [path] [--exit-code]` | Line diff between disk and what the Forge would generate, for every file `sync --check` refuses: `update`, `drift`, `collision`, `new`, an `orphan` (shown as the removal of the whole file — the next `sync` deletes it) and an `orphan-drift` (a header and one line: `sync` keeps it). `[path]` limits it to the one file whose workspace-relative path, as `status` prints it, equals it. Exits 0 by default, differences or not. `--exit-code` exits 1 when there are differences — exactly when `sync --check` would — and makes a `[path]` that names no file craftar manages an error (exit 1, nothing on stdout); without the flag such a path prints `no differences`. With a remote Forge, `--exit-code` also exits 1 when the fetch fails, as `sync --check` does; plain `diff` reads the cached copy with a warning. |
 | `craftar explain <path>` | Which ingredient, recipe chain, target and origin produced a file and, for an ingredient with sections, which layer filled each one: `sections    flavors (profile globex), extra (default)` (`default`, `profile <p>` or `workspace`). `AGENTS.md` gets no sections line: it is not one ingredient. |
 | `craftar ls` | Recipes and ingredients resolved for this workspace. |
 | `craftar recipes [--forge <dir> [--profile <name>] \| --workspace <dir>] [--json]` | Every recipe of the Forge, sorted by name: slot, the parents it extends, the ingredients it lists itself and the profiles that reach it. In a workspace (or with `--forge <dir> --profile <name>`) each recipe says whether it is in use and why — `profile`, `workspace` (`recipes.add`), `extends <child>` — and a recipe `recipes.remove` names reads `removed by this workspace`. A context that does not resolve (two recipes on one slot, an unknown recipe, a cycle) still lists everything, marks nothing and warns. Read-only: it resolves, never plans. `--json` is a contract: `{forge, context, recipes, warnings}`. |
@@ -65,7 +65,7 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar forge diff <type/name> [--against <profile>] [--forge <dir> \| --workspace <dir>] [--json]` | Shows the differences between a base ingredient and each of its variants: a header carrying the same distance `forge variants` reports, then hunk by hunk, each with a suggested class and reason — `evolution` (one side is newer text), `value` (an identifier-like token swapped in shared prose, with a suggested `param.<slug>`) or `block` (lines only one side has) — then the files that exist on only one side. A suggestion never decides anything. It compares the raw Forge text, section marker lines included, so a base with markers shows them as hunks against a variant that has none. Read-only. `--json` prints an array of `{ref, profile, distance, diff}`; each hunk carries `suggestion: {class, reason, tokens?}` next to its `kind`. |
 | `craftar forge unify <type/name> --profile <p> (--take base\|variant \| --plan <file> \| --save-plan <file>) [--forge <dir> \| --workspace <dir>] [--json]` | Resolves one variant back into its base, hunk by hunk. `--save-plan` writes a reviewable plan with every decision set to `keep`, each hunk annotated with its suggested class (which `--plan` ignores) and, for a `value` hunk, a pre-filled `params` list (`token` → suggested `key`); on a `block` hunk, a pre-filled `section: { name }` from the Markdown heading above (or `section-<n>`); and on a hunk touching a section the base already has, that section's name. It refuses a path that resolves inside the Forge (after `..` segments and symlinks) and a path that already exists, so it never overwrites a Forge file or a plan you already edited; it writes nothing else. A hunk set to `take: param` turns each listed token into `{{key}}` in the base, declares the base's text as the key's default in the base's `ingredient.yaml` and writes the variant's text into the variant profile's `profile.yaml` `params` — only after proving that both the base's and the variant's text render back exactly, and only when the same plan resolves the variant; it refuses (with the Forge untouched) a key another layer, profile or ingredient already uses, a variant another profile also uses, a whitespace-only difference, and a YAML file that would not round-trip unchanged. A hunk set to `take: section` (with `section: { name, lines? }`) wraps the base's lines in section markers as the default and writes the variant's lines into the variant profile's `sections` — consecutive hunks with one name form one section, `lines: "<from>-<to>"` widens it over equal base lines, and hunks inside a section the base already has only write the profile value; it is proved (both sides render back exactly) and needs the same plan to resolve the variant; `take: param` and `take: section` may share a plan, never a hunk. It refuses (Forge untouched) a `take: param` or `take: section` on a file no target emits, a variant that holds markers, a profile that already sets that section (another profile for a new section, or the variant's profile with other content), a span that cuts a hunk or crosses another section, a span that covers a hunk outside the run (including `take: base` on a hunk inside a section the plan fills), a hunk mixing lines inside and outside an existing section, and a span reaching a missing final newline; when it adds a section to a Forge still at `schema: 1` it sets `schema: 2` in `craftar.forge.yaml` in place (refused if the file does not round-trip). `--plan` applies an edited plan, refusing when it is not for this exact ingredient/profile or either side's fingerprint moved since it was saved. `--take base\|variant` resolves every decision to that side. Writes the merged base and, once every difference is resolved, removes the variant and rewrites every recipe reference to it (`ingredients`) to name the base. It never deletes a recipe and never edits an `extends`; it edits a profile only to write the values of a `take: param` or `take: section` extraction into the variant's own profile, and otherwise never: a `<recipe>--<profile>` left identical to `<recipe>` is reported as a warning, to be removed by hand after repointing the lists that name it — unify does not, because a workspace or an `extends` chain may also name `<recipe>` and the recipe order or param precedence would change. Unify cannot reach workspaces, so a removed variant is reported as a warning for any `craftar.yaml` that disables it in `overrides.ingredients.disable`. Every recipe rewrite is checked before the first write, so one that cannot land (a reference behind a YAML alias) is refused with the Forge untouched; a failure after writing began (an I/O error, a locked file) names the paths already touched and the `git checkout` / `git clean` commands that undo them. A merge never adds, removes or changes a section marker other than the sections the plan declares; a plan or `--take variant` that would is refused before the first write — take `base` for the marker lines, or `take: section` to fill the section; the citation checks of `take: param` also read the profiles' section values, which can cite `{{key}}`. `ingredient.yaml` is never merged: when the two sides' metadata differs (beyond `name`, `as` and `origin`), the variant stays unresolved and the differing fields are named — edit it by hand, or `--take base` to discard the variant, metadata included. Requires a clean git checkout in the Forge with at least one commit (`--save-plan` excepted) — the Forge has no lock, so git is the undo. It also refuses when any path it would overwrite or delete (the base, the variant, the recipe files it rewrites, the profile a parameter or section extraction edits, `craftar.forge.yaml` when it is bumped) is ignored, untracked, modified, or flagged skip-worktree or assume-unchanged in the index, since git could not restore it. `--json` prints `{base, profile, resolved, written, removed, unresolved, variantRemoved, recipes: {rewritten, identicalToSibling}, metaDiffers, params, profileEdited, sections, manifestEdited, warnings}` for `--take`/`--plan` (every key always present, `[]` when empty), or `{base, profile, plan, unresolved}` for `--save-plan`. |
 
-All commands take `--workspace <dir>` (default: current directory); the `forge` commands, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it, and `targets` needs no Forge.
+All commands take `--workspace <dir>` (default: current directory); the `forge` commands, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it — a directory: a URL there is refused — and `targets` needs no Forge. With a remote Forge (see *Remote Forge*), `status`, `sync`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `forge variants` and `forge diff` fetch first and take `--offline` to use the cached copy; `targets` never fetches; `forge unify` refuses a workspace whose Forge is remote — clone it and pass `--forge <dir>`; `import --write-config` keeps a remote `forge:` and sets only `profile` and `targets`.
 
 ## Forge layout
 
@@ -171,7 +171,8 @@ params: { angularVersion: { default: "20" } }
 Workspace `craftar.yaml`:
 
 ```yaml
-forge: ../forge                      # path today; git URL later
+forge: ../forge                      # a path, or a git URL (see Remote Forge)
+ref: v1.4.0                          # optional, with a git URL: a branch, a tag or a full SHA
 profile: acme-portal
 targets: [claude-code, kiro]         # optional, overrides the profile
 recipes: { add: [], remove: [] }
@@ -250,13 +251,37 @@ npm test
 
 Copy a workspace with `.claude/` and `.kiro/` into `fixtures/` (keep `local-stack/` and `projects/` out).
 
+## Remote Forge
+
+`forge:` may be a git URL — `https://…`, `ssh://…`, `file://…`, or the SCP-like `git@host:org/forge.git` (any SSH user) — with an optional `ref`: a branch (followed: its tip at each fetch), a tag or a full 40-hex SHA (fixed); `refs/heads/<x>` / `refs/tags/<x>` when a name is both; no `ref` follows the remote's default branch. Abbreviated SHAs are refused. A `ref` next to a path `forge:` is ignored, with a warning.
+
+- **The cache.** Each machine keeps one copy per URL in `$CRAFTAR_HOME/forges/` (`~/.craftar` by default): a bare repository and one tree per resolved commit, never written by Craftar, shared by every workspace on the machine. Each tree holds the commit's bytes on every platform: the host's `core.autocrlf`, `core.eol` and global attributes file do not apply to it; the Forge's own `.gitattributes` does. Trees unused for 14 days are removed after a fetch. It is the one place Craftar writes outside a workspace and a Forge on its own.
+- **The network.** `sync` (with `--check` and `--dry-run`) and `diff --exit-code` fetch first and exit 1 when they cannot; `status`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `forge variants` and `forge diff` fall back to the cached copy with a warning; `--offline` uses the cached copy on purpose; with no cached copy every one of them exits 1. `targets` never fetches: it reads the cached copy, and without one prints the matrix unmarked, with a warning. A full SHA already cached is not fetched again.
+- **Authentication belongs to git** (credential helper, SSH agent). A URL holding credentials (`https://user:token@…`, a password in any scheme) is refused in `craftar.yaml` and `craftar.local.yaml`, naming the file and never the value. In CI, configure git (e.g. a credential helper or an SSH deploy key), never a token in `forge:`; without a terminal, git does not prompt.
+- **Writing into the Forge** stays local: `import` and `forge unify` need a clone passed as `--forge <dir>`; Craftar never pushes. After importing into the clone, push it for `sync` to see the import.
+- **`craftar.local.yaml`** may override `forge:` (a local clone while you work on the Forge); every planning command then warns not to commit `craftar.lock` or the generated files.
+
 ## Roadmap (from the functional spec)
 
-Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix).
-Next: `craftar init` from a profile; profile-driven integrations (PM tool → MCP, IDP → MCP); `service` ingredients with compose fragments (`craftar services up`); `dotnet new` template registration; rulesync bridge for Codex/Kimi/Cursor specifics; remote Forge (git URL + ref); `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
+Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock).
+Next: `craftar init` from a profile; profile-driven integrations (PM tool → MCP, IDP → MCP); `service` ingredients with compose fragments (`craftar services up`); `dotnet new` template registration; rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
 
 ## Upgrading
 
+### to 0.11.0
+
+- **`craftar.lock` is schema 2**, written by the next `sync` of every workspace, path Forge or remote: it adds `forge.ref`, `recipes` and `targets`. **Once a schema 2 lock is committed, every craftar up to 0.10.1 stops on it** (a zod error on `schema`) until upgraded — upgrade the whole team, and CI, before committing it. This craftar reads schema 1 and 2, and refuses a later one by name.
+- **The lock is rewritten only when its content changes** (`generatedAt` is when it last did): a `sync` that changes nothing no longer touches it. The first `sync` after upgrading rewrites it once.
+- **A `user@host:path` value of `forge:` is a URL** now (any SSH user, not only `git@`); before, it was read as a relative path.
+- A `forge:` value holding credentials is refused; a `ref` next to a path `forge:` is ignored with a warning; `forge:` from `craftar.local.yaml` adds a do-not-commit warning.
+- `status --json` gains a `forge` key (additive). `diff`, `explain`, `ls`, `forge variants` and `forge diff` print warnings about loading the workspace on stderr. A missing path Forge reads `Forge not found at <path>`.
+
+### to 0.10.0
+
+- **`craftar diff` shows orphans.** A file the Forge no longer produces is printed as the removal of the whole file (`+++ <path> (forge: no longer produced — sync removes it)`), and a hand-edited one as a header and one line, since `sync` keeps it. Output changes only in a workspace that has an `orphan` or an `orphan-drift` — one whose only pending change was an orphan used to print `no differences`; elsewhere it is byte for byte 0.9.0's.
+- **`craftar diff --exit-code`** exits 1 when there are differences — exactly when `sync --check` would — and refuses a `[path]` that names no file craftar manages. Without the flag `diff` still exits 0.
+- **No byte change**: no emitter, `plan`, `status` or `sync` changed. No workspace sees `update`.
+
 ### to 0.9.0
 
 - **Three new read-only commands**: `craftar recipes`, `craftar ingredients` and `craftar targets`. They write nothing — no generated file, no lock, no Forge file.

package/dist/cli.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
+import { classifyForge } from "./core/remote.js";
 import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE } from "./core/sync.js";
 import { resolve, sectionKey } from "./core/resolve.js";
 import { catalogueContext, listRecipes, listIngredients, checkType } from "./core/catalogue.js";
@@ -19,8 +20,14 @@ import { checkParamWrites, writeParamFile } from "./core/param-writes.js";
 import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 process.stdout.on("error", (e) => { if (e.code === "EPIPE")
     process.exit(0); });
+/**
+ * Q13-1, answered by the user (2026-10-07): with a remote Forge whose fetch fails, `diff --exit-code`
+ * fails like `sync --check` — a CI gate does not pass against a stale cached copy. Plain `diff` still
+ * reads the cached copy with a warning (spec 13 §4.1).
+ */
+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.9.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.11.0");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -33,6 +40,9 @@ program
     .action(async (o) => {
     if (o.from !== "claude-code")
         fail(`unsupported source "${o.from}" (only claude-code for now)`);
+    // import writes a local Forge; a URL would become a directory named after it (spec 13 §4.4).
+    if (classifyForge(o.forge) === "url")
+        fail("--forge takes a directory; to read a remote Forge, run inside a workspace that names it");
     const r = await importClaudeCode({ workspaceRoot: o.workspace, forgeRoot: o.forge, profileName: o.profile, writeWorkspaceConfig: o.writeConfig });
     console.log(pc.bold(`Imported ${path.resolve(o.workspace)} → ${path.resolve(o.forge)} as profile "${r.profile}"`));
     console.log(`  ${pc.green(String(r.created.length))} created, ${pc.cyan(String(r.reused.length))} reused, ${pc.yellow(String(r.variants.length))} variants, ${pc.red(String(r.rejected.length))} rejected`);
@@ -64,7 +74,9 @@ program
     const split = new Map(r.recipeSplits.map((x) => [x.owned, x.reason]));
     console.log(`  recipes: ${r.recipes.map((n) => (split.has(n) ? `${n} (${split.get(n)})` : n)).join(", ")}`);
     if (r.configWrite === "edited")
-        console.log(`  workspace craftar.yaml edited (forge, profile, targets)`);
+        console.log(r.configForgeKept
+            ? `  workspace craftar.yaml edited (profile, targets) — forge kept (remote ${r.configForgeKept}); push the Forge for sync to see this import`
+            : `  workspace craftar.yaml edited (forge, profile, targets)`);
     for (const w of r.warnings)
         console.log(`  ${pc.yellow("warn")} ${w}`);
 });
@@ -74,13 +86,15 @@ program
     .description("Show what sync would do: new, update, drift, orphan, collision")
     .option("--workspace <dir>", "workspace root", ".")
     .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
-    const ws = await loadWorkspace(o.workspace);
+    const ws = await loadWorkspace(o.workspace, load(o, "read"));
     const p = await plan(ws);
-    const st = await status(ws, p, await readLock(ws.root));
+    const lock = await readLock(ws.root);
+    const st = await status(ws, p, lock);
     if (o.json)
-        return console.log(JSON.stringify({ statuses: st.map(({ planned, ...s }) => s), warnings: p.warnings }, null, 2));
-    printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes);
+        return console.log(JSON.stringify({ forge: forgeJson(ws, lock), statuses: st.map(({ planned, ...s }) => s), warnings: p.warnings }, null, 2));
+    printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, false, forgeLine(ws, lock));
 });
 /* ---------------------------------------------------------------- sync */
 program
@@ -90,13 +104,15 @@ program
     .option("--check", "exit 1 when the workspace is out of date or has drift (CI mode)", false)
     .option("--dry-run", "show the plan, write nothing", false)
     .option("--overwrite-drift", "regenerate files that were hand-edited (their edits are lost)", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
-    const ws = await loadWorkspace(o.workspace);
+    const ws = await loadWorkspace(o.workspace, load(o, "sync"));
     const p = await plan(ws);
-    const st = await status(ws, p, await readLock(ws.root));
+    const lock = await readLock(ws.root);
+    const st = await status(ws, p, lock);
     if (o.check) {
         const bad = st.filter((s) => !["unchanged", "adopt"].includes(s.state));
-        printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, true);
+        printStatus(st, p.warnings, ws.config.profile, p.resolution.recipes, true, forgeLine(ws, lock));
         if (bad.length) {
             console.log(pc.red(`\n${bad.length} file(s) out of sync`));
             process.exit(1);
@@ -107,6 +123,9 @@ program
     const r = await apply(ws, p, st, { dryRun: o.dryRun, overwriteDrift: o.overwriteDrift });
     const verb = o.dryRun ? "would write" : "wrote";
     console.log(pc.bold(`craftar sync — profile ${ws.config.profile} · recipes ${p.resolution.recipes.join(" → ")} · targets ${p.resolution.targets.join(", ")}`));
+    const fl = forgeLine(ws, lock);
+    if (fl)
+        console.log(fl);
     console.log(`  ${verb} ${pc.green(String(r.written.length))}, removed ${pc.magenta(String(r.removed.length))} orphan(s), skipped ${pc.yellow(String(r.skipped.length))}`);
     for (const f of r.written)
         console.log(`  ${pc.green("+")} ${f}`);
@@ -120,28 +139,53 @@ program
 /* ---------------------------------------------------------------- diff */
 program
     .command("diff")
-    .description("Unified diff between the files on disk and what the Forge would generate")
+    .description("Unified diff between the files on disk and what the Forge would generate, orphans included (files the Forge no longer produces)")
     .option("--workspace <dir>", "workspace root", ".")
+    .option("--exit-code", "exit 1 when there are differences (exactly when `sync --check` would fail); a [path] that names no file craftar manages becomes an error; with a remote Forge, a failed fetch exits 1 as `sync --check` does (--offline to use the cached copy)", false)
     .argument("[path]", "limit to one file")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (only, o) => {
-    const ws = await loadWorkspace(o.workspace);
+    const ws = await loadWorkspace(o.workspace, load(o, o.exitCode ? DIFF_EXIT_CODE_FETCH_MODE : "read"));
+    warnStderr(ws.warnings);
     const p = await plan(ws);
     const st = await status(ws, p, await readLock(ws.root));
+    // Spec 19 §3.3: under --exit-code a path nothing matches must not read as "clean" to a script
+    if (o.exitCode && only && !st.some((s) => s.path === only))
+        fail(`${only} is not a file craftar manages in this workspace — pass the workspace-relative path as \`craftar status\` prints it (forward slashes)`);
     let shown = 0;
+    const render = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
     for (const s of st) {
         if (only && s.path !== only)
             continue;
-        if (!["update", "drift", "collision", "new"].includes(s.state))
+        // Spec 19 §3.2: show the six states sync --check refuses (skip unchanged and adopt)
+        if (["unchanged", "adopt"].includes(s.state))
             continue;
         shown++;
+        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)}`);
+            continue;
+        }
         const disk = await readText(path.join(ws.root, s.path));
-        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)`));
-        console.log(renderDiff(disk ?? "", next, { paint: { same: pc.dim, del: pc.red, add: pc.green } }));
+        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 ?? "", "", render));
+        }
+        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)`));
+            console.log(renderDiff(disk ?? "", next, render));
+        }
     }
     if (!shown)
         console.log(pc.green("no differences"));
+    // exitCode, not process.exit: exit drops a piped diff still queued for a slow reader (spec 19 §3.1)
+    else if (o.exitCode)
+        process.exitCode = 1;
 });
 /* ---------------------------------------------------------------- explain */
 program
@@ -149,8 +193,10 @@ program
     .description("Why does this file exist? Which ingredient, recipe chain and target produced it, and which layer filled each section")
     .argument("<path>", "workspace-relative path of a generated file")
     .option("--workspace <dir>", "workspace root", ".")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (file, o) => {
-    const ws = await loadWorkspace(o.workspace);
+    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, "/"));
     if (!f)
@@ -175,10 +221,15 @@ program
     .command("ls")
     .description("List recipes and ingredients resolved for this workspace")
     .option("--workspace <dir>", "workspace root", ".")
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
-    const ws = await loadWorkspace(o.workspace);
+    const ws = await loadWorkspace(o.workspace, load(o, "read"));
+    warnStderr(ws.warnings);
     const p = await plan(ws);
     console.log(pc.bold(`Forge ${ws.forge.manifest.name} @ ${ws.forge.commit?.slice(0, 8) ?? "no git"} · profile ${ws.config.profile}`));
+    const fl = forgeLine(ws, await readLock(ws.root));
+    if (fl)
+        console.log(fl);
     for (const r of p.resolution.recipes) {
         const rec = ws.forge.recipes.get(r);
         console.log(`\n${pc.cyan(r)}${rec.slot ? pc.dim(` [slot ${rec.slot}]`) : ""}${rec.description ? pc.dim(" — " + rec.description) : ""}`);
@@ -197,10 +248,11 @@ program
     .option("--profile <name>", "with --forge: mark what this profile resolves")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
     if (o.profile && !o.forge)
         fail("--profile goes with --forge — inside a workspace the profile comes from craftar.yaml");
-    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace });
+    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace, ...load(o, "read") });
     const source = workspace
         ? { kind: "workspace", config: workspace.config }
         : o.profile
@@ -216,6 +268,9 @@ 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);
     if (o.json) {
         return console.log(JSON.stringify(r, null, 2));
     }
@@ -305,6 +360,7 @@ program
     .option("--profile <name>", "with --forge: mark what this profile resolves")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
     if (o.profile && !o.forge)
         fail("--profile goes with --forge — inside a workspace the profile comes from craftar.yaml");
@@ -316,7 +372,7 @@ program
             fail(e instanceof Error ? e.message : String(e));
         }
     }
-    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace });
+    const { forge: forg, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace, ...load(o, "read") });
     const source = workspace
         ? { kind: "workspace", config: workspace.config }
         : o.profile
@@ -338,6 +394,8 @@ program
     catch (e) {
         fail(e instanceof Error ? e.message : String(e));
     }
+    if (workspace)
+        result.warnings.unshift(...workspace.warnings);
     if (o.json) {
         return console.log(JSON.stringify(result, null, 2));
     }
@@ -505,7 +563,7 @@ program
         if (o.workspace !== undefined) {
             // Explicit --workspace: exit 1 with loadWorkspace's message
             try {
-                await loadWorkspace(root);
+                await loadWorkspace(root, load({}, "no-fetch"));
             }
             catch (e) {
                 fail(e instanceof Error ? e.message : String(e));
@@ -516,7 +574,7 @@ program
     else {
         // craftar.yaml exists, try to load
         try {
-            const ws = await loadWorkspace(root);
+            const ws = await loadWorkspace(root, load({}, "no-fetch"));
             inUse = resolve(ws.forge, ws.config).targets;
         }
         catch (e) {
@@ -580,8 +638,9 @@ forge
     .option("--forge <dir>", "Forge directory (instead of --workspace)")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (o) => {
-    const f = await resolveForge({ forge: o.forge, workspace: o.workspace });
+    const f = await forgeFor(o);
     const report = await listVariants(f);
     if (o.json)
         return console.log(JSON.stringify(report, null, 2));
@@ -609,8 +668,9 @@ forge
     .option("--forge <dir>", "Forge directory (instead of --workspace)")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
     .action(async (ref, o) => {
-    const f = await resolveForge({ forge: o.forge, workspace: o.workspace });
+    const f = await forgeFor(o);
     const base = f.ingredients.get(ref);
     if (!base)
         fail(`${ref} is not an ingredient of this Forge`);
@@ -670,7 +730,13 @@ forge
         fail("pass exactly one of --take, --plan or --save-plan");
     if (o.take !== undefined && o.take !== "base" && o.take !== "variant")
         fail(`--take must be "base" or "variant"`);
-    const f = await resolveForge({ forge: o.forge, workspace: o.workspace });
+    // Never through the cache: a tree there is clean and tracked, so gitUnheld would pass and the edit
+    // would be lost at the next cleanup without reaching the remote (spec 13 §4.4).
+    const f = await resolveForge({
+        forge: o.forge,
+        workspace: o.workspace,
+        refuseRemote: (url) => `the Forge of this workspace is remote (${url}) — clone it and pass --forge <dir>`,
+    });
     const base = f.ingredients.get(ref);
     if (!base)
         fail(`${ref} is not an ingredient of this Forge`);
@@ -921,15 +987,55 @@ forge
 });
 program.parseAsync().catch((e) => fail(e instanceof Error ? e.message : String(e)));
 /* ---------------------------------------------------------------- helpers */
+/** The network rule of a command, `--offline`, and `$CRAFTAR_HOME` (spec 13 §4.1, §6.3). */
+function load(o, mode) {
+    return { mode, offline: o.offline === true, home: process.env.CRAFTAR_HOME || undefined };
+}
+/** A `forge` command's Forge; the warnings of reading a remote one go to stderr, so `--json` stays its shape. */
+async function forgeFor(o) {
+    const { forge, workspace } = await resolveForgeSource({ forge: o.forge, workspace: o.workspace, ...load(o, "read") });
+    warnStderr(workspace?.warnings ?? []);
+    return forge;
+}
+/** Warnings of loading the workspace, for commands whose stdout is not a report (a diff, `explain`, `ls`, `--json`). */
+function warnStderr(warnings) {
+    for (const w of warnings)
+        console.error(`${pc.yellow("warn")} ${w}`);
+}
+/** The header line naming a remote Forge (spec 13 §4.1); null for a path Forge, whose headers keep their shape. */
+function forgeLine(ws, lock) {
+    const o = ws.origin;
+    if (o.kind !== "remote")
+        return null;
+    const commit = ws.forge.commit;
+    const at = o.ref ?? `${o.defaultBranch} (default branch)`;
+    const moved = lock?.forge.commit && commit && lock.forge.commit !== commit ? ` · lock ${lock.forge.commit.slice(0, 8)}` : "";
+    return `  forge ${o.source} @ ${at} ${commit?.slice(0, 8) ?? "no git"}${moved}`;
+}
+/** `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,
+    };
+}
 function fail(msg) {
     console.error(pc.red("error: ") + msg);
     process.exit(1);
 }
-function printStatus(st, warnings, profile, recipes, compact = false) {
+function printStatus(st, warnings, profile, recipes, compact = false, forge = null) {
     const counts = {};
     for (const s of st)
         counts[s.state] = (counts[s.state] ?? 0) + 1;
     console.log(pc.bold(`craftar status — profile ${profile} · recipes ${recipes.join(" → ")}`));
+    if (forge)
+        console.log(forge);
     console.log("  " +
         Object.entries(counts)
             .map(([k, v]) => `${color(k)(k)} ${v}`)