Skip to content

Course quality pass: onboarding flow, content correctness, backend fixes, docs, versioning design - #1

Merged
kevinmamaqi merged 7 commits into
mainfrom
course-quality-pass
Jul 18, 2026
Merged

Course quality pass: onboarding flow, content correctness, backend fixes, docs, versioning design#1
kevinmamaqi merged 7 commits into
mainfrom
course-quality-pass

Conversation

@kevinmamaqi

@kevinmamaqi kevinmamaqi commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Parallel quality pass across the whole app, plus the native-shell work it builds on (ws4 commits included since that branch was never pushed).

Onboarding & UX (public/)

  • Screen 2 is now a concise onboarding card: just the AI-guide options (Codex, Cursor, Claude Code), connect + skip. No local-progress panel, no two-column reading layout. Kimi was not added — the backend has no such integration; needs an integrations.ts entry first.
  • Screen 3 lands directly on the course library; returning users with a connected guide skip screen 2.
  • "Add your course" action linking to github.com/learn-deck/courses with fork/PR instructions; GitHub-synced catalogue framed as primary, bundled packs as offline fallback.
  • Real fixes: 4s poll wiped answer drafts and stole focus; double-submit duplicates; two stuck-button unhandled rejections; zero-question section crash; alert()s → accessible live regions.

Backend correctness (src/, test/)

  • TOML corruption: disconnect/repair deleted only the [mcp_servers.learndeck] header, stranding keys in the user's own tables in ~/.codex/config.toml, and Codex always reported stale. Fixed with full-block matching.
  • Provenance forgery: evidence backfill ran on every DB open, duplicating learner notes as guide evidence. Now first-creation only.
  • Progress downgrades: four siblings of 7642d37 (evidence, submit, correct evaluation, self-review could un-complete sections; one variant stranded nextActivity permanently).
  • Cache-root escape: .. branch segments in LEARNDECK_COURSE_REPOSITORY escaped the cache dir that sync rm -rfs. Rejected.
  • Each fix has a regression test; suite went 32 → 43 tests, all green.

Course content (courses/)

  • Both packs audited for technical correctness; every snippet and arithmetic total in testing-fundamentals verified by actually running the assembled learner project (tsc clean, 17/17 vitest).
  • Fixed dead anchors, invalid TS, missing setup steps, impossible testing advice, a test double that couldn't prove substitution, mock/spy/stub conflation; added worked examples so running examples compose module to module.
  • No module/question IDs, filenames, or frontmatter keys changed.

Docs

  • Every command, path, error string, and enum verified against code; macOS app packaging documented; 5-step contribute-a-course walkthrough; broken link fixed.
  • New docs/course-versioning.md: design proposal for contentVersion, learner-facing changelogs with severity/action levels, per-course version pinning in SQLite, and progress-migration rules (not yet implemented).

Test plan

  • bun test — 43 pass, 0 fail
  • Server smoke: all assets 200, bootstrap/integrations endpoints respond
  • Full curl-driven learner flow: create path → submit → evidence → export → reset
  • Manual visual pass of the new onboarding flow in a browser

🤖 Generated with Claude Code

kevinmamaqi and others added 6 commits July 18, 2026 19:15
@kevinmamaqi @claude
feat: local macOS app packaging via compiled Bun binary
3382bf1 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
feat: native AppKit shell for the Mac app
3f37d17 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
fix: backend correctness pass — TOML corruption, evidence provenance,…
65e6606 
… progress downgrades

- integrations: TOML block regex matched only the section header, so
  disconnect/repair corrupted ~/.codex/config.toml and Codex always
  reported stale; now matches the full block
- store: legacy evidence backfill ran on every open, duplicating learner
  notes as guide evidence; now runs only when the table is first created
- store: evidence recording, answer submission, correct evaluation, and
  self-review no longer downgrade complete/self_reviewed sections
  (siblings of 7642d37), including a stuck-nextActivity scenario
- course: reject '..' segments in course repository branch refs (cache
  dir escape on a path the sync deletes recursively)
- store: resetPath now counts deleted evidence rows, not sections
- server: clear 400 for non-string label input

