Add a complete Git practice course with validated lesson states

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to GitUnstuck
 
 Thanks for your interest in contributing. GitUnstuck is a dependency-free,
-client-side application: `index.html`, shared `recovery.js`, SVG assets and automated tests.
+client-side application: `index.html`, shared `recovery.js` and `learning.js`, SVG assets and automated tests.
 We welcome contributions that keep it small, private, and easy to run.
 
 ## How to contribute
@@ -22,7 +22,7 @@ We welcome contributions that keep it small, private, and easy to run.
 ## Coding conventions
 
 - **Zero dependencies.** Do not add npm packages, external fonts, external
-  scripts or runtime frameworks. Preserve the existing build-only minifiers. Source use opens `index.html` alongside `recovery.js`.
+  scripts or runtime frameworks. Preserve the existing build-only minifiers. Source use opens `index.html` alongside `recovery.js` and `learning.js`.
 - **Privacy first.** Pasted terminal output stays in the browser tab. Never
   transmit input over the network, and do not log or store it.
 - **Risk-aware guidance.** Every destructive command must be paired with a
@@ -37,8 +37,10 @@ We welcome contributions that keep it small, private, and easy to run.
 
 - `index.html` — markup, styles, navigation and rendering.
 - `recovery.js` — shared recipe data and diagnosis logic.
+- `learning.js` — canonical lessons, controlled Git/editor actions, manifests, routes and pure transitions.
 - `tests/test-analyzer.js` — parser, data and source assertions.
 - `tests/test-recovery.js` — executable disposable-repository scenarios.
+- `tests/test-learning.js` — all lesson and independent-task outcomes, reference/parent checks and actual shell setup runs.
 - `tests/test-browser.cjs` — optional browser journey and presentation checks.
 - `docs/` — plans, feature specifications, and design notes.
 - `.github/` — CI workflows, issue/PR templates, and funding configuration.
@@ -47,6 +49,14 @@ We welcome contributions that keep it small, private, and easy to run.
 
 Keep parser checks, executable recovery evidence and browser checks distinct. Tests must execute the same recipe definitions as the UI and assert protected file/index/history state. Do not treat matching source strings as proof that a recovery works. See README.md for supported environments and provider limitations.
 
+## Teaching changes
+
+Before adding a lesson or control, name the learner difficulty, the resulting behaviour and a meaningful check. Keep the bounded sequence in `docs/learning-implementation.md`; record evidence and gaps in `docs/learning-evidence.md`. Additional topics need an explicit unmet need rather than a larger course outline.
+
+Define a stable lesson/checkpoint ID, prerequisites, fresh named practice setup, initial/final file/index/reference manifests, controlled action arrays, expected observations, prediction feedback, a changed independent task with a worked answer, and relevant reference/source links. Reuse the practice setup helper and canonical recovery prerequisites/consequences. Never execute lesson prose or learner-provided commands. Test actual repository contents and relationships, plus any new Bash/PowerShell syntax in those shells. Preserve old hashes and validated return context.
+
+Run `npm test`, `npm run build:check`, and `npm run build`; then run `node tests/test-browser.cjs` against source and the built artifact with an installed Playwright/Chromium environment. Keep build fingerprints aligned with tested inputs. Real beginner observations, older-Git runtime compatibility and unavailable accessibility checks must be reported separately from automated passes. Do not mark real learner validation complete using simulated beginners.
+
 ## Code of Conduct
 
 All participants are expected to follow the

README.md

@@ -5,7 +5,7 @@
 GitUnstuck is a browser guide with three destinations:
 
 - **Fix a problem:** paste Git output or choose a specific recovery path. Read the prerequisites, run one step at a time, and verify the result.
-- **Learn Git:** follow the existing lessons on repositories, staging, commits, branches and remotes.
+- **Learn Git:** optional setup followed by six practical lessons: inspect, staging, history, branches/merges, remotes, and recovery. Each uses a fresh plain-text practice project, a prediction, observations, and an independent task.
 - **Find a command:** search the command reference for syntax, effects and examples.
 
 Pasted terminal content is processed in the current tab. The app does not upload or save that content. Theme and display preferences use local storage. No account or runtime package installation is required.
@@ -22,15 +22,17 @@ Protected-branch guidance creates and publishes a new review branch. It does not
 
 ## Run and check locally
 
