my-vault/CLAUDE.md

# Obsidian Vault Configuration

**Generated**: January 05, 2026
**Organization**: PARA Method
**Uses**: Research, Writing, Project Management, Daily Notes
**Status**: Active Configuration

---

## Quick Start

### First-Time Setup
1. Run `git pull` to sync with remote repository
2. Review folder structure below
3. Start capturing notes in `00_Inbox/`
4. Schedule your first weekly review

### Daily Workflow
```bash
# Morning
git pull                    # Sync latest changes
# Review inbox, work on projects

# Evening
git status                  # Check modifications
git add .                   # Stage changes
git commit -m "vault backup: $(date)"
git push                    # Sync to remote
```

### Essential Commands
- **Inbox Processing**: Review `00_Inbox/` weekly
- **Web Content**: Use WebSearch or WebFetch tools
- **Attachments**: Store in `05_Attachments/`, organize when processed
- **Weekly Review**: Follow checklist in `WEEKLY_REVIEW.md`

---

## Folder Structure

```
D:\tmp\vault\my-vault/
├── 00_Inbox/              # Temporary capture point
│   ├── Clippings/         # Web content from Firecrawl
│   └── [Daily captures]   # Quick notes to process
│
├── 01_Projects/           # Time-bound initiatives
│   └── [ProjectName]/
│       ├── Research/      # Background materials
│       ├── Drafts/        # Work in progress
│       ├── References/    # Supporting documents
│       └── Output/        # Final deliverables
│
├── 02_Areas/              # Ongoing responsibilities
│   └── [AreaName]/        # Health, Finances, etc.
│
├── 03_Resources/          # Reference materials
│   └── [TopicName]/       # Knowledge bases by subject
│
├── 04_Archive/            # Completed/inactive items
│   ├── Projects/          # Completed projects
│   ├── Areas/             # Inactive areas
│   └── Resources/         # Outdated resources
│
├── 05_Attachments/        # Non-text files
│   ├── Organized/         # Processed attachments
│   └── [Unprocessed]      # Awaiting organization
│
└── 06_Metadata/           # Documentation & templates
    ├── Reference/         # Guides and standards
    ├── Plans/             # Strategic documents
    └── Templates/         # Reusable structures
```

---

## PARA Method Explained

### Projects (01_Projects/)
**Definition**: Time-bound initiatives with clear completion criteria

**Characteristics**:
- Has a specific end goal
- Has a deadline or completion state
- Contains discrete tasks and deliverables
- Will eventually move to Archive

**Examples**:
- Writing a research paper
- Planning a presentation
- Learning a specific skill
- Organizing an event

**Structure**:
```
01_Projects/[ProjectName]/
├── README.md              # Project overview, goals, timeline
├── Research/              # Background materials
├── Drafts/                # Work in progress
├── References/            # Supporting documents
└── Output/                # Final deliverables
```

### Areas (02_Areas/)
**Definition**: Ongoing responsibilities without end dates

**Characteristics**:
- Continuous maintenance required
- Standards to uphold
- No completion date
- Generates multiple projects over time

**Examples**:
- Health & Fitness
- Professional Development
- Finances
- Relationships
- Home Management

**Structure**:
```
02_Areas/[AreaName]/
├── Overview.md            # Area definition and standards
├── Projects.md            # Related project links
└── Resources.md           # Helpful references
```

### Resources (03_Resources/)
**Definition**: Topics of interest for reference and learning

**Characteristics**:
- Not tied to current projects
- Reference material
- Long-term knowledge building
- Curated information

**Examples**:
- Programming languages
- Historical topics
- Philosophical concepts
- Technical documentation
- Book notes

**Structure**:
```
03_Resources/[TopicName]/
├── Index.md               # Topic overview
├── Notes/                 # Individual concept notes
└── References/            # Source materials
```

### Archive (04_Archive/)
**Definition**: Completed projects and inactive items

**Characteristics**:
- Completed projects
- Inactive areas
- Outdated resources
- Historical reference

**When to Archive**:
- Projects: When objectives are met
- Areas: When no longer relevant
- Resources: When superseded or outdated

---

## File Organization Rules

### Naming Conventions

**Daily Notes**:
```
YYYY-MM-DD - [Topic or Activity]
Example: 2026-01-05 - Meeting Notes
```

**Meeting Notes**:
```
Meeting - [Topic] - YYYY-MM-DD
Example: Meeting - Project Planning - 2026-01-05
```

