docs: one file per topic, and one page for every release

.gitignore

@@ -65,7 +65,6 @@ packages/db/npm-pack/
 # Homebrew formula docs (tracked)
 !packaging/homebrew/README.md
 !apps/cli/README.md
-!docs/homebrew.md
 
 
 # The workflow engine's SQLite DB, created at the repo root by default

AGENTS.md

@@ -3,7 +3,7 @@
 Fox Schema (`foxschema`) is a database schema diff & migration tool: an npm-workspaces
 monorepo delivered as a web app (`apps/web` = React/Vite UI + `packages/server`
 Fastify API), a CLI (`apps/cli`), and the dialect engine (`packages/sql` +
-`packages/db`). Optional workflow engine: `apps/workflow-server` ([docs/WORKFLOW.md](docs/WORKFLOW.md)).
+`packages/db`). Optional workflow engine: `apps/workflow-server` ([docs/workflow.md](docs/workflow.md)).
 See `README.md` and `CONTRIBUTING.md` for the product overview and the canonical
 dev/test/build commands.
 
@@ -48,7 +48,7 @@ Standard commands live in `CONTRIBUTING.md` and `package.json` scripts (`npm run
   UI at http://localhost:5173. API liveness: `GET http://localhost:3210/api/health`
   → `{"ok":true}`. Every install requires sign-in; first open runs admin setup. Workflow engine:
   `npm run dev:with-workflow` (needs `WORKFLOW_ENGINE_TOKEN` and
-  `FOXFLOW_ENCRYPTION_KEY` — [docs/WORKFLOW.md](docs/WORKFLOW.md)).
+  `FOXFLOW_ENCRYPTION_KEY` — [docs/workflow.md](docs/workflow.md)).
 - Vite is configured with `server.host: true`, `server.strictPort: true`, and
   `server.allowedHosts: true` so `http://127.0.0.1:5173` works (not only IPv6
   localhost), the port does not silently hop to 5174+, and Cursor/cloud

CONTRIBUTING.md

@@ -13,8 +13,9 @@ fresh clone to a running app with a passing test suite.
   develop on).
 - **Docker** — for the test databases and the end-to-end suite.
 
-User install channels: [docs/INSTALL.md](docs/INSTALL.md). Release publish:
-[docs/PUBLISH.md](docs/PUBLISH.md).
+User install channels: [docs/install.md](docs/install.md). Release publish:
+[docs/publish.md](docs/publish.md). The rest of the docs, one file per topic:
+[docs/README.md](docs/README.md).
 
 ## First-time setup
 
@@ -41,7 +42,7 @@ export FOXFLOW_ENCRYPTION_KEY="$(openssl rand -hex 32)"
 npm run dev:with-workflow
 ```
 
-Then **Workflow → Engine → Enabled**. Runbook: [docs/WORKFLOW.md](docs/WORKFLOW.md).
+Then **Workflow → Engine → Enabled**. Runbook: [docs/workflow.md](docs/workflow.md).
 
 For the advanced test schemas (`demo_c` / `demo_d` — FK chains, cross-dialect type
 matrix, materialized views, etc.): `bash scripts/seed/seed-advanced.sh all`.

README.md

@@ -9,7 +9,7 @@
 Install once, then open the local web UI (`foxschema`) for **Compare**, the
 **SQL Editor**, **Utils**, **Snapshots**, and optional **Workflow**. Self-host with Docker when you need a server.
 
-[foxschema.com](https://foxschema.com) · [Install](docs/INSTALL.md) · [User guide](docs/USER_GUIDE.md) · [Workflow](docs/WORKFLOW.md) · [Publish](docs/PUBLISH.md) · [Contributing](CONTRIBUTING.md)
+[foxschema.com](https://foxschema.com) · [Install](docs/install.md) · [User guide](docs/user-guide.md) · [Workflow](docs/workflow.md) · [Docs](docs/README.md) · [Contributing](CONTRIBUTING.md)
 
 <p>
   <a href="https://www.npmjs.com/package/foxschema"><img alt="npm" src="https://img.shields.io/npm/v/foxschema.svg?logo=npm" /></a>
@@ -45,7 +45,7 @@ winget install OpenJS.NodeJS.LTS
 npm install -g foxschema
 ```
 
