@manny-est/node-red-flowpilot 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT-OVERVIEW.md

@@ -0,0 +1,98 @@
+# FlowPilot — Project Overview
+
+FlowPilot is an AI-powered development assistant that lives in the Node-RED
+editor sidebar. It talks to any OpenAI-compatible API (OpenAI, LocalAI,
+Ollama, etc.) and helps you chat about, generate, modify, and document your
+flows — always through Node-RED's own review and undo mechanisms, never
+behind your back.
+
+This document describes how FlowPilot was built and what it can do today.
+For installation and provider setup, see [README.md](README.md).
+
+## How it was built
+
+FlowPilot grew through a sequence of phases, each adding one capability on
+top of a stable foundation, with a working, reviewable build at every step:
+
+- **Phase 1 — Foundation.** The sidebar plugin itself: an OpenAI-compatible
+  provider connection, a settings UI for provider profiles, and a basic
+  connectivity check.
+- **Phase 2 — Context awareness.** FlowPilot reads the user's current node
+  selection and its wiring, sanitizes it (stripping editor-internal fields
+  and anything that looks like a credential), and sends that as context —
+  only when the user has something selected, and only on request.
+- **Phase 3 — Read-only copilot.** Chat, plus one-click "intent" buttons
+  (Explain, Troubleshoot, Review, Suggest, and user-defined custom intents)
+  that pre-fill the prompt box with a ready-to-edit instruction.
+- **Phase 4 — Generate.** FlowPilot can produce a brand-new flow fragment
+  from a plain-language description. The result is validated, laid out, and
+  handed to Node-RED's own import mechanism — the user places it with one
+  click and can undo it like any other paste.
+- **Phase 5 — Modify.** FlowPilot can propose changes to the *selected*
+  nodes — property edits, rewiring, additions, and removals — shown as a
+  diff the user reviews and applies node-by-node, each as a native undo
+  step.
+- **Phase 6 — Conversation, memory, and streaming.** Multi-turn conversation
+  history (capped and truncation-aware), per-conversation transcripts, a
+  "Flight log" of past conversations, Recall (keyword search across past
+  conversations), and SSE streaming for chat and generation responses.
+- **Phase 6.5 — Polish.** Performance/audit metrics (timing, token usage),
+  UI refinements, and groundwork for the agentic phase.
+- **Phase 7 — Agentic tool-calling.** For providers that support
+  tool/function calling, FlowPilot can autonomously call a small set of
+  read-only tools (inspect a node, list flows, search the flow, check
+  connections, read the Debug sidebar, get the current selection) to gather
+  information *before* answering or proposing a change — an
+  "explore-then-propose" loop, bounded by a step count and token ceiling,
+  with a visible cost summary and a Stop button.
+
+Throughout, every phase preserved the same core guarantees: nothing is sent
+without the user's selection or request, every proposed change is a
+reviewable diff, and every applied change is a normal Node-RED undo step.
+
+## Current feature set
+
+- **Chat** — a conversational copilot with selection context, conversation
+  history, and optional live Debug-sidebar context attachment.
+- **Query intents** — Explain, Troubleshoot, Review, Suggest, and
+  user-defined custom buttons that pre-fill a ready-to-edit prompt.
+- **Generate** — describe a flow in plain language and get a new set of
+  nodes + wiring, reviewed and imported on your terms.
+- **Modify** — select existing nodes, describe a change, and review a diff
+  before applying (property changes, rewiring, additions, removals).
+- **Document** — auto-generate a "Read Me" comment node summarizing a
+  selection.
+- **Recall & Flight log** — search and revisit past conversations; loading
+  one rehydrates the chat and its memory.
+- **Debug context attachment** — attach recent Node-RED Debug sidebar output
+  to a request for troubleshooting.
+- **Action chips** — when a chat reply describes a change the user could
+  make, FlowPilot offers a one-click switch to Generate/Modify/Document with
+  the request pre-filled.
+- **Clarifying questions** — if an instruction is too vague to act on
+  safely, FlowPilot asks ONE question (optionally with quick-reply options)
+  instead of guessing.
+- **Agentic exploration** — on providers with tool-calling support,
+  FlowPilot can inspect the flow itself before answering or proposing a
+  change.
+- **Streaming replies** — SSE streaming for chat, generate, modify, and
+  document.
+- **Models dropdown** — fetch the provider's available models instead of
+  typing a model name blind.
+- **`/demo`** — a guided first request that walks through Generate end to
+  end.
+
+## Architecture at a glance
+
+- **`flowpilot.html`** — the editor-side plugin: sidebar UI, settings,
+  selection/context handling, and all the chat/generate/modify/document
+  client logic.
+- **`flowpilot.js`** — the Node-RED runtime plugin: HTTP routes
+  (`/flowpilot/*`), provider calls, response parsing/validation, and audit
+  logging.
+- **`lib/`** — system prompts (default/generation/document/modify), the
+  OpenAI-compatible provider adapter, and on-disk storage (settings,
+  transcripts, audit log).
+- **Storage** — FlowPilot keeps its own settings, audit log, and
+  per-conversation transcripts under `<node-red-userDir>/flowpilot/`,
+  separate from the plugin code itself.

