Vault Conventions

Universal conventions for all notes in this vault. One-stop reference for naming, frontmatter, note types, hub notes, and tag vocabulary. Project-specific rules live in project-config-* notes.

This vault stores durable, evergreen knowledge — finished plans, decisions, research, how-tos, and project learnings. It is NOT working memory. Working notes that don't yet have a permanent home should not be archived here until they have something stable to say.

I want to...	Do this
Know the note types	See Note Types below
Look up valid tag facets	See Tag Taxonomy below
Know file naming rules	See File Naming below
Understand hub notes	See Hub Notes below
Find project-specific context	Read the relevant `project-config-*` note

File Naming

YYYY-MM-DD-descriptive-slug.md

Date is creation date
Slug is lowercase kebab-case
Source platform suffix when applicable: -chatgpt, -gemini, -claude
Generated by tooling — do not rename manually

Frontmatter Contract

Every note requires these fields. No exceptions; defer writing the summary for nothing.

---
summary: One sentence, human-written at creation. Used by the Graphify graph and SessionStart context injection.
tags:
  - type/reference      # facet-namespaced; type/ listed first; at least one type/ required
  - client/acme         # omit if not client-specific
  - project/website-redesign  # omit if not project-specific
  - domain/seo          # topic area
  - tool/semrush        # tool referenced, if any
  - convention/api-style  # cross-project convention, if applicable
  - scope/global        # or scope/project — always include one
source: <origin: repo name, "web-clipper", "ios-shortcut", "manual", etc.>
date: YYYY-MM-DD
---

summary field rules:

One sentence, written by the human (or agent) at creation time.
Describes what the note is about, not what it contains.
Used by Graphify when building the knowledge graph and by the memory plugin for SessionStart injection.
Never defer it. A placeholder summary defeats the purpose.

Note Types (`type/` facet)

Use exactly one type/ tag per note.

Type tag	Use for
`type/reference`	Reference material: market research, competitive intel, research dumps
`type/plan`	Implementation plans, strategy docs
`type/log`	Session logs, increment logs, decisions
`type/adr`	Architecture decision records
`type/howto`	Process docs, step-by-step guides
`type/hub`	Hub notes: index/navigation notes linking 3+ related notes (see Hub Notes)
`type/clip`	Web clips, saved articles
`type/project-config`	Per-project tag inference rules and conventions
`type/meta`	Vault governance (this file, CLAUDE.md)

Tag Taxonomy

Tags are flat and parallel — no nested paths, no hierarchy inside a facet. Six facets plus scope/:

Facet	Purpose	Example
`type/`	Note type (see table above)	`type/howto`
`client/`	Client or company this pertains to	`client/acme`
`project/`	Specific project or engagement	`project/website-redesign`
`domain/`	Topic area or discipline	`domain/seo`, `domain/cold-email`
`tool/`	Tool, library, or platform referenced	`tool/graphify`, `tool/semrush`
`convention/`	Cross-project convention or pattern	`convention/api-style`
`scope/`	Applicability breadth	`scope/global` or `scope/project`

scope/ values:

scope/global — applies across all work; not tied to a specific client or project
scope/project — specific to one client/project context; pair with client/ or project/

Rules:

Always include type/ and scope/. All other facets are optional.
Use multiple tags within a facet when accurate (e.g., domain/seo and domain/cold-email).
Facets are not nested: domain/cold-email is correct; domain/outbound/cold-email is not.

Hub Notes

When a topic has 3 or more related notes, create a hub note (type/hub) that wikilinks to all of them. Hub notes are the primary navigation mechanism — hierarchy and relationships live here, not in nested folders or tag nesting.

A hub note should:

Have a descriptive summary explaining what this cluster is about
List wikilinks to all related notes with a one-line description of each
Use type/hub as the type tag
Be linked back to from the notes it indexes (add a ## Related section)

Hierarchy lives in hub notes + wikilinks, not in folder structure or tag nesting.

Graphify Awareness

The graphify-out/ directory at the vault root is generated by Graphify — do not author files there. It is disposable and fully rebuilt by running graphify against the vault. The graph uses summary fields and wikilinks as primary signal.

Never edit files in graphify-out/ by hand.

Migration Compatibility

Pre-migration notes use legacy flat tags (plan, research, log, etc.) — both legacy and facet-namespaced forms coexist during incremental migration (ADR-013). Do not "fix" old notes on sight without a migration plan. New notes must use facet-namespaced tags from creation.

5.4 KiB Raw Blame History

Vault Conventions

Navigation