Adds regression tests for each fix (43 tests green).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
feat: onboarding-style guide connect flow and GitHub-first course lib…
80e37e1 
…rary

- screen 2 is a single centered onboarding card: guide options (codex,
  cursor, claude-code), one-line explanation, connect + skip actions;
  removed the two-column layout and local-progress panel
- connecting or skipping lands directly on the course library; returning
  users with a connected guide skip the step entirely
- 'Add your course' block on the library linking to the public courses
  repository with fork/PR instructions
- catalogue provenance framed GitHub-first with bundled packs as the
  offline fallback
- fixes: 4s poll no longer wipes drafts or steals focus, drafts survive
  re-renders, double-submit guards, unhandled rejections, stale header
  guide button, zero-question section crash, alert()s replaced with
  accessible live-region messages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
docs: verify against code, add macOS app section and course versionin…
fd98330 
…g proposal

- README: fixed seed example collision, documented the packaged macOS
  app (build, data paths, limitations), GitHub-first catalogue framing
- troubleshooting: new sections matched to exact error strings in code
- mcp: integration statuses and evaluate-answer constraints documented
- progress-database: added missing evidence table, corrected enums
- public-course-distribution: 5-step contribute-a-course walkthrough
- course/README: removed pointer to deleted JSON manifest
- new docs/course-versioning.md: design proposal for contentVersion,
  learner-facing changelogs with severity levels, per-course pinning
  in SQLite, and progress migration rules

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
content: correctness and pedagogy pass over both course packs
0e9ca68 
ddd-backend-foundations: fixed dead source anchors, invalid TS snippet,
missing test-runner setup step; documented the check-then-act booking
race and transaction boundaries; added worked examples to modules 03 and
06 so the running example composes across 01-06; sharper Evans/Vernon
and Cockburn terminology; pinned dependency versions.

testing-fundamentals: fixed broken-from-step-one TS setup (tsconfig,
missing deps), literal-widening type error, impossible in-process
Request/Response testing advice (now ephemeral port + fetch), fake that
could not prove substitution (distinct rates via RateSource seam),
mock/spy/stub taxonomy conflation; explicit red-first steps; closed the
dangling 400/422 test promise in module 04; honest course duration.
Every snippet and price total verified by execution (tsc + vitest).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi kevinmamaqi mentioned this pull request Jul 18, 2026
Merged
2 tasks done
@kevinmamaqi @claude
refactor: bundle only a format-example pack; real courses live in lea…
7eb8fc8 
…rn-deck/courses

The app repository no longer ships learner-facing course packs. The DDD
and testing-fundamentals packs (with today's quality pass) move to the
public catalogue repository (learn-deck/courses PR #1), together with
the course-facing references (learning-protocol, source-index,
language-paths).

- new courses/example-course: a two-module reference pack that
  documents the course format by using all of it (every front-matter
  field, all three question kinds, notes/, observable rubrics); serves
  as the documentation example and the test fixture
- tests rewired from ddd-backend-foundations/node-typescript to
  example-course/default; shape assertions updated; 43 tests green
- README, courses/README, course/README, course-authoring, and
  public-course-distribution reframed: GitHub catalogue is the home of
  real courses, the bundled pack exists for documentation and offline
  development only
- references/progress-database.md stays (app documentation linked from
  README); UI placeholders no longer assume a DDD workspace

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi

kevinmamaqi commented Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Added commit 7eb8fc8: the app repo no longer bundles learner-facing course packs. DDD + testing-fundamentals (with the quality pass) moved to learn-deck/courses#1; this repo now ships only courses/example-course, a two-module reference pack that documents the format and doubles as the test fixture. Merge learn-deck/courses#1 first (or together) so the public catalogue has the packs before a release configuration points at it.

@kevinmamaqi
kevinmamaqi marked this pull request as ready for review July 18, 2026 19:43
@kevinmamaqi
kevinmamaqi merged commit 98756e6 into main Jul 18, 2026
1 check passed
@kevinmamaqi
kevinmamaqi deleted the course-quality-pass branch July 18, 2026 19:43
@kevinmamaqi kevinmamaqi mentioned this pull request Jul 18, 2026
Closed
3 of 4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kevinmamaqi