diff --git a/README.md b/README.md
index e464b42..5d01991 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,108 @@
-# Brain Atlas (by Laboratory for Symbolic Cognitive Development, BSI)
+# BSI-NI Brain Atlas
 
-React project for brainatlas.brain.riken.jp
+Static front-end for the archived [BSI-NI Brain Atlas](https://brainatlas.brain.riken.jp/)
+site (Laboratory for Symbolic Cognitive Development, RIKEN BSI), built with
+[Vite](https://vite.dev/), React and TypeScript.
+
+One app serves three former XOOPS installations side by side: `degu`, `jm`
+(Japanese Macaque Monkey) and `marmoset`.
+
+## Requirements
+
+- Node.js 20.19+ / 22.12+ (Vite 8)
+- npm
+
+## Setup
+
+```sh
+npm install
+```
+
+## Site data
+
+The pages are rendered from JSON dumped out of the original XooNIps
+installations. All of it lives in `static-contents/`, which sits next to the
+repository rather than inside it, laid out the way the XOOPS sites served it:
+
+```
+brainatlas.brain.riken.jp/
+├── brainatlas.brain.riken.jp/   this repository
+└── static-contents/
+    ├── degu/
+    │   ├── modules/xoonips/     tree.json, items.json, file/<id>/
+    │   └── static/              the 3D atlas databases (*.sqlite) and manuals
+    ├── jm/                      same shape
+    └── marmoset/                same shape
+```
+
+Two things inside it carry absolute paths and have to move with the layout:
+the `url` fields in each `items.json`, and the `RewriteBase` in every
+`file/<id>/.htaccess`, which redirects a bare file directory to the file.
+
+The dev and preview servers mount that directory at the site root. It is
+deliberately kept out of `dist/`: it runs to about 50 GB, and the web server
+maps it in directly. It is not tracked in git.
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the dev server on http://localhost:5173 |
+| `npm run build` | Type-check and build into `dist/` |
+| `npm run preview` | Serve the production build on http://localhost:4173 |
+| `npm run lint` | Lint with [Biome](https://biomejs.dev/) |
+| `npm run format` | Format with Biome |
+| `npm run check` | Lint, format and organize imports, applying the safe fixes |
+
+`@types/node` is pinned to the major that matches the Node runtime in use (24);
+`.ncurc.js` keeps `npm-check-updates` from bumping it past that.
+
+The base stylesheet is `sanitize.css` (with its `forms` and `typography`
+sheets), not the `modern-normalize` the other converted sites use: this theme
+was written on top of it, and swapping it moves nearly every element.
+
+There is currently no test suite.
+
+## Deployment
+
+Build locally and copy the result up; the server does not need a toolchain.
+
+```sh
+npm ci
+npm run check
+npm run build
+../deploy.sh
+```
+
+`deploy.sh`, next to `static-contents/`, sends the data to
+`archive:/data/www/brainatlas.brain.riken.jp/static-contents/`, then `dist/` to
+`.../html/`, and finally links every top-level entry of `static-contents/` into
+the document root over ssh (`ln -sfn ../static-contents/* .`). The data has to
+go first: the document root's `rsync --delete` removes those links, and they
+are only put back at the end.
+
+Apache needs `Options FollowSymLinks` and `AllowOverride All` on both
+directories. Use symlinks rather than `Alias`: an `Alias` maps the URL outside
+the document root, so `.htaccess` no longer applies and the SPA fallback and
+the legacy redirects stop working.
+
+The atlas directories are real directories on disk as well as SPA routes
+(`/degu/`, `/degu/modules/xoonips/listitem.php`, ...). `public/.htaccess`
+therefore sends every request that is not a real file to `index.html`,
+directories included.
+
+### Legacy URLs
+
+`.htaccess` keeps the earlier addresses working with a 301:
+
+| From | To |
+| --- | --- |
+| `/<atlas>/modules/xoonips/download.php?file_id=N` | `/<atlas>/modules/xoonips/file/N` |
+| `/data/<atlas>/file/...` (v2.0.0) | `/<atlas>/modules/xoonips/file/...` |
+| `/data/<atlas>/static/...` (v2.0.0) | `/<atlas>/static/...` |
+| `/<atlas>/file/...` | `/<atlas>/modules/xoonips/file/...` |
+
+## Google Analytics
+
+`GOOGLE_ANALYTICS_TRACKING_ID` in `src/config.ts` is empty, which disables
+tracking. Set a GA4 measurement ID (`G-XXXXXXXXXX`) to enable it.