Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Blueprints: cover them across the docs

Hayden Smith7cf2b6900341
diff --git a/README.md b/README.md
index cb36cbc..a858975 100644
--- a/README.md
+++ b/README.md
@@ -246,7 +246,7 @@ More in [Privacy and security](docs/privacy-and-security.md).
| | |
|---|---|
-| [Getting started](docs/getting-started.md) | Install, first map, updating, removing |
+| [Getting started](docs/getting-started.md) | Install, first map, updating, planning from a PRD, removing |
| [Floorplan in Codex](docs/codex.md) | Installing and using it in Codex |
| [Using the map](docs/using-the-map.md) | Every button, view, shortcut and menu |
| [How it works](docs/how-it-works.md) | The pipeline, connection matching, refreshes |
diff --git a/docs/README.md b/docs/README.md
index 255fd87..deeb451 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,10 +2,10 @@
| Guide | What's in it |
|---|---|
-| [Getting started](getting-started.md) | Installing, making your first map, keeping it updated, updating and removing the plugin |
+| [Getting started](getting-started.md) | Installing, making your first map, keeping it updated, planning an app before it exists, updating and removing the plugin |
| [Floorplan in Codex](codex.md) | Installing and using Floorplan in Codex, and what's different from Claude Code |
-| [Using the map](using-the-map.md) | Every button, view, panel, shortcut and right-click menu |
-| [How it works](how-it-works.md) | The pipeline from scan to map, how connections are found, how updates stay cheap |
+| [Using the map](using-the-map.md) | Every button, view, panel, shortcut and right-click menu, and what a blueprint adds |
+| [How it works](how-it-works.md) | The pipeline from scan to map, how connections are found, how updates stay cheap, how blueprints are drawn and changed |
| [What's in your project](project-files.md) | Every file Floorplan creates, which ones you can edit, and how it stays out of git |
| [Privacy and security](privacy-and-security.md) | What runs where, what leaves your machine, and how secrets are handled |
| [Troubleshooting](troubleshooting.md) | Common problems and how to fix them |
diff --git a/docs/codex.md b/docs/codex.md
index b8ff162..3fde619 100644
--- a/docs/codex.md
+++ b/docs/codex.md
@@ -55,7 +55,7 @@ It finds `codex` on your PATH, and on Windows the CLI that comes with the Codex
- **No notes file.** In Claude Code, Floorplan keeps a short note in `CLAUDE.local.md` (personal and never committed) that points future sessions at the map. Codex has no personal, uncommitted equivalent (`AGENTS.md` is shared with your team), so in Codex Floorplan leaves your project's notes alone.
- **No Claude app.** Publishing the map to the Claude app is a Claude feature. In Codex the map opens in your browser, served from your computer.
-- **"Fix with Codex".** The Health panel's ready-made fix prompts are for pasting into Codex.
+- **"Fix with Codex".** The Health panel's ready-made fix prompts are for pasting into Codex. On a [blueprint](getting-started.md#plan-something-you-havent-built-yet), the same goes for **Build this with Codex**, and the Ask bar's **Change** switch runs Codex in its read-only sandbox too: Codex replies with the updated plan, and the map's server saves it.
## Update or remove it
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 77dd33f..7fd6ad8 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -59,6 +59,21 @@ After you, or your AI, have worked on the code:
Floorplan re-scans and compares with the last map. Moved files keep their descriptions, deleted ones disappear, and only what's new or what changed in purpose is rewritten. A map already open in your browser reloads itself, and the cards that just changed light up green under **Recent work**.
+## Plan something you haven't built yet
+
+Floorplan can also draw the map of an app that doesn't exist yet. Open the folder you'll build it in (an empty one is fine), and share a PRD, a spec or a description of what you want:
+
+> Here's my PRD. Make me a floorplan of what we'd need to build.
+
+You get a **blueprint**: the same map, with every part, file, endpoint and screen the app would need, how they connect, and the outside services they rely on. Its cards have dashed outlines so you can tell it's a plan. The reply names the stack Claude or Codex chose, what it assumed, and the questions your PRD leaves open.
+
+On the map:
+- **Review** lists what the plan still has to decide, like endpoints anyone could use or open questions. **Resolve on the map** settles one: for a question, you just type your answer.
+- Switch the Ask bar to **Change** to shape the plan ("also plan out refunds"). The map redraws with what changed highlighted, and **Undo** puts it back.
+- Each part has **Build this with Claude** (or Codex), a ready request to build just that part.
+
+Once the code exists, ask Claude or Codex to "map the real code now", and the blueprint becomes a normal map. See [Blueprints](how-it-works.md#blueprints) for how it works.
+
## Open the map yourself
The map is a folder in your project. Either:
diff --git a/docs/privacy-and-security.md b/docs/privacy-and-security.md
index b788600..bcb2406 100644
--- a/docs/privacy-and-security.md
+++ b/docs/privacy-and-security.md
@@ -10,6 +10,7 @@
| The map's server (`serve.mjs`) | your computer, listening on `127.0.0.1` only | nothing on its own |
| Asking questions (Claude Code CLI) | a `claude -p` session on your computer, with your account | your question, and the files Claude chooses to read |
| Asking questions (Codex) | a `codex exec` run on your computer, with your ChatGPT sign-in, not saved to your Codex history | your question, and the files Codex chooses to read |
+| Changing a blueprint from the map | the same as asking questions, with Claude Code or Codex; the map's server then writes only the plan's files in `floorplan/` | your request, and the files the AI chooses to read |
| Asking questions (Claude app) | your claude.ai account | the map (names, descriptions, structure), never your source code. Claude asks before publishing it there |
| Floorplan Cloud waitlist (only if you sign up) | the map's server, to Floorplan's waitlist service | the email you typed or chose, and "just me" or "with my team". See [below](#floorplan-cloud-waitlist) |
diff --git a/docs/project-files.md b/docs/project-files.md
index dd7e4dd..68461c7 100644
--- a/docs/project-files.md
+++ b/docs/project-files.md
@@ -10,12 +10,13 @@ Floorplan writes to exactly two places in your project: the `floorplan/` folder,
| `graph.json` | Everything the map shows, as data | No. Rebuilt every time |
| `architecture.json` | The parts of your app, outside services, extra connections, flows and the tour | **Yes** |
| `descriptions/*.json` | The name and description of every file and endpoint, one file per part | **Yes** |
+| `plan.json` | Blueprints only: the planned files, endpoints and screens, who may use each endpoint, the stack, assumptions and open questions. Names and descriptions live here instead of `descriptions/` | **Yes** |
| `recent-work.json` | What was just worked on, and why. Replaced on every update | Rarely. The AI writes it |
| `custom-flows.json` | Flows requested from the map | Only to delete one |
| `serve.mjs` | Serves the map locally and answers questions through the Claude Code CLI or Codex | No |
| `query.mjs` | Looks things up in the map from the command line; Claude and Codex use it too | No |
| `artifact.html` | A copy for opening in the Claude app, only if you asked for one | No |
-| `.cache/` | The scan, the description worksheets, the last update's changes, and the running server's address | No. Safe to delete |
+| `.cache/` | The scan, the description worksheets, the last update's changes, the running server's address, and, for a blueprint, the last 20 versions of the plan that **Undo** goes back to | No. Safe to delete, though Undo then has nothing to go back to |
| `.gitignore` | Keeps this whole folder out of git | No |
### Editing names and structure
@@ -29,6 +30,8 @@ Your edits to `architecture.json` and `descriptions/` are kept on every update.
Or just ask Claude or Codex ("rename 'Main server' to 'Shop API' on the floorplan").
+A blueprint is edited the same way, through `plan.json` and `architecture.json`, or from the map with the Ask bar's **Change** switch. The plan's format is in [`blueprint.md`](../skills/floorplan/references/blueprint.md).
+
The full format is in [`skills/floorplan/references/schema.md`](../skills/floorplan/references/schema.md), and the style guide for names and descriptions is in [`writing-descriptions.md`](../skills/floorplan/references/writing-descriptions.md).
## `CLAUDE.local.md`
@@ -40,6 +43,8 @@ In Claude Code, Floorplan adds a short marked section here, telling future Claud
To turn it off, put `<!-- floorplan:off -->` anywhere in `CLAUDE.local.md`.
+A blueprint adds no section, since there's no code to look up yet. It's added once the map switches to the real code.
+
In Codex this file isn't touched. Codex has no personal, uncommitted notes file (`AGENTS.md` is shared with your team), so Floorplan doesn't add a note there.
## Staying out of git
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 9896a68..e7fd68a 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -47,6 +47,12 @@ Ask Claude or Codex to "update the floorplan". If a tab was already open, it rel
### The map is blank, or stuck on "Laying out"
Maps made before version 0.1.3 load their layout engine from the internet, so check your connection or any content blocker, or ask Claude to "update the floorplan". Newer maps have everything built in and work offline.
+### The Ask bar has no Change switch
+**Change** appears only on a [blueprint](getting-started.md#plan-something-you-havent-built-yet), opened through its server (`node floorplan/serve.mjs`) with the Claude Code CLI or Codex available. A map of real code doesn't have it: ask Claude Code or Codex to change the code, then update the floorplan.
+
+### A change to a blueprint failed, or I don't like it
+If the updated plan doesn't pass Floorplan's checks after a second try, nothing is saved and the map stays as it was; try asking more specifically. If a change went through but isn't what you wanted, press **Undo** in its summary, or ask for another change. The previous versions are kept in `floorplan/.cache/history/`.
+
### A connection is missing
Floorplan finds most web requests and imports by reading the code, but not all of them, for example requests to an address that only exists in settings. Ask Claude to add the missing connection to the floorplan; it records it in `architecture.json` and it stays on every update.
diff --git a/docs/using-the-map.md b/docs/using-the-map.md
index 2dacf25..abea181 100644
--- a/docs/using-the-map.md
+++ b/docs/using-the-map.md
@@ -50,7 +50,7 @@ A count of important issues, and a plain-language list of problems the scan foun
- files nothing uses;
- files over about 1,000 lines, which AI struggles to edit safely.
-Each issue has **Show on map**, which highlights the affected files and endpoints with notes, and **Fix with Claude** (or **Fix with Codex**, for a map made in Codex), which copies a ready-made prompt naming the exact files and lines and the safe fix. It's a quick automatic check, not a security audit.
+Each issue has **Show on map**, which highlights the affected files and endpoints with notes, and **Fix with Claude** (or **Fix with Codex**, for a map made in Codex), which copies a ready-made prompt naming the exact files and lines and the safe fix. It's a quick automatic check, not a security audit. On a blueprint this button is **Review** instead (see [Blueprints](#blueprints)).
### Recent work
Appears when Claude or Codex has just changed things. It lays the changed cards out on one board, with what you asked for, a summary of what was done, and a note on every card. Elsewhere on the map, changed cards have a green ring and a **Changed** or **New** tag, and the parts that contain them show **N changed**, so you can follow the green down from the top level.
@@ -81,6 +81,16 @@ Type into the Ask bar at the bottom and press **Enter**. Claude or Codex answers
- The label in the bar shows what's answering. **Claude Code** means the Claude Code CLI and **Codex** means Codex, both running on your computer and able to read your source code. **Claude** means the map was opened in the Claude app, which answers from the map alone.
- If neither is available, the bar explains what's needed. See [Troubleshooting](troubleshooting.md).
+## Blueprints
+
+A blueprint is a map planned from a PRD or a description, before the code exists (see [Getting started](getting-started.md#plan-something-you-havent-built-yet)). It works like any other map, with a few differences:
+
+- **Dashed cards and a Blueprint label** beside the board's title show it's a plan. With nothing selected, the panel says which document it was planned from, the stack and the assumptions made.
+- **Review** replaces Health. It's a design review of the plan: endpoints anyone could use to change data, endpoints with no decision on who may use them, questions the PRD leaves open, and pieces nothing connects to. Each item has **Show on map** and **Resolve on the map**, which switches the Ask bar to Change and fills in a request to settle it. For an open question, type your answer after "My answer:" and press **Enter**. (When the map isn't served, the button is **Resolve with Claude** or **Resolve with Codex**, a request to paste instead.)
+- **Who may use it:** an endpoint's panel says whether anyone, signed-in people (and which ones), your own team, or another service may use it.
+- **Build it:** every part and file has **Build this with Claude** (or Codex), which shows a request to build just that piece the way the plan describes (its files, endpoints, what it relies on and any open questions), ready to copy into Claude Code or Codex.
+- **Ask and Change:** the Ask bar has a switch. **Ask** answers questions from the plan and the PRD. **Change** takes requests like "also plan out refunds" or "drop the admin page". It takes a few minutes; then the map redraws, the new and changed cards are highlighted as recent work, and a summary offers **Show N changes**, **Undo** and suggested next changes.
+
## Right-click menus
| On | You get |