docs: record phase 0-3 build progress and status

README status table, full env var reference including admin bootstrap and
cookie security, package layout, and build commands. Plan doc updated with a
progress log, the deviations from plan and why, and the gaps carried forward.

README.md

@@ -13,17 +13,21 @@ The full plan lives in `~/.opencode/plan/vellum.md`.
 | Phase | Scope | State |
 | --- | --- | --- |
 | **0** | Repo, config, migrations, health, Docker | **done** |
-| 1 | Users, sessions, library grants | not started |
+| **1** | Users, sessions, library grants | **done** |
-| 2 | Scanner, items, assets, FTS5 search | not started |
+| **2** | Scanner, items, assets | **done** |
-| 3 | EPUB reader + progress | not started |
+| **3** | EPUB reader + progress | **done** |
+| **UI** | Svelte app (login, libraries, items, reader, users) | **done** |
+| 2b | FTS5 search | not started |
 | 4 | Comic (CBZ/PDF) viewers | not started |
 | 5 | Metadata providers | not started |
 | 6 | Audiobooks, music, photos | not started |
 | 7 | Games | not started |
 | — | Video (stays on Jellyfin for now) | deferred |
 
-Phase 0 delivers a binary that boots, migrates its schema, serves a health
+What works today: an administrator creates a library pointing at a server
-check, and shuts down cleanly. No media features yet.
+folder, scans it, and users sign in and read EPUBs in the browser with their
+position saved per account. Accounts, per-library grants, cover extraction,
+range-based file serving, and the container all work. Nothing else does yet.
 
 ## Quick start
 
@@ -49,20 +53,35 @@ binary runs with no configuration at all.
 | --- | --- | --- |
 | `VELLUM_LISTEN` | `:7788` | Bind address |
 | `VELLUM_DATA_DIR` | `./data` | SQLite database lives here |
-| `VELLUM_CONFIG_DIR` | `./config` | Regenerable cache (thumbnails, pages) |
+| `VELLUM_CONFIG_DIR` | `./config` | Regenerable cache (covers, pages) |
 | `VELLUM_MEDIA_DIRS` | *(none)* | Read-only library roots, colon-separated |
+| `VELLUM_ADMIN_USER` | *(none)* | Creates the first admin, **only on an empty database** |
+| `VELLUM_ADMIN_PASSWORD` | *(none)* | Password for that first admin (min 8 chars) |
+| `VELLUM_COOKIE_SECURE` | `false` | Set `true` when serving over TLS |
 | `VELLUM_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
 | `VELLUM_LOG_FORMAT` | `text` | `text` or `json` |
 | `VELLUM_SESSION_TTL` | `720h` | Login session lifetime |
 | `VELLUM_SHUTDOWN_GRACE` | `15s` | Graceful shutdown timeout |
 
+The first admin is created only when no users exist, so setting these on an
+established install does nothing. If the database is empty and they are unset,
+the server logs a warning and refuses to invent a default password.
+
 ## Layout
 
 ```
 cmd/vellum/          main — wiring and lifecycle only
 internal/
   core/              config, logging, database, migration runner
-  httpapi/           router, middleware, handlers
+  httpx/             shared JSON helpers
+  httpapi/           router, middleware, static SPA serving
+  auth/              argon2id, sessions, grants, bootstrap
+  library/           library CRUD, media-type registry, scanner
+  media/             generic item endpoints, cover-extractor registry
+  progress/          the polymorphic per-user progress store
+  stream/            range-capable file serving
+  modules/ebooks/    EPUB parsing and cover extraction
+web/                 Svelte app; dist/ is embedded via web/embed.go
 migrations/          embedded SQL, applied in order at boot
 ```
 
@@ -102,6 +121,9 @@ The application never writes to `/media`.
 ## Development
 
 ```bash
+make build      # builds the frontend, then the Go binary with it embedded
+make build-go   # Go only, when the frontend is unchanged
 make check      # gofmt + vet + test
-make test
+make run        # run the server on :7788
+cd web && pnpm dev   # frontend dev server, proxies /api to :7788
 ```