**Ideas**:
```
Idea - [Brief Description]
Example: Idea - Automated Daily Review Process
```

**Resources**:
```
Resource - [Topic] - [Source]
Example: Resource - PARA Method - Forte Labs
```

**Clippings (Auto-generated by Firecrawl)**:
```
[Domain]_[Timestamp].md
Example: anthropic.com_1736095200.md
```

### Movement Best Practices

**ALWAYS**:
- Use `mv` command (not `cp`) to avoid duplicates
- Verify destination folder exists before moving
- Update internal links after moving files
- Add YAML frontmatter when organizing
- Commit changes after significant reorganization

**NEVER**:
- Move files with number prefixes (00-06) from root
- Delete files without reviewing content
- Create deep folder hierarchies (max 3 levels)
- Leave broken links after reorganization

### YAML Frontmatter Template

```yaml
---
created: YYYY-MM-DD
modified: YYYY-MM-DD
tags: [tag1, tag2, tag3]
status: [draft|active|complete|archived]
type: [note|project|area|resource]
---
```

---

## Inbox Management

### Core Principles
- Inbox is **temporary**, not permanent storage
- Process weekly using: Capture → Process → Organize
- Maintain fewer than 20 unprocessed items
- Everything in inbox should be recent (< 1 week old)

### What Stays in Inbox Permanently
- Files with number prefixes: `00-`, `01-`, etc.
- Core configuration files: `CLAUDE.md`, `WEEKLY_REVIEW.md`, `.gitignore`
- Active daily notes (last 7 days)
- Current weekly summaries (last 3 months)

### Processing Workflow

**Step 1: Review**
```bash
git status                  # See what's new
ls 00_Inbox/               # List inbox contents
```

**Step 2: Decide**
For each item, ask:
- Is this actionable? → Create task or project
- Is this reference? → Move to Resources
- Is this project-related? → Move to Projects
- Is this outdated? → Delete or archive
- Needs more work? → Tag `#needs-processing`

**Step 3: Organize**
```bash
# Move to appropriate location
mv "00_Inbox/filename.md" "01_Projects/ProjectName/"

# Verify
ls "01_Projects/ProjectName/"
```

**Step 4: Commit**
```bash
git add .
git commit -m "Organize inbox: processed weekly items"
git push
```

### Inbox Clippings Folder
- Firecrawl automatically saves web content here
- Process within 1 week
- Move to appropriate PARA location
- Delete duplicates or low-value content

---

## Attachments Management

### Organization Rules

**Storage Location**:
- All non-text files: `05_Attachments/`
- Unprocessed: `05_Attachments/`
- Processed: `05_Attachments/Organized/`

**Naming Convention**:
```
[RelatedNote]_[Description].[ext]

Examples:
ProjectProposal_Diagram.png
Research_StatisticsTable.pdf
Meeting2026-01-05_Whiteboard.jpg
```

**Supported File Types**:
- Images: PNG, JPG, GIF, SVG
- Documents: PDF, DOCX
- Data: CSV, XLSX, JSON
- Media: MP3, MP4 (use sparingly)

### Processing Workflow

**Step 1: List Unprocessed**
```bash
ls 05_Attachments/
```

**Step 2: Review Each File**
- Is it referenced in notes? Keep and rename
- Is it orphaned? Delete or add reference
- Is it project-related? Keep with clear name

**Step 3: Rename and Move**
```bash
mv "05_Attachments/screenshot.png" "05_Attachments/Organized/ProjectName_Feature.png"
```

**Step 4: Update Links**
Update any markdown references:
```markdown
Before: ![](../05_Attachments/screenshot.png)
After: ![](../05_Attachments/Organized/ProjectName_Feature.png)
```

### Helper Scripts

```bash
# List unprocessed attachments
pnpm attachments:list

# Count organized files
pnpm attachments:organized

# Find unreferenced files (orphans)
pnpm attachments:orphans

# Update links after moving files
pnpm attachments:update-links
```

---

## Web Content Workflow

### Built-in Tools (Preferred Method)

**WebSearch Tool**:
```
Use for: General web searches, current information
Output: Search results with sources
Action: Copy relevant content into notes manually
```

**WebFetch Tool**:
```
Use for: Specific URLs, documentation pages
Output: Page content in markdown format
Action: Save to appropriate PARA location
```

**Best Practices**:
1. Use WebSearch/WebFetch within Claude Code
2. Review content before saving
3. Add frontmatter and context
4. Save to appropriate folder (not Inbox unless processing later)
5. Include source URL in frontmatter

