n8n-decanter 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-07-20
+
+### Changed
+
+- **Refreshed the scaffolded agent guide (`AGENTS.md`).** It now steers agents
+  to the `rename` and `duplicate` verbs (rename led with the command instead of
+  a hand-edit checklist, `duplicate` added to the new-workflow and command
+  taxonomies), opens with a compact "short version" of the hard invariants,
+  points at `n8n-globals.d.ts` as the authoritative globals list instead of an
+  inline copy that could drift, and drops a stale reference to a non-existent
+  `SCAFFOLD.md`.
+
+## [0.4.0] - 2026-07-20
+
+### Added
+
+- **`add` verb** — `n8n-decanter <ref> add "<Node name>" [--ts]` scaffolds a
+  Code node into a pulled workflow in one offline step: it mints the node id,
+  writes the `code/` source file (kebab-case, with the `-<id8>` collision
+  suffix), adds the node object plus its `//@file:` placeholder, and registers
+  it in `.decanter.json`, then re-checks the folder. The node lands
+  **disconnected** (wire it in the editor); `--ts` scaffolds a `.ts` source.
+  The next `push` propagates it.
+- **`duplicate` verb** — `n8n-decanter <ref> duplicate ["<new name>"]` clones an
+  already-pulled workflow into a **new workflow on the server** and pulls the
+  copy. The clone carries the repo's current content (placeholders
+  reconstituted from `code/`, `.ts` nodes compiled), is born **unpublished**,
+  and defaults its name to `"<name> (copy)"`. The source folder and the source
+  remote workflow are left untouched.
+
+### Removed
+
+- **Breaking: the `uuid` verb is gone.** Its only job was minting a node id for
+  hand-adding a Code node — now `add` does the whole scaffold (id included) in
+  one guard-checked step, so a bare id generator is redundant. Use
+  `n8n-decanter <ref> add "<Node name>"` instead.
+
+## [0.3.4] - 2026-07-20
+
+### Added
+
+- **Modification-aware template refresh.** `init` now records a copy-time
+  baseline of every template file in a git-tracked `.decanter-template.json`
+  manifest. Re-running `init` uses it to refresh files you haven't touched
+  (after a confirm), pull in files newly added to the template, and **leave
+  your local edits alone** — reporting them as drift instead of silently
+  keeping the old version. Files that changed in both the template and your
+  copy are flagged as conflicts and left untouched.
+
+### Changed
+
+- **Re-running `init` is no longer all-or-nothing.** Previously the default
+  refused to overwrite anything and `--force` clobbered every template file.
+  Now the default is modification-aware (see above); `--force` is unchanged —
+  the escape hatch that overwrites everything, now noting which files "had
+  local changes" as it goes.
+
+## [0.3.3] - 2026-07-20
+
+### Changed
+
+- **Interactive picker got a visual refresh.** Each workflow row now leads with
+  a `●` (pulled) / `○` (not pulled) status glyph and the ids line up in an
+  aligned column; each stage carries a short title (`pick a workflow` over the
+  list, the workflow name over its verb menu). The state distinction is now
+  carried by the glyph *shape*, so the per-row `(not pulled)` words are gone —
+  the key is stated once in a footer legend (`● pulled · ○ not pulled`), and
+  the output stays legible under `NO_COLOR`. Behavior (filtering, navigation,
+  verbs) is unchanged.
+
 ## [0.3.2] - 2026-07-20
 
 ### Fixed

package/README.md

