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.
| Topic | Document |
|---|---|
| What the product is and how to install it | README, install.md |
| How to use the app | user-guide.md |
| Where code lives | CODE_MAP.md |
| What each feature is, what it touches, and how to plan work on it | FEATURE_MAP.md |
| How the system is put together | ARCHITECTURE.md |
| File and symbol names | CONVENTIONS.md |
| How to work in this repo | CONTRIBUTING.md, AGENTS.md |
| Topic | Document |
|---|---|
| Install channels (npm, Homebrew, Windows, Docker) | install.md |
| Server deploy, env, encryption, SSO | DEPLOYMENT.md |
| Workflow engine | workflow.md |
| Cutting a release | publish.md |
| Refresh the Homebrew formula after npm publish | packaging/homebrew/README.md |
| Dependency updates | DEPENDENCY_POLICY.md |
| Security process | security/security-process.md |
| Db2 OS user example | examples/db2-os-user.md |
| SQL editor examples | examples/sql-editor/README.md |
Homebrew install steps live only in install.md. The packaging readme does not repeat them.
| Topic | Document |
|---|---|
| Repo layout, dialects, migration flow | ARCHITECTURE.md |
| HTTP server, logging, what is never logged | BACKEND_ARCHITECTURE.md |
| Feature folders and how to add one | architecture/FEATURE-MODULE-GUIDE.md |
| Which feature may import which | architecture/FEATURE-DEPENDENCY-RULES.md |
| Dialect hooks | packages/sql/src/providers/DIALECTS.md |
| Topic | Document |
|---|---|
| How to write an end-to-end test | testing/WRITING_E2E.md |
| How to run it against the engines, and failures that are not bugs | testing/RUNNING_E2E.md |
| Generated test-id catalog | testing/TEST_IDS.md |
Finished or in-progress design notes. Do not treat them as the map of the code. The current map is CODE_MAP.md.
Every shipped version in one page: releases/SUMMARY.md. The per-version files, listed in releases/README.md, are the GitHub Release bodies and are not updated after the version ships.