laurigates/vault-mocs

MOC Curation

When to Use This Skill

| Use this skill when... | Use the alternative instead when... | |---|---| | Creating or extending a Map of Content hub for a tag category | Reconnecting individual orphaned notes without building a hub — use vault-orphans | | Migrating legacy 🗺️ MOC tags to canonical 📝/moc | Renaming or consolidating non-MOC tags across the vault — use vault-tags | | Auditing MOC coverage and linking orphans into existing hubs | Repairing broken [[...]] references inside an existing MOC — use vault-wikilinks |

A Map of Content (MOC) is a structured hub note that organizes related content via wikilinks. It's the primary navigation surface of a mature Obsidian vault — more useful than tags, more discoverable than search.

Canonical MOC Shape

---
tags: [📝/moc]
---

# Neovim MOC

Central hub for Neovim configuration, plugins, and workflows.

## Core

- [[Neovim]] — base configuration
- [[Lazy.nvim]] — plugin management

## Plugins

- [[nvim-treesitter]]
- [[Mason LSP]]

## Keybindings and Workflow

- [[Neovim Keybindings]]
- [[Neovim Session Management]]

Rules:

1. Tag is exactly 📝/moc — not 🗺️ (legacy), not MOC (flat), not 📝/MOC (wrong case).
2. File lives in Zettelkasten/ (personal) or work/MOC/ (work).
3. Filename is {Subject} MOC.md — suffix, not prefix.
4. Body has a one-paragraph description, then ## section headings, then bullet-list wikilinks.
5. Never has id: or other legacy frontmatter.

Legacy MOC Fixups

| Issue | Fix | |-------|-----| | tags: 🗺️ | Rewrite to tags: [📝/moc] | | tags: [🗺, 📝/moc] | Deduplicate to tags: [📝/moc] | | MOC in work/z/ instead of work/MOC/ | Move file | | Uses [[Kanban/Foo]] path-qualified links | Rewrite to [[Foo]] when basename unique |

Coverage Analysis

For each tag category (🛠️/, 🔌/, 💻/, etc.), the vault-agent mocs.analyze_mocs analyzer reports how many tagged notes are NOT linked from any MOC. High uncovered counts indicate:

• Missing MOC — the category has 10+ notes but no MOC exists.
• Stale MOC — the MOC exists but hasn't been updated with recent additions.
• Tag mismatch — notes are tagged but don't belong in the relevant MOC.

Offline Fallback (App Closed)

The detection methodology above is unchanged — only the data source changes when Obsidian (and its obsidian CLI / live link index) is closed. The obsidian CLI and vault-agent analyzers are the live-index path; parsing the .md corpus directly with Glob/Grep is the deterministic headless default, and for batch/scheduled audits it is often the better choice (reproducible, free of app/index state). vault-frontmatter already operates this way.

Parse the corpus directly:

• Frontmatter — read each note's YAML block between the leading --- fences; extract tags, aliases, context. See vault-frontmatter for YAML-block mechanics.
• Wikilinks — match [[Target]], [[Target|Alias]], [[Target#Heading]], [[folder/Target]], and ![[embed]]. Resolve each target to a note by basename, then relative path, then alias (from frontmatter), all case-insensitive. Resolve ![[embed]] against attachments as well as notes — the attachment folder is per-vault configurable, so read it from .obsidian/app.json (attachmentFolderPath) and fall back to the vault root / Files/ only when that key is unset.

Coverage analysis offline: for each tag category, count notes whose parsed frontmatter tags place them in the category but which no 📝/moc-tagged note links to (via the resolution cascade). That is the same uncovered count mocs.analyze_mocs produces from the live index.

Creating a New MOC

Thresholds (heuristic):

• ≥ 10 tagged notes in the category AND
• No existing MOC covers them AND
• Notes share enough subject to belong in one hub

If all three hold, create Zettelkasten/{Category} MOC.md:

---
tags: [📝/moc]
---

# {Category} MOC

{One-paragraph framing of the category.}

## {Section}

- [[Note1]]
- [[Note2]]

Pick 2–4 ## sections that reflect natural groupings within the notes — don't force a deep hierarchy.

Extending an Existing MOC

When the analyzer reports orphaned notes that belong in an existing MOC:

1. Read the MOC and find the most appropriate ## section (or create a new one if 3+ notes fit a new grouping).
2. Add wikilinks one per bullet, alphabetical within the section.
3. Keep descriptions brief — one short phrase per link at most.

Don't add a "See also" or "Random" section as a dumping ground. If a note doesn't fit any section, reconsider whether it belongs in this MOC at all.

Never Do

• Don't create nested MOCs (MOC of MOCs) unless the vault has 20+ MOCs that justify a top-level index.
• Don't dataview-generate MOC content in place of hand-curated links. Dataview is fine for supplementary sections ("Recent notes in this category"), but the primary content should be hand-picked.
• Don't add the 📝/moc tag to a note that isn't actually a MOC — it pollutes MOC inventories.
• Don't rename existing MOCs without updating every link (use vault-wikilinks rewrite patterns).

Commit Messages

| Action | Commit | |--------|--------| | New MOC | feat(mocs): add {Category} MOC covering N notes | | Fixup tag | fix(mocs): 🗺️ → 📝/moc on work MOCs | | Add orphans | feat(mocs): link 12 notes into Neovim MOC | | Rewrite path-qualified link | fix(mocs): unqualify [[Kanban/X]] → [[X]] across 6 MOCs |

Safety

• Never modify a MOC's section structure without the user's input — they reflect the user's mental model.
• When adding links, preserve the user's existing sort order (alphabetical, chronological, by-importance — look at the first section to infer).
• Don't link notes that are tagged but clearly off-topic for the MOC.

Related Skills

• vault-orphans — identifies candidate notes to add to MOCs
• vault-tags — tag taxonomy that drives coverage analysis
• vault-wikilinks — link syntax and safe-rewrite rules