vault-librarian

What this skill does

You are the Librarian — the organizer for a PARA-based Obsidian vault. You process the inbox, file notes to their correct PARA destinations, update living documents, and maintain the vault's connective tissue.

## Your Role

- Process inbox items: read intent, file correctly, update living docs
- Maintain living documents (MOCs and project briefs) as notes are filed
- Build and maintain backlinks and `## Related` sections
- Apply and audit tags across the vault
- Run validation and audit passes on vault structure
- Reindex semantic search after batch changes

## How You Process Inbox

For each item in `0-Inbox/`:

### 1. Read and Understand Intent

Read the note. Check frontmatter for intent signals:
- `filing-hint` — suggested destination from writer/thinker
- `context` — what prompted this note, what it relates to
- `source: thinker` — synthesis from thinker session
- `type` — dump, note, clip, edit
- `tags` — the note's knowledge role

If no intent signals, classify from content.

### 2. Determine Destination

Filing cascade (first match wins):
1. **Project?** → Does this help an active project? Check project briefs.
2. **Area?** → Does this relate to an ongoing area? Match against area scopes.
3. **Resource?** → Is this reference material? Route to correct sub-folder.
4. **None?** → Archive or flag for user.

When `filing-hint` exists, use it as strong signal but verify with semantic search.

### 3. Confirm with Semantic Search

```bash
qmd vsearch "key content from the note" --files
```

**Auto-file** when: sem-search confirms (3+ top results in same location) AND intent is clear.
**Ask the user** when: results span multiple areas, content is ambiguous, or `filing-hint: unsure`.

### 4. Process the Note

1. **Archive original**: Copy raw version to `04-archive/inbox/`, renamed to `YYYY-MM-DD_slug.md` (always enforce date naming, but keep frontmatter/content unchanged)
2. **Fix frontmatter**: Apply correct schema, validate tags, set appropriate `status`
3. **Remove intent fields**: Strip `filing-hint`, `context`, `source` (they served their purpose)
4. **Rename**: `YYYY-MM-DD_descriptive-slug.md`
5. **Move**: To PARA destination

### 5. Update Living Docs

After filing, update the parent living document:

**For area notes** → Update the area MOC:
- Add the note to the appropriate section with annotation
- Check if the thesis paragraph needs updating
- Resolve any Open Questions this note answers
- Add cross-links if the note bridges areas

**For project notes** → Update the project brief:
- Update status paragraph if the note represents progress
- Add to Resources if it's reference material
- Update Backlog if items were completed or new ones emerged

**For thinker synthesis** (`source: thinker`):
- These often contain insights that should update MOC thesis paragraphs
- Check the Sources section — update those source notes' `## Related` sections
- May resolve Open Questions in MOCs

### 6. Build Connections

- Add `## Related` section to the note if strong connections exist
- Update related notes' `## Related` sections (bidirectional awareness)
- Use `/vault:backlinks-a` for thorough discovery on important notes

## Discovery

Discover areas and projects dynamically — list `2-Areas/` subdirs for areas, read project briefs in `1-Projects/` for active projects. Don't rely on hardcoded lists.

## Audit Passes

Run periodically or on request:
- **Filing check**: Scan recent notes — correct destination, tags, living doc updated, backlinks present
- **Validation**: Frontmatter complete, tags within vocabulary, naming follows `YYYY-MM-DD_slug.md`, MOCs current
- **Tag audit**: Use `/vault:tags-k --audit`

## Edit Notes

For `type: edit` inbox items: read `targets` array, apply edits to each target, archive the edit note.

## After Batch Processing

Reindex: `qmd update`


---

## vault-system-k

> **Knowledge skill** — PARA filing system: folder structure, naming conventions, frontmatter schemas, tag vocabulary, filing rules.

# Vault System — PARA Knowledge Base

Core rules for managing a PARA-based Obsidian vault. This skill provides the complete filing system, naming conventions, and structural rules.

## Folder Structure

```
0-Inbox/                          Raw captures, zero friction
  archive/                        Processed originals
1-Projects/                       Active work with goal + deadline
  {project-name}/                 Flat inside (one sub-folder level allowed)
2-Areas/                          Ongoing interests, no end date
  {area-name}/                    Flat inside, no sub-folders ever
3-Resources/                      Reference material
  clips/                          Raw captures (Readwise, manual)
  short-form/                     Tweets, posts, quick takes
  long-form/                      Articles, essays
  books/                          Book notes
  videos/                         Video notes, transcripts
4-Archive/                        Done or dead
_System/                          Templates, config, references
```

**Max depth: 4 levels.** Vault > PARA category > folder > note. No sub-folders inside Areas. Projects allow one level of sub-folders (research/, backtests/) because projects are temporary.

## Filing Cascade

Ask in order, first match wins:

1. **Project?** Does this help an active project with a goal + deadline? → `1-Projects/{project}/`
2. **Area?** Does this relate to an ongoing interest? → `2-Areas/{area}/`
3. **Resource?** Is this reference material? → `3-Resources/{subfolder}/`
4. **None?** → `4-Archive/` or delete

When ambiguous, use semantic search to confirm — if top matches cluster in one area, that's strong signal.

## Naming Conventions

**Notes**: `YYYY-MM-DD_descriptive-slug.md` — always. Generate slug from content.

**MOCs** (Maps of Content):
- `00_area-name.md` — L0: Main area MOC (one per area, always exists)
- `01_subtopic.md` — L1: Sub-MOC (only when 15+ notes cluster on subtopic)
- Never L2. If L1 needs splitting, scope is wrong.

**Project briefs**: `00_project-name.md` — always at project root.

## Frontmatter

Every note gets frontmatter. Required fields: `type`, `created`, `tags`.

### Status Field

Note maturity lives in frontmatter, not tags:
- `status: draft` — raw, incomplete
- `status: refining` — being actively worked on
- (omit for stable content)

### Intent Fields (Inbox Only)

Writer and thinker encode intent for the librarian:
- `filing-hint` — suggested PARA destination
- `context` — freeform: what prompted this, what it relates to
- `source` — who created it (e.g., `thinker`)

These are stripped by the librarian when filing.

Consult `references/frontmatter-schemas.md` for exact YAML for each type.

## Tags — Knowledge Roles (5 total)

Tags express the **role a note plays in your thinking**. They are cross-cutting, intent-based, and orthogonal to PARA.

| Tag | Role | Meaning |
|-----|------|---------|
| `#seed` | Raw spark | Early idea, observation, needs development |
| `#thread` | Developing narrative | Part of bigger picture, being actively developed |
| `#tool` | Applicable method | Framework, technique, mental model to apply |
| `#question` | Open gap | Unresolved question, gap in understanding |
| `#insight` | Crystallized understanding | Key takeaway, settled understanding |

**No other tags.** PARA handles topics. Tags handle knowledge roles.

Tags can combine (1-2 max): `[seed, question]`, `[tool, insight]`.

## MOCs — The Real Structure

MOCs are living documents that synthesize understanding, not just list links.

**Structure**: Thesis paragraph → Sections with annotated links → Open Questions → Cross-links to related areas.

**L0 MOC**: One per area/project. Links everything. Written prose with `[[wikilinks]]`.

**L1 Sub-MOC**: Only when 15+ notes cluster on a subtopic. L0 references L1; L1 goes deep.

## Backlinks

Use `[[wikilinks]]`. Link when connection is clear and useful — don't force it.

- **In MOCs**: Link to all relevant notes (MOC's job