Experiment: replace how-to guides with paired human + agent tutorials

[abegong]

Idea

Experiment with replacing the how-to guides (docs/content/how-to/) with
tutorials. Rather than task-oriented recipes, offer two tutorials that walk
the same workflow end to end:

1. Handcrafted, artisanal tutorial (human). Shows a human how to do it with
   a toy example. Deliberately simple, and the whole thing could be tested
   (the toy example and its expected output pinned), so it stays correct as the
   CLI evolves.
2. Agent-driven tutorial (same workflow, richer). Uses an agent to perform
   the same steps in the same workflow, with more richness and detail. Likely
   shown as a video rather than source code — the agent run is too complex
   and detailed to render well as plain documentation.

The two mirror each other: same workflow, one done by hand and one driven by an
agent, at different levels of fidelity.

Why note it

• It would shift the docs from Diátaxis how-to toward tutorial, which is a
  content-strategy change worth deciding deliberately.
• There's already a prefiguring split in the tree:
  profile-an-existing-wiki-by-hand.md vs
  profile-an-existing-wiki-with-an-agent.md.
• It interacts with the skill-distribution work: that spec sets up a
  shared-taxonomy + cross-link relationship between the how-to guides and the
  skills. If the guides become tutorials, the cross-link targets and the
  "matching guide" mapping move with them.

Open questions (for later)

• A tested human tutorial implies a harness for doc examples — relation to the
  existing worked-examples registry / docs-gen machinery?
• Where do videos live and how are they kept current as the CLI changes (the
  thing plain docs make easy to test, video makes hard)?
• Does this replace the how-to section outright, or sit alongside it?

Scope

Out of scope for the skill-distribution spec; no change needed there. This
is a separate experiment to pick up on its own.

🤖 Generated with Claude Code