Skip to content

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

Floorplan 0.1.0

Hayden Smithd50103f3cd95
diff --git a/.claude-plugin/icon.png b/.claude-plugin/icon.png
new file mode 100644
index 0000000..b2f4a2a
Binary files /dev/null and b/.claude-plugin/icon.png differ
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..443fccd
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,18 @@
+{
+ "name": "floorplan",
+ "owner": {
+ "name": "Hayden Smith",
+ "url": "https://github.com/haydenschmitty"
+ },
+ "metadata": {
+ "description": "Floorplan: an interactive map of your codebase for Claude Code."
+ },
+ "plugins": [
+ {
+ "name": "floorplan",
+ "source": "./",
+ "description": "An interactive map of your codebase: every part, file and web request with a plain-English name and description, plus a health check, screens, guided flows and recent-work highlights.",
+ "category": "productivity"
+ }
+ ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..6ef8ae8
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,21 @@
+{
+ "name": "floorplan",
+ "version": "0.1.0",
+ "description": "See how your app actually fits together: an interactive map of your codebase where every part, file and web request has a plain-English name and description, with a health check, screens, guided flows, questions answered on the map, and highlights of what was just worked on.",
+ "author": {
+ "name": "Hayden Smith",
+ "url": "https://github.com/haydenschmitty"
+ },
+ "homepage": "https://github.com/haydenschmitty/floorplan",
+ "repository": "https://github.com/haydenschmitty/floorplan",
+ "license": "MIT",
+ "keywords": [
+ "codebase",
+ "architecture",
+ "map",
+ "visualization",
+ "onboarding",
+ "diagram",
+ "documentation"
+ ]
+}
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..dcb131d
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,5 @@
+# Store text with LF line endings so scripts behave the same on every platform
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.webp binary
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..55d25c7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,43 @@
+name: Bug report
+description: Something went wrong making, updating or using a map
+labels: [bug]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for reporting! Please don't paste private code, secrets, or screenshots of a map of a private project.
+ Security problems: use the Security tab's **Report a vulnerability** instead.
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened?
+ description: What you asked Claude, what you expected, and what happened instead.
+ validations:
+ required: true
+ - type: textarea
+ id: output
+ attributes:
+ label: Output
+ description: Anything Claude or the scripts printed, especially lines starting with ✗ or !
+ render: text
+ - type: input
+ id: project
+ attributes:
+ label: Your project
+ description: Languages and frameworks, and whether it's one repo, a monorepo or several repos side by side
+ placeholder: e.g. Next.js frontend + Flask API, two repos
+ - type: dropdown
+ id: where
+ attributes:
+ label: Where were you using Claude Code?
+ options:
+ - Desktop app (Code tab)
+ - CLI in a terminal
+ - IDE extension
+ - Other
+ - type: input
+ id: versions
+ attributes:
+ label: Versions
+ description: Floorplan version, Node version (`node --version`), and your OS
+ placeholder: Floorplan 0.1.0, Node 22, Windows 11
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..e777f15
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Report a security problem
+ url: https://github.com/haydenschmitty/floorplan/security/advisories/new
+ about: Please report vulnerabilities privately, not in a public issue.
+ - name: Documentation
+ url: https://github.com/haydenschmitty/floorplan/tree/main/docs
+ about: Guides for installing, using and troubleshooting Floorplan.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..af3375e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,24 @@
+name: Feature idea
+description: Something that would make the map more useful
+labels: [enhancement]
+body:
+ - type: textarea
+ id: goal
+ attributes:
+ label: What were you trying to do?
+ description: Start with the problem, not the solution. What did you want to understand or find, and what got in the way?
+ validations:
+ required: true
+ - type: textarea
+ id: idea
+ attributes:
+ label: What would help?
+ description: Your idea, if you have one.
+ - type: dropdown
+ id: who
+ attributes:
+ label: Who's it for?
+ options:
+ - People who built an app but don't read code
+ - Developers
+ - Both
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..fa2845c
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,16 @@
+## What this changes
+
+<!-- What does this do, and why? Link the issue if there is one. -->
+
+## How I tested it
+
+<!-- Which kind of project did you try it on? (languages, frameworks, one repo or several) -->
+
+## Checklist
+
+- [ ] No new dependencies
+- [ ] Anything the map shows people is in plain language
+- [ ] No secret values stored or printed
+- [ ] No details of a real private project in code, comments, docs or screenshots
+- [ ] `claude plugin validate .` passes
+- [ ] `CHANGELOG.md` updated, if people will notice the change
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ae4b2e5
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+# Local Claude Code settings and dev previews
+.claude/
+CLAUDE.local.md
+
+# A floorplan made of this repo itself (root only: skills/floorplan/ is the plugin)
+/floorplan/
+
+# OS and editor clutter
+.DS_Store
+Thumbs.db
+*.log
+node_modules/
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..423e1e9
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (2026-10-27)
+
+First release.
+
+- **The map:** an interactive node graph of a codebase, from the whole app down to single files and endpoints. Every part has a plain-English name and description. It works across several repos side by side.
+- **Connections:** imports, and web requests matched to the server endpoints they reach, including URLs built in variables, nested template strings and small request helpers. Flask blueprint and Express router prefixes are resolved, nested mounts included.
+- **Screens:** detects an app's pages (Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack) and shows everything behind each one.
+- **Health check:** passwords and keys in code, endpoints anyone can use without signing in, unused files and very large files, each with a ready-made fix prompt. Secret values are never stored.
+- **Ask:** questions answered as a mini-map with a walkthrough, through the Claude Code CLI or the Claude app.
+- **Flows:** guided walkthroughs, plus "Request a new flow".
+- **Start here** tour, plain-language glossary and a "Show technical detail" switch.
+- **Recent work:** the cards Claude just changed are highlighted, each with a note tying the change to what was asked.
+- **Updates:** refreshes re-read only what changed, and an open map reloads itself.
+- **Git:** nothing Floorplan creates is committed. The map folder ignores itself, and Claude's notes go in `CLAUDE.local.md`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..4674655
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,33 @@
+# Contributing to Floorplan
+
+Thanks for helping. Bug reports, ideas and pull requests are all welcome.
+
+## Reporting a bug
+
+[Open an issue](https://github.com/haydenschmitty/floorplan/issues/new/choose) and include:
+- what you asked Claude, and what happened;
+- the output Claude showed, especially lines starting with `✗` or `!`;
+- your project's languages and frameworks, and whether it's one repo or several;
+- your OS and Node version.
+
+**Please don't paste private code, secrets, or screenshots of a map of a private project.** A description of the shape of the problem is usually enough.
+
+Security problems go through [SECURITY.md](SECURITY.md), not public issues.
+
+## Suggesting a feature
+
+Open an issue describing what you were trying to do and what got in the way. Plugin users are often not engineers, so ideas that make the map clearer for them are especially welcome.
+
+## Pull requests
+
+1. Read [Developing Floorplan](docs/development.md) for the layout and how to test a local copy.
+2. Keep changes focused, and follow the guidelines there:
+ - no dependencies;
+ - plain language in anything the map shows;
+ - never store or print secret values;
+ - keep examples generic.
+3. Try your change on at least one real project, and say which kind in the PR.
+4. If you changed behaviour people will notice, add a line to `CHANGELOG.md` under an "Unreleased" heading at the top.
+5. Run `claude plugin validate .` before opening the PR.
+
+By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..40a6884
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayden Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b52a8f5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,227 @@
+<div align="center">
+
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.png">
+ <img src="docs/images/logo-light.png" alt="Floorplan logo" height="88">
+</picture>
+
+# Floorplan
+
+**See how your app actually fits together.**
+
+Claude reads your codebase and draws an interactive map of it. Every part, file and web request gets a plain-English name, and every connection between them is shown.
+
+[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757?style=flat-square)](https://code.claude.com/docs/en/overview)
+[![Version](https://img.shields.io/badge/version-0.1.0-111?style=flat-square)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-111?style=flat-square)](LICENSE)
+[![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-111?style=flat-square)](https://nodejs.org)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-0-111?style=flat-square)](#how-it-works)
+
+[Install](#install) · [Quick start](#quick-start) · [Features](#features) · [How it works](#how-it-works) · [Docs](docs/README.md) · [FAQ](#faq)
+
+</div>
+
+<!--
+ WALKTHROUGH VIDEO: on github.com, edit this README and drag your .mp4 (up to 10 MB on free plans,
+ 100 MB on paid) into the editor. GitHub uploads it and inserts a https://github.com/user-attachments/...
+ link. Put that link on its own line here (replacing this comment) and it plays inline.
+-->
+
+<!--
+ SCREENSHOT: save it as docs/images/overview.png, then replace this comment with:
+ <p align="center"><img src="docs/images/overview.png" alt="A Floorplan map of a web app" width="100%"></p>
+-->
+
+## Why Floorplan?
+
+You built an app, probably with a lot of help from AI, and it works. But ask "what happens when someone checks out?" or "what breaks if I change this?" and the honest answer is *no idea*.
+
+Floorplan gives you the diagram nobody drew. Ask Claude for a floorplan and a few minutes later you have a map you can explore, ask questions on, and keep up to date as you work.
+
+- **For builders:** understand the app you made, in your own words, without reading the code.
+- **For teams:** onboard someone in minutes, from the big picture down to the exact file.
+- **For working with Claude:** after every change, see exactly which parts it touched and why.
+
+## Features
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**🗺️ A map at every zoom**<br>
+Start with the whole app, then double-click into a part, a group of files, a file, and its endpoints. Each view shows what it's used by and what it uses.
+
+</td>
+<td width="50%" valign="top">
+
+**💬 Plain English everywhere**<br>
+"Takes card payments at checkout", not "Stripe API wrapper". Technical terms are explained on hover, and one switch shows the developer view.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**🔌 Real connections, across repos**<br>
+It follows imports, and matches each web request in your frontend to the server endpoint that answers it, even across separate repos.
+
+</td>
+<td valign="top">
+
+**🖥️ Start from a screen**<br>
+Pick a page you know and see everything behind it: its parts, the requests it makes, the server code, the data, and outside services.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**🧭 Ask the map**<br>
+"How does a refund reach the customer's card?" comes back as an answer plus a mini-map of just the pieces involved, with a step-by-step walkthrough.
+
+</td>
+<td valign="top">
+
+**🩺 Health check**<br>
+Finds passwords in code, endpoints anyone can use without signing in, unused files and files too big to edit safely. Each comes with a ready-to-paste fix.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**🟢 Recent work**<br>
+The cards Claude just changed light up green, each with a note on how the change serves what you asked for.
+
+</td>
+<td valign="top">
+
+**⚡ 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>
+</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.
+
+## Install
+
+You need [Claude Code](https://code.claude.com/docs/en/overview) (the desktop app's Code tab or the CLI) and [Node.js 18+](https://nodejs.org).
+
+```bash
+claude plugin marketplace add haydenschmitty/floorplan
+claude plugin install floorplan@floorplan
+```
+
+Start a new session and it's ready. Installing the Claude Code CLI is recommended even if you use the desktop app, because it lets the map's Ask bar read your real code. More in [Getting started](docs/getting-started.md).
+
+## Quick start
+
+1. Open your project in Claude Code. For a frontend and backend in separate repos, open the folder that holds both.
+2. Ask:
+ > Make me a floorplan of this app.
+3. Explore. The map opens on its own, starting with a short tour.
+
+When you've done more work, ask:
+
+> Update the floorplan.
+
+Only what changed is re-read, and what you just worked on lights up under **Recent work**.
+
+### Things to try
+
+| Ask Claude | Ask the map |
+|---|---|
+| "Make me a floorplan of this app" | "What happens when someone places an order?" |
+| "Update the floorplan" | "Where do we talk to Stripe?" |
+| "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?" |
+
+## How it works
+
+```mermaid
+flowchart LR
+ code["Your codebase<br/>one repo or several"] --> scan["Scan<br/>files, imports, routes, requests"]
+ scan --> claude["Claude<br/>names the parts, describes every file"]
+ claude --> build["Build<br/>map, health, screens, recent work"]
+ build --> map["floorplan/index.html<br/>opens in your browser"]
+ map -. "update the floorplan" .-> scan
+```
+
+Scripts do the mechanical work: finding repos, parsing code in a dozen languages, matching web requests to endpoints, laying out the map. They're plain Node with no dependencies. Claude does the part only a reader can: deciding what the parts of your app *are*, and saying so plainly. Details in [How it works](docs/how-it-works.md).
+
+**Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Scala, plus Vue, Svelte and Astro files, with lighter support for others.<br>
+**Endpoints:** Express, Koa, Hono, Next.js, Flask, FastAPI, Django, Go's net/http, Gin, Echo and chi, Actix, Axum, Spring.<br>
+**Screens:** Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack.
+
+## What it adds to your project
+
+A `floorplan/` folder holding the map, plus a short section in `CLAUDE.local.md` so future Claude sessions know the map is there. **Neither is committed:** the folder ignores itself in git, and `CLAUDE.local.md` goes in your clone's private ignore list. Your `.gitignore` and other tracked files are never touched. See [What's in your project](docs/project-files.md).
+
+## Privacy
+
+- The scan, the map and its small local server all run on your computer. The server only accepts connections from your own machine.
+- Questions on the map go to your own Claude account, through the Claude Code CLI.
+- The Health check never stores or shows secret values, only where they are.
+
+More in [Privacy and security](docs/privacy-and-security.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, first map, updating, removing |
+| [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 |
+| [What's in your project](docs/project-files.md) | Every file Floorplan creates, and how to edit it |
+| [Privacy and security](docs/privacy-and-security.md) | What runs where, and what leaves your machine |
+| [Troubleshooting](docs/troubleshooting.md) | Common problems and fixes |
+| [Developing Floorplan](docs/development.md) | Repo layout, local installs, releases |
+
+## FAQ
+
+<details>
+<summary><b>Does my code leave my computer?</b></summary>
+
+Only the way Claude Code always works: Claude reads the files it needs to describe your app, through your own account. The map itself is a local file and its server only listens on your machine. If you choose to open the map in the Claude app instead, Claude uploads the map (names, descriptions and structure, not your source code) to your private claude.ai account, and asks first.
+</details>
+
+<details>
+<summary><b>How long does it take, and what does it cost?</b></summary>
+
+A first map takes a few minutes for a small app and longer for a big one, because Claude describes every file and endpoint. It uses your Claude plan like any other task. Big projects are split across parallel helpers. Updates re-read only what changed, so they're quick and cheap.
+</details>
+
+<details>
+<summary><b>Do I need the Claude Code CLI?</b></summary>
+
+No. The map works without it. With the CLI, the Ask bar can read your real code to answer questions. Without it, you can ask from the Claude app instead, using the map alone.
+</details>
+
+<details>
+<summary><b>Will it change or commit my files?</b></summary>
+
+It only writes its own `floorplan/` folder and a section in `CLAUDE.local.md`, and neither is committed. It never changes your code, your `.gitignore` or your `CLAUDE.md`.
+</details>
+
+<details>
+<summary><b>The names it picked aren't how we talk about it. Can I change them?</b></summary>
+
+Yes. Ask Claude ("rename 'Main server' to 'Shop API' on the floorplan"), or edit `floorplan/architecture.json` and `floorplan/descriptions/` yourself. Your edits are kept on every update.
+</details>
+
+<details>
+<summary><b>Does it work on monorepos and multi-repo setups?</b></summary>
+
+Yes. Point it at a monorepo, a subfolder of one, or a plain folder that holds several repos side by side. It finds every repo and connects them.
+</details>
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and [Developing Floorplan](docs/development.md).
+
+## License
+
+[MIT](LICENSE) © 2026 [Hayden Smith](https://github.com/haydenschmitty)
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..abe11d5
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,25 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security problems privately through GitHub: open the repository's **Security** tab and choose **Report a vulnerability**. Don't open a public issue.
+
+Helpful details:
+- what the problem is, and what someone could do with it;
+- the steps to reproduce it;
+- which version of Floorplan you're on (see `.claude-plugin/plugin.json`).
+
+You'll get a reply within a few days. Once a fix is out, you'll be credited unless you'd rather not be.
+
+## Scope
+
+In scope:
+- the map's local server (`serve.mjs`);
+- anything that could leak secrets or source code;
+- anything that writes outside the project's `floorplan/` folder and `CLAUDE.local.md`.
+
+Out of scope: issues in Claude Code itself, which go to [Anthropic](https://www.anthropic.com/responsible-disclosure-policy).
+
+## Supported versions
+
+Only the latest release gets security fixes.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..32929cd
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,13 @@
+# Floorplan documentation
+
+| Guide | What's in it |
+|---|---|
+| [Getting started](getting-started.md) | Installing, making your first map, keeping it updated, updating and removing the plugin |
+| [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 |
+| [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 |
+| [Developing Floorplan](development.md) | Repo layout, testing a local copy, releasing a new version |
+
+New here? Start with [Getting started](getting-started.md).
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..6a48385
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,86 @@
+# Developing Floorplan
+
+## Repo layout
+
+```
+.claude-plugin/
+ plugin.json the plugin: name, version, author
+ marketplace.json this repo as its own one-plugin marketplace
+ icon.png
+skills/floorplan/
+ SKILL.md the workflow Claude follows
+ references/ formats and style guides Claude reads while working
+ schema.md architecture.json and recent-work.json
+ choosing-boundaries.md how to carve a codebase into a good map
+ writing-descriptions.md plain-language names and descriptions
+ scripts/ Node.js, no dependencies; Claude runs these
+ status.mjs is there a map, and how stale is it (runs when the skill loads)
+ scan.mjs repos, files, imports, endpoints, requests → .cache/scan.json
+ build.mjs validate, assign files, connect, Health, screens → graph.json + index.html
+ describe.mjs worksheets for Claude to name and describe files and endpoints
+ refresh.mjs incremental update: re-scan, carry over, flag changes, rebuild
+ recent.mjs facts for marking recent work
+ open.mjs start or reuse the map's server, and open the browser
+ lib/ extraction, import resolution, route matching, Health, screens, helpers
+ assets/
+ viewer.html the map (template the build fills in)
+ ui/ viewer extensions: glossary, Health, recent work, screens, tour
+ graph-query.js shared map lookups (viewer, query.mjs, Ask instructions)
+ serve.mjs copied into each project's floorplan/ folder
+ query-cli.mjs becomes floorplan/query.mjs
+ logo.png, favicon.png
+docs/ these guides
+```
+
+## Try your working copy
+
+Install from your local folder instead of GitHub:
+
+```bash
+claude plugin marketplace add /path/to/floorplan
+claude plugin install floorplan@floorplan
+```
+
+A plugin installed from a local folder runs straight from it, so edits apply in the next session with no update step.
+
+The scripts also run on their own, which is the fastest way to work on them:
+
+```bash
+node skills/floorplan/scripts/scan.mjs /path/to/project
+node skills/floorplan/scripts/build.mjs /path/to/project
+node skills/floorplan/scripts/open.mjs /path/to/project
+```
+
+`build.mjs` needs a `floorplan/architecture.json` in the project, so run the skill once first, or write a small one by hand ([schema](../skills/floorplan/references/schema.md)).
+
+## Extending the viewer
+
+Files in `skills/floorplan/assets/ui/` are inlined into every map, in name order. They talk to the viewer only through `window.Floorplan`, which offers:
+- the graph and lookups;
+- navigation (`go`, `open`, `reveal`, `showBoard`, `playFlow`);
+- `addHeaderButton` and `addPanelSection('overview' | 'item', fn)`;
+- `modal`, `toast`, `store`;
+- events (`on('ready' | 'render' | 'panel' | 'technical')`).
+
+`20-health.js` and `25-recent.js` are good examples.
+
+## Guidelines
+
+- **No dependencies.** The scripts must run anywhere Node 18+ does, with nothing to install.
+- **Plain language first.** Anything the map shows people should make sense to an app's owner, not just its engineers.
+- **Never store or print secret values.** Health findings record where a secret is and a masked hint, never the value.
+- **Keep examples generic.** Code comments, docs and prompts must not describe any real private project.
+
+## Releasing
+
+1. Update `CHANGELOG.md`.
+2. Bump `version` in `.claude-plugin/plugin.json`. Users only receive an update when the version changes.
+3. Check the manifests, including the official plugin directory's requirements:
+ ```bash
+ claude plugin validate . --profile directory
+ ```
+4. Commit, then create the release tag, which checks that `plugin.json` and the marketplace entry agree:
+ ```bash
+ claude plugin tag
+ git push --follow-tags
+ ```
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..7b89a73
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,88 @@
+# Getting started
+
+## What you need
+
+- **Claude Code**: the Code tab in the Claude desktop app, or the Claude Code CLI in a terminal.
+- **[Node.js](https://nodejs.org) 18 or newer.** Floorplan's scripts run on it. Check with `node --version`.
+- **Recommended: the [Claude Code CLI](https://code.claude.com/docs/en/overview)**, even if you mainly use the desktop app. With it, the map's Ask bar can read your actual code when answering questions.
+
+## Install
+
+Run these once, in any terminal:
+
+```bash
+claude plugin marketplace add haydenschmitty/floorplan
+claude plugin install floorplan@floorplan
+```
+
+The first command adds this repository as a plugin source. The second installs Floorplan for all your projects. The desktop app and the CLI share the same settings, so it shows up in both.
+
+**Start a new session** afterwards. Plugins load when a session starts.
+
+> In the desktop app you can also browse plugins with the **+** button next to the prompt box (**Add plugins**, or **Plugins → Browse plugins**). It lists plugins from marketplaces you've already added.
+
+## Make your first map
+
+1. **Open your project.** In the desktop app's Code tab, choose your project's folder in the row under the prompt box before sending your first message. In a terminal, run `claude` from the project folder.
+
+ If your app is split across several repos (say `web/` and `api/` side by side), open the folder that contains them all. Floorplan maps them together and connects the requests between them.
+
+2. **Ask for it:**
+
+ > Make me a floorplan of this app.
+
+ You can also pick **floorplan** from the **/** menu, or type `/floorplan:floorplan`.
+
+3. **Let Claude work.** This is what happens:
+ - A scan lists every file, import, endpoint and web request. This takes seconds and costs no tokens.
+ - Claude reads your READMEs, setup files and entry points, then decides the main parts of your app and what each one is for.
+ - Claude writes a plain-English name and a one-line description for every file and endpoint. Projects with more than about 150 files are split across parallel helpers.
+ - The map is built and checked: connections, Health issues and screens.
+
+ A small app takes a few minutes, a large one longer. You may be asked to let Claude run Floorplan's scripts (`node …`); allow them.
+
+4. **Look around.** The map opens by itself, in the desktop app's browser pane or your web browser. A one-minute **Start here** tour runs the first time. Claude's message sums up how your app fits together and points out anything serious the Health check found.
+
+See [Using the map](using-the-map.md) for everything you can do on it.
+
+## Keep it up to date
+
+After you, or Claude, have worked on the code:
+
+> Update the floorplan.
+
+Floorplan re-scans and compares with the last map. Moved files keep their descriptions, deleted ones disappear, and Claude rewrites only what's new or what changed in purpose. A map already open in your browser reloads itself, and the cards that just changed light up green under **Recent work**.
+
+## Open the map yourself
+
+The map is a folder in your project. Either:
+
+```bash
+node floorplan/serve.mjs
+```
+
+serves it at http://127.0.0.1:4378 with a working Ask bar, or double-click `floorplan/index.html`, where everything works except asking questions.
+
+When Claude opens the map for you, the server runs in the background and stops by itself two hours after you close the last tab. To stop it sooner:
+
+```bash
+node floorplan/serve.mjs --stop
+```
+
+## Update the plugin
+
+Plugins installed from GitHub don't update automatically unless you turn that on. To get the latest version:
+
+```bash
+claude plugin update floorplan@floorplan
+```
+
+Or turn on automatic updates: in a Claude Code session, run `/plugin`, open **Marketplaces**, and choose **Enable auto-update**. Either way, updates apply in your next session. See the [changelog](../CHANGELOG.md) for what changed.
+
+## Remove it
+
+```bash
+claude plugin uninstall floorplan@floorplan
+```
+
+Then delete the `floorplan/` folder and the Floorplan section of `CLAUDE.local.md` from any project you used it in.
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
new file mode 100644
index 0000000..4c4916d
--- /dev/null
+++ b/docs/how-it-works.md
@@ -0,0 +1,97 @@
+# How it works
+
+Floorplan splits the work between scripts and Claude. The scripts do everything mechanical: finding files, parsing code, matching requests to endpoints, laying out the map. They're plain Node.js with no dependencies, and they cost no tokens. Claude does what only a reader of the code can: deciding what the parts of your app *are*, and explaining them plainly.
+
+```mermaid
+flowchart TD
+ status["status: is there a map already?"] -->|no| scan
+ status -->|yes| refresh["refresh: re-scan, carry over what didn't change"]
+ scan["scan: repos, files, imports, endpoints, requests"] --> arch["Claude writes architecture.json<br/>the parts of the app, outside services, flows, tour"]
+ arch --> build["build: assign files, connect everything,<br/>Health, screens, the map"]
+ build --> describe["Claude names and describes every file and endpoint"]
+ describe --> recent["Claude marks recent work"]
+ refresh --> describe
+ recent --> open["open: serve the map and show it"]
+```
+
+## 1. Scan
+
+`scan.mjs` finds every git repository under the folder you point it at (one repo, a monorepo, or several repos side by side), skipping duplicate worktrees. It lists files with git, so your `.gitignore` is respected, then extracts from each file:
+
+- **imports**, resolved to real files: TypeScript path aliases, Python packages, Go modules, Rust crates, JVM packages;
+- **exported definitions** and their doc comments;
+- **endpoints** the server defines;
+- **web requests** the code makes;
+- content **fingerprints**, so later updates can tell what changed.
+
+Supported languages: TypeScript and JavaScript (including Vue, Svelte and Astro files), Python, Go, Rust, Java, Kotlin, Scala and Groovy, with lighter support for others.
+
+## 2. Connecting requests to endpoints
+
+The most useful lines on the map connect a screen's web requests to the server code that answers them, often across repos. Floorplan:
+
+- **Finds endpoints** in Express, Koa, Hono, Next.js (route files and API routes), Flask, FastAPI, Django, Go (net/http, Gin, Echo, chi, Fiber), Actix, Axum and Spring.
+- **Resolves prefixes**: Flask blueprints registered with a `url_prefix`, and Express routers mounted with `app.use('/api/users', usersRouter)`, including routers mounted inside other routers and mounts with middleware in front.
+- **Finds requests** made with `fetch`, axios, ky, `requests` and similar, including:
+ - addresses built in a variable first: `const url = …; api.get(url)`;
+ - template strings with nested parts;
+ - small helpers in the same file that add a prefix, like `call('/definitions')`.
+- **Matches** the two. When a request only spells out part of the address, because the base URL lives in settings, Floorplan learns each client's base path and prefers matches that fit it.
+
+It's pattern matching, not a compiler, so it catches most connections but not all. If an important link is missing, ask Claude to add it to the floorplan, and it will record it as an explicit connection.
+
+## 3. Claude describes the system
+
+Claude reads the scan summary, READMEs, setup files and entry points, then writes `architecture.json`:
+
+- the main parts of your app, each with a plain summary;
+- the outside services it really talks to (databases, payment providers, email);
+- connections the scan can't see, like queues, scheduled jobs and webhooks;
+- a few guided flows and a "Start here" tour.
+
+The build then assigns every file to the deepest part whose patterns match, and reports anything left over.
+
+Next, `describe.mjs` writes a worksheet for each part. A worksheet is a digest of every file and endpoint: what it defines, its doc comments, what it uses and what uses it. Claude fills in a name and description for each. On large projects, the worksheets are split across parallel Claude helpers.
+
+By default everything is written for the app's owner, not an engineer: what each thing does for the business, in everyday words. Ask for a developer-facing map and it switches to technical style.
+
+## 4. Build
+
+`build.mjs` validates everything Claude wrote and reports problems by name ("did you mean …"). It then:
+
+- connects the parts, using imports, matched requests and Claude's explicit connections;
+- runs the **Health** check;
+- detects **screens**: Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack;
+- writes `graph.json` and the self-contained `index.html`.
+
+The map lays itself out in your browser with [ELK](https://eclipse.dev/elk/), so the build itself is fast.
+
+## 5. Recent work
+
+After every make or update, Claude records what was just worked on in `recent-work.json`. `recent.mjs` lists the facts: what changed since the last map, uncommitted changes, and recent commits, each matched to its card. Claude adds the *why*: what you asked for, and how each change serves it. The previous highlights are replaced every time.
+
+## 6. Showing it
+
+`open.mjs` starts the map's small local server in the background and opens your browser. If the server is already running for this map, it's reused, and any open tab reloads itself in place instead of a new one opening.
+
+## Updates
+
+`refresh.mjs` re-scans and compares against the last build, using each file's fingerprint:
+
+- **exact content**, which spots edits, renames and moves;
+- **signature**: its exports, endpoints and doc comments. Edits inside function bodies don't count.
+
+It then:
+- carries descriptions over to moved and renamed files and endpoints;
+- drops entries for deleted files;
+- flags entries whose signature changed for Claude to review.
+
+Then it rebuilds. Claude only has to describe what's new or flagged, and check the structure if the change was large. That's why updates are quick.
+
+## Asking questions
+
+With the Claude Code CLI, the map's server runs `claude -p` in your project for each question. That session gets read-only tools only: reading and searching files, and `floorplan/query.mjs`, which looks things up in the map. It answers with text plus the cards to show, so answers can cite real code.
+
+In the Claude app, the map asks Claude through the app instead, with the same lookups but no access to your source.
+
+The same lookups help ordinary Claude Code sessions. The short section Floorplan adds to `CLAUDE.local.md` tells them to check the map (`query.mjs find`, `show`, `path`, `overview`) before searching the code from scratch.
diff --git a/docs/images/logo-dark.png b/docs/images/logo-dark.png
new file mode 100644
index 0000000..cf4794d
Binary files /dev/null and b/docs/images/logo-dark.png differ
diff --git a/docs/images/logo-light.png b/docs/images/logo-light.png
new file mode 100644
index 0000000..df249e9
Binary files /dev/null and b/docs/images/logo-light.png differ
diff --git a/docs/privacy-and-security.md b/docs/privacy-and-security.md
new file mode 100644
index 0000000..e7cebd6
--- /dev/null
+++ b/docs/privacy-and-security.md
@@ -0,0 +1,37 @@
+# Privacy and security
+
+## What runs where
+
+| Part | Where it runs | What it sends |
+|---|---|---|
+| Scan, build, updates | your computer (Node.js) | nothing |
+| Writing names and descriptions | Claude, through your Claude Code session | the files Claude reads, the same as any Claude Code task |
+| The map | your browser | it loads its layout engine from [jsDelivr](https://www.jsdelivr.com/) and fonts from Google Fonts. No code or map data is sent |
+| 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 (Claude app) | your claude.ai account | the map (names, descriptions, structure), never your source code. Claude asks before publishing it there |
+
+Floorplan has no analytics or telemetry, and no servers of its own.
+
+To keep the map fully offline, put `elk.bundled.js` (elkjs 0.9.x) in `skills/floorplan/assets/vendor/`. The build then inlines it into the map instead of loading it from a CDN.
+
+## The local server
+
+- It listens on `127.0.0.1` only, so other machines on your network can't reach it.
+- Every start creates a random token, which only the map page it serves receives. Asking questions and saving flows require that token, and those requests are refused when they come from another website.
+- Questions run Claude with **read-only** tools: reading files, searching, and the map's own lookup script. It can't edit files or run other commands.
+- It stops by itself two hours after the last tab closes, and `node floorplan/serve.mjs --stop` stops it immediately.
+
+## Secrets
+
+The Health check looks for passwords, API keys and private keys in your code, and for `.env` files that would be committed. When it finds one, it records only the file, the line, the kind of secret, and a masked hint like "starts AKIA…, 20 characters". **Secret values are never stored in the map, printed, or sent anywhere**, and Claude is instructed never to repeat them.
+
+The check is a helpful first pass, not a security audit.
+
+## Git
+
+Nothing Floorplan creates is committed. See [What's in your project](project-files.md#staying-out-of-git).
+
+## Reporting a vulnerability
+
+Please report security problems privately, as described in [SECURITY.md](../SECURITY.md), rather than in a public issue.
diff --git a/docs/project-files.md b/docs/project-files.md
new file mode 100644
index 0000000..6503fd6
--- /dev/null
+++ b/docs/project-files.md
@@ -0,0 +1,54 @@
+# What's in your project
+
+Floorplan writes to exactly two places in your project: the `floorplan/` folder, and a short section in `CLAUDE.local.md`. Neither is committed to git, and nothing else in your project is touched.
+
+## The `floorplan/` folder
+
+| File | What it is | Edit it? |
+|---|---|---|
+| `index.html` | The map: one self-contained page | No. Rebuilt every time |
+| `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** |
+| `recent-work.json` | What was just worked on, and why. Replaced on every update | Rarely. Claude 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 | No |
+| `query.mjs` | Looks things up in the map from the command line; Claude uses it too | No |
+| `artifact.html` | A copy for opening in the Claude app, only if you asked for one | No |
+| `.cache/` | The scan, Claude's worksheets, the last update's changes, and the running server's address | No. Safe to delete |
+| `.gitignore` | Keeps this whole folder out of git | No |
+
+### Editing names and structure
+
+Your edits to `architecture.json` and `descriptions/` are kept on every update. You can:
+- rename a part, or reword a description;
+- move files between parts by changing the `paths` patterns;
+- add a connection the scan missed;
+- pin a note to a file;
+- add or change flows and the tour.
+
+Or just ask Claude ("rename 'Main server' to 'Shop API' on the floorplan").
+
+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`
+
+Floorplan adds a short marked section here, telling future Claude Code sessions in your project that the map exists and how to look things up in it. `CLAUDE.local.md` is Claude Code's file for personal project notes, loaded at the start of every session like `CLAUDE.md`. Floorplan:
+- creates the file if you don't have one;
+- only ever rewrites its own section, between `<!-- floorplan:start -->` and `<!-- floorplan:end -->`;
+- adds the file to your clone's private ignore list, `.git/info/exclude`.
+
+To turn it off, put `<!-- floorplan:off -->` anywhere in `CLAUDE.local.md`.
+
+## Staying out of git
+
+- **`floorplan/`** contains its own `.gitignore` that ignores everything in the folder, including itself. Your `.gitignore` isn't changed, and the folder never appears in `git status`.
+- **`CLAUDE.local.md`** is listed in `.git/info/exclude`, the per-clone ignore list that is never committed. If your project already ignores it, nothing is added.
+
+The map is personal to each clone. Teammates who install Floorplan make their own.
+
+If you committed a `floorplan/` folder before, ignoring it doesn't untrack those files. The build tells you the command that does, which keeps the files on disk:
+
+```bash
+git rm -r --cached floorplan
+```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..acb171e
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,64 @@
+# Troubleshooting
+
+### The Ask bar says it needs the Claude Code CLI
+The map is open without a way to ask questions. Either:
+- install the [Claude Code CLI](https://code.claude.com/docs/en/overview), sign in, then ask Claude to update the floorplan or run `node floorplan/serve.mjs`;
+- or open the map in the Claude app: ask Claude to "publish my floorplan to the Claude app". Answers there come from the map only.
+
+### The CLI is installed but isn't found
+`serve.mjs` looks for `claude` on your PATH and in `~/.local/bin`. If it lives somewhere else:
+
+```bash
+node floorplan/serve.mjs --claude /path/to/claude
+```
+
+### `node` isn't recognized
+Install [Node.js](https://nodejs.org) 18 or newer, then start a new session so Claude Code picks it up.
+
+### Claude keeps asking to run `node` scripts
+Floorplan pre-approves its own scripts while it's running, but Claude Code may still ask in some setups. Choose the option to always allow them for this project.
+
+### The skill doesn't show up
+Plugins load when a session starts, so start a new one after installing. Check that it's installed and enabled:
+
+```bash
+claude plugin list
+```
+
+Plain requests like "make me a floorplan" work without the slash command. If you do want it, it's `/floorplan:floorplan`.
+
+### The map looks out of date
+Ask Claude to "update the floorplan". If a tab was already open, it reloads itself once the update finishes.
+
+### The map is blank, or stuck on "Laying out"
+The map loads its layout engine from a CDN, so check your internet connection or any content blocker. For fully offline maps, see [Privacy and security](privacy-and-security.md#what-runs-where).
+
+### 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.
+
+### A file is in the wrong part, or under "Unassigned"
+Ask Claude to move it, or edit the `paths` patterns in `floorplan/architecture.json` and ask for an update.
+
+### "floorplan/ already exists here and isn't a map"
+Your project has its own folder called `floorplan`, which Floorplan won't write into. Rename your folder, or ask Claude to build the map somewhere else; the scan and build scripts accept `--out <folder>`.
+
+### `git status` shows files under `floorplan/`
+They were committed before Floorplan started ignoring the folder. Untrack them, keeping the files on disk:
+
+```bash
+git rm -r --cached floorplan
+```
+
+### Port 4378 is in use
+Nothing to do. The server moves to the next free port, and the URL it prints, or that Claude gives you, is the right one.
+
+### Stopping the background server
+
+```bash
+node floorplan/serve.mjs --stop
+```
+
+It also stops by itself two hours after the last tab closes.
+
+### Still stuck?
+[Open an issue](https://github.com/haydenschmitty/floorplan/issues/new/choose) with what you asked, what happened, and the output Claude showed. Please leave out anything private from your code.
diff --git a/docs/using-the-map.md b/docs/using-the-map.md
new file mode 100644
index 0000000..e79e525
--- /dev/null
+++ b/docs/using-the-map.md
@@ -0,0 +1,88 @@
+# Using the map
+
+The map is a board of cards connected by lines. Each card is a part of your app: a big area like "Main server", a group of files, a single file, or an endpoint (a request the server can receive). Lines show what uses what.
+
+## Getting around
+
+| To… | Do this |
+|---|---|
+| go inside a card | double-click it, or select it and press **Enter** |
+| go back up | **Backspace**, the back arrow, or the breadcrumbs at the top |
+| pan | drag the background |
+| zoom | scroll, or **+** / **−** |
+| fit everything on screen | **F**, or the frame button bottom-left |
+| find anything | **/** or **Ctrl/⌘ K**, then type a name, file or URL |
+| see details | click a card; the panel on the right fills in |
+| show or hide the panel | **P**, or the panel button top-right |
+| close a menu, stop a flow, clear a selection | **Esc** |
+
+The details on cards simplify as you zoom out: descriptions drop away and titles get bigger, so the map stays readable from far away.
+
+## Cards
+
+- **Title and description:** a plain-English name, and one line on what it does.
+- **Footer:** how much is inside (modules, files or endpoints) on the left. On the right, a green tag when it's part of recent work.
+- **Endpoint cards** show the method and address (`POST /api/orders`) above their name.
+- **A small amber dot** after a title means there's a note pinned to that file.
+- **Pill-shaped cards at the edges** of a view are things outside it. The brackets above each column say which side is which:
+ - **Used by:** outside parts that use or call into this one.
+ - **Inside ‹name›:** what this part is made of.
+ - **Uses:** outside parts it relies on, like a database or Stripe.
+
+ Double-click an outside card to jump there.
+
+Hover over a card for a moment to see what kind of thing it is, where it lives, and how big it is. Hover over a line to see what it carries, for example which endpoints a screen calls.
+
+## The side panel
+
+Click anything to see it in the panel: its full description, what it's part of, what's inside it, what it's **used by** and what it **depends on**, its endpoints, and buttons to open it or ask about it. With nothing selected, the panel describes the current view, or the whole app at the top level.
+
+Drag the panel's left edge to resize it.
+
+## Header buttons
+
+### Health
+A count of important issues, and a plain-language list of problems the scan found:
+- passwords and keys written into the code, or into a committed `.env` file;
+- endpoints that let anyone change or read data without signing in;
+- 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**, 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.
+
+### Recent work
+Appears when Claude 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.
+
+### Screens
+Every page of your app that Floorplan detected. Pick one to see everything behind it: its components, the requests it makes, the server code that answers them, the data they touch, and outside services.
+
+### Start here
+Replays the one-minute tour that runs the first time you open a map.
+
+### Flows
+Guided walkthroughs of the app's main jobs, like "Checkout" or "Sign up". A flow moves across the board step by step, with a narration at each stop. Use **←** / **→** or the flow bar's buttons to step through, and **Esc** to stop.
+
+**Request a new flow** lets you describe one in plain words ("how does a refund get back to the customer's card?"), and Claude traces it through the code. Flows you request are saved with the map.
+
+### Filters
+- **Show connections:** turn kinds of lines on or off (Uses, Web requests, Background jobs and so on).
+- **Show technical detail:** switch to developer terms (Imports, HTTP, Queues), and show each file's exports.
+- **Highlight recent work:** turn the green highlights off for a clean map.
+
+## Asking questions
+
+Type into the Ask bar at the bottom and press **Enter**. Claude answers in a few sentences and shows an **answer board**: just the cards involved, how they connect, a short note on each, and a numbered walkthrough when the answer is a sequence. Follow-up suggestions appear under the answer. **Back to map** returns to where you were.
+
+- **Right-click → Ask about this** on any card or line adds it to your question as context.
+- The label in the bar shows what's answering. **Claude Code** means the CLI, which can read your source code. **Claude app** 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).
+
+## Right-click menus
+
+| On | You get |
+|---|---|
+| a card | Open · Show on the map · Ask about this · Show details · Copy name · Copy path (or endpoint) · Open in editor |
+| a line | Ask about this connection · Show details |
+| the background | Ask about this view · Up one level · Back to overview · Fit to screen · Search |
+
+**Open in editor** opens the file in VS Code (or another editor that handles `vscode://` links) at the right line.
diff --git a/skills/floorplan/SKILL.md b/skills/floorplan/SKILL.md
new file mode 100644
index 0000000..b715add
--- /dev/null
+++ b/skills/floorplan/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: floorplan
+description: Draw a floorplan of an app's codebase (one repo or several side by side), an interactive node-graph map where every subsystem, module, file and HTTP route has a human-readable name and a one-line description, connected by the imports and HTTP calls between them, at several zoom levels. It is saved as a self-contained floorplan/index.html in the codebase. Use whenever the user wants to visualize, map, diagram, document or get an architectural overview of a codebase, repo or monorepo, understand how their app works or is connected under the hood, onboard onto unfamiliar code, see how the frontend talks to the backend, or update an existing floorplan, even if they don't say "visualize".
+argument-hint: "[path-to-codebase-root] [--refresh]"
+allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/*)
+---
+
+# Floorplan
+
+You produce `floorplan/` at the codebase root: a floorplan of the app that someone new can read like a system diagram. Every card shows a human name and a one-line description, with the real path in small type underneath.
+
+- **You write:** `architecture.json` (subsystems, modules, flows) and `descriptions/*.json` (a name and description for every file and route).
+- **Generated:** `graph.json` and `index.html`.
+
+The scripts do the mechanical work: finding repos, parsing imports and routes, matching HTTP calls to endpoints, layout and rendering. Your job is the part only a reader of the code can do: deciding what things *are* and saying so plainly.
+
+Existing map: !`node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || true`
+Arguments: $ARGUMENTS
+
+## A map already exists? Refresh it instead
+
+If the status above shows an existing map, don't start over. Run:
+
+`node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>`
+
+It re-scans, compares content fingerprints against the last build, and does the bookkeeping without spending tokens:
+- carries descriptions over to moved or renamed files and endpoints;
+- drops entries for deleted files;
+- flags entries whose exports or routes changed with a `review` note (edits inside function bodies don't count);
+- rebuilds;
+- prints what changed and a short NEXT list.
+
+Do only what NEXT asks:
+- add globs for new directories that landed in "unassigned";
+- run describe.mjs (step 6), which now only produces worksheets for the new and flagged items;
+- check module summaries and flows if the change was large.
+
+A typical refresh after a few hours of work is a handful of worksheet entries. Then mark recent work (step 7), and show it and report (step 8). Always show it, even when nothing changed: the user asked to see their floorplan.
+
+## Workflow (first run)
+
+The codebase root is the argument if one was given, otherwise the current directory. It may be a single repo, or a plain folder holding several repos (frontend + backend + infra, and so on). The scanner finds every git repo under it and skips duplicate worktrees.
+
+1. **Scan.**
+ `node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root>`
+ It writes `floorplan/.cache/scan.json` and prints a summary: repos, a code tree with LOC, entrypoints, the heaviest directory→directory import edges, HTTP call→route matches across repos, external packages and hosts. Work from the summary. Don't read scan.json, which is large.
+
+2. **Read the contract.** Read [references/schema.md](references/schema.md) (the architecture.json format) and [references/choosing-boundaries.md](references/choosing-boundaries.md) (how to carve a codebase into a good map).
+
+3. **Explore just enough.** Read READMEs, manifests (package.json, pyproject, go.mod, docker-compose, deploy configs) and entrypoints, then skim 1–2 files per candidate subsystem until you can write a one-sentence summary for each. You're after the shape of the system, not a code review.
+
+4. **Write `floorplan/architecture.json`.** Aim for:
+ - 3–9 top-level nodes;
+ - 3–12 children under each big one;
+ - globs covering more than 90% of code files;
+ - external nodes for the databases and third-party services the code really talks to;
+ - edges only for what the scan can't see (queues, cron, webhooks, cross-service calls through env-configured URLs);
+ - 1–3 flows that explain the system's main jobs;
+ - a `tour`: 3–8 narrated stops for the "Start here" tour (see below).
+
+ Every node needs a `summary`.
+
+ **Audience.** The people opening this map are usually the app's owners, often non-technical builders who made it with AI. Unless the user asks for a developer-facing map, leave `"audience"` unset or set it to `"everyone"`, and write every `project.summary`, node `label`/`summary`, and file/route description in plain language (see "Plain language" in references/writing-descriptions.md). Use short labels like "Main server" rather than "Shop API (Flask)". Paths and method/URL stay visible on the cards, so descriptions only need to say what the thing is for.
+
+ **Tour.** Add `"tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }]`, with stops in the order a newcomer should see them: what the app is, the apps people use, the main server, outside services, and ending on an important screen's file. Write titles and notes in plain words for someone who has never read the code. The first guided flow is added at the end automatically as "watch a real request". Without a tour, one is built from node summaries and the first flow, so good summaries and at least one flow matter.
+
+5. **Build and fix.**
+ `node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root>`
+ It validates everything and names each problem ("did you mean …", files unassigned by directory, ambiguous globs). Fix and rebuild until it's clean and unassigned is under ~10%.
+
+ **Nothing Floorplan makes is committed.** `floorplan/` holds its own `.gitignore` that ignores the whole folder, so the project's tracked files aren't touched. If git already tracks files there, the build prints the `git rm -r --cached` command to untrack them; pass it on to the user rather than running it.
+
+ Each build also keeps a short marked block in the project's `CLAUDE.local.md`, Claude Code's personal, uncommitted project notes, which load at session start like CLAUDE.md. The block tells future Claude Code sessions here that the map exists and how to look things up in it with `floorplan/query.mjs`, so they start from the map instead of searching the code from scratch. The build adds `CLAUDE.local.md` to the repo's local ignore list (`.git/info/exclude`, not `.gitignore`). It rewrites only its own block, and moves the block out of `CLAUDE.md` if an older version put it there. To opt out, pass `--no-claude-md`, or put `<!-- floorplan:off -->` in CLAUDE.local.md.
+
+6. **Describe every file and route.**
+ `node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root>`
+ This writes one worksheet per module (`floorplan/.cache/worksheets/<key>.md`) and a skeleton to fill in (`floorplan/descriptions/<key>.json`). Each worksheet holds a digest of every file (docstrings, definitions, what it uses and what uses it) and every route (handler, docstring), which is enough to describe most files without opening them.
+ - Read [references/writing-descriptions.md](references/writing-descriptions.md) first.
+ - **More than ~150 files:** split the worksheets across parallel subagents if you have them, ~100–150 files each, grouped by area (backend routes, services, scripts, tests, UI). Give each one its worksheet keys, the codebase root and the writing guide, and tell it to edit only its own `descriptions/<key>.json` files and keep the keys unchanged.
+ - **Smaller codebases:** do it yourself.
+
+ Then rebuild. The build reports `DESCRIPTIONS files X/Y · routes X/Y`. Get both to 100%: re-run describe.mjs and it lists only what's still missing.
+
+7. **Mark recent work.** The map highlights what was just worked on: those cards get a green "Changed"/"New" tag, the parts containing them show "N changed", hovering shows your note, and a **Recent work** button lays them out on one board. Do this on every make and every update, because it replaces the previous highlights.
+ `node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root>`
+ It lists what changed since the previous map, uncommitted changes and recent commits, each matched to the card it appears as. The *why* comes from you:
+ - **What counts.** Work done in this conversation, by you or your subagents, is the main source. Lean on what you know about it. If you did nothing here (a fresh session), use what recent.mjs shows that is clearly in flight: uncommitted changes and the latest commits. If there's nothing, write `{ "tasks": [] }` so old highlights clear.
+ - **Write `floorplan/recent-work.json`.** Use one task per thing the user asked for: `title` (2–5 words), `request` (what they asked, in their words, shortened), `summary` (1–2 sentences on what was done toward it and where it stands, including anything deleted, since deleted files can't be highlighted). Then add `items`: the cards that changed, as a file path, node id or `"METHOD /path"`, with `change` (`"new"` or `"changed"`) and a `note`.
+ - **Every note answers "how does this relate to what they asked for?"** In one or two plain sentences, say what changed on this card and why the request needed it. For example, write "Now catches web requests whose address is built up in a variable first, which is why the orders and inventory screens were showing no server calls." Not "Added flattenTemplates and variableUse helpers".
+ - **Highlight what mattered.** Pick the files and endpoints whose behaviour changed for this request, usually 3–15. Skip tests and drive-by edits unless they're the point. A file with a changed endpoint can list both the file and the endpoint.
+ - **Keep the code's words out unless the audience is developers.** Never put secrets in notes.
+
+ Format: [references/schema.md#recent-work](references/schema.md#recent-work). Then run build.mjs. It reports `RECENT WORK N card(s) highlighted` and warns about refs that aren't on the map.
+
+8. **Show it, then report.** Whenever you make or update a floorplan, finish by putting it in front of the user:
+ `node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>`
+ - It starts the map's server in the background (or reuses the one already running for this map) and opens it in their browser. Tabs that are already open reload in place instead of a new one opening.
+ - It prints the URL, whether Ask works (the Claude Code CLI was found), and how to stop the server. The server also stops on its own a couple of hours after the last tab closes.
+ - If you have an in-app browser or preview tool, pass `--no-open` and open the printed URL there instead, so the map appears right beside the conversation.
+ - If this is a remote or headless machine where the user can't reach 127.0.0.1, skip open.mjs and tell them to run `node floorplan/serve.mjs` on their own machine, or offer the Claude app route (step 9).
+
+ Then **report.** Give the URL, then describe the architecture you mapped in 3–5 lines, in the user's language, including anything surprising: cycles, god-files, dead areas, coupled subsystems. Always mention the **high-severity Health items** (`graph.health`; the build output and graph.json list them). Hard-coded passwords/keys and endpoints anyone can change data through are things the owner needs to hear about. Never repeat a secret's value. Say that `architecture.json` and `descriptions/` are theirs to edit, and that after more work they can just ask to "update the floorplan", which re-reads only what changed. Give them those plain words rather than a slash command: installed as a plugin, the command is `/floorplan:floorplan`, and as a personal skill it's `/floorplan`. On a first run, mention in one line that the map and its notes for future sessions (in CLAUDE.local.md) stay out of git.md so future sessions use the map. On an update, start with what changed for what they asked (it's highlighted under **Recent work**).
+
+## 9. Opening the map and asking questions
+
+The map has a floating Ask bar. The user types a question, and Claude answers with text plus an answer board: the relevant cards, the connections among them, a note on each card, and an optional step-by-step walkthrough. There are two ways to power it. The UI is the same either way.
+
+- **Claude Code CLI (best).** The map's server (`floorplan/serve.mjs`, started by open.mjs in step 8) serves it at http://127.0.0.1:4378, or the next free port. Each question runs the user's `claude` CLI in the codebase with read-only tools (the map via `floorplan/query.mjs`, plus Read/Grep/Glob on the source), so answers can cite real code. The script finds `claude` on PATH or in `~/.local/bin`; `--claude <path>` overrides that and `--model <name>` picks the model (open.mjs passes both through). Users can also run `node floorplan/serve.mjs` themselves at any time, and stop a background one with `node floorplan/serve.mjs --stop`.
+- **Claude app.** If you're running in the Claude app (the Artifact tool is available), offer to publish the map so they can open it there and ask questions on their own Claude account. Answers then come from the map only (names, descriptions, connections, endpoints), not the source, and the Ask bar shows a hint to install the CLI for a better experience. To publish:
+ 1. `node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifact`. This writes `floorplan/artifact.html` without the machine's absolute path.
+ 2. Publish that file with the Artifact tool, `capabilities: {"sample": {}}`, and keep the same file path for later publishes so the URL stays stable.
+ 3. After each refresh, rebuild with `--artifact` and republish.
+
+ Publishing uploads the map (paths, names, descriptions, structure), not the source code, to their private claude.ai account. Say that before you do it.
+- **Neither:** `floorplan/index.html` still opens directly in a browser. The Ask bar explains what's needed.
+
+### What else the map gives them (automatic)
+
+- **Health.** A header button, with a count of important issues, opens a plain-language list of problems the scan found:
+ - passwords and API keys written into the code or a committed `.env`;
+ - endpoints that let anyone change or read data without signing in (including a sign-in check placed above the route line);
+ - files nothing uses;
+ - files over ~1,000 lines, which AI struggles to edit safely.
+
+ Each issue has **Show on map** (highlights the affected files and endpoints with notes) and **Fix with Claude** (a ready-to-paste prompt naming the exact files and lines and the safe fix). It's computed by `scripts/lib/health.mjs` during scan and build, and it never stores secret values, only the file, line and a masked hint. Treat it as a quick automatic check, not a security audit.
+- **Screens.** The build detects the app's screens (Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack) with `scripts/lib/screens.mjs`. It also works out what sits behind each one: its components, the requests it makes, the server code and data that answer them, and outside services. A **Screens** button lets people start from the page they know.
+- **Start here.** A one-minute tour runs on first open and can be replayed from the header. It uses your `tour`, or builds one automatically.
+- **Plain words by default.** Connection types read "Uses", "Web requests", "Background jobs". Common technical terms are underlined and explained on hover. **Filters → Show technical detail** switches to developer terms and shows exports.
+
+People can also use **Flows → Request a new flow** to have Claude trace something ("how does a refund get back to the customer's card?") into a step-by-step flow. With serve.mjs these are saved to `floorplan/custom-flows.json`, and every build folds them into the map (steps pointing at deleted code are dropped with a warning). Treat that file as user content: keep it on refresh, and don't edit it unless asked.
+
+## Notes
+
+- Paths are relative to the codebase root and use forward slashes. In a multi-repo root they start with the repo folder, e.g. `api-service/src/**`.
+- Route keys in descriptions are `"METHOD /full/path"` exactly as the worksheet prints them.
+- The viewer loads its layout engine (ELK) and fonts from CDNs. To make output work offline, put `elk.bundled.js` (elkjs 0.9.x) in `${CLAUDE_SKILL_DIR}/assets/vendor/` and the build will inline it.
+- HTTP edges come from matching URL strings at call sites (including URLs kept in a variable first, nested template strings, and small same-file helpers that add a path prefix) to route definitions (Flask, FastAPI, Express, Next.js, Spring, Go and others), with blueprint/router prefixes resolved, nested mounts included. Treat them as strong hints. If an important service-to-service link is missing, add it as an explicit edge.
+- Don't hand-edit graph.json or index.html; they're regenerated on every build.
diff --git a/skills/floorplan/assets/favicon.png b/skills/floorplan/assets/favicon.png
new file mode 100644
index 0000000..fbd8150
Binary files /dev/null and b/skills/floorplan/assets/favicon.png differ
diff --git a/skills/floorplan/assets/graph-query.js b/skills/floorplan/assets/graph-query.js
new file mode 100644
index 0000000..3319e71
--- /dev/null
+++ b/skills/floorplan/assets/graph-query.js
@@ -0,0 +1,230 @@
+// floorplan graph queries, shared by the viewer (as page tools for the Claude app) and by
+// floorplan/query.mjs (as a CLI the Claude Code CLI calls). Plain script: no imports, no exports.
+// Item ids: n:<node id> f:<file path> r:<route index> s:<file path>#<export index>
+
+function createGraphQuery(G) {
+ const nodes = new Map(G.nodes.map((n) => [n.id, n]));
+ const files = new Map(G.files.map((f) => [f.p, f]));
+ const routes = G.routes || [];
+ const routesByFile = new Map();
+ routes.forEach((r, i) => { if (!routesByFile.has(r.f)) routesByFile.set(r.f, []); routesByFile.get(r.f).push(i); });
+ const kidsOf = new Map();
+ for (const n of G.nodes) if (n.parent) { if (!kidsOf.has(n.parent)) kidsOf.set(n.parent, []); kidsOf.get(n.parent).push(n.id); }
+
+ const nodeChain = (id) => { const out = []; let n = nodes.get(id); while (n) { out.push(n.id); n = n.parent ? nodes.get(n.parent) : null; } return out; };
+ /** The node ids an item lives under, deepest first. */
+ function owners(id) {
+ if (id.startsWith('n:')) return nodeChain(id.slice(2));
+ if (id.startsWith('f:')) { const f = files.get(id.slice(2)); return f ? nodeChain(f.n) : []; }
+ if (id.startsWith('r:')) { const r = routes[+id.slice(2)]; return r ? owners('f:' + r.f) : []; }
+ if (id.startsWith('s:')) return owners('f:' + id.slice(2).replace(/#\d+$/, ''));
+ return [];
+ }
+ function brief(id) {
+ if (id.startsWith('n:')) { const n = nodes.get(id.slice(2)); return n && { id, type: n.kind === 'external' ? 'external' : 'module', name: n.label, description: n.summary || '' }; }
+ if (id.startsWith('f:')) { const f = files.get(id.slice(2)); return f && { id, type: 'file', name: f.name, description: f.d || '', path: f.p }; }
+ if (id.startsWith('r:')) { const r = routes[+id.slice(2)]; return r && { id, type: 'endpoint', name: r.name, description: r.d || '', path: `${r.m} ${r.p}` }; }
+ if (id.startsWith('s:')) {
+ const m = /^s:(.*)#(\d+)$/.exec(id); const f = m && files.get(m[1]); const s = f?.s?.[+m[2]];
+ return s && { id, type: s[1], name: s[0], description: s[4] || '', path: `${f.p}:${s[2]}` };
+ }
+ return null;
+ }
+ const exists = (id) => !!brief(id);
+ const inside = (x, container) => x === container || (container.startsWith('n:') && owners(x).includes(container.slice(2))) || (container.startsWith('f:') && (x.startsWith('r:') ? 'f:' + routes[+x.slice(2)].f === container : x.startsWith('s:') ? 'f:' + x.slice(2).replace(/#\d+$/, '') === container : false));
+ const ownerItem = (endpoint) => endpoint.startsWith('f:') ? 'n:' + (files.get(endpoint.slice(2))?.n || '') : endpoint;
+
+ /** Accepts an id, or what people naturally pass: a file path, a module id, or "GET /path". */
+ function normId(id) {
+ id = String(id || '').trim().replace(/^\.\//, '').replace(/\\/g, '/');
+ if (brief(id)) return id;
+ if (files.has(id)) return 'f:' + id;
+ if (nodes.has(id)) return 'n:' + id;
+ const m = /^([A-Z]+)\s+(\/\S*)$/i.exec(id);
+ if (m) { const ri = routes.findIndex((r) => r.m === m[1].toUpperCase() && r.p === m[2]); if (ri >= 0) return 'r:' + ri; }
+ return id;
+ }
+
+ const FILLER = new Set(['how', 'does', 'do', 'did', 'the', 'a', 'an', 'is', 'are', 'where', 'what', 'which', 'who', 'of', 'to', 'for', 'in', 'on', 'and', 'or', 'we', 'i', 'my', 'our', 'it', 'work', 'works', 'happen', 'happens', 'get', 'gets', 'with']);
+ function find(query, kind, limit = 15) {
+ const words = String(query || '').toLowerCase().split(/\s+/).filter(Boolean);
+ const terms = words.filter((t) => !FILLER.has(t)).length ? words.filter((t) => !FILLER.has(t)) : words;
+ if (!terms.length) return [];
+ const pool = [];
+ if (!kind || kind === 'module') for (const n of G.nodes) pool.push(['n:' + n.id, n.label, n.summary || '', n.id, 4]);
+ if (!kind || kind === 'file') for (const f of G.files) pool.push(['f:' + f.p, f.name, f.d || '', f.p, 3]);
+ if (!kind || kind === 'endpoint') routes.forEach((r, i) => pool.push(['r:' + i, r.name, r.d || '', `${r.m} ${r.p}`, 3]));
+ if (!kind || kind === 'symbol') for (const f of G.files) (f.s || []).forEach((s, i) => pool.push([`s:${f.p}#${i}`, s[0], s[4] || '', f.p, 1]));
+ // everything matching every word; if nothing does, the best partial matches
+ const scored = [];
+ for (const [id, name, desc, p, w] of pool) {
+ const n = name.toLowerCase(), d = desc.toLowerCase(), pp = p.toLowerCase();
+ let s = 0, hit = 0;
+ for (const t of terms) {
+ const sc = n === t ? 30 : n.startsWith(t) ? 20 : n.includes(t) ? 12 : pp.includes(t) ? 7 : d.includes(t) ? 5 : 0;
+ if (sc) { s += sc; hit++; }
+ }
+ if (hit) scored.push([hit, s + w * 2 - n.length * 0.02, id]);
+ }
+ const best = Math.max(0, ...scored.map((x) => x[0]));
+ const floor = best === terms.length ? best : Math.max(1, Math.ceil(terms.length / 2));
+ return scored.filter((x) => x[0] >= floor).sort((a, b) => b[0] - a[0] || b[1] - a[1])
+ .slice(0, Math.min(Number(limit) || 15, 40)).map(([, , id]) => brief(id));
+ }
+
+ function connections(id, max = 15) {
+ const out = new Map(), inn = new Map();
+ for (const l of G.links) {
+ const ia = inside(l.a, id), ib = inside(l.b, id);
+ if (ia === ib) continue;
+ const other = ia ? l.b : l.a;
+ const key = (id.startsWith('n:') ? ownerItem(other) : other) + '|' + l.k;
+ const m = ia ? out : inn;
+ const cur = m.get(key) || { id: key.split('|')[0], via: l.k, weight: 0, endpoints: new Set() };
+ cur.weight += l.w;
+ for (const [ri] of l.calls || []) if (ri != null) cur.endpoints.add(ri);
+ m.set(key, cur);
+ }
+ const fmt = (m) => [...m.values()].sort((a, b) => b.weight - a.weight).slice(0, max).map((c) => ({
+ ...brief(c.id), via: c.via, weight: c.weight,
+ ...(c.endpoints.size ? { endpoints: [...c.endpoints].slice(0, 6).map((ri) => `r:${ri} ${routes[ri].m} ${routes[ri].p}`) } : {}),
+ })).filter((x) => x.id);
+ return { dependsOn: fmt(out), usedBy: fmt(inn) };
+ }
+
+ function show(id) {
+ id = normId(id);
+ const b = brief(id);
+ if (!b) throw new Error(`Unknown id "${id}". Use find first; ids look like n:api, f:src/app.ts, r:12, s:src/app.ts#3.`);
+ const parent = owners(id)[id.startsWith('n:') ? 1 : 0];
+ const res = { ...b, ...(parent ? { partOf: brief('n:' + parent) && { id: 'n:' + parent, name: nodes.get(parent).label } } : {}) };
+ const recent = (G.recent?.items || []).filter((x) => x.id === id);
+ if (recent.length) res.recentWork = recent.map((x) => `${G.recent.tasks[x.task]?.title}: ${x.note}`);
+ if (id.startsWith('n:')) {
+ const n = nodes.get(id.slice(2));
+ if (n.details) res.details = n.details;
+ res.size = { files: n.stats.files, loc: n.stats.loc };
+ res.children = (kidsOf.get(n.id) || []).map((k) => ({ id: 'n:' + k, name: nodes.get(k).label, description: nodes.get(k).summary || '' }));
+ const fl = G.files.filter((f) => owners('f:' + f.p).includes(n.id)).sort((a, z) => z.loc - a.loc);
+ res.files = fl.slice(0, 12).map((f) => ({ id: 'f:' + f.p, name: f.name, description: f.d || '' }));
+ if (fl.length > 12) res.moreFiles = fl.length - 12;
+ res.endpoints = routes.filter((r) => owners('f:' + r.f).includes(n.id)).length;
+ Object.assign(res, connections(id));
+ } else if (id.startsWith('f:')) {
+ const f = files.get(id.slice(2));
+ Object.assign(res, { loc: f.loc, module: { id: 'n:' + f.n, name: nodes.get(f.n)?.label }, ...(f.note ? { note: f.note } : {}) });
+ const rs = routesByFile.get(f.p) || [];
+ if (rs.length) res.endpoints = rs.slice(0, 40).map((ri) => ({ id: 'r:' + ri, method: routes[ri].m, path: routes[ri].p, name: routes[ri].name }));
+ const handlers = new Set(rs.map((ri) => routes[ri].h));
+ const ex = (f.s || []).map((s, i) => [s, i]).filter(([s]) => !handlers.has(s[0]));
+ if (ex.length) res.exports = ex.slice(0, 30).map(([s, i]) => `s:${f.p}#${i} ${s[0]} (${s[1]})`);
+ Object.assign(res, connections(id, 20));
+ } else if (id.startsWith('r:')) {
+ const ri = +id.slice(2), r = routes[ri];
+ Object.assign(res, { method: r.m, routePath: r.p, handler: r.h, line: r.l, file: { id: 'f:' + r.f, name: files.get(r.f)?.name } });
+ const callers = new Map();
+ for (const l of G.links) { const n = (l.calls || []).filter(([x]) => x === ri).length; if (n) callers.set(l.a, (callers.get(l.a) || 0) + n); }
+ res.calledFrom = [...callers.entries()].map(([a, n]) => ({ ...brief(a), calls: n }));
+ } else {
+ const m = /^s:(.*)#(\d+)$/.exec(id); const f = files.get(m[1]); const s = f.s[+m[2]];
+ res.file = { id: 'f:' + f.p, name: f.name };
+ res.importedBy = G.links.filter((l) => l.b === 'f:' + f.p && (l.names || []).some((nm) => nm === s[0] || (nm === 'default' && s[3]))).slice(0, 25).map((l) => brief(l.a));
+ }
+ return res;
+ }
+
+ /** Shortest dependency chain from anything inside `from` to anything inside `to`. */
+ function path(from, to) {
+ from = normId(from); to = normId(to);
+ if (!exists(from) || !exists(to)) throw new Error('Unknown id; use find first.');
+ const adj = new Map();
+ const add = (a, b, l) => { if (!adj.has(a)) adj.set(a, []); adj.get(a).push([b, l]); };
+ for (const l of G.links) add(l.a, l.b, l);
+ const starts = [...new Set([...G.links.map((l) => l.a), ...G.links.map((l) => l.b)])].filter((x) => inside(x, from));
+ const isGoal = (x) => inside(x, to);
+ const prev = new Map(starts.map((s) => [s, null]));
+ const queue = [...starts];
+ let goal = null;
+ while (queue.length && !goal) {
+ const x = queue.shift();
+ for (const [y, l] of adj.get(x) || []) {
+ if (prev.has(y)) continue;
+ prev.set(y, [x, l]);
+ if (isGoal(y)) { goal = y; break; }
+ queue.push(y);
+ }
+ }
+ if (!goal) return { found: false, note: `No chain of imports/calls leads from ${from} to ${to}. Try the reverse direction, or the two may only meet through a shared dependency.` };
+ const hops = [];
+ for (let x = goal; prev.get(x); x = prev.get(x)[0]) {
+ const [p, l] = prev.get(x);
+ hops.unshift({ from: brief(p), to: brief(x), via: l.k, ...(l.calls?.length ? { endpoints: l.calls.slice(0, 3).map(([ri]) => ri != null ? `r:${ri} ${routes[ri].m} ${routes[ri].p}` : '').filter(Boolean) } : {}) });
+ }
+ return { found: true, hops: hops.slice(0, 15) };
+ }
+
+ function overview() {
+ return {
+ project: G.project.name, summary: G.project.summary || '',
+ systems: G.nodes.filter((n) => !n.parent).map((n) => ({ id: 'n:' + n.id, name: n.label, kind: n.kind, description: n.summary || '', modules: (kidsOf.get(n.id) || []).map((k) => `n:${k} ${nodes.get(k).label}`) })),
+ flows: (G.flows || []).map((f) => ({ title: f.title, steps: f.steps.map((s) => `${s.ref} ${s.note}`) })),
+ counts: { files: G.files.length, endpoints: routes.length },
+ ...(G.recent ? { recentWork: (G.recent.tasks || []).map((t, ti) => ({ title: t.title, request: t.request, summary: t.summary, changed: G.recent.items.filter((x) => x.task === ti).map((x) => `${x.id} ${x.note}`) })) } : {}),
+ };
+ }
+
+ return { find, show, path, overview, exists, brief };
+}
+
+// What an answer looks like, for both engines (JSON Schema).
+const FLOORPLAN_ANSWER_SCHEMA = {
+ type: 'object',
+ properties: {
+ title: { type: 'string', description: 'Short title for the answer view, at most 6 words.' },
+ answer: { type: 'string', description: 'The answer in Markdown, at most ~180 words. Mention map items inline as [[id]].' },
+ items: { type: 'array', description: '3-14 map items most relevant to the answer, most important first.', items: { type: 'object', properties: { id: { type: 'string' }, note: { type: 'string', description: 'Why this item matters here, at most 15 words.' } }, required: ['id', 'note'] } },
+ steps: { type: 'array', description: 'Optional ordered walkthrough when the answer is a sequence (a request path, a data flow). Empty otherwise.', items: { type: 'object', properties: { id: { type: 'string' }, note: { type: 'string' } }, required: ['id', 'note'] } },
+ followups: { type: 'array', description: '2-3 short follow-up questions the person might ask next.', items: { type: 'string' } },
+ },
+ required: ['title', 'answer', 'items'],
+};
+
+// A requested flow: an ordered walkthrough of map items (JSON Schema).
+const FLOORPLAN_FLOW_SCHEMA = {
+ type: 'object',
+ properties: {
+ title: { type: 'string', description: 'Short flow title, at most 6 words, e.g. "Checkout to Stripe payment".' },
+ description: { type: 'string', description: 'One sentence on what the flow shows.' },
+ steps: { type: 'array', description: '3-9 steps in the order things happen, each a map item and what happens there.', items: { type: 'object', properties: { id: { type: 'string' }, note: { type: 'string', description: 'What happens at this step, at most 18 words.' } }, required: ['id', 'note'] } },
+ },
+ required: ['title', 'steps'],
+};
+
+function floorplanFlowInstructions(G, engine) {
+ return [
+ `You build guided flows for an interactive architecture map of the codebase "${G.project.name}". A flow is an ordered walkthrough: each step is one map item (module n:..., file f:..., endpoint r:..., or export s:...) and a note on what happens there.`,
+ engine === 'cli'
+ ? 'Find the items with `node floorplan/query.mjs find "<words>"`, `show <id>` and `path <fromId> <toId>`; read source files when you need to confirm the order of events.'
+ : 'Find the items with the tools find_items, get_item and dependency_path.',
+ 'Trace what the person asks for from its trigger (a user action, webhook, cron job) to its final effect (database write, external call, response).',
+ 'Use 3-9 steps. Prefer the most specific item that tells the story (an endpoint over its file, a file over its module), and make consecutive steps things that really call or import each other.',
+ 'Reply with JSON only: {"title", "description", "steps": [{"id", "note"}]}. Only use ids the map gave you.',
+ ].join('\n');
+}
+
+function floorplanAskInstructions(G, engine) {
+ const tools = engine === 'cli'
+ ? `Query the map with Bash: \`node floorplan/query.mjs overview\`, \`node floorplan/query.mjs find "<words>" [--kind module|file|endpoint|symbol]\`, \`node floorplan/query.mjs show <id>\`, \`node floorplan/query.mjs path <fromId> <toId>\`. Every result is JSON with ids. Start with the map; read or grep source files when you need specifics the map does not have.`
+ : `Use the tools find_items, get_item and dependency_path to explore the map. You cannot read source files, so answer from the map's names, descriptions, endpoints and connections, and say so when a question needs the code itself.`;
+ return [
+ `You answer questions about the codebase "${G.project.name}" for someone exploring an interactive architecture map of it.`,
+ `The map has cards for modules (ids n:...), files (f:<path>), HTTP endpoints (r:<number>) and exported symbols (s:<path>#<number>), each with a human-readable name and description, connected by imports and HTTP calls.`,
+ tools,
+ 'Use a few lookups, not dozens. Then reply with JSON only: {"title", "answer", "items", "steps", "followups"}.',
+ '- answer: Markdown, at most ~180 words, plain and specific. Refer to map items inline as [[id]] (they become clickable).',
+ '- items: the 3-14 cards that best show the answer, most important first, each with a note (at most 15 words) on its role.',
+ '- steps: an ordered walkthrough when the answer is a sequence (a request path, a data flow); otherwise [].',
+ '- followups: 2-3 short follow-up questions.',
+ 'Only use ids that the map gave you.',
+ ].join('\n');
+}
diff --git a/skills/floorplan/assets/logo.png b/skills/floorplan/assets/logo.png
new file mode 100644
index 0000000..b690d2d
Binary files /dev/null and b/skills/floorplan/assets/logo.png differ
diff --git a/skills/floorplan/assets/query-cli.mjs b/skills/floorplan/assets/query-cli.mjs
new file mode 100644
index 0000000..478f866
--- /dev/null
+++ b/skills/floorplan/assets/query-cli.mjs
@@ -0,0 +1,30 @@
+// floorplan/query.mjs: look things up in this folder's graph.json. Generated by build.mjs; the Claude
+// Code CLI calls it when you ask questions from the map (node floorplan/serve.mjs).
+//
+// usage: node floorplan/query.mjs overview
+// node floorplan/query.mjs find "<words>" [--kind module|file|endpoint|symbol] [--limit 15]
+// node floorplan/query.mjs show <id>
+// node floorplan/query.mjs path <fromId> <toId>
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const G = JSON.parse(fs.readFileSync(path.join(here, 'graph.json'), 'utf8'));
+const q = createGraphQuery(G);
+const argv = process.argv.slice(2);
+const flag = (name) => { const i = argv.indexOf('--' + name); if (i < 0) return undefined; const v = argv[i + 1]; argv.splice(i, 2); return v; };
+const kind = flag('kind'), limit = flag('limit');
+const [cmd, ...rest] = argv;
+try {
+ let out;
+ if (cmd === 'overview') out = q.overview();
+ else if (cmd === 'find') out = q.find(rest.join(' '), kind, limit);
+ else if (cmd === 'show') out = q.show(rest[0]);
+ else if (cmd === 'path') out = q.path(rest[0], rest[1]);
+ else { console.log('commands: overview | find "<words>" [--kind module|file|endpoint|symbol] | show <id> | path <fromId> <toId>'); process.exit(cmd ? 1 : 0); }
+ console.log(JSON.stringify(out, null, 1));
+} catch (e) {
+ console.log(JSON.stringify({ error: e.message }));
+ process.exit(1);
+}
diff --git a/skills/floorplan/assets/serve.mjs b/skills/floorplan/assets/serve.mjs
new file mode 100644
index 0000000..1cf9ec7
--- /dev/null
+++ b/skills/floorplan/assets/serve.mjs
@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// floorplan/serve.mjs: serve this map locally and answer questions about the codebase through the
+// Claude Code CLI. Generated by build.mjs; needs only Node 18+ and a logged-in `claude` CLI.
+//
+// usage: node floorplan/serve.mjs [--port 4378] [--model <model>] [--claude <path to claude>] [--no-open] [--idle-exit <minutes>]
+// node floorplan/serve.mjs --stop
+//
+// The server listens on 127.0.0.1 only. Each question runs `claude -p` in the codebase root with
+// read-only tools (Read, Grep, Glob, and Bash limited to floorplan/query.mjs), on your own Claude account.
+// When the map is rebuilt, open tabs reload in place. The running server is recorded in .cache/server.json.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const argv = process.argv.slice(2);
+const opt = (name, dflt) => { const i = argv.indexOf('--' + name); return i < 0 ? dflt : argv[i + 1]; };
+const has = (name) => argv.includes('--' + name);
+const stateFile = path.join(here, '.cache', 'server.json');
+const readState = () => { try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch { return null; } };
+if (has('stop')) {
+ const s = readState();
+ let stopped = false;
+ if (s?.pid) { try { process.kill(s.pid); stopped = true; } catch {} }
+ try { fs.unlinkSync(stateFile); } catch {}
+ console.log(stopped ? `Stopped the map server (${s.url}).` : 'The map server was not running.');
+ process.exit(0);
+}
+const wantPort = Number(opt('port', 4378));
+const idleExit = Number(opt('idle-exit', 0)) * 60000; // stop this long after the last tab closes (0 = never)
+const selfHash = crypto.createHash('sha1').update(fs.readFileSync(fileURLToPath(import.meta.url))).digest('hex').slice(0, 12);
+const model = opt('model', process.env.FLOORPLAN_MODEL || '');
+const token = crypto.randomBytes(16).toString('hex');
+const TYPES = { '.html': 'text/html; charset=utf-8', '.json': 'application/json', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml' };
+
+// ---------- find the Claude Code CLI ----------
+function which(cmd) {
+ try {
+ const out = execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+ return out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+ } catch { return []; }
+}
+/** Returns { cmd, args } to spawn, or null. Handles native installs, npm shims on Windows, and .js entry points. */
+function resolveClaude() {
+ const explicit = opt('claude', process.env.FLOORPLAN_CLAUDE);
+ const candidates = explicit ? [explicit] : [
+ ...which('claude'),
+ path.join(process.env.HOME || process.env.USERPROFILE || '', '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude'),
+ ...(process.platform === 'win32' ? [path.join(process.env.APPDATA || '', 'npm', 'claude.cmd')] : []),
+ ];
+ for (const c of candidates) {
+ if (!c || !fs.existsSync(c)) continue;
+ if (/\.(m?js)$/i.test(c)) return { cmd: process.execPath, args: [c], path: c };
+ if (/\.(cmd|bat|ps1)$/i.test(c) || (process.platform === 'win32' && !path.extname(c))) {
+ // npm shim: run its JS entry point with node directly (spawning .cmd files needs a shell)
+ const cli = path.join(path.dirname(c), 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+ if (fs.existsSync(cli)) return { cmd: process.execPath, args: [cli], path: c };
+ const exe = c.replace(/\.(cmd|bat|ps1)$/i, '.exe');
+ if (fs.existsSync(exe)) return { cmd: exe, args: [], path: exe };
+ continue;
+ }
+ return { cmd: c, args: [], path: c };
+ }
+ return null;
+}
+const claude = resolveClaude();
+let version = null;
+if (claude) { try { version = execFileSync(claude.cmd, [...claude.args, '--version'], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {} }
+
+// The page, the graph, and the instructions and answer schema (from query.mjs's inlined graph-query
+// code). Loaded at start and again whenever the map is rebuilt.
+const inject = `<script>window.FLOORPLAN_SERVER=${JSON.stringify({ token, cli: !!claude, version, model: model || null })};</script>`;
+let page, G, core, MODES;
+function load() {
+ const html = fs.readFileSync(path.join(here, 'index.html'), 'utf8');
+ const g = JSON.parse(fs.readFileSync(path.join(here, 'graph.json'), 'utf8'));
+ const coreSrc = fs.readFileSync(path.join(here, 'query.mjs'), 'utf8').split('// ---- cli ----')[0];
+ const c = new Function(`${coreSrc.replace(/^import .*$/gm, '')}; return { FLOORPLAN_ANSWER_SCHEMA, FLOORPLAN_FLOW_SCHEMA, floorplanAskInstructions, floorplanFlowInstructions, createGraphQuery };`)();
+ c.q = c.createGraphQuery(g);
+ page = html.replace('</head>', inject + '</head>');
+ G = g; core = c;
+ // two kinds of request: a question (answer + board) or a new guided flow
+ MODES = {
+ ask: { instructions: core.floorplanAskInstructions(G, 'cli'), schema: JSON.stringify(core.FLOORPLAN_ANSWER_SCHEMA) },
+ flow: { instructions: core.floorplanFlowInstructions(G, 'cli'), schema: JSON.stringify(core.FLOORPLAN_FLOW_SCHEMA) },
+ };
+}
+load();
+
+// ---------- open tabs: live reload, and idle shutdown ----------
+const tabs = new Set();
+let lastTab = Date.now();
+const broadcast = (event, data = {}) => { for (const t of tabs) t.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); };
+let reloadTimer = null;
+fs.watchFile(path.join(here, 'index.html'), { interval: 1000 }, (cur, prev) => {
+ if (cur.mtimeMs === prev.mtimeMs) return;
+ // build writes several files; wait for it to finish, and keep serving the old map if the new one is half-written
+ clearTimeout(reloadTimer);
+ reloadTimer = setTimeout(() => { try { load(); broadcast('reload'); console.log('map rebuilt: reloaded open tabs'); } catch {} }, 800);
+});
+if (idleExit) setInterval(() => { if (!tabs.size && !running.size && Date.now() - lastTab > idleExit) process.exit(0); }, 60000).unref();
+const flowsFile = path.join(here, 'custom-flows.json');
+const readFlows = () => { try { return JSON.parse(fs.readFileSync(flowsFile, 'utf8')).flows || []; } catch { return []; } };
+
+// ---------- asking ----------
+const nameFor = (id) => { try { return core.q.brief(id)?.name || id; } catch { return id; } };
+const running = new Map();
+function describeTool(name, input = {}) {
+ const rel = (p) => String(p || '').replace(/\\/g, '/').replace(root.replace(/\\/g, '/') + '/', '');
+ if (name === 'Bash') {
+ // Claude often chains several lookups in one command; describe each one, by name
+ const parts = String(input.command || '').split(/\s*(?:&&|;|\|\|)\s*/).map((c) => /query\.mjs\s+(\w+)\s*(.*)$/.exec(c)).filter(Boolean);
+ if (!parts.length) return 'Running a command';
+ const one = ([, cmd, rest]) => {
+ const a = rest.replace(/--\w+\s+\S+/g, '').replace(/["']/g, '').trim();
+ return { overview: 'Reading the map overview', find: `Searching the map for "${a}"`, show: `Looking at ${a.split(/\s+/).map(nameFor).join(', ')}`, path: `Tracing a path ${a.split(/\s+/).map(nameFor).join(' → ')}` }[cmd] || 'Querying the map';
+ };
+ return parts.slice(0, 2).map(one).join(' · ') + (parts.length > 2 ? ` (+${parts.length - 2} more)` : '');
+ }
+ if (name === 'Read') return `Reading ${rel(input.file_path)}`;
+ if (name === 'Grep') return `Searching code for "${input.pattern}"`;
+ if (name === 'Glob') return `Listing ${input.pattern}`;
+ return name;
+}
+function parseAnswer(ev) {
+ if (ev.structured_output && typeof ev.structured_output === 'object') return ev.structured_output;
+ const t = String(ev.result || '');
+ const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(t);
+ for (const cand of [t, fence?.[1], t.slice(t.indexOf('{'), t.lastIndexOf('}') + 1)]) { try { const v = JSON.parse(cand); if (v && typeof v === 'object') return v; } catch {} }
+ return { title: 'Answer', answer: t, items: [] };
+}
+function ask(req, res, body) {
+ res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+ const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+ if (!claude) { send('failure', { code: 'cli_missing', message: 'Claude Code CLI not found.' }); return res.end(); }
+ const mode = MODES[body.mode] || MODES.ask;
+ const args = [...claude.args, '-p', '--output-format', 'stream-json', '--verbose',
+ '--json-schema', mode.schema, '--append-system-prompt', mode.instructions,
+ '--tools', 'Read,Grep,Glob,Bash', '--allowedTools', 'Bash(node floorplan/query.mjs:*)', 'Read', 'Grep', 'Glob'];
+ if (body.session) args.push('--resume', String(body.session));
+ if (model) args.push('--model', model);
+ // Started from inside a Claude Code session? Don't let the child think it's nested in it.
+ const env = { ...process.env };
+ for (const k of Object.keys(env)) if (/^CLAUDE_?CODE_(SESSION|ENTRYPOINT|CHILD|MESSAGING|HOST|SDK)|^CLAUDECODE$/.test(k)) delete env[k];
+ const child = spawn(claude.cmd, args, { cwd: root, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+ const id = crypto.randomBytes(6).toString('hex');
+ running.set(id, child);
+ send('start', { id });
+ child.stdin.end(String(body.question || '').slice(0, 4000));
+ let buf = '', stderr = '', done = false;
+ child.stdout.on('data', (d) => {
+ buf += d;
+ let nl;
+ while ((nl = buf.indexOf('\n')) >= 0) {
+ const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
+ if (!line) continue;
+ let ev; try { ev = JSON.parse(line); } catch { continue; }
+ if (ev.type === 'assistant') for (const c of ev.message?.content || []) if (c.type === 'tool_use') send('progress', { text: describeTool(c.name, c.input) });
+ if (ev.type === 'result') {
+ done = true;
+ if (ev.is_error) {
+ const msg = String(ev.result || ev.subtype || 'Claude Code reported an error');
+ send('failure', { code: /not logged in|\/login|authenticat/i.test(msg) ? 'not_logged_in' : 'cli_error', message: msg });
+ } else send('answer', { ...parseAnswer(ev), session: ev.session_id });
+ }
+ }
+ });
+ child.stderr.on('data', (d) => { stderr = (stderr + d).slice(-2000); });
+ child.on('error', (e) => { if (!done) { done = true; send('failure', { code: 'cli_error', message: e.message }); } res.end(); });
+ child.on('close', (code) => {
+ running.delete(id);
+ if (!done) send('failure', { code: /not logged in|\/login/i.test(stderr) ? 'not_logged_in' : 'cli_error', message: stderr.trim() || `claude exited with code ${code}` });
+ res.end();
+ });
+ // the browser went away (closed tab, Stop): don't leave Claude working. Note req 'close' fires as soon as
+ // the body is read, so watch the response instead.
+ res.on('close', () => { if (!done) child.kill(); });
+}
+
+// ---------- http ----------
+const server = http.createServer((req, res) => {
+ const url = new URL(req.url, `http://${req.headers.host}`);
+ const sameOrigin = !req.headers.origin || req.headers.origin === `http://${req.headers.host}`;
+ if (url.pathname.startsWith('/api/')) {
+ // EventSource can't send headers, so the events stream takes the token in the query string
+ const given = req.headers['x-floorplan-token'] || (url.pathname === '/api/events' ? url.searchParams.get('token') : null);
+ if (!sameOrigin || given !== token) { res.writeHead(403); return res.end(); }
+ if (req.method === 'GET' && url.pathname === '/api/events') {
+ res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+ res.write('retry: 1000\n\n'); // reconnect quickly after a restart
+ tabs.add(res);
+ req.on('close', () => { tabs.delete(res); lastTab = Date.now(); });
+ return;
+ }
+ if (req.method === 'GET' && url.pathname === '/api/status') { res.writeHead(200, { 'Content-Type': 'application/json' }); return res.end(JSON.stringify({ tabs: tabs.size, pid: process.pid, hash: selfHash, root })); }
+ if (req.method === 'GET' && url.pathname === '/api/health') { res.writeHead(200, { 'Content-Type': 'application/json' }); return res.end(JSON.stringify({ cli: !!claude, version, path: claude?.path || null })); }
+ // requested flows are saved next to the map; build.mjs folds them into graph.json
+ if (url.pathname === '/api/flows') {
+ if (req.method === 'GET') { res.writeHead(200, { 'Content-Type': 'application/json' }); return res.end(JSON.stringify({ flows: readFlows() })); }
+ if (req.method === 'POST' || req.method === 'DELETE') {
+ let raw = '';
+ req.on('data', (d) => { raw += d; if (raw.length > 50000) req.destroy(); });
+ req.on('end', () => {
+ let body = {}; try { body = JSON.parse(raw); } catch {}
+ let flows = readFlows().filter((x) => x.id !== body.id && x.id !== body.flow?.id);
+ if (req.method === 'POST' && body.flow?.id && Array.isArray(body.flow.steps)) flows.push({ ...body.flow, createdAt: new Date().toISOString() });
+ fs.writeFileSync(flowsFile, JSON.stringify({ flows }, null, 2) + '\n');
+ res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ flows }));
+ });
+ return;
+ }
+ }
+ if (req.method === 'POST' && url.pathname === '/api/cancel') { for (const c of running.values()) c.kill(); res.writeHead(204); return res.end(); }
+ if (req.method === 'POST' && url.pathname === '/api/ask') {
+ let raw = '';
+ req.on('data', (d) => { raw += d; if (raw.length > 20000) req.destroy(); });
+ req.on('end', () => { let body = {}; try { body = JSON.parse(raw); } catch {} ask(req, res, body); });
+ return;
+ }
+ res.writeHead(404); return res.end();
+ }
+ if (url.pathname === '/' || url.pathname === '/index.html') { res.writeHead(200, { 'Content-Type': TYPES['.html'], 'Cache-Control': 'no-store' }); return res.end(page); }
+ const file = path.join(here, decodeURIComponent(url.pathname));
+ if (!file.startsWith(here) || !fs.existsSync(file) || !fs.statSync(file).isFile()) { res.writeHead(404); return res.end('not found'); }
+ res.writeHead(200, { 'Content-Type': TYPES[path.extname(file)] || 'application/octet-stream' });
+ fs.createReadStream(file).pipe(res);
+});
+// another map (or anything else) on the port: take the next free one
+let port = wantPort;
+server.on('error', (e) => {
+ if (e.code === 'EADDRINUSE' && port < wantPort + 20) { port++; server.listen(port, '127.0.0.1'); return; }
+ console.error(`✗ Couldn't start the map server: ${e.message}`);
+ process.exit(1);
+});
+server.listen(port, '127.0.0.1');
+server.on('listening', () => {
+ const u = `http://127.0.0.1:${port}`;
+ try {
+ fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+ fs.writeFileSync(stateFile, JSON.stringify({ pid: process.pid, port, url: u, token, hash: selfHash, startedAt: new Date().toISOString() }, null, 2));
+ } catch {}
+ const forget = () => { try { if (readState()?.pid === process.pid) fs.unlinkSync(stateFile); } catch {} };
+ process.on('exit', forget);
+ for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => process.exit(0));
+ console.log(`Floorplan: ${u}`);
+ console.log(claude ? `asking via Claude Code CLI ${version || ''} (${claude.path})${model ? `, model ${model}` : ''}` : 'Claude Code CLI not found: the map works, but asking questions needs it (https://docs.claude.com/en/docs/claude-code). Pass --claude <path> if it is installed somewhere unusual.');
+ if (!has('no-open')) {
+ const opener = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', u]] : process.platform === 'darwin' ? ['open', [u]] : ['xdg-open', [u]];
+ try { spawn(opener[0], opener[1], { stdio: 'ignore', detached: true }).unref(); } catch {}
+ }
+});
diff --git a/skills/floorplan/assets/ui/10-glossary.js b/skills/floorplan/assets/ui/10-glossary.js
new file mode 100644
index 0000000..6026c5f
--- /dev/null
+++ b/skills/floorplan/assets/ui/10-glossary.js
@@ -0,0 +1,194 @@
+// floorplan glossary: explains the technical words a non-developer meets on the map.
+// The first time a known term appears in a description (details panel, board title area), it gets a
+// dotted underline; hovering or focusing it shows a one-sentence explanation. Off while
+// "Show technical detail" is on. Talks to the viewer only through window.Floorplan.
+(() => {
+ const SC = window.Floorplan;
+ if (!SC) return;
+
+ // [display name, plain explanation, aliases...]. Aliases are matched as whole words, ignoring case,
+ // except those marked with a leading "=" (matched exactly, so "REST" doesn't fire on "the rest").
+ const TERMS = [
+ ['API', 'The way programs talk to each other: one asks for something (prices, an order) and the other answers.', 'API', 'APIs', 'API client'],
+ ['Endpoint', 'One specific request the app can receive, like "mark this order shipped"; each has its own web address.', 'endpoint', 'endpoints'],
+ ['Webhook', 'A message another service sends your app automatically when something happens there, like "a payment went through".', 'webhook', 'webhooks'],
+ ['Server', 'A computer in the cloud that runs your app\'s behind-the-scenes work and answers requests from the screens.', 'server', 'servers', 'main server'],
+ ['Frontend', 'The part of the app people see and click: the screens, buttons and forms in the browser.', 'frontend', 'front end', 'front-end'],
+ ['Backend', 'The behind-the-scenes part of the app that stores the records, applies the rules and talks to other services.', 'backend', 'back end', 'back-end'],
+ ['Database', 'Where the app keeps its records (products, orders, customers) so nothing is lost when it restarts.', 'database', 'databases', 'DB'],
+ ['Record', 'One saved entry in the database, like a single order or customer; a table is the list of all records of one kind.', 'database record', 'database records', 'database table', 'database tables'],
+ ['Model', 'In code, a model describes how one kind of record (an order, a customer) is stored in the database.', 'model', 'models', 'ORM', 'ORM model', 'ORM models', 'data model'],
+ ['Query', 'A question the app asks the database, like "all orders from today that haven\'t shipped".', 'query', 'queries'],
+ ['Queue', 'A waiting line of tasks; work is dropped in and handled one by one in the background so nothing gets lost.', 'queue', 'queues', 'queued', 'outbox', 'message queue'],
+ ['Background job', 'A task that runs on its own behind the scenes, so people don\'t have to wait for it on screen.', 'background job', 'background jobs', 'background task', 'background tasks', 'worker', 'workers'],
+ ['Scheduled job', 'A task that runs automatically on a timetable, like every hour or every night.', 'cron', 'cron job', 'cron jobs', 'scheduled job', 'scheduled jobs', 'scheduler'],
+ ['Environment variable', 'A setting stored outside the code, such as which database or account to use, so it can differ between test and live.', 'environment variable', 'environment variables', 'env var', 'env vars', '.env'],
+ ['Secret', 'A password or key the app uses to sign in to another service; it must never be shared or put in the code.', 'secret', 'secrets', 'API key', 'API keys', 'credentials'],
+ ['Deploy', 'Putting a new version of the app live so people start using it.', 'deploy', 'deploys', 'deployed', 'deployment', 'deployments'],
+ ['Migration', 'A one-time change to how records are stored, like adding a new field to every order.', 'migration', 'migrations'],
+ ['Cache', 'A saved copy of something kept close by so it loads faster instead of being worked out again.', 'cache', 'cached', 'caching'],
+ ['Sign-in', 'Checking who someone is (usually with a password) before letting them in.', 'auth', 'authentication', 'login', 'log in', 'sign-in', 'sign in'],
+ ['Permissions', 'The rules for who is allowed to do what, like only managers issuing refunds.', 'permissions', 'authorization', 'roles', 'RBAC'],
+ ['Session', 'How the app remembers you are signed in, so you don\'t have to type your password on every screen.', 'session', 'sessions'],
+ ['Token', 'A temporary digital pass the app hands out after sign-in and checks on every request.', 'token', 'tokens', 'bearer token', 'access token'],
+ ['SDK', 'A ready-made kit of code a company provides so apps can talk to its service more easily.', 'SDK', 'SDKs'],
+ ['Repository', 'The folder that holds all of a project\'s code and its full history of changes.', 'repository', 'repositories', 'repo', 'repos'],
+ ['Component', 'A reusable building block of the screens, like a button, a table or a whole product editor.', 'component', 'components'],
+ ['Route', 'A web address the app answers: on the screens it\'s a page, on the server it\'s a kind of request.', 'route', 'routes', 'routing', 'App Router'],
+ ['Request', 'A message asking the server to do or fetch something; the server sends back a response with the result.', 'request', 'requests', 'response', 'responses'],
+ ['JSON', 'A simple text format programs use to send data to each other, like a labelled list.', 'JSON'],
+ ['REST', 'A common style for building APIs, where each web address stands for a kind of thing (orders, products).', '=REST', '=RESTful'],
+ ['HTTP method', 'The kind of request: GET reads something, POST creates, PUT or PATCH changes, DELETE removes.', 'HTTP method', 'HTTP methods', '=GET', '=POST', '=PUT', '=PATCH', '=DELETE'],
+ ['HTTP', 'The language browsers and servers use to talk over the web; HTTPS is the encrypted version.', 'HTTP', 'HTTPS'],
+ ['CDN', 'A network of servers around the world that delivers images and files quickly from somewhere near the visitor.', 'CDN', 'CDNs'],
+ ['Storage bucket', 'Cloud file storage for things like product images, uploads and exports.', 'storage bucket', 'bucket', 'buckets', 'S3', 'GCS', 'Cloud Storage'],
+ ['Pub/Sub', 'Google\'s message service: one part of the app posts an event and others pick it up to handle in the background.', 'Pub/Sub', 'PubSub'],
+ ['MCP', 'A standard way to connect AI assistants (like Claude or ChatGPT) to an app so they can look things up in it.', 'MCP', 'MCP server', 'Model Context Protocol'],
+ ['Next.js', 'A popular toolkit for building websites and web apps with React.', 'Next.js', 'NextJS'],
+ ['React', 'A popular library for building interactive screens out of reusable pieces.', '=React'],
+ ['Flask', 'A Python toolkit for building web servers.', 'Flask'],
+ ['SQLAlchemy', 'A Python toolkit that lets the code read and save database records without writing raw database commands.', 'SQLAlchemy'],
+ ['Postgres', 'A widely used database; RDS and Cloud SQL are Amazon\'s and Google\'s hosted versions of it.', 'Postgres', 'PostgreSQL', 'RDS', 'Cloud SQL'],
+ ['Docker', 'A way to package an app with everything it needs so it runs the same on any computer or cloud.', 'Docker', 'container', 'containers'],
+ ['Cloud Run', 'Google\'s service for running an app\'s servers and background jobs in the cloud without managing machines.', 'Cloud Run'],
+ ['Middleware', 'A check every request passes through on its way in, such as "is this person signed in?".', 'middleware'],
+ ['Blueprint', 'In Flask, a group of related requests bundled together, like all the order requests.', 'blueprint', 'blueprints'],
+ ['Tests', 'Automatic checks that the code still does what it should, run before changes go live.', 'test suite', 'unit test', 'unit tests', 'pytest', 'Vitest'],
+ ['Script', 'A small program run by hand for a one-off job, like fixing or importing data.', 'script', 'scripts'],
+ ['OAuth', 'The standard behind "Sign in with…" buttons: it lets one app use another on your behalf without sharing your password.', 'OAuth'],
+ ];
+
+ const exact = new Map(), loose = new Map(), alts = [];
+ TERMS.forEach(([name, text, ...aliases], i) => {
+ for (let a of aliases) {
+ const strict = a.startsWith('=');
+ if (strict) a = a.slice(1);
+ (strict ? exact : loose).set(strict ? a : a.toLowerCase(), i);
+ alts.push(a);
+ }
+ });
+ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ alts.sort((a, b) => b.length - a.length);
+ const RE = new RegExp(`(?<![\\w./-])(?:${alts.map(esc).join('|')})(?![\\w/]|-\\w|\\.\\w)`, 'gi');
+ const termOf = (m) => exact.has(m) ? exact.get(m) : loose.has(m.toLowerCase()) ? loose.get(m.toLowerCase()) : -1;
+
+ // Where to look, and what to leave alone.
+ const TARGETS = '.pd, .rd, .callout';
+ const SKIP = 'a[href], button, code, pre, kbd, samp, input, textarea, select, [contenteditable], .tag, .rp, .pp, .method, .kbd, .sc-term, [data-noglossary]';
+ const CLICKABLE = 'a, [data-go], [data-sel], [data-flow], [data-open], [role="button"]';
+ const isMono = (el) => /mono|monospace/i.test(el.style?.fontFamily || '');
+
+ function annotate(scope, targets) {
+ if (!scope || SC.technical()) return;
+ const used = new Set([...scope.querySelectorAll('.sc-term')].map((s) => +s.dataset.term)); // max one per term per scope
+ const skipped = (from, stop) => { for (let p = from; p && p !== stop; p = p.parentElement) if (p.matches(SKIP) || isMono(p)) return true; return false; };
+ for (const el of targets) {
+ if (skipped(el, scope)) continue;
+ const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, {
+ acceptNode: (t) => !t.nodeValue.trim() || skipped(t.parentElement, el) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+ });
+ const texts = [];
+ while (walker.nextNode()) texts.push(walker.currentNode);
+ for (const t of texts) wrapIn(t, used);
+ }
+ }
+ function wrapIn(textNode, used) {
+ let node = textNode;
+ while (node) {
+ RE.lastIndex = 0;
+ let m, hit = null;
+ while ((m = RE.exec(node.nodeValue))) {
+ const i = termOf(m[0]);
+ if (i >= 0 && !used.has(i)) { hit = { m, i }; break; }
+ }
+ if (!hit) return;
+ used.add(hit.i);
+ const word = node.splitText(hit.m.index);
+ const rest = word.splitText(hit.m[0].length);
+ const span = document.createElement('span');
+ span.className = 'sc-term';
+ span.dataset.term = String(hit.i);
+ if (!word.parentElement.closest(CLICKABLE)) span.tabIndex = 0; // inside clickable rows: hover only, clicks pass through
+ word.replaceWith(span);
+ span.appendChild(word);
+ node = rest;
+ }
+ }
+ function strip(scope) {
+ if (!scope) return;
+ for (const s of scope.querySelectorAll('.sc-term')) s.replaceWith(...s.childNodes);
+ scope.normalize();
+ }
+
+ const panelEl = () => document.getElementById('panel');
+ const contextEl = () => document.getElementById('context');
+ const doPanel = () => { const p = panelEl(); if (p) annotate(p, p.querySelectorAll(TARGETS)); };
+ const doContext = () => { const c = contextEl(); if (c) annotate(c, c.querySelectorAll('p, .callout')); };
+
+ // Run after the viewer and any other extension listeners have finished filling the DOM.
+ SC.on('panel', () => { hide(true); queueMicrotask(doPanel); });
+ SC.on('render', () => { hide(true); queueMicrotask(doContext); });
+ SC.on('technical', (on) => {
+ hide(true);
+ if (on) { strip(panelEl()); strip(contextEl()); }
+ else { queueMicrotask(() => { strip(panelEl()); strip(contextEl()); doPanel(); doContext(); }); }
+ });
+
+ // ---------- popover ----------
+ const style = document.createElement('style');
+ style.textContent = `
+.sc-term { pointer-events: auto; cursor: help; border-radius: 4px; text-decoration-line: underline; text-decoration-style: dotted; text-decoration-thickness: 1px; text-underline-offset: 3px;
+ text-decoration-color: rgba(255, 255, 255, .32); text-decoration-color: color-mix(in srgb, currentColor 45%, transparent); transition: text-decoration-color .2s var(--ease), color .2s var(--ease); }
+.sc-term:hover, .sc-term.on { text-decoration-color: currentColor; color: var(--text); }
+.callout .sc-term:hover, .callout .sc-term.on { color: inherit; }
+.sc-term:focus { outline: none; }
+.sc-term:focus-visible { box-shadow: 0 0 0 2px var(--focus); }
+#sc-gloss { position: fixed; left: 0; top: 0; z-index: 55; max-width: 280px; padding: 11px 13px; border-radius: 14px; font-size: 12.5px; line-height: 1.5; color: var(--text-2);
+ pointer-events: none; opacity: 0; transform: translateY(3px); transition: opacity .15s var(--ease), transform .25s var(--ease); }
+#sc-gloss.on { opacity: 1; transform: none; }
+#sc-gloss b { display: block; color: var(--text); font-weight: 600; margin-bottom: 2px; }`;
+ document.head.appendChild(style);
+
+ const pop = document.createElement('div');
+ pop.id = 'sc-gloss';
+ pop.className = 'glass';
+ pop.setAttribute('role', 'tooltip');
+ document.body.appendChild(pop);
+
+ let current = null, showT = 0, hideT = 0;
+ function show(el) {
+ clearTimeout(hideT);
+ if (current === el) return;
+ const term = TERMS[+el.dataset.term];
+ if (!term) return;
+ current?.classList.remove('on'); current?.removeAttribute('aria-describedby');
+ current = el;
+ el.classList.add('on');
+ el.setAttribute('aria-describedby', 'sc-gloss');
+ pop.innerHTML = `<b>${SC.h(term[0])}</b>${SC.h(term[1])}`;
+ const r = el.getClientRects()[0] || el.getBoundingClientRect();
+ const pw = pop.offsetWidth, ph = pop.offsetHeight, gap = 8;
+ const x = Math.max(12, Math.min(r.left, innerWidth - pw - 12));
+ const below = r.bottom + gap + ph <= innerHeight - 12;
+ const y = below ? r.bottom + gap : Math.max(12, r.top - gap - ph);
+ pop.style.left = `${Math.round(x)}px`;
+ pop.style.top = `${Math.round(y)}px`;
+ pop.classList.add('on');
+ }
+ function hide(now) {
+ clearTimeout(showT); clearTimeout(hideT);
+ const go = () => { pop.classList.remove('on'); current?.classList.remove('on'); current?.removeAttribute('aria-describedby'); current = null; };
+ if (now === true) go(); else hideT = setTimeout(go, 90);
+ }
+ const termAt = (ev) => ev.target instanceof Element ? ev.target.closest('.sc-term') : null;
+ document.addEventListener('mouseover', (ev) => { const t = termAt(ev); if (!t) return; clearTimeout(showT); showT = setTimeout(() => show(t), current ? 0 : 140); });
+ document.addEventListener('mouseout', (ev) => { const t = termAt(ev); if (t && !t.contains(ev.relatedTarget)) { clearTimeout(showT); hide(); } });
+ document.addEventListener('focusin', (ev) => { const t = termAt(ev); if (t) show(t); });
+ document.addEventListener('focusout', (ev) => { if (termAt(ev)) hide(); });
+ document.addEventListener('keydown', (ev) => { if (ev.key === 'Escape' && current) hide(true); });
+ document.addEventListener('scroll', () => { if (current) hide(true); }, true);
+ addEventListener('resize', () => { if (current) hide(true); });
+
+ // initial pass, in case the first render/panel happened before this script ran
+ if (document.readyState !== 'loading') queueMicrotask(() => { doPanel(); doContext(); });
+})();
diff --git a/skills/floorplan/assets/ui/20-health.js b/skills/floorplan/assets/ui/20-health.js
new file mode 100644
index 0000000..609c96a
--- /dev/null
+++ b/skills/floorplan/assets/ui/20-health.js
@@ -0,0 +1,147 @@
+// Health check panel: plain-language warnings from graph.health (lib/health.mjs) — leaked keys,
+// endpoints anyone can call, unused and oversized files — each with "Show on map" and a ready
+// prompt to paste into Claude Code. Talks to the viewer only through window.Floorplan.
+(() => {
+ const SC = window.Floorplan;
+ if (!SC) return;
+ const { h } = SC;
+ const issues = (SC.graph.health && SC.graph.health.issues) || [];
+
+ const SEV = {
+ high: { color: '#f28b8b', group: 'Fix these first', word: 'important' },
+ medium: { color: '#f0c36b', group: 'Worth fixing soon', word: 'worth fixing' },
+ low: { color: '#8b8b8b', group: 'Good to tidy up', word: 'minor' },
+ };
+ const ORDER = ['high', 'medium', 'low'];
+ const count = (sev) => issues.filter((i) => i.severity === sev).length;
+ const urgent = count('high') + count('medium');
+
+ SC.icons.health = '<path d="M3 12h4l2.5-6 4 12 2.5-6H21"/>';
+ SC.icons.check = '<path d="m5 12.5 4.5 4.5L19 7.5"/>';
+
+ const style = document.createElement('style');
+ style.textContent = `
+ .hc-issue { padding: 12px 14px; border-radius: 16px; background: rgba(255, 255, 255, .04); margin-bottom: 8px; }
+ .hc-issue:last-child { margin-bottom: 0; }
+ .hc-t { display: flex; gap: 9px; align-items: flex-start; font-weight: 500; line-height: 1.4; }
+ .hc-t .dot { margin-top: 6px; }
+ .hc-d { color: var(--text-2); font-size: 12.5px; line-height: 1.55; margin: 6px 0 0 17px; }
+ .hc-n { color: var(--text-3); font-size: 12.5px; line-height: 1.45; margin: 4px 0 0 17px; }
+ .hc-w { font-family: var(--mono); font-size: 11px; color: var(--text-3); margin: 6px 0 0 17px; word-break: break-all; line-height: 1.5; }
+ .hc-a { display: flex; gap: 6px; flex-wrap: wrap; margin: 10px 0 0 17px; }
+ .hc-a .btn { height: 30px; padding: 0 12px; font-size: 12.5px; gap: 6px; }
+ .hc-a .btn svg.i { width: 14px; height: 14px; }
+ .hc-calm { margin-top: 14px; padding: 11px 13px; border-radius: 14px; background: rgba(111, 215, 168, .08); color: #a9e5c9; font-size: 13px; line-height: 1.55; }
+ .hc-sub { display: flex; flex-wrap: wrap; gap: 4px 14px; margin-top: 12px; font-size: 12px; color: var(--text-2); }
+ .hc-sub span { display: inline-flex; align-items: center; gap: 6px; }
+ #btn-health .badge { background: var(--hc-badge, #ececec); }
+ #btn-health.calm svg.i { color: #6fd7a8; }
+ #modal .hc-hint { margin: 0; }
+ #modal .hc-hint b { color: var(--text); font-weight: 500; }
+ `;
+ document.head.appendChild(style);
+
+ // ---------- actions ----------
+ let isOpen = false, openedAt = null;
+ const where = () => JSON.stringify([SC.state.selected, SC.state.container]);
+ function closeList() { isOpen = false; SC.closePanel(); }
+ function showOnMap(issue) {
+ const items = (issue.items || []).filter((id) => SC.exists(id)).map((id) => ({ id, note: (issue.notes && issue.notes[id]) || '' }));
+ if (!items.length) { SC.toast('This one isn’t on the map. Use “Fix with Claude” instead.'); return; }
+ if (isOpen) closeList();
+ SC.showBoard({ title: issue.title, question: issue.detail, items });
+ }
+ function fixWithClaude(issue) {
+ SC.modal({
+ title: 'Fix with Claude',
+ html: `<p class="hc-hint">Copy this request and paste it into <b>Claude Code</b>, opened in your project folder. It explains what to change and asks before anything risky.</p><pre>${h(issue.fix)}</pre>`,
+ actions: [{ label: 'Copy prompt', primary: true, icon: 'copy', onClick: () => { SC.copy(issue.fix); SC.toast('Copied. Paste it into Claude Code.'); } }],
+ });
+ }
+ const onMap = (issue) => (issue.items || []).some((id) => SC.exists(id));
+
+ // ---------- html ----------
+ const locText = (issue) => {
+ const locs = issue.locations || [];
+ if (!SC.technical() || !locs.length) return '';
+ const shown = locs.slice(0, 3).map((l) => `${l.file}${l.line > 1 ? ':' + l.line : ''}`);
+ return `<div class="hc-w">${shown.map(h).join('<br>')}${locs.length > 3 ? `<br>+${locs.length - 3} more` : ''}</div>`;
+ };
+ const issueHtml = (issue, idx, note) => `<div class="hc-issue">
+ <div class="hc-t"><span class="dot" style="background:${SEV[issue.severity].color}"></span><span>${h(issue.title)}</span></div>
+ ${note ? `<div class="hc-n">${h(note)}</div>` : `<div class="hc-d">${h(issue.detail)}</div>`}
+ ${locText(issue)}
+ <div class="hc-a">
+ ${onMap(issue) ? `<button class="btn soft" data-hc-show="${idx}">${SC.iconI('search')}Show on map</button>` : ''}
+ <button class="btn soft" data-hc-fix="${idx}">${SC.iconI('spark')}Fix with Claude</button>
+ </div>
+ </div>`;
+ const bindIssues = (el) => {
+ el.querySelectorAll('[data-hc-show]').forEach((b) => b.addEventListener('click', (ev) => { ev.stopPropagation(); showOnMap(issues[+b.dataset.hcShow]); }));
+ el.querySelectorAll('[data-hc-fix]').forEach((b) => b.addEventListener('click', (ev) => { ev.stopPropagation(); fixWithClaude(issues[+b.dataset.hcFix]); }));
+ };
+ const headline = () => urgent ? `${SC.plural(urgent, 'thing')} need${urgent === 1 ? 's' : ''} attention` : issues.length ? 'Nothing urgent' : 'No problems found';
+ const breakdown = () => `<div class="hc-sub">${ORDER.filter(count).map((s) => `<span><i class="dot" style="background:${SEV[s].color}"></i>${count(s)} ${SEV[s].word}</span>`).join('')}</div>`;
+
+ function listHtml() {
+ const top = `<div class="sec">
+ <div class="ph"><span class="ico" style="--c:${urgent ? SEV[count('high') ? 'high' : 'medium'].color : '#6fd7a8'}">${SC.icon('health')}</span><span class="kindlabel">Health check</span></div>
+ <h2 class="pt">${h(headline())}</h2>
+ <p class="pd">We looked for passwords and keys left in the code, parts of your app anyone on the internet can use, leftover files and files too big to edit safely.</p>
+ ${issues.length ? breakdown() : `<div class="hc-calm">Nothing stood out. This is a quick automatic check, not a full security review.</div>`}
+ <div class="actions"><button class="btn soft" data-hc-back>${SC.iconI('left')}Back</button></div>
+ </div>`;
+ const groups = ORDER.map((sev) => {
+ const list = issues.map((i, idx) => [i, idx]).filter(([i]) => i.severity === sev);
+ return list.length ? `<div class="sec"><h3>${h(SEV[sev].group)} <span class="c">${list.length}</span></h3>${list.map(([i, idx]) => issueHtml(i, idx)).join('')}</div>` : '';
+ }).join('');
+ const foot = issues.length ? `<div class="sec" style="color:var(--text-3);font-size:12px;line-height:1.6">These are automatic hints. “Fix with Claude” gives you a request to paste into Claude Code; it checks the code before changing anything.</div>` : '';
+ return top + groups + foot;
+ }
+ function openList() {
+ isOpen = true;
+ openedAt = where();
+ SC.showPanel(listHtml(), (panel) => {
+ panel.querySelector('[data-hc-back]')?.addEventListener('click', closeList);
+ bindIssues(panel);
+ });
+ }
+
+ // ---------- chrome ----------
+ const btn = SC.addHeaderButton({
+ id: 'btn-health', label: 'Health', icon: urgent ? 'health' : 'check',
+ title: urgent ? `Health check: ${headline()}` : 'Health check: nothing urgent',
+ onClick: () => (isOpen ? closeList() : openList()),
+ });
+ if (urgent) {
+ const b = document.createElement('span');
+ b.className = 'badge';
+ b.textContent = urgent > 99 ? '99+' : String(urgent);
+ btn.style.setProperty('--hc-badge', count('high') ? SEV.high.color : SEV.medium.color);
+ btn.appendChild(b);
+ } else btn.classList.add('calm');
+
+ // Selecting something else on the map while the list is open shows that item instead.
+ SC.on('panel', () => { if (isOpen && openedAt && where() !== openedAt) { isOpen = false; SC.closePanel(); } });
+
+ SC.addPanelSection('overview', () => ({
+ html: `<div class="sec"><h3>Health</h3><div class="list"><a class="row" data-hc-open>
+ <span class="dot" style="background:${urgent ? SEV[count('high') ? 'high' : 'medium'].color : '#6fd7a8'}"></span>
+ <span class="rt"><div class="rn">${h(headline())}</div><div class="rd">${issues.length ? ORDER.filter(count).map((s) => `${count(s)} ${SEV[s].word}`).join(' · ') : 'Quick automatic check of secrets, open endpoints and leftover files'}</div></span>
+ <span class="rc">${SC.iconI('right')}</span></a></div></div>`,
+ bind: (el) => el.querySelector('[data-hc-open]')?.addEventListener('click', (ev) => { ev.preventDefault(); openList(); }),
+ }));
+
+ SC.addPanelSection('item', (itemId) => {
+ if (!itemId || typeof itemId !== 'string' || !issues.length) return '';
+ const hits = [];
+ issues.forEach((issue, idx) => {
+ const inside = (issue.items || []).filter((id) => id === itemId || (SC.exists(id) && SC.chain(id).includes(itemId)));
+ if (!inside.length) return;
+ const exact = issue.notes && inside.includes(itemId) ? issue.notes[itemId] : '';
+ hits.push(issueHtml(issue, idx, exact || (inside.length > 1 || inside[0] !== itemId ? `Affects ${SC.plural(inside.length, 'place')} in here` : '')));
+ });
+ if (!hits.length) return '';
+ return { html: `<div class="sec"><h3>Health <span class="c">${hits.length}</span></h3>${hits.slice(0, 6).join('')}${hits.length > 6 ? `<div class="more" data-hc-open style="cursor:pointer">+${hits.length - 6} more in the health check</div>` : ''}</div>`, bind: (el) => { bindIssues(el); el.querySelector('[data-hc-open]')?.addEventListener('click', openList); } };
+ });
+})();
diff --git a/skills/floorplan/assets/ui/25-recent.js b/skills/floorplan/assets/ui/25-recent.js
new file mode 100644
index 0000000..02cb769
--- /dev/null
+++ b/skills/floorplan/assets/ui/25-recent.js
@@ -0,0 +1,89 @@
+// Recent work: what Claude just changed (graph.recent, from floorplan/recent-work.json), framed against
+// what the user asked for. Cards carry the green tag and hover note (core viewer); this adds the header
+// button that lays the changed cards out on one board, and the panel sections. Talks to the viewer only
+// through window.Floorplan.
+(() => {
+ const SC = window.Floorplan;
+ const R = SC && SC.graph.recent;
+ if (!R || !R.items || !R.items.length) return;
+ const { h } = SC;
+ const tasks = R.tasks || [];
+ const items = R.items.filter((it) => SC.exists(it.id));
+ if (!items.length) return;
+
+ SC.icons.recent = '<path d="M12 3v3M12 18v3M3 12h3M18 12h3M5.6 5.6l2.1 2.1M16.3 16.3l2.1 2.1M5.6 18.4l2.1-2.1M16.3 7.7l2.1-2.1"/>';
+
+ const style = document.createElement('style');
+ style.textContent = `
+ #btn-recent svg.i { color: var(--recent); }
+ #btn-recent .badge { background: var(--recent); color: #0b1f12; }
+ .rw-task { padding: 12px 14px; border-radius: 16px; background: color-mix(in srgb, var(--recent) 6%, transparent); margin-bottom: 8px; }
+ .rw-task:last-child { margin-bottom: 0; }
+ .rw-tt { display: flex; gap: 9px; align-items: center; font-weight: 600; line-height: 1.4; }
+ .rw-tt::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: var(--recent); flex: none; }
+ .rw-q { color: var(--text-3); font-size: 12.5px; line-height: 1.5; margin: 6px 0 0 16px; }
+ .rw-q b { color: var(--text-2); font-weight: 500; }
+ .rw-s { color: var(--text-2); font-size: 12.5px; line-height: 1.55; margin: 6px 0 0 16px; }
+ .rw-a { display: flex; gap: 6px; margin: 10px 0 0 16px; }
+ .rw-a .btn { height: 30px; padding: 0 12px; font-size: 12.5px; gap: 6px; }
+ .rw-note { margin-top: 10px; padding: 10px 12px; border-radius: 14px; background: color-mix(in srgb, var(--recent) 9%, transparent); font-size: 13px; line-height: 1.55; }
+ .rw-note .rw-h { color: var(--recent); font-size: 11.5px; font-weight: 600; margin-bottom: 3px; }
+ .rw-when { color: var(--text-3); font-size: 12px; margin-top: 4px; }
+ `;
+ document.head.appendChild(style);
+
+ const ago = (iso) => {
+ const t = Date.parse(iso); if (!t) return '';
+ const m = Math.round((Date.now() - t) / 60000);
+ return m < 2 ? 'just now' : m < 60 ? `${m} minutes ago` : m < 48 * 60 ? `${Math.round(m / 60)} hours ago` : `${Math.round(m / 1440)} days ago`;
+ };
+ const itemsOf = (ti) => items.filter((it) => ti == null || it.task === ti);
+
+ /** One board with just the changed cards (and how they connect), each with its note. */
+ function showRecent(ti) {
+ const one = ti != null ? tasks[ti] : tasks.length === 1 ? tasks[0] : null;
+ SC.showBoard({
+ kind: 'Recent work', icon: 'recent',
+ title: one ? one.title : 'Recent work',
+ question: one ? (one.request ? `You asked: ${one.request}` : '') : tasks.map((t) => t.title).join(' · '),
+ answer: one ? one.summary : tasks.map((t) => `**${t.title}.** ${t.summary}`).join('\n\n'),
+ items: itemsOf(ti != null ? ti : null).map((it) => ({ id: it.id, note: it.note || (it.change === 'new' ? 'New' : 'Changed') })),
+ });
+ }
+
+ const btn = SC.addHeaderButton({ id: 'btn-recent', label: 'Recent work', icon: 'recent', title: 'What was just worked on, on one board', onClick: () => showRecent() });
+ const b = document.createElement('span');
+ b.className = 'badge';
+ b.textContent = String(items.length);
+ btn.appendChild(b);
+
+ // codebase panel: each task, what was asked, what was done, and a way to see its cards
+ SC.addPanelSection('overview', () => ({
+ top: true,
+ html: `<div class="sec"><h3>Recent work <span class="c">${items.length}</span></h3>${R.updatedAt ? `<div class="rw-when">Updated ${h(ago(R.updatedAt))}</div>` : ''}<div style="margin-top:10px">${tasks.map((t, i) => itemsOf(i).length ? `
+ <div class="rw-task"><div class="rw-tt">${h(t.title)}</div>
+ ${t.request ? `<div class="rw-q"><b>You asked:</b> ${h(t.request)}</div>` : ''}
+ ${t.summary ? `<div class="rw-s">${h(t.summary)}</div>` : ''}
+ <div class="rw-a"><button class="btn soft" data-rw="${i}">${SC.iconI('recent')}Show ${SC.plural(itemsOf(i).length, 'card')}</button></div></div>` : '').join('')}</div></div>`,
+ bind: (el) => el.querySelectorAll('[data-rw]').forEach((x) => x.addEventListener('click', () => showRecent(+x.dataset.rw))),
+ }));
+
+ // a selected card that changed: the full note, and which request it was for. A part that
+ // contains changes: what changed inside it, each a click away.
+ SC.addPanelSection('item', (id) => {
+ const key = id.startsWith('m:') ? 'f:' + id.slice(2) : id;
+ const mine = items.filter((it) => it.id === key);
+ const inside = items.filter((it) => it.id !== key && SC.chain(it.id).includes(key));
+ if (!mine.length && !inside.length) return '';
+ if (!mine.length) return { top: true, html: `<div class="sec"><h3>Recent work inside <span class="c">${inside.length}</span></h3><div class="list">${inside.map((it) => {
+ const i = SC.info(it.id);
+ return `<a class="row" data-go="${h(it.id)}"><span class="dot" style="background:var(--recent)"></span><span class="rt"><div class="rn">${h(i.name)}</div>${it.note ? `<div class="rd">${h(it.note)}</div>` : ''}</span></a>`;
+ }).join('')}</div></div>` };
+ return { top: true, html: `<div class="sec">${mine.map((it) => {
+ const t = tasks[it.task] || {};
+ return `<div class="rw-note"><div class="rw-h">${it.change === 'new' ? 'New' : 'Changed'} · ${h(t.title || 'Recent work')}</div>${h(it.note || '')}${t.request ? `<div class="rw-q" style="margin:6px 0 0"><b>You asked:</b> ${h(t.request)}</div>` : ''}</div>`;
+ }).join('')}</div>` };
+ });
+
+ window.FloorplanRecent = { show: showRecent, items, tasks };
+})();
diff --git a/skills/floorplan/assets/ui/30-screens.js b/skills/floorplan/assets/ui/30-screens.js
new file mode 100644
index 0000000..e9f47e5
--- /dev/null
+++ b/skills/floorplan/assets/ui/30-screens.js
@@ -0,0 +1,139 @@
+// Screens lens: start from a page people recognise ("the checkout page") and see everything behind it:
+// the parts on it, the requests it makes, the server code that answers them, the data and outside
+// services involved. Data comes from graph.screens (scripts/lib/screens.mjs).
+(() => {
+ const SC = window.Floorplan;
+ if (!SC) return;
+ const G = SC.graph;
+ // pages that only bounce you elsewhere have nothing behind them worth a board
+ const screens = (G.screens || []).filter((s) => s && s.url && Array.isArray(s.behind) && s.behind.length && !(s.behind.length < 2 && /redirect/i.test(`${s.name} ${s.description}`)));
+ if (!screens.length) return;
+ const { h } = SC;
+
+ const style = document.createElement('style');
+ style.textContent = `
+#sc-menu { position: fixed; width: 340px; max-height: min(70vh, 580px); overflow: auto; transform-origin: top right; overscroll-behavior: contain; }
+#sc-menu .sc-f { position: sticky; top: -6px; margin: -6px -6px 4px; padding: 10px 10px 6px; background: rgba(26, 26, 26, .94); backdrop-filter: blur(20px); -webkit-backdrop-filter: blur(20px); z-index: 1; border-radius: 18px 18px 0 0; }
+#sc-menu .sc-f input { width: 100%; height: 34px; border: 0; border-radius: 12px; padding: 0 12px; background: rgba(255, 255, 255, .06); color: var(--text); outline: none; transition: background .2s var(--ease), box-shadow .2s var(--ease); }
+#sc-menu .sc-f input:focus { background: rgba(255, 255, 255, .08); box-shadow: 0 0 0 1px rgba(255, 255, 255, .14); }
+#sc-menu .sc-g { padding: 10px 12px 4px; font-size: 12px; color: var(--text-3); }
+#sc-menu .sc-r { display: block; width: 100%; text-align: left; border: 0; background: none; color: var(--text); padding: 9px 12px; border-radius: 12px; cursor: pointer; transition: background .15s var(--ease); }
+#sc-menu .sc-r:hover, #sc-menu .sc-r.on { background: rgba(255, 255, 255, .07); }
+#sc-menu .sc-r b { font-weight: 500; display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#sc-menu .sc-r span { font-family: var(--mono); font-size: 11.5px; color: var(--text-3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; display: block; }
+#sc-menu .sc-none { padding: 14px 12px; color: var(--text-3); font-size: 12.5px; }
+`;
+ document.head.appendChild(style);
+
+ // ---------- data ----------
+ const topLabel = new Map(G.nodes.filter((n) => !n.parent).map((n) => [n.id, n.label]));
+ const appName = (id) => topLabel.get(id) || (id === 'unassigned' ? 'Other' : id);
+ const byApp = new Map();
+ for (const s of screens) { if (!byApp.has(s.app)) byApp.set(s.app, []); byApp.get(s.app).push(s); }
+ const byFile = new Map();
+ for (const s of screens) { if (!byFile.has(s.file)) byFile.set(s.file, []); byFile.get(s.file).push(s); }
+ // which screens each card shows up behind (for "Shown on these screens" in the details panel)
+ const usedBy = new Map();
+ for (const s of screens) for (const b of s.behind) {
+ if (b.kind === 'screen' || b.id === 'f:' + s.file) continue;
+ if (!usedBy.has(b.id)) usedBy.set(b.id, []);
+ usedBy.get(b.id).push(s);
+ }
+
+ function showScreen(s) {
+ closeMenu();
+ const items = s.behind.filter((b) => SC.exists(b.id));
+ // a short walkthrough: the screen → its first request → the server code → where it ends up
+ const firstOf = (kind) => items.find((b) => b.kind === kind);
+ const steps = [firstOf('screen'), firstOf('request'), firstOf('server'), firstOf('data') || firstOf('outside')].filter(Boolean);
+ SC.showBoard({ title: s.name, question: 'Everything behind ' + s.url, items, steps: steps.length >= 3 ? steps : [] });
+ }
+
+ // ---------- header menu ----------
+ const menu = document.createElement('div');
+ menu.id = 'sc-menu';
+ menu.className = 'menu glass';
+ document.body.appendChild(menu);
+ let btn = null;
+ const many = screens.length > 8;
+
+ function renderList(q = '') {
+ const words = q.toLowerCase().split(/\s+/).filter(Boolean);
+ const hit = (s) => !words.length || words.every((w) => `${s.name} ${s.url} ${appName(s.app)}`.toLowerCase().includes(w));
+ let html = '', shown = 0;
+ for (const [app, list] of byApp) {
+ const rows = list.filter(hit);
+ if (!rows.length) continue;
+ if (byApp.size > 1) html += `<div class="sc-g">${h(appName(app))}</div>`;
+ for (const s of rows) html += `<button class="sc-r" data-sc="${h(s.id)}"><b>${h(s.name)}</b><span>${h(s.url)}</span></button>`;
+ shown += rows.length;
+ }
+ if (!shown) html = `<div class="sc-none">No screen matches “${h(q)}”.</div>`;
+ const list = menu.querySelector('.sc-l');
+ list.innerHTML = html;
+ list.querySelectorAll('[data-sc]').forEach((b) => b.onclick = (ev) => { ev.stopPropagation(); showScreen(screens.find((s) => s.id === b.dataset.sc)); });
+ list.querySelector('.sc-r')?.classList.add('on');
+ }
+ function renderMenu() {
+ menu.innerHTML = `${many ? '<div class="sc-f"><input id="sc-q" placeholder="Find a screen…" spellcheck="false" autocomplete="off"></div>' : ''}<div class="sc-l"></div>`;
+ renderList('');
+ const input = menu.querySelector('#sc-q');
+ if (!input) return;
+ input.oninput = () => renderList(input.value);
+ input.onkeydown = (ev) => {
+ const rows = [...menu.querySelectorAll('.sc-r')];
+ const cur = rows.findIndex((r) => r.classList.contains('on'));
+ if (ev.key === 'Enter' && rows[cur]) { ev.preventDefault(); rows[cur].click(); }
+ else if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+ ev.preventDefault();
+ const next = rows[Math.max(0, Math.min(rows.length - 1, cur + (ev.key === 'ArrowDown' ? 1 : -1)))];
+ rows.forEach((r) => r.classList.toggle('on', r === next));
+ next?.scrollIntoView({ block: 'nearest' });
+ }
+ };
+ }
+ function openMenu() {
+ document.body.click(); // let the viewer close its own menus (Flows, filters)
+ renderMenu();
+ place();
+ menu.classList.add('open');
+ menu.querySelector('#sc-q')?.focus();
+ }
+ function place() {
+ const r = btn.getBoundingClientRect();
+ menu.style.top = r.bottom + 8 + 'px';
+ menu.style.right = Math.max(8, innerWidth - r.right) + 'px';
+ }
+ function closeMenu() { menu.classList.remove('open'); }
+ const isOpen = () => menu.classList.contains('open');
+
+ btn = SC.addHeaderButton({ id: 'screens-btn', label: 'Screens', icon: 'ui', title: 'Pick a screen of the app to see everything behind it', onClick: () => (isOpen() ? closeMenu() : openMenu()) });
+ window.addEventListener('pointerdown', (ev) => { if (isOpen() && !menu.contains(ev.target) && !btn.contains(ev.target)) closeMenu(); }, true);
+ window.addEventListener('keydown', (ev) => {
+ if (!isOpen()) return;
+ if (ev.key === 'Escape') { ev.stopImmediatePropagation(); ev.preventDefault(); closeMenu(); }
+ else if (ev.target?.id !== 'sc-q') ev.stopPropagation(); // keep viewer shortcuts out of the open menu
+ }, true);
+ window.addEventListener('resize', () => { if (isOpen()) place(); });
+
+ // ---------- details panel ----------
+ const row = (s, label) => `<a class="row" data-sc="${h(s.id)}"><span class="dot" style="background:var(--n-ui)"></span><span class="rt"><div class="rn">${h(label || s.name)}</div><div class="rp">${h(s.url)}</div></span></a>`;
+ const bindRows = (el) => el?.querySelectorAll('[data-sc]').forEach((a) => a.addEventListener('click', (ev) => { ev.preventDefault(); showScreen(screens.find((s) => s.id === a.dataset.sc)); }));
+ SC.addPanelSection('item', (id) => {
+ if (typeof id !== 'string') return null;
+ const own = id.startsWith('f:') ? byFile.get(id.slice(2)) || [] : [];
+ const on = (usedBy.get(id) || []).filter((s) => !own.includes(s));
+ if (!own.length && !on.length) return null;
+ let html = '';
+ if (own.length) html += `<div class="sec"><h3>This is a screen</h3><div class="list">${own.map((s) => row(s, 'See everything behind this screen')).join('')}</div></div>`;
+ if (on.length) html += `<div class="sec"><h3>Behind these screens <span class="c">${on.length}</span></h3><div class="list">${on.slice(0, 8).map((s) => row(s)).join('')}</div></div>`;
+ return { html, bind: bindRows };
+ });
+ SC.addPanelSection('overview', () => ({
+ html: `<div class="sec"><h3>Screens <span class="c">${screens.length}</span></h3><div class="list"><a class="row" data-sc-open><span class="dot" style="background:var(--n-ui)"></span><span class="rt"><div class="rn">Start from a screen</div><div class="rd">Pick a page of the app to see the parts on it, the requests it makes and the server code behind them.</div></span></a></div></div>`,
+ bind: (el) => el?.querySelector('[data-sc-open]')?.addEventListener('click', (ev) => { ev.preventDefault(); ev.stopPropagation(); openMenu(); }),
+ }));
+
+ // other features (the tour) can open a screen's board
+ window.FloorplanScreens = { list: screens, show: showScreen, openMenu };
+})();
diff --git a/skills/floorplan/assets/ui/40-tour.js b/skills/floorplan/assets/ui/40-tour.js
new file mode 100644
index 0000000..5924aa0
--- /dev/null
+++ b/skills/floorplan/assets/ui/40-tour.js
@@ -0,0 +1,171 @@
+// "Start here": a calm one-minute tour on first open. What the app is, its main parts, the outside
+// services it leans on, then one real path traced end to end. Steps come from graph.tour (written by
+// Claude in architecture.json) or are built from the map itself.
+(() => {
+ const SC = window.Floorplan;
+ if (!SC) return;
+ const G = SC.graph;
+ const { h } = SC;
+ const SEEN = 'tour-seen:' + (G.project?.name || G.meta?.rootName || 'map');
+
+ const style = document.createElement('style');
+ style.textContent = `
+#tour { position: fixed; left: 16px; bottom: 76px; width: min(360px, calc(100vw - 32px)); padding: 16px 16px 12px 20px; border-radius: var(--r-panel); z-index: 6; animation: tourIn .4s var(--ease); }
+#tour[hidden] { display: none; }
+#tour .tk { font-size: 12px; color: var(--text-3); margin-bottom: 4px; display: flex; gap: 6px; align-items: center; }
+#tour .tk i { width: 3px; height: 3px; border-radius: 50%; background: var(--text-4); }
+#tour .tt { font-size: 16px; font-weight: 600; letter-spacing: -.01em; line-height: 1.35; padding-right: 22px; }
+#tour .tn { color: var(--text-2); line-height: 1.55; margin-top: 6px; font-size: 13.5px; }
+#tour .tip { color: var(--text-3); font-size: 12px; line-height: 1.5; margin-top: 10px; }
+#tour .tf { display: flex; align-items: center; gap: 8px; margin-top: 14px; }
+#tour .dots { display: flex; gap: 4px; flex: 1; }
+#tour .dots i { width: 14px; height: 3px; border-radius: 2px; background: rgba(255, 255, 255, .12); transition: background .3s var(--ease); }
+#tour .dots i.on { background: #ececec; }
+#tour .tf .btn { height: 32px; }
+#tour .tf .btn.icon { width: 32px; }
+#tour .tx { position: absolute; top: 10px; right: 10px; width: 28px; height: 28px; }
+@keyframes tourIn { from { opacity: 0; transform: translateY(8px) scale(.98); } }
+`;
+ document.head.appendChild(style);
+
+ // ---------- steps ----------
+ const clip = (s, max = 230) => {
+ s = String(s || '').trim();
+ if (s.length <= max) return s;
+ const cut = s.slice(0, max);
+ const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('; '));
+ return end > 80 ? cut.slice(0, end + 1) : cut.replace(/\s+\S*$/, '') + '…';
+ };
+ const listOf = (names) => names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+ const tops = G.nodes.filter((n) => !n.parent && n.id !== 'unassigned');
+ const bySize = (a, b) => (b.stats?.files || 0) - (a.stats?.files || 0);
+ const screensOf = (id) => (G.screens || []).filter((s) => s.app === id).length;
+
+ function flowStep() {
+ const f = (G.flows || []).find((x) => !x.custom) || (G.flows || [])[0];
+ if (!f || !f.steps?.length) return null;
+ return { ref: 'root', flow: f.id, kicker: 'One real path', title: f.title, note: `${f.description ? clip(f.description, 160) + ' ' : ''}Press Play to follow it through the code, one step at a time.` };
+ }
+ function autoSteps() {
+ const p = G.project || {};
+ const steps = [{ ref: 'root', kicker: 'The codebase', title: p.name || 'This codebase', note: clip(p.summary) || 'A map of the main parts of this app and how they talk to each other.' }];
+ const ui = tops.filter((n) => n.kind === 'ui').sort(bySize).slice(0, 2);
+ for (const n of ui) {
+ const k = screensOf(n.id);
+ steps.push({ ref: 'n:' + n.id, kicker: 'What people use', title: n.label, note: clip(n.summary, 200) + (k > 1 ? ` It has ${k} screens.` : '') });
+ }
+ let back = tops.filter((n) => n.kind === 'service' || n.kind === 'worker').sort(bySize);
+ if (!back.length) back = tops.filter((n) => !['ui', 'external', 'test', 'script', 'config', 'infra', 'misc'].includes(n.kind)).sort(bySize);
+ for (const n of back.slice(0, ui.length > 1 ? 1 : 2)) steps.push({ ref: 'n:' + n.id, kicker: 'Behind the scenes', title: n.label, note: clip(n.summary, 200) });
+ const data = tops.find((n) => n.kind === 'data' && !back.includes(n));
+ if (data && steps.length < 5) steps.push({ ref: 'n:' + data.id, kicker: 'Where the data lives', title: data.label, note: clip(data.summary, 200) });
+ const ext = tops.filter((n) => n.kind === 'external');
+ if (ext.length) {
+ steps.push({
+ ref: ext.length === 1 ? 'n:' + ext[0].id : 'root', kicker: 'Outside services', title: ext.length === 1 ? ext[0].label : `${ext.length} outside services`,
+ note: ext.length === 1 ? clip(ext[0].summary, 200) : `It also relies on ${listOf(ext.slice(0, 6).map((n) => n.label))}${ext.length > 6 ? ` and ${ext.length - 6} more` : ''}. They sit at the edge of the map; the lines show which parts talk to them.`,
+ });
+ }
+ return steps;
+ }
+ function buildSteps() {
+ const own = (G.tour || []).filter((s) => s && s.ref && (s.ref === 'root' || SC.exists(s.ref))).map((s) => ({ ref: s.ref, title: s.title || SC.info(s.ref).name, note: s.note || SC.info(s.ref).desc || '', kicker: '' }));
+ const steps = own.length >= 2 ? own : autoSteps();
+ const fl = flowStep();
+ if (fl && !steps.some((s) => s.flow) && steps.length < 9) steps.push(fl);
+ return steps.filter((s) => s.ref === 'root' || SC.exists(s.ref)).slice(0, 9);
+ }
+
+ // ---------- card ----------
+ const card = document.createElement('div');
+ card.id = 'tour';
+ card.className = 'glass';
+ card.hidden = true;
+ card.setAttribute('role', 'dialog');
+ card.setAttribute('aria-label', 'Start here tour');
+ document.body.appendChild(card);
+ let steps = [], at = -1;
+ const active = () => at >= 0;
+
+ function go(s) {
+ if (!s.ref || s.ref === 'root') { SC.go('root', { select: null }); return; }
+ const parent = SC.parentOf(s.ref) || 'root';
+ if (parent === 'root') SC.go('root', { select: s.ref }); // stay on the overview, just highlight the card
+ else SC.reveal(s.ref);
+ }
+ function render() {
+ const s = steps[at], last = at === steps.length - 1;
+ const tip = last ? `Replay this tour any time from <b>Start here</b> at the top.${window.FloorplanScreens ? ' <b>Screens</b> shows everything behind any page.' : ''}` : '';
+ card.innerHTML = `<button class="btn icon tx" data-x title="Close (Esc)">${SC.iconI('x')}</button>
+ <div class="tk"><span>Start here</span><i></i><span>${at + 1} of ${steps.length}</span>${s.kicker ? `<i></i><span>${h(s.kicker)}</span>` : ''}</div>
+ <div class="tt">${h(s.title)}</div>${s.note ? `<div class="tn">${h(s.note)}</div>` : ''}${tip ? `<div class="tip">${tip}</div>` : ''}
+ <div class="tf"><div class="dots">${steps.map((_, k) => `<i class="${k <= at ? 'on' : ''}"></i>`).join('')}</div>
+ ${at > 0 ? `<button class="btn icon soft" data-back title="Back (←)">${SC.iconI('left')}</button>` : `<button class="btn" data-x>Skip</button>`}
+ ${s.flow ? `<button class="btn primary" data-play>${SC.iconI('right')}Play it</button>${last ? '' : '<button class="btn soft" data-next>Next</button>'}` : `<button class="btn primary" data-next>${last ? 'Done' : 'Next'}</button>`}
+ </div>`;
+ card.querySelectorAll('[data-x]').forEach((b) => b.onclick = end);
+ card.querySelector('[data-back]')?.addEventListener('click', back);
+ card.querySelector('[data-next]')?.addEventListener('click', next);
+ card.querySelector('[data-play]')?.addEventListener('click', () => { const id = s.flow; end(); SC.startFlow(id); });
+ }
+ // sit above the zoom controls, and above the Ask bar (and its notices) where they overlap
+ function place() {
+ let bottom = 76;
+ const ask = document.getElementById('ask');
+ if (ask) {
+ const a = ask.getBoundingClientRect(), c = card.getBoundingClientRect();
+ const top = [...ask.children].filter((x) => x.offsetParent && x.getBoundingClientRect().height > 0).reduce((m, x) => Math.min(m, x.getBoundingClientRect().top), a.bottom);
+ if (a.width && a.left < 16 + c.width + 12 && top < innerHeight) bottom = Math.max(bottom, innerHeight - top + 12);
+ }
+ card.style.bottom = Math.min(bottom, Math.max(76, innerHeight - card.offsetHeight - 80)) + 'px';
+ }
+ window.addEventListener('resize', () => { if (active()) place(); });
+ function show(i) {
+ at = i;
+ card.hidden = false;
+ render();
+ place();
+ go(steps[at]);
+ if (at === 0) setTimeout(() => SC.fit(true), 450);
+ }
+ function next() { if (at >= steps.length - 1) end(); else show(at + 1); }
+ function back() { if (at > 0) show(at - 1); }
+ function end() {
+ if (!active()) return;
+ at = -1;
+ card.hidden = true;
+ SC.store.set(SEEN, true);
+ if (SC.state.container === 'root') SC.select(null);
+ }
+ function start() {
+ steps = buildSteps();
+ if (steps.length < 2) { SC.toast('There is not enough on this map for a tour yet.'); return; }
+ SC.store.set(SEEN, true);
+ show(0);
+ }
+
+ const tourBtn = SC.addHeaderButton({ id: 'tour-btn', label: 'Start here', icon: 'home', title: 'A one-minute tour of this codebase', onClick: () => (active() ? end() : start()) });
+ const ic = tourBtn.querySelector('svg');
+ if (ic) ic.innerHTML = '<circle cx="12" cy="12" r="9"/><path d="m15.5 8.5-2.2 4.8-4.8 2.2 2.2-4.8z"/>'; // compass
+ window.addEventListener('keydown', (ev) => {
+ if (!active() || ev.target?.tagName === 'INPUT' || ev.target?.tagName === 'TEXTAREA') return;
+ if (ev.key === 'Escape') { ev.stopPropagation(); ev.preventDefault(); end(); }
+ else if (!SC.state.flow && ev.key === 'ArrowRight') { ev.stopPropagation(); ev.preventDefault(); next(); }
+ else if (!SC.state.flow && ev.key === 'ArrowLeft') { ev.stopPropagation(); ev.preventDefault(); back(); }
+ }, true);
+ // a guided flow takes over the canvas: step aside
+ SC.on('render', () => { if (active() && SC.state.flow) end(); });
+
+ // first visit: start on its own, unless the link points somewhere specific
+ let auto = false;
+ const maybeAuto = () => {
+ if (auto) return;
+ auto = true;
+ if (SC.store.get(SEEN, false) || location.hash.length > 1) return;
+ setTimeout(() => { if (!active() && !SC.state.flow && SC.state.container === 'root') start(); }, 700);
+ };
+ SC.on('ready', maybeAuto);
+ if (SC.state.layout) maybeAuto();
+
+ window.FloorplanTour = { start, end };
+})();
diff --git a/skills/floorplan/assets/viewer.html b/skills/floorplan/assets/viewer.html
new file mode 100644
index 0000000..c24a8bf
--- /dev/null
+++ b/skills/floorplan/assets/viewer.html
@@ -0,0 +1,1984 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__FLOORPLAN_TITLE__</title>
+<link rel="icon" type="image/png" href="__FLOORPLAN_FAVICON__">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap">
+<style>
+:root {
+ --sans: "Inter", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+ --mono: "JetBrains Mono", ui-monospace, "Cascadia Code", "SF Mono", Consolas, monospace;
+ --bg: #0f0f0f; --grid: #1f1f1f;
+ --surface: #191919; --surface-hover: #1e1e1e; --raise: #232323; --raise-2: #2b2b2b;
+ --elev: rgba(26, 26, 26, .86); --hair: rgba(255, 255, 255, .06); --hair-2: rgba(255, 255, 255, .1);
+ --text: #ececec; --text-2: #b4b4b4; --text-3: #8b8b8b; --text-4: #5c5c5c;
+ --recent: #4ade80;
+ --ring: rgba(255, 255, 255, .88); --focus: rgba(255, 255, 255, .16);
+ --r-card: 20px; --r-panel: 24px; --r-ctl: 12px;
+ --ease: cubic-bezier(.16, 1, .3, 1); --ease-io: cubic-bezier(.65, 0, .35, 1);
+ --shadow-card: 0 1px 0 rgba(255, 255, 255, .035) inset, 0 12px 32px -20px rgba(0, 0, 0, .95);
+ --shadow-float: 0 0 0 1px rgba(255, 255, 255, .05), 0 24px 64px -24px rgba(0, 0, 0, .9);
+ --k-import: #6e6e6e; --k-http: #7aa7ff; --k-call: #b49cff; --k-rpc: #8f9bff; --k-event: #f19ac7; --k-queue: #f0c36b; --k-data: #63d2b8; --k-config: #6b7280; --k-contains: #4a4a4a;
+ --n-ui: #7cc4ff; --n-service: #b49cff; --n-worker: #f0c36b; --n-library: #6fd7a8; --n-feature: #8fb4ff; --n-data: #63d2b8; --n-config: #a3a3a3;
+ --n-test: #f19ac7; --n-script: #f5a66b; --n-infra: #f28b8b; --n-external: #e3a6f0; --n-misc: #8b8b8b; --n-dir: #a3a3a3; --n-file: #a3a3a3;
+ --n-module: #a3a3a3; --n-symbol: #c7b8ff; --n-route: #7aa7ff; --n-connector: #8b8b8b;
+ --m-GET: #6fd7a8; --m-POST: #7aa7ff; --m-PUT: #f0c36b; --m-PATCH: #c7a3ff; --m-DELETE: #f28b8b; --m-ANY: #a3a3a3;
+ --panel-w: 360px; --pw: calc(var(--panel-w) + 32px); --gutter: 28px;
+ color-scheme: dark;
+}
+body.no-panel { --pw: 0px; }
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 13.5px; overflow: hidden; -webkit-font-smoothing: antialiased; }
+button, input { font: inherit; color: inherit; }
+button { -webkit-tap-highlight-color: transparent; }
+::selection { background: rgba(255, 255, 255, .2); }
+svg.i { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.75; stroke-linecap: round; stroke-linejoin: round; flex: none; }
+.glass { background: var(--elev); backdrop-filter: blur(20px) saturate(1.2); -webkit-backdrop-filter: blur(20px) saturate(1.2); box-shadow: var(--shadow-float); }
+.kbd { font-family: var(--mono); font-size: 10.5px; color: var(--text-3); background: rgba(255, 255, 255, .06); border-radius: 6px; padding: 1px 6px; line-height: 17px; }
+
+/* ---------- top bar: brand + path left, search centered, actions right ---------- */
+header { position: fixed; inset: 0 0 auto 0; height: 64px; display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 12px; padding: 0 16px; z-index: 10; pointer-events: none;
+ background: linear-gradient(to bottom, rgba(15, 15, 15, .96) 35%, rgba(15, 15, 15, 0)); }
+header > * { pointer-events: auto; }
+.hl { display: flex; align-items: center; gap: 4px; min-width: 0; }
+.hc { display: flex; justify-content: center; }
+.hr { display: flex; align-items: center; justify-content: flex-end; gap: 4px; }
+.brand { display: flex; align-items: center; gap: 10px; font-weight: 600; letter-spacing: -.01em; white-space: nowrap; padding-right: 6px; }
+.mark { height: 22px; width: auto; display: block; flex: none; }
+#crumbs { display: flex; align-items: center; min-width: 0; overflow: hidden; }
+#crumbs .sep { color: var(--text-4); padding: 0 1px; }
+#crumbs button { background: none; border: 0; padding: 6px 10px; border-radius: 999px; cursor: pointer; color: var(--text-3); white-space: nowrap; max-width: 220px; overflow: hidden; text-overflow: ellipsis; transition: background .2s var(--ease), color .2s var(--ease); }
+#crumbs button:hover { background: rgba(255, 255, 255, .06); color: var(--text); }
+#crumbs button.cur { color: var(--text); }
+.btn { height: 36px; display: inline-flex; align-items: center; gap: 8px; padding: 0 14px; border-radius: 999px; border: 0; background: transparent; color: var(--text-2); cursor: pointer; white-space: nowrap; text-decoration: none; font-size: 13px;
+ transition: background .2s var(--ease), color .2s var(--ease), transform .2s var(--ease); }
+.btn:hover { background: rgba(255, 255, 255, .07); color: var(--text); }
+.btn:active { transform: scale(.97); }
+.btn.icon { width: 36px; padding: 0; justify-content: center; }
+.btn.soft { background: rgba(255, 255, 255, .06); color: var(--text); }
+.btn.soft:hover { background: rgba(255, 255, 255, .1); }
+.btn.primary { background: #ececec; color: #0f0f0f; }
+.btn.primary:hover { background: #fff; }
+.btn:disabled { opacity: .35; cursor: default; }
+.btn .badge { min-width: 16px; height: 16px; border-radius: 999px; background: #ececec; color: #0f0f0f; font-size: 10px; font-weight: 600; display: grid; place-items: center; padding: 0 4px; }
+#btn-up[hidden] { display: none; }
+#search-btn { width: min(460px, 36vw); height: 40px; justify-content: flex-start; gap: 10px; padding: 0 8px 0 16px; background: var(--raise); color: var(--text-3); }
+#search-btn:hover { background: var(--raise-2); color: var(--text-2); }
+#search-btn .kbd { margin-left: auto; }
+.rel { position: relative; }
+
+/* ---------- canvas ---------- */
+#stage { position: fixed; inset: 0; overflow: hidden; background-color: var(--bg); background-image: radial-gradient(var(--grid) 1px, transparent 1px); background-size: 24px 24px; }
+#svg { width: 100%; height: 100%; display: block; cursor: grab; user-select: none; }
+#svg.panning { cursor: grabbing; }
+#viewport { transform-origin: 0 0; }
+#viewport.anim { transition: transform .5s var(--ease), opacity .35s var(--ease); }
+#context { position: absolute; left: 24px; top: 72px; max-width: min(520px, calc(100% - var(--pw) - 64px)); pointer-events: none; }
+#context .k { display: inline-flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--text-3); }
+#context .k .ico { width: 20px; height: 20px; border-radius: 7px; }
+#context::before { content: ""; position: absolute; inset: -28px -60px -28px -40px; background: radial-gradient(closest-side, rgba(15, 15, 15, .9), rgba(15, 15, 15, 0)); z-index: -1; }
+#context h1 { margin: 6px 0 4px; font-size: 24px; font-weight: 600; letter-spacing: -.025em; }
+#context p { margin: 0; color: var(--text-2); line-height: 1.55; font-size: 14px; }
+
+/* ---------- cards ---------- */
+.node foreignObject { pointer-events: none; overflow: visible; }
+.node .card { pointer-events: auto; cursor: pointer; }
+.fo-pad { width: 100%; height: 100%; padding: var(--gutter); }
+.card { width: 100%; height: 100%; border-radius: var(--r-card); background: var(--surface); padding: 16px 18px; display: flex; flex-direction: column; gap: 7px; overflow: hidden; position: relative;
+ box-shadow: var(--shadow-card); transition: background .25s var(--ease), box-shadow .25s var(--ease), transform .3s var(--ease);
+ animation: cardIn .55s var(--ease) both; animation-delay: var(--d, 0ms); }
+@keyframes cardIn { from { opacity: 0; transform: translateY(8px) scale(.985); } }
+.card > * { flex-shrink: 0; }
+.node:hover .card { background: var(--surface-hover); transform: translateY(-2px); box-shadow: 0 1px 0 rgba(255, 255, 255, .05) inset, 0 18px 40px -20px rgba(0, 0, 0, 1); }
+/* selected: a soft ring that follows the card's radius, plus a faint halo */
+.node.sel .card { background: var(--surface-hover); box-shadow: 0 0 0 1.5px rgba(255, 255, 255, .5), 0 0 0 6px rgba(255, 255, 255, .05), 0 18px 40px -20px rgba(0, 0, 0, 1); }
+.node.sel .card.external { box-shadow: inset 0 0 0 1.5px rgba(255, 255, 255, .1), 0 0 0 1.5px rgba(255, 255, 255, .5), 0 0 0 6px rgba(255, 255, 255, .05); }
+.node.flash .card { animation: flash 1.2s var(--ease) 2; }
+@keyframes flash { 50% { box-shadow: 0 0 0 1.5px rgba(255, 255, 255, .6), 0 0 0 10px rgba(255, 255, 255, .08); } }
+.head { display: flex; align-items: center; gap: 10px; min-width: 0; }
+.ico { width: 30px; height: 30px; border-radius: 10px; display: grid; place-items: center; flex: none; color: var(--c); background: color-mix(in srgb, var(--c) 13%, transparent); }
+.ico svg { width: 15px; height: 15px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+.title { font-size: 15px; font-weight: 600; letter-spacing: -.015em; line-height: 1.3; overflow: hidden; min-width: 0; flex: 1; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow-wrap: anywhere; }
+.card > .title { flex: none; } /* an endpoint's name, on its own row under the method and path */
+/* footer: size on the left, recent-work pill on the right, pinned to the bottom of the card */
+.foot { margin-top: auto; display: flex; align-items: center; justify-content: space-between; gap: 8px; min-height: 23px; }
+.foot .meta { align-self: center; }
+svg.lod-low .foot .meta { visibility: hidden; }
+.title.mono { font-family: var(--mono); font-size: 13px; font-weight: 500; }
+.meta { font-size: 11.5px; color: var(--text-3); white-space: nowrap; font-variant-numeric: tabular-nums; background: rgba(255, 255, 255, .05); border-radius: 999px; padding: 2px 8px; }
+.desc { color: var(--text-2); font-size: 13px; line-height: 19px; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: var(--lines, 2); overflow: hidden; max-height: calc(var(--lines, 2) * 19px); }
+.desc[style*="--lines:1"] { -webkit-line-clamp: 1; } .desc[style*="--lines:2"] { -webkit-line-clamp: 2; } .desc[style*="--lines:3"] { -webkit-line-clamp: 3; }
+.desc.empty { color: var(--text-4); }
+.method { font-family: var(--mono); font-size: 10.5px; font-weight: 600; padding: 3px 8px; border-radius: 8px; color: var(--m); background: color-mix(in srgb, var(--m) 14%, transparent); letter-spacing: .02em; flex: none; }
+.rpath { font-family: var(--mono); font-size: 12px; color: var(--text-2); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+.card.external { background: transparent; box-shadow: inset 0 0 0 1.5px rgba(255, 255, 255, .1); }
+.node:hover .card.external { background: rgba(255, 255, 255, .03); }
+.card.dir { background: rgba(25, 25, 25, .7); box-shadow: inset 0 0 0 1px rgba(255, 255, 255, .05); }
+.card.module { background: var(--raise); }
+/* recent work: cards Claude just changed (green ring + tag), and the parts that contain them (soft ring + count) */
+.card.recent { box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--recent) 62%, transparent), var(--shadow-card); }
+.node:hover .card.recent { box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--recent) 85%, transparent), 0 18px 40px -20px rgba(0, 0, 0, 1); }
+.card.recent-in { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--recent) 30%, transparent), var(--shadow-card); }
+.rw { flex: none; display: inline-flex; align-items: center; gap: 5px; font-size: 11px; font-weight: 600; line-height: 1; color: var(--recent); background: color-mix(in srgb, var(--recent) 13%, transparent); border-radius: 999px; padding: 4px 8px 4px 7px; white-space: nowrap; }
+.rw::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
+.rw.soft { font-weight: 500; }
+body.no-recent .rw { display: none; }
+body.no-recent .card.recent, body.no-recent .card.recent-in { box-shadow: var(--shadow-card); }
+svg.lod-low .rw { font-size: 18px; padding: 6px 12px; }
+.card.has-note .title::after { content: ""; display: inline-block; width: 6px; height: 6px; border-radius: 50%; background: #f0c36b; margin-left: 8px; vertical-align: middle; }
+.card.connector { flex-direction: row; align-items: center; gap: 10px; padding: 0 14px 0 10px; border-radius: var(--r-card); background: var(--raise); }
+.card.connector .ico { width: 26px; height: 26px; border-radius: 9px; }
+.card.connector .lbl { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--text-2); font-weight: 500; font-size: 13px; flex: 1; }
+.card.connector .dir-ico { color: var(--text-4); display: grid; }
+.card.connector .dir-ico svg { width: 14px; height: 14px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+.anote { margin-top: 4px; display: flex; gap: 9px; align-items: flex-start; padding: 9px 11px; border-radius: 14px; background: rgba(255, 255, 255, .05); font-size: 12.5px; line-height: 1.45; color: var(--text); }
+.anote b { flex: none; width: 19px; height: 19px; border-radius: 999px; background: #ececec; color: #0f0f0f; display: grid; place-items: center; font-size: 10.5px; font-weight: 700; }
+.anote span { display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+svg.lod-mid .desc { -webkit-line-clamp: 1 !important; max-height: 19px; }
+svg.lod-low .meta, svg.lod-low .anote { visibility: hidden; }
+/* far out, the big title and the footer pill are what's readable: drop the description so they fit */
+svg.lod-low .desc { display: none; }
+svg.lod-low .title { font-size: 22px; white-space: normal; }
+svg.dim .node:not(.hl) .card { box-shadow: none; }
+svg.dim .node:not(.hl) .card > * { opacity: .28; transition: opacity .3s var(--ease); }
+
+/* ---------- edges ---------- */
+.edges { animation: fadeIn .7s var(--ease) .12s both; }
+/* column brackets over a view: what uses this part · what's inside it · what it uses */
+.cols { animation: fadeIn .7s var(--ease) .2s both; pointer-events: none; }
+.cols path { fill: none; stroke: rgba(255, 255, 255, .16); stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+.cols text { fill: var(--text-3); font: 500 13px Inter, system-ui, sans-serif; letter-spacing: -.005em; dominant-baseline: central; text-anchor: middle; }
+@keyframes fadeIn { from { opacity: 0; } }
+.edge { color: var(--k-import); }
+.edge .trace { fill: none; stroke: currentColor; stroke-opacity: .5; stroke-linecap: round; stroke-linejoin: round; transition: stroke-opacity .25s var(--ease), stroke-width .25s var(--ease); }
+.edge .flow { fill: none; stroke: currentColor; stroke-width: 2; stroke-dasharray: 2 10; stroke-linecap: round; opacity: 0; transition: opacity .25s var(--ease); }
+.edge .hit { fill: none; stroke: transparent; stroke-width: 16; cursor: pointer; }
+.edge .port { fill: var(--bg); stroke: currentColor; stroke-width: 1.5; transition: opacity .25s var(--ease); }
+.edge.k-config .trace { stroke-dasharray: 5 5; }
+.edge.k-contains .trace { stroke-dasharray: 2 6; stroke-opacity: .9; }
+.edge:hover .trace, .edge.hl .trace { stroke-opacity: 1; }
+.edge:hover .flow, .edge.hl .flow { opacity: .95; animation: flow 1.1s linear infinite; }
+@keyframes flow { to { stroke-dashoffset: -24; } }
+svg.dim .edge:not(.hl) { opacity: .1; }
+.edge { transition: opacity .3s var(--ease); }
+.pulse { fill: #fff; filter: drop-shadow(0 0 6px rgba(255, 255, 255, .8)); }
+.flowlink { fill: none; stroke: #ececec; stroke-opacity: .7; stroke-width: 2; stroke-dasharray: 5 7; animation: flow 1.1s linear infinite; }
+
+/* ---------- floating chrome ---------- */
+#zoom { position: absolute; left: 16px; bottom: 16px; display: flex; padding: 4px; gap: 2px; border-radius: 999px; }
+#zoom button { width: 34px; height: 34px; border: 0; background: none; color: var(--text-2); border-radius: 999px; cursor: pointer; display: grid; place-items: center; transition: background .2s var(--ease), color .2s var(--ease); }
+#zoom button:hover { background: rgba(255, 255, 255, .08); color: var(--text); }
+.menu { position: absolute; z-index: 30; min-width: 230px; padding: 6px; border-radius: 18px; display: none; transform-origin: top right; }
+.menu.open { display: block; animation: menuIn .22s var(--ease); }
+@keyframes menuIn { from { opacity: 0; transform: translateY(-4px) scale(.97); } }
+#flowmenu, #legend { top: 44px; right: 0; width: 320px; }
+#flowmenu .r { padding: 10px 12px; border-radius: 12px; cursor: pointer; transition: background .15s var(--ease); }
+#flowmenu .r:hover { background: rgba(255, 255, 255, .07); }
+#flowmenu .r b { font-weight: 500; display: block; }
+#flowmenu .r span { color: var(--text-3); font-size: 12.5px; }
+#flowmenu .r.custom { display: flex; gap: 8px; align-items: flex-start; }
+#flowmenu .r.custom .rt { flex: 1; min-width: 0; }
+#flowmenu .r .del { border: 0; background: none; color: var(--text-4); border-radius: 999px; width: 26px; height: 26px; display: grid; place-items: center; cursor: pointer; opacity: 0; transition: opacity .15s var(--ease), background .15s var(--ease); flex: none; }
+#flowmenu .r:hover .del { opacity: 1; }
+#flowmenu .r .del:hover { background: rgba(255, 255, 255, .1); color: var(--text); }
+#flowmenu .yours { font-size: 11px; color: var(--text-3); background: rgba(255, 255, 255, .06); border-radius: 999px; padding: 1px 7px; margin-left: 6px; font-weight: 400; }
+#flowmenu .new { display: flex; align-items: center; gap: 10px; color: var(--text); }
+#flowmenu .new svg { color: var(--text-3); }
+.ff { padding: 8px 6px 6px; }
+.ff label { display: block; font-size: 12.5px; color: var(--text-3); padding: 2px 6px 8px; }
+.ff textarea { width: 100%; min-height: 84px; resize: none; background: rgba(255, 255, 255, .05); border: 0; border-radius: 14px; padding: 11px 13px; color: var(--text); outline: none; font: inherit; line-height: 1.5; transition: background .2s var(--ease), box-shadow .2s var(--ease); }
+.ff textarea:focus { background: rgba(255, 255, 255, .07); box-shadow: 0 0 0 1px rgba(255, 255, 255, .14); }
+.ff .ffa { display: flex; justify-content: flex-end; gap: 6px; margin-top: 10px; }
+.ff .ffa .btn { height: 34px; }
+.ff .note { font-size: 12px; color: var(--text-4); padding: 8px 6px 0; }
+#legend { width: 250px; }
+#legend .lh { padding: 8px 12px 6px; font-size: 12px; color: var(--text-3); }
+#legend label { display: flex; align-items: center; gap: 10px; padding: 9px 12px; border-radius: 12px; cursor: pointer; color: var(--text); user-select: none; transition: background .15s var(--ease); }
+#legend label:hover { background: rgba(255, 255, 255, .07); }
+#legend label.off { color: var(--text-4); }
+#legend label.off .sw { opacity: .25; }
+#legend input { display: none; }
+#legend .sw { width: 16px; height: 3px; border-radius: 2px; }
+#legend .n { margin-left: auto; color: var(--text-3); font-variant-numeric: tabular-nums; font-size: 12px; }
+#legend .tog { width: 28px; height: 16px; border-radius: 999px; background: rgba(255, 255, 255, .12); position: relative; transition: background .2s var(--ease); flex: none; }
+#legend .tog::after { content: ""; position: absolute; left: 2px; top: 2px; width: 12px; height: 12px; border-radius: 50%; background: #8b8b8b; transition: transform .25s var(--ease), background .2s var(--ease); }
+#legend label:not(.off) .tog { background: rgba(255, 255, 255, .28); }
+#legend label:not(.off) .tog::after { transform: translateX(12px); background: #fff; }
+#ctxmenu { position: fixed; display: block; transform-origin: top left; }
+#ctxmenu[hidden] { display: none; }
+#ctxmenu:not([hidden]) { animation: menuIn .18s var(--ease); }
+.mi { width: 100%; display: flex; align-items: center; gap: 10px; padding: 9px 12px; border: 0; border-radius: 12px; background: none; cursor: pointer; color: var(--text); text-align: left; font-size: 13px; transition: background .15s var(--ease); }
+.mi:hover { background: rgba(255, 255, 255, .08); }
+.mi svg { color: var(--text-3); }
+.mi .hint { margin-left: auto; color: var(--text-4); font-size: 12px; }
+.mi-sep { height: 1px; background: var(--hair); margin: 5px 8px; }
+.mi-title { padding: 8px 12px 6px; font-size: 12px; color: var(--text-3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 280px; }
+#flowbar { position: absolute; left: calc((100% - var(--pw)) / 2); top: 76px; transform: translateX(-50%); width: min(680px, calc(100% - var(--pw) - 48px)); padding: 14px 14px 14px 20px; display: flex; gap: 12px; align-items: center; z-index: 3; border-radius: var(--r-panel); animation: sheetIn .4s var(--ease); transition: left .45s var(--ease); }
+#flowbar[hidden] { display: none; }
+#flowbar .fk { font-size: 12px; color: var(--text-3); margin-bottom: 2px; }
+#flowbar .ft { flex: 1; min-width: 0; line-height: 1.5; }
+#flowbar .ft b { font-weight: 600; }
+#flowbar .ft span { color: var(--text-2); }
+#flowbar .dots { display: flex; gap: 4px; margin-top: 8px; }
+#flowbar .dots i { width: 18px; height: 3px; border-radius: 2px; background: rgba(255, 255, 255, .12); transition: background .3s var(--ease); }
+#flowbar .dots i.on { background: #ececec; }
+#tooltip { position: absolute; pointer-events: none; padding: 11px 13px; max-width: 320px; z-index: 6; font-size: 12.5px; line-height: 1.5; border-radius: 16px; animation: tipIn .2s var(--ease); }
+@keyframes tipIn { from { opacity: 0; transform: translateY(3px); } }
+#tooltip[hidden] { display: none; }
+#tooltip .tt { font-weight: 600; }
+#tooltip .td { color: var(--text-2); }
+#tooltip .tp { color: var(--text-3); font-family: var(--mono); font-size: 11.5px; margin-top: 4px; word-break: break-all; white-space: pre-line; }
+#tooltip .th { display: flex; gap: 10px; margin-top: 8px; color: var(--text-3); font-size: 11.5px; }
+#tooltip .trw { margin-top: 9px; padding: 8px 10px; border-radius: 11px; background: color-mix(in srgb, var(--recent) 9%, transparent); }
+#tooltip .trh { display: flex; align-items: center; gap: 6px; color: var(--recent); font-size: 11.5px; font-weight: 600; }
+#tooltip .trh::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; flex: none; }
+#tooltip .trn { color: var(--text); margin-top: 3px; }
+#tooltip .th span { display: inline-flex; gap: 5px; align-items: center; }
+#loading { position: absolute; left: calc((100% - var(--pw)) / 2); top: 50%; transform: translate(-50%, -50%); padding: 10px 16px; border-radius: 999px; font-size: 12.5px; color: var(--text-2); opacity: 0; transition: opacity .3s var(--ease); pointer-events: none; }
+#loading.on { opacity: 1; }
+#empty { position: absolute; inset: 0; display: grid; place-items: center; color: var(--text-3); pointer-events: none; }
+
+/* ---------- inspector (floating) ---------- */
+#panel { position: fixed; top: 68px; right: 16px; bottom: 16px; width: var(--panel-w); border-radius: var(--r-panel); overflow: auto; z-index: 5;
+ background: var(--elev); backdrop-filter: blur(24px) saturate(1.2); -webkit-backdrop-filter: blur(24px) saturate(1.2); box-shadow: var(--shadow-float);
+ transition: transform .45s var(--ease), opacity .3s var(--ease); }
+body.no-panel #panel { transform: translateX(24px) scale(.98); opacity: 0; pointer-events: none; }
+#panel-resize { position: fixed; top: 84px; bottom: 32px; right: calc(var(--panel-w) + 16px - 6px); width: 12px; cursor: ew-resize; z-index: 6; display: grid; place-items: center; transition: opacity .3s var(--ease); }
+#panel-resize::after { content: ""; width: 4px; height: 40px; border-radius: 999px; background: rgba(255, 255, 255, .14); opacity: 0; transition: opacity .2s var(--ease), height .25s var(--ease), background .2s var(--ease); }
+#panel-resize:hover::after, body.resizing #panel-resize::after { opacity: 1; height: 64px; }
+body.resizing #panel-resize::after { background: rgba(255, 255, 255, .4); }
+body.resizing, body.resizing * { cursor: ew-resize !important; user-select: none; }
+body.resizing #panel, body.resizing #ask, body.resizing #flowbar { transition: none; }
+body.no-panel #panel-resize { opacity: 0; pointer-events: none; }
+#panel::-webkit-scrollbar { width: 12px; } #panel::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, .1); border-radius: 10px; border: 4px solid transparent; background-clip: padding-box; }
+#panel > * { animation: panelIn .4s var(--ease) both; }
+@keyframes panelIn { from { opacity: 0; transform: translateY(6px); } }
+.sec { padding: 18px 20px 6px; }
+.sec:first-child { padding-top: 22px; }
+.sec:last-child { padding-bottom: 22px; }
+.sec h3 { margin: 0 0 8px; font-size: 12.5px; font-weight: 500; color: var(--text-3); display: flex; align-items: center; gap: 6px; }
+.sec h3 .c { color: var(--text-4); }
+.ph { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.ph .kindlabel { font-size: 12.5px; color: var(--text-3); text-transform: capitalize; }
+.pt { margin: 0 0 6px; font-size: 20px; font-weight: 600; letter-spacing: -.02em; line-height: 1.3; word-break: break-word; }
+.pd { margin: 0; color: var(--text-2); line-height: 1.6; }
+.pd.empty { color: var(--text-4); }
+.pp { display: flex; align-items: center; gap: 6px; margin-top: 14px; font-family: var(--mono); font-size: 11.5px; color: var(--text-3); background: rgba(255, 255, 255, .04); border-radius: 12px; padding: 8px 10px 8px 12px; word-break: break-all; }
+.pp button { margin-left: auto; background: none; border: 0; color: var(--text-3); cursor: pointer; padding: 4px; display: grid; border-radius: 8px; transition: background .2s var(--ease), color .2s var(--ease); }
+.pp button:hover { color: var(--text); background: rgba(255, 255, 255, .08); }
+.actions { display: flex; gap: 6px; margin-top: 14px; flex-wrap: wrap; }
+.actions .btn { height: 34px; }
+.stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
+.stats div { background: rgba(255, 255, 255, .04); border-radius: 14px; padding: 10px 12px; }
+.stats b { display: block; font-size: 17px; font-weight: 600; font-variant-numeric: tabular-nums; letter-spacing: -.01em; }
+.stats span { font-size: 12px; color: var(--text-3); }
+.bar { display: flex; height: 6px; border-radius: 999px; overflow: hidden; margin: 14px 0 10px; gap: 3px; }
+.bar span { border-radius: 999px; }
+.legend-row { display: flex; flex-wrap: wrap; gap: 4px 14px; font-size: 12px; color: var(--text-2); }
+.legend-row span { display: inline-flex; align-items: center; gap: 6px; }
+.dot { width: 8px; height: 8px; border-radius: 999px; display: inline-block; flex: none; }
+.list { display: flex; flex-direction: column; gap: 2px; margin: 0 -10px; }
+.row { display: flex; align-items: flex-start; gap: 12px; padding: 9px 10px; border-radius: 14px; cursor: pointer; text-decoration: none; color: inherit; transition: background .15s var(--ease); }
+.row:hover { background: rgba(255, 255, 255, .06); }
+.row .dot { margin-top: 6px; }
+.row .rt { flex: 1; min-width: 0; }
+.row .rn { font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row .rd { color: var(--text-3); font-size: 12.5px; line-height: 1.45; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; margin-top: 1px; }
+.row .rp { font-family: var(--mono); font-size: 11.5px; color: var(--text-3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row .rc { font-size: 12px; color: var(--text-3); white-space: nowrap; font-variant-numeric: tabular-nums; }
+.more { color: var(--text-4); font-size: 12.5px; padding: 6px 10px; }
+.tags { display: flex; flex-wrap: wrap; gap: 6px; }
+.tag { font-family: var(--mono); font-size: 11.5px; color: var(--text-2); background: rgba(255, 255, 255, .05); border-radius: 999px; padding: 3px 10px; }
+.callout { margin-top: 14px; padding: 11px 13px; border-radius: 14px; background: rgba(240, 195, 107, .08); color: #f3d79b; font-size: 13px; line-height: 1.55; }
+
+/* ---------- command palette ---------- */
+#palette { position: fixed; inset: 0; z-index: 40; background: rgba(0, 0, 0, .45); backdrop-filter: blur(4px); display: none; align-items: flex-start; justify-content: center; padding-top: 14vh; }
+#palette.open { display: flex; animation: fadeIn .2s var(--ease); }
+#palette .box { width: min(640px, calc(100% - 32px)); overflow: hidden; border-radius: var(--r-panel); animation: menuIn .3s var(--ease); background: rgba(30, 30, 30, .96); }
+#palette .in { display: flex; align-items: center; gap: 12px; padding: 0 20px; color: var(--text-3); }
+#palette input { flex: 1; height: 58px; background: none; border: 0; outline: none; font-size: 16px; color: var(--text); }
+#results { max-height: 52vh; overflow: auto; padding: 0 8px 8px; }
+#results .r { display: flex; gap: 12px; align-items: center; padding: 10px 12px; border-radius: 14px; cursor: pointer; }
+#results .r.active { background: rgba(255, 255, 255, .07); }
+#results .r .rt { flex: 1; min-width: 0; }
+#results .r .rn { font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#results .r .rd { color: var(--text-3); font-size: 12.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#results .r .rk { font-size: 12px; color: var(--text-4); white-space: nowrap; max-width: 200px; overflow: hidden; text-overflow: ellipsis; }
+#results .empty { padding: 22px; color: var(--text-3); text-align: center; }
+#palette .hint { display: flex; gap: 16px; padding: 12px 20px; color: var(--text-4); font-size: 12px; background: rgba(255, 255, 255, .02); }
+
+/* ---------- ask ---------- */
+#ask { position: absolute; left: calc((100% - var(--pw)) / 2); bottom: 20px; transform: translateX(-50%); width: min(700px, calc(100% - var(--pw) - 320px)); min-width: 320px; z-index: 4; display: flex; flex-direction: column; gap: 10px; transition: left .45s var(--ease), width .45s var(--ease); }
+#ask-form { display: flex; align-items: center; gap: 10px; padding: 8px 8px 8px 18px; border-radius: 28px; transition: box-shadow .25s var(--ease); flex-wrap: wrap; }
+#ask-form:focus-within { box-shadow: 0 0 0 1px rgba(255, 255, 255, .16), 0 24px 64px -24px rgba(0, 0, 0, .9); }
+#ask-chips { display: contents; }
+.chip { display: inline-flex; align-items: center; gap: 7px; height: 30px; padding: 0 6px 0 8px; border-radius: 999px; background: rgba(255, 255, 255, .08); font-size: 12.5px; max-width: 220px; animation: chipIn .3s var(--ease); }
+@keyframes chipIn { from { opacity: 0; transform: scale(.9); } }
+.chip .ico { width: 20px; height: 20px; border-radius: 999px; }
+.chip .ico svg { width: 11px; height: 11px; }
+.chip span { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.chip button { border: 0; background: none; color: var(--text-3); cursor: pointer; width: 20px; height: 20px; border-radius: 999px; display: grid; place-items: center; flex: none; }
+.chip button:hover { background: rgba(255, 255, 255, .1); color: var(--text); }
+#ask-input { flex: 1; min-width: 160px; height: 38px; background: none; border: 0; outline: none; font-size: 15px; color: var(--text); }
+#ask-input::placeholder { color: var(--text-3); }
+#ask-input:disabled { cursor: not-allowed; }
+.engine { font-size: 12px; color: var(--text-3); background: rgba(255, 255, 255, .05); border-radius: 999px; padding: 4px 10px; white-space: nowrap; display: inline-flex; align-items: center; gap: 7px; }
+.engine i { width: 6px; height: 6px; border-radius: 50%; background: var(--text-4); }
+.engine.ok i { background: #6fd7a8; box-shadow: 0 0 8px rgba(111, 215, 168, .8); }
+.engine.warn { color: #f3d79b; background: rgba(240, 195, 107, .1); }
+.engine.warn i { background: #f0c36b; }
+.einfo { background: none; border: 0; padding: 0; margin-left: 1px; color: var(--text-3); cursor: pointer; display: grid; }
+.einfo:hover { color: var(--text); }
+.einfo svg { width: 14px; height: 14px; }
+#ask-send { width: 38px; height: 38px; border-radius: 999px; border: 0; background: #ececec; color: #0f0f0f; cursor: pointer; display: grid; place-items: center; flex: none; transition: transform .2s var(--ease), background .2s var(--ease), opacity .2s; }
+#ask-send:hover:not(:disabled) { transform: scale(1.06); background: #fff; }
+#ask-send:disabled { background: rgba(255, 255, 255, .1); color: var(--text-4); cursor: default; }
+#ask-send.stop { background: rgba(255, 255, 255, .14); color: var(--text); }
+#ask-warn { display: flex; align-items: center; gap: 12px; padding: 12px 14px 12px 16px; border-radius: 20px; font-size: 13px; line-height: 1.5; color: #f3d79b; background: rgba(46, 38, 18, .9); backdrop-filter: blur(16px); animation: sheetIn .35s var(--ease); }
+#ask-warn[hidden] { display: none; }
+#ask-warn.info { color: var(--text-2); background: var(--elev); box-shadow: var(--shadow-float); }
+#ask-warn code { font-family: var(--mono); font-size: 12px; background: rgba(0, 0, 0, .3); padding: 1px 7px; border-radius: 7px; color: var(--text); }
+#ask-warn.info code { background: rgba(255, 255, 255, .07); }
+#ask-warn a { color: inherit; text-underline-offset: 3px; }
+#ask-warn.info a { color: var(--text); }
+#ask-warn button { margin-left: auto; background: rgba(255, 255, 255, .08); border: 0; color: inherit; border-radius: 999px; padding: 6px 12px; cursor: pointer; font-size: 12.5px; white-space: nowrap; }
+#ask-warn button:hover { background: rgba(255, 255, 255, .14); }
+#ask-sheet { max-height: min(46vh, 480px); display: flex; flex-direction: column; overflow: hidden; border-radius: var(--r-panel); animation: sheetIn .45s var(--ease); }
+@keyframes sheetIn { from { opacity: 0; transform: translateY(12px) scale(.985); } }
+#ask-sheet[hidden] { display: none; }
+#ask-sheet .sh { display: flex; align-items: center; gap: 6px; padding: 12px 12px 4px 20px; }
+#ask-sheet .sh .q { flex: 1; min-width: 0; color: var(--text-3); font-size: 13px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+#ask-sheet .sh .btn { height: 32px; }
+#ask-sheet .sb { padding: 6px 20px 18px; overflow: auto; line-height: 1.65; color: var(--text); font-size: 14px; }
+#ask-sheet .sb p { margin: 0 0 10px; }
+#ask-sheet .sb ul, #ask-sheet .sb ol { margin: 0 0 10px; padding-left: 20px; }
+#ask-sheet .sb li { margin: 3px 0; }
+#ask-sheet .sb code { font-family: var(--mono); font-size: 12.5px; background: rgba(255, 255, 255, .07); padding: 1px 6px; border-radius: 6px; }
+#ask-sheet .sb strong { font-weight: 600; }
+.ref { display: inline-flex; align-items: center; gap: 6px; padding: 0 9px 0 7px; border-radius: 999px; background: rgba(255, 255, 255, .08); color: var(--text); cursor: pointer; font-weight: 500; font-size: 13px; line-height: 23px; white-space: nowrap; vertical-align: 1px; transition: background .2s var(--ease); }
+.ref:hover { background: rgba(255, 255, 255, .15); }
+.ref i { width: 7px; height: 7px; border-radius: 999px; background: var(--c); }
+.progress { display: flex; flex-direction: column; gap: 7px; font-size: 13px; color: var(--text-3); }
+.progress div { display: flex; align-items: center; gap: 10px; animation: chipIn .3s var(--ease); }
+.progress div:last-child { color: var(--text); }
+.spin { width: 13px; height: 13px; border-radius: 50%; border: 2px solid rgba(255, 255, 255, .15); border-top-color: #ececec; animation: spin .8s linear infinite; flex: none; }
+@keyframes spin { to { transform: rotate(360deg); } }
+.followups { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+.followups button { background: rgba(255, 255, 255, .06); border: 0; color: var(--text-2); border-radius: 999px; padding: 7px 13px; cursor: pointer; font-size: 12.5px; text-align: left; transition: background .2s var(--ease), color .2s var(--ease); }
+.followups button:hover { background: rgba(255, 255, 255, .11); color: var(--text); }
+.sheet-actions { display: flex; gap: 6px; margin-top: 12px; flex-wrap: wrap; }
+.err { color: #f6a5a5; }
+
+/* ---------- extension chrome: header slot, modal, toast, grouped lists ---------- */
+.hr-ext { display: contents; }
+#modal { position: fixed; inset: 0; z-index: 45; background: rgba(0, 0, 0, .5); backdrop-filter: blur(4px); display: none; align-items: center; justify-content: center; padding: 24px; }
+#modal.open { display: flex; animation: fadeIn .2s var(--ease); }
+#modal .box { width: min(620px, 100%); max-height: min(80vh, 760px); overflow: auto; border-radius: var(--r-panel); background: rgba(30, 30, 30, .97); animation: menuIn .3s var(--ease); padding: 22px 24px 20px; }
+#modal h2 { margin: 0 0 8px; font-size: 18px; font-weight: 600; letter-spacing: -.015em; }
+#modal .mb { color: var(--text-2); line-height: 1.6; }
+#modal pre { white-space: pre-wrap; word-break: break-word; font-family: var(--mono); font-size: 12px; line-height: 1.55; background: rgba(255, 255, 255, .05); border-radius: 14px; padding: 14px 16px; color: var(--text); margin: 12px 0 0; max-height: 46vh; overflow: auto; }
+#modal .ma { display: flex; justify-content: flex-end; gap: 8px; margin-top: 18px; flex-wrap: wrap; }
+#toast { position: fixed; left: calc((100% - var(--pw)) / 2); bottom: 96px; transform: translateX(-50%); z-index: 50; padding: 10px 16px; border-radius: 999px; font-size: 13px; pointer-events: none; opacity: 0; transition: opacity .25s var(--ease), transform .3s var(--ease); }
+#toast.on { opacity: 1; transform: translateX(-50%) translateY(-4px); }
+.group-h { display: flex; align-items: baseline; gap: 8px; margin: 14px 0 4px; font-size: 12.5px; color: var(--text-2); font-weight: 500; }
+.group-h:first-of-type { margin-top: 2px; }
+.group-h .gd { color: var(--text-4); font-weight: 400; font-size: 12px; }
+#legend .tech { border-top: 1px solid var(--hair); margin-top: 4px; padding-top: 4px; }
+</style>
+</head>
+<body>
+<div id="stage">
+ <svg id="svg" xmlns="http://www.w3.org/2000/svg"><g id="viewport"></g></svg>
+ <div id="context"></div>
+ <div id="zoom" class="glass">
+ <button id="z-out" title="Zoom out (−)"><svg class="i" viewBox="0 0 24 24"><path d="M5 12h14"/></svg></button>
+ <button id="z-fit" title="Fit to screen (F)"><svg class="i" viewBox="0 0 24 24"><path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/></svg></button>
+ <button id="z-in" title="Zoom in (+)"><svg class="i" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg></button>
+ </div>
+ <div id="flowbar" class="glass" hidden></div>
+ <div id="ask">
+ <div id="ask-sheet" class="glass" hidden></div>
+ <div id="ask-warn" hidden></div>
+ <form id="ask-form" class="glass" autocomplete="off">
+ <span id="ask-chips"></span>
+ <input id="ask-input" placeholder="Ask anything about this codebase…" spellcheck="false">
+ <span class="engine" id="ask-engine"><i></i>checking…</span>
+ <button id="ask-send" type="submit" title="Ask" disabled><svg class="i" viewBox="0 0 24 24"><path d="M12 19V5M5 12l7-7 7 7"/></svg></button>
+ </form>
+ </div>
+ <div id="tooltip" class="glass" hidden></div>
+ <div id="loading" class="glass">Laying out…</div>
+ <div id="empty" hidden></div>
+</div>
+<header>
+ <div class="hl">
+ <div class="brand"><img class="mark" src="__FLOORPLAN_LOGO__" alt="Floorplan" title="Floorplan"><span id="proj-name"></span></div>
+ <button class="btn icon" id="btn-up" title="Up one level (Backspace)" hidden><svg class="i" viewBox="0 0 24 24"><path d="M19 12H5M11 18l-6-6 6-6"/></svg></button>
+ <nav id="crumbs"></nav>
+ </div>
+ <div class="hc">
+ <button class="btn" id="search-btn"><svg class="i" viewBox="0 0 24 24"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg>Search files, routes, modules<span class="kbd">/</span></button>
+ </div>
+ <div class="hr">
+ <div id="hdr-ext" class="hr-ext"></div>
+ <div class="rel"><button class="btn" id="flows-btn"><svg class="i" viewBox="0 0 24 24"><path d="M7 5v14l11-7z"/></svg>Flows</button><div id="flowmenu" class="menu glass"></div></div>
+ <div class="rel"><button class="btn icon" id="filters-btn" title="Connection types"><svg class="i" viewBox="0 0 24 24"><path d="M4 6h16M7 12h10M10 18h4"/></svg></button><div id="legend" class="menu glass"></div></div>
+ <button class="btn icon" id="btn-panel" title="Toggle details (P)"><svg class="i" viewBox="0 0 24 24"><rect x="3" y="4" width="18" height="16" rx="3"/><path d="M15 4v16"/></svg></button>
+ </div>
+</header>
+<aside id="panel"></aside>
+<div id="panel-resize" title="Drag to resize"></div>
+<div id="ctxmenu" class="menu glass" hidden></div>
+<div id="modal"><div class="box glass"></div></div>
+<div id="toast" class="glass"></div>
+<div id="palette"><div class="box glass">
+ <div class="in"><svg class="i" viewBox="0 0 24 24"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg><input id="search" placeholder="Search by name, description, path or route…" autocomplete="off" spellcheck="false"></div>
+ <div id="results"></div>
+ <div class="hint"><span><span class="kbd">↑↓</span> navigate</span><span><span class="kbd">↵</span> open</span><span><span class="kbd">esc</span> close</span></div>
+</div></div>
+<!--__ELK_SCRIPT__-->
+<script>window.FLOORPLAN = /*__FLOORPLAN_DATA__*/null;</script>
+<script>/*__GRAPH_QUERY__*/</script>
+<script>
+(() => {
+'use strict';
+const G = window.FLOORPLAN;
+if (!G) { document.body.innerHTML = '<p style="padding:2rem">No data. Run build.mjs.</p>'; return; }
+if (typeof ELK === 'undefined') { document.body.innerHTML = '<p style="padding:2rem">Could not load the ELK layout engine. It loads from a CDN; vendor elk.bundled.js into the skill\'s assets/vendor/ to work offline.</p>'; return; }
+
+const NS = 'http://www.w3.org/2000/svg';
+const $ = (s) => document.querySelector(s);
+const svg = $('#svg'), vp = $('#viewport'), panel = $('#panel');
+const elk = new ELK();
+const KINDS = ['import', 'http', 'call', 'rpc', 'event', 'queue', 'data', 'config'];
+// connection names: plain by default, developer terms when "Show technical detail" is on
+const KIND_TECH = { contains: 'Contains', import: 'Imports', http: 'HTTP', call: 'Calls', rpc: 'RPC', event: 'Events', queue: 'Queues', data: 'Data', config: 'Config' };
+const KIND_PLAIN = { contains: 'Contains', import: 'Uses', http: 'Web requests', call: 'Calls', rpc: 'Calls', event: 'Events', queue: 'Background jobs', data: 'Reads & writes data', config: 'Settings' };
+const KIND_LABEL = new Proxy({}, { get: (_, k) => (technical() ? KIND_TECH : KIND_PLAIN)[k] || k });
+let technicalFlag = false;
+const technical = () => technicalFlag;
+const METHODS = { GET: 1, POST: 1, PUT: 1, PATCH: 1, DELETE: 1 };
+const store = { get(k, d) { try { return JSON.parse(localStorage.getItem('floorplan:' + k) ?? localStorage.getItem('show-code:' + k)) ?? d; } catch { return d; } }, set(k, v) { try { localStorage.setItem('floorplan:' + k, JSON.stringify(v)); } catch {} } };
+const h = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const fmt = (n) => n >= 10000 ? Math.round(n / 1000) + 'k' : n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n);
+const dirname = (p) => p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '';
+const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+function el(tag, attrs = {}, parent) {
+ const e = document.createElementNS(NS, tag);
+ for (const [k, v] of Object.entries(attrs)) if (v !== undefined && v !== null) e.setAttribute(k, v);
+ if (parent) parent.appendChild(e);
+ return e;
+}
+
+// ---------- icons ----------
+const P = {
+ ui: '<rect x="3" y="4" width="18" height="12" rx="2"/><path d="M8 20h8M12 16v4"/>',
+ service: '<rect x="3" y="4" width="18" height="7" rx="2"/><rect x="3" y="13" width="18" height="7" rx="2"/><path d="M7 7.5h.01M7 16.5h.01"/>',
+ worker: '<path d="M13 2 4 14h7l-1 8 9-12h-7z"/>',
+ library: '<path d="M21 8 12 3 3 8v8l9 5 9-5z"/><path d="m3 8 9 5 9-5M12 13v8"/>',
+ feature: '<path d="m12 3 9 5-9 5-9-5z"/><path d="m3 13 9 5 9-5"/>',
+ data: '<ellipse cx="12" cy="5" rx="8" ry="3"/><path d="M4 5v14c0 1.7 3.6 3 8 3s8-1.3 8-3V5"/><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3"/>',
+ config: '<path d="M4 6h9M17 6h3M4 12h3M11 12h9M4 18h11M19 18h1"/><circle cx="15" cy="6" r="2"/><circle cx="9" cy="12" r="2"/><circle cx="17" cy="18" r="2"/>',
+ test: '<path d="M9 3h6M10 3v6L4.5 19a1.5 1.5 0 0 0 1.3 2h12.4a1.5 1.5 0 0 0 1.3-2L14 9V3"/><path d="M7 15h10"/>',
+ script: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="m7 9 3 3-3 3M13 15h4"/>',
+ infra: '<path d="M7 18h10a4 4 0 0 0 .5-8 6 6 0 0 0-11.5 1.5A3.5 3.5 0 0 0 7 18z"/>',
+ external: '<circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c2.5 2.7 3.5 5.7 3.5 9s-1 6.3-3.5 9c-2.5-2.7-3.5-5.7-3.5-9s1-6.3 3.5-9z"/>',
+ misc: '<circle cx="12" cy="12" r="8" stroke-dasharray="3 3"/>',
+ dir: '<path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>',
+ file: '<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5M10 13l-2 2 2 2M14 13l2 2-2 2"/>',
+ module: '<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/>',
+ function: '<path d="M10 20c2 0 2.5-1.5 3-4l2-9c.5-2.5 1-4 3-4M8 10h8"/>',
+ class: '<rect x="4" y="4" width="16" height="16" rx="3"/><path d="M14.5 9.5a3.5 3.5 0 1 0 0 5"/>',
+ route: '<path d="M4 12h12M12 6l6 6-6 6"/><path d="M20 5v14"/>',
+ in: '<path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4M10 17l5-5-5-5M15 12H3"/>',
+ out: '<path d="M7 17 17 7M8 7h9v9"/>',
+ open: '<path d="M15 3h6v6M10 14 21 3M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/>',
+ drill: '<path d="M9 18l6-6-6-6"/>',
+ copy: '<rect x="9" y="9" width="12" height="12" rx="3"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/>',
+ spark: '<path d="M12 3.5 13.8 9a2 2 0 0 0 1.2 1.2l5.5 1.8-5.5 1.8a2 2 0 0 0-1.2 1.2L12 20.5 10.2 15A2 2 0 0 0 9 13.8L3.5 12 9 10.2A2 2 0 0 0 10.2 9z"/>',
+ panel: '<rect x="3" y="4" width="18" height="16" rx="3"/><path d="M15 4v16"/>',
+ fit: '<path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/>',
+ home: '<path d="m3 11 9-7 9 7"/><path d="M5 10v10h14V10"/>',
+ search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
+ x: '<path d="M18 6 6 18M6 6l12 12"/>',
+ left: '<path d="m15 18-6-6 6-6"/>',
+ right: '<path d="m9 18 6-6-6-6"/>',
+};
+const icon = (k) => `<svg viewBox="0 0 24 24">${P[k] || P.file}</svg>`;
+const iconI = (k) => `<svg class="i" viewBox="0 0 24 24">${P[k] || P.file}</svg>`;
+const symIcon = (kind) => (['class', 'interface', 'struct', 'type', 'enum', 'record', 'trait', 'object'].includes(kind) ? 'class' : 'function');
+
+// ======================= model =======================
+const nodes = new Map(G.nodes.map((n) => [n.id, n]));
+const files = new Map(G.files.map((f) => [f.p, f]));
+const routes = G.routes || [];
+const parentOf = new Map();
+const kids = new Map();
+const addChild = (p, item) => { parentOf.set(item, p); if (!kids.has(p)) kids.set(p, []); kids.get(p).push(item); };
+const dirs = new Map();
+
+for (const n of G.nodes) addChild(n.parent ? 'n:' + n.parent : 'root', 'n:' + n.id);
+const filesByNode = new Map();
+for (const f of G.files) { if (!filesByNode.has(f.n)) filesByNode.set(f.n, []); filesByNode.get(f.n).push(f); }
+const GROUP_AT = 24;
+for (const [nid, list] of filesByNode) {
+ const parent = 'n:' + nid;
+ if (list.length <= GROUP_AT) { list.forEach((f) => addChild(parent, 'f:' + f.p)); continue; }
+ const dirsOf = list.map((f) => dirname(f.p).split('/'));
+ let common = dirsOf[0].slice();
+ for (const d of dirsOf) { let i = 0; while (i < common.length && d[i] === common[i]) i++; common = common.slice(0, i); }
+ const groups = new Map();
+ list.forEach((f, i) => {
+ const seg = dirsOf[i][common.length];
+ const key = seg === undefined ? '' : [...common, seg].join('/');
+ if (!groups.has(key)) groups.set(key, []);
+ groups.get(key).push(f);
+ });
+ for (const [key, fs] of groups) {
+ if (!key || fs.length < 2) { fs.forEach((f) => addChild(parent, 'f:' + f.p)); continue; }
+ const did = `d:${nid}|${key}`;
+ dirs.set(did, { node: nid, path: key, files: fs });
+ addChild(parent, did);
+ fs.forEach((f) => addChild(did, 'f:' + f.p));
+ }
+}
+// inside a file: its endpoints, then the exports that aren't route handlers
+const routesByFile = new Map();
+routes.forEach((r, i) => { if (!routesByFile.has(r.f)) routesByFile.set(r.f, []); routesByFile.get(r.f).push(i); });
+for (const f of G.files) {
+ const rs = routesByFile.get(f.p) || [];
+ const handlers = new Set(rs.map((i) => routes[i].h));
+ rs.forEach((i) => addChild('f:' + f.p, 'r:' + i));
+ (f.s || []).forEach((s, i) => { if (!handlers.has(s[0])) addChild('f:' + f.p, `s:${f.p}#${i}`); });
+}
+
+const chainCache = new Map();
+function chain(item) {
+ if (chainCache.has(item)) return chainCache.get(item);
+ const out = [item];
+ let p = parentOf.get(item);
+ while (p && p !== 'root') { out.push(p); p = parentOf.get(p); }
+ if (item !== 'root') out.push('root');
+ chainCache.set(item, out);
+ return out;
+}
+// Recent work (G.recent): the cards Claude just changed, and how many changes sit inside each part
+const recentTasks = G.recent?.tasks || [];
+const recentBy = new Map();
+for (const it of G.recent?.items || []) { if (!parentOf.has(it.id)) continue; if (!recentBy.has(it.id)) recentBy.set(it.id, []); recentBy.get(it.id).push(it); }
+const recentIn = new Map();
+for (const id of recentBy.keys()) for (const a of chain(id).slice(1)) if (a !== 'root') { if (!recentIn.has(a)) recentIn.set(a, []); recentIn.get(a).push(id); }
+const recentOf = (item) => recentBy.get(item.startsWith('m:') ? 'f:' + item.slice(2) : item);
+const recentLabel = (list) => (list.some((x) => x.change === 'new') ? 'New' : 'Changed');
+let recentShown = !!store.get('recent-hl', true);
+const setRecentShown = (on) => { recentShown = on; store.set('recent-hl', on); document.body.classList.toggle('no-recent', !on); };
+document.body.classList.toggle('no-recent', !recentShown);
+const symOf = (item) => { const m = /^s:(.*)#(\d+)$/.exec(item); const f = files.get(m[1]); return { f, s: f.s[+m[2]] }; };
+function humanize(s) { s = s.replace(/[_\-.]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2').trim(); return s.charAt(0).toUpperCase() + s.slice(1); }
+
+function info(item) {
+ if (item === 'root') return { type: 'root', name: G.project.name, desc: G.project.summary || '', kind: 'root' };
+ if (item === 'q:answer') return { type: 'answer', name: state.answer?.title || 'Answer', desc: state.answer?.question || '', kind: 'answer' };
+ const t = item.slice(0, 2);
+ if (t === 'n:') { const n = nodes.get(item.slice(2)); return { type: 'node', name: n.label, desc: n.summary, kind: n.kind, n }; }
+ if (t === 'd:') { const d = dirs.get(item); return { type: 'dir', name: humanize(d.path.split('/').pop()), desc: `${plural(d.files.length, 'file')} in ${d.path}/`, kind: 'dir', d, path: d.path + '/' }; }
+ if (t === 'f:') { const f = files.get(item.slice(2)); return { type: 'file', name: f.name, desc: f.d, kind: 'file', f, path: f.p }; }
+ if (t === 'm:') { const f = files.get(item.slice(2)); return { type: 'module', name: f.name, desc: f.d, kind: 'module', f, path: f.p }; }
+ if (t === 'r:') { const r = routes[+item.slice(2)]; return { type: 'route', name: r.name, desc: r.d, kind: 'route', r, f: files.get(r.f), path: `${r.m} ${r.p}` }; }
+ if (t === 's:') { const { f, s } = symOf(item); return { type: 'symbol', name: s[0], desc: s[4] || '', kind: symIcon(s[1]), symKind: s[1], f, s, path: `${f.p}:${s[2]}` }; }
+ return { type: 'unknown', name: item, desc: '', kind: 'misc' };
+}
+const connEntity = (id) => id.replace(/^x:(in|out):/, '');
+const nameOf = (item) => info(item.startsWith('x:') ? connEntity(item) : item).name;
+// in plain mode a file opens only when it has endpoints to show (its exports are developer detail)
+const visibleKids = (item) => (kids.get(item) || []).filter((k) => technical() || !k.startsWith('s:'));
+const drillable = (item) => /^(n:|d:|f:)/.test(item) && visibleKids(item).length > 0;
+const methodVar = (m) => `var(--m-${m in METHODS ? m : 'ANY'})`;
+const colorOf = (i) => i.type === 'route' ? methodVar(i.r.m) : `var(--n-${i.type === 'node' ? i.kind : i.type === 'symbol' ? 'symbol' : i.type})`;
+const iconKey = (i) => i.type === 'node' ? i.kind : i.type === 'symbol' ? i.kind : i.type;
+
+function statsOf(item) {
+ const i = info(item);
+ if (i.type === 'node') return i.n.stats;
+ if (i.type === 'dir') return { files: i.d.files.length, loc: i.d.files.reduce((s, f) => s + f.loc, 0) };
+ if (i.type === 'file' || i.type === 'module') return { files: 1, loc: i.f.loc };
+ return null;
+}
+const nodePaths = (n) => n.paths?.length ? n.paths[0].replace(/\/\*\*$/, '') + (n.paths.length > 1 ? ` +${n.paths.length - 1}` : '') : n.hosts?.[0] || n.packages?.[0] || '';
+
+// ======================= view projection =======================
+const state = { container: 'root', selected: null, kinds: Object.fromEntries(KINDS.map((k) => [k, true])), t: { x: 0, y: 0, k: 1 }, layout: null, flow: null };
+
+function project(item, ctx) {
+ const ch = chain(item);
+ for (const x of ch) { if (ctx.vis.has(x)) return { item: x }; if (x === ctx.container) return null; }
+ if (ctx.cchain.has(item)) return null;
+ const idx = ch.findIndex((x) => ctx.cchain.has(x));
+ return { outside: ch[idx - 1] };
+}
+/** The visible export whose definition most closely precedes a line (the caller of an HTTP request). */
+function enclosingSymbol(f, line) {
+ let best = null;
+ (f.s || []).forEach((s, i) => { if (s[2] <= line && (!best || s[2] > best.line)) best = { line: s[2], id: `s:${f.p}#${i}` }; });
+ return best && parentOf.has(best.id) ? best.id : null;
+}
+
+/** An answer's ad-hoc board: just the cards Claude picked, and every connection among them. */
+function buildAnswerView() {
+ const visible = state.answer.items.map((x) => x.id);
+ const vis = new Set(visible);
+ const up = (x) => { for (const y of chain(x)) if (vis.has(y)) return y; return null; };
+ // a file that isn't on the board but some of its endpoints/exports are: route to those instead
+ const down = (x, names) => {
+ if (!x.startsWith('f:')) return [];
+ const inside = visible.filter((v) => v !== x && chain(v).includes(x));
+ if (!names?.length) return inside;
+ const f = files.get(x.slice(2));
+ const byName = inside.filter((v) => v.startsWith('s:') && names.some((nm) => { const s = symOf(v).s; return nm === s[0] || (nm === 'default' && s[3]); }));
+ return byName.length ? byName : inside;
+ };
+ const proj = (x, names) => { const u = up(x); return u ? [u] : down(x, names); };
+ // one hidden hop: a screen that reaches a request through an API-client file that isn't on the board
+ const importersOf = new Map();
+ for (const l of G.links) if (l.k === 'import' && l.b.startsWith('f:')) { if (!importersOf.has(l.b)) importersOf.set(l.b, []); importersOf.get(l.b).push(l.a); }
+ const viaHidden = (x) => [...new Set((importersOf.get(x) || []).map(up).filter(Boolean))];
+ const agg = new Map();
+ const add = (a, b, l, w) => {
+ const key = `${a}>${b}>${l.k}`;
+ let e = agg.get(key);
+ if (!e) { e = { id: 'e' + agg.size, a, b, k: l.k, w: 0, links: [] }; agg.set(key, e); }
+ e.w += w; if (!e.links.includes(l)) e.links.push(l);
+ };
+ for (const l of G.links) {
+ if (!state.kinds[l.k]) continue;
+ let srcs = proj(l.a), dsts = proj(l.b, l.names);
+ if (!srcs.length && l.k === 'http' && l.a.startsWith('f:') && dsts.length) srcs = viaHidden(l.a);
+ if (l.calls?.length) {
+ const rs = [...new Set(l.calls.map(([ri]) => ri))].filter((ri) => ri != null && vis.has('r:' + ri)).map((ri) => 'r:' + ri);
+ if (rs.length) dsts = rs;
+ const f = l.a.startsWith('f:') ? files.get(l.a.slice(2)) : null;
+ const syms = f ? [...new Set(l.calls.map(([, line]) => enclosingSymbol(f, line)).filter((s) => s && vis.has(s)))] : [];
+ if (syms.length) srcs = syms;
+ }
+ for (const s of srcs) for (const d of dsts) if (s !== d && !chain(d).includes(s) && !chain(s).includes(d)) add(s, d, l, l.calls?.length ? l.calls.length : l.w);
+ }
+ // show containment (a file and its endpoint both on the board) as a faint line
+ const containsLink = { k: 'contains', w: 1, a: '', b: '' };
+ for (const v of visible) { const p = chain(v).slice(1).find((y) => vis.has(y)); if (p) add(p, v, containsLink, 1); }
+ return { container: 'q:answer', visible, connectors: [], edges: [...agg.values()], hidden: 0 };
+}
+const answerNote = (item) => {
+ if (state.container !== 'q:answer' || !state.answer) return null;
+ const i = state.answer.items.findIndex((x) => x.id === item);
+ return i < 0 || !state.answer.items[i].note ? null : { n: i + 1, text: state.answer.items[i].note };
+};
+
+function buildView(container) {
+ if (container === 'q:answer') return buildAnswerView();
+ const isFile = container.startsWith('f:');
+ const visible = visibleKids(container).slice();
+ if (isFile) visible.unshift('m:' + container.slice(2));
+ const ctx = { container, vis: new Set(visible), cchain: new Set(chain(container)) };
+ const agg = new Map(), connectors = new Map();
+ const add = (a, b, l, w = l.w) => {
+ const key = `${a}>${b}>${l.k}`;
+ let e = agg.get(key);
+ if (!e) { e = { id: 'e' + agg.size, a, b, k: l.k, w: 0, links: [] }; agg.set(key, e); }
+ e.w += w; if (!e.links.includes(l)) e.links.push(l);
+ };
+ const conn = (side, entity) => { const id = `x:${side}:${entity}`; if (!connectors.has(id)) connectors.set(id, { id, side, entity }); return id; };
+
+ for (const l of G.links) {
+ if (!state.kinds[l.k]) continue;
+ if (isFile) {
+ const fid = container, f = files.get(fid.slice(2));
+ if (l.b === fid && l.a !== fid) {
+ const pa = project(l.a, ctx); if (!pa?.outside) continue;
+ const src = conn('in', pa.outside);
+ if (l.calls?.length) { let hit = false; for (const [ri] of l.calls) if (ri != null && ctx.vis.has('r:' + ri)) { add(src, 'r:' + ri, l, 1); hit = true; } if (!hit) add(src, 'm:' + f.p, l); continue; }
+ const targets = new Set();
+ for (const nm of l.names || []) { const i = (f.s || []).findIndex((s) => nm === 'default' ? s[3] : s[0] === nm); if (i >= 0 && ctx.vis.has(`s:${f.p}#${i}`)) targets.add(`s:${f.p}#${i}`); }
+ if (!targets.size) targets.add('m:' + f.p);
+ for (const t of targets) add(src, t, l);
+ } else if (l.a === fid && l.b !== fid) {
+ const pb = project(l.b, ctx); if (!pb?.outside) continue;
+ const dst = conn('out', pb.outside);
+ if (l.calls?.length) { for (const [, line] of l.calls) add(enclosingSymbol(f, line) || 'm:' + f.p, dst, l, 1); continue; }
+ add('m:' + f.p, dst, l);
+ }
+ continue;
+ }
+ const pa = project(l.a, ctx), pb = project(l.b, ctx);
+ if (!pa || !pb) continue;
+ if (pa.item && pb.item) { if (pa.item !== pb.item) add(pa.item, pb.item, l); }
+ else if (pa.item && pb.outside) add(pa.item, conn('out', pb.outside), l);
+ else if (pa.outside && pb.item) add(conn('in', pa.outside), pb.item, l);
+ }
+ const edges = [...agg.values()];
+ let hidden = 0;
+ if (isFile && visible.length > 22) {
+ const used = new Set(edges.flatMap((e) => [e.a, e.b]));
+ const keep = visible.filter((v) => v.startsWith('m:') || used.has(v));
+ hidden = visible.length - keep.length;
+ visible.length = 0; visible.push(...keep);
+ }
+ return { container, visible, connectors: [...connectors.values()], edges, hidden };
+}
+
+// ======================= cards =======================
+// Cards carry only what you read at a glance: icon, name, description, one count. Paths, kinds and
+// sizes live in the hover tooltip and the details panel.
+// [width, min height]
+const SIZES = { node: [300, 128], dir: [272, 110], file: [284, 110], module: [284, 110], route: [300, 128], symbol: [260, 100] };
+const NOTE_H = 64;
+const FOOT_H = 30; // the footer row: size on the left, recent-work pill on the right
+const TITLE2_H = 10; // a title that wraps onto a second line
+const GUTTER = 28; // room around each card for its shadow, selection ring and hover lift (matches --gutter)
+/** Footer pieces: the card's size (modules / files / endpoints) and its recent-work pill. Empty when neither applies. */
+function cardFoot(item) {
+ const i = info(item);
+ let size = '';
+ if (i.type === 'node' && i.n.kind !== 'external') { const sub = (kids.get(item) || []).filter((k) => k.startsWith('n:')).length; size = sub ? plural(sub, 'module') : plural(statsOf(item).files, 'file'); }
+ else if (i.type === 'dir') size = plural(statsOf(item).files, 'file');
+ else if (i.type === 'module') size = 'this file';
+ else if (i.type === 'file') { const nr = (routesByFile.get(i.f.p) || []).length; size = nr ? plural(nr, 'endpoint') : ''; }
+ const rec = recentOf(item), inside = recentIn.get(item.startsWith('m:') ? 'f:' + item.slice(2) : item);
+ const pill = rec ? `<span class="rw">${recentLabel(rec)}</span>` : inside ? `<span class="rw soft">${inside.length} changed</span>` : '';
+ return size || pill ? `<div class="foot">${size ? `<span class="meta">${size}</span>` : '<span></span>'}${pill}</div>` : '';
+}
+/** Extra height a card needs beyond its base size: a footer, and a title long enough to wrap. */
+function cardExtraH(item) {
+ const i = info(item);
+ const [w] = SIZES[i.type] || SIZES.file;
+ const name = i.type === 'route' ? i.r.name : i.type === 'symbol' ? i.s[0] : i.name;
+ const room = w - 36 - (i.type === 'route' ? 0 : 40); // padding, and the icon beside the title
+ return (cardFoot(item) ? FOOT_H : 0) + (textW(name, 15, 600) > room ? TITLE2_H : 0);
+}
+function cardHTML(item) {
+ const i = info(item);
+ let head = '', title = '', desc = '', cls = i.type;
+ const dsc = (t, lines = 2) => t ? `<div class="desc" style="--lines:${lines}">${h(t)}</div>` : `<div class="desc empty">No description yet</div>`;
+ if (i.type === 'node') {
+ const n = i.n;
+ if (n.kind === 'external') cls += ' external';
+ head = `<span class="ico">${icon(n.kind)}</span><div class="title">${h(n.label)}</div>`;
+ desc = dsc(n.summary, 3);
+ } else if (i.type === 'dir') {
+ head = `<span class="ico">${icon('dir')}</span><div class="title">${h(i.name)}</div>`;
+ desc = dsc(i.d.files.slice().sort((a, b) => b.loc - a.loc).slice(0, 4).map((f) => f.name).join(', ') + (i.d.files.length > 4 ? ', …' : ''), 2);
+ } else if (i.type === 'file' || i.type === 'module') {
+ const f = i.f;
+ if (f.note) cls += ' has-note';
+ head = `<span class="ico">${icon(i.type)}</span><div class="title">${h(f.name)}</div>`;
+ desc = dsc(f.d, 2);
+ } else if (i.type === 'route') {
+ const r = i.r;
+ head = `<span class="method" style="--m:${methodVar(r.m)}">${h(r.m)}</span><span class="rpath">${h(r.p)}</span>`;
+ title = `<div class="title">${h(r.name)}</div>`;
+ desc = dsc(r.d, 2);
+ } else if (i.type === 'symbol') {
+ head = `<span class="ico">${icon(i.kind)}</span><div class="title mono">${h(i.s[0])}</div>`;
+ desc = i.desc ? dsc(i.desc, 2) : '';
+ }
+ const note = answerNote(item);
+ const noteHTML = note ? `<div class="anote"><b>${note.n}</b><span>${h(note.text)}</span></div>` : '';
+ if (recentOf(item)) cls += ' recent';
+ else if (recentIn.get(item.startsWith('m:') ? 'f:' + item.slice(2) : item)) cls += ' recent-in';
+ return `<div class="card ${cls}" style="--c:${colorOf(i)}"><div class="head">${head}</div>${title}${desc}${noteHTML}${cardFoot(item)}</div>`;
+}
+function connectorHTML(c) {
+ const i = info(c.entity);
+ return `<div class="card connector" style="--c:${colorOf(i)}"><span class="ico">${icon(iconKey(i))}</span><span class="lbl">${h(i.name)}</span><span class="dir-ico">${icon(c.side === 'in' ? 'in' : 'out')}</span></div>`;
+}
+/** Hover tooltip for a card: what it is, where it lives, and what you can do with it. */
+function cardTip(id) {
+ if (id.startsWith('x:')) {
+ const i = info(connEntity(id));
+ return `<div class="tt">${id.startsWith('x:in') ? 'From' : 'To'} ${h(i.name)}</div>${i.desc ? `<div class="td">${h(i.desc)}</div>` : ''}<div class="th"><span><span class="kbd">2×click</span> go there</span><span><span class="kbd">right-click</span> more</span></div>`;
+ }
+ const i = info(id);
+ const st = statsOf(id);
+ const kind = i.type === 'node' ? i.kind : i.type === 'route' ? 'endpoint' : i.type === 'symbol' ? i.symKind : i.type === 'module' ? 'file' : i.type;
+ const where = i.type === 'node' ? (i.n.paths || []).join('\n') : i.type === 'route' ? `${i.f.p}${i.r.h ? ` · ${i.r.h}()` : ''}` : i.path || '';
+ const size = st?.files ? (i.type === 'file' || i.type === 'module' ? `${fmt(st.loc)} lines` : `${plural(st.files, 'file')} · ${fmt(st.loc)} lines`) : '';
+ const hints = [drillable(id) && state.container !== id ? '<span><span class="kbd">2×click</span> open</span>' : '', '<span><span class="kbd">right-click</span> more</span>'].join('');
+ return `<div class="tt">${h(i.name)}</div><div class="td" style="text-transform:capitalize">${h(kind)}${size ? ` · ${size}` : ''}</div>${where ? `<div class="tp">${h(where)}</div>` : ''}${recentTip(id)}<div class="th">${hints}</div>`;
+}
+/** Hover lines for recent work: what changed on this card and how it serves the request, or what changed inside it. */
+function recentTip(id) {
+ if (!recentShown) return '';
+ const key = id.startsWith('m:') ? 'f:' + id.slice(2) : id;
+ const task = (t) => h(recentTasks[t]?.title || 'Recent work');
+ const rec = recentBy.get(key);
+ if (rec) return rec.map((x) => `<div class="trw"><div class="trh">${x.change === 'new' ? 'New' : 'Changed'} · ${task(x.task)}</div>${x.note ? `<div class="trn">${h(x.note)}</div>` : ''}</div>`).join('');
+ const inside = recentIn.get(key);
+ if (!inside) return '';
+ const tasks = [...new Set(inside.flatMap((x) => recentBy.get(x).map((r) => r.task)))];
+ const names = inside.slice(0, 3).map((x) => info(x).name);
+ return `<div class="trw"><div class="trh">${inside.length} changed inside · ${tasks.map(task).join(', ')}</div><div class="trn">${h(names.join(', '))}${inside.length > 3 ? ` and ${inside.length - 3} more` : ''}</div></div>`;
+}
+
+// ======================= layout =======================
+const measure = document.createElement('canvas').getContext('2d');
+const textW = (s, px = 12, w = 500) => { measure.font = `${w} ${px}px Inter, system-ui, sans-serif`; return measure.measureText(s).width; };
+
+async function layout(view) {
+ const deg = new Map();
+ const bump = (id) => deg.set(id, (deg.get(id) || 0) + 1);
+ for (const e of view.edges) { bump(e.a); bump(e.b); }
+ const children = [];
+ for (const item of view.visible) {
+ const [w, hh] = SIZES[info(item).type] || SIZES.file;
+ const ext = item.startsWith('n:') && nodes.get(item.slice(2)).kind === 'external';
+ children.push({ id: item, width: w, height: Math.max(hh + cardExtraH(item) + (answerNote(item) ? NOTE_H : 0), (deg.get(item) || 0) * 7 + 28), ...(ext ? { layoutOptions: { 'elk.layered.layering.layerConstraint': 'LAST' } } : {}) });
+ }
+ for (const c of view.connectors) {
+ children.push({ id: c.id, width: clamp(textW(info(c.entity).name, 13) + 84, 150, 320), height: Math.max(42, (deg.get(c.id) || 0) * 7 + 14),
+ layoutOptions: { 'elk.layered.layering.layerConstraint': c.side === 'in' ? 'FIRST_SEPARATE' : 'LAST_SEPARATE' } });
+ }
+ return elk.layout({
+ id: 'g', children,
+ edges: view.edges.map((e) => ({ id: e.id, sources: [e.a], targets: [e.b] })),
+ layoutOptions: {
+ 'elk.algorithm': 'layered', 'elk.direction': 'RIGHT', 'elk.edgeRouting': 'ORTHOGONAL',
+ 'elk.layered.spacing.nodeNodeBetweenLayers': '130', 'elk.spacing.nodeNode': '32',
+ 'elk.layered.spacing.edgeEdgeBetweenLayers': '8', 'elk.spacing.edgeEdge': '8', 'elk.layered.spacing.edgeNodeBetweenLayers': '24',
+ 'elk.layered.nodePlacement.strategy': 'NETWORK_SIMPLEX', 'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+ 'elk.layered.thoroughness': '12', 'elk.separateConnectedComponents': 'true', 'elk.spacing.componentComponent': '80',
+ 'elk.padding': '[top=40,left=40,bottom=40,right=40]',
+ },
+ });
+}
+
+// ======================= render =======================
+function roundedPath(pts, r = 10) {
+ let d = `M${pts[0].x},${pts[0].y}`;
+ for (let i = 1; i < pts.length - 1; i++) {
+ const a = pts[i - 1], b = pts[i], c = pts[i + 1];
+ const d1 = Math.hypot(b.x - a.x, b.y - a.y), d2 = Math.hypot(c.x - b.x, c.y - b.y);
+ const rr = Math.min(r, d1 / 2, d2 / 2);
+ if (!rr) { d += `L${b.x},${b.y}`; continue; }
+ const p1 = { x: b.x + ((a.x - b.x) * rr) / d1, y: b.y + ((a.y - b.y) * rr) / d1 };
+ const p2 = { x: b.x + ((c.x - b.x) * rr) / d2, y: b.y + ((c.y - b.y) * rr) / d2 };
+ d += `L${p1.x.toFixed(1)},${p1.y.toFixed(1)}Q${b.x},${b.y} ${p2.x.toFixed(1)},${p2.y.toFixed(1)}`;
+ }
+ const z = pts[pts.length - 1];
+ return d + `L${z.x},${z.y}`;
+}
+
+let renderToken = 0;
+async function render(opts = {}) {
+ const token = ++renderToken;
+ const view = buildView(state.container);
+ const loading = setTimeout(() => $('#loading').classList.add('on'), 160);
+ let res;
+ try { res = await layout(view); }
+ catch (e) { console.error(e); clearTimeout(loading); $('#loading').classList.remove('on'); $('#empty').hidden = false; $('#empty').textContent = 'Layout failed: ' + e.message; return; }
+ clearTimeout(loading);
+ $('#loading').classList.remove('on');
+ if (token !== renderToken) return;
+ state.view = view; state.layout = res;
+ queueMicrotask(() => emit('render', { container: state.container, view }));
+ draw(view, res);
+ renderContext(); renderCrumbs(); renderLegend(view);
+ $('#empty').hidden = view.visible.length > 0;
+ $('#empty').textContent = view.visible.length ? '' : 'Nothing inside.';
+ if (opts.keepTransform) applyTransform(); else fit(false);
+ applySelection();
+ if (opts.after) opts.after();
+}
+
+function draw(view, res) {
+ vp.innerHTML = '';
+ state.bounds = { x: 0, y: 0, w: res.width, h: res.height };
+ const edgeById = new Map(view.edges.map((e) => [e.id, e]));
+ // layers, bottom to top: traces, flow effects (walkthrough line + pulse), cards, port dots
+ const gCols = el('g', { class: 'cols' }, vp);
+ const gEdges = el('g', { class: 'edges' }, vp), gFx = el('g', {}, vp), gNodes = el('g', {}, vp), gPorts = el('g', { class: 'edges' }, vp);
+ state.fxLayer = gFx;
+ drawColumns(gCols, view, res);
+ state.edgeEls = new Map(); state.chipEls = new Map();
+ for (const re of res.edges || []) {
+ const e = edgeById.get(re.id), s = re.sections?.[0];
+ if (!s) continue;
+ const pts = [s.startPoint, ...(s.bendPoints || []), s.endPoint];
+ const d = roundedPath(pts, 14);
+ const g = el('g', { class: `edge k-${e.k}`, style: `color:var(--k-${e.k})` }, gEdges);
+ const width = 1.3 + Math.min(4, Math.log2(e.w + 1)) * 0.5;
+ el('path', { class: 'trace', d, 'stroke-width': width.toFixed(2) }, g);
+ el('path', { class: 'flow', d }, g);
+ el('path', { class: 'hit', d }, g);
+ const pg = el('g', { class: `edge k-${e.k}`, style: `color:var(--k-${e.k})` }, gPorts);
+ el('circle', { class: 'port', cx: s.startPoint.x, cy: s.startPoint.y, r: 3.4 }, pg);
+ el('circle', { class: 'port', cx: s.endPoint.x, cy: s.endPoint.y, r: 3.4 }, pg);
+ g.addEventListener('mouseenter', (ev) => showTip(ev, edgeTip(e)));
+ g.addEventListener('mousemove', moveTip);
+ g.addEventListener('mouseleave', hideTip);
+ g.addEventListener('click', (ev) => { ev.stopPropagation(); select({ edge: e.id }); });
+ g.addEventListener('contextmenu', (ev) => { ev.preventDefault(); ev.stopPropagation(); hideTip(); openMenu(ev, edgeMenu(e)); });
+ state.edgeEls.set(e.id, { g, pg, d, e });
+ }
+ // cards rise in left-to-right, a few ms apart
+ const order = res.children.slice().sort((a, b) => a.x - b.x || a.y - b.y);
+ const delay = new Map(order.map((c, i) => [c.id, Math.min(i * 18, 360)]));
+ for (const c of res.children) {
+ const g = el('g', { class: 'node', transform: `translate(${c.x},${c.y})` }, gNodes);
+ const fo = el('foreignObject', { x: -GUTTER, y: -GUTTER, width: c.width + GUTTER * 2, height: c.height + GUTTER * 2 }, g);
+ fo.innerHTML = `<div class="fo-pad">${c.id.startsWith('x:') ? connectorHTML(view.connectors.find((x) => x.id === c.id)) : cardHTML(c.id)}</div>`;
+ fo.querySelector('.card')?.style.setProperty('--d', `${delay.get(c.id)}ms`);
+ g.addEventListener('click', (ev) => { ev.stopPropagation(); select(c.id); });
+ g.addEventListener('dblclick', (ev) => { ev.stopPropagation(); if (ev.button !== 0) return; hideTip(); open(c.id); });
+ g.addEventListener('contextmenu', (ev) => { ev.preventDefault(); ev.stopPropagation(); hideTip(); openMenu(ev, itemMenu(c.id)); });
+ g.addEventListener('mouseenter', (ev) => tipSoon(ev, () => cardTip(c.id)));
+ g.addEventListener('mousemove', moveTip);
+ g.addEventListener('mouseleave', hideTip);
+ state.chipEls.set(c.id, g);
+ }
+}
+
+/** Brackets over the three columns of a view that has outside connections: what uses this part (left),
+ * what's inside it (middle), and what it uses (right). Drawn in map space so they pan and zoom with it. */
+function drawColumns(g, view, res) {
+ if (!view.connectors?.length || state.container === 'root' || state.container === 'q:answer') return;
+ const span = (cs) => cs.length ? [Math.min(...cs.map((c) => c.x)), Math.max(...cs.map((c) => c.x + c.width))] : null;
+ const ins = res.children.filter((c) => c.id.startsWith('x:in:'));
+ const outs = res.children.filter((c) => c.id.startsWith('x:out:'));
+ const mid = res.children.filter((c) => !c.id.startsWith('x:'));
+ const y = Math.min(...res.children.map((c) => c.y)) - 26;
+ const cols = [[span(ins), 'Used by'], [span(mid), `Inside ${info(state.container).name}`], [span(outs), 'Uses']];
+ for (const [s, label] of cols) {
+ if (!s) continue;
+ const [x0, x1] = s, cx = (x0 + x1) / 2;
+ const half = Math.min(textW(label, 13, 500) / 2 + 10, (x1 - x0) / 2 - 12);
+ // ⌐—— label ——¬ : end ticks curl down toward the cards, with a gap in the line for the label
+ el('path', { d: `M${x0},${y + 9} v-5 q0,-4 4,-4 H${cx - half} M${cx + half},${y} H${x1 - 4} q4,0 4,4 v5` }, g);
+ el('text', { x: cx, y }, g).textContent = label;
+ }
+}
+
+// ======================= tooltips =======================
+const tip = $('#tooltip');
+let tipTimer = null, lastPointer = null;
+function showTip(ev, html) { clearTimeout(tipTimer); if (!html || drag?.moved || !$('#ctxmenu').hidden) return; tip.innerHTML = html; tip.hidden = false; moveTip(ev); }
+/** Cards explain themselves after a short hover, so passing over them doesn't flicker tooltips. */
+function tipSoon(ev, make) { clearTimeout(tipTimer); lastPointer = ev; tipTimer = setTimeout(() => showTip(lastPointer, make()), 420); }
+function moveTip(ev) {
+ lastPointer = ev;
+ if (tip.hidden) return;
+ const r = $('#stage').getBoundingClientRect();
+ let x = ev.clientX - r.left + 18, y = ev.clientY - r.top + 18;
+ if (x + tip.offsetWidth + 12 > r.width) x = ev.clientX - r.left - tip.offsetWidth - 14;
+ if (y + tip.offsetHeight + 12 > r.height) y = ev.clientY - r.top - tip.offsetHeight - 14;
+ tip.style.left = x + 'px'; tip.style.top = y + 'px';
+}
+function hideTip() { clearTimeout(tipTimer); tip.hidden = true; }
+function endpointsOf(e) {
+ const m = new Map();
+ for (const l of e.links) for (const [ri] of l.calls || []) if (ri != null) m.set(ri, (m.get(ri) || 0) + 1);
+ return [...m.entries()].sort((a, b) => b[1] - a[1]).map(([ri, n]) => ({ r: routes[ri], i: ri, n }));
+}
+function edgeTip(e) {
+ if (e.k === 'contains') return `<div class="tt">${h(nameOf(e.a))} contains ${h(nameOf(e.b))}</div>`;
+ const eps = endpointsOf(e);
+ const names = [...new Set(e.links.flatMap((l) => l.names || []))];
+ const labels = [...new Set(e.links.flatMap((l) => l.labels || []))].filter((x) => !/^[A-Z]+ \//.test(x));
+ const desc = e.links.map((l) => l.desc).find(Boolean);
+ const meta = eps.length ? eps.slice(0, 4).map((x) => `${x.r.m} ${x.r.p}`).join('\n') + (eps.length > 4 ? `\n+${eps.length - 4} more` : '')
+ : names.length ? 'uses ' + names.slice(0, 8).join(', ') + (names.length > 8 ? '…' : '') : labels.slice(0, 4).join('\n');
+ return `<div class="tt">${h(nameOf(e.a))} → ${h(nameOf(e.b))}</div><div class="td">${h(KIND_LABEL[e.k])} · ${plural(e.w, 'connection')}${eps.length ? ` · ${plural(eps.length, 'endpoint')}` : ''}</div>${desc ? `<div class="td">${h(desc)}</div>` : ''}${meta ? `<div class="tp">${h(meta)}</div>` : ''}<div class="th"><span><span class="kbd">click</span> details</span><span><span class="kbd">right-click</span> more</span></div>`;
+}
+
+// ======================= right-click menus =======================
+const ctxEl = $('#ctxmenu');
+function openMenu(ev, items) {
+ const acts = [];
+ ctxEl.innerHTML = items.filter(Boolean).map((it) => {
+ if (it === '-') return '<div class="mi-sep"></div>';
+ if (it.title) return `<div class="mi-title">${h(it.title)}</div>`;
+ acts.push(it.run);
+ return `<button class="mi" data-k="${acts.length - 1}">${iconI(it.icon || 'right')}<span>${h(it.label)}</span>${it.hint ? `<span class="hint">${h(it.hint)}</span>` : ''}</button>`;
+ }).join('').replace(/^(<div class="mi-sep"><\/div>)+|(<div class="mi-sep"><\/div>)+$/g, '');
+ ctxEl.querySelectorAll('.mi').forEach((b) => b.onclick = (e) => { e.stopPropagation(); closeMenu(); acts[+b.dataset.k](); });
+ ctxEl.hidden = false;
+ const w = ctxEl.offsetWidth, hgt = ctxEl.offsetHeight;
+ const x = Math.min(ev.clientX, innerWidth - w - 8), y = Math.min(ev.clientY, innerHeight - hgt - 8);
+ ctxEl.style.left = x + 'px'; ctxEl.style.top = y + 'px';
+ ctxEl.style.transformOrigin = `${ev.clientX - x}px ${ev.clientY - y}px`;
+}
+function closeMenu() { ctxEl.hidden = true; }
+const copy = (text) => navigator.clipboard?.writeText(text).catch(() => {});
+function itemMenu(id) {
+ const real = id.startsWith('x:') ? connEntity(id) : id.startsWith('m:') ? 'f:' + id.slice(2) : id;
+ const i = info(real);
+ const path = i.type === 'route' ? `${i.r.m} ${i.r.p}` : i.type === 'node' ? (i.n.paths || []).join(' ') : i.path;
+ const fileForEditor = i.type === 'file' ? [i.f.p, 1] : i.type === 'route' ? [i.r.f, i.r.l] : i.type === 'symbol' ? [i.f.p, i.s[2]] : null;
+ const url = fileForEditor && editorUrl(...fileForEditor);
+ return [
+ { title: i.name },
+ id.startsWith('x:') ? { label: `Go to ${i.name}`, icon: 'right', hint: '2×click', run: () => reveal(real) }
+ : drillable(real) && state.container !== real ? { label: 'Open', icon: 'drill', hint: '2×click', run: () => open(real) } : null,
+ state.container === 'q:answer' && !id.startsWith('x:') ? { label: 'Show on the map', icon: 'external', run: () => reveal(real) } : null,
+ { label: 'Ask about this', icon: 'spark', run: () => addAskContext(real) },
+ { label: 'Show details', icon: 'panel', run: () => { setPanel(true); if (id.startsWith('x:')) reveal(real); else select(id); } },
+ '-',
+ path ? { label: i.type === 'route' ? 'Copy endpoint' : 'Copy path', icon: 'copy', run: () => copy(path) } : null,
+ { label: 'Copy name', icon: 'copy', run: () => copy(i.name) },
+ url ? { label: 'Open in editor', icon: 'open', run: () => { location.href = url; } } : null,
+ ];
+}
+function edgeMenu(e) {
+ const ep = (x) => x.startsWith('x:') ? connEntity(x) : x.startsWith('m:') ? 'f:' + x.slice(2) : x;
+ return [
+ { title: `${nameOf(e.a)} → ${nameOf(e.b)}` },
+ { label: 'Ask about this connection', icon: 'spark', run: () => { addAskContext(ep(e.a)); addAskContext(ep(e.b)); } },
+ { label: 'Show details', icon: 'panel', run: () => { setPanel(true); select({ edge: e.id }); } },
+ '-',
+ { label: `Go to ${nameOf(e.a)}`, icon: 'left', run: () => reveal(ep(e.a)) },
+ { label: `Go to ${nameOf(e.b)}`, icon: 'right', run: () => reveal(ep(e.b)) },
+ ];
+}
+function canvasMenu() {
+ return [
+ { label: 'Fit to screen', icon: 'fit', hint: 'F', run: () => fit(true) },
+ state.container !== 'root' ? { label: 'Up one level', icon: 'left', hint: '⌫', run: up } : null,
+ state.container !== 'root' ? { label: 'Back to overview', icon: 'home', run: () => go('root') } : null,
+ '-',
+ { label: 'Search', icon: 'search', hint: '/', run: openPalette },
+ { label: 'Ask about this view', icon: 'spark', run: () => { if (state.container !== 'root' && state.container !== 'q:answer') addAskContext(state.container); askInput.focus(); } },
+ ];
+}
+svg.addEventListener('contextmenu', (ev) => { ev.preventDefault(); hideTip(); openMenu(ev, canvasMenu()); });
+window.addEventListener('pointerdown', (ev) => { if (!ctxEl.hidden && !ctxEl.contains(ev.target)) closeMenu(); }, true);
+window.addEventListener('blur', closeMenu);
+
+// ======================= pan / zoom =======================
+function applyTransform() {
+ const { x, y, k } = state.t;
+ vp.style.transform = `translate(${x}px,${y}px) scale(${k})`;
+ svg.classList.toggle('lod-low', k < 0.42);
+ svg.classList.toggle('lod-mid', k >= 0.42 && k < 0.65);
+}
+const stageRect = () => svg.getBoundingClientRect();
+function setT(t, animate) {
+ state.t = t;
+ if (animate) { vp.classList.add('anim'); requestAnimationFrame(applyTransform); setTimeout(() => vp.classList.remove('anim'), 520); } else applyTransform();
+}
+/** The canvas area not covered by the header, context title, details panel and ask bar. */
+function freeArea() {
+ const r = stageRect();
+ const panelW = document.body.classList.contains('no-panel') ? 0 : $('#panel').offsetWidth + 32;
+ const top = 72 + Math.min(130, $('#context').offsetHeight);
+ const bottom = $('#ask').offsetHeight + 36;
+ return { x: 16, y: top, w: Math.max(200, r.width - panelW - 32), h: Math.max(140, r.height - top - bottom) };
+}
+function fit(animate) {
+ const b = state.bounds; if (!b) return;
+ const a = freeArea();
+ const k = Math.min(a.w / (b.w + 40), a.h / (b.h + 20), 1.1);
+ setT({ k, x: a.x + (a.w - b.w * k) / 2 - b.x * k, y: a.y + Math.max(0, (a.h - b.h * k) / 2) - b.y * k }, animate);
+}
+function zoomBy(f, cx, cy) {
+ const r = stageRect();
+ cx ??= r.width / 2; cy ??= r.height / 2;
+ const k = clamp(state.t.k * f, 0.08, 2.5);
+ setT({ k, x: cx - (cx - state.t.x) * (k / state.t.k), y: cy - (cy - state.t.y) * (k / state.t.k) }, false);
+}
+// wheel/pinch zooms around the cursor; two-finger trackpad scroll pans
+svg.addEventListener('wheel', (ev) => {
+ ev.preventDefault();
+ const r = stageRect();
+ const trackpadPan = !ev.ctrlKey && ev.deltaMode === 0 && (Math.abs(ev.deltaX) > 0 || Math.abs(ev.deltaY) < 40);
+ if (trackpadPan) setT({ ...state.t, x: state.t.x - ev.deltaX, y: state.t.y - ev.deltaY }, false);
+ else zoomBy(Math.exp(-ev.deltaY * (ev.ctrlKey ? 0.01 : 0.0018)), ev.clientX - r.left, ev.clientY - r.top);
+}, { passive: false });
+let drag = null;
+svg.addEventListener('pointerdown', (ev) => { if (ev.button !== 0) return; drag = { x: ev.clientX, y: ev.clientY, tx: state.t.x, ty: state.t.y, moved: false }; });
+window.addEventListener('pointermove', (ev) => {
+ if (!drag) return;
+ const dx = ev.clientX - drag.x, dy = ev.clientY - drag.y;
+ if (!drag.moved && Math.hypot(dx, dy) < 4) return;
+ drag.moved = true; svg.classList.add('panning'); hideTip();
+ setT({ ...state.t, x: drag.tx + dx, y: drag.ty + dy }, false);
+});
+window.addEventListener('pointerup', () => { if (drag?.moved) svg.addEventListener('click', (e) => e.stopPropagation(), { capture: true, once: true }); drag = null; svg.classList.remove('panning'); });
+svg.addEventListener('click', () => select(null));
+window.addEventListener('resize', () => fit(false));
+$('#z-in').onclick = () => zoomBy(1.25);
+$('#z-out').onclick = () => zoomBy(0.8);
+$('#z-fit').onclick = () => fit(true);
+
+// ======================= navigation =======================
+function setHash(container, sel) {
+ if (container.startsWith('q:')) return; // answer views are transient
+ const p = new URLSearchParams();
+ if (container !== 'root') p.set('v', container);
+ if (sel && typeof sel === 'string') p.set('s', sel);
+ const s = p.toString();
+ try { if (location.hash.slice(1) !== s) history.pushState(null, '', s ? '#' + s : location.pathname + location.search); } catch {}
+}
+function readHash() {
+ const p = new URLSearchParams(location.hash.slice(1));
+ let v = p.get('v') || 'root', s = p.get('s');
+ if (v !== 'root' && !parentOf.has(v)) v = 'root';
+ if (s && !parentOf.has(s) && !s.startsWith('x:') && !s.startsWith('m:')) s = null;
+ return { v, s };
+}
+window.addEventListener('popstate', () => { const { v, s } = readHash(); go(v, { select: s, push: false }); });
+
+async function go(container, { select: sel = null, push = true, zoomFrom = null, after, force = false } = {}) {
+ hideTip();
+ custom.panel = null;
+ const changed = container !== state.container;
+ state.container = container; state.selected = sel;
+ if (push) setHash(container, sel);
+ if (!changed && state.layout && !force) { applySelection(); renderPanel(); if (after) after(); return; }
+ const c = zoomFrom && state.layout?.children.find((x) => x.id === zoomFrom);
+ if (c) {
+ const r = stageRect();
+ const k = Math.min(r.width / c.width, r.height / c.height) * 0.6;
+ setT({ k, x: r.width / 2 - (c.x + c.width / 2) * k, y: r.height / 2 - (c.y + c.height / 2) * k }, true);
+ vp.style.opacity = '0';
+ await new Promise((ok) => setTimeout(ok, 260));
+ }
+ vp.classList.remove('anim'); vp.style.opacity = '0';
+ await render({ after: () => { vp.classList.add('anim'); requestAnimationFrame(() => { vp.style.opacity = '1'; }); setTimeout(() => vp.classList.remove('anim'), 340); renderPanel(); if (after) after(); } });
+}
+function open(item) {
+ if (item.startsWith('x:')) { reveal(connEntity(item)); return; }
+ if (item.startsWith('m:')) return;
+ if (state.container === 'q:answer' && !drillable(item)) { reveal(item); return; }
+ if (!drillable(item)) { select(item); return; }
+ go(item, { zoomFrom: item });
+}
+function up() { if (state.container === 'root') return; const from = state.container; go(parentOf.get(from) || 'root', { select: from }); }
+function reveal(item) {
+ if (item === 'root') return go('root');
+ const container = parentOf.get(item) || 'root';
+ go(container, { select: item, after: () => { const g = state.chipEls.get(item); if (g) { g.classList.remove('flash'); void g.getBBox(); g.classList.add('flash'); centerOn(item); } } });
+}
+function centerOn(item) {
+ const c = state.layout?.children.find((x) => x.id === item); if (!c) return;
+ const a = freeArea();
+ const k = Math.max(state.t.k, 0.75);
+ setT({ k, x: a.x + a.w / 2 - (c.x + c.width / 2) * k, y: a.y + a.h / 2 - (c.y + c.height / 2) * k }, true);
+}
+
+// ======================= selection =======================
+function select(sel) { custom.panel = null; state.selected = sel; if (typeof sel === 'string' || sel === null) setHash(state.container, sel); applySelection(); renderPanel(); }
+function applySelection() {
+ const sel = state.selected;
+ svg.classList.remove('dim');
+ for (const g of state.chipEls?.values() || []) g.classList.remove('sel', 'hl');
+ for (const { g, pg } of state.edgeEls?.values() || []) { g.classList.remove('hl'); pg.classList.remove('hl'); }
+ if (!sel) return;
+ const mark = (x) => { x.g.classList.add('hl'); x.pg.classList.add('hl'); };
+ if (typeof sel === 'object' && sel.edge) {
+ const x = state.edgeEls.get(sel.edge); if (!x) return;
+ svg.classList.add('dim'); mark(x);
+ for (const id of [x.e.a, x.e.b]) state.chipEls.get(id)?.classList.add('hl');
+ return;
+ }
+ const g = state.chipEls?.get(sel); if (!g) return;
+ svg.classList.add('dim'); g.classList.add('sel', 'hl');
+ for (const x of state.edgeEls.values()) if (x.e.a === sel || x.e.b === sel) { mark(x); state.chipEls.get(x.e.a === sel ? x.e.b : x.e.a)?.classList.add('hl'); }
+}
+
+// ======================= chrome: context, crumbs, legend =======================
+function renderContext() {
+ if (state.container === 'q:answer') {
+ $('#context').innerHTML = `<div class="k"><span class="ico" style="--c:#ececec">${icon(state.answer.icon || 'spark')}</span>${h(state.answer.kind || 'Answer')} · ${plural(state.answer.items.length, 'card')}</div><h1>${h(state.answer.title)}</h1><p>${h(state.answer.question)}</p>`;
+ return;
+ }
+ const i = info(state.container);
+ const kind = state.container === 'root' ? 'Overview' : i.type === 'node' ? i.kind.charAt(0).toUpperCase() + i.kind.slice(1) : i.type === 'dir' ? 'Folder' : i.type === 'file' ? 'File' : i.type;
+ const badge = state.container === 'root' ? '' : `<span class="ico" style="--c:${colorOf(i)}">${icon(iconKey(i))}</span>`;
+ $('#context').innerHTML = `<div class="k">${badge}${h(kind)}</div><h1>${h(i.name)}</h1>${i.desc ? `<p>${h(i.desc)}</p>` : ''}${state.view?.hidden ? `<p style="color:var(--text-3);font-size:12.5px;margin-top:8px">${state.view.hidden} more exports aren't imported by name anywhere; they're listed in the details panel.</p>` : ''}`;
+}
+function renderCrumbs() {
+ const c = $('#crumbs'); c.innerHTML = '';
+ const path = chain(state.container).slice().reverse();
+ path.forEach((item, idx) => {
+ if (idx) { const s = document.createElement('span'); s.className = 'sep'; s.textContent = '/'; c.appendChild(s); }
+ const b = document.createElement('button');
+ b.textContent = item === 'root' ? 'Overview' : item === 'q:answer' ? `${state.answer.kind || 'Answer'}: ${state.answer.title}` : info(item).name;
+ if (item === state.container) b.className = 'cur';
+ b.onclick = () => go(item, { select: path[idx + 1] || null });
+ c.appendChild(b);
+ });
+ $('#btn-up').hidden = state.container === 'root';
+}
+function renderLegend(view) {
+ const total = {}; for (const l of G.links) total[l.k] = (total[l.k] || 0) + 1;
+ const here = {}; for (const e of view.edges) here[e.k] = (here[e.k] || 0) + 1;
+ const L = $('#legend'); L.innerHTML = '<div class="lh">Show connections</div>';
+ const techRow = () => { const lab = document.createElement('label'); lab.className = 'tech' + (technical() ? '' : ' off'); lab.innerHTML = `<input type="checkbox" ${technical() ? 'checked' : ''}><span>Show technical detail</span><span class="tog" style="margin-left:auto"></span>`; lab.querySelector('input').onchange = (ev) => setTechnical(ev.target.checked); return lab; };
+ let off = 0;
+ for (const k of KINDS) {
+ if (!total[k]) continue;
+ if (!state.kinds[k]) off++;
+ const lab = document.createElement('label');
+ lab.className = state.kinds[k] ? '' : 'off';
+ lab.innerHTML = `<input type="checkbox" ${state.kinds[k] ? 'checked' : ''}><span class="sw" style="background:var(--k-${k})"></span>${KIND_LABEL[k]}<span class="n">${here[k] || ''}</span><span class="tog"></span>`;
+ lab.querySelector('input').onchange = (ev) => { state.kinds[k] = ev.target.checked; store.set('kinds', state.kinds); render({ keepTransform: true }); };
+ L.appendChild(lab);
+ }
+ L.appendChild(techRow());
+ if (recentBy.size) {
+ const lab = document.createElement('label'); lab.className = 'tech' + (recentShown ? '' : ' off');
+ lab.innerHTML = `<input type="checkbox" ${recentShown ? 'checked' : ''}><span>Highlight recent work</span><span class="tog" style="margin-left:auto"></span>`;
+ lab.querySelector('input').onchange = (ev) => { setRecentShown(ev.target.checked); lab.classList.toggle('off', !ev.target.checked); };
+ L.appendChild(lab);
+ }
+ const fb = $('#filters-btn');
+ fb.querySelector('.badge')?.remove();
+ if (off) fb.insertAdjacentHTML('beforeend', `<span class="badge">${off}</span>`);
+ fb.classList.toggle('icon', !off);
+}
+
+// ======================= inspector =======================
+const editorUrl = (p, line = 1) => G.meta.root ? `vscode://file/${encodeURI(G.meta.root.replace(/\\/g, '/'))}/${encodeURI(p)}:${line}` : null;
+const rowFor = (item, extra = '', dotColor) => {
+ const i = info(item);
+ return `<a class="row" data-go="${h(item)}" title="${h(i.path || '')}"><span class="dot" style="background:${dotColor || colorOf(i)}"></span><span class="rt"><div class="rn">${h(i.name)}</div>${i.desc ? `<div class="rd">${h(i.desc)}</div>` : ''}</span>${extra ? `<span class="rc">${extra}</span>` : ''}</a>`;
+};
+const routeRow = (ri, extra = '') => {
+ const r = routes[ri];
+ return `<a class="row" data-go="r:${ri}"><span class="method" style="--m:${methodVar(r.m)};margin-top:1px">${h(r.m)}</span><span class="rt"><div class="rn">${h(r.name)}</div>${r.d ? `<div class="rd">${h(r.d)}</div>` : ''}<div class="rp">${h(r.p)}</div></span>${extra ? `<span class="rc">${extra}</span>` : ''}</a>`;
+};
+const listSec = (title, rows, count, max = 30) => rows.length ? `<div class="sec"><h3>${h(title)} <span class="c">${count ?? rows.length}</span></h3><div class="list">${rows.slice(0, max).join('')}${rows.length > max ? `<div class="more">+${rows.length - max} more</div>` : ''}</div></div>` : '';
+const pathBox = (p) => `<div class="pp"><span>${h(p)}</span><button data-copy="${h(p)}" title="Copy">${iconI('copy')}</button></div>`;
+function header(i) {
+ const kind = i.type === 'node' ? i.kind : i.type === 'symbol' ? i.symKind : i.type === 'route' ? 'Endpoint' : i.type === 'module' ? 'file' : i.type;
+ return `<div class="ph"><span class="ico" style="--c:${colorOf(i)}">${icon(iconKey(i))}</span><span class="kindlabel">${h(kind)}</span></div>
+ <h2 class="pt">${h(i.name)}</h2>${i.desc ? `<p class="pd">${h(i.desc)}</p>` : '<p class="pd empty">No description yet.</p>'}`;
+}
+
+function renderPanel() {
+ const sel = state.selected;
+ let html;
+ if (sel && typeof sel === 'object' && sel.edge) html = edgePanel(state.edgeEls.get(sel.edge)?.e);
+ else if (sel && sel.startsWith('x:')) html = itemPanel(connEntity(sel), true);
+ else if (sel && sel.startsWith('m:')) html = itemPanel('f:' + sel.slice(2));
+ else if (sel) html = itemPanel(sel);
+ else html = state.container === 'root' ? overviewPanel() : state.container === 'q:answer' ? answerPanel() : itemPanel(state.container);
+ // extensions add sections: 'overview' on the codebase panel, 'item' on a selected/opened item
+ const where = sel && typeof sel === 'object' ? null : sel ? 'item' : state.container === 'root' ? 'overview' : state.container === 'q:answer' ? null : 'item';
+ const target = sel && typeof sel === 'string' ? (sel.startsWith('x:') ? connEntity(sel) : sel.startsWith('m:') ? 'f:' + sel.slice(2) : sel) : state.container;
+ const extOut = [];
+ if (custom.panel) { html = custom.panel.html; extOut.push(...(custom.panel.bind ? [{ bind: custom.panel.bind, whole: true }] : [])); }
+ else if (where) for (const fn of ext.sections[where]) {
+ try {
+ const r = fn(target);
+ if (!r) continue;
+ const o = typeof r === 'string' ? { html: r } : r;
+ extOut.push(o);
+ const block = `<div data-ext="${extOut.length - 1}">${o.html || ''}</div>`;
+ // { top: true }: right after the panel's header section instead of at the end
+ const second = o.top ? html.indexOf('<div class="sec"', 1) : -1;
+ html = second > 0 ? html.slice(0, second) + block + html.slice(second) : html + block;
+ } catch (e) { console.error('floorplan extension', e); }
+ }
+ panel.innerHTML = html || '';
+ extOut.forEach((o, i) => { try { o.bind?.(o.whole ? panel : panel.querySelector(`[data-ext="${i}"]`)); } catch (e) { console.error('floorplan extension', e); } });
+ panel.scrollTop = 0;
+ panel.querySelectorAll('[data-go]').forEach((a) => a.addEventListener('click', (ev) => { ev.preventDefault(); reveal(a.dataset.go); }));
+ panel.querySelectorAll('[data-open]').forEach((a) => a.addEventListener('click', (ev) => { ev.preventDefault(); open(a.dataset.open); }));
+ panel.querySelectorAll('[data-flow]').forEach((a) => a.addEventListener('click', (ev) => { ev.preventDefault(); startFlow(a.dataset.flow); }));
+ panel.querySelectorAll('[data-sel]').forEach((a) => a.addEventListener('click', (ev) => { ev.preventDefault(); select(a.dataset.sel); centerOn(a.dataset.sel); }));
+ panel.querySelector('[data-goroot]')?.addEventListener('click', () => go('root'));
+ panel.querySelectorAll('[data-copy]').forEach((a) => a.addEventListener('click', () => { navigator.clipboard?.writeText(a.dataset.copy); a.textContent = '✓'; }));
+ emit('panel', { selected: sel, container: state.container });
+}
+
+function answerPanel() {
+ const a = state.answer;
+ return `<div class="sec"><div class="ph"><span class="ico" style="--c:var(--accent)">${icon('feature')}</span><span class="kind">${h(a.kind || 'Answer')}</span></div><h2 class="pt">${h(a.title)}</h2><p class="pd">${h(a.question)}</p>${a.kind && a.answer ? `<div class="pd md">${md(a.answer)}</div>` : ''}
+ <div class="actions"><button class="btn soft" data-goroot>Back to map</button></div></div>
+ ${listSec('On this board', a.items.map((x, i) => { const ii = info(x.id); return `<a class="row" data-sel="${h(x.id)}"><span class="anote" style="margin:0;padding:0;background:none;border:0"><b>${i + 1}</b></span><span class="rt"><div class="rn">${h(ii.name)}</div>${x.note ? `<div class="rd">${h(x.note)}</div>` : ''}${ii.path ? `<div class="rp">${h(ii.path)}</div>` : ''}</span></a>`; }))}
+ ${a.steps?.length >= 2 ? `<div class="sec"><h3>Walkthrough <span class="c">${a.steps.length}</span></h3><div class="list">${a.steps.map((s, i) => `<a class="row" data-sel="${h(s.id)}"><span class="dot" style="background:var(--accent)"></span><span class="rt"><div class="rn">${i + 1}. ${h(info(s.id).name)}</div><div class="rd">${h(s.note)}</div></span></a>`).join('')}</div></div>` : ''}`;
+}
+
+// Top-level parts, grouped under names people understand instead of bare colour dots.
+const SYSTEM_GROUPS = [
+ { label: 'Apps people use', hint: 'what users and staff open', kinds: ['ui'] },
+ { label: 'Behind the scenes', hint: 'servers, background work, shared code', kinds: ['service', 'worker', 'library', 'feature', 'data', 'config'] },
+ { label: 'Outside services', hint: 'other companies your app relies on', kinds: ['external'] },
+ { label: 'Developer tools', hint: 'scripts, tests, deployment', kinds: ['script', 'test', 'infra'] },
+];
+function systemsSection(tops) {
+ const placed = new Set();
+ const parts = SYSTEM_GROUPS.map((g) => {
+ const items = tops.filter((t) => g.kinds.includes(info(t).kind));
+ items.forEach((t) => placed.add(t));
+ return items.length ? `<div class="group-h">${h(g.label)}<span class="gd">${h(g.hint)}</span></div><div class="list">${items.map((t) => rowFor(t, info(t).kind === 'external' ? '' : technical() && statsOf(t)?.files ? fmt(statsOf(t).loc) + ' loc' : statsOf(t)?.files ? plural(statsOf(t).files, 'file') : '')).join('')}</div>` : '';
+ });
+ const rest = tops.filter((t) => !placed.has(t));
+ if (rest.length) parts.push(`<div class="group-h">Other</div><div class="list">${rest.map((t) => rowFor(t)).join('')}</div>`);
+ return `<div class="sec"><h3>Systems <span class="c">${tops.length}</span></h3>${parts.join('')}</div>`;
+}
+
+function overviewPanel() {
+ const p = G.project;
+ const tops = kids.get('root') || [];
+ const undescribed = G.files.filter((f) => f.auto).length + routes.filter((r) => r.auto).length;
+ return `<div class="sec"><div class="ph"><span class="ico" style="--c:var(--accent)">${icon('feature')}</span><span class="kind">Codebase</span></div><h2 class="pt">${h(p.name)}</h2>${p.summary ? `<p class="pd">${h(p.summary)}</p>` : ''}
+ <div class="stats" style="margin-top:14px"><div><b>${fmt(G.meta.counts.files)}</b><span>files</span></div><div><b>${fmt(G.meta.counts.loc)}</b><span>lines</span></div><div><b>${fmt(routes.length)}</b><span>endpoints</span></div></div>
+ ${undescribed ? `<div class="callout">${undescribed} files and endpoints still use generated names. Run the skill again to describe them.</div>` : ''}</div>
+ ${systemsSection(tops)}
+ ${listSec('Guided flows', G.flows.map((f) => `<a class="row" data-flow="${h(f.id)}"><span class="dot" style="background:var(--accent)"></span><span class="rt"><div class="rn">${h(f.title)}</div>${f.description ? `<div class="rd">${h(f.description)}</div>` : ''}</span><span class="rc">${f.steps.length} steps</span></a>`))}
+ ${listSec('Repositories', G.meta.repos.map((r) => `<div class="row" style="cursor:default"><span class="dot" style="background:var(--text-4)"></span><span class="rt"><div class="rn">${h(r.name)}</div><div class="rp">${h(r.branch || '')} @ ${h((r.head || '').slice(0, 7))}</div></span></div>`))}
+ ${p.entrypoints?.length ? listSec('Entrypoints', p.entrypoints.filter((e) => files.has(e)).map((e) => rowFor('f:' + e))) : ''}
+ <div class="sec" style="color:var(--text-3);line-height:1.7;font-size:12px">Click a card to inspect it · double-click to open it<br><span class="kbd">/</span> search · <span class="kbd">⌫</span> up · <span class="kbd">F</span> fit · <span class="kbd">P</span> inspector</div>`;
+}
+
+function connections(item) {
+ const own = new Set(chain(item));
+ const inside = (x) => chain(x).includes(item);
+ const peerOf = (x) => { const ch = chain(x); const idx = ch.findIndex((y) => own.has(y)); return ch[idx - 1] || x; };
+ const out = new Map(), inn = new Map();
+ for (const l of G.links) {
+ const ia = inside(l.a), ib = inside(l.b);
+ if (ia === ib) continue;
+ const peer = peerOf(ia ? l.b : l.a);
+ const m = ia ? out : inn;
+ const key = peer + '|' + l.k;
+ const cur = m.get(key) || { peer, k: l.k, w: 0 };
+ cur.w += l.w; m.set(key, cur);
+ }
+ const rows = (m) => [...m.values()].sort((a, b) => b.w - a.w).map((c) => rowFor(c.peer, `${KIND_LABEL[c.k]} · ${c.w}`, `var(--k-${c.k})`));
+ return { out: rows(out), inn: rows(inn) };
+}
+
+function itemPanel(item, viaConnector) {
+ const i = info(item);
+ let html = `<div class="sec">${header(i)}`;
+ const actions = [];
+ if (drillable(item) && state.container !== item) actions.push(`<button class="btn soft" data-open="${h(item)}">${iconI('drill')}Open</button>`);
+ if (viaConnector || (parentOf.get(item) !== state.container && state.container !== item)) actions.push(`<button class="btn soft" data-go="${h(item)}">Show on map</button>`);
+ if (i.type === 'node' || i.type === 'dir') {
+ const n = i.n, s = statsOf(item);
+ if (n?.details) html += n.details.split(/\n\n+/).map((p) => `<p class="pd" style="margin-top:8px">${h(p)}</p>`).join('');
+ if (n?.paths?.length || i.d) html += pathBox(i.d ? i.d.path + '/' : n.paths.join(' '));
+ if (actions.length) html += `<div class="actions">${actions.join('')}</div>`;
+ html += '</div>';
+ if (s?.files) {
+ const langs = Object.entries(n?.stats.langs || {}).sort((a, b) => b[1] - a[1]).slice(0, 5);
+ const tot = langs.reduce((a, [, v]) => a + v, 0) || 1;
+ const palette = ['#a78bfa', '#38bdf8', '#34d399', '#fbbf24', '#f472b6'];
+ const nr = routes.filter((r) => chain('f:' + r.f).includes(item)).length;
+ html += `<div class="sec"><div class="stats"><div><b>${fmt(s.files)}</b><span>files</span></div><div><b>${fmt(s.loc)}</b><span>lines</span></div><div><b>${nr}</b><span>endpoints</span></div></div>
+ ${langs.length ? `<div class="bar">${langs.map(([, v], k) => `<span style="flex:${v};background:${palette[k]}"></span>`).join('')}</div><div class="legend-row">${langs.map(([l, v], k) => `<span><span class="dot" style="background:${palette[k]}"></span>${h(l)} ${Math.round((v / tot) * 100)}%</span>`).join('')}</div>` : ''}</div>`;
+ }
+ if (n?.packages?.length || n?.hosts?.length || n?.tags?.length) html += `<div class="sec"><h3>Matched by</h3><div class="tags">${[...n.packages.map((p) => 'pkg ' + p), ...n.hosts.map((p) => 'host ' + p), ...n.tags.map((t) => '#' + t)].map((t) => `<span class="tag">${h(t)}</span>`).join('')}</div></div>`;
+ html += listSec('Inside', (kids.get(item) || []).filter((k) => !k.startsWith('f:')).map((k) => rowFor(k)));
+ const c = connections(item);
+ html += listSec('Used by', c.inn) + listSec('Depends on', c.out);
+ const fl = (i.d ? i.d.files : G.files.filter((f) => chain('f:' + f.p).includes(item))).slice().sort((a, b) => b.loc - a.loc);
+ html += listSec('Files', fl.map((f) => rowFor('f:' + f.p, fmt(f.loc))), fl.length, 25);
+ } else if (i.type === 'file' || i.type === 'module') {
+ const f = i.f, fid = 'f:' + f.p, url = editorUrl(f.p);
+ if (f.note) html += `<div class="callout">${h(f.note)}</div>`;
+ html += pathBox(f.p);
+ if (url) actions.push(`<a class="btn soft" href="${url}">${iconI('open')}Open in editor</a>`);
+ if (actions.length) html += `<div class="actions">${actions.join('')}</div>`;
+ const owner = nodes.get(f.n);
+ html += `</div><div class="sec"><div class="stats"><div><b>${fmt(f.loc)}</b><span>lines</span></div><div><b>${(routesByFile.get(f.p) || []).length}</b><span>endpoints</span></div><div><b>${technical() ? (f.s || []).length : fmt(G.links.filter((l) => l.b === 'f:' + f.p).length)}</b><span>${technical() ? 'exports' : 'used by'}</span></div></div>
+ ${owner ? `<div class="list" style="margin-top:12px">${rowFor('n:' + owner.id, 'module')}</div>` : ''}</div>`;
+ html += listSec('Endpoints', (routesByFile.get(f.p) || []).map((ri) => routeRow(ri)), undefined, 60);
+ const inL = G.links.filter((l) => l.b === fid), outL = G.links.filter((l) => l.a === fid);
+ const rowL = (l, other) => rowFor(other, l.calls?.length ? plural(l.calls.length, 'call') : KIND_LABEL[l.k], `var(--k-${l.k})`);
+ html += listSec('Used by', inL.map((l) => rowL(l, l.a)));
+ html += listSec('Depends on', outL.map((l) => rowL(l, l.b)));
+ const handlers = new Set((routesByFile.get(f.p) || []).map((ri) => routes[ri].h));
+ if (technical()) html += listSec('Exports', (f.s || []).map((s, k) => [s, k]).filter(([s]) => !handlers.has(s[0])).map(([s, k]) => `<a class="row" ${parentOf.has(`s:${f.p}#${k}`) ? `data-go="s:${h(f.p)}#${k}"` : ''}><span class="dot" style="background:var(--n-symbol)"></span><span class="rt"><div class="rn" style="font-family:var(--mono);font-size:12px">${h(s[0])}</div>${s[4] ? `<div class="rd">${h(s[4])}</div>` : ''}</span><span class="rc">${h(s[1])} · L${s[2]}</span></a>`), undefined, 60);
+ } else if (i.type === 'route') {
+ const r = i.r, url = editorUrl(r.f, r.l);
+ html += pathBox(`${r.m} ${r.p}`);
+ if (url) actions.push(`<a class="btn soft" href="${url}">${iconI('open')}Open handler</a>`);
+ html += `<div class="actions">${actions.join('')}</div></div>`;
+ html += `<div class="sec"><h3>Handled by</h3><div class="list">${rowFor('f:' + r.f, r.h ? h(r.h) + '()' : '')}</div></div>`;
+ const ri = routes.indexOf(r);
+ const callers = new Map();
+ for (const l of G.links) { const n = (l.calls || []).filter(([x]) => x === ri).length; if (n) callers.set(l.a, (callers.get(l.a) || 0) + n); }
+ html += callers.size ? listSec('Called from', [...callers.entries()].map(([a, n]) => rowFor(a, plural(n, 'call'), 'var(--k-http)')))
+ : `<div class="sec"><h3>Called from</h3><p class="pd empty">No call sites matched in the scanned code. It may be called by an external system, or through a URL built at runtime.</p></div>`;
+ } else if (i.type === 'symbol') {
+ const url = editorUrl(i.f.p, i.s[2]);
+ html += pathBox(`${i.f.p}:${i.s[2]}`);
+ if (url) actions.push(`<a class="btn soft" href="${url}">${iconI('open')}Open in editor</a>`);
+ html += `<div class="actions">${actions.join('')}</div></div>`;
+ html += `<div class="sec"><h3>Defined in</h3><div class="list">${rowFor('f:' + i.f.p)}</div></div>`;
+ const users = G.links.filter((l) => l.b === 'f:' + i.f.p && (l.names || []).some((nm) => nm === i.s[0] || (nm === 'default' && i.s[3])));
+ html += listSec('Imported by', users.map((l) => rowFor(l.a)));
+ } else html += '</div>';
+ return html;
+}
+
+function edgePanel(e) {
+ if (!e) return '';
+ const eps = endpointsOf(e);
+ const names = [...new Set(e.links.flatMap((l) => l.names || []))];
+ const desc = e.links.map((l) => l.desc).filter(Boolean);
+ const ep = (id) => id.startsWith('x:') ? connEntity(id) : id;
+ const pairs = e.links.filter((l) => l.a.startsWith('f:') || l.b.startsWith('f:'));
+ return `<div class="sec"><div class="ph"><span class="ico" style="--c:var(--k-${e.k})">${icon(e.k === 'http' ? 'route' : 'feature')}</span><span class="kind">${KIND_LABEL[e.k]} connection</span></div>
+ <h2 class="pt">${h(nameOf(e.a))} → ${h(nameOf(e.b))}</h2>
+ <p class="pd">${desc.length ? h(desc.join(' ')) : `${plural(e.w, 'connection')}${eps.length ? ` across ${plural(eps.length, 'endpoint')}` : ''}${e.k === 'http' && eps.length ? ', matched from call sites to route definitions' : ''}.`}</p>
+ <div class="actions"><button class="btn soft" data-go="${h(ep(e.a))}">Go to source</button><button class="btn soft" data-go="${h(ep(e.b))}">Go to target</button></div></div>
+ ${listSec('Endpoints', eps.map((x) => routeRow(x.i, plural(x.n, 'call'))), eps.length, 40)}
+ ${names.length && technical() ? `<div class="sec"><h3>Imported names <span class="c">${names.length}</span></h3><div class="tags">${names.slice(0, 60).map((x) => `<span class="tag">${h(x)}</span>`).join('')}</div></div>` : ''}
+ ${listSec('Files involved', pairs.map((l) => { const a = l.a.startsWith('f:') ? files.get(l.a.slice(2)) : null, b = l.b.startsWith('f:') ? files.get(l.b.slice(2)) : null;
+ return `<a class="row" data-go="${h(l.a)}"><span class="dot" style="background:var(--k-${l.k})"></span><span class="rt"><div class="rn">${h(a ? a.name : nameOf(l.a))} → ${h(b ? b.name : nameOf(l.b))}</div><div class="rp">${h(a ? a.p : '')}</div></span><span class="rc">${l.w}</span></a>`; }), pairs.length, 40)}`;
+}
+
+// ======================= search (command palette) =======================
+const index = [
+ ...G.nodes.map((n) => ({ id: 'n:' + n.id, name: n.label, desc: n.summary || '', path: n.id, kind: n.kind, w: 4 })),
+ ...G.files.map((f) => ({ id: 'f:' + f.p, name: f.name, desc: f.d || '', path: f.p, kind: 'file', w: 3 })),
+ ...routes.map((r, i) => ({ id: 'r:' + i, name: r.name, desc: r.d || '', path: `${r.m} ${r.p}`, kind: 'route', w: 3 })),
+ ...G.files.flatMap((f) => (f.s || []).map((s, i) => ({ id: `s:${f.p}#${i}`, name: s[0], desc: s[4] || '', path: f.p, kind: symIcon(s[1]), w: 1 }))).filter((x) => parentOf.has(x.id)),
+];
+const pal = $('#palette'), sInput = $('#search'), sRes = $('#results');
+let sActive = 0, sItems = [];
+function openPalette() { pal.classList.add('open'); sInput.value = ''; runSearch(); setTimeout(() => sInput.focus(), 0); }
+function closePalette() { pal.classList.remove('open'); }
+function runSearch() {
+ const terms = sInput.value.trim().toLowerCase().split(/\s+/).filter(Boolean);
+ let scored = [];
+ if (!terms.length) scored = (kids.get('root') || []).map((id) => [1, index.find((x) => x.id === id)]).filter((x) => x[1]);
+ else for (const it of index) {
+ if (!technical() && (it.kind === 'function' || it.kind === 'class')) continue;
+ const n = it.name.toLowerCase(), d = it.desc.toLowerCase(), p = it.path.toLowerCase();
+ let s = 0;
+ for (const t of terms) {
+ const sc = n === t ? 30 : n.startsWith(t) ? 20 : n.includes(t) ? 12 : p.includes(t) ? 6 : d.includes(t) ? 4 : 0;
+ if (!sc) { s = 0; break; }
+ s += sc;
+ }
+ if (s) scored.push([s + it.w * 2 - n.length * 0.02, it]);
+ }
+ sItems = scored.sort((a, b) => b[0] - a[0]).slice(0, 40).map((x) => x[1]);
+ sActive = 0;
+ sRes.innerHTML = sItems.map((it, i) => {
+ const ii = info(it.id);
+ const ic = it.kind === 'route' ? `<span class="method" style="--m:${methodVar(ii.r.m)}">${h(ii.r.m)}</span>` : `<span class="ico" style="--c:${colorOf(ii)}">${icon(iconKey(ii))}</span>`;
+ return `<div class="r${i === 0 ? ' active' : ''}" data-i="${i}">${ic}<span class="rt"><div class="rn">${h(it.name)}</div><div class="rd">${h(it.desc || it.path)}</div></span><span class="rk">${h(it.kind === 'route' ? ii.r.p : it.kind)}</span></div>`;
+ }).join('') || '<div class="empty">No matches</div>';
+ sRes.querySelectorAll('.r').forEach((r) => { r.addEventListener('mousedown', (ev) => { ev.preventDefault(); pick(+r.dataset.i); }); r.addEventListener('mousemove', () => setActive(+r.dataset.i)); });
+}
+function setActive(i) { sActive = i; sRes.querySelectorAll('.r').forEach((r, k) => r.classList.toggle('active', k === i)); sRes.children[i]?.scrollIntoView({ block: 'nearest' }); }
+function pick(i) { const it = sItems[i]; if (!it) return; closePalette(); reveal(it.id); }
+sInput.addEventListener('input', runSearch);
+sInput.addEventListener('keydown', (ev) => {
+ if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') { ev.preventDefault(); setActive(clamp(sActive + (ev.key === 'ArrowDown' ? 1 : -1), 0, sItems.length - 1)); }
+ else if (ev.key === 'Enter') pick(sActive);
+ else if (ev.key === 'Escape') closePalette();
+});
+pal.addEventListener('mousedown', (ev) => { if (ev.target === pal) closePalette(); });
+$('#search-btn').onclick = openPalette;
+
+// ======================= flows =======================
+const fm = $('#flowmenu');
+fm.addEventListener('click', (ev) => ev.stopPropagation());
+function renderFlowMenu() {
+ fm.innerHTML = G.flows.map((f) => f.custom
+ ? `<div class="r custom" data-flow="${h(f.id)}"><div class="rt"><b>${h(f.title)}<span class="yours">yours</span></b><span>${f.steps.length} steps${f.description ? ' · ' + h(f.description) : ''}</span></div><button class="del" data-del="${h(f.id)}" title="Delete flow">${iconI('x')}</button></div>`
+ : `<div class="r" data-flow="${h(f.id)}"><b>${h(f.title)}</b><span>${f.steps.length} steps${f.description ? ' · ' + h(f.description) : ''}</span></div>`).join('')
+ + (G.flows.length ? '<div class="mi-sep"></div>' : '')
+ + `<div class="r new" data-new>${iconI('spark')}<b>Request a new flow…</b></div>`;
+ fm.querySelectorAll('[data-flow]').forEach((r) => r.onclick = () => { fm.classList.remove('open'); startFlow(r.dataset.flow); });
+ fm.querySelectorAll('[data-del]').forEach((b) => b.onclick = (ev) => { ev.stopPropagation(); deleteCustomFlow(b.dataset.del); });
+ fm.querySelector('[data-new]').onclick = showFlowForm;
+}
+function showFlowForm() {
+ fm.innerHTML = `<form class="ff"><label>Describe what to trace, and Claude builds a step-by-step flow through the map.</label>
+ <textarea placeholder="e.g. How does an order end up charged through Stripe?" spellcheck="false"></textarea>
+ ${askState.engine ? '' : '<div class="note">Needs the Claude Code CLI (run node floorplan/serve.mjs) or the Claude app.</div>'}
+ <div class="ffa"><button type="button" class="btn" data-cancel>Cancel</button><button type="submit" class="btn primary" ${askState.engine ? '' : 'disabled'}>Build flow</button></div></form>`;
+ const form = fm.querySelector('form'), ta = form.querySelector('textarea');
+ setTimeout(() => ta.focus(), 30);
+ ta.addEventListener('keydown', (ev) => { if (ev.key === 'Enter' && !ev.shiftKey) { ev.preventDefault(); form.requestSubmit(); } if (ev.key === 'Escape') { ev.stopPropagation(); renderFlowMenu(); } });
+ form.querySelector('[data-cancel]').onclick = renderFlowMenu;
+ form.onsubmit = (ev) => { ev.preventDefault(); const p = ta.value.trim(); if (!p) return; fm.classList.remove('open'); renderFlowMenu(); requestFlow(p); };
+}
+
+// Custom flows persist next to the map when served (custom-flows.json, folded in by build.mjs),
+// otherwise in this browser. Steps are saved with stable refs so they survive rebuilds.
+const FLOWS_KEY = `flows:${G.project.name}`;
+const stableRef = (id) => id.startsWith('r:') ? `route:${routes[+id.slice(2)].m} ${routes[+id.slice(2)].p}` : id.startsWith('s:') ? `sym:${symOf(id).f.p}#${symOf(id).s[0]}` : id;
+function liveRef(ref) {
+ if (ref.startsWith('route:')) { const i = routes.findIndex((r) => `${r.m} ${r.p}` === ref.slice(6)); return i < 0 ? null : 'r:' + i; }
+ if (ref.startsWith('sym:')) { const p = ref.slice(4, ref.lastIndexOf('#')), nm = ref.slice(ref.lastIndexOf('#') + 1); const i = files.get(p)?.s?.findIndex((s) => s[0] === nm) ?? -1; return i < 0 ? null : `s:${p}#${i}`; }
+ return Q.exists(ref) ? ref : null;
+}
+const toStored = (fl) => ({ id: fl.id, title: fl.title, description: fl.description, steps: fl.steps.map((s) => ({ ref: stableRef(s.ref), note: s.note })) });
+function addFlow(stored) {
+ if (G.flows.some((x) => x.id === stored.id)) return null;
+ const steps = (stored.steps || []).map((s) => ({ ref: liveRef(s.ref), note: s.note || '' })).filter((s) => s.ref);
+ if (steps.length < 2) return null;
+ const fl = { id: stored.id, title: stored.title || 'Flow', description: stored.description || '', steps, custom: true };
+ G.flows.push(fl);
+ return fl;
+}
+const serverApi = (method, body) => fetch('/api/flows', { method, headers: { 'content-type': 'application/json', 'x-floorplan-token': window.FLOORPLAN_SERVER.token }, ...(body ? { body: JSON.stringify(body) } : {}) }).then((r) => r.json());
+async function saveCustomFlow(fl) {
+ if (window.FLOORPLAN_SERVER) { try { await serverApi('POST', { flow: toStored(fl) }); return; } catch {} }
+ store.set(FLOWS_KEY, [...store.get(FLOWS_KEY, []).filter((x) => x.id !== fl.id), toStored(fl)]);
+}
+async function deleteCustomFlow(id) {
+ G.flows = G.flows.filter((x) => x.id !== id);
+ if (state.flow?.f.id === id) stopFlow();
+ if (window.FLOORPLAN_SERVER) { try { await serverApi('DELETE', { id }); } catch {} }
+ store.set(FLOWS_KEY, store.get(FLOWS_KEY, []).filter((x) => x.id !== id));
+ renderFlowMenu();
+}
+async function loadCustomFlows() {
+ for (const s of store.get(FLOWS_KEY, [])) addFlow(s);
+ if (window.FLOORPLAN_SERVER) { try { for (const s of (await serverApi('GET')).flows || []) addFlow(s); } catch {} }
+ renderFlowMenu();
+}
+
+// Served by serve.mjs: reload in place when the map is rebuilt (the view lives in the URL hash). If the
+// server restarts, this tab's token is stale and the stream closes for good, so wait for it to come back.
+(function liveReload() {
+ const S = window.FLOORPLAN_SERVER;
+ if (!S || typeof EventSource === 'undefined') return;
+ const reload = () => { toast('Map updated'); setTimeout(() => location.reload(), 500); };
+ const es = new EventSource('/api/events?token=' + encodeURIComponent(S.token));
+ es.addEventListener('reload', reload);
+ es.onerror = () => {
+ if (es.readyState !== EventSource.CLOSED) return; // a dropped connection retries on its own
+ // every second at first (a restart takes about that long), then every 5s, for up to 30 minutes
+ const t0 = Date.now();
+ const check = () => fetch('/', { cache: 'no-store' }).then((r) => (r.ok ? reload() : next()), next);
+ const next = () => { const age = Date.now() - t0; if (age < 30 * 60000) setTimeout(check, age < 30000 ? 1000 : 5000); };
+ check();
+ };
+})();
+
+async function requestFlow(prompt) {
+ if (!askState.engine) { setWarning(window.FLOORPLAN_SERVER ? 'cli_missing' : 'no_engine'); return; }
+ if (askState.busy) cancelAsk();
+ setBusy(true);
+ askState.ctl = new AbortController();
+ const label = `New flow: ${prompt}`;
+ const lines = ['Thinking…'];
+ const progress = (t) => { lines.push(t); showProgress(label, lines.slice(-6)); };
+ showProgress(label, lines);
+ try {
+ const raw = askState.engine === 'cli' ? await askViaCli(prompt, progress, 'flow') : await askViaApp(prompt, progress, 'flow');
+ const steps = (raw.steps || []).map((s) => ({ ref: String(s.id || ''), note: String(s.note || '') })).filter((s) => Q.exists(s.ref));
+ if (steps.length < 2) throw { code: 'flow_empty', message: "Claude couldn't find enough connected steps for that. Try naming where it starts or ends." };
+ const fl = { id: 'custom-' + Date.now().toString(36), title: String(raw.title || prompt).slice(0, 80), description: String(raw.description || ''), steps, custom: true };
+ G.flows.push(fl);
+ await saveCustomFlow(fl);
+ renderFlowMenu();
+ sheetShell(label, `<p>Added <strong>${h(fl.title)}</strong> to Flows, ${plural(fl.steps.length, 'step')}.${fl.description ? ' ' + h(fl.description) : ''}</p>
+ <div class="sheet-actions"><button class="btn soft" data-play="${h(fl.id)}">${iconI('right')}Play again</button></div>`);
+ sheet.querySelector('[data-play]').onclick = () => startFlow(fl.id);
+ startFlow(fl.id);
+ } catch (e) {
+ if (e?.name === 'AbortError') showFailure(label, 'cancelled');
+ else showFailure(label, e?.code || 'upstream_error', e?.message || String(e));
+ } finally { setBusy(false); }
+}
+const legendEl = $('#legend');
+$('#flows-btn').onclick = (ev) => { ev.stopPropagation(); legendEl.classList.remove('open'); fm.classList.toggle('open'); };
+$('#filters-btn').onclick = (ev) => { ev.stopPropagation(); fm.classList.remove('open'); legendEl.classList.toggle('open'); };
+legendEl.addEventListener('click', (ev) => ev.stopPropagation());
+window.addEventListener('click', () => { fm.classList.remove('open'); legendEl.classList.remove('open'); });
+function startFlow(id) { const f = G.flows.find((x) => x.id === id); if (!f) return; state.flow = { f, i: 0 }; flowStep(); }
+function stopFlow() { state.flow = null; $('#flowbar').hidden = true; vp.querySelectorAll('.flowfx').forEach((x) => x.remove()); select(null); }
+function lcaContainer(a, b) {
+ const cb = new Set(chain(b));
+ for (const x of chain(a)) if (cb.has(x)) return (x === a || x === b) ? (parentOf.get(x) || 'root') : x;
+ return 'root';
+}
+function flowStep() {
+ const { f, i } = state.flow;
+ const a = f.steps[i].ref, b = f.steps[i + 1]?.ref;
+ const container = b ? lcaContainer(a, b) : parentOf.get(a) || 'root';
+ const bar = $('#flowbar'); bar.hidden = false;
+ bar.innerHTML = `<div class="ft"><div class="fk">${h(f.title)} · step ${i + 1} of ${f.steps.length}</div><b>${h(info(a).name)}</b>${b ? ` <span>→</span> <b>${h(info(b).name)}</b>` : ''}<br><span>${h(f.steps[i].note)}</span><div class="dots">${f.steps.map((_, k) => `<i class="${k <= i ? 'on' : ''}"></i>`).join('')}</div></div>
+ <button class="btn icon" id="fl-prev" ${i === 0 ? 'disabled' : ''}>${iconI('left')}</button><button class="btn icon" id="fl-next">${iconI(i >= f.steps.length - 1 ? 'x' : 'right')}</button><button class="btn icon" id="fl-x" title="Exit">${iconI('x')}</button>`;
+ $('#fl-prev').onclick = () => { state.flow.i--; flowStep(); };
+ $('#fl-next').onclick = () => { if (state.flow.i >= f.steps.length - 1) stopFlow(); else { state.flow.i++; flowStep(); } };
+ $('#fl-x').onclick = stopFlow;
+ // an answer's walkthrough plays on the answer board itself
+ if (state.flow.inPlace) { if (state.container === 'q:answer') highlightFlow(a, b); else go('q:answer', { after: () => highlightFlow(a, b) }); }
+ else go(container, { after: () => highlightFlow(a, b) });
+}
+function highlightFlow(a, b) {
+ vp.querySelectorAll('.flowfx').forEach((x) => x.remove());
+ const ctx = { container: state.container, vis: new Set(state.view.visible), cchain: new Set(chain(state.container)) };
+ const pa = project(a, ctx)?.item, pb = b ? project(b, ctx)?.item : null;
+ svg.classList.add('dim');
+ for (const g of state.chipEls.values()) g.classList.remove('hl', 'sel');
+ for (const x of state.edgeEls.values()) { x.g.classList.remove('hl'); x.pg.classList.remove('hl'); }
+ if (pa) state.chipEls.get(pa)?.classList.add('hl', 'sel');
+ if (pb) state.chipEls.get(pb)?.classList.add('hl');
+ if (!pa || !pb) return;
+ let path = null;
+ for (const x of state.edgeEls.values()) if ((x.e.a === pa && x.e.b === pb) || (x.e.a === pb && x.e.b === pa)) { x.g.classList.add('hl'); x.pg.classList.add('hl'); path = { d: x.d, reverse: x.e.a === pb }; break; }
+ if (!path) {
+ const A = state.layout.children.find((c) => c.id === pa), B = state.layout.children.find((c) => c.id === pb);
+ const x1 = A.x + A.width, y1 = A.y + A.height / 2, x2 = B.x, y2 = B.y + B.height / 2, mx = (x1 + x2) / 2;
+ path = { d: roundedPath([{ x: x1, y: y1 }, { x: mx, y: y1 }, { x: mx, y: y2 }, { x: x2, y: y2 }]), reverse: false };
+ el('path', { class: 'flowlink flowfx', d: path.d }, state.fxLayer);
+ }
+ const dot = el('circle', { class: 'pulse flowfx', r: 4.5 }, state.fxLayer);
+ const anim = el('animateMotion', { dur: '1.5s', repeatCount: 'indefinite', path: path.d, keyPoints: path.reverse ? '1;0' : '0;1', keyTimes: '0;1', calcMode: 'linear' }, dot);
+ anim.beginElement?.();
+}
+
+// ======================= ask (Claude Code CLI via serve.mjs, or the Claude app) =======================
+const Q = createGraphQuery(G);
+const askState = { engine: null, sample: null, busy: false, ctl: null, session: null, turns: [], last: null };
+const askInput = $('#ask-input'), askSend = $('#ask-send'), sheet = $('#ask-sheet'), warn = $('#ask-warn');
+const DOCS = 'https://docs.claude.com/en/docs/claude-code/overview';
+const WARNINGS = {
+ no_engine: `Asking needs the <b>Claude Code CLI</b>. From the codebase root run <code>node floorplan/serve.mjs</code>, or open this map in the Claude app.`,
+ cli_missing: `Requires the <b>Claude Code CLI</b> installed to work. <a href="${DOCS}" target="_blank" rel="noopener">Install it</a>, then restart <code>serve.mjs</code>.`,
+ not_logged_in: `The Claude Code CLI isn't signed in. Run <code>claude</code> in a terminal once to sign in, then ask again.`,
+ app_unavailable: `Claude isn't available for this map in this view.`,
+ not_granted: `Claude access was declined for this map. Reload the page to be asked again.`,
+ cli_tip: `Install the <b>Claude Code CLI</b> for a better experience: it can read your source code, not just this map. <a href="${DOCS}" target="_blank" rel="noopener">Install it</a>, then run <code>node floorplan/serve.mjs</code> in the codebase.`,
+};
+function setWarning(code) {
+ warn.hidden = !code;
+ warn.classList.toggle('info', code === 'cli_tip');
+ if (!code) return;
+ warn.innerHTML = `<svg class="i" viewBox="0 0 24 24"><path d="M12 9v4M12 17h.01M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0z"/></svg><span>${WARNINGS[code] || h(code)}</span>${code === 'no_engine' ? '<button type="button" data-copycmd>Copy command</button>' : code === 'cli_tip' ? '<button type="button" data-dismiss>Got it</button>' : ''}`;
+ warn.querySelector('[data-dismiss]')?.addEventListener('click', () => setWarning(null));
+ warn.querySelector('[data-copycmd]')?.addEventListener('click', (e) => { navigator.clipboard?.writeText('node floorplan/serve.mjs'); e.target.textContent = 'Copied'; });
+}
+function setEngine(engine, label, warning) {
+ askState.engine = engine;
+ const tag = $('#ask-engine');
+ tag.className = 'engine ' + (engine ? 'ok' : 'warn');
+ tag.innerHTML = `<i></i>${h(engine ? label : 'Unavailable')}${engine === 'app' ? `<button type="button" class="einfo" title="Install the Claude Code CLI for a better experience" aria-label="About the Claude Code CLI"><svg class="i" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><path d="M12 11v5M12 8h.01"/></svg></button>` : ''}`;
+ tag.querySelector('.einfo')?.addEventListener('click', () => setWarning(warn.hidden || !warn.classList.contains('info') ? 'cli_tip' : null));
+ tag.title = engine === 'cli' ? 'Answers come from your local Claude Code CLI, which can read the source' : engine === 'app' ? 'Answers come from Claude in the Claude app, using the map (not the source files)' : '';
+ askInput.disabled = !engine;
+ askSend.disabled = !engine;
+ askInput.placeholder = engine ? `Ask anything about ${G.project.name}…` : 'Asking is unavailable';
+ if (typeof renderChips === 'function' && askState.context) renderChips();
+ setWarning(warning || null);
+}
+async function detectEngine() {
+ const S = window.FLOORPLAN_SERVER;
+ if (S) { S.cli ? setEngine('cli', 'Claude Code' + (S.model ? ' · ' + S.model : '')) : setEngine(null, null, 'cli_missing'); return; }
+ if (window.claude?.use) {
+ setEngine(null, null); $('#ask-engine').innerHTML = '<i></i>connecting…';
+ let sample = null;
+ try { sample = await window.claude.use('sample'); } catch {}
+ const lim = sample ? await sample.limits().catch(() => null) : null;
+ if (sample && lim?.tools) { askState.sample = sample; setEngine('app', 'Claude'); return; }
+ setEngine(null, null, 'app_unavailable');
+ return;
+ }
+ setEngine(null, null, 'no_engine');
+}
+
+// tiny markdown: paragraphs, lists, **bold**, `code`, [[id]] references
+function refChip(id) {
+ const b = Q.brief(id);
+ if (!b) return h(id);
+ const ii = info(id);
+ return `<span class="ref" data-ref="${h(id)}" style="--c:${colorOf(ii)}"><i></i>${h(b.name)}</span>`;
+}
+function md(src) {
+ const inline = (s) => h(s).replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>').replace(/`([^`]+)`/g, '<code>$1</code>').replace(/\[\[([^\]]+)\]\]/g, (_, id) => refChip(id.replace(/&#39;|&quot;/g, '').trim()));
+ const out = [];
+ let list = null;
+ for (const raw of String(src || '').split('\n')) {
+ const line = raw.trim();
+ const li = /^([-*]|\d+\.)\s+(.*)$/.exec(line);
+ if (li) { const tag = /\d/.test(li[1]) ? 'ol' : 'ul'; if (list !== tag) { if (list) out.push(`</${list}>`); out.push(`<${tag}>`); list = tag; } out.push(`<li>${inline(li[2])}</li>`); continue; }
+ if (list) { out.push(`</${list}>`); list = null; }
+ if (line) out.push(`<p>${inline(line.replace(/^#+\s*/, ''))}</p>`);
+ }
+ if (list) out.push(`</${list}>`);
+ return out.join('');
+}
+
+function sheetShell(question, body) {
+ sheet.hidden = false;
+ sheet.innerHTML = `<div class="sh"><span class="q" title="${h(question)}">${h(question)}</span>
+ ${askState.last && state.container !== 'q:answer' ? '<button class="btn soft" data-act="board">Show answer board</button>' : ''}
+ ${state.container === 'q:answer' ? '<button class="btn soft" data-act="map">Back to map</button>' : ''}
+ <button class="btn icon" data-act="close" title="Close">${iconI('x')}</button></div><div class="sb">${body}</div>`;
+ sheet.querySelector('[data-act="close"]').onclick = () => { if (askState.busy) cancelAsk(); sheet.hidden = true; if (state.container === 'q:answer') go('root'); else fit(true); };
+ sheet.querySelector('[data-act="map"]')?.addEventListener('click', () => go('root'));
+ sheet.querySelector('[data-act="board"]')?.addEventListener('click', () => go('q:answer'));
+ sheet.querySelectorAll('[data-ref]').forEach((r) => r.onclick = () => {
+ const id = r.dataset.ref;
+ if (state.container === 'q:answer' && state.view.visible.includes(id)) { select(id); centerOn(id); } else reveal(id);
+ });
+ sheet.querySelectorAll('[data-follow]').forEach((b) => b.onclick = () => { askInput.value = b.dataset.follow; submitAsk(); });
+ sheet.querySelector('[data-act="steps"]')?.addEventListener('click', () => {
+ const a = askState.last;
+ state.flow = { f: { title: a.title, steps: a.steps.map((s) => ({ ref: s.id, note: s.note })) }, i: 0, inPlace: true };
+ flowStep();
+ });
+}
+function showProgress(question, lines) {
+ sheetShell(question, `<div class="progress">${lines.map((l, i) => `<div>${i === lines.length - 1 ? '<span class="spin"></span>' : '<span style="width:12px;display:inline-block;text-align:center">✓</span>'}${h(l)}</div>`).join('')}</div>`);
+}
+function renderAnswer(a) {
+ const steps = a.steps?.length >= 2;
+ sheetShell(a.question, `${md(a.answer)}
+ <div class="sheet-actions">${steps ? `<button class="btn soft" data-act="steps">${iconI('right')}Walk through ${a.steps.length} steps</button>` : ''}</div>
+ ${a.followups?.length ? `<div class="followups">${a.followups.slice(0, 3).map((f) => `<button data-follow="${h(f)}">${h(f)}</button>`).join('')}</div>` : ''}`);
+}
+function showAnswer(raw, question) {
+ const clean = (arr) => (Array.isArray(arr) ? arr : []).map((x) => typeof x === 'string' ? { id: x, note: '' } : x).filter((x) => x && Q.exists(String(x.id))).map((x) => ({ id: String(x.id), note: String(x.note || '') }));
+ const items = clean(raw.items);
+ const steps = clean(raw.steps);
+ for (const s of steps) if (!items.some((x) => x.id === s.id)) items.push({ id: s.id, note: s.note });
+ const a = { title: String(raw.title || 'Answer'), answer: String(raw.answer || ''), items: items.slice(0, 18), steps, followups: (raw.followups || []).map(String), question };
+ askState.last = a;
+ if (a.items.length) { state.answer = a; go('q:answer', { force: true, after: () => renderAnswer(a) }); }
+ else renderAnswer(a);
+}
+function showFailure(question, code, message, partial) {
+ if (code === 'not_logged_in' || code === 'not_granted') setWarning(code);
+ if (code === 'not_granted' || code === 'sampling_disabled') setEngine(null, null, code === 'not_granted' ? 'not_granted' : 'app_unavailable');
+ if (code === 'cancelled') { sheet.hidden = true; return; }
+ const copy = { rate_limited: 'Claude is busy or you have hit a usage limit. Try again in a bit.', not_logged_in: 'The Claude Code CLI needs you to sign in first.', cli_missing: 'Claude Code CLI not found.', invalid_json: "Claude's answer couldn't be read as a map view. Try rephrasing.", session_expired: 'Your Claude session expired. Sign in again.' }[code];
+ sheetShell(question, `<p class="err">${h(copy || message || 'Something went wrong.')}</p>${partial ? md(partial) : ''}${code === 'cli_error' && message ? `<p style="font-family:var(--mono);font-size:11px;color:var(--text-3)">${h(message.slice(0, 400))}</p>` : ''}`);
+}
+function setBusy(b) {
+ askState.busy = b;
+ askSend.classList.toggle('stop', b);
+ askSend.innerHTML = b ? `<svg class="i" viewBox="0 0 24 24"><rect x="7" y="7" width="10" height="10" rx="2"/></svg>` : `<svg class="i" viewBox="0 0 24 24"><path d="M12 19V5M5 12l7-7 7 7"/></svg>`;
+ askSend.title = b ? 'Stop' : 'Ask';
+}
+function cancelAsk() {
+ askState.ctl?.abort();
+ if (askState.engine === 'cli') fetch('/api/cancel', { method: 'POST', headers: { 'x-floorplan-token': window.FLOORPLAN_SERVER.token } }).catch(() => {});
+}
+
+async function askViaCli(question, progress, mode = 'ask') {
+ const res = await fetch('/api/ask', {
+ method: 'POST', signal: askState.ctl.signal,
+ headers: { 'content-type': 'application/json', 'x-floorplan-token': window.FLOORPLAN_SERVER.token },
+ body: JSON.stringify({ question, mode, session: mode === 'ask' ? askState.session : undefined }),
+ });
+ if (!res.ok || !res.body) throw { code: 'cli_error', message: `Server returned ${res.status}` };
+ const reader = res.body.getReader(), dec = new TextDecoder();
+ let buf = '', answer = null;
+ for (;;) {
+ const { value, done } = await reader.read();
+ if (done) break;
+ buf += dec.decode(value, { stream: true });
+ let i;
+ while ((i = buf.indexOf('\n\n')) >= 0) {
+ const block = buf.slice(0, i); buf = buf.slice(i + 2);
+ const ev = /^event: (.*)$/m.exec(block)?.[1], data = JSON.parse(/^data: (.*)$/m.exec(block)?.[1] || 'null');
+ if (ev === 'progress') progress(data.text);
+ else if (ev === 'answer') { answer = data; if (mode === 'ask') askState.session = data.session || askState.session; }
+ else if (ev === 'failure') throw data;
+ }
+ }
+ if (!answer) throw { code: 'cli_error', message: 'The CLI ended without an answer.' };
+ return answer;
+}
+
+async function askViaApp(question, progress, mode = 'ask') {
+ const clip = (v) => { const s = JSON.stringify(v); return s.length > 24000 ? s.slice(0, 24000) + '…(truncated)' : s; };
+ const tools = [
+ { name: 'find_items', description: 'Search the map by words. Returns up to 15 items {id, type, name, description, path}. kind optionally limits results to module, file, endpoint or symbol.',
+ inputSchema: { type: 'object', properties: { query: { type: 'string' }, kind: { type: 'string', enum: ['module', 'file', 'endpoint', 'symbol'] } }, required: ['query'] },
+ execute: ({ query, kind }) => { progress(`Searching the map for "${query}"`); return clip(Q.find(String(query), kind ? String(kind) : undefined)); } },
+ { name: 'get_item', description: "Details of one map item by id: its description, parent module, children/files, endpoints, exports, and what it depends on and is used by (with ids).",
+ inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+ execute: ({ id }) => { const b = Q.brief(String(id)); progress(`Looking at ${b ? b.name : id}`); return clip(Q.show(String(id))); } },
+ { name: 'dependency_path', description: 'Shortest chain of imports/HTTP calls from anything inside one item to anything inside another. Returns hops with ids.',
+ inputSchema: { type: 'object', properties: { from: { type: 'string' }, to: { type: 'string' } }, required: ['from', 'to'] },
+ execute: ({ from, to }) => { progress('Tracing a dependency path'); return clip(Q.path(String(from), String(to))); } },
+ ];
+ const flow = mode === 'flow';
+ const rules = `${flow ? floorplanFlowInstructions(G, 'app') : floorplanAskInstructions(G, 'app')}\nThe JSON must match this schema:\n${JSON.stringify(flow ? FLOORPLAN_FLOW_SCHEMA : FLOORPLAN_ANSWER_SCHEMA)}\n\nMap overview:\n${clip(Q.overview())}`;
+ const turns = [{ role: 'user', content: rules }, ...(flow ? [] : askState.turns.slice(-6)), { role: 'user', content: question }];
+ const answer = await askState.sample.json(turns, { tools, signal: askState.ctl.signal });
+ if (flow) return answer || {};
+ askState.turns.push({ role: 'user', content: question }, { role: 'assistant', content: JSON.stringify({ title: answer?.title, answer: answer?.answer }) });
+ return answer || {};
+}
+
+askState.context = [];
+/** Pin a map item to the next question ("Ask about this"). */
+function addAskContext(id) {
+ if (!Q.exists(id)) return;
+ askState.context = [...askState.context.filter((x) => x !== id), id].slice(-3);
+ renderChips();
+ askInput.focus();
+}
+function renderChips() {
+ const box = $('#ask-chips');
+ box.innerHTML = askState.context.map((id) => { const i = info(id); return `<span class="chip" title="${h(i.path || '')}"><span class="ico" style="--c:${colorOf(i)}">${icon(iconKey(i))}</span><span>${h(i.name)}</span><button type="button" data-rm="${h(id)}" aria-label="Remove">${iconI('x')}</button></span>`; }).join('');
+ box.querySelectorAll('[data-rm]').forEach((b) => b.onclick = () => { askState.context = askState.context.filter((x) => x !== b.dataset.rm); renderChips(); askInput.focus(); });
+ askInput.placeholder = !askState.engine ? 'Asking is unavailable' : askState.context.length ? 'Ask about this…' : `Ask anything about ${G.project.name}…`;
+ askSend.disabled = !askState.engine;
+}
+askInput.addEventListener('keydown', (ev) => { if (ev.key === 'Backspace' && !askInput.value && askState.context.length) { askState.context.pop(); renderChips(); } });
+
+async function submitAsk() {
+ if (askState.busy) { cancelAsk(); return; }
+ const ctxIds = askState.context.slice();
+ let question = askInput.value.trim();
+ if (!question && ctxIds.length) question = ctxIds.length === 1 ? `What is ${info(ctxIds[0]).name} and how does it fit in?` : `How do ${ctxIds.map((id) => info(id).name).join(' and ')} relate?`;
+ if (!question || !askState.engine) return;
+ askInput.value = '';
+ askState.context = []; renderChips();
+ const shown = question;
+ // what Claude sees: the question plus the pinned items, by id, so it starts from them
+ if (ctxIds.length) question += `\n\nFocus on these map items: ${ctxIds.map((id) => `${id} (${info(id).name})`).join(', ')}.`;
+ setBusy(true);
+ askState.ctl = new AbortController();
+ const lines = ['Thinking…'];
+ const progress = (t) => { lines.push(t); showProgress(shown, lines.slice(-6)); };
+ showProgress(shown, lines);
+ try {
+ const raw = askState.engine === 'cli' ? await askViaCli(question, progress) : await askViaApp(question, progress);
+ showAnswer(raw, shown);
+ } catch (e) {
+ if (e?.name === 'AbortError') showFailure(shown, 'cancelled');
+ else showFailure(shown, e?.code || 'upstream_error', e?.message || String(e), e?.text && e.code !== 'invalid_json' ? e.text : '');
+ } finally { setBusy(false); }
+}
+$('#ask-form').addEventListener('submit', (ev) => { ev.preventDefault(); submitAsk(); });
+askSend.addEventListener('click', (ev) => { if (askState.busy) { ev.preventDefault(); cancelAsk(); } });
+detectEngine();
+renderFlowMenu();
+loadCustomFlows();
+
+// ======================= boot =======================
+$('#proj-name').textContent = G.project.name;
+document.title = `${G.project.name} map`;
+$('#btn-up').onclick = up;
+// drag the panel's left edge to resize it; the width sticks between visits
+const setPanelWidth = (w) => { document.documentElement.style.setProperty('--panel-w', `${clamp(Math.round(w), 300, Math.min(720, innerWidth - 360))}px`); };
+setPanelWidth(store.get('panelWidth', 360));
+$('#panel-resize').addEventListener('pointerdown', (ev) => {
+ ev.preventDefault();
+ const handle = ev.currentTarget;
+ handle.setPointerCapture(ev.pointerId);
+ document.body.classList.add('resizing');
+ const move = (e) => setPanelWidth(innerWidth - e.clientX - 16);
+ const end = () => {
+ document.body.classList.remove('resizing');
+ handle.removeEventListener('pointermove', move);
+ store.set('panelWidth', $('#panel').offsetWidth);
+ };
+ handle.addEventListener('pointermove', move);
+ handle.addEventListener('pointerup', end, { once: true });
+ handle.addEventListener('pointercancel', end, { once: true });
+});
+$('#panel-resize').addEventListener('dblclick', () => { setPanelWidth(360); store.set('panelWidth', 360); });
+const setPanel = (on) => { const was = !document.body.classList.contains('no-panel'); document.body.classList.toggle('no-panel', !on); store.set('panel', on); if (was !== on) fit(true); };
+document.body.classList.toggle('no-panel', !store.get('panel', true));
+$('#btn-panel').onclick = () => setPanel(document.body.classList.contains('no-panel'));
+Object.assign(state.kinds, store.get('kinds', {}));
+window.addEventListener('keydown', (ev) => {
+ if (pal.classList.contains('open') || ev.target.tagName === 'INPUT') return;
+ if (ev.key === '/' || (ev.key === 'k' && (ev.metaKey || ev.ctrlKey))) { ev.preventDefault(); openPalette(); }
+ else if (ev.key === 'Backspace') { ev.preventDefault(); up(); }
+ else if (ev.key === 'Escape') {
+ if (!ctxEl.hidden || fm.classList.contains('open') || legendEl.classList.contains('open')) { closeMenu(); fm.classList.remove('open'); legendEl.classList.remove('open'); }
+ else if (state.flow) stopFlow(); else if (state.selected) select(null); else up();
+ }
+ else if (ev.key === 'f' || ev.key === 'F') fit(true);
+ else if (ev.key === 'p' || ev.key === 'P') $('#btn-panel').click();
+ else if (ev.key === 'Enter' && typeof state.selected === 'string') open(state.selected);
+ else if (state.flow && ev.key === 'ArrowRight') $('#fl-next')?.click();
+ else if (state.flow && ev.key === 'ArrowLeft') $('#fl-prev')?.click();
+ else if (ev.key === '=' || ev.key === '+') zoomBy(1.2);
+ else if (ev.key === '-') zoomBy(0.83);
+});
+// ======================= extension API =======================
+// Features in assets/ui/*.js are inlined after this script and talk to the viewer only through
+// window.Floorplan. Keep this surface small and stable.
+function setTechnical(on) {
+ technicalFlag = !!on; store.set('technical', technicalFlag);
+ chainCache.clear();
+ render({ keepTransform: true, after: renderPanel });
+ emit('technical', technicalFlag);
+}
+function showModal({ title = '', html = '', actions = [] } = {}) {
+ const m = $('#modal'), box = m.querySelector('.box');
+ box.innerHTML = `<h2>${h(title)}</h2><div class="mb">${html}</div><div class="ma">${actions.map((a, i) => `<button class="btn ${a.primary ? 'primary' : 'soft'}" data-mi="${i}">${a.icon ? iconI(a.icon) : ''}${h(a.label)}</button>`).join('')}<button class="btn" data-close>Close</button></div>`;
+ const close = () => m.classList.remove('open');
+ box.querySelectorAll('[data-mi]').forEach((b) => b.onclick = () => { const a = actions[+b.dataset.mi]; if (a.onClick?.(close) !== false && !a.keepOpen) close(); });
+ box.querySelector('[data-close]').onclick = close;
+ m.onmousedown = (ev) => { if (ev.target === m) close(); };
+ m.classList.add('open');
+ return { close, el: box };
+}
+let toastTimer = null;
+function toast(msg) { const t = $('#toast'); t.textContent = msg; t.classList.add('on'); clearTimeout(toastTimer); toastTimer = setTimeout(() => t.classList.remove('on'), 2200); }
+function showBoard({ title, question = '', answer = '', items = [], steps = [], kind = '', icon: ic = '' }) {
+ const clean = (arr) => (arr || []).map((x) => typeof x === 'string' ? { id: x, note: '' } : x).filter((x) => x && Q.exists(String(x.id))).map((x) => ({ id: String(x.id), note: String(x.note || '') }));
+ const a = { title: title || 'Board', question, answer, items: clean(items).slice(0, 24), steps: clean(steps), followups: [], ...(kind ? { kind } : {}), ...(ic ? { icon: ic } : {}) };
+ if (!a.items.length) { toast('Nothing on the map matches that.'); return; }
+ state.answer = a; askState.last = a;
+ go('q:answer', { force: true });
+}
+function playFlow({ title = 'Tour', description = '', steps = [], inPlace = false }) {
+ const st = steps.map((s) => ({ ref: s.ref || s.id, note: s.note || '', title: s.title || '' })).filter((s) => Q.exists(s.ref) || s.ref === 'root');
+ if (!st.length) return;
+ state.flow = { f: { id: 'tmp-' + Date.now(), title, description, steps: st }, i: 0, inPlace };
+ flowStep();
+}
+const ext = { sections: { overview: [], item: [] }, listeners: {} };
+const custom = { panel: null };
+function emit(event, data) { for (const fn of ext.listeners[event] || []) { try { fn(data); } catch (e) { console.error('floorplan extension', e); } } }
+window.Floorplan = Object.freeze({
+ version: 1,
+ graph: G, query: Q, state,
+ // model helpers
+ info, chain, children: (id) => visibleKids(id), parentOf: (id) => parentOf.get(id), exists: (id) => Q.exists(id),
+ files, nodes, routes, colorOf, iconKey,
+ // html helpers
+ h, icon, iconI, fmt, plural, md,
+ // navigation
+ go, reveal, select, open, up, fit, render: (o) => render({ keepTransform: true, ...o }), refreshPanel: () => renderPanel(),
+ showBoard, playFlow, startFlow, stopFlow: () => { if (state.flow) stopFlow(); },
+ freeArea: () => freeArea(),
+ closeMenus: () => { closeMenu(); fm.classList.remove('open'); legendEl.classList.remove('open'); },
+ // asking
+ addAskContext, ask: (text) => { askInput.value = text; submitAsk(); }, askEngine: () => askState.engine,
+ // chrome
+ addHeaderButton({ id, label = '', icon: ic, svg, title = '', onClick }) {
+ const b = document.createElement('button');
+ b.className = 'btn' + (label ? '' : ' icon'); if (id) b.id = id; b.title = title || label;
+ b.innerHTML = `${svg ? `<svg class="i" viewBox="0 0 24 24">${svg}</svg>` : ic ? iconI(ic) : ''}${label ? `<span class="bl">${h(label)}</span>` : ''}`;
+ b.onclick = (ev) => { ev.stopPropagation(); onClick?.(ev, b); };
+ $('#hdr-ext').appendChild(b);
+ return b;
+ },
+ addPanelSection(where, fn) { (ext.sections[where] ||= []).push(fn); },
+ showPanel(html, bind) { custom.panel = { html, bind }; setPanel(true); renderPanel(); },
+ closePanel() { custom.panel = null; renderPanel(); },
+ modal: showModal, toast, copy: (text) => copy(text),
+ icons: P,
+ technical, setTechnical,
+ store,
+ on(event, fn) { (ext.listeners[event] ||= []).push(fn); },
+});
+technicalFlag = !!store.get('technical', false);
+
+const init = readHash();
+state.container = init.v; state.selected = init.s;
+const fontsReady = document.fonts?.ready ? Promise.race([document.fonts.ready, new Promise((ok) => setTimeout(ok, 1500))]) : Promise.resolve();
+fontsReady.then(() => render({ after: () => { renderPanel(); emit('ready', {}); } }));
+})();
+</script>
+<!--__UI_EXTENSIONS__-->
+</body>
+</html>
diff --git a/skills/floorplan/references/choosing-boundaries.md b/skills/floorplan/references/choosing-boundaries.md
new file mode 100644
index 0000000..92ef624
--- /dev/null
+++ b/skills/floorplan/references/choosing-boundaries.md
@@ -0,0 +1,40 @@
+# Choosing boundaries
+
+The board is useful when each chip is something a person would name in a whiteboard conversation. It's useless when it just mirrors the folder tree. Use these heuristics to get there.
+
+## The top-level board (3–9 chips)
+
+Ask: *what are the deployable or ownable things, and what do they talk to?*
+
+- **Multi-repo codebase.** Usually one chip per deployable (frontend, API, worker, a second app like an admin panel or a mobile app), plus shared libraries, plus externals. The repo is not always the unit: a backend repo might hold an API *and* a worker *and* an MCP connector, so give each its own chip.
+- **Monorepo** (`apps/*`, `packages/*`, `services/*`). Apps and services become top-level chips. Group packages as one `Shared libraries` chip with children, unless a package is big and central.
+- **Single monolith.** Use layers or domains as the top level (`Web layer`, `Domain services`, `Data`, `Jobs`), or the 4–8 biggest domains if the code is organized by feature. Choose the one the code actually follows.
+- **Externals.** Add the database(s) and each third-party API the code meaningfully depends on. Use the scan's EXTERNAL PACKAGES and EXTERNAL HOSTS lists; `packages` and `hosts` on external nodes connect them automatically. Skip utility libraries (react, lodash, pytest). They're dependencies, not architecture.
+- **Tests, scripts, migrations.** Give them their own top-level chips (`kind: test`, `script`, `data`) rather than mixing them into the service. Otherwise they bury the real dependency structure: tests import everything.
+
+## Second level (3–12 per chip)
+
+- Prefer **responsibility** over **file type**. "Orders", "Inventory" and "Auth" beat "routes", "services" and "models" when the code is organized that way. But if the code really is layered (routes/ → services/ → models/), mirror the layers. A layered board that shows routes → services → models is honest and readable.
+- A child is worth making when it has a clear one-sentence purpose and enough files (roughly 3+) or importance (a central API client) to matter.
+- Large UI component trees: group by feature area (`products`, `orders`, `checkout`), and keep a `UI kit` chip for shared primitives (`components/ui`). The kit will have many incoming traces. That's correct and useful to see.
+- Don't go deeper than three levels of nodes. The viewer already gives you folder, file and symbol levels below your nodes.
+
+## Covering the files
+
+- Write broad globs on parents (`backend/app/**`), then narrower ones on children. The deepest match wins, so you never need `exclude` just to stop a parent stealing a child's files.
+- After building, look at `unassigned, by directory`, and give each sizeable directory a home or an `ignore` entry.
+- `ignore` is for things that aren't the system: generated clients, vendored copies, snapshot fixtures, one-off data dumps. It's not for tests or scripts, which belong on their own chips.
+
+## Summaries
+
+One sentence, about responsibility, in the codebase's own vocabulary. "Syncs product catalog and inventory with Shopify" beats "Contains Shopify-related services". Mention the framework only at the top level.
+
+## Flows
+
+Pick the 1–3 things the system exists to do (take an order, sync inventory, run a nightly job). Trace them across the board in 3–7 steps from the user or trigger to the final side effect. Check that consecutive steps are actually connected by an import, HTTP or explicit edge; if not, add the missing edge. The flow should make the system's main path obvious to someone seeing it for the first time.
+
+## Sanity checks before you finish
+
+- Does the top-level board, read left to right, tell the system's story (UI → API → services → data/externals)?
+- Is any chip connected to almost everything? That's either a shared kit (fine, label it) or a sign the boundary is wrong.
+- Are there traces you didn't expect, like the frontend importing backend code, or tests that are imported by production code? Mention them to the user; they're often the most valuable finding.
diff --git a/skills/floorplan/references/schema.md b/skills/floorplan/references/schema.md
new file mode 100644
index 0000000..4897ef2
--- /dev/null
+++ b/skills/floorplan/references/schema.md
@@ -0,0 +1,170 @@
+# architecture.json schema
+
+`floorplan/architecture.json` describes the structure: subsystems, modules, external services, flows. Names and descriptions for individual files and routes go in `floorplan/descriptions/*.json` instead (see [writing-descriptions.md](writing-descriptions.md)). They're kept separate so parallel agents can write them without conflicts. `build.mjs` checks both against the scan and reports problems by field.
+
+Contents: [Top level](#top-level) · [nodes](#nodes) · [Assignment rules](#how-files-get-assigned) · [edges](#edges) · [annotations](#annotations) · [flows](#flows) · [Recent work](#recent-work) · [Full example](#full-example)
+
+## Top level
+
+| field | type | required | meaning |
+|---|---|---|---|
+| `$schema` | `"floorplan/architecture@1"` | no | marker |
+| `project` | object | yes | `name` (string, required), `summary` (1–3 sentences), `entrypoints` (file paths) |
+| `nodes` | array | yes | subsystems and modules. See below |
+| `edges` | array | no | connections the scanner can't see |
+| `annotations` | array | no | notes pinned to specific files |
+| `flows` | array | no | guided walkthroughs through the board |
+| `tour` | array | no | the "Start here" tour shown on first open: 3–8 stops `{ "node": "<node id or file path>", "title": "…", "note": "…" }`, in plain language, in the order a newcomer should see them. The first flow is appended automatically |
+| `audience` | `"everyone"` \| `"developers"` | no | who names and descriptions are written for. Default `"everyone"`: plain language a non-technical owner understands (what it does for the business, in everyday words). `"developers"`: technical style for engineers |
+| `include` | string[] | no | file categories to map. Default `["code"]`. Others: `config`, `docs` |
+| `ignore` | string[] | no | globs for files to leave off the board entirely (generated code, vendored libs, fixtures) |
+
+## nodes
+
+Each node is a chip on the board. Hierarchy comes from `parent`. A node with no parent sits on the top-level board.
+
+| field | type | meaning |
+|---|---|---|
+| `id` | string | unique; letters, digits, `_ - .`. Convention: dotted by parent (`api.orders`) |
+| `label` | string | short display name ("Orders API") |
+| `kind` | enum | `ui` `service` `worker` `library` `feature` `data` `config` `test` `script` `infra` `external` |
+| `parent` | string | id of the enclosing node |
+| `summary` | string | one sentence: what it's responsible for |
+| `details` | string | optional longer notes; blank lines separate paragraphs |
+| `paths` | string[] | globs claiming files (see below) |
+| `exclude` | string[] | globs to carve files back out of `paths`. **Inherited by all descendants**, e.g. `"exclude": ["**/*.test.tsx"]` on a frontend node keeps co-located tests out of every child, so a separate Tests node can claim them |
+| `packages` | string[] | **external nodes:** package names this node stands for, e.g. `"stripe"`, `"npm:@stripe/*"`, `"pypi:sqlalchemy"`. Imports of them become edges to this node |
+| `hosts` | string[] | **external nodes:** hostnames called from code, e.g. `"api.stripe.com"`, `"*.squareup.com"`. Calls become `http` edges |
+| `tags` | string[] | free-form, shown in the panel |
+
+Kinds, briefly:
+- `ui`: frontends and apps
+- `service`: a deployable server
+- `worker`: background jobs and queues
+- `library`: shared code
+- `feature`: a vertical slice inside a service or UI
+- `data`: models, migrations, the DB layer
+- `config`
+- `test`
+- `script`: one-off and ops scripts
+- `infra`: deploy, CI, IaC
+- `external`: databases and third-party APIs. These own no files.
+
+### Glob syntax
+- `**` matches any number of directories, `*` stays within one path segment, `?` matches one character, `{a,b}` is alternation.
+- A pattern with no wildcard also matches as a directory: `backend/app` equals `backend/app/**`.
+- Paths are relative to the codebase root. In a multi-repo root they start with the repo folder.
+
+### How files get assigned
+Every included file goes to exactly one node:
+1. Collect the nodes whose `paths` match the file and whose `exclude` doesn't.
+2. The **deepest** node wins, so a child beats its parent. You can give a parent a broad glob (`web/**`) and children narrower ones; files no child claims stay on the parent.
+3. Between nodes at the same depth, the glob with the longer literal prefix wins. Real ties are warned about.
+4. Files no node claims go to an automatic **Unassigned** chip. Keep it under ~10%.
+
+In the viewer, a node with more than ~24 files of its own groups them into folder chips automatically, so you don't need a node for every directory. Make a node when it means something.
+
+## edges
+
+Only add what static analysis can't find. Imports (`import`) and HTTP calls matched to routes (`http`) are already in the scan.
+
+| field | type | meaning |
+|---|---|---|
+| `from`, `to` | string | node id **or** file path |
+| `kind` | enum | `import` `call` `http` `rpc` `event` `queue` `data` `config` |
+| `label` | string | short, e.g. `"POST /orders"`, `"order.paid"`, `"reads/writes"` |
+| `description` | string | optional sentence shown when the trace is clicked |
+
+Good candidates:
+- service → database (`data`)
+- publisher → queue → consumer (`queue` / `event`)
+- webhooks coming in from third parties (`http`, from the external node to the handler)
+- cron/scheduler → job (`call`)
+- calls through env-configured base URLs that the matcher missed (`http`)
+
+## annotations
+
+`{ "path": "<file>", "note": "…", "tags": ["hotspot"] }` pins a note to a file. The file's chip gets an accent outline. Use these sparingly, for god-files, tricky invariants, or deprecated code still in use.
+
+## flows
+
+```json
+{ "id": "checkout", "title": "Checkout", "description": "optional",
+ "steps": [ { "node": "web.cart", "note": "User clicks Pay" }, { "node": "api.orders", "note": "Creates the order" } ] }
+```
+- Each step's `node` is a node id or a file path. There must be at least 2 steps.
+- The viewer moves to the board where each pair of consecutive steps is visible and animates a signal between them.
+- Write the notes as a narration a new engineer would want.
+
+## recent work
+
+`floorplan/recent-work.json` is a separate file, rewritten on every make and update. It holds what was just worked on, framed against what the user asked for. The viewer gives those cards a green "Changed"/"New" tag, shows "N changed" on the parts containing them, adds each `note` to the card's hover, and lists the tasks under a **Recent work** button and in the overview panel.
+
+```json
+{
+ "updatedAt": "2026-10-27T10:30:00Z",
+ "tasks": [
+ {
+ "title": "Refunds from the order page",
+ "request": "Let staff refund an order straight from its order page",
+ "summary": "Staff can now refund all or part of an order from its page. The money goes back to the customer's card through Stripe, and they get an email. Refunds over $500 need a manager.",
+ "items": [
+ { "ref": "shop-api/app/services/refunds.py", "change": "new", "note": "New: works out how much to refund, sends it back through Stripe and records it on the order. This is the heart of what was asked." },
+ { "ref": "POST /api/orders/<int:order_id>/refund", "change": "new", "note": "The request the Refund button sends; it checks the manager limit before anything is refunded." }
+ ]
+ }
+ ]
+}
+```
+
+| field | meaning |
+|---|---|
+| `tasks[].title` | 2–5 words, shown on hover and as the board title |
+| `tasks[].request` | what the user asked for, in their words (shortened). Shown as "You asked: …" |
+| `tasks[].summary` | 1–2 sentences: what was done toward it, and where it stands. Mention deletions here; deleted files aren't on the map |
+| `items[].ref` | a file path, a node id, or `"METHOD /path"` exactly as on the map. Refs that aren't on the map are left out with a warning |
+| `items[].change` | `"new"` or `"changed"` (default) |
+| `items[].note` | 1–2 plain sentences: what changed on this card, and how it serves the request |
+
+`{ "tasks": [] }` clears all highlights.
+
+## Full example
+
+A frontend repo and a backend repo side by side:
+
+```json
+{
+ "$schema": "floorplan/architecture@1",
+ "project": {
+ "name": "Acme Shop",
+ "summary": "Next.js storefront talking to a Flask API over REST; Postgres for storage; Stripe for payments.",
+ "entrypoints": ["shop-api/app.py", "shop-web/src/app/page.tsx"]
+ },
+ "ignore": ["shop-api/migrations/versions/**"],
+ "nodes": [
+ { "id": "web", "label": "Storefront", "kind": "ui", "summary": "Next.js app router UI.", "paths": ["shop-web/src"] },
+ { "id": "web.pages", "parent": "web", "label": "Pages", "kind": "feature", "paths": ["shop-web/src/app"] },
+ { "id": "web.api", "parent": "web", "label": "API client", "kind": "library", "summary": "Typed fetch wrapper for every backend call.", "paths": ["shop-web/src/lib/api*"] },
+ { "id": "api", "label": "Shop API", "kind": "service", "summary": "Flask REST API.", "paths": ["shop-api/app.py", "shop-api/app"] },
+ { "id": "api.routes", "parent": "api", "label": "Routes", "kind": "feature", "paths": ["shop-api/app/routes"] },
+ { "id": "api.models", "parent": "api", "label": "Models", "kind": "data", "paths": ["shop-api/app/models"] },
+ { "id": "tests", "label": "Tests", "kind": "test", "paths": ["shop-api/tests", "shop-web/**/*.test.{ts,tsx}"] },
+ { "id": "pg", "label": "Postgres", "kind": "external", "packages": ["pypi:sqlalchemy", "pypi:psycopg2"] },
+ { "id": "stripe", "label": "Stripe", "kind": "external", "packages": ["stripe"], "hosts": ["api.stripe.com"] }
+ ],
+ "edges": [
+ { "from": "stripe", "to": "api.routes", "kind": "http", "label": "webhooks", "description": "payment_intent.succeeded marks orders paid." }
+ ],
+ "annotations": [
+ { "path": "shop-api/app/routes/orders.py", "note": "All order state transitions live here.", "tags": ["hotspot"] }
+ ],
+ "flows": [
+ { "id": "checkout", "title": "Checkout", "steps": [
+ { "node": "web.pages", "note": "Cart page submits the order" },
+ { "node": "web.api", "note": "POST /api/orders" },
+ { "node": "api.routes", "note": "Validates and creates the order" },
+ { "node": "stripe", "note": "Creates a PaymentIntent" }
+ ]}
+ ]
+}
+```
diff --git a/skills/floorplan/references/writing-descriptions.md b/skills/floorplan/references/writing-descriptions.md
new file mode 100644
index 0000000..b54a7cc
--- /dev/null
+++ b/skills/floorplan/references/writing-descriptions.md
@@ -0,0 +1,156 @@
+# Writing names and descriptions
+
+Every card on the map shows a **name** and a **description**. The file path and route path are still shown, but in small type underneath. The goal is that someone who has never seen the code can read the board like a system diagram.
+
+This guide covers the names and descriptions in `descriptions/*.json` and the `label` / `summary` of nodes and `project.summary` in `architecture.json`.
+
+## Who you're writing for: `audience`
+
+`architecture.json` has an optional top-level `"audience"`. Each worksheet header repeats it.
+
+- **`"everyone"` (default).** Assume the reader is the owner of the app, not an engineer. Often they built it with AI and don't know how it works inside. Write in **plain language**: what the thing does for the business or its users, in everyday words. Stay specific and accurate. See [Plain language](#plain-language) below.
+- **`"developers"`.** The reader is an engineer joining the codebase. Naming frameworks, patterns and mechanics is fine and often useful ("Flask blueprint", "SQLAlchemy model", "Pub/Sub consumer").
+
+Use `"developers"` only when the user asks for it, or the map is plainly for an engineering team (a library, an SDK, infrastructure code). If you're unsure, use `"everyone"`.
+
+## Where they go
+
+`describe.mjs` writes one worksheet per module (`floorplan/.cache/worksheets/<key>.md`) and a matching skeleton (`floorplan/descriptions/<key>.json`):
+
+```json
+{
+ "files": {
+ "api/app/services/inventory_bulk_service.py": { "name": "Bulk stock updates", "description": "Applies stock changes from an uploaded spreadsheet in the background, checking every row before anything changes." }
+ },
+ "routes": {
+ "GET /api/products/<int:product_id>/activity": { "name": "Product history", "description": "Shows who changed a product and when, most recent first." }
+ }
+}
+```
+
+Fill in every `description` and improve every `name`. **Don't change, add or remove keys.** The keys are how `build.mjs` matches entries to files and routes. Keep the JSON valid.
+
+## Names
+
+- 2–5 words in sentence case, naming what the thing *is* or *does* in the business's own words. Short and concrete: "Staff app", "Main server", "Gift cards", "Refunds".
+- Don't just restate the filename. `inventory_bulk_service.py` becomes "Bulk stock updates", not "Inventory bulk service". `page.tsx` under `dashboard/products/` becomes "Products page".
+- UI components get the name a user would recognise: "Product photo editor", "Discount rules table".
+- Tests: "<subject> tests", e.g. "Bulk stock update tests".
+- Migrations and scripts say what they do: "Add gift-card balances", "Backfill Stripe customer links".
+- Routes are named from the caller's point of view: "Product history", "Mark orders shipped", "Stripe payment alerts".
+- Product names stay as they are (Stripe, Shopify, Postgres, SendGrid). People know them, and the glossary in the viewer explains the technical ones.
+
+## Descriptions
+
+- **One sentence, ideally under 140 characters**, present tense, starting with a verb: "Keeps…", "Shows…", "Sends…", "Checks…".
+- Say what it's responsible for and anything notable: a side effect (changes prices on Shopify, emails the customer), a constraint (staff only, safe to retry), or a role (the one place X is decided).
+- Use concrete domain nouns: "gift card", "pick list", "Shopify listing", not "data", "items", "stuff".
+- Don't say "This file…", don't hedge, and don't repeat the name.
+- For routes, describe the effect, not the HTTP mechanics. "Marks an order as shipped and emails the customer their tracking link" beats "POST endpoint for shipping".
+
+## Plain language
+
+The default audience is `"everyone"`. Write as if explaining the app to its owner over coffee: they know the business inside out, but not the code.
+
+**You don't need to carry the technical identity.** The real path is printed under every card, and endpoint cards show the method and URL (`POST /api/orders/<id>/ship`). "Show technical detail" in the viewer reveals exports, line counts and developer terms. So the description is free to say only what the thing is *for*.
+
+### Rules
+
+1. **Lead with the job, not the mechanism.** What does it do for staff, customers or the business? "Takes card payments at checkout", not "Stripe Payments API wrapper".
+2. **Everyday words.** Swap jargon for the plain phrase in the table below. If a technical word really is the clearest (a "database", a "login"), it's fine. The viewer underlines common terms and explains them on hover.
+3. **Keep it specific.** Plain doesn't mean vague. "Handles orders" is plain *and* useless. "Holds an online order's stock while payment is checked, then releases or ships it" is plain and tells you something.
+4. **Name the outside services.** "Sends new prices to Shopify and Amazon" beats "Syncs with external channels".
+5. **No framework or library names in descriptions** (Flask, SQLAlchemy, React, Radix, Pydantic…) unless the thing exists *because* of that tool. Labels can keep a product name the owner chose and knows (e.g. "Stripe", "Google Cloud").
+6. **No counts of code, file names or code identifiers** ("~6.7k lines", "product_routes.py", `ApiClient`) in summaries. Those belong in `annotations` or are shown elsewhere.
+7. **Warnings in plain terms.** "Run by hand against live data; double-check before using" rather than "non-idempotent prod script".
+
+### Jargon → plain
+
+| Instead of | Say |
+|---|---|
+| API | the way programs talk to each other; for your own, "the main server" (e.g. "asks Shippo for shipping rates") |
+| endpoint, route (backend) | a request the app can receive (e.g. "the request that marks an order shipped") |
+| page, route (frontend) | a screen / page |
+| webhook | a message another service sends your app when something happens ("Stripe tells us a payment went through") |
+| REST, HTTP, GET/POST | (leave out; the method and URL are already on the card) |
+| frontend / client | the app people use / the screens |
+| backend / server / service | the main server, the part that does the work behind the screens |
+| monolith | one main server that does everything |
+| blueprint, router, controller | a group of related requests (e.g. "order requests") |
+| middleware | a check every request passes through (e.g. "makes sure you're signed in") |
+| ORM model, schema, entity | how a kind of record is stored (e.g. "how an order is stored") |
+| table, row | a list of records / a record |
+| query | a lookup / a search of the records |
+| database (Postgres, MySQL, RDS, Cloud SQL) | the database, where all the records are kept |
+| migration | a change to how records are stored (e.g. "adds a place to store gift-card numbers") |
+| seed, fixture | sample data for testing |
+| worker, background job | a task that runs on its own in the background |
+| queue, outbox, Pub/Sub, message bus | a waiting line of tasks / a way to hand work to background tasks |
+| cron, scheduler, scheduled job | runs automatically on a timetable (e.g. "every night at 2am") |
+| cache, snapshot | a saved copy kept so things load faster |
+| SDK, client library, API client | ready-made code for talking to a service (e.g. "talks to Stripe") |
+| integration, sync | keeps X and Y in step / copies changes between X and Y |
+| env var, config | settings (e.g. "which store and password to use") |
+| secret, API key, token | a password for a service / a sign-in pass |
+| auth, authentication | sign-in |
+| authorization, roles, permissions, RBAC | who is allowed to do what |
+| session | staying signed in |
+| hook, context, provider (React) | shared screen logic / keeps the screens in step |
+| component, UI kit, primitives | a building block of the screens (button, table, dialog) |
+| state | what the screen currently remembers |
+| deploy, CI/CD | putting a new version live |
+| container, Docker, Cloud Run, serverless | where the server runs in the cloud |
+| storage bucket, S3, GCS, blob | file storage in the cloud (images, uploads, exports) |
+| CDN | a fast delivery network for images and files |
+| idempotent | safe to run twice |
+| rate limit | a cap on how often something can be asked |
+| reconcile | compares two records of the same thing and fixes differences |
+| refactor, tech debt | (leave out) |
+| MCP server | a connection that lets AI assistants (like Claude) look things up in your app |
+| unit tests, test suite | automatic checks that the code still works |
+
+### Examples
+
+**Modules / subsystems (`architecture.json` `summary`)**
+
+| | |
+|---|---|
+| ✗ | "Flask monolith with route blueprints over a growing service layer and SQLAlchemy models." |
+| ✓ | "The main server: the storefront and the admin app both talk to it, and it keeps stock, prices, orders and gift cards in step across Shopify, Stripe and the warehouse." |
+| ✗ | "Radix-based primitives (components/ui) and the dashboard shell." |
+| ✓ | "The shared building blocks of every screen: buttons, tables, dialogs, and the menu and frame around the staff app." |
+| ✗ | "Long-running Cloud Run workers: bulk inventory, pricing, abandoned-cart emails, Stripe reconcile." |
+| ✓ | "Tasks that run on their own in the background or on a timetable: big stock uploads, price changes, abandoned-cart emails and the nightly Stripe payout check." |
+
+**Files (`descriptions/*.json`)**
+
+| | |
+|---|---|
+| ✗ | name "Stripe gift card service", "Wraps the Stripe customer balance API for ledger projection." |
+| ✓ | name "Gift card balances", "Keeps each customer's gift-card balance in Stripe matching the balance the shop shows them." |
+| ✗ | name "useAuth context", "React context provider exposing auth state and token refresh." |
+| ✓ | name "Staff sign-in", "Remembers which staff member is signed in, keeps them signed in, and hides the dashboard from everyone else." |
+| ✗ | name "Order lock", "Postgres advisory lock keyed by Shopify order id." |
+| ✓ | name "One order at a time", "Stops the same online order being processed twice when Shopify sends duplicate alerts." |
+
+**Routes (endpoints)**
+
+| | |
+|---|---|
+| ✗ | name "POST ship", "POST endpoint that transitions an order to shipped." |
+| ✓ | name "Mark order shipped", "Marks an order as shipped and emails the customer their tracking link." |
+| ✗ | name "Stripe webhook", "Receives and signature-checks Stripe webhook payloads." |
+| ✓ | name "Stripe alerts", "Stripe calls this when a payment, refund or dispute changes; it checks the message is genuine and queues it." |
+
+For `"developers"`, the ✗ column is closer to right (minus the filler). Same rules otherwise: one sentence, verb first, specific.
+
+## How to work
+
+1. Read the worksheet. It lists each file's definitions, docstrings, what it uses and what uses it, and each route's handler. That's enough for most files.
+2. Open the file (the top ~80 lines, or the specific handler) only when the digest leaves the purpose unclear. Generic names (`utils.py`, `index.ts`, `common.py`) and big files usually need a look.
+3. Write the JSON in one go per worksheet, in the style the worksheet's `Audience:` line asks for.
+4. Be consistent within a module: sibling files should read as a set.
+
+## Quality bar
+
+A good description lets someone pick the right file to open without opening the others. If two siblings end up with nearly identical descriptions, find what actually distinguishes them and say that. For `"everyone"`, also check: would the owner understand every word without asking?
diff --git a/skills/floorplan/scripts/build.mjs b/skills/floorplan/scripts/build.mjs
new file mode 100644
index 0000000..7c450be
--- /dev/null
+++ b/skills/floorplan/scripts/build.mjs
@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+// floorplan builder: validate floorplan/architecture.json against the scan, assign every file to a
+// node, attach import/HTTP/external edges, and write floorplan/graph.json + floorplan/index.html.
+//
+// usage: node build.mjs [root] [--arch <file>] [--scan <file>] [--out <dir>] [--check]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compileGlob, parseArgs, fmtNum, mapDir, keepOutOfGit } from './lib/common.mjs';
+import { fallbackFileName, fallbackRouteName, routeKey } from './lib/names.mjs';
+import { buildHealth } from './lib/health.mjs';
+import { buildScreens } from './lib/screens.mjs';
+import { writeClaudeMd } from './lib/claudemd.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.resolve(HERE, '..');
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const outDir = path.resolve(args.out || mapDir(root));
+const archFile = path.resolve(args.arch || path.join(outDir, 'architecture.json'));
+const scanFile = path.resolve(args.scan || path.join(outDir, '.cache', 'scan.json'));
+
+export const NODE_KINDS = ['ui', 'service', 'worker', 'library', 'feature', 'data', 'config', 'test', 'script', 'infra', 'external'];
+export const EDGE_KINDS = ['import', 'call', 'http', 'rpc', 'event', 'queue', 'data', 'config'];
+
+const errors = [];
+const warnings = [];
+const err = (msg) => errors.push(msg);
+const warn = (msg) => warnings.push(msg);
+
+const fail = (msg) => { console.error(`✗ ${msg}`); process.exit(1); };
+if (!fs.existsSync(scanFile)) fail(`No scan at ${scanFile}. Run: node ${path.join(SKILL_DIR, 'scripts', 'scan.mjs')} "${root}"`);
+if (!fs.existsSync(archFile)) fail(`No architecture file at ${archFile}. Write it first (see references/schema.md).`);
+const scan = JSON.parse(fs.readFileSync(scanFile, 'utf8'));
+let arch;
+try { arch = JSON.parse(fs.readFileSync(archFile, 'utf8')); } catch (e) { fail(`architecture.json is not valid JSON: ${e.message}`); }
+
+// ---------- validate shape ----------
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+const isStrArr = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+function closest(word, options) {
+ let best = null, bestD = Infinity;
+ for (const o of options) {
+ const d = lev(word, o);
+ if (d < bestD) { bestD = d; best = o; }
+ }
+ return bestD <= Math.max(2, word.length / 3) ? best : null;
+}
+function lev(a, b) {
+ const dp = Array.from({ length: b.length + 1 }, (_, i) => i);
+ for (let i = 1; i <= a.length; i++) {
+ let prev = dp[0]; dp[0] = i;
+ for (let j = 1; j <= b.length; j++) { const tmp = dp[j]; dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1)); prev = tmp; }
+ }
+ return dp[b.length];
+}
+const didYouMean = (w, opts) => { const c = closest(w, opts); return c ? ` — did you mean "${c}"?` : ''; };
+
+if (!arch || typeof arch !== 'object') fail('architecture.json must be an object');
+if (!arch.project || !isStr(arch.project.name)) err('project.name is required');
+if (!Array.isArray(arch.nodes) || !arch.nodes.length) err('nodes must be a non-empty array');
+const nodes = Array.isArray(arch.nodes) ? arch.nodes : [];
+const archEdges = Array.isArray(arch.edges) ? arch.edges : [];
+const flows = Array.isArray(arch.flows) ? arch.flows : [];
+const annotations = Array.isArray(arch.annotations) ? arch.annotations : [];
+const include = isStrArr(arch.include) ? arch.include : ['code'];
+const ignoreGlobs = (isStrArr(arch.ignore) ? arch.ignore : []).map(compileGlob);
+// who the descriptions are written for: "everyone" (plain language, default) or "developers"
+const AUDIENCES = ['everyone', 'developers'];
+if (arch.audience !== undefined && !AUDIENCES.includes(arch.audience)) err(`audience "${arch.audience}" must be one of ${AUDIENCES.join(', ')}${didYouMean(String(arch.audience), AUDIENCES)}`);
+const audience = AUDIENCES.includes(arch.audience) ? arch.audience : 'everyone';
+
+const byId = new Map();
+nodes.forEach((n, i) => {
+ const where = `nodes[${i}]${n?.id ? ` ("${n.id}")` : ''}`;
+ if (!n || typeof n !== 'object') return err(`${where} must be an object`);
+ if (!isStr(n.id)) return err(`${where}.id is required`);
+ if (!/^[A-Za-z0-9_.\-]+$/.test(n.id)) err(`${where}.id may only use letters, digits, "_", "-" and "."`);
+ if (n.id === 'unassigned') err(`${where}.id "unassigned" is reserved`);
+ if (byId.has(n.id)) err(`${where}.id duplicates an earlier node`);
+ byId.set(n.id, n);
+ if (!isStr(n.label)) err(`${where}.label is required`);
+ if (!NODE_KINDS.includes(n.kind)) err(`${where}.kind "${n.kind}" must be one of ${NODE_KINDS.join(', ')}${didYouMean(String(n.kind), NODE_KINDS)}`);
+ for (const k of ['paths', 'exclude', 'packages', 'hosts', 'tags']) if (n[k] !== undefined && !isStrArr(n[k])) err(`${where}.${k} must be an array of strings`);
+ if (n.kind === 'external' && n.paths?.length) warn(`${where} is external but has paths; external nodes normally own no files`);
+});
+const ids = [...byId.keys()];
+for (const n of nodes) {
+ if (n?.parent === undefined) continue;
+ if (!byId.has(n.parent)) err(`node "${n.id}".parent "${n.parent}" does not exist${didYouMean(n.parent, ids)}`);
+}
+// cycles + depth
+const depthOf = new Map();
+const depth = (id, seen = new Set()) => {
+ if (depthOf.has(id)) return depthOf.get(id);
+ if (seen.has(id)) { err(`node "${id}" is part of a parent cycle`); return 0; }
+ seen.add(id);
+ const n = byId.get(id);
+ const d = n?.parent && byId.has(n.parent) ? depth(n.parent, seen) + 1 : 0;
+ depthOf.set(id, d);
+ return d;
+};
+ids.forEach((id) => depth(id));
+
+// ---------- files ----------
+const filesAll = scan.files;
+const fileByPath = new Map(filesAll.map((f) => [f.path, f]));
+const included = filesAll.filter((f) => include.includes(f.category) && !ignoreGlobs.some((g) => g.test(f.path)));
+const includedSet = new Set(included.map((f) => f.path));
+
+// ---------- assign files to nodes ----------
+// A node's `exclude` also applies to its descendants, so "web excludes tests" holds all the way down.
+const inheritedExcludes = (n, seen = new Set()) => {
+ if (!n || seen.has(n.id)) return [];
+ seen.add(n.id);
+ return [...(isStrArr(n.exclude) ? n.exclude : []), ...(n.parent ? inheritedExcludes(byId.get(n.parent), seen) : [])];
+};
+const matchers = nodes.filter((n) => n?.id && isStrArr(n.paths ?? [])).map((n, order) => ({
+ id: n.id, order, depth: depthOf.get(n.id) || 0,
+ paths: (n.paths || []).map(compileGlob), exclude: inheritedExcludes(n).map(compileGlob), hits: new Array((n.paths || []).length).fill(0),
+}));
+const owner = new Map();
+let ambiguous = 0;
+const ambiguousEx = [];
+for (const f of included) {
+ let best = null, bestKey = null, tie = null;
+ for (const m of matchers) {
+ if (m.exclude.some((g) => g.test(f.path))) continue;
+ let spec = -1;
+ m.paths.forEach((g, i) => { if (g.test(f.path)) { m.hits[i]++; spec = Math.max(spec, g.specificity); } });
+ if (spec < 0) continue;
+ const key = [m.depth, spec];
+ if (!best || key[0] > bestKey[0] || (key[0] === bestKey[0] && key[1] > bestKey[1])) { best = m; bestKey = key; tie = null; }
+ else if (key[0] === bestKey[0] && key[1] === bestKey[1]) tie = m.id;
+ }
+ if (tie) { ambiguous++; if (ambiguousEx.length < 3) ambiguousEx.push(`${f.path} (${best.id} vs ${tie})`); }
+ owner.set(f.path, best ? best.id : 'unassigned');
+}
+for (const m of matchers) m.hits.forEach((h, i) => { if (!h) warn(`node "${m.id}" path "${m.paths[i].glob}" matches no included file`); });
+if (ambiguous) warn(`${ambiguous} file(s) matched two sibling nodes equally; the first declared won. Make globs more specific or add an exclude. e.g. ${ambiguousEx.join('; ')}`);
+
+// ---------- endpoints ----------
+const resolveEndpoint = (ref, where) => {
+ if (!isStr(ref)) { err(`${where} must be a node id or file path`); return null; }
+ if (byId.has(ref)) return `n:${ref}`;
+ const p = ref.replace(/^file:/, '');
+ if (includedSet.has(p)) return `f:${p}`;
+ if (fileByPath.has(p)) { err(`${where} "${ref}" is a file that is not included (category ${fileByPath.get(p).category}); point at its node instead`); return null; }
+ err(`${where} "${ref}" is neither a node id nor a scanned file${didYouMean(ref, ids)}`);
+ return null;
+};
+
+// ---------- links ----------
+const links = new Map(); // key -> link
+const addLink = (a, b, k, extra = {}) => {
+ if (!a || !b || a === b) return;
+ const key = `${a}|${b}|${k}`;
+ let l = links.get(key);
+ if (!l) { l = { a, b, k, w: 0 }; links.set(key, l); }
+ l.w += extra.w || 1;
+ if (extra.names?.length) l.names = [...new Set([...(l.names || []), ...extra.names])].slice(0, 40);
+ if (extra.label) { l.labels = l.labels || []; if (!l.labels.includes(extra.label) && l.labels.length < 40) l.labels.push(extra.label); }
+ if (extra.inferred) l.inferred = true;
+ if (extra.desc) l.desc = extra.desc;
+ if (extra.route !== undefined) { l.calls = l.calls || []; if (l.calls.length < 80) l.calls.push([extra.route, extra.callLine || 0]); }
+};
+
+// ---------- routes ----------
+const routeIdx = new Map();
+const routesIn = scan.routes.filter((r) => includedSet.has(r.file));
+routesIn.forEach((r, i) => routeIdx.set(`${r.file}|${r.method}|${r.path}`, i));
+
+for (const e of scan.edges) if (includedSet.has(e.from) && includedSet.has(e.to)) addLink(`f:${e.from}`, `f:${e.to}`, 'import', { w: e.count || 1, names: e.names });
+for (const h of scan.http) if (includedSet.has(h.from) && includedSet.has(h.to)) addLink(`f:${h.from}`, `f:${h.to}`, 'http', { label: `${h.method} ${h.path}`, inferred: true, route: routeIdx.get(`${h.to}|${h.method}|${h.path}`), callLine: h.line });
+
+// externals: packages / hosts claimed by nodes
+const extIds = scan.externals.map((e) => e.id);
+const pkgMatchers = nodes.filter((n) => n?.packages?.length).map((n) => ({ id: n.id, globs: n.packages.map((p) => compileGlob(p.includes(':') ? p : `*:${p}`)), hits: 0 }));
+const hostMatchers = nodes.filter((n) => n?.hosts?.length).map((n) => ({ id: n.id, globs: n.hosts.map((h) => compileGlob(h.toLowerCase())), hits: 0 }));
+for (const e of scan.extEdges) {
+ if (!includedSet.has(e.from)) continue;
+ const m = pkgMatchers.find((pm) => pm.globs.some((g) => g.test(e.pkg)));
+ if (m) { m.hits++; addLink(`f:${e.from}`, `n:${m.id}`, 'import', { w: e.count, names: [e.pkg.split(':')[1]] }); }
+}
+for (const h of scan.hosts) {
+ if (!includedSet.has(h.from)) continue;
+ const m = hostMatchers.find((hm) => hm.globs.some((g) => g.test(h.host)));
+ if (m) { m.hits++; addLink(`f:${h.from}`, `n:${m.id}`, 'http', { label: h.host, inferred: true }); }
+}
+for (const pm of pkgMatchers) if (!pm.hits) warn(`node "${pm.id}" packages match nothing imported. Known: ${extIds.slice(0, 8).join(', ')}…`);
+for (const hm of hostMatchers) if (!hm.hits) warn(`node "${hm.id}" hosts match no host called from code`);
+
+archEdges.forEach((e, i) => {
+ const where = `edges[${i}]`;
+ if (!EDGE_KINDS.includes(e?.kind)) err(`${where}.kind "${e?.kind}" must be one of ${EDGE_KINDS.join(', ')}${didYouMean(String(e?.kind), EDGE_KINDS)}`);
+ const a = resolveEndpoint(e?.from, `${where}.from`);
+ const b = resolveEndpoint(e?.to, `${where}.to`);
+ if (a && b && EDGE_KINDS.includes(e.kind)) addLink(a, b, e.kind, { label: e.label, desc: e.description, w: 1 });
+});
+
+// ---------- flows + annotations ----------
+const outFlows = [];
+flows.forEach((fl, i) => {
+ const where = `flows[${i}]`;
+ if (!isStr(fl?.id) || !isStr(fl?.title)) err(`${where} needs id and title`);
+ if (!Array.isArray(fl?.steps) || fl.steps.length < 2) { err(`${where}.steps needs at least 2 steps`); return; }
+ const steps = fl.steps.map((s, j) => ({ ref: resolveEndpoint(s?.node, `${where}.steps[${j}].node`), note: s?.note || '' }));
+ outFlows.push({ id: fl.id, title: fl.title, description: fl.description || '', steps });
+});
+// Flows people requested from the map (saved by serve.mjs). Steps use stable refs —
+// "route:METHOD /path" and "sym:<file>#<name>" — so they survive rebuilds; stale steps are dropped.
+const customFile = path.join(outDir, 'custom-flows.json');
+if (fs.existsSync(customFile)) {
+ let custom = [];
+ try { custom = JSON.parse(fs.readFileSync(customFile, 'utf8')).flows || []; } catch (e) { warn(`custom-flows.json is not valid JSON: ${e.message}`); }
+ const routeAt = new Map(routesIn.map((r, i) => [routeKey(r), i]));
+ const resolveStep = (ref) => {
+ if (typeof ref !== 'string') return null;
+ if (ref.startsWith('route:')) { const i = routeAt.get(ref.slice(6)); return i == null ? null : `r:${i}`; }
+ if (ref.startsWith('sym:')) {
+ const [p, name] = [ref.slice(4, ref.lastIndexOf('#')), ref.slice(ref.lastIndexOf('#') + 1)];
+ const i = (fileByPath.get(p)?.symbols || []).findIndex((s) => s.name === name);
+ return includedSet.has(p) && i >= 0 ? `s:${p}#${i}` : null;
+ }
+ if (ref.startsWith('n:')) return byId.has(ref.slice(2)) ? ref : null;
+ if (ref.startsWith('f:')) return includedSet.has(ref.slice(2)) ? ref : null;
+ return null;
+ };
+ let dropped = 0;
+ for (const fl of custom) {
+ const steps = (fl.steps || []).map((s) => ({ ref: resolveStep(s.ref), note: s.note || '' })).filter((s) => s.ref);
+ dropped += (fl.steps || []).length - steps.length;
+ if (steps.length >= 2 && isStr(fl.id) && !outFlows.some((x) => x.id === fl.id)) outFlows.push({ id: fl.id, title: fl.title || 'Flow', description: fl.description || '', steps, custom: true });
+ }
+ if (dropped) warn(`${dropped} step(s) in custom-flows.json point at code that no longer exists and were left out.`);
+}
+// "Start here" tour: 3-8 narrated stops (node id or file path), written by Claude in architecture.json
+const outTour = [];
+if (arch.tour !== undefined) {
+ if (!Array.isArray(arch.tour)) err('tour must be an array of { node, title, note }');
+ else arch.tour.forEach((s, i) => {
+ const ref = resolveEndpoint(s?.node, `tour[${i}].node`);
+ if (ref) outTour.push({ ref, title: isStr(s.title) ? s.title : '', note: isStr(s.note) ? s.note : '' });
+ });
+}
+// "Recent work": what Claude just changed, per task, framed against what the user asked for
+// (floorplan/recent-work.json, rewritten on every make/update). Stale refs are warnings, never errors.
+let outRecent = null;
+const recentFile = path.join(outDir, 'recent-work.json');
+if (fs.existsSync(recentFile)) {
+ let rw = null;
+ try { rw = JSON.parse(fs.readFileSync(recentFile, 'utf8')); } catch (e) { warn(`recent-work.json is not valid JSON: ${e.message}`); }
+ const routeIdx = new Map(routesIn.map((r, i) => [routeKey(r), i]));
+ const resolveRecent = (ref) => {
+ if (!isStr(ref)) return null;
+ const s = ref.trim().replace(/^\.\//, '').replace(/^(route:|file:)/, '');
+ if (/^n:/.test(s)) return byId.has(s.slice(2)) ? s : null;
+ if (/^f:/.test(s)) return includedSet.has(s.slice(2)) ? s : null;
+ if (byId.has(s)) return 'n:' + s;
+ if (includedSet.has(s)) return 'f:' + s;
+ const m = /^([A-Za-z]+)\s+(\/\S*)$/.exec(s);
+ if (m && routeIdx.has(`${m[1].toUpperCase()} ${m[2]}`)) return `r:${routeIdx.get(`${m[1].toUpperCase()} ${m[2]}`)}`;
+ return null;
+ };
+ if (rw && !Array.isArray(rw.tasks)) warn('recent-work.json needs a "tasks" array (an empty one clears the highlights)');
+ else if (rw) {
+ const tasks = [], items = [], missing = [];
+ rw.tasks.forEach((t, ti) => {
+ if (!isStr(t?.title)) return warn(`recent-work.json tasks[${ti}] needs a title`);
+ tasks.push({ title: t.title, request: isStr(t.request) ? t.request : '', summary: isStr(t.summary) ? t.summary : '', ...(isStr(t.status) ? { status: t.status } : {}) });
+ for (const it of Array.isArray(t.items) ? t.items : []) {
+ const id = resolveRecent(it?.ref);
+ if (!id) { missing.push(it?.ref); continue; }
+ items.push({ id, task: tasks.length - 1, change: it.change === 'new' ? 'new' : 'changed', note: isStr(it.note) ? it.note : '' });
+ }
+ });
+ if (missing.length) warn(`recent-work.json: ${missing.length} ref(s) aren't on the map and were left out (use a file path, a node id or "METHOD /path"): ${missing.slice(0, 5).map(String).join(', ')}${missing.length > 5 ? '…' : ''}`);
+ outRecent = { updatedAt: isStr(rw.updatedAt) ? rw.updatedAt : fs.statSync(recentFile).mtime.toISOString(), tasks, items };
+ }
+}
+const notes = new Map();
+annotations.forEach((a, i) => {
+ if (!isStr(a?.path) || !isStr(a?.note)) return err(`annotations[${i}] needs path and note`);
+ if (!includedSet.has(a.path)) return err(`annotations[${i}].path "${a.path}" is not an included file`);
+ notes.set(a.path, { note: a.note, tags: isStrArr(a.tags) ? a.tags : undefined });
+});
+for (const ep of arch.project?.entrypoints || []) if (!includedSet.has(ep)) warn(`project.entrypoints "${ep}" is not an included file`);
+
+// ---------- names + descriptions (floorplan/descriptions/*.json) ----------
+const descDir = path.join(outDir, 'descriptions');
+const fileDesc = new Map(), routeDesc = new Map();
+const routeKeys = new Set(routesIn.map(routeKey));
+let staleFiles = 0, staleRoutes = 0;
+const staleEx = [];
+if (fs.existsSync(descDir)) {
+ for (const name of fs.readdirSync(descDir).filter((n) => n.endsWith('.json')).sort()) {
+ let d;
+ try { d = JSON.parse(fs.readFileSync(path.join(descDir, name), 'utf8')); } catch (e) { err(`descriptions/${name} is not valid JSON: ${e.message}`); continue; }
+ for (const [p, v] of Object.entries(d.files || {})) {
+ if (!v || typeof v !== 'object') { err(`descriptions/${name}: files["${p}"] must be { name, description }`); continue; }
+ if (!includedSet.has(p)) { staleFiles++; if (staleEx.length < 3) staleEx.push(p); continue; }
+ fileDesc.set(p, { name: isStr(v.name) ? v.name.trim() : null, d: isStr(v.description) ? v.description.trim() : null, review: isStr(v.review) ? v.review : null });
+ }
+ for (const [k, v] of Object.entries(d.routes || {})) {
+ if (!v || typeof v !== 'object') { err(`descriptions/${name}: routes["${k}"] must be { name, description }`); continue; }
+ if (!routeKeys.has(k)) { staleRoutes++; continue; }
+ routeDesc.set(k, { name: isStr(v.name) ? v.name.trim() : null, d: isStr(v.description) ? v.description.trim() : null, review: isStr(v.review) ? v.review : null });
+ }
+ }
+}
+if (staleFiles) warn(`${staleFiles} described file(s) no longer exist or aren't included (e.g. ${staleEx.join(', ')}). Remove them from descriptions/.`);
+if (staleRoutes) warn(`${staleRoutes} described route(s) no longer match a route in the scan; remove or re-key them.`);
+
+// ---------- stats ----------
+const unassigned = included.filter((f) => owner.get(f.path) === 'unassigned');
+const stats = new Map([...ids, 'unassigned'].map((id) => [id, { files: 0, loc: 0, langs: {}, repos: new Set() }]));
+for (const f of included) {
+ let id = owner.get(f.path);
+ while (id) {
+ const s = stats.get(id);
+ s.files++; s.loc += f.loc; s.langs[f.lang || f.category] = (s.langs[f.lang || f.category] || 0) + f.loc;
+ if (f.repo !== null) s.repos.add(f.repo);
+ id = id === 'unassigned' ? null : byId.get(id)?.parent;
+ }
+}
+
+// ---------- report ----------
+const pct = included.length ? (unassigned.length / included.length) * 100 : 0;
+const report = [];
+if (errors.length) {
+ report.push(`✗ ${errors.length} error(s) in ${path.relative(root, archFile)}:`);
+ for (const e of errors) report.push(` - ${e}`);
+}
+if (warnings.length) {
+ report.push(`! ${warnings.length} warning(s):`);
+ for (const w of warnings.slice(0, 40)) report.push(` - ${w}`);
+}
+report.push('');
+report.push(`ASSIGNMENT ${included.length} files (${include.join('+')}), ${unassigned.length} unassigned (${pct.toFixed(1)}%)`);
+for (const n of nodes.filter((n) => n?.id && !n.parent)) {
+ const s = stats.get(n.id);
+ report.push(` ${n.id.padEnd(28)} ${String(s.files).padStart(5)} files ${fmtNum(s.loc).padStart(6)} loc [${n.kind}]`);
+}
+if (unassigned.length) {
+ const byDir = new Map();
+ for (const f of unassigned) { const d = f.path.split('/').slice(0, -1).join('/') || '.'; byDir.set(d, (byDir.get(d) || 0) + 1); }
+ report.push(` unassigned, by directory:`);
+ for (const [d, c] of [...byDir.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15)) report.push(` ${String(c).padStart(4)} ${d}/`);
+}
+const byKind = {};
+for (const l of links.values()) byKind[l.k] = (byKind[l.k] || 0) + 1;
+report.push(`LINKS ${[...links.values()].length} (${Object.entries(byKind).map(([k, v]) => `${k} ${v}`).join(', ')})`);
+const describedFiles = included.filter((f) => fileDesc.get(f.path)?.d).length;
+const describedRoutes = routesIn.filter((r) => routeDesc.get(routeKey(r))?.d).length;
+const noSummary = nodes.filter((n) => n?.id && !isStr(n.summary)).map((n) => n.id);
+const reviewCount = [...fileDesc.values(), ...routeDesc.values()].filter((d) => d.review).length;
+report.push(`DESCRIPTIONS files ${describedFiles}/${included.length} · routes ${describedRoutes}/${routesIn.length} · modules ${nodes.length - noSummary.length}/${nodes.length}${reviewCount ? ` · ${reviewCount} need review (code changed)` : ''}`);
+if (noSummary.length) report.push(` modules without a summary: ${noSummary.slice(0, 12).join(', ')}${noSummary.length > 12 ? '…' : ''}`);
+if (describedFiles < included.length || describedRoutes < routesIn.length || reviewCount) report.push(` Run describe.mjs to get worksheets for the ${included.length - describedFiles} file(s) and ${routesIn.length - describedRoutes} route(s) still missing descriptions.`);
+
+if (errors.length) { console.log(report.join('\n')); console.log('\nFix the errors above and run build again.'); process.exit(1); }
+if (args.check) { console.log(report.join('\n')); process.exit(0); }
+
+// ---------- write graph.json + index.html ----------
+const graph = {
+ schema: 'floorplan/graph@1',
+ meta: {
+ generatedAt: new Date().toISOString(), scanAt: scan.generatedAt, rootName: scan.rootName, root: scan.root,
+ audience,
+ repos: scan.repos.map(({ path: p, name, branch, head, remote }) => ({ path: p, name, branch, head, remote })),
+ counts: { files: included.length, loc: included.reduce((s, f) => s + f.loc, 0), unassigned: unassigned.length },
+ },
+ project: arch.project,
+ nodes: [
+ ...nodes.map((n) => ({
+ id: n.id, parent: n.parent || null, label: n.label, kind: n.kind, summary: n.summary || '', details: n.details || '',
+ tags: n.tags || [], paths: n.paths || [], packages: n.packages || [], hosts: n.hosts || [],
+ stats: { ...stats.get(n.id), repos: [...stats.get(n.id).repos] },
+ })),
+ ...(unassigned.length ? [{ id: 'unassigned', parent: null, label: 'Unassigned', kind: 'misc', summary: 'Files no node claims. Add globs in architecture.json to place them.', details: '', tags: [], paths: [], packages: [], hosts: [], stats: { ...stats.get('unassigned'), repos: [...stats.get('unassigned').repos] } }] : []),
+ ],
+ files: included.map((f) => {
+ const d = fileDesc.get(f.path);
+ return {
+ p: f.path, n: owner.get(f.path), r: f.repo, l: f.lang || f.category, loc: f.loc,
+ name: d?.name || fallbackFileName(f.path), d: d?.d || f.doc || '', ...(d?.d ? {} : { auto: true }),
+ ...(f.doc ? { doc: f.doc } : {}),
+ ...(d?.review ? { review: d.review } : {}),
+ ...(f.h ? { h: f.h, sig: f.sig } : {}),
+ ...(f.symbols ? { s: f.symbols.map((s) => [s.name, s.kind, s.line, s.default ? 1 : 0, s.doc || '']) } : {}),
+ ...(notes.has(f.path) ? notes.get(f.path) : {}),
+ };
+ }),
+ routes: routesIn.map((r) => {
+ const d = routeDesc.get(routeKey(r));
+ return { f: r.file, m: r.method, p: r.path, l: r.line, h: r.handler || null, name: d?.name || fallbackRouteName(r), d: d?.d || r.doc || '', ...(d?.d ? {} : { auto: true }), ...(d?.review ? { review: d.review } : {}), ...(r.doc ? { doc: r.doc } : {}) };
+ }),
+ links: [...links.values()],
+ flows: outFlows,
+ tour: outTour,
+ ...(outRecent?.items.length ? { recent: outRecent } : {}),
+};
+// extension hooks, computed from the finished graph plus the raw scan
+try { graph.health = buildHealth({ graph, scan, arch, root }); } catch (e) { warn(`health check failed: ${e.message}`); graph.health = { issues: [] }; }
+try { graph.screens = buildScreens({ graph, scan, arch, root }); } catch (e) { warn(`screen detection failed: ${e.message}`); graph.screens = []; }
+fs.mkdirSync(outDir, { recursive: true });
+const trackedWarning = keepOutOfGit(outDir);
+fs.writeFileSync(path.join(outDir, 'graph.json'), JSON.stringify(graph, null, 0));
+
+const template = fs.readFileSync(path.join(SKILL_DIR, 'assets', 'viewer.html'), 'utf8');
+const vendored = path.join(SKILL_DIR, 'assets', 'vendor', 'elk.bundled.js');
+const elkTag = fs.existsSync(vendored)
+ ? `<script>${fs.readFileSync(vendored, 'utf8').replace(/<\/script/gi, '<\\/script')}</script>`
+ : '<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/elk.bundled.js"></script>';
+const graphQuery = fs.readFileSync(path.join(SKILL_DIR, 'assets', 'graph-query.js'), 'utf8');
+const page = (g) => template
+ .replace('/*__GRAPH_QUERY__*/', () => graphQuery.replace(/<\/script/gi, '<\\/script'))
+ .replace('<!--__ELK_SCRIPT__-->', () => elkTag)
+ .replace('/*__FLOORPLAN_DATA__*/null', () => JSON.stringify(g).replace(/<\/(script)/gi, '<\\/$1').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029'))
+ .replace(/__FLOORPLAN_TITLE__/g, () => escapeHtml(`${arch.project.name} map`))
+ .replace(/__FLOORPLAN_LOGO__/g, () => dataUri('logo.png'))
+ .replace(/__FLOORPLAN_FAVICON__/g, () => dataUri('favicon.png'))
+ .replace('<!--__UI_EXTENSIONS__-->', () => uiScripts);
+const uiDir = path.join(SKILL_DIR, 'assets', 'ui');
+const uiScripts = fs.existsSync(uiDir) ? fs.readdirSync(uiDir).filter((n) => n.endsWith('.js')).sort().map((n) => `<script>/* ui/${n} */\n${fs.readFileSync(path.join(uiDir, n), 'utf8').replace(/<\/script/gi, '<\\/script')}</script>`).join('\n') : '';
+const html = page(graph);
+fs.writeFileSync(path.join(outDir, 'index.html'), html);
+// --artifact: a copy to publish to the Claude app, without this machine's absolute path (editor links)
+if (args.artifact) fs.writeFileSync(path.join(outDir, 'artifact.html'), page({ ...graph, meta: { ...graph.meta, root: null } }));
+// Self-contained helpers next to the map: ask questions through the Claude Code CLI (serve.mjs)
+// and the graph lookups it hands to Claude (query.mjs). They need only Node, not this skill.
+fs.writeFileSync(path.join(outDir, 'query.mjs'), `${graphQuery}
+// ---- cli ----
+${fs.readFileSync(path.join(SKILL_DIR, 'assets', 'query-cli.mjs'), 'utf8')}`);
+fs.copyFileSync(path.join(SKILL_DIR, 'assets', 'serve.mjs'), path.join(outDir, 'serve.mjs'));
+// the logo and tab icon are inlined so the map stays one self-contained file
+function dataUri(name) { return 'data:image/png;base64,' + fs.readFileSync(path.join(SKILL_DIR, 'assets', name)).toString('base64'); }
+function escapeHtml(s) { return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]); }
+
+const hs = graph.health?.summary;
+if (hs && (hs.high || hs.medium || hs.low)) {
+ report.push(`HEALTH ${hs.high} important · ${hs.medium} worth fixing · ${hs.low} minor`);
+ for (const i of graph.health.issues.filter((x) => x.severity !== 'low').slice(0, 8)) report.push(` [${i.severity}] ${i.title}`);
+}
+if (graph.screens?.length) report.push(`SCREENS ${graph.screens.length} detected`);
+report.push(graph.recent
+ ? `RECENT WORK ${graph.recent.items.length} card(s) highlighted across ${graph.recent.tasks.length} task(s)`
+ : `RECENT WORK none highlighted${fs.existsSync(recentFile) ? '' : ' (no recent-work.json)'}`);
+// point future Claude Code sessions in this project at the map
+if (!args['no-claude-md']) report.push(`CLAUDE.LOCAL.MD ${writeClaudeMd(root, outDir)}`);
+report.push(trackedWarning ? `GIT ! ${trackedWarning}` : 'GIT floorplan/ is kept out of git (it ignores itself)');
+report.push('');
+report.push(`✓ wrote ${path.relative(root, path.join(outDir, 'index.html'))} (${fmtNum(Math.round(html.length / 1024))} KB) and graph.json`);
+if (pct > 10) report.push(` Unassigned is ${pct.toFixed(0)}%: add nodes or globs for the directories above (or "ignore" them) and rebuild.`);
+console.log(report.join('\n'));
diff --git a/skills/floorplan/scripts/describe.mjs b/skills/floorplan/scripts/describe.mjs
new file mode 100644
index 0000000..afed537
--- /dev/null
+++ b/skills/floorplan/scripts/describe.mjs
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// floorplan describer: turn the built graph into per-module worksheets that Claude (or parallel
+// subagents) use to write a human-readable name + one-line description for every file and route.
+//
+// usage: node describe.mjs [root] write worksheets + description skeletons, print an index
+// node describe.mjs [root] --all include entries that already have descriptions
+// node describe.mjs [root] --max-files 40 files per worksheet before splitting into parts
+//
+// Run build.mjs first: worksheets are generated from floorplan/graph.json.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs, fmtNum, mapDir } from './lib/common.mjs';
+import { fallbackFileName, fallbackRouteName, routeKey } from './lib/names.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const outDir = mapDir(root);
+const graphFile = path.join(outDir, 'graph.json');
+if (!fs.existsSync(graphFile)) { console.error('✗ No floorplan/graph.json. Run build.mjs first.'); process.exit(1); }
+const g = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
+const maxFiles = Number(args['max-files']) || 40;
+const wsDir = path.join(outDir, '.cache', 'worksheets');
+const descDir = path.join(outDir, 'descriptions');
+fs.mkdirSync(wsDir, { recursive: true });
+fs.mkdirSync(descDir, { recursive: true });
+for (const f of fs.readdirSync(wsDir)) fs.unlinkSync(path.join(wsDir, f));
+
+const nodes = new Map(g.nodes.map((n) => [n.id, n]));
+const fileByPath = new Map(g.files.map((f) => [f.p, f]));
+const label = (id) => nodes.get(id)?.label || id;
+// Who the map is written for (architecture.json "audience", copied into graph.meta by build.mjs).
+const audience = g.meta?.audience === 'developers' ? 'developers' : 'everyone';
+const STYLE = audience === 'developers'
+ ? 'technical style for engineers: name the frameworks, patterns and mechanics where they help.'
+ : 'plain language for a non-technical owner: what it does for the business or its users, in everyday words, still specific. No jargon (endpoint, ORM, blueprint, webhook, worker…): the path and method/URL are already shown next to it. See "Plain language" in references/writing-descriptions.md.';
+
+// file -> neighbours, summarised by owning node
+const usesOf = new Map(), usedBy = new Map();
+const bump = (m, k, v) => { if (!m.has(k)) m.set(k, new Map()); m.get(k).set(v, (m.get(k).get(v) || 0) + 1); };
+for (const l of g.links) {
+ if (!l.a.startsWith('f:')) continue;
+ const a = l.a.slice(2);
+ const bNode = l.b.startsWith('f:') ? fileByPath.get(l.b.slice(2))?.n : l.b.slice(2);
+ if (bNode) bump(usesOf, a, label(bNode));
+ if (l.b.startsWith('f:')) { const aNode = fileByPath.get(a)?.n; if (aNode) bump(usedBy, l.b.slice(2), label(aNode)); }
+}
+const top = (m, n = 5) => m ? [...m.entries()].sort((x, y) => y[1] - x[1]).slice(0, n).map(([k, v]) => `${k}${v > 1 ? ` ×${v}` : ''}`).join(', ') : '';
+
+const routesByFile = new Map();
+for (const r of g.routes || []) { if (!routesByFile.has(r.f)) routesByFile.set(r.f, []); routesByFile.get(r.f).push(r); }
+
+const needs = (f) => args.all || f.auto || f.review;
+const byNode = new Map();
+for (const f of g.files) {
+ const rs = routesByFile.get(f.p) || [];
+ if (!needs(f) && !rs.some((r) => args.all || r.auto || r.review)) continue;
+ if (!byNode.has(f.n)) byNode.set(f.n, []);
+ byNode.get(f.n).push(f);
+}
+
+const index = [];
+for (const [nid, list] of byNode) {
+ list.sort((a, b) => a.p.localeCompare(b.p));
+ // Split into parts of at most maxFiles files or ~100 routes, whichever comes first.
+ const chunks = [[]];
+ let routesInChunk = 0;
+ for (const f of list) {
+ const nr = (routesByFile.get(f.p) || []).length;
+ const cur = chunks[chunks.length - 1];
+ if (cur.length && (cur.length >= maxFiles || routesInChunk + nr > 100)) { chunks.push([]); routesInChunk = 0; }
+ chunks[chunks.length - 1].push(f);
+ routesInChunk += nr;
+ }
+ const parts = chunks.length;
+ for (let i = 0; i < parts; i++) {
+ const chunk = chunks[i];
+ const key = parts > 1 ? `${nid}--${i + 1}` : nid;
+ const descFile = path.join(descDir, `${key}.json`);
+ const n = nodes.get(nid);
+ const out = [];
+ out.push(`# Worksheet ${key}: ${n?.label || nid}${parts > 1 ? ` (part ${i + 1}/${parts})` : ''}`);
+ out.push(`Audience: ${audience}. Write in ${STYLE}`);
+ if (n?.summary) out.push(`Module: ${n.summary}`);
+ out.push(`Write to: floorplan/descriptions/${key}.json (a skeleton is already there; fill in every "description", improve every "name").`);
+ out.push('Entries marked REVIEW already have a description but their code changed: update name/description if the change matters, then delete the "review" field. Entries not listed here are fine; leave them alone.');
+ out.push('');
+ let routeCount = 0;
+ for (const f of chunk) {
+ out.push(`## ${f.p} (${fmtNum(f.loc)} loc, ${f.l})${f.review ? ' REVIEW' : !needs(f) ? ' (already described; only its routes need work)' : ''}`);
+ if (f.review) out.push(`current: ${f.name} — ${f.d}
+changed: ${f.review}`);
+ if (f.doc) out.push(`doc: ${f.doc}`);
+ if (f.s?.length) {
+ const syms = f.s.slice(0, 12).map((s) => `${s[0]}${s[1] === 'function' ? '()' : ''}${s[4] ? ` (${s[4]})` : ''}`);
+ out.push(`defines: ${syms.join('; ')}${f.s.length > 12 ? `; … +${f.s.length - 12}` : ''}`);
+ }
+ const u = top(usesOf.get(f.p)), b = top(usedBy.get(f.p));
+ if (u) out.push(`uses: ${u}`);
+ if (b) out.push(`used by: ${b}`);
+ for (const r of routesByFile.get(f.p) || []) {
+ routeCount++;
+ const mark = r.review ? ` REVIEW (${r.review}); current: ${r.name} — ${r.d}` : r.auto ? ' NEW' : ' (described)';
+ out.push(`route: ${routeKey({ method: r.m, path: r.p })} handler ${r.h || '?'}${r.doc ? ` (${r.doc})` : ''}${mark}`);
+ }
+ out.push('');
+ }
+ fs.writeFileSync(path.join(wsDir, `${key}.md`), out.join('\n'));
+
+ // skeleton: keep anything already written, add missing keys
+ let existing = {};
+ try { existing = JSON.parse(fs.readFileSync(descFile, 'utf8')); } catch {}
+ const skel = { files: { ...(existing.files || {}) }, routes: { ...(existing.routes || {}) } };
+ for (const f of chunk) {
+ if (!skel.files[f.p]) skel.files[f.p] = { name: f.auto ? fallbackFileName(f.p) : f.name, description: f.auto ? '' : f.d };
+ for (const r of routesByFile.get(f.p) || []) {
+ const k = routeKey({ method: r.m, path: r.p });
+ if (!skel.routes[k]) skel.routes[k] = { name: r.auto ? fallbackRouteName({ handler: r.h, method: r.m, path: r.p }) : r.name, description: r.auto ? '' : r.d };
+ }
+ }
+ if (!Object.keys(skel.routes).length) delete skel.routes;
+ fs.writeFileSync(descFile, JSON.stringify(skel, null, 2) + '\n');
+ index.push({ key, node: n?.label || nid, files: chunk.length, routes: routeCount, loc: chunk.reduce((s, f) => s + f.loc, 0) });
+ }
+}
+
+if (!index.length) { console.log('✓ Every file and route already has a description. Use --all to regenerate worksheets for everything.'); process.exit(0); }
+const totals = index.reduce((s, w) => ({ files: s.files + w.files, routes: s.routes + w.routes }), { files: 0, routes: 0 });
+console.log(`${index.length} worksheet(s) in floorplan/.cache/worksheets/ covering ${totals.files} files and ${totals.routes} routes still to describe.`);
+console.log('Each has a matching skeleton in floorplan/descriptions/<key>.json. Fill those in, then run build.mjs.');
+console.log(`Audience: ${audience}. Write in ${STYLE}\n`);
+console.log('key'.padEnd(34) + 'files'.padStart(6) + 'routes'.padStart(8) + 'loc'.padStart(8) + ' module');
+for (const w of index.sort((a, b) => b.files - a.files)) console.log(w.key.padEnd(34) + String(w.files).padStart(6) + String(w.routes).padStart(8) + fmtNum(w.loc).padStart(8) + ' ' + w.node);
diff --git a/skills/floorplan/scripts/lib/claudemd.mjs b/skills/floorplan/scripts/lib/claudemd.mjs
new file mode 100644
index 0000000..1636e79
--- /dev/null
+++ b/skills/floorplan/scripts/lib/claudemd.mjs
@@ -0,0 +1,90 @@
+// Keeps a short block in the project's CLAUDE.local.md pointing future Claude Code sessions at the map, so
+// "where is X / how does Y work" starts from the map instead of a fresh search of the code.
+// CLAUDE.local.md is Claude Code's personal, uncommitted project memory (loaded at launch like CLAUDE.md,
+// including from parent folders); the map itself isn't committed, so its pointer isn't either. The file
+// is added to the repo's local ignore list (.git/info/exclude), which leaves tracked files untouched.
+// The block sits between markers and is rewritten in place; the rest of the file is never touched.
+// Put <!-- floorplan:off --> in CLAUDE.local.md to opt out.
+import fs from 'node:fs';
+import path from 'node:path';
+import { git } from './common.mjs';
+
+const START = '<!-- floorplan:start -->';
+const END = '<!-- floorplan:end -->';
+const NAME = 'CLAUDE.local.md';
+
+function block(rel) {
+ return `${START}
+## Floorplan: map of this codebase
+
+\`${rel}/\` holds a map of this codebase: every module, file and endpoint with a plain-English name and a one-line description, and what connects to what. For questions like "where is X", "how does Y work" or "what uses Z", look it up before searching the code (run these from the folder this file is in):
+
+- \`node ${rel}/query.mjs find "<words>"\`: modules, files and endpoints that match
+- \`node ${rel}/query.mjs show <file path | module id | "GET /path">\`: what it is, what it uses, what uses it
+- \`node ${rel}/query.mjs path <from> <to>\`: how two things connect
+- \`node ${rel}/query.mjs overview\`: the whole system at a glance
+
+The map can lag behind recent edits, so confirm in the code before changing anything. Open it with \`node ${rel}/serve.mjs\`. After big changes, update it with the floorplan skill (the user can just ask to "update the floorplan"; only changed files are re-read).
+${END}`;
+}
+
+const read = (f) => (fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : null);
+/** The text with the block removed (normalized to \n), or null when there's no block. */
+const stripBlock = (text) => {
+ const a = text.indexOf(START), b = text.indexOf(END);
+ if (a < 0 || b < a) return null;
+ return [text.slice(0, a).trimEnd(), text.slice(b + END.length).trimStart()].filter(Boolean).join('\n\n').replace(/\r\n/g, '\n');
+};
+
+/** Adds CLAUDE.local.md to the enclosing repo's .git/info/exclude unless git already ignores it. */
+function excludeLocally(root) {
+ if (git(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') return 'not in a git repo';
+ if (git(root, ['ls-files', '--', NAME])) return `${NAME} is committed in this repo; the Floorplan section will show up in it`;
+ if (git(root, ['check-ignore', '-q', NAME]) !== null) return 'already ignored';
+ const prefix = git(root, ['rev-parse', '--show-prefix']) || '';
+ const excl = git(root, ['rev-parse', '--git-path', 'info/exclude']);
+ if (!excl) return 'could not find .git/info/exclude';
+ const file = path.resolve(root, excl);
+ const line = '/' + prefix + NAME;
+ const cur = read(file) || '';
+ if (!cur.split(/\r?\n/).includes(line)) {
+ fs.mkdirSync(path.dirname(file), { recursive: true });
+ fs.writeFileSync(file, cur.replace(/\s*$/, cur.trim() ? '\n' : '') + `# personal Claude Code notes (added by Floorplan)\n${line}\n`);
+ }
+ return 'ignored locally via .git/info/exclude';
+}
+
+/** Adds or refreshes the block, and moves it out of a committed CLAUDE.md written by older versions. */
+export function writeClaudeMd(root, outDir) {
+ const rel = path.relative(root, outDir).replace(/\\/g, '/');
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return 'skipped (map is outside the codebase)';
+ const notes = [];
+
+ // older versions wrote the block into CLAUDE.md, which is usually committed: take it back out
+ for (const f of [path.join(root, 'CLAUDE.md'), path.join(root, '.claude', 'CLAUDE.md')]) {
+ const t = read(f);
+ const rest = t == null ? null : stripBlock(t);
+ if (rest == null) continue;
+ const eol = t.includes('\r\n') ? '\r\n' : '\n';
+ const tracked = !!git(path.dirname(f), ['ls-files', '--', path.basename(f)]);
+ if (!rest.trim() && !tracked) fs.unlinkSync(f);
+ else fs.writeFileSync(f, rest.replace(/\n/g, eol) + (rest.trim() ? eol : ''));
+ notes.push(`moved the Floorplan section out of ${path.relative(root, f).replace(/\\/g, '/')}${!rest.trim() && tracked ? ' (now empty; delete it if you like)' : ''}`);
+ }
+
+ const file = path.join(root, NAME);
+ const old = read(file);
+ if (old?.includes('<!-- floorplan:off -->')) return 'skipped (opted out)';
+ const eol = old?.includes('\r\n') ? '\r\n' : '\n';
+ const text = block(rel).replace(/\n/g, eol);
+ let next;
+ if (old == null) next = text + eol;
+ else {
+ const a = old.indexOf(START), b = old.indexOf(END);
+ next = a >= 0 && b > a ? old.slice(0, a) + text + old.slice(b + END.length) : old.replace(/\s*$/, '') + eol + eol + text + eol;
+ }
+ if (next !== old) { fs.writeFileSync(file, next); notes.unshift(`${old == null ? 'created' : 'updated'} ${NAME}`); }
+ else notes.unshift(`${NAME} unchanged`);
+ notes.push(excludeLocally(root));
+ return notes.join('; ');
+}
diff --git a/skills/floorplan/scripts/lib/common.mjs b/skills/floorplan/scripts/lib/common.mjs
new file mode 100644
index 0000000..72c40e6
--- /dev/null
+++ b/skills/floorplan/scripts/lib/common.mjs
@@ -0,0 +1,269 @@
+// Shared helpers: paths, globs, file classification, git, and codebase discovery.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const toPosix = (p) => p.replace(/\\/g, '/');
+export const rel = (from, to) => toPosix(path.relative(from, to)) || '.';
+
+// ---------- globs ----------
+
+const GLOB_CHARS = /[*?{[]/;
+
+export function globToRegExp(glob) {
+ const g = toPosix(glob).replace(/^\.\//, '').replace(/\/$/, '');
+ let re = '';
+ let braces = 0;
+ for (let i = 0; i < g.length; ) {
+ const c = g[i];
+ if (c === '*') {
+ if (g[i + 1] === '*') {
+ const atStart = i === 0 || g[i - 1] === '/';
+ const atEnd = i + 2 === g.length || g[i + 2] === '/';
+ if (atStart && atEnd) {
+ if (i + 2 === g.length) { re += '.*'; i += 2; }
+ else { re += '(?:.*/)?'; i += 3; }
+ continue;
+ }
+ re += '.*'; i += 2; continue;
+ }
+ re += '[^/]*'; i++; continue;
+ }
+ if (c === '?') { re += '[^/]'; i++; continue; }
+ if (c === '{') { braces++; re += '(?:'; i++; continue; }
+ if (c === '}' && braces) { braces--; re += ')'; i++; continue; }
+ if (c === ',' && braces) { re += '|'; i++; continue; }
+ if (c === '[') {
+ const j = g.indexOf(']', i + 1);
+ if (j > i) { re += '[' + g.slice(i + 1, j).replace(/^!/, '^').replace(/\\/g, '\\\\') + ']'; i = j + 1; continue; }
+ }
+ re += c.replace(/[.+^$()|\\\]]/g, '\\$&');
+ i++;
+ }
+ return new RegExp('^' + re + '$');
+}
+
+/** Compile a glob. A pattern with no wildcards also matches everything under it as a directory. */
+export function compileGlob(glob) {
+ const g = toPosix(glob).replace(/^\.\//, '').replace(/\/$/, '');
+ const literalPrefix = g.split(GLOB_CHARS)[0];
+ if (!GLOB_CHARS.test(g)) {
+ return { glob, specificity: g.length, test: (p) => p === g || p.startsWith(g + '/') };
+ }
+ // A glob that names directories (src/components/{a,b}) also matches everything beneath them.
+ const re = globToRegExp(g);
+ const under = globToRegExp(g + '/**');
+ return { glob, specificity: literalPrefix.length, test: (p) => re.test(p) || under.test(p) };
+}
+
+// ---------- file classification ----------
+
+const LANG_BY_EXT = {
+ '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+ '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+ '.vue': 'vue', '.svelte': 'svelte', '.astro': 'astro',
+ '.py': 'python', '.pyi': 'python',
+ '.go': 'go', '.rs': 'rust', '.java': 'java', '.kt': 'kotlin', '.kts': 'kotlin', '.scala': 'scala',
+ '.cs': 'csharp', '.fs': 'fsharp', '.rb': 'ruby', '.php': 'php', '.swift': 'swift', '.dart': 'dart',
+ '.c': 'c', '.h': 'c', '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp', '.m': 'objc', '.mm': 'objc',
+ '.ex': 'elixir', '.exs': 'elixir', '.erl': 'erlang', '.clj': 'clojure', '.lua': 'lua', '.r': 'r', '.jl': 'julia',
+ '.zig': 'zig', '.elm': 'elm', '.hs': 'haskell', '.ml': 'ocaml', '.groovy': 'groovy',
+ '.sh': 'shell', '.bash': 'shell', '.zsh': 'shell', '.ps1': 'powershell', '.psm1': 'powershell',
+ '.sql': 'sql', '.tf': 'terraform', '.proto': 'protobuf', '.graphql': 'graphql', '.gql': 'graphql',
+ '.css': 'css', '.scss': 'css', '.sass': 'css', '.less': 'css',
+ '.html': 'html', '.htm': 'html', '.ejs': 'html', '.hbs': 'html', '.jinja': 'html', '.j2': 'html', '.njk': 'html',
+};
+const CONFIG_EXT = new Set(['.json', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.conf', '.xml', '.gradle', '.properties', '.env']);
+const CONFIG_NAMES = /^(dockerfile.*|makefile|procfile|justfile|\.env\..*|\.?[\w-]*rc|gemfile|rakefile|cargo\.toml|go\.mod|pyproject\.toml|setup\.cfg|requirements.*\.txt)$/i;
+const JSON_CONFIG = /^(package|tsconfig.*|jsconfig|composer|manifest|app|components|turbo|nx|lerna|angular|firebase|vercel|now|renovate|tslint|.?eslintrc|.?babelrc|.?prettierrc|.*.config|.*rc|settings|launch|tasks|deno|biome|project|workspace|devcontainer|cdk|serverless|appsettings.*|openapi|swagger).json$/i;
+const DOC_EXT = new Set(['.md', '.mdx', '.rst', '.adoc', '.txt']);
+const DATA_EXT = new Set(['.csv', '.tsv', '.jsonl', '.ndjson', '.parquet', '.sqlite', '.db', '.xlsx', '.xls', '.avro']);
+const ASSET_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp', '.avif', '.bmp', '.woff', '.woff2', '.ttf', '.otf', '.eot',
+ '.mp3', '.mp4', '.wav', '.webm', '.mov', '.pdf', '.zip', '.gz', '.tar', '.tgz', '.7z', '.jar', '.wasm', '.exe', '.dll', '.so', '.dylib', '.bin']);
+const LOCK_NAMES = /^(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb|poetry\.lock|pipfile\.lock|cargo\.lock|go\.sum|composer\.lock|gemfile\.lock|.*\.lock)$/i;
+const GENERATED = /(\.min\.(js|css)$|\.map$|\.tsbuildinfo$|\.pyc$|\.pyo$|\.class$|\.o$|(^|\/)next-env\.d\.ts$)/i;
+
+/** Directories never worth scanning, even if a repo tracks them. */
+export const HARD_IGNORE_DIRS = new Set([
+ 'node_modules', '.git', '.pnpm-store', '.yarn', '__pycache__', '.venv', 'venv', 'site-packages',
+ '.tox', '.mypy_cache', '.pytest_cache', '.ruff_cache', '.next', '.nuxt', '.svelte-kit', '.turbo',
+ '.parcel-cache', '.gradle', '.idea',
+]);
+
+/** The folder the map lives in, at the codebase root. Maps made before the rename used show-code/. */
+export const MAP_DIR = 'floorplan';
+export const LEGACY_MAP_DIR = 'show-code';
+/** True for a folder holding a map, so a project's own folder that happens to be called "floorplan" isn't taken for one. */
+export const isMapDir = (d) => ['architecture.json', 'graph.json', '.cache'].some((f) => fs.existsSync(path.join(d, f)));
+/**
+ * Keeps the map folder out of git: its own .gitignore ignores everything in it, itself included, so
+ * nothing in the project's tracked files changes. Returns a warning when git already tracks files
+ * there (ignoring doesn't untrack them), else null.
+ */
+export function keepOutOfGit(dir) {
+ const gi = path.join(dir, '.gitignore');
+ const want = '# Floorplan keeps its map out of git: this ignores everything in this folder, this file included.\n*\n';
+ fs.mkdirSync(dir, { recursive: true });
+ try { if (!fs.existsSync(gi) || fs.readFileSync(gi, 'utf8') !== want) fs.writeFileSync(gi, want); } catch {}
+ const tracked = (git(dir, ['ls-files', '--', '.']) || '').split('\n').filter(Boolean);
+ if (!tracked.length) return null;
+ const rel = path.basename(dir);
+ return `${tracked.length} file(s) in ${rel}/ were committed to git before; they stay tracked until you run: git rm -r --cached ${rel} (this keeps the files on disk)`;
+}
+
+/** The map folder for a codebase root. Moves an old show-code/ map into place unless migrate is false. */
+export function mapDir(root, { migrate = true } = {}) {
+ const dir = path.join(root, MAP_DIR);
+ const old = path.join(root, LEGACY_MAP_DIR);
+ if (migrate && !fs.existsSync(dir) && isMapDir(old)) {
+ fs.renameSync(old, dir);
+ console.error(`(moved the existing map from ${LEGACY_MAP_DIR}/ to ${MAP_DIR}/)`);
+ }
+ if (fs.existsSync(dir) && !isMapDir(dir) && fs.readdirSync(dir).length) {
+ console.error(`✗ ${MAP_DIR}/ already exists here and isn't a map (it's part of the project). Pass --out <folder> to put the map somewhere else.`);
+ process.exit(1);
+ }
+ return dir;
+}
+/** Extra directories skipped when walking outside of git (where .gitignore can't help). */
+export const WALK_IGNORE_DIRS = new Set([...HARD_IGNORE_DIRS, 'dist', 'build', 'out', 'target', 'coverage', '.cache', 'vendor', 'bin', 'obj', 'env', '.vscode', '.claude']);
+
+export function classify(relPath, bytes) {
+ const base = path.posix.basename(relPath).toLowerCase();
+ const ext = path.posix.extname(base);
+ if (GENERATED.test(relPath)) return { category: 'generated', lang: null };
+ if (LOCK_NAMES.test(base)) return { category: 'lock', lang: null };
+ if (ext === '.log' || base.endsWith('.log')) return { category: 'log', lang: null };
+ if (ASSET_EXT.has(ext)) return { category: 'asset', lang: null };
+ if (DATA_EXT.has(ext)) return { category: 'data', lang: null };
+ if (LANG_BY_EXT[ext]) {
+ if (ext === '.svg') return { category: 'asset', lang: null };
+ return { category: 'code', lang: LANG_BY_EXT[ext] };
+ }
+ if (ext === '.json' && (bytes > 100_000 || !JSON_CONFIG.test(base))) return { category: 'data', lang: null };
+ if (CONFIG_EXT.has(ext) || CONFIG_NAMES.test(base)) return { category: 'config', lang: ext ? ext.slice(1) : base };
+ if (DOC_EXT.has(ext)) return { category: 'docs', lang: null };
+ return { category: 'other', lang: null };
+}
+
+// ---------- git ----------
+
+export function git(cwd, args) {
+ try {
+ return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }).trimEnd();
+ } catch {
+ return null;
+ }
+}
+
+export function gitInfo(dir) {
+ const head = git(dir, ['rev-parse', 'HEAD']);
+ const branch = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+ const remote = git(dir, ['config', '--get', 'remote.origin.url']);
+ return { head, branch, remote: remote ? remote.replace(/\/\/[^@/]+@/, '//') : null };
+}
+
+/** Files git considers part of the repo: tracked + untracked-but-not-ignored. */
+export function gitFiles(dir) {
+ const out = git(dir, ['ls-files', '-co', '--exclude-standard', '-z']);
+ if (out == null) return null;
+ return [...new Set(out.split('\0').filter(Boolean))].map(toPosix);
+}
+
+/** If dir/.git is a file pointing into another repo's worktrees/, return that repo's working dir. */
+function worktreeMain(dir) {
+ const dotgit = path.join(dir, '.git');
+ let st;
+ try { st = fs.statSync(dotgit); } catch { return null; }
+ if (!st.isFile()) return null;
+ const m = /gitdir:\s*(.+)/.exec(fs.readFileSync(dotgit, 'utf8'));
+ if (!m) return null;
+ const gitdir = path.resolve(dir, m[1].trim());
+ const idx = toPosix(gitdir).lastIndexOf('/.git/worktrees/');
+ if (idx === -1) return null; // submodule or other indirection: treat as a normal repo
+ return path.resolve(toPosix(gitdir).slice(0, idx));
+}
+
+// ---------- discovery ----------
+
+/**
+ * Walk the codebase root and find every git repo in it. Repos are not descended into
+ * (git ls-files covers them). Loose files outside any repo are collected too.
+ * Linked worktrees of a repo that is itself in the codebase are skipped as duplicates.
+ */
+export function discover(root, { includeWorktrees = false, maxLooseFiles = 5000 } = {}) {
+ const repos = [];
+ const loose = [];
+ const skipped = [];
+
+ const walk = (dir, depth) => {
+ if (fs.existsSync(path.join(dir, '.git'))) {
+ repos.push({ abs: dir, path: rel(root, dir), worktreeOf: worktreeMain(dir) });
+ return;
+ }
+ if (depth > 8) return;
+ let entries;
+ try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+ if (entries.filter((e) => e.isFile()).length > 500) { skipped.push({ path: rel(root, dir), reason: 'over 500 files outside git (data dump?)' }); return; }
+ for (const e of entries) {
+ const abs = path.join(dir, e.name);
+ if (e.isSymbolicLink()) continue;
+ if (e.isDirectory()) {
+ if (WALK_IGNORE_DIRS.has(e.name) || (e.name.startsWith('.') && e.name !== '.github')) {
+ if (!['.git', 'node_modules', '__pycache__'].includes(e.name)) skipped.push({ path: rel(root, abs), reason: 'ignored directory' });
+ continue;
+ }
+ walk(abs, depth + 1);
+ } else if (e.isFile()) {
+ if (loose.length < maxLooseFiles) loose.push(rel(root, abs));
+ }
+ }
+ };
+ walk(root, 0);
+
+ // Drop worktree duplicates.
+ const norm = (p) => toPosix(path.resolve(p)).toLowerCase();
+ const primary = new Set(repos.filter((r) => !r.worktreeOf).map((r) => norm(r.abs)));
+ const seenMains = new Set();
+ const kept = [];
+ for (const r of repos) {
+ if (r.worktreeOf && !includeWorktrees && r.abs !== root) {
+ const main = norm(r.worktreeOf);
+ if (primary.has(main)) { skipped.push({ path: r.path, reason: `worktree of ${rel(root, r.worktreeOf)}` }); continue; }
+ if (seenMains.has(main)) { skipped.push({ path: r.path, reason: `another worktree of ${r.worktreeOf}` }); continue; }
+ seenMains.add(main);
+ }
+ kept.push(r);
+ }
+ return { repos: kept, loose, skipped };
+}
+
+// ---------- misc ----------
+
+export function readJsonLoose(file) {
+ try {
+ const txt = fs.readFileSync(file, 'utf8')
+ .replace(/^/, '')
+ .replace(/("(?:[^"\\]|\\.)*")|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (m, str) => str ?? '')
+ .replace(/,(\s*[}\]])/g, '$1');
+ return JSON.parse(txt);
+ } catch {
+ return null;
+ }
+}
+
+export function parseArgs(argv, defaults = {}) {
+ const out = { _: [], ...defaults };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a.startsWith('--')) {
+ const [k, v] = a.slice(2).split('=');
+ if (v !== undefined) out[k] = v;
+ else if (argv[i + 1] && !argv[i + 1].startsWith('--')) out[k] = argv[++i];
+ else out[k] = true;
+ } else out._.push(a);
+ }
+ return out;
+}
+
+export const fmtNum = (n) => n >= 10000 ? (n / 1000).toFixed(0) + 'k' : n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n);
diff --git a/skills/floorplan/scripts/lib/extract.mjs b/skills/floorplan/scripts/lib/extract.mjs
new file mode 100644
index 0000000..cee1ae9
--- /dev/null
+++ b/skills/floorplan/scripts/lib/extract.mjs
@@ -0,0 +1,497 @@
+// Per-language, regex-based extraction of imports, exported symbols, HTTP routes and HTTP calls.
+// Deliberately approximate: good enough to draw the map, cheap enough to run on any repo.
+
+const lineIndex = (src) => {
+ const starts = [0];
+ for (let i = 0; i < src.length; i++) if (src.charCodeAt(i) === 10) starts.push(i + 1);
+ return (offset) => {
+ let lo = 0, hi = starts.length - 1;
+ while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= offset) lo = mid; else hi = mid - 1; }
+ return lo + 1;
+ };
+};
+
+const blank = (s) => s.replace(/[^\n]/g, ' ');
+// Strip comments while keeping offsets (so line numbers stay right).
+const stripCStyle = (src) => src
+ .replace(/\/\*[\s\S]*?\*\//g, blank)
+ .replace(/(^|[^:"'`\\])\/\/[^\n]*/g, (m, pre) => pre + blank(m.slice(pre.length)));
+const stripHash = (src) => src.replace(/(^|\s)#[^\n]*/g, (m, pre) => pre + blank(m.slice(pre.length)));
+
+const all = (re, s) => [...s.matchAll(re)];
+
+// ---------- HTTP call literals ----------
+
+const HTTP_CONTEXT = /\b(fetch|axios|ky|got|request|requests|httpx|aiohttp|session|client|http|https|api|Api|API|endpoint|Endpoint|url|Url|URL|BASE|base)\b|\.(get|post|put|patch|delete|head)\s*(<[^>]*>)?\s*\(/;
+const NAV_CONTEXT = /\b(router\.(push|replace|prefetch)|navigate|redirect|href|revalidatePath|pathname|Link|to=|location\.)\b|window\.location/;
+const STR_LITERAL = /(["'`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+const IGNORED_HOST = /^(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?$|\.(test|example|invalid|local|localhost|internal)(:\d+)?$|(^|\.)example\.(com|org|net)$/;
+const FILE_EXT_TAIL = /\.(png|jpe?g|gif|svg|ico|webp|css|js|mjs|ts|tsx|json|html?|txt|md|pdf|csv|xml|woff2?|ttf|map)$/i;
+
+function normalizeCallLiteral(raw) {
+ let s = raw.trim();
+ let host = null;
+ const abs = /^https?:\/\/([^/${}\s]+)(.*)$/i.exec(s);
+ if (abs) { host = abs[1].toLowerCase(); s = abs[2] || '/'; }
+ // leading interpolations: ${API_BASE}/x, {BASE_URL}/x
+ s = s.replace(/^(?:\$\{[^}]*\}|\{[^}]*\})+/, '');
+ if (!s.startsWith('/')) return null;
+ s = s.split(/[?#]/)[0];
+ // a query string interpolated straight onto the last segment: `/cost-lots${qs}`, `/items{query}`
+ s = s.replace(/([A-Za-z0-9_\-])(?:\$\{[^}]*\}|\{[^}]*\})+$/, '$1');
+ if (!/^\/[\w\-.~%/*${}:@<>\[\]]*$/.test(s)) return null;
+ if (FILE_EXT_TAIL.test(s)) return null;
+ if (!/[a-zA-Z]{2,}/.test(s.replace(/\$\{[^}]*\}|\{[^}]*\}/g, ''))) return host ? { host, path: null } : null;
+ return { host, path: s };
+}
+
+/**
+ * Collapse every ${…} inside template literals to ${x}, counting braces, so nested templates like
+ * `/orders${q ? `?${q}` : ''}` read as one literal "/orders${x}" instead of breaking at the inner backtick.
+ */
+export function flattenTemplates(line) {
+ let out = '', inTpl = false;
+ for (let i = 0; i < line.length; i++) {
+ const c = line[i];
+ if (c === '\\') { out += c + (line[i + 1] ?? ''); i++; continue; }
+ if (c === '`') { inTpl = !inTpl; out += c; continue; }
+ if (inTpl && c === '$' && line[i + 1] === '{') {
+ let depth = 1, j = i + 2;
+ for (; j < line.length && depth; j++) { if (line[j] === '{') depth++; else if (line[j] === '}') depth--; }
+ out += '${x}'; i = j - 1; continue;
+ }
+ out += c;
+ }
+ return out;
+}
+
+const METHOD_CALL = /\.(get|post|put|patch|delete)\s*(?:<[^>]*>)?\s*\(/i;
+const METHOD_OPT = /method\s*[:=]\s*["'`](\w+)/i;
+// `const url = …`, `url = f"…"`, `this.endpoint = …`: a URL kept in a variable for the call below
+const ASSIGN = /(?:\b(?:const|let|var)\s+|^\s*(?:self\.|this\.)?)([A-Za-z_$][\w$]*)\s*(?::\s*[\w<>[\]|. ]+?\s*)?=(?![=>])/;
+/** Where a variable is passed to an HTTP call within the next few lines, and with which method. */
+function variableUse(lines, i, name) {
+ const use = new RegExp(`(?:\\.(get|post|put|patch|delete|head|request)\\s*(?:<[^>]*>)?\\s*\\(|\\b(?:fetch|axios|ky|got|request|urlopen)\\s*\\(|\\brequests\\.(get|post|put|patch|delete)\\s*\\()\\s*${name}\\b`, 'i');
+ for (let j = i + 1; j < Math.min(lines.length, i + 10); j++) {
+ const m = use.exec(lines[j]);
+ if (!m) continue;
+ const verb = (m[1] && m[1].toLowerCase() !== 'request' ? m[1] : m[2]) || METHOD_OPT.exec(lines.slice(j, j + 4).join(' '))?.[1] || '';
+ return { method: verb.toUpperCase() || null };
+ }
+ return null;
+}
+
+function extractCalls(src, at, { skip } = {}) {
+ const calls = [];
+ const hosts = [];
+ const lines = src.split('\n');
+ let offset = 0;
+ for (let i = 0; i < lines.length; i++) {
+ const line = flattenTemplates(lines[i]);
+ const lineStart = offset;
+ offset += lines[i].length + 1;
+ if (line.length > 500 || NAV_CONTEXT.test(line)) continue;
+ if (skip && skip.test(line)) continue;
+ // a URL assigned to a variable counts when an HTTP call below uses that variable
+ const assigned = ASSIGN.exec(line)?.[1];
+ const use = assigned ? variableUse(lines, i, assigned) : null;
+ if (!HTTP_CONTEXT.test(line) && !use) continue;
+ const method = (METHOD_CALL.exec(line)?.[1] || METHOD_OPT.exec(line)?.[1] || use?.method || '').toUpperCase() || null;
+ for (const m of line.matchAll(STR_LITERAL)) {
+ const n = normalizeCallLiteral(m[2]);
+ if (!n) continue;
+ const lineNo = at(lineStart);
+ if (n.host && !IGNORED_HOST.test(n.host) &&!n.host.includes('${') && !n.host.includes('{')) hosts.push({ host: n.host, line: lineNo });
+ if (n.path && !n.host) calls.push({ path: n.path, method, line: lineNo });
+ }
+ }
+ return { calls, hosts };
+}
+
+// ---------- JS / TS ----------
+
+/** Imported names plus their local bindings: `import users, { a as b } from` → locals { users: 'default', b: 'a' }. */
+function parseImportClause(clause) {
+ const names = [];
+ const locals = {};
+ const c = clause.replace(/^type\s+/, '').trim();
+ const brace = /\{([^}]*)\}/.exec(c);
+ if (brace) for (const part of brace[1].split(',')) {
+ const [orig, alias] = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/).map((s) => s?.trim());
+ if (orig) { names.push(orig); locals[alias || orig] = orig; }
+ }
+ const head = c.replace(/\{[^}]*\}/, '').replace(/,/g, ' ').trim();
+ const ns = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(head);
+ if (ns) locals[ns[1]] = '*';
+ const def = /^([A-Za-z_$][\w$]*)/.exec(head);
+ if (def && def[1] !== 'as') { names.push('default'); locals[def[1]] = 'default'; }
+ return { names, locals };
+}
+
+function extractJs(src, filePath) {
+ const code = stripCStyle(src);
+ const at = lineIndex(code);
+ const imports = [];
+ for (const m of all(/(?:^|[;\n}])\s*import\s+(?!\()((?:type\s+)?[^'";]*?)\s+from\s+["']([^"'\n]+)["']/g, code)) imports.push({ spec: m[2], ...parseImportClause(m[1]), line: at(m.index) });
+ for (const m of all(/(?:^|[;\n])\s*import\s+["']([^"'\n]+)["']/g, code)) imports.push({ spec: m[1], names: [], line: at(m.index) });
+ for (const m of all(/\bexport\s+(?:type\s+)?(\*(?:\s+as\s+\w+)?|\{[^}]*\})\s+from\s+["']([^"'\n]+)["']/g, code)) imports.push({ spec: m[2], names: m[1].startsWith('{') ? parseImportClause(m[1]).names : [], line: at(m.index), reexport: true });
+ for (const m of all(/\brequire\(\s*["']([^"'\n]+)["']\s*\)/g, code)) {
+ // `const usersRouter = require('./users')` / `const { a, b: c } = require(…)` bind local names
+ const before = code.slice(code.lastIndexOf('\n', m.index) + 1, m.index);
+ const bind = /(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?$/.exec(before);
+ const locals = {};
+ if (bind?.[1].startsWith('{')) for (const part of bind[1].slice(1, -1).split(',')) { const [orig, alias] = part.trim().split(/\s*:\s*/); if (orig) locals[(alias || orig).trim()] = orig.trim(); }
+ else if (bind) locals[bind[1]] = 'default';
+ imports.push({ spec: m[1], names: Object.values(locals), locals, line: at(m.index) });
+ }
+ for (const m of all(/\bimport\(\s*["']([^"'\n]+)["']\s*\)/g, code)) imports.push({ spec: m[1], names: [], line: at(m.index), dynamic: true });
+
+ const symbols = [];
+ const seen = new Set();
+ const addSym = (name, kind, idx, isDefault) => {
+ const key = name + (isDefault ? '#d' : '');
+ if (seen.has(key)) return;
+ seen.add(key);
+ symbols.push({ name, kind, line: at(idx), ...(isDefault ? { default: true } : {}) });
+ };
+ for (const m of all(/^[ \t]*export\s+(default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm, code)) {
+ const kind = m[2].startsWith('function') ? 'function' : ['const', 'let', 'var'].includes(m[2]) ? 'const' : m[2];
+ addSym(m[3], kind, m.index, !!m[1]);
+ }
+ for (const m of all(/^[ \t]*export\s+default\s+([A-Za-z_$][\w$]*)\s*;?\s*$/gm, code)) {
+ if (!['function', 'class', 'async'].includes(m[1])) addSym(m[1], 'default', m.index, true);
+ }
+ for (const m of all(/^[ \t]*export\s*\{([^}]*)\}\s*;?\s*$/gm, code)) {
+ for (const part of m[1].split(',')) {
+ const [orig, alias] = part.trim().split(/\s+as\s+/);
+ if (orig) addSym((alias || orig).trim(), 'export', m.index, (alias || '').trim() === 'default');
+ }
+ }
+ // Next.js route handlers / module exports
+ for (const m of all(/^[ \t]*module\.exports\s*=\s*([A-Za-z_$][\w$]*)?/gm, code)) addSym(m[1] || 'module.exports', 'default', m.index, true);
+
+ // Express / Koa / Hono style routes and mounts
+ const routes = [];
+ const mounts = [];
+ for (const m of all(/\b([A-Za-z_$][\w$]*)\.(get|post|put|patch|delete|all|options|head)\(\s*["'`](\/[^"'`]*)["'`]/g, code)) {
+ if (!/^(app|server|fastify|hono|routes?|[a-z]*Router|router)$/.test(m[1])) continue;
+ routes.push({ method: m[2].toUpperCase(), path: m[3], var: m[1], line: at(m.index) });
+ }
+ for (const m of all(/\b([A-Za-z_$][\w$]*)\.(use|route)\(\s*["'`](\/[^"'`]*)["'`]\s*,([^\n;]*)/g, code)) {
+ const req = /require\(\s*["']([^"']+)["']\s*\)/.exec(m[4]);
+ if (req) { mounts.push({ prefix: m[3], spec: req[1], line: at(m.index) }); continue; }
+ const args = m[4].replace(/\)\s*$/, '').split(',').map((s) => s.trim()).filter((s) => /^[A-Za-z_$][\w$.]*$/.test(s));
+ if (args.length) mounts.push({ prefix: m[3], var: args[args.length - 1], line: at(m.index) });
+ }
+
+ // Next.js app/pages API routes, derived from the file path
+ const next = /(?:^|\/)(?:src\/)?app\/(.*?)\/?route\.(?:t|j)sx?$/.exec(filePath) || /(?:^|\/)(?:src\/)?pages\/(api\/.*?)(?:\/index)?\.(?:t|j)sx?$/.exec(filePath);
+ if (next) {
+ const p = '/' + next[1].split('/').filter((s) => s && !/^\(.*\)$/.test(s) && !s.startsWith('@')).join('/');
+ const methods = all(/export\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/g, code).map((m) => m[1]);
+ for (const method of methods.length ? methods : ['ANY']) routes.push({ method, path: p, var: null, line: 1, framework: 'next' });
+ }
+
+ const serverLine = /\b\w+\.(use|route)\(\s*["'`]\/|\b(?:app|server|fastify|hono|routes?|router|[a-z]+Router)\.(?:get|post|put|patch|delete|all|options|head)\(\s*["'`]\//;
+ const { calls, hosts } = extractCalls(code, at, { skip: serverLine });
+ const seenCall = new Set(calls.map((c) => `${c.line}|${c.path}`));
+ for (const c of wrapperCalls(code, at)) if (!seenCall.has(`${c.line}|${c.path}`)) calls.push(c);
+ return { imports, symbols, routes, mounts, calls, hosts };
+}
+
+/**
+ * Calls through a helper defined in the same file that adds a prefix and fetches, e.g.
+ * const call = (path, method = 'GET') => apiClient.request(`/inventory${path}`, { method });
+ * definitions: () => call('/definitions'),
+ * becomes GET /inventory/definitions. Only same-file helpers whose first parameter is
+ * spliced into a URL that an HTTP call fetches.
+ */
+function wrapperCalls(code, at) {
+ const out = [];
+ const defs = /(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*\(([^)]*)\)|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:<[^>]*>\s*)?\(([^)]*)\)\s*(?::\s*[^=]+?)?=>/g;
+ for (const m of code.matchAll(defs)) {
+ const name = m[1] || m[3];
+ const params = (m[2] ?? m[4]).split(',').map((p) => p.trim()).filter(Boolean);
+ const pnames = params.map((p) => /^[A-Za-z_$][\w$]*/.exec(p)?.[0]);
+ if (!pnames[0] || /^(get|post|put|patch|delete|request|fetch)$/i.test(name)) continue;
+ const rawBody = code.slice(m.index + m[0].length, m.index + m[0].length + 700);
+ const body = flattenTemplates(rawBody);
+ if (!HTTP_CONTEXT.test(body)) continue;
+ const tpl = spliced(rawBody, pnames[0]);
+ if (tpl == null) continue;
+ const methodIdx = pnames.findIndex((p, i) => i > 0 && (/^method$/i.test(p) || new RegExp(`method\\s*:\\s*${p}\\b`).test(body)));
+ const defMethod = (methodIdx > 0 && /=\s*["'`](\w+)["'`]/.exec(params[methodIdx])?.[1]) || METHOD_CALL.exec(body)?.[1] || 'GET';
+ const callRe = new RegExp(`\\b${name}\\s*(?:<[^>]*>)?\\(\\s*([\"'\`])((?:\\\\.|(?!\\1)[^\\\\\\n])*)\\1([^\\n]*)`, 'g');
+ const defLine = at(m.index);
+ code.split('\n').forEach((raw, i) => {
+ if (i + 1 === defLine) return; // the definition itself
+ for (const c of flattenTemplates(raw).matchAll(callRe)) {
+ const n = normalizeCallLiteral(tpl + c[2]);
+ if (!n?.path || n.host) continue;
+ const verb = methodIdx > 0 ? /["'`](GET|POST|PUT|PATCH|DELETE)["'`]/i.exec(c[3])?.[1] : null;
+ out.push({ path: n.path, method: (verb || defMethod).toUpperCase(), line: i + 1 });
+ }
+ });
+ }
+ return out;
+}
+/** The literal prefix right before ${param} in the helper's URL template (`${BASE}/prefix${path}` → "/prefix"), or null. */
+function spliced(rawBody, param) {
+ const raw = new RegExp(`\`((?:\\$\\{[^}]*\\})*)([^\`$]*)\\$\\{\\s*${param}\\s*\\}`).exec(rawBody);
+ return raw ? raw[2] : null;
+}
+
+// ---------- Python ----------
+
+function extractPy(src) {
+ const code = stripHash(src);
+ const at = lineIndex(code);
+ const imports = [];
+ for (const m of all(/^[ \t]*import[ \t]+([\w., \t]+)$/gm, code)) {
+ for (const part of m[1].split(',')) {
+ const [mod, alias] = part.trim().split(/\s+as\s+/);
+ if (mod) imports.push({ spec: mod.trim(), names: [], alias: alias?.trim(), line: at(m.index) });
+ }
+ }
+ for (const m of all(/^[ \t]*from[ \t]+(\.*[\w.]*)[ \t]+import[ \t]+(\([^)]*\)|[^\n]+)/gm, code)) {
+ const names = [];
+ const aliases = {};
+ for (const part of m[2].replace(/[()\\]/g, ' ').split(',')) {
+ const [orig, alias] = part.trim().split(/\s+as\s+/);
+ if (orig && orig !== '*') { names.push(orig.trim()); if (alias) aliases[alias.trim()] = orig.trim(); }
+ }
+ imports.push({ spec: m[1], names, aliases, from: true, line: at(m.index) });
+ }
+
+ const symbols = [];
+ for (const m of all(/^(?:async[ \t]+)?def[ \t]+([A-Za-z]\w*)/gm, code)) symbols.push({ name: m[1], kind: 'function', line: at(m.index) });
+ for (const m of all(/^class[ \t]+([A-Za-z]\w*)/gm, code)) symbols.push({ name: m[1], kind: 'class', line: at(m.index) });
+ symbols.sort((a, b) => a.line - b.line);
+
+ const routes = [];
+ const routers = {};
+ for (const m of all(/^[ \t]*([A-Za-z_]\w*)\s*=\s*(?:\w+\.)?(Blueprint|APIRouter|Router)\(([^)]*)\)/gm, code)) {
+ routers[m[1]] = /(?:url_)?prefix\s*=\s*["']([^"']*)["']/.exec(m[3])?.[1] || '';
+ }
+ for (const m of all(/^[ \t]*@([A-Za-z_]\w*)\.(route|get|post|put|patch|delete|api_route|websocket)\(\s*[rf]?["']([^"']*)["']([^\n]*)/gm, code)) {
+ let methods = [m[2].toUpperCase()];
+ if (m[2] === 'route' || m[2] === 'api_route') {
+ // the decorator's arguments may continue over several lines, up to the next decorator or def
+ const rest = code.slice(m.index + m[0].length - m[4].length, m.index + m[0].length + 400).split(/\n\s*(?:@|def |async def )/)[0];
+ const ms = /methods\s*=\s*[\[(]([^\])]*)[\])]/.exec(rest);
+ methods = ms ? [...ms[1].matchAll(/["'](\w+)["']/g)].map((x) => x[1].toUpperCase()) : ['GET'];
+ }
+ for (const method of methods) routes.push({ method, path: m[3], var: m[1], line: at(m.index) });
+ }
+ // Django urls.py
+ for (const m of all(/\b(?:re_)?path\(\s*r?["']([^"']*)["']\s*,\s*(?!include)/g, code)) routes.push({ method: 'ANY', path: '/' + m[1].replace(/^\^|\$$/g, ''), var: null, line: at(m.index), framework: 'django' });
+
+ const mounts = [];
+ for (const m of all(/\b(?:register_blueprint|include_router|mount)\(\s*([A-Za-z_][\w.]*)([^)]*)\)/g, code)) {
+ mounts.push({ var: m[1], prefix: /(?:url_)?prefix\s*=\s*["']([^"']*)["']/.exec(m[2])?.[1] || '', line: at(m.index) });
+ }
+
+ const routeLine = /^\s*@\w+\.(route|get|post|put|patch|delete)\(/;
+ const { calls, hosts } = extractCalls(code, at, { skip: routeLine });
+ return { imports, symbols, routes, mounts, calls, hosts, routers };
+}
+
+// ---------- Go ----------
+
+function extractGo(src) {
+ const code = stripCStyle(src);
+ const at = lineIndex(code);
+ const imports = [];
+ for (const m of all(/^import\s+(?:[\w.]+\s+)?"([^"]+)"/gm, code)) imports.push({ spec: m[1], names: [], line: at(m.index) });
+ for (const block of all(/^import\s*\(([\s\S]*?)\)/gm, code)) {
+ for (const m of all(/(?:[\w.]+\s+)?"([^"]+)"/g, block[1])) imports.push({ spec: m[1], names: [], line: at(block.index) });
+ }
+ const symbols = [];
+ for (const m of all(/^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)/gm, code)) symbols.push({ name: m[1], kind: 'function', line: at(m.index) });
+ for (const m of all(/^type\s+([A-Z]\w*)\s+(struct|interface)?/gm, code)) symbols.push({ name: m[1], kind: m[2] || 'type', line: at(m.index) });
+ const routes = [];
+ for (const m of all(/\.(HandleFunc|Handle|GET|POST|PUT|PATCH|DELETE|Get|Post|Put|Patch|Delete)\(\s*"(\/[^"]*)"/g, code)) {
+ const method = /^handle/i.test(m[1]) ? 'ANY' : m[1].toUpperCase();
+ const p = m[2].replace(/^(GET|POST|PUT|PATCH|DELETE)\s+/, '');
+ routes.push({ method, path: p, var: null, line: at(m.index) });
+ }
+ const { calls, hosts } = extractCalls(code, at, { skip: /\.(HandleFunc|Handle|GET|POST)\(/ });
+ return { imports, symbols, routes, mounts: [], calls, hosts };
+}
+
+// ---------- Rust ----------
+
+function extractRust(src) {
+ const code = stripCStyle(src);
+ const at = lineIndex(code);
+ const imports = [];
+ for (const m of all(/^[ \t]*(?:pub(?:\([^)]*\))?\s+)?mod\s+(\w+)\s*;/gm, code)) imports.push({ spec: m[1], kind: 'mod', names: [], line: at(m.index) });
+ for (const m of all(/^[ \t]*(?:pub(?:\([^)]*\))?\s+)?use\s+([\w:]+)/gm, code)) imports.push({ spec: m[1], kind: 'use', names: [], line: at(m.index) });
+ const symbols = [];
+ for (const m of all(/^[ \t]*pub\s+(?:async\s+)?(fn|struct|enum|trait|type|const|static)\s+(\w+)/gm, code)) symbols.push({ name: m[2], kind: m[1] === 'fn' ? 'function' : m[1], line: at(m.index) });
+ const routes = [];
+ for (const m of all(/#\[(get|post|put|patch|delete)\(\s*"([^"]+)"/g, code)) routes.push({ method: m[1].toUpperCase(), path: m[2], var: null, line: at(m.index) });
+ for (const m of all(/\.route\(\s*"([^"]+)"\s*,\s*(get|post|put|patch|delete)/g, code)) routes.push({ method: m[2].toUpperCase(), path: m[1], var: null, line: at(m.index) });
+ const { calls, hosts } = extractCalls(code, at);
+ return { imports, symbols, routes, mounts: [], calls, hosts };
+}
+
+// ---------- JVM ----------
+
+function extractJvm(src) {
+ const code = stripCStyle(src);
+ const at = lineIndex(code);
+ const pkg = /^\s*package\s+([\w.]+)/m.exec(code)?.[1] || null;
+ const imports = all(/^\s*import\s+(?:static\s+)?([\w.*]+)/gm, code).map((m) => ({ spec: m[1], names: [], line: at(m.index) }));
+ const symbols = [];
+ for (const m of all(/^\s*(?:public\s+|internal\s+)?(?:abstract\s+|final\s+|data\s+|sealed\s+|open\s+)*(class|interface|enum|record|object)\s+(\w+)/gm, code)) symbols.push({ name: m[2], kind: m[1], line: at(m.index) });
+ const routes = [];
+ const classPrefix = /@RequestMapping\(\s*(?:value\s*=\s*|path\s*=\s*)?"([^"]*)"[^)]*\)\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+)?class/.exec(code)?.[1] || '';
+ for (const m of all(/@(Get|Post|Put|Patch|Delete|Request)Mapping\(\s*(?:value\s*=\s*|path\s*=\s*)?"([^"]*)"/g, code)) {
+ if (m[1] === 'Request' && m[2] === classPrefix) continue;
+ routes.push({ method: m[1] === 'Request' ? 'ANY' : m[1].toUpperCase(), path: classPrefix + m[2], var: null, line: at(m.index) });
+ }
+ const { calls, hosts } = extractCalls(code, at, { skip: /@\w+Mapping/ });
+ return { imports, symbols, routes, mounts: [], calls, hosts, pkg };
+}
+
+// ---------- small ones ----------
+
+function extractSimple(src, lang) {
+ const code = lang === 'ruby' ? stripHash(src) : stripCStyle(src);
+ const at = lineIndex(code);
+ const imports = [];
+ if (lang === 'ruby') for (const m of all(/\brequire_relative\s*\(?\s*["']([^"']+)["']/g, code)) imports.push({ spec: './' + m[1].replace(/^\.\//, ''), names: [], line: at(m.index) });
+ if (lang === 'c' || lang === 'cpp' || lang === 'objc') for (const m of all(/^\s*#\s*(?:include|import)\s+"([^"]+)"/gm, code)) imports.push({ spec: m[1], names: [], kind: 'include', line: at(m.index) });
+ if (lang === 'php') for (const m of all(/\b(?:require|include)(?:_once)?\s*\(?\s*(?:__DIR__\s*\.\s*)?["']([^"']+)["']/g, code)) imports.push({ spec: m[1].startsWith('/') ? '.' + m[1] : m[1], names: [], line: at(m.index) });
+ if (lang === 'css') for (const m of all(/@(?:import|use|forward)\s+(?:url\()?["']([^"']+)["']/g, code)) imports.push({ spec: m[1].startsWith('.') ? m[1] : './' + m[1], names: [], line: at(m.index) });
+ const symbols = [];
+ if (lang === 'ruby') for (const m of all(/^\s*(class|module)\s+([A-Z][\w:]*)/gm, code)) symbols.push({ name: m[2], kind: m[1], line: at(m.index) });
+ if (lang === 'csharp') for (const m of all(/^\s*public\s+(?:static\s+|abstract\s+|sealed\s+|partial\s+)*(class|interface|enum|record|struct)\s+(\w+)/gm, code)) symbols.push({ name: m[2], kind: m[1], line: at(m.index) });
+ const { calls, hosts } = ['ruby', 'php', 'csharp', 'swift', 'dart', 'kotlin'].includes(lang) ? extractCalls(code, at) : { calls: [], hosts: [] };
+ return { imports, symbols, routes: [], mounts: [], calls, hosts };
+}
+
+function extractByLang(src, lang, filePath) {
+ switch (lang) {
+ case 'typescript': case 'javascript': case 'vue': case 'svelte': case 'astro': return extractJs(src, filePath);
+ case 'python': return extractPy(src);
+ case 'go': return extractGo(src);
+ case 'rust': return extractRust(src);
+ case 'java': case 'kotlin': case 'scala': case 'groovy': return extractJvm(src);
+ default: return extractSimple(src, lang);
+ }
+}
+
+export function extract(src, lang, filePath) {
+ const r = extractByLang(src, lang, filePath);
+ addDocs(src, lang, r);
+ return r;
+}
+
+// ---------- docs: file headers, docstrings, JSDoc, route handlers ----------
+
+const HASH_LANGS = new Set(['python', 'ruby', 'shell', 'powershell', 'r', 'elixir', 'perl']);
+const LICENSE = /copyright|license|spdx|eslint-disable|@ts-nocheck|prettier-ignore|^-\*-|coding[:=]|generated by|do not edit/i;
+
+export function cleanDoc(text) {
+ if (!text) return null;
+ const lines = text.split('\n')
+ .map((l) => l.replace(/^\s*(\/\*\*?|\*\/|\*|\/\/\/?|#+|"""|''')\s?/, '').replace(/(\*\/|"""|''')\s*$/, '').trim())
+ .filter((l) => l && !/^@\w+/.test(l) && !/^[-=*_]{3,}$/.test(l));
+ // first paragraph only
+ const para = [];
+ for (const l of lines) { if (!l && para.length) break; para.push(l); }
+ let s = para.join(' ').replace(/\s+/g, ' ').trim();
+ if (!s || s.length < 8 || LICENSE.test(s)) return null;
+ const sentence = /^(.{20,220}?[.!?])(\s|$)/.exec(s);
+ s = sentence ? sentence[1] : s.length > 220 ? s.slice(0, 217).replace(/\s+\S*$/, '') + '…' : s;
+ return s;
+}
+
+function pyDocAfter(lines, idx) {
+ // idx: 0-based line of the def/class (or -1 for module). Find the end of the signature, then a string literal.
+ let i = idx;
+ if (idx >= 0) {
+ while (i < lines.length && i < idx + 20 && !/:\s*(#.*)?$/.test(lines[i])) i++;
+ i++;
+ } else i = 0;
+ while (i < lines.length && (!lines[i].trim() || (idx < 0 && /^\s*(#|from __future__)/.test(lines[i])))) i++;
+ const first = lines[i];
+ if (!first) return null;
+ const m = /^\s*[rRbBuUfF]?("""|''')(.*)$/.exec(first);
+ if (!m) return idx < 0 ? hashHeader(lines) : null;
+ const q = m[1];
+ if (m[2].includes(q)) return cleanDoc(m[2].slice(0, m[2].indexOf(q)));
+ const buf = [m[2]];
+ for (let j = i + 1; j < lines.length && j < i + 40; j++) {
+ const k = lines[j].indexOf(q);
+ if (k >= 0) { buf.push(lines[j].slice(0, k)); break; }
+ buf.push(lines[j]);
+ }
+ return cleanDoc(buf.join('\n'));
+}
+
+function hashHeader(lines) {
+ const buf = [];
+ for (const l of lines) {
+ if (/^#!/.test(l)) continue;
+ if (/^\s*#/.test(l)) { buf.push(l); continue; }
+ if (!l.trim() && !buf.length) continue;
+ break;
+ }
+ return cleanDoc(buf.join('\n'));
+}
+
+function commentBefore(lines, idx) {
+ // idx: 0-based line of the declaration. Skip decorators/annotations, then read a /** */ block or // run.
+ let i = idx - 1;
+ while (i >= 0 && /^\s*@/.test(lines[i])) i--;
+ if (i < 0) return null;
+ if (/\*\/\s*$/.test(lines[i])) {
+ const end = i;
+ while (i >= 0 && !/\/\*/.test(lines[i])) i--;
+ return i >= 0 ? cleanDoc(lines.slice(i, end + 1).join('\n')) : null;
+ }
+ const buf = [];
+ while (i >= 0 && /^\s*(\/\/|#(?!!))/.test(lines[i])) buf.unshift(lines[i--]);
+ return buf.length ? cleanDoc(buf.join('\n')) : null;
+}
+
+function headerComment(lines) {
+ let i = 0;
+ while (i < lines.length && (!lines[i].trim() || /^\s*['"]use (client|server|strict)['"];?\s*$/.test(lines[i]) || /^#!/.test(lines[i]))) i++;
+ const l = lines[i] || '';
+ if (/^\s*\/\*/.test(l)) {
+ const start = i;
+ while (i < lines.length && !/\*\//.test(lines[i])) i++;
+ return cleanDoc(lines.slice(start, i + 1).join('\n'));
+ }
+ const buf = [];
+ while (i < lines.length && /^\s*\/\//.test(lines[i])) buf.push(lines[i++]);
+ return cleanDoc(buf.join('\n'));
+}
+
+function addDocs(src, lang, r) {
+ const lines = src.split('\n');
+ r.doc = lang === 'python' ? pyDocAfter(lines, -1) : HASH_LANGS.has(lang) ? hashHeader(lines) : headerComment(lines);
+ for (const s of r.symbols || []) {
+ const d = lang === 'python' ? pyDocAfter(lines, s.line - 1) : commentBefore(lines, s.line - 1);
+ if (d) s.doc = d;
+ }
+ // A route's handler is the first declaration after it (decorator-style frameworks).
+ const syms = (r.symbols || []).slice().sort((a, b) => a.line - b.line);
+ for (const rt of r.routes || []) {
+ if (rt.framework === 'next') { rt.handler = rt.method; continue; }
+ const h = syms.find((s) => s.line >= rt.line && s.line - rt.line <= 12);
+ if (h) { rt.handler = h.name; if (h.doc) rt.doc = h.doc; }
+ else if (lang === 'python') {
+ const m = lines.slice(rt.line, rt.line + 12).findIndex((l) => /^\s*(async\s+)?def\s+\w+/.test(l));
+ if (m >= 0) {
+ rt.handler = /def\s+(\w+)/.exec(lines[rt.line + m])[1];
+ const d = pyDocAfter(lines, rt.line + m);
+ if (d) rt.doc = d;
+ }
+ }
+ }
+}
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
new file mode 100644
index 0000000..47bc988
--- /dev/null
+++ b/skills/floorplan/scripts/lib/health.mjs
@@ -0,0 +1,664 @@
+// Health check: plain-language warnings about the codebase (secrets, endpoints anyone can call,
+// unused files, oversized files), written for people who built an app with AI and don't know its
+// insides. Precision beats recall: a false alarm costs this audience more than a missed one.
+//
+// findIssues(src, file) — called by scan.mjs for every code/config/docs file with its source.
+// Returns raw findings for that file, stored in scan.json files[].issues.
+// Findings never contain a secret's value, only its line, kind and a masked hint.
+// buildHealth(ctx) — called by build.mjs with { graph, scan, arch, root } after the graph is built.
+// Returns { summary: { high, medium, low }, issues: [...] }, stored as graph.health.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { git } from './common.mjs';
+
+const lineIndex = (src) => {
+ const starts = [0];
+ for (let i = 0; i < src.length; i++) if (src.charCodeAt(i) === 10) starts.push(i + 1);
+ return (offset) => {
+ let lo = 0, hi = starts.length - 1;
+ while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= offset) lo = mid; else hi = mid - 1; }
+ return lo + 1;
+ };
+};
+
+/** Shannon entropy in bits per character: random keys score ~4+, words and placeholders ~2-3. */
+function entropy(s) {
+ const counts = new Map();
+ for (const c of s) counts.set(c, (counts.get(c) || 0) + 1);
+ let e = 0;
+ for (const n of counts.values()) { const p = n / s.length; e -= p * Math.log2(p); }
+ return e;
+}
+
+// Files where keys are usually fake: tests, fixtures, examples, docs.
+const TEST_FILE = /(^|\/)(tests?|__tests__|__mocks__|spec|specs|e2e|fixtures?|testdata|mocks?)\/|\.(test|spec|stories)\.[a-z]+$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$|(^|\/)conftest\.py$/i;
+const EXAMPLE_FILE = /(^|\/)(examples?|samples?|docs?|demo)\/|\.(example|sample|template|dist|tmpl)(\.|$)|(^|\/)[^/]*example[^/]*$/i;
+const PLACEHOLDER = /your|xxxx|example|changeme|change[-_]?me|placeholder|replace|dummy|fake|sample|redacted|insert|<[^>]*>|\$\{|\{\{|%\(|\*\*\*|0{8,}|1234567|abcdef|_here\b|-here\b/i;
+
+// ---------- 1. secrets ----------
+
+// Well-known key formats. `sev` defaults to high; `live` formats are flagged even in test files.
+const FORMATS = [
+ { re: /\bAKIA[0-9A-Z]{16}\b/g, what: 'an Amazon Web Services (AWS) access key', svc: 'AWS', live: true },
+ { re: /\b(?:sk|rk)_live_[0-9a-zA-Z]{20,}/g, what: 'a Stripe live secret key', svc: 'Stripe', live: true },
+ { re: /\b(?:sk|rk)_test_[0-9a-zA-Z]{20,}/g, what: 'a Stripe test key', svc: 'Stripe', sev: 'medium' },
+ { re: /\bwhsec_[A-Za-z0-9]{24,}/g, what: 'a Stripe webhook signing secret', svc: 'Stripe' },
+ { re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g, what: 'a GitHub access token', svc: 'GitHub', live: true },
+ { re: /\bgithub_pat_[A-Za-z0-9_]{50,}/g, what: 'a GitHub access token', svc: 'GitHub', live: true },
+ { re: /\bglpat-[A-Za-z0-9_-]{20,}/g, what: 'a GitLab access token', svc: 'GitLab', live: true },
+ { re: /\bxox[abposr]-[A-Za-z0-9-]{10,}/g, what: 'a Slack token', svc: 'Slack', live: true },
+ { re: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]{20,}/g, what: 'a Slack webhook address (anyone with it can post to your Slack)', svc: 'Slack', sev: 'medium' },
+ { re: /\bAIza[0-9A-Za-z_\-]{35}\b/g, what: 'a Google API key', svc: 'Google Cloud', sev: 'medium', skipIf: /firebase|authDomain|messagingSenderId/i },
+ { re: /\bGOCSPX-[A-Za-z0-9_\-]{20,}/g, what: 'a Google sign-in client secret', svc: 'Google Cloud' },
+ { re: /\bsk-ant-[a-z]+\d*-[A-Za-z0-9_\-]{40,}/g, what: 'an Anthropic (Claude) API key', svc: 'Anthropic', live: true },
+ { re: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_\-]{16,}T3BlbkFJ[A-Za-z0-9_\-]{16,}/g, what: 'an OpenAI API key', svc: 'OpenAI', live: true },
+ { re: /\bsk-(?:proj|svcacct|admin)-[A-Za-z0-9_\-]{40,}/g, what: 'an OpenAI API key', svc: 'OpenAI', live: true },
+ { re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/g, what: 'a private key', svc: null, whole: true },
+ { re: /\bSG\.[A-Za-z0-9_\-]{22}\.[A-Za-z0-9_\-]{43}\b/g, what: 'a SendGrid email API key', svc: 'SendGrid', live: true },
+ { re: /\bsq0csp-[0-9A-Za-z_\-]{40,}/g, what: 'a Square app secret', svc: 'Square', live: true },
+ { re: /\bsq0atp-[0-9A-Za-z_\-]{20,}/g, what: 'a Square access token', svc: 'Square', live: true },
+ { re: /\bEAAA[A-Za-z0-9_\-]{60,}/g, what: 'a Square access token', svc: 'Square', live: true },
+ { re: /\bshp(?:at|ss|ca|pa)_[a-fA-F0-9]{32}\b/g, what: 'a Shopify access token', svc: 'Shopify', live: true },
+ { re: /\bhf_[A-Za-z0-9]{30,}\b/g, what: 'a Hugging Face token', svc: 'Hugging Face', live: true },
+ { re: /\bnpm_[A-Za-z0-9]{36}\b/g, what: 'an npm publishing token', svc: 'npm', live: true },
+ { re: /\bsbp_[a-f0-9]{40}\b/g, what: 'a Supabase account token', svc: 'Supabase', live: true },
+ { re: /\bsb_secret_[A-Za-z0-9_\-]{20,}/g, what: 'a Supabase secret key', svc: 'Supabase', live: true },
+ { re: /\b\d{8,10}:AA[0-9A-Za-z_\-]{33}\b/g, what: 'a Telegram bot token', svc: 'Telegram', live: true },
+ { re: /\bdop_v1_[a-f0-9]{64}\b/g, what: 'a DigitalOcean token', svc: 'DigitalOcean', live: true },
+ { re: /\bpat[A-Za-z0-9]{14}\.[a-f0-9]{64}\b/g, what: 'an Airtable token', svc: 'Airtable', live: true },
+];
+const JWT = /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{20,}/g;
+const DB_URL = /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|rediss?|amqps?)(?:\+\w+)?:\/\/([^:\s\/'"@]+):([^@\s'"]+)@([^\/\s'":?,]+)/g;
+const LOCAL_HOST = /^(localhost|127\.0\.0\.1|0\.0\.0\.0|db|postgres|mysql|redis|mongo|database|host\.docker\.internal)$/i;
+
+// Names that hold secrets (after camelCase → snake_case). Public-by-design keys are excluded below.
+const SECRET_NAME = /(?:^|[_.-])(api_?key|apikey|secret(?:_?key)?|client_?secret|app_?secret|token|access_?token|refresh_?token|auth_?token|authtoken|bearer_?token|passw(?:or)?d|passwd|pwd|private_?key|secret_?access_?key|signing_?(?:key|secret)|signature_?key|webhook_?secret|encryption_?key|auth(?:orization)?_?key|master_?key|credentials?)$/i;
+const PUBLIC_NAME = /(^|_)(public|publishable|anon|site_?key|example|sample|test|dummy|fake|mock|placeholder|default|field|label|header|name|type|url|uri|endpoint|path|file|env|var|prefix|length|len|min|max|regex|pattern|format|expires?|ttl)(_|$)|^(next_public|vite|react_app|expo_public|nuxt_public|gatsby)_/i;
+const ENV_LOOKUP = /os\.environ|os\.getenv|getenv\(|process\.env|import\.meta\.env|ENV\[|ENV\.fetch|System\.getenv|Deno\.env|secrets\.|config\(\s*['"]|env\(\s*['"]|\$\{\{/;
+const PASSWORD_NAME = /pass|pwd/i;
+const CONFIG_LANGS = new Set(['yaml', 'yml', 'ini', 'cfg', 'conf', 'properties', 'env', 'toml']);
+
+const snake = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+const kindFromName = (name) => {
+ const n = snake(name);
+ if (/pass|pwd/.test(n)) return 'a password';
+ if (/private_?key/.test(n)) return 'a private key';
+ if (/token/.test(n)) return 'an access token';
+ if (/api_?key|apikey/.test(n)) return 'an API key';
+ if (/credential/.test(n)) return 'login credentials';
+ return 'a secret key';
+};
+const mask = (v, password) => password || v.length < 12 ? `${v.length} characters` : `starts “${v.slice(0, 4)}…”, ${v.length} characters`;
+
+function valueLooksReal(v, name) {
+ if (/\s/.test(v) || PLACEHOLDER.test(v)) return false;
+ if (/^(none|null|nil|undefined|true|false|string|number|text|required|optional|bearer|basic|secret|token|password|test|dev|development|local|admin)$/i.test(v)) return false;
+ if (/^[A-Z][A-Z0-9_]+$/.test(v)) return false; // the NAME of an env var
+ if (/^[a-z_]+(\.[a-z_]+)+$/i.test(v)) return false; // dotted identifier / key path
+ if (/^(\.{0,2}\/|~\/|https?:\/\/|[a-z]:\\)/i.test(v)) return false; // paths and URLs
+ if (/\.(json|pem|key|txt|ya?ml|env|crt|p12)$/i.test(v)) return false; // a file name, not the key
+ if (/^x-[\w-]+$/i.test(v) || /^(application|text)\//.test(v)) return false;
+ if (/^(.)\1+$/.test(v)) return false;
+ if (/^(pass(word)?|secret|admin|test|user|changeit|letmein|qwerty|demo|guest|root|welcome)[\d!@#$._-]*$/i.test(v)) return false;
+ if (PASSWORD_NAME.test(name)) return v.length >= 6 && !/^[a-z]+$/.test(v);
+ return v.length >= 16 && entropy(v) >= 3.2 && /\d/.test(v) && /[a-zA-Z]/.test(v);
+}
+
+/** 1-based line numbers inside docstrings or block comments (examples there aren't real config). */
+function docLines(src, lang) {
+ const set = new Set();
+ if (!['python', 'typescript', 'javascript', 'java', 'kotlin', 'go', 'csharp', 'php', 'rust', 'swift'].includes(lang)) return set;
+ const re = lang === 'python' ? /("""|''')[\s\S]*?\1/g : /\/\*[\s\S]*?\*\//g;
+ const at = lineIndex(src);
+ for (const m of src.matchAll(re)) { const a = at(m.index), b = at(m.index + m[0].length); for (let l = a; l <= b; l++) set.add(l); }
+ return set;
+}
+
+function findSecrets(src, f, out) {
+ const at = lineIndex(src);
+ const isTest = TEST_FILE.test(f.path) || EXAMPLE_FILE.test(f.path);
+ const seenLines = new Set();
+ const add = (line, rec) => { if (seenLines.has(line)) return; seenLines.add(line); out.push({ k: 'secret', line, ...rec }); };
+
+ for (const fm of FORMATS) {
+ if (fm.skipIf?.test(src)) continue;
+ for (const m of src.matchAll(fm.re)) {
+ const v = m[0];
+ if (isTest && (!fm.live || fm.whole)) continue;
+ if (!fm.whole && (/EXAMPLE|xxxx|XXXX|0{10,}/.test(v) || entropy(v) < 3)) continue;
+ add(at(m.index), { what: fm.what, svc: fm.svc, sev: fm.sev || 'high', hint: fm.whole ? 'private key block' : mask(v) });
+ }
+ }
+ if (!isTest) {
+ for (const m of src.matchAll(JWT)) {
+ let payload = null;
+ try { payload = JSON.parse(Buffer.from(m[0].split('.')[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')); } catch { continue; }
+ if (payload?.role !== 'service_role') continue; // "anon" keys are public by design
+ add(at(m.index), { what: 'a Supabase service-role key (full access to your database, skipping all security rules)', svc: 'Supabase', sev: 'high', hint: mask(m[0]) });
+ }
+ for (const m of src.matchAll(DB_URL)) {
+ const [, user, pw, host] = m;
+ if (LOCAL_HOST.test(host) || PLACEHOLDER.test(pw) || /^[:$%{<]/.test(pw) || pw.length < 4 || /^(password|pass|postgres|root|secret|admin|user)$/i.test(pw)) continue;
+ add(at(m.index), { what: 'a database password inside a connection address', svc: 'your database', sev: 'high', hint: mask(pw, true) });
+ }
+ }
+ if (isTest || f.category === 'docs') return;
+
+ // Assignments: api_key = "…", "password": "…", PASSWORD=… (config files may leave values unquoted).
+ const lines = src.split('\n');
+ const inDoc = docLines(src, f.lang);
+ // CI / docker-compose database containers get throwaway passwords
+ const throwawayDb = /(^|\/)\.github\/|(^|\/)(docker-)?compose[\w.-]*\.ya?ml$/i.test(f.path);
+ const quoted = /(["']?)([A-Za-z_][\w.-]*)\1\s*(?::=|=>|=|:)\s*(?:[rbuRBU]{1,2})?(["'`])([^"'`\n]{6,200})\3/g;
+ const unquoted = /^\s*(?:export\s+)?([A-Za-z_][\w.-]*)\s*[:=]\s*([^\s#'"]{6,200})\s*(?:#.*)?$/;
+ lines.forEach((text, i) => {
+ if (text.length > 400 || ENV_LOOKUP.test(text) || inDoc.has(i + 1) || /^\s*(#|\/\/|\*|\/\*|<!--)/.test(text)) return;
+ const pairs = [...text.matchAll(quoted)].map((m) => [m[2], m[4]]);
+ if (!pairs.length && (f.category === 'config' && CONFIG_LANGS.has(f.lang))) { const u = unquoted.exec(text); if (u) pairs.push([u[1], u[2]]); }
+ for (const [name, value] of pairs) {
+ const n = snake(name.split('.').pop());
+ if (!SECRET_NAME.test(n) || PUBLIC_NAME.test(n) || !valueLooksReal(value, n)) continue;
+ if (throwawayDb && /^(postgres|mysql|mariadb|mongo(_initdb_root)?|redis|pg|rabbitmq_default|db|database)_(root_)?(password|pass|pwd)$/.test(n)) continue;
+ add(i + 1, { what: kindFromName(name), name: name.split('.').pop(), sev: 'high', hint: mask(value, PASSWORD_NAME.test(n)), generic: true });
+ }
+ });
+}
+
+// ---------- 2. who may call each endpoint ----------
+
+// Decorators / middleware / dependencies whose names say "check who is calling".
+const GUARD_NAME = /(^|_)(login|auth|authenticated|authorized?|jwt|token|permission|permissions|perm|role|roles|staff|admin|superuser|owner|scope|scopes|session|api_?key|signature|signed|hmac|device|member|user)(_|$)|_required$|^requires?_|^ensure_|^verify_|^check_(auth|token|user|session|permission|role|api)|protect|^is_?authenticated|^is_?admin/i;
+const NOT_GUARD = /^(route|get|post|put|patch|delete|cached?|limit|limiter|rate_?limit\w*|cross_origin|wraps|staticmethod|classmethod|property|retry|timed|log\w*|swag_from|validate\w*|expects|marshal\w*|doc|json_required|fields?_required|params?_required|body_required|transaction\w*|csrf\w*|exempt)$/i;
+const isGuardName = (name) => !!name && !NOT_GUARD.test(name) && GUARD_NAME.test(snake(name));
+// A handler body that inspects the caller itself.
+const INLINE_CHECK = /request\.headers(?:\.get)?\(?\s*\[?\s*['"](authorization|x-api-key|x-[\w-]*(token|key|secret|signature)[\w-]*)['"]|req\.headers(?:\.|\[\s*['"])(authorization|x-api-key)|\b(verify|check|require|validate|authenticate|authorize)_?\w*(auth|token|session|user|key|signature|webhook|hmac|jwt|device|staff|admin|permission|role|request|caller)\w*\s*\(|\bcurrent_user\b|get_jwt_identity|verify_jwt_in_request|compare_digest|abort\(\s*40[13]\b|,\s*40[13]\s*\)?\s*$|status(?:Code)?\s*[:=(]\s*40[13]\b|\.status\(\s*40[13]\s*\)|req\.user\b|req\.session\.user|req\.auth\b|jwt\.verify|jwtVerify|getServerSession|auth\(\)|currentUser\(|getAuth\(|auth\.getUser|getSession\(|verifyIdToken|getToken\(/m;
+const SIGNATURE_CHECK = /hmac|signature|verify_?webhook|construct_?event|x-hub-signature|compare_digest|svix|webhooks?\.verify|jwt\.decode|oidc|id_token|authenticated|verify_\w*(token|request|push)/i;
+const NEXT_GUARD = /getServerSession|\bauth\(\)|currentUser\(|getAuth\(|auth\.getUser|supabase\.auth\.get(User|Session)|getSession\(|verifyIdToken|jwt\.verify|jwtVerify|getToken\(|clerkClient|requireAuth|requireUser|withAuth|validateRequest|headers\(\)\.get\(\s*['"]authorization|status:\s*40[13]\b/;
+const NEXT_MIDDLEWARE_GUARD = /getToken|withAuth|clerkMiddleware|authMiddleware|auth\(|supabase|getSession|jwtVerify|jwt\.verify|cookies\.get\([^)]*(session|token|auth)|redirect\([^)]*login/i;
+
+function blockAfter(lines, defIdx) {
+ // A Python def's body: every line after it that's more indented, up to 120 lines.
+ const ind = /^\s*/.exec(lines[defIdx])[0].length;
+ let end = defIdx + 1;
+ while (end < lines.length && end < defIdx + 120 && (!lines[end].trim() || /^\s*/.exec(lines[end])[0].length > ind || /^\s*[)\]]/.test(lines[end]))) end++;
+ return lines.slice(defIdx, end).join('\n');
+}
+
+function pyRoutes(src, f, out) {
+ const lines = src.split('\n');
+ // Blueprint / app-wide before_request hooks and router-level dependencies that check the caller.
+ const guardedVars = new Map();
+ for (const m of src.matchAll(/^@(\w+)\.before_(?:app_)?request\s*\n(?:@.*\n)*\s*def\s+(\w+)/gm)) {
+ const defIdx = src.slice(0, m.index + m[0].length).split('\n').length - 1;
+ const body = blockAfter(lines, defIdx);
+ if (!/\b40[13]\b|Unauthorized|Forbidden|verify_jwt_in_request|login_required|is_authenticated|current_user/.test(body)) continue;
+ guardedVars.set(m[1], m[2]);
+ if (m[1] === 'app') out.push({ k: 'global-guard', framework: 'flask', name: m[2], line: defIdx + 1 });
+ }
+ for (const m of src.matchAll(/^\s*(\w+)\s*=\s*(?:\w+\.)?APIRouter\(([^)]*(?:\([^)]*\)[^)]*)*)\)/gm)) {
+ const dep = /dependencies\s*=\s*\[[^\]]*Depends\(\s*([\w.]+)/.exec(m[2]);
+ if (dep && isGuardName(dep[1].split('.').pop())) guardedVars.set(m[1], dep[1]);
+ }
+ // Decorators defined here: auth-named ones, and project wrappers like `@endpoint(write=True)` whose
+ // body applies an auth decorator itself. Repeat once so a wrapper of a wrapper counts too.
+ const localGuards = new Set();
+ const defs = [...src.matchAll(/^def\s+(\w+)\s*\(/gm)].map((m) => { const idx = src.slice(0, m.index).split('\n').length - 1; return { name: m[1], line: idx + 1, body: blockAfter(lines, idx) }; });
+ const decoratorish = (body) => /wraps|decorat|def\s+\w+\(\s*\*args|return\s+\w+\s*$/m.test(body);
+ for (let pass = 0; pass < 2; pass++) for (const d of defs) {
+ if (localGuards.has(d.name) || !decoratorish(d.body)) continue;
+ const applied = [...d.body.matchAll(/^\s*@([\w.]+)/gm)].map((m) => m[1].split('.').pop());
+ const wraps = applied.some((a) => isGuardName(a) || localGuards.has(a));
+ if (isGuardName(d.name) || wraps) { localGuards.add(d.name); out.push({ k: 'guard-def', name: d.name, line: d.line, ...(wraps && !isGuardName(d.name) ? { wrapper: true } : {}) }); }
+ }
+
+ for (const r of f.routes || []) {
+ if (r.framework === 'django') continue;
+ const i0 = r.line - 1;
+ // decorators above the route decorator (wrong place in Flask/FastAPI: the route registers the unwrapped function)
+ const above = [];
+ for (let i = i0 - 1; i >= 0 && /^\s*@/.test(lines[i]); i--) above.push(/^\s*@([\w.]+)/.exec(lines[i])[1].split('.').pop());
+ // decorators below it, up to the def
+ const below = [];
+ let defIdx = -1;
+ for (let i = i0 + 1; i < lines.length && i < i0 + 30; i++) {
+ if (/^\s*(async\s+)?def\s/.test(lines[i])) { defIdx = i; break; }
+ const d = /^\s*@([\w.]+)/.exec(lines[i]);
+ if (d) below.push(d[1].split('.').pop());
+ }
+ const decoText = lines.slice(i0, defIdx > 0 ? defIdx : i0 + 1).join('\n');
+ const sig = defIdx > 0 ? lines.slice(defIdx, defIdx + 15).join('\n').split(/\)\s*(->[^:]*)?:\s*$/m)[0] : '';
+ const body = defIdx > 0 ? blockAfter(lines, defIdx) : '';
+ const rec = { k: 'route', line: r.line, method: r.method };
+ const deco = below.find((d) => (isGuardName(d) || localGuards.has(d)) && !/^(route|get|post|put|patch|delete)$/.test(d));
+ const dep = /Depends\(\s*([\w.]+)|Security\(\s*([\w.]+)/g;
+ const deps = [...(decoText + '\n' + sig).matchAll(dep)].map((m) => (m[1] || m[2]).split('.').pop());
+ if (deco) Object.assign(rec, { guard: deco, via: 'decorator' });
+ else if (guardedVars.has(r.var)) Object.assign(rec, { guard: guardedVars.get(r.var), via: 'blueprint' });
+ else if (deps.some(isGuardName)) Object.assign(rec, { guard: deps.find(isGuardName), via: 'dependency' });
+ else if (INLINE_CHECK.test(body)) Object.assign(rec, { via: 'inline' });
+ else {
+ const misplaced = above.find((d) => isGuardName(d) && !/^(route|get|post|put|patch|delete)$/.test(d));
+ if (misplaced) rec.misplaced = misplaced;
+ // other decorators may be auth wrappers defined in another file; build resolves them
+ const other = below.filter((d) => !/^(route|get|post|put|patch|delete|api_route|websocket)$/.test(d));
+ if (other.length) rec.decos = other;
+ }
+ if (SIGNATURE_CHECK.test(body)) rec.signed = true;
+ if (defIdx > 0) rec.fn = /def\s+(\w+)/.exec(lines[defIdx])[1];
+ out.push(rec);
+ }
+}
+
+function jsRoutes(src, f, out) {
+ const routes = f.routes || [];
+ if (!routes.length && !/\.use\(/.test(src) && !/(^|\/)middleware\.(t|j)s$/.test(f.path)) return;
+ const lines = src.split('\n');
+ // Next.js middleware.ts protecting the app
+ if (/(^|\/)(src\/)?middleware\.(t|j)s$/.test(f.path) && NEXT_MIDDLEWARE_GUARD.test(src)) {
+ const matcher = /matcher\s*:\s*([^\n]+)/.exec(src)?.[1] || '';
+ if (!matcher || /api|\(\?!/.test(matcher)) out.push({ k: 'global-guard', framework: 'next', line: 1 });
+ }
+ // app.use(auth) / router.use(requireAuth) without a path guards everything registered after it
+ const uses = [];
+ for (const m of src.matchAll(/\b(\w+)\.use\(\s*([^'"`)][^)]*)\)/g)) {
+ const names = m[2].match(/[A-Za-z_$][\w$]*/g) || [];
+ if (names.some(isGuardName)) uses.push({ v: m[1], line: src.slice(0, m.index).split('\n').length, name: names.find(isGuardName) });
+ }
+ for (const u of uses) if (u.v === 'app' || u.v === 'server') out.push({ k: 'global-guard', framework: 'express', name: u.name, line: u.line });
+
+ routes.forEach((r, idx) => {
+ const rec = { k: 'route', line: r.line, method: r.method };
+ if (r.framework === 'next') {
+ if (NEXT_GUARD.test(src)) rec.via = 'inline';
+ if (SIGNATURE_CHECK.test(src)) rec.signed = true;
+ rec.fn = r.method;
+ out.push(rec);
+ return;
+ }
+ // the route call's own arguments: router.post('/x', requireAuth, async (req, res) => …)
+ const head = lines.slice(r.line - 1, r.line + 4).join('\n');
+ const args = (/\.\w+\(\s*["'`][^"'`]*["'`]\s*,([\s\S]*?)(?:async\s*)?(?:\(\s*req\b|function\b|\breq\s*=>|\(\s*\{|\(\s*c\s*\)|\(\s*ctx\b)/.exec(head)?.[1] || '');
+ const mw = (args.match(/[A-Za-z_$][\w$.]*/g) || []).map((x) => x.split('.').pop()).find(isGuardName);
+ const next = routes[idx + 1]?.line || r.line + 60;
+ const body = lines.slice(r.line - 1, Math.min(next - 1, r.line + 60)).join('\n');
+ const prior = uses.find((u) => u.v === r.var && u.line < r.line);
+ if (mw) Object.assign(rec, { guard: mw, via: 'middleware' });
+ else if (prior) Object.assign(rec, { guard: prior.name, via: 'router' });
+ else if (INLINE_CHECK.test(body)) rec.via = 'inline';
+ if (SIGNATURE_CHECK.test(body)) rec.signed = true;
+ out.push(rec);
+ });
+}
+
+// ---------- per-file entry point ----------
+
+export function findIssues(src, f) {
+ const out = [];
+ findSecrets(src, f, out);
+ if (f.category !== 'code') return out;
+ if (f.lang === 'python') pyRoutes(src, f, out);
+ else if (['typescript', 'javascript'].includes(f.lang)) jsRoutes(src, f, out);
+ // run directly or registered by name (so "nothing imports it" doesn't mean unused)
+ if (/^#!|if\s+__name__\s*==\s*['"]__main__['"]|@(?:\w+\.)*(?:task|shared_task|command|group|receiver|scheduled_job|on_event|listener|hookimpl|periodic_task|cli\.command)\b|require\.main\s*===\s*module|import\.meta\.main/m.test(src)) out.push({ k: 'runnable' });
+ // a frontend calling a fixed localhost address (breaks once deployed)
+ // (only in files with no environment / hostname switching, where it can't be a dev-only fallback)
+ if (['typescript', 'javascript', 'vue', 'svelte'].includes(f.lang) && !TEST_FILE.test(f.path) && !/process\.env|import\.meta\.env|NODE_ENV|location\.(hostname|host|origin)|isDev|__DEV__/.test(src)) {
+ src.split('\n').forEach((t, i) => {
+ if (/["'`]https?:\/\/(localhost|127\.0\.0\.1):\d+/.test(t) && !/\?\?|\|\||local|dev|fallback|default|^\s*(\/\/|\*)/i.test(t.replace(/https?:\/\/(localhost|127\.0\.0\.1)/g, ''))) out.push({ k: 'localhost', line: i + 1 });
+ });
+ }
+ return out;
+}
+
+// ======================= build: turn findings into issues =======================
+
+const SEV_ORDER = { high: 0, medium: 1, low: 2 };
+const PUBLIC_PATH = /(^|\/)(health|healthz|healthcheck|ping|status|ready|readiness|live|liveness|version|metrics|robots\.txt|sitemap[\w.]*|favicon[\w.]*|\.well-known|login|logout|signin|pair|sign-in|signout|signup|sign-up|register|forgot[\w-]*|reset[\w-]*|verify[\w-]*|oauth\w*|callback|auth|token|refresh|static|assets|public|openapi\.json|docs|swagger[\w.]*|i|images?)(\/|$)/i;
+const WEBHOOK_PATH = /webhook|\/hooks?\//i;
+// endpoints under a webhook URL that manage the webhooks (create, list, test…) rather than receive them
+const WEBHOOK_ADMIN = /\/(manage|admin|setup|settings|config|list|create|register|delete|test[\w-]*)(\/|$)/i;
+const NOT_USED_KINDS = new Set(['test', 'script', 'infra', 'config', 'worker', 'external']);
+const SPECIAL_FILE = /(^|\/)(index|main|app|server|cli|manage|wsgi|asgi|__init__|__main__|conftest|setup|config|settings|env|middleware|instrumentation|layout|page|route|loading|error|not-found|template|default|global-error|sitemap|robots|manifest|opengraph-image|twitter-image|icon|apple-icon|_app|_document|_error|404|500|models|admin|apps|views|urls|signals|tasks|forms|serializers|celery|gunicorn\.conf|vite-env\.d|worker|sw|service-worker)\.[a-z]+$|\.d\.ts$|\.config\.[a-z]+$|\.stories\.|(^|\/)(pages|migrations|alembic|versions|scripts|bin|tools|seeds?|fixtures?|examples?|docs?|public|static|templates|\.github|e2e|cypress|playwright)\//i;
+const USED_LANGS = new Set(['typescript', 'javascript', 'python', 'vue', 'svelte', 'astro']);
+const plural = (n, w, ws) => `${n} ${n === 1 ? w : ws || w + 's'}`;
+
+export function buildHealth({ graph, scan, arch, root }) {
+ const issues = [];
+ const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+ const fileByPath = new Map(graph.files.map((f) => [f.p, f]));
+ const scanByPath = new Map(scan.files.map((f) => [f.path, f]));
+ const lineage = (id) => { const out = []; let n = nodeById.get(id); while (n) { out.push(n); n = n.parent ? nodeById.get(n.parent) : null; } return out; };
+ const kinds = (id) => lineage(id).map((n) => n.kind);
+ const isFrontend = (p) => { const f = fileByPath.get(p); return !!f && kinds(f.n).includes('ui'); };
+ const nameOf = (p) => fileByPath.get(p)?.name || p.split('/').pop();
+ const label = (id) => nodeById.get(id)?.label || id;
+ // Files outside the map (config, .env) point at the module that owns their folder instead.
+ const dirOwner = new Map();
+ for (const f of graph.files) { let d = f.p; while (d.includes('/')) { d = d.slice(0, d.lastIndexOf('/')); if (!dirOwner.has(d)) dirOwner.set(d, new Map()); const m = dirOwner.get(d); m.set(f.n, (m.get(f.n) || 0) + 1); } }
+ const itemFor = (p) => {
+ if (fileByPath.has(p)) return 'f:' + p;
+ let d = p;
+ while (d.includes('/')) {
+ d = d.slice(0, d.lastIndexOf('/'));
+ const m = dirOwner.get(d);
+ const top = m && [...m.entries()].filter(([n]) => n !== 'unassigned').sort((a, b) => b[1] - a[1])[0];
+ if (top) return 'n:' + top[0];
+ }
+ return null;
+ };
+ const findings = (p) => scanByPath.get(p)?.issues || [];
+
+ // ---------- secrets in code and config ----------
+ const secretFiles = [];
+ for (const f of scan.files) {
+ const s = findings(f.path).filter((x) => x.k === 'secret');
+ if (s.length) secretFiles.push({ path: f.path, list: s });
+ }
+ // credential files (service-account JSON, .pem keys) that the scanner doesn't read as config
+ for (const f of scan.files) {
+ const base = f.path.split('/').pop();
+ if (TEST_FILE.test(f.path) || EXAMPLE_FILE.test(f.path) || /\.pub$/.test(base)) continue;
+ if (!/\.(pem|key|p12|pfx|jks|keystore)$|^id_(rsa|dsa|ecdsa|ed25519)$|service[-_]?account.*\.json$|^credentials?\.json$|firebase-adminsdk.*\.json$|^client_secret.*\.json$|-key\.json$/i.test(base)) continue;
+ let head = '';
+ try { head = readHead(path.join(root, f.path), 65536); } catch { continue; }
+ if (/PRIVATE KEY|"private_key"\s*:\s*"-----|"client_secret"\s*:\s*"[^"]{8,}/.test(head) || /\.(p12|pfx|jks|keystore)$/i.test(base)) secretFiles.push({ path: f.path, list: [{ k: 'secret', line: 1, what: 'a credentials file (a private key that logs in as your app)', sev: 'high', hint: 'whole file' }], file: true });
+ }
+ const secretIssue = (group) => {
+ const locations = [], notes = {}, items = [];
+ const kinds = new Set(), svcs = new Set();
+ let frontend = false;
+ for (const { path: p, list, file } of group) {
+ list.sort((a, b) => a.line - b.line);
+ const it = itemFor(p);
+ if (it && !items.includes(it)) items.push(it);
+ for (const s of list) {
+ locations.push({ file: p, line: s.line });
+ kinds.add(s.what);
+ if (s.svc) svcs.add(s.svc);
+ }
+ if (isFrontend(p)) frontend = true;
+ if (it) notes[it] = (notes[it] ? notes[it] + ' · ' : '') + list.slice(0, 4).map((s) => `${file ? p.split('/').pop() : `line ${s.line}`}: ${s.name ? `${s.name}, ` : ''}${s.what.replace(/ \(.*\)$/, '')} (${s.hint})`).join(' · ') + (list.length > 4 ? ` · +${list.length - 4} more` : '');
+ }
+ const n = locations.length;
+ const sev = group.some((g) => g.list.some((s) => s.sev === 'high')) ? 'high' : 'medium';
+ const one = group.length === 1 ? group[0].path : null;
+ const kindText = kinds.size === 1 ? [...kinds][0].replace(/ \(.*\)$/, '') : 'passwords or keys';
+ return {
+ id: 'secret:' + (one || group.map((g) => g.path).join('|')),
+ kind: 'secret', severity: sev,
+ title: n === 1 ? `A secret key is written into ${one ? one.split('/').pop() : `${group.length} more files`}` : `${n} passwords or keys are written into ${one ? one.split('/').pop() : `${group.length} more files`}`,
+ detail: `${one ? `${nameOf(one)} (${one})` : plural(group.length, 'file')} contains ${n === 1 ? kindText : `${n} secrets (${kindText})`}. Anyone who can see the code can use ${n === 1 ? 'it' : 'them'} to get into ${svcs.size ? [...svcs].slice(0, 4).join(', ') : 'the services they unlock'} as you${frontend ? ', and this code is sent to every visitor’s browser' : ''}. Treat ${n === 1 ? 'it' : 'them'} as leaked: move ${n === 1 ? 'it' : 'them'} out of the code and replace ${n === 1 ? 'it with a new one' : 'them with new ones'}.`,
+ items, notes, locations,
+ fix: [
+ `Security fix: hard-coded secrets. Do not print, echo or repeat any secret value in your replies, commits or logs.`,
+ ``,
+ `These lines contain ${n === 1 ? 'a secret' : 'secrets'} written directly in the code:`,
+ ...group.flatMap(({ path: p, list, file }) => list.map((s) => `- ${p}${file ? ' (the whole file)' : `:${s.line}`}: ${s.name ? `${s.name} — ` : ''}${s.what.replace(/ \(.*\)$/, '')}`)),
+ ``,
+ `For each one:`,
+ `1. Replace the literal with an environment variable lookup (${group.some((g) => /\.py$/.test(g.path)) ? `os.environ["NAME"] in Python` : ''}${group.some((g) => /\.py$/.test(g.path)) && group.some((g) => /\.[jt]sx?$/.test(g.path)) ? ', ' : ''}${group.some((g) => /\.[jt]sx?$/.test(g.path)) ? 'process.env.NAME in JavaScript/TypeScript' : ''}${!group.some((g) => /\.(py|[jt]sx?)$/.test(g.path)) ? 'or a secret manager reference' : ''}), using a clear variable name. If the app can't run without it, fail with a clear error when it is missing instead of falling back to a hard-coded value.`,
+ `2. Add each variable name (with an empty value, never the real one) to .env.example, and make sure .env is listed in .gitignore.`,
+ frontend ? `3. This is frontend code that ships to the browser. Move the call that needs the secret to a server-side route or function so the key never reaches visitors.` : `3. Update any deployment config (Docker, Cloud Run, Vercel, etc.) so the variable is set in production.`,
+ group.some((g) => g.file) ? `4. Remove the credentials file from the repository (git rm --cached), add its name to .gitignore, and load it from a path given by an environment variable.` : `4. Run the app or its tests to confirm it still starts with the variables set.`,
+ ``,
+ `Then give me a short checklist (without the values) of which services these keys belong to, so I can rotate each one: create a new key in that service's dashboard, put it in my environment, and revoke the old one. Because the old values are in git history, assume they are compromised.`,
+ ].join('\n'),
+ };
+ };
+ secretFiles.sort((a, b) => b.list.length - a.list.length);
+ const MAX_SECRET_ISSUES = 8;
+ secretFiles.slice(0, MAX_SECRET_ISSUES).forEach((g) => issues.push(secretIssue([g])));
+ if (secretFiles.length > MAX_SECRET_ISSUES) issues.push(secretIssue(secretFiles.slice(MAX_SECRET_ISSUES)));
+
+ // ---------- .env files that are (or will be) committed ----------
+ for (const f of scan.files) {
+ const base = f.path.split('/').pop();
+ if (!/^\.env(\.[\w.-]+)?$/i.test(base) || /example|sample|template|dist|defaults?|schema|test/i.test(base)) continue;
+ let src = '';
+ try { src = readHead(path.join(root, f.path), 262144); } catch { continue; }
+ const secretVars = [];
+ src.split('\n').forEach((t, i) => {
+ const m = /^\s*(?:export\s+)?([A-Za-z_][\w.]*)\s*=\s*["']?([^"'#\s]*)/.exec(t);
+ if (!m || !m[2]) return;
+ const n = snake(m[1]);
+ const known = FORMATS.some((fm) => { fm.re.lastIndex = 0; const hit = fm.re.test(m[2]); fm.re.lastIndex = 0; return hit; });
+ if (known || (SECRET_NAME.test(n) && !PUBLIC_NAME.test(n) && valueLooksReal(m[2], n)) || (/url|uri|dsn/i.test(n) && /:\/\/[^:\s\/]+:[^@\s]+@/.test(m[2]))) secretVars.push({ name: m[1], line: i + 1 });
+ });
+ if (!secretVars.length) continue;
+ const repoAbs = f.repo ? path.join(root, f.repo) : root;
+ const relInRepo = f.repo ? f.path.slice(f.repo.length + 1) : f.path;
+ const tracked = !!git(repoAbs, ['ls-files', '--', relInRepo]);
+ const it = itemFor(f.path);
+ issues.push({
+ id: 'env-file:' + f.path, kind: 'env-file', severity: tracked ? 'high' : 'medium',
+ title: tracked ? 'Your private settings file is saved in git' : 'Your private settings file isn’t hidden from git',
+ detail: tracked
+ ? `${f.path} holds ${plural(secretVars.length, 'password or key', 'passwords and keys')} and is committed, so everyone with access to the code (and its history) can read them. This file is meant to stay on your computer only.`
+ : `${f.path} holds ${plural(secretVars.length, 'password or key', 'passwords and keys')} and isn’t listed in .gitignore, so the next commit will upload it with your code.`,
+ items: it ? [it] : [], notes: it ? { [it]: `${f.path}: ${secretVars.slice(0, 6).map((v) => v.name).join(', ')}${secretVars.length > 6 ? '…' : ''}` } : {},
+ locations: secretVars.map((v) => ({ file: f.path, line: v.line })),
+ fix: [
+ `Security fix: ${f.path} contains secrets and ${tracked ? 'is committed to git' : 'is not ignored by git'}. Do not print or repeat any value from it.`,
+ ``,
+ `1. Add ${base} (and .env*.local) to ${f.repo ? f.repo + '/' : ''}.gitignore, keeping .env.example tracked.`,
+ tracked ? `2. Stop tracking it without deleting my local copy: git rm --cached "${relInRepo}" (run inside ${f.repo || 'the repo'}), then commit.` : `2. Confirm with git status that the file no longer shows up as a new file.`,
+ `3. Create or update .env.example next to it with the same variable names and empty values: ${secretVars.map((v) => v.name).join(', ')}.`,
+ tracked ? `4. Give me a checklist (names only, no values) of which keys I need to rotate in each service's dashboard, since they are in git history. Mention that removing them from history needs a tool like git filter-repo, and ask before doing that.` : `4. Tell me which deployment settings need these variables.`,
+ ].join('\n'),
+ });
+ }
+
+ // ---------- endpoints anyone can call ----------
+ const routeFinding = new Map(); // `${file}|${line}|${method}` -> finding
+ const globalGuards = new Map(); // repo -> [{framework, name, file}]
+ const guardDefs = new Map(); // name -> [{ file, wrapper }]
+ for (const f of scan.files) for (const x of findings(f.path)) {
+ if (x.k === 'route') routeFinding.set(`${f.path}|${x.line}|${x.method}`, x);
+ // app-wide checks count only from the app itself, not from scripts or tests that spin up their own
+ if (x.k === 'global-guard' && !TEST_FILE.test(f.path) && !/(^|\/)(scripts?|tools|bin|examples?)\//.test(f.path) && !(fileByPath.has(f.path) && kinds(fileByPath.get(f.path).n).some((k) => NOT_USED_KINDS.has(k)))) { const k = f.repo ?? ''; if (!globalGuards.has(k)) globalGuards.set(k, []); globalGuards.get(k).push({ ...x, file: f.path }); }
+ if (x.k === 'guard-def' && !TEST_FILE.test(f.path)) { if (!guardDefs.has(x.name)) guardDefs.set(x.name, []); guardDefs.get(x.name).push({ file: f.path, wrapper: !!x.wrapper }); }
+ }
+ const perRepo = new Map(); // repo -> { guarded, open: [], guardCounts }
+ graph.routes.forEach((r, i) => {
+ const fnd = routeFinding.get(`${r.f}|${r.l}|${r.m}`);
+ if (!fnd) return; // framework we don't analyse: say nothing
+ const gf = fileByPath.get(r.f);
+ if (!gf || kinds(gf.n).some((k) => NOT_USED_KINDS.has(k)) || TEST_FILE.test(r.f)) return;
+ const repo = gf.r ?? '';
+ if (!perRepo.has(repo)) perRepo.set(repo, { guarded: 0, total: 0, open: [], misplaced: [], guardCounts: new Map(), fileGuards: new Map(), guardedIn: new Map() });
+ const pr = perRepo.get(repo);
+ pr.total++;
+ const global = (globalGuards.get(repo) || []).find((g) => g.framework === 'flask' || g.framework === 'express' || (g.framework === 'next' && fnd.fn === r.m));
+ // an unrecognised decorator that turns out to be an auth wrapper defined elsewhere in the project
+ const viaWrapper = !fnd.via && fnd.decos?.find((d) => guardDefs.get(d)?.some((g) => (g.file.split('/')[0] === r.f.split('/')[0])));
+ if (fnd.via || global || viaWrapper) {
+ pr.guarded++; pr.guardedIn.set(r.f, (pr.guardedIn.get(r.f) || 0) + 1);
+ const name = fnd.guard || viaWrapper;
+ if (name) {
+ pr.guardCounts.set(name, (pr.guardCounts.get(name) || 0) + 1);
+ if (!pr.fileGuards.has(r.f)) pr.fileGuards.set(r.f, new Map());
+ pr.fileGuards.get(r.f).set(name, (pr.fileGuards.get(r.f).get(name) || 0) + 1);
+ }
+ return;
+ }
+ if (r.m === 'OPTIONS' || r.m === 'HEAD') return;
+ // webhook receivers: by URL, or a webhook-ish handler in a webhook file (not that file's admin endpoints)
+ const webhook = (WEBHOOK_PATH.test(r.p) && !WEBHOOK_ADMIN.test(r.p)) || (/webhook|hooks?\//i.test(r.f) && /webhook|hook|notify|event|ingress|pubsub|callback|receive|inbound/i.test(r.h || '') && !/create|list|manage|register|delete|test|setup|sync/i.test((r.h || '') + r.p));
+ if (webhook && fnd.signed) return;
+ if (!webhook && PUBLIC_PATH.test(r.p.replace(/<[^>]*>|\{[^}]*\}|:\w+|\[[^\]]*\]/g, 'x'))) return;
+ if (r.p === '/' && r.m === 'GET') return;
+ const entry = { i, r, fnd, write: !['GET', 'ANY'].includes(r.m), webhook };
+ if (fnd.misplaced) pr.misplaced.push(entry); else pr.open.push(entry);
+ });
+ for (const [repo, pr] of perRepo) {
+ const top = (m) => m && [...m.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+ // prefer what this file already uses, then the project's most common real (non-wrapper) check
+ const guardHint = (file, lang) => {
+ const local = top(pr.fileGuards.get(file));
+ const name = local || top(new Map([...pr.guardCounts].filter(([n]) => !guardDefs.get(n)?.every((g) => g.wrapper))));
+ if (!name) return `the project's existing login check (find how other protected endpoints verify the user; if there is none, ask me before adding one)`;
+ const defs = guardDefs.get(name) || [];
+ const where = defs.find((g) => g.file === file) ? 'defined in this file' : defs.length ? `defined in ${defs[0].file}` : '';
+ return `the same check ${local ? 'the other endpoints in this file' : 'the protected endpoints'} already use (${lang === 'python' ? '@' : ''}${name}${where ? ', ' + where : ''})`;
+ };
+ const routeLine = (e) => `- ${e.r.m} ${e.r.p} — ${e.r.f}:${e.r.l}${e.fnd.fn && !/^[A-Z]+$/.test(e.fnd.fn) ? ` (${e.fnd.fn})` : ''}`;
+ if (pr.misplaced.length) {
+ const list = pr.misplaced;
+ issues.push({
+ id: 'misplaced-guard:' + repo, kind: 'unprotected-endpoint', severity: 'high',
+ title: 'A login check is in the wrong place, so it does nothing',
+ detail: `On ${plural(list.length, 'endpoint')} the login check (@${list[0].fnd.misplaced}) is written above the route line instead of below it. Flask only sees what's below, so ${list.length === 1 ? 'it is' : 'they are'} open to anyone even though ${list.length === 1 ? 'it looks' : 'they look'} protected.`,
+ items: list.slice(0, 24).map((e) => 'r:' + e.i),
+ notes: Object.fromEntries(list.slice(0, 24).map((e) => ['r:' + e.i, `@${e.fnd.misplaced} sits above the route line, so it is skipped`])),
+ locations: list.map((e) => ({ file: e.r.f, line: e.r.l })),
+ fix: [`Security fix: these endpoints have their auth decorator above the route decorator, so the framework registers the unprotected function:`, ...list.map(routeLine), ``, `Move each auth decorator directly below the @…route(...) line (route decorator first, then the auth decorator, then def). Change nothing else, then run the tests that cover these endpoints.`].join('\n'),
+ });
+ }
+ if (!pr.open.length) continue;
+ // Nothing in this repo checks the caller: probably protected elsewhere (gateway, private network) or not at all.
+ if (pr.guarded === 0) {
+ const list = pr.open.sort((a, b) => b.write - a.write);
+ issues.push({
+ id: 'no-auth:' + repo, kind: 'unprotected-endpoint', severity: 'medium',
+ title: `None of ${repo ? `${repo}’s` : 'your'} endpoints check who is calling`,
+ detail: `${plural(list.length, 'endpoint')} answer anyone who knows the address, with no login check in the code. That's fine only if this server is private (for example behind a company network or a gateway that checks logins); otherwise anyone could read or change its data.`,
+ items: list.slice(0, 24).map((e) => 'r:' + e.i),
+ notes: Object.fromEntries(list.slice(0, 24).map((e) => ['r:' + e.i, e.write ? 'Changes data, no login check' : 'No login check'])),
+ locations: list.map((e) => ({ file: e.r.f, line: e.r.l })),
+ fix: [`Review access control${repo ? ` in ${repo}` : ''}. None of these endpoints verify the caller in code:`, ...list.slice(0, 40).map(routeLine), list.length > 40 ? `- …and ${list.length - 40} more` : null, ``, `First tell me in plain words whether this server is reachable from the internet and whether anything in front of it (gateway, network rules) checks logins. If it is public, propose the smallest safe way to require login for the data-changing endpoints (POST/PUT/PATCH/DELETE) first, show me the plan, and wait for my OK before changing code.`].filter((x) => x !== null).join('\n'),
+ });
+ continue;
+ }
+ // One issue per route file
+ const byFile = new Map();
+ for (const e of pr.open) { if (!byFile.has(e.r.f)) byFile.set(e.r.f, []); byFile.get(e.r.f).push(e); }
+ for (const [file, list] of byFile) {
+ list.sort((a, b) => b.write - a.write || a.r.l - b.r.l);
+ const writes = list.filter((e) => e.write && !e.webhook), hooks = list.filter((e) => e.webhook), reads = list.filter((e) => !e.write && !e.webhook);
+ // many providers can't sign webhooks at all, so an unsigned one alone stays low
+ const sev = writes.length ? 'high' : reads.length > 2 ? 'medium' : 'low';
+ const lang = scanByPath.get(file)?.lang;
+ const fileGuarded = pr.guardedIn.get(file) || 0;
+ const sv = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+ const parts = [];
+ if (writes.length) parts.push(sv(writes.length, 'endpoint that changes data (create, update or delete)', 'endpoints that change data (create, update or delete)'));
+ if (reads.length) parts.push(sv(reads.length, 'endpoint that returns data', 'endpoints that return data'));
+ const nOpen = writes.length + reads.length;
+ const hookText = hooks.length ? `${sv(hooks.length, 'webhook (an automatic message from another service) is', 'webhooks (automatic messages from another service) are')} accepted without checking that ${hooks.length === 1 ? 'it really comes' : 'they really come'} from that service, so anyone could send fake ones. Some providers can't sign their messages; if so, that's expected.` : '';
+ issues.push({
+ id: 'open-endpoints:' + file, kind: 'unprotected-endpoint', severity: sev,
+ title: writes.length ? `Anyone could change data through ${nameOf(file)}` : hooks.length ? `Anyone could send fake events to ${nameOf(file)}` : `Anyone could read data from ${nameOf(file)}`,
+ detail: [
+ parts.length ? `${file.split('/').pop()} has ${parts.join(' and ')} with no login check, so anyone who finds the address can use ${nOpen === 1 ? 'it' : 'them'}${fileGuarded > 0 ? ` (${sv(fileGuarded, 'other endpoint', 'other endpoints')} in the same file ${fileGuarded === 1 ? 'is' : 'are'} protected)` : ''}. If ${nOpen === 1 ? 'it is' : 'some are'} meant to be public, that's fine; otherwise ${nOpen === 1 ? 'it needs' : 'they need'} a login check.` : '',
+ parts.length && hooks.length ? `It also accepts ${sv(hooks.length, 'webhook', 'webhooks')} without checking who sent ${hooks.length === 1 ? 'it' : 'them'}.` : hookText,
+ ].filter(Boolean).join(' '),
+ items: list.slice(0, 24).map((e) => 'r:' + e.i),
+ notes: Object.fromEntries(list.slice(0, 24).map((e) => ['r:' + e.i, e.webhook ? 'Webhook with no visible signature check' : e.write ? 'Changes data, no login check' : 'Returns data, no login check'])),
+ locations: list.map((e) => ({ file: e.r.f, line: e.r.l })),
+ fix: [
+ `Security fix in ${file}: these endpoints don't check who is calling:`,
+ ...list.map((e) => routeLine(e) + (e.webhook ? ' [webhook]' : '')),
+ ``,
+ `For each endpoint that isn't meant to be public, add ${guardHint(file, lang)}.`,
+ hooks.length ? `For webhooks, verify the provider's signature (using its signing secret from an environment variable) before doing anything, and reject requests that fail.` : null,
+ `If an endpoint is intentionally public (for example a public page or a health check), leave it and tell me why. Don't change anything else; afterwards list exactly which endpoints you protected and run the related tests.`,
+ ].filter((x) => x !== null).join('\n'),
+ });
+ }
+ }
+
+ // ---------- unused files ----------
+ const incoming = new Set();
+ for (const l of graph.links) if (l.a !== l.b && l.b.startsWith('f:')) incoming.add(l.b.slice(2));
+ const entry = new Set(graph.project?.entrypoints || []);
+ const routeFiles = new Set(graph.routes.map((r) => r.f));
+ for (const fl of graph.flows || []) for (const s of fl.steps || []) if (s.ref?.startsWith('f:')) entry.add(s.ref.slice(2));
+ const candidates = graph.files.filter((f) => {
+ if (incoming.has(f.p) || entry.has(f.p) || routeFiles.has(f.p) || !USED_LANGS.has(f.l)) return false;
+ if (TEST_FILE.test(f.p) || SPECIAL_FILE.test(f.p) || /(^|\/)app\/.*\/(page|layout|route|loading|error|template|default)\.[jt]sx?$/.test(f.p)) return false;
+ if (/(^|\/)src\/routes\//.test(f.p) && /\+|\$|\[/.test(f.p.split('/').pop())) return false;
+ if (kinds(f.n).some((k) => NOT_USED_KINDS.has(k))) return false;
+ if (findings(f.p).some((x) => x.k === 'runnable' || x.k === 'route')) return false;
+ return true;
+ });
+ // Safety net for dynamic loading: skip a file whose name appears in any other source file.
+ if (candidates.length) {
+ const want = new Map(candidates.map((f) => [stemOf(f.p), f.p]));
+ const mentioned = new Set();
+ for (const f of scan.files) {
+ if (!['code', 'config', 'docs'].includes(f.category) || f.bytes > 524288) continue;
+ let src;
+ try { src = fs.readFileSync(path.join(root, f.path), 'utf8'); } catch { continue; }
+ for (const tok of new Set(src.match(/[\w$-]+/g) || [])) { const p = want.get(tok); if (p && p !== f.path) mentioned.add(p); }
+ }
+ const unused = candidates.filter((f) => !mentioned.has(f.p));
+ // A module where most files look unused is more likely loaded in a way we can't see; stay quiet.
+ const byNode = new Map();
+ for (const f of unused) { if (!byNode.has(f.n)) byNode.set(f.n, []); byNode.get(f.n).push(f); }
+ const groups = [...byNode.entries()].filter(([n, list]) => { const total = graph.files.filter((f) => f.n === n).length; return n === 'unassigned' || list.length <= 3 || list.length / total <= 0.6; }).sort((a, b) => b[1].length - a[1].length);
+ const MAX = 5;
+ const merged = groups.length > MAX ? [...groups.slice(0, MAX - 1), ['', groups.slice(MAX - 1).flatMap(([, l]) => l)]] : groups;
+ for (const [nid, list] of merged) {
+ list.sort((a, b) => b.loc - a.loc);
+ const where = nid ? label(nid) : 'other areas';
+ const lines = list.reduce((s, f) => s + f.loc, 0);
+ issues.push({
+ id: 'unused:' + (nid || 'other'), kind: 'unused-file', severity: 'low',
+ title: list.length === 1 ? `A file in ${where} looks unused` : `${list.length} files in ${where} look unused`,
+ detail: `Nothing in the app imports or calls ${list.length === 1 ? 'this file' : 'these files'} (${lines.toLocaleString('en-US')} lines). Leftover code confuses AI assistants, which may edit or copy the wrong version. Double-check before deleting: some files are loaded in ways the map can't see.`,
+ items: list.slice(0, 24).map((f) => 'f:' + f.p),
+ notes: Object.fromEntries(list.slice(0, 24).map((f) => ['f:' + f.p, `Nothing uses this file (${f.loc.toLocaleString('en-US')} lines)`])),
+ locations: list.map((f) => ({ file: f.p, line: 1 })),
+ fix: [`Cleanup check: these files look unused (nothing imports or calls them):`, ...list.slice(0, 40).map((f) => `- ${f.p}`), list.length > 40 ? `- …and ${list.length - 40} more` : null, ``, `For each file, search the codebase (including configs, scripts, HTML templates and dynamic imports) to confirm nothing uses it. Then tell me which ones are safe to delete and which are actually used, with one line of evidence each. Don't delete anything until I confirm.`].filter((x) => x !== null).join('\n'),
+ });
+ }
+ }
+
+ // ---------- very large files ----------
+ const big = graph.files.filter((f) => f.loc > 1000 && USED_LANGS.has(f.l) && !TEST_FILE.test(f.p) && !/(^|\/)(migrations|alembic|versions|fixtures?|seeds?|generated|__generated__)\//i.test(f.p) && !/\.d\.ts$/.test(f.p)).sort((a, b) => b.loc - a.loc);
+ if (big.length) {
+ const huge = big.filter((f) => f.loc >= 2000);
+ issues.push({
+ id: 'large-files', kind: 'large-file', severity: huge.length ? 'medium' : 'low',
+ title: big.length === 1 ? 'One file is very large' : `${big.length} files are very large`,
+ detail: `${big.length === 1 ? 'This file has' : 'These files each have'} over 1,000 lines${huge.length ? ` (the biggest has ${big[0].loc.toLocaleString('en-US')})` : ''}. AI assistants read and edit big files less reliably: they lose track of what's where and can break one part while fixing another. Splitting them into smaller files by job makes future changes safer.`,
+ items: big.slice(0, 24).map((f) => 'f:' + f.p),
+ notes: Object.fromEntries(big.slice(0, 24).map((f) => ['f:' + f.p, `${f.loc.toLocaleString('en-US')} lines`])),
+ locations: big.map((f) => ({ file: f.p, line: 1 })),
+ fix: [`Refactor plan: these files are very large:`, ...big.slice(0, 15).map((f) => `- ${f.p} (${f.loc.toLocaleString('en-US')} lines)`), ``, `Start with ${big[0].p}. Read it and propose how to split it into smaller files, each with one clear job (for example by feature or by type of work), keeping every public function name and behaviour the same. Show me the plan first. After I approve, move code in small steps, update the imports, and run the tests after each step. Don't change behaviour.`].join('\n'),
+ });
+ }
+
+ // ---------- frontend hard-coded to localhost ----------
+ const local = [];
+ for (const f of graph.files) if (isFrontend(f.p)) for (const x of findings(f.p)) if (x.k === 'localhost') local.push({ file: f.p, line: x.line });
+ if (local.length) {
+ const filesL = [...new Set(local.map((x) => x.file))];
+ issues.push({
+ id: 'localhost-url', kind: 'hardcoded-url', severity: 'low',
+ title: 'The app points at your own computer’s address',
+ detail: `${filesL.length === 1 ? 'A frontend file' : `${filesL.length} frontend files`} call${filesL.length === 1 ? 's' : ''} a fixed “localhost” address. That only works on your machine; once the app is online those calls will fail for everyone else.`,
+ items: filesL.slice(0, 24).map((p) => 'f:' + p),
+ notes: Object.fromEntries(filesL.slice(0, 24).map((p) => ['f:' + p, `localhost address on line ${local.filter((x) => x.file === p).map((x) => x.line).join(', ')}`])),
+ locations: local,
+ fix: [`These frontend lines use a hard-coded localhost URL:`, ...local.map((x) => `- ${x.file}:${x.line}`), ``, `Replace each with the project's existing API base URL setting (or add one read from a public environment variable such as NEXT_PUBLIC_API_URL / VITE_API_URL, with the localhost value only in .env.development). Don't change anything else.`].join('\n'),
+ });
+ }
+
+ const KIND_ORDER = ['secret', 'env-file', 'unprotected-endpoint', 'large-file', 'hardcoded-url', 'unused-file'];
+ issues.sort((a, b) => SEV_ORDER[a.severity] - SEV_ORDER[b.severity] || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) || (b.locations?.length || 0) - (a.locations?.length || 0));
+ const kept = issues.slice(0, 40);
+ const summary = { high: 0, medium: 0, low: 0 };
+ for (const i of kept) summary[i.severity]++;
+ return { summary, issues: kept };
+}
+
+function readHead(file, max) {
+ const fd = fs.openSync(file, 'r');
+ try { const buf = Buffer.alloc(max); const n = fs.readSync(fd, buf, 0, max, 0); return buf.subarray(0, n).toString('utf8'); } finally { fs.closeSync(fd); }
+}
+function stemOf(p) {
+ const base = p.split('/').pop().replace(/\.[^.]+$/, '');
+ return base === 'index' ? p.split('/').slice(-2, -1)[0] : base;
+}
diff --git a/skills/floorplan/scripts/lib/names.mjs b/skills/floorplan/scripts/lib/names.mjs
new file mode 100644
index 0000000..6148e0e
--- /dev/null
+++ b/skills/floorplan/scripts/lib/names.mjs
@@ -0,0 +1,44 @@
+// Fallback human-readable names, used until Claude writes real ones in floorplan/descriptions/.
+import path from 'node:path';
+
+const P = path.posix;
+const ACRONYMS = /\b(api|ui|ux|id|ids|sku|skus|csv|url|urls|http|db|sql|bc|mcp|pos|gcs|s3|aws|gcp|jwt|pdf|ai|llm|cli|css|html|json|xml|oauth|sso|cdn|dns|ip|io|qa|ci|cd|crud|rpc|grpc|sdk|ttl|uuid|mtg)\b/g;
+const GENERIC = /^(index|page|layout|route|routes|__init__|__main__|main|mod|lib|app|server|loading|error|not-found|template|default|handler|handlers|views?|urls|models?|schemas?|types?|constants?|utils?|helpers?|config|settings)$/i;
+
+export function humanize(id) {
+ let s = String(id)
+ .replace(/\.[a-z0-9]+$/i, '')
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+ .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+ .replace(/[_\-.\s]+/g, ' ')
+ .trim()
+ .toLowerCase();
+ s = s.replace(ACRONYMS, (m) => m.toUpperCase());
+ return s ? s.charAt(0).toUpperCase() + s.slice(1) : String(id);
+}
+
+const cleanSeg = (seg) => seg.replace(/^\((.*)\)$/, '$1').replace(/^\[\.{0,3}(.*)\]$/, '$1 detail');
+
+export function fallbackFileName(p) {
+ const base = P.basename(p);
+ const stem = base.replace(/\.(test|spec)(?=\.)/, '').replace(/\.[^.]+$/, '');
+ const isTest = /\.(test|spec)\.[a-z]+$/i.test(base) || /^test_/.test(base) || /_test\.(py|go)$/.test(base);
+ const core = stem.replace(/^test_/, '').replace(/_test$/, '');
+ let name;
+ if (GENERIC.test(core)) {
+ const dirs = P.dirname(p).split('/').filter((d) => d && !/^(src|app|lib|pkg|internal)$/.test(d)).map(cleanSeg);
+ const parent = dirs.slice(-1)[0] || '';
+ const role = { page: 'page', layout: 'layout', route: 'route handler', __init__: 'package', index: '', loading: 'loading state', error: 'error state' }[core.toLowerCase()];
+ name = parent ? `${humanize(parent)}${role ? ' ' + role : role === '' ? '' : ' ' + humanize(core).toLowerCase()}` : humanize(core);
+ } else name = humanize(core);
+ return isTest ? `${name} tests` : name;
+}
+
+export function fallbackRouteName(r) {
+ if (r.handler && !/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|ANY)$/.test(r.handler)) return humanize(r.handler);
+ const segs = r.path.split('/').filter((s) => s && !/[<{:[*]/.test(s));
+ const verb = { GET: 'Get', POST: 'Create', PUT: 'Replace', PATCH: 'Update', DELETE: 'Delete' }[r.method] || r.method;
+ return `${verb} ${humanize(segs.slice(-2).join(' ') || 'root').toLowerCase()}`;
+}
+
+export const routeKey = (r) => `${r.method} ${r.path}`;
diff --git a/skills/floorplan/scripts/lib/resolve.mjs b/skills/floorplan/scripts/lib/resolve.mjs
new file mode 100644
index 0000000..20306d9
--- /dev/null
+++ b/skills/floorplan/scripts/lib/resolve.mjs
@@ -0,0 +1,254 @@
+// Resolve import specifiers to files in the codebase, or to named external packages.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonLoose } from './common.mjs';
+
+const P = path.posix;
+
+const NODE_BUILTINS = new Set(['assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console', 'constants', 'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'http', 'http2', 'https', 'inspector', 'module', 'net', 'os', 'path', 'perf_hooks', 'process', 'punycode', 'querystring', 'readline', 'repl', 'stream', 'string_decoder', 'timers', 'tls', 'tty', 'url', 'util', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib', 'test']);
+const PY_STDLIB = new Set('__future__ abc argparse array ast asyncio atexit base64 bisect builtins bz2 calendar cgi cmath codecs collections colorsys concurrent configparser contextlib contextvars copy csv ctypes curses dataclasses datetime decimal difflib dis email encodings enum errno faulthandler fcntl filecmp fileinput fnmatch fractions ftplib functools gc getopt getpass gettext glob graphlib gzip hashlib heapq hmac html http imaplib importlib inspect io ipaddress itertools json keyword linecache locale logging lzma mailbox math mimetypes mmap multiprocessing netrc numbers operator optparse os pathlib pdb pickle pkgutil platform plistlib poplib posixpath pprint profile pstats pty queue quopri random re readline reprlib resource rlcompleter runpy sched secrets select selectors shelve shlex shutil signal site smtplib socket socketserver sqlite3 ssl stat statistics string stringprep struct subprocess sys sysconfig syslog tarfile tempfile termios textwrap threading time timeit tkinter token tokenize tomllib trace traceback tracemalloc tty turtle types typing typing_extensions unicodedata unittest urllib uuid venv warnings wave weakref webbrowser winreg wsgiref xml xmlrpc zipfile zipimport zlib zoneinfo'.split(' '));
+const RUST_STD = new Set(['std', 'core', 'alloc', 'crate', 'self', 'super']);
+
+const JS_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.vue', '.svelte', '.d.ts', '.json'];
+
+export function createResolver(root, files) {
+ const fileSet = new Set(files.map((f) => f.path));
+ const byPath = new Map(files.map((f) => [f.path, f]));
+ const dirsWith = (name) => files.filter((f) => P.basename(f.path) === name).map((f) => P.dirname(f.path));
+
+ // ---- JS: tsconfig/jsconfig paths + workspace packages ----
+ const tsconfigCache = new Map();
+ const loadTsconfig = (file) => {
+ if (tsconfigCache.has(file)) return tsconfigCache.get(file);
+ let cfg = null;
+ const json = readJsonLoose(path.join(root, file));
+ if (json) {
+ const dir = P.dirname(file);
+ let opts = json.compilerOptions || {};
+ let optsDir = dir;
+ if ((!opts.paths && !opts.baseUrl) && typeof json.extends === 'string' && json.extends.startsWith('.')) {
+ const extFile = P.normalize(P.join(dir, json.extends.endsWith('.json') ? json.extends : json.extends + '.json'));
+ const base = fileSet.has(extFile) ? loadTsconfig(extFile) : null;
+ if (base) { opts = base.raw; optsDir = base.optsDir; }
+ }
+ const baseDir = opts.baseUrl ? P.normalize(P.join(optsDir, opts.baseUrl)) : optsDir;
+ cfg = { raw: opts, optsDir, baseDir, hasBaseUrl: !!opts.baseUrl, paths: Object.entries(opts.paths || {}) };
+ }
+ tsconfigCache.set(file, cfg);
+ return cfg;
+ };
+ const nearestCache = new Map();
+ const nearestTsconfig = (dir) => {
+ if (nearestCache.has(dir)) return nearestCache.get(dir);
+ let found = null;
+ for (const name of ['tsconfig.json', 'jsconfig.json']) {
+ const f = dir === '.' ? name : `${dir}/${name}`;
+ if (fileSet.has(f)) { found = loadTsconfig(f); if (found) break; }
+ }
+ if (!found && dir !== '.' && dir !== '') found = nearestTsconfig(P.dirname(dir));
+ nearestCache.set(dir, found);
+ return found;
+ };
+ const workspacePkgs = new Map();
+ for (const dir of dirsWith('package.json')) {
+ const pj = readJsonLoose(path.join(root, dir, 'package.json'));
+ if (pj?.name) workspacePkgs.set(pj.name, { dir, pj });
+ }
+
+ const tryJsFile = (p) => {
+ p = P.normalize(p);
+ if (fileSet.has(p) && !p.endsWith('/')) return p;
+ for (const ext of JS_EXTS) if (fileSet.has(p + ext)) return p + ext;
+ const jsToTs = p.replace(/\.(m|c)?jsx?$/, '');
+ if (jsToTs !== p) for (const ext of ['.ts', '.tsx', '.mts', '.cts']) if (fileSet.has(jsToTs + ext)) return jsToTs + ext;
+ for (const ext of JS_EXTS) if (fileSet.has(`${p}/index${ext}`)) return `${p}/index${ext}`;
+ return null;
+ };
+
+ const resolveJs = (from, spec) => {
+ if (spec.startsWith('.')) {
+ const hit = tryJsFile(P.join(P.dirname(from), spec));
+ return hit ? { file: hit } : { unresolved: true };
+ }
+ const cfg = nearestTsconfig(P.dirname(from));
+ if (cfg) {
+ for (const [pattern, targets] of cfg.paths) {
+ const star = pattern.indexOf('*');
+ const matched = star === -1 ? (spec === pattern ? '' : null)
+ : (spec.startsWith(pattern.slice(0, star)) && spec.endsWith(pattern.slice(star + 1)) ? spec.slice(star, spec.length - (pattern.length - star - 1)) : null);
+ if (matched === null) continue;
+ for (const t of targets) {
+ const hit = tryJsFile(P.join(cfg.baseDir, t.replace('*', matched)));
+ if (hit) return { file: hit };
+ }
+ }
+ if (cfg.hasBaseUrl) { const hit = tryJsFile(P.join(cfg.baseDir, spec)); if (hit) return { file: hit }; }
+ }
+ if (spec.startsWith('node:')) return { builtin: true };
+ const parts = spec.split('/');
+ const pkgName = spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+ const sub = parts.slice(spec.startsWith('@') ? 2 : 1).join('/');
+ const ws = workspacePkgs.get(pkgName);
+ if (ws) {
+ if (sub) { const hit = tryJsFile(P.join(ws.dir, sub)) || tryJsFile(P.join(ws.dir, 'src', sub)); if (hit) return { file: hit }; }
+ const exp = ws.pj.exports;
+ const entries = [ws.pj.source, typeof exp === 'string' ? exp : exp?.['.']?.import || exp?.['.']?.default || (typeof exp?.['.'] === 'string' ? exp['.'] : null), ws.pj.module, ws.pj.main, 'src/index', 'index'];
+ for (const e of entries) { if (typeof e !== 'string') continue; const hit = tryJsFile(P.join(ws.dir, e)); if (hit) return { file: hit }; }
+ }
+ if (NODE_BUILTINS.has(pkgName)) return { builtin: true };
+ if (/^[@a-z0-9]/i.test(pkgName)) return { external: pkgName, eco: 'npm' };
+ return { unresolved: true };
+ };
+
+ // ---- Python ----
+ const pyRootsCache = new Map();
+ const pyRootsFor = (from, repoPath) => {
+ const dir = P.dirname(from);
+ const key = dir + '|' + repoPath;
+ if (pyRootsCache.has(key)) return pyRootsCache.get(key);
+ const roots = [];
+ const repoRoot = repoPath === '.' ? '' : repoPath;
+ let d = dir;
+ while (true) {
+ roots.push(d === '.' ? '' : d);
+ if (d === repoRoot || d === '.' || d === '') break;
+ d = P.dirname(d);
+ }
+ roots.push(repoRoot ? repoRoot + '/src' : 'src');
+ pyRootsCache.set(key, roots);
+ return roots;
+ };
+ const tryPyModule = (base) => {
+ const b = base.replace(/^\/+/, '');
+ if (fileSet.has(b + '.py')) return b + '.py';
+ if (fileSet.has(b + '/__init__.py')) return b + '/__init__.py';
+ if (fileSet.has(b + '.pyi')) return b + '.pyi';
+ return null;
+ };
+ const resolvePy = (from, imp, repoPath) => {
+ const spec = imp.spec;
+ const targets = [];
+ if (spec.startsWith('.')) {
+ const dots = spec.match(/^\.+/)[0].length;
+ let base = P.dirname(from);
+ for (let i = 1; i < dots; i++) base = P.dirname(base);
+ const rest = spec.slice(dots).replace(/\./g, '/');
+ const modBase = rest ? P.join(base, rest) : base;
+ const mod = rest ? tryPyModule(modBase) : null;
+ const subs = (imp.names || []).map((n) => tryPyModule(P.join(modBase, n))).filter(Boolean);
+ if (subs.length) return { files: subs, names: imp.names, module: mod };
+ if (mod) return { file: mod };
+ if (!rest) { const init = tryPyModule(base); if (init) return { file: init }; }
+ return { unresolved: true };
+ }
+ const top = spec.split('.')[0];
+ const modPath = spec.replace(/\./g, '/');
+ for (const r of pyRootsFor(from, repoPath)) {
+ const base = r ? `${r}/${modPath}` : modPath;
+ if (imp.from && imp.names?.length) {
+ const subs = imp.names.map((n) => tryPyModule(`${base}/${n}`)).filter(Boolean);
+ if (subs.length) return { files: subs, names: imp.names, module: tryPyModule(base) };
+ }
+ const hit = tryPyModule(base);
+ if (hit) return { file: hit };
+ // `import a.b.c` where only a/b exists
+ const parts = modPath.split('/');
+ for (let k = parts.length - 1; k >= 1; k--) {
+ const h = tryPyModule((r ? r + '/' : '') + parts.slice(0, k).join('/'));
+ if (h && targets.length === 0) { targets.push(h); break; }
+ }
+ if (targets.length) return { file: targets[0] };
+ }
+ if (PY_STDLIB.has(top)) return { builtin: true };
+ return { external: top, eco: 'pypi' };
+ };
+
+ // ---- Go ----
+ const goMods = dirsWith('go.mod').map((dir) => {
+ const txt = fs.readFileSync(path.join(root, dir, 'go.mod'), 'utf8');
+ return { dir, module: /^module\s+(\S+)/m.exec(txt)?.[1] };
+ }).filter((m) => m.module).sort((a, b) => b.module.length - a.module.length);
+ const goDirFiles = new Map();
+ for (const f of files) if (f.path.endsWith('.go') && !f.path.endsWith('_test.go')) {
+ const d = P.dirname(f.path);
+ if (!goDirFiles.has(d)) goDirFiles.set(d, []);
+ goDirFiles.get(d).push(f.path);
+ }
+ const resolveGo = (from, spec) => {
+ for (const m of goMods) {
+ if (spec === m.module || spec.startsWith(m.module + '/')) {
+ const dir = P.normalize(P.join(m.dir, spec.slice(m.module.length)));
+ const list = goDirFiles.get(dir === '' ? '.' : dir);
+ if (list?.length) {
+ const pref = list.find((p) => P.basename(p, '.go') === P.basename(dir)) || list.sort()[0];
+ return { file: pref };
+ }
+ return { unresolved: true };
+ }
+ }
+ if (!spec.split('/')[0].includes('.')) return { builtin: true };
+ return { external: spec.split('/').slice(0, 3).join('/'), eco: 'go' };
+ };
+
+ // ---- Rust ----
+ const crateRoots = dirsWith('Cargo.toml').map((d) => (d === '.' ? 'src' : `${d}/src`)).sort((a, b) => b.length - a.length);
+ const resolveRust = (from, imp) => {
+ const dir = P.dirname(from);
+ const stem = P.basename(from, '.rs');
+ if (imp.kind === 'mod') {
+ const base = ['mod', 'lib', 'main'].includes(stem) ? dir : `${dir}/${stem}`;
+ for (const c of [`${base}/${imp.spec}.rs`, `${base}/${imp.spec}/mod.rs`]) if (fileSet.has(c)) return { file: c };
+ return { unresolved: true };
+ }
+ const segs = imp.spec.split('::');
+ if (segs[0] === 'crate') {
+ const cr = crateRoots.find((r) => from.startsWith(r + '/'));
+ if (!cr) return { unresolved: true };
+ const rest = segs.slice(1);
+ for (let k = rest.length; k >= 1; k--) {
+ const b = `${cr}/${rest.slice(0, k).join('/')}`;
+ for (const c of [b + '.rs', b + '/mod.rs']) if (fileSet.has(c)) return { file: c };
+ }
+ return { unresolved: true };
+ }
+ if (RUST_STD.has(segs[0])) return { builtin: true };
+ return { external: segs[0], eco: 'cargo' };
+ };
+
+ // ---- JVM ----
+ const jvmIndex = new Map();
+ for (const f of files) if (f.pkg) jvmIndex.set(`${f.pkg}.${P.basename(f.path).replace(/\.\w+$/, '')}`, f.path);
+ const resolveJvm = (from, spec) => {
+ if (jvmIndex.has(spec)) return { file: jvmIndex.get(spec) };
+ if (/^(java|javax|kotlin|scala|jdk|sun)\./.test(spec)) return { builtin: true };
+ const parts = spec.split('.');
+ for (let k = parts.length - 1; k >= 2; k--) if (jvmIndex.has(parts.slice(0, k).join('.'))) return { file: jvmIndex.get(parts.slice(0, k).join('.')) };
+ return { external: parts.slice(0, Math.min(3, parts.length - 1)).join('.'), eco: 'maven' };
+ };
+
+ // ---- generic relative (C, Ruby, PHP, CSS) ----
+ const byBasename = new Map();
+ for (const f of files) { const b = P.basename(f.path); byBasename.set(b, byBasename.has(b) ? null : f.path); }
+ const resolveRelative = (from, spec, exts) => {
+ const base = P.normalize(P.join(P.dirname(from), spec));
+ for (const e of ['', ...exts]) if (fileSet.has(base + e)) return { file: base + e };
+ const uniq = byBasename.get(P.basename(spec));
+ if (uniq) return { file: uniq };
+ return { unresolved: true };
+ };
+
+ return function resolve(file, imp) {
+ const lang = file.lang;
+ switch (lang) {
+ case 'typescript': case 'javascript': case 'vue': case 'svelte': case 'astro': return resolveJs(file.path, imp.spec);
+ case 'python': return resolvePy(file.path, imp, file.repo);
+ case 'go': return resolveGo(file.path, imp.spec);
+ case 'rust': return resolveRust(file.path, imp);
+ case 'java': case 'kotlin': case 'scala': case 'groovy': return resolveJvm(file.path, imp.spec);
+ case 'ruby': return resolveRelative(file.path, imp.spec, ['.rb']);
+ case 'php': return resolveRelative(file.path, imp.spec, ['.php']);
+ case 'css': return resolveRelative(file.path, imp.spec, ['.css', '.scss', '.sass', '.less']).file ? resolveRelative(file.path, imp.spec, ['.css', '.scss']) : resolveRelative(file.path, P.join(P.dirname(imp.spec), '_' + P.basename(imp.spec)), ['.scss', '.sass']);
+ default: return resolveRelative(file.path, imp.spec, []);
+ }
+ };
+}
diff --git a/skills/floorplan/scripts/lib/routes.mjs b/skills/floorplan/scripts/lib/routes.mjs
new file mode 100644
index 0000000..a6eadfb
--- /dev/null
+++ b/skills/floorplan/scripts/lib/routes.mjs
@@ -0,0 +1,142 @@
+// Turn per-file route definitions + mounts into full paths, then match HTTP call literals to them.
+// This is what links a frontend repo to a backend repo when no import connects them.
+
+export const routeSegments = (p) => p.split('/').filter(Boolean).map((s) =>
+ /^(<[^>]*>|\{[^}]*\}|:\w+|\[\.{0,3}[^\]]*\]|\*{1,2}|\$\{[^}]*\})$/.test(s) || /\$\{|\{[^}]*\}/.test(s) ? '*' : s);
+
+const TEST_FILE = /(^|\/)(tests?|__tests__|spec|specs|e2e|fixtures?)\/|\.(test|spec)\.[a-z]+$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$|(^|\/)conftest\.py$/;
+
+const joinPath =(...parts) => '/' + parts.map((p) => (p || '').replace(/^\/+|\/+$/g, '')).filter(Boolean).join('/');
+
+/**
+ * @param files scanned files: { path, lang, routes, mounts, routers, imports:[{names, aliases, alias, files[]}] }
+ * @returns routes [{ file, method, path, line }]
+ */
+/** The file (and router variable, '*' = all) a mount statement points at. */
+function mountTarget(f, mount) {
+ const imports = (f.imports || []).filter((i) => i.files?.length);
+ if (mount.spec) { const imp = imports.find((i) => i.spec === mount.spec); return imp ? { file: imp.files[0], v: '*' } : null; }
+ const [head, attr] = mount.var.split('.');
+ if (f.lang !== 'python') {
+ // JS: match the mounted name to the local binding of an import or require (every router can be called `router`)
+ const imp = imports.find((i) => i.locals && Object.hasOwn(i.locals, head));
+ return { file: imp ? imp.files[0] : f.path, v: '*' };
+ }
+ for (const imp of imports) {
+ if (attr && (imp.alias === head || imp.spec?.split('.').pop() === head || imp.names?.includes(head))) {
+ return { file: imp.files[imp.names?.indexOf(head) ?? 0] || imp.files[0], v: attr };
+ }
+ if (!attr) {
+ const orig = imp.aliases?.[head] || head;
+ if (imp.names?.includes(orig)) return { file: imp.files.length === 1 ? imp.files[0] : imp.files[imp.names.indexOf(orig)] || imp.files[0], v: orig };
+ }
+ }
+ return { file: f.path, v: head }; // defined in the same file
+}
+
+export function resolveRoutes(files) {
+ // mountsTo[file] = [{ from, v, prefix }] (v === '*' applies to every route in the file)
+ const mountsTo = new Map();
+ for (const f of files) for (const mount of TEST_FILE.test(f.path) ? [] : f.mounts || []) {
+ const t = mountTarget(f, mount);
+ if (!t) continue;
+ if (!mountsTo.has(t.file)) mountsTo.set(t.file, []);
+ mountsTo.get(t.file).push({ from: f.path, v: t.v, prefix: mount.prefix });
+ }
+ // Every prefix a file's routes live under, composing nested mounts (a router mounted into a router
+ // that is itself mounted), e.g. app.use('/api', api) + api.use('/users', users) → /api/users.
+ const outerPrefixes = (file, v, seen = new Set()) => {
+ const ms = (mountsTo.get(file) || []).filter((m) => v == null || m.v === '*' || m.v === v);
+ if (!ms.length || seen.has(file)) return [''];
+ const next = new Set(seen).add(file);
+ const out = [];
+ for (const m of ms) for (const p of m.from === file ? [''] : outerPrefixes(m.from, null, next)) out.push(joinPath(p, m.prefix));
+ return [...new Set(out)];
+ };
+
+ const routes = [];
+ for (const f of files) {
+ // Test files define throwaway apps and stub servers; their routes aren't part of the system.
+ if (!f.routes?.length || TEST_FILE.test(f.path)) continue;
+ for (const r of f.routes) {
+ const defPrefix = (r.var && f.routers?.[r.var]) || '';
+ for (const mp of outerPrefixes(f.path, r.var)) routes.push({ file: f.path, method: r.method, path: joinPath(mp, defPrefix, r.path), line: r.line, ...(r.handler ? { handler: r.handler } : {}), ...(r.doc ? { doc: r.doc } : {}) });
+ }
+ }
+ return dedupe(routes, (r) => `${r.file}|${r.method}|${r.path}`);
+}
+
+function dedupe(list, key) {
+ const seen = new Set();
+ return list.filter((x) => { const k = key(x); if (seen.has(k)) return false; seen.add(k); return true; });
+}
+
+/** Score how well a call path matches a route path; null when they can't match. */
+function score(c, r) {
+ const n = Math.min(c.length, r.length);
+ if (n === 0) return null;
+ let literal = 0, wild = 0, loose = 0;
+ for (let i = 1; i <= n; i++) {
+ const a = c[c.length - i], b = r[r.length - i];
+ if (a === b && a !== '*') literal++;
+ else if (b === '*') wild++; // route parameter: matches anything
+ else if (a === '*') loose++; // call interpolation vs a fixed route segment: possible, less likely
+ else return null;
+ }
+ wild += loose;
+ const extra = Math.max(c.length, r.length) - n;
+ if (literal === 0) return null;
+ // thin evidence (one literal segment under an unknown prefix): only kept if the prefix matches
+ // what this caller is known to use, see matchCalls
+ const weak = (literal === 1 && wild === 0 && extra > 2) || (literal === 1 && wild > 0 && extra > 0);
+ // the part of the route the call didn't spell out, usually the client's base URL ("api/store")
+ const prefix = r.length > c.length ? r.slice(0, r.length - n).join('/') : '';
+ return { s: literal * 3 + wild - loose * 0.8 - extra * 0.5 + (extra === 0 ? 1 : 0) - (weak ? 100 : 0), literal, prefix, weak };
+}
+
+/**
+ * Match call literals against resolved routes.
+ * Ties are broken by the caller's learned base prefix: if a client's unambiguous calls all land
+ * under /api/store, its ambiguous `/orders` means /api/store/orders, not /api/admin/orders.
+ * @returns [{ from, to, method, path, call, line }]
+ */
+export function matchCalls(files, routes) {
+ const rs = routes.map((r) => ({ ...r, segs: routeSegments(r.path) }));
+ const pending = [];
+ const learned = new Map(); // caller file or dir -> Map(prefix -> count)
+ const learn = (key, prefix) => { if (!learned.has(key)) learned.set(key, new Map()); const m = learned.get(key); m.set(prefix, (m.get(prefix) || 0) + 1); };
+ for (const f of files) {
+ for (const call of f.calls || []) {
+ const cs = routeSegments(call.path);
+ let best = -Infinity, hits = [];
+ for (const r of rs) {
+ if (r.file === f.path) continue;
+ if (call.method && r.method !== 'ANY' && r.method !== call.method) continue;
+ const sc = score(cs, r.segs);
+ if (!sc) continue;
+ if (sc.s > best) { best = sc.s; hits = [{ r, ...sc }]; } else if (sc.s === best) hits.push({ r, ...sc });
+ }
+ if (!hits.length) continue;
+ pending.push({ f, call, hits });
+ if (!hits[0].weak && new Set(hits.map((h) => h.r.file)).size === 1) { learn(f.path, hits[0].prefix); learn(dir(f.path), hits[0].prefix); }
+ }
+ }
+ const top = (key) => { const m = learned.get(key); return m ? [...m.entries()].sort((a, b) => b[1] - a[1])[0][0] : null; };
+ const out = [];
+ for (const { f, call, hits } of pending) {
+ let keep = hits;
+ const pref = top(f.path) ?? top(dir(f.path));
+ // weak matches need the caller's own track record, not a neighbour's
+ if (hits[0].weak) { const own = top(f.path); keep = own == null ? [] : hits.filter((h) => h.prefix === own); if (!keep.length) continue; }
+ // no method visible at the call site: fetch's default is GET
+ if (!call.method && keep.some((h) => h.r.method === 'GET') && new Set(keep.map((h) => h.r.method)).size > 1) keep = keep.filter((h) => h.r.method === 'GET' || h.r.method === 'ANY');
+ if (new Set(keep.map((h) => h.r.file)).size > 1) {
+ const narrowed = pref == null ? [] : keep.filter((h) => h.prefix === pref);
+ if (narrowed.length) keep = narrowed;
+ }
+ if (new Set(keep.map((h) => h.r.file)).size > 3) continue;
+ for (const { r } of keep) out.push({ from: f.path, to: r.file, method: r.method, path: r.path, call: call.path, line: call.line, routeLine: r.line });
+ }
+ return dedupe(out, (e) => `${e.from}|${e.to}|${e.method}|${e.path}`);
+}
+const dir = (p) => p.split('/').slice(0, -1).join('/');
diff --git a/skills/floorplan/scripts/lib/screens.mjs b/skills/floorplan/scripts/lib/screens.mjs
new file mode 100644
index 0000000..c24ce5d
--- /dev/null
+++ b/skills/floorplan/scripts/lib/screens.mjs
@@ -0,0 +1,638 @@
+// Screens: the pages a person can open in the app (Next.js routes, React Router routes, …), so the
+// map can be entered from what people recognise ("the checkout page") instead of code layers.
+//
+// findScreens(src, file) — called by scan.mjs for every code/config/docs file with its source.
+// Returns raw screen hints for that file, stored in scan.json files[].screens:
+// { fw, url } the file itself is the screen (file-based routers)
+// { fw, url, comp, spec, files } a router entry pointing at a component (resolved by import)
+// { fw, url, target } a router config naming the screen's file path
+// buildScreens(ctx) — called by build.mjs with { graph, scan, arch, root } after the graph is built.
+// Returns graph.screens: [{ id, url, file, app, fw, name, description, behind: [{ id, note, kind }] }]
+// kind: screen | part | request | server | data | outside (in that order, ~16 items).
+//
+// Supported: Next.js (app + pages router), React Router (JSX <Route> and route objects, v5–v7 incl.
+// routes.ts config), Vue Router, Angular routes, TanStack Router (createFileRoute), SvelteKit, Remix
+// (flat + nested routes), Nuxt, Astro, Expo Router.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const P = path.posix;
+const JS_LANGS = new Set(['typescript', 'javascript', 'vue', 'svelte', 'astro']);
+
+// ======================= scan side =======================
+
+export function findScreens(src, file) {
+ if (file.category !== 'code' || !JS_LANGS.has(file.lang)) return [];
+ const p = file.path;
+ const out = [];
+ const page = fileBasedScreen(p, src);
+ if (page) out.push(page);
+ if (file.lang === 'typescript' || file.lang === 'javascript' || file.lang === 'vue') {
+ for (const r of routerScreens(src, file)) out.push(r);
+ }
+ // de-dupe within a file
+ const seen = new Set();
+ return out.filter((s) => { const k = `${s.url}|${s.comp || ''}|${s.spec || ''}|${s.target || ''}`; if (seen.has(k)) return false; seen.add(k); return true; });
+}
+
+/** Turn file-router segments into a URL. Returns null when the file isn't routable (private folders, intercepts). */
+function segmentsToUrl(segs, { indexName = null } = {}) {
+ const out = [];
+ for (let s of segs) {
+ if (!s) continue;
+ if (/^\(\.+\)/.test(s)) return null; // Next intercepting routes: (.)photo
+ if (/^\(.*\)$/.test(s) || s.startsWith('@')) continue; // route groups, parallel slots
+ if (s.startsWith('_')) return null; // Next private folders
+ if (indexName && s === indexName) continue;
+ s = s.replace(/^\[\[\.\.\.(.+)\]\]$/, '*').replace(/^\[\.\.\.(.+)\]$/, '*').replace(/^\[\[(.+)\]\]$/, ':$1?').replace(/^\[(.+)\]$/, ':$1');
+ out.push(s);
+ }
+ return '/' + out.join('/');
+}
+
+function fileBasedScreen(p, src) {
+ let m;
+ // Next.js app router: app/**/page.tsx
+ if ((m = /(?:^|\/)app\/((?:[^/]+\/)*)page\.(?:tsx|jsx|ts|js|mdx)$/.exec(p))) {
+ const url = segmentsToUrl(m[1].split('/'));
+ return url && { fw: 'next-app', url };
+ }
+ // SvelteKit: src/routes/**/+page.svelte
+ if ((m = /(?:^|\/)routes\/((?:[^/]+\/)*)\+page\.svelte$/.exec(p))) {
+ const url = segmentsToUrl(m[1].split('/').map((s) => s.replace(/^\[(\.\.\.)?([^\]=]+)(=[^\]]+)?\]$/, (_, rest, name) => rest ? '[...x]' : `[${name}]`)));
+ return url && { fw: 'sveltekit', url };
+ }
+ // TanStack Router file routes: createFileRoute('/products/$id')
+ if ((m = /\bcreateFileRoute\(\s*["'`]([^"'`]*)["'`]\s*\)/.exec(src)) && !/__root/.test(p)) {
+ const url = normalizeUrl(m[1].replace(/\/_[^/]+/g, '').replace(/\$([A-Za-z_]\w*)/g, ':$1').replace(/\/\$$/, '/*'));
+ return url && { fw: 'tanstack', url };
+ }
+ // Remix / React Router v7 file routes: app/routes/*
+ if ((m = /(?:^|\/)app\/routes\/(.+)\.(?:tsx|jsx|ts|js|mdx)$/.exec(p)) && !/react-native/.test(src)) {
+ if (!/\bexport\s+default\b/.test(src)) return null; // resource routes (loader/action only) aren't screens
+ let rel = m[1];
+ if (/(^|\/)route$/.test(rel)) rel = rel.replace(/\/?route$/, ''); // folder routes: products.$id/route.tsx
+ const segs = [];
+ for (const part of rel.split('/')) for (const raw of part.split(/\.(?![^[]*\])/)) {
+ let s = raw.replace(/\[(.*?)\]/g, '$1');
+ if (s === '_index' || s === 'index') continue;
+ if (s.startsWith('_')) continue; // pathless layout
+ s = s.replace(/_$/, '');
+ if (s === '$') s = '*';
+ else if (/^\(\$(\w+)\)$/.test(s)) s = ':' + s.slice(2, -1) + '?';
+ else if (/^\((.+)\)$/.test(s)) s = s.slice(1, -1);
+ else if (s.startsWith('$')) s = ':' + s.slice(1);
+ if (s) segs.push(s);
+ }
+ return { fw: 'remix', url: '/' + segs.join('/') };
+ }
+ // Expo Router: app/**/*.tsx that renders React Native
+ if ((m = /(?:^|\/)app\/((?:[^/]+\/)*)([^/]+)\.(?:tsx|jsx|ts|js)$/.exec(p)) && /from\s+["'](react-native|expo-router)["']/.test(src)) {
+ const base = m[2];
+ if (base.startsWith('_') || base.startsWith('+') || /\+api$/.test(base) || /^(page|layout|route)$/.test(base)) return null;
+ const url = segmentsToUrl([...m[1].split('/'), base], { indexName: 'index' });
+ return url && { fw: 'expo', url };
+ }
+ // Pages routers: Next.js (pages/**.tsx), Nuxt (pages/**.vue), Astro (src/pages/**.astro)
+ if ((m = /(?:^|\/)pages\/((?:[^/]+\/)*)([^/]+)\.(tsx|jsx|ts|js|vue|astro|mdx?)$/.exec(p))) {
+ const [, dir, base, ext] = m;
+ if (/^api\//.test(dir) || base.startsWith('_') || /\.(test|spec|stories)$/.test(base) || /(^|\/)(components?|_[^/]*)\//.test(dir)) return null;
+ if ((ext === 'ts' || ext === 'js') && !/\bexport\s+default\b/.test(src)) return null;
+ const fw = ext === 'vue' ? 'nuxt' : ext === 'astro' ? 'astro' : 'next-pages';
+ const url = segmentsToUrl([...dir.split('/'), base], { indexName: 'index' });
+ return url && { fw, url };
+ }
+ return null;
+}
+
+function normalizeUrl(u) {
+ if (u == null) return null;
+ let s = String(u).trim().split(/[?#]/)[0];
+ s = s.replace(/\(([^()]*)\)/g, (m0, inner) => (/^[\w-]+$/.test(inner) ? m0 : '')); // vue param regexes :id(\\d+)
+ s = ('/' + s).replace(/\/{2,}/g, '/');
+ if (s.length > 1) s = s.replace(/\/$/, '');
+ return s;
+}
+const joinUrl = (parent, child) => {
+ if (child == null) return parent;
+ if (child.startsWith('/')) return normalizeUrl(child);
+ return normalizeUrl((parent || '') + '/' + child);
+};
+const isCatchAll = (u) => /^\/?(\*\*?|:pathMatch.*|:catchAll.*)$/.test(u);
+
+const WRAPPER = /^(Route|Routes|Switch|Navigate|Redirect|Outlet|Suspense|React\.Suspense|Fragment|React\.Fragment|ErrorBoundary|\w*(Guard|Protected|Private|Require\w*|Auth\w*|Provider|Boundary|Layout|Wrapper|Shell))$/;
+const pickComponent = (names) => names.filter((n) => !WRAPPER.test(n)).pop() || null;
+
+/** local name -> import spec, including default imports and lazy(() => import('...')) bindings. */
+function importBindings(code) {
+ const map = new Map();
+ for (const m of code.matchAll(/\bimport\s+(?:type\s+)?([A-Za-z_$][\w$]*)?\s*,?\s*(?:\{([^}]*)\})?\s*(?:\*\s+as\s+([A-Za-z_$][\w$]*))?\s*from\s*["']([^"']+)["']/g)) {
+ if (m[1]) map.set(m[1], m[4]);
+ if (m[3]) map.set(m[3], m[4]);
+ for (const part of (m[2] || '').split(',')) {
+ const [orig, alias] = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/);
+ if (orig) map.set((alias || orig).trim(), m[4]);
+ }
+ }
+ for (const m of code.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:React\.)?(?:lazy|loadable|lazyWithRetry|defineAsyncComponent|dynamic)\s*\(\s*(?:async\s*)?\(\s*\)\s*=>\s*import\(\s*["']([^"']+)["']/g)) map.set(m[1], m[2]);
+ return map;
+}
+
+const ROUTER_SIGNAL = /createBrowserRouter|createHashRouter|createMemoryRouter|createRoutesFromElements|useRoutes|RouterProvider|createRouter|new\s+(?:Vue)?Router\s*\(|RouteRecordRaw|RouteObject|provideRouter|RouterModule|Routes\s*=\s*\[|\broutes\s*(?::\s*[\w<>[\]\s]+)?=\s*\[/;
+
+function routerScreens(src, file) {
+ const code = src.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')).replace(/(^|[^:"'`\\])\/\/[^\n]*/g, (m, pre) => pre + ' '.repeat(m.length - pre.length));
+ const out = [];
+ const bindings = importBindings(code);
+ const nests = new Map(); // hint -> nesting depth; a layout and its index child share a URL, the child wins
+ const make = (fw, url, comp, spec, nest = 0) => {
+ if (!url || isCatchAll(url.replace(/^\//, ''))) return;
+ spec = spec || (comp ? bindings.get(comp.split('.')[0]) : null) || null;
+ if (!comp && !spec) return;
+ const hint = { fw, url, ...(comp ? { comp } : {}), ...(spec ? { spec } : {}) };
+ // the scanner resolves this file's imports after the hooks run; read them lazily when scan.json is written
+ if (spec) Object.defineProperty(hint, 'files', { enumerable: true, get: () => (file.imports || []).find((i) => i.spec === spec && i.files?.length)?.files });
+ nests.set(hint, nest);
+ out.push(hint);
+ };
+
+ // React Router v7 config: app/routes.ts with route("path", "routes/file.tsx") / index("routes/home.tsx")
+ if (/(^|\/)routes\.(ts|js|mjs)$/.test(file.path) && /@react-router\/dev\/routes|\b(route|index)\(\s*["']/.test(code)) {
+ const calls = [];
+ for (const m of code.matchAll(/\b(route|index|layout|prefix)\(\s*/g)) {
+ const end = matchClose(code, m.index + m[0].length - 1, '(', ')');
+ if (end < 0) continue;
+ const args = [...code.slice(m.index, end).matchAll(/["'`]([^"'`]*)["'`]/g)].map((x) => x[1]);
+ calls.push({ type: m[1], start: m.index, end, args });
+ }
+ for (const c of calls) {
+ const parents = calls.filter((o) => o !== c && o.start < c.start && o.end > c.end && (o.type === 'route' || o.type === 'prefix')).sort((a, b) => a.start - b.start);
+ let base = '';
+ for (const o of parents) base = joinUrl(base, o.args[0]);
+ const dir = P.dirname(file.path);
+ if (c.type === 'route' && c.args.length >= 2) out.push({ fw: 'react-router', url: joinUrl(base, c.args[0]), target: P.normalize(P.join(dir, c.args[1])) });
+ if (c.type === 'index' && c.args.length >= 1) out.push({ fw: 'react-router', url: base || '/', target: P.normalize(P.join(dir, c.args[0])) });
+ }
+ if (out.length) return out;
+ }
+
+ // JSX: <Route path="x" element={<X/>} />, nested routes join paths
+ if (/<Route\b/.test(code)) {
+ const stack = [];
+ for (const m of code.matchAll(/<Route\b|<\/Route\s*>/g)) {
+ if (m[0].startsWith('</')) {
+ const top = stack.pop();
+ if (top && top.pendingAt != null && !top.done) {
+ const inner = code.slice(top.pendingAt, m.index);
+ if (!/<Route\b/.test(inner)) make('react-router', top.url, pickComponent([...inner.matchAll(/<([A-Z][\w.]*)/g)].map((x) => x[1])), null, stack.length + 1);
+ }
+ continue;
+ }
+ const end = tagEnd(code, m.index + 6);
+ if (end < 0) continue;
+ const attrs = code.slice(m.index + 6, end);
+ const selfClosing = /\/\s*$/.test(attrs);
+ const parent = stack.length ? stack[stack.length - 1].url : '';
+ const pathAttr = /\bpath\s*=\s*(?:["']([^"']*)["']|\{\s*["'`]([^"'`]*)["'`]\s*\})/.exec(attrs);
+ const isIndex = /(^|\s)index(\s|=\{?true|\/|$)/.test(attrs);
+ const url = pathAttr ? joinUrl(parent, pathAttr[1] ?? pathAttr[2]) : (parent || '/');
+ const el = /\belement\s*=\s*\{/.exec(attrs);
+ let comp = null;
+ if (el) { const close = matchClose(attrs, el.index + el[0].length - 1, '{', '}'); comp = pickComponent([...attrs.slice(el.index, close > 0 ? close : undefined).matchAll(/<([A-Z][\w.]*)/g)].map((x) => x[1])); }
+ comp = comp || /\b[Cc]omponent\s*=\s*\{\s*([A-Z][\w$.]*)\s*\}/.exec(attrs)?.[1] || null;
+ if (!comp) { const r = /\brender\s*=\s*\{/.exec(attrs); if (r) comp = pickComponent([...attrs.slice(r.index).matchAll(/<([A-Z][\w.]*)/g)].map((x) => x[1])); }
+ const lazySpec = /\blazy\s*=\s*\{[^}]*import\(\s*["']([^"']+)["']/.exec(attrs)?.[1];
+ if ((pathAttr || isIndex) && (comp || lazySpec)) make('react-router', url, comp, lazySpec, stack.length);
+ if (!selfClosing) stack.push({ url: pathAttr ? url : parent, pendingAt: (pathAttr || isIndex) && !comp && !lazySpec ? end + 1 : null, done: !!comp });
+ }
+ }
+
+ // Route objects: { path: 'x', element: <X/> | component: X | component: () => import('./X.vue'), children: [...] }
+ if (ROUTER_SIGNAL.test(code)) {
+ const recs = [];
+ for (const m of code.matchAll(/\bpath\s*:\s*(["'`])([^"'`]*)\1|\bindex\s*:\s*true\b/g)) {
+ const open = enclosingBrace(code, m.index);
+ if (open < 0) continue;
+ const close = matchClose(code, open, '{', '}');
+ if (close < 0) continue;
+ if (recs.some((r) => r.open === open)) { const r = recs.find((x) => x.open === open); if (m[2] != null) r.path = m[2]; continue; }
+ recs.push({ open, close, path: m[2] ?? null, index: m[2] == null });
+ }
+ for (const r of recs) {
+ const own = maskNested(code.slice(r.open + 1, r.close));
+ if (/\bredirect(To)?\s*:/.test(own) && !/\b(element|component|Component)\s*:/.test(own)) continue;
+ const parents = recs.filter((o) => o !== r && o.open < r.open && o.close > r.close).sort((a, b) => a.open - b.open);
+ let base = '';
+ for (const o of parents) if (o.path != null) base = joinUrl(base, o.path);
+ const url = r.path != null ? joinUrl(base, r.path) : (base || '/');
+ const raw = code.slice(r.open + 1, r.close);
+ let comp = null, spec = null;
+ const el = /\belement\s*:\s*</.exec(own);
+ if (el) comp = pickComponent([...own.slice(el.index).split(/,\s*\n/)[0].matchAll(/<([A-Z][\w.]*)/g)].map((x) => x[1]));
+ comp = comp || /\b(?:component|Component)\s*:\s*([A-Z][\w$.]*)/.exec(own)?.[1] || null;
+ if (!comp) spec = /\b(?:component|Component|lazy|loadComponent|element)\s*:[^,\n]*?import\(\s*["']([^"']+)["']/.exec(raw.replace(/\bchildren\s*:\s*\[[\s\S]*$/, ''))?.[1] || null;
+ if (comp || spec) make(/\.vue["']|createRouter|VueRouter|RouteRecordRaw/.test(code) ? 'vue-router' : /RouterModule|provideRouter|loadComponent/.test(code) ? 'angular' : 'react-router', url, comp, spec, parents.length);
+ }
+ }
+ const best = new Map();
+ for (const h of out) if (!best.has(h.url) || (nests.get(h) || 0) > (nests.get(best.get(h.url)) || 0)) best.set(h.url, h);
+ return out.filter((h) => best.get(h.url) === h);
+}
+
+/** Index of the '>' that closes a JSX opening tag starting at i (skips braces and strings). */
+function tagEnd(s, i) {
+ let depth = 0, q = null;
+ for (; i < s.length; i++) {
+ const c = s[i];
+ if (q) { if (c === '\\') i++; else if (c === q) q = null; continue; }
+ if (c === '"' || c === "'" || c === '`') q = c;
+ else if (c === '{') depth++;
+ else if (c === '}') depth--;
+ else if (c === '>' && depth === 0) return i;
+ }
+ return -1;
+}
+function matchClose(s, i, open, close) {
+ let depth = 0, q = null;
+ for (; i < s.length; i++) {
+ const c = s[i];
+ if (q) { if (c === '\\') i++; else if (c === q) q = null; continue; }
+ if (c === '"' || c === "'" || c === '`') q = c;
+ else if (c === open) depth++;
+ else if (c === close && --depth === 0) return i;
+ }
+ return -1;
+}
+function enclosingBrace(s, i) {
+ let depth = 0;
+ for (let j = i - 1; j >= 0; j--) {
+ const c = s[j];
+ if (c === '}' || c === ']') depth++;
+ else if (c === '{' || c === '[') { if (depth === 0) return c === '{' ? j : -1; depth--; }
+ }
+ return -1;
+}
+/** Blank out nested {...} and [...] so only an object's own keys remain (children arrays disappear). */
+function maskNested(s) {
+ let out = '', depth = 0;
+ for (const c of s) {
+ if (c === '{' || c === '[') { depth++; out += depth === 1 ? c : ' '; continue; }
+ if (c === '}' || c === ']') { out += depth === 1 ? c : ' '; depth = Math.max(0, depth - 1); continue; }
+ out += depth ? (c === '\n' ? '\n' : ' ') : c;
+ }
+ return out;
+}
+
+// ======================= build side =======================
+
+const UI_KIT = /(^|\/)(components\/(ui|common|shared|primitives|base|icons?|layout)|ui|primitives)\//i;
+const UTILITY = /(^|\/)(utils?|helpers?|constants?|types?|typings|styles?|theme|icons?|config|i18n|locales?)(\/|\.[a-z]+$)|\.d\.ts$|(^|\/)(index|globals?)\.(css|scss)$/i;
+const TESTY = /(^|\/)(tests?|__tests__|spec|e2e|cypress|playwright|__mocks__|fixtures|stories)(\/|$)|\.(test|spec|stories)\.[a-z]+$|(^|\/)test_[^/]+\.py$|_test\.(py|go)$/i;
+const DATA_PATH = /(^|\/)(models?|schemas?|entities|entity|db|database|repositor(y|ies)|dao|tables?|prisma|orm)(\/|\.[a-z]+$|_)/i;
+const DB_LABEL = /postgres|mysql|maria|sqlite|mongo|redis|\bdatabase\b(?!s)|\bdb\b|supabase|firebase|firestore|dynamo|prisma|planetscale|cockroach|\bsql\b/i;
+const GET_VERBS = /^(list|get|fetch|load|search|find|look|lookup|check|export|download|preview|calculate|compute|count|show|view|read|poll|ping|generate|validate|verify|resolve|suggest|autocomplete)s?$/;
+const DB_PKG =/sqlalchemy|psycopg|\bpg\b|postgres|mysql|mongo|prisma|redis|sqlite|knex|typeorm|sequelize|drizzle|supabase|firebase|dynamo|gorm|diesel|activerecord/i;
+const AUTHY = /(^|\/)(auth|middlewares?|decorators?|permissions?|security|extensions)(\/|\.[a-z]+$|_)/i;
+const VERBS = new Set('place book reserve claim view read write post put rename renew rotate revoke grant request notify email share attach detach link unlink accept reject decline finalize lock unlock release hold quote estimate count tag untag filter sort report track subscribe unsubscribe join leave follow rate review comment reply flag block activate deactivate suspend resume pause poll ping backfill seed migrate map match swap replace convert recalculate rerun reprocess regenerate recount reorder restock return exchange weigh label fulfill dispatch deliver build deploy upsert insert fill clear flush purge expire invalidate trigger handle ack list get fetch load create add update edit save delete remove search find look check send start stop run mark apply approve cancel set reset preview calculate compute generate refresh submit record adjust issue redeem void close open print scan sync import export upload download move transfer assign archive restore publish unpublish toggle enable disable confirm complete process verify validate log sign register login logout invite connect disconnect wake retry resend bulk merge split duplicate clone schedule queue push pull test rebuild reprice receive pick pack ship refund charge pay collect capture authorize'.split(' '));
+
+export function buildScreens({ graph, scan, root }) {
+ const files = new Map(graph.files.map((f) => [f.p, f]));
+ const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
+ const routes = graph.routes || [];
+ const topOf = (id) => { let n = nodes.get(id), guard = 0; while (n?.parent && guard++ < 50) n = nodes.get(n.parent); return n?.id || id; };
+ const kindsOf = (id) => { const ks = new Set(); let n = nodes.get(id), guard = 0; while (n && guard++ < 50) { ks.add(n.kind); n = nodes.get(n.parent); } return ks; };
+ const appOf = (p) => topOf(files.get(p)?.n);
+ const isTest = (p) => TESTY.test(p) || kindsOf(files.get(p)?.n).has('test');
+ const isData = (p) => kindsOf(files.get(p)?.n).has('data') || DATA_PATH.test(p);
+
+ // ---------- collect screen hints ----------
+ const scanFiles = scan.files || [];
+ const pathsByStem = new Map();
+ const stemOf = (p) => p.replace(/\.(d\.)?[a-z0-9]+$/i, '').replace(/\/index$/, '');
+ for (const f of graph.files) pathsByStem.set(stemOf(f.p), f.p);
+ // which folders use Next.js (to tell a Next pages/ router from a React app's pages/ folder of components)
+ const nextFiles = new Set((scan.extEdges || []).filter((e) => e.pkg === 'npm:next').map((e) => e.from));
+ const usesNext = (p) => { const base = p.replace(/(^|\/)(src\/)?pages\/.*$/, '$1'); for (const f of nextFiles) if (f.startsWith(base)) return true; return false; };
+ const edgesFrom = new Map();
+ for (const e of scan.edges || []) { if (!edgesFrom.has(e.from)) edgesFrom.set(e.from, []); edgesFrom.get(e.from).push(e.to); }
+ const resolveHint = (from, h) => {
+ if (h.target) {
+ if (files.has(h.target)) return h.target;
+ return pathsByStem.get(stemOf(h.target)) || null;
+ }
+ const resolved = (h.files || []).filter((x) => files.has(x) && !/\.d\.ts$/.test(x));
+ if (resolved.length) return resolved[0];
+ if (h.spec) {
+ const tail = h.spec.replace(/^(\.\.?\/)+|^[@~#]\//, '').replace(/\.(tsx|jsx|ts|js|vue|svelte)$/, '');
+ const hit = (edgesFrom.get(from) || []).find((to) => stemOf(to).endsWith(tail));
+ if (hit && files.has(hit)) return hit;
+ return null;
+ }
+ return h.comp ? from : null; // component defined in the router file itself
+ };
+ const routed = []; // router entries: { url, file, fw }
+ const pageHints = [];
+ for (const f of scanFiles) for (const h of f.screens || []) {
+ if (!h || typeof h.url !== 'string') continue;
+ if (h.comp || h.spec || h.target) { const file = resolveHint(f.path, h); if (file) routed.push({ url: h.url, file, fw: h.fw }); }
+ else pageHints.push({ url: h.url, file: f.path, fw: h.fw });
+ }
+ const routedFiles = new Set(routed.map((r) => r.file));
+ const candidates = [...routed];
+ for (const h of pageHints) {
+ if (h.fw === 'next-pages' && (routedFiles.has(h.file) || !usesNext(h.file))) continue;
+ if (h.fw === 'nuxt' && routedFiles.has(h.file)) continue;
+ candidates.push(h);
+ }
+
+ // ---------- link indexes ----------
+ const out = new Map(), indeg = new Map();
+ for (const l of graph.links || []) {
+ if (!out.has(l.a)) out.set(l.a, []);
+ out.get(l.a).push(l);
+ if (l.k === 'import' && l.a.startsWith('f:') && l.b.startsWith('f:')) indeg.set(l.b, (indeg.get(l.b) || 0) + 1);
+ }
+ const appSize = new Map();
+ for (const f of graph.files) { const a = topOf(f.n); appSize.set(a, (appSize.get(a) || 0) + 1); }
+ const noiseFront = (p) => UI_KIT.test(p) || UTILITY.test(p) || (indeg.get('f:' + p) || 0) >= Math.max(6, Math.round((appSize.get(appOf(p)) || 0) * 0.05));
+ const isDb = (n) => DB_PKG.test((n.packages || []).join(' ')) || DB_LABEL.test(n.label);
+ const noiseBack = (p) => !isData(p) && (UTILITY.test(p) || AUTHY.test(p) || (indeg.get('f:' + p) || 0) >= Math.max(10, Math.round((appSize.get(appOf(p)) || 0) * 0.08)));
+
+ // ---------- source regions (to follow only what a screen / an endpoint really uses) ----------
+ const srcCache = new Map();
+ const lines = (p) => {
+ if (srcCache.has(p)) return srcCache.get(p);
+ let v = null;
+ try { if (root) v = fs.readFileSync(path.join(root, p), 'utf8').split('\n'); } catch {}
+ srcCache.set(p, v);
+ return v;
+ };
+ const symRanges = (p) => {
+ const s = (files.get(p)?.s || []).map((x) => ({ name: x[0], line: x[2] })).sort((a, b) => a.line - b.line);
+ return s.map((x, i) => ({ ...x, end: (s[i + 1]?.line || 1e9) - 1 }));
+ };
+ /** Line ranges of a file covered by a focus (null = the whole file). */
+ const rangesFor = (p, focus) => {
+ if (!focus || !focus.size) return null;
+ const rs = symRanges(p).filter((x) => focus.has(x.name)).map((x) => [x.line, x.end]);
+ return rs.length ? rs : null;
+ };
+ const textOf = (p, ranges) => {
+ const ls = lines(p); if (!ls) return null;
+ if (!ranges) return ls.join('\n');
+ return ranges.map(([a, b]) => ls.slice(a - 1, Math.min(b, ls.length)).join('\n')).join('\n');
+ };
+ const inRanges = (line, ranges) => !ranges || ranges.some(([a, b]) => line >= a && line <= b);
+ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ const stemName = (p) => { const b = P.basename(p).replace(/\.[^.]+$/, ''); return /^(index|__init__|route|page)$/.test(b) ? P.basename(P.dirname(p)) : b; };
+ /** Which of a file's outgoing import links are used inside `text`, and what names/members they're used for. */
+ const usedImports = (p, text, filter) => {
+ const res = [];
+ for (const l of out.get('f:' + p) || []) {
+ if (l.k !== 'import' || !l.b.startsWith('f:')) continue;
+ const to = l.b.slice(2);
+ if (filter && !filter(to)) continue;
+ if (text == null) { res.push({ to, focus: namedFocus(l.names) }); continue; }
+ const names = (l.names || []).filter((n) => n !== 'default' && n !== '*');
+ if (names.length) {
+ const hit = names.filter((n) => new RegExp(`(^|[^\\w$.])${esc(n)}\\b`).test(text));
+ if (!hit.length) continue;
+ const members = new Set(), pos = new Map(); // pos: where each member is first used (earlier ranks first)
+ for (const n of hit) for (const m of text.matchAll(new RegExp(`\\b${esc(n)}\\.(\\w+)`, 'g'))) {
+ const k = `${n}.${m[1]}`;
+ members.add(k);
+ if (!pos.has(k)) pos.set(k, m.index / text.length);
+ }
+ res.push({ to, focus: new Set(hit), members: members.size ? members : null, pos });
+ } else {
+ // module import (python `from pkg import module [as alias]`, `import * as alias`): the module's
+ // name or alias in the text means it's used, and what's called on it narrows the focus
+ const stem = stemName(to);
+ const whole = (lines(p) || []).join('\n');
+ const aliases = [stem, ...[...whole.matchAll(new RegExp(`\\b${esc(stem)}["']?\\s+as\\s+([A-Za-z_$][\\w$]*)`, 'g'))].map((m) => m[1]),
+ ...[...whole.matchAll(new RegExp(`\\*\\s+as\\s+([A-Za-z_$][\\w$]*)\\s+from\\s+["'][^"']*${esc(stem)}["']`, 'g'))].map((m) => m[1])];
+ const used = aliases.some((a) => new RegExp(`\\b${esc(a)}\\b`, a === stem ? 'i' : '').test(text));
+ if (!used && !(l.names || []).includes('default')) continue;
+ const members = new Set();
+ for (const a of aliases) for (const m of text.matchAll(new RegExp(`\\b${esc(a)}\\.(\\w+)`, 'g'))) members.add(m[1]);
+ res.push({ to, focus: members.size ? members : null });
+ }
+ }
+ return res;
+ };
+ const namedFocus = (names) => { const n = (names || []).filter((x) => x !== 'default' && x !== '*'); return n.length ? new Set(n) : null; };
+ /** The object member a call line sits in (`productAPI.getAll`), found by walking up to a shallower `key:` line. */
+ const memberAt = (p, line, symLine, symName) => {
+ const ls = lines(p); if (!ls) return null;
+ const ind = (s) => s.match(/^\s*/)[0].length;
+ const KEY = /^\s*(?:async\s+)?(?:get\s+|set\s+)?([A-Za-z_$][\w$]*)\s*(?::|\(|=\s*(?:async\s*)?\()/;
+ const KEYWORDS = /^(if|for|while|switch|catch|return|function|await|typeof|new|else|do|try|with|const|let|var|throw|yield)$/;
+ const keyOf = (s) => { const m = KEY.exec(s); return m && !KEYWORDS.test(m[1]) ? m[1] : null; };
+ const own = line > symLine && keyOf(ls[line - 1] || '');
+ if (own) return `${symName}.${own}`; // one-line member: `list: () => api.get('/x')`
+ // the outermost `key:` / `method(` line above the call, below the symbol's own line
+ let min = ind(ls[line - 1] || ''), found = null;
+ for (let i = line - 1; i > symLine; i--) {
+ const s = ls[i - 1] || ''; if (!s.trim()) continue;
+ const d = ind(s);
+ if (d < min) { const k = keyOf(s); if (k) { found = k; min = d; } }
+ }
+ return found && `${symName}.${found}`;
+ };
+ const symbolAt = (p, line) => { let best = null; for (const r of symRanges(p)) if (r.line <= line) best = r; return best; };
+
+ // ---------- route notes ----------
+ const lc = (s) => s.charAt(0).toLowerCase() + s.slice(1);
+ const routeNote = (r) => {
+ const name = String(r.name || '').trim();
+ if (!name) return 'Asks the server for something';
+ const first = name.split(/\s+/)[0].toLowerCase();
+ const keepCase = /^[A-Z0-9]{2,}/.test(name.split(/\s+/)[0]);
+ const body = keepCase ? name : lc(name);
+ // "Place order" → "Asks the server to place order"; "Product list" → "… for the product list"
+ const verb = r.m === 'GET' ? GET_VERBS.test(first) : VERBS.has(first) || VERBS.has(first.replace(/e?s$/, '')) || (!/s$/.test(first) && name.split(/\s+/).length > 1);
+ return verb ? `Asks the server to ${body}` : `Asks the server for ${/^(the|a|an)\b/i.test(body) ? body : 'the ' + body}`;
+ };
+ const humanUrl = (url) => {
+ const segs = url.split('/').filter(Boolean);
+ if (!segs.length) return 'Home';
+ const last = [...segs].reverse().find((s) => !s.startsWith(':') && s !== '*') || 'Page';
+ const word = last.replace(/[-_]+/g, ' ');
+ return word.charAt(0).toUpperCase() + word.slice(1) + (segs[segs.length - 1].startsWith(':') ? ' (one item)' : '');
+ };
+ const frontNote = (p, depth, parentName) => {
+ const b = P.basename(p);
+ if (/^use[A-Z]/.test(b) || /(^|\/)hooks?\//.test(p)) return 'Logic this screen uses';
+ if (/(^|\/)(contexts?|stores?|state|atoms)\//i.test(p) || /(Context|Provider|Store|[-_.]store|slice|atoms?)\.[jt]sx?$/.test(b)) return 'Shared state this screen uses';
+ if (/^[a-z]/.test(b) && /\.(ts|js|mjs)$/.test(b)) {
+ return (out.get('f:' + p) || []).some((l) => l.k === 'http') || /api|client|service|quer(y|ies)|requests?/i.test(b) ? 'Talks to the server for this screen' : 'Helper code this screen uses';
+ }
+ return depth <= 1 ? 'A component on this screen' : `Part of ${parentName}`;
+ };
+
+ // ---------- behind: walk from the screen's file ----------
+ function behind(page, app, url) {
+ const appKind = (id) => nodes.get(id)?.kind;
+ const frontOk = (p) => files.has(p) && !isTest(p) && (appOf(p) === app || ['ui', 'library', 'feature'].includes(appKind(appOf(p))));
+ // 1) frontend walk with focus (which exports of each file are actually used)
+ const seen = new Map(); // path -> { depth, focus:Set|null(all), members:Set|null, parent }
+ const queue = [{ p: page, depth: 0, focus: null, members: null, parent: null }];
+ // a file reached twice is used for the union of both reasons; null focus/members means "all of it"
+ const union = (a, b) => (a && b ? new Set([...a, ...b]) : null);
+ const merge = (cur, nx) => {
+ const focus = union(cur.focus, nx.focus), members = union(cur.members, nx.members);
+ const changed = (focus?.size ?? -1) !== (cur.focus?.size ?? -1) || (members?.size ?? -1) !== (cur.members?.size ?? -1) || nx.depth < cur.depth;
+ return changed ? { ...cur, focus, members, depth: Math.min(cur.depth, nx.depth) } : null;
+ };
+ let guard = 0;
+ while (queue.length && guard++ < 400) {
+ const it = queue.shift();
+ const prev = seen.get(it.p);
+ // how close to the screen each member is used (the page's own calls rank above a child's)
+ const md = prev?.md || new Map();
+ for (const x of it.members || []) md.set(x, Math.min(md.get(x) ?? 9, it.depth - 1 + (it.pos?.get(x) ?? 0.99) * 0.5));
+ const m = prev ? merge(prev, it) : it;
+ if (prev) prev.md = md;
+ if (m) m.md = md;
+ if (!m) continue;
+ seen.set(it.p, m);
+ const noisy = it.p !== page && noiseFront(it.p);
+ if (noisy || m.depth >= 3) continue; // shared building blocks: we only read their calls
+ const text = textOf(it.p, rangesFor(it.p, m.focus));
+ for (const u of usedImports(it.p, text, frontOk)) {
+ if (u.to === page) continue;
+ queue.push({ p: u.to, depth: m.depth + 1, focus: u.focus, members: u.members || null, pos: u.pos, parent: it.p });
+ }
+ }
+ // 2) requests: HTTP calls from the visited files, inside the parts this screen uses
+ const reqs = new Map(); // routeIndex -> { order, from }
+ let order = 0;
+ const byDepth = [...seen.entries()].sort((a, b) => a[1].depth - b[1].depth);
+ for (const [p, v] of byDepth) {
+ const ranges = rangesFor(p, v.focus);
+ for (const l of out.get('f:' + p) || []) {
+ if (l.k !== 'http' || !l.calls) continue;
+ for (const [ri, line] of l.calls) {
+ if (ri == null || !routes[ri] || !inRanges(line, ranges)) continue;
+ let rank = v.depth + 0.5;
+ const sym = v.focus ? symbolAt(p, line) : null;
+ const mem = sym && memberAt(p, line, sym.line, sym.name);
+ if (mem && v.members && !v.members.has(mem) && [...v.members].some((x) => x.startsWith(sym.name + '.'))) continue;
+ if (mem && v.md?.has(mem)) rank = v.md.get(mem);
+ const prev = reqs.get(ri);
+ if (!prev) reqs.set(ri, { order: order++, from: p, rank });
+ else prev.rank = Math.min(prev.rank, rank);
+ }
+ }
+ }
+ const reqList = [...reqs.entries()].sort((a, b) => a[1].rank - b[1].rank || a[1].order - b[1].order).map(([ri]) => ri);
+
+ // ---------- rank the screen's own parts ----------
+ const urlWords = new Set(url.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 3));
+ const frontData = [...seen.keys()].filter((p) => p !== page && kindsOf(files.get(p)?.n).has('data'));
+ const comps = [...seen.entries()].filter(([p]) => p !== page && !noiseFront(p) && !frontData.includes(p)).map(([p, v]) => {
+ const f = files.get(p);
+ const related = p.toLowerCase().split(/[^a-z0-9]+/).some((w) => w.length > 3 && urlWords.has(w));
+ const calls = (out.get('f:' + p) || []).some((l) => l.k === 'http');
+ const score = (v.depth === 1 ? 3 : v.depth === 2 ? 1.5 : 0) + Math.min(3, Math.log10((f?.loc || 1) + 1)) + (related ? 1.5 : 0) + (calls ? 1 : 0) - Math.min(2, Math.max(0, (indeg.get('f:' + p) || 0) - 2) / 4);
+ return { p, v, score };
+ }).sort((a, b) => b.score - a.score);
+ const BUDGET = 15; // plus the screen itself
+ const nComp = Math.min(4, comps.length);
+ const nReq = Math.min(reqList.length, 4 + Math.min(2, 4 - nComp));
+ const shownReqs = reqList.slice(0, nReq);
+
+ // 3) server side: the handler of each shown request, what its body uses, a few levels down
+ const server = new Map(); // path -> { score, routes:[ri], role:'handler'|'logic', depth }
+ const dataHits = new Map(); // path -> Set(names)
+ const extHits = new Map(); // nodeId -> { count, via }
+ const addExt = (id, via) => { const n = nodes.get(id); if (!n || n.kind !== 'external') return; const e = extHits.get(id) || { count: 0, via }; e.count++; extHits.set(id, e); };
+ const extsOf = (p) => { for (const l of out.get('f:' + p) || []) if (l.b.startsWith('n:')) addExt(l.b.slice(2), p); };
+ const backOk = (p) => files.has(p) && !isTest(p);
+ for (const ri of shownReqs) {
+ const r = routes[ri];
+ const h = r.f;
+ if (!files.has(h)) continue;
+ const hs = server.get(h) || { score: 0, routes: [], role: 'handler', depth: 0 };
+ hs.score += 3; hs.routes.push(ri); server.set(h, hs);
+ const nextRoute = routes.filter((x) => x.f === h && x.l > r.l).reduce((m, x) => Math.min(m, x.l), Infinity);
+ const body = textOf(h, [[r.l, Math.min(nextRoute - 1, r.l + 400)]]);
+ extsOf(h);
+ const q = usedImports(h, body, backOk).map((u) => ({ ...u, depth: 1, via: ri }));
+ const visited = new Set([h]);
+ while (q.length) {
+ const u = q.shift();
+ if (visited.has(u.to)) continue;
+ visited.add(u.to);
+ if (isData(u.to)) {
+ const set = dataHits.get(u.to) || new Set();
+ for (const n of u.focus || []) set.add(n);
+ dataHits.set(u.to, set);
+ extsOf(u.to);
+ continue;
+ }
+ if (noiseBack(u.to)) continue;
+ const s = server.get(u.to) || { score: 0, routes: [], role: 'logic', depth: u.depth };
+ s.score += 2 / u.depth; if (!s.routes.includes(u.via)) s.routes.push(u.via); s.depth = Math.min(s.depth, u.depth);
+ server.set(u.to, s);
+ extsOf(u.to);
+ if (u.depth >= 3) continue;
+ const text = textOf(u.to, rangesFor(u.to, u.focus));
+ for (const v of usedImports(u.to, text, backOk)) q.push({ ...v, depth: u.depth + 1, via: u.via });
+ }
+ }
+ // outside services the screen itself talks to (payment SDKs, hosted APIs), and data it reads
+ // directly (full-stack frameworks: a page or server action that queries the database)
+ for (const p of seen.keys()) extsOf(p);
+ for (const p of frontData) if (!dataHits.has(p)) dataHits.set(p, new Set());
+
+ const servers = [...server.entries()].sort((a, b) => (a[1].role === 'handler' ? 0 : 1) - (b[1].role === 'handler' ? 0 : 1) || b[1].score - a[1].score);
+ const datas = [...dataHits.entries()].sort((a, b) => b[1].size - a[1].size);
+ const exts = [...extHits.entries()].sort((a, b) => b[1].count - a[1].count);
+
+ // ---------- cap: screen → components → requests → server → data → outside ----------
+ const caps = { comp: nComp, server: Math.min(3, servers.length), data: Math.min(2, datas.length), ext: Math.min(2, exts.length) };
+ let spare = BUDGET - nReq - caps.comp - caps.server - caps.data - caps.ext;
+ const most = { comp: 6, server: 5, ext: 3, data: 3 };
+ const avail = { comp: comps.length, server: servers.length, ext: exts.length, data: datas.length };
+ for (const k of ['comp', 'server', 'ext', 'data']) { const extra = Math.max(0, Math.min(spare, Math.min(most[k], avail[k]) - caps[k])); caps[k] += extra; spare -= extra; }
+
+ const name = (p) => files.get(p)?.name || stemName(p);
+ const items = [{ id: 'f:' + page, note: 'The screen itself', kind: 'screen' }];
+ for (const c of comps.slice(0, caps.comp)) items.push({ id: 'f:' + c.p, note: frontNote(c.p, c.v.depth, name(c.v.parent || page)), kind: 'part' });
+ for (const ri of shownReqs) items.push({ id: 'r:' + ri, note: routeNote(routes[ri]), kind: 'request' });
+ for (const [p, s] of servers.slice(0, caps.server)) {
+ const rn = s.routes.map((ri) => routes[ri]?.name).filter(Boolean);
+ const first = rn[0] ? `“${rn[0]}”` : 'these requests';
+ const more = rn.length > 1 ? ` and ${rn.length - 1} more` : '';
+ items.push({ id: 'f:' + p, note: s.role === 'handler' ? `Server code that handles ${first}${more}` : `Does the work behind ${first}${more}`, kind: 'server' });
+ }
+ for (const [p, names] of datas.slice(0, caps.data)) {
+ const ns = [...names].filter((n) => /^[A-Z][a-z]/.test(n)).sort((a, b) => a.length - b.length).slice(0, 2).map((n) => n.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase());
+ items.push({ id: 'f:' + p, note: ns.length ? `Keeps the ${ns.join(' and ')} records` : 'Saved data this reads or changes', kind: 'data' });
+ }
+ for (const [id, e] of exts.slice(0, caps.ext)) {
+ const n = nodes.get(id);
+ items.push({ id: 'n:' + id, note: isDb(n) ? 'Where the data is kept' : `Outside service, used by ${name(e.via)}`, kind: 'outside' });
+ }
+ return items;
+ }
+
+ // ---------- assemble ----------
+ const screens = new Map();
+ for (const c of candidates) {
+ if (!files.has(c.file) || isTest(c.file)) continue;
+ const app = appOf(c.file);
+ const url = normalizeUrl(c.url) || '/';
+ const id = `screen:${app}:${url}`;
+ if (screens.has(id)) continue;
+ const f = files.get(c.file);
+ screens.set(id, { id, url, file: c.file, app, fw: c.fw, name: f.auto && /\b(page|index|route)\b/i.test(f.name) ? humanUrl(url) : f.name || humanUrl(url), description: f.d || '' });
+ }
+ const list = [...screens.values()].sort((a, b) => a.app.localeCompare(b.app) || a.url.localeCompare(b.url));
+ for (const s of list) {
+ try { s.behind = behind(s.file, s.app, s.url); } catch (e) { s.behind = [{ id: 'f:' + s.file, note: 'The screen itself', kind: 'screen' }]; }
+ }
+ return list;
+}
diff --git a/skills/floorplan/scripts/open.mjs b/skills/floorplan/scripts/open.mjs
new file mode 100644
index 0000000..d1c2d13
--- /dev/null
+++ b/skills/floorplan/scripts/open.mjs
@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Show the map to the user after a build or refresh. Reuses this map's server if it's running (open tabs
+// have already reloaded themselves), restarts it if serve.mjs changed, otherwise starts it in the
+// background and opens a browser tab. Prints the URL and how to stop it.
+// usage: node open.mjs [root] [--no-open] [--port N] [--model M] [--claude PATH]
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { parseArgs, mapDir } from './lib/common.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const dir = mapDir(root);
+const serveFile = path.join(dir, 'serve.mjs');
+const stateFile = path.join(dir, '.cache', 'server.json');
+const rel = path.relative(process.cwd(), dir).replace(/\\/g, '/') || '.';
+const IDLE_MINUTES = 120;
+
+if (!fs.existsSync(path.join(dir, 'index.html')) || !fs.existsSync(serveFile)) {
+ console.error('✗ No built map here yet. Run build.mjs first.');
+ process.exit(1);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const readState = () => { try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch { return null; } };
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+async function api(s, p) {
+ try {
+ const r = await fetch(s.url + p, { headers: { 'x-floorplan-token': s.token }, signal: AbortSignal.timeout(3000) });
+ return r.ok ? await r.json() : null;
+ } catch { return null; }
+}
+function openBrowser(u) {
+ const [cmd, a] = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', u]] : process.platform === 'darwin' ? ['open', [u]] : ['xdg-open', [u]];
+ try { spawn(cmd, a, { stdio: 'ignore', detached: true, windowsHide: true }).unref(); return true; } catch { return false; }
+}
+const hash = crypto.createHash('sha1').update(fs.readFileSync(serveFile)).digest('hex').slice(0, 12);
+
+let s = readState();
+let status = s?.pid && alive(s.pid) ? await api(s, '/api/status') : null;
+let restarted = false;
+const hadTabs = status?.tabs > 0;
+
+if (status && status.hash !== hash) {
+ // a newer serve.mjs came with this build: restart so the map gets it; open tabs reconnect and reload
+ try { process.kill(s.pid); } catch {}
+ for (let i = 0; i < 20 && alive(s.pid); i++) await sleep(150);
+ status = null;
+ restarted = true;
+}
+
+if (!status) {
+ const pass = ['port', 'model', 'claude'].flatMap((k) => (args[k] ? ['--' + k, String(args[k])] : []));
+ if (!args.port && s?.port) pass.push('--port', String(s.port)); // keep the address people have open
+ fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+ const log = fs.openSync(path.join(dir, '.cache', 'server.log'), 'w');
+ const prev = s?.pid;
+ spawn(process.execPath, [serveFile, '--no-open', '--idle-exit', String(IDLE_MINUTES), ...pass], {
+ cwd: root, detached: true, stdio: ['ignore', log, log], windowsHide: true,
+ }).unref();
+ // finding the Claude CLI takes a few seconds before the server listens
+ for (let i = 0; i < 100; i++) {
+ await sleep(200);
+ const n = readState();
+ if (n?.pid && n.pid !== prev && alive(n.pid)) { s = n; status = await api(s, '/api/status'); if (status) break; }
+ }
+ if (!status) {
+ console.error(`✗ The map server didn't start. Its log is in ${rel}/.cache/server.log. The map still opens as a file: ${rel}/index.html`);
+ process.exit(1);
+ }
+ // tabs from before a restart come back on their own within a few seconds
+ if (restarted && hadTabs) for (let i = 0; i < 50 && !(status?.tabs > 0); i++) { await sleep(200); status = await api(s, '/api/status'); }
+}
+
+const health = await api(s, '/api/health');
+let shown;
+if (status.tabs > 0) shown = `already open in ${status.tabs === 1 ? 'a browser tab' : status.tabs + ' browser tabs'}, which reloaded with the latest map`;
+else if (args['no-open']) shown = 'not opened in a browser (--no-open): open the URL yourself';
+else shown = openBrowser(s.url) ? 'opened in the browser' : 'could not open a browser: open the URL yourself';
+
+console.log(`FLOORPLAN ${s.url} (${shown})`);
+console.log(health?.cli
+ ? `ASK works: questions run through the Claude Code CLI${health.version ? ' ' + health.version : ''}`
+ : 'ASK needs the Claude Code CLI, which was not found; the map itself works (https://docs.claude.com/en/docs/claude-code)');
+console.log(`SERVER runs in the background, updates open tabs when the map is rebuilt, and stops ${IDLE_MINUTES / 60} hours after the last tab closes. Stop it now: node ${rel}/serve.mjs --stop`);
diff --git a/skills/floorplan/scripts/recent.mjs b/skills/floorplan/scripts/recent.mjs
new file mode 100644
index 0000000..e028e04
--- /dev/null
+++ b/skills/floorplan/scripts/recent.mjs
@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Facts for marking "recent work" on the map: what changed since the last map (from refresh.mjs),
+// uncommitted changes, and recent commits, each tied to the card it shows up as. Claude adds the why
+// (what the user asked for) and writes floorplan/recent-work.json. Read-only.
+// usage: node recent.mjs [root] [--days 7]
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, parseArgs, mapDir } from './lib/common.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const dir = mapDir(root);
+const graphFile = path.join(dir, 'graph.json');
+if (!fs.existsSync(graphFile)) { console.error('✗ No floorplan/graph.json. Run build.mjs first.'); process.exit(1); }
+const G = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const changes = readJson(path.join(dir, '.cache', 'changes.json'));
+const current = readJson(path.join(dir, 'recent-work.json'));
+
+const files = new Map(G.files.map((f) => [f.p, f]));
+const labels = new Map(G.nodes.map((n) => [n.id, n.label]));
+const routesOf = new Map();
+for (const r of G.routes) { if (!routesOf.has(r.f)) routesOf.set(r.f, []); routesOf.get(r.f).push(`${r.m} ${r.p}`); }
+const card = (p) => {
+ const f = files.get(p);
+ if (!f) return '(not on the map)';
+ const rs = routesOf.get(p) || [];
+ return `"${f.name}" in ${labels.get(f.n) || f.n}${rs.length ? ` · ${rs.length} endpoint(s)` : ''}`;
+};
+const L = [];
+const MAX = 40;
+const list = (rows) => { rows.slice(0, MAX).forEach((r) => L.push(' ' + r)); if (rows.length > MAX) L.push(` … +${rows.length - MAX} more`); };
+
+L.push(`RECENT WORK FACTS for ${G.project.name} (map built ${G.meta.generatedAt})`);
+L.push(current?.tasks
+ ? `Current recent-work.json: ${current.tasks.length} task(s), updated ${current.updatedAt || 'unknown'}. Rewrite it: it replaces the previous highlights.`
+ : 'No recent-work.json yet.');
+
+if (changes) {
+ L.push('', `CHANGED SINCE THE PREVIOUS MAP (${changes.since} → ${changes.at})`);
+ const rows = [
+ ...changes.files.new.map((p) => `new ${p} → ${card(p)}`),
+ ...changes.files.edited.map((p) => `edited ${p} → ${card(p)}`),
+ ...changes.files.moved.map((m) => `moved ${m.from} → ${m.to} → ${card(m.to)}`),
+ ...changes.files.deleted.map((p) => `deleted ${p} (gone from the map; mention it in the task summary)`),
+ ...changes.routes.new.map((k) => `new endpoint ${k}`),
+ ...changes.routes.moved.map((m) => `re-pathed endpoint ${m.from} → ${m.to}`),
+ ...changes.routes.removed.map((k) => `removed endpoint ${k}`),
+ ];
+ if (rows.length) list(rows); else L.push(' nothing');
+}
+
+const since = changes?.since || current?.updatedAt || new Date(Date.now() - (Number(args.days) || 7) * 86400000).toISOString();
+for (const r of G.meta.repos || []) {
+ const abs = path.join(root, r.path);
+ const prefix = r.path === '.' ? '' : r.path + '/';
+ const status = (git(abs, ['status', '--porcelain=v1', '-uall']) || '').split('\n').filter(Boolean);
+ const log = (git(abs, ['log', `--since=${since}`, '--max-count=20', '--no-merges', '--name-only', '--date=short', '--format=@@%h %ad %s']) || '').trim();
+ if (!status.length && !log) continue;
+ L.push('', `REPO ${r.path === '.' ? G.meta.rootName : r.path}`);
+ if (status.length) {
+ L.push(' uncommitted:');
+ list(status.map((s) => { const p = prefix + s.slice(3).replace(/^.* -> /, '').replace(/"/g, ''); return ` ${s.slice(0, 2).trim().padEnd(2)} ${p} → ${card(p)}`; }));
+ }
+ if (log) {
+ L.push(` commits since ${since.slice(0, 10)}:`);
+ for (const block of log.split('@@').filter(Boolean)) {
+ const [head, ...paths] = block.trim().split('\n').filter(Boolean);
+ L.push(` ${head}`);
+ paths.slice(0, 8).forEach((p) => L.push(` ${prefix + p} → ${card(prefix + p)}`));
+ if (paths.length > 8) L.push(` … +${paths.length - 8} more files`);
+ }
+ }
+}
+
+L.push('', 'Write floorplan/recent-work.json (refs: a file path, a node id, or "METHOD /path"; see references/schema.md#recent-work):',
+ ' { "tasks": [ { "title": "…", "request": "what the user asked for", "summary": "what was done toward it, and where it stands",',
+ ' "items": [ { "ref": "<file path>", "change": "changed|new", "note": "what changed here, and how it serves the request" } ] } ] }',
+ 'Then run build.mjs. Use { "tasks": [] } when nothing was worked on.');
+console.log(L.join('\n'));
diff --git a/skills/floorplan/scripts/refresh.mjs b/skills/floorplan/scripts/refresh.mjs
new file mode 100644
index 0000000..1a5b031
--- /dev/null
+++ b/skills/floorplan/scripts/refresh.mjs
@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// floorplan refresh: bring an existing map up to date without redoing the whole thing.
+// Re-scans, compares against the last build (graph.json), reconciles descriptions/*.json
+// (renames carried over, deleted entries removed, entries whose exports/routes changed flagged
+// with "review"), rebuilds, and reports exactly what is left for Claude to look at.
+//
+// usage: node refresh.mjs [root]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { compileGlob, parseArgs, mapDir } from './lib/common.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const outDir = mapDir(root);
+const graphFile = path.join(outDir, 'graph.json');
+const archFile = path.join(outDir, 'architecture.json');
+if (!fs.existsSync(graphFile) || !fs.existsSync(archFile)) {
+ console.log('No existing map here (floorplan/graph.json + architecture.json). Do a full run instead.');
+ process.exit(0);
+}
+const old = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
+const arch = JSON.parse(fs.readFileSync(archFile, 'utf8'));
+
+// ---------- 1. re-scan (no tokens) ----------
+const node = process.execPath;
+execFileSync(node, [path.join(HERE, 'scan.mjs'), root], { stdio: ['ignore', 'ignore', 'inherit'] });
+const scan = JSON.parse(fs.readFileSync(path.join(outDir, '.cache', 'scan.json'), 'utf8'));
+
+const include = Array.isArray(arch.include) ? arch.include : ['code'];
+const ignore = (arch.ignore || []).map(compileGlob);
+const now = new Map(scan.files.filter((f) => include.includes(f.category) && !ignore.some((g) => g.test(f.path))).map((f) => [f.path, f]));
+const before = new Map(old.files.map((f) => [f.p, f]));
+
+// ---------- 2. diff files ----------
+const added = [...now.keys()].filter((p) => !before.has(p));
+const removed = [...before.keys()].filter((p) => !now.has(p));
+const edited = [...now.keys()].filter((p) => before.has(p) && before.get(p).h && now.get(p).h !== before.get(p).h);
+const digestChanged = edited.filter((p) => before.get(p).sig && now.get(p).sig !== before.get(p).sig);
+
+// renames: same content, or same file name + same digest
+const renames = new Map();
+const addedLeft = new Set(added);
+for (const r of removed) {
+ const o = before.get(r);
+ let match = o.h ? [...addedLeft].find((a) => now.get(a).h === o.h) : null;
+ if (!match) {
+ const cands = [...addedLeft].filter((a) => path.posix.basename(a) === path.posix.basename(r) && (!o.sig || now.get(a).sig === o.sig));
+ if (cands.length === 1) match = cands[0];
+ }
+ if (match) { renames.set(r, match); addedLeft.delete(match); }
+}
+const deleted = removed.filter((r) => !renames.has(r));
+const created = [...addedLeft];
+
+// what changed in a file's exports/routes, for the review note
+const oldRoutesByFile = new Map();
+for (const r of old.routes || []) { if (!oldRoutesByFile.has(r.f)) oldRoutesByFile.set(r.f, []); oldRoutesByFile.get(r.f).push(`${r.m} ${r.p}`); }
+const newRoutesByFile = new Map();
+for (const r of scan.routes) { if (!newRoutesByFile.has(r.file)) newRoutesByFile.set(r.file, []); newRoutesByFile.get(r.file).push(`${r.method} ${r.path}`); }
+function changeNote(p, prevPath = p) {
+ const o = before.get(prevPath), n = now.get(p);
+ const os = new Set((o.s || []).map((s) => s[0])), ns = new Set((n.symbols || []).map((s) => s.name));
+ const plus = [...ns].filter((x) => !os.has(x)), minus = [...os].filter((x) => !ns.has(x));
+ const orr = new Set(oldRoutesByFile.get(prevPath) || []), nr = new Set(newRoutesByFile.get(p) || []);
+ const rPlus = [...nr].filter((x) => !orr.has(x)).length, rMinus = [...orr].filter((x) => !nr.has(x)).length;
+ const parts = [];
+ if (plus.length) parts.push(`new exports: ${plus.slice(0, 6).join(', ')}${plus.length > 6 ? '…' : ''}`);
+ if (minus.length) parts.push(`removed exports: ${minus.slice(0, 6).join(', ')}${minus.length > 6 ? '…' : ''}`);
+ if (rPlus) parts.push(`${rPlus} new route(s)`);
+ if (rMinus) parts.push(`${rMinus} removed route(s)`);
+ if (!parts.length) parts.push('docstring or structure changed');
+ return parts.join('; ');
+}
+
+// ---------- 3. diff routes ----------
+const oldRouteKeys = new Map((old.routes || []).map((r) => [`${r.m} ${r.p}`, r]));
+const newRouteKeys = new Map(scan.routes.map((r) => [`${r.method} ${r.path}`, r]));
+const routeMoves = new Map(); // old key -> new key (same handler in the same / renamed file)
+const goneRoutes = [...oldRouteKeys.keys()].filter((k) => !newRouteKeys.has(k));
+const newRoutes = new Set([...newRouteKeys.keys()].filter((k) => !oldRouteKeys.has(k)));
+for (const k of goneRoutes) {
+ const o = oldRouteKeys.get(k);
+ const file = renames.get(o.f) || o.f;
+ const m = [...newRoutes].find((nk) => { const n = newRouteKeys.get(nk); return n.file === file && o.h && n.handler === o.h; });
+ if (m) { routeMoves.set(k, m); newRoutes.delete(m); }
+}
+
+// ---------- 4. reconcile descriptions ----------
+const descDir = path.join(outDir, 'descriptions');
+let carried = 0, pruned = 0, flagged = 0, routeCarried = 0, routePruned = 0;
+const digestSet = new Set(digestChanged);
+if (fs.existsSync(descDir)) {
+ for (const name of fs.readdirSync(descDir).filter((n) => n.endsWith('.json'))) {
+ const fp = path.join(descDir, name);
+ let d;
+ try { d = JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { continue; }
+ let changed = false;
+ const filesOut = {};
+ for (const [p, v] of Object.entries(d.files || {})) {
+ if (renames.has(p)) {
+ const np = renames.get(p);
+ filesOut[np] = now.get(np).sig !== before.get(p).sig ? { ...v, review: `moved from ${p}; ${changeNote(np, p)}` } : v;
+ carried++; changed = true;
+ } else if (deleted.includes(p)) { pruned++; changed = true; }
+ else if (digestSet.has(p) && v.description) { filesOut[p] = { ...v, review: changeNote(p) }; flagged++; changed = true; }
+ else filesOut[p] = v;
+ }
+ const routesOut = {};
+ for (const [k, v] of Object.entries(d.routes || {})) {
+ if (routeMoves.has(k)) { routesOut[routeMoves.get(k)] = { ...v, review: `path changed from ${k}` }; routeCarried++; changed = true; }
+ else if (!newRouteKeys.has(k) && oldRouteKeys.has(k)) { routePruned++; changed = true; }
+ else routesOut[k] = v;
+ }
+ if (changed) {
+ const outObj = { files: filesOut, ...(Object.keys(routesOut).length ? { routes: routesOut } : {}) };
+ if (!Object.keys(filesOut).length && !Object.keys(routesOut).length) fs.unlinkSync(fp);
+ else fs.writeFileSync(fp, JSON.stringify(outObj, null, 2) + '\n');
+ }
+ }
+}
+
+// what changed since the last build, for recent.mjs (marking recent work on the map)
+fs.writeFileSync(path.join(outDir, '.cache', 'changes.json'), JSON.stringify({
+ since: old.meta.generatedAt, at: new Date().toISOString(),
+ files: { new: created, edited: edited.filter((p) => !created.includes(p)), moved: [...renames].map(([a, b]) => ({ from: a, to: b })), deleted },
+ routes: { new: [...newRoutes], removed: goneRoutes.filter((k) => !routeMoves.has(k)), moved: [...routeMoves].map(([a, b]) => ({ from: a, to: b })) },
+}, null, 2));
+
+// ---------- 5. rebuild (no tokens) ----------
+let buildOut = '';
+let buildOk = true;
+try { buildOut = execFileSync(node, [path.join(HERE, 'build.mjs'), root], { encoding: 'utf8' }); }
+catch (e) { buildOut = (e.stdout || '') + (e.stderr || ''); buildOk = false; }
+
+// ---------- 6. report ----------
+const since = new Date(old.meta.generatedAt);
+const L = [];
+L.push(`Floorplan refresh — last map ${since.toLocaleString()}`);
+L.push(` files +${created.length} new · −${deleted.length} deleted · ${renames.size} moved/renamed (descriptions carried over) · ${edited.length} edited, ${digestChanged.length} with changed exports/routes`);
+L.push(` routes +${newRoutes.size} new · −${goneRoutes.length - routeMoves.size} removed · ${routeMoves.size} re-pathed (descriptions carried over)`);
+L.push(` descriptions: ${carried + routeCarried} carried over, ${pruned + routePruned} removed, ${flagged} flagged for review`);
+if (!before.values().next().value?.h) L.push(' (the previous map predates content fingerprints, so edits since then could not be detected; future refreshes will)');
+const byDir = new Map();
+for (const p of created) { const d = p.split('/').slice(0, -1).join('/'); byDir.set(d, (byDir.get(d) || 0) + 1); }
+if (byDir.size) {
+ L.push(' new files by directory:');
+ for (const [d, c] of [...byDir.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12)) L.push(` ${String(c).padStart(4)} ${d}/`);
+}
+L.push('');
+L.push('BUILD');
+L.push(buildOut.split('\n').filter((l) => /^(✗|!| - |ASSIGNMENT| unassigned| |DESCRIPTIONS| Run describe|✓)/.test(l)).slice(0, 40).join('\n'));
+L.push('');
+const todo = [];
+if (!buildOk) todo.push('Fix the build errors above in architecture.json (usually a flow step or annotation pointing at a deleted file), then run build.mjs.');
+if (/unassigned, by directory/.test(buildOut)) todo.push('New files landed outside every node: add globs (or a node) in architecture.json for the directories listed under "unassigned".');
+if (/Run describe/.test(buildOut)) todo.push('Run describe.mjs: it writes worksheets for only the new and flagged items. Fill them in (drop each "review" field once the entry is accurate), then run build.mjs.');
+if (created.length + deleted.length > Math.max(20, before.size * 0.15)) todo.push('This is a large change: re-read the summaries of the modules that gained or lost many files, and check the flows still hold.');
+todo.push('Mark recent work: run recent.mjs, rewrite recent-work.json for what was just worked on (an empty "tasks" list if nothing was), then run build.mjs.');
+L.push('NEXT');
+todo.forEach((t, i) => L.push(` ${i + 1}. ${t}`));
+console.log(L.join('\n'));
diff --git a/skills/floorplan/scripts/scan.mjs b/skills/floorplan/scripts/scan.mjs
new file mode 100644
index 0000000..2c48f0a
--- /dev/null
+++ b/skills/floorplan/scripts/scan.mjs
@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// floorplan scanner: discover every repo under a codebase root, list files, extract imports,
+// symbols and HTTP routes/calls, resolve them, and write floorplan/.cache/scan.json.
+// Prints a compact summary meant to be read by Claude (the JSON itself can be large).
+//
+// usage: node scan.mjs [root] [--out <file>] [--include-worktrees] [--max-file-kb 512]
+
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { discover, gitFiles, gitInfo, classify, toPosix, parseArgs, fmtNum, HARD_IGNORE_DIRS, MAP_DIR, LEGACY_MAP_DIR, isMapDir, mapDir, keepOutOfGit } from './lib/common.mjs';
+import { extract } from './lib/extract.mjs';
+import { findIssues } from './lib/health.mjs';
+import { findScreens } from './lib/screens.mjs';
+import { createResolver } from './lib/resolve.mjs';
+import { resolveRoutes, matchCalls } from './lib/routes.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const root = path.resolve(args._[0] || '.');
+const outDir = args.out ? path.dirname(path.dirname(path.resolve(args.out))) : mapDir(root);
+const outFile = path.resolve(args.out || path.join(outDir, '.cache', 'scan.json'));
+const maxBytes = (Number(args['max-file-kb']) || 512) * 1024;
+const t0 = Date.now();
+const hash = (s) => createHash('sha1').update(s).digest('hex').slice(0, 12);
+
+// ---------- 1. discover repos and files ----------
+const found = discover(root, { includeWorktrees: !!args['include-worktrees'] });
+const repos = [];
+const fileList = []; // { path, repo }
+const seen = new Set();
+// map folders (ours, or an old show-code/ one) are output, not code
+const mapDirs = new Map();
+const inMap = (p) => {
+ const segs = p.split('/');
+ for (let i = 0; i < segs.length - 1; i++) {
+ if (segs[i] !== MAP_DIR && segs[i] !== LEGACY_MAP_DIR) continue;
+ const d = segs.slice(0, i + 1).join('/');
+ if (!mapDirs.has(d)) mapDirs.set(d, isMapDir(path.join(root, d)));
+ if (mapDirs.get(d)) return true;
+ }
+ return false;
+};
+const ignoredByDir = (p) => p.split('/').some((seg) => HARD_IGNORE_DIRS.has(seg)) || inMap(p);
+
+for (const r of found.repos) {
+ const listed = gitFiles(r.abs);
+ const info = gitInfo(r.abs);
+ const prefix = r.path === '.' ? '' : r.path + '/';
+ let count = 0;
+ for (const f of listed || []) {
+ const p = prefix + f;
+ if (seen.has(p) || ignoredByDir(p)) continue;
+ seen.add(p);
+ fileList.push({ path: p, repo: r.path });
+ count++;
+ }
+ repos.push({ path: r.path, name: path.basename(r.abs), ...info, files: count, ...(r.worktreeOf ? { worktreeOf: toPosix(r.worktreeOf) } : {}) });
+}
+for (const p of found.loose) if (!seen.has(p) && !inMap(p)) { seen.add(p); fileList.push({ path: p, repo: null }); }
+
+// ---------- 2. classify, read, extract ----------
+const files = [];
+for (const { path: p, repo } of fileList) {
+ const abs = path.join(root, p);
+ let st;
+ try { st = fs.statSync(abs); } catch { continue; }
+ if (!st.isFile()) continue;
+ const { category, lang } = classify(p, st.size);
+ const f = { path: p, repo, category, lang, bytes: st.size, loc: 0 };
+ if ((category === 'code' || category === 'config' || category === 'docs') && st.size <= maxBytes) {
+ let src;
+ try { src = fs.readFileSync(abs, 'utf8'); } catch { src = ''; }
+ if (src.includes('\u0000')) { f.category = 'asset'; files.push(f); continue; }
+ f.loc = src.split('\n').filter((l) => l.trim()).length;
+ if (category === 'code' && src.length) {
+ try { Object.assign(f, extract(src, lang, p)); } catch (e) { f.extractError = String(e.message || e); }
+ // h: exact content. sig: the parts a description depends on (exports, routes, docstring),
+ // so edits inside function bodies don't mark a file's description as stale.
+ f.h = hash(src);
+ f.sig = hash(JSON.stringify([(f.symbols || []).map((s) => s.name).sort(), (f.routes || []).map((r) => `${r.method} ${r.path}`).sort(), f.doc || '']));
+ }
+ // extension hooks: per-file health findings (lib/health.mjs) and app screens (lib/screens.mjs)
+ if (src.length) {
+ try { const iss = findIssues(src, f); if (iss?.length) f.issues = iss; } catch (e) { f.healthError = String(e.message || e); }
+ try { const scr = findScreens(src, f); if (scr?.length) f.screens = scr; } catch (e) { f.screensError = String(e.message || e); }
+ }
+ } else if (category === 'code') {
+ f.tooLarge = true;
+ }
+ files.push(f);
+}
+
+// ---------- 3. resolve imports ----------
+const resolve = createResolver(root, files);
+const edges = [];
+const externals = new Map(); // `${eco}:${name}` -> { eco, name, count, files:Set }
+const extEdges = [];
+let unresolved = 0;
+for (const f of files) {
+ if (!f.imports) continue;
+ for (const imp of f.imports) {
+ const res = resolve(f, imp);
+ if (res.file || res.files) {
+ imp.files = res.files || [res.file];
+ const targets = res.files ? res.files.map((t, i) => [t, res.names?.[i]]) : [[res.file, null]];
+ for (const [to, subName] of targets) {
+ if (to === f.path) continue;
+ edges.push({ from: f.path, to, names: subName ? [] : (imp.names || []), line: imp.line, ...(imp.dynamic ? { dynamic: true } : {}) });
+ }
+ } else if (res.external) {
+ const key = `${res.eco}:${res.external}`;
+ if (!externals.has(key)) externals.set(key, { eco: res.eco, name: res.external, count: 0, files: new Set() });
+ const e = externals.get(key);
+ e.count++;
+ e.files.add(f.path);
+ extEdges.push({ from: f.path, pkg: key });
+ } else if (res.unresolved) unresolved++;
+ }
+}
+// merge duplicate edges (same from/to)
+const edgeMap = new Map();
+for (const e of edges) {
+ const k = e.from + '\u0000' + e.to;
+ const prev = edgeMap.get(k);
+ if (prev) { prev.names = [...new Set([...prev.names, ...e.names])]; prev.count++; }
+ else edgeMap.set(k, { ...e, count: 1 });
+}
+
+// ---------- 4. routes and HTTP calls ----------
+const routes = resolveRoutes(files);
+const http = matchCalls(files, routes);
+const hosts = [];
+for (const f of files) for (const h of f.hosts || []) hosts.push({ from: f.path, host: h.host, line: h.line });
+
+// ---------- 5. write scan.json ----------
+const scan = {
+ version: 1,
+ generatedAt: new Date().toISOString(),
+ root: toPosix(root),
+ rootName: path.basename(root),
+ repos,
+ skipped: found.skipped,
+ files: files.map((f) => ({
+ path: f.path, repo: f.repo, category: f.category, lang: f.lang, loc: f.loc, bytes: f.bytes,
+ ...(f.doc ? { doc: f.doc } : {}),
+ ...(f.h ? { h: f.h, sig: f.sig } : {}),
+ ...(f.symbols?.length ? { symbols: f.symbols } : {}),
+ ...(f.tooLarge ? { tooLarge: true } : {}),
+ ...(f.issues ? { issues: f.issues } : {}),
+ ...(f.screens ? { screens: f.screens } : {}),
+ })),
+ edges: [...edgeMap.values()].map(({ from, to, names, count, dynamic }) => ({ from, to, ...(names.length ? { names } : {}), ...(count > 1 ? { count } : {}), ...(dynamic ? { dynamic } : {}) })),
+ externals: [...externals.values()].map((e) => ({ id: `${e.eco}:${e.name}`, eco: e.eco, name: e.name, imports: e.count, files: e.files.size })),
+ extEdges: dedupeExt(extEdges),
+ routes,
+ http,
+ hosts,
+};
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+fs.writeFileSync(outFile, JSON.stringify(scan));
+if (!args.out) keepOutOfGit(outDir);
+
+function dedupeExt(list) {
+ const m = new Map();
+ for (const e of list) { const k = e.from + '|' + e.pkg; m.set(k, (m.get(k) || 0) + 1); }
+ return [...m.entries()].map(([k, count]) => { const [from, pkg] = k.split('|'); return { from, pkg, count }; });
+}
+
+// ---------- 6. summary for Claude ----------
+const code = scan.files.filter((f) => f.category === 'code');
+const out = [];
+const line = (s = '') => out.push(s);
+line(`Floorplan scan of ${scan.rootName} (${((Date.now() - t0) / 1000).toFixed(1)}s) -> ${toPosix(path.relative(root, outFile))}`);
+line();
+line(`REPOS (${repos.length})`);
+for (const r of repos) line(` ${r.path.padEnd(40)} ${String(r.files).padStart(6)} files ${r.branch || '-'}@${(r.head || '').slice(0, 8)}${r.worktreeOf ? ' (worktree)' : ''}`);
+const looseCount = scan.files.filter((f) => f.repo === null).length;
+if (looseCount) line(` (outside any repo)${''.padEnd(22)} ${String(looseCount).padStart(6)} files`);
+const wts = found.skipped.filter((s) => s.reason.includes('worktree'));
+if (wts.length) line(` skipped ${wts.length} duplicate worktree(s), e.g. ${wts.slice(0, 3).map((s) => s.path).join(', ')}`);
+const dumps = found.skipped.filter((s) => s.reason.includes('data dump'));
+if (dumps.length) line(` skipped ${dumps.length} large non-git dir(s), e.g. ${dumps.slice(0, 2).map((s) => s.path).join(', ')}`);
+line();
+
+const byCat = {};
+for (const f of scan.files) byCat[f.category] = (byCat[f.category] || 0) + 1;
+line(`FILES ${Object.entries(byCat).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join(' · ')}`);
+const byLang = {};
+for (const f of code) { byLang[f.lang] ??= { files: 0, loc: 0 }; byLang[f.lang].files++; byLang[f.lang].loc += f.loc; }
+line(`CODE ${Object.entries(byLang).sort((a, b) => b[1].loc - a[1].loc).slice(0, 10).map(([k, v]) => `${k} ${v.files} files/${fmtNum(v.loc)} loc`).join(' · ')}`);
+line();
+
+// directory tree of code, collapsing small dirs
+line('CODE TREE (files / loc; dirs under 2% of code collapsed)');
+const tree = { children: new Map(), files: 0, loc: 0 };
+for (const f of code) {
+ let node = tree;
+ node.files++; node.loc += f.loc;
+ const parts = f.path.split('/').slice(0, -1);
+ for (const part of parts) {
+ if (!node.children.has(part)) node.children.set(part, { children: new Map(), files: 0, loc: 0 });
+ node = node.children.get(part);
+ node.files++; node.loc += f.loc;
+ }
+}
+const minLoc = Math.max(50, tree.loc * 0.02);
+const printTree = (node, prefix, depth) => {
+ const kids = [...node.children.entries()].sort((a, b) => b[1].loc - a[1].loc);
+ const shown = kids.filter(([, n]) => n.loc >= minLoc);
+ for (const [name, n] of shown) {
+ line(`${prefix}${name}/`.padEnd(64) + `${String(n.files).padStart(5)} ${fmtNum(n.loc).padStart(6)}`);
+ if (depth < 5) printTree(n, prefix + ' ', depth + 1);
+ }
+ const rest = kids.length - shown.length;
+ if (rest > 0) { const rf = kids.slice(shown.length).reduce((s, [, n]) => s + n.files, 0); line(`${prefix}… ${rest} smaller dir(s), ${rf} files`); }
+};
+printTree(tree, ' ', 0);
+line();
+
+// entrypoint candidates
+const ENTRY = /(^|\/)(main|index|app|server|cli|manage|wsgi|asgi|__main__|program|lib)\.(py|ts|tsx|js|mjs|go|rs|java|kt|cs|rb)$|(^|\/)app\/(page|layout)\.(t|j)sx?$|(^|\/)cmd\/[^/]+\/main\.go$|(^|\/)Dockerfile[^/]*$|(^|\/)(docker-compose|compose)\.ya?ml$|(^|\/)(cloudbuild|serverless|vercel|netlify|fly|render|app)\.(ya?ml|json|toml)$/i;
+const entries = scan.files.filter((f) => ENTRY.test(f.path) && f.path.split('/').length <= 5).map((f) => f.path);
+line(`ENTRYPOINT / DEPLOY CANDIDATES (${entries.length})`);
+for (const e of entries.slice(0, 30)) line(` ${e}`);
+if (entries.length > 30) line(` … ${entries.length - 30} more`);
+line();
+
+// directory-level dependency clusters
+const dirOf = (p, depth) => p.split('/').slice(0, -1).slice(0, depth).join('/') || '.';
+const depthFor = (p) => {
+ const r = p.split('/');
+ return Math.min(r.length - 1, 3 + (repos.length > 1 ? 1 : 0));
+};
+const dirEdges = new Map();
+for (const e of scan.edges) {
+ const a = dirOf(e.from, depthFor(e.from)), b = dirOf(e.to, depthFor(e.to));
+ if (a === b) continue;
+ const k = `${a} -> ${b}`;
+ dirEdges.set(k, (dirEdges.get(k) || 0) + (e.count || 1));
+}
+line(`IMPORT EDGES ${scan.edges.length} file->file resolved, ${unresolved} unresolved. Heaviest directory->directory:`);
+for (const [k, v] of [...dirEdges.entries()].sort((a, b) => b[1] - a[1]).slice(0, 25)) line(` ${String(v).padStart(5)} ${k}`);
+line();
+
+line(`HTTP ${routes.length} route definitions, ${http.length} call->route matches (cross-file links not visible to imports)`);
+const httpDir = new Map();
+for (const h of http) {
+ const k = `${dirOf(h.from, depthFor(h.from))} -> ${dirOf(h.to, depthFor(h.to))}`;
+ httpDir.set(k, (httpDir.get(k) || 0) + 1);
+}
+for (const [k, v] of [...httpDir.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12)) line(` ${String(v).padStart(5)} ${k}`);
+line();
+
+const topExt = scan.externals.sort((a, b) => b.files - a.files).slice(0, 25);
+line(`EXTERNAL PACKAGES (top ${topExt.length} by importing files)`);
+line(' ' + topExt.map((e) => `${e.id}(${e.files})`).join(' '));
+const hostCounts = new Map();
+for (const h of hosts) hostCounts.set(h.host, (hostCounts.get(h.host) || 0) + 1);
+if (hostCounts.size) {
+ line(`EXTERNAL HOSTS called from code`);
+ line(' ' + [...hostCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 20).map(([h, c]) => `${h}(${c})`).join(' '));
+}
+line();
+const big = code.filter((f) => f.loc > 1500).sort((a, b) => b.loc - a.loc).slice(0, 10);
+if (big.length) { line('LARGEST FILES'); for (const f of big) line(` ${fmtNum(f.loc).padStart(6)} ${f.path}`); line(); }
+line('Next: read references/schema.md, explore entrypoints, then write floorplan/architecture.json and run build.mjs.');
+console.log(out.join('\n'));
diff --git a/skills/floorplan/scripts/status.mjs b/skills/floorplan/scripts/status.mjs
new file mode 100644
index 0000000..e04550c
--- /dev/null
+++ b/skills/floorplan/scripts/status.mjs
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Prints whether a floorplan already exists here and how stale it is. Never fails.
+// usage: node status.mjs [root]
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, mapDir, LEGACY_MAP_DIR, isMapDir } from './lib/common.mjs';
+
+try {
+ const root = path.resolve(process.argv[2] || '.');
+ const legacy = !fs.existsSync(path.join(root, 'floorplan')) && isMapDir(path.join(root, LEGACY_MAP_DIR));
+ if (legacy) console.log(`(a map from before the rename is in ${LEGACY_MAP_DIR}/; the next scan, build or refresh moves it to floorplan/)`);
+ const dir = legacy ? path.join(root, LEGACY_MAP_DIR) : mapDir(root, { migrate: false });
+ const graphFile = path.join(dir, 'graph.json');
+ const hasArch = fs.existsSync(path.join(dir, 'architecture.json'));
+ if (!fs.existsSync(graphFile)) {
+ console.log(hasArch ? 'architecture.json exists but was never built: run build.mjs.' : 'none: no floorplan here yet (fresh run).');
+ process.exit(0);
+ }
+ const g = JSON.parse(fs.readFileSync(graphFile, 'utf8'));
+ const lines = [`map built ${g.meta.generatedAt} covering ${g.meta.counts.files} files, ${g.nodes.length} nodes.`];
+ for (const r of g.meta.repos || []) {
+ const abs = path.join(root, r.path);
+ const head = git(abs, ['rev-parse', 'HEAD']);
+ if (!head || !r.head) { lines.push(` ${r.path}: not a git repo now`); continue; }
+ const changed = head === r.head ? [] : (git(abs, ['diff', '--name-only', r.head, head]) || '').split('\n').filter(Boolean);
+ const dirty = (git(abs, ['status', '--porcelain']) || '').split('\n').filter(Boolean).length;
+ lines.push(` ${r.path}: ${head === r.head ? 'same commit' : `${changed.length} file(s) changed since ${r.head.slice(0, 7)}`}${dirty ? `, ${dirty} uncommitted` : ''}`);
+ if (changed.length) lines.push(` e.g. ${changed.slice(0, 6).map((p) => (r.path === '.' ? p : `${r.path}/${p}`)).join(', ')}`);
+ }
+ lines.push('A map exists: update it with refresh.mjs (only changed files cost tokens) rather than starting over.');
+ console.log(lines.join('\n'));
+} catch (e) {
+ console.log(`status unavailable (${e.message})`);
+}