# Agent Coding Guidelines

**Purpose**: Code style and workflow for agentic coding assistants in this vault
**Last Updated**: 2026-01-06

---

## Build & Lint Commands

```bash
# Lint & format (auto-fixes issues)
pnpm lint                  # Run eslint + prettier with auto-fix

# Check only (no fixes)
pnpm lint:check            # Verify code style compliance

# Format only
pnpm format                # Prettier format all files
pnpm format:check          # Check formatting without changes

# Run scripts directly (no test framework configured)
node .scripts/update-attachment-links.js
GEMINI_API_KEY=xxx node .claude/mcp-servers/gemini-vision.mjs
python3 .scripts/rename-chinese-to-english.py
```

---

## Code Style Guidelines

### TypeScript/JavaScript

#### Imports

```javascript
import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { readFile } from 'node:fs/promises'
import path from 'node:path'
import fs from 'node:fs'
```

#### Formatting

```javascript
// Single quotes for strings, use semicolons
const value = 'string'
const obj = { name, value }
const msg = `Hello ${name}`
```

#### Error Handling

```javascript
// Always handle errors in async functions
try {
  await fs.access(filePath)
} catch {
  throw new Error(`File not found: ${filePath}`)
}

// Check environment variables early
if (!process.env.API_KEY) {
  console.error('❌ API_KEY environment variable is required')
  process.exit(1)
}
```

#### Naming Conventions

```javascript
function analyzeImage(args) {} // camelCase
const MAX_ATTEMPTS = 60 // UPPER_SNAKE_CASE
const imagePath = 'path/to/file.png' // camelCase
class ImageAnalyzer {} // PascalCase
function process(data, _unused) {} // Prefix unused with _
```

### Python Scripts

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from pathlib import Path
from typing import List, Dict

path = Path('05_Attachments/Organized')

def process_files(files: List[str]) -> Dict[str, str]:
    """Process list of files."""
    return {f: f for f in files}

file_path = 'path/to/file.md'  # snake_case
MAX_RETRIES = 3                # UPPER_SNAKE_CASE
```

---

## File Organization

```bash
.claude/mcp-servers/    # MCP server implementations
.scripts/              # Utility scripts (JS/Python)
.config/               # Config files (eslint, prettier, tsconfig)
```

### Script Structure

```javascript
#!/usr/bin/env node

import fs from 'node:fs'

const args = process.argv.slice(2)
if (args.length !== 1) {
  console.log('Usage: node script.js <arg>')
  process.exit(1)
}

async function main() {
  // Implementation
}

main().catch(console.error)
```

---

## Common Patterns

### File Walking

```javascript
function walkDir(dir, callback) {
  fs.readdirSync(dir).forEach((f) => {
    const dirPath = path.join(dir, f)
    const isDirectory = fs.statSync(dirPath).isDirectory()
    if (isDirectory && !f.includes('node_modules') && !f.includes('.git')) {
      walkDir(dirPath, callback)
    } else if (!isDirectory) {
      callback(dirPath)
    }
  })
}
```

### Processing Files

```javascript
walkDir('.', (filepath) => {
  if (filepath.endsWith('.md')) {
    let content = fs.readFileSync(filepath, 'utf8')
    // Process content
    if (content !== originalContent) {
      fs.writeFileSync(filepath, content, 'utf8')
    }
  }
})
```

---

## Before Making Changes

1. Read existing files to understand patterns
2. Check package.json for available scripts/dependencies
3. Run lint before committing: `pnpm lint`
4. Test changes by running scripts directly
5. Commit with descriptive message after verification

---

**Resources**:

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