package/README.md

@@ -0,0 +1,144 @@
+# FlowPilot for Node-RED
+
+Package: `@manny-est/node-red-flowpilot`
+
+FlowPilot: AI assistance for Node-RED, designed for builders who want help
+without giving up control.
+
+FlowPilot is an AI-powered development assistant that lives in the Node-RED
+editor sidebar. It talks to any OpenAI-compatible API (OpenAI, LocalAI,
+Ollama, etc.) and helps you generate, modify, document, and discuss your
+flows — without ever acting behind your back.
+
+![FlowPilot sidebar](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/sidebar-chat-overview.png)
+
+▶ [Watch a full walkthrough](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/full-intro-demo.mp4) (MP4, ~30MB) — first launch, setting a provider, `/help`, and `/demo`.
+
+See [PROJECT-OVERVIEW.md](PROJECT-OVERVIEW.md) for how FlowPilot was built
+and a full rundown of its features, or [USER-GUIDE.md](USER-GUIDE.md) for
+installation, the sidebar UI, and a chapter on every feature.
+
+## Design principles
+
+- **Reuse Node-RED** — built on native capabilities (undo, import, deploy,
+  selection, events) instead of parallel systems.
+- **User-initiated only** — FlowPilot never changes your flow without an
+  explicit request.
+- **Complete visibility** — every proposed change is shown as a diff/review
+  before anything is applied.
+- **Undo first** — every change goes through Node-RED's native undo
+  (Ctrl+Z), including multi-part changes (insertions + rewires + new nodes)
+  as a single step.
+- **Open architecture** — provider-agnostic, OpenAI-compatible REST. No
+  lock-in to one AI platform.
+- **Simple and lightweight** — favors simple, maintainable solutions over
+  speculative complexity.
+
+## Privacy & data
+
+FlowPilot sends data to an AI provider only when **you** trigger a request —
+nothing happens in the background. When you do, it sends the context you've
+given it: your selected nodes and their wiring, any debug messages you've
+attached, and your conversation history.
+
+Before anything is sent, that context is sanitized: editor-internal fields are
+stripped, and values that look like secrets (credentials, tokens, API keys,
+auth headers) are redacted. Node-RED's separate credential store is never
+included. A warning (⚠) appears in the status strip when a selection might
+still contain sensitive configuration or code, so you can review before
+sending.
+
+Because your flow contents leave your Node-RED instance when you send a
+request, a **local or private AI provider (LocalAI, Ollama, etc.) is
+recommended for sensitive or proprietary flows**. You choose the provider, and
+nothing is sent anywhere you didn't configure.
+
+See the [User Guide](USER-GUIDE.md#privacy-and-safety) for the full details.
+
+## Features
+
+- **Chat** — a read-only copilot that can see your selected nodes and their
+  connections, with multi-turn conversation memory.
+- **Generate** — describe a flow in plain language and get a new set of
+  nodes + wiring, reviewed and imported on your terms.
+- **Modify** — select existing nodes, describe a change, and review a diff
+  before applying (property changes, rewiring, additions, removals).
+- **Document** — auto-generate a "Read Me" comment node summarizing a
+  selection.
+- **Review / Suggest / custom intents** — ask FlowPilot to critique or
+  suggest improvements to a selection.
+- **Conversational memory** — FlowPilot remembers recent exchanges
+  (configurable depth) and carries that context into Generate/Modify/
+  Document, with a clear notice when older messages are truncated.
+- **Clarifying questions** — if an instruction is too vague to act on
+  safely, FlowPilot asks ONE question instead of guessing.
+- **Streaming replies** — optional SSE streaming for chat responses.
+
+## Install in a local Node-RED user directory
+
+From your Node-RED user directory:
+
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-flowpilot
+node-red
+```
+
+For a Docker/container setup, place or install the package inside the
+mounted Node-RED user directory. If your user directory is
+`/data` (or `/workspaces/nodered`, etc.), this folder should exist:
+
+```text
+<node-red-userDir>/node_modules/@manny-est/node-red-flowpilot
+```
+
+Restart the Node-RED container/process after installing or updating —
+plugin HTML is cached server-side, so a browser refresh alone is not enough.
+
+FlowPilot stores its own settings and logs separately from the plugin code,
+under `<node-red-userDir>/flowpilot/`:
+
+- `settings.json` — provider configs (including API keys), custom intents,
+  conversation/streaming preferences
+- `audit.log` — a log of every generate/modify/document action
+- `chats/` — lightweight per-session chat logs
+- `backups/` — pre-change backups
+
+## Provider setup (example: LocalAI)
+
+Open the FlowPilot sidebar, click the settings (gear) icon, and add a
+provider:
+
+- Provider name: `LocalAI` (or any label)
+- Base URL: `http://localhost:8080`
+- API key: blank unless your instance requires one
+- Model: your model name
+- Temperature: `0.2`
+
+If Node-RED is running in Docker, `localhost` refers to the Node-RED
+container, not the Docker host. Use the provider's container name, Docker
+network alias, or host IP instead, e.g.:
+
+```text
+http://localai:8080
+http://172.17.0.1:8080
+```
+
+Click **Pre-flight check** to save and verify connectivity.
+
+## Examples
+
+The `examples/` folder includes a couple of small starter flows, available
+from the editor's **Import → Examples → FlowPilot** menu — see
+[USER-GUIDE.md](USER-GUIDE.md#examples) for what they're for.
+
+## Development status
+
+FlowPilot is under active development. Every change is reviewable and
+undoable, but as with any AI-assisted tool, review proposed changes before
+applying them — especially on flows you care about.
+
+## Feedback
+
+Found a bug or have a feature request? Please open an issue:
+https://github.com/manny-est/flowpilot/issues

package/USER-GUIDE.md

@@ -0,0 +1,319 @@
+# FlowPilot — User Guide
+
+This guide covers installing FlowPilot, the parts of its sidebar UI, setting
+up an AI provider, and a walkthrough of every feature. For a high-level
+overview of what FlowPilot is and how it was built, see
+[PROJECT-OVERVIEW.md](PROJECT-OVERVIEW.md).
+
+## Getting Started
+
+▶ **[Watch a full walkthrough](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/full-intro-demo.mp4)** (MP4, ~30MB) — first launch, setting a provider, `/help`, and `/demo` end to end.
+
+### Install from the Palette
+
+In the Node-RED editor, open the menu (top-right) → **Manage palette** →
+**Install**, and search for `@manny-est/node-red-flowpilot`. Click **Install**.
+
+### Install via npm
+
+From your Node-RED user directory:
+
+```bash
+cd ~/.node-red
+npm install @manny-est/node-red-flowpilot
+```
+
+For a Docker/container setup, install into the mounted Node-RED user
+directory (commonly `/data`), so the package ends up at:
+
+```text
+<node-red-userDir>/node_modules/@manny-est/node-red-flowpilot
+```
+
+### Restart Node-RED
+
+Either way, **restart Node-RED** (or the container) after installing or
+updating. FlowPilot's editor UI is cached server-side, so a browser refresh
+alone is not enough.
+
+### First launch
+
+![The FlowPilot tab in the Node-RED editor's sidebar](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/Node-Red-Tool-Menu.png)
+
+Open the FlowPilot sidebar tab (the paper-plane icon, usually grouped with
+Info/Debug/etc. on the right edge of the editor) — or watch [a short clip of
+finding it](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/finding-flowpilot.mp4).
+On first launch, FlowPilot
+walks you through the basics in the chat panel and ends by pointing you at
+**Settings** to add a provider — see [Set a Provider](#set-a-provider) below.
+This walkthrough only appears once; it disappears for good after you save
+settings (which happens automatically the first time you run a **Pre-flight
+check**).
+
+![FlowPilot's first-run welcome and cockpit tour](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/first-run-welcome.png)
+
+## UI Basics
+
+![The FlowPilot sidebar's Chat panel](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/sidebar-chat-overview.png)
+
+The FlowPilot sidebar has three panels, switched using the icons in the
+header row (top-right of the sidebar):
+
+| Icon | Tooltip | What it does |
+| --- | --- | --- |
+| 🖉 eraser | Clear chat | Clears the chat and resets conversation memory |
+| 🔍 magnifying glass | Recall | Searches past conversations for text in the prompt box |
+| 🐛 bug | Debug log | View recent Debug sidebar output and attach it as context |
+| ✈ paper-plane | Chat | Switch to the Chat panel |
+| 🕐 clock | Flight log | Switch to the Flight log (past conversations) panel |
+| ⚙ gear | Settings | Switch to the Settings panel |
+
+### The Chat panel
+
+This is FlowPilot's main view:
+
+- **Messages area** — your conversation with FlowPilot, including any review
+  diffs, action chips, and clarifying questions.
+- **Query buttons** (orange, left side, above the prompt box) — **Explain**,
+  **Troubleshoot**, **Review**, **Suggest**, plus any custom buttons you add.
+  Clicking one pre-fills the prompt box with a ready-to-edit instruction and
+  switches the prompt to an amber "Query" look.
+- **Execute buttons** (blue, right side, above the prompt box) — **Document**,
+  **Generate**, **Modify**. Clicking one *arms* that mode (the prompt turns
+  blue) — describe what you want and hit Send.
+- **Prompt box** — type your question or instruction here. Press **Enter** to
+  send, **Shift+Enter** for a new line. Drag the handle in the top-right
+  corner of the box to resize it.
+- **Status strip** (below the prompt) — shows how many nodes are selected,
+  estimated context size, a credentials warning if relevant, any attached
+  debug messages, and the active provider. **Clear** empties the prompt box;
+  **Send** sends the request.
+
+### The Settings panel
+
+Configure AI providers, the system prompt, conversation memory, custom intent
+buttons, and safety warnings. See [Set a Provider](#set-a-provider) and the
+feature chapters below for details on each section.
+
+### The Flight log panel
+
+A list of past conversations. Click one to load it back into Chat — new
+messages continue that conversation's memory. **Delete all** removes every
+saved transcript permanently.
+
+## Set a Provider
+
+FlowPilot talks to any **OpenAI-compatible** API — OpenAI itself, LocalAI,
+Ollama (with its OpenAI-compatible endpoint), LM Studio, etc.
+
+1. Open **Settings** (gear icon).
+2. Under **Providers**, click **+ Add** if you need a new provider slot
+   (one is created for you by default).
+3. Fill in:
+   - **Provider Name** — any label, e.g. `LocalAI` or `OpenAI`.
+   - **Base URL** — e.g. `http://localhost:8080` or `https://api.openai.com`.
+     If Node-RED is running in Docker, `localhost` refers to the *Node-RED
+     container*, not the Docker host — use the provider's container name, a
+     Docker network alias, or a host IP (e.g. `http://172.17.0.1:8080`)
+     instead.
+   - **API Key** — leave blank unless your provider requires one.
+   - **Model** — type a model name, or click **Refresh models** to fetch the
+     provider's available models (via `GET /v1/models`) and pick from the
+     list.
+   - **Temperature** — a starting value of `0.2` works well for most uses.
+
+![Provider settings: Base URL, API key, model, and temperature fields](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/sidebar-settings-providers.png)
+
+4. Click **Pre-flight check**. This saves your settings and sends a small
+   test request. A reply in the chat panel means you're connected.
+
+![A successful Pre-flight check reply in Chat](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/preflight-success.png)
+
+You can configure multiple providers and switch between them with the
+**Active provider** dropdown — useful for comparing models, or keeping a
+cheap/fast provider and a more capable one side by side. **Remove** deletes
+the currently selected provider.
+
+## Features
+
+### Chat
+
+Ask FlowPilot anything in plain language. If you have nodes selected on the
+canvas, FlowPilot sees their configuration and wiring (sanitized — see
+[Privacy and safety](#privacy-and-safety) below) and can reason about them.
+Chat remembers recent exchanges (configurable under **Behavior → Remember
+last N exchanges**) so you can have a back-and-forth conversation.
+
+### Query intents: Explain, Troubleshoot, Review, Suggest
+
+One-click buttons that pre-fill the prompt box with a ready-to-edit
+instruction about your current selection:
+
+- **Explain** — walks through what the selection does, step by step.
+- **Troubleshoot** — looks for disabled nodes, dead-end wires, and likely
+  misconfigurations.
+- **Review** — a design/architecture critique with concrete suggestions.
+- **Suggest** — suggests improvements or other Node-RED nodes that could help.
+
+You can add your own custom intent buttons under **Settings → Behavior →
+Custom intent buttons** — give it a label and the instruction text it should
+send.
+
+![Explain run on a selected node](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/query-explain-example.png)
+
+### Generate
+
+Describe a new flow in plain language (e.g. "fetch the weather every hour and
+log it to a file") and click **Generate**, then **Send**. FlowPilot returns a
+flow fragment, which you review before doing anything with it — nothing is
+added to your canvas automatically. Approve it and FlowPilot hands the nodes
+to Node-RED's own import, so placement and undo (Ctrl+Z) work exactly like a
+normal paste.
+
+Try `/demo` in the prompt box for a ready-made example: it types a Generate
+request for a small "fetch a dad joke" flow into the box for you.
+
+![A Generate request and the resulting reply](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/generate-example.png)
+
+![Generate's review step, with the raw flow JSON](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/generate-review-json.png)
+
+![Generate's review/diff before import](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/generate-review.png)
+
+### Modify
+
+Select the node(s) you want to change, arm **Modify**, and describe the
+change (e.g. "add a 5 second delay before this", "change this function to
+also log errors"). FlowPilot proposes property changes, rewiring, additions,
+and removals as a diff. You review and apply each change — every applied
+change is a single native Node-RED undo step (Ctrl+Z).
+
+![Modify's proposed diff before applying](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/modify-diff.png)
+
+![The same change applied to the flow](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/modify-diff-applied.png)
+
+### Document
+
+Select node(s), arm **Document**, and (optionally) add notes about what you
+want highlighted, then **Send**. FlowPilot generates a "Read Me" comment node
+summarizing the selection, which you review and place like any other change.
+
+![A generated Read Me comment node, reviewed before placing](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/document-readme-node.png)
+
+![The Read Me comment node placed on the canvas](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/document-readme-node-placed.png)
+
+### Recall & Flight log
+
+- **Recall** (magnifying glass icon) — type a search term in the prompt box
+  and click Recall to search across your past conversations. Each result has
+  a **Use this** button to load that conversation back into Chat.
+- **Flight log** (clock icon) — browse and reload past conversations
+  directly, or delete saved transcripts.
+
+![The Flight log panel listing past conversations](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/flight-log.png)
+
+### Debug context attachment
+
+Click the **bug icon** to view recent messages from Node-RED's Debug sidebar.
+Click **Attach** on any entry to include it as context for your next request
+— useful for troubleshooting ("here's the error my flow just printed, what's
+wrong?"). The status strip shows how many debug messages are attached; clear
+them from there or by clicking **Clear chat**.
+
+![The Debug log panel with recent entries](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/debug-log.png)
+
+![A debug message attached, shown in the status strip](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/debug-log-attached.png)
+
+### Action chips
+
+When FlowPilot's reply describes a change you could make, it may offer an
+action chip — a one-click button that switches to the suggested mode
+(Generate/Modify/Document/Chat) with the request pre-filled. Nothing is sent
+until you review and hit Send yourself.
+
+![A reply with an action chip below it](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/action-chip.png)
+
+![The full chat thread leading up to an action chip](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/action-chip-full.png)
+
+### Clarifying questions
+
+If your instruction is too vague to act on safely, FlowPilot asks **one**
+clarifying question instead of guessing — often with quick-reply buttons (plus
+an "Other" option for free text). Picking an answer sends it immediately.
+
+![A clarifying question with quick-reply buttons](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/clarifying-question.png)
+
+### Agentic exploration
+
+If your provider supports tool/function calling, FlowPilot can autonomously
+inspect your flow before answering or proposing a change — looking at a
+node's config, listing flows, searching for nodes, checking connections, or
+reading the Debug sidebar. This is read-only, bounded by a step count and
+token budget, shown to you as it happens, and can be interrupted with the
+**Stop** button.
+
+![An agentic exploration run in progress](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/agentic-exploration.png)
+
+### Streaming replies
+
+Chat (and Generate/Modify/Document) responses can stream in as they're
+generated rather than appearing all at once. Toggle this under **Settings →
+Behavior → Stream chat replies**.
+
+![Settings → Behavior, including streaming and custom intents](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/settings-behavior.png)
+
+### Slash commands
+
+Type these directly into the prompt box:
+
+- `/help` — show the full command/feature briefing
+- `/generate`, `/document`, `/modify` — arm that Execute mode
+- `/query` (or `/chat`) — back to Query mode
+- `/clear` — start a fresh conversation (clears chat and memory)
+- `/history` — open the Flight log
+- `/settings` — open Settings
+- `/demo` — load a sample Generate request into the prompt box
+
+![`/help`'s full command/feature briefing](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/slash-help.png)
+
+![`/demo` pre-filling a Generate request](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/demo-command.png)
+
+![The flow generated by `/demo`, reviewed and imported](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/slash-demo-complete.png)
+
+### Privacy and safety
+
+- FlowPilot only sends data when **you** trigger a request — nothing happens
+  in the background.
+- Selected nodes are sanitized before sending: editor-internal fields are
+  stripped, and config-node credential fields are dropped entirely.
+- A warning icon (⚠) appears in the status strip if your selection might
+  still contain sensitive configuration or code — review before sending,
+  especially with cloud providers. A local/private AI provider (LocalAI,
+  Ollama, etc.) is recommended for sensitive flows.
+- Every Generate/Modify/Document result is shown as a review or diff —
+  nothing is applied until you click Apply/import, and every applied change
+  is a normal Node-RED undo step.
+
+![Settings → Context & Safety](https://github.com/manny-est/flowpilot/releases/download/v0.2.1/settings-context-safety.png)
+
+## Examples
+
+The `examples/` folder (visible via the editor's **Import → Examples →
+FlowPilot** menu) includes:
+
+- **Getting Started** — a tiny inject → function → debug flow to practice
+  Explain/Modify on.
+- **Dad Joke Demo** — a working version of the flow that `/demo` generates,
+  so you can see the end result before trying Generate yourself.
+
+## Bug Reports & Feature Requests
+
+Found a bug, or have an idea for a feature? Please open an issue on GitHub:
+
+**https://github.com/manny-est/flowpilot/issues**
+
+When reporting a bug, it helps to include:
+
+- Your Node-RED version and FlowPilot version (`package.json` → `version`).
+- The AI provider/model you're using (not your API key).
+- Steps to reproduce, and what you expected vs. what happened.
+- Anything relevant from the browser console or Node-RED's log.

package/examples/dad-joke-demo.json

@@ -0,0 +1,84 @@
+[
+    {
+        "id": "fp-ex2-tab",
+        "type": "tab",
+        "label": "FlowPilot: Dad Joke Demo",
+        "disabled": false,
+        "info": "This is the kind of flow FlowPilot's `/demo` slash command generates from scratch via Generate.\n\nDeploy this flow, then click the inject node to fetch a random dad joke — the node's status will show the joke text, and it'll print in the debug sidebar too.\n\nTry selecting these nodes in FlowPilot and clicking **Explain**, or arm **Modify** and ask it to write the joke to a file instead of the debug sidebar.",
+        "env": []
+    },
+    {
+        "id": "fp-ex2-inject",
+        "type": "inject",
+        "z": "fp-ex2-tab",
+        "name": "get a dad joke",
+        "props": [
+            { "p": "payload" }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "payload": "",
+        "payloadType": "date",
+        "x": 150,
+        "y": 140,
+        "wires": [["fp-ex2-http"]]
+    },
+    {
+        "id": "fp-ex2-http",
+        "type": "http request",
+        "z": "fp-ex2-tab",
+        "name": "icanhazdadjoke",
+        "method": "GET",
+        "ret": "obj",
+        "paytoqs": "ignore",
+        "url": "https://icanhazdadjoke.com/",
+        "tls": "",
+        "persist": false,
+        "proxy": "",
+        "insecureHTTPParser": false,
+        "authType": "",
+        "senderr": false,
+        "headers": [
+            { "keyType": "other", "keyValue": "Accept", "valueType": "other", "valueValue": "application/json" }
+        ],
+        "x": 350,
+        "y": 140,
+        "wires": [["fp-ex2-function"]]
+    },
+    {
+        "id": "fp-ex2-function",
+        "type": "function",
+        "z": "fp-ex2-tab",
+        "name": "show joke status",
+        "func": "var joke = (msg.payload && msg.payload.joke) || \"(no joke returned)\";\nnode.status({ fill: \"green\", shape: \"dot\", text: joke });\nmsg.payload = joke;\nreturn msg;",
+        "outputs": 1,
+        "timeout": 0,
+        "noerr": 0,
+        "initialize": "",
+        "finalize": "",
+        "libs": [],
+        "x": 580,
+        "y": 140,
+        "wires": [["fp-ex2-debug"]]
+    },
+    {
+        "id": "fp-ex2-debug",
+        "type": "debug",
+        "z": "fp-ex2-tab",
+        "name": "joke",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "payload",
+        "targetType": "msg",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 780,
+        "y": 140,
+        "wires": []
+    }
+]