@@ -4,12 +4,17 @@
 [![npm](https://img.shields.io/npm/v/n8n-decanter)](https://www.npmjs.com/package/n8n-decanter)
 [![Docs](https://img.shields.io/badge/docs-website-blue.svg)](https://buttjer.github.io/n8n-decanter/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![vibe coded](https://img.shields.io/badge/vibe%20coded-with%20Claude%20Code-8A2BE2)](https://claude.com/claude-code)
 
 **Work on n8n like a codebase — built for AI coding agents.**
 
 **Pre-1.0 — breaking changes to the data model or CLI may ship in minor
 versions until v1.0.**
 
+> **Built with AI agents.** Much of this codebase was written by Claude Code
+> under human review. It's tested (CI + a real-n8n integration suite) and used
+> in earnest, but treat pre-1.0 the way the version implies.
+
 n8n-decanter syncs your n8n instance into a git-friendly, folder-per-workflow
 layout: every Code node's source becomes its own `.js` or `.ts` file,
 editable in your IDE or by your agent, and pushed back through the n8n API.
@@ -64,9 +69,11 @@ directly, no build needed.
 
 `init` copies everything in [template/](template/); files named `X.example`
 land as `X` (the suffix keeps agent configs inert in this repo, live in the
-target). It never overwrites existing files (safe to re-run) unless you pass
-`--force`, which re-copies template files over existing ones (`.env` is never
-touched by it). When `.env` already holds both values, init skips the
+target). Re-running `init` is safe and **modification-aware**: it refreshes
+template files you haven't edited (after a confirm), leaves your local changes
+alone (reporting them as drift), and picks up files new to the template —
+tracked via a `.decanter-template.json` baseline. `--force` is the escape hatch
+that overwrites everything (`.env` is never touched). When `.env` already holds both values, init skips the
 prompts and reuses them — edit or delete `.env` to change credentials. It
 also does a best-effort credential check. Alternatively set up manually: `cp .env.example .env` and
 fill it in. Then add workflow ids to `decanter.config.json`:
@@ -98,7 +105,7 @@ PostToolUse hook that runs `check` after node edits. Verification routes through
 the CLI, so `n8n-decanter` must be on the sync dir's PATH: install it globally
 (`npm i -g n8n-decanter`), add it to the sync dir's `devDependencies`, or
 `npm link` a git checkout (build it first — Node won't type-strip `.mts`
-under `node_modules`). The verbs `check`, `run`, and `uuid` are fully
+under `node_modules`). The verbs `check`, `run`, `rename`, and `add` are fully
 offline (no credentials, no network).
 
 ## Commands
@@ -118,11 +125,13 @@ n8n-decanter [ref...] status [--diff]   # drift report (--diff: line diffs);
 n8n-decanter [ref...] check         # offline layout-compliance + typecheck
 n8n-decanter <ref> rename "<old node>" "<new node>"   # rename a node everywhere
 n8n-decanter <ref> rename --workflow "<new name>"     # rename the workflow
+n8n-decanter <ref> add "<Node name>" [--ts]           # scaffold a Code node (offline)
 n8n-decanter [ref] watch            # push a workflow's nodes on save
                                     #   (+ browser live-reload, opt-in)
 n8n-decanter [ref...] publish       # take the draft(s) live
 n8n-decanter [ref...] unpublish     #   (unpublish returns to draft-only)
 n8n-decanter create "<name>"        # create a blank workflow, then pull it
+n8n-decanter <ref> duplicate ["<new name>"]   # clone a workflow, then pull it
 n8n-decanter <ref> delete [--force]   # delete a workflow from the server
                                     #   (y/N confirm; --force skips it; the
                                     #   local folder is left untouched)
@@ -136,7 +145,6 @@ n8n-decanter list [--remote]        # pulled workflows: name, id, folder
                                     #   (--remote adds unpulled ones)
 n8n-decanter completion zsh|bash    # print a shell completion script
 n8n-decanter <node-file> run [fixture.json] [--allow-env]   # run a node offline, print items
-n8n-decanter uuid [count]           # lowercase v4 UUID(s) for new node ids
 ```
 
 A workflow `<ref>` is its **id, its workflow/folder name, or a unique name

package/dist/lib/add.mjs

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { findWorkflowDir, readState, writeState } from "./state.mjs";
+import { CODE_DIR, CODE_NODE_TYPE, FILE_PLACEHOLDER_PREFIX, kebabCase, stableWorkflowJson } from "./util.mjs";
+import { validateWorkflowDir } from "./validate.mjs";
+/**
+ * Starter source for a freshly scaffolded Code node: valid, self-contained
+ * (no `$('…')` references, so it lands compliant), and it typechecks under the
+ * n8n ambient globals — the same body for `.js` and `.ts`.
+ */
+const DEFAULT_SOURCE = `// New Code node — runs once for all items. Edit me, then push.
+// See https://docs.n8n.io/code/ for the Code node API.
+for (const item of $input.all()) {
+  item.json.myNewField = 1;
+}
+
+return $input.all();
+`;
+/** Rightmost node's x + a step, so a scaffolded node doesn't stack on another. */
+function nextPosition(nodes) {
+    let maxX = 0;
+    for (const node of nodes) {
+        const pos = node.position;
+        if (Array.isArray(pos) && typeof pos[0] === "number")
+            maxX = Math.max(maxX, pos[0]);
+    }
+    return [maxX + 220, 0];
+}
+/**
+ * Scaffold a `n8n-nodes-base.code` node into a pulled workflow in one atomic,
+ * guard-checked step (offline; `push` propagates). Mints a v4 uuid, writes the
+ * kebab-case source file under `code/` (sharing pull/rename's `-<id8>` collision
+ * suffix), appends the node object (default parameters, `mode:
+ * runOnceForAllItems`, a `//@file:` placeholder) to `workflow.json`, and
+ * registers it in `.decanter.json`. **No connections are wired** — the node
+ * lands disconnected but compliant; wiring stays in the editor. Re-validates
+ * afterwards and fails loudly on any violation, exactly like `rename`.
+ */
+export function addCodeNode(root, id, nodeName, { ts = false } = {}, log) {
+    nodeName = nodeName.trim();
+    if (!nodeName)
+        throw new Error("node name must not be empty");
+    const dir = findWorkflowDir(root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${root} — pull it first`);
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile))
+        throw new Error(`missing workflow.json in ${dir} — pull first`);
+    let wf;
+    try {
+        wf = JSON.parse(readFileSync(wfFile, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${wfFile}: invalid JSON (${err.message})`);
+    }
+    if (wf.nodes.some((n) => n.name === nodeName))
+        throw new Error(`a node named "${nodeName}" already exists in "${wf.name}"`);
+    const nodeId = randomUUID();
+    const ext = ts ? ".ts" : ".js";
+    mkdirSync(path.join(dir, CODE_DIR), { recursive: true });
+    let base = kebabCase(nodeName);
+    if (existsSync(path.join(dir, CODE_DIR, `${base}${ext}`))) {
+        base = `${base}-${nodeId.slice(0, 8)}`;
+        if (existsSync(path.join(dir, CODE_DIR, `${base}${ext}`))) {
+            throw new Error(`cannot add "${nodeName}": both kebab-case targets exist (${CODE_DIR}/${base}${ext})`);
+        }
+    }
+    const file = `${CODE_DIR}/${base}${ext}`;
+    writeFileSync(path.join(dir, file), DEFAULT_SOURCE);
+    const node = {
+        id: nodeId,
+        name: nodeName,
+        type: CODE_NODE_TYPE,
+        typeVersion: 2,
+        position: nextPosition(wf.nodes),
+        parameters: { mode: "runOnceForAllItems", jsCode: FILE_PLACEHOLDER_PREFIX + file },
+    };
+    wf.nodes.push(node);
+    writeFileSync(wfFile, stableWorkflowJson(wf));
+    const state = readState(dir);
+    if (state) {
+        state.nodes[nodeId] = { file };
+        writeState(dir, state);
+    }
+    log.info(`added Code node "${nodeName}" (${nodeId}) -> ${file} — disconnected; wire it in the editor, then push to propagate`);
+    const { errors } = validateWorkflowDir(dir);
+    if (errors.length > 0) {
+        throw new Error(`add left the workflow non-compliant — files were written, inspect (git diff) and fix:\n${errors.map((e) => `  ${e}`).join("\n")}`);
+    }
+}

package/dist/lib/api.mjs

@@ -49,14 +49,15 @@ export class N8nApi {
         return this.#request("PUT", `/api/v1/workflows/${encodeURIComponent(id)}`, body);
     }
     /**
-     * Create a blank draft on the server (n8n 2.x `POST /workflows`). The minimal
-     * accepted body is name + empty nodes/connections/settings (verified against
-     * 2.30.7 — name-only is rejected). Born **unpublished** (`active:false`); the
-     * caller pulls the returned id so the folder + state land. `createWorkflow` is
-     * the shared entry point Plan 21's `duplicate` reuses.
+     * Create a workflow on the server (n8n 2.x `POST /workflows`). The required
+     * fields are name + nodes/connections/settings (verified against 2.30.7 —
+     * name-only is rejected), so `create` posts empty collections while
+     * `duplicate` posts the cloned nodes/connections. Born **unpublished**
+     * (`active:false`); the caller pulls the returned id so the folder + state
+     * land. Shared by `create` (blank) and `duplicate` (Plan 21).
      */
-    async createWorkflow(name) {
-        return this.#request("POST", "/api/v1/workflows", { name, nodes: [], connections: {}, settings: {} });
+    async createWorkflow(body) {
+        return this.#request("POST", "/api/v1/workflows", body);
     }
     /** Take the draft live (n8n 2.x publish). Idempotent server-side; returns the workflow. */
     async activateWorkflow(id) {

package/dist/lib/init.mjs

@@ -4,6 +4,8 @@ import { fileURLToPath } from "node:url";
 import { parseEnvFile } from "./config.mjs";
 import { createPrompt } from "./prompt.mjs";
 import { style } from "./style.mjs";
+import { classifyTemplateFile, MANIFEST_FILE, readManifest, writeManifest } from "./template.mjs";
+import { sha256 } from "./util.mjs";
 /**
  * Nearest ancestor of `startDir` holding a package.json — the package root.
  * Works from the checkout (lib/ → repo root) *and* from the published build
@@ -52,30 +54,151 @@ export function printBanner(log) {
         console.log(style.red(row.slice(0, 6)) + style.bold(row.slice(6)));
     console.log(style.dim(`n8n workflows ⇄ agentic code · v${version}`));
 }
-function copyTemplate(srcDir, destDir, { force = false, protect = new Set() } = {}) {
-    const overwritten = [];
-    const walk = (src, dest, rel) => {
-        mkdirSync(dest, { recursive: true });
+/**
+ * Classify every template file against the target dir and the copy-time
+ * baseline manifest. Pure scan — no files are written.
+ */
+function scanTemplate(srcDir, destDir, manifest, protect) {
+    const entries = [];
+    const walk = (src, rel) => {
         for (const entry of readdirSync(src, { withFileTypes: true })) {
             const srcPath = path.join(src, entry.name);
             if (entry.isDirectory()) {
-                walk(srcPath, path.join(dest, entry.name), path.join(rel, entry.name));
+                walk(srcPath, path.join(rel, entry.name));
                 continue;
             }
             const name = entry.name.endsWith(".example") && entry.name !== ".example"
                 ? entry.name.slice(0, -".example".length)
                 : entry.name;
-            const destPath = path.join(dest, name);
+            const materializedRel = path.join(rel, name);
+            const destPath = path.join(destDir, materializedRel);
+            if (protect.has(destPath))
+                continue; // .env: written separately, never manifest-tracked
+            const templateHash = sha256(readFileSync(srcPath, "utf8"));
             const exists = existsSync(destPath);
-            if (exists && (!force || protect.has(destPath)))
-                continue;
-            copyFileSync(srcPath, destPath);
-            if (exists)
-                overwritten.push(path.join(rel, name));
+            const targetHash = exists ? sha256(readFileSync(destPath, "utf8")) : undefined;
+            const manifestHash = manifest[materializedRel];
+            entries.push({
+                rel: materializedRel,
+                srcPath,
+                destPath,
+                templateHash,
+                targetHash,
+                outcome: classifyTemplateFile({ exists, targetHash, templateHash, manifestHash }),
+            });
         }
     };
-    walk(srcDir, destDir, "");
-    return overwritten;
+    walk(srcDir, "");
+    return entries;
+}
+function copyEntry(entry) {
+    mkdirSync(path.dirname(entry.destPath), { recursive: true });
+    copyFileSync(entry.srcPath, entry.destPath);
+}
+/**
+ * Modification-aware template refresh (dpkg conffile-style). First init copies
+ * everything and records a baseline manifest. Re-init copies files new to the
+ * template, offers to refresh files the user hasn't touched (pristine), and
+ * leaves locally-modified files alone while reporting the drift. `--force` is
+ * the escape hatch: it overwrites every template file regardless.
+ */
+async function refreshTemplate(srcDir, destDir, { force, protect, version }, log) {
+    const manifest = readManifest(destDir);
+    const firstInit = !existsSync(path.join(destDir, MANIFEST_FILE));
+    const entries = scanTemplate(srcDir, destDir, manifest.files, protect);
+    const nextFiles = {};
+    if (force) {
+        let anyExisting = false;
+        for (const e of entries) {
+            const changed = e.targetHash !== undefined && e.targetHash !== e.templateHash;
+            if (e.targetHash !== undefined)
+                anyExisting = true;
+            copyEntry(e);
+            nextFiles[e.rel] = e.templateHash;
+            if (e.targetHash !== undefined)
+                log.warn(`--force: overwrote ${e.rel} with the template version${changed ? " (had local changes)" : ""}`);
+        }
+        writeManifest(destDir, { version, files: nextFiles });
+        log.info(anyExisting ? `reset template -> ${destDir}` : `copied template -> ${destDir}`);
+        return;
+    }
+    const added = [];
+    const pending = [];
+    const modified = [];
+    const conflicts = [];
+    let uptodate = 0;
+    for (const e of entries) {
+        switch (e.outcome) {
+            case "added":
+                copyEntry(e);
+                nextFiles[e.rel] = e.templateHash;
+                added.push(e.rel);
+                break;
+            case "converged":
+                nextFiles[e.rel] = e.templateHash; // adopt: on-disk copy now equals the template
+                break;
+            case "adopt":
+                nextFiles[e.rel] = e.targetHash; // legacy dir: trust the on-disk copy as the baseline
+                break;
+            case "update":
+                pending.push(e);
+                nextFiles[e.rel] = manifest.files[e.rel]; // provisional; set to templateHash if applied
+                break;
+            case "drift-modified":
+                modified.push(e.rel);
+                nextFiles[e.rel] = manifest.files[e.rel];
+                break;
+            case "drift-conflict":
+                conflicts.push(e.rel);
+                nextFiles[e.rel] = manifest.files[e.rel];
+                break;
+            case "uptodate":
+                uptodate++;
+                nextFiles[e.rel] = e.templateHash;
+                break;
+        }
+    }
+    // On first init everything is "added" — the single "copied template" line
+    // below says it; only call out files the template *gained* on a re-init.
+    if (!firstInit)
+        for (const rel of added)
+            log.info(`added ${rel} from the template`);
+    if (pending.length > 0) {
+        let apply = false;
+        if (process.stdin.isTTY) {
+            const rl = createPrompt();
+            try {
+                log.info(`${pending.length} template file(s) have newer versions and are unmodified locally:`);
+                for (const e of pending)
+                    log.info(`  ${e.rel}`);
+                apply = (await rl.question(`Update ${pending.length} pristine file(s) to the template version? [y/N] `)).trim().toLowerCase().startsWith("y");
+            }
+            finally {
+                rl.close();
+            }
+        }
+        else {
+            log.warn(`${pending.length} pristine template file(s) have updates available — re-run init interactively or with --force to apply: ${pending.map((e) => e.rel).join(", ")}`);
+        }
+        if (apply) {
+            for (const e of pending) {
+                copyEntry(e);
+                nextFiles[e.rel] = e.templateHash;
+            }
+            log.info(`updated ${pending.length} file(s) from the template`);
+        }
+    }
+    if (modified.length > 0)
+        log.warn(`left unchanged (modified locally): ${modified.join(", ")}`);
+    if (conflicts.length > 0)
+        log.warn(`left unchanged (changed in both the template and your copy — resolve manually or --force to reset): ${conflicts.join(", ")}`);
+    writeManifest(destDir, { version, files: nextFiles });
+    // "copied" only when the whole tree was genuinely fresh; a dir that pre-dates
+    // the manifest (files present, no baseline) adopts in place — report as such.
+    if (added.length === entries.length)
+        log.info(`copied template -> ${destDir}`);
+    else
+        log.info(`template up to date (${uptodate} unchanged${added.length ? `, ${added.length} added` : ""})`);
 }
 /** Interactive bootstrap: prompt for credentials, write .env, copy template/. */
 export async function init(targetDir, { force = false } = {}, log) {
@@ -107,16 +230,14 @@ export async function init(targetDir, { force = false } = {}, log) {
         writeFileSync(envFile, `N8N_HOST=${host}\nN8N_API_KEY=${apiKey}\n`);
         log.info(`wrote ${envFile}`);
     }
-    // Copy the template completely (whatever it contains, recursively).
-    // Default: never overwrite files that already exist in the target.
-    // --force re-copies template files over existing ones (.env excepted —
-    // it was just written with real credentials).
+    // Copy the template (whatever it contains, recursively), recording a
+    // per-file baseline in .decanter-template.json. Re-init is modification-aware:
+    // pristine files can be refreshed (after confirm), locally-edited files are
+    // left alone with drift reported, and `--force` overwrites everything. `.env`
+    // is protected (just written with real credentials) and never tracked.
     // Files named `X.example` are inert in this repo (so agent tooling ignores
     // them while working on the CLI itself) and materialize as `X` in the target.
-    const overwritten = copyTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]) });
-    log.info(`copied template -> ${dir}`);
-    for (const rel of overwritten)
-        log.warn(`--force: overwrote ${rel} with the template version`);
+    await refreshTemplate(TEMPLATE_DIR, dir, { force, protect: new Set([envFile]), version: cliVersion() }, log);
     const configFile = path.join(dir, "decanter.config.json");
     if (!existsSync(configFile)) {
         writeFileSync(configFile, JSON.stringify({ root: "./workflows", workflows: [] }, null, 2) + "\n");

package/dist/lib/lifecycle.mjs

@@ -1,8 +1,11 @@
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { createPrompt } from "./prompt.mjs";
 import { pullWorkflow } from "./pull.mjs";
+import { assertCompliant, buildNodeCode } from "./push.mjs";
 import { findWorkflowDir } from "./state.mjs";
-import { publicationState } from "./util.mjs";
+import { isJsCodeNode, placeholderFile, publicationState, sanitizeForPut } from "./util.mjs";
+import { validateWorkflowDir } from "./validate.mjs";
 /**
  * `publish` — take an unpublished draft live (n8n 2.x activate). A workflow
  * that is already published is a no-op-with-a-note, not an error: a push to a
@@ -39,13 +42,47 @@ export async function unpublishWorkflow(api, id, log) {
  * Plan 21's `duplicate`.
  */
 export async function createWorkflow(api, config, name, log) {
-    const created = await api.createWorkflow(name);
+    const created = await api.createWorkflow({ name, nodes: [], connections: {}, settings: {} });
     const id = created.id;
     log.ok(`created "${name}" (${id}) on the server — unpublished draft`);
     const { dir } = await pullWorkflow(api, config.root, id, { commitOnPull: config.commitOnPull }, log);
     log.info(`edit code/, push, then "publish" to go live`);
     return { dir, id };
 }
+/**
+ * `<ref> duplicate ["<new name>"]` — clone an already-pulled workflow into a
+ * brand-new remote one, then pull the copy. The body is assembled from the
+ * **local** folder exactly as `push` does (placeholders reconstituted from
+ * `code/`, `.ts` nodes compiled), so the clone carries the repo's current
+ * content — even edits not yet pushed to the source. The default name is
+ * `"<name> (copy)"` (matching the n8n UI). Born **unpublished**, like any
+ * create; the source folder and the source remote workflow are left untouched.
+ * Pull-first is preserved: the copy is born server-side and materialized via a
+ * fresh pull. Reuses `api.createWorkflow` (Plan 20) with a full body.
+ */
+export async function duplicateWorkflow(api, config, id, newName, log) {
+    const dir = findWorkflowDir(config.root, id, log);
+    if (!dir)
+        throw new Error(`workflow ${id} not found under ${config.root} — pull it first`);
+    assertCompliant(validateWorkflowDir(dir), log, `"${path.basename(dir)}"`);
+    const wf = JSON.parse(readFileSync(path.join(dir, "workflow.json"), "utf8"));
+    const sourceName = wf.name;
+    for (const node of wf.nodes) {
+        if (!isJsCodeNode(node))
+            continue;
+        const file = placeholderFile(node);
+        if (file === null)
+            continue;
+        node.parameters.jsCode = (await buildNodeCode(dir, file, log)).jsCode;
+    }
+    const body = sanitizeForPut(wf);
+    body.name = newName?.trim() || `${sourceName} (copy)`;
+    const created = await api.createWorkflow(body);
+    log.ok(`duplicated "${sourceName}" -> "${body.name}" (${created.id}) on the server — unpublished draft`);
+    const { dir: newDir } = await pullWorkflow(api, config.root, created.id, { commitOnPull: config.commitOnPull }, log);
+    log.info(`edit code/, push, then "publish" to go live`);
+    return { dir: newDir, id: created.id };
+}
 /**
  * `<ref> delete` — hard-delete a workflow from the server, deliberately.
  * Destructive and outward-facing, so consent is explicit: on a TTY a `y/N`

package/dist/lib/picker.mjs

@@ -103,7 +103,17 @@ const LIST_HEIGHT = 10;
 // loads: light-gray blocks shaped like "name  id", varied widths on purpose.
 const SKELETON_WIDTHS = [[14, 8], [9, 8], [17, 8]];
 const truncate = (text, max) => (text.length > max ? text.slice(0, max - 1) + "…" : text);
-function renderLines(state) {
+/** Filled = pulled, hollow = not pulled — differs by *shape*, so the state
+ * survives NO_COLOR/monochrome without the old trailing `(not pulled)` words. */
+const statusGlyph = (pulled) => (pulled ? style.green("●") : style.yellow("○"));
+/**
+ * Pure view: `PickerState` → the lines to paint. Fed the docs-site
+ * simulation's polish (Plan 23) — an aligned id column, `●`/`○` shape-based
+ * status glyphs, and a per-stage title. Color is decoration only; every
+ * distinction is carried by shape or words too, so `NO_COLOR` output stays
+ * legible. Exported for the render unit tests (no TTY needed).
+ */
+export function renderLines(state) {
     const d = style.dim;
     const lines = [];
     if (state.stage === "verb") {
@@ -116,26 +126,34 @@ function renderLines(state) {
         return lines;
     }
     const filtered = filterEntries(state.entries, state.query);
-    lines.push(`${style.bold("?")} ${state.query === "" ? d("type to filter") : state.query}`);
+    lines.push(style.bold("pick a workflow"));
+    lines.push(`${d("?")} ${state.query === "" ? d("type to filter") : state.query}`);
     const { start, end } = visibleWindow(filtered.length, state.cursor, LIST_HEIGHT);
+    // Pad names to the widest one in the current window so the dim ids line up.
+    let nameWidth = 0;
+    for (let i = start; i < end; i++)
+        nameWidth = Math.max(nameWidth, truncate(filtered[i].name, 48).length);
     for (let i = start; i < end; i++) {
         const e = filtered[i];
         const pointer = i === state.cursor ? style.green("❯") : " ";
-        const name = e.pulled ? style.green(truncate(e.name, 48)) : style.yellow(truncate(e.name, 48));
-        // "(not pulled)" in words, not only color — NO_COLOR/monochrome safety
-        lines.push(`${pointer} ${name}  ${d(e.id)}${e.pulled ? "" : `  ${d("(not pulled)")}`}`);
+        const display = truncate(e.name, 48);
+        const name = (e.pulled ? style.green(display) : style.yellow(display)) + " ".repeat(nameWidth - display.length);
+        lines.push(`${pointer} ${statusGlyph(e.pulled)} ${name}  ${d(e.id)}`);
     }
     if (filtered.length === 0 && !state.loadingRemote)
         lines.push(d(state.entries.length === 0 ? "  nothing pulled yet" : "  no match"));
     if (end < filtered.length)
         lines.push(d(`  … ${filtered.length - end} more`));
     if (state.loadingRemote) {
-        for (const [nameWidth, idWidth] of SKELETON_WIDTHS) {
-            lines.push(`  ${d("░".repeat(nameWidth))}  ${d("░".repeat(idWidth))}`);
+        for (const [nameW, idWidth] of SKELETON_WIDTHS) {
+            lines.push(`  ${d("░".repeat(nameW))}  ${d("░".repeat(idWidth))}`);
         }
     }
     if (state.notice)
         lines.push(d(state.notice));
+    // Legend states the glyph key once (footer), not on every row.
+    if (filtered.length > 0)
+        lines.push(d(`${statusGlyph(true)} pulled · ${statusGlyph(false)} not pulled`));
     const enterHint = filtered[state.cursor]?.pulled === false ? "enter pull" : "enter select";
     lines.push(d(`↑↓ move · ${enterHint} · esc quit`));
     return lines;

package/dist/lib/push.mjs

@@ -7,7 +7,7 @@ import { findWorkflowDir, readState, writeState } from "./state.mjs";
 import { isJsCodeNode, placeholderFile, publicationState, sanitizeForPut, sha256, splitMarker, withMarker, workflowStructureHash, } from "./util.mjs";
 import { validateNodeFile, validateWorkflowDir } from "./validate.mjs";
 /** Layout-compliance gate: warnings pass through, errors abort the push. */
-function assertCompliant({ errors, warnings }, log, what) {
+export function assertCompliant({ errors, warnings }, log, what) {
     for (const w of warnings)
         log.warn(w);
     if (errors.length === 0)

package/dist/lib/template.mjs

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Sync-dir manifest recording the `sha256:` of each template file *as copied*
+ * by `init` (dpkg conffile-style baseline). Comparing this baseline against the
+ * file currently on disk and the current template lets re-init tell a file the
+ * user edited from a pristine one, so template improvements can be pulled in
+ * without clobbering local changes. Git-tracked (shared across a team).
+ */
+export const MANIFEST_FILE = ".decanter-template.json";
+/** Tolerant read: a missing or corrupt manifest is an empty baseline. */
+export function readManifest(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(path.join(dir, MANIFEST_FILE), "utf8"));
+        const files = raw.files && typeof raw.files === "object" ? raw.files : {};
+        return { version: typeof raw.version === "string" ? raw.version : "0.0.0", files };
+    }
+    catch {
+        return { version: "0.0.0", files: {} };
+    }
+}
+export function writeManifest(dir, manifest) {
+    // sorted keys → stable, review-friendly diffs
+    const files = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b)));
+    writeFileSync(path.join(dir, MANIFEST_FILE), JSON.stringify({ version: manifest.version, files }, null, 2) + "\n");
+}
+/** True when a sync dir already has a manifest (i.e. this is a re-init). */
+export function hasManifest(dir) {
+    return existsSync(path.join(dir, MANIFEST_FILE));
+}
+export function classifyTemplateFile(input) {
+    const { exists, targetHash, templateHash, manifestHash } = input;
+    if (!exists)
+        return "added";
+    if (manifestHash === undefined)
+        return targetHash === templateHash ? "uptodate" : "adopt";
+    const pristine = targetHash === manifestHash;
+    if (templateHash === manifestHash)
+        return pristine ? "uptodate" : "drift-modified";
+    if (pristine)
+        return "update";
+    if (targetHash === templateHash)
+        return "converged";
+    return "drift-conflict";
+}

package/dist/n8n-decanter.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { addCodeNode } from "./lib/add.mjs";
 import { N8nApi } from "./lib/api.mjs";
 import { loadConfig } from "./lib/config.mjs";
 import { cleanExecutions, fetchExecutionById, fetchExecutions } from "./lib/executions.mjs";
 import { init, printBanner } from "./lib/init.mjs";
-import { createWorkflow, deleteWorkflow, publishWorkflow, unpublishWorkflow } from "./lib/lifecycle.mjs";
+import { createWorkflow, deleteWorkflow, duplicateWorkflow, publishWorkflow, unpublishWorkflow } from "./lib/lifecycle.mjs";
 import { mergeRemote, runPicker } from "./lib/picker.mjs";
 import { pullWorkflow } from "./lib/pull.mjs";
 import { pushWorkflow } from "./lib/push.mjs";
@@ -44,7 +44,8 @@ const usage = () => {
                                    ${d("choose a workflow, then verbs — stays in")}
                                    ${d("the workflow's menu until Esc")}
   ${b("n8n-decanter init")} [dir] [--force]   ${d("interactive setup: .env, starter files, config")}
-                                   ${d("(--force re-copies template files over existing ones)")}
+                                   ${d("(re-init refreshes unedited template files, keeps")}
+                                   ${d("your edits; --force overwrites everything)")}
   ${b("n8n-decanter")} [ref...] ${b("pull")}       ${d("pull workflows (default: all in decanter.config.json)")}
   ${b("n8n-decanter")} [ref...] ${b("push")} [--force] [--no-typecheck]
   ${b("n8n-decanter")} [ref...] ${b("status")} [--diff]   ${d("drift report (--diff shows line diffs);")}
@@ -52,6 +53,8 @@ const usage = () => {
   ${b("n8n-decanter")} [ref...] ${b("check")} [--no-typecheck]   ${d("offline layout-compliance check")}
   ${b("n8n-decanter")} <ref> ${b("rename")} "<old node>" "<new node>"   ${d("rename a node everywhere (offline)")}
   ${b("n8n-decanter")} <ref> ${b("rename")} --workflow "<new name>"     ${d("rename the workflow itself")}
+  ${b("n8n-decanter")} <ref> ${b("add")} "<Node name>" [--ts]   ${d("scaffold a disconnected Code node (offline)")}
+  ${b("n8n-decanter")} <ref> ${b("duplicate")} ["<new name>"]   ${d("clone a workflow into a new remote one, then pull it")}
   ${b("n8n-decanter")} [ref...] ${b("publish")}     ${d("take the draft(s) live (unpublish returns to draft-only)")}
   ${b("n8n-decanter")} [ref...] ${b("unpublish")}
   ${b("n8n-decanter create")} "<name>"     ${d("create a blank workflow on the server, then pull it")}
@@ -70,7 +73,6 @@ const usage = () => {
   ${b("n8n-decanter completion")} zsh|bash  ${d("print a shell completion script for your rc file")}
   ${b("n8n-decanter")} <node-file> ${b("run")} [fixture.json] [--allow-env]   ${d("run a node locally (offline;")}
                                    ${d("$env is empty unless the fixture sets env or --allow-env inherits process.env)")}
-  ${b("n8n-decanter uuid")} [count]         ${d("print lowercase v4 UUID(s) for new node ids")}
 
 A workflow <ref> is its id, its workflow/folder name, or a unique name prefix
 (case-insensitive; ambiguity is an error, never a prompt). A workflow named
@@ -81,7 +83,7 @@ and flags may appear in any position too.
 Config: decanter.config.json (searched upward from cwd), credentials from .env
 next to it or the environment (N8N_HOST, N8N_API_KEY).`;
 };
-const VERBS = new Set(["init", "pull", "push", "status", "check", "rename", "watch", "run", "uuid", "list", "executions", "publish", "unpublish", "create", "delete", "completion", "__complete", "help"]);
+const VERBS = new Set(["init", "pull", "push", "status", "check", "rename", "add", "duplicate", "watch", "run", "list", "executions", "publish", "unpublish", "create", "delete", "completion", "__complete", "help"]);
 /** Verbs whose workflow arguments go through name resolution. */
 const REF_VERBS = new Set(["pull", "push", "status", "check", "watch", "publish", "unpublish", "delete"]);
 // Both scripts delegate to the hidden `__complete` verb at completion time,
@@ -135,6 +137,7 @@ async function main() {
     const workflowFlag = args.includes("--workflow");
     const remoteFlag = args.includes("--remote");
     const diffFlag = args.includes("--diff");
+    const tsFlag = args.includes("--ts");
     const positional = args.filter((a) => !a.startsWith("--"));
     // id-first support: the first token matching a known verb is the command,
     // wherever it sits — `push wf123` and `wf123 push` are equivalent.
@@ -169,14 +172,6 @@ async function main() {
         return;
     }
     // Offline, config-free verbs — no decanter.config.json or credentials needed.
-    if (command === "uuid") {
-        const count = rest[0] ? Number(rest[0]) : 1;
-        if (!Number.isInteger(count) || count < 1)
-            throw new Error("uuid count must be a positive integer");
-        for (let i = 0; i < count; i++)
-            console.log(randomUUID());
-        return;
-    }
     if (command === "run") {
         if (rest.length < 1)
             throw new Error("run needs a node file argument: n8n-decanter run <node-file> [fixture.json]");
@@ -194,7 +189,7 @@ async function main() {
         // hidden helper backing the completion scripts: verbs, flags, and local
         // workflow names/ids — offline, credentials-free, silent without a config
         const words = [...VERBS].filter((v) => v !== "__complete" && v !== "help");
-        words.push("--force", "--no-typecheck", "--workflow", "--remote", "--diff", "--status=", "--limit=", "--allow-env", "--help");
+        words.push("--force", "--no-typecheck", "--workflow", "--remote", "--diff", "--ts", "--status=", "--limit=", "--allow-env", "--help");
         try {
             const config = loadConfig(process.cwd(), { requireCredentials: false });
             for (const ref of listWorkflowRefs(config.root))
@@ -206,10 +201,10 @@ async function main() {
         console.log([...new Set(words)].join("\n"));
         return;
     }
-    await dispatch(command, rest, { force, noTypecheck, workflowFlag, remoteFlag, diffFlag, valueFlags });
+    await dispatch(command, rest, { force, noTypecheck, workflowFlag, remoteFlag, diffFlag, tsFlag, valueFlags });
 }
 /** Flag defaults for picker-launched verbs (no CLI flags in play). */
-const PICKER_FLAGS = { force: false, noTypecheck: false, workflowFlag: false, remoteFlag: false, diffFlag: false, valueFlags: new Map() };
+const PICKER_FLAGS = { force: false, noTypecheck: false, workflowFlag: false, remoteFlag: false, diffFlag: false, tsFlag: false, valueFlags: new Map() };
 /**
  * Interactive session (Plan 19 + loop follow-up): banner, then pick → run →
  * back in the same workflow's verb menu until Esc (workflow list, then quit)
@@ -258,8 +253,8 @@ async function pickerLoop(config) {
 }
 /** Config-needing verbs: load config, resolve refs, run the verb switch. */
 async function dispatch(command, rest, flags) {
-    const { force, noTypecheck, workflowFlag, remoteFlag, diffFlag, valueFlags } = flags;
-    const offline = command === "check" || command === "rename" || (command === "list" && !remoteFlag)
+    const { force, noTypecheck, workflowFlag, remoteFlag, diffFlag, tsFlag, valueFlags } = flags;
+    const offline = command === "check" || command === "rename" || command === "add" || (command === "list" && !remoteFlag)
         || (command === "executions" && rest.includes("clean"));
     const config = loadConfig(process.cwd(), { requireCredentials: !offline });
     const api = new N8nApi(config);
@@ -295,7 +290,9 @@ async function dispatch(command, rest, flags) {
         for (const r of rest)
             refs.push(await resolveRef(r));
     }
-    else if (command === "rename" && rest.length > 0) {
+    else if ((command === "rename" || command === "add" || command === "duplicate") && rest.length > 0) {
+        // ref-plus-literals verbs: only the first argument is a workflow ref;
+        // the rest are names (node names, a new workflow name) — not resolved.
         refs = [await resolveRef(rest[0]), ...rest.slice(1)];
     }
     const ids = refs.length > 0 ? refs : config.workflows;
@@ -505,6 +502,24 @@ async function dispatch(command, rest, flags) {
             }
             break;
         }
+        case "add": {
+            const [id, ...names] = refs;
+            if (!id)
+                throw new Error('add needs a workflow ref and a node name: n8n-decanter <ref> add "<Node name>" [--ts]');
+            if (names.length !== 1)
+                throw new Error('add needs exactly one node name: n8n-decanter <ref> add "<Node name>" [--ts]');
+            addCodeNode(config.root, id, names[0], { ts: tsFlag }, log);
+            break;
+        }
+        case "duplicate": {
+            const [id, ...names] = refs;
+            if (!id)
+                throw new Error('duplicate needs a workflow ref: n8n-decanter <ref> duplicate ["<new name>"]');
+            if (names.length > 1)
+                throw new Error('duplicate takes at most one new name: n8n-decanter <ref> duplicate ["<new name>"]');
+            await duplicateWorkflow(api, config, id, names[0], log);
+            break;
+        }
         case "watch": {
             if (ids.length !== 1)
                 throw new Error("watch needs exactly one workflow id (pass it, or list a single workflow in decanter.config.json)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-decanter",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Work on n8n like a codebase — built for AI coding agents",
   "keywords": [
     "n8n",
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "prepare": "node scripts/setup-hooks.mts",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.cli.json && node scripts/typecheck.mts",
     "test": "node --test 'test/unit/*.test.mts' && node test/e2e.mts && node test/proxy.mts && node test/interactive.mts",

package/template/.claude/settings.local.json.example

@@ -6,7 +6,7 @@
       "Bash(n8n-decanter check)",
       "Bash(n8n-decanter check:*)",
       "Bash(n8n-decanter run:*)",
-      "Bash(n8n-decanter uuid:*)",
+      "Bash(n8n-decanter add:*)",
       "Bash(n8n-decanter status:*)",
       "Bash(npm run typecheck)",
       "Bash(npm run check)"

package/template/AGENTS.md.example

@@ -3,7 +3,7 @@
 This is the **source of truth** for working in this repository, and it is written to
 be tool-agnostic. Codex and opencode read this file natively; Claude Code reads it
 through a one-line `@AGENTS.md` import in `CLAUDE.md`; other agents can be pointed at
-it (see `SCAFFOLD.md`). Keep project-specific rules here so every agent stays in sync.
+this file directly. Keep project-specific rules here so every agent stays in sync.
 
 This repo holds n8n workflows *decanted* into git-friendly form: one folder per
 workflow containing `workflow.json` plus a `code/` subdir with one source file
@@ -11,6 +11,21 @@ per Code node. The
 `n8n-decanter` CLI moves content between here and the live n8n instance
 (`pull` / `push`). This document is the contract for creating and editing these files.
 
+## The short version
+
+- **Code lives in `code/`, never in `workflow.json`.** A node's `jsCode` is only
+  a `//@file:code/<name>` placeholder — edit the file it points at.
+- **Never hand-edit `.decanter.json` or a `*.remote.js`, and never write a
+  `// @ts-n8n sha256:` marker.** These are machine-owned; touching them corrupts
+  sync state and the CLI blocks it at `push`.
+- **Structural edits have verbs — use them instead of hand-editing JSON:**
+  `add` a Code node, `rename` a node/workflow, `create`/`duplicate` a workflow.
+  Each does the fiddly multi-file edit atomically and re-validates the folder.
+- **`push` is a deploy to the live instance — only when the user asks.** Edit,
+  then verify offline with `n8n-decanter check` and `n8n-decanter run`.
+
+The rest of this document is the full contract behind those four points.
+
 ## How this differs from standard n8n editing — read this first
 
 Your general n8n knowledge (docs, n8n MCP tools, training data) is **valid** for:
@@ -35,12 +50,14 @@ runtime. It is **wrong** about how code is stored here. The deviations:
    diff: port the change into the `.ts`, delete the `.remote.js`, then the user
    pushes. Never edit `.remote.js` itself; never push while one exists.
 6. **Renames have no UI magic here.** The n8n editor auto-updates references on
-   rename; raw JSON editing does not. See the rename checklist below.
+   rename; editing files does not. Use `n8n-decanter <ref> rename` — it rewrites
+   every reference atomically. See "Renaming a node" below.
 7. **New workflows are born on the server, not from a repo folder.** There is no
    id-less folder that becomes a workflow on push. Use `n8n-decanter create
    "<name>"` — it posts a blank draft to n8n and pulls it back (the server
-   assigns the id) — or create it in the n8n UI and `pull`. Then add its id to
-   `decanter.config.json`. A created workflow is **unpublished**; `publish`
+   assigns the id) — `n8n-decanter <ref> duplicate` to clone an existing
+   workflow into a new one, or create it in the n8n UI and `pull`. Then add its
+   id to `decanter.config.json`. A created workflow is **unpublished**; `publish`
    takes it live, `unpublish` returns it to draft-only, and `<ref> delete`
    removes one from the server (the local folder is kept).
 
@@ -72,7 +89,7 @@ A node object:
 
 ```json
 {
-  "id": "a1b2c3d4-…",            // UUID v4 — `n8n-decanter uuid` to generate; NEVER change an existing id
+  "id": "a1b2c3d4-…",            // UUID v4 — `n8n-decanter <ref> add` mints it; NEVER change an existing id
   "name": "Amazon Feed",          // unique per workflow — connections + $('…') reference it
   "type": "n8n-nodes-base.code",
   "typeVersion": 2,
@@ -103,24 +120,36 @@ Rules:
   (whitelisted keys), `staticData`. Activation is managed in the n8n UI.
 - **Position:** keep a sensible grid; new nodes roughly +200 x from their input.
 
-### Renaming a node — checklist (all four, atomically)
+### Renaming a node
+
+Use the verb — it rewrites every reference atomically, offline, and re-validates
+the folder:
+
+```sh
+n8n-decanter <ref> rename "<Old Name>" "<New Name>"
+```
+
+It touches all four places a rename must hit at once — the same four you'd have
+to keep in sync **by hand** (and atomically) if you ever edit the raw JSON:
 
 1. `name` in the node object.
 2. Every reference in `connections` (keys *and* target `"node"` values).
 3. Every `$('Old Name')` in **all** code files of the workflow.
-4. The source file name and its `//@file:` placeholder (keep the kebab-case
-   name-file convention, file stays in `code/`). The tool re-maps by node id
-   on the next pull, but the repo must be self-consistent immediately.
+4. The source file name and its `//@file:` placeholder (kebab-case convention,
+   file stays in `code/`).
 
-Renaming a **workflow**: change `name` in `workflow.json`; folder rename happens
-on the next pull (or do it yourself, folder names are cosmetic — the id inside
-`workflow.json` is authoritative).
+Renaming a **workflow**: `n8n-decanter <ref> rename --workflow "<New Name>"`.
+The folder rename follows on the next pull — folder names are cosmetic; the id
+inside `workflow.json` is authoritative.
 
 ### Adding a Code node
 
-1. Add the node object — generate its `id` with `n8n-decanter uuid` (a lowercase
-   v4 UUID), placeholder `jsCode`, position, connections.
-2. Create the source file it points at in `code/` (`.js` or `.ts`, see below).
+1. `n8n-decanter <ref> add "<Node name>" [--ts]` scaffolds it in one step: it
+   mints the node `id`, writes the `code/` source (`.js`, or `.ts` with
+   `--ts`), adds the `//@file:` placeholder, records it in `.decanter.json`,
+   and re-checks the folder. The node lands **disconnected**.
+2. Wire it up — add its connections in `workflow.json` (and any `$('…')`
+   references from other nodes), then edit the source in `code/`.
 3. Verify: `n8n-decanter run <file> [fixture.json]` to execute it, then
    `n8n-decanter check` (typecheck + layout).
 
@@ -141,12 +170,11 @@ The runtime contract (identical for `.js` and `.ts` — types are erased):
     workspace TypeScript: `npm install`, then in VS Code accept
     *Use Workspace Version* (offered via `.vscode/settings.json`'s
     `typescript.tsdk`; JetBrains uses the project TypeScript by default).
-- Available globals (extend `n8n-globals.d.ts` when you use one it lacks):
-  `$input.all()/.first()/.last()/.item` · `$('Node Name').all()/.first()/.item/.itemMatching(i)` ·
-  `$json`, `$binary`, `$itemIndex` (each-item mode) ·
-  `DateTime`, `Duration`, `Interval` (Luxon), `$now`, `$today` ·
-  `$jmespath()` · `$workflow`, `$execution`, `$prevNode`, `$runIndex` ·
-  `$getWorkflowStaticData('global' | 'node')`.
+- **Available globals: `n8n-globals.d.ts` is the authoritative list.** Open it
+  to see every global in scope with its exact signature (`$input`, `$('Node
+  Name')`, `$json`, `$binary`, the Luxon `DateTime`/`$now`/`$today`, `$workflow`,
+  `$execution`, `$getWorkflowStaticData`, …). If node code needs a global that
+  file doesn't declare yet, add it there.
 - **Imports**: `.js` nodes — none at all (they run verbatim; assume the
   instance allows no external or built-in modules). `.ts` nodes — imports
   from inside this repo (`shared/`, relative paths) and from npm packages
@@ -157,7 +185,7 @@ The runtime contract (identical for `.js` and `.ts` — types are erased):
   builtins (`node:*`, `fs`, `crypto`, …) are compile errors. Never
   `require()`.
 - `console.log` is available for debugging (visible in the execution view).
-- `$('Node Name')` takes the node's **name** — see the rename checklist.
+- `$('Node Name')` takes the node's **name** — so `rename` keeps it in sync.
 
 ### `.js` nodes (default — lossless)
 
@@ -292,18 +320,20 @@ Rules:
 ## Commands — who runs what
 
 - **Offline, safe — run freely:** `n8n-decanter check` (or `npm run typecheck`),
-  `n8n-decanter run <file> [fixture]`, `n8n-decanter uuid [n]`,
-  `n8n-decanter executions clean`. These never touch the network.
+  `n8n-decanter run <file> [fixture]`, `n8n-decanter <ref> add "<Node name>"`,
+  `n8n-decanter <ref> rename …`, `n8n-decanter executions clean`. These never
+  touch the network.
 - **Reads remote, no writes:** `n8n-decanter status` (`--diff` shows the line
   diffs; exits 1 on conflict/remote drift) and `n8n-decanter <ref> executions`
   (fetches execution data, read-only) — safe to run, but they do contact the
   instance.
 - **Live n8n instance — only when the user explicitly asks:** `n8n-decanter
   pull` / `push` / `watch` read/write the real instance and `push` deploys;
-  `create "<name>"` adds a new workflow, and `publish` / `unpublish` change what
-  is live (`publish` takes the draft live immediately, `unpublish` returns it to
-  draft-only). Otherwise finish edits, verify with `check` + `run`, and report
-  that the change is ready to push (or publish).
+  `create "<name>"` adds a new workflow and `<ref> duplicate` clones an existing
+  one into a new (unpublished) remote workflow, and `publish` / `unpublish`
+  change what is live (`publish` takes the draft live immediately, `unpublish`
+  returns it to draft-only). Otherwise finish edits, verify with `check` +
+  `run`, and report that the change is ready to push (or publish).
 - **Destructive — never without an explicit instruction:** `n8n-decanter <ref>
   delete` removes a workflow from the server (hard delete, even if published;
   the local folder is kept as the git record). Run it only when the user has