tutorial

## 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`:
```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:
   ```yaml
   ---
   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 thought, expressed as a sentence.
```

Update state, then continue to Step 2.

---

### Step 2: Discover — Find connections

**WHY:**

```
--=={ ars contexta : tutorial }==--
  [==>   ] Step 2 of 5 -- Discover

  A note alone is a file. Notes that connect
  become a knowledge graph.
```

Adapt to track:

| Track | WHY Framing |
|-------|-------------|
| researcher | "Research compounds when claims connect. A finding about methodology might e