Adding migrations and lot of work. Starting work on the demo scope

README.md

@@ -5,6 +5,7 @@ A standalone, server-backed proof of concept for the Glitch University investiga
 The accepted normalized domain model and terminology are specified in [`docs/exhibit-data-model.md`](docs/exhibit-data-model.md). PostgreSQL stores **exhibits**; frontend **widgets** visualize exhibit types.
 
 Planned schema and exhibit work is tracked in [`docs/TODO.md`](docs/TODO.md).
+The intentionally narrow current demo is defined in [`docs/demo-scope.md`](docs/demo-scope.md): it opens directly on the board and focuses on investigation, flag-gated evidence reveals, and pasted screenshots.
 
 ## Run locally
 
@@ -74,7 +75,15 @@ The API surface is:
 - `PUT /api/levels/:id`
 - `POST /api/levels/:id/reset`
 - `POST /api/levels/:id/templates` (save a new immutable version; editor only)
-- `POST /api/levels/:id/documents` (editor only)
+- `POST /api/levels/:id/documents` (player-uploaded evidence)
+- `POST /api/levels/:id/reveals/seen`
+- `GET /api/levels/:id/flags` (admin only)
+- `PUT /api/levels/:id/flags/:key` (admin only)
+- `DELETE /api/levels/:id/flags/:key` (admin only)
+- `GET /api/levels/:id/evidence-match-rules` (admin only)
+- `POST /api/levels/:id/evidence-match-rules` (editor only)
+- `PUT /api/levels/:id/evidence-match-rules/:ruleId` (editor only)
+- `DELETE /api/levels/:id/evidence-match-rules/:ruleId` (editor only)
 - `GET /api/assets/:id`
 - `GET /api/session` (verified session and admin capability summary)
 - `GET /api/health`
@@ -87,7 +96,11 @@ Set `LEVEL_EDITING_ENABLED=true` and open `/?edit=1` while signed in with a JWT
 
 For the standalone development Compose stack, visit `/api/dev/admin-session?returnTo=/?edit=1` once to receive a local signed admin cookie. This helper does not exist in production.
 
-In edit mode, files can be dragged from the desktop onto the board or selected with **Import Document**. Images, PDFs, and text files render inside document windows; unknown formats remain downloadable source files. Extracted evidence becomes an editable folder widget. Its editor controls the title, annotation, contained documents, and each source document's publication time. The default upload limit is 25 MB and can be changed with `MAX_DOCUMENT_BYTES`.
+Files can be dragged from the desktop onto the board or selected with **Add Document**. Pasting a clipboard image creates a persisted image Document, which supports ordinary macOS and Windows screenshot workflows. Images, PDFs, and text files render inside document windows; unknown formats remain downloadable source files. Extracted evidence becomes an editable folder widget. Its editor controls the title, annotation, contained documents, and each source document's publication time. The default upload limit is 25 MB and can be changed with `MAX_DOCUMENT_BYTES`.
+
+Image uploads are OCRed by the Tesseract executable bundled into the application image; text-file uploads use their text directly. Extracted text is stored against the immutable asset, copied into the Document's searchable body, and evaluated against level-authored fuzzy passage rules. A successful rule awards its configured flag and immediately participates in ordinary document reveals. Rules, anchors, per-anchor scores, and evaluation provenance are normalized PostgreSQL data—no case text is compiled into the engine. OCR is time-limited and failure-tolerant: the source remains on the board even when text extraction fails. `OCR_LANGUAGES`, `OCR_TIMEOUT_MS`, `MAX_OCR_BYTES`, and `MAX_EXTRACTED_TEXT_CHARACTERS` tune the worker; `OCR_ENABLED=false` disables image OCR without disabling uploads. Authors configure passages under **Admin → Evidence Matching** while editing a level.
+
+In author mode, a Document may be assigned comma-separated reveal flags in its metadata editor. Play-mode level responses omit gated Documents until all requirements are earned. Admins can exercise the demo through **Admin → Level Flags**; newly delivered evidence receives a one-time arrival animation.
 
 Production defaults editing to disabled. Set `LEVEL_EDITING_ENABLED=true` in `/opt/gu_common/.env.prod` only when the authoring surface should be available. `JWT_SECRET` is inherited from that shared environment, and authoring endpoints additionally require a verified admin claim.
 
@@ -126,4 +139,4 @@ The deploy script builds and syncs the application, reads production database cr
 
 ## Deliberate POC boundaries
 
-Authentication is supplied by the shared Glitch University account system. There is no OSINT-specific account model, real-world web browsing, OCR, or collaboration yet. The server data model and provenance fields leave room for those later without making them part of the first playability test.
+Authentication is supplied by the shared Glitch University account system. There is no OSINT-specific account model, real-world web browsing, or collaboration yet. OCR deliberately recognizes only evidence the player brings onto the board; it does not fetch or search the web.