-Full matrix: **[docs/INSTALL.md](docs/INSTALL.md)**.
+Full matrix: **[docs/install.md](docs/install.md)**.
 
 ## Use the app
 
@@ -83,7 +83,7 @@ A full query workbench next to Schema Sync — not a thin prompt.
 | **Safe mode** | Confirm writes; bookmarks & samples included |
 | **Access control** | Optional `admin` / `editor` / `viewer` roles when multi-user login is on |
 
-Walkthrough: [User guide → SQL Editor](docs/USER_GUIDE.md#sql-editor).
+Walkthrough: [User guide → SQL Editor](docs/user-guide.md#sql-editor).
 
 ## Workflow
 
@@ -97,8 +97,8 @@ export FOXFLOW_ENCRYPTION_KEY="$(openssl rand -hex 32)"
 npm run dev:with-workflow
 ```
 
-Then **Workflow → Engine → Enabled**. Runbook: [docs/WORKFLOW.md](docs/WORKFLOW.md).
-User steps: [User guide → Workflow](docs/USER_GUIDE.md#workflow).
+Then **Workflow → Engine → Enabled**. Runbook: [docs/workflow.md](docs/workflow.md).
+User steps: [User guide → Workflow](docs/user-guide.md#workflow).
 
 ## Schema Sync
 
@@ -155,7 +155,7 @@ CommonJS at runtime. Requires **Node ≥ 22.5**.
 | `apps/workflow-server` | Workflow engine HTTP process (`:8081`) |
 | `apps/e2e` | Playwright tests against dockerized databases |
 
-Maintainers: [docs/PUBLISH.md](docs/PUBLISH.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Maintainers: [docs/publish.md](docs/publish.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## License
 

apps/cli/README.md

@@ -71,8 +71,8 @@ foxschema tui
 
 ## Docs
 
-- [User guide](https://github.com/tedious-code/foxschema/blob/main/docs/USER_GUIDE.md)
-- [Install](https://github.com/tedious-code/foxschema/blob/main/docs/INSTALL.md)
+- [User guide](https://github.com/tedious-code/foxschema/blob/main/docs/user-guide.md)
+- [Install](https://github.com/tedious-code/foxschema/blob/main/docs/install.md)
 - [Site](https://foxschema.com)
 
 ## License

docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Architecture reference
 
 Stable orientation for FoxSchema. For where a change belongs see
-[CODE_MAP.md](CODE_MAP.md). Workflow engine runbook: [WORKFLOW.md](WORKFLOW.md).
+[CODE_MAP.md](CODE_MAP.md). Workflow engine runbook: [workflow.md](workflow.md).
 
 ## What this is
 

docs/CODE_MAP.md

@@ -41,7 +41,7 @@ apps/workflow-server        The workflow engine's HTTP process (port 8081), plus
                             the server's engine proxy (WORKFLOW_ENGINE_TOKEN);
                             trigger ingress can take a port of its own
                             (INGRESS_PORT). Pulls engine settings from the server.
-                            Runbook: docs/WORKFLOW.md.
+                            Runbook: docs/workflow.md.
 apps/e2e                    Browser tests that drive the running application.
 ```
 
@@ -156,7 +156,7 @@ database/    The metadata store and its migrations.
 | `sql-editor` | SQL editor, code cells, sandboxed execution |
 | `users` | Profile, preferences, first-run wizard |
 | `workspaces` | Shared workspaces: create, switch, members, invites, public or private (`/api/workspaces`). Which workspace a request acts in is `platform/workspaces`. Admins list every workspace (`GET /all`) and open one only by joining. |
-| `workflow` | Workflow engine settings and health; the engine proxy (an allowlist of engine routes, each behind a `workflow.*` permission); saved-connection grants; and the token-guarded internal routes the engine calls to resolve a granted connection and read its settings. Runbook: [WORKFLOW.md](WORKFLOW.md). |
+| `workflow` | Workflow engine settings and health; the engine proxy (an allowlist of engine routes, each behind a `workflow.*` permission); saved-connection grants; and the token-guarded internal routes the engine calls to resolve a granted connection and read its settings. Runbook: [workflow.md](workflow.md). |
 
 Every feature folder has an `index.ts` exporting its `ServerFeatureModule`
 and its public API; other features import only that
@@ -270,7 +270,7 @@ the page-epoch guard, bookmarks and recents, SQL variables.
 | Guard or cross-cutting HTTP concern | `packages/server/src/platform/` |
 | How a dialect lexes SQL (permission gates, splitter) | `packages/sql/src/modules/sql-text/sql-readings.ts` + `sql-tokens.ts`. Do not add a second scanner. |
 | Workspace membership, invites, public / private | `packages/server/src/features/workspaces/`; request scope is `platform/workspaces`. Services take `WorkspaceScope` (`scopeOf(req)`). |
-| Workflow pipe, runtime, or store | `packages/workflow-engine/` — HTTP process in `apps/workflow-server/` ([WORKFLOW.md](WORKFLOW.md)) |
+| Workflow pipe, runtime, or store | `packages/workflow-engine/` — HTTP process in `apps/workflow-server/` ([workflow.md](workflow.md)) |
 
 ## Checks to run
 

docs/DEPLOYMENT.md

@@ -1,7 +1,7 @@
 # Deploying Fox Schema
 
 **Day-to-day on a laptop:** install the CLI, open the UI in your browser, optionally add a
-desktop shortcut (`foxschema shortcut`). See **[INSTALL.md](INSTALL.md)**.
+desktop shortcut (`foxschema shortcut`). See **[install.md](install.md)**.
 
 ```bash
 npm install -g foxschema
@@ -12,7 +12,7 @@ foxschema                  # http://localhost:3210
 foxschema shortcut
 ```
 
-Maintainers: **[PUBLISH.md](PUBLISH.md)**.
+Maintainers: **[publish.md](publish.md)**.
 
 ### Sign-in + RBAC
 
@@ -47,15 +47,15 @@ and the desktop app alike. Roles are `admin` / `editor` / `owner` / `viewer`.
   **Admins: One / Several** lives there (`FOX_ADMIN_POLICY` overrides it). Saved
   connections, snapshots, runs and secrets belong to a **workspace**; every
   account has a personal one. Admins see every workspace and open one only by
-  joining. [USER_GUIDE — Workspaces](USER_GUIDE.md#workspaces).
+  joining. [USER_GUIDE — Workspaces](user-guide.md#workspaces).
 - Permissions cover Schema Sync (browse / compare / migrate), SQL Editor (sidebar, variables, writes, Data grid insert/update/delete, code cells), Utilities, Secrets, Access, Workflow (`workflow.access` / `design` / `run` / `admin`), and Workspaces (`workspace.members` / `settings` / `create`). Code cells, Git, workflow and `workspace.create` are install-wide (account role); the rest follow the member’s role in the current workspace.
 - **Database Access** catalog (`POST /schema/db-access`) is an OR gate: **Use utilities** *or* any Access-workspace permission (`access.access`, Users, builder, diff, inspector, report) may load it. GRANT / REVOKE still needs **Grant privileges**.
 
 **Servers / teams:** Fox Schema ships as a **single Docker image** (all dialects including
 Db2) that serves both the UI and the API on one configurable port (default **3210**).
 
-- [Install (all channels)](INSTALL.md)
-- [CLI / Homebrew](homebrew.md)
+- [Install (all channels)](install.md)
+- [CLI / Homebrew](install.md#homebrew-macos)
 - [Quick start (Docker)](#quick-start)
 - [Configuration (environment variables)](#configuration-environment-variables)
 - [The encryption key](#the-encryption-key)
@@ -200,7 +200,7 @@ npm -w @foxschema/workflow-server run start:worker      # claim queued runs
 **The published Docker image does not start the engine.** `Dockerfile` /
 `docker-compose.app.yml` run FoxSchema only. Deploy `apps/workflow-server` beside
 it (same token on both). Local checkout: `npm run dev:with-workflow`. Full
-runbook: [WORKFLOW.md](WORKFLOW.md).
+runbook: [workflow.md](workflow.md).
 
 ### First-open email subscriber wizard
 

docs/README.md

@@ -0,0 +1,75 @@
+# Documentation
+
+One file per topic. If two pages used to say the same thing, this list names the one to read.
+
+Living documents describe the tree as it is. Plans and release notes are history: they record why a change was made, and their paths can be stale.
+
+## Start here
+
+| Topic | Document |
+| --- | --- |
+| What the product is and how to install it | [README](../README.md), [install.md](install.md) |
+| How to use the app | [user-guide.md](user-guide.md) |
+| Where code lives | [CODE_MAP.md](CODE_MAP.md) |
+| How the system is put together | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| File and symbol names | [CONVENTIONS.md](CONVENTIONS.md) |
+| How to work in this repo | [CONTRIBUTING.md](../CONTRIBUTING.md), [AGENTS.md](../AGENTS.md) |
+
+## Run and ship
+
+| Topic | Document |
+| --- | --- |
+| Install channels (npm, Homebrew, Windows, Docker) | [install.md](install.md) |
+| Server deploy, env, encryption, SSO | [DEPLOYMENT.md](DEPLOYMENT.md) |
+| Workflow engine | [workflow.md](workflow.md) |
+| Cutting a release | [publish.md](publish.md) |
+| Refresh the Homebrew formula after npm publish | [packaging/homebrew/README.md](../packaging/homebrew/README.md) |
+| Dependency updates | [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md) |
+| Security process | [security/security-process.md](security/security-process.md) |
+| Db2 OS user example | [examples/db2-os-user.md](examples/db2-os-user.md) |
+| SQL editor examples | [examples/sql-editor/README.md](examples/sql-editor/README.md) |
+
+Homebrew install steps live only in [install.md](install.md#homebrew-macos). The packaging readme does not repeat them.
+
+## Architecture (current)
+
+| Topic | Document |
+| --- | --- |
+| Repo layout, dialects, migration flow | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| HTTP server, logging, what is never logged | [BACKEND_ARCHITECTURE.md](BACKEND_ARCHITECTURE.md) |
+| Feature folders and how to add one | [architecture/FEATURE-MODULE-GUIDE.md](architecture/FEATURE-MODULE-GUIDE.md) |
+| Which feature may import which | [architecture/FEATURE-DEPENDENCY-RULES.md](architecture/FEATURE-DEPENDENCY-RULES.md) |
+| Dialect hooks | [packages/sql/src/providers/DIALECTS.md](../packages/sql/src/providers/DIALECTS.md) |
+
+## Testing
+
+| Topic | Document |
+| --- | --- |
+| How to write an end-to-end test | [testing/WRITING_E2E.md](testing/WRITING_E2E.md) |
+| Generated test-id catalog | [testing/TEST_IDS.md](testing/TEST_IDS.md) |
+
+## Plans (history)
+
+Finished or in-progress design notes. Do not treat them as the map of the code. The current map is [CODE_MAP.md](CODE_MAP.md).
+
+| Topic | Document |
+| --- | --- |
+| Package split (`packages/core` → sql + db) | [plans/package-split.md](plans/package-split.md) |
+| Backend moved out of the web app; Express removed | [plans/backend-extraction.md](plans/backend-extraction.md) |
+| API layout and the decisions still open | [plans/api-restructure.md](plans/api-restructure.md) |
+| Frontend moved to `app/` + `features/` + `shared/` | [plans/frontend-refactor.md](plans/frontend-refactor.md) |
+| Feature-module schedule | [plans/2026-10-10-feature-architecture.md](plans/2026-10-10-feature-architecture.md) |
+| Workspaces and admin policy | [plans/2026-10-09-workspaces-and-admin-policy.md](plans/2026-10-09-workspaces-and-admin-policy.md) |
+| SQL editor | [plans/sql-editor.md](plans/sql-editor.md) |
+| Test ids | [plans/2026-10-03-test-ids.md](plans/2026-10-03-test-ids.md) |
+| Migrations in Git | [plans/2026-10-02-migrations-in-git.md](plans/2026-10-02-migrations-in-git.md) |
+| Seed and migration ordering | [plans/2026-07-01-seed-test-matrix.md](plans/2026-07-01-seed-test-matrix.md), [plans/2026-07-01-migration-ordering-bugs.md](plans/2026-07-01-migration-ordering-bugs.md) |
+| Diff colors and safety gates | [plans/2026-06-30-diff-colors-and-safety-gates.md](plans/2026-06-30-diff-colors-and-safety-gates.md) |
+| Schema versioning | [plans/schema-versioning-and-revert.md](plans/schema-versioning-and-revert.md) |
+| Server beam | [plans/server-beam.md](plans/server-beam.md) |
+| Excel and Sheets import | [plans/excel-and-sheets-import.md](plans/excel-and-sheets-import.md) |
+| Feature review test plan | [plans/2026-10-06-review-features-test-plan.md](plans/2026-10-06-review-features-test-plan.md) |
+
+## Releases
+
+Every shipped version in one page: [releases/SUMMARY.md](releases/SUMMARY.md). The per-version files, listed in [releases/README.md](releases/README.md), are the GitHub Release bodies and are not updated after the version ships.

docs/INSTALL.md → docs/install.md

@@ -51,7 +51,7 @@ foxschema
 foxschema shortcut        # Desktop app with fox icon
 ```
 
-Details: [homebrew.md](homebrew.md).
+`brew search foxschema` works only after the tap and the one-time trust. There is one formula and one npm package. Db2 is optional on npm and included in the Docker image. After an npm release, maintainers refresh the formula with [packaging/homebrew/update-formula.sh](../packaging/homebrew/update-formula.sh).
 
 ---
 
@@ -149,10 +149,10 @@ foxschema tui          # terminal UI
 ```
 
 In the UI: **Schema Sync** (compare / migrate) or **SQL Editor** (ad-hoc SQL against
-saved connections). Editor walkthrough: [USER_GUIDE.md § SQL Editor](USER_GUIDE.md#sql-editor).
+saved connections). Editor walkthrough: [user guide — SQL Editor](user-guide.md#sql-editor).
 
 ---
 
 ## Publishing (maintainers)
 
-See [PUBLISH.md](PUBLISH.md) for npm, Homebrew, Docker Hub/GHCR, and release tags.
+See [publish.md](publish.md) for npm, Homebrew, Docker Hub/GHCR, and release tags.

docs/API_RESTRUCTURE_PLAN.md → docs/plans/api-restructure.md

@@ -14,7 +14,7 @@ in place; the layering is not. Last reconciled against the tree 2026-09-21.
 | Resource-level authorization (§6) | Not started — highest remaining security value |
 | Async stores for locks / idempotency / rate limit | Not started — multi-instance prep |
 | Scope-aware cache (§4) | Not started, deliberately last |
-| Remove Express entirely | **Done** — see `docs/BACKEND_EXTRACTION_PLAN.md` §8 |
+| Remove Express entirely | **Done** — see `docs/plans/backend-extraction.md` §8 |
 
 **Paths below are as-written and now stale.** The tree has moved twice since:
 out of `apps/web/src/backend/` into `packages/server/src/`, and through a

docs/plans/sql-editor.md

@@ -4,7 +4,7 @@
 > stale: `packages/core` is now `packages/sql` + `packages/db`; the API lives in
 > `packages/server` (not `apps/web/src/backend`); SQLite is read-write; ports are
 > **3210** / **5173**. Current map: [CODE_MAP.md](../CODE_MAP.md). User walkthrough:
-> [USER_GUIDE.md](../USER_GUIDE.md#sql-editor). Agent notes:
+> [user-guide.md](../user-guide.md#sql-editor). Agent notes:
 > `.cursor/rules/sql-editor-agent-memory.mdc`.
 
 ## Context

docs/PUBLISH.md → docs/publish.md

@@ -1,6 +1,6 @@
 # Publishing Fox Schema
 
-How maintainers ship a release. **Users** should follow [INSTALL.md](INSTALL.md).
+How maintainers ship a release. **Users** should follow [install.md](install.md).
 
 Distribution channels (one product, no separate Db2 edition):