n8n-decanter 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -7,6 +7,283 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-09-10
+
+### Added
+
+- **`N8N_DECANTER_AUTH=upstream` — an auth mode for instances behind a proxy
+  that attaches the n8n credentials itself.** In this mode decanter sends *no*
+  credential header at all: no `Authorization` on MCP, no `X-N8N-API-KEY` on
+  REST. That is the only thing that works — a proxy which adds its own key
+  **appends** it to whatever the client sent, and n8n answers `401` to the pair,
+  so the previous workaround (a placeholder value in `N8N_API_KEY`, to satisfy
+  the REST-verb guard) fails just like an empty one. `N8N_API_KEY` stops being
+  required, so `executions`, `data-tables` and `backup` work with no key of your
+  own. `mcp serve` drops the agent's session secret instead of swapping it for a
+  credential, so that local secret is never forwarded upstream. Set it in `.env`
+  or with the new **`init --auth upstream`**, which needs no token, no browser
+  and no TTY, and verifies both backends through the proxy. Existing credentials
+  are kept, ignored, and reported as unused. Any other value of the variable is
+  an error on every verb — a typo must not silently restore the header.
+
+### Fixed
+
+- **A REST 401 now says what is wrong.** It used to fall through to a bare
+  `401 Unauthorized` status line; it now names `N8N_API_KEY` as invalid for the
+  host (or, in upstream mode, points at the proxy).
+
+## [0.11.0] - 2026-09-03
+
+### Changed
+
+- **Breaking: a compiled `.ts` node now identifies itself on line 1, not on
+  its last line.** Open a bundled node in n8n and you used to see
+  `var __n8n_node = {}` followed by a few hundred lines of inlined helpers,
+  with the only trace of where it came from — `// @ts-n8n sha256:…` — at the
+  bottom, where nobody looks, naming *n8n* rather than the tool that put it
+  there. Push now writes one self-describing line where the editor opens:
+
+  ```js
+  // n8n-decanter · workflows/orders/code/normalize-lines.ts · do not edit here · @ts-n8n sha256:39af5ea6… · v0.10.1 ca3c201 2026-08-20T09:14Z
+  ```
+
+  **Nothing you already pushed has to change.** The old trailing form is read
+  forever and counts as fully in sync — `push`, `diff` and `preflight` say
+  nothing about it, and no write is queued just to relocate a marker. Nodes
+  adopt line 1 on their next real code push; there is no migration and no mass
+  re-push. The break runs the other way: **an older n8n-decanter will not
+  recognise a node pushed by this version** (its reader only looks at the last
+  line) and would pull such a node down as a plain `.js` file. Pre-1.0, that is
+  accepted rather than shimmed — upgrade the CLI everywhere that pulls the same
+  instance. The `@ts-n8n` token itself is unchanged, so one `grep -r @ts-n8n`
+  still finds both forms.
+
+- **The layout guard now rejects a marker line in a node source file in either
+  position, and in `.ts` files too** (it was trailing-only and `.js`-only).
+  That line is written by `push`; it is never source. Surfaces as before via
+  `preflight`'s `layout` check.
+
+### Fixed
+
+- **An auth failure no longer sends you in a circle, and throttling is no
+  longer called an expiry.** Every failed OAuth token refresh used to print
+  the same sentence — `MCP session expired … re-run: n8n-decanter init` — and
+  both halves of it could be wrong. `init` reuses `.decanter-auth.json`
+  whenever the host matches and never re-mints, so following the advice
+  re-probed with the same dead credentials and finished with "credentials
+  written anyway"; the only apparent way out was deleting a credential file
+  that was often perfectly fine. The three cases are now told apart:
+  - **the refresh token really is spent** (`invalid_grant`) — named as such,
+    and pointed at `init --reauth`, a command that actually re-mints;
+  - **n8n is rate-limiting** (429) — now **retried** with the same backoff the
+    MCP endpoint has always had (honouring `Retry-After`, five attempts), and
+    if it still fails it says the credentials are fine and never mentions
+    `init`. OAuth discovery got the same retry; both sat on bare `fetch` calls;
+  - **anything else** — the reason is named without a diagnosis, and nothing
+    is suggested for discarding.
+
+- **`init`'s closing connection check acts on a spent token instead of
+  shrugging.** It had the failure in hand and printed "credentials written
+  anyway". On a terminal it now offers to re-authorize on the spot; off one it
+  names `init --reauth`. Deliberately narrow — a network error, a 401, or a
+  403 "MCP access is disabled" still report as before, because none of them
+  says anything about your credentials.
+
+- **A successful first OAuth consent no longer warns "no MCP credentials
+  yet".** The check looked for a *pre-existing* auth file, so a browser
+  authorization that had just succeeded still ended with advice to re-run
+  `init` with a token.
+
+- **`<verb> --help` prints help instead of running the verb.** `--help` was
+  only recognised in argument slot 0, and every `--flag` is stripped before
+  dispatch, so `n8n-decanter init --help` was indistinguishable from a bare
+  `init` — a request for help **scaffolded a sync dir** into whatever directory
+  it was asked from. `--help` (and `-h`) now wins from any position, before any
+  verb, any namespace and the picker. It prints **that verb's own block** rather
+  than the whole listing, with only the notes that apply to it; `help <verb>` is
+  the same question, and a bare `help`/`--help` still prints everything.
+
+### Added
+
+- **`init` refuses to scaffold on top of a sync dir that already exists below
+  the target.** Run from the root of a bigger repo whose sync dir lives in
+  `n8n/`, `init` used to drop a second `decanter.config.json`, the template,
+  `workflows/`, `shared/`, `tsconfig.json` and the agent configs into the root.
+  It now looks a few levels down first and stops, naming the sync dir it found
+  and the `--dir=`/`N8N_DECANTER_DIR` form that addresses it from where you are
+  — the same advice every read verb already gives. A terminal gets it as a
+  question (`y` scaffolds anyway); a piped or flag-driven run exits 1 having
+  written nothing, not even the target directory. Re-running `init` **inside**
+  an existing sync dir is unchanged.
+
+- **The provenance line carries the build stamp, not just the hash**: the
+  node's source path relative to the sync dir, "do not edit here", the CLI
+  version, the git commit and the push time. The commit is HEAD at build time
+  and renders as `ca3c201+dirty` when the sync dir has uncommitted changes —
+  which, with `commitOnPush` on, is the normal case and reads correctly as
+  "built from working-tree state on top of `ca3c201`". Fields that cannot be
+  known (no git repo, unreadable `package.json`) are simply left out. **None of
+  it is hashed**, so a rename, a new commit or a CLI upgrade never makes a node
+  look changed — only the code below line 1 does.
+
+- **Credentials now resolve in a git worktree.** Both `.env` and
+  `.decanter-auth.json` are gitignored, so a fresh linked worktree had neither
+  and every credentialed verb died on `N8N_HOST must be set` — including the
+  `mcp connect` guard, which left agents in a worktree with no `n8n-instance`
+  tools at all. A worktree without its own credentials now reads the main
+  checkout's copies (same path, resolved from git's own worktree pointer, no
+  `git` subprocess). **A local file still wins**, so a worktree deliberately
+  aimed at another instance keeps its own, and nothing else is redirected —
+  `workflows/`, `.decanter.json` and `decanter.config.json` stay worktree-local.
+  For `.decanter-auth.json` the shared file is the only correct shape: the
+  refresh token is single-use and rotates, so **copying** it into a worktree
+  (what Claude Code's `.worktreeinclude` would do) forks it into two token
+  chains and kills the loser. New [Git
+  worktrees](/docs/concepts/configuration/#git-worktrees) section covers the two
+  remaining worktree gaps decanter cannot fix — a missing `node_modules` and the
+  per-path MCP approval — and the troubleshooting entry for missing
+  `n8n-instance` tools gained the worktree case.
+
+## [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

@@ -37,6 +37,10 @@ clean git diffs.
 - **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.
+- **The deployed node says where it came from** — a compiled `.ts` node opens
+  in n8n with its source path, "do not edit here", the content hash and the
+  build stamp (CLI version, git commit, push time) on line 1, so a bundle full
+  of inlined helpers is never a mystery artifact.
 - **Agent-native** — `init` scaffolds Claude Code / Cursor / Codex configs;
   `preflight --offline` and `node run` give agents a credential-free loop.
 - **Guarded agent access to n8n's MCP, wired by default** — the scaffolded
@@ -73,6 +77,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,8 +91,12 @@ 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`,
-`data-tables`, and `backup`. Details: [Installation](docs/getting-started/installation.md),
+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`. Behind a proxy that attaches the n8n credentials
+itself, `init --auth upstream` sets `N8N_DECANTER_AUTH=upstream` and decanter
+sends none of its own. Details: [Installation](docs/getting-started/installation.md),
 [init](docs/cli/init.md), [Configuration](docs/concepts/configuration.md).
 
 ## Works with n8n's official skills
@@ -109,7 +124,7 @@ Full flag reference: `n8n-decanter --help`, or the
 
 | Verb | What it does |
 |---|---|
-| `init [dir]` | Bootstrap a sync dir — OAuth/token, template, config, agent tooling (`--host`/`--token`/`--api-key` drive it non-interactively) |
+| `init [dir]` | Bootstrap a sync dir — OAuth/token, template, config, agent tooling (`--host`/`--token`/`--api-key` drive it non-interactively; `--reauth` re-consents after a spent token) |
 | `completion zsh\|bash` | Print a shell completion script |
 | `pull [workflow…]` | Code + structure snapshot → `workflows/<kebab>/` |
 | `push [workflow…]` | Push Code-node source to the workflow's **draft** |
@@ -132,6 +147,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/api.mjs

@@ -1,3 +1,4 @@
+import { AUTH_MODE_ENV } from "./config.mjs";
 /**
  * n8n public REST API client — since Plan 33 only the surfaces MCP cannot
  * serve: executions (no MCP read of full run data), data-table rows (MCP is
@@ -16,7 +17,19 @@
  * fold into `dataTable:read`, so a key that lists tables fine still 403s on
  * `/columns`.
  */
-function scopeHint(method, pathname) {
+function scopeHint(method, pathname, authMode) {
+    const scope = scopeName(method, pathname);
+    // In upstream mode the under-scoped key belongs to the proxy, so the scope
+    // name alone would send the reader to an `.env` that holds no key (Plan 92).
+    // Credentials mode keeps its exact previous wording.
+    if (authMode === "upstream") {
+        const where = "The key belongs to the upstream auth proxy, not to your .env — fix it where the proxy mints it.";
+        return scope === "" ? where : `${scope} ${where}`;
+    }
+    return scope === "" ? "Check the key's scopes in n8n → Settings → n8n API." : scope;
+}
+/** The scope a refused path needed, or `""` when the path is not one we map. */
+function scopeName(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}`;
@@ -32,16 +45,18 @@ function scopeHint(method, pathname) {
         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.";
+    return "";
 }
 export class N8nApi {
     #host;
     #apiKey;
     #timeoutMs;
-    constructor({ host, apiKey, requestTimeoutMs = 30_000 }) {
+    #authMode;
+    constructor({ host, apiKey, requestTimeoutMs = 30_000, authMode = "credentials" }) {
         this.#host = host;
         this.#apiKey = apiKey;
         this.#timeoutMs = requestTimeoutMs;
+        this.#authMode = authMode;
     }
     /**
      * Recent executions, newest first. Read-only by design — the executions API is
@@ -134,7 +149,10 @@ export class N8nApi {
             const res = await fetch(this.#host + pathname, {
                 method,
                 headers: {
-                    "X-N8N-API-KEY": this.#apiKey,
+                    // OMITTED, not blanked, in upstream mode: the proxy in front of n8n
+                    // APPENDS its key to whatever the client sent, and n8n answers 401 to
+                    // the pair (measured 2026-09-09). An empty header is still a header.
+                    ...(this.#authMode === "credentials" && { "X-N8N-API-KEY": this.#apiKey }),
                     accept: "application/json",
                     ...(body !== undefined && { "content-type": "application/json" }),
                 },
@@ -147,8 +165,18 @@ export class N8nApi {
                 // 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.
+                // 401 used to fall through to the bare status line below — the least
+                // helpful place to land, and the failure upstream mode makes most
+                // likely (a proxy that forwards but attaches nothing).
+                if (res.status === 401) {
+                    throw new Error(this.#authMode === "upstream"
+                        ? `${method} ${pathname} was rejected (401) — decanter sent no API key by design (${AUTH_MODE_ENV}=upstream); the upstream auth proxy did not attach a valid one`
+                        : `${method} ${pathname} was rejected (401) — N8N_API_KEY is not valid for ${this.#host} (n8n → Settings → n8n API)`);
+                }
                 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(this.#authMode === "upstream"
+                        ? `${method} ${pathname} was refused (403) — the API key the upstream auth proxy attaches is valid but lacks a scope. ${scopeHint(method, pathname, this.#authMode)}`
+                        : `${method} ${pathname} was refused (403) — N8N_API_KEY is valid but lacks a scope. ${scopeHint(method, pathname, this.#authMode)}`);
                 }
                 throw new Error(`${method} ${pathname} failed: ${res.status} ${res.statusText}\n${text.slice(0, 2000)}`);
             }