learn-cli 0.4.2__tar.gz → 0.5.1__tar.gz

learn_cli-0.5.1/.github/workflows/deploy-site.yml

@@ -0,0 +1,122 @@
+name: Deploy site
+
+# learn-cli's web face: site-astro/ builds the /learn/ landing page, one
+# sub-page per subject, and a story reader per story, then deploys to
+# Cloudflare Pages. Modeled on org/site-astro's deploy.yml (same steps, same
+# gating pattern) but targets a NEW, learn-cli-owned Pages project
+# ("agentculture-learn") rather than org's "agentculture-org" — how (or
+# whether) agentculture.org/learn/* gets routed to it is a separate,
+# still-open integration decision; see site-astro/README.md.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site-astro/**'
+      - '.github/workflows/deploy-site.yml'
+  pull_request:
+    paths:
+      - 'site-astro/**'
+      - '.github/workflows/deploy-site.yml'
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: pages-deploy-${{ github.ref }}
+      cancel-in-progress: true
+    # Mapped here so later steps can gate with `if: env.CLOUDFLARE_API_TOKEN
+    # != ''` — secrets.* isn't usable directly in an `if:` conditional.
+    env:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: site-astro/.nvmrc
+          cache: npm
+          cache-dependency-path: site-astro/package-lock.json
+
+      - name: Install dependencies
+        working-directory: site-astro
+        run: npm ci
+
+      - name: Build site
+        working-directory: site-astro
+        run: npm run build
+
+      # Fails the job if the content-export fixtures and the built pages
+      # have drifted apart — a subject/module/story with no page, or a page
+      # with no export backing. See scripts/check-export-pages.mjs.
+      - name: Check export/page consistency
+        working-directory: site-astro
+        run: npm run check
+
+      # astro.config.mjs sets base: '/learn', so Astro's own bundled asset
+      # links (fonts, per-page CSS) come out of `astro build` as absolute
+      # `/learn/_astro/...` hrefs — but the physical dist/ tree stays flat
+      # (dist/_astro/..., no dist/learn/ nesting; only Astro's own dev/
+      # preview server understands `base` and rewrites around that). A dumb
+      # static host — Cloudflare Pages included — serves dist/ as literal
+      # paths, so those asset requests would 404 unless the deployed tree's
+      # physical layout matches the emitted hrefs. Wrapping dist/ under a
+      # `learn/` folder before upload fixes that for both the Pages preview
+      # domain (which then serves the site at .../learn/, not its bare
+      # root — intentional, so preview and production share one URL shape)
+      # and the eventual agentculture.org/learn mount. See site-astro/README.md
+      # ("Base path and relative links").
+      - name: Prepare deploy directory
+        run: |
+          mkdir -p site-astro/dist-deploy/learn
+          cp -r site-astro/dist/. site-astro/dist-deploy/learn/
+          # Bare-root visits (e.g. the raw *.pages.dev URL) land on /learn/
+          # instead of 404ing.
+          printf '/    /learn/    302\n' > site-astro/dist-deploy/_redirects
+
+      # No cloudflare/wrangler-action — invoking wrangler directly via npx
+      # keeps the deploy dependency-light and auditable, matching org's
+      # deploy.yml (and this repo's zero-runtime-dependency temperament).
+      # site-astro/package.json is not touched: wrangler is fetched on
+      # demand, not installed as a devDep.
+      #
+      # --branch selects production vs. preview: the Cloudflare Pages project
+      # (agentculture-learn) has production branch "main", so pushing to main
+      # (or a manual workflow_dispatch off main) deploys to production, while
+      # a pull_request run passes the PR's head branch and gets a preview
+      # deployment alias instead.
+      - name: Deploy to Cloudflare Pages
+        if: env.CLOUDFLARE_API_TOKEN != '' && env.CLOUDFLARE_ACCOUNT_ID != ''
+        run: >-
+          npx wrangler@4 pages deploy site-astro/dist-deploy
+          --project-name agentculture-learn
+          --branch "${{ github.head_ref || github.ref_name }}"
+
+      - name: Skip notice (Cloudflare secrets not configured)
+        if: env.CLOUDFLARE_API_TOKEN == '' || env.CLOUDFLARE_ACCOUNT_ID == ''
+        run: |
+          echo "::notice::CLOUDFLARE_API_TOKEN and/or CLOUDFLARE_ACCOUNT_ID are not configured on this repo yet — skipping the Cloudflare Pages deploy. The build and export/page check above still ran, so this validates the site builds cleanly."
+          {
+            echo '### Deploy skipped'
+            echo ''
+            echo 'The Cloudflare secrets (`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`) are not both set on this repo yet, so the Cloudflare Pages deploy step was skipped. The build and export/page consistency check above still ran and validated cleanly.'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Deployment summary
+        if: env.CLOUDFLARE_API_TOKEN != '' && env.CLOUDFLARE_ACCOUNT_ID != ''
+        run: |
+          BRANCH="${{ github.head_ref || github.ref_name }}"
+          {
+            echo '### Deployed to Cloudflare Pages'
+            echo ''
+            if [ "$BRANCH" = "main" ]; then
+              echo '- Production: https://agentculture-learn.pages.dev/learn/'
+              echo '- Production (custom domain, once the agentculture.org/learn route is wired up): https://agentculture.org/learn/'
+            else
+              echo "- Preview: https://${BRANCH}.agentculture-learn.pages.dev/learn/"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

{learn_cli-0.4.2 → learn_cli-0.5.1}/.gitignore

@@ -14,7 +14,7 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
+/lib/
 lib64/
 parts/
 sdist/
@@ -231,3 +231,4 @@ skills.local.yaml
 
 # devague working state (not committed by default)
 .devague/reviews/
+.claude/settings.json

{learn_cli-0.4.2 → learn_cli-0.5.1}/.markdownlint-cli2.yaml

@@ -16,6 +16,13 @@ config:
 
 ignores:
   - "node_modules/**"
+  # site-astro/ (and any future npm-managed subproject) has its own nested
+  # node_modules/ — a bare "node_modules/**" only matches the root one, so
+  # this recursive form is needed too (learn-cli#<t13>: the site-astro build).
+  - "**/node_modules/**"
+  # The uv virtualenv — third-party packages (starlette, uvicorn, httpx, …) ship
+  # their own LICENSE.md / README.md; never lint installed dependencies.
+  - ".venv/**"
   - ".local/**"
   - ".afi/**"
   - ".teken/**"
@@ -23,3 +30,5 @@ ignores:
   - ".claude/skills/**"
   # devague working state (generated review artifacts, gitignored).
   - ".devague/**"
+  # Generated by `learn site export` — registry content, not authored prose.
+  - "site-astro/src/content-export/**"

{learn_cli-0.4.2 → learn_cli-0.5.1}/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-07-11
+
+### Fixed
+
+- API worker: the /learn zone-mount proxy strips Cookie/Authorization before forwarding to the Pages origin (review finding: session leak)
+- API worker: withCors appends to an existing Vary header instead of overwriting it
+- Profile ledger: created 0600 like auth.json (learner data is private)
+- Profile ledger: a malformed ledger line is skipped instead of crashing progress/next/sync
+
+## [0.5.0] - 2026-07-11
+
+### Added
+
+- The learn platform: subject registry fronting french-cli, spanish-cli, and culture-guide as external runtimes (`learn subjects`, `learn subject doctor <name>` conformance gate)
+- Subject-plugin contract v1.0: 11 versioned JSON schemas + stdlib validator as package data (learn/contract), directive pattern, story schema shared by all subjects
+- Motivation layer (learn/motivation): deterministic scores, streaks, time-decayed mastery, review queues, and never-ending what-next over recorded history
+- Learner profile (learn/profile + auth/progress/next/record verbs): GitHub device-flow sign-in, offline-first local ledger with best-effort sync
+- Three faces via agentfront>=0.20: learn mcp serve (stdio MCP), learn site serve (agent-readable web), learn site export (pinned content export), surfaces-agree CI test
+- Web face (site-astro/): 29 static pages in org's design system (zero new tokens), signed-out/in split with client hydration and a zero-API static proof, Cloudflare Pages deploy workflow
+- API worker (workers/learn-api): GitHub OAuth, KV/D1 learner ledger, tutoring broker, and the agentculture.org/learn/* zone mount (API + static proxy in one worker)
+- E2E launch gate (tools/launch-gate): 66 machine-checked assertions across web/CLI/MCP audiences with live-mode rerun
+
+### Changed
+
+- Runtime dependencies: agentfront[mcp]>=0.20 (was zero-dependency scaffold)
+- CLAUDE.md and lint config updated for the new surfaces
+
 ## [0.4.2] - 2026-07-11
 
 ### Added

{learn_cli-0.4.2 → learn_cli-0.5.1}/CLAUDE.md

@@ -46,8 +46,13 @@ consistent → cross-subject learner state → hosting + model-access wiring.
 
 ## Commands
 
-Python ≥3.12, managed with **uv**. The runtime package has **zero third-party
-dependencies** (`dependencies = []`); all tooling lives in the `dev` group.
+Python ≥3.12, managed with **uv**. The runtime package depends on
+**`agentfront[mcp]>=0.20`** (`dependencies = ["agentfront[mcp]>=0.20"]`) — the
+one library the three faces are derived from: the `mcp` extra powers
+`learn mcp serve`, while the CLI/HTTP/export faces work without it. Everything
+else (test + lint tooling) lives in the `dev` group. (The hand-rolled argparse
+CLI under `learn/cli/` stays; agentfront backs the *parallel* App registry in
+`learn/front/` that the MCP server, HTTP site, and `learn site export` read.)
 
 ```bash
 uv sync                                   # install deps + dev tools into .venv

{learn_cli-0.4.2 → learn_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learn-cli
-Version: 0.4.2
+Version: 0.5.1
 Summary: A CLI, MCP server, and web front for learning — a hosted site where humans and agents learn a subject step by step. Fronts the french-cli and spanish-cli language tutors, and generalizes to other learnable domains such as leading teams of agents. The learn command is the local operator surface and how agents drive it.
 Project-URL: Homepage, https://github.com/agentculture/learn-cli
 Project-URL: Issues, https://github.com/agentculture/learn-cli/issues
@@ -13,6 +13,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Requires-Dist: agentfront[mcp]>=0.20
 Description-Content-Type: text/markdown
 
 # learn-cli

learn_cli-0.5.1/docs/hosting.md

@@ -0,0 +1,76 @@
+# Hosting and cost-when-busy note
+
+This records the hosting choice for `agentculture.org/learn` and its
+cost-when-busy profile, per the brief's honesty condition h8 (the hosting
+choice must be recorded with a cost-when-busy note before build) and spec
+decisions c21/c22.
+
+## Shape of the deployment
+
+Two surfaces, deliberately split by cost:
+
+1. **Static shell + signed-out tour — Cloudflare Pages.** The subject catalog,
+   module sub-pages, sample stories, and the whole visitor tour are pre-built
+   static content (the `org` house style, Astro `output: 'static'`). Serving
+   them is free and infinitely cacheable at the edge.
+2. **Dynamic layer — the learn API Worker** (`workers/learn-api/`). Auth
+   sessions, the learner ledger (KV + D1), and the tutoring broker. Only
+   signed-in learners reach it.
+
+The load-bearing invariant: **signed-out traffic is served entirely from the
+static pages and can never reach the broker.** Sign-in is the resource gate
+(spec c21). `POST /api/tutor` is the only route that spends model tokens, and it
+sits behind auth middleware that runs before the route body — so a visitor who
+never signs in costs nothing beyond static bandwidth (free) and cannot trigger a
+model call. This is enforced in code and proven by test
+(`workers/learn-api/test/worker.test.js`).
+
+## Cost-when-busy
+
+Rough order-of-magnitude figures (Cloudflare pricing as of 2026; confirm
+against the current plan before launch — these move):
+
+| Component | When idle | When busy | Notes |
+| --- | --- | --- | --- |
+| Cloudflare Pages (static shell + tour) | free | free | Signed-out visitors, however many, cost ~0. Static assets cache at the edge. |
+| Workers (the learn API) | ~$5/mo base (paid plan) | + per-request beyond the included allotment (~10M requests/mo included; ~$0.30 per additional million) | Only signed-in requests hit the Worker. CPU-time billing is negligible for this thin JSON layer. |
+| KV (`SESSIONS`) | pennies | usage-priced reads/writes + storage | Only device-flow codes + revocation tombstones — tiny. |
+| D1 (`learn-ledger`) | free tier covers early usage | usage-priced (rows read/written + storage) | Append-only ledger; one small row per recorded result. Reads on progress. |
+| Inference (tutoring broker) | $0 | **per-use, and the dominant cost when busy** | Live tutoring tokens billed per-call through the served `cloudai-cli` / `ec2bedrock-cli` endpoint. Signed-in interactive lessons only. |
+
+### The dominant term when busy is inference, and only signed-in learners incur it
+
+Everything except inference is either free (static, Pages) or cheap and
+usage-metered (Workers/KV/D1 for signed-in JSON traffic). The one materially
+variable cost is **live model tokens**, and by construction it is gated behind
+sign-in:
+
+- A traffic spike of signed-out visitors (a launch, a link on the front page)
+  scales on free static bandwidth — **zero marginal model cost**.
+- Only a signed-in learner running an interactive lesson brokers a model call,
+  and each such call is billed per-use by the served inference endpoint
+  (`cloudai-cli` / `ec2bedrock-cli`), never a bespoke provider SDK.
+- Pre-generated content (stories, starter lessons) is batch-produced, human
+  reviewed, and committed to each subject repo (spec decision on model access),
+  so serving it is static and free — live calls are reserved for genuinely
+  interactive, personalized tutoring.
+
+### Containing the busy-case bill
+
+Levers available if signed-in inference volume grows:
+
+- Rate-limit `POST /api/tutor` per learner (add a KV counter — the binding is
+  already present).
+- Point `INFERENCE_URL` at a cheaper served model or an autoscaled
+  `ec2bedrock-cli` endpoint that scales to zero when idle.
+- Cache/pre-generate more content so fewer interactions need a live call.
+- Keep the token TTL short (already 1h) so abandoned sessions can't be replayed
+  to spend tokens.
+
+## Why this split
+
+It honors the brief's cost discipline: the expensive resource (model tokens) is
+spent only for signed-in, interactive learning; the free resource (static edge
+content) carries every anonymous visitor. The dynamic layer stays thin and
+Cloudflare-native (Worker + KV + D1) rather than a always-on server, so idle
+cost is near the Workers base plan and busy cost tracks actual signed-in usage.

learn_cli-0.5.1/docs/specs/subject-plugin-contract.md

@@ -0,0 +1,262 @@
+# The subject-plugin contract (v1.0)
+
+**Status:** authoritative for contract version `1.0` · **Owner:** learn-cli ·
+**Machine-readable half:** `learn/contract/schemas/*.json` (package data, importable as `learn.contract`)
+
+This is the central design of the learn uplift: the interface a subject CLI must satisfy to be
+hosted by learn-cli. It descends from the converged spec
+([`docs/specs/2026-07-10-agentculture-org-learn-is-live-one-learning-hub-in.md`](2026-07-10-agentculture-org-learn-is-live-one-learning-hub-in.md),
+claims c9, c15/c17, c18, c27/c28, c29) and generalizes culture-guide's proven `teach` engine.
+Everything downstream composes on it: the registry + conformance gate (t3), the french/spanish
+implementations (t4/t5), the culture-guide adapter (t6), story content (t7/t8), and the
+motivation layer (t9).
+
+## 1. The model: portal, subject, driver
+
+Three roles, three kinds of intelligence:
+
+- **The subject CLI** (french, spanish, culture-guide, …) is an **LLM-free engine**. It owns
+  committed content (stories, lessons, exercises) and per-learner mastery state, resolves *what*
+  to teach next within itself, and emits **structured teaching directives**. It never converses,
+  never grades free text, never calls a model, and **never computes scores**.
+- **The driver** (an agent or human harness — Claude Code, a colleague backend, the learn API's
+  tutoring broker) does the conversational tutoring the directive describes: presents, explains,
+  quizzes, grades `pass|partial|fail` against the answer or rubric, and **writes raw results
+  back** via the subject's `record` verb.
+- **learn-cli** (the portal) drives subjects **as external runtimes over subprocess `--json`** —
+  it never imports subject code — and owns the uniform **motivation layer**: numeric scores per
+  exercise, per-subject and cross-subject streaks, time-decayed review queues, and adaptive
+  what-next, all computed **deterministically** from the recorded-result history. No LLM in the
+  scoring path; the same history yields the same numbers on web, CLI, and MCP.
+
+This is the **directive pattern** (culture-guide's `teach` shape, generalized): the subject emits
+a directive; the driver tutors; the driver records; the subject updates mastery; learn-cli
+ledgers the raw result and derives motivation.
+
+### State division (normative)
+
+| Concern | Owner |
+| --- | --- |
+| Content: stories, lessons, exercises (committed files) | subject repo |
+| Per-learner mastery ladder + item history, per subject | subject CLI (XDG-path state file) |
+| Within-subject next-step recommendation | subject CLI (deterministic) |
+| Conversational tutoring, grading of answers | driver |
+| Raw-result ledger across subjects | learn-cli |
+| Numeric scores, streaks, review queues, cross-subject what-next | learn-cli (pure functions of the ledger) |
+| Cross-subject learner profile / identity | learn-cli |
+
+Two hard prohibitions fall out of this:
+
+1. **Subjects never emit scores.** The `record` ack's `recorded` object structurally forbids
+   `score`/`grade`/`points` fields (a `not` clause in `record.json`). Subjects report raw
+   observations only: `result`, optional `correct`/`total` counts, `duration_seconds`.
+2. **learn-cli never contains subject content or progression logic.** Deleting a subject's
+   registry entry removes it from every face.
+
+## 2. Conventions every verb follows
+
+- **Invocation:** `<subject-command> <verb> [args] --json [--learner <id>]`. The subject command
+  is a console script on PATH (e.g. `french`), declared in the registry entry.
+- **`--json` everywhere.** learn-cli only consumes `--json` output. Text mode exists for humans
+  and is uncontracted (rubric rules still apply inside the subject repo).
+- **`--learner <id>`** on every learner-scoped verb. When omitted, the subject resolves a default
+  (its own env var, then the OS user) and **must echo the resolved id** in the payload's
+  `learner` field. The learner may be a human or an agent.
+- **Streams:** results → stdout, errors/diagnostics → stderr, never mixed.
+- **Exit codes:** `0` success · `1` user error · `2` environment error · `3+` reserved.
+- **Errors:** on any failure, stderr carries the `error.json` shape
+  `{code, message, remediation}` in `--json` mode (`error: …` + `hint: …` in text mode), and the
+  process exits with `code`. No traceback ever reaches stderr.
+- **Versioning:** every payload carries `schema_version` (see §5).
+- **Open payloads:** schemas validate required structure but allow extra fields, so subjects can
+  extend (e.g. culture-guide's `unclear_questions_for_ori`) and minor contract versions can add
+  optional fields without breaking older validators. Consumers must ignore unknown fields.
+
+## 3. The eight verbs
+
+Schema files live in `learn/contract/schemas/`; golden example payloads (validated in CI) in
+`tests/fixtures/payloads/`. "Learner-scoped" means the verb reads or writes per-learner state.
+
+| # | Verb | Invocation | Payload schema | `kind` | Learner-scoped | Writes state |
+| - | --- | --- | --- | --- | --- | --- |
+| 1 | overview | `overview --json` | `overview.json` | `subject_overview` | no | no |
+| 2 | progress | `progress --json` | `progress.json` | `progress` | yes | no |
+| 3 | advice | `advice --json` | `advice.json` | `advice` | yes | no |
+| 4 | story | `story list --json` / `story read <id> --json` | `story_list.json` / `story_read.json` | `story_list` / `story_read` | list: no · read: yes | read: may set current position |
+| 5 | lesson | `lesson start [<target>]` / `lesson next` / `lesson repeat [<id>] [--harder]`, all `--json` | `lesson.json` | `lesson_directive` | yes | yes (current lesson; first exposure lifts items to `introduced`) |
+| 6 | practice | `practice [<scope>] --json` | `practice.json` | `practice_directive` | yes | no |
+| 7 | record | `record --item <id> --result pass\|partial\|fail […] --json` | `record.json` | `record_ack` | yes | yes (history + mastery) |
+| 8 | doctor | `doctor --json` | `doctor.json` | `subject_doctor` | no | no |
+
+### 3.1 `overview` — the subject describes itself
+
+Identity, description, ordered **modules** (the web face renders one sub-page per module), and
+content counts. Learner-independent and deterministic, so the static site can be built from it
+with zero model or state access.
+
+### 3.2 `progress` — where the learner stands
+
+Per-item mastery map on the shared ladder (§4), counters
+(`items_total`/`items_touched`/`items_mastered`), completed and weak item lists, timestamps, and
+the subject's own `next` recommendation `{done, text, command, item_id?, module_id?}`. `done:
+true` never dead-ends the learner: it is the signal for learn-cli to switch to maintenance +
+depth mode (review decayed items, `lesson repeat --harder`, fresh stories).
+
+### 3.3 `advice` — deterministic study advice
+
+What to shore up and why, each entry with a runnable `command`. A pure function of stored state —
+the "tutor's opinion" a driver can relay verbatim. May be empty for a brand-new learner.
+
+### 3.4 `story` — the shared content surface
+
+`story list` returns level-tagged summaries (id, title, level, exercise count) — enough for the
+public catalog. `story read <id>` returns the **full story object exactly as committed**
+(`story.json`, §6) wrapped in a directive: present paragraph-at-a-time, use the glossary on
+demand, run the comprehension exercises, record each result. Unknown story id → exit 1 with the
+error shape.
+
+### 3.5 `lesson` — start / next / repeat
+
+The subject resolves *what* to teach — `start` (optionally targeted at a module or item), `next`
+(continue from mastery state), or `repeat [<id>] [--harder]` (re-issue a completed lesson;
+`--harder` increments the lesson's integer `difficulty` rung — the repeatable-lessons half of
+never-ending progression). The payload carries the lesson's items (each with teachable `points`)
+plus the directive (optionally with a `persona`). Item ids in the lesson are exactly what
+`record --item` expects back.
+
+### 3.6 `practice` — exercises to run
+
+A batch of exercises scoped to an item, a module, or `review` (no argument: the subject picks its
+weakest touched items). Exercise types: `multiple_choice`, `true_false`, `cloze`, `short_answer`,
+`translation`, `open`, `discussion`. Checkable types carry `answer`; open types carry `rubric`
+(what passes, what is partial).
+
+### 3.7 `record` — the write-back (the motivation layer's input)
+
+The driver reports one graded outcome:
+
+```bash
+french record --learner ori --item numbers-money --activity practice \
+  --exercise nm-p1 --result pass --correct 1 --total 1 --duration-seconds 38 --json
+```
+
+The subject appends the raw result to its history, updates the item's mastery (inferred from
+`result` unless `--mastery` is given explicitly; inference never regresses a level), and acks
+with:
+
+- `recorded` — the normalized raw-result object `{item_id, activity, exercise_id?, story_id?,
+  lesson_id?, result, correct?, total?, duration_seconds?, notes?, at}`. **This object is the
+  contract's scoring input:** learn-cli appends it verbatim to its cross-subject ledger, and the
+  motivation layer (t9) computes scores/streaks/review-queues from the ledger alone. It
+  structurally rejects `score`/`grade`/`points`.
+- `mastery` — the item's post-record level.
+- `next` — the refreshed within-subject recommendation.
+
+Result inference default (culture-guide's proven mapping): `fail → introduced`,
+`partial → practiced`, `pass → mastered`, never regressing.
+
+### 3.8 `doctor` — self-check + contract pin
+
+Health checks in the established doctor shape (`{id, passed, severity, message, remediation}`)
+plus **`contract_version`** — the contract version this subject pins. `learn subject doctor`
+(t3) reads the pin first, then validates the other seven verbs' payloads against that version's
+schemas. Exit 0 when healthy, 2 when not. Recommended checks: content files validate against
+`story.json`, learner-state dir writable, pinned contract version supported.
+
+## 4. Shared vocabularies
+
+Exported as constants from `learn.contract` and embedded in the schemas (tests assert they
+agree):
+
+- **Mastery ladder** (ordered): `unknown → introduced → practiced → mastered`.
+- **Raw results:** `pass | partial | fail`.
+- **Story/lesson levels:** `beginner | intermediate | advanced` (finer grading goes in
+  `level_detail`, e.g. `"A1"`, `"B2"`, `"scenario"`).
+- **Ids:** subjects match `^[a-z][a-z0-9-]*$`; items/stories/lessons/exercises/checks match
+  `^[a-z0-9][a-z0-9._-]*$`. Item ids are the join key across `lesson`/`practice`/`story`
+  exercises, `record`, and `progress.mastery`.
+
+## 5. Versioning (`schema_version`)
+
+- The contract version is a `major.minor` string; this document and the shipped schemas are
+  **`1.0`** (`learn.contract.CONTRACT_VERSION`).
+- **Every payload** (and every story content file) carries `schema_version`; v1 schemas pin the
+  pattern `^1\.[0-9]+$`, so a v2 payload fails v1 validation loudly.
+- **Minor bump** (`1.0 → 1.1`): additive only — new optional fields, new enum members at the
+  tail. Older consumers keep validating (open payloads, §2).
+- **Major bump** (`2.0`): anything breaking — removed/renamed fields, changed semantics, new
+  required fields. Requires new schema files and a coordinated subject migration.
+- Subjects **pin** the version they satisfy in `doctor.contract_version`; each subject repo runs
+  the conformance gate in its own CI, so drift fails the subject's build, not learn-cli's
+  runtime.
+- The `error.json` stderr shape predates the contract (it is the template chassis's `CliError`)
+  and carries no `schema_version`.
+
+## 6. The story schema (`story.json`)
+
+One schema for all subjects (spec c29): language subjects ship **graded-reader ladders**;
+culture-guide ships **narrative scenarios** (an agent-team incident the learner reasons through)
+in the same shape. Stories are committed content files in each subject repo, validated against
+this schema in the subject's CI, and embedded verbatim in `story read` payloads.
+
+| Field | Req | Meaning |
+| --- | --- | --- |
+| `schema_version` | ✓ | contract version family (`^1\.[0-9]+$`) |
+| `kind` | ✓ | const `story` |
+| `id` | ✓ | stable slug, unique within the subject |
+| `subject` | ✓ | owning subject id |
+| `title` | ✓ | display title |
+| `level` | ✓ | `beginner \| intermediate \| advanced` |
+| `level_detail` | – | finer grading: CEFR tag or `scenario` |
+| `language` | – | BCP-47 tag of the body (`fr`, `es`, `en`) |
+| `summary` | – | one-line teaser, safe for the signed-out catalog |
+| `body` | ✓ | the story text (markdown, blank-line paragraphs) |
+| `glossary` | ✓ | glossary/annotations: `[{term, definition, note?}]` (may be empty) |
+| `exercises` | ✓ | ≥1 comprehension exercises (same exercise shape as `practice`) |
+| `audio` | – | **reserved slot** for the spoken-practice follow-up: `null` or `{url?, format?, voice?, duration_seconds?}`; producers omit/null until the audio pipeline exists |
+| `source` | – | provenance for the batch pipeline: `{generator?, model?, reviewed_by?, generated_at?}` |
+
+Three reference fixtures validate against it in this repo's test suite
+(`tests/test_story_fixtures.py`), one per launch subject:
+
+- `tests/fixtures/stories/french-beginner-le-marche.json` — French graded story (A1).
+- `tests/fixtures/stories/spanish-beginner-la-panaderia.json` — Spanish graded story (A1).
+- `tests/fixtures/stories/culture-guide-scenario-overloaded-agent.json` — culture-guide
+  narrative scenario.
+
+## 7. How a new subject registers (registration, not a fork)
+
+Adding subject #4 requires **zero new platform code** in learn-cli:
+
+1. **Build a conformant CLI** — implement the eight verbs over the subject's own content and
+   state (the french/spanish implementation is the reference; culture-guide's adapter shows the
+   wrap-an-existing-engine path: `teach status → progress`, `teach lesson → lesson`,
+   `teach quiz → practice`, `teach record → record`).
+2. **Add a registry entry** in learn-cli's data-driven subject registry (t3) — no code, just
+   data: subject `id`, `display_name`, the executable `command` (console script on PATH), and
+   the pinned `contract_version`.
+3. **Prove conformance** — `learn subject doctor <subject>` must pass: it spawns the subject's
+   verbs as subprocesses, validates each `--json` payload against the pinned version's schemas,
+   and checks the exit-code and stream contracts. Wire the same gate into the subject repo's CI.
+4. **Ship content** — committed story/lesson files that validate against `story.json` (launch
+   bar: ≥10 stories across ≥3 levels for a language, ≥3 scenarios for a non-language subject).
+
+Deleting the registry entry cleanly removes the subject from all three faces.
+
+## 8. Using the machine-readable contract
+
+```python
+from learn import contract
+
+contract.CONTRACT_VERSION          # "1.0"
+contract.SCHEMA_NAMES              # the 11 shipped schemas
+schema = contract.load_schema("story")
+errors = contract.validate(payload, "story")   # [] means valid
+```
+
+Schemas are package data (`learn/contract/schemas/*.json`) loaded via `importlib.resources`, so
+the installed wheel carries them — t3's conformance gate and any subject repo's CI can validate
+without this repo checked out. Validation is stdlib-only (`learn/contract/_validate.py`);
+runtime dependencies stay empty. The validator supports exactly the keyword subset the schemas
+use, and a guard test (`test_schema_uses_only_supported_keywords`) keeps schemas inside that
+subset. Cross-file references are limited to sibling schemas (`story_read.json` → `story.json`).

{learn_cli-0.4.2 → learn_cli-0.5.1}/learn/cli/__init__.py

@@ -62,11 +62,19 @@ def _argv_has_json(argv: list[str] | None) -> bool:
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    from learn.cli._commands import auth as _auth_group
     from learn.cli._commands import cli as _cli_group
     from learn.cli._commands import doctor as _doctor_cmd
     from learn.cli._commands import explain as _explain_cmd
     from learn.cli._commands import learn as _learn_cmd
+    from learn.cli._commands import mcp as _mcp_group
+    from learn.cli._commands import next_cmd as _next_cmd
     from learn.cli._commands import overview as _overview_cmd
+    from learn.cli._commands import progress as _progress_cmd
+    from learn.cli._commands import record as _record_cmd
+    from learn.cli._commands import site as _site_group
+    from learn.cli._commands import subject as _subject_group
+    from learn.cli._commands import subjects as _subjects_cmd
     from learn.cli._commands import whoami as _whoami_cmd
 
     parser = _CliArgumentParser(
@@ -88,6 +96,14 @@ def _build_parser() -> argparse.ArgumentParser:
     _overview_cmd.register(sub)
     _doctor_cmd.register(sub)
     _cli_group.register(sub)
+    _subjects_cmd.register(sub)
+    _subject_group.register(sub)
+    _mcp_group.register(sub)
+    _site_group.register(sub)
+    _auth_group.register(sub)
+    _progress_cmd.register(sub)
+    _next_cmd.register(sub)
+    _record_cmd.register(sub)
     # Register your own noun groups here:
     #   from learn.cli._commands import my_noun as _my_noun_group
     #   _my_noun_group.register(sub)