A Docs-Grounded RAG Coach That Debugs n8n Workflows
A 24/7 AI coach for n8n training students. Answers questions with inline citations back to the n8n docs, auto-detects pasted workflow JSON and switches to debug mode with a structured diagnosis, and enforces corpus scope with an off-topic similarity gate. Built so that getting stuck at 9pm does not mean waiting for the next office hour.
- Role
- Founder & Product Owner (shipped with Claude Code)
- Tools
- Claude Sonnet 4.6 ,Next.js 16 ,Supabase pgvector ,Voyage embeddings ,Vercel
Watch the walkthrough.
The problem
Students Get Blocked Between Sessions
Every cohort loses momentum in the 6-day gap between live sessions. A student hits a broken expression at 9pm on a Tuesday, does not solve it alone, and waits until the next office hour. By then they have moved on, disengaged, or forgotten the context. The roadmap slows to match the slowest unblocking cycle, not the speed of learning. For a training program billed on outcomes, the unblocking gap is the single biggest brake on completion rate.
Generic AI Fabricates n8n Syntax
Point a stuck student at baseline ChatGPT or Claude and the model invents n8n expressions, hallucinates node names, and references properties absent from the actual platform. The answer looks authoritative and is plausibly wrong, worse than no answer. The student pastes the snippet, hits a cryptic error, spends another 40 minutes debugging a fabricated suggestion. Without doc-grounded retrieval, generic AI makes the problem worse, not better.
Debugging a Broken Workflow Is the Hardest Self-Solve
The highest-friction moment in n8n training is reading someone else's broken JSON. Missing credentials, wrong expression syntax, node-order issues, rate-limit risk. Every one of these requires domain knowledge the student is still building. Without a tool reading the actual workflow and pointing at the specific node with the specific fix, students loop on the same three errors for hours.
The solution.
Architecture diagram, click to zoom
Stage 1: Query Intake & Off-Topic Gate
Natural-language n8n questions arrive through a streaming chat UI. Every message hits a cosine-similarity gate at 0.25 against the 332-page corpus before retrieval. Off-topic queries (forex rates, weather, anything outside n8n) get a strict redirect response. Scope is enforced at retrieval time, not by prompt alone. Prompt injection attempts inside user input cannot bypass the gate.
Stage 2: Mode Routing and Debug Detection
The bot auto-detects pasted workflow JSON by parsing incoming text for a nodes[] key. Detection is code, not prompt, which removes an entire class of bypass risk. Every message routes through one of three modes: answer (general Q&A), debug (workflow diagnosis), or redirect (off-topic). Debug mode uses a different system prompt and strips the JSON from the semantic query so retrieval stays clean.
Stage 3: Grounded Retrieval and Cited Response
The router pulls the top-5 most relevant doc chunks via Supabase pgvector with an HNSW index and Voyage voyage-3 embeddings at 1024 dimensions. Claude Sonnet 4.6 answers the user with streaming output and inline markdown citations linking each claim back to docs.n8n.io. In debug mode the output is structured: what the workflow does, what is broken, which node, why it breaks, the exact fix with citation.
Stage 4: Guardrails and Rate Limiting
Pasted JSON is wrapped in <workflow> XML tags and treated as data, not instructions. A Postgres function enforces rate limits: 10 requests per minute, 100 per day per hashed IP (SHA-256, no raw IPs stored). Module-scope env reads were replaced with lazy singletons to keep the Vercel build clean. Responses stream token by token through Vercel AI SDK v6.
The impact
What Was Built
- 332 n8n doc pages chunked, embedded, and indexed in Supabase pgvector
- Two-stage retrieval: top-50 vector recall, reranked down to the top 5 passages
- Debug mode triggers on a parsed nodes[] key in code, not by asking the model to notice
- Off-topic queries are refused at retrieval time by a similarity gate, not by prompt wording alone
Strategic Value
- Absorbs the between-session support load so office hours are not the only path to getting unstuck.
- Answers are tied to retrieved passages and cite the source, which is the difference between a coach and a plausible guess.
- Pattern generalizes to any docs-heavy SaaS support, internal team enablement, or training-program unblocking.
Have a similar problem?
Tell me what is going on and I will tell you what I would do about it. No obligation.