n8n-decanter 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -7,6 +7,146 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-08-18
+
+### Changed
+
+- **"Missing `n8n-instance` tools? Restart" is no longer the only answer we
+  give — in a nested sync dir it was a dead end.** Agent wiring loads at
+  startup *from the dir the agent was started in*, so tools declared in
+  `.mcp.json` can be absent for two reasons: the wiring is new (a restart fixes
+  it), or the wiring sits **below** the launch dir, where no restart will ever
+  load it. Every surface that taught only the first now teaches both, with the
+  discriminator you can apply yourself — *is that `.mcp.json` below the
+  directory you started the agent in?* — and the two working routes (start the
+  agent in the sync dir, or wire the root with `N8N_DECANTER_DIR` plus a
+  root-resolvable command): the scaffolded `AGENTS.md`, `init`'s own output
+  (which now prints the nested guidance **instead of** the restart line when it
+  scaffolds into a nested dir), [Working with coding
+  agents](/docs/agents/overview/), [init](/docs/cli/init/) and a new
+  [troubleshooting](/docs/faq/troubleshooting/) entry. The CLI never needed
+  that wiring, so `pull`/`push`/`preflight` keep working either way — the docs
+  now say so too.
+
+- **The oversized-scenario warning now names a remedy you can actually take.**
+  Above 1 MB `scenario create` said "Trim it before that" — but there is no
+  trim flag, so the advice pointed nowhere. It now says what is true and what
+  to do: nothing is committed yet (`scenario create` never commits — only the
+  next `pull`/`push` sweeps the folder into history), so you can still cut
+  items out of `data.resultData.runData` by hand, or re-create the scenario
+  with `--scaffold` instead of `--execution` and author the pins yourself.
+  `docs/cli/scenario.md` spells out both, including which parts of a capture
+  are unsafe to delete.
+
+- **The agent contract now says to orient *before* the first edit, not only
+  before the push.** `preflight` was always the read-only report of the
+  instance's side (`drift`, `CONFLICT`, a pending `parity`), but every surface
+  framed it as the pre-push gate — so an agent edited first and learned about a
+  colleague's UI edit afterwards. The scaffolded `AGENTS.md` and both agent doc
+  pages now open the loop with it: on drift, `pull` and carry on; on a
+  `CONFLICT`, show `diff` and ask before either side is overwritten.
+- **The scaffold stopped advertising a deny rule it no longer has.** The
+  Claude Code `settings.json` denies `.decanter.json`, `.env` and
+  `push --force` — but the scaffolded `CLAUDE.md` and `opencode.json` still
+  claimed `*.remote.js` was blocked too. Those conflict artifacts were removed
+  in the MCP pivot; both files now describe the policy that actually ships.
+- **Docs: `mcp connect` / `mcp serve` no longer read as if the guard obtained
+  credentials itself.** "decanter's own credentials", "the agent never holds an
+  n8n credential" and "no secret to manage" led readers (and agents) to believe
+  the guard handles the n8n login. It does not: it only *reads* what `init`
+  wrote to `.env` / `.decanter-auth.json`, and can at most refresh an OAuth
+  token. The mcp-connect / mcp-serve pages and the template `AGENTS.md` now say
+  so outright — obtaining credentials is exclusively `init`'s job, and a
+  "no MCP credentials" answer means run `init`, not retry.
+
+- **"decanter.config.json not found" now points at `init` — with its flags.**
+  The classic half-setup is a hand-written `.env`: an agent that cannot run the
+  browser OAuth flow asks its human to paste `N8N_MCP_TOKEN` into a file and
+  stops there, leaving no config, template, `.gitignore` or agent wiring behind.
+  The error now says the dir is not a sync dir yet, that `.env` alone is not
+  enough, and prints the prompt-free command that fixes it
+  (`n8n-decanter init . --host <host-url> --token <mcp-token>`). The docs
+  (init, configuration, troubleshooting, README) say the same thing: headless is
+  not a reason to skip `init` — it takes the same token as a flag.
+
+- **`init`'s restart reminder now covers everything it wires, not just
+  permission rules.** MCP servers (`.mcp.json` / `opencode.json` — including the
+  guarded `n8n-instance` server), permission rules and hooks are all read at
+  agent **startup**, and `init` normally runs inside the session it configures.
+  The reminder now fires when any of those files is newly scaffolded and says
+  what it means: this session is still unconfigured, restart the agent (or
+  `/reload`). README, init and the agents docs say the same, and the scaffolded
+  `AGENTS.md` tells the agent to **ask for a restart** when the `n8n-instance`
+  tools are missing instead of connecting to the instance directly.
+
+### Fixed
+
+- **The scaffolded hooks now work when your sync dir is not where the agent was
+  started.** All three found the sync dir by assuming it was the current
+  directory, which only holds for an agent launched inside it. With the sync dir
+  nested in a bigger repo — a layout the docs explicitly allow — the agent runs
+  at the repo root and every one of them misbehaved: the rename-reference guard
+  became a **silent no-op**, so `$('Old Name')` references left behind by a
+  `renameNode` went unreported until a later `push` refused them; the verify hook
+  spawned the CLI without a directory, so it **blocked every node-file edit** with
+  a "not a sync dir" error; and the MCP routing check scanned the wrong tree.
+  Each hook now locates the sync dir from its own installed path, so it behaves
+  the same wherever the agent starts.
+- **The routing check no longer misses direct-route servers in your user
+  config.** Its lookup for this project's entry in `~/.claude.json` matched the
+  current directory, but that file is keyed by the repository root — so in any
+  sync dir inside a git repo the check silently found nothing. It now matches the
+  project entry for the sync dir or any parent of it.
+- **The verify hook finds a locally installed CLI.** It only ever looked for
+  `n8n-decanter` on `PATH`, so with a local (non-global) install it stayed quiet
+  and no verification ran at all. It now prefers the sync dir's
+  `node_modules/.bin` and falls back to `PATH`.
+- **"decanter.config.json not found" no longer sends you to `init` when the sync
+  dir is simply somewhere else.** Run from *above* a perfectly good sync dir —
+  what happens whenever an agent starts at the repo root — the error read as if
+  nothing had ever been set up, and advised scaffolding a second sync dir on top
+  of the working one. It now looks below the directory it searched from, names
+  the sync dir it finds there, and prints the `--dir` / `N8N_DECANTER_DIR` form
+  that reaches it. When there really is no sync dir, the `init` advice is
+  unchanged.
+
+### Added
+
+- **The routing check also looks at parent directories, up to your repository
+  root.** Agents merge `.mcp.json` from every directory above the one they start
+  in, so a server pointing straight at your n8n instance can sit in the repo
+  root's config and still route this session. The scan stops at the repository
+  boundary, so it never reaches into unrelated parent directories, and an
+  offender found above the sync dir is named by its relative path
+  (`../.mcp.json`) so you can tell which file it means.
+
+- **`--dir <path>` (or `N8N_DECANTER_DIR`) points any verb at a sync dir that is
+  not the current directory.** The layout the docs allow but nothing supported:
+  the sync dir nested inside a bigger repo, with the agent started at the repo
+  root. The MCP entry `init` writes into the sync dir is invisible from up
+  there, and hoisting it to the repo root spawned the guard where no
+  `decanter.config.json` could be found — so the guard did not work at all. The
+  search still only walks *up*; this says where it starts. In an agent's server
+  entry the environment variable is the form to reach for
+  (`"env": { "N8N_DECANTER_DIR": "flows" }`), and relative values resolve
+  against the working directory, so a repo-relative one keeps working for
+  everyone who clones. `init` does not take `--dir` — it still takes the
+  directory to scaffold as an argument.
+
+- **`init` now tells you how to wire an agent when your sync dir is nested in a
+  bigger project.** Agents look for `.mcp.json`, `opencode.json` and
+  `.claude/settings.json` from the directory they were *started* in and never in
+  one below it, so everything `init` scaffolds is inert for an agent started at
+  the repo root above the sync dir. When init sees a project around it (a `.git` or
+  `package.json` in a parent) it prints both shapes that work: starting the
+  agent inside the sync dir — recommended, nothing further to configure — or the
+  paste-ready MCP, opencode and hooks/permissions blocks for the project root,
+  with every path and glob already prefixed. That prefixing is the point: copied
+  up verbatim, `Read(.env)` / `Edit(.env)` guard the *root's* `.env` and quietly
+  stop protecting your credentials. `init` prints this; it never writes into a
+  parent directory. Only on the run that first scaffolds the agent files, and
+  never for a standalone sync dir.
+
 ## [0.10.1] - 2026-08-16
 
 ### Added

