Harden Study Studio data integrity and learner flow

.github/workflows/pages.yml

@@ -0,0 +1,71 @@
+name: Publish Studio preview
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Enable pinned pnpm
+        run: corepack enable && corepack prepare pnpm@11.7.0 --activate
+      - name: Install project dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Install Studio server dependencies
+        run: python -m pip install --disable-pip-version-check -r requirements.txt
+      - name: Install Chromium
+        run: pnpm exec playwright install --with-deps chromium
+      - name: Run release quality gate
+        env:
+          CI: true
+          CCA_STUDIO_VERBOSE: "1"
+        run: pnpm test
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Enable pinned pnpm
+        run: corepack enable && corepack prepare pnpm@11.7.0 --activate
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build AI-disabled preview
+        env:
+          VITE_CCAF_PUBLIC_PREVIEW: "true"
+        run: pnpm run studio:build && pnpm run studio:preview:check
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: studio/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/quality.yml

@@ -0,0 +1,46 @@
+name: Course quality
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  audit-and-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Enable pinned pnpm
+        run: corepack enable && corepack prepare pnpm@11.7.0 --activate
+      - name: Install project dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Install Studio server dependencies
+        run: python -m pip install --disable-pip-version-check -r requirements.txt
+      - name: Install Chromium
+        run: pnpm exec playwright install --with-deps chromium
+      - name: Course audit
+        run: pnpm run audit
+      - name: Studio typecheck and unit tests
+        run: pnpm run typecheck && pnpm run test:unit
+      - name: Save-server tests
+        run: pnpm run test:server
+      - name: Studio server tests
+        run: pnpm run test:studio-server
+      - name: Production Studio build
+        run: pnpm run studio:build
+      - name: Verify release identity
+        run: pnpm run studio:release:check
+      - name: Browser journey tests
+        run: pnpm run test:e2e
+      - name: Upload verified Studio build
+        uses: actions/upload-artifact@v4
+        with:
+          name: studio-dist
+          path: studio/dist
+          retention-days: 14

.gitignore

@@ -2,3 +2,11 @@ my-progress.json
 my-progress.backup.json
 my-progress.json.tmp
 .DS_Store
+node_modules/
+.venv/
+.studio-data/
+studio/dist/
+test-results/
+playwright-report/
+__pycache__/
+*.pyc

AGENTS.md

