Clarify Doris stack README purpose and runtime

home/doris-schoolhouse/README.md

@@ -1,10 +1,21 @@
 # Doris Schoolhouse
 
-Desktop-first local web app for school intake, recordings, D2L sync, and Paperless linkage.
+Desktop-first school operations app for John.
 
-## Purpose
+## What it is
 
-This app gives John a fast local UI to:
+Doris Schoolhouse is the front door for John's college workflow. It pulls scattered school chores into one place so Doris can handle intake, metadata, archiving, and later grade follow-up without bouncing between D2L, file uploads, recordings, and Paperless by hand.
+
+In plain English, this stack exists to answer:
+
+- what classwork is due
+- where a submission or recording should be filed
+- how that item should be archived and tagged
+- whether grading/comments later made it back onto the archived record
+
+## What it does
+
+Schoolhouse gives John a local UI to:
 
 - upload assignment turn-ins, with programming-class source files bundled into one archived submission artifact
 - upload class recordings
@@ -13,25 +24,51 @@ This app gives John a fast local UI to:
 - sync classes/assignments/grades/comments from D2L
 - archive submissions/transcripts/summaries in Paperless
 
-## Source vs runtime
+## Why it exists
+
+The point is not just "another web app." The point is to make school intake boring and repeatable.
+
+- D2L is the source for classes, assignments, grades, and comments.
+- Schoolhouse is the operational layer where uploads, recordings, and metadata are managed.
+- Paperless is the long-term archive for receipts, transcripts, summaries, and school documents.
+- n8n handles the workflow glue between intake events and downstream processing.
+
+That split keeps John from doing the same clerical nonsense over and over, and gives Doris one consistent place to reason about schoolwork.
+
+## Runtime model
 
 - **Repo source:** `home/doris-schoolhouse`
-- **Expected live NOMAD runtime:** `/opt/doris-schoolhouse`
+- **Live NOMAD runtime:** `/opt/doris-schoolhouse`
+- **Published app port:** `8091`
+- **Public path:** `schoolhouse.paccoco.com` behind Pangolin OAuth
+- **Storage:** shared Postgres in production, JSON fallback for local iteration
+- **Archive path:** Paperless + n8n school workflows
 
-Do not run production from an agent workspace.
+Do not run production from an agent workspace. Repo source is for editing; `/opt/doris-schoolhouse` is the live runtime.
 
-## Stack
+## How it works
 
 - FastAPI
 - Jinja2 templates
 - shared Postgres
-- Pangolin network
+- Pangolin-authenticated public route
 - existing Paperless and n8n school workflows
-- container build now includes Python deps + `ffmpeg` for recording conversion
+- bundled `ffmpeg` for recording conversion inside the container
+
+Typical flow:
+
+1. D2L data is synced into Schoolhouse.
+2. John uploads an assignment or recording through Schoolhouse.
+3. Schoolhouse normalizes the intake payload and keeps local/runtime state.
+4. n8n receives the handoff and pushes the right artifacts into Paperless.
+5. Paperless becomes the durable archive.
+6. Later grade/comment updates can be reflected back onto the archived record.
+
+Programming-class uploads get special handling: multiple source files are bundled into one canonical source archive, with manifest and receipt/listing artifacts so the repo of what was turned in stays coherent.
 
 ## Current state
 
-The app is live on NOMAD at `/opt/doris-schoolhouse` and uses shared Postgres in production.
+Schoolhouse is live on NOMAD and already covers the real workflow, not just a mockup.
 
 For local iteration, the source tree still supports a JSON-backed mode:
 
@@ -49,11 +86,11 @@ Production runtime uses shared Postgres plus Paperless/n8n integration.
 
 `SCHOOLHOUSE_STORAGE_BACKEND=auto` prefers Postgres when psycopg and a PostgreSQL DSN are available, and falls back to JSON state for local iteration.
 
-Repo contents still include:
-- route handlers and templates
+This repo directory contains:
+- the FastAPI app and templates
 - schema/bootstrap helpers
 - compose/env examples
-- D2L / Paperless / n8n integration code
+- D2L, Paperless, and n8n integration code
 
 ## Layout