build-MOC

When to use

The user wants a navigation hub for a topic. MOCs are the LYT central primitive; they replace folders for many vaults. Default output is static wikilinks (round-trip safe under git); the user can opt into Dataview style.

Procedure

1. Capture the topic phrase from the user (e.g. "RAG research"). If absent, ask.
2. Call find_related(seed=topic_phrase, top_k=30). These are the candidate notes.
3. Optionally call find_orphans(near_topic=topic_phrase) and merge results — orphans near the topic almost always belong in the MOC.
4. Call read_notes_batch(paths=[top 10 candidates]) to get headings and lead paragraphs for clustering.
5. Cluster the candidates into 2–5 sub-themes. Use the notes' headings, primary tags, and lead paragraphs as features. Name each sub-theme with a short imperative phrase.
6. Surface the proposed MOC structure to the user IN CHAT (sub-themes + notes that would fall under each). Wait for approval; the user may want to drop notes, add notes, or rename a sub-theme.
7. Call build_moc(title=topic_phrase, notes=approved_paths, structure="grouped", style="wikilinks", confirm=true). Default out path is MOCs/<title>.md; user may override.
8. Reply with the path and a 2-sentence top-line. Suggest the user link the MOC from their Home.md or top-level index (one suggestion, not a demand).

Output format (the MOC body itself)

# {Topic}

> MOC for: {topic phrase}
> Generated: {YYYY-MM-DD}

## {Sub-theme 1}
- [[Note A]]
- [[Note B]]

## {Sub-theme 2}
- [[Note C]]
- [[Note D]]

## Related MOCs
- [[Related MOC]]

## Open questions
-

Anti-patterns

• Don't auto-include every candidate. Cap at ~20 notes. A MOC with 60 entries is a search result, not a map.
• Don't use Dataview by default. Static wikilinks are round-trip safe and don't require a plugin. Use style="dataview" only when the user asks.
• Don't make the MOC encyclopedic. Headings should be imperative ("Use cross-encoders for reranking") not nominal ("Cross-encoders").
• Don't link orphans into the MOC without the user's explicit OK, even if find_orphans returned them. Orphan triage is the user's call.
• Don't write the MOC over an existing one without overwrite=True from the user.