flowforge-map 0.2.0__tar.gz → 0.4.0__tar.gz

{flowforge_map-0.2.0 → flowforge_map-0.4.0}/.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.2.0 → flowforge_map-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowforge-map
-Version: 0.2.0
+Version: 0.4.0
 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,9 +26,12 @@ 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
 
@@ -58,12 +61,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 and Intel) 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. 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)
 
@@ -82,7 +125,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,30 +148,80 @@ Switch the map to **Flow**. FlowForge reads your Python (by its syntax tree), Da
 - **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 seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits 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
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
 
 ### 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:
+**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). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. 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`, or read your keychain, so it isn't impossible. 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
 
@@ -175,6 +268,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 |
@@ -255,7 +349,11 @@ 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 /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
+| `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) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |

{flowforge_map-0.2.0 → flowforge_map-0.4.0}/README.md

@@ -24,12 +24,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 and Intel) 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. 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 +88,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
 ```
 
@@ -71,30 +111,80 @@ Switch the map to **Flow**. FlowForge reads your Python (by its syntax tree), Da
 - **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 seven read-only tools: `get_map`, `get_flow`, `get_advice`, `check_health`, `get_security_findings`, `get_keys` and `what_changed`. Every answer is masked (key values never appear), FlowForge never edits 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
+
+The **Issues** page lists what the scan found unsafe, and every issue has one button:
+
+| Issue | Button | What happens |
+|---|---|---|
+| A key written in Python, or in JS/TS that runs on Node | **Fix** | FlowForge shows the change (the key masked). On **Approve**, the key goes to your keys and the line reads it from the environment, on a new branch `flowforge/fix-…`. Your branch and files aren't touched; merge it when you're ready. |
+| `http://`, an unpinned MCP server, a server given the whole disk, a key in `.mcp.json`, Dart or browser code | **Send to agent** | It joins your coding agent's list (`get_fix_requests`). Tell your agent "do the FlowForge fixes". |
+
+Fix needs a git repo and the file committed. FlowForge works out the change itself, with no AI. Replace a key that was in your code with its provider anyway: older commits still hold it.
 
 ### 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:
+**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). On the map, a 🔑 badge marks a block whose key is missing, and the ⚠ list has a box to paste it into. 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`, or read your keychain, so it isn't impossible. 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
 
@@ -141,6 +231,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 |
@@ -221,7 +312,11 @@ 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 /keys`, `PUT /keys/{name}`, `DELETE /keys/{name}` | The keys the code reads and their status; save one (write-only: the value never comes back) or forget it (D36) |
+| `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) |
 | `GET /health/tools`, `GET /stats/savings`, `GET /meta`, `GET /presets` | Tool health, money and time, app info, ready-made apps |
 | `GET /workflows`, `GET /workflows/{name}` | The example workflows |
 | `GET /flow?layer=mine\|planner` | The flow map: blocks, lines, positions, critical path, your edits |