Classhub demo solid state

Author: bseverns

docs/COURSEPACK_REGISTRY_RFC.md

@@ -2,6 +2,7 @@
 
 ## Status
 
+- Closed for the current release line on `main` as of 2026-06-20.
 - Local authoring/package tooling is live and should be treated as the shipped source-of-truth workflow.
 - Live import/export flows are also real on `main`, including:
   - local SDK validation/build/package via `scripts/coursepack_sdk.py`
@@ -22,11 +23,11 @@
   - `/teach` now includes a filtered content/import audit surface for recent packaging and import operations,
   - operators can deep-link into a selected audit row and inspect stored provenance metadata without leaving `/teach`,
   - class dashboards now include shortcuts into the class-scoped audit feed.
-- Remote registry service, signed discovery API, and desktop GUI authoring remain optional future work and should not be implied as active roadmap commitments without a concrete operator need.
+- Remote registry service, signed discovery API, and desktop GUI authoring remain parked future work and should not be implied as active roadmap commitments without a concrete operator need.
 
-## Closure recommendation
+## Closure
 
-Close this RFC as implemented for the current release line. Phase 1 and the bounded Phase 2 static-index slice are complete.
+This RFC is implemented for the current release line. Phase 1 and the bounded Phase 2 static-index slice are complete.
 
 Remaining items are deferred product/governance decisions, not active implementation commitments:
 
@@ -57,7 +58,7 @@ Implemented now:
   - `package`: package only (skip validation)
 - `docs/COURSE_AUTHORING.md` now documents SDK usage as the primary local workflow.
 
-Still not implemented:
+Parked future work:
 - Remote registry service/API for signed discovery and sync orchestration.
 - Desktop GUI app for drag-drop authoring/packaging.
 - District-grade signed artifact verification and trust policy management.

docs/CURRENT_STATE.md

@@ -3,7 +3,7 @@
 ## Summary
 This page is the live snapshot of what ClassHub currently ships on `main`.
 It is updated manually when shipped capabilities change.
-Last reviewed: 2026-06-09
+Last reviewed: 2026-06-20
 
 ## Current state at a glance
 
@@ -21,7 +21,7 @@ Last reviewed: 2026-06-09
 ### Teacher/program operations
 - Teacher portal supports roster, lesson release controls, submissions, moderation, outcomes, certificates, and class closeout workflows.
 - Superuser org, staff, class assignment, coursepack import, and content/import audit tools are live.
-- Teacher day-of-class shell and top-task choreography are wired into `/teach`.
+- Teacher day-of-class shell and top-task choreography are wired into `/teach`, with stabilized first-contact CTA wording for create/open class, join-card sharing, submission review, lessons, and summary export.
 
 ### Trust, privacy, and org boundaries
 - `/trust`, `/student/my-data`, retention presets, student rename/export/delete controls, and privacy-safe support tags are live.
@@ -64,11 +64,11 @@ Last reviewed: 2026-06-09
 - Repo now ships a narrow Headscale control-plane ops bundle for the Jetson_B/`hs.creatempls.org` role: bootstrap, Compose stack, backup, restore, and systemd timer artifacts live under `ops/headscale/`.
 - Repo now also ships a Headscale replacement-host rehearsal wrapper (`bash scripts/headscale_restore_rehearsal_evidence.sh --backup ...`) that captures control-plane restore artifacts plus LMS/Thundercompute-side verification placeholders.
 - Helper classroom-quality eval tooling is live (`scripts/run_helper_classroom_eval.sh` + classroom prompt pack in `services/homework_helper/tutor/fixtures/eval_prompts_classroom_realistic.jsonl`).
