n8n-decanter 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,270 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,30 @@ 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 from `shared/` 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 +117,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 +133,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 | ✅ `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 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
 

package/dist/lib/api.mjs

@@ -6,6 +6,34 @@
  * export a redeployable copy). The daily code path and lifecycle (pull/push/
  * watch/status/publish) stay on MCP (lib/mcp.mts).
  */
+/**
+ * Which n8n API scope a refused request needed (Plan 63 task 6).
+ *
+ * A 403 says "valid key, missing scope" and n8n names no scope — so the caller
+ * is left guessing which of eight to add. The scope names are already pinned in
+ * `template/.env.example` and the smoke suite, and Plan 25 verified the trap
+ * this exists for: column and row reads have **distinct** scopes that do not
+ * fold into `dataTable:read`, so a key that lists tables fine still 403s on
+ * `/columns`.
+ */
+function scopeHint(method, pathname) {
+    const readOnly = " decanter only ever READS data tables — no write scope is needed.";
+    if (pathname.includes("/data-tables/") && pathname.includes("/columns"))
+        return `Add \`dataTableColumn:read\` (listing tables uses \`dataTable:list\`, which does NOT cover columns).${readOnly}`;
+    if (pathname.includes("/data-tables/") && pathname.includes("/rows"))
+        return `Add \`dataTableRow:read\` (separate from \`dataTable:read\`).${readOnly}`;
+    if (pathname.startsWith("/api/v1/data-tables"))
+        return `Add \`dataTable:list\` and \`dataTable:read\`.${readOnly}`;
+    if (/^\/api\/v1\/executions\/\d/.test(pathname))
+        return "Add `execution:read`.";
+    if (pathname.startsWith("/api/v1/executions"))
+        return "Add `execution:list` (and `execution:read` to fetch one).";
+    if (pathname.startsWith("/api/v1/workflows") && method === "POST")
+        return "Add `workflow:create` (`backup restore` redeploys a backup as a new workflow).";
+    if (pathname.startsWith("/api/v1/workflows"))
+        return "Add `workflow:read` (and `workflow:list` for init's connection check).";
+    return "Check the key's scopes in n8n → Settings → n8n API.";
+}
 export class N8nApi {
     #host;
     #apiKey;
@@ -115,6 +143,13 @@ export class N8nApi {
             });
             const text = await res.text();
             if (!res.ok) {
+                // A 403 from the public API means the key is valid but under-scoped —
+                // and n8n does not say which scope is missing. Mapped HERE rather than
+                // in each caller so every REST surface (executions, data-tables, backup)
+                // gets it: `pathname` already identifies what was refused.
+                if (res.status === 403) {
+                    throw new Error(`${method} ${pathname} was refused (403) — N8N_API_KEY is valid but lacks a scope. ${scopeHint(method, pathname)}`);
+                }
                 throw new Error(`${method} ${pathname} failed: ${res.status} ${res.statusText}\n${text.slice(0, 2000)}`);
             }
             return text ? JSON.parse(text) : undefined;

package/dist/lib/config.mjs

