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
2. Use vocabulary.notes for the notes folder name
3. Use vocabulary.note / vocabulary.note_plural for note type references
4. Use vocabulary.reduce for the extraction verb
5. Use vocabulary.reflect for the connection-finding verb
6. Use vocabulary.topic_map for MOC references
7. Use vocabulary.inbox for the inbox folder name

1. 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:

```yaml

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

```

1. Write 2-3 sentences developing the thought
2. Add Topics footer linking to the hub {vocabulary.topic_map}
3. 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 extend a finding about tools. A pattern in one study might contradict a pattern in another. These connections are where insight lives — not in individual papers but in the relationships between ideas." | | manager | "Organizational knowledge compounds when decisions connect. A hiring decision relates to a capacity concern. A strategy shift affects multiple projects. The connections reveal the system behind individual choices." | | personal | "Self-knowledge compounds when observations connect. A morning routine insight might connect to an energy pattern. A relationship observation might extend a communication realization. The connections reveal what you actually believe." |

DO:

Use AskUserQuestion with track-adapted prompt:

| Track | Prompt | |-------|--------| | researcher | "Share a second research insight — ideally one that connects to your first note, but any genuine claim works." | | manager | "Share another work observation — ideally one that relates to the first, but any genuine insight works." | | personal | "Share another thought — ideally one that connects to the first, but any genuine observation works." |

Create a second {vocabulary.note}. Then search for connections to the first {vocabulary.note}:

1. Read both {vocabulary.note_plural}
2. Apply the articulation test: can you complete "[[note A]] connects to [[note B]] because [specific reason]"?
3. If genuine connection exists:
4. Add inline wiki link in one or both {vocabulary.note_plural}
5. Add relevant_notes entry with context phrase
6. If no genuine connection exists:
7. Explain that forced connections are worse than none
8. "These notes do not connect yet, and that is fine. The graph grows over time."

SEE:

If connected:

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

  Connection:
    [[note A]] connects to [[note B]]
    because [your articulated reason]

  This is what /reflect does at scale --
  finding genuine connections across your
  entire graph.
`