Record extension options and decisions in docs/ROADMAP.md

Nothing implemented. Captures the setup decisions (bearer token,
stateless, inline extraction) and, for any future persistence, that it
goes in the Pi's existing PostgreSQL under its own database and user.

Worth keeping because the build surfaced facts that are expensive to
rediscover: search covers file names but never file contents, so the 93
PDFs here are opaque to it; one search costs ~270 upstream requests;
extracted file text is immutable per fileRecord and so cacheable
forever; German needs the german FTS dictionary plus pg_trgm, since
compounds defeat stemming; and "what's new since X" is impossible today
because the API has no changed-since filter anywhere.

Also records what is ruled out and why — collaborative text editor
contents are not retrievable, OCR is unnecessary since images go to
Claude directly, and write tools would forfeit the read-only property
that makes the public endpoint acceptable.

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

docs/ROADMAP.md

@@ -0,0 +1,92 @@
+# Possible extensions
+
+**Nothing here is built.** This records options considered during setup, the
+decisions already taken, and the trade-offs found while building — so none of it
+has to be rediscovered.
+
+## Decisions already taken
+
+| Decision | Choice | Rejected |
+|---|---|---|
+| Endpoint auth | Static bearer token (`MCP_AUTH_TOKEN`, constant-time check) | OAuth 2.1; secret URL path |
+| State | Stateless — every tool call hits the API live | Postgres cache; cache + full-text search |
+| File delivery | Inline extracted text; images inline | Raw base64 only |
+| **If** persistence is added | **The Pi's existing PostgreSQL, with its own database and user** | A dedicated container; SQLite |
+
+Two of the rejected options need no revisiting. OAuth 2.1 is disproportionate
+machinery for a single-user endpoint a bearer token already protects. "Raw bytes
+as well as extracted text" got built anyway — `download_file` takes `raw: true`.
+
+## 1. Full-text search over file contents
+
+**The gap:** `search` covers course/board/card/lesson/task titles and text, and
+file *names* — never file *contents*. The 93 PDFs in this account are opaque to
+it. "Where does it explain the Caesar cipher?" only hits if those words are in a
+filename.
+
+**The cost:** one `search` walks ~26 course pages, ~30 board skeletons plus card
+fetches, and ~150 per-element file listings — roughly **270 upstream requests**,
+several seconds, every time.
+
+**Design sketch**
+
+- Postgres `tsvector` + GIN. Use the **`german`** dictionary, so *Verschlüsselung*
+  matches *Verschlüsselungsverfahren*; the default `english` config stems these
+  wrongly.
+- Add **`pg_trgm`** alongside. German compounds defeat stemming —
+  *Datenschutzgrundverordnung* will not match *Datenschutz* — and trigram
+  similarity also absorbs typos.
+- Index: titles and text of courses, boards, cards, lessons, tasks; file names;
+  and **extracted file text**.
+- Later, optionally: embeddings in `pgvector`, so "the thing about encryption"
+  finds *Verschlüsselung* without sharing a word. Needs an embedding model in the
+  loop, so it is a separate step, not part of this.
+
+## 2. Cache, with bypass
+
+**The split that makes staleness tolerable** — index is *discovery*, live API is
+*detail*. Search the index to find where something is; always re-fetch it to read
+it. A stale index then costs a missed or spurious hit, never wrong content. That
+is a far better failure mode than a cache that can serve last week's homework
+list as current.
+
+- `fresh: true` on `search` (re-crawl the relevant course first) and on the
+  detail tools.
+- **State freshness in every cached result** ("indexed 2h ago"), regardless of
+  the flag — a bypass only helps if the agent knows it needs one.
+- **Extracted file text is cacheable indefinitely.** A `fileRecord` id maps to
+  immutable bytes; an edit produces a new record. PDF parsing happens once, ever.
+  Cheapest large win here, and free of staleness risk.
+- Sync: nightly full crawl (~270 requests, trivial) plus on-demand per course.
+
+**Consequence to weigh:** coursework text would then live on the Pi at rest,
+outside Schulcloud. It does not weaken the read-only property, but it is new —
+consider disk encryption and whether it lands in a backup.
+
+## 3. "What's new since …"
+
+Falls out of having an index with history: diff successive crawls to surface new
+boards, cards, files and tasks. **Impossible today at any speed** — the API has no
+changed-since filter anywhere. Arguably the most useful item on this list for a
+student, and nearly free once the sync job exists.
+
+## 4. Smaller items
+
+- **Video/audio transcription** — this account has 5 MP4s and a WebM that are
+  currently just "here is a file you cannot read".
+- **MCP resources and prompts** — expose courses/boards as attachable resources;
+  canned prompts such as "summarise this week's homework".
+- **Calendar** — a separate `schulcloud-calendar` service, not part of the v3 API
+  mapped in `API.md`.
+
+## 5. Ruled out
+
+- **Collaborative text editor contents.** Confirmed unavailable:
+  `GET /api/v3/collaborative-text-editor/{parentType}/{parentId}` returns a URL
+  to the editor, never the document text.
+- **OCR.** Unnecessary — images are returned inline and Claude reads them
+  directly.
+- **Write tools** (submitting homework, marking tasks done). Technically easy,
+  but this forfeits the property that makes an internet-facing endpoint
+  acceptable: that a leaked token cannot act as the user. A deliberate, separate
+  decision — see the invariant in `CLAUDE.md`.