/tutorial

name: tutorial
description: Interactive walkthrough for new users. Learn by doing — each step creates real content in your vault. Three tracks (researcher, manager, personal) with a universal learning arc. Triggers on "/tutorial", "walk me through", "how do I use this".
user-invocable: true
allowed-tools: Read, Write, Edit, Grep, Glob, AskUserQuestion, Bash
context: fork
model: opus
version: "1.0"
generated_from: "arscontexta-v1.6"

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. **`ops/derivation-manifest.md`** — vocabulary mapping, platform hints

• Use `vocabulary.notes` for the notes folder name
• Use `vocabulary.note` / `vocabulary.note_plural` for note type references
• Use `vocabulary.reduce` for the extraction verb
• Use `vocabulary.reflect` for the connection-finding verb
• Use `vocabulary.topic_map` for MOC references
• Use `vocabulary.inbox` for the inbox folder name

2. **`ops/config.yaml`** — processing depth, domain context

If these files don't exist, use universal defaults.

EXECUTE NOW

**Target: $ARGUMENTS**

• If `ops/tutorial-state.yaml` exists and `current_step` <= 5: resume from saved step
• If target is "reset": delete `ops/tutorial-state.yaml` and start fresh
• If no state file exists: begin new tutorial with track selection

**START NOW.** Reference below defines the flow.

---

Resume Detection

Read `ops/tutorial-state.yaml`. If it exists and tutorial is incomplete, display:

--=={ ars contexta : tutorial }==--

  Welcome back.
  Track: [track]     [step-progress] Step [N] of 5
  Resuming where you left off...

Skip to the saved `current_step`. Do NOT re-ask for track. If `current_step` > 5, tutorial is complete — offer to reset.

**Progress indicator format:**

• Step 1 of 5: `[=> ]`
• Step 2 of 5: `[==> ]`
• Step 3 of 5: `[===> ]`
• Step 4 of 5: `[====> ]`
• Step 5 of 5: `[=====>]`

Track Selection (new tutorial only)

Display header, then use AskUserQuestion:

--=={ ars contexta : tutorial }==--

Which track fits your work best?

  (a) Researcher -- academic papers, domain
      research, literature processing

  (b) Manager -- meeting notes, strategy docs,
      decision tracking

  (c) Personal -- daily observations, goal
      setting, reflective journaling

Wait for response. Map a/b/c to researcher/manager/personal.

Write initial state to `ops/tutorial-state.yaml`:

track: [researcher|manager|personal]
current_step: 1
completed_steps: []
started: [ISO 8601 UTC]
last_activity: [ISO 8601 UTC]

---

Step Execution Pattern

Every step follows WHY / DO / SEE. Before each step show progress bar. After each step, update `ops/tutorial-state.yaml` (append to `completed_steps`, increment `current_step`, update `last_activity`).

Track Adaptation Reference

Each step adapts its language and examples to the track. The structure is identical; the content varies.

| Step | Researcher | Manager | Personal | |------|-----------|---------|----------| | Capture | Claim from a paper | Decision from a meeting | Realization from a day | | Discover | Cross-paper connections | Decision-stakeholder links | Observation-goal patterns | | Process | Paper extraction | Meeting note mining | Journal crystallization | | Maintain | Stale claims, broken citations | Orphaned decisions | Disconnected reflections | | Reflect | Research graph growth | Institutional memory | Self-knowledge patterns |

---

Step 1: Capture — Create your first {vocabulary.note}

**WHY:**

--=={ ars contexta : tutorial }==--
  [=>    ] Step 1 of 5 -- Capture

  Everything starts with a thought worth keeping.

Adapt the philosophy to the track:

| Track | WHY Framing | |-------|-------------| | researcher | "Research begins when you notice something worth remembering. A claim from a paper, a pattern across studies, a question that has not been asked. The system captures these as prose-sentence titles — each title is a proposition that reads naturally when linked to other notes." | | manager | "Good decisions start with captured observations. A pattern from a meeting, a stakeholder concern, a strategic insight. The system turns these into connected notes where each title is a complete thought — not a label like 'Q3 planning' but a claim like 'Q3 velocity depends on reducing context switching'." | | personal | "Growth starts with noticing. A realization during a walk, a pattern in your week, a question about what matters. The system captures these as prose-sentence notes — each title is something you genuinely believe, like 'morning routines work because they reduce decision fatigue'." |

**DO:**

Use AskUserQuestion with track-adapted prompt:

| Track | Prompt | |-------|--------| | researcher | "Share a claim, observation, or question from your research. One sentence — something you genuinely want to remember and build on." | | manager | "Share a decision, pattern, or insight from your work. One sentence — something worth tracking across meetings and projects." | | personal | "Share a thought, observation, or realization. One sentence — something you genuinely want to remember." |

Transform input into a real {vocabulary.note}: 1. Convert input to prose-as-title filename (lowercase, safe characters, full sentence) 2. Create YAML frontmatter:

   ---
   description: [adds context beyond the title — scope, mechanism, or implication]
   topics: ["[[index]]"]
   created: [today's date]
   ---

3. Write 2-3 sentences developing the thought 4. Add Topics footer linking to the hub {vocabulary.topic_map} 5. Write the file to `{vocabulary.notes}/`

**SEE:**

  Note created:
    {vocabulary.notes}/[filename].md

  Title: [the prose title]
  Description: [the description]
  Topics: [[index]]

  Notice how the title works as prose:
    "Since [[your note title]], the question
     becomes..."

  That is what makes notes linkable. The title
  IS the t