package/README.md

@@ -73,6 +73,13 @@ n8n-decanter init [dir]   # OAuth in your browser (or a pasted MCP token)
 n8n-decanter pull         # pick a workflow from the list → it pulls
 ```
 
+**Restart your coding agent after `init`** — the MCP servers, permission rules
+and hooks it scaffolds are read at agent startup, so the session that ran `init`
+is still unconfigured. If the sync dir is nested in a bigger repo and you start
+the agent at the repo root, a restart is *not* enough — that wiring loads only
+from the dir the agent starts in
+([which file loads from where](docs/agents/overview.md#where-the-agent-wiring-loads-from)).
+
 On a terminal, `pull` with no argument lists your n8n workflows — pick one and
 it lands in `workflows/<slug>/`. Know the id already? `n8n-decanter pull
 <id-or-name>` pulls it directly (scriptable, no TTY needed).
@@ -80,7 +87,9 @@ it lands in `workflows/<slug>/`. Know the id already? `n8n-decanter pull
 set a bare `pull`/`push`/`diff` acts on.)
 
 **Credentials:** OAuth by default (via `init`); `N8N_MCP_TOKEN` for
-headless/CI; `N8N_API_KEY` is optional, needed only for `executions`,
+headless/CI — pass it to `init --host <url> --token <mcp-token>` rather than
+hand-writing `.env`, which leaves the config, template, `.gitignore` and agent
+configs unscaffolded; `N8N_API_KEY` is optional, needed only for `executions`,
 `data-tables`, and `backup`. Details: [Installation](docs/getting-started/installation.md),
 [init](docs/cli/init.md), [Configuration](docs/concepts/configuration.md).
 
