T-B7Y2-learning-p2-corpus-and-cli

State: planning/proposed · Impact: high · Complexity: large

Goal

Give the solution its content and its first authoring tool together. The CLI’s check verb validates a book vault against the book-model contracts and bundle zips it with a manifest. The two existing corpora, vimit’s MDX collections and learn_web’s books_v2 SQL book, are converted into book vaults by a one-shot script and are the first books to pass check. Four content formats become one.

Today

Location	Role today
solutions/augmented/apps/vimit/content/	The vim curriculum: 4 books, 4 parts, 18 modules, 41 definitions, flash cards and sets, as MDX with Astro-collection frontmatter (src-astro/src/content.config.ts)
solutions/augmented/apps/learn_web/data/books_v2/	The SQL book in Model B: a JSON tree, content notes by id, SQL files and sqlite-example configs
solutions/augmented/apps/learn_web/scripts/migrate-v1-to-v2.ts	The precedent for a one-shot corpus converter with a test
solutions/augmented/apps/augmented-books/runners/sqlite/schema.call.json	The SQL exercise verification schema the exercise spec adopts
solutions/augmented/apps/vimit_prototype/shared/types/vim-problem.ts	The vim exercise spec: start document, target state, allowed keys, hints
packages/vaults/fitness/	The reference corpus-as-vault package: generator, check via rumdl, idempotent rebuild
solutions/determined/packages/vault-contracts/	The reference contract corpus: zod, with a JSON Schema projection

Proposed

Each book is one vault under solutions/determined/vaults/<book>/:

vaults/vim/
  book.md               kind: book; id, title, description, order of parts
  parts/<part>.md        kind: part; order, modules
  modules/<module>.md    kind: module; prose with exercise fences
  glossary/<term>.md     kind: definition
  cards/<set>.md         kind: card-set; cards in frontmatter

@determined/book-model holds the zod contract per kind, the exercise fence spec schemas (vim-exercise, sql-exercise), and a JSON Schema projection. solutions/determined/apps/learning-cli/ is a Bun CLI with check <vault> and bundle <vault> --out. The bundle is a zip of the vault folder plus manifest.json carrying the book id, title, format version and content hash. Both corpora convert with a script that is idempotent and tested.

Approach

1. Define the note kinds and their contracts in book-model, with the two exercise spec schemas ported from the vim-problem type and the SQL verification schema.
2. Write check: walk the vault with @sksizer/obsidian-vault, validate frontmatter per kind, resolve wikilinks, parse every exercise fence, and fail with a path and a reason.
3. Write bundle and its inverse unbundle in the CLI. Ids come from book.md, never from the folder name.
4. Write the vimit converter: MDX to markdown, the Term and Demonstration components to a fence and a wikilink, collections to folders, references to wikilinks, flash-card JSON to card-set notes.
5. Write the books_v2 converter: the tree becomes folder order plus order fields; sqlite-example configs become sql-exercise fences.
6. Run both, run check, commit the vaults. Bundle each once to prove the round trip.

Areas

Area	Note
solutions/determined/packages/book-model/	Contracts, exercise specs, schema projection
solutions/determined/apps/learning-cli/	check, bundle, unbundle
solutions/determined/vaults/vim/	Converted vim curriculum
solutions/determined/vaults/intro-to-sql/	Converted SQL book
solutions/determined/scripts/	The two converters and their tests
lefthook.yml	Exclude solutions/determined/vaults/** from markdown reflow

Acceptance criteria

• AC-1: learning check passes on both converted vaults and fails, naming the note, on a fixture with a bad kind and one with an unparseable fence.
• AC-2: bundle then unbundle reproduces the vault byte for byte.
• AC-3: Running each converter twice changes nothing.
• AC-4: The product from P1 opens either vault and reads every module.

Out of scope

• Exercises rendering as anything but a code block. P3.
• Model A content under learn_web/data/books/ and the editor-scratch books. Dropped.

Dependencies

• T-4VNC for the solution tree and the package stubs.

Discovery context

• D-LIRI and the augmented survey of 2026-09-12.

Depends on

T-4VNC

---

← Back to Tasks