### Firecrawl Scripts (Batch Processing)

**Single URL**:
```bash
pnpm firecrawl:scrape <url> <output-filename>
# Saves to: 00_Inbox/Clippings/
```

**Batch URLs**:
```bash
pnpm firecrawl:batch <url1> <url2> <url3>
# Saves to: 00_Inbox/Clippings/
```

**Auto-generated Frontmatter**:
```yaml
---
source_url: https://example.com/article
scraped_date: YYYY-MM-DD
tags: [clipping, needs-processing]
---
```

**Processing Clippings**:
1. Review content quality
2. Add relevant tags and notes
3. Move to appropriate PARA location
4. Delete low-value clippings

---

## Writing Style Guidelines

### Structure Standards

**Internal Linking**:
- Use `[[WikiLinks]]` for all internal references
- Link liberally (better too many than too few)
- Create bidirectional links when relevant
- Use descriptive link text

**Markdown Formatting**:
- Headings: Use `#` hierarchy (H1 for title, H2 for sections)
- Lists: Use `-` for unordered, `1.` for ordered
- Code: Use backticks for inline, triple backticks for blocks
- Emphasis: `**bold**` for important, `*italic*` for subtle

**YAML Frontmatter**:
- Always include: created, modified, tags
- Optional: status, type, project, area
- Keep tags specific and consistent
- Update modified date when editing

### Content Style Preferences

**Direct Communication**:
- Lead with the main point
- Avoid unnecessary preambles
- Be specific and concrete
- Use active voice

**Avoid**:
- Clichéd transitions ("In today's world...")
- Filler phrases ("It's worth noting that...")
- Unnecessary qualifiers ("I think maybe...")
- Overused business jargon

**Prefer**:
- Clear, confident statements
- Specific examples over generalizations
- Simple sentences over complex
- Technical precision when needed

---

## Git Workflow

### Critical Rule
**ALWAYS start sessions with `git pull`** to sync latest changes from remote repository.

### Daily Workflow

**Morning (Session Start)**:
```bash
cd D:\tmp\vault\my-vault
git pull
git status                  # Check for any conflicts
```

**During Work**:
```bash
git status                  # Periodically check changes
```

**Evening (Session End)**:
```bash
git status                  # Review all changes
git add .                   # Stage all changes
git commit -m "vault backup: $(date +%Y-%m-%d\ %H:%M:%S)"
git push                    # Sync to remote
```

### Commit Message Guidelines

**Format**:
```
[type]: [brief description]

Examples:
vault backup: 2026-01-05 20:30:15
Add: Project planning notes for Q1 initiatives
Update: Weekly review template with new sections
Organize: Moved inbox items to appropriate folders
Archive: Completed research project
```

**When to Commit**:
- After organizing inbox
- After creating new notes
- After significant edits
- Before ending session
- After weekly review

### Common Git Commands

```bash
git status                  # Check current state
git pull                    # Sync from remote
git add .                   # Stage all changes
git commit -m "message"     # Commit with message
git push                    # Sync to remote
git log --oneline -10       # View recent commits
```

### Handling Conflicts

If `git pull` shows conflicts:
1. Review conflicted files
2. Resolve conflicts manually
3. Stage resolved files: `git add .`
4. Commit: `git commit -m "Resolve merge conflicts"`
5. Push: `git push`

---

## AI Assistant Guidelines

### Before Any Organization Task

**Step 1: Map Structure**
```bash
find . -type d | sort > 06_Metadata/STRUCTURE.md
```

**Step 2: Document Current State**
- List all folders
- Note any custom organization
- Identify files needing attention

**Step 3: Verify Destinations**
```bash
ls -la 01_Projects/
ls -la 02_Areas/
ls -la 03_Resources/
```

### Working with Content

**DO**:
- Use `mv` command (not `cp`) to avoid duplicates
- Verify destination folders exist before moving
- Preserve and update bidirectional links
- Add appropriate YAML frontmatter
- Respect numbered core files (never move files with 00-06 prefix)
- Commit changes after organization

**DON'T**:
- Use complex piped commands or regex
- Move files without checking destinations
- Leave broken links after reorganization
- Create deep folder hierarchies
- Delete without reviewing content

### Command Simplicity Rule

**REQUIRED**: Use direct, basic commands only
```bash
# RIGHT
ls -1
ls 00_Inbox/
find . -type d

# WRONG
ls | grep pattern
find . -name "*.md" -mtime +7
ls | wc -l
```

