Upgrade TLDR to v0.2 with NDJSON format and add --tldr=all flag

TLDR v0.1 → v0.2 Migration:
- Replace ASCII KEY:value format with NDJSON (newline-delimited JSON)
- Add tool delimiter (--- tool: forest ---) and metadata headers
- Implement Forest's condensed keymap (12 keys vs 38 stdlib, 60% reduction)
  - Command-level: cmd, p, in, out, fx, fl, ex, rel
  - Flag-level: n, t, d, desc
- Update type system: STR→str, BOOL→bool, INT→int, FLOAT→float, etc.
- Transform all 31 command definitions to v0.2 abbreviated format
- Convert side effects to namespaced: db:write, compute:embedding, etc.
- Update emitTldrAndExit signature: (data, jsonMode) → (data, version)

New --tldr=all Feature:
- Add formatAllCommandsTldr() to output entire CLI surface in one call
- Enable zero-shot CLI discovery for AI agents (31 commands in single response)
- Format: tool delimiter + metadata header + 31 JSON objects (one per line)
- Non-breaking: preserves existing 'forest --tldr' behavior

Benefits:
- 60% token reduction from condensed keymap
- Single API call discovers full CLI capability
- Valid NDJSON for easy parsing
- Self-documenting with embedded keymap

Testing:
- forest --tldr outputs global index ✓
- forest capture --tldr outputs single command ✓
- forest --tldr=all outputs 33 lines (delimiter + header + 31 commands) ✓
- All JSON lines parse correctly ✓

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bwl

.claude/agents/api-tester.md