-Open `index.html` alongside `recovery.js` and the SVG assets in a modern browser. Source checkout use needs no build. Commands in the guide use Git 2.23+ syntax and ordinary double-quoted paths. Replace uppercase placeholders before running a command; paths containing shell expansion characters or quotes need shell-specific quoting. Do not paste credentials into the guide.
+Open `index.html` alongside `recovery.js`, `learning.js` and the SVG assets in a modern browser. Source checkout use needs no build. `#learn` opens the outline; `#learn/staging/edited-v3` opens a specific checkpoint. Lesson reference links retain their validated checkpoint through reload and search. Browser controls change illustrations only; the page cannot inspect or grade a real repository.
+
+Commands use Git 2.23+ syntax. Current learning fixtures ran on Git 2.56.0.windows.4; actual Git 2.23 runtime compatibility remains unverified. Bash and Windows PowerShell 5.1 setup blocks were executed in their actual shells. Use a fresh named directory for each lesson; practice identity, hook, signing and pager settings stay local. Replace uppercase reference placeholders with checked values; paths containing shell expansion characters or quotes need shell-specific quoting. Do not paste credentials into the guide.
 
 With Node.js 22 or later and Git installed:
 
 ```text
 npm test
 ```
 
-This runs parser/source checks and disposable-repository integration tests. On the implementation machine, 194 parser/data/source assertions and 33 recovery scenarios passed. The Ubuntu CI suite exercises Bash; Windows additionally runs the PowerShell scenario. Source-string assertions only establish markup/data properties; the integration tests establish repository outcomes.
+This runs parser/source checks, recovery integration tests, and the learning data/real-Git suite. Current Windows runs passed 194 analyzer assertions, 33 recovery scenarios and all seven lesson setups/worked examples/independent tasks. Learning setup was executed in Git Bash and Windows PowerShell 5.1. Checked-in CI workflows run Ubuntu with Node 22; there is no checked-in Windows job. Local validation used Node 26.12.1. Source-string assertions establish markup properties; Git fixtures establish repository outcomes.
 
 The recovery tests use temporary repositories and local bare remotes. They inspect actual file contents, index snapshots, untracked files, commit reachability and remote history. Coverage includes full staged-diff review, fetched outgoing-secret history, everyday remote updates in equal/ahead/behind/diverged states, latest and earlier secrets, dirty protected-branch recovery, main/master/custom branches, custom remotes, paths with spaces, existing backup names, real merge and rebase conflicts, reflog, snapshots, discard, unstage, rewind, revert, clone, commit, worktree, tags, cherry-pick, lease rejection and deterministic bisect. The snapshot commands were also executed in actual Windows PowerShell and Git Bash.
 
@@ -42,7 +44,7 @@ npm run build:check
 npm run build
 ```
 
-Build-only minifiers are locked in `package-lock.json`; they are not browser dependencies. The build embeds the same `recovery.js` consumed by the interface and tests into `dist/index.html`. The Pages workflow runs `npm test` before building and deploying.
+Build-only minifiers are locked in `package-lock.json`; they are not browser dependencies. The build embeds the same `recovery.js` and `learning.js` consumed by the interface and tests into `dist/index.html`. Metadata records base Git HEAD, clean/dirty working-tree state, and a SHA-256 of source/build inputs so an uncommitted artifact is not mistaken for a clean revision. The Pages workflow runs `npm test` before building and deploying.
 
 ## Browser verification
 
@@ -54,7 +56,9 @@ node tests/test-browser.cjs
 
 Set `GITUNSTUCK_TEST_URL` to test an HTTP deployment or the built `dist/index.html` file URL. Results and screenshots are written to ignored `artifacts/`.
 
-Desktop (1440×1000) and mobile (390×844) Chromium checks cover recovery, staging lessons, command search, reload/Back, retained deep links, copy output, keyboard entry/arrow navigation, focus visibility, reduced motion, sampled recovery-text contrast in both themes, and horizontal overflow. Screenshots were visually inspected. The same journeys passed against the deployed HTTPS site; see [release evidence](docs/recovery-audit/release.md). This is not a complete accessibility certification or cross-browser test.
+Current source and built Chromium journeys cover all lessons, reference return/reload/Back/Forward, recovery, legacy routes, clipboard success/failure, input privacy and reference printing. Presentation checks use 320, 390, 768 and 1440 CSS-pixel widths in both themes, keyboard focus, reduced motion, sampled text/graph contrast and desktop CSS zoom at 200%. Screenshots were inspected. Actual browser-menu zoom, a second engine and a real screen-reader pass remain unverified. No accessibility certification or beginner teaching-effectiveness claim is made.
+
+The new course has not been deployed or tested with actual beginners. See [learning evidence](docs/learning-evidence.md) for the tested scope and remaining gaps. [Earlier release evidence](docs/recovery-audit/release.md) concerns the earlier recovery release, not this learning implementation.
 
 ## Limits and evidence