-- Coursepack Authoring SDK is live via `scripts/coursepack_sdk.py` (validate/build/package local content artifacts, checksum sidecars, static registry index create/validate/list/fetch flows), and ClassHub can now import directly from a static registry index via `manage.py import_coursepack_registry` as well as superuser browser flows in `/teach` and `/admin`.
+- Coursepack Authoring SDK is live via `scripts/coursepack_sdk.py` (validate/build/package local content artifacts, checksum sidecars, static registry index create/validate/list/fetch flows), and ClassHub can now import directly from a static registry index via `manage.py import_coursepack_registry` as well as superuser browser flows in `/teach` and `/admin`. The coursepack registry RFC is closed for the current release line; live operator workflow belongs in `COURSEPACK_REGISTRY_PUBLISHING.md` and `COURSE_AUTHORING.md`.
 - Registry remote fetches are timeout-bounded and byte-capped for indexes, checksum sidecars, and artifact downloads; artifact verification streams SHA-256 calculation instead of loading the full remote payload into memory first.
 - `/teach` now includes a filtered content/import audit feed for recent registry imports, upload imports, syllabus compilation, template generation, and syllabus export operations.
 - Teacher syllabus zip import now maps session-prefixed support images into lesson assets.
-- Organization boundaries and RBAC capability checks are live.
+- Organization boundaries and RBAC capability checks are live. The RBAC capabilities RFC is closed for architecture; live operator guidance belongs in `RBAC_GUIDE.md` and rollout truth belongs in `FEATURE_MATURITY.md`.
 - Scoped RBAC grants are live behind `CLASSHUB_RBAC_SCOPED_GRANTS_ENABLED`.
 - RBAC simulation and policy bundle import/export endpoints are live for operators.
 - RBAC custom roles are live (role definitions, capabilities, and staff assignments) in teacher RBAC tools and policy bundles.
@@ -84,7 +84,7 @@ Last reviewed: 2026-06-09
 - Telemetry split Phase 1 Slice 0/1/2/3/4/5/6 scaffolding is live (validated telemetry mode envs, optional telemetry DB registration in settings, telemetry router + dedicated `hub_telemetry` schema app, centralized dual-write service seam for event/outcome emit paths, read abstraction for support/rollup/lifespan event queries, baseline split-write instrumentation counters/log fields, an idempotent `backfill_telemetry_events` command with dry-run/batch resume controls, and a strict `check_telemetry_parity` command for cutover gates). Slice 7 release-cycle evidence capture is complete at `artifacts/stability/2026-03-10/telemetry/` (parity + strict smoke + rollback drill).
 - Telemetry evidence tooling now also renders machine-checked `slo_summary.md` artifacts from explicit metric inputs and can include telemetry DB backup/restore validation in restore rehearsal evidence when telemetry split is active.
 - Superuser runtime policy lock checks are live in `/teach?advanced=1&portal_mode=admin` and in stability guardrails via `scripts/check_runtime_policy_lock.py`.
-- Teacher top-task choreography and `Start Here Today` contract wiring are live in `/teach` and guarded by `scripts/check_teacher_top_tasks_contract.py`.
+- Teacher top-task choreography and `Start Here Today` contract wiring are live in `/teach` and guarded by `scripts/check_teacher_top_tasks_contract.py`; the current wording baseline uses `Create class workspace`, `Print join card`, `Open class`, `Review submissions`, `Lessons`, and `Export summary CSV`.
 - Registry-backed docs truth checks are live via `docs/_registry/runtime_contracts.json` and `scripts/check_docs_truth.py`.
 
 ## Deployment and reliability posture
