Organize learning state as a loosely-linked Obsidian vault (journal + mental-model map + gotchas)

[ktaletsk]

Proposal

Evolve the single learning-journal.md into a loosely-linked Obsidian vault of learning state, stored at a configurable vault root. This captures the Obsidian knowledge-base crowd and matches the durable-artifact strength of bevibing/tutor-skills (935★), which is the popularity leader in the tutor space largely because it produces something you can keep and browse.

Depends on / extends #2 — the global store decided there becomes the default vault root, and the repo-key scheme is shared.

Structure

The vault root is a single Obsidian vault; each project is a folder inside it keyed by repo identity:

<vault-root>/
  [learn-codebase/]            # subfolder used only when vault-root is a user's EXISTING vault
    <repo-key>/
      index.md                 # MOC: links the notes below, landing page
      journal.md               # learner's progress: mastery map, review queue, session log
      map.md                   # mental model of the repo, in the learner's own words
      gotchas.md               # footguns, surprising couplings, tribal knowledge

• <vault-root> is configurable; default is the global store from Move learning journal out of .claude/ to a durable, agent-neutral global store #2: ~/.local/share/learn-codebase/ (honoring $XDG_DATA_HOME).
• <repo-key> uses the same scheme as Move learning journal out of .claude/ to a durable, agent-neutral global store #2 (git remote, normalized; toplevel path fallback).
• When the user points the vault root at their own existing Obsidian vault, we write under a learn-codebase/ subfolder (configurable) to avoid polluting their vault root. Writing into a user's real vault should be confirmed on first use (higher trust than writing to ~/.local/share).

Why this works

• Single vault, repos as folders → cross-repo graph view for free. Most of the "central dashboard" idea (Organize learning state as a loosely-linked Obsidian vault (journal + mental-model map + gotchas) #3) falls out of Obsidian's native graph, no build required.
• Captures the Obsidian crowd — a large, dedicated knowledge-base audience the tutor skills compete for.
• Matches tutor-skills' biggest feature (durable, visible artifact) while keeping our codebase-native focus and anti-vibe framing.

Obsidian-native details that matter

These are what make it a vault rather than markdown in folders:

• Wiki-links between notes. journal.md, map.md, gotchas.md, and concepts within them link with [[ ]]. The mental-model map and gotchas should cross-reference shared concepts.
• Frontmatter / tags for Dataview. Put mastery level, dates, and a #learn-codebase tag in YAML frontmatter. Payoff: a "concepts due for review across all repos" or mastery-rollup dashboard becomes a Dataview query, not a feature we build (directly advances Organize learning state as a loosely-linked Obsidian vault (journal + mental-model map + gotchas) #3).
• MOC index per repo (index.md) as the idiomatic entry point.
• Don't manage .obsidian/ — Obsidian creates it on first open of the default dir; an existing vault already has one.

Config file

Add a lightweight config at ~/.local/share/learn-codebase/config.yaml (created on demand), to hold the vault location when non-standard and future settings:

# all fields optional; sensible defaults when absent
vault_root: /Users/me/Documents/ObsidianVault   # default: ~/.local/share/learn-codebase
vault_subfolder: learn-codebase                  # used when vault_root is a pre-existing vault
# future: review scheduling prefs, per-repo path overrides, in-repo opt-in (#2), Anki export, etc.

Relationship to #2

• Move learning journal out of .claude/ to a durable, agent-neutral global store #2 keeps ownership of: repo-key normalization scheme, migration mechanics, durability rationale.
• This issue owns: multi-file vault layout, config file, Obsidian-native conventions.
• The migration prompt from Move learning journal out of .claude/ to a durable, agent-neutral global store #2's discussion needs to move/relocate a folder of notes (and respect vault_root), not a single file.

Open questions

• Config format — YAML (proposed) vs. JSON/TOML. YAML is friendliest to hand-edit.
• Existing-vault detection — auto-detect a .obsidian/ dir at vault_root to decide whether to apply the learn-codebase/ subfolder, or always require explicit config?
• Note granularity — start with the 3 notes + index, or allow the map/gotchas to split into multiple linked notes as a repo grows (closer to tutor-skills' per-module notes)?
• Frontmatter schema — define the property names now so a future Dataview dashboard is stable (e.g. mastery: red|yellow|green, review_due: YYYY-MM-DD).
• Relocation UX — when a user later sets a vault_root, do we move the existing default-store contents there automatically, or leave both and prefer config going forward?