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

```bash
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`