n8n-decanter 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,122 @@ 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
+
+- **Globally-installed CLI (`npm i -g n8n-decanter`) could crash on
+  `push`/`check`/`watch`'s typecheck gate** — it resolved the `typescript`
+  package relative to its own install location instead of the sync dir
+  being checked, which only ever worked when the CLI happened to be nested
+  inside the sync dir's `node_modules` (e.g. a local `devDependency`
+  install). A global install is never nested there, so the gate could fail
+  to find `typescript` at all. Now resolved relative to the sync dir first,
+  falling back to the CLI's own location.
+
+## [0.3.1] - 2026-07-20
+
+### Added
+
+- **`publish` / `unpublish` verbs** close the n8n 2.x workflow lifecycle from
+  the CLI: `n8n-decanter <ref> publish` takes a draft live, `unpublish` returns
+  it to draft-only. Already-in-that-state is a no-op with a note, not an error.
+  A staged rollout is now `unpublish` → `push` → `publish` without leaving the
+  terminal.
+- **`create` verb** — `n8n-decanter create "<name>"` creates a blank workflow
+  on the server (born unpublished) and immediately pulls it, so the folder and
+  the new id are ready to edit → push → `publish`.
+- **`delete` verb** — `n8n-decanter <ref> delete` removes a workflow from the
+  server. It asks for a `y/N` confirmation naming the workflow; non-interactive
+  runs require `--force`. The **local folder is left untouched** as the
+  git-tracked record, and a stale `decanter.config.json` `workflows` entry is
+  flagged. Requires a ref (never deletes config workflows by default), one at a
+  time.
+
+### Changed
+
+- **`status` is version-aware.** On a published workflow whose draft has moved
+  ahead of the live version (a UI edit not yet published), `status` now says
+  the live version is older than the draft (`push` or `publish` to catch it
+  up) instead of the plain `published` note.
+- **`executions` warns on stale fixtures.** When a fetched execution ran a
+  published version different from your local draft, the fetch now warns that
+  the captured data may not match the code you're editing (still written — a
+  warning, not an error).
+- The recommended **scoped API key** now includes `workflow:create`,
+  `workflow:delete`, `workflow:activate`, and `workflow:deactivate` so the new
+  lifecycle verbs work (`README`, `.env.example`).
+
 ## [0.3.0] - 2026-07-20
 
 ### Security

package/README.md

