Skip to content

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

Closed
kevinmamaqi wants to merge 42 commits into
mainfrom
course-quality-pass
Closed

Course quality pass: onboarding flow, content correctness, backend fixes, docs, versioning design#1
kevinmamaqi wants to merge 42 commits into
mainfrom
course-quality-pass

Conversation

@kevinmamaqi

@kevinmamaqi kevinmamaqi commented Jul 18, 2026

Copy link
Copy Markdown
Owner

Summary

Parallel quality pass across the whole app, plus the native-shell foundation 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 the public courses repo 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 30 commits July 18, 2026 17:17
@kevinmamaqi
feat: launch LearnDeck local learning experience
f78ce60
@kevinmamaqi
docs: target the learn-deck public namespace
a369b0c
@kevinmamaqi
ci: verify every LearnDeck change
bb0ac2b
@kevinmamaqi
fix: keep verification output portable
6621238
@kevinmamaqi
test: verify the public course namespace
a20d18c
@kevinmamaqi
ci: use the current checkout runtime
8a80472
@kevinmamaqi
chore: issue forms, PR template, conduct, and tiny roadmap
b7bc2c9
@kevinmamaqi
merge: open-source operating model
5aeb233
@kevinmamaqi
test: enforce the course-pack contract and first journey
12b1d6b
@kevinmamaqi
merge: course-pack contract tests
c656bba
@kevinmamaqi
course: strengthen DDD teaching with worked examples and contrasts
37ffea3
@kevinmamaqi
merge: DDD teaching improvements
1d6d867
@kevinmamaqi
docs: copyable quick start and six-failure troubleshooting
85927bc
@kevinmamaqi
merge: install and troubleshooting docs
171eb86
@kevinmamaqi
course: add Testing Fundamentals pack
a940491
@kevinmamaqi
merge: Testing Fundamentals course
161d53a
@kevinmamaqi
feat: legible connection recovery, path reset, and export
1bcb516
@kevinmamaqi
merge: setup resilience backend
cfc7e1b
@kevinmamaqi
fix: keyboard, contrast, and honest-state pass on the UI
e053055
@kevinmamaqi
merge: UI accessibility pass
8902b89
@kevinmamaqi @claude
docs: EADDRINUSE recovery and what-stays-local disclosure
aa20098 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
feat: catalogue provenance and workspace validation
5a2f904 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
feat: learner evidence and solo self-review progression
c5a0de3 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
test: dogfood regression suite for solo, provenance, first hour
438ee34 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi
merge: catalogue provenance and workspace validation
8a1bc62
@kevinmamaqi
merge: learner evidence and solo self-review
e47e31d 
# Conflicts:
#	src/types.ts
@kevinmamaqi @claude
feat: solo mode, honest guide states, and data controls in the UI
250388e 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
course: make DDD modules executable solo from an empty folder
61cb61f 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
course: quality review pass on Testing Fundamentals
c54da60 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi
merge: solo mode and honest guide states in the UI
9388ba3
kevinmamaqi and others added 12 commits July 18, 2026 18:35
@kevinmamaqi
merge: DDD solo executability fixes
0c2fea7
@kevinmamaqi
merge: Testing Fundamentals review pass
87edc02
@kevinmamaqi
merge: local-data docs
bd3766f
@kevinmamaqi
merge: dogfood regression suite
ae559aa
@kevinmamaqi @claude
fix: keep learner evidence from downgrading section progress
7642d37 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kevinmamaqi @claude
docs: reflect the new disconnect, export, and reset controls
7c5406e 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@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 commented Jul 18, 2026

Copy link
Copy Markdown
Owner Author

Superseded by learn-deck/learndeck#1 (merged).

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