@@ -130,4 +130,4 @@ Last reviewed: 2026-06-09
 - Infrastructure hardening roadmap: [INFRASTRUCTURE_HARDENING_ROADMAP.md](INFRASTRUCTURE_HARDENING_ROADMAP.md)
 - Ops execution: [RUNBOOK.md](RUNBOOK.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
 - Remote-compute evidence: [EVIDENCE_REMOTE_COMPUTE.md](EVIDENCE_REMOTE_COMPUTE.md)
-- RBAC implementation and policy ops: [RBAC_GUIDE.md](RBAC_GUIDE.md), [RBAC_CAPABILITIES_RFC.md](RBAC_CAPABILITIES_RFC.md)
+- RBAC implementation and policy ops: [RBAC_GUIDE.md](RBAC_GUIDE.md), [FEATURE_MATURITY.md](FEATURE_MATURITY.md), [RBAC_CAPABILITIES_RFC.md](RBAC_CAPABILITIES_RFC.md) for historical architecture rationale.

docs/DECISIONS.md

@@ -4343,3 +4343,47 @@ Execution ownership and gates:
 - Reduces drift between repo documentation and actual platform behavior.
 - Makes it easier to decide what should be built next versus what should stop pretending to be near-term.
 - Keeps roadmap language honest for operators, contributors, and future product decisions.
+
+## Teacher first-contact wording baseline (2026-06-20)
+
+**Current decision:**
+- Keep `/teach` and `/teach/class/<id>` first-contact CTAs aligned to one small vocabulary:
+  - `Create class workspace`
+  - `Print join card`
+  - `Open class`
+  - `Review submissions`
+  - `Lessons`
+  - `Export summary CSV`
+- Keep operator/import/policy language below the classroom-first path when both are visible.
+- Treat destructive class-dashboard actions as copy-sensitive controls:
+  - permanent roster/student deletion copy must say what is deleted and that it cannot be undone,
+  - helper conversation reset copy should describe cache clearing and optional export, not imply the same permanence as roster deletion.
+
+**Why this remains active:**
+- Reduces first-time teacher ambiguity without adding routes, models, or workflows.
+- Keeps copy/order stabilization tied to the top-task contract in `docs/TEACHER_TOP_TASKS.md`.
+- Makes irreversible actions easier to distinguish from reversible or cache-only maintenance actions.
+
+## Implemented RFCs stay historical once live (2026-06-20)
+
+**Current decision:**
+- Mark `docs/RBAC_CAPABILITIES_RFC.md` closed for architecture; use `docs/RBAC_GUIDE.md` and `docs/FEATURE_MATURITY.md` for live RBAC operation and rollout truth.
+- Mark `docs/COURSEPACK_REGISTRY_RFC.md` closed for the current release line; use `docs/COURSEPACK_REGISTRY_PUBLISHING.md` and `docs/COURSE_AUTHORING.md` for live workflow.
+- Keep the RFCs in the docs tree as historical rationale and bounded future-polish records, not active implementation backlogs.
+
+**Why this remains active:**
+- Prevents shipped architecture from continuing to look speculative.
+- Points operators and future agents to the docs that describe current behavior.
+- Keeps optional future work parked until concrete operator need appears.
+
+## Remote compute metric accounting split (2026-06-20)
+
+**Current decision:**
+- Keep `tutor/remote_compute_control.py` responsible for lease lifecycle, provider state refresh, readiness, and routing decisions.
+- Move per-class accounting counters into `tutor/remote_compute_metrics.py`.
+- Keep the public control API unchanged while reducing the size and responsibility of the lifecycle controller.
+
+**Why this remains active:**
+- Makes the remote-compute hot spot easier to review without changing behavior.
+- Keeps future bridge/idempotency hardening focused on lifecycle and audit semantics instead of mixed metric bookkeeping.
+- Preserves durable metric behavior through the existing `remote_compute_store` persistence layer.

docs/DOCS_MAP.md

@@ -116,10 +116,11 @@ You should be able to find the canonical doc for a topic without opening multipl
 - [HUBCTL.md](HUBCTL.md)
 - [LOCALIZATION.md](LOCALIZATION.md)
 - [LOCALIZATION_SO_REVIEW_PACKET.md](LOCALIZATION_SO_REVIEW_PACKET.md)
-- [COURSEPACK_REGISTRY_RFC.md](COURSEPACK_REGISTRY_RFC.md)
+- [COURSEPACK_REGISTRY_PUBLISHING.md](COURSEPACK_REGISTRY_PUBLISHING.md)
+- [COURSEPACK_REGISTRY_RFC.md](COURSEPACK_REGISTRY_RFC.md) (historical rationale; current release line closed)
 - [ASYNC_SELF_PACED_RFC.md](ASYNC_SELF_PACED_RFC.md)
 - [IDENTITY_SSO_EXPANSION_PLAN.md](IDENTITY_SSO_EXPANSION_PLAN.md)
-- [RBAC_CAPABILITIES_RFC.md](RBAC_CAPABILITIES_RFC.md)
+- [RBAC_CAPABILITIES_RFC.md](RBAC_CAPABILITIES_RFC.md) (historical rationale; architecture closed)
 - [TELEMETRY_DB_SPLIT_PLAN.md](TELEMETRY_DB_SPLIT_PLAN.md)
 - [RUNTIME_LOCK_PROFILES.md](RUNTIME_LOCK_PROFILES.md)
 - [KIOSK_PWA.md](KIOSK_PWA.md)

docs/MAINTENANCE_RISK_REGISTER.md

@@ -24,7 +24,7 @@ Use this register as a pruning tool, not just a warning list.
 - Evidence:
   - `/teach` and related routes aggregate many staff workflows in one surface: [TEACHER_PORTAL.md](TEACHER_PORTAL.md)
   - `teach_home` assembles class list, profile, teacher invites, org admin, submissions, and template generation in one view: `services/classhub/hub/views/teacher_parts/content_home.py`
-  - baseline shell sizes remain tracked: `services/classhub/templates/teach_home.html` is 81 lines; `services/classhub/templates/teach_class.html` is 82 lines; `services/classhub/hub/views/teacher_parts/roster_class.py` is 80 lines after split, with extracted endpoint logic in `services/classhub/hub/views/teacher_parts/roster_class_dashboard.py` (148 lines) and `services/classhub/hub/views/teacher_parts/roster_class_controls.py` (295 lines)
+  - baseline shell sizes remain tracked: `services/classhub/templates/teach_home.html` is 81 lines; `services/classhub/templates/teach_class.html` is 83 lines; `services/classhub/hub/views/teacher_parts/roster_class.py` is 80 lines after split, with extracted endpoint logic in `services/classhub/hub/views/teacher_parts/roster_class_dashboard.py` (148 lines) and `services/classhub/hub/views/teacher_parts/roster_class_controls.py` (295 lines)
   - root templates are slimmed, but complexity now lives in bounded section partials/builders: `services/classhub/templates/includes/teach_class/class_setup_roster_student_row.html` is 83 lines; `services/classhub/templates/includes/teach_class/support_board_card.html` is 102 lines; `services/classhub/hub/services/teacher_dashboard_sections/facilitator_support_builders.py` is 213 lines
   - size/function budgets are continuously guarded in CI via `scripts/check_view_size_budgets.py` and `scripts/check_view_function_budgets.py`
   - section-level budgets and decomposition contracts are guarded via `scripts/check_teach_class_section_budgets.py`, `scripts/check_teach_class_template_contract.py`, and `scripts/check_teacher_roster_service_contract.py`

docs/RBAC_CAPABILITIES_RFC.md

@@ -2,17 +2,17 @@
 
 ## Status
 
-- This RFC is mostly implemented on `main`.
+- Closed for architecture on `main` as of 2026-06-20.
 - The evaluator, scoped grants, simulation tools, policy import/export, custom role persistence, and delegated approval queue foundation are all real.
 - The remaining work is not core RBAC existence; it is operational polish for district-scale approval routing and higher-level administration UX.
 
-## Closure recommendation
+## Closure
 
-Treat this RFC as effectively closed for architecture. Ongoing work should move under implementation docs and maturity tracking:
+Treat this RFC as historical architecture rationale. Ongoing work should move under implementation docs and maturity tracking:
 
 - keep [RBAC_GUIDE.md](RBAC_GUIDE.md) as the operator/how-to source,
 - keep [FEATURE_MATURITY.md](FEATURE_MATURITY.md) as the rollout truth,
-- reserve this RFC for historical architecture rationale plus the small list of remaining non-shipped items.
+- reserve this RFC for the rationale that led to the shipped model plus the small list of remaining non-shipped polish items.
 
 ## Summary
 ClassHub currently uses organization roles (`owner`, `admin`, `teacher`, `viewer`) with coarse permissions. This RFC defines a capability-driven RBAC model that supports district-grade policy needs while preserving current behavior during rollout.
@@ -67,7 +67,7 @@ Implemented on `main`:
   - `CLASSHUB_RBAC_POLICY_APPROVAL_REQUIRED=1`
   - policy mutations queue `RbacPolicyChangeRequest` and require separate reviewer approval.
 
-Still RFC/pending:
+Still parked/future polish:
 - Hardened district-scale approval routing (multi-step approvers, notification routing, SLA escalation).
 - More polished custom-role administration UX beyond the current operator tooling surface.
 

docs/TEACHER_TOP_TASKS.md

@@ -7,24 +7,31 @@ Use it for:
 - copy/order decisions in teacher surfaces
 - release readiness checks against real teacher workflows
 
-Last updated: March 11, 2026
+Last updated: June 20, 2026
 
 Current UI contract:
 - `/teach` now surfaces a **Start Here Today** block that maps this list into:
   - daily teaching workflows (tasks 1-8),
   - operator/policy workflows (tasks 9-10, superuser + advanced mode).
+- First-contact CTA wording is intentionally stable across `/teach` and `/teach/class/<id>`:
+  - `Create class workspace`
+  - `Print join card`
+  - `Open class`
+  - `Review submissions`
+  - `Lessons`
+  - `Export summary CSV`
 
 ## Task Map
 
 | # | Task | Primary routes/actions | Completion signal |
 | --- | --- | --- | --- |
 | 1 | Create a class | `POST /teach/create-class` from `/teach` | New class row appears with join code and open status. |
 | 2 | Share join access with students | `GET /teach/class/<id>/join-card`, copy class join code on `/teach` or `/teach/class/<id>` | Students can join via class code or printed join card. |
-| 3 | Open class dashboard for live teaching | `GET /teach/class/<id>` | Class dashboard loads with roster, modules, and status controls. |
+| 3 | Open class for live teaching | `GET /teach/class/<id>` | Class dashboard loads with roster, modules, and status controls. |
 | 4 | Review submission queue and download work | `GET /teach/material/<material_id>/submissions`, `GET /submission/<id>/download` | Teacher can see missing/submitted rows and retrieve files. |
 | 5 | Close/open class access at session boundaries | `POST /teach/class/<id>/toggle-lock` (and closeout lock action) | Class state pill changes (`Open`/`Locked`) and student join behavior changes accordingly. |
 | 6 | Set lesson release schedule and helper scope | `POST /teach/lessons/release` from class lesson release grid | Release date/scope values persist and appear in lesson release table. |
-| 7 | Export day-of-class outputs | `GET /teach/class/<id>/export-submissions-today`, `GET /teach/class/<id>/export-outcomes-csv`, `GET /teach/class/<id>/export-summary-csv` | Export downloads succeed and include current class data. |
+| 7 | Export summary and day-of-class outputs | `GET /teach/class/<id>/export-submissions-today`, `GET /teach/class/<id>/export-outcomes-csv`, `GET /teach/class/<id>/export-summary-csv` | Export downloads succeed and include current class data. |
 | 8 | Correct roster identity mistakes | `POST /teach/class/<id>/rename-student`, `POST /teach/class/<id>/merge-students` | Target student names/records update without duplicate roster confusion. |
 | 9 | Create/invite and maintain teacher accounts (admin/superuser) | `POST /teach/create-teacher`, `POST /teach/teacher-account/*` actions | Teacher account row reflects expected active/superuser/invite state. |
 | 10 | Maintain organization boundaries and assignments (admin/superuser) | `POST /teach/org-membership/upsert`, `POST /teach/class-staff-assignment/upsert`, `POST /teach/class-organization/set` | Membership/assignment rows update and class scope reflects intended org boundary. |

mkdocs.yml

@@ -112,10 +112,10 @@ nav:
       - Facilitator CLI (hubctl): HUBCTL.md
       - Localization: LOCALIZATION.md
       - Somali Review Packet: LOCALIZATION_SO_REVIEW_PACKET.md
-      - Coursepack Registry RFC: COURSEPACK_REGISTRY_RFC.md
+      - Coursepack Registry RFC (Historical): COURSEPACK_REGISTRY_RFC.md
       - Async Self-Paced RFC: ASYNC_SELF_PACED_RFC.md
       - Identity SSO Expansion Plan: IDENTITY_SSO_EXPANSION_PLAN.md
-      - RBAC Capabilities RFC: RBAC_CAPABILITIES_RFC.md
+      - RBAC Capabilities RFC (Historical): RBAC_CAPABILITIES_RFC.md
       - Telemetry DB Split Plan: TELEMETRY_DB_SPLIT_PLAN.md
       - Runtime Lock Profiles: RUNTIME_LOCK_PROFILES.md
       - Classroom Kiosk PWA: KIOSK_PWA.md