@@ -2,14 +2,25 @@
 
 [![CI](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml/badge.svg)](https://github.com/buttjer/n8n-decanter/actions/workflows/ci.yml)
 [![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.
 
+![Terminal demo — the interactive picker: filter workflows, choose a verb, sync](./docs/terminal-demo.gif)
+
 - **Real version control** — meaningful diffs, PRs, blame; every push and
   pull is auto-committed.
 - **TypeScript or typed JS** — write nodes in TS (compiled on push); n8n
@@ -33,7 +44,9 @@ editable in your IDE or by your agent, and pushed back through the n8n API.
   behavior that touches the API is verified against a real n8n 2.x instance
   by an automated integration suite.
 
-![VS Code Screenshot](./docs/screenshot.webp)
+![Agent demo — a coding agent edits a Code node, tests it offline, then pushes live](./docs/agent-demo.gif)
+
+📖 **Full documentation: [buttjer.github.io/n8n-decanter](https://buttjer.github.io/n8n-decanter/)**
 
 ## Setup
 
@@ -56,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`:
@@ -72,6 +87,8 @@ limited to the permissions the CLI actually uses rather than a full-access one,
 so a leaked `.env` has a small blast radius:
 
 - `workflow:read`, `workflow:list`, `workflow:update` — `pull` / `status` / `push`
+- `workflow:create`, `workflow:delete` — `create` / `delete`
+- `workflow:activate`, `workflow:deactivate` — `publish` / `unpublish`
 - `execution:read`, `execution:list` — the `executions` verb
 
 A full-access key also works if your n8n version predates scoped keys.
@@ -88,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
@@ -108,8 +125,16 @@ 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)
 n8n-decanter [ref...] executions [--status=success|error|waiting] [--limit=N]
                                     # fetch recent execution data (run JSON)
                                     #   into workflows/<Name>/executions/
@@ -120,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
@@ -209,9 +233,13 @@ already run, so Claude Code on a Claude subscription needs no extra API tokens.
   update through the API** (pushing to an *unpublished* workflow only updates
   its draft). This is an n8n API limitation, not decanter's; decanter surfaces
   the outcome — push prints `published: code is live now` vs `unpublished:
-  draft only`, and `status`/`watch` show the state. For a staged rollout,
-  unpublish → push → publish (triggers are down in between), or push to a
-  staging-copy workflow.
+  draft only`, and `status`/`watch` show the state. The **`publish`** and
+  **`unpublish`** verbs take a draft live / return it to draft-only from the
+  CLI, so a staged rollout is `unpublish` → `push` → `publish` (triggers are
+  down in between) without leaving the terminal, or push to a staging-copy
+  workflow. On a published workflow whose draft has moved ahead in the UI,
+  `status` says the live version is older than the draft (`push` or `publish`
+  to catch it up).
 - **n8n's optimistic locking isn't reachable through the API.** That same `PUT`
   also forces `forceSave: true` and exposes no version checksum, so the server
   won't reject a stale write. Decanter's **drift guard** is the only thing

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

@@ -48,6 +48,33 @@ export class N8nApi {
     async updateWorkflow(id, body) {
         return this.#request("PUT", `/api/v1/workflows/${encodeURIComponent(id)}`, body);
     }
+    /**
+     * 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(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) {
+        return this.#request("POST", `/api/v1/workflows/${encodeURIComponent(id)}/activate`);
+    }
+    /** Return a published workflow to draft-only. Idempotent server-side; returns the workflow. */
+    async deactivateWorkflow(id) {
+        return this.#request("POST", `/api/v1/workflows/${encodeURIComponent(id)}/deactivate`);
+    }
+    /**
+     * Hard-delete a workflow (n8n 2.x `DELETE /workflows/:id`). Verified to delete
+     * even a *published* workflow outright (no refusal, no archive), so the CLI's
+     * confirmation gate is the only guard. Returns the deleted workflow.
+     */
+    async deleteWorkflow(id) {
+        return this.#request("DELETE", `/api/v1/workflows/${encodeURIComponent(id)}`);
+    }
     async #request(method, pathname, body) {
         try {
             // The signal also covers body consumption, so a stalled response

package/dist/lib/executions.mjs

@@ -1,7 +1,37 @@
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { findWorkflowDir, listWorkflowDirs } from "./state.mjs";
 export const EXECUTIONS_DIR = "executions";
+/**
+ * Warn when fetched executions ran a *published* version that differs from the
+ * local draft (`workflow.json`'s `versionId`) — the captured data may not match
+ * the code you're now editing (PLAN.md's "convenience data, not ground truth"
+ * caveat, enforced). A warning, not an error: the data is still useful. Deduped
+ * by version so a page of same-version executions warns once; silent when the
+ * draft version or the execution version is unavailable (defensive).
+ */
+function warnStaleFixtures(dir, executions, log) {
+    const wfFile = path.join(dir, "workflow.json");
+    if (!existsSync(wfFile))
+        return;
+    let draft;
+    try {
+        draft = JSON.parse(readFileSync(wfFile, "utf8")).versionId;
+    }
+    catch {
+        return; // unparsable workflow.json — nothing to compare against
+    }
+    if (typeof draft !== "string")
+        return;
+    const stale = new Set();
+    for (const exec of executions) {
+        if (typeof exec.workflowVersionId === "string" && exec.workflowVersionId !== draft)
+            stale.add(exec.workflowVersionId);
+    }
+    for (const ran of stale) {
+        log.warn(`captured executions ran published version ${ran}; your draft is ${draft} — the data may not match the code you're editing`);
+    }
+}
 /**
  * Materialize execution JSON under `<workflow>/executions/`. The dir is made
  * self-ignoring via an `executions/.gitignore` containing `*` — execution
@@ -30,6 +60,7 @@ export async function fetchExecutions(api, root, workflowId, { status, limit },
         return;
     }
     writeExecutionFiles(dir, executions, log);
+    warnStaleFixtures(dir, executions, log);
     log.ok(`${executions.length} execution${executions.length === 1 ? "" : "s"} -> ${path.relative(process.cwd(), path.join(dir, EXECUTIONS_DIR))} (gitignored — temp data, "executions clean" removes it)`);
 }
 /**
@@ -45,6 +76,7 @@ export async function fetchExecutionById(api, root, executionId, log) {
     if (!dir)
         throw new Error(`execution ${executionId} belongs to workflow ${workflowId}, which is not pulled under ${root} — pull it first`);
     writeExecutionFiles(dir, [exec], log);
+    warnStaleFixtures(dir, [exec], log);
     log.ok(`execution ${executionId} -> ${path.relative(process.cwd(), path.join(dir, EXECUTIONS_DIR))}`);
 }
 /**

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");