my-vault/AGENTS.md

AGENTS.md — Vault Operations Manual

Purpose: Single source of truth for AI agents operating in this Obsidian vault. Last Updated: 2026-09-26

---

Directory Structure (PARA)

00_Inbox/           Temporary capture, process weekly
01_Projects/        Time-bound work with deadlines
02_Areas/           Ongoing responsibilities (Health, Finance, etc.)
03_Resources/       Reference materials and knowledge base
04_Archive/         Completed items and clippings
05_Attachments/     Media files (images, PDFs)
06_Metadata/        Templates and reference docs (8 files)

.claude/            Agent config, commands, hooks
.config/            ESLint, Prettier, TypeScript config
.scripts/           Utility scripts (JS/Python)
.github/            CI workflows
.obsidian/          Obsidian app config (do not rewrite)

Permission Table

Path	Rule
00_Inbox/	Free to create and edit
01_Projects/	Edit on request
03_Resources/	Edit on request
02_Areas/	Ask before editing
04_Archive/	Never rewrite — read-only historical record
06_Metadata/Templates/	Never rewrite — wired to Obsidian plugins
.obsidian/	Never rewrite — app config
.obsidian/plugins/*/data.json	Hard deny — may contain secrets
Credential files (see .gitignore)	Never read or write

Frontmatter Conventions

Active notes (00–03) use these core keys:

• created (required) — ISO date YYYY-MM-DD
• status — one of: draft, active, done, archived
• tags, type, updated — optional

Content keys (never delete): title, description, source, date, author, published, aliases

Clipper boundary: 04_Archive/Inbox-Clippings/** permanently uses the web clipper schema (date/page-title/url). Never migrate.

Safety Rules

1. Read before writing — always read a file before editing it
2. Never delete without approval — ask before removing content
3. Preserve everything when merging — only remove verified exact duplicates
4. Verify before moving — check destination exists, update all [[wikilinks]] after move
5. Never move numbered folders (00–06) from vault root
6. Get approval for bulk operations affecting 5+ files
7. Never commit secrets — run .scripts/verify-vault.mjs before pushing

Git Workflow

pnpm lint              # Auto-fix before committing
pnpm lint:check        # Verify without changes
node .scripts/verify-vault.mjs  # Secret scanner (CI runs this too)

• Commit after each work session with descriptive messages
• Pull before starting work
• Never force-push to main

Organization Principles

• Inbox is temporary — process weekly
• One idea per note (atomic notes)
• Flat structure over deep nesting (max 4 levels for new notes)
• Use links not folders for relationships
• Link liberally, prefer over-linking

Work Approach

• Simple tasks — execute directly
• Complex changes — propose plan first (affected files, steps, rollback)

---

Scripts — Code Style

JavaScript/TypeScript

• Single quotes, semicolons, node: prefix for built-in imports
• camelCase functions/variables, UPPER_SNAKE_CASE constants, PascalCase classes
• Prefix unused params with _
• Handle errors in async functions, check env vars early

Python

• snake_case functions/variables, UPPER_SNAKE_CASE constants
• Type hints on function signatures

Config

• ESLint: .config/eslint.config.js
• Prettier: .config/.prettierrc.js
• TypeScript: .config/tsconfig.json