9.0 KiB

Raw Blame History

summary

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.

Note Types (Authoring Guide)

This section defines the three primary note types used for durable, evergreen knowledge. For the type/ tag vocabulary and full type list, see Note Types (type/ facet) above.

convention

Question this answers: "When I encounter [situation X], what rule or pattern should I follow, and why?" A convention is a repeatable rule, principle, or decision framework meant to guide repeated choices in a specific context. Value gate: Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?) Mutability: stable knowledge Template: (not yet created) Sub-templates: none

reference

Question this answers: "What are the established rules, structures, setup requirements, or role definitions I need to know to [make decisions | integrate with a system | understand who does what]?" A reference note is authoritative lookup material that supports decision-making or implementation. Value gate: Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?) Mutability: stable knowledge (except API integration refs, which may need last_reviewed date) Template: (not yet created) Sub-templates: pattern/framework, API integration, role definitions, design rules, navigation/index

howto

Question this answers: "How do I accomplish [specific, repeatable task]?" A howto covers concrete, actionable steps — setup, configuration, deployment, migration, or troubleshooting. The reader wants to DO the thing, not understand it theoretically. Value gate: Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?) Mutability: stable knowledge, but experience-driven updates apply — when a session executes the procedure and finds a discrepancy, update the note rather than relying on a review date. Template: (not yet created) Sub-templates: none

Note on directories: The standard directories for these types are convention/, reference/, and howto/ at the vault root. These directories do not yet exist; notes of these types currently live at the vault root until directory structure is established.

Standard Frontmatter Schema

All notes use this frontmatter block. Type-specific additions are noted inline.

---
type: [convention|reference|howto]
title: [Human-readable title]
summary: [1-2 sentences answering "what question does this note answer?"]
tags:
  - type/[convention|reference|howto]
  - domain/[field]        # e.g., domain/rails, domain/ai-agents, domain/design
  - tool/[tool]           # if tool-specific; omit if not
  - client/[client]       # if client-specific; omit if general
  - project/[project]     # if project-specific; omit if general
scope: [global|project|client]
last_updated: YYYY-MM-DD
# For mutable facts (API integration refs, billing rates):
# last_reviewed: YYYY-MM-DD
---

Field notes:

type — machine-readable; mirrors the type/ tag. Required.
title — human-readable display name. Required.
summary — 1-2 sentences that answer the note's core question. Used by Graphify and SessionStart injection. Required; never defer.
tags — at minimum type/ and scope/ are required (see Tag Taxonomy above). Add domain/, tool/, client/, project/ as applicable.
scope — global (applies across all work) or project (specific to one client/project). Required.
last_updated — date of last substantive edit. Required.
last_reviewed — optional; add only for mutable facts (API integration refs, billing rates, role definitions that change).

9.0 KiB Raw Blame History