Clarify Doris stack README purpose and runtime

home/doris-dashboard/README.md

@@ -1,6 +1,56 @@
 # Doris Dashboard
 
-Local static homepage for John’s morning briefing and peek-anytime news dashboard.
+Local homepage for John's briefing, glanceable status, and "what matters right now" view.
+
+## What it is
+
+Doris Dashboard is the quiet front page for John's local information stack on NOMAD. It is not a general website and it is not meant to be another feed reader with a fresh coat of paint. It exists to turn Doris Digest output and a few homelab/task signals into one page John can open for a fast read.
+
+The dashboard is meant to answer:
+
+- what is worth looking at this morning
+- what local or homelab signals need attention
+- what chores or Paperless follow-ups are still hanging around
+- what topics are surfacing too often and should be tuned down
+
+## Why it exists
+
+Without this stack, the raw inputs are noisy:
+
+- Doris Digest candidates are too broad on their own
+- Donetick and Paperless are useful but fragmented
+- local weather/sky/homelab signals live in separate places
+
+The dashboard turns that into one opinionated, local-only page that Doris can tune over time.
+
+## Runtime model
+
+- **Repo source:** `/home/fizzlepoof/repos/truenas-stacks/home/doris-dashboard`
+- **Live runtime:** `/opt/doris-dashboard`
+- **Generated page:** `/opt/doris-dashboard/public/index.html`
+- **LAN URL:** `http://10.5.1.16:8787/`
+- **Exposure rule:** local-only unless John explicitly asks otherwise
+
+## What it shows
+
+- top briefing cards from Doris Digest candidates
+- space / homelab / local / other signal lanes
+- an experimental `New to You` lane for off-profile category sampling
+- Donetick tasks
+- Paperless review queue items
+- weather, sky, and homelab pulse cards
+- lightweight stats about candidate/source mix
+
+## How it works
+
+- `bin/generate_dashboard.py` reads Doris Digest candidates plus a few local/runtime data files.
+- It scores, deduplicates, and groups stories into dashboard sections.
+- It writes generated JSON artifacts under `data/` and the final static page under `public/`.
+- `bin/dashboard_server.py` serves the page and handles interactive actions like topic feedback and Paperless review state.
+
+That means the dashboard is static-looking for the reader, but still has enough local interactivity for feedback and review flows.
+
+## Live paths
 
 Live runtime path:
 
@@ -8,30 +58,12 @@ Live runtime path:
 /opt/doris-dashboard
 ```
 
-Source path in the homelab repo:
-
-```bash
-/home/fizzlepoof/repos/truenas-stacks/home/doris-dashboard
-```
-
 Generated page:
 
 ```bash
 /opt/doris-dashboard/public/index.html
 ```
 
-## What it shows
-
-- Morning briefing with fleshed-out cards
-- Today panel for calendar placeholders
-- To-do panel for Donetick/to-do placeholders
-- Notes panel
-- Sky / Space
-- Homelab / Smart Home / Ham Radio
-- Local news
-- Other signal
-- Source/candidate stats
-
 ## Generate manually
 
 ```bash

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