**Reasoning**: Simple commands are more reliable and easier to verify.

---

## Daily Workflows

### Morning Routine (5 minutes)

```bash
# 1. Sync changes
git pull

# 2. Check inbox
ls 00_Inbox/

# 3. Review today's focus
# Create or open: YYYY-MM-DD - Daily Notes.md
```

**Daily Note Template**:
```markdown
---
created: YYYY-MM-DD
type: daily
tags: [daily, journal]
---

# YYYY-MM-DD - Daily Notes

## Focus for Today
- [ ] Primary task 1
- [ ] Primary task 2
- [ ] Primary task 3

## Capture
[Quick notes throughout the day]

## Reflections
[End of day thoughts]
```

### Evening Routine (5 minutes)

```bash
# 1. Process quick inbox items
ls 00_Inbox/

# 2. Update project notes
# Review and update active projects

# 3. Commit changes
git status
git add .
git commit -m "vault backup: $(date)"
git push
```

### Weekly Review (30-45 minutes)

See `WEEKLY_REVIEW.md` for complete checklist.

**Quick Overview**:
1. Process entire inbox (target: zero items)
2. Review all active projects
3. Update area notes
4. Archive completed items
5. Clean up attachments
6. Plan next week

---

## Available Commands

### Attachment Management
```bash
pnpm attachments:list          # List unprocessed attachments
pnpm attachments:organized     # Count organized files
pnpm attachments:orphans       # Find unreferenced files
pnpm attachments:update-links  # Update links after moving
```

### Web Content
```bash
pnpm firecrawl:scrape <url> <output>    # Scrape single URL
pnpm firecrawl:batch <url1> <url2>      # Scrape multiple URLs
```

### Git Operations
```bash
git pull                       # Sync from remote
git status                     # Check modifications
git add .                      # Stage all changes
git commit -m "message"        # Commit with message
git push                       # Sync to remote
```

### Folder Navigation
```bash
cd D:\tmp\vault\my-vault       # Vault root
ls 00_Inbox/                   # List inbox
ls 01_Projects/                # List projects
find . -type d | sort          # Map all folders
```

---

## Best Practices

### Organization Principles

**Keep It Shallow**:
- Maximum 3 levels of folders
- Create subfolders only with 7+ related notes
- Use linking over deep nesting
- Flat is better than nested

**Maintain Clarity**:
- Include README.md in major folders
- Use consistent naming conventions
- Tag consistently and specifically
- Update frontmatter regularly

**Regular Maintenance**:
- Weekly inbox processing (non-negotiable)
- Monthly project reviews
- Quarterly archive cleanup
- Daily git commits

### Content Creation Principles

**Capture First, Organize Later**:
- Don't let organization block capture
- Inbox is for quick entry
- Process in batches, not individually
- Speed over perfection initially

**One Idea Per Note**:
- Atomic notes are more reusable
- Easier to link and discover
- Better for future reorganization
- Clear single purpose

**Link Generously**:
- Create connections between ideas
- Build bidirectional links
- Use consistent link syntax
- Review links when moving files

**Tag Consistently**:
- Use specific tags over generic
- Maintain tag vocabulary list
- Tag for retrieval, not categorization
- Review tags during weekly review

### Maintenance Schedule

**Daily**:
- Morning: `git pull`, check inbox
- Evening: Commit changes, `git push`

**Weekly**:
- Process entire inbox
- Review active projects
- Update area notes
- Clean attachments folder

**Monthly**:
- Review all projects for completion
- Archive inactive items
- Consolidate resources
- Update documentation

**Quarterly**:
- Deep archive review
- Prune old resources
- Update folder structure if needed
- Review and refine workflows

---

## Troubleshooting

### Common Issues

**Inbox Overflow**:
- Schedule immediate processing session
- Delete obvious low-value items first
- Process in batches by type
- Set calendar reminder for weekly review

**Broken Links**:
- Use attachment update script
- Manually verify critical links
- Commit after fixing links
- Document link structure

**Git Conflicts**:
- Always start with `git pull`
- Resolve conflicts immediately
- Don't force push
- Backup before major changes

**Lost Files**:
- Check git history: `git log --all --full-history -- <path>`
- Look in Archive folders
- Search by content: use grep or Obsidian search
- Check recent commits for moves

---

**Last Updated**: January 05, 2026
**Next Review**: Weekly during weekly review process