Add the schulcloud CLI, and document the split

The CLI talks only to the Pi's /api surface and holds no Schulcloud
credential — only the same bearer token the Claude connector uses. That
is not layering for its own sake: a Schulcloud session dies after two
hours idle and a CLI process lives for seconds, so a CLI with its own
token would be dead most times you reached for it. Routing through the
Pi means one session, one keepalive, one monthly cookie paste.

sync is a one-way mirror, which follows from the data rather than from
scope-cutting: file records are immutable upstream, so there is no
versioning, no conflict resolution and no merge. State is keyed by file
record id with the path as derived output, so an upstream rename moves
the local file instead of duplicating it — verified against the live
server. Verification is size-only because the download endpoint exposes
no ETag and Schulcloud publishes no hash; size still catches the failure
that happens, a truncated download. Downloads land on a .part neighbour
and are renamed, so an interrupted run leaves no half-file that a later
run mistakes for complete. Deletions are reported but not propagated —
a teacher removing a worksheet is no reason to destroy the student's
copy — with --prune to opt in.

what_changed now clamps to the oldest stored generation instead of
refusing, and says it did: "what's new this week" is a reasonable
question to ask a two-day-old index.

Two build bugs caught by the checks rather than by luck: the smoke
harness constructed the app without services, so the index-backed tools
were never exercised; and the Docker build could not see
scripts/copy-assets.mjs, so the image would have shipped without
migrations and silently degraded to live-only.

67 unit tests (9 needing Postgres), smoke green both ways — 34 checks
with an index, 32 without, because graceful degradation is a supported
mode and not a fallback nobody runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/DEPLOYMENT.md

@@ -3,12 +3,19 @@
 ## The shape of it
 
 ```
-claude.ai  ──HTTPS──▶  VPS (public IP)  ──tunnel──▶  Pi 5 (home network)
-                                                      └─ Caddy ──▶ schulcloud-mcp:8080
-                                                                      │
-                                                                      └──▶ schulcloud-thueringen.de
+claude.ai  ──HTTPS──┐
+                    ├─▶ VPS (public IP) ──tunnel──▶ Pi 5 (home network)
+schulcloud CLI ─────┘                                └─ Caddy ─▶ schulcloud-mcp:8080
+                                                                  ├─ /mcp      (Claude)
+                                                                  ├─ /api      (CLI)
+                                                                  ├─ Postgres  (index)
+                                                                  ├─ mirror    (file bytes)
+                                                                  └──▶ schulcloud-thueringen.de
 ```
 
+Both front ends use the same hostname and the same bearer token. `/mcp` speaks
+MCP; `/api` serves the CLI's manifest, file bytes and re-crawl requests.
+
 Claude's custom connectors call the endpoint from Anthropic's cloud, so it must
 be publicly reachable over real TLS — a localhost tunnel or self-signed cert
 will not do. The VPS provides the public address; Caddy on the Pi terminates
@@ -64,6 +71,26 @@ networks:
     name: <the network name you just found>
 ```
 
+### Postgres
+
+The index needs a database. On the Pi, use the existing PostgreSQL rather than
+the container in `docker-compose.yml` — create a database and user for it:
+
+```sql
+CREATE USER schulcloud WITH PASSWORD '…';
+CREATE DATABASE schulcloud OWNER schulcloud;
+```
+
+Then set `DATABASE_URL` in `.env` and delete the `postgres` service from the
+compose file. Migrations run automatically at startup; `pg_trgm` is created by
+the first migration, which needs the database owner to be able to
+`CREATE EXTENSION`.
+
+Without `DATABASE_URL` the server still runs: search crawls live on every call
+and `/api` returns `503`. The startup log says which mode it is in.
+
+### Caddy
+
 Append `deploy/Caddyfile.snippet` to the Pi's Caddyfile, replacing
 `mcp.example.org` with the real hostname, and reload:
 
@@ -151,10 +178,16 @@ npm run probe                                  # re-verify the API assumptions
 - **Sessions** are in-memory and dropped after 30 minutes idle. A restart
   invalidates them; Claude re-initializes transparently.
 - **Logs** are capped at 3 × 10 MB. The Authorization header is never logged.
-- **The container is read-only** with `cap_drop: ALL` and
-  `no-new-privileges`, running as the unprivileged `node` user. It writes
-  nothing to disk — downloads are streamed through memory, capped at
-  `MAX_DOWNLOAD_BYTES` (25 MiB default).
+- **The container is read-only** with `cap_drop: ALL` and `no-new-privileges`,
+  running as the unprivileged `node` user. The one writable path is the mirror
+  volume at `/data/mirror`, which holds downloaded file bytes; everything else
+  stays read-only.
+- **The mirror grows.** It holds a copy of every course file under
+  `MIRROR_MAX_BYTES` (64 MiB default). Larger files — videos, mostly — are
+  indexed as metadata and proxied live on request instead. Budget a few GB.
+- **A re-crawl of unchanged content downloads nothing**, because Schulcloud file
+  records are immutable, so the 6-hourly crawl costs a few hundred cheap GETs in
+  the steady state.
 - **The Schulcloud session has a 2-hour sliding TTL**, so the server calls
   `refresh-session` every 30 minutes. Watch for
   `keepalive: session extended, 7200s` in the logs, or run