concept-hub

Create / update a concept hub

Concept hubs are the relational junctions of the vault: a short note per cross-cutting idea that collects, via Backlinks, every lecture note that touches it. The contract is notes/_meta/SCHEMA.md §2.3 and §4 — read it first. _concepts/merge.md is the template to copy.

When a concept deserves a hub

Create a hub when an idea is cross-cutting — referenced by two or more notes, ideally across topics. A term used in a single note does not need a hub (put it in that note's concepts: list instead). Prefer a small set of high-traffic hubs over many sparse ones. The obsidian-vault-kit checker's "hub-gap candidates" warnings are good signal: a concept spanning ≥2 topics with no hub is a prime candidate — but you still decide whether it earns one.

Procedure

1. Pick the slug and title

• Slug: lower-kebab-case, a concept noun — property-graph, merge, constraints. Not a phrase (how-merge-avoids-duplicates) and not a sentence.
• Check _concepts/ for an existing hub (including near-synonyms) before creating a duplicate. If one exists, update it instead.
• title: the human form ("MERGE", "Property Graph Model"). Add aliases: for alternate surface forms readers might search or autolink (e.g. upsert for merge).

2. Create the hub file

Write _concepts/<slug>.md with the concept frontmatter from SCHEMA.md §2.3 (type: concept, title, status, optional aliases, appears_in, related, tags: [status/published, kind/concept]).

Body — keep it short (a junction, not a lecture):

• A blockquoted definition (one Cypher snippet or one sentence).
• A Why It Matters paragraph: what work this concept does in the course.
• A See Also / Compare With list linking [[related]] sibling hubs.

3. Populate appears_in

List every note that meaningfully uses the concept, as note-folder wikilinks. Find them by searching the lecture notes for the term and its aliases. This is the curated inverse of the per-note concepts: field — keep the two consistent.

4. Layer the prose wikilinks (the back-link source)

In each appears_in note, add one [[slug|alias]] at the first meaningful mention (SCHEMA.md §4): pipe alias for natural reading, one per note, keep existing markdown links, and never self-link (the note that defines the concept does not link the hub). These prose links are what populate the hub's Backlinks panel.

5. Wire related bidirectionally

If this hub lists [[other-hub]] in related:, add this hub to that other hub's related: too, so the concept graph is symmetric.

6. Verify

Run the deterministic checker and confirm your hub introduced no new findings:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-vault.sh <project-dir>

Specifically: the hub's appears_in notes should each show a resolving backlink (no new "appears_in backlink gap" WARN), and there should be no new dangling wikilinks. Then report: hub created/updated, N source notes linked, M reciprocal related edits.

Normalizing an existing (deviant) hub

When fixing a hub that was created off-spec (see SCHEMA.md §7): rename the file to a concept-noun slug if needed (update any inbound links), bring frontmatter to §2.3, rebuild appears_in from an actual search, add the prose wikilinks that were missing, and make related reciprocal. Confirm with the user before deleting a hub outright.

Out of scope

• Full per-topic integration (use the obsidianize-module skill).
• Changing the schema itself (edit _meta/SCHEMA.md deliberately, then migrate).