n8n-decanter 0.8.0 → 0.10.1

package/CHANGELOG.md

@@ -7,6 +7,480 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-08-16
+
+### Added
+
+- **The live mirror now tells the agent when it overwrote your work.** It runs a
+  full `pull` after a structure edit, so it can replace an unpushed local code
+  edit with what is on the instance. It always warned about that — on stderr,
+  which is the one stream an MCP agent structurally cannot read, so the party
+  able to react never heard it. The warning now rides the **result of the
+  agent's next tool call**, naming the files and how to recover them from the
+  safety commit. Delivered once, never repeated.
+
+  Only on `mcp connect` (the transport `init` scaffolds). `mcp serve` pipes
+  upstream responses through untouched — including SSE — and buffering them to
+  inject an advisory line would break streaming for every response to deliver it
+  on some. On that transport the stderr warning stays the only signal.
+
+- **`init` now says that its permission rules only bind the next session.** It
+  writes `.claude/settings.json` with the deny rules that keep an agent off
+  `.decanter.json`, `.env` and `push --force` — but agents read permission config
+  at startup, not on change, and `init` is normally run *from inside* the session
+  those rules are meant to constrain. They were silently inert until a restart,
+  and the docs mentioned a restart only for the skills plugin — so the rules that
+  actually gate the agent went unmentioned. Printed once, when the file is first
+  written; a re-init in a set-up directory stays quiet.
+
+- **`node run` fixtures can pin a node's other outputs, so `$('Node').all(1)`
+  finally answers.** Give a node one items array **per output** and the branch
+  is readable offline:
+
+  ```json
+  "nodes": { "Decide": [[{ "json": { "side": "true" } }], [{ "json": { "side": "false" } }]] }
+  ```
+
+  `all(1)` / `first(1)` / `last(1)` and `$items('Decide', 1)` read output 1, and
+  an **empty** array is a real answer — that branch took no items. `input` takes
+  the same shape, indexed by the node's *input* (a Merge node's second input).
+  A plain items array still means a single output, so existing fixtures are
+  unchanged; asking for an output the fixture doesn't supply still refuses,
+  now saying how many it has. Until now every such call was refused outright,
+  because a fixture could only express one array per node.
+
+- **`preflight --simulate` now replays a pinned node's other outputs too.** The
+  stand-in decanter substitutes for a network node is a Code node, which has one
+  output — so an error output (or any second branch) captured in your execution
+  was replayed nowhere, and everything behind it sat with no input, emitted
+  nothing, and let the run pass. Each populated output now gets **its own
+  stand-in**, wired to the same input as the original and feeding exactly that
+  output's targets, so the branch really runs. Deliberately not wired to the
+  synthetic trigger: a stand-in fires only when the original would, so a replay
+  whose real nodes take a different path can't have the old branch's items
+  injected into it anyway. The `simulate` check names the splits in its details
+  (terminal and `--json`). **`test` still replays `main[0]` only** — n8n's
+  `pinData` is one flat items array per node, with no output dimension — and
+  `scenario check` now spells out which of the two you are looking at.
+
+- **`test` now reports what the run actually moved, not just that it
+  finished** — a coverage line over the nodes that executed (enabled and
+  unpinned; a pinned node's items are the input you supplied):
+  `coverage: 7/9 unpinned node(s) emitted items — 2 emitted none: Group
+  products, Write rows`. A node counts as emitting if it put an item on **any**
+  output. Some empty nodes are normal — a filter that dropped everything — so
+  the line warns and nothing more.
+
+  **But a run in which not one unpinned node emitted an item now fails
+  (exit 1), even with synthetic pins.** n8n calls such a run `success` and
+  it is: nothing errored. No data moved either, so nothing was demonstrated,
+  and reporting it as a pass was the check lying. The message names the usual
+  cause — a pin replays a node's first output only.
+
+- **`scenario check` warns about what the replay will throw away.** Both replay
+  paths (`test`'s `pinData`, `preflight --simulate`'s stand-in node) read
+  `main[0]` only, while the validator happily accepts — and `✓ valid`s — a
+  scenario carrying items on several outputs. The check now says so offline:
+  once for a node whose data populates more than one output, naming the indices
+  that get dropped, and once for a node source that reads a pinned node's
+  non-first output (`$('Enrich').all(1)`, `$items('Enrich', 1)`) — the call that
+  returns nothing and leaves the node emitting nothing. Warnings only; the
+  scenario stays valid for the outputs that do replay.
+
+### Changed
+
+- **An explicit `.ts` extension in a node file's import no longer fails the
+  typecheck.** The scaffolded `tsconfig.json` now sets
+  `allowImportingTsExtensions`, so `import { total } from
+  "../../../shared/money.ts"` type-checks — until now it was rejected
+  (TS5097) even though `push` bundles it without complaint, which made the
+  gate and the bundler disagree over a pure spelling choice. Extensionless
+  stays the recommended form (it survives a helper later becoming `.js`);
+  both spellings resolve everywhere. Existing sync dirs are offered the
+  updated `tsconfig.json` on the next `init` — a `tsconfig.json` you edited
+  yourself is reported as drift and left alone, so add the option by hand
+  there.
+- **Two of the four import rules for `.ts` nodes now warn instead of
+  blocking a push**: a relative import resolving outside the sync dir, and an
+  absolute-path import. Both only endanger the author's own portability — the
+  bundle still builds locally and fails loudly (`Could not resolve`) wherever
+  the target is genuinely absent — so blocking them was decanter making the
+  user's call. The advisory prints on every surface (`preflight`'s `layout`
+  details, `push`, `node run`) and exactly once per push;
+  `preflight --fail-on=warn` is the strict variant for CI. **Node builtins
+  and npm packages not opted into `bundleDependencies` still block** —
+  esbuild is silent about both, so without the block the failure would
+  surface at runtime on the n8n instance.
+- **The scaffolded `mcp-route-check.mjs` session hook now also inspects
+  user-level agent config for direct n8n MCP routes** — Claude Code's
+  `~/.claude.json` (including its entry for the current project), Cursor's
+  `~/.cursor/mcp.json`, the VS Code user profile, and opencode's global
+  config. Previously it read only project files, so an `n8n` server added
+  with `claude mcp add -s user` (or any other user-scoped config) bypassed
+  the decanter guard without a word — exactly the "second door" the hook
+  exists to catch. Still a warning, never a gate. Re-run `init` in an
+  existing sync dir (or re-copy the hook from the template) to pick it up.
+- **The scaffolded `tsconfig.json` now covers the whole sync dir**, not just
+  `shared/` and `workflows/` — helper code may live in any folder inside the
+  sync dir (`shared/` is only the scaffolded default), so the typecheck and
+  the editor's tsserver now own every root without a config edit. Existing
+  sync dirs keep their scaffolded file; to match, widen `include` to
+  `["n8n-globals.d.ts", "**/*.ts", "**/*.js"]` and add
+  `"**/backups/**", "**/executions/**", "decanter-ts-plugin", "dist"` to
+  `exclude`. Two consequences worth knowing: a loose node-shaped scratch file
+  (top-level `return` outside any workflow's `code/`) is now part of the
+  program and reports TS1108 — move it into a workflow or add its folder to
+  `exclude`; and when `init` scaffolds into an **existing project** that had
+  no `tsconfig.json`, the new config sweeps that project's own `.ts`/`.js`
+  into the node-file typecheck — add your app dirs to `exclude` if they
+  shouldn't gate pushes.
+
+### Fixed
+
+- **`diff` and `preflight` no longer report a `CONFLICT` for a node with no
+  recorded sync hash.** "Changed both locally and remotely" is measured against
+  the last-sync baseline in `.decanter.json`; with no baseline nothing is
+  *known* to have moved on the instance, and `push` has always treated that as
+  pushable. The two disagreed, so the report described a dead end the CLI did
+  not have — worse, its documented exit (`push --force`) is denied to agents by
+  the permission rules `init` scaffolds. Such a node now reads as
+  `push pending`, which is what `push` does with it. `pull` no longer warns
+  `CONFLICT` for the same case on `.ts` nodes.
+- **A `.js` → `.ts` conversion no longer reads as data loss.** Re-pointing a
+  node's `//@file:` placeholder is the sanctioned way to convert, and `push`
+  and `pull` both adopt it before doing anything — but `diff` and `preflight`
+  looked the file up in `.decanter.json` alone and announced `local file
+  code/<node>.js missing` for the file you had just replaced. They now read the
+  placeholder too, so a converted node reports `local changes in
+  code/<node>.ts — push pending`, identically for every converted node.
+- **`preflight` no longer prints `✓ parity local code matches the draft`
+  directly above `✗ drift CONFLICT`.** Both checks read the same facts, so
+  `parity` may claim a match only when every node is in sync; divergence that
+  `drift` owns is reported as an `info` line pointing at it.
+- **`mcp connect` survives an unreachable n8n instead of dying at the
+  handshake.** `initialize` was forwarded like any other message, so a
+  connection failure answered the *handshake* with an error: the agent's MCP
+  client got no `serverInfo` and tore the session down before a single tool
+  call could report what was wrong. The guard now completes the handshake
+  itself when n8n does not answer, and the failure surfaces on the tool call
+  that needed the instance. Once n8n is reachable, the handshake is replayed
+  upstream so the session it uses is a real one. The startup line now reads
+  `guard: ready — forwarding all n8n MCP tools to <host>` instead of
+  `connected to <host>`, which claimed a connection nothing had made yet.
+- **The scaffolded `AGENTS.md` now names the n8n-side prerequisites.** MCP
+  access is a switch per *instance* **and** one per *workflow* ("Available in
+  MCP"), and until a workflow's is on, `pull`/`push`/`diff`/`preflight`/`watch`
+  all fail for it. The CLI's error says so; the file an agent reads *before*
+  running anything did not.
+- **`preflight`'s `types` check now reports type errors in shared helper
+  files** instead of passing green while `push` fails on them. The scoped
+  typecheck dropped every diagnostic outside the graded workflow's own dir —
+  and helper code lives outside every workflow dir by definition — so a
+  workflow could grade `ready` on code `push` then rejected. Helper
+  diagnostics (under `shared/` or any other folder) now surface in every
+  workflow's `types` line, while another workflow's *node* errors stay out of
+  scope as before.
+- **The documented shared-import path was one level short** for the `code/`
+  layout: `../../shared/money` in the TypeScript-nodes docs and the scaffolded
+  `AGENTS.md` resolved to `workflows/shared/money` and failed on copy-paste.
+  The correct depth from `workflows/<folder>/code/` is `../../../shared/money`.
+- **Compiled module labels — and therefore sync hashes — are now stable when
+  the sync dir is reached through a symlinked path** (macOS `/tmp`, a
+  symlinked checkout). esbuild resolves bundled files to their realpaths, so
+  an un-realpathed label base produced machine-specific `../…`-climbing
+  labels inside the hashed bytes — nodes reading "push pending" across
+  machines with nobody touching code. The same spelling mismatch made a
+  *scoped* typecheck silently drop every node diagnostic under a symlinked
+  path; both now realpath. If a sync dir lives behind a symlink, the first
+  push after this release re-baselines the affected nodes' hashes once.
+- **The route-check hook now reads opencode's real config shape**
+  (`mcp.<name>`). It previously looked only for `mcpServers` / `mcp.servers` /
+  `servers` bags, so an `opencode.json` routing straight at the instance was
+  listed as checked but never actually flagged.
+- **A `watch` save now runs the same folder-wide compliance guard as `push`.** It
+  used to check only the saved file, which cannot see the workflow's node names —
+  so it could not catch a dangling `$('Renamed Node')` and pushed straight to the
+  draft what a manual `push` refuses outright. The break then surfaced at run time
+  in n8n instead of at save time. Four surfaces already claimed the guards were
+  the same; now they are.
+
+  **The abort is scoped, deliberately:** a save is refused when the violation is
+  in the file you just saved, and violations elsewhere in the folder are printed
+  on every save without blocking it. Repairing a rename means fixing several
+  files, and a folder-wide abort would stop every save until the last fix — which
+  would disable `watch` during exactly the job it is for.
+
+- **`liveMirror` is documented as what it is: a full `pull`.** The shipped agent
+  contract and the config reference both described it as refreshing the
+  `workflow.json` snapshot. It also rewrites the `code/` files and
+  `.decanter.json` and moves files on a rename, so it can overwrite an unpushed
+  local edit — which is worth knowing before you restructure. No behaviour change;
+  the docs now say what the code has always done.
+
+## [0.10.0] - 2026-08-07
+
+### Added
+
+- **`scenario create <workflow> "<slug>" --extend`** — top an **existing**
+  scenario up with the pinnable nodes it is missing, keeping every value already
+  authored. Previously `scenario create` refused an existing file outright, so a
+  scenario `test` rejected could only be fixed by hand-editing raw JSON for nodes
+  the tool had never named. Also covers the ordinary case of a workflow that
+  gained a node after its scenario was written.
+
+- **`scenario create --scaffold` now works with no instance.** The fill entries
+  were always built from your local `workflow.json`; the instance only supplied
+  the per-node output **JSON Schemas**, which annotate the fill rather than
+  enable it. With no `N8N_HOST` configured it now says the annotations are
+  missing and scaffolds anyway — each node lands as provenance `authored`
+  instead of `scaffolded`, so the difference stays visible in the file. This is
+  what makes `preflight --offline --simulate` reachable on a plane: of the four
+  pin sources, only *fetching a fresh capture* actually needs n8n. The messages
+  that route you to a pin source now lead with the offline-viable ones, and
+  `docs/cli/preflight.md` states which of the four need the instance.
+
+### Changed
+
+- **Breaking:** **a slug-less `scenario create --scaffold` now writes
+  `scenarios/scaffold.json`, not `scenarios/scenario.json`.** The old default collided with the `scenario`
+  verb, and the flag parser refuses to read a verb name as a flag value — so
+  `preflight --simulate --scenario scenario` failed with `--scenario needs a
+  value`, leaving the default file referenceable only as `--scenario=scenario`.
+  If you have a script that names the old default file, point it at the new one
+  (an explicit `<slug>` argument was, and stays, unaffected).
+
+- **`scenario check` now reports the `test` gate too, not just the
+  `preflight --simulate` one.** The two demand different node sets on purpose —
+  `--simulate` asks only for nodes the capture **reached**, `test` asks for
+  **every** enabled non-pure node because it runs on the live instance with real
+  credentials. Reporting only the looser one meant a scenario could be green and
+  still be refused by `test`. `check` now says which gate you have passed, and
+  names `--extend` as the way to close the difference. The docs that asserted the
+  two rules were the same are corrected.
+
+- **`scenario create --execution` pins unreached nodes to an empty run instead of
+  asking you to invent output for them.** A pinnable node the capture never
+  reached is written as `[{"data":{"main":[[]]}}]` — "this branch isn't
+  exercised" — and listed under `_decanterScenario.notExercised`. That makes a
+  capture-seeded scenario usable with `test` straight away, keeps the node pinned
+  to zero items (so it can never touch the real world), and leaves the claim
+  visible for review: if a branch *should* have run, give it real data.
+
+- **The cold-start errors now name the non-interactive `init`, and `--mcp-token`
+  is an accepted alias for `--token`.** A fresh clone has no `.env` (it is
+  gitignored), so `N8N_HOST must be set …` is the first thing you — or a coding
+  agent — read. It said what was wrong and pointed only at a path that needs
+  someone at a prompt; a blind session diagnosed the problem in one command and
+  then had to hand the job back to a human. Both messages now spell out
+  `n8n-decanter init . --host <host-url> --token <mcp-token>`, `init --host` on
+  its own names `--token` when it warns about missing credentials, and the token
+  flag accepts either spelling.
+
+### Fixed
+
+- **The "install typescript" advice now pins `@^5`.** A bare
+  `npm i -D typescript` installs **7.x**, whose compiler is the native rewrite
+  and no longer exposes the programmatic API decanter's node-file typecheck
+  drives — so following the old advice replaced a *skipped* check with a broken
+  one. The skip message and `preflight`'s unlock now both say
+  `npm i -D typescript@^5` and name the reason. `init`'s scaffold already pinned
+  `^5`; this only ever bit projects `init` deliberately left alone.
+
+- **A 403 from the public API now names the scope you are missing.** n8n answers
+  a valid-but-under-scoped `N8N_API_KEY` with a bare 403 and says nothing about
+  which of eight scopes is absent. Every REST surface — executions, data tables,
+  backup — now gets a per-endpoint hint, including the trap that catches people
+  out: `dataTable:read` does **not** cover `/columns` or `/rows`, which need
+  `dataTableColumn:read` and `dataTableRow:read`. The data-table hints also say
+  outright that decanter only ever **reads** them, so no write scope is needed.
+
+- **`scenario create` prints the file's size, and warns before it lands in git.**
+  A capture-seeded scenario is a verbatim copy of every item of every node; one
+  from a busy production run can be tens of megabytes. Nothing measured it, and
+  `scenarios/` is tracked — so the folder-wide auto-commit on the next `pull` or
+  `push` swept it into history unasked. The success line now carries the size,
+  and anything above 1 MB warns explicitly that it is about to be committed.
+
+- **Three scenario messages pointed somewhere the thing you needed was not.**
+  A pre-rename scenario (`_decanterMock`) was told to look in
+  `_decanterScenario.fill` — a key not in the file; the message now names the key
+  it actually found. A replay gap derives its node list from the **workflow
+  graph**, so those nodes are by definition *not* in `fill`, yet it said "see the
+  `_decanterScenario` block"; it now says they are **not** listed, and points at
+  `--extend`. And a node deliberately written as `"Node": []` was reported as
+  unfilled — it is now told apart from a node with no entry at all, with the
+  spelling for "emits nothing".
+
+- **The agent guard's 401 no longer reads as "this project was never set up".**
+  It led with *"run `n8n-decanter init`"*, and a blind field-test round watched an
+  agent conclude from it that there was no `.env` and no token at all — then send
+  its user through a pointless `init`. The `.env` existed; the token had simply
+  been rotated. The guard now leads with the cause (*"n8n rejected decanter's
+  existing MCP credentials … they are configured but no longer valid"*), matching
+  what the CLI already said, and offers `init` only as the OAuth alternative. It
+  also maps **403** now, pointing at n8n → Settings → MCP.
+
+- **A missing `typescript` is reported as a skipped check, not a failed one.**
+  `preflight`'s node-file typecheck needs `typescript` in your project. A
+  globally installed decanter ships none (it is a devDependency), and `init`
+  leaves an existing `package.json` alone — so scaffolding into a project you
+  already had produced a module-resolution stack trace surfacing as a *typecheck
+  failure*, which reads like a type error in your own code. It is now an honest
+  skip, named in the coverage block with the one-command fix
+  (`npm i -D typescript`).
+
+- **The scaffolded `AGENTS.md` tells agents that `.env` is unreadable by policy
+  and that this is not evidence it is missing** — the reasoning trap behind the
+  401 finding above.
+
+- **`node run` no longer answers a branch index with the wrong branch's data.**
+  `$('Node').all(1)`, `$items('Node', 1)` and `$input.all(1)` ask for a node's
+  *second* output — an `IF`'s false branch, a `Switch`'s other case. A fixture
+  pins **one** items array per node, so there is no honest answer, but the
+  argument was accepted and **ignored**: you got output 0's items and the node
+  looked like it worked, graded against a shape it will never see live. Worse
+  than empty data, because nothing fails. These calls now refuse with a message
+  naming the call and the two ways forward (pin that branch as its own fixture
+  node, or run it for real with `test`) — the same signpost pattern `$vars` and
+  `$secrets` already use. `n8n-globals.d.ts` declared the parameter and
+  `docs/cli/node-run.md` listed the calls as fully covered, so both surfaces had
+  promised something the emulation never did.
+
+- **`pull` no longer destroys uncommitted local edits.** It committed the folder
+  *after* overwriting it, so an uncommitted `.js` edit was gone and had never
+  entered git — while the warning printed on that exact path told you to
+  "recover via git". Pull now takes a **snapshot commit before it writes
+  anything** (`watch` and the live mirror already did). If the snapshot cannot be
+  made — no git repo, `commitOnPull: false`, a git error — the pull still runs,
+  but the warning says the overwrite is **not** recoverable instead of promising
+  a safety net that isn't there.
+
+- **`pull`'s clobber warning now fires for a node it has never synced.** It was
+  gated on the node already having a sync baseline, which is backwards on the
+  read side: no baseline means the node isn't in `.decanter.json` yet, so the
+  local file is precisely the one with no protection. The loss path this opened
+  matches the scaffolded agent workflow exactly — an agent adds a Code node over
+  the guard (the guard blocks `jsCode`, so the remote body is empty), writes the
+  source into `code/<node>.js`, and a background mirror pull lands before the
+  first push: fresh file replaced by the empty remote body, silently.
+
+- **The live mirror stops refreshing when its safety commit fails.** It awaited
+  the commit and discarded the result, but that call returns a failure (it never
+  throws) for any git error — unset identity, a mid-merge tree, `index.lock`, a
+  rejecting hook. The documented "a dirty tree is safety-committed before the
+  pull" rail therefore degraded silently into an unrecoverable overwrite. It now
+  skips the refresh and says why, matching `watch`.
+
+- **Scenario gaps are now judged per branch, not per node.** A branching node
+  (an `IF`, a `Switch`) emits on **one** output per run, but `preflight
+  --simulate` and `scenario create --execution` read its *first* output for every
+  outgoing edge. Two consequences, both wrong: a node on the branch the capture
+  **never took** was reported as a gap you had to write pin data for, and a
+  genuine gap's `inputSample` was filled from the **other** branch's items — so
+  you coded against the wrong upstream shape. Untaken branches are exempt and
+  neutralized, as documented.
+
+- **An n8n whose MCP access is switched off now says so.** Turning MCP off is a
+  one-click state in n8n (Settings → MCP) and it makes the server answer a valid
+  token with `403 MCP access is disabled` — it never 404s. decanter recognised
+  401 and 404 but not 403, so every command failed with a bare
+  `403 Forbidden` and no next step. It now surfaces n8n's own reason plus the
+  fix. The 404 message was reworded to match what 404 actually means (no MCP
+  server at that address — wrong `N8N_HOST`, or an n8n too old to have one).
+
+  Note the ordering trap, now documented in the troubleshooting FAQ: a missing
+  or stale token still returns 401 while MCP is off, so the 401 can hide the 403.
+
+## [0.9.0] - 2026-08-04
+
+### Changed
+
+- **The agent guard now refuses a `publish_workflow` that would take a broken
+  draft live.** `publish` already checked, but the raw MCP tool went straight
+  through the guard — so an agent could go live around the verb and ship exactly
+  the breakage the check exists to catch. Both transports (`mcp connect` and
+  `mcp serve`) run the same check on the same shared code.
+
+  **Fail-closed:** if the check itself cannot run — n8n unreachable — the publish
+  is refused too, and the message says the *check* failed rather than claiming
+  the workflow is broken. A read that fails almost certainly means the publish
+  would have failed anyway, and "couldn't verify, so we shipped it" is not a gate.
+
+- **Dangling-reference checks now cover all four forms n8n rewrites on a rename**
+  — `` $('X') `` (as before) plus `$node["X"]`, `$node.X` and `$items('X')`.
+  Previously only the first was detected, so a rename could strand a `$node[…]`
+  call site that nothing reported: `preflight`, `push`, `test` and `publish` all
+  passed it, and it failed at run time instead. The rule is n8n's own — its
+  rewriter handles exactly these four — so if n8n treats it as a reference, the
+  guard now does too.
+
+  **This can surface errors in workflows that passed before.** A `$node["Old"]`
+  reference to a node that no longer exists is a hard compliance error, which
+  `--force` does not bypass. The message quotes the reference **as written**, so
+  it is clear which form triggered it. Computed references (`$(someVar)`, a
+  template literal with `${…}`) are still left alone — a regex cannot resolve
+  them, and n8n has the same limit.
+
+- **Breaking: `n8n-decanter test <workflow>` no longer executes.** It used to
+  fall back to the newest capture under `executions/` and run the workflow for
+  real on your instance — a directory that is gitignored, so the same commit
+  behaved differently for different people, and a bare verb had real side
+  effects. Bare `test` is now a **static tier**: it reads the instance's draft,
+  reports dangling `$('…')` references, and runs nothing. Pass
+  `--execution <id>` or `--scenario <slug>` for the pinned run, which is
+  otherwise unchanged. There is no deprecation shim — a `test` that still
+  executed *sometimes* would keep exactly the ambiguity this removes.
+
+  The pinned run now also does the static check first, so a draft already known
+  to be broken is never fired at the instance.
+- **`publish` refuses a draft carrying a dangling `$('…')` reference.**
+  Previously nothing checked: the compliance guard runs on `push`, `preflight`
+  and `backup` — not `publish` — so a task that only renamed nodes never hit a
+  gate and the break went live. The check reads **the draft on the instance**
+  (the read `publish` already makes), not your local folder: `workflow.json` is
+  a snapshot, so grading it would pass a broken workflow on a stale mirror and
+  block a legitimate publish from a fresh clone.
+
+### Added
+
+- **`init` now scaffolds a hook that catches stranded `$('…')` references right
+  after a rename.** n8n's `renameNode` MCP op rewrites the node name and the
+  connections only, so the references it leaves behind used to surface at the
+  next `push` — arbitrarily far from the rename that caused them. On Claude Code
+  a PostToolUse hook on `update_workflow` now reports them immediately, split
+  into the two halves and in the order they must be repaired: other nodes'
+  expression parameters in n8n first, then the code files here, then `push`.
+
+  It scans for the old name instead of running `preflight`, deliberately: the
+  hook fires before the background snapshot refresh, and until that lands the
+  snapshot still carries the old name, so every reference still resolves and
+  `preflight` would report clean. Silent when nothing references the renamed
+  node. The checklist in the scaffolded `AGENTS.md` remains the contract for
+  every agent — the hook is a reminder, not a replacement.
+
+### Fixed
+
+- **Corrected the rename guidance: n8n's `renameNode` MCP op does NOT rewrite
+  `$('…')` references.** The scaffolded agent guide (and the 0.6.0 notes below)
+  claimed n8n rewrites connections *and* `$('…')` references server-side on a
+  rename. Verified against real n8n 2.30.7 and 2.33.3: the MCP op rewrites the
+  node name and the **connections only**, then reports success with
+  `validationWarnings: []` — every `$('Old Name')` ref is left dangling, both in
+  Code-node source and in other nodes' expression parameters. The n8n *editor*
+  does rewrite them, but in the browser before it saves, so "server-side" was
+  wrong for that path too. No amount of pulling repairs this; `pull` faithfully
+  mirrors what n8n stored.
+
+  `init`'s `AGENTS.md`/`CLAUDE.md` now describe the real contract, including the
+  repair order that matters: **fix other nodes' expression parameters over MCP
+  first, then local code, then `push`.** The other order loses the code fix,
+  because a forwarded MCP write schedules a background snapshot refresh whose
+  pull overwrites unpushed `.js` edits.
+- **A dangling-reference error now says which half it is and where to fix it.**
+  The two compliance errors were near-identical and neither mentioned a rename,
+  which led to `workflow.json` being hand-edited — turning the check green while
+  n8n stayed broken.
+
 ## [0.8.0] - 2026-07-27
 
 ### Added

package/README.md

@@ -30,46 +30,31 @@ clean git diffs.
 
 ![Terminal demo — the interactive picker: filter workflows, choose a verb, sync](./docs/terminal-demo.gif)
 
-- **Real version control** — meaningful diffs, PRs, blame; every push and
-  pull is auto-committed.
+- **Real version control** — meaningful diffs, PRs and blame per Code node;
+  every push and pull is auto-committed.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push) or plain
   JS; n8n globals (`$input`, `$('…')`, …) are typed in both.
+- **Shared code and small libraries** — `.ts` nodes import helper files from
+  anywhere in the sync dir (`shared/` by default) and opted-in npm packages,
+  bundled on push to run anywhere, n8n Cloud included.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs;
-  the offline `preflight --offline` / `node run` loop gives agents a
-  credential-free feedback loop.
-- **One gate, two depth flags** — a compliance guard, typecheck gate, and
-  per-node drift guard gate every push; `preflight` folds layout, types and
-  instance sync facts into a single **read-only, CI-gateable verdict** (never
-  writes, never runs on your instance). `--simulate` *adds* an offline engine
-  replay (Docker), `--offline` *drops* the instance reads — and both that
-  replay and instance-side `test` diff every node against a real captured
-  execution and exit 1 on divergence. The flow is **`preflight` → `push` →
-  `test` → `publish`**: verify local, make it the draft, run what you pushed,
-  go live.
-- **Committed, schema-scaffolded scenarios** — `scenario create` turns a
-  captured execution and/or the workflow's own output schemas
-  (`--scaffold`, no LLM API) into a reviewable, git-tracked pin-data set that
-  `test` and `preflight --simulate` replay — the durable counterpart to an
-  agent's ephemeral
-  in-session pin flow.
+  `preflight --offline` and `node run` give agents a credential-free loop.
+- **Guarded agent access to n8n's MCP, wired by default** — the scaffolded
+  `.mcp.json` forwards n8n's full MCP surface except Code-node `jsCode` writes,
+  and the read-only `workflow.json` snapshot refreshes itself afterwards.
+- **One gate before you push** — `preflight` folds layout, types and instance
+  sync facts into a single read-only, CI-gateable verdict; `--simulate` adds an
+  offline engine replay, `--offline` drops the instance reads.
+- **Draft-first by construction** — every push lands on the **draft**;
+  `publish` is the deliberate go-live. Flow: **preflight → push → test → publish**.
+- **Committed, schema-scaffolded scenarios** — `scenario create` turns a captured
+  execution and/or the workflow's own output schemas into a git-tracked pin-data
+  set that `test` and `preflight --simulate` replay.
 - **Live editing** — `watch` pushes on save; the open n8n editor tab reflects
   each push live (n8n's own draft-edit refresh, no proxy needed).
-- **Guarded agent access to n8n's MCP — wired by default** — the scaffolded
-  `.mcp.json` spawns `mcp connect`, forwarding the full n8n MCP surface
-  except writes to a Code node's `jsCode`; no secret to manage. The read-only
-  `workflow.json` snapshot then **refreshes itself** after an agent
-  restructures the workflow through the guard — no manual `pull`
-  (`liveMirror`, on by default).
-- **Git-native disaster recovery** — `backup create` captures a versioned,
-  redeployable full export into a committed `backups/` store (fidelity MCP
-  can't give — credential refs kept, code stays a placeholder); `backup
-  restore` redeploys it as a new workflow with **node ids preserved**, a
-  second version history that outlives the instance.
-- **Shared code and small libraries** — `.ts` nodes import helpers/types from
-  `shared/` and opted-in npm packages, bundled on push into self-contained
-  nodes that run anywhere, n8n Cloud included.
-- **Draft-first by construction** — every push lands on the workflow's
-  **draft**; `publish` (or `push --publish`) is the deliberate go-live step.
+- **Git-native disaster recovery** — `backup create` captures a redeployable
+  full export into a committed `backups/` store; `restore` redeploys it as a new
+  workflow with **node ids preserved**.
 
 ![Agent demo — a coding agent edits a Code node, verifies it offline, then pushes to the draft](./docs/agent-demo.gif)
 
@@ -133,7 +118,7 @@ Full flag reference: `n8n-decanter --help`, or the
 | `diff [workflow…]` | Per-node line diff of local code vs the n8n draft — an inspection view, always exits 0 |
 | `executions [workflow…]` | Fetch recent execution data (read-only) |
 | `data-tables [table…]` | Fetch data-table schema + rows (read-only) |
-| `test <workflow>` | Pinned run **on the instance** (draft); diffs vs a capture |
+| `test <workflow>` | Grade the **instance's draft**: static check bare, pinned run with `--execution`/`--scenario` |
 | `preflight [workflow…]` | The one local gate — layout, types, instance sync facts, optional local-engine replay — scored and read-only; run before `push` (exits 1 on *not ready*) |
 | `scenario create` / `scenario check` | Build / validate a committed scenario (captured and/or schema-scaffolded) |
 | `backup create` / `restore` / `list` | Git-native disaster recovery — capture / redeploy / list versioned full-export backups |
@@ -149,50 +134,34 @@ tools (through the guard above); the next `pull` reconciles the local mirror.
 
 ## How it compares
 
-n8n-decanter is **Code-node-first**: it optimizes the loop of writing, typing,
-verifying, and shipping the JavaScript/TypeScript *inside* your workflows. It
-builds **on** n8n's own MCP server and skills — they're the foundation it rides
-for structure and lifecycle, not a rival. So the comparison below is against the
-native editor and against
-[n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) — a broader,
-whole-workflow authoring toolkit.
-
-> **Choose [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) if you…**
-> need an enterprise-ready automation framework — where AI agents assemble
-> complete workflows, multi-environment Dev → Prod pipelines automatically handle
-> credential governance, and full TypeScript GitOps ensures strict auditability
-> across your team.
->
-> **Choose n8n-decanter if you…** your workflows live or die by their Code nodes
-> and you want them as real files — TypeScript with typed n8n globals, shared libraries,
-> preflights (offline or instance-side), and code-level git history, synced
-> draft-first between your IDE, your coding agent, and n8n (even on Cloud).
+n8n-decanter is **Code-node-first**: it optimizes writing, typing, verifying and
+shipping the JavaScript/TypeScript *inside* your workflows, and builds **on**
+n8n's own MCP server and skills rather than rivalling them. Compared against the
+native editor and [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code),
+a broader whole-workflow authoring toolkit:
 
 | Capability | Native n8n (browser) | n8n-as-code | n8n-decanter |
 |---|---|---|---|
-| **TypeScript for Code nodes** | ❌ JavaScript or Python only | ❌ TS is at workflow level, not node logic | ✅ Code nodes as `.ts`, compiled on push, typed n8n globals |
-| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only; no libraries | ❌ not part of its model | ✅ `shared/*.ts` + npm bundled into self-contained nodes (Cloud-safe) |
-| **Code as individual files** | ❌ no source files (JSON blob) | 🟡 one `.workflow.ts` per workflow | ✅ folder per workflow; each Code node its own `.js`/`.ts` |
-| **Code-level git versioning** | 🟡 in-app history (DB snapshots, tiered retention); Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame per Code node; auto-commit each sync (+ read-only structure snapshot) |
-| **Preflights** (`preflight`, then `test`) | 🟡 re-run past executions / pin data, but online in-editor | 🟡 inspect executions against a live env | ✅ `preflight` scores your **local** code (layout, types, instance reads, optional offline `--simulate` engine replay) into one read-only, CI-gateable verdict *before* the push — then instance-side `test` runs the pushed draft; each runtime check diffs every node vs a real capture, exits 1 on divergence |
-| **Draft-first code sync** | ✅ editor *Save* vs *Publish* (manual, in-browser) | 🟡 API sync republishes on push (no draft-only) | ✅ pushes land on the **draft**; `publish` is the deliberate go-live (over MCP) |
-| **Live editing** | ✅ the canvas (baseline) | 🟡 explicit pull/push, no auto-watch | ✅ `watch`: push on save; the open editor tab reflects each push live (n8n-native) |
-| **Agent-native tooling** | 🟡 n8n's own canvas AI, not your agent on the codebase | ✅ Agent Workbench, skills, MCP, Claude/editor plugins | ✅ scaffolds Claude Code / Cursor / Codex configs incl. a pre-wired `mcp connect` guard holding the credentials; offline `preflight --offline`/`node run` loop |
-| **Model ownership** | ❌ locked to n8n's own hosted AI; can't use your Claude subscription | 🟡 beta Claude Code plugin uses your subscription; flagship Workbench needs an Anthropic key for Claude | ✅ never calls an LLM itself — your agent/subscription does 100%, no key or model config ever |
-| **Agentic workflow creation** | 🟡 AI Workflow Builder (natural language), but Cloud / plan-gated — credits, self-host needs setup | ✅ 537 node schemas + 7,700+ templates + skills | ✅ your agent builds structure over n8n's MCP (through the pre-wired `mcp connect` guard); decanter owns the Code-node source (files + `push`) |
-| **Whole-workflow authoring** | ❌ | ✅ `.workflow.ts` decorator classes (structure + links) | 🟡 Code-node source only; your agent builds structure live over MCP (row above), mirrored to a read-only `workflow.json` |
-| **Multi-environment promotion** | 🟡 Enterprise source control / environments | ✅ `promote` remaps creds + refs Dev→Prod | 🟡 separate sync dir per instance, but no `promote` (IDs/creds/refs not remapped) |
+| **TypeScript for Code nodes** | ❌ JavaScript or Python only | ❌ TS at workflow level, not node logic | ✅ `.ts` nodes, compiled on push, typed n8n globals |
+| **Shared types & helpers in Code nodes** | ❌ self-host `NODE_FUNCTION_ALLOW_*` only | ❌ not part of its model | ✅ helper `.ts` anywhere in the sync dir + npm, bundled into self-contained nodes (Cloud-safe) |
+| **Code as individual files** | ❌ no source files (JSON blob) | 🟡 one `.workflow.ts` per workflow | ✅ folder per workflow; each Code node its own file |
+| **Code-level git versioning** | 🟡 in-app history; Git source control is Enterprise-only | ✅ GitOps sync of workflow source | ✅ real git — diffs, PRs, blame per Code node; auto-commit each sync |
+| **Preflights** (`preflight`, then `test`) | 🟡 re-run past executions, but online in-editor | 🟡 inspect executions against a live env | ✅ one read-only, CI-gateable verdict *before* the push; then `test` runs the pushed draft — each diffs every node vs a real capture |
+| **Draft-first code sync** | ✅ editor *Save* vs *Publish* (in-browser) | 🟡 API sync republishes on push | ✅ pushes land on the **draft**; `publish` is the deliberate go-live |
+| **Live editing** | ✅ the canvas (baseline) | 🟡 explicit pull/push, no auto-watch | ✅ `watch`: push on save; the open editor tab reflects it live |
+| **Agent-native tooling** | 🟡 n8n's canvas AI, not your agent on the codebase | ✅ Agent Workbench, skills, MCP, editor plugins | ✅ scaffolds Claude Code / Cursor / Codex + a pre-wired `mcp connect` guard; offline agent loop |
+| **Model ownership** | ❌ locked to n8n's hosted AI | 🟡 Workbench needs an Anthropic key for Claude | ✅ never calls an LLM itself — your agent/subscription does 100% |
+| **Agentic workflow creation** | 🟡 AI Workflow Builder, but Cloud / plan-gated | ✅ 537 node schemas + 7,700+ templates + skills | ✅ your agent builds structure over n8n's MCP; decanter owns the Code-node source |
+| **Whole-workflow authoring** | ❌ | ✅ `.workflow.ts` decorator classes | 🟡 Code-node source only; structure goes over MCP, mirrored read-only |
+| **Multi-environment promotion** | 🟡 Enterprise source control / environments | ✅ `promote` remaps creds + refs Dev→Prod | 🟡 separate sync dir per instance, no `promote` |
 
 Legend: ✅ first-class · 🟡 partial or indirect · ❌ not supported.
 
 **Bottom line:** reach for n8n-decanter when your workflows live or die by their
-Code nodes — TypeScript, shared libraries, preflights, and code-level git
-history, shipped draft-first. It rides n8n's own MCP and skills for everything
-structural, so n8n-as-code still shines for whole-workflow authoring/generation
-and multi-environment ops, and the native editor stays the live visual canvas
-everything syncs back to. And decanter makes no LLM calls of its own — you drive
-it with the coding agent you already run, so Claude Code on a Claude subscription
-needs no extra API tokens.
+Code nodes. n8n-as-code still shines for whole-workflow authoring and
+multi-environment ops, and the native editor stays the visual canvas everything
+syncs back to. decanter makes no LLM calls of its own — you drive it with the
+coding agent you already run.
 
 ## Caveats