@path58/p58-n8n 0.2.17 → 0.2.20-demo.2

package/README.md

@@ -1,45 +1,76 @@
 # p58-n8n — The n8n MCP Server That Gets Workflows Right
 
-**Build n8n workflows from plain English. First try. Every time.**
+**Build n8n workflows from plain English — execution-verified, built to land on the first try.**
 
 [![npm](https://img.shields.io/npm/v/@path58/p58-n8n)](https://www.npmjs.com/package/@path58/p58-n8n)
 [![License: BSL 1.1](https://img.shields.io/badge/License-BSL_1.1-orange.svg)](LICENSE)
-[![Tests: 9,860 passed](https://img.shields.io/badge/Tests-9%2C860_passed-brightgreen)](https://github.com/tsvika58/p58-n8n/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/tsvika58/p58-n8n/ci.yml?branch=main&label=CI)](https://github.com/tsvika58/p58-n8n/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-p58-n8n is an MCP server that gives your AI assistant deep knowledge of n8n — **1,545 nodes**, **12,619 operations**, **679 credential types** — so it can plan, build, validate, fix, and deploy workflows correctly.
+p58-n8n is an MCP server that gives your AI assistant a catalog of n8n — an offline index of **1,603 nodes**, **14,805 operations**, and **679 credential types**, plus (with a premium token) the full parameter & connection schemas<sup>[[1]](#sources)</sup> — so it can plan, build, validate, fix, and deploy workflows correctly.
 
 > **🤖 AI Agent?** Read [`AGENT_INSTALL.md`](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for the autonomous installation guide.
 
 ---
 
 ## Why p58?
-|                        | **p58-n8n**            | Other MCP servers      | LLM alone              |
-|------------------------|------------------------|------------------------|------------------------|
-| **Pass rate**          | **100%** (all models)  | 56%                    | 56%                    |
-| **Cost per workflow**  | **$0.24** (Haiku)      | $4–6/pass              | $7.16/pass             |
-| **Avg conversation**   | 22.7 turns             | 60–71 turns            | 59.6 turns             |
-| **Credential mgmt**   | ✅ Full lifecycle       | ❌                      | ❌                      |
-| **Validation**         | ✅ Multi-layer          | ❌                      | ❌                      |
-| **Auto-fix**           | ✅ Deterministic        | ❌                      | ❌                      |
-| **Catalog bundled**    | ✅ Works offline        | Needs live n8n          | Guesses from training  |
-
-<details>
-<summary>📊 Benchmark methodology</summary>
-
-25 real-world n8n workflow prompts. 225 total runs across Haiku 4.5, Sonnet 4.6, and Opus 4.6.
-Five MCP servers tested head-to-head in nine configurations. Each arm ran in isolation with no
-shared context. Scored using AX (Agent Experience) — a behavioral framework measuring planning
-quality, tool use, efficiency, and recovery. Full evidence available on request.
-
-</details>
+
+p58-n8n is built around one honest metric — **1-shot-1-kill (STRONG ⭐)**: the agent builds a working, *execution-verified* workflow on the **first** try. We publish it as a strict, audit-grade number (not a pass-rate slogan), and we report pass-rate as a separate column on purpose. The capability differences that drive it:
+
+**What p58-n8n does:**
+
+- **Full credential lifecycle** — discover, health-check (HTTP/TCP), create, and wire n8n credentials.
+- **Multi-layer validation (L1–L6)** plus deterministic auto-fix against the real catalog.
+- **Execution-verified testing** — `test_workflow` returns n8n's synchronous execution result, so a "pass" means the workflow *actually ran*. Competitor n8n MCP servers can prove only "HTTP 200 — saved" (REST CRUD), which is why all 9 measured competitor architectures sit at **0% strong-proof** in our canonical shootout.<sup>[[2]](#sources)</sup>
+- **Offline discovery index** bundled in npm (node/operation/credential names); the enriched catalog (parameter & connection schemas) is unlocked with a premium token.
+
+See **[v5 Demo & Honest Performance](#v5-demo--honest-performance)** for the measured numbers and methodology.
+
+---
+
+## v5 Demo & Honest Performance
+
+### Install for the demo
+
+**Easiest — one-click Desktop Extension:** install **`p58-n8n.mcpb`** in Claude Desktop (Settings → Extensions → Install Extension…) and fill the prompted fields. No JSON editing, no terminal; the bundle carries its own runtime deps. See [docs/INSTALLATION.md › Claude Desktop](docs/INSTALLATION.md#claude-desktop).
+
+**Or via npm** — if you were given a `P58_ACCESS_TOKEN`, install the **demo** build explicitly (not the bare package, which resolves to an older `latest` tag):
+
+```bash
+npm install @path58/p58-n8n@demo
+```
+
+Then follow **[docs/GET-STARTED-IN-5-MIN.md](docs/GET-STARTED-IN-5-MIN.md)** — token-in-hand to your first agent-built, agent-tested workflow in under 10 minutes, entirely through Claude Desktop.
+
+### One-shot-one-kill (STRONG ⭐) — the metric we actually publish
+
+Our North-Star metric is **1-shot-1-kill STRONG ⭐**: the agent gets it right on the **first** attempt — one `build_workflow`, the **first** `test_workflow` runs green, no patches, no rebuilds — **and** the harness directly observed the workflow execute (audit-grade proof). It is deliberately stricter than pass rate.
+
+Measured on the v5 release, canonical 250-cell shootout (golden07 substrate)<sup>[[2]](#sources)</sup>:
+
+| Model | 1-shot-1-kill STRONG ⭐ | Pass rate (eventual) |
+|---|---|---|
+| **P58 + Opus** | **42%** (21/50) | 100% |
+| **P58 + Sonnet** | **38%** (19/50) | 100% |
+| **P58 + Haiku** | **4%** (2/50) | 94% |
+| **Every competitor MCP (9 architectures)** | **0%** | varies |
+
+> **These two columns measure different things.** Pass rate = "eventually got there, possibly after several patches." STRONG ⭐ = "got it right on the first try, with verified proof it ran." The **Pass rate (eventual)** column is the eventual-success number; the **STRONG ⭐** column is the first-try-with-proof number. We report them as separate columns on purpose — collapsing them into one "we're always right" claim would be a Goodhart trap our methodology doctrine explicitly forbids.
+
+### Why every competitor sits at 0% STRONG — architecture, not tuning
+
+Competitor n8n MCP servers talk to n8n over **REST CRUD** (create / update / delete). The strongest proof they can produce is "HTTP 200 — workflow saved," after which the harness must *poll* the executions list to guess which run was theirs — a weak proof tier. The signal that proves a workflow actually executed the way you asked lives in n8n's execution-result payload, and **only p58-n8n's `test_workflow` returns that synchronously.** Under fair, identical scoring, competitors can *claim* success but cannot *prove* execution, so they top out at the "ran, weak proof" tier and reach **zero** strong-proof cells across all 9 measured architectures.
+
+The most extreme case is **N8NMCP-V253**: across 25 cells it logged **0 strong-proof (verified-green)** results and **25 weak-proof (verified-yellow)** results. It uses `n8n_update_partial_workflow` as its *primary* editing tool — so every workflow is assembled through one or more patches **by design**, which architecturally rules out the one-shot trace shape on top of the proof-tier ceiling. It cannot reach STRONG even in principle. That is an architectural moat, not a tuning gap.
+
+> **Methodology footnote.** All v5 numbers were measured per the RAG-4.97.8 v5 release on the canonical **golden07** substrate, per the formal `is_1s1k_strong(cell)` definition in STRATEGIC_ANCHORS v1.2.0, and were **substrate-clean** per the INC-2026-05-29 memory-quarantine fix (pre-2026-05-29 baselines on this hardware are non-canonical and are not cited here). Tier colors were cross-validated by the canonical reclassifier (`per-cell-outcome-1.1.0` schema). This is the project's first canonical-clean performance release.
 
 ---
 
 ## How It Works
 ```mermaid
 graph LR
-    A["🗣️ Plain English<br/>prompt"] --> B["📋 plan_workflow<br/>Research & design"]
+    A["🗣️ Plain English<br/>prompt"] --> B["📋 Plan<br/>Research & design"]
     B --> C["🔨 build_workflow<br/>Assemble JSON"]
     C --> D["✅ Validate<br/>Structure · Nodes · Creds"]
     D --> E{"Pass?"}
@@ -53,6 +84,26 @@ You say what you want. p58-n8n plans the architecture, builds valid JSON, valida
 
 ---
 
+## Install in 30 seconds — AX-Native (recommended)
+
+If you have an MCP-aware client (Claude Desktop, Claude Code, Cursor, etc.), the fastest install is to tell your client to do it:
+
+> **You:** *"Install the p58-n8n MCP server using `https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md` as the guide."*
+
+Your LLM reads our agent install guide, auto-probes for your n8n instance, asks **at most 2 questions** (your n8n API key and — if you have one — your Path58 premium token), writes the config, and tells you to restart. Total: ~30 seconds, two pastes. The agent handles the rest.
+
+This is the **AX-Native install** path — every customer-facing operation happens through the agent you already use, per the project's Pillar 3 design (`STRATEGIC_ANCHORS.md` v1.2.0 § Pillar 3 — AX-Native).
+
+**Don't have premium / want to try free first?** Tell your agent *"install with free tier only"* — it skips the premium-token question and configures discovery + L1-L3 validation only. Upgrade later by adding `P58_ACCESS_TOKEN` to your config.
+
+### Alternatives if you prefer non-agent install
+
+- [**Manual JSON config**](docs/INSTALLATION.md) — multi-client guide; you edit the config file yourself
+- [**Claude Desktop Extension (`.mcpb`)**](#claude-desktop-extension-mcpb) — drag-and-drop install; zero-config quick start works instantly
+- See [**Supported clients**](#supported-clients) for verified-tier client coverage
+
+---
+
 ## Quick Start
 
 **Install and run (no global install needed):**
@@ -83,22 +134,25 @@ claude mcp add p58-n8n \
 }
 ```
 
-> **Note:** Catalog tools work immediately from the bundled data — no n8n connection needed.
-> `N8N_API_URL` + `N8N_API_KEY` unlock workflow and credential management on your server.
-### Supported Clients
+> **Note:** Node/operation/credential *discovery* works offline from the bundled index. Full parameter & connection schemas (needed to actually build) require a premium `P58_ACCESS_TOKEN`. `N8N_API_URL` + `N8N_API_KEY` unlock workflow + credential management on your server.
+### Supported clients
 
-| Client | Setup |
-|--------|-------|
-| **Claude Code** | `claude mcp add` — one command |
-| **Claude Desktop** | JSON config → restart |
-| **Cursor** | MCP config file |
-| **Windsurf** | MCP config file |
+| Client | Status |
+|---|---|
+| **Claude Desktop** (manual config) | ✅ **Verified** — Phase C install matrix C-3 GREEN; canonical demo path |
+| **Claude Desktop Extensions** (`.mcpb` drag-and-drop) | ✅ **Verified — zero-config quick start** (drag, install, save blank for free-tier instant access); ⚠️ premium + n8n full-config requires 7-field manual paste until 0.3.0 (`REQ-2026-06-02-mcpb-config-autofill.md`) |
+| **Claude Code** (CLI / VS Code extension / terminal) | ✅ **Verified** — used end-to-end for RAG-4.97.6.1 RND execution (this task itself) |
+| Cursor / VS Code Copilot / Windsurf | ⚠️ **Documented, verification pending** — should work via standard MCP protocol; please report issues via GitHub Issues |
+| Codex (OpenAI) / Antigravity (Google) / Gemini CLI (legacy) | ⚠️ **Documented, verification pending** — multi-client QA matrix queued post-demo (`REQ-2026-06-02-multi-client-install-qa.md`) |
 
-See [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for all clients, config templates, and troubleshooting.
+See [docs/INSTALLATION.md](https://github.com/tsvika58/p58-n8n/blob/main/docs/INSTALLATION.md) for all clients, config templates, and troubleshooting.
 
 ---
 
-## 12 Tools — Everything You Need
+## Your Core Toolset
+
+p58-n8n surfaces **18 MCP tools** (the Config-C locked set): **5 catalog/validation tools that work offline (free)** plus **13 that operate on your connected n8n** (workflow build/test/deploy + full credential management). Run `setup_check` for the live availability breakdown in your session.<sup>[[3]](#sources)</sup>
+
 ```mermaid
 graph TB
     subgraph catalog["📚 Catalog Intelligence"]
@@ -107,7 +161,6 @@ graph TB
     end
 
     subgraph workflows["⚡ Workflow Management"]
-        C["list_workflows<br/><i>Browse & filter workflows</i>"]
         D["get_workflow<br/><i>Fetch workflow by ID</i>"]
         E["build_workflow<br/><i>Plan → validate → fix → deploy → test</i>"]
         F["partial_update_workflow<br/><i>Surgical diff-based updates</i>"]
@@ -123,44 +176,42 @@ graph TB
     end
 ```
 
-### Catalog Intelligence (2 tools)
-
-**`setup_check`** — Full diagnostic: server version, n8n connectivity, credential count, tool availability. Run this first.
+### Catalog & validation — 5 tools (work offline, free)
 
-**`get_node_info`** — Deep lookup for any of 1,545 nodes: operations, credential requirements, property schemas, config examples, version history.
-### Workflow Management (8 tools)
+**`setup_check`** — Full diagnostic: server version, n8n connectivity, credential count, live tool availability. Run this first.
+**`get_node_info`** — Look up any of 1,603 nodes: metadata, operations, credential requirements, best-practices, version history. (Full property schemas + config examples require a premium token.)
+**`get_operation_parameters`** / **`get_operation_schema`** — Parameter requirements and schema details for any node operation.
+**`activate_premium`** — Activate premium catalog access with your `P58_ACCESS_TOKEN`.
 
-**`build_workflow`** — The powerhouse. Takes a structured spec → assembles JSON → validates → auto-fixes → deploys → tests. End-to-end in one call.
-
-**`list_workflows`** / **`get_workflow`** — Browse, filter, and fetch workflows from your n8n server.
-
-**`partial_update_workflow`** — Surgical, diff-based updates. Six atomic operations with pre-validation — no need to replace the entire workflow.
+### Workflow engine — 7 tools (need your connected n8n)
 
+**`build_workflow`** — The powerhouse. Structured spec → assemble JSON → validate → auto-fix → deploy → test, end-to-end in one call.
+**`test_workflow`** — Auto-detects trigger type (webhook, schedule, manual), executes, and returns per-node results. Handles `respondToWebhook` safely.
+**`get_workflow`** — Fetch a workflow by ID from your n8n server.
+**`partial_update_workflow`** — Surgical, diff-based updates with pre-validation — no need to replace the entire workflow.
 **`activate_workflow`** / **`delete_workflow`** — Toggle state or safely remove workflows.
+**`get_execution_result`** — Detailed per-node execution data for debugging.
 
-**`test_workflow`** — Auto-detects trigger type (webhook, schedule, manual), executes, and returns results. Handles `respondToWebhook` safely.
-
-**`get_execution_result`** — Detailed execution data with per-node output for debugging.
+### Credential management — 6 tools (need your connected n8n)
 
-### Credential Lifecycle (2 tools)
-
-**`list_credentials`** — Discover all credentials on your n8n server with optional schema enrichment and node filtering. See what you have before building.
-
-**`test_credential`** — Health-check probe supporting 25 credential types via HTTP and TCP. Know if your Slack token, database connection, or API key is actually working before wiring it into a workflow.
+**`list_credentials`** — Discover credentials on your n8n server with optional schema enrichment and node filtering.
+**`test_credential`** — Health-check probe (HTTP + TCP) — know if a token/connection works before wiring it into a workflow.
+**`create_credential`** / **`update_credential`** / **`delete_credential`** — Full credential lifecycle, validated against the catalog schema.
+**`get_credential_schema`** — Required/optional fields for any of 679 credential types.
 
 ---
 
 ## Architecture
 ```mermaid
 graph TB
-    Client["AI Client<br/><i>Claude · Cursor · Windsurf</i>"]
+    Client["AI Client<br/><i>Claude Desktop · Claude Code · VS Code · Cursor · Windsurf · Codex · Antigravity</i>"]
     Client -->|"MCP Protocol (stdio)"| Server
 
     subgraph Server["p58-n8n Server (local process)"]
         direction TB
-        Tools["12 MCP Tools"]
-        Tools --> Catalog["📚 Bundled Catalog<br/><i>1,545 nodes · 12,619 ops<br/>679 credential types</i>"]
-        Tools --> Validation["✅ Validation Engine<br/><i>L1 Structure · L2 Nodes · L3 Creds</i>"]
+        Tools["18 MCP Tools"]
+        Tools --> Catalog["📚 Bundled Index<br/><i>1,603 node + 14,805 op names<br/>679 credential types</i>"]
+        Tools --> Validation["✅ Validation Engine<br/><i>Multi-layer L1–L6</i>"]
         Tools --> AutoFix["🔧 Auto-Fix Engine<br/><i>Deterministic repair</i>"]
     end
 
@@ -172,7 +223,7 @@ graph TB
     style AutoFix fill:#0f3460,stroke:#16213e,color:#fff
 ```
 
-p58-n8n runs as a **local stdio process** — no cloud, no telemetry, no external servers. Your credentials and workflow data never leave your machine. The bundled catalog (6 JSON files) provides full node/operation intelligence offline. Connect your n8n server to unlock workflow CRUD, credential management, and execution.
+p58-n8n runs as a **local stdio process** — no cloud, no telemetry, no external servers. Your credentials and workflow data never leave your machine. The bundled index provides node/operation/credential **discovery** offline; the **enriched catalog** (parameter & connection schemas) is served via the premium REST proxy. Connect your n8n server to unlock workflow CRUD, credential management, and execution.
 
 ---
 
@@ -181,7 +232,7 @@ Every workflow passes through multi-layer validation before deployment:
 
 ```mermaid
 graph LR
-    subgraph public["Bundled (works offline)"]
+    subgraph public["Static validation (pre-deploy)"]
         L1["L1 Structure<br/><i>JSON schema, node graph,<br/>trigger rules ~30ms</i>"]
         L2["L2 Nodes<br/><i>Node existence, versions,<br/>operation validity ~60ms</i>"]
         L3["L3 Credentials<br/><i>Type matching, required<br/>fields, schema check ~80ms</i>"]
@@ -194,12 +245,13 @@ graph LR
 
 Validation runs against the **real catalog** — not LLM guesses. When validation fails, the auto-fix engine applies deterministic repairs (reconnect orphaned nodes, add missing credentials, patch parameter types) before retrying. No extra LLM calls. No extra cost.
 
+
 ---
 
 ## What Makes p58 Unique
-### 🎯 Bundled Catalog — Works Offline
+### 🎯 Offline Discovery Index
 
-The npm package ships with a complete public catalog: 1,545 nodes, 12,619 operations, 679 credential types across 6 JSON files. No database, no API key, no internet required for planning and discovery. Other servers need a live n8n connection just to list nodes.
+The npm package ships an offline **discovery index** — 1,603 node names, 14,805 operation names, and 679 credential types<sup>[[1]](#sources)</sup> — so your agent can browse what n8n offers with no database, API key, or internet. The **enriched catalog** (parameter schemas, connection rules, config examples) that powers actual building is unlocked with a premium `P58_ACCESS_TOKEN` (see [Free vs Premium](#-free-vs-premium)).
 
 ### 🔄 Full Lifecycle — Not Just JSON Generation
 
@@ -207,27 +259,37 @@ Most tools generate workflow JSON and stop. p58-n8n runs the complete cycle: pla
 
 ### 🔑 Credential Management — A Category No One Else Touches
 
-Discover what credentials exist on your server, health-check them with real HTTP/TCP probes, and wire them into workflows automatically. No other n8n MCP server offers credential lifecycle management.
+Discover what credentials exist on your server, health-check them with real HTTP/TCP probes, and wire them into workflows automatically — the only n8n MCP we know of with full credential lifecycle management.
 
 ### ✅ Deterministic Validation & Auto-Fix
 
-Validation runs against real catalog data, not LLM inference. When issues are found, deterministic fixers repair them — no extra tokens burned, no hallucinated fixes. The result: 100% pass rate across all model tiers.
+Validation runs against real catalog data, not LLM inference. When issues are found, deterministic fixers repair them — no extra tokens burned, no hallucinated fixes. The result: catalog-backed repairs and the strictest one-shot-verified (STRONG ⭐) proof of any n8n MCP we've measured.<sup>[[2]](#sources)</sup>
 
 ### 🧪 Built-In Test Loop
 
 `test_workflow` auto-detects your trigger type, executes safely (including webhook-aware flows), and returns per-node results. `get_execution_result` gives you detailed debug data. No need to leave the conversation to verify your workflow works.
 
-### 💰 29× Cheaper
+### ⚡ Fewer Turns
+
+Structured catalog data means smaller prompts and fewer back-and-forth turns. On the v5 canonical shootout, p58 averaged **6.2 turns/pass with Opus and 7.5 with Sonnet** (18.4 with Haiku)<sup>[[2]](#sources)</sup> — the agent isn't rediscovering n8n's schema from scratch on every build.
+
+### 📊 Free vs Premium
+
+p58-n8n has two **independent** dimensions: the **catalog tier** (how much node intelligence the agent gets) and your **n8n engine** (needed to build/deploy/test). They're orthogonal.
 
-Structured catalog data means smaller prompts, fewer turns, and less token waste. On Haiku 4.5: **$0.24/workflow** vs $6.02 for the next-best server and $7.16 for no server at all.
+| Catalog tier | **Free** (npm default) | **Premium** (`P58_ACCESS_TOKEN`) |
+|---|---|---|
+| **Catalog** | Offline discovery **index**: 1,603 node + 14,805 operation names, 679 credential types, and which creds each node needs<sup>[[1]](#sources)</sup> | Live **enriched** catalog: parameter schemas, connection rules, node properties, config examples, gotchas |
+| **Validation** | L1–L3 (structure · node existence/versions · credential types) | adds L4–L6 (connection rules · parameter config · deep patterns)<sup>[[6]](#sources)</sup> |
+| **Price** | $0 — default install state | per [Path58](https://path58.com) |
 
-### ⭐ Premium Catalog Access
+> **n8n engine (orthogonal):** building, deploying, testing, and credential management run against *your own* n8n via `N8N_API_URL` + `N8N_API_KEY` — independent of the catalog tier above.
 
-The free public catalog covers 1,545 node names and basic metadata. **Premium access** unlocks the full enriched catalog — operations, parameters, credential schemas, config examples, connection rules — served via a dedicated REST API. No database credentials needed on your machine. Activate directly from your AI assistant:
+Activate premium directly from your AI assistant:
 
 > *"Run `activate_premium` with my access token"*
 
-Your token is validated, stored locally at `~/.config/p58-n8n/config.json`, and used automatically on every session. If the premium API is unreachable, p58-n8n gracefully falls back to the public catalog — you keep working without interruption.
+Your token is validated, stored locally at `~/.config/p58-n8n/config.json`, and used automatically on every session. If the premium API is unreachable, p58-n8n falls back to the bundled index — you keep working without interruption.
 
 ---
 
@@ -267,10 +329,12 @@ p58-n8n runs as a local stdio process. There are no cloud relays, no analytics e
 
 | Layer | Variables | Purpose |
 |-------|----------|---------|
-| **API Key** | `N8N_API_KEY` | Workflow CRUD, activation, execution |
-| **Session Auth** | `N8N_USER_EMAIL` + `N8N_USER_PASSWORD` | Credential testing (optional) |
+| **Premium catalog** | `P58_ACCESS_TOKEN` | Unlocks the full enriched catalog + private intelligence via the Path58 REST proxy. *Knowledge about n8n* — does **not** touch your n8n engine. |
+| **n8n engine (API key)** | `N8N_API_URL` + `N8N_API_KEY` | Workflow CRUD, activation, execution, and credential management on *your* n8n. |
+| **Session Auth** (optional) | `N8N_USER_EMAIL` + `N8N_USER_PASSWORD` | Credential testing (`test_credential`). Without it, every tool works except `test_credential`, which prompts per-call. |
+| **Cloudflare Access** (if applicable) | `CF_ACCESS_CLIENT_ID` + `CF_ACCESS_CLIENT_SECRET` | Service-token headers for an n8n instance behind Cloudflare Access. See [AGENT_INSTALL.md](AGENT_INSTALL.md) Step 3c and the [CF-Access runbook](docs/mcp-install-cloudflare-access-runbook.md). |
 
-Session auth is optional. Without it, all tools work except `test_credential`, which will prompt per-call.
+> **Premium vs engine boundary:** `P58_ACCESS_TOKEN` alone gives you catalog/intelligence (works with no n8n). Live workflow operations (`build_workflow`, `test_workflow`, credential CRUD) require `N8N_API_URL` + `N8N_API_KEY`. The premium proxy serves *knowledge about* n8n; it does not proxy to your n8n engine.
 
 ### Your Responsibility
 
@@ -304,25 +368,25 @@ Looks up the Slack credential schema, creates with validation, health-checks the
 ## FAQ
 
 **Q: Do I need a running n8n instance?**
-A: No. The bundled catalog gives you full node/operation discovery, planning, and schema intelligence offline. Connect n8n when you want to deploy, execute, or manage credentials.
+A: For discovery, no — the bundled index gives you node/operation/credential lookup offline. Full schema intelligence (parameters, connections) comes with a premium token; deploying, executing, and managing credentials need your own n8n connected via `N8N_API_URL` + `N8N_API_KEY`.
 
 **Q: Which AI clients are supported?**
-A: Claude Desktop, Claude Code, Cursor, and Windsurf. See [AGENT_INSTALL.md](https://github.com/tsvika58/p58-n8n/blob/main/AGENT_INSTALL.md) for all clients.
+A: Claude Desktop (chat + Cowork), Claude Code, VS Code, Cursor, Windsurf, Codex (OpenAI), and Antigravity (Google). See [docs/INSTALLATION.md](https://github.com/tsvika58/p58-n8n/blob/main/docs/INSTALLATION.md) for all clients with config paths and key notes.
 
 **Q: Is my data sent to any cloud service?**
 A: No. p58-n8n is a local stdio process. No telemetry, no cloud relay. Your credentials and workflow data never leave your machine.
 
 **Q: What's the difference between the free package and premium?**
-A: The npm package includes 12 tools, the full public catalog (1,545 nodes, 12,619 ops, 679 credential types), multi-layer validation (L1–L3), and deterministic auto-fix. Premium (via [Path58](https://path58.com)) adds deeper validation layers (L4–L6) covering connection rules, parameter intelligence, and pattern matching from real workflows.
+A: The npm package includes all 18 tools, the bundled **discovery index** (1,603 node names, 14,805 operation names, 679 credential types),<sup>[[1]](#sources)</sup> L1–L3 validation, and deterministic auto-fix. Premium (via [Path58](https://path58.com), activated with a `P58_ACCESS_TOKEN`) adds the **enriched catalog** — parameter schemas, connection rules, config examples, gotchas — plus L4–L6 validation.<sup>[[6]](#sources)</sup> See [Free vs Premium](#-free-vs-premium).
 
 **Q: How does validation work without premium?**
-A: The bundled L1–L3 layers validate structure, node existence/versions, and credential type matching. This catches the vast majority of issues. Premium L4–L6 adds connection-rule validation, parameter type/enum checking, and pattern-informed fixes.
+A: Validation runs against whatever catalog the server has. With the bundled catalog (free), it checks structure, node existence/versions, and credential types — catching the large majority of issues. Premium's enriched catalog adds the raw parameter and connection data that powers deeper connection-rule, parameter, and pattern checks.
 
 **Q: Can I use this in production?**
 A: Yes. The BSL 1.1 license allows any use — personal, commercial, enterprise. The only restriction: you may not use this code to build and sell a competing n8n MCP server product.
 
 **Q: What happens on March 28, 2028?**
-A: The license automatically converts to MIT. No restrictions at all after that date.
+A: The Business Source License 1.1 converts to the MIT License — that's the Change Date in [LICENSE](LICENSE). No restrictions at all after that date.
 
 **Q: How do I get an n8n API key?**
 A: In n8n: Settings → API → Create API Key. Paste it into your MCP config as `N8N_API_KEY`.
@@ -336,17 +400,32 @@ p58-n8n is licensed under the [Business Source License 1.1](LICENSE).
 
 **One restriction:** You may not use this code to build and sell a competing n8n MCP server product.
 
-**Auto-converts to MIT** on March 28, 2028. After that, no restrictions at all.
+**BSL 1.1 → MIT on 2028-03-28.** On the Change Date the license converts to the MIT License<sup>[[4]](#sources)</sup>; after that, no restrictions at all.
 
 ---
 
 ## Contributing
 
-p58-n8n is in **soft launch**. Issues and feedback welcome:
+p58-n8n is in **pre-softlaunch**<sup>[[5]](#sources)</sup> (early demo cohort). Issues and feedback welcome:
 
 - **Bugs:** [GitHub Issues](https://github.com/tsvika58/p58-n8n/issues)
 - **Email:** tvagman@gmail.com
 
 ---
 
-**Built by [Path58](https://path58.com)** · Node.js 18+ required
+## Sources
+
+Every catalog and performance number in this README is sourced from a canonical artifact:
+
+1. **Catalog counts** — 1,603 nodes / 14,805 operations / 679 credential types: the bundled `src/data/public-catalog/` index (`manifest.json`, `bundle_type: public-basic` — node/operation/credential **names + metadata only, no parameter or connection schemas**), generated from the Path58 catalog database (migration `20260525102247`). The premium proxy reports identical counts (`setup_check.catalog`) and additionally serves the enriched per-node schemas.
+2. **Performance** — STRONG ⭐ 42% Opus / 38% Sonnet / 4% Haiku; pass 100% / 100% / 94%; 6.2 / 7.5 / 18.4 turns/pass; competitors 0% verified-green: the *P58 v5 Performance Report* (RAG-4.97.8), canonical 250-cell golden07 shootout (P58 arms) + 12-arm cross-architecture shootout (320 cells, competitor arms), scored by the canonical `per-cell-outcome-1.1.0` reclassifier. The per-cell schema is published so anyone can re-score — see *Want to check our claims?* above.
+3. **Tool count** — `src/mcp/tools/index.ts` registers 18 tools (14 core + 4 credential-management); live availability per `setup_check`.
+4. **License** — [LICENSE](LICENSE): Business Source License 1.1, Change Date 2028-03-28, Change License MIT.
+5. **Launch stage** — Path58 internal sprint context (current stage: pre-softlaunch).
+6. **Free vs premium tiers** — the free bundle's catalog adapter (`src/mcp/adapters/free-catalog.ts`) returns parameters, connection rules, and node properties as empty, so L4–L6 validation requires the premium enriched catalog while L1–L3 run on the bundled index. Tier model per the Path58 tier-model design (Free = bundled snapshot; Premium = live VPS-proxy catalog).
+
+Definitions of STRONG ⭐ / pass-rate / verification tiers follow the formal `is_1s1k_strong(cell)` predicate in the Path58 Strategic Anchors (v1.2.0).
+
+---
+
+**Built by [Path58](https://path58.com)** · Node.js 18+ required