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

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

Read the MOC and find the most appropriate ## section (or create a new one if 3+ notes fit a new grouping).
Add wikilinks one per bullet, alphabetical within the section.
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