flowforge-map 0.3.0__tar.gz → 0.4.1__tar.gz

{flowforge_map-0.3.0 → flowforge_map-0.4.1}/.gitignore

@@ -25,3 +25,10 @@ claude-resume.md
 desktop.ini
 .vscode/
 .idea/
+
+# the desktop app (D42): build output
+build/
+desktop/src-tauri/binaries/
+desktop/src-tauri/target/
+desktop/node_modules/
+desktop/src-tauri/gen/

{flowforge_map-0.3.0 → flowforge_map-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowforge-map
-Version: 0.3.0
+Version: 0.4.1
 Summary: Map what your app depends on (LLMs, MCP servers, APIs), check their health and security, and see what could run faster. Local and free; the scan needs no AI.
 Project-URL: Homepage, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator
 Project-URL: Issues, https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/issues
@@ -26,31 +26,39 @@ Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: keyring>=25
 Requires-Dist: mcp>=1.2
 Requires-Dist: openai>=1.40
+Requires-Dist: packaging>=24
 Requires-Dist: pydantic>=2.8
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: rich>=13
 Requires-Dist: segno>=1.6
 Requires-Dist: uvicorn[standard]>=0.30
 Description-Content-Type: text/markdown
 
 # FlowForge
 
-**An LLMOps tool for apps that already use AI: a map of how your app's LLM, MCP and API calls fit together, and a scheduler that runs them.**
+**See everything your AI app depends on: whether it's up, whether it's safe, and what's slowing it down.**
 
-You connect the apps your project uses (LLMs, MCP servers, HTTP APIs, local commands). The **Planner** reads your repo and runs the app in test mode, then draws the flow on the home page: the calls, the decisions, what runs together, the retries and fallbacks, and a gate in front of anything that moves money or sends a message. Only apps your code actually calls go on the map, and every block cites its evidence (a `file:line` or a traced call). You read the map, edit it if you want (your edits never touch your code), and re-check it when the code changes.
+```bash
+npx flowforge-map --example      # a sample app's map in your browser: no keys, nothing sent
+```
 
-Underneath, FlowForge runs workflows as a DAG: it orders the steps, runs independent ones together under rate limits, caches repeat calls, and (on the roadmap) holds the secrets and pauses risky steps for a human to approve.
+![The dependency map: every LLM, MCP server and API the app calls, with live health](docs/images/map.png)
 
-What makes it different: **it knows which chain of steps is the bottleneck and schedules around it.**
+| | |
+|---|---|
+| 🗺 **Map** | Every LLM, MCP server, HTTP API and local program your code calls, each with the `file:line` it came from |
+| 💚 **Check now** | Green, amber or red for each one, with its latency. When something is down, it tells you why |
+| ⚡ **Faster** | Reads the order your code makes its calls and shows which ones could run together, with the time you'd save |
+| 🛡 **Issues** | Keys written in code, plain `http://`, MCP servers that aren't pinned. Fix one on a new branch, or send it to your agent |
+| 🔑 **Keys** | Paste a key once. **Add to code** writes it to a git-ignored file your app reads; FlowForge only ever hands your agent a mask |
+| 🤖 **Your agent** | One MCP entry gives Claude Code, Codex or Antigravity the map, the advice and the issues |
 
-- orders steps with **topological sort** (Kahn's), and reports the exact loop if there is a cycle
-- finds the bottleneck chain with a **longest-path DP** (critical path), predicted before the run and measured after it
-- runs independent steps concurrently under limited resources (`k` slots + per-provider rate limits) using **critical-path list scheduling** (HLFET), which is within `(2 − 1/k)` of optimal (Graham's bound)
-- makes duplicate calls only once through **memoization** (single-flight in-run cache + a safe persistent cache)
+![Flow: 16.5 s as written, 11.6 s if four calls start together](docs/images/flow.png)
 
-**Free by default.** The default install, the tests and CI need no paid service: LLM steps use NVIDIA NIM's free tier, and local models (Ollama) are planned. Paid providers will work if you bring your own key, but are never needed.
+**Free and local.** MIT, no account, no paid service. FlowForge keeps its data on your machine, and the scan is plain code that sends nothing to any LLM.
 
-**Local first.** One process, SQLite, files on disk. No cloud account, no Docker, no Redis.
+**Under the hood:** a DAG scheduler runs the checks concurrently under rate limits. It uses a topological sort, a critical-path DP and HLFET list scheduling (within `(2 − 1/k)` of optimal), and it caches repeat calls. See [Scheduling policies and benchmarks](#scheduling-policies-and-benchmarks).
 
 > FlowForge started as a Design and Analysis of Algorithms course project. That version is frozen on the [`DAA`](../../tree/DAA) branch. `main` is the product.
 
@@ -59,12 +67,52 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 ### Install
 
 ```bash
-uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
-pip install flowforge-map        # or install it (the command is `flowforge`)
-flowforge --repo ~/my-app        # map your own repo
+npx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
+npx flowforge-map --repo .       # map the folder you're in
 ```
 
-You need Python 3.12 or newer ([uv](https://docs.astral.sh/uv/) installs it for you). The dashboard is inside the package: no Node needed. Your data lives in `~/.flowforge`.
+That's all: no Python, no virtual env. The first run downloads FlowForge's ready-made program for your computer (about 60 MB, checked against the release's checksums) into `~/.flowforge/bin`; after that it starts at once, even offline. Works on Windows, macOS (Apple chips) and Linux x64 with Node 18+. Your data lives in `~/.flowforge`.
+
+| You have | Run | |
+|---|---|---|
+| Node (most developers) | `npx flowforge-map` | ⭐ no Python needed |
+| Node, every day | `npm i -g flowforge-map`, then just `flowforge` | installs the launcher; the program comes on first run |
+| Python people | `uvx flowforge-map` or `pipx install flowforge-map` | Python 3.12+; no virtual env to manage |
+| No terminal | the desktop app (Releases) | download and open; **Settings → Terminal** adds the `flowforge` command too (Linux .rpm/.deb have it already) |
+
+Every way gives the same `flowforge` command: `npx flowforge-map status`, `npx flowforge-map key add STRIPE_KEY`, and so on. Intel Macs, Linux ARM and Windows ARM have no ready-made build yet, so `npx` uses `uvx` there.
+
+The first time, a short welcome walks you through three steps, each one skippable: your app's folder (or the example), pairing your coding agent once, and a lock for your keys. **⚙ Settings** at the bottom of the rail keeps what applies to every project: your agent, the theme and map style, the Vault's lock, and your data (each project's size, the MCP servers it may start, its check history, and the version, with **Check for updates**, which asks pypi.org only when you press it).
+
+### Terminal
+
+```bash
+flowforge status [PROJECT]     # health, issues, missing keys and the next step
+flowforge projects             # every project at a glance
+flowforge issues [PROJECT]     # security findings and fixes
+flowforge check [PROJECT]      # preview checks; run them from the dashboard
+flowforge settings             # saved settings, data location and version
+flowforge scan ~/my-app        # terminal summary; pipe it or use --json for JSON
+flowforge key list             # key names and statuses, never values
+```
+
+Project commands use the current folder's project, else the last opened; PROJECT is its name or id. They read local files and work with the dashboard stopped. `--plain` or `NO_COLOR` disables colour and the banner; pipes have no colour or animation.
+
+### Desktop app
+
+The same dashboard in its own window, with Python inside: nothing else to install. Download the installer for your computer from the [Releases](https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/releases) page:
+
+| Your computer | Download |
+|---|---|
+| Windows | `FlowForge_x.y.z_x64-setup.exe` or `.msi` |
+| Mac (Apple Silicon or Intel) | `FlowForge_x.y.z_aarch64.dmg` or `_x64.dmg` |
+| Linux | `.AppImage`, `.deb` or `.rpm` |
+
+The builds aren't signed yet (signing costs money every year), so the first launch asks once:
+- **Mac:** right-click FlowForge in Applications → **Open** → **Open**.
+- **Windows:** on "Windows protected your PC", click **More info** → **Run anyway**.
+
+After that it opens normally. **Browse…** picks your app's folder; **Settings → Your agent** pairs your coding agent with the app's own FlowForge.
 
 ### From source (to work on FlowForge)
 
@@ -83,7 +131,7 @@ uv run flowforge --example                # opens http://127.0.0.1:8000: a sampl
 ### Map your own repo
 
 ```bash
-uv run flowforge scan path/to/your/repo     # what it depends on, as JSON: nothing stored, nothing sent
+uv run flowforge scan path/to/your/repo     # summary (pipe or --json for JSON); nothing stored, nothing sent
 uv run flowforge --repo path/to/your/repo   # opens its dependency map; add --replace to switch folders
 ```
 
@@ -105,19 +153,24 @@ Switch the map to **Flow**. FlowForge reads your Python (by its syntax tree), Da
 - **Faster** compares "as written" (the slowest action, one call after another) with "could be", and lists the calls that don't need each other's results. **Show the change** writes out the `asyncio.gather`, Dart's `(a, b).wait` or `Promise.all` (now → could be, ready to copy) when it's safe; **Copy prompt for your coding agent** hands the rest to Claude Code, Codex or any agent. FlowForge never edits your code.
 - **Watch it run** plays the could-be schedule; pointing at a block lights up its path. Five map styles: Studio, Boxed, Blueprint, Metro, Soft.
 
+### Many projects
+
+The home page lists every app you've mapped, with its dependencies, what needs fixing and missing keys. **+ New project** takes your app's folder, scans it and shows its map. The project tile at the top of the rail switches between the projects you have open, and each one comes back where you left it. **×** closes a project from that list without deleting it. Each project keeps its own map, checks, issues and keys; `flowforge --repo PATH` opens (or adds) that folder's project.
 
 ### Use it from your coding agent
 
-FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can ask it about your app and then make the change themselves. Open **Connect agent** in the dashboard: it gives you the one line (or config block) for your agent, with the paths filled in. For Claude Code it looks like:
+FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can ask it about your app and then make the change themselves. **Settings → Your agent** (also on **Connect agent**) gives you the one line (or config block) for your agent. With `uvx`, for Claude Code it looks like:
 
 ```bash
-claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
+claude mcp add flowforge -- uvx flowforge-map mcp
 ```
 
-Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Pair your agent once and it sees every project: `flowforge mcp` with no folder answers about the project your agent is working in, or any other by name (`list_projects` shows them all). Your agent gets eleven tools: `list_projects`, `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
 
 ### Fix what's unsafe, with one click
 
+![Issues: a key in the code, an unpinned MCP server, plain http](docs/images/issues.png)
+
 The **Issues** page lists what the scan found unsafe, and every issue has one button:
 
 | Issue | Button | What happens |
@@ -129,22 +182,55 @@ Fix needs a git repo and the file committed. FlowForge works out the change itse
 
 ### Keys your coding agent never sees
 
-Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+![Keys: paste once, Add to code, the agent sees a mask](docs/images/keys.png)
 
+**Add to code.** The **Keys** page lists each place your code needs a key, with its `file:line`. Paste the key and press **Add to code**:
+
+```
+lib/config.dart:8   String.fromEnvironment('SUPABASE_ANON_KEY')      ← FlowForge found the spot
+[ •••••••••••• ]  [ Add to code ]                                      ← you paste, one click
+✓ SUPABASE_ANON_KEY is in your app. Press Run as always.
+  Changed: .flowforge/dart-defines.json · Run config · .gitignore · Claude Code told not to read it · Vault
+```
+
+The key goes where your app reads it, and **never into a code file**:
+
+| Your app | The key goes to | Then |
+|---|---|---|
+| Flutter (`String.fromEnvironment`) | `.flowforge/dart-defines.json`, and `--dart-define-from-file` is added to your Run config (Android Studio, IntelliJ, VS Code) | press Run |
+| Python, Node or Flutter with a `.env` loader | `.env` | start it as always |
+| Vite | `.env.local` (as `VITE_…`) | start it as always |
+
+- A placeholder like `apiKey = "ENTER KEY HERE"` is rewritten to read the key.
+- A real key written in the code gets **Hide it**: one click moves it out the same way.
+- The file is git-ignored, and nothing is committed: you see the change in `git diff`.
+- An app that loads no file gets **Save**, and the Keys page says why.
+- The settings a key needs come too: `SUPABASE_URL` is listed under **Your app also needs**, filled in from your Supabase key, with the same **Add to code** (a setting isn't secret, so it doesn't go to the Vault).
+
+**With an agent**, the agent never gets a key; it gets a **mask**:
+
+```
+you paste STRIPE_SECRET_KEY once  →  your agent sees  ffkey://STRIPE_SECRET_KEY
+the agent writes the mask where the key goes (or reads the env var STRIPE_SECRET_KEY in code)
+the agent calls run_app(["flutter", "run", "--dart-define=STRIPE_SECRET_KEY=ffkey://STRIPE_SECRET_KEY"])
+FlowForge asks you once: "Your agent wants to run flutter run … with STRIPE_SECRET_KEY"   [Deny] [Allow]
+FlowForge (plain code, no AI) fills the mask and starts the app → the output comes back masked
+```
+
+Masks work in commands, in the environment and in `.env` lines; other config files never get the key written into them, so read the env var there. After you allow a command once, the same command runs without asking (**Settings** can turn the question off). The Keys page lists your agent's runs with **Stop**. This covers keys read when the app is *built* too, such as Flutter's `--dart-define` and Vite's `import.meta.env`. On the map, a 🔑 badge marks a block whose key is missing. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**No agent?** The same works by hand:
 ```bash
 flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
 flowforge key list                         # each key the code reads: saved · in .env · missing
-flowforge key import                       # move a .env into FlowForge (then delete the .env)
-flowforge run -- python app.py             # your app starts with the keys in its environment
+flowforge run -- python app.py             # your app starts with the keys (masks filled)
 ```
 
-Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
-
 **When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
 
 **See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
 
-What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
+What FlowForge promises: a key is never in anything your agent receives (answers, its own process, the output it returns), never in a code file, a stored row or a log. **Add to code** puts it in one hidden, git-ignored file next to your app (like `.env`), which Claude Code is told not to read; other agents could still read it. Outside FlowForge: what your own app does with a key, a key built into an app (anyone holding the app can read it, so use publishable keys there), and other programs running as your user. The 2FA on the Vault stops web pages, anyone at your browser, and anything without your phone.
 
 ### Send someone the map
 
@@ -191,6 +277,7 @@ To use real LLM steps, `cp .env.example .env` and add a free `NVIDIA_API_KEY` fr
 | **MCP Map** (Export) | The map to send: SVG, PNG, PDF, Mermaid or Flow JSON |
 | **Checks** | Check now, each dependency's verdict, why it's down and the likely fix, and the history |
 | **Connect agent** | The set-up for Claude Code, Codex or Antigravity; what your agent gets from this repo (dependencies, health, time, ways to be faster); and, once connected, what it asked |
+| **Settings** (⚙, every project) | Your agent, paired once; the theme and the map style maps open in; the Vault's lock and where keys are kept (never a value); your data, each project's yeses and check history, and Check for updates |
 | **How the Planner drew it** | The analysis replayed: read the repo, run the app in test mode, trace the calls, draft, check. What it read, what it dropped and why |
 | **Re-check** | What changed in your repo since the last map: added, changed, removed, and conflicts with your edits. You pick what to take; the old version stays listed |
 | **Apps and connectors** (Map ⋯) | A catalog of 56 apps with search and categories, honest **Live** / **Demo only** badges, and a mock test run for every one. Apps you connected but your code doesn't call wait here, off the map |
@@ -271,6 +358,8 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /projects`, `POST /projects`, `PATCH\|DELETE /projects/{id}`, `/p/{id}/…` | Every project; add a folder; rename or remove one (its folder is never touched); any route above for one project (D39) |
+| `GET\|PATCH /settings`, `DELETE /projects/{id}/checks\|confirmed`, `POST /settings/update-check` | Settings for every project (no secret in them); clear a project's check history or take back its yeses; ask pypi.org for the newest version, only when pressed (D40) |
 | `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
 | `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
 | `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |

{flowforge_map-0.3.0 → flowforge_map-0.4.1}/README.md

@@ -1,21 +1,27 @@
 # FlowForge
 
-**An LLMOps tool for apps that already use AI: a map of how your app's LLM, MCP and API calls fit together, and a scheduler that runs them.**
+**See everything your AI app depends on: whether it's up, whether it's safe, and what's slowing it down.**
 
-You connect the apps your project uses (LLMs, MCP servers, HTTP APIs, local commands). The **Planner** reads your repo and runs the app in test mode, then draws the flow on the home page: the calls, the decisions, what runs together, the retries and fallbacks, and a gate in front of anything that moves money or sends a message. Only apps your code actually calls go on the map, and every block cites its evidence (a `file:line` or a traced call). You read the map, edit it if you want (your edits never touch your code), and re-check it when the code changes.
+```bash
+npx flowforge-map --example      # a sample app's map in your browser: no keys, nothing sent
+```
 
-Underneath, FlowForge runs workflows as a DAG: it orders the steps, runs independent ones together under rate limits, caches repeat calls, and (on the roadmap) holds the secrets and pauses risky steps for a human to approve.
+![The dependency map: every LLM, MCP server and API the app calls, with live health](docs/images/map.png)
 
-What makes it different: **it knows which chain of steps is the bottleneck and schedules around it.**
+| | |
+|---|---|
+| 🗺 **Map** | Every LLM, MCP server, HTTP API and local program your code calls, each with the `file:line` it came from |
+| 💚 **Check now** | Green, amber or red for each one, with its latency. When something is down, it tells you why |
+| ⚡ **Faster** | Reads the order your code makes its calls and shows which ones could run together, with the time you'd save |
+| 🛡 **Issues** | Keys written in code, plain `http://`, MCP servers that aren't pinned. Fix one on a new branch, or send it to your agent |
+| 🔑 **Keys** | Paste a key once. **Add to code** writes it to a git-ignored file your app reads; FlowForge only ever hands your agent a mask |
+| 🤖 **Your agent** | One MCP entry gives Claude Code, Codex or Antigravity the map, the advice and the issues |
 
-- orders steps with **topological sort** (Kahn's), and reports the exact loop if there is a cycle
-- finds the bottleneck chain with a **longest-path DP** (critical path), predicted before the run and measured after it
-- runs independent steps concurrently under limited resources (`k` slots + per-provider rate limits) using **critical-path list scheduling** (HLFET), which is within `(2 − 1/k)` of optimal (Graham's bound)
-- makes duplicate calls only once through **memoization** (single-flight in-run cache + a safe persistent cache)
+![Flow: 16.5 s as written, 11.6 s if four calls start together](docs/images/flow.png)
 
-**Free by default.** The default install, the tests and CI need no paid service: LLM steps use NVIDIA NIM's free tier, and local models (Ollama) are planned. Paid providers will work if you bring your own key, but are never needed.
+**Free and local.** MIT, no account, no paid service. FlowForge keeps its data on your machine, and the scan is plain code that sends nothing to any LLM.
 
-**Local first.** One process, SQLite, files on disk. No cloud account, no Docker, no Redis.
+**Under the hood:** a DAG scheduler runs the checks concurrently under rate limits. It uses a topological sort, a critical-path DP and HLFET list scheduling (within `(2 − 1/k)` of optimal), and it caches repeat calls. See [Scheduling policies and benchmarks](#scheduling-policies-and-benchmarks).
 
 > FlowForge started as a Design and Analysis of Algorithms course project. That version is frozen on the [`DAA`](../../tree/DAA) branch. `main` is the product.
 
@@ -24,12 +30,52 @@ What makes it different: **it knows which chain of steps is the bottleneck and s
 ### Install
 
 ```bash
-uvx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
-pip install flowforge-map        # or install it (the command is `flowforge`)
-flowforge --repo ~/my-app        # map your own repo
+npx flowforge-map --example      # try it: a sample app's maps in your browser, no keys, nothing sent
+npx flowforge-map --repo .       # map the folder you're in
 ```
 
-You need Python 3.12 or newer ([uv](https://docs.astral.sh/uv/) installs it for you). The dashboard is inside the package: no Node needed. Your data lives in `~/.flowforge`.
+That's all: no Python, no virtual env. The first run downloads FlowForge's ready-made program for your computer (about 60 MB, checked against the release's checksums) into `~/.flowforge/bin`; after that it starts at once, even offline. Works on Windows, macOS (Apple chips) and Linux x64 with Node 18+. Your data lives in `~/.flowforge`.
+
+| You have | Run | |
+|---|---|---|
+| Node (most developers) | `npx flowforge-map` | ⭐ no Python needed |
+| Node, every day | `npm i -g flowforge-map`, then just `flowforge` | installs the launcher; the program comes on first run |
+| Python people | `uvx flowforge-map` or `pipx install flowforge-map` | Python 3.12+; no virtual env to manage |
+| No terminal | the desktop app (Releases) | download and open; **Settings → Terminal** adds the `flowforge` command too (Linux .rpm/.deb have it already) |
+
+Every way gives the same `flowforge` command: `npx flowforge-map status`, `npx flowforge-map key add STRIPE_KEY`, and so on. Intel Macs, Linux ARM and Windows ARM have no ready-made build yet, so `npx` uses `uvx` there.
+
+The first time, a short welcome walks you through three steps, each one skippable: your app's folder (or the example), pairing your coding agent once, and a lock for your keys. **⚙ Settings** at the bottom of the rail keeps what applies to every project: your agent, the theme and map style, the Vault's lock, and your data (each project's size, the MCP servers it may start, its check history, and the version, with **Check for updates**, which asks pypi.org only when you press it).
+
+### Terminal
+
+```bash
+flowforge status [PROJECT]     # health, issues, missing keys and the next step
+flowforge projects             # every project at a glance
+flowforge issues [PROJECT]     # security findings and fixes
+flowforge check [PROJECT]      # preview checks; run them from the dashboard
+flowforge settings             # saved settings, data location and version
+flowforge scan ~/my-app        # terminal summary; pipe it or use --json for JSON
+flowforge key list             # key names and statuses, never values
+```
+
+Project commands use the current folder's project, else the last opened; PROJECT is its name or id. They read local files and work with the dashboard stopped. `--plain` or `NO_COLOR` disables colour and the banner; pipes have no colour or animation.
+
+### Desktop app
+
+The same dashboard in its own window, with Python inside: nothing else to install. Download the installer for your computer from the [Releases](https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator/releases) page:
+
+| Your computer | Download |
+|---|---|
+| Windows | `FlowForge_x.y.z_x64-setup.exe` or `.msi` |
+| Mac (Apple Silicon or Intel) | `FlowForge_x.y.z_aarch64.dmg` or `_x64.dmg` |
+| Linux | `.AppImage`, `.deb` or `.rpm` |
+
+The builds aren't signed yet (signing costs money every year), so the first launch asks once:
+- **Mac:** right-click FlowForge in Applications → **Open** → **Open**.
+- **Windows:** on "Windows protected your PC", click **More info** → **Run anyway**.
+
+After that it opens normally. **Browse…** picks your app's folder; **Settings → Your agent** pairs your coding agent with the app's own FlowForge.
 
 ### From source (to work on FlowForge)
 
@@ -48,7 +94,7 @@ uv run flowforge --example                # opens http://127.0.0.1:8000: a sampl
 ### Map your own repo
 
 ```bash
-uv run flowforge scan path/to/your/repo     # what it depends on, as JSON: nothing stored, nothing sent
+uv run flowforge scan path/to/your/repo     # summary (pipe or --json for JSON); nothing stored, nothing sent
 uv run flowforge --repo path/to/your/repo   # opens its dependency map; add --replace to switch folders
 ```
 
@@ -70,19 +116,24 @@ Switch the map to **Flow**. FlowForge reads your Python (by its syntax tree), Da
 - **Faster** compares "as written" (the slowest action, one call after another) with "could be", and lists the calls that don't need each other's results. **Show the change** writes out the `asyncio.gather`, Dart's `(a, b).wait` or `Promise.all` (now → could be, ready to copy) when it's safe; **Copy prompt for your coding agent** hands the rest to Claude Code, Codex or any agent. FlowForge never edits your code.
 - **Watch it run** plays the could-be schedule; pointing at a block lights up its path. Five map styles: Studio, Boxed, Blueprint, Metro, Soft.
 
+### Many projects
+
+The home page lists every app you've mapped, with its dependencies, what needs fixing and missing keys. **+ New project** takes your app's folder, scans it and shows its map. The project tile at the top of the rail switches between the projects you have open, and each one comes back where you left it. **×** closes a project from that list without deleting it. Each project keeps its own map, checks, issues and keys; `flowforge --repo PATH` opens (or adds) that folder's project.
 
 ### Use it from your coding agent
 
-FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can ask it about your app and then make the change themselves. Open **Connect agent** in the dashboard: it gives you the one line (or config block) for your agent, with the paths filled in. For Claude Code it looks like:
+FlowForge is also an **MCP server**, so Claude Code, Codex or Antigravity can ask it about your app and then make the change themselves. **Settings → Your agent** (also on **Connect agent**) gives you the one line (or config block) for your agent. With `uvx`, for Claude Code it looks like:
 
 ```bash
-claude mcp add flowforge -- uv --directory /path/to/flowforge run flowforge mcp --repo /path/to/your/app
+claude mcp add flowforge -- uvx flowforge-map mcp
 ```
 
-Your agent gets ten tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
+Pair your agent once and it sees every project: `flowforge mcp` with no folder answers about the project your agent is working in, or any other by name (`list_projects` shows them all). Your agent gets eleven tools: `list_projects`, `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys`, `get_fix_requests`, `request_key`, `wait_for_keys` and `what_changed`. All read only, except `request_key`, which only asks you for a key by name. Every answer is masked (key values never appear), the agent can't make FlowForge change your code, and a check starts an MCP server only after you said yes to it on the Checks page. FlowForge needs no AI of its own for any of this.
 
 ### Fix what's unsafe, with one click
 
+![Issues: a key in the code, an unpinned MCP server, plain http](docs/images/issues.png)
+
 The **Issues** page lists what the scan found unsafe, and every issue has one button:
 
 | Issue | Button | What happens |
@@ -94,22 +145,55 @@ Fix needs a git repo and the file committed. FlowForge works out the change itse
 
 ### Keys your coding agent never sees
 
-Your agent only needs a key's **name**: the code it writes reads `os.environ["STRIPE_SECRET_KEY"]`. You give FlowForge the value once, and your app gets it when it starts:
+![Keys: paste once, Add to code, the agent sees a mask](docs/images/keys.png)
 
+**Add to code.** The **Keys** page lists each place your code needs a key, with its `file:line`. Paste the key and press **Add to code**:
+
+```
+lib/config.dart:8   String.fromEnvironment('SUPABASE_ANON_KEY')      ← FlowForge found the spot
+[ •••••••••••• ]  [ Add to code ]                                      ← you paste, one click
+✓ SUPABASE_ANON_KEY is in your app. Press Run as always.
+  Changed: .flowforge/dart-defines.json · Run config · .gitignore · Claude Code told not to read it · Vault
+```
+
+The key goes where your app reads it, and **never into a code file**:
+
+| Your app | The key goes to | Then |
+|---|---|---|
+| Flutter (`String.fromEnvironment`) | `.flowforge/dart-defines.json`, and `--dart-define-from-file` is added to your Run config (Android Studio, IntelliJ, VS Code) | press Run |
+| Python, Node or Flutter with a `.env` loader | `.env` | start it as always |
+| Vite | `.env.local` (as `VITE_…`) | start it as always |
+
+- A placeholder like `apiKey = "ENTER KEY HERE"` is rewritten to read the key.
+- A real key written in the code gets **Hide it**: one click moves it out the same way.
+- The file is git-ignored, and nothing is committed: you see the change in `git diff`.
+- An app that loads no file gets **Save**, and the Keys page says why.
+- The settings a key needs come too: `SUPABASE_URL` is listed under **Your app also needs**, filled in from your Supabase key, with the same **Add to code** (a setting isn't secret, so it doesn't go to the Vault).
+
+**With an agent**, the agent never gets a key; it gets a **mask**:
+
+```
+you paste STRIPE_SECRET_KEY once  →  your agent sees  ffkey://STRIPE_SECRET_KEY
+the agent writes the mask where the key goes (or reads the env var STRIPE_SECRET_KEY in code)
+the agent calls run_app(["flutter", "run", "--dart-define=STRIPE_SECRET_KEY=ffkey://STRIPE_SECRET_KEY"])
+FlowForge asks you once: "Your agent wants to run flutter run … with STRIPE_SECRET_KEY"   [Deny] [Allow]
+FlowForge (plain code, no AI) fills the mask and starts the app → the output comes back masked
+```
+
+Masks work in commands, in the environment and in `.env` lines; other config files never get the key written into them, so read the env var there. After you allow a command once, the same command runs without asking (**Settings** can turn the question off). The Keys page lists your agent's runs with **Stop**. This covers keys read when the app is *built* too, such as Flutter's `--dart-define` and Vite's `import.meta.env`. On the map, a 🔑 badge marks a block whose key is missing. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
+
+**No agent?** The same works by hand:
 ```bash
 flowforge key add STRIPE_SECRET_KEY        # typed hidden; saved in your OS keychain
 flowforge key list                         # each key the code reads: saved · in .env · missing
-flowforge key import                       # move a .env into FlowForge (then delete the .env)
-flowforge run -- python app.py             # your app starts with the keys in its environment
+flowforge run -- python app.py             # your app starts with the keys (masks filled)
 ```
 
-Each command takes `--repo PATH` (default: the folder you're in). In the dashboard, the **Keys** page does the same with no commands: paste a missing key into its box, or click **Move into FlowForge** for one that's in `.env`. On the map, a 🔑 badge marks a block whose key is missing. Your agent's `get_keys` tool gets names, statuses and the command to ask you to run, never a value. With no keychain (a server, CI), keys go to an encrypted file in `~/.flowforge`.
-
 **When your agent adds a dependency that needs a key**, it calls `request_key("STRIPE_SECRET_KEY", "for Stripe in pay.py")`. The map says "Your agent asked for a key", and the new block shows in coral, "key missing". Click it, paste the key on the Keys page, and the agent's `wait_for_keys` returns the moment it's saved. The agent only ever sees the name.
 
 **See a key again** in the **Vault**: set a password and scan the QR with an authenticator app (Google Authenticator, Authy, 1Password), once. After that, your password, then the 6-digit code on your phone, open it for 5 minutes. It lists every key with its health: healthy, written in code, in `.env`, can't read, unused, or old. It also shows where each key lives, what uses it, and whether it's a live or test key. Each value shows for 30 seconds. Forgot the password? `flowforge lock reset --forget` drops the lock (your keys stay) and the dashboard says so.
 
-What this does and doesn't promise: the key is never handed to your agent and isn't left in a file it reads by habit. An agent that can run commands as you could still run `flowforge run -- printenv`, read your keychain, or reset the lock (the dashboard then shows it was reset), so it isn't impossible. The 2FA stops web pages, anyone at your browser, and anything without your phone. MCP servers your coding tool starts get their environment from that tool, not from FlowForge.
+What FlowForge promises: a key is never in anything your agent receives (answers, its own process, the output it returns), never in a code file, a stored row or a log. **Add to code** puts it in one hidden, git-ignored file next to your app (like `.env`), which Claude Code is told not to read; other agents could still read it. Outside FlowForge: what your own app does with a key, a key built into an app (anyone holding the app can read it, so use publishable keys there), and other programs running as your user. The 2FA on the Vault stops web pages, anyone at your browser, and anything without your phone.
 
 ### Send someone the map
 
@@ -156,6 +240,7 @@ To use real LLM steps, `cp .env.example .env` and add a free `NVIDIA_API_KEY` fr
 | **MCP Map** (Export) | The map to send: SVG, PNG, PDF, Mermaid or Flow JSON |
 | **Checks** | Check now, each dependency's verdict, why it's down and the likely fix, and the history |
 | **Connect agent** | The set-up for Claude Code, Codex or Antigravity; what your agent gets from this repo (dependencies, health, time, ways to be faster); and, once connected, what it asked |
+| **Settings** (⚙, every project) | Your agent, paired once; the theme and the map style maps open in; the Vault's lock and where keys are kept (never a value); your data, each project's yeses and check history, and Check for updates |
 | **How the Planner drew it** | The analysis replayed: read the repo, run the app in test mode, trace the calls, draft, check. What it read, what it dropped and why |
 | **Re-check** | What changed in your repo since the last map: added, changed, removed, and conflicts with your edits. You pick what to take; the old version stays listed |
 | **Apps and connectors** (Map ⋯) | A catalog of 56 apps with search and categories, honest **Live** / **Demo only** badges, and a mock test run for every one. Apps you connected but your code doesn't call wait here, off the map |
@@ -236,6 +321,8 @@ FlowForge itself keeps keys out of its runs, events, cache, logs and the dashboa
 | `POST /connectors/{id}/test` | One harmless check (MCP and local apps) |
 | `GET /connectors/{id}/activity`, `GET /connectors/{id}/tools` | What an app has done; an MCP server's tools |
 | `GET /security` | The scan's security findings, by level, with the fix and a prompt for each (D31) |
+| `GET /projects`, `POST /projects`, `PATCH\|DELETE /projects/{id}`, `/p/{id}/…` | Every project; add a folder; rename or remove one (its folder is never touched); any route above for one project (D39) |
+| `GET\|PATCH /settings`, `DELETE /projects/{id}/checks\|confirmed`, `POST /settings/update-check` | Settings for every project (no secret in them); clear a project's check history or take back its yeses; ask pypi.org for the newest version, only when pressed (D40) |
 | `GET /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}`, `POST /keys/{name}/import` | The keys the code reads and their status; save one (write-only), move one in from `.env`, or forget it (D36, D37) |
 | `GET /issues`, `POST /issues/{id}/preview\|fix\|send` | Every issue with its button; the masked change; make it on a new branch; send it to your agent (D37) |
 | `GET /lock`, `POST /lock/setup\|confirm\|password\|code\|close`, `GET /vault/keys`, `POST /keys/reveal` | The Vault: its lock (your password, then the authenticator code) and, once open, every key's health and one value at a time (D37, D38) |