@@ -132,6 +141,17 @@ renaming, and archiving workflows — and adding or renaming nodes — are
 **n8n's acts**: do them in the editor or let your agent do it over n8n's MCP
 tools (through the guard above); the next `pull` reconciles the local mirror.
 
+**Sync dir nested in a bigger repo?** A global `--dir <path>` (or
+`N8N_DECANTER_DIR`) starts the upward `decanter.config.json` search there
+instead of in the working directory — every verb honours it except `init`,
+which takes the directory to scaffold as its argument. A coding agent launched
+at the repo root needs it too — agents look for `.mcp.json` and
+`.claude/settings.json` from where they were *started*, never in a directory
+below it, so either start the agent in the sync dir or wire the root
+explicitly:
+[Working with coding agents](docs/agents/overview.md#where-the-agent-wiring-loads-from),
+[mcp connect](docs/cli/mcp-connect.md#when-your-sync-dir-is-not-your-project-root).
+
 ## How it compares
 
 n8n-decanter is **Code-node-first**: it optimizes writing, typing, verifying and

package/dist/lib/config.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 /**
  * The one message every cold start hits — a fresh clone has no `.env`, so this
@@ -44,12 +44,114 @@ export function loadEnv(dir) {
             process.env[key] = value;
     }
 }
+/**
+ * Where `loadConfig`'s upward search STARTS: `--dir` > `N8N_DECANTER_DIR` > cwd.
+ * The search itself is untouched (Plan 81) — this only moves its origin, so a
+ * sync dir nested in a bigger repo stays reachable from a process started at the
+ * repo root. That is the shape agent wiring falls into: an MCP entry hoisted to
+ * the repo root spawns `mcp connect` with cwd = the root, and an upward-only
+ * search can never walk *down* into `flows/`.
+ *
+ * **The env var is the load-bearing half, not the flag** — every agent's MCP
+ * server entry has an `env` block, while a `cwd` key is not guaranteed across
+ * agents and versions.
+ *
+ * **Both forms resolve against cwd on purpose:** a committed root `.mcp.json`
+ * carrying `N8N_DECANTER_DIR=flows` survives a clone on a teammate's machine,
+ * where an absolute `/home/me/repo/flows` would not. (`loadEnv` never overrides
+ * an already-set variable, so the sync dir's own `.env` can't fight the value
+ * that pointed decanter at it — and couldn't anyway: it is read only *after*
+ * the dir has been found.)
+ *
+ * A path that is not a directory fails here, loudly. Left alone it would walk
+ * to the filesystem root and surface as "not found (searched from … upward)" —
+ * a message about the wrong problem.
+ */
+export function resolveSearchStart(dirFlag, cwd = process.cwd(), env = process.env) {
+    const envDir = env.N8N_DECANTER_DIR;
+    // Empty counts as unset: an agent config that interpolates a missing value
+    // ships `"N8N_DECANTER_DIR": ""`, and inheriting cwd beats failing on it.
+    const override = dirFlag !== undefined && dirFlag !== ""
+        ? { value: dirFlag, source: "--dir" }
+        : envDir !== undefined && envDir !== ""
+            ? { value: envDir, source: "N8N_DECANTER_DIR" }
+            : undefined;
+    if (override === undefined)
+        return path.resolve(cwd);
+    const resolved = path.resolve(cwd, override.value);
+    const stat = statSync(resolved, { throwIfNoEntry: false });
+    if (stat === undefined || !stat.isDirectory()) {
+        throw new Error(`${override.source} ${override.value} is not a directory (resolved to ${resolved})\n` +
+            "  it names the sync dir — the folder holding decanter.config.json — and relative paths\n" +
+            "  resolve against the working directory, so a repo-relative value stays portable");
+    }
+    return resolved;
+}
+/**
+ * Bounded hunt for a sync dir *below* `start` — the evidence that separates
+ * "not a sync dir yet" from "the search started too high" (Plan 81). Breadth-
+ * first so the shallow hit wins, skipping `node_modules` and every dot-dir
+ * (`.git` included — nobody's sync dir lives there, and they are where the file
+ * count explodes). Symlinked dirs report `isDirectory()` false from a `Dirent`,
+ * so a link cycle is never entered.
+ *
+ * **Three caps, and the WALL-CLOCK one is the load-bearing cap.** Counting
+ * directories is not enough: measured here, a single `existsSync` inside an
+ * rclone/NFS-style mount costs ~500 ms, so a scan of a home directory holding
+ * one ran **16 seconds** — on the failure path of every verb, the guard's
+ * `mcp connect` startup included. This whole scan only sharpens an error
+ * message, so it is never worth waiting for: past the deadline it gives up and
+ * the caller falls back to the cold-start advice.
+ *
+ * One `readdirSync` per visited dir, and the hit is read out of those entries —
+ * the earlier shape (readdir the parent, then stat `<child>/decanter.config.json`
+ * for every child) paid two round trips per directory to learn the same thing.
+ */
+function findConfigBelow(start, maxDepth = 3, maxDirs = 400, maxMs = 250) {
+    const deadline = Date.now() + maxMs;
+    const queue = [{ dir: start, depth: 0 }];
+    let visited = 0;
+    while (queue.length > 0) {
+        if (visited >= maxDirs || Date.now() > deadline)
+            return undefined;
+        const { dir, depth } = queue.shift();
+        visited++;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // unreadable directory (permissions, a race) — skip it; this scan is
+            // never authoritative
+            continue;
+        }
+        // `start` itself cannot hold one — loadConfig checked it before walking up.
+        // `!isDirectory()` rather than `isFile()`: a `Dirent` reports a SYMLINK as
+        // neither, and loadConfig's own `existsSync` would happily follow one.
+        if (dir !== start && entries.some((e) => e.name === "decanter.config.json" && !e.isDirectory()))
+            return dir;
+        if (depth >= maxDepth)
+            continue;
+        for (const entry of entries) {
+            // Cap the QUEUE too, or one directory with 100k children buys itself
+            // 100k queue entries before the visit counter ever gets a say.
+            if (queue.length >= maxDirs)
+                break;
+            if (!entry.isDirectory() || entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+    return undefined;
+}
 /**
  * Load decanter.config.json from cwd (or nearest ancestor) and resolve paths.
  * `requireHost` gates only N8N_HOST (online verbs need it): the API key is
  * optional since Plan 32 (MCP is the sync backend; `requireApiKey` guards the
  * REST-API-only verbs at use time) and MCP credentials are resolved separately
  * (lib/mcp.mts `resolveMcpAuth` — env token or .decanter-auth.json).
+ * `cwd` is where the search *starts*; the CLI passes `resolveSearchStart(…)` so
+ * `--dir`/`N8N_DECANTER_DIR` can move that origin without touching the walk.
  */
 export function loadConfig(cwd = process.cwd(), { requireHost = true } = {}) {
     let dir = path.resolve(cwd);
@@ -86,8 +188,34 @@ export function loadConfig(cwd = process.cwd(), { requireHost = true } = {}) {
             };
         }
         const parent = path.dirname(dir);
-        if (parent === dir)
-            throw new Error("decanter.config.json not found (searched from " + cwd + " upward)");
+        if (parent === dir) {
+            // Two different situations end up here, and the advice inverts between
+            // them — so say which one the user is in. A sync dir sitting *below* the
+            // starting point means the setup is fine and the search merely began too
+            // high (an agent launched at the repo root; Plan 81). Sending that user to
+            // `init` would scaffold a second sync dir on top of a working one.
+            const nested = findConfigBelow(path.resolve(cwd));
+            if (nested !== undefined) {
+                const rel = path.relative(path.resolve(cwd), nested) || ".";
+                throw new Error("decanter.config.json not found (searched from " + cwd + " upward)\n" +
+                    "  it is not missing — the sync dir sits BELOW the working directory: " + nested + "\n" +
+                    "  the search only walks up, so name the sync dir explicitly:\n" +
+                    // The `=` form, not `--dir <rel>`: the space form declines to eat a
+                    // value that is also a verb, so a sync dir called `test/` or `list/`
+                    // would come back as "--dir needs a value" from a copy-paste.
+                    "  n8n-decanter <verb> --dir=" + rel + "\n" +
+                    "  or set N8N_DECANTER_DIR=" + rel + " (agents: the `env` block of the decanter MCP server entry)");
+            }
+            // A hand-written `.env` is the classic half-setup: an agent that cannot
+            // run the browser OAuth flow asks its human to paste `N8N_MCP_TOKEN`
+            // into a file and stops there, leaving no config, template, .gitignore
+            // or agent wiring. Name the non-interactive `init` (it takes the very
+            // same token as a flag) so the fix is one command, not a research task.
+            throw new Error("decanter.config.json not found (searched from " + cwd + " upward)\n" +
+                "  this is not a decanter sync dir yet — writing .env by hand is not enough; init also\n" +
+                "  scaffolds the config, template, .gitignore and agent configs:\n" +
+                "  n8n-decanter init . --host <host-url> --token <mcp-token>");
+        }
         dir = parent;
     }
 }

package/dist/lib/init.mjs

@@ -212,6 +212,156 @@ function migrateRenamedTemplateFiles(srcDir, destDir, manifest, force, log) {
     }
     return { skip, keep };
 }
+/**
+ * Nearest STRICT ancestor of `dir` that looks like the **agent's** project root
+ * — one holding `.git` (a *file* in worktrees and submodules, so `existsSync`,
+ * never `statSync().isDirectory()`) or a `package.json`. Null when there is
+ * none, which is the standalone sync dir every earlier version assumed.
+ *
+ * Only strict ancestors count, and that is what makes the test cheap: the sync
+ * dir's own scaffolded `package.json` — and a `git init` run inside it, the
+ * shape the docs teach — are never mistaken for a parent project.
+ *
+ * `.git` beats an intermediate `package.json` on the way up: in a monorepo the
+ * repo root is the dir people actually open, while a sub-package manifest is
+ * just a stop along the walk.
+ *
+ * Consulting git here answers "where would the agent be started?", a different
+ * question from "where is the sync dir?" — so it is **not** a reversal of
+ * `docs/concepts/sync-layout.md`'s "decanter never uses git to find the sync
+ * dir" (which remains true: that is still the upward `decanter.config.json`
+ * search, git-blind).
+ */
+export function projectRootAbove(dir) {
+    let current = path.resolve(dir);
+    let pkgRoot = null;
+    for (;;) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            return pkgRoot; // fs root: only a package.json ever matched
+        if (existsSync(path.join(parent, ".git")))
+            return parent;
+        if (pkgRoot === null && existsSync(path.join(parent, "package.json")))
+            pkgRoot = parent;
+        current = parent;
+    }
+}
+/**
+ * The nested-sync-dir note (Plan 81), printed verbatim rather than pointed at:
+ * the wiring `init` just wrote is loaded **only from the dir the agent starts
+ * in** — `.mcp.json` is merged from every ancestor of that dir (so a nested one
+ * is invisible from above) and `.claude/settings.json` is read from that dir
+ * alone, no walk in either direction. Verified against Claude Code 2.1.234.
+ *
+ * Option A leads because it is the only shape with zero further config *and*
+ * the only one in which the scaffolded permission globs stay anchored where
+ * they were written. Option B is deliberately the long half: a root-hoisted MCP
+ * entry needs BOTH the `N8N_DECANTER_DIR` pin (decanter's config search only
+ * ever walks *up* from its cwd) and a command that resolves from the root —
+ * which `npx --no-install n8n-decanter` does not: it looks in the *launch*
+ * dir's `node_modules/.bin`, which under a local install is the sync dir
+ * itself. And a hoisted permission list is worse than none: relative globs
+ * re-anchor at the root, so a verbatim `Read(.env)`/`Edit(.env)` stops covering
+ * the credentials file — hence every glob below carries the sync-dir prefix.
+ */
+export function nestedWiringNote(syncDir, projectRoot) {
+    const rel = path.relative(projectRoot, syncDir).split(path.sep).join("/");
+    // Local install → the binary is not on the root's PATH; point at it
+    // repo-relative (child_process resolves a command containing a separator
+    // against the spawn cwd = the agent's root), because an ABSOLUTE path in a
+    // committed root config is wrong on every other machine.
+    const hasLocalBin = existsSync(path.join(syncDir, "node_modules", ".bin", "n8n-decanter"));
+    const command = hasLocalBin ? `${rel}/node_modules/.bin/n8n-decanter` : "n8n-decanter";
+    const commandNote = hasLocalBin
+        ? `     The command is that path because decanter is installed inside the sync
+     dir, not globally. Keep it repo-relative — an absolute path in a committed
+     root config breaks for everyone else who clones.`
+        : `     The bare command name assumes a global install (npm i -g n8n-decanter).
+     If you instead run npm install inside the sync dir, nothing is on the
+     root's PATH — use ${rel}/node_modules/.bin/n8n-decanter (repo-relative;
+     an absolute path in a committed root config breaks for everyone else).`;
+    return `
+  This sync dir is nested inside ${projectRoot}. Agents load the wiring just
+  scaffolded here only when they are STARTED here: .mcp.json is merged from
+  every ancestor of the launch dir (so a nested one is invisible from above),
+  and .claude/settings.json is read from the launch dir alone.
+
+  ${style.bold("A. Recommended — start the agent in this dir:")}
+
+       cd "${syncDir}" && claude        # or opencode, codex, …
+
+     Everything just scaffolded then applies unchanged, with no further config.
+     Its one cost: that project's own .claude/settings.json does not load then
+     (its .mcp.json still does, via the ancestor walk).
+
+  ${style.bold(`B. Or wire up ${projectRoot} by hand — both halves, or it still fails:`)}
+
+     ${projectRoot}/.mcp.json — merge into the servers already there (the
+     "n8n-docs" entry needs no dir, copy it over unchanged):
+
+     {
+       "mcpServers": {
+         "n8n-instance": {
+           "command": "${command}",
+           "args": ["mcp", "connect"],
+           "env": { "N8N_DECANTER_DIR": "${rel}" }
+         }
+       }
+     }
+
+     N8N_DECANTER_DIR is what makes decanter find this dir at all — its config
+     search only walks UP from where it was started. It resolves against the
+     agent's working dir, so keep it repo-relative.
+
+${commandNote}
+
+     ${projectRoot}/opencode.json — the same two halves:
+
+     {
+       "mcp": {
+         "n8n-instance": {
+           "type": "local",
+           "command": ["${command}", "mcp", "connect"],
+           "environment": { "N8N_DECANTER_DIR": "${rel}" }
+         }
+       }
+     }
+
+     ${projectRoot}/.claude/settings.json — hooks and permissions, every path
+     and every relative glob prefixed with ${rel}:
+
+     {
+       "hooks": {
+         "PostToolUse": [
+           { "matcher": "Edit|Write|MultiEdit",
+             "hooks": [{ "type": "command", "command": "node ${rel}/.claude/hooks/verify.mjs" }] },
+           { "matcher": "mcp__n8n-instance__update_workflow",
+             "hooks": [{ "type": "command", "command": "node ${rel}/.claude/hooks/rename-refs.mjs" }] }
+         ],
+         "SessionStart": [
+           { "hooks": [{ "type": "command", "command": "node ${rel}/.claude/hooks/mcp-route-check.mjs" }] }
+         ]
+       },
+       "permissions": {
+         "deny": ["Read(${rel}/.env)", "Edit(${rel}/.env)", "Edit(**/.decanter.json)"]
+       }
+     }
+
+     Those two .env rules are the sharp end: a relative glob anchors at the
+     settings file that declares it, so copying Read(.env)/Edit(.env) up
+     verbatim would guard the ROOT's .env and silently stop protecting
+     ${rel}/.env — the credentials file. The allow list moves the same way:
+     Edit(workflows/**) becomes Edit(${rel}/workflows/**), Edit(shared/**)
+     becomes Edit(${rel}/shared/**). Everything else in
+     ${rel}/.claude/settings.json names no path and moves across verbatim —
+     copy it over too, the "push --force" Bash denies above all; the block
+     above is short because only the PATHS need rewriting, not because the
+     rest is optional.
+
+     Do not reach for \${CLAUDE_PROJECT_DIR}: it expands to the agent's project
+     root — the parent — so it reads as if it pointed here and never does.
+`;
+}
 /**
  * Modification-aware template refresh (dpkg conffile-style). First init copies
  * everything and records a baseline manifest. Re-init copies files new to the
@@ -321,16 +471,36 @@ async function refreshTemplate(srcDir, destDir, { force, protect, version, extra
         log.info(`copied template -> ${destDir}`);
     else
         log.info(`template up to date (${uptodate} unchanged${added.length ? `, ${added.length} added` : ""})`);
-    // Permission rules do not hot-load, and `init` is normally run from INSIDE the
-    // session they are meant to constrain — so the deny rules it just wrote (no
-    // edits to `.decanter.json`, no reads of `.env`, no `push --force`) are inert
-    // until that session restarts. The docs said "restart" only for the skills
-    // plugin, so the rules that actually gate the agent went unmentioned: the tool
-    // knew something the user needed and never said it. Only when the file is new
-    // — re-running init in a set-up dir must not nag.
-    const settingsFile = path.join(".claude", "settings.json");
-    if (added.includes(settingsFile)) {
-        log.info(style.dim("  agent permission rules take effect on the NEXT session — restart your agent (or /reload) so they apply"));
+    // None of the agent wiring hot-loads, and `init` is normally run from INSIDE
+    // the session it is meant to configure: permission rules (no edits to
+    // `.decanter.json`, no reads of `.env`, no `push --force`), the guarded
+    // `n8n-instance` MCP server, and the session hooks are all read at agent
+    // startup, so everything just written is inert for it. The docs said
+    // "restart" only for the skills plugin, so the wiring that actually gates the
+    // agent went unmentioned: the tool knew something the user needed and never
+    // said it. Only when a file is new — re-running init in a set-up dir must not
+    // nag. What "make it live" MEANS then splits on the layout (see below).
+    const agentFiles = [path.join(".claude", "settings.json"), ".mcp.json", "opencode.json"];
+    if (agentFiles.some((f) => added.includes(f))) {
+        // Plan 81: those same three files are the ones a nested sync dir never gets
+        // to use — an agent started at the surrounding project root loads none of
+        // them. So the note rides the same gate — it answers "here is what it takes
+        // to make what I just wrote live" — and a standalone dir (the shape this all
+        // assumed until now) stays completely silent.
+        const projectRoot = projectRootAbove(destDir);
+        // Plan 83: which line is TRUE depends on that same detection, so branch on
+        // it rather than printing "restart" unconditionally and appending the
+        // nested note. In a nested dir a restart is not merely insufficient, it is
+        // a dead end — startup discovery walks UP from the launch dir, so a session
+        // started at the root re-misses this file every time. A blind agent read
+        // the old unconditional line, concluded "restart", and had no next idea.
+        if (projectRoot === null) {
+            log.info(style.dim("  restart your agent (or /reload) before working here — the MCP servers, permission rules and hooks just scaffolded load at agent STARTUP, so this session is still unconfigured"));
+        }
+        else {
+            log.info(style.dim("  the MCP servers, permission rules and hooks just scaffolded load at agent STARTUP, from the dir the agent was STARTED in — so a restart makes them live only for an agent started in this dir. Started higher up, no restart ever loads them; use A or B below."));
+            log.info(nestedWiringNote(destDir, projectRoot));
+        }
     }
 }
 /**

package/dist/lib/simulate.mjs

@@ -758,8 +758,13 @@ export async function writeScenario(dir, opts, log) {
     else {
         log.ok(`scenario "${name}" written from ${seededFrom} -> ${rel} (${size}) — no gaps; replay with \`preflight --simulate --scenario ${name}\``);
     }
+    // Both remedies are named because "trim it" alone left the reader hunting for
+    // a flag that does not exist (the `--trim` idea was retired — the file is
+    // hand-editable by design, and `--scaffold` is the no-capture path). The
+    // window is real and worth stating: `scenario create` does NOT commit, so
+    // nothing is in history until the next pull/push sweeps the folder.
     if (bytes > 1024 * 1024) {
-        log.warn(`that scenario is ${size} and \`scenarios/\` is TRACKED — the next pull or push auto-commits the whole workflow folder, so it lands in git history permanently. Trim it before that, or keep the capture out of the scenario.`);
+        log.warn(`that scenario is ${size} and \`scenarios/\` is TRACKED — nothing is committed yet, but the next pull or push auto-commits the whole workflow folder and it lands in git history permanently. Before that: cut items out of "data.resultData.runData" by hand (the file is indented for exactly that), or re-create it with \`--scaffold\` instead of \`--execution\` — that carries no capture data at all, and you author the pins.`);
     }
     if (notExercised.length > 0) {
         log.info(`pinned ${notExercised.length} node${notExercised.length === 1 ? "" : "s"} to an EMPTY run — the capture never reached ${notExercised.length === 1 ? "it" : "them"}: ${notExercised.join(", ")}. That is what makes this scenario usable with \`test\` too; review the claim, and give one real output if a branch should have run.`);