@@ -1,5 +1,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+/**
+ * The one message every cold start hits — a fresh clone has no `.env`, so this
+ * is the first thing a user (or their agent) reads. It names the **flag** form
+ * on purpose: [Plan 75](../plans/done/75-init-cold-start-discoverability.md)
+ * came out of a blind round where the agent diagnosed the missing `.env` in one
+ * command and then sent its human to the *interactive* `init`, because nothing
+ * here mentioned that `init` takes the values as arguments. Shared with
+ * `createMcpClient`, which used to carry its own copy of the same string.
+ */
+export const HOST_UNSET = "N8N_HOST must be set (via .env next to decanter.config.json or the environment)\n" +
+    "  set it without prompts: n8n-decanter init . --host <host-url> --token <mcp-token>";
 /** Parse KEY=VALUE lines (optional `export`, quotes stripped) from an env file. */
 export function parseEnvFile(file) {
     const values = {};
@@ -57,7 +68,7 @@ export function loadConfig(cwd = process.cwd(), { requireHost = true } = {}) {
             const host = (process.env.N8N_HOST ?? "").replace(/\/+$/, "");
             const apiKey = process.env.N8N_API_KEY ?? "";
             if (requireHost && !host) {
-                throw new Error("N8N_HOST must be set (via .env next to decanter.config.json or the environment)");
+                throw new Error(HOST_UNSET);
             }
             return {
                 configDir: dir,

package/dist/lib/init.mjs

@@ -384,7 +384,9 @@ export async function init(targetDir, { force = false, host: hostFlag, token: to
         // --token / any setup flag suppresses every prompt (non-interactive mode).
         const auth = readAuthFileTolerant(dir, log);
         if (mcpToken !== "") {
-            log.info(tokenFlag !== undefined ? "using MCP token from --token" : "using existing MCP token from .env (N8N_MCP_TOKEN)");
+            // Doesn't name the flag: `--token` and `--mcp-token` both land here, and
+            // echoing a spelling the user didn't type reads like a correction.
+            log.info(tokenFlag !== undefined ? "using the MCP token given on the command line" : "using existing MCP token from .env (N8N_MCP_TOKEN)");
         }
         else if (auth !== null && auth.host === host) {
             log.info(`using existing MCP OAuth credentials (${AUTH_FILE})`);
@@ -405,7 +407,9 @@ export async function init(targetDir, { force = false, host: hostFlag, token: to
             mcpToken = await ask("n8n MCP token (n8n → Settings → MCP → API key) [Enter to skip]: ");
         }
         if (mcpToken === "" && !(auth !== null && auth.host === host)) {
-            log.warn("no MCP credentials yet — sync verbs (pull/push/watch/…) will not work until you re-run init or set N8N_MCP_TOKEN");
+            // Names the flag, not just "re-run init": this fires on exactly the
+            // host-only `init --host …` a blind agent reaches first (Plan 75).
+            log.warn("no MCP credentials yet — sync verbs (pull/push/watch/…) will not work until you re-run init with `--token <mcp-token>` (n8n → Settings → MCP → API key) or set N8N_MCP_TOKEN");
         }
         // --- optional public API key (the REST-only surfaces)
         if (apiKey === "" && !flagDriven) {

package/dist/lib/lifecycle.mjs

@@ -1,5 +1,6 @@
 import { getWorkflowDetails, publishWorkflowMcp, unpublishWorkflowMcp } from "./mcp.mjs";
 import { publicationState } from "./util.mjs";
+import { danglingNodeRefs, describeDanglingRefs } from "./validate.mjs";
 /**
  * `publish` — take the draft live (MCP `publish_workflow`, Plan 32). Since
  * pushes are draft-only now, this is THE go-live step: on a published
@@ -12,6 +13,21 @@ export async function publishWorkflow(mcp, id, log) {
         log.info(`"${before.name}" (${id}) is already published — the draft is live`);
         return;
     }
+    // Go-live gate (Plan 64 task 3b). Scans the draft we just read — the thing
+    // about to become live — NOT the repo folder: `workflow.json` is a snapshot,
+    // so grading it here would false-green on a stale mirror and false-red on a
+    // fresh clone. The scan is shared with `test`'s static tier, and re-running it
+    // is the point rather than waste: the instance can change between the two, so
+    // only the check inside `publish` is authoritative for this publish. It costs
+    // no extra call — the read above already happened.
+    const dangling = danglingNodeRefs(before.nodes);
+    if (dangling.length > 0) {
+        throw new Error([
+            `refusing to publish "${before.name}" — ${dangling.length} dangling $('…') reference(s) on the draft would go live:`,
+            ...describeDanglingRefs(dangling),
+            `then re-check with: n8n-decanter test ${id}`,
+        ].join("\n"));
+    }
     await publishWorkflowMcp(mcp, id);
     log.ok(`published "${before.name}" (${id}) — code is live now`);
 }

package/dist/lib/mcp.mjs

@@ -6,6 +6,7 @@
 // (plans/OPEN-32 spike).
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { HOST_UNSET } from "./config.mjs";
 import { CODE_NODE_TYPE } from "./util.mjs";
 export const MCP_PATH = "/mcp-server/http";
 export const AUTH_FILE = ".decanter-auth.json";
@@ -505,8 +506,26 @@ export class McpClient {
                 ? "the MCP token was rejected (401) — mint a fresh one in n8n (Settings → MCP) and update N8N_MCP_TOKEN (the public API key is not a valid MCP token)"
                 : "MCP authorization rejected (401) — re-run: n8n-decanter init");
         }
+        // 403 is what a SWITCHED-OFF MCP server answers a valid token with, verified
+        // on n8n 2.30.7 (Plan 74). It never 404s for that — 404 means the endpoint
+        // is not there at all. Without this branch the user got a bare
+        // "403 Forbidden" for a state they reach by flipping a documented switch.
+        // Note a missing/stale token still 401s while MCP is off, so the 401 above
+        // can mask this one; the troubleshooting page says so.
+        if (res.status === 403) {
+            const detail = (() => {
+                try {
+                    const m = JSON.parse(text).message;
+                    return typeof m === "string" && m !== "" ? ` (${m})` : "";
+                }
+                catch {
+                    return "";
+                }
+            })();
+            throw new Error(`n8n refused the MCP request (403)${detail} — turn MCP access on in n8n (Settings → MCP); if it is on, the token's user may lack access`);
+        }
         if (res.status === 404) {
-            throw new Error(`no MCP endpoint at ${this.#host}${MCP_PATH} (404) — enable MCP access in n8n (Settings → MCP; needs n8n ≥ ~2.20)`);
+            throw new Error(`no MCP endpoint at ${this.#host}${MCP_PATH} (404) — this n8n has no MCP server: check N8N_HOST points at the right instance, and that n8n is ≥ ~2.20 (a server that exists but is switched off answers 403, not 404)`);
         }
         if (isNotification)
             return undefined;
@@ -551,11 +570,12 @@ export class McpClient {
  */
 export function createMcpClient(config, log) {
     if (config.host === "") {
-        throw new Error("N8N_HOST must be set (via .env next to decanter.config.json or the environment)");
+        throw new Error(HOST_UNSET);
     }
     const auth = resolveMcpAuth(config.configDir, config.host, log);
     if (auth === null) {
-        throw new Error("no MCP credentials — run `n8n-decanter init` to connect via OAuth, or set N8N_MCP_TOKEN (n8n → Settings → MCP → API key)");
+        throw new Error("no MCP credentials — run `n8n-decanter init . --token <mcp-token>` (n8n → Settings → MCP → API key),\n" +
+            "  or bare `n8n-decanter init` to connect via OAuth in a browser, or set N8N_MCP_TOKEN");
     }
     return new McpClient({ host: config.host, auth, requestTimeoutMs: config.requestTimeoutMs, log });
 }