@@ -0,0 +1,107 @@
+---
+name: api-tester
+description: Use this agent when the user has just implemented or modified API endpoints and needs comprehensive endpoint testing. Trigger when you see phrases like 'test the endpoints', 'verify the API', 'check if the routes work', 'test the new endpoints I added', or after completing implementation of REST endpoints, server routes, or API features. Also use proactively after you've helped implement new endpoints or modified existing routes to suggest testing before the user commits changes.\n\nExamples:\n\n<example>\nContext: User just implemented new /nodes CRUD endpoints.\nuser: "I just added the /nodes endpoints with GET, POST, PUT, and DELETE. Can you test them?"\nassistant: "I'll use the api-tester agent to run comprehensive tests on your new /nodes endpoints."\n<commentary>The user explicitly requested endpoint testing after implementation, which is the primary use case for api-tester.</commentary>\n</example>\n\n<example>\nContext: User modified edge management routes to add new query parameters.\nuser: "I updated the /edges endpoint to support filtering by status and score range. Please verify it works."\nassistant: "Let me launch the api-tester agent to verify your updated /edges endpoint with the new filtering parameters."\n<commentary>User wants verification of modified routes with new functionality - perfect for api-tester.</commentary>\n</example>\n\n<example>\nContext: Assistant just helped implement pagination on /tags endpoint.\nuser: "Thanks for adding pagination!"\nassistant: "You're welcome! Let me use the api-tester agent to verify the pagination parameters work correctly on the /tags endpoint before you commit this change."\n<commentary>Proactive testing suggestion after implementation is complete - api-tester should verify the new feature works.</commentary>\n</example>\n\n<example>\nContext: User asks to test error handling.\nuser: "Can you test if the API properly returns 404 for missing nodes?"\nassistant: "I'll use the api-tester agent to test error cases including 404 responses for missing resources."\n<commentary>Testing specific error scenarios is part of comprehensive endpoint testing.</commentary>\n</example>
+tools: Bash, Read, Grep
+model: haiku
+color: orange
+---
+
+You are an expert API testing specialist with deep knowledge of REST API design, HTTP protocols, and comprehensive endpoint validation. Your role is to execute thorough, systematic tests of API endpoints and provide concise, actionable test reports.
+
+## Your Responsibilities
+
+1. **Comprehensive Endpoint Testing**: For each endpoint, you will:
+   - Test all HTTP methods (GET, POST, PUT, DELETE, PATCH as applicable)
+   - Verify successful responses return correct status codes (200, 201, 204)
+   - Test error cases (400, 404, 422, 500) with invalid inputs
+   - Validate response formats match expected schemas (JSON structure, field types)
+   - Check pagination parameters (limit, offset, page, cursor as applicable)
+   - Test query parameters and filters
+   - Verify request/response headers
+   - Measure and note response times
+
+2. **Systematic Test Execution**: You will:
+   - Use curl commands via the Bash tool to make HTTP requests
+   - Parse JSON responses to validate structure and data
+   - Test edge cases: empty results, boundary values, missing parameters
+   - Verify data persistence (create → read → update → read → delete flows)
+   - Test related endpoints together (e.g., create node, then link it, then query the link)
+
+3. **Intelligent Test Coverage**: Based on the endpoint type, adapt your tests:
+   - **CRUD endpoints**: Full lifecycle testing (Create, Read, Update, Delete)
+   - **List endpoints**: Empty state, single item, multiple items, pagination, filtering
+   - **Search endpoints**: Query variations, no results, partial matches
+   - **Batch operations**: Single vs multiple items, partial failures
+
+4. **Concise Reporting**: After testing, provide a structured summary:
+   - **Test Summary**: Total tests run, passed count, failed count
+   - **Failures**: List any failed tests with brief error descriptions
+   - **Performance**: Note any unusually slow responses (>1s)
+   - **Recommendations**: Suggest fixes for failures or improvements
+   - **DO NOT**: Include verbose curl output or full JSON responses unless explaining a failure
+
+## Test Execution Guidelines
+
+- **Server Discovery**: First check if a server is running (typically localhost:3000 or similar). Use Read tool to check project files for server config if needed.
+- **Test Data**: Create minimal test data needed for validation, clean up after tests when possible
+- **Error Handling**: Gracefully handle connection failures, timeouts, and unexpected responses
+- **Context Efficiency**: Keep test execution details internal, only surface actionable results
+- **Use jq**: Pipe curl output through jq for JSON validation and field extraction when available
+
+## Example Test Flow
+
+For a hypothetical `/api/nodes` endpoint:
+```bash
+# 1. Test GET all (empty state)
+curl -s http://localhost:3000/api/nodes | jq '.data | length'
+
+# 2. Test POST create
+curl -s -X POST http://localhost:3000/api/nodes -H "Content-Type: application/json" -d '{"title":"Test","body":"Body"}' | jq '.id'
+
+# 3. Test GET single (with created ID)
+curl -s http://localhost:3000/api/nodes/{id} | jq '.title'
+
+# 4. Test error case (404)
+curl -s -w "\n%{http_code}" http://localhost:3000/api/nodes/nonexistent
+
+# 5. Test pagination
+curl -s "http://localhost:3000/api/nodes?limit=10&offset=0" | jq '.data | length'
+```
+
+## Output Format
+
+Your final response should follow this structure:
+
+```
+=== API Test Results ===
+
+**Endpoints Tested**: /api/nodes, /api/edges
+**Total Tests**: 24
+**Passed**: 22
+**Failed**: 2
+
+**Failures**:
+- GET /api/nodes?invalidParam=x: Expected 400, got 200 (invalid params not validated)
+- DELETE /api/edges/{id}: 500 error (foreign key constraint not handled)
+
+**Performance**:
+- Most responses < 100ms
+- GET /api/search taking 1.2s (consider indexing)
+
+**Recommendations**:
+1. Add query parameter validation to return 400 for unknown params
+2. Handle edge deletion constraints with proper cascade or error message
+3. Add database index on search fields
+
+**Test Coverage**: CRUD operations, pagination, filtering, error cases
+```
+
+## Decision Framework
+
+- If server isn't running, report this immediately and suggest starting it
+- If endpoints are undocumented, make reasonable assumptions based on REST conventions
+- If a test fails, try to diagnose the root cause (validation, data, server error)
+- If you encounter unexpected behavior, include it in recommendations
+- If all tests pass, still provide the summary with performance notes
+
+You work efficiently and autonomously. You don't ask for permission to run tests - you execute them systematically and report results. You are thorough but concise, ensuring the user gets actionable insights without context pollution.

.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(forest:*)",
+      "WebSearch",
+      "Bash(curl -s http://localhost:3000/api/v1/health)",
+      "Bash(curl -s \"http://localhost:3000/api/v1/nodes?limit=5\")",
+      "WebFetch(domain:platform.openai.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

AGENTS.md

