Skip to content

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

Docs: lead with mapping existing code, blueprints as the second use

Hayden Smith77d780bc4be3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6044769..ae3232c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
## Unreleased
-- **Blueprints: plan it before you build it.** Share a PRD, a spec or a description of something you want to build, and Floorplan draws the map of what it would take: every part, file, endpoint and screen, how they connect, and the outside services they rely on. It's marked as planned (dashed cards and a **Blueprint** label), Health becomes a design review of the plan (endpoints anyone could use, decisions the PRD leaves open, loose ends), and each part has **Build this with Claude** (or Codex), a ready request to build it as planned. Switch the Ask bar to **Change** to shape the plan from the map ("also plan out refunds"): the map redraws with the new and changed pieces highlighted, and **Undo** puts it back. Design review items can be settled the same way with **Resolve on the map**: an open question just needs your answer. Once the code exists, the map can switch to the real code.
+- **Blueprints: plan it before you build it.** Floorplan still maps the code you have; now it can also start from no code at all. Share a PRD, a spec or a description of something you want to build, and Floorplan draws the map of what it would take: every part, file, endpoint and screen, how they connect, and the outside services they rely on. It's marked as planned (dashed cards and a **Blueprint** label), Health becomes a design review of the plan (endpoints anyone could use, decisions the PRD leaves open, loose ends), and each part has **Build this with Claude** (or Codex), a ready request to build it as planned. Switch the Ask bar to **Change** to shape the plan from the map ("also plan out refunds"): the map redraws with the new and changed pieces highlighted, and **Undo** puts it back. Design review items can be settled the same way with **Resolve on the map**: an open question just needs your answer. Once the code exists, the map can switch to the real code.
## 0.2.2 (2026-10-28)
diff --git a/README.md b/README.md
index a858975..364df5b 100644
--- a/README.md
+++ b/README.md
@@ -96,20 +96,16 @@ The cards your AI just changed light up green, each with a note on how the chang
**⚡ Stays current, stays yours**<br>
Updates re-read only what changed, and an open map reloads itself. Everything runs on your machine, and nothing is committed to git.
-</td>
-</tr>
-<tr>
-<td colspan="2" valign="top">
-
-**📐 Plan it before you build it**<br>
-No code yet? Share a PRD or describe what you want to build, and get a blueprint: the same map of every piece you'd need and how they fit together, with a review of what's still undecided and a ready request to build each part. Then shape it from the map: "also plan out refunds" redraws it with the new pieces highlighted.
-
</td>
</tr>
</table>
Plus guided **flows** you can request in plain words, a one-minute **Start here** tour, search, keyboard shortcuts, and right-click actions on every card.
+### Also: blueprints, for apps you haven't built yet
+
+Floorplan is made for mapping code you already have. It can also start from a PRD, a spec or a description of something you want to build, and draw a **blueprint**: the same kind of map, showing every part, file, endpoint and screen you'd need and how they'd fit together. Cards are dashed to show it's a plan. Instead of a Health check you get a review of what the plan still leaves open, each part has a ready request to build it, and you can reshape the plan from the map ("also plan out refunds"). Once the code exists, the blueprint becomes a map of the real thing. See [Plan something you haven't built yet](docs/getting-started.md#plan-something-you-havent-built-yet).
+
## See it in action
Want to click around yourself? Open the [live demo](https://haydenschmitty.github.io/floorplan-demo/): the real Brewline map beside a scripted conversation, in Claude Code or Codex.
@@ -194,11 +190,11 @@ When you've done more work, ask:
Only what changed is re-read, and what you just worked on lights up under **Recent work**.
-**Planning something new?** Ask:
+**No code yet?** Floorplan can plan an app from a PRD or spec instead. Share the document and ask:
> Here's my PRD. Make me a floorplan of what we'd need to build.
-You get a blueprint of the planned system, marked as planned. Switch the map's Ask bar to **Change** to add or rework pieces ("also plan out refunds"), and each part has **Build this with Claude** (or Codex) when you're ready to start.
+You get a [blueprint](#also-blueprints-for-apps-you-havent-built-yet) of the planned system, clearly marked as a plan.
### Things to try
@@ -209,7 +205,6 @@ You get a blueprint of the planned system, marked as planned. Switch the map's A
| "Fix the important issues from the floorplan's Health check" | "If I change the users table, what breaks?" |
| "Add a flow showing how a new user signs up" | "Which files handle login?" |
| "Rewrite the floorplan for developers" | "What did we change for refunds?" |
-| "Here's my PRD: make me a blueprint" | "What do I need to build for payments?" |
## How it works
@@ -293,6 +288,12 @@ Yes. Just ask ("rename 'Main server' to 'Shop API' on the floorplan"), or edit `
Yes. It's the same plugin, the same map and the same Health check. Each app runs it on your own plan: Claude Code on your Claude account, Codex on your ChatGPT sign-in. A map made in one opens fine with the other. See [Floorplan in Codex](docs/codex.md).
</details>
+<details>
+<summary><b>Can I use it before I've written any code?</b></summary>
+
+Yes, though mapping existing code is what it's mainly for. Share a PRD, a spec or a description of your app and ask for a floorplan, and you get a blueprint: a map of what you'd need to build, marked as a plan, with a review of the decisions still open. You can change it from the map, then switch to a map of the real code once it's built. See [Plan something you haven't built yet](docs/getting-started.md#plan-something-you-havent-built-yet).
+</details>
+
<details>
<summary><b>Does it work on monorepos and multi-repo setups?</b></summary>
diff --git a/docs/README.md b/docs/README.md
index deeb451..3e53f71 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,3 +12,5 @@
| [Developing Floorplan](development.md) | Repo layout, testing a local copy, releasing a new version |
New here? Start with [Getting started](getting-started.md).
+
+Floorplan is mainly for mapping code you already have, and every guide is written for that. It can also draw a **blueprint**, a map planned from a PRD or spec before the code exists: see [Plan something you haven't built yet](getting-started.md#plan-something-you-havent-built-yet), [Blueprints on the map](using-the-map.md#blueprints) and [how blueprints work](how-it-works.md#blueprints).
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 7fd6ad8..9b0a7a4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -61,7 +61,7 @@ Floorplan re-scans and compares with the last map. Moved files keep their descri
## 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:
+Everything above is about Floorplan's main job: mapping code that already exists. It has a second use, for when there's no code yet: drawing a **blueprint** of an app from a PRD, a spec or a description of what you want to build. Open the folder you'll build it in (an empty one is fine), share the document, and ask:
> Here's my PRD. Make me a floorplan of what we'd need to build.
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 0d70686..15c11be 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -91,7 +91,7 @@ Then it rebuilds. The AI only has to describe what's new or flagged, and check t
## Blueprints
-A blueprint is a map of something that isn't built yet. The AI reads a PRD or a description and writes `floorplan/plan.json`: every file and endpoint the system would need, which screen calls which endpoint, which parts use outside services and the database, and who may use each endpoint. It also lists the stack it chose, its assumptions and the questions the PRD leaves open.
+Everything above is how Floorplan maps existing code, its main job. A blueprint is the other way in: a map of something that isn't built yet. The AI reads a PRD or a description and writes `floorplan/plan.json`: every file and endpoint the system would need, which screen calls which endpoint, which parts use outside services and the database, and who may use each endpoint. It also lists the stack it chose, its assumptions and the questions the PRD leaves open.
`plan.mjs` turns the plan into the same scan `scan.mjs` makes from code, so the build, Screens, flows, the tour and Ask all work the same way. The differences:
diff --git a/docs/using-the-map.md b/docs/using-the-map.md
index abea181..2fe73f4 100644
--- a/docs/using-the-map.md
+++ b/docs/using-the-map.md
@@ -83,7 +83,7 @@ Type into the Ask bar at the bottom and press **Enter**. Claude or Codex answers
## 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:
+Everything above describes a map of existing code, which is what most maps are. A blueprint is the other kind: a map planned from a PRD or a spec before the code exists (see [Getting started](getting-started.md#plan-something-you-havent-built-yet)). It works the same way, 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.)