@mulmoclaude/core 0.1.0

package/assets/helps/guide.md

@@ -0,0 +1,61 @@
+# Guide & Planner Templates
+
+Reference templates for the Guide & Planner role. Use these structures when authoring documents with `presentDocument` for any of the supported guide types.
+
+## Document Conventions (all types)
+
+Every guide should:
+
+- **Overview**: open with a summary of the key parameters (servings, days, level, budget, etc.)
+- **Numbered steps OR structured sections**: use one or the other consistently across the document
+- **Anchors**: add `<a id="step-1"></a>` (or `step-N`, `day-N`, `section-name`) to each major heading for `scrollToAnchor` navigation
+- **Images**: embed via `![Detailed image prompt](__too_be_replaced_image_path__)` — make the alt-text prompt specific enough to generate a useful illustration on its own
+- **Close**: end with tips, variations, troubleshooting, or follow-up recommendations
+- **Tone**: warm and encouraging; adapt vocabulary to the user's stated experience level
+
+## Form-First Workflow
+
+Always call `presentForm` before producing the document. Tailor fields to the request type:
+
+- **Recipe**: servings, dietary restrictions, skill level, available time, equipment
+- **Travel**: destination, dates, traveler count, interests, budget tier, accommodation type
+- **Fitness**: goal (weight loss / strength / endurance), starting level, days per week, equipment access
+- **Event**: occasion, guest count, budget, venue type, dietary needs
+- **Study guide**: topic, current level, time available, learning goal
+- **DIY / home project**: project type, skill level, tools available, budget
+
+Pre-fill any field the user already provided via `defaultValue`. Mark fields the user must answer as `required: true`. Keep forms concise — ask only for what is needed to produce a great result.
+
+## Per-Type Document Structures
+
+### Recipe
+
+overview → ingredients (scaled to the chosen servings) → equipment → prep work → numbered cooking steps (each with an image) → chef's tips → storage notes
+
+### Travel
+
+overview → day-by-day itinerary (morning / afternoon / evening) → accommodation & dining → transport between stops → budget breakdown → packing tips → local culture tips
+
+### Fitness
+
+overview → weekly schedule → per-workout breakdown (warm-up, main exercises with sets / reps / form notes, cool-down) → progression plan over weeks → nutrition tips
+
+### Event
+
+overview → timeline & checklist (T-minus weeks) → venue & catering → guest list & invitations → décor & entertainment → budget tracker
+
+### Study Guide
+
+overview → topic breakdown → key concepts per section → worked examples → practice questions → resources & references
+
+### DIY / Home Project
+
+overview → required tools & materials → safety notes → numbered steps (each with an image) → finishing & cleanup → maintenance & care
+
+## Follow-up Pattern
+
+After presenting the document:
+
+- Offer to read any step aloud (scroll to it first with `scrollToAnchor`, then narrate the step)
+- Invite follow-up questions
+- Offer to adjust the plan based on feedback (regenerate the form, add steps, change scope)

package/assets/helps/index.md

@@ -0,0 +1,89 @@
+# About MulmoClaude
+
+MulmoClaude is a GUI front-end for Claude Code. It lets you talk to Claude Code through a chat interface with rich visual output, powered by the **GUI Chat Protocol** — a plugin layer that allows Claude to render structured results (documents, spreadsheets, mind maps, images, and more) directly in the canvas alongside the conversation.
+
+Under the hood it uses the Claude Code Agent SDK as its LLM core. Claude has full access to your workspace files and can use built-in tools (read, write, bash, search) as well as GUI Chat Protocol plugins registered as MCP servers.
+
+**Core philosophy**: The workspace is the database. Files are the source of truth. Claude is the intelligent interface.
+
+## Roles
+
+- **General** — Everyday assistant: task management, scheduling, wiki, mind maps, and general Q&A.
+- **Office** — Creates documents, spreadsheets, presentations, and MulmoScript slideshows.
+- **Guide & Planner** — Collects your needs via a form, then produces a rich illustrated guide or plan. Works for recipes, travel itineraries, fitness programs, event planning, study guides, DIY projects, and more.
+- **Artist** — Generates and edits images, opens a drawing canvas, and creates 3D scenes.
+- **Tutor** — Assesses your knowledge level, then teaches any topic with structured documents and visuals.
+- **Storyteller** — Crafts illustrated narrative stories as a MulmoScript storyboard.
+- **Storyteller Plus** — Like Storyteller, with consistent character images across beats.
+- **Settings** — Manages information sources, skills, and scheduled automations for the workspace.
+- _(Additional roles may be defined by the user in the workspace.)_
+
+## Key Capabilities
+
+- Build **collections** — schema-driven data apps (todo lists, trackers, ledgers, decks) with table / calendar / kanban / dashboard views, plus LLM-authored **custom views**; manage a calendar scheduler
+- Present documents and spreadsheets with rich formatting
+- Generate and edit images
+- Create interactive mind maps
+- Generate and edit HTML pages / 3D scenes
+- Present MulmoScript multimedia stories
+- Manage a personal knowledge wiki
+- Switch between roles mid-conversation
+- Ask clarifying questions via interactive forms
+- Play browser games
+
+## Collections — Apps from Data
+
+Collections are MulmoClaude's most distinctive capability: a **schema-driven data app declared in a single small JSON file**, with no database, ORM, or migration tool. You describe a data model, cross-record relations, computed fields, and per-record action buttons in a `schema.json`; the host reads that DSL and renders a full app — table, calendar, kanban board, and dashboard views — over a folder of plain `<id>.json` records. The same primitives power todo lists, recipe boxes, stock portfolios, invoice ledgers, vocabulary decks, and curricula, all without any app-specific host code. This is the core philosophy made concrete: a `schema.json` plus a folder of records **is** the app.
+
+Because Claude authors and edits the schema for you in conversation, you build and reshape these apps just by talking — "add a priority field," "track this as a kanban," "make rent recur monthly" — and the collection updates live. We call this **vibe crafting**: the end-user counterpart of a developer's "vibe coding" — you describe the app you want and Claude builds it, with the schema validated and custom views sandboxed so you get the power without the pitfalls. Records stay validated, computed fields (totals, cross-collection lookups) recompute on every render, and completion bells / recurring obligations are declared in the same schema.
+
+See [Collection skills](config/helps/collection-skills.md) for the full schema DSL.
+
+## Custom Views — Views the Built-ins Don't Cover
+
+When the built-in table / calendar / kanban / dashboard views don't fit what you want to _see_ — a year-at-a-glance planner, a Gantt bar, a heat-map, a printable report — Claude authors a **custom view**: a single HTML file rendered in a sandboxed iframe over the collection's records. It reads (and optionally writes) records through a scoped token, stays live as the data changes, and can hand work back to a chat — all without any view-specific host code. The view is data, just like the rest of the collection, so you can ask for an entirely new way to look at your data in plain language and get it.
+
+See [Custom views](config/helps/custom-view.md) for the authoring contract.
+
+## Wiki — Long-Term Memory
+
+The wiki (`wiki/` in the workspace) acts as Claude's long-term memory. Unlike the conversation history which resets each session, the wiki is a persistent, compounding knowledge base that Claude builds and maintains over time. You feed it sources — articles, URLs, notes — and Claude ingests them into structured, interlinked Markdown pages. The more you add, the smarter it gets.
+
+See [Wiki](config/helps/wiki.md) for details on how it works.
+
+## Help Pages
+
+- [Wiki](config/helps/wiki.md) — how the personal knowledge wiki works, its folder layout, page format, and operations
+- [Gemini API Key](config/helps/gemini.md) — why `GEMINI_API_KEY` is strongly recommended (images, audio, video) and how to get one from Google AI Studio
+- [MulmoScript](config/helps/mulmoscript.md) — format reference for authoring multimedia stories: beats, image types, speech, audio, and a minimal example
+- [Business Presentation Template](config/helps/business.md) — MulmoScript template and rules for business presentations in the Office role
+- [Presentation Deck](config/helps/presentation-deck.md) — authoring business decks two ways: structured `slide` layouts (title/stats/table/timeline/…) or animated `html_tailwind` + `animation: true`, with full worked samples
+- [Storyteller Template](config/helps/storyteller.md) — MulmoScript template and rules for character-driven narrated stories in the Storyteller role
+- [Guide & Planner Templates](config/helps/guide.md) — document structures and form-field hints per guide type for the Guide & Planner role
+- [Spreadsheet](config/helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
+- [presentHtml](config/helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
+- [Sandbox](config/helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
+- [Telegram Bridge](config/helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
+- [Feeds](config/helps/feeds.md) — register a self-refreshing data feed (RSS/Atom/JSON) by authoring `feeds/<slug>/schema.json`: schema shape, the `ingest` block, raw-item field mapping, and `maxItems` retention
+- [GitHub repositories in the workspace](config/helps/github.md) — clone-destination rules under `github/<name>/` and how to handle existing directories with matching or different remotes
+- [Collection skills](config/helps/collection-skills.md) — build a data app (model + UI + relations + computed fields + action buttons) by authoring a `schema.json` collection skill: the DSL, field types, derived formulas, actions, records
+- [Custom views](config/helps/custom-view.md) — give a collection a view the built-ins don't cover (year/quarter overview, Gantt): an HTML file under `views/`, registered in `schema.json`, rendered in a sandboxed iframe over the records
+- [Todo list collection](config/helps/todo-collection.md) — the canonical recipe for building or migrating a todo / task list: full schema (status enum + `done` toggle + priority bells), `SKILL.md`, and legacy `todo-plugin` migration steps
+- [Vocabulary collection](config/helps/vocabulary.md) — recipe for a language-learning word deck (any language): `proficiency` enum + `mastered` toggle + `meaning`/`example` fields, a kanban for drag-to-promote review, and bulk-add / quiz workflows
+- [Lessons collection](config/helps/lessons-collection.md) — recipe for a multi-session **curriculum** (any topic): one lesson per record, a `status` kanban, a `file` link to each lesson's HTML, and per-lesson + course-level **Learn** actions run by the Tutor
+- [Clients + Worklog](config/helps/billing-clients-worklog.md) — recipe for a client database and a per-client timesheet (Bundle A of the billing suite); set this up before invoicing
+- [Invoicing](config/helps/billing-invoice.md) — recipe for an invoice ledger + business profile with line items, host-computed totals, and PDF / bookkeeping action buttons (Bundle B; references the clients + worklog from Bundle A)
+- [Portfolio tracker](config/helps/portfolio-tracker.md) — recipe for a paired stock-quotes watchlist + holdings portfolio whose price/value are computed live from the quotes via a cross-collection derived ref
+
+## Workspace Layout
+
+```
+~/mulmoclaude/
+  chat/          ← session tool results (.jsonl per session)
+  todos/         ← todo items
+  calendar/      ← calendar events
+  contacts/      ← address book
+  wiki/          ← personal knowledge wiki (long-term memory)
+  config/helps/  ← help pages (synced from app on every start)
+  memory.md      ← distilled facts loaded into every session
+```

package/assets/helps/lessons-collection.md

@@ -0,0 +1,400 @@
+# Lessons — a stateful-curriculum collection recipe
+
+Read this whenever the user wants to **learn a topic over multiple sessions** and
+have their **course tracked** — a sequence of lessons, where each lesson is taught
+once, practiced, and revisited, with progress that survives across conversations.
+It is the authoritative template for a lessons collection — copy it rather than
+reinventing one from the generic DSL fragments in
+`config/helps/collection-skills.md`. Read that file first for the general schema
+rules; this one is the lessons-specific specialization. For a **flashcard / word
+deck** (single-item drilling rather than a structured curriculum) use
+`config/helps/vocabulary.md` instead.
+
+The design in one line: **each lesson is one record, the `status` enum is the
+single source of truth for where the learner is in the curriculum, and a kanban
+board turns the whole course into a visible progress pipeline.** The lesson's
+actual content lives as a self-contained HTML artifact that a `file` field links
+to — so the collection is the *table of contents + progress board* over the
+self-contained HTML lessons you author.
+
+> **The `lesson` field points at a real HTML file on disk.** Each lesson's body
+> is a self-contained HTML page saved under `artifacts/html/…`; the `file` field
+> stores its **workspace-relative path**, and the row becomes a clickable link
+> that re-opens the rendered page. The collection never stores the lesson body —
+> it points at it. One concept per lesson, one HTML file per lesson, one record
+> per lesson. **How and *when* that file gets written matters — see "Authoring the
+> lesson HTML" and "Pre-generating lessons in the background" below: author ahead of
+> time in a hidden background session so the learner never waits; `presentHtml`
+> renders a single lesson to the learner but don't loop it to batch-create files.**
+
+## Ground it in the learner's goal first
+
+A curriculum is only good if it serves a real goal. **Before** authoring lessons,
+establish *why* the learner wants this and *where they already are* — the Tutor
+role does this with `putQuestions`. Capture the answer (their goal + current
+level) so later sessions can resume without re-asking: either in the SKILL.md, or
+as a `singleton` companion collection (see "Extending it"). Then pitch each
+lesson at the learner's **zone of proximal development** — challenging but
+reachable — and prefer cited, external sources over unverified recall.
+
+## schema.json
+
+Author it at `data/skills/lessons-<topic>/schema.json` — one collection per
+course, so the slug carries the topic (`lessons-french-cooking`,
+`lessons-linear-algebra`). The bridge mirrors it to `.claude/skills/<slug>/`; the
+user opens it at `/collections/lessons-<topic>`:
+
+```json
+{
+  "title": "Linear Algebra",
+  "icon": "school",
+  "dataPath": "data/lessons-linear-algebra/items",
+  "primaryKey": "id",
+  "fields": {
+    "id":        { "type": "string",   "label": "ID", "primary": true, "required": true },
+    "order":     { "type": "number",   "label": "#", "required": true },
+    "title":     { "type": "string",   "label": "Lesson", "required": true },
+    "status":    { "type": "enum",     "label": "Status", "values": ["planned", "learning", "practiced", "mastered"], "required": true },
+    "objective": { "type": "text",     "label": "What this lesson teaches" },
+    "lesson":    { "type": "file",     "label": "Lesson" },
+    "resources": { "type": "markdown", "label": "Cited sources" },
+    "notes":     { "type": "text",     "label": "Where the learner is" }
+  },
+  "displayField": "title",
+  "kanbanField": "status",
+  "actions": [
+    { "id": "learn", "label": "Learn", "icon": "school", "kind": "chat", "role": "tutor", "template": "templates/learn.md" }
+  ],
+  "collectionActions": [
+    { "id": "continue", "label": "Learn", "icon": "play_arrow", "kind": "chat", "role": "tutor", "template": "templates/continue.md" }
+  ]
+}
+```
+
+Every key earns its place:
+
+| Key | What it gives the user |
+|---|---|
+| `order` (`number`) | The curriculum sequence. Sort the table by it to read the course top-to-bottom. Cheap to renumber, unlike renaming files. |
+| `title` (`string`) | The lesson name. It is the `displayField`, so it labels every table row and kanban card. |
+| `status` (`enum`) | The four stages of mastery and the single source of truth for "where the learner is". Drives the kanban columns: `planned` → `learning` → `practiced` → `mastered`. |
+| `objective` (`text`) | The **prompt the lesson's HTML page is generated from** (see the callout below). A paragraph covering the one concept this lesson teaches, the key points, and the takeaway — keep it to **one concept** (the cardinal rule of good lessons), but describe it *fully*. Not a one-line title. |
+| `lesson` (`file`) | The clickable link to the lesson's HTML page on disk. Stores the bare workspace-relative path (`artifacts/html/lessons-<topic>/<id>.html`) — never an `/api/files/raw?...` URL. Written directly to disk when pre-authored, or set from the path `presentHtml` returns when taught live. Empty until the page exists. |
+| `resources` (`markdown`) | Cited external sources for the lesson — links the learner can return to. Grounds teaching in verifiable material, not unverified recall. |
+| `notes` (`text`) | Learner-specific observations: what they struggled with, what to revisit next time. The continuity that makes multi-session teaching work. |
+| `kanbanField` | Pins the board to `status` (drag a card → writes `status`). |
+| `displayField` | Card / table label (the lesson title, not the opaque id). |
+
+> **`objective` is the lesson's generation prompt — write it like one.** Because
+> lessons are authored just-in-time, when the page is finally written the LLM sees
+> only this record: `title` + `objective` are the entire spec it generates the
+> HTML from. So don't write a label — write a brief. Spell out the angle to take,
+> the points that must be covered, a worked example or analogy to use, what to
+> defer to other lessons, and the takeaway the learner should leave with. The
+> richer the `objective`, the better the page and the less it drifts from the
+> course you planned. Think of it as the prompt you're handing your future self.
+>
+> **Because it's a long prose field, mind the JSON:** an unescaped ASCII quote
+> inside `objective` (e.g. `…もう"中心"ではなく…`) breaks the file, and a broken
+> record is **silently skipped** — you'll quietly end up with fewer lessons than
+> you wrote. In prose, use `「」`/`『』` (or escape as `\"`), never a raw `"`.
+
+**Labels are localizable.** `title`, every `label`, and the enum `values` are free
+text — translate them into the learner's language. Product/role names stay in
+English. Keep the `status` `values` in lockstep with anything that references them
+(`kanbanField`, action `when` predicates).
+
+## Action templates
+
+There are just **two actions, both labeled "Learn"** — each picks the right mode
+automatically, so the learner never has to choose "teach vs. review vs. extend".
+Each needs a plain-English template inside the skill dir; the host starts a new
+chat in the `tutor` role seeded with it.
+
+- **Per-record action** (`actions`) — the **Learn** button on a lesson's detail
+  panel. The host prepends **that lesson's record JSON** as passive data; the
+  `learn` template teaches or reviews it depending on its `status` (the gating
+  that used to need a `when` predicate now lives inside the template).
+- **Collection-level action** (`collectionActions`) — the **Learn** button in the
+  collection header. There's no single record, so the host prepends a **compact
+  progress summary of every lesson** (each one's `id`, `title`, and `status`); the
+  `continue` template reads how far the learner has got and picks the next lesson
+  to run. `when` predicates are not evaluated on collection-level actions.
+
+Keep templates short — the role prompt already knows how to teach.
+
+`data/skills/lessons-<topic>/templates/learn.md` (per-record):
+
+```markdown
+Learn this lesson. The record above gives the lesson's `title`, its `objective`
+(a paragraph describing what to teach — your authoring brief), `status`, and — if
+already authored — its `lesson` HTML path. Pick the mode from `status`, and never
+jump straight to a quiz — the HTML page IS the lesson, so deliver it first.
+
+Deliver the page with `presentHtml`:
+- `lesson` already set (often pre-authored in the background — see below) → present
+  it by passing its **path** to `presentHtml` (no duplicate save). Instant.
+- `lesson` empty (the prefetch worker hasn't finished, or never ran) → author the
+  page **from the `objective` brief** and present it with `presentHtml` (passing the
+  `html`), then write the returned `data.filePath` into the record's `lesson` field.
+  This is the graceful fallback.
+
+**The moment the page is on screen — _before_ you teach or quiz — prefetch the next
+lesson** so its generation overlaps the whole time the learner spends here: call
+`spawnBackgroundChat` (`hidden: true`, `role: "tutor"`) to author the next-by-`order`
+lesson's HTML in the background (a self-contained message that reads that record and
+`Write`s the page to `artifacts/html/lessons-<topic>/<id>.html`, sets its `lesson`
+field, and presents nothing). Skip if it's already authored or this is the last
+lesson. **Do this now, not at the end** — the learner often advances the instant they
+finish, and a prefetch fired during the wrap-up is too late to hide the wait.
+
+Then branch on `status`:
+- `planned` / `learning` → teach the page, check understanding with a question or a
+  `presentForm` quiz, and set `status` to `learning` (or `practiced` if they nailed
+  it).
+- `practiced` / `mastered` → run a short review quiz on the `objective` (include an
+  "explain it in your own words" item); set `status` to `mastered`, or back to
+  `learning` if they're shaky.
+
+Cite real sources in the page and in `resources`, and record anything to revisit in
+`notes`. Don't re-show the collection card after a single lesson — just keep the
+conversation going; the board reflects the new `status` next time it's opened. (The
+next lesson was already prefetched right after you showed this page — see above.)
+```
+
+`data/skills/lessons-<topic>/templates/continue.md` (collection-level):
+
+```markdown
+Continue the course. The summary above lists every lesson's `id`, `title`, and
+`status`. Pick the next move, in order:
+
+1. a lesson with `status: learning` → resume it
+2. else the lowest-`order` `status: planned` lesson → start it
+3. else a `practiced` (not yet `mastered`) lesson → review it
+
+In cases 1–3, run that one lesson exactly like the per-lesson Learn button: present
+by `path` if `lesson` is set (else author from `objective`), and **immediately
+prefetch the next lesson** with a hidden `spawnBackgroundChat` worker — _before_ you
+teach or quiz, so it generates while the learner works. Then deliver the lesson, check
+understanding, and update `status` + `notes`. Don't re-show the collection card
+afterwards — just continue the conversation.
+
+4. only if **every** lesson is `mastered` → append the next batch as `planned`
+   records (a **paragraph `objective`** each — the authoring brief — continuing the
+   `order`), pitched at the learner's now-higher level; do NOT author the HTML yet.
+   When you write these records, use the language's quotation marks (`「」`/`『』`,
+   or `'…'`/`“…”`) — or escape as `\"` — in string values, never a raw `"`, or the
+   file breaks and the record is silently skipped. Then call
+   `presentCollection` once to show the expanded roadmap.
+```
+
+## Authoring the lesson HTML — two ways
+
+`presentHtml` does two things: it saves the HTML *and* **renders it in the
+learner's canvas**. The `Write` tool only saves. Choose by whether the learner
+should see the page right now.
+
+**Batch / scaffolding (no user involvement) — Write the file directly.** If you
+pre-author several lessons at once, do NOT loop `presentHtml` over them — that
+would flash every page into the canvas one after another, hijacking the
+conversation. Instead:
+
+1. Author the self-contained HTML (see `config/helps/presenthtml.md` for the
+   document rules — full `<!DOCTYPE html>`, inline CSS/JS or an allowed CDN).
+2. **Write it straight to disk** at a stable, course-scoped path:
+   `artifacts/html/lessons-<topic>/<id>.html` (filename = the record id, so the
+   link is meaningful and stable). Use the `Write` tool — not `presentHtml`.
+3. Set that path as the lesson record's `lesson` field.
+
+**Teaching one lesson live — use `presentHtml`.** This is the common case: most
+lessons are authored **just-in-time**, the moment the learner reaches them (you
+don't pre-generate the whole course up front). When you teach one and want it in
+the canvas:
+
+- **New lesson** (empty `lesson`): call `presentHtml` with the `html` — it saves
+  and renders in one step and returns the saved path in `data.filePath`. Write
+  *that* returned path into the record's `lesson` field (don't also `Write` it
+  yourself, or you'll create two copies).
+- **Pre-authored lesson** (`lesson` already set): call `presentHtml` with the
+  **`path`** (the existing `lesson` value) instead of `html` — it presents the
+  file in place without saving a duplicate.
+
+Either way, **`presentHtml` must actually run** — delivering the page is the heart
+of teaching, not an optional step before the quiz.
+
+Keep lesson pages **self-contained** (inline everything or an allowed CDN) so
+they render correctly regardless of the directory they were saved in.
+
+## Pre-generating lessons in the background — no wait
+
+Authoring a full HTML page takes the model tens of seconds, and `presentHtml` only
+renders **after** the page is fully generated. So a lesson authored at the moment
+the learner asks for it makes them **stare at a blank canvas** — worst of all on the
+very first lesson of a brand-new course. The fix: author **ahead of time, in a
+parallel background session**, so the page is already on disk (and the record's
+`lesson` field set) by the time the learner opens it. Then you just present it by
+`path`, instantly.
+
+The tool is **`spawnBackgroundChat({ message, role, hidden })`** — it launches a
+second, independent agent session that runs **concurrently** with this conversation
+and returns immediately. To pre-author one lesson:
+
+```
+spawnBackgroundChat({
+  role: "tutor",
+  hidden: true,
+  message: "<a fully self-contained instruction — see the rules below>"
+})
+```
+
+Rules for the worker:
+
+- **`hidden: true`, always.** These are plumbing, not conversations — a visible
+  worker would clutter the learner's chat history. (`hidden: false` exists for other
+  uses where the user *should* see the spawned chat; a lesson worker is never that.)
+- **The `message` must be fully self-contained** — the worker shares NONE of this
+  chat's context. Spell out: read the record at
+  `data/lessons-<topic>/items/<id>.json`; author a self-contained HTML page **from
+  its `objective`** (full `<!DOCTYPE html>`, inline CSS/JS or an allowed CDN — see
+  `config/helps/presenthtml.md`); **`Write`** it to
+  `artifacts/html/lessons-<topic>/<id>.html`; set that path as the record's `lesson`
+  field with `manageCollection` putItems `mode: "merge"` (`{ id, lesson }` — merge
+  keeps every other field); do **NOT** call `presentHtml` and do **NOT** present
+  anything — just write the files and stop. (No one is viewing the worker's canvas,
+  so presenting there is wasted.)
+- **One lesson per call**, and don't spawn a fleet — the host caps concurrent hidden
+  workers and a worker can't spawn further workers.
+
+**When to pre-author:**
+
+1. **At course creation — pre-author lesson 1 (optionally 2).** Right after
+   `presentCollection` shows the roadmap, fire a worker for lesson 1 and tell the
+   learner it's being prepared (e.g. "コースができました!最初のレッスンを準備中です。
+   準備ができたら『始めて』と言ってください"). The learner reads the roadmap while the
+   page generates — the wait now **overlaps** with something useful instead of being
+   dead air. Do **not** also author lesson 1 inline in the same turn.
+2. **Prefetch the next lesson the moment you present the current one — not at the
+   end.** As soon as lesson N's page is on screen (*before* you teach or quiz it),
+   fire a worker for the next-by-`order` lesson, so its generation overlaps the
+   *whole* time the learner spends on N. Waiting until you update `status`/`notes` is
+   too late — the learner often advances the instant they finish, and the wait
+   reappears. By the time they reach N+1, it's already authored → instant.
+
+**Presenting, and the fallback.** When the learner opens a lesson, check its `lesson`
+field: **set** → `presentHtml` by `path` (instant); **still empty** (the worker
+hasn't finished, or never ran) → author it inline from `objective` as usual. The
+inline path is the graceful fallback — background pre-generation is a pure
+optimization, never a dependency. Because workers write to the **stable**
+`artifacts/html/lessons-<topic>/<id>.html` path, a rare double-author (learner races
+ahead of the worker) just overwrites in place — never a duplicate.
+
+## SKILL.md
+
+`data/skills/lessons-<topic>/SKILL.md` tells the agent when and how to operate the
+collection. Keep it short — the schema and templates do the heavy lifting. Cover:
+
+- **Trigger phrases** — "teach me <topic>", "what's my next lesson", "continue my
+  course", "I'm ready for the next one", plus the equivalents in the learner's
+  language.
+- **Record shape** — point at the schema; note `id` is the filename
+  (`lesson-<order3>-<slug>`, e.g. `lesson-001-eigenvalues`), new lessons start at
+  `status: "planned"` with an empty `lesson`, `order` is the reading sequence, and
+  `objective` is a **full paragraph** (the authoring brief), not a one-liner.
+- **The teaching loop** —
+  - **Plan the course**: once the goal/level is known, draft the full sequence of
+    lessons as `planned` records, in `order`, so the learner can see the road
+    ahead. Give each one a **paragraph `objective`** — what that lesson must teach,
+    its key points, the intended takeaway — not just a title. That paragraph is
+    what makes deferred authoring work: when you write the page later, the record's
+    `objective` is the prompt you generate it from, so write it that way. Once the
+    records are written, call `presentCollection` **once** to show the roadmap (this
+    also surfaces any malformed records right away). **Then immediately fire a hidden
+    `spawnBackgroundChat` worker to pre-author lesson 1** and tell the learner it's
+    being prepared — do NOT author lesson 1 inline in the same turn (see
+    "Pre-generating lessons in the background"). The learner reads the roadmap while
+    it generates.
+  - **Pre-author lesson 1 in the background** (then the rest just-in-time): the
+    worker above writes lesson 1's HTML to disk and sets its `lesson` path, so the
+    first open never waits. You *may* fire a second worker for lesson 2 as well.
+    Leaving the rest `planned` with an empty `lesson` and prefetching each next
+    lesson as you open the current one is the default — never pre-generate the
+    whole course up front.
+  - **Learn a lesson** (the per-lesson **Learn** button): always **deliver the page
+    with `presentHtml` first** — never jump straight to a quiz. Present by `path` if
+    `lesson` is set (usually it was pre-authored in the background), else author from
+    `objective` inline (store the returned `data.filePath`) as the fallback. **The
+    moment the page is shown — before teaching or quizzing — prefetch the next lesson**
+    with a hidden `spawnBackgroundChat` worker, so its generation overlaps this whole
+    lesson rather than starting at the end. Then branch on `status`:
+    `planned`/`learning` → teach + quiz (→ `learning`/`practiced`);
+    `practiced`/`mastered` → review quiz (→ `mastered`, or back to `learning` if
+    shaky). Record gaps in `notes`.
+  - **Continue the course** (the header **Learn** button, `continue` action): from
+    the progress summary, resume a `learning` lesson, else start the lowest-`order`
+    `planned` one, else review a `practiced` lesson; **prefetch the next lesson the
+    moment you present the current one** (not after running it) — and only once
+    everything is `mastered`, append the next batch of `planned` lessons (paragraph
+    `objective` each, HTML authored lazily later).
+- **Operations** — record I/O via `manageCollection` (`getItems` to read;
+  `putItems` for schema-validated writes — `mode: "create"` for new lessons,
+  `mode: "merge"` with a partial row for status/notes/lesson updates so the
+  fields you omit survive; Delete removes the file at
+  `data/lessons-<topic>/items/<id>.json`; raw Read / Write / Edit is the
+  escape hatch). Rather than dumping the whole course into chat,
+  point the user at `/collections/lessons-<topic>`.
+- **When to call `presentCollection`** — when the **course itself** changes: after
+  creating the collection or adding/extending lessons (it also surfaces malformed
+  records). Do **not** call it after each individual lesson's teach/review — a
+  single `status` update doesn't need the whole board re-rendered; that's just
+  noise mid-lesson.
+
+## A record on disk
+
+One JSON per lesson — `lesson` is empty until the lesson is taught. Note the
+`objective` is a full paragraph (the brief the page will be authored from), not a
+one-liner:
+
+```json
+{ "id": "lesson-001-eigenvalues", "order": 1, "title": "What an eigenvalue is", "status": "planned", "objective": "Teach that an eigenvector is a direction a matrix only scales (never rotates), and its eigenvalue is the scale factor. Cover the geometric picture first (a transformation acting on a few vectors, most changing direction, a special one not), then the equation Av = λv. The takeaway: the learner can look at a 2x2 transformation and point to which directions are eigenvectors. Keep it geometric — defer the characteristic-polynomial algebra to a later lesson." }
+```
+
+After teaching, the same record gains its artifact link:
+
+```json
+{ "id": "lesson-001-eigenvalues", "order": 1, "title": "What an eigenvalue is", "status": "learning", "objective": "Teach that an eigenvector is a direction a matrix only scales (never rotates), and its eigenvalue is the scale factor. Cover the geometric picture first, then Av = λv. Takeaway: spot eigenvectors of a 2x2 transformation by eye. Keep it geometric.", "lesson": "artifacts/html/lessons-linear-algebra/lesson-001-eigenvalues.html", "resources": "- [3Blue1Brown](https://www.3blue1brown.com/)", "notes": "Solid on the geometry; revisit the algebra next time." }
+```
+
+## What the learner gets, with zero host code
+
+- **Table** — the whole course in `order`, each row showing its `status` and a
+  clickable link to the rendered lesson. The `status` dropdown edits inline.
+- **Kanban** — columns from `status`; the course as a progress pipeline. Drag a
+  card to promote/demote a lesson, or run an entire review pass by dragging.
+- **Learn button (per lesson)** — one tap starts a fresh Tutor chat seeded with
+  that lesson; it teaches or reviews based on the lesson's `status`, so there's
+  nothing to decide.
+- **Learn button (header)** — seeds a Tutor chat with the whole course's progress
+  and resumes where you left off — picking the next lesson, or growing the course
+  once everything's mastered.
+- Because each lesson is its own file, the course is fully diffable and portable;
+  the learner owns it as plain JSON plus the HTML artifacts.
+
+## Extending it
+
+- **Spaced review reminders.** Add a `reviewBy` (`date`) field plus
+  `"completionField": "status"`, `"completionDoneValues": ["mastered"]`,
+  `"triggerField": "reviewBy"`, and a `"notifyWhen": { "field": "status", "in":
+  ["practiced", "mastered"] }`. The bell then nudges the learner to review a
+  taught lesson on its `reviewBy` date — without belling every `planned` lesson.
+- **The mission / goal.** For a durable record of *why* the learner is studying,
+  add a `singleton` companion collection (`lessons-<topic>-goal`, `singleton:
+  "goal"`) with `goal`, `level`, and `target` fields — read it at the start of
+  every session to resume without re-interviewing.
+- **A "mastered" checkbox.** Add a `toggle` projecting `status`
+  (`"field": "status", "onValue": "mastered", "offValue": "practiced"`) for a
+  one-click way to mark a reviewed lesson done.
+- **Prerequisites.** Add a `ref` field pointing back into the same collection to
+  record which lesson must come first — useful for non-linear curricula.
+
+Keep additions minimal — the core fields (`order`, `title`, `status`,
+`objective`, `lesson`) are enough to start teaching a tracked course today.