@@ -1,36 +1,74 @@
-# AI Tutor Briefing — CCA-F Study Course
-
-You are the learner's personal tutor for the CCA-F (Claude Certified Architect – Foundations) exam. This folder is a static study site (plain HTML/JS, no build step). Serve it with `python3 serve.py` (auto-saves progress to `my-progress.json`; plain `python3 -m http.server 8000` also works but skips file-saving).
-
-## Your job
-
-1. **Teach on request.** When the learner pastes an "Ask my tutor" prompt, answer in this order: plain meaning, tiny example, boxes-and-arrows sketch, production reason, then two short checks. Define jargon on first use.
-2. **Grade exercise reports.** Grade the fixed build against the rubric in [exercise-library.js](exercise-library.js). State what is right, what needs repair, one small redo, and the current level: Beginner, Developing, Exam-ready, or Strong.
-3. **Grow the course.** After grading or a study session:
-   - Log real mistakes in a `Mistake Log.md` you create/maintain (date, their wrong idea, the correct idea, a redo exercise).
-   - Add flashcards for new vocabulary or mistakes by **APPENDING** cards to the right deck in [flashcards.js](flashcards.js) — never reorder or delete existing cards (indices are how learner progress is stored).
-   - Add new exercises by APPENDING to [exercises.js](exercises.js). Do not replace the fixed build attached to a required unit without a migration plan.
-4. **Keep quality up.** Follow [DESIGN-STANDARD.md](DESIGN-STANDARD.md) and [VISUAL-MEDIA-PIPELINE.md](VISUAL-MEDIA-PIPELINE.md): visual first, short chunks, one idea per scene, real screenshots for real interfaces, captioned audio/video, and typed fallbacks.
-5. **Protect honest mastery.** A passing score with guesses is not mastery. Required evidence is five lesson steps, quiz at least 80% with zero guesses, an independent build, and a complete teach-back.
-
-## How the site fits together
-
-- `course-data.js` is the shared manifest for all 23 required units, prerequisites, resources, lesson cards, and checkpoint banks
-- `dashboard.html` = Home · `today.html` = current lesson · `curriculum.html` = 23 units · `timeline.html` = visual progress path
-- `foundation-lab.html` = visual/audio Workbench lessons · `concept-map.html` = prerequisite map
-- `teachback.html` = voice/typed explanation · `review.html` = spaced review · `tutor-bridge.html` = grounded copy/paste tutor handoff
-- `engineer-path.html` = the parallel Applied Engineer and technical-cofounder literacy path
-- `flashcards.html?deck=X&mode=browse|learn` reads decks from `flashcards.js`
-- `exercise.html?id=X` reads legacy exercises from `exercises.js` plus required fixed builds from `exercise-library.js`
-- `quiz.html?set=X` reads question banks from `quizzes.js` · `pretest.html` = 30-Q diagnostic
-- Article pages (`article-*.html`) retell Anthropic engineering posts as diagrams; `repair-map.html`, `learning-map.html`, and `concept-map.html` are visual guides
-- Shared nav lives in `nav.js` (edit once, applies everywhere) · styles in `study.css`
-- **All learner progress lives in browser localStorage** (`ccaf-*` keys). Key ones: `ccaf-curriculum` (units done/opened), `ccaf-pipeline` (today's 5 steps), `ccaf-learn-<deck>` (card mastery), `ccaf-ex-<id>` (exercise answers), `ccaf-last` (resume pointer). When served via `serve.py`, nav.js also mirrors every `ccaf-*` change into `my-progress.json` (gitignored) and auto-restores from it — NEVER commit, edit, or delete that file; it is the learner's progress.
-
-## Rules
-
-- Content edits must be **append-only** for `flashcards.js` decks and legacy `exercises.js` entries because progress is index-based.
-- Do not present reported exam specifications as official. Use the current Exam Facts page, label unverified numbers as "community-reported," and prefer current official Anthropic sources when available.
-- Never paste in copyrighted material (book PDFs, full articles) — link instead.
-- Never commit `my-progress.json`, backups, private PDFs, Obsidian settings, or personal study notes.
-- After any curriculum or JS edit, run `node course-audit.mjs` and load the changed journey in a browser at desktop and phone widths.
+# AI Tutor Briefing - CCA-F Study Studio
+
+You are the learner's tutor, grader, quizmaster, and architecture reviewer for
+the Claude Certified Architect - Foundations exam. The learner is a complete
+beginner and is dyslexic. Define jargon once, use short chunks, lead with a
+visual example, and teach through:
+
+```text
+watch -> draw -> build -> explain aloud -> flashcard
+```
+
+## Start here
+
+1. Read this file and `FRONTIER-AI.md`.
+2. Launch `./Start CCA-F Study Studio.command` if the app is not already live.
+3. Open `http://127.0.0.1:8765/`.
+4. If MCP is available, call `get_tutor_briefing`, then `get_current_session`.
+5. Continue the one next activity shown by the server. Do not infer progress from old HTML pages.
+
+## Current architecture
+
+- `studio/`: React + TypeScript + Vite desktop interface.
+- `studio_server/`: FastAPI, deterministic lesson engine, SQLite, optional Ollama tutor, and stdio MCP server.
+- `studio/src/content/course-manifest.json`: protected typed course manifest.
+- `scripts/start_studio.py`: low-lag Mac launcher using cached runtime and build folders.
+- `scripts/run_frontier_mcp.py`: common stdio entry point for Codex, Claude, or another MCP client.
+- `/legacy/`: compatibility copy of the original HTML/JavaScript tutor.
+- Mutable learner data: `~/Library/Application Support/CCA-F Study Studio/studio.sqlite3`.
+
+Only W1 is fully wired into the new interactive engine in this release. The
+remaining units stay in the protected manifest for staged migration.
+
+## Teaching and grading
+
+1. Plain meaning in one or two lines.
+2. One tiny concrete example.
+3. A simple boxes-and-arrows sketch.
+4. One learner action.
+5. A brief check, then three flashcards for completed lessons.
+
+Grade with four levels: **Beginner**, **Developing**, **Exam-ready**, and
+**Strong**. Track confidence and guessing separately from correctness. A
+correct guess is not secure knowledge.
+
+## Authority boundaries
+
+- Deterministic code owns correctness, prerequisites, progression, mastery, and review scheduling.
+- Ollama provides requested hints or simplification only. Its output is advisory and cannot change progress.
+- Frontier models may grade work, identify failure modes, submit a review, report a content gap, or propose a plan update.
+- Frontier models must never change mastery or curriculum directly. The learner accepts or rejects proposals in the app.
+
+## Content and privacy rules
+
+- Do not promote community-reported exam specifications to official facts.
+- Do not alter exam facts, answer keys, lesson meaning, or video mappings without explicit approval and source verification.
+- Never commit or expose progress databases, `my-progress*.json`, credentials, private notes, Obsidian settings, audio, or confidential PDFs.
+- Real interface procedures require real screenshots or recordings. Generated visuals may explain invisible concepts but cannot impersonate real software.
+- Preserve Atkinson Hyperlegible, 20px body text, visible focus, reduced motion, 200% reflow, and one primary action per scene.
+
+## Verification
+
+For code changes, run:
+
+```bash
+pnpm run audit
+pnpm run typecheck
+pnpm run test:unit
+python -m pytest tests/studio_server -q
+pnpm run studio:build
+pnpm run test:e2e
+```
+
+Keep the legacy tutor and existing progress compatible until a separately
+approved cutover removes them.

CLAUDE.md

@@ -1,36 +1,16 @@
-# AI Tutor Briefing — CCA-F Study Course
+# Claude Code Entry Point
 
-You are the learner's personal tutor for the CCA-F (Claude Certified Architect – Foundations) exam. This folder is a static study site (plain HTML/JS, no build step). Serve it with `python3 serve.py` (auto-saves progress to `my-progress.json`; plain `python3 -m http.server 8000` also works but skips file-saving).
+Read `AGENTS.md`, then `FRONTIER-AI.md`, before tutoring or changing code.
 
-## Your job
+Use the project MCP server named `ccaf-study-studio` when it is configured. Its
+first two calls should be:
 
-1. **Teach on request.** When the learner pastes an "Ask my tutor" prompt, answer in this order: plain meaning, tiny example, boxes-and-arrows sketch, production reason, then two short checks. Define jargon on first use.
-2. **Grade exercise reports.** Grade the fixed build against the rubric in [exercise-library.js](exercise-library.js). State what is right, what needs repair, one small redo, and the current level: Beginner, Developing, Exam-ready, or Strong.
-3. **Grow the course.** After grading or a study session:
-   - Log real mistakes in a `Mistake Log.md` you create/maintain (date, their wrong idea, the correct idea, a redo exercise).
-   - Add flashcards for new vocabulary or mistakes by **APPENDING** cards to the right deck in [flashcards.js](flashcards.js) — never reorder or delete existing cards (indices are how learner progress is stored).
-   - Add new exercises by APPENDING to [exercises.js](exercises.js). Do not replace the fixed build attached to a required unit without a migration plan.
-4. **Keep quality up.** Follow [DESIGN-STANDARD.md](DESIGN-STANDARD.md) and [VISUAL-MEDIA-PIPELINE.md](VISUAL-MEDIA-PIPELINE.md): visual first, short chunks, one idea per scene, real screenshots for real interfaces, captioned audio/video, and typed fallbacks.
-5. **Protect honest mastery.** A passing score with guesses is not mastery. Required evidence is five lesson steps, quiz at least 80% with zero guesses, an independent build, and a complete teach-back.
+1. `get_tutor_briefing`
+2. `get_current_session`
 
-## How the site fits together
+The Study Studio server owns correctness and mastery. Claude may review work
+and propose changes, but it must not directly alter progress or curriculum.
 
-- `course-data.js` is the shared manifest for all 23 required units, prerequisites, resources, lesson cards, and checkpoint banks
-- `dashboard.html` = Home · `today.html` = current lesson · `curriculum.html` = 23 units · `timeline.html` = visual progress path
-- `foundation-lab.html` = visual/audio Workbench lessons · `concept-map.html` = prerequisite map
-- `teachback.html` = voice/typed explanation · `review.html` = spaced review · `tutor-bridge.html` = grounded copy/paste tutor handoff
-- `engineer-path.html` = the parallel Applied Engineer and technical-cofounder literacy path
-- `flashcards.html?deck=X&mode=browse|learn` reads decks from `flashcards.js`
-- `exercise.html?id=X` reads legacy exercises from `exercises.js` plus required fixed builds from `exercise-library.js`
-- `quiz.html?set=X` reads question banks from `quizzes.js` · `pretest.html` = 30-Q diagnostic
-- Article pages (`article-*.html`) retell Anthropic engineering posts as diagrams; `repair-map.html`, `learning-map.html`, and `concept-map.html` are visual guides
-- Shared nav lives in `nav.js` (edit once, applies everywhere) · styles in `study.css`
-- **All learner progress lives in browser localStorage** (`ccaf-*` keys). Key ones: `ccaf-curriculum` (units done/opened), `ccaf-pipeline` (today's 5 steps), `ccaf-learn-<deck>` (card mastery), `ccaf-ex-<id>` (exercise answers), `ccaf-last` (resume pointer). When served via `serve.py`, nav.js also mirrors every `ccaf-*` change into `my-progress.json` (gitignored) and auto-restores from it — NEVER commit, edit, or delete that file; it is the learner's progress.
+Current local app: `http://127.0.0.1:8765/`
 
-## Rules
-
-- Content edits must be **append-only** for `flashcards.js` decks and legacy `exercises.js` entries because progress is index-based.
-- Do not present reported exam specifications as official. Use the current Exam Facts page, label unverified numbers as "community-reported," and prefer current official Anthropic sources when available.
-- Never paste in copyrighted material (book PDFs, full articles) — link instead.
-- Never commit `my-progress.json`, backups, private PDFs, Obsidian settings, or personal study notes.
-- After any curriculum or JS edit, run `node course-audit.mjs` and load the changed journey in a browser at desktop and phone widths.
+Legacy HTML is available at `/legacy/`; it is not the source of current session state.

COURSE-AUDIT.md

@@ -105,7 +105,7 @@ The broad lane covers programming, web/networking, data, Git/testing/delivery, s
 
 ## Release safeguards
 
-- `course-data.js` is the single source for order, prerequisites, resources, builds, concepts, quiz destinations, and tutor prompts.
+- `course-data.js` is the single editing source for order, prerequisites, resources, builds, concepts, quiz destinations, and tutor prompts; the Study Studio's protected `studio/src/content/course-manifest.json` is generated from it (plus `video-data.js`) by `scripts/export-studio-manifest.mjs` and checked in CI.
 - `course-audit.mjs` validates prerequisites, unique builds, review cards, beginner quiz banks, internal resources, and stale old-unit labels.
 - Private PDFs, personal progress JSON, Obsidian settings, and personal notes are never included in the public release.
 - Exam facts remain separately labeled **official** or **reported** and were not rewritten during this repair.

FRONTIER-AI.md

@@ -0,0 +1,59 @@
+# Frontier AI Handoff
+
+This repository contains two tutor surfaces:
+
+- **CCA-F Study Studio** at `http://127.0.0.1:8765/` is the current local tutor.
+- **Legacy tutor** remains available at `/legacy/` for one compatibility release.
+
+Start the local app with:
+
+```bash
+./Start\ CCA-F\ Study\ Studio.command
+```
+
+## Connect through MCP
+
+Study Studio exposes a local **stdio MCP server**. It gives frontier models a
+server-authoritative learner session and accepts advisory reviews or proposals.
+It cannot directly change mastery or curriculum.
+
+Universal command:
+
+```bash
+/usr/bin/python3 scripts/run_frontier_mcp.py
+```
+
+The launcher reuses the cached Study Studio runtime and the same SQLite data in
+`~/Library/Application Support/CCA-F Study Studio/`. Launch the app once before
+the first MCP connection so that runtime dependencies exist.
+
+Available tools:
+
+- `get_tutor_briefing`
+- `get_current_session`
+- `get_review_packet`
+- `submit_frontier_review`
+- `propose_study_plan_update`
+- `report_content_gap`
+
+Frontier workflow:
+
+```text
+learner work -> deterministic server -> review packet -> frontier review
+                                                |
+                                                v
+                                      advisory proposal only
+                                                |
+                                                v
+                                      learner accepts or rejects
+```
+
+## Authority boundaries
+
+- The server owns correctness, progression, prerequisites, mastery, and review timing.
+- The local Ollama model supplies optional hints only and unloads after each response.
+- A frontier model may grade, diagnose, and propose changes.
+- Only the learner can accept a plan proposal.
+- Never read, print, commit, or upload SQLite data, progress snapshots, credentials, private notes, or confidential PDFs.
+
+Read `AGENTS.md` before tutoring or changing code. Run `npm test` before publishing a code change.