v0.10.2

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, init and a new
  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.