flownav 0.1.2 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ It is read-only against n8n. Inspired by [graphify](https://github.com/safishams
 ## Why
 
 - **Token cost.** A real workflow export is large and mostly noise. `flownav explain "Node"` is about ten lines.
-- **The rename gap.** When you rename or delete a node, n8n updates the connections but not `$('Old Name')` inside other nodes' expressions or Code nodes. Those silently break. `flownav affected "Old Name" --rename` lists exactly which nodes and parameters will break, before you change anything.
+- **The rename gap.** The n8n editor tries to rewrite `$('Old Name')` references when you rename a node, but community reports describe that as imperfect, and references inside Code nodes' JavaScript are reported not to be rewritten. Renames that don't go through the editor (the API, edited JSON, an AI agent changing a workflow) don't get that rewrite step at all, and deleting a node never fixes the references to it. A broken reference fails silently. `flownav affected "Old Name" --rename` lists exactly which nodes and parameters reference the node by name, so you can check them before and after you change anything.
 - **Cross-workflow structure.** Sub-workflows, agent tool workflows, error workflows and webhook-to-webhook calls become edges, so you can ask what calls what across your whole instance.
 
 ## Install
@@ -113,7 +113,9 @@ $ flownav affected "Normalize" --rename
 wf-orders:Normalize — impact of rename
 2 node(s) reference "Normalize" by name and will break unless their expressions are rewritten:
   × wf-orders:Notify Sales uses {email}  in text
+      text: {{ 'Big order from ' + $('Normalize').item.json.email }}
   × wf-orders:Orphan Code uses {email}  in jsCode
+      jsCode: L1: const row = $('Normalize').first().json.email;
 ```
 
 **A path, even across workflows**
@@ -163,7 +165,7 @@ $ flownav check
   INFO  no-error-handler   [wf-enrich] Enrich customer has no error workflow and no node-level error handling
 ```
 
-`check` exits with code 1 when it finds an `ERROR`, so it can run in CI.
+`check` exits with code 1 when it finds an `ERROR`. Use `--fail-on warn` (or `info`) to fail on less severe findings, `--fail-on none` to always exit 0, and `--only a,b` to run just some checks. See [Use it in CI](#use-it-in-ci).
 
 ## Using it with an AI agent
 
@@ -171,7 +173,7 @@ $ flownav check
 flownav install claude --mcp     # writes .claude/skills/flownav/SKILL.md and .mcp.json
 ```
 
-This installs a skill that tells the agent to query flownav before reading, renaming or deleting nodes, and registers an MCP server (`flownav serve`, stdio) exposing `flownav_scan`, `explain`, `neighbors`, `path`, `find`, `affected`, `callers`, `calls`, `uses`, `check` and `report`. The server reads `.flownav/graph.json` from the working directory (or `--graph <file>`) and reloads it when the file changes. The skill works without MCP too, as long as the agent can run shell commands.
+This installs a skill that tells the agent to query flownav before reading, renaming or deleting nodes, and registers an MCP server (`flownav serve`, stdio) exposing `flownav_scan`, `explain`, `neighbors`, `path`, `find`, `affected`, `callers`, `calls`, `uses`, `check`, `read` and `report`. The server reads `.flownav/graph.json` from the working directory (or `--graph <file>`) and reloads it when the file changes. The skill works without MCP too, as long as the agent can run shell commands.
 
 A typical rename: the agent runs `scan` to find the workflow id, then `affected "wf-orders:Normalize"`, edits the listed expressions together with the rename using whatever tool it has for editing n8n, syncs again, and runs `check` to confirm nothing dangles. flownav does not write to n8n; it tells the agent what is safe.
 
@@ -190,6 +192,38 @@ error: "order" matches 5 nodes. Do not guess: ask the user which one they mean.
 
 If a partial name matches exactly one node, it resolves but the reply starts with a `NOTE:` asking the agent to confirm with the user before changing anything. To search a family of workflows, use `flownav find --match "<part of workflow name>" --name "<part of node name>"` (`--name` searches node names only; `--text` also searches parameters and code). The installed skill tells the agent to stop and ask in these cases. How reliably an agent follows that depends on the agent.
 
+## Reading code in small pieces
+
+flownav normally returns structure (cards, paths, references), not code. When an agent (or you) needs to read a large Code node, `read` returns it in small, capped slices instead of the whole node:
+
+```text
+$ flownav read "Orphan Code"                 # default: an outline
+wf-orders:Orphan Code · jsCode · 3 line(s), 127 chars
+longest line: 46 chars
+functions: none found
+node references:
+  Normalize  line 1  {email}
+  Deleted Step  line 2  {x}
+next: grep for a name, or read a range with lines
+
+$ flownav read "Orphan Code" --grep normalize
+wf-orders:Orphan Code · jsCode · 3 line(s), 127 chars
+> 1: const row = $('Normalize').first().json.email;
+  2: const gone = $('Deleted Step').first().json.x;
+  3: return [{ json: { row, gone } }];
+1 of 1 matching line(s) shown
+
+$ flownav read "Orphan Code" --lines 2-3
+```
+
+- **Outline** (the default): size, the longest line, function names, and which nodes the code references, all with line numbers, so you can pick a slice without reading blindly.
+- **`--grep <pattern>`**: matching lines with context (`--context`, default 2, up to 10), overlapping windows merged, up to `--max` matches (default 20). Literal and case-insensitive by default; `--regex` and `--case` change that.
+- **`--lines 120-180`** (also `120` or `120-`): numbered lines, with a hint for the next slice. An open-ended range returns 60 lines.
+- **Long lines:** a line over 240 characters is shown windowed, and `--cols 241-480` reads inside it, which is what you need for minified or generated code.
+- **`--param`** reads another text parameter (for example an HTML field); without it, `read` uses `jsCode`, `pythonCode`, `functionCode` or `code`.
+
+Every reply is capped at about 6,000 characters whatever you ask for, and secrets in the code are redacted (key-like assignments such as `apiKey = "..."`, and token shapes such as `Bearer ...`; this is best-effort, not a guarantee). `read` takes the code from your exported files, or does one read-only `GET` of that workflow from your instance (it needs the API key in the environment variable named by your profile, `N8N_API_KEY` by default). `--from <folder>` reads from a folder of exports instead. If the workflow changed since the graph was built, the reply starts with a warning and shows the current source. The MCP tool `flownav_read` does the same and cannot be pointed at other folders.
+
 ## Seeing the graph
 
 ```bash
@@ -250,7 +284,11 @@ flownav path <A> <B> [--max N --kinds a,b]
 flownav find [--type --cred --text --name --resource --workflow --match --disabled --trigger]
 flownav affected <node> --rename|--delete|--schema|--behavior
 flownav callers <workflow> | calls <workflow> | uses --cred <c>
-flownav check [--only fragile-reads|dead-refs|cycles|unreachable|dead-ends|no-error-handler|webhook-no-respond]
+flownav read <node> [--outline | --grep p [--regex --case --context n --max n] | --lines a-b]
+                    [--param p --cols a-b --from path]     read part of a Code node, capped and redacted
+flownav stats [--from path]           measure raw JSON tokens against flownav replies on your workflows
+flownav check [--only a,b] [--fail-on error|warn|info|none]
+                                      checks: fragile-reads, dead-refs, cycles, unreachable, dead-ends, no-error-handler, webhook-no-respond
 flownav view [workflow] [--match text --collapse --focus <node> --depth N --out file.html --open]
 flownav diagram [workflow] [--match text --collapse --focus <node> --depth N --no-reads --dir LR|TD --out file.md]
 flownav diff old.json new.json        what changed between two graphs
@@ -260,12 +298,39 @@ flownav serve                         MCP server on stdio
 
 Global options: `--graph <file>` and `--format text|json`. Nodes are addressed as `Name` or `workflow:Name` (workflow id or name).
 
+## Use it in CI
+
+`flownav check` exits with code 1 when it finds an error, and `--only dead-refs` limits it to broken references (a node that reads a node that no longer exists, a connection to a missing node, a call to a missing workflow). Two ways to feed it, as a GitHub Actions example:
+
+```yaml
+name: n8n workflow check
+on: [pull_request]
+jobs:
+  flownav:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # Option A: workflow JSON exported into the repo (e.g. ./workflows)
+      - run: npx -y flownav build ./workflows
+      # Option B: a live instance with a read-only API key stored as a secret
+      # - run: npx -y flownav sync --url ${{ secrets.N8N_URL }}
+      #   env:
+      #     N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+      - run: npx -y flownav check --only dead-refs
+```
+
+For a manual "before I touch this" step, run `flownav affected "Node" --rename` instead. flownav is static analysis: it can only gate on what it can see, so references built at runtime are reported as unresolved and are not failures.
+
 ## Privacy and safety
 
 - Read-only against n8n: the only network method is `GET`.
 - `pinData` (sample execution data) is dropped on load and never stored.
 - String parameters are redacted before being kept for search: values under secret-looking keys (`apiKey`, `token`, `password`, `Authorization`, ...) and known token shapes (Bearer, `sk-...`, GitHub, Slack, AWS, JWT).
 - Credentials are recorded by id and type only.
+- `flownav read` is the one command that returns code. It redacts key-like assignments and token shapes (best-effort), caps every reply, and for live graphs makes a single read-only `GET` of the one workflow it needs.
 - Execution data is not fetched; `--executions` records only the last status per workflow.
 - `.flownav/` holds your graph and is git-ignored by this repo. Don't commit it or share the HTML views if your workflows are sensitive.
 
@@ -274,7 +339,7 @@ Global options: `--graph <file>` and `--format text|json`. Nodes are addressed a
 This is a back-of-the-envelope model, not a measurement of real agent sessions. Tokens are estimated as characters ÷ 4.
 
 - **n**: nodes the agent would otherwise read; **τ**: tokens per node in raw n8n JSON (assumed 300, it varies a lot: Code and HTML nodes are far heavier than a Set node); **W = n·τ**.
-- **S ≈ 1,300 tokens**: flownav's fixed overhead per session (the 11 MCP tool definitions, about 800 tokens, plus the skill, about 500).
+- **S ≈ 1,600 tokens**: flownav's fixed overhead per session (the 12 MCP tool definitions, about 1,000 tokens, plus the skill, about 550).
 - **r ≈ 100 tokens**: a typical reply. `explain` and `affected` replies are tens of tokens; a `scan` of a dozen workflows is a few hundred.
 - With prompt caching, text read once costs about 1.25× the first time and about 0.1× on each later turn. For Q questions:
   - raw: `C_raw ≈ W · (1.25 + 0.1·(Q − 1))`
@@ -287,25 +352,25 @@ Raw reading grows with the workflow; a flownav reply depends only on a node's lo
 
 | workflow size | raw tokens | 1 question | 10 questions |
 |---|---|---|---|
-| 5 nodes | 1,500 | 8% | −18% (costs more) |
-| 10 nodes | 3,000 | 54% | 41% |
-| 30 nodes | 9,000 | 85% | 80% |
-| 132 nodes | 40,000 | 97% | 96% |
-| whole instance (443 nodes) | 133,000 | 99% | 99% |
+| 5 nodes | 1,500 | −12% (costs more) | −38% (costs more) |
+| 10 nodes | 3,000 | 44% | 31% |
+| 30 nodes | 9,000 | 81% | 77% |
+| 132 nodes | 40,000 | 96% | 95% |
+| whole instance (443 nodes) | 133,000 | 99% | 98% |
 
 **Saving when the agent searches and reads only a fraction of a 132-node workflow:**
 
 | fraction read | 1 question | 10 questions |
 |---|---|---|
-| 30% | 89% | 85% |
-| 20% | 83% | 78% |
-| 10% | 66% | 56% |
+| 30% | 86% | 83% |
+| 20% | 79% | 74% |
+| 10% | 58% | 48% |
 
 What to take from it:
 
 - Below roughly 6 nodes, reading the JSON is cheaper than loading the tools. Around 10 to 30 nodes flownav saves about half to four fifths; on large workflows the saving approaches 100%.
 - Most agents search instead of reading everything, so for large workflows a realistic range is about 55 to 90%; the 96% rows are the best case.
-- τ is the main unknown. To get a real figure, measure the size of your own exports, or run the same task with and without flownav and compare the usage Claude reports, several times, since agent runs vary.
+- τ is the main unknown, and `flownav stats` measures it on your own workflows (the bundled examples come out at about 130 tokens per node, well below the 300 assumed here, because they are small and hand-written; real Code and HTML nodes are far heavier). You can also run the same task with and without flownav and compare the usage Claude reports, several times, or measure the size of your own exports, or run the same task with and without flownav and compare the usage Claude reports, several times, since agent runs vary.
 - Tokens are not the only benefit: `affected` finds `$('Name')` references in expressions and Code nodes that a skimming agent misses.
 
 ## Limitations

package/dist/assemble.js

@@ -1,7 +1,7 @@
 import { CROSS_KINDS } from './types.js';
 import { shortType } from './util.js';
 /** Bump whenever extraction logic changes so cached per-workflow results are not reused. */
-export const BUILDER_VERSION = 4;
+export const BUILDER_VERSION = 5;
 export const wfOf = (g, id) => {
     if (id.startsWith('wf:'))
         return id.slice(3);

package/dist/build.js

@@ -1,5 +1,16 @@
-import { expressionBodies, extractRefs } from './expressions.js';
+import { expressionBlocks, extractRefs } from './expressions.js';
 import { redactString, rlValue, sha, shortType, stable, trunc, walkStrings } from './util.js';
+const MAX_SNIPPETS = 3;
+const clip = (s, n = 140) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+/** `L12: <the line>` for a reference at offset `at` of a code string. */
+function codeSnippet(raw, at) {
+    const line = raw.slice(0, at).split('\n').length;
+    const start = raw.lastIndexOf('\n', at - 1) + 1;
+    let end = raw.indexOf('\n', at);
+    if (end < 0)
+        end = raw.length;
+    return `L${line}: ${clip(raw.slice(start, end).trim())}`;
+}
 const CODE_KEYS = new Set(['jsCode', 'pythonCode', 'functionCode', 'code']);
 const CODE_TYPES = new Set(['code', 'function', 'functionItem']);
 const TRIGGER_NAMES = new Set(['webhook', 'manualTrigger', 'start', 'cron', 'interval']);
@@ -254,26 +265,35 @@ export function buildWorkflow(raw, id, file) {
         const envs = new Set();
         let dynamic = 0;
         walkStrings(n.parameters, (s, path, key) => {
-            let body;
             // Only {{ }} blocks are expressions; the rest of an "=" string is literal text
             // (e.g. an HTML page whose browser JS contains $('form')).
-            if (s.startsWith('='))
-                body = expressionBodies(s);
-            else if (isCodeNode && CODE_KEYS.has(key))
-                body = s;
-            if (!body)
-                return;
-            const ex = extractRefs(body);
-            dynamic += ex.dynamic;
-            ex.env.forEach((e) => envs.add(`res:env:${e}`));
-            ex.vars.forEach((e) => envs.add(`res:var:${e}`));
-            for (const name of ex.inferred)
-                inf.set(name, new Set([...(inf.get(name) ?? []), path]));
-            for (const r of ex.refs) {
-                const a = acc.get(r.name) ?? { fields: new Set(), params: new Set() };
-                r.fields.forEach((f) => a.fields.add(f));
-                a.params.add(path);
-                acc.set(r.name, a);
+            const units = [];
+            if (s.startsWith('=')) {
+                for (const b of expressionBlocks(s)) {
+                    const whole = clip(s.slice(b.start, b.end).replace(/\s+/g, ' ').trim());
+                    units.push({ body: b.body, snip: () => whole });
+                }
+            }
+            else if (isCodeNode && CODE_KEYS.has(key)) {
+                units.push({ body: s, snip: (at) => codeSnippet(s, at) });
+            }
+            for (const u of units) {
+                const ex = extractRefs(u.body);
+                dynamic += ex.dynamic;
+                ex.env.forEach((e) => envs.add(`res:env:${e}`));
+                ex.vars.forEach((e) => envs.add(`res:var:${e}`));
+                for (const name of ex.inferred)
+                    inf.set(name, new Set([...(inf.get(name) ?? []), path]));
+                for (const r of ex.refs) {
+                    const a = acc.get(r.name) ?? { fields: new Set(), params: new Set(), snips: new Map() };
+                    r.fields.forEach((f) => a.fields.add(f));
+                    a.params.add(path);
+                    for (const at of r.at) {
+                        const text = u.snip(at);
+                        a.snips.set(`${path}\u0000${text}`, { param: path, text });
+                    }
+                    acc.set(r.name, a);
+                }
             }
         });
         for (const [name, a] of acc) {
@@ -286,6 +306,7 @@ export function buildWorkflow(raw, id, file) {
             edges.push({
                 from: nid(name), to: nid(n.name), kind: 'reads', confidence: 'EXTRACTED',
                 fields: [...a.fields].sort(), params: [...a.params].sort(),
+                snippets: [...a.snips.values()].slice(0, MAX_SNIPPETS),
             });
         }
         // Names reached via a loop variable over a literal list: real dependencies, but only INFERRED.

package/dist/cli.js

@@ -10,7 +10,9 @@ import { G } from './graph.js';
 import { installClaude } from './install.js';
 import { serve } from './mcp.js';
 import { affected, callers, calls, explain, find, neighbors, paths, uses } from './queries.js';
+import { readNode } from './read.js';
 import { report, scan } from './report.js';
+import { stats } from './stats.js';
 import { buildFromFiles, N8nApi, syncApi } from './source.js';
 import { DEFAULT_DIR, graphPath, loadGraph, loadProfiles, saveGraph, saveProfiles, writeText } from './store.js';
 import { FLOW_KINDS } from './types.js';
@@ -172,16 +174,50 @@ program.command('uses').requiredOption('--cred <c>').action((o) => run(() => emi
 program
     .command('check')
     .description(`Health checks (${ALL_CHECKS.join(', ')})`)
-    .option('--only <name>', 'run a single check')
+    .option('--only <names>', 'run only these checks (comma separated)')
+    .option('--fail-on <level>', 'exit 1 when a finding is at least this severe: error | warn | info | none', 'error')
     .action((o) => run(() => {
-    if (o.only && !ALL_CHECKS.includes(o.only))
-        throw new Error(`Unknown check. Choose: ${ALL_CHECKS.join(', ')}`);
+    const only = o.only ? String(o.only).split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const bad = (only ?? []).filter((x) => !ALL_CHECKS.includes(x));
+    if (bad.length)
+        throw new Error(`Unknown check "${bad.join(', ')}". Choose from: ${ALL_CHECKS.join(', ')}`);
+    const rank = { error: 0, warn: 1, info: 2 };
+    const failOn = String(o.failOn);
+    if (failOn !== 'none' && !(failOn in rank))
+        throw new Error('--fail-on must be one of: error, warn, info, none');
     const g = load();
-    const f = runChecks(g, o.only ? [o.only] : undefined);
+    const f = runChecks(g, only);
     emit(formatFindings(g, f));
-    if (f.some((x) => x.severity === 'error'))
+    if (failOn !== 'none' && f.some((x) => rank[x.severity] <= rank[failOn]))
         process.exitCode = 1;
 })());
+program
+    .command('read <node>')
+    .description("Read part of a node's code in small pieces: outline (default), --grep, or --lines")
+    .option('--param <name>', 'parameter to read (default: the code parameter)')
+    .option('--lines <range>', '"120-180", "120" or "120-"')
+    .option('--grep <pattern>', 'lines matching a pattern, with context')
+    .option('--regex', 'treat the grep pattern as a regular expression')
+    .option('--case', 'case-sensitive grep')
+    .option('--context <n>', 'lines around each grep match', '2')
+    .option('--max <n>', 'grep matches to show', '20')
+    .option('--outline', 'size, functions and node references with line numbers')
+    .option('--cols <range>', 'character window per line, e.g. 241-480')
+    .option('--from <path>', 'read the source from this folder of exported workflows')
+    .action((n, o) => run(async () => {
+    emit(await readNode(load(), {
+        node: n, param: o.param, lines: o.lines, grep: o.grep, regex: o.regex, caseSensitive: o.case,
+        context: Number(o.context), max: Number(o.max), outline: o.outline, cols: o.cols, from: o.from,
+        dir: dirname(opts().graph ?? graphPath()),
+    }));
+})());
+program
+    .command('stats')
+    .description('Measure raw workflow JSON size against flownav replies on your own workflows')
+    .option('--from <path>', 'read the workflows from this folder of exports')
+    .action((o) => run(async () => {
+    emit(await stats(load(), { from: o.from, dir: dirname(opts().graph ?? graphPath()) }));
+})());
 program
     .command('diagram [workflow]')
     .description('Mermaid flowchart of a workflow, everything, or --focus <node>')

package/dist/expressions.js

@@ -24,35 +24,51 @@ function field(tail, needAccessor) {
         .join('.');
 }
 const unescape = (s) => s.replace(/\\(.)/g, '$1');
-/** Text inside {{ ... }} blocks of an expression string. */
-export function expressionBodies(s) {
+/** `{{ ... }}` blocks of an expression string: the inner code and where the whole block sits. */
+export function expressionBlocks(s) {
     const out = [];
     const re = /\{\{([\s\S]*?)\}\}/g;
     let m;
     while ((m = re.exec(s)))
-        out.push(m[1]);
-    return out.join('\n');
+        out.push({ body: m[1], start: m.index, end: m.index + m[0].length });
+    return out;
+}
+/** Text inside {{ ... }} blocks of an expression string. */
+export function expressionBodies(s) {
+    return expressionBlocks(s).map((b) => b.body).join('\n');
 }
 // String literals worth keeping: the argument of $('X') / $items('X') / $node['X'] and ["field"] accesses.
 const KEEP_BEFORE = /(?:\$\(|\$items\(|\$node\[|[\w$\])]\[)\s*$/;
 /**
  * Blank out comments and string-literal contents so text such as an HTML page held in a
  * string (`"...$('form')..."`) is not mistaken for a node reference. Template-literal
- * `${...}` code is kept and scanned.
+ * `${...}` code is kept and scanned. The result has the same length as the input (removed
+ * characters become spaces, newlines are kept), so offsets and line numbers still line up.
  */
 export function stripLiterals(src) {
-    let out = '';
+    const a = src.split('');
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (a[k] !== '\n')
+                a[k] = ' ';
+    };
+    const before = (i) => a.slice(Math.max(0, i - 24), i).join('');
     let i = 0;
     while (i < src.length) {
         const c = src[i];
         if (c === '/' && src[i + 1] === '/') {
-            while (i < src.length && src[i] !== '\n')
-                i++;
+            let j = i;
+            while (j < src.length && src[j] !== '\n')
+                j++;
+            blank(i, j);
+            i = j;
             continue;
         }
         if (c === '/' && src[i + 1] === '*') {
             const e = src.indexOf('*/', i + 2);
-            i = e < 0 ? src.length : e + 2;
+            const j = e < 0 ? src.length : e + 2;
+            blank(i, j);
+            i = j;
             continue;
         }
         if (c === '"' || c === "'") {
@@ -62,13 +78,16 @@ export function stripLiterals(src) {
                     j++;
                 j++;
             }
-            out += KEEP_BEFORE.test(out) ? src.slice(i, j + 1) : c + c;
+            if (!KEEP_BEFORE.test(before(i)))
+                blank(i + 1, Math.min(j, src.length));
             i = j + 1;
             continue;
         }
         if (c === '`') {
+            const keep = KEEP_BEFORE.test(before(i));
+            const texts = [];
+            let segStart = i + 1;
             let j = i + 1;
-            let code = '';
             while (j < src.length && src[j] !== '`') {
                 if (src[j] === '\\') {
                     j += 2;
@@ -84,20 +103,26 @@ export function stripLiterals(src) {
                             depth--;
                         k++;
                     }
-                    code += ` ${stripLiterals(src.slice(j + 2, k - 1))} `;
+                    texts.push([segStart, j]);
+                    const inner = stripLiterals(src.slice(j + 2, k - 1));
+                    for (let m = 0; m < inner.length; m++)
+                        a[j + 2 + m] = inner[m];
+                    segStart = k;
                     j = k;
                     continue;
                 }
                 j++;
             }
-            out += KEEP_BEFORE.test(out) ? src.slice(i, j + 1) : '``' + code;
+            texts.push([segStart, Math.min(j, src.length)]);
+            if (!keep)
+                for (const [s, e] of texts)
+                    blank(s, e);
             i = j + 1;
             continue;
         }
-        out += c;
         i++;
     }
-    return out;
+    return a.join('');
 }
 const STR = /(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
 /** Names in an array literal made only of string literals, else undefined. */
@@ -139,17 +164,18 @@ const RE_VARUSE = /\$(?:\(|items\()\s*([A-Za-z_$][\w$]*)\s*[,)]|\$node\s*\[\s*([
 export function extractRefs(raw) {
     const src = stripLiterals(raw);
     const byName = new Map();
-    const add = (name, f) => {
-        const set = byName.get(name) ?? new Set();
+    const add = (name, at, f) => {
+        const cur = byName.get(name) ?? { fields: new Set(), at: [] };
         if (f)
-            set.add(f);
-        byName.set(name, set);
+            cur.fields.add(f);
+        cur.at.push(at);
+        byName.set(name, cur);
     };
     const scan = (re, needAccessor) => {
         re.lastIndex = 0;
         let m;
         while ((m = re.exec(src))) {
-            add(unescape(m[2]), field(src.slice(re.lastIndex, re.lastIndex + 240), needAccessor));
+            add(unescape(m[2]), m.index, field(src.slice(re.lastIndex, re.lastIndex + 240), needAccessor));
         }
     };
     scan(RE_PAREN, true);
@@ -175,7 +201,7 @@ export function extractRefs(raw) {
         hit.forEach((n) => inferred.add(n));
     }
     return {
-        refs: [...byName].map(([name, f]) => ({ name, fields: [...f].sort() })),
+        refs: [...byName].map(([name, v]) => ({ name, fields: [...v.fields].sort(), at: v.at.sort((x, y) => x - y) })),
         inferred: [...inferred],
         env: names(RE_ENV),
         vars: names(RE_VARS),

package/dist/install.js

@@ -16,9 +16,10 @@ Then query the graph; do not open workflow JSON unless the graph cannot answer.
 - \`flownav path A B\` ordered paths with edge kinds and labels
 - \`flownav neighbors "<node>" --depth 2\`
 - \`flownav find --type httpRequest --cred slack --text "api.example"\`
-- \`flownav affected "<node>" --rename|--delete|--schema|--behavior\` **run before renaming or deleting a node**: expressions like \`$('Old Name')\` are not updated by n8n when connections are
+- \`flownav affected "<node>" --rename|--delete|--schema|--behavior\` **run before renaming or deleting a node**: references like \`$('Old Name')\` are not reliably rewritten (reportedly not inside Code nodes, and not for renames made through the API or by editing JSON), so list them first
 - \`flownav callers <workflow>\` / \`calls <workflow>\` cross-workflow links
 - \`flownav check\` fragile reads, dead refs, unreachable nodes, cycles, missing error handling
+- \`flownav read "<node>"\` read part of a Code node: start with the default outline (size, functions, node references with line numbers), then \`--grep "text"\` or \`--lines 120-180\`. Never read a whole large node at once; every reply is capped and secrets are redacted
 
 ## When the request is not specific
 

package/dist/mcp.js

@@ -1,8 +1,10 @@
 import { statSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { ALL_CHECKS, formatFindings, runChecks } from './checks.js';
 import { G } from './graph.js';
 import { affected, callers, calls, explain, find, neighbors, paths, uses } from './queries.js';
+import { readNode } from './read.js';
 import { report, scan } from './report.js';
 import { graphPath, loadGraph } from './store.js';
 import { VERSION } from './version.js';
@@ -17,7 +19,13 @@ const TOOLS = [
     { name: 'flownav_callers', description: 'Which workflows/nodes call this workflow (Execute Workflow, tool workflows, error workflow, webhook calls).', schema: { workflow: str }, run: (g, a) => callers(g, a.workflow) },
     { name: 'flownav_calls', description: 'What this workflow calls, plus unresolved dynamic calls.', schema: { workflow: str }, run: (g, a) => calls(g, a.workflow) },
     { name: 'flownav_uses', description: 'Nodes that use a credential (id, name or type).', schema: { credential: str }, run: (g, a) => uses(g, a.credential) },
-    { name: 'flownav_check', description: `Health checks: ${ALL_CHECKS.join(', ')}.`, schema: { only: str }, run: (g, a) => formatFindings(g, runChecks(g, a.only ? [a.only] : undefined)) },
+    { name: 'flownav_check', description: `Health checks: ${ALL_CHECKS.join(', ')}. Pass only="a,b" to run some.`, schema: { only: str }, run: (g, a) => formatFindings(g, runChecks(g, a.only ? String(a.only).split(',').map((x) => x.trim()) : undefined)) },
+    {
+        name: 'flownav_read',
+        description: 'Read PART of one node\'s code (or other long text) instead of the whole node. Start with the default outline (size, functions, which nodes the code references, with line numbers), then grep for a name or read a line range. Replies are capped at about 6,000 characters and secrets are redacted. Use cols to read inside very long (minified) lines. If the reply says the workflow changed since the graph was built, ask the user to sync. If the name is ambiguous or only a partial match, ask the user which node before acting.',
+        schema: { node: str, param: str, lines: str, grep: str, regex: { type: 'boolean' }, caseSensitive: { type: 'boolean' }, context: { type: 'number' }, max: { type: 'number' }, outline: { type: 'boolean' }, cols: str },
+        run: (g, a, ctx) => readNode(g, { node: a.node, param: a.param, lines: a.lines, grep: a.grep, regex: a.regex, caseSensitive: a.caseSensitive, context: a.context, max: a.max, outline: a.outline, cols: a.cols, dir: ctx.dir }),
+    },
     { name: 'flownav_report', description: 'Full markdown workflow report.', schema: {}, run: (g) => report(g) },
 ];
 export function serve(graphFile) {
@@ -63,13 +71,9 @@ export function serve(graphFile) {
                 const tool = TOOLS.find((t) => t.name === params?.name);
                 if (!tool)
                     return void fail(-32602, `Unknown tool ${params?.name}`);
-                try {
-                    const r = tool.run(getG(), params.arguments ?? {});
-                    reply({ content: [{ type: 'text', text: typeof r === 'string' ? r : r.text }] });
-                }
-                catch (err) {
-                    reply({ isError: true, content: [{ type: 'text', text: err.message }] });
-                }
+                Promise.resolve()
+                    .then(() => tool.run(getG(), params.arguments ?? {}, { dir: dirname(file) }))
+                    .then((r) => reply({ content: [{ type: 'text', text: typeof r === 'string' ? r : r.text }] }), (err) => reply({ isError: true, content: [{ type: 'text', text: err.message }] }));
             }
             else if (id !== undefined) {
                 fail(-32601, `Method not found: ${method}`);

package/dist/queries.js

@@ -173,13 +173,15 @@ export function affected(g, q, mode = 'rename') {
     const readers = g.outE(n.id, ['reads']);
     const lines = [`${g.label(n.id)} — impact of ${mode}`];
     const data = { node: n.id, mode };
+    /** the reader line, then the exact expression or code line(s) under it */
+    const withSnips = (head, e) => [head, ...(e.snippets ?? []).map((s) => `      ${s.param}: ${s.text}`)];
     const fmtReader = (e) => `${g.label(e.to)}${e.fields?.length ? ` uses {${e.fields.join(', ')}}` : ''}  in ${(e.params ?? []).join(', ')}${e.confidence === 'INFERRED' ? '  (inferred from a literal name list)' : ''}`;
     if (mode === 'rename' || mode === 'delete') {
         lines.push(readers.length
             ? `${readers.length} node(s) reference "${n.name}" by name and will ${mode === 'rename' ? 'break unless their expressions are rewritten' : 'read a missing node'}:`
             : `No expression references "${n.name}" by name.${mode === 'rename' ? " Safe to rename (connections are keyed by name; update them with the rename)." : ''}`);
         for (const e of readers)
-            lines.push(`  × ${fmtReader(e)}`);
+            lines.push(...withSnips(`  × ${fmtReader(e)}`, e));
         data.breaks = readers;
     }
     if (mode === 'delete') {
@@ -212,7 +214,7 @@ export function affected(g, q, mode = 'rename') {
     if (mode === 'schema') {
         lines.push(readers.length ? 'nodes reading fields from this node:' : 'No node reads this node by name.');
         for (const e of readers)
-            lines.push(`  ! ${fmtReader(e)}`);
+            lines.push(...withSnips(`  ! ${fmtReader(e)}`, e));
         const succ = g.outE(n.id, ['main']);
         if (succ.length) {
             lines.push('direct successors (may use $json / $input, field use is not tracked):');

package/dist/read.js

@@ -0,0 +1,277 @@
+import { readFileSync } from 'node:fs';
+import { buildWorkflow } from './build.js';
+import { extractRefs } from './expressions.js';
+import { extractWorkflows, loadFiles, N8nApi } from './source.js';
+import { loadProfiles } from './store.js';
+import { redactString } from './util.js';
+/** Hard cap on what one call returns, whatever the request asks for. */
+export const MAX_CHARS = 6000;
+const DEFAULT_WIDTH = 240;
+const MAX_LINE_SCAN = 5000;
+const CODE_PARAMS = ['jsCode', 'pythonCode', 'functionCode', 'code'];
+/* ---------------- source ---------------- */
+export async function loadRaw(g, wfId, o) {
+    const info = g.g.workflows[wfId];
+    const pick = (wfs) => wfs.find((w) => w.id != null && String(w.id) === wfId) ??
+        wfs.find((w) => w.name === info.name) ??
+        (wfs.length === 1 ? wfs[0] : undefined);
+    if (o.from) {
+        const hit = pick(loadFiles(o.from).items.map((i) => i.raw));
+        if (!hit)
+            throw new Error(`Workflow "${info.name}" (${wfId}) was not found under ${o.from}.`);
+        return hit;
+    }
+    if (g.g.source.type === 'files') {
+        if (!info.file)
+            throw new Error(`The graph does not record a source file for ${wfId}. Rebuild it, or pass a folder of exports.`);
+        let wfs;
+        try {
+            wfs = extractWorkflows(JSON.parse(readFileSync(info.file, 'utf8')));
+        }
+        catch {
+            throw new Error(`Cannot read ${info.file}. Pass the folder of exports to read from.`);
+        }
+        const hit = pick(wfs);
+        if (!hit)
+            throw new Error(`Workflow "${info.name}" is not in ${info.file} any more.`);
+        delete hit.pinData;
+        return hit;
+    }
+    const profile = g.g.source.profile ? loadProfiles(o.dir)[g.g.source.profile] : undefined;
+    const keyEnv = profile?.keyEnv ?? 'N8N_API_KEY';
+    const key = process.env[keyEnv];
+    if (!key) {
+        throw new Error(`Reading code from the live instance needs the API key in the ${keyEnv} environment variable of this process (read-only GET). Set it, or read from exported files instead.`);
+    }
+    const wf = await new N8nApi(g.g.source.ref, key).get(`/workflows/${encodeURIComponent(wfId)}`);
+    delete wf.pinData;
+    return wf;
+}
+/* ---------------- parameter + redaction ---------------- */
+function getPath(obj, path) {
+    // accepts the paths this module prints, e.g. "assignments.assignments[0].value"
+    return path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean).reduce((a, k) => (a == null ? undefined : a[k]), obj);
+}
+function textParams(v, prefix = '', out = [], depth = 0) {
+    if (depth > 8 || v == null)
+        return out;
+    if (typeof v === 'string') {
+        if (v.length)
+            out.push({ path: prefix, len: v.length });
+    }
+    else if (Array.isArray(v)) {
+        v.forEach((x, i) => textParams(x, `${prefix}[${i}]`, out, depth + 1));
+    }
+    else if (typeof v === 'object') {
+        for (const [k, x] of Object.entries(v))
+            textParams(x, prefix ? `${prefix}.${k}` : k, out, depth + 1);
+    }
+    return out;
+}
+function listText(node) {
+    const rows = textParams(node.parameters).sort((a, b) => b.len - a.len).slice(0, 8);
+    return rows.length ? `Text parameters: ${rows.map((r) => `${r.path} (${r.len.toLocaleString('en-US')} chars)`).join(', ')}.` : 'It has no text parameters.';
+}
+function pickParam(node, wanted) {
+    const p = (node.parameters ?? {});
+    if (wanted) {
+        const v = getPath(p, wanted);
+        if (typeof v !== 'string')
+            throw new Error(`Parameter "${wanted}" of ${node.name} is not text. ${listText(node)}`);
+        return { name: wanted, text: v };
+    }
+    for (const k of CODE_PARAMS)
+        if (typeof p[k] === 'string')
+            return { name: k, text: p[k] };
+    throw new Error(`${node.name} has no code parameter; pass param. ${listText(node)}`);
+}
+const KEYED = /((?:api[-_]?key|token|secret|passw(?:or)?d|authorization|private[-_]?key|client[-_]?secret)["']?\s*[:=]\s*)(["'`])([^"'`\n]{6,})\2/gi;
+/** Best-effort redaction of a line of code: key-like assignments and known token shapes. */
+export function redactCode(line) {
+    return redactString(line.replace(KEYED, (_m, pre, q) => `${pre}${q}[REDACTED]${q}`));
+}
+/* ---------------- formatting ---------------- */
+function parseRange(s, what) {
+    const m = /^\s*(\d*)\s*(-?)\s*(\d*)\s*$/.exec(s ?? '');
+    if (!s || !m || (!m[1] && !m[3]))
+        throw new Error(`${what} must look like "120-180", "120" or "120-".`);
+    const a = m[1] ? Number(m[1]) : 1;
+    const b = m[2] ? (m[3] ? Number(m[3]) : undefined) : a;
+    if (a < 1 || (b !== undefined && b < a))
+        throw new Error(`${what} "${s}" is not a valid range.`);
+    return [a, b];
+}
+/** One line for display: windowed and marked when it is longer than the window. */
+function show(line, cols, focus) {
+    let start = 0;
+    let end = line.length;
+    if (cols) {
+        start = cols[0] - 1;
+        end = cols[1] ?? start + DEFAULT_WIDTH;
+    }
+    else if (line.length > DEFAULT_WIDTH) {
+        start = focus != null && focus > DEFAULT_WIDTH - 40 ? Math.max(0, focus - 80) : 0;
+        end = start + DEFAULT_WIDTH;
+    }
+    if (start >= line.length && line.length > 0)
+        return `[line has ${line.length} chars; the window starts at column ${start + 1}]`;
+    const body = line.slice(start, end);
+    return `${start > 0 ? '…' : ''}${body}${end < line.length ? `… [+${(line.length - end).toLocaleString('en-US')} chars, ${line.length.toLocaleString('en-US')} total]` : ''}`;
+}
+const lineIndexOf = (text, at) => text.slice(0, at).split('\n').length;
+function outlineOf(text, lines) {
+    const out = [];
+    const longest = lines.reduce((m, l) => Math.max(m, l.length), 0);
+    out.push(`longest line: ${longest.toLocaleString('en-US')} chars${longest > 1000 ? ' (minified or generated: use cols to read inside long lines)' : ''}`);
+    const fns = [];
+    lines.forEach((l, i) => {
+        const m = /^\s*(?:export\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/.exec(l) ??
+            /^\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/.exec(l) ??
+            /^\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?function/.exec(l) ??
+            /^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/.exec(l);
+        if (m)
+            fns.push(`L${i + 1} ${m[1]}`);
+    });
+    out.push(fns.length ? `functions (${fns.length}): ${fns.slice(0, 30).join(', ')}${fns.length > 30 ? ', …' : ''}` : 'functions: none found');
+    const ex = extractRefs(text);
+    if (ex.refs.length || ex.inferred.length) {
+        out.push('node references:');
+        for (const r of ex.refs) {
+            const ls = [...new Set(r.at.map((a) => lineIndexOf(text, a)))];
+            out.push(`  ${r.name}  line${ls.length > 1 ? 's' : ''} ${ls.slice(0, 12).join(', ')}${ls.length > 12 ? ', …' : ''}${r.fields.length ? `  {${r.fields.join(', ')}}` : ''}`);
+        }
+        if (ex.inferred.length)
+            out.push(`  via a literal name list (inferred): ${ex.inferred.join(', ')}`);
+    }
+    else {
+        out.push('node references: none');
+    }
+    if (ex.dynamic)
+        out.push(`computed-name references: ${ex.dynamic} (cannot be resolved statically)`);
+    if (ex.env.length)
+        out.push(`env vars: ${ex.env.join(', ')}`);
+    if (ex.vars.length)
+        out.push(`vars: ${ex.vars.join(', ')}`);
+    return out;
+}
+/* ---------------- main ---------------- */
+export async function readNode(g, o) {
+    const modes = [o.lines != null, o.grep != null, o.outline === true].filter(Boolean).length;
+    if (modes > 1)
+        throw new Error('Give only one of: lines, grep, outline.');
+    const { node: n, fuzzy } = g.resolveNodeEx(o.node);
+    const wf = await loadRaw(g, n.wf, o);
+    const notes = [];
+    if (fuzzy)
+        notes.push(`NOTE: "${fuzzy}" was only a partial name and matched just ${g.label(n.id)}. Confirm with the user that this is the node they mean before changing anything.`);
+    if (buildWorkflow(wf, n.wf).info.hash !== g.g.workflows[n.wf].hash) {
+        notes.push('WARNING: this workflow changed since the graph was built, so line numbers and references may not match the graph. Run flownav sync (or build) to refresh it. Showing the current source.');
+    }
+    const raw = wf.nodes?.find((x) => x.name === n.name);
+    if (!raw)
+        throw new Error(`Node "${n.name}" is no longer in the current source of ${g.wfName(n.wf)}. The graph is stale: run flownav sync (or build).`);
+    const { name: param, text } = pickParam(raw, o.param);
+    const lines = text.split(/\r?\n/);
+    const total = lines.length;
+    const safe = lines.map(redactCode);
+    const cols = o.cols ? parseRange(o.cols, 'cols') : undefined;
+    const head = `${g.label(n.id)} · ${param} · ${total.toLocaleString('en-US')} line(s), ${text.length.toLocaleString('en-US')} chars`;
+    const out = [...notes, head];
+    let used = out.join('\n').length;
+    const data = { node: n.id, param, totalLines: total, chars: text.length };
+    const push = (s) => {
+        if (used + s.length + 1 > MAX_CHARS)
+            return false;
+        out.push(s);
+        used += s.length + 1;
+        return true;
+    };
+    if (!text.length) {
+        out.push('(empty)');
+        return { text: out.join('\n'), data };
+    }
+    if (o.lines != null) {
+        const [a, b] = parseRange(o.lines, 'lines');
+        if (a > total)
+            throw new Error(`lines "${o.lines}" starts past the end: ${param} has ${total} line(s).`);
+        const end = Math.min(b ?? a + 59, total, a + 199);
+        const w = String(end).length;
+        let shown = a - 1;
+        for (let i = a; i <= end; i++) {
+            if (!push(`  ${String(i).padStart(w)}: ${show(safe[i - 1], cols)}`))
+                break;
+            shown = i;
+        }
+        const next = shown < total ? `; next: lines ${shown + 1}-${Math.min(total, shown + 60)}` : ' (end)';
+        out.push(`showing ${a}-${shown} of ${total}${shown < end ? ` (output capped at ${MAX_CHARS} chars)` : ''}${next}`);
+        Object.assign(data, { mode: 'lines', from: a, to: shown });
+        return { text: out.join('\n'), data };
+    }
+    if (o.grep != null) {
+        const pattern = o.grep;
+        if (!pattern)
+            throw new Error('grep needs a pattern.');
+        if (o.regex && pattern.length > 200)
+            throw new Error('A regex pattern may be at most 200 characters.');
+        let re;
+        try {
+            re = new RegExp(o.regex ? pattern : pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), o.caseSensitive ? '' : 'i');
+        }
+        catch (e) {
+            throw new Error(`Invalid regex: ${e.message}`);
+        }
+        const ctx = Math.min(Math.max(o.context ?? 2, 0), 10);
+        const max = Math.min(Math.max(o.max ?? 20, 1), 100);
+        const hits = [];
+        safe.forEach((l, i) => {
+            const m = re.exec(l.slice(0, MAX_LINE_SCAN));
+            if (m)
+                hits.push({ i, col: m.index });
+        });
+        if (!hits.length) {
+            out.push(`no match for ${o.regex ? 'regex ' : ''}"${pattern}"${o.caseSensitive ? '' : ' (case-insensitive)'}. Try a shorter pattern, regex=true, or outline.`);
+            Object.assign(data, { mode: 'grep', matches: 0 });
+            return { text: out.join('\n'), data };
+        }
+        const use = hits.slice(0, max);
+        const focus = new Map(use.map((h) => [h.i, h.col]));
+        const groups = [];
+        for (const h of use) {
+            const from = Math.max(0, h.i - ctx);
+            const to = Math.min(total - 1, h.i + ctx);
+            const last = groups[groups.length - 1];
+            if (last && from <= last[1] + 1)
+                last[1] = Math.max(last[1], to);
+            else
+                groups.push([from, to]);
+        }
+        const w = String(total).length;
+        let shownMatches = 0;
+        let capped = false;
+        outer: for (let gi = 0; gi < groups.length; gi++) {
+            if (gi > 0 && !push('  --')) {
+                capped = true;
+                break;
+            }
+            for (let i = groups[gi][0]; i <= groups[gi][1]; i++) {
+                const isHit = focus.has(i);
+                if (!push(`${isHit ? '>' : ' '} ${String(i + 1).padStart(w)}: ${show(safe[i], cols, focus.get(i))}`)) {
+                    capped = true;
+                    break outer;
+                }
+                if (isHit)
+                    shownMatches++;
+            }
+        }
+        out.push(`${shownMatches} of ${hits.length} matching line(s) shown${capped ? ` (output capped at ${MAX_CHARS} chars)` : ''}${hits.length > shownMatches ? '; narrow the pattern, raise max, or read a range with lines' : ''}`);
+        Object.assign(data, { mode: 'grep', matches: hits.length, shown: shownMatches });
+        return { text: out.join('\n'), data };
+    }
+    // default and explicit outline
+    for (const l of outlineOf(text, lines))
+        if (!push(l))
+            break;
+    out.push('next: grep for a name, or read a range with lines');
+    Object.assign(data, { mode: 'outline' });
+    return { text: out.join('\n'), data };
+}

package/dist/stats.js

@@ -0,0 +1,64 @@
+import { formatFindings, runChecks } from './checks.js';
+import { affected, explain } from './queries.js';
+import { loadRaw } from './read.js';
+import { scan } from './report.js';
+import { trunc } from './util.js';
+const tok = (s) => Math.round(s.length / 4);
+const fmt = (n) => n.toLocaleString('en-US');
+function median(xs) {
+    if (!xs.length)
+        return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+const pct = (small, big) => (big > 0 ? `${Math.max(0, Math.round((1 - small / big) * 100))}% fewer` : 'n/a');
+/**
+ * Measure, on your own workflows, how much an agent would read without flownav (the whole
+ * workflow JSON) against what flownav replies with. Tokens are estimated as characters / 4.
+ */
+export async function stats(g, o) {
+    const wfs = Object.values(g.g.workflows);
+    const rows = [];
+    for (const w of wfs) {
+        const raw = await loadRaw(g, w.id, o);
+        delete raw.pinData;
+        const rawTokens = tok(JSON.stringify(raw, null, 2));
+        rows.push({ id: w.id, name: w.name, nodes: w.nodeCount, rawTokens, perNode: w.nodeCount ? Math.round(rawTokens / w.nodeCount) : 0 });
+    }
+    rows.sort((a, b) => b.rawTokens - a.rawTokens);
+    const explainToks = g.g.nodes.map((n) => tok(explain(g, n.id).text));
+    const withReaders = g.g.nodes.filter((n) => g.outE(n.id, ['reads']).length);
+    const affectedToks = withReaders.map((n) => tok(affected(g, n.id, 'rename').text));
+    const scanTok = tok(scan(g).text);
+    const checkTok = tok(formatFindings(g, runChecks(g)).text);
+    const totalRaw = rows.reduce((a, r) => a + r.rawTokens, 0);
+    const totalNodes = rows.reduce((a, r) => a + r.nodes, 0);
+    const medRaw = median(rows.map((r) => r.rawTokens));
+    const medExplain = median(explainToks);
+    const medAffected = median(affectedToks);
+    const tau = totalNodes ? Math.round(totalRaw / totalNodes) : 0;
+    const w = Math.min(36, Math.max(...rows.map((r) => r.name.length), 8));
+    const L = [];
+    L.push(`${'workflow'.padEnd(w)}  ${'nodes'.padStart(5)}  ${'raw tokens'.padStart(10)}  ${'per node'.padStart(8)}`);
+    for (const r of rows)
+        L.push(`${trunc(r.name, w).padEnd(w)}  ${String(r.nodes).padStart(5)}  ${fmt(r.rawTokens).padStart(10)}  ${String(r.perNode).padStart(8)}`);
+    L.push(`${'total'.padEnd(w)}  ${String(totalNodes).padStart(5)}  ${fmt(totalRaw).padStart(10)}  ${String(tau).padStart(8)}`);
+    L.push('');
+    L.push('Cost of one question about one workflow (median):');
+    L.push(`  read the whole workflow JSON      ${fmt(medRaw).padStart(8)} tokens`);
+    L.push(`  flownav explain                   ${fmt(medExplain).padStart(8)} tokens   ${pct(medExplain, medRaw)}`);
+    L.push(`  flownav affected --rename         ${fmt(medAffected).padStart(8)} tokens   ${pct(medAffected, medRaw)}${withReaders.length ? '' : '  (no references found)'}`);
+    L.push('');
+    L.push('Whole instance:');
+    L.push(`  read every workflow               ${fmt(totalRaw).padStart(8)} tokens`);
+    L.push(`  flownav scan                      ${fmt(scanTok).padStart(8)} tokens   ${pct(scanTok, totalRaw)}`);
+    L.push(`  flownav check (all findings)      ${fmt(checkTok).padStart(8)} tokens   ${pct(checkTok, totalRaw)}`);
+    L.push('');
+    L.push(`Tokens are estimated as characters / 4 on each workflow's JSON re-printed with 2-space indentation (about ${tau} tokens per node here).`);
+    L.push('These compare against an agent that reads the whole workflow. An agent that searches first reads less, so treat the percentages as upper bounds.');
+    return {
+        text: L.join('\n'),
+        data: { workflows: rows, totalRawTokens: totalRaw, tokensPerNode: tau, median: { workflow: medRaw, explain: medExplain, affected: medAffected }, scan: scanTok, check: checkTok },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flownav",
-  "version": "0.1.2",
-  "description": "Typed node graph for n8n workflows: explain, path, affected (rename/delete safety), checks, and an MCP server so agents navigate workflows with far fewer tokens.",
+  "version": "0.2.0",
+  "description": "See what references an n8n node before you rename it. A typed graph of your workflows with a CLI and an MCP server, so AI agents read a few lines instead of the whole workflow JSON.",
   "author": "Omer Turkenits",
   "license": "MIT",
   "repository": {
@@ -32,8 +32,15 @@
   "keywords": [
     "n8n",
     "workflow",
+    "workflow-automation",
     "graph",
     "mcp",
+    "model-context-protocol",
+    "ai",
+    "ai-agents",
+    "claude",
+    "rename",
+    "static-analysis",
     "cli"
   ],
   "dependencies": {