@@ -0,0 +1,29 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/index.ts` stitches together the CLI, orchestrating capture, explore, and linking commands.
+- `src/lib/` contains focused modules: `db.ts` wraps sql.js persistence, `graph.ts` builds graphology structures, `scoring.ts` maintains suggestion heuristics, and `text.ts` handles tokenization and tagging.
+- `dist/` is generated output from TypeScript; rebuild instead of editing files here.
+- `docs/` hosts design notes such as `cli-surface-proposal.md`; keep long-form discussions and ADR-style writeups here.
+- `forest.db` is a sample database for local smoke tests; feel free to reset it when experimenting.
+
+## Build, Test, and Development Commands
+- `npm run build` compiles TypeScript to `dist/` with the repo tsconfig.
+- `npm run dev` executes the CLI through `tsx`, ideal for iterating on commands without compiling.
+- `npm run lint` runs `tsc --noEmit` for type safety; treat failures as blockers.
+- `npm start` runs the compiled CLI (`node dist/index.js`); use it when verifying release artifacts.
+
+## Coding Style & Naming Conventions
+- Follow the existing 2-space indentation, single quotes, and trailing commas where they clarify multi-line structures.
+- Favor small, pure functions; keep modules under `src/lib/` single-purpose and export named functions instead of default exports.
+- Use lowerCamelCase for variables/functions, PascalCase for types, and kebab-case for new file names.
+
+## Testing Guidelines
+- There is no automated test suite yet; for new features, add targeted TypeScript tests alongside the code (e.g., `src/lib/__tests__/graph.spec.ts`) using `tsx` or `ts-node`.
+- Cover edge cases around scoring thresholds, tag extraction, and graph linking; include fixtures under a nearby `fixtures/` folder if needed.
+- Run `npm run dev -- capture --body "example"` against a fresh `forest.db` to perform smoke tests before submitting.
+
+## Commit & Pull Request Guidelines
+- Write concise, imperative commit subjects (e.g., “Add capture preview summary”), mirroring the existing history.
+- Group related changes per commit and mention the affected module path in the body when context helps reviewers.
+- In pull requests, link related issues, summarize behavior changes, note manual test commands, and include CLI output snippets or screenshots when UI-facing functionality changes.

Camper/PRODUCT_STRATEGY.md

@@ -0,0 +1,79 @@
+# Camper Product Strategy
+
+**READ THIS FIRST**: GPT-5 generated a comprehensive product strategy report for Camper.
+
+## How to Access
+
+```bash
+forest node read e860b1c3
+```
+
+Or view in Forest's knowledge base as node `e860b1c3`.
+
+## Report Summary
+
+**Title**: "What Humans Actually Want: A Human-First Product Strategy for Camper (Built on Forest)"
+
+**Generated**: 2025-10-21
+**Cost**: $0.02 (GPT-5 high reasoning)
+**Length**: ~2,424 words
+
+## Key Insights
+
+### Core Principle
+> "Build the Practice, Not the Graph. The graph is the engine; the practice is the product."
+
+### Strategic Focus Areas
+
+1. **Three-Second Capture** - Every primary action <2 seconds
+2. **Review Mode Over Dashboards** - Calm triage, not information overload
+3. **Editor-First Experience** - People live in the editor
+4. **Human-in-the-Loop Intelligence** - Forest proposes, humans decide
+5. **Rhythmic Workflows** - Daily, weekly, monthly patterns
+
+### What NOT to Build
+
+- ❌ Heavy PM suite (Gantt charts, sprints)
+- ❌ Real-time collaboration as core feature
+- ❌ Notion-like database engine
+- ❌ Flashy graph dashboard
+- ❌ Auto-rewriting notes without confirmation
+
+### The Camper Advantage
+
+Forest handles graph intelligence (embeddings, auto-linking, scoring). This frees Camper to focus entirely on human workflows that competitors can't match because they conflate the graph layer with the interface layer.
+
+## Three-Phase Roadmap
+
+**Phase 1 (0-3mo)**: Quick capture, daily notes, Review Mode v1, editor experience
+**Phase 2 (3-6mo)**: Tasks, meeting briefings, context panel, AI-assisted extraction
+**Phase 3 (6-9mo)**: Automations, integrations (Readwise/Omnivore), lightweight sharing
+
+## Success Metrics
+
+- Time-to-capture < 2 seconds
+- Triage throughput (inbox zero in ~12 minutes)
+- Retrieval success within 10 seconds
+- **Forest proposal acceptance rate** (trust indicator)
+- 4-week retention
+
+## Read the Full Report
+
+The full report covers:
+- User psychology and friction points
+- Daily/weekly/monthly workflow patterns
+- The capture problem (lessons from Readwise, Omnivore)
+- Cozy features that build trust
+- Editor integration insights
+- Triage workflow design
+- Task management (PKM vs. dedicated managers)
+- Collaboration boundaries
+- Concrete UX examples
+
+```bash
+forest node read e860b1c3
+```
+
+---
+
+**Note**: This report was generated using `forest write` with a detailed prompt about Forest/Camper architecture and user needs. It represents GPT-5's synthesis of PKM best practices, user behavior patterns, and strategic opportunities given our clean separation of concerns.

FEATURE_CHECKLIST.md

@@ -0,0 +1,127 @@
+# Feature Development Checklist
+
+Use this checklist when adding new features to Forest to ensure CLI/API parity.
+
+## Pre-Implementation
+
+- [ ] Define feature requirements clearly
+- [ ] Identify where the feature should be accessible (CLI only, API only, or both?)
+- [ ] Design the core function signature and return types
+- [ ] Plan error cases and validation
+
+## Implementation Order
+
+### 1. Core Business Logic
+- [ ] Create or update function in `src/core/*.ts`
+  - [ ] Function is pure (no I/O formatting, no HTTP/CLI dependencies)
+  - [ ] Returns typed data structures
+  - [ ] Handles all business validation
+  - [ ] Includes comprehensive error handling
+  - [ ] Well-documented with JSDoc comments
+
+### 2. REST API (if applicable)
+- [ ] Create or update route in `src/server/routes/*.ts`
+  - [ ] Calls core function (no business logic duplication)
+  - [ ] Parses and validates query parameters/request body
+  - [ ] Uses helper functions from `src/server/utils/helpers.ts`
+  - [ ] Returns standard envelope format via `createSuccessResponse()`
+  - [ ] Handles errors with `ForestError` classes
+  - [ ] Sets appropriate HTTP status codes
+  - [ ] Includes Swagger/OpenAPI documentation tags
+- [ ] Register route in `src/server/index.ts`
+  - [ ] Import route module
+  - [ ] Add `.use()` call to app
+  - [ ] Add tag to Swagger documentation config
+
+### 3. CLI Command (if applicable)
+- [ ] Create or update command in `src/cli/commands/*.ts`
+  - [ ] Calls core function (no business logic duplication)
+  - [ ] Parses command-line arguments and flags
+  - [ ] Provides human-readable text output (default)
+  - [ ] Provides machine-readable JSON output (with `--json` flag)
+  - [ ] Uses utilities from `src/cli/shared/utils.ts`
+  - [ ] Handles errors with `handleError()`
+- [ ] Register command in `src/cli/index.ts`
+  - [ ] Import command factory
+  - [ ] Call `cli.command(createYourCommand(clerc))`
+
+### 4. Documentation
+- [ ] Update `CLAUDE.md`
+  - [ ] Add command to command structure list (if new command)
+  - [ ] Document any new patterns or utilities
+  - [ ] Update examples if needed
+- [ ] Update README.md (if user-facing)
+- [ ] Add inline code comments for complex logic
+
+### 5. Testing
+- [ ] Test core function independently
+  - [ ] Happy path with valid inputs
+  - [ ] Error cases and edge cases
+  - [ ] Boundary conditions
+- [ ] Test API endpoint (if applicable)
+  - [ ] Valid requests return expected responses
+  - [ ] Invalid requests return appropriate errors
+  - [ ] Pagination works correctly (if applicable)
+  - [ ] Filtering works correctly (if applicable)
+  - [ ] Response format matches standard envelope
+- [ ] Test CLI command (if applicable)
+  - [ ] Valid arguments produce expected output
+  - [ ] Invalid arguments show helpful errors
+  - [ ] Both text and JSON output formats work
+  - [ ] Help text is clear and accurate
+
+### 6. Validation
+- [ ] CLI and API produce identical results for equivalent inputs
+- [ ] Error messages are consistent between CLI and API
+- [ ] Feature behavior is documented
+- [ ] No duplicate business logic between layers
+
+## Architecture Compliance
+
+### ✅ Good Patterns
+- Core function contains all business logic
+- CLI command calls core function, only handles formatting
+- API route calls core function, only handles HTTP concerns
+- Validation happens in both route/command AND core function
+- Errors use typed error classes (`ForestError` hierarchy)
+
+### ❌ Anti-Patterns to Avoid
+- Business logic implemented in CLI command or API route
+- Different validation logic in CLI vs API
+- Different error handling in CLI vs API
+- Direct database access from routes/commands (should go through core)
+- Copy-pasted code between CLI and API
+
+## Example: Semantic Search Feature
+
+**Core Function** (`src/core/search.ts`):
+```typescript
+export async function semanticSearchCore(
+  query: string,
+  options: SemanticSearchOptions = {},
+): Promise<SemanticSearchResult>
+```
+
+**API Route** (`src/server/routes/search.ts`):
+```typescript
+app.get('/api/v1/search/semantic', async ({ query }) => {
+  const result = await semanticSearchCore(query.q, { ... });
+  return createSuccessResponse({ nodes: result.nodes, ... });
+});
+```
+
+**CLI Command** (`src/cli/commands/search.ts`):
+```typescript
+export function createSearchCommand(clerc) {
+  return clerc.defineCommand({ name: 'search' }, async ({ flags }) => {
+    const result = await semanticSearchCore(flags.query, { ... });
+    printTextResults(result); // or JSON.stringify for --json
+  });
+}
+```
+
+## Notes
+
+- If a feature only makes sense in one interface (CLI or API), that's okay! Not everything needs to be in both.
+- When in doubt, put logic in the core layer. It's easier to extract than to consolidate later.
+- Keep the API and CLI in sync by always implementing both at the same time when appropriate.