tutorial-creator v2.0.0

[Terryc21]

What's in v2.0.0

A ground-up redesign that turns tutorial-creator from a single-mode tutorial generator into a three-surface learning workflow.

Added

• Three top-level surfaces, gateway-mediated. Bare invocation now asks what you want to do ([1] write a tutorial for myself, [2] write a tutorial for others, [3] manage vocabulary, [4] inspect learning
  state). The --mode learn|audience|both|vocab|status flag skips the gateway.

• Six writing-to-learn entry points: [a] daily progression, [b] topic + file, [c] topic only (skill ranks candidate files by pedagogical fit), [d] question-led (with honest-machine ambiguity surfacing),
  [e] gap-driven (reads from vocab gap radar), [f] external source (fetches a public artifact and produces a writing-to-learn synthesis).

• Audience-facing path with five entry points (annotated source / incident-grounded / synthesized / external / documentation-grounded) that hand off to six venue templates: reddit, book-chapter,
  apple-developer-article, medium, blog, repo-doc. Each venue has its own voice register, length budget, and honest-machine section convention.

• Vocabulary as a first-class object. vocabulary.yaml is the source of truth; VOCABULARY.md is a regenerated view. Subcommands: vocab add, list, show, edit, merge, review, gap, regen-md, undo.
  Status state machine: new → reviewing → mastered | confused. Status is earned through tests, never user-set.

• vocab review — spaced-repetition test session. Picks 5 terms (confused > stale > random); grades leniently by default (--strict available). Each result appends to test_history and recomputes status.

• vocab gap — radar of confused terms, ranked by staleness. Feeds entry [e] gap-driven directly.

• Status dashboard (/skill tutorial-creator status) — read-only view: tutorials shipped, last lesson, streak, vocab counts by status, due-for-review count, gap radar, suggested next lesson.

• Recovery surface: per-generation session log under .claude/tutorial-sessions/, snapshot save before generation, undo (revert most recent generation), renumber <old> <new>, 24-hour soft-stage for vocab add
  with vocab undo. Last 10 sessions retained.

• Project resolution from any cwd: --project-dir flag, TUTORIAL_CREATOR_PROJECT_DIR env var, ancestor walk from cwd, registry at ~/.claude/tutorial-creator/registry.yaml, and open / forget subcommands.

• Externalized progressions for Swift, TypeScript, Python, and Rust under progressions/<lang>.yaml. Custom progressions go via progression_override in tutorial-config.yaml.

• Schemas locked in SCHEMAS.md: tutorial-config, vocabulary, session-log, progressions.

Changed

• Bare invocation no longer assumes tutorial-generation intent. The gateway question runs first; pass --mode <surface> to skip it.
• VOCABULARY.md is no longer the source of truth; vocabulary.yaml is. VOCABULARY.md is regenerated on demand from yaml via vocab regen-md.
• The legacy v1.1 invocation (/skill tutorial-creator <topic> <source>) still works and routes to writing-to-learn entry [b].

Migration from v1.1

After installing v2.0, run a one-time import to convert your existing VOCABULARY.md to the v2.0 vocabulary.yaml source of truth:

/skill tutorial-creator vocab regen-md --import

Migrated terms enter v2.0 with status: reviewing. Use vocab edit to add types, vocab merge to collapse duplicates, and vocab review to start earning mastered status.

See CHANGELOG.md for the full release notes.

Checkboxes (bottom of form):

• ☑ Set as the latest release
• ☐ Set as a pre-release (leave unchecked)
• ☑ Create a discussion for this release → Category: Announcements

Click Publish release. Tell me when it lands and I'll do the post-merge cleanup.

✻ Worked for 27s

❯ Shouldn't the most valuable feedback be pasted into a description field of hte disccusion?

⏺ You're right — that's cleaner.

GitHub does in fact let you customize the discussion when you create it from a release. Here's how it actually works:

1. On the release form, when you check "Create a discussion for this release," the discussion's initial post = the release body. There's no separate field on the release form itself.
2. BUT — once the release is published and the discussion is auto-created, you can edit the discussion post independently of the release notes. They become two separate artifacts after that point.

So the clean split you want is achievable. Here's the workflow:

Step 1 — On the release form (now):

Paste only the changelog half in "Describe this release":

A ground-up redesign that turns tutorial-creator from a single-mode tutorial generator into a three-surface learning workflow.

Added

• Three top-level surfaces, gateway-mediated. Bare invocation now asks what you want to do ([1] write a tutorial for myself, [2] write a tutorial for others, [3] manage vocabulary, [4] inspect learning
  state). The --mode learn|audience|both|vocab|status flag skips the gateway.

• Six writing-to-learn entry points: [a] daily progression, [b] topic + file, [c] topic only (skill ranks candidate files by pedagogical fit), [d] question-led (with honest-machine ambiguity surfacing),
  [e] gap-driven (reads from vocab gap radar), [f] external source (fetches a public artifact and produces a writing-to-learn synthesis).

• Audience-facing path with five entry points (annotated source / incident-grounded / synthesized / external / documentation-grounded) that hand off to six venue templates: reddit, book-chapter,
  apple-developer-article, medium, blog, repo-doc. Each venue has its own voice register, length budget, and honest-machine section convention.

• Vocabulary as a first-class object. vocabulary.yaml is the source of truth; VOCABULARY.md is a regenerated view. Subcommands: vocab add, list, show, edit, merge, review, gap, regen-md, undo.
  Status state machine: new → reviewing → mastered | confused. Status is earned through tests, never user-set.

• vocab review — spaced-repetition test session. Picks 5 terms (confused > stale > random); grades leniently by default (--strict available). Each result appends to test_history and recomputes status.

• vocab gap — radar of confused terms, ranked by staleness. Feeds entry [e] gap-driven directly.

• Status dashboard (/skill tutorial-creator status) — read-only view: tutorials shipped, last lesson, streak, vocab counts by status, due-for-review count, gap radar, suggested next lesson.

• Recovery surface: per-generation session log under .claude/tutorial-sessions/, snapshot save before generation, undo (revert most recent generation), renumber <old> <new>, 24-hour soft-stage for vocab add
  with vocab undo. Last 10 sessions retained.

• Project resolution from any cwd: --project-dir flag, TUTORIAL_CREATOR_PROJECT_DIR env var, ancestor walk from cwd, registry at ~/.claude/tutorial-creator/registry.yaml, and open / forget subcommands.

• Externalized progressions for Swift, TypeScript, Python, and Rust under progressions/<lang>.yaml. Custom progressions go via progression_override in tutorial-config.yaml.

• Schemas locked in SCHEMAS.md: tutorial-config, vocabulary, session-log, progressions.

Changed

• Bare invocation no longer assumes tutorial-generation intent. The gateway question runs first; pass --mode <surface> to skip it.
• VOCABULARY.md is no longer the source of truth; vocabulary.yaml is. VOCABULARY.md is regenerated on demand from yaml via vocab regen-md.
• The legacy v1.1 invocation (/skill tutorial-creator <topic> <source>) still works and routes to writing-to-learn entry [b].

Migration from v1.1

After installing v2.0, run a one-time import to convert your existing VOCABULARY.md to the v2.0 vocabulary.yaml source of truth:

/skill tutorial-creator vocab regen-md --import

Migrated terms enter v2.0 with status: reviewing. Use vocab edit to add types, vocab merge to collapse duplicates, and vocab review to start earning mastered status.

Feedback wanted — see the linked discussion below for specific questions I'd love your input on.

See CHANGELOG.md for the full release notes.

---

This discussion was created from the release tutorial-creator v2.0.0.