overview

n8n-decanter is built to let AI coding agents work on workflows safely. A scaffolded sync dir (init) contains everything an agent needs to behave:

• AGENTS.md — the tool-agnostic contract for the repo: how code is stored here (placeholders, code/, markers), the file-ownership rules, the rename checklist, and how to verify changes. Codex and opencode read it natively; Claude Code reads it through a one-line import in CLAUDE.md.
• Per-agent configs — Claude Code, Cursor, Codex, opencode — kept as thin pointers to AGENTS.md, so every agent follows the same rules.
• Guard hooks — on Claude Code and opencode, edits that would break a hard invariant are blocked before the write happens; a Claude Code PostToolUse hook runs preflight --offline after node edits. A second PostToolUse hook watches MCP update_workflow calls and speaks up when a renameNode leaves $('Old Name') references behind — n8n's rename rewrites the node name and connections only, so those refs are the caller's to repair (see pull). It scans for the old name rather than running preflight, because it fires before the background snapshot refresh, while every reference still resolves. The same rules are enforced by the CLI at push time regardless of who made the edit. Each hook finds the sync dir from its own installed location, so it behaves the same whether the agent was started in the sync dir or above it. On Claude Code these live in .claude/settings.json — project scope, meant to be committed, so everyone who clones the repo gets the same permissions and hooks. .claude/settings.local.json stays yours for machine-specific rules: permission lists merge across the two and a deny beats an allow, so your local file can add to the policy but cannot unblock what the project denies.

Restart the agent after init. MCP servers, permission rules and hooks are read at agent startup, and init is normally run from inside the very session it configures — so that session has no n8n-instance tools and no deny rules until it restarts (or /reloads). There is no hot-reload; init prints the reminder when it first scaffolds those files, and the scaffolded AGENTS.md tells the agent to ask for a restart rather than route around the missing guard.

But a restart is only half the diagnosis. ".mcp.json declares n8n-instance and the tools aren't there" has two causes, and they need opposite answers:

Cause	Symptom is	Fix
The wiring is new — init ran inside this very session	temporary	restart / /reload
The wiring is below the launch dir — nested sync dir, agent started at the repo root	permanent	start the agent in the sync dir, or wire the root (below)

The discriminator is a path comparison: is the .mcp.json in question below the directory the agent was started in? If it is, no restart can ever load it — startup only reads the launch dir and its ancestors (next section), so restarting reruns exactly the discovery that already missed the file. Advising a restart there costs the user a session and teaches them nothing. The scaffolded AGENTS.md carries both branches, so an agent that reads it can tell them apart; init names the one you are actually in when it scaffolds.

Where the agent wiring loads from

init scaffolds .mcp.json, .claude/settings.json and the hook scripts into the sync dir. When the sync dir is where you start the agent, that is the end of the story. When it is a subfolder of a bigger repo, what actually loads depends on where the agent was started — and the files disagree about it (matrix verified against Claude Code 2.1.x):

Agent started at	<syncdir>/.mcp.json	<syncdir>/.claude/settings.json	repo root's .claude/settings.json
the repo root	not loaded	not loaded	loaded
the sync dir	loaded (merged with the repo root's)	loaded	not loaded