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:

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

DO:

Use AskUserQuestion with track-adapted prompt:

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

DO:

Use AskUserQuestion with track-adapted prompt:

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:
   • Add inline wiki link in one or both {vocabulary.note_plural}
   • Add relevant_notes entry with context phrase
4. If no genuine connection exists:
   • Explain that forced connections are worse than none
   • "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.

If not connected:

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

  No genuine connection to your first note.
  That is fine -- forced connections pollute
  the graph. Real connections emerge as your
  graph grows.

Update state, then continue to Step 3.

Step 3: Process — Extract structured knowledge

WHY:

--=={ ars contexta : tutorial }==--
  [===>  ] Step 3 of 5 -- Process

  Raw material becomes structured knowledge
  through extraction. You mine for atomic
  insights, not summaries.

Adapt to track:

DO:

Use AskUserQuestion with track-adapted prompt:

Extract 1-2 atomic insights:

1. Identify propositions worth keeping (not summaries, not logistics)
2. Apply selectivity: skip purely conversational content, temporary logistics, vague observations
3. Check for connections to existing tutorial {vocabulary.note_plural}
4. Create {vocabulary.note}(s) with proper schema
5. Link where genuine connections exist

SEE:

  Extracted [N] insight(s) from your material:

  1. [title of extracted note]
     [connection status: linked to [[note]] | standalone]

  Raw material -> atomic {vocabulary.note_plural} -> connected graph.
  This is what /{reduce} does. It finds the
  propositions worth keeping and turns each into
  a composable {vocabulary.note}.

If nothing worth extracting:

  No atomic insights found in this material.
  That happens — not everything contains
  extractable propositions. The selectivity
  gate is working: better to skip than to
  create low-value {vocabulary.note_plural}.

Update state, then continue to Step 4.