Format Vault

House-style formatter for this repo’s Obsidian vault (obsidian/) and its two index files. Three jobs:

Format a note — apply the house style and colored highlights to a .md note.
Sync obsidian/MOC.md — the per-note vault index, kept current as notes are added/renamed/moved.
Sync root README.md — the repo overview, kept current at the topic/folder level.

⛔ Cardinal rule: format, never rewrite

When formatting, change only presentation — structure, headings, callouts, tags, highlights, whitespace, link syntax. Never change the substance:

Do not reword, paraphrase, expand, condense, or “improve” sentences.
Do not translate. Ukrainian notes stay Ukrainian; English notes stay English.
Do not add, remove, or reorder facts, list items, or sections.
Do not fix perceived technical errors silently.

If you believe the content itself should change, stop and ask first, or do it only when the user explicitly requests a content edit. A formatting pass must be safe to accept blind.

After a format pass, a git diff should show only markup changes — the prose words on each line must be identical.

Scope — what this skill touches

In scope: hand-written notes under obsidian/ (configs/, certifications/, studying/), plus obsidian/MOC.md and root README.md.
Leave alone: plugin-generated files — obsidian/studying/vocabulary/*.md (Vocab Collector output, its own schema), anything under .obsidian/, embedded PDFs/images, and vscode/plugins/harp/**.

Before you edit anything

Read the relevant reference file first — they hold the exact patterns, palettes, and worked examples:

Formatting a note → read house-style.md
Updating the MOC → read update-moc.md
Updating the README → read update-readme.md

Then read the target note(s) in full before changing them.

Note anatomy (quick reference)

Every note follows this shape (full detail in house-style.md):

tags: #topic #subtopic #key-term
 
> [!abstract] Contents
> 
>
> - [[#First section]]
> - [[#Second section]]
 
---
 
## First section
 
Body text with a <mark style="background: #FFF3A3A6;">key term</mark> highlighted.
 
## Second section
 
...

Rules:

Line 1 is the tags line — literal tags: then space-separated #kebab-case inline tags. Not YAML frontmatter.
One blank line, then an opener callout: > [!abstract] Contents (a [[#heading]] TOC) for multi-section notes, or > [!abstract] Goal / > [!info]- … for guides/runbooks. Optional extra > [!info]- Official docs etc.
--- then the body.
Sections are ## (H2); subsections ### (H3). Never use # (H1) inside a note.
Images: ![[name|width]]. Use callouts (> [!important], > [!info]-) and tables where they already fit the content.

Highlight colors (quick reference)

Highlight genuine key theses only — roughly the term being defined per paragraph/section, not whole sentences. Use Obsidian’s native palette via <mark style="background: <hex>;">…</mark>.

Core rule: one color = one concept group. Terms that belong together (a term + its definition, synonyms, items of the same category) share a color. Unrelated concepts get different colors. Contrasting pairs use intuitive opposites (green ↔ red).

Role	Color	Hex
Primary term being defined	yellow	`#FFF3A3A6`
Related / secondary concept	blue	`#ADCCFFA6`
Pros / benefits / recommended	green	`#BBFABBA6`
Cons / risks / warnings / deprecated	red	`#FF5582A6`
Protocol / standard / technology	purple	`#D2B3FFA6`
Values / numbers / ranges (ports, sizes, IPs)	cyan	`#ABF7F7A6`
Commands / actions / steps	orange	`#FFB86CA6`
Contrasting alternative to the primary	pink	`#FFB8EBA6`

Keep to ~2–4 colors per note unless the content truly spans more distinct groups. The legacy single-yellow notes are fine to recolor by role during a format pass. See house-style.md for examples.

Tags (quick reference)

Add a few precise #kebab-case tags to the line-1 tags: line: topic + key concepts of the note.
Reuse existing tag names wherever possible so colors stay consistent — check the known set with: python3 -c "import json;print(' '.join(sorted(json.load(open('obsidian/.obsidian/plugins/colored-tags/data.json'))['knownTags'])))"
The colored-tags plugin assigns colors automatically. Do not edit obsidian/.obsidian/plugins/colored-tags/data.json.

Keeping the indexes in sync

Granularity differs — get this right:

obsidian/MOC.md is per-note. Every note appears as a link line (with a short CODE mnemonic) under its topic’s [!info]- callout, plus a one-paragraph entry in that topic’s [!summary]- callout. New note → add both. See update-moc.md.
Root README.md is per-topic / per-folder. It lists topics and folder counts, not individual notes. A new note usually only nudges a count or description; a new topic folder adds a table row; a new top-level area adds a section. Also keep the ## Structure ASCII tree current. See update-readme.md.

When asked to “format X”, default to also offering to sync MOC + README if X is a new or renamed note.

Workflow

Identify the task (format note / sync MOC / sync README) and read the matching reference file.
Read the target file(s) in full. For index work, also read obsidian/MOC.md / README.md.
Make markup-only edits with Edit (prefer surgical edits over full rewrites so the diff stays reviewable).
Verify against this checklist:
- Prose words unchanged (formatting-only diff); language preserved.
- Line-1 tags line present; tags are #kebab-case, reuse known names.
- Opener callout + --- present; sections are ##/###, no # H1.
- Highlights mark only key theses; one color per concept group; ≤ ~4 colors.
- If a note was added/renamed/moved: MOC link line + summary updated; README topic/tree updated if needed.
- data.json, .obsidian/, and plugin-generated files untouched.
Report what changed in one or two lines.

Reference files

house-style.md — full note anatomy, every callout type, the highlight palette with worked before/after examples, do/don’t.
update-moc.md — obsidian/MOC.md structure and exact insertion patterns for a new note/topic/area.
update-readme.md — root README.md structure and which sections/tables/tree to update.

configs

Explorer