arscontexta 0.6.0

package/reference/validate-kernel.sh

@@ -0,0 +1,432 @@
+#!/usr/bin/env bash
+# validate-kernel.sh — Check a knowledge system against the 15 universal primitives
+# Usage: ./validate-kernel.sh [path-to-vault]
+# Defaults to current directory if no path given.
+
+VAULT="${1:-.}"
+PASS=0
+WARN=0
+FAIL=0
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+pass() { echo -e "  ${GREEN}PASS${NC} $1"; PASS=$((PASS + 1)); }
+warn() { echo -e "  ${YELLOW}WARN${NC} $1"; WARN=$((WARN + 1)); }
+fail() { echo -e "  ${RED}FAIL${NC} $1"; FAIL=$((FAIL + 1)); }
+
+echo "=== Kernel Validation: $VAULT ==="
+echo ""
+
+# --- Primitive 1: Markdown files with YAML frontmatter ---
+echo "1. Markdown files with YAML frontmatter"
+md_files=$(find "$VAULT" -name "*.md" -not -path "*/.git/*" -not -path "*/node_modules/*" -not -name "README.md" -not -name "SKILL.md" -not -name "CLAUDE.md" -not -name "AGENTS.md" -not -name "SOUL.md")
+md_count=$(echo "$md_files" | grep -c . || true)
+
+if [ "$md_count" -gt 0 ]; then
+    yaml_count=$(echo "$md_files" | xargs -I{} head -1 {} 2>/dev/null | grep -c "^---$" || true)
+    no_yaml=$((md_count - yaml_count))
+
+    if [ "$no_yaml" -eq 0 ]; then
+        pass "$md_count markdown files, all with YAML frontmatter"
+    elif [ "$no_yaml" -lt "$((yaml_count / 5 + 1))" ]; then
+        warn "$yaml_count with YAML, $no_yaml without (< 20% missing)"
+    else
+        fail "$no_yaml of $md_count files missing YAML frontmatter"
+    fi
+else
+    fail "No markdown files found"
+fi
+
+# --- Primitive 2: Wiki links as graph edges ---
+echo "2. Wiki links as graph edges"
+link_files=$(grep -rl '\[\[' "$VAULT" --include="*.md" 2>/dev/null | grep -v ".git" | wc -l | tr -d ' ')
+total_notes=$(echo "$md_count")
+if [ "$total_notes" -eq 0 ]; then
+    fail "No notes to check"
+elif [ "$link_files" -gt "$((total_notes / 2))" ]; then
+    pass "$link_files of $total_notes files contain wiki links"
+else
+    warn "Only $link_files of $total_notes files contain wiki links (< 50%)"
+fi
+
+# Build index of existing filenames for dangling link check
+existing_files=$(find "$VAULT" -name "*.md" -not -path "*/.git/*" 2>/dev/null | xargs -I{} basename {} .md | sort -u)
+
+# Extract wiki links from note content (scan known note directories)
+dangling=0
+checked=0
+
+# Collect links from note directories only
+link_candidates=""
+for d in "01_thinking" "notes" "00_inbox" "04_meta/logs"; do
+    if [ -d "$VAULT/$d" ]; then
+        new_links=$(grep -roh '\[\[[A-Za-z][^]]*\]\]' "$VAULT/$d" 2>/dev/null | sed 's/\[\[//g;s/\]\]//g' | sort -u)
+        if [ -n "$new_links" ]; then
+            link_candidates=$(printf '%s\n%s' "$link_candidates" "$new_links")
+        fi
+    fi
+done
+# Also check parent self/ if it exists
+[ -d "$VAULT/../self" ] && {
+    new_links=$(grep -roh '\[\[[A-Za-z][^]]*\]\]' "$VAULT/../self" 2>/dev/null | sed 's/\[\[//g;s/\]\]//g' | sort -u)
+    [ -n "$new_links" ] && link_candidates=$(printf '%s\n%s' "$link_candidates" "$new_links")
+}
+
+# Deduplicate and sample
+link_candidates=$(echo "$link_candidates" | sort -u | head -100)
+
+while IFS= read -r link; do
+    [ -z "$link" ] && continue
+    checked=$((checked + 1))
+    if ! echo "$existing_files" | grep -qxF "$link"; then
+        dangling=$((dangling + 1))
+    fi
+done <<< "$link_candidates"
+
+if [ "$checked" -eq 0 ]; then
+    warn "No wiki links found to check"
+elif [ "$dangling" -eq 0 ]; then
+    pass "No dangling wiki links (checked $checked unique links)"
+else
+    # Dangling links are common in mature vaults (examples, planned notes)
+    # Report as info, not failure
+    warn "$dangling unresolved wiki links out of $checked unique (may include examples)"
+fi
+
+# --- Primitive 3: MOC hierarchy ---
+echo "3. MOC hierarchy for attention management"
+moc_count=$(grep -rl '^type: moc' "$VAULT" --include="*.md" 2>/dev/null | grep -v ".git" | wc -l | tr -d ' ')
+if [ "$moc_count" -eq 0 ]; then
+    moc_like=$(grep -rl '## Core Ideas' "$VAULT" --include="*.md" 2>/dev/null | grep -v ".git" | wc -l | tr -d ' ')
+    if [ "$moc_like" -gt 0 ]; then
+        warn "$moc_like MOC-like files but none declare type: moc"
+    else
+        fail "No MOCs found"
+    fi
+elif [ "$moc_count" -lt 3 ]; then
+    warn "$moc_count MOCs (minimum recommended: 3)"
+else
+    pass "$moc_count MOCs found"
+fi
+
+# --- Primitive 4: Tree injection / workspace map ---
+echo "4. Tree injection at session start"
+has_tree=false
+[ -f "$VAULT/.claude/hooks/session-start.sh" ] && has_tree=true
+[ -f "$VAULT/WORKSPACE-MAP.md" ] && has_tree=true
+for ctx in "$VAULT/CLAUDE.md" "$VAULT/AGENTS.md" "$VAULT/SOUL.md"; do
+    [ -f "$ctx" ] && grep -qi "tree\|workspace.map\|orient" "$ctx" 2>/dev/null && has_tree=true
+done
+find "$VAULT" -name "session-orient.sh" -not -path "*/.git/*" 2>/dev/null | grep -q . && has_tree=true
+
+if $has_tree; then
+    pass "Tree injection mechanism found"
+else
+    warn "No tree injection mechanism detected"
+fi
+
+# --- Primitive 5: Description field ---
+echo "5. Description field for progressive disclosure"
+# Find notes in common locations
+notes_dirs=""
+for d in "notes" "01_thinking" "thinking" "knowledge"; do
+    [ -d "$VAULT/$d" ] && notes_dirs="$notes_dirs $VAULT/$d"
+done
+[ -z "$notes_dirs" ] && notes_dirs="$VAULT"
+
+desc_count=0
+no_desc=0
+for dir in $notes_dirs; do
+    d=$(grep -rl '^description:' "$dir" --include="*.md" -l 2>/dev/null | grep -v ".git" | wc -l | tr -d ' ')
+    n=$(find "$dir" -maxdepth 1 -name "*.md" -not -name "README.md" -not -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+    desc_count=$((desc_count + d))
+    no_desc=$((no_desc + n - d))
+done
+
+total_n=$((desc_count + no_desc))
+if [ "$total_n" -eq 0 ]; then
+    warn "No notes found in expected directories"
+elif [ "$no_desc" -le 0 ]; then
+    pass "All $desc_count notes have description fields"
+elif [ "$no_desc" -lt "$((total_n / 5 + 1))" ]; then
+    warn "$desc_count with descriptions, $no_desc without (< 20% missing)"
+else
+    fail "$no_desc of $total_n notes missing description field"
+fi
+
+# --- Primitive 6: Topics footer ---
+echo "6. Topics footer linking notes to MOCs"
+topics_count=0
+no_topics=0
+for dir in $notes_dirs; do
+    t=$(grep -rl '^topics:' "$dir" --include="*.md" 2>/dev/null | grep -v ".git" | wc -l | tr -d ' ')
+    n=$(find "$dir" -maxdepth 1 -name "*.md" -not -name "README.md" -not -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+    topics_count=$((topics_count + t))
+    no_topics=$((no_topics + n - t))
+done
+
+total_t=$((topics_count + no_topics))
+if [ "$total_t" -eq 0 ]; then
+    warn "No notes found in expected directories"
+elif [ "$no_topics" -le 0 ]; then
+    pass "All $topics_count notes have topics"
+elif [ "$no_topics" -lt "$((total_t / 5 + 1))" ]; then
+    warn "$topics_count with topics, $no_topics without (< 20% missing)"
+else
+    fail "$no_topics of $total_t notes missing topics"
+fi
+
+# --- Primitive 7: Schema enforcement ---
+echo "7. Schema enforcement via validation"
+has_templates=false
+has_validation=false
+for d in "templates" "04_meta/templates" "_templates"; do
+    [ -d "$VAULT/$d" ] && has_templates=true && break
+done
+find "$VAULT" -name "validate-schema.sh" -o -name "validate.sh" -not -path "*/.git/*" 2>/dev/null | grep -q . && has_validation=true
+find "$VAULT" -path "*/validate/SKILL.md" -o -path "*/verify/SKILL.md" 2>/dev/null | grep -q . && has_validation=true
+
+if $has_templates && $has_validation; then
+    pass "Templates and validation mechanism found"
+elif $has_templates; then
+    warn "Templates found but no validation mechanism"
+elif $has_validation; then
+    warn "Validation found but no template directory"
+else
+    fail "No templates or validation mechanism found"
+fi
+
+# --- Primitive 8: Self space (CONFIGURABLE) ---
+echo "8. Self space for agent persistent memory (configurable)"
+# Check for self/ in vault, sibling to vault, or common alternatives
+self_dir=""
+for candidate in "$VAULT/self" "$VAULT/../self" "$VAULT/self/memory"; do
+    [ -d "$candidate" ] && self_dir="$candidate" && break
+done
+
+if [ -n "$self_dir" ]; then
+    self_files=$(find "$self_dir" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    has_identity=false; [ -f "$self_dir/identity.md" ] && has_identity=true
+    has_methodology=false; [ -f "$self_dir/methodology.md" ] && has_methodology=true
+    has_goals=false; [ -f "$self_dir/goals.md" ] && has_goals=true
+
+    if $has_identity && $has_methodology && $has_goals; then
+        pass "self/ with $self_files files (identity, methodology, goals present)"
+    elif [ "$self_files" -gt 0 ]; then
+        warn "self/ exists with $self_files files but missing some core MOCs"
+    else
+        warn "self/ directory exists but is empty"
+    fi
+else
+    # Self space is configurable — check for ops/ fallback
+    if [ -f "$VAULT/ops/goals.md" ]; then
+        pass "self/ disabled, ops/ fallback in use (ops/goals.md found)"
+    elif [ -d "$VAULT/.claude/memory" ] || [ -f "$VAULT/MEMORY.md" ]; then
+        warn "Memory mechanism found but no dedicated self/ space"
+    else
+        warn "No self/ directory found (configurable — off by default for research vaults)"
+    fi
+fi
+
+# --- Primitive 9: Session rhythm ---
+echo "9. Session rhythm: orient, work, persist"
+has_rhythm=false
+for ctx in "$VAULT/CLAUDE.md" "$VAULT/AGENTS.md" "$VAULT/SOUL.md"; do
+    [ -f "$ctx" ] && grep -qi "orient\|session start\|session end\|persist\|session rhythm" "$ctx" 2>/dev/null && has_rhythm=true
+done
+[ -f "$VAULT/.claude/hooks/session-start.sh" ] && has_rhythm=true
+find "$VAULT" -name "session-orient.sh" -not -path "*/.git/*" 2>/dev/null | grep -q . && has_rhythm=true
+
+if $has_rhythm; then
+    pass "Session rhythm documented or automated"
+else
+    warn "No session rhythm pattern found"
+fi
+
+# --- Primitive 10: Semantic search (CONFIGURABLE) ---
+echo "10. Semantic search capability (configurable)"
+has_search=false
+[ -f "$VAULT/.mcp.json" ] && grep -q "qmd\|search\|embed" "$VAULT/.mcp.json" 2>/dev/null && has_search=true
+command -v qmd &>/dev/null && has_search=true
+for ctx in "$VAULT/CLAUDE.md" "$VAULT/AGENTS.md" "$VAULT/SOUL.md"; do
+    [ -f "$ctx" ] && grep -qi "semantic search\|qmd\|vsearch" "$ctx" 2>/dev/null && has_search=true
+done
+
+if $has_search; then
+    pass "Semantic search capability found"
+else
+    pass "Semantic search not enabled (configurable)"
+fi
+
+# --- Primitive 10A: Filesystem graph database (unique-addresses) ---
+echo "10A. Filesystem graph database (unique-addresses)"
+has_graph_scripts=false
+for d in "ops/scripts/graph" "04_meta/scripts/graph" "scripts/graph"; do
+    [ -d "$VAULT/$d" ] && has_graph_scripts=true && break
+done
+
+if $has_graph_scripts; then
+    pass "Graph analysis scripts directory found"
+else
+    warn "No ops/scripts/graph/ directory detected"
+fi
+
+# --- Primitive 11: Discovery-first quality gate ---
+echo "11. Discovery-first quality gate"
+has_discovery_section=false
+has_discovery_skills=false
+
+# Check context files for Discovery-First section
+for ctx in "$VAULT/CLAUDE.md" "$VAULT/AGENTS.md" "$VAULT/SOUL.md"; do
+    [ -f "$ctx" ] && grep -qi "discovery.first" "$ctx" 2>/dev/null && has_discovery_section=true
+done
+
+# Check skills for discovery checks
+skill_dirs=""
+for d in ".claude/skills" "skills"; do
+    [ -d "$VAULT/$d" ] && skill_dirs="$skill_dirs $VAULT/$d"
+done
+if [ -n "$skill_dirs" ]; then
+    for dir in $skill_dirs; do
+        grep -rqi "discovery\|findability" "$dir" 2>/dev/null && has_discovery_skills=true
+    done
+fi
+
+if $has_discovery_section && $has_discovery_skills; then
+    pass "Discovery-first gate in context file and skills"
+elif $has_discovery_section; then
+    warn "Discovery-first in context file but not in skills"
+elif $has_discovery_skills; then
+    warn "Discovery checks in skills but no context file section"
+else
+    warn "No discovery-first quality gate detected"
+fi
+
+# --- Primitive 12: Operational learning loop ---
+echo "12. Operational learning loop"
+has_obs_dir=false
+has_tensions_dir=false
+has_review_trigger=false
+has_rethink=false
+
+# Check for ops/observations/ and ops/tensions/ directories (or common variants)
+for candidate in "ops/observations" "04_meta/logs/observations" "logs/observations" "observations"; do
+    [ -d "$VAULT/$candidate" ] && has_obs_dir=true && break
+done
+for candidate in "ops/tensions" "04_meta/logs/tensions" "logs/tensions" "tensions"; do
+    [ -d "$VAULT/$candidate" ] && has_tensions_dir=true && break
+done
+
+# Check context files for review trigger documentation
+for ctx in "$VAULT/CLAUDE.md" "$VAULT/AGENTS.md" "$VAULT/SOUL.md"; do
+    [ -f "$ctx" ] && grep -qi "rethink\|review\|observations" "$ctx" 2>/dev/null && has_review_trigger=true
+done
+
+# Check for rethink command/skill
+for d in ".claude/skills/rethink" "skills/rethink"; do
+    [ -d "$VAULT/$d" ] && has_rethink=true && break
+done
+# Also check for rethink skill files directly
+find "$VAULT" -path "*/rethink/SKILL.md" -not -path "*/.git/*" 2>/dev/null | grep -q . && has_rethink=true
+find "$VAULT" -path "*/rethink.md" -not -path "*/.git/*" 2>/dev/null | grep -q . && has_rethink=true
+
+checks_passed=0
+$has_obs_dir && checks_passed=$((checks_passed + 1))
+$has_tensions_dir && checks_passed=$((checks_passed + 1))
+$has_review_trigger && checks_passed=$((checks_passed + 1))
+$has_rethink && checks_passed=$((checks_passed + 1))
+
+if [ "$checks_passed" -eq 4 ]; then
+    pass "Operational learning loop: observations, tensions, review trigger, rethink mechanism"
+elif [ "$checks_passed" -ge 2 ]; then
+    details=""
+    $has_obs_dir || details="${details}observations dir, "
+    $has_tensions_dir || details="${details}tensions dir, "
+    $has_review_trigger || details="${details}review trigger, "
+    $has_rethink || details="${details}rethink mechanism, "
+    details=$(echo "$details" | sed 's/, $//')
+    warn "Partial learning loop ($checks_passed/4). Missing: $details"
+else
+    fail "No operational learning loop detected (need observations dir, tensions dir, review trigger, rethink mechanism)"
+fi
+
+# --- Primitive 13: Task stack ---
+echo "13. Task stack"
+has_tasks_md=false
+has_queue_file=false
+
+# Check for ops/tasks.md or common variants
+for candidate in "ops/tasks.md" "04_meta/tasks/tasks.md"; do
+    [ -f "$VAULT/$candidate" ] && has_tasks_md=true && break
+done
+
+# Check for queue file (JSON or YAML)
+for candidate in "ops/queue/queue.json" "ops/queue/queue.yaml" "04_meta/tasks/queue.json" "04_meta/tasks/queue.yaml"; do
+    [ -f "$VAULT/$candidate" ] && has_queue_file=true && break
+done
+
+if $has_tasks_md && $has_queue_file; then
+    pass "Task stack: tasks.md and queue file found"
+elif $has_tasks_md; then
+    warn "tasks.md found but no queue file"
+elif $has_queue_file; then
+    warn "Queue file found but no tasks.md"
+else
+    warn "No task stack detected (ops/tasks.md + queue file)"
+fi
+
+# --- Primitive 14: Methodology folder ---
+echo "14. Methodology folder"
+has_methodology_dir=false
+has_methodology_moc=false
+
+for candidate in "ops/methodology" "04_meta/methodology"; do
+    [ -d "$VAULT/$candidate" ] && has_methodology_dir=true
+    [ -f "$VAULT/$candidate/methodology.md" ] && has_methodology_moc=true
+    $has_methodology_dir && break
+done
+
+if $has_methodology_dir && $has_methodology_moc; then
+    pass "Methodology folder with methodology.md MOC found"
+elif $has_methodology_dir; then
+    warn "ops/methodology/ exists but no methodology.md MOC inside"
+else
+    warn "No ops/methodology/ directory detected"
+fi
+
+# --- Primitive 15: Session capture ---
+echo "15. Session capture"
+has_sessions_dir=false
+
+for candidate in "ops/sessions" "04_meta/sessions" "self/sessions"; do
+    [ -d "$VAULT/$candidate" ] && has_sessions_dir=true && break
+done
+
+if $has_sessions_dir; then
+    pass "Session capture directory found"
+else
+    warn "No ops/sessions/ directory detected"
+fi
+
+# --- Summary ---
+echo ""
+echo "=== Kernel Validation Summary ==="
+echo -e "  ${GREEN}PASS:${NC} $PASS"
+echo -e "  ${YELLOW}WARN:${NC} $WARN"
+echo -e "  ${RED}FAIL:${NC} $FAIL"
+echo ""
+
+if [ "$FAIL" -eq 0 ] && [ "$WARN" -eq 0 ]; then
+    echo -e "${GREEN}All 15 primitives validated successfully.${NC}"
+    exit 0
+elif [ "$FAIL" -eq 0 ]; then
+    echo -e "${YELLOW}Kernel present with warnings. $WARN primitive(s) need attention.${NC}"
+    exit 0
+else
+    echo -e "${RED}$FAIL kernel primitive(s) missing. System may not function reliably.${NC}"
+    exit 1
+fi

package/reference/vocabulary-transforms.md

@@ -0,0 +1,85 @@
+# Vocabulary Transformation Reference
+
+When generating a knowledge system for a specific domain, every universal term in the generated context file, templates, skills, and self/ files must use the domain-native equivalent. Vocabulary transformation is not cosmetic — it changes how the system feels to use.
+
+"Surface patterns in reflections" is therapy work. "Extract claims from sources" is research work. Same structural operation, different cognitive framing.
+
+---
+
+## Universal → Domain Mapping
+
+| Universal Term | Research | Therapy | Learning | Relationships | Creative | PM | Companion |
+|---------------|----------|---------|----------|---------------|----------|-----|-----------|
+| note | claim | reflection | concept note | observation | idea | decision | memory |
+| extract / reduce | reduce | surface | break down | notice | discover | document | remember |
+| connect / reflect | reflect | find patterns | relate concepts | trace connections | combine ideas | link decisions | recall together |
+| verify | verify | check resonance | test understanding | confirm accuracy | evaluate draft | review quality | verify memory |
+| MOC | topic map | theme | study guide | relationship map | project hub | decision register | memory collection |
+| description field | claim context | reflection summary | concept explanation | observation context | idea sketch | decision rationale | memory context |
+| topics footer | research areas | themes | study areas | relationship facets | creative projects | project areas | life areas |
+| inbox | capture | journaling | study notes | encounters | inspiration | action items | moments |
+| processing / pipeline | pipeline | reflection cycle | study cycle | relationship review | creative process | review cycle | reminiscence |
+| wiki link | connection | pattern link | concept link | connection | inspiration thread | decision trail | memory link |
+| thinking notes | claims | reflections | concepts | observations | ideas | decisions | memories |
+| archive | processed sources | past reflections | mastered material | past encounters | completed works | closed decisions | past events |
+| self/ space | research identity | reflection partner | study companion | relationship tracker | creative identity | project mind | companion memory |
+| orient | orient | center | review progress | check in | survey ideas | status check | remember |
+| persist | persist | journal | log progress | update records | save state | update status | save memories |
+
+---
+
+## Template Name Mapping
+
+| Universal Template | Research | Therapy | Learning | Relationships | Creative | PM | Companion |
+|-------------------|----------|---------|----------|---------------|----------|-----|-----------|
+| base-note.md | thinking-note.md | reflection-note.md | concept-note.md | observation-note.md | idea-note.md | decision-note.md | memory-note.md |
+| moc.md | topic-map.md | theme.md | study-guide.md | relationship-map.md | project-hub.md | decision-register.md | collection.md |
+
+---
+
+## Folder Name Mapping
+
+| Universal Folder | Research | Therapy | Learning | Relationships | Creative | PM | Companion |
+|-----------------|----------|---------|----------|---------------|----------|-----|-----------|
+| notes/ | notes/ | reflections/ | concepts/ | observations/ | ideas/ | decisions/ | memories/ |
+| inbox/ | inbox/ | journal/ | study-inbox/ | encounters/ | inspiration/ | action-items/ | moments/ |
+| archive/ | archive/ | past/ | mastered/ | history/ | completed/ | closed/ | past/ |
+| templates/ | templates/ | templates/ | templates/ | templates/ | templates/ | templates/ | templates/ |
+
+---
+
+## Skill Name Mapping
+
+| Universal Skill | Research | Therapy | Learning | Relationships | Creative | PM | Companion |
+|----------------|----------|---------|----------|---------------|----------|-----|-----------|
+| /reduce | /reduce | /surface | /break-down | /notice | /discover | /document | /capture |
+| /reflect | /reflect | /find-patterns | /relate | /trace | /combine | /link | /recall |
+| /verify | /verify | /check-resonance | /test | /confirm | /evaluate | /review | /verify |
+| /reweave | /reweave | /revisit | /revise | /reconnect | /rework | /update | /revisit |
+| /remember | /remember | /note-friction | /flag | /flag | /flag | /flag | /remember |
+| /next | /next | /next | /next | /next | /next | /next | /next |
+| /stats | /stats | /stats | /stats | /stats | /stats | /stats | /stats |
+| /graph | /graph | /graph | /graph | /graph | /graph | /graph | /graph |
+
+**Note:** /remember (formerly /friction) captures operational friction with automatic detection in session transcripts. /next (formerly /work + /next) surfaces the next recommended action from the task stack. /stats provides vault metrics and progress visualization. /graph enables graph query generation. These commands use universal names across all domains.
+
+---
+
+## Applying Transformations
+
+### In the init wizard (Step 5b):
+
+1. Determine the user's use case
+2. Look up all universal terms in the mapping table above
+3. Replace every instance in the generated context file
+4. Replace template names and folder names
+5. Replace skill names if generating skills
+6. **Verify:** Read the generated output. Does it feel natural for the domain? Would a therapy user ever see the word "claim"? Would a PM user see "reduce"?
+
+### Quality check:
+
+The vocabulary test: read the generated context file as if you were the domain user. Every technical term should feel native to the domain. If any term feels imported from a different discipline, transform it.
+
+### Extending the table:
+
+For "Custom / Mixed" use cases, the init wizard should ask the user for their preferred vocabulary. Populate a custom column using the universal terms as prompts: "What do you call a single knowledge unit?" → their answer becomes the "note" equivalent.

package/scripts/sync-thinking.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+#
+# sync-thinking.sh
+# Syncs the research graph from the vault into the bundled thinking/ directory.
+# Tracks added/removed/changed files and records the vault's git hash.
+#
+# Usage:
+#   ./scripts/sync-thinking.sh                      # uses default vault path
+#   VAULT_PATH=/path/to/vault ./scripts/sync-thinking.sh  # custom vault path
+#   ./scripts/sync-thinking.sh --dry-run             # preview changes without copying
+
+set -euo pipefail
+
+# --- Configuration ---
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+VAULT_PATH="${VAULT_PATH:-/Users/jozark/Documents/cornelius/workspace/vault}"
+SOURCE_DIR="$VAULT_PATH/01_thinking"
+DEST_DIR="$PROJECT_ROOT/thinking"
+HASH_FILE="$PROJECT_ROOT/thinking/.vault-sync-hash"
+DRY_RUN=false
+
+if [[ "${1:-}" == "--dry-run" ]]; then
+  DRY_RUN=true
+  echo "=== DRY RUN — no files will be modified ==="
+  echo ""
+fi
+
+# --- Validate source ---
+if [[ ! -d "$SOURCE_DIR" ]]; then
+  echo "ERROR: Source directory not found: $SOURCE_DIR"
+  echo "Set VAULT_PATH to the vault root directory."
+  exit 1
+fi
+
+# --- Ensure destination exists ---
+if [[ "$DRY_RUN" == false ]]; then
+  mkdir -p "$DEST_DIR"
+fi
+
+# --- Get vault git hash ---
+VAULT_HASH="(not a git repo)"
+if git -C "$VAULT_PATH" rev-parse --git-dir &>/dev/null; then
+  VAULT_HASH=$(git -C "$VAULT_PATH" rev-parse --short HEAD)
+  VAULT_DIRTY=""
+  if ! git -C "$VAULT_PATH" diff --quiet 2>/dev/null; then
+    VAULT_DIRTY="-dirty"
+  fi
+  VAULT_HASH="${VAULT_HASH}${VAULT_DIRTY}"
+fi
+
+# --- Previous hash ---
+PREV_HASH="(none)"
+if [[ -f "$HASH_FILE" ]]; then
+  PREV_HASH=$(cat "$HASH_FILE")
+fi
+
+# --- Diff: find added, removed, changed ---
+# Build file lists (basenames only)
+SOURCE_FILES=$(ls -1 "$SOURCE_DIR"/*.md 2>/dev/null | xargs -I{} basename {} | sort)
+DEST_FILES=$(ls -1 "$DEST_DIR"/*.md 2>/dev/null | xargs -I{} basename {} | sort)
+
+ADDED=$(comm -23 <(echo "$SOURCE_FILES") <(echo "$DEST_FILES"))
+REMOVED=$(comm -13 <(echo "$SOURCE_FILES") <(echo "$DEST_FILES"))
+COMMON=$(comm -12 <(echo "$SOURCE_FILES") <(echo "$DEST_FILES"))
+
+# Check which common files have changed
+CHANGED=""
+CHANGED_COUNT=0
+while IFS= read -r file; do
+  [[ -z "$file" ]] && continue
+  if ! diff -q "$SOURCE_DIR/$file" "$DEST_DIR/$file" &>/dev/null; then
+    CHANGED="${CHANGED}${file}"$'\n'
+    ((CHANGED_COUNT++))
+  fi
+done <<< "$COMMON"
+
+if [[ -z "$ADDED" ]]; then
+  ADDED_COUNT=0
+else
+  ADDED_COUNT=$(echo "$ADDED" | wc -l | tr -d ' ')
+fi
+
+if [[ -z "$REMOVED" ]]; then
+  REMOVED_COUNT=0
+else
+  REMOVED_COUNT=$(echo "$REMOVED" | wc -l | tr -d ' ')
+fi
+
+# --- Report ---
+echo "Sync: vault/01_thinking/ -> thinking/"
+echo "Vault hash: $VAULT_HASH (previous: $PREV_HASH)"
+echo ""
+SOURCE_COUNT=$(echo "$SOURCE_FILES" | wc -l | tr -d ' ')
+DEST_COUNT=$(echo "$DEST_FILES" | wc -l | tr -d ' ')
+echo "Source files:  $SOURCE_COUNT"
+echo "Dest files:    $DEST_COUNT"
+echo ""
+
+if [[ "$ADDED_COUNT" -gt 0 ]]; then
+  echo "ADDED ($ADDED_COUNT):"
+  echo "$ADDED" | sed 's/^/  + /'
+  echo ""
+fi
+
+if [[ "$REMOVED_COUNT" -gt 0 ]]; then
+  echo "REMOVED ($REMOVED_COUNT):"
+  echo "$REMOVED" | sed 's/^/  - /'
+  echo ""
+fi
+
+if [[ "$CHANGED_COUNT" -gt 0 ]]; then
+  echo "CHANGED ($CHANGED_COUNT):"
+  echo "$CHANGED" | grep -v '^$' | sed 's/^/  ~ /'
+  echo ""
+fi
+
+TOTAL_CHANGES=$((ADDED_COUNT + REMOVED_COUNT + CHANGED_COUNT))
+if [[ "$TOTAL_CHANGES" -eq 0 ]]; then
+  echo "No changes detected. Already in sync."
+  exit 0
+fi
+
+echo "Total changes: $TOTAL_CHANGES"
+echo ""
+
+# --- Apply changes ---
+if [[ "$DRY_RUN" == true ]]; then
+  echo "Dry run complete. Re-run without --dry-run to apply."
+  exit 0
+fi
+
+# Copy all source files (overwrites changed, adds new)
+cp "$SOURCE_DIR"/*.md "$DEST_DIR/"
+
+# Remove files that no longer exist in source
+while IFS= read -r file; do
+  [[ -z "$file" ]] && continue
+  rm "$DEST_DIR/$file"
+  echo "Removed: $file"
+done <<< "$REMOVED"
+
+# Record vault hash
+echo "$VAULT_HASH" > "$HASH_FILE"
+
+FINAL_COUNT=$(ls -1 "$DEST_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Sync complete. $FINAL_COUNT files in thinking/. Vault hash: $VAULT_HASH"