{"owner":"benbjohnson","repo":"litestream","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md","GEMINI.md","llms.txt"],"skills":{"AGENTS.md":"# AGENTS.md - Litestream AI Agent Guide\n\nLitestream is a disaster recovery tool for SQLite that runs as a background process, monitors the WAL, converts changes to immutable LTX files, and replicates them to cloud storage. It uses `modernc.org/sqlite` (pure Go, no CGO required).\n\n## Before You Start\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) for contribution requirements\n2. Check [CONTRIBUTING.md](CONTRIBUTING.md) for what we accept (bug fixes welcome, features need discussion)\n3. Review recent PRs for current patterns\n\n## Critical Rules\n\n- **Lock page at 1GB**: SQLite reserves page at 0x40000000. Always skip it. See [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md)\n- **LTX files are immutable**: Never modify after creation. See [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md)\n- **Single replica per database**: Each DB replicates to exactly one destination\n- **Use `litestream ltx`**: Not `litestream wal` (deprecated)\n- **Use `litestream reset`**: Clears corrupted local LTX state for a database. See `cmd/litestream/reset.go`\n- **`auto-recover` config**: Replica option that automatically resets local state on LTX errors. Disabled by default. See `replica.go`\n- **Retention enabled by default**: `Store.RetentionEnabled` is `true` by default. Disable only when cloud lifecycle policies handle cleanup. See `store.go`\n- **IPC socket disabled by default**: Control socket is off by default. Enable with `socket.enabled: true` in config. See `server.go`\n- **`$PID` config expansion**: Config files support `$PID` to expand to the current process ID, plus standard `$ENV_VAR` expansion. See `cmd/litestream/main.go`\n- **`litestream ltx -level`**: Use `-level 0`–`9` or `-level all` to inspect specific compaction levels. See `cmd/litestream/ltx.go`\n- **Return errors, don't log them**: Always return errors to callers. Never `log.Printf(err)` and continue — this silently hides failures in a disaster recovery tool. Only use DEBUG log for best-effort operations where failure doesn't affect correctness and a valid fallback exists (e.g., reading SHM mxFrame optimization hint). See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling)\n\n## Layer Boundaries\n\n| Layer | File | Responsibility |\n|-------|------|----------------|\n| DB | `db.go` | Database state, restoration, WAL monitoring, library API (`SyncStatus`, `SyncAndWait`, `EnsureExists`) |\n| Replica | `replica.go` | Replication mechanics only |\n| Storage | `**/replica_client.go` | Backend implementations (includes `ReplicaClientV3` for v0.3.x restore) |\n| IPC | `server.go` | Unix socket control API (register/unregister, /txid, pprof) |\n| Leasing | `leaser.go`, `s3/leaser.go` | Distributed lease acquisition via conditional writes |\n\nDatabase state logic belongs in DB layer, not Replica layer.\n\n## Quick Reference\n\n**Build:**\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\n```\n\n**Code quality:**\n\n```bash\npre-commit run --all-files\n```\n\n## Documentation\n\n| Document | When to Read |\n|----------|--------------|\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Deep component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Adding storage backends |\n| [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) | Provider-specific S3/cloud configs |\n\n## Checklist\n\nBefore submitting changes:\n\n- [ ] Read relevant docs above\n- [ ] Follow patterns in [docs/PATTERNS.md](docs/PATTERNS.md)\n- [ ] Test with race detector (`go test -race`)\n- [ ] Run `pre-commit run --all-files`\n- [ ] For page iteration: test with >1GB databases\n- [ ] Show investigation evidence in PR (see [AI_PR_GUIDE.md](AI_PR_GUIDE.md))\n","CLAUDE.md":"# CLAUDE.md - Claude Code Configuration\n\nClaude-specific optimizations for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Critical Coding Rules\n\n- **Always return errors, never log and continue.** The only exception is DEBUG logging for best-effort operations that don't affect correctness. This is the #1 cause of PR review feedback. See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling) for the full decision framework.\n\n## Context Window\n\nWith Claude's large context window, load documentation as needed:\n\n- Start with [AGENTS.md](AGENTS.md) for overview and checklist\n- Load [docs/PATTERNS.md](docs/PATTERNS.md) when writing code\n- Load [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) for WAL/page work\n- Load [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) for storage backend configs\n\n## Claude-Specific Resources\n\n### Specialized Agents (.claude/agents/)\n\n- `sqlite-expert.md` - SQLite WAL and page management\n- `replica-client-developer.md` - Storage backend implementation\n- `ltx-compaction-specialist.md` - LTX format and compaction\n- `test-engineer.md` - Testing strategies\n- `performance-optimizer.md` - Performance optimization\n\n### Commands (.claude/commands/)\n\n- `/analyze-ltx` - Analyze LTX file structure\n- `/debug-ipc` - Debug IPC Unix socket issues\n- `/debug-wal` - Debug WAL replication issues\n- `/test-compaction` - Test compaction scenarios\n- `/trace-replication` - Trace replication flow\n- `/validate-replica` - Validate replica client\n- `/add-storage-backend` - Create new storage backend\n- `/fix-common-issues` - Diagnose common problems\n- `/run-comprehensive-tests` - Execute full test suite\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","GEMINI.md":"# GEMINI.md - Gemini Code Assist Configuration\n\nGemini-specific configuration for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Before Contributing\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n\n## File Exclusions\n\nCheck `.aiexclude` for patterns of files that should not be shared with Gemini.\n\n## Gemini Strengths for This Project\n\n- **Test generation** - Creating comprehensive test suites\n- **Documentation** - Generating and updating docs\n- **Code review** - Identifying issues and security concerns\n- **Local codebase awareness** - Enable for full repository understanding\n\n## Documentation\n\nLoad as needed:\n\n- [docs/PATTERNS.md](docs/PATTERNS.md) - Code patterns when writing code\n- [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) - For WAL/page work\n- [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) - For test generation\n\n## Critical Rules\n\n- **Lock page at 1GB** - Skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","llms.txt":"# Litestream\n\nDisaster recovery tool for SQLite. Replicates WAL changes to S3, GCS, Azure, SFTP, or local filesystem.\n\n## Quick Start for AI Contributors\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n4. Show investigation evidence in PRs\n\n## PR Checklist\n\n- [ ] Evidence of problem (logs, file patterns)\n- [ ] Clear scope (what PR does/doesn't do)\n- [ ] Runnable test commands\n- [ ] Race detector tested (`go test -race`)\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [AGENTS.md](AGENTS.md) | Project overview, critical rules |\n| [AI_PR_GUIDE.md](AI_PR_GUIDE.md) | PR templates, common mistakes |\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, 1GB lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Storage backends |\n\n## Core Files\n\n| File | Purpose |\n|------|---------|\n| `db.go` | Database monitoring, WAL, checkpoints |\n| `replica.go` | Replication management |\n| `store.go` | Multi-database coordination |\n| `replica_client.go` | Storage backend interface |\n\n## Storage Backends\n\n- `s3/replica_client.go` - AWS S3\n- `gs/replica_client.go` - Google Cloud Storage\n- `abs/replica_client.go` - Azure Blob Storage\n- `sftp/replica_client.go` - SFTP\n- `file/replica_client.go` - Local filesystem\n- `nats/replica_client.go` - NATS JetStream\n\n## Critical Concepts\n\n- **Lock page at 1GB** - Always skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Single replica per DB** - One destination per database\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Build\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n"},"files":{"AGENTS.md":"# AGENTS.md - Litestream AI Agent Guide\n\nLitestream is a disaster recovery tool for SQLite that runs as a background process, monitors the WAL, converts changes to immutable LTX files, and replicates them to cloud storage. It uses `modernc.org/sqlite` (pure Go, no CGO required).\n\n## Before You Start\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) for contribution requirements\n2. Check [CONTRIBUTING.md](CONTRIBUTING.md) for what we accept (bug fixes welcome, features need discussion)\n3. Review recent PRs for current patterns\n\n## Critical Rules\n\n- **Lock page at 1GB**: SQLite reserves page at 0x40000000. Always skip it. See [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md)\n- **LTX files are immutable**: Never modify after creation. See [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md)\n- **Single replica per database**: Each DB replicates to exactly one destination\n- **Use `litestream ltx`**: Not `litestream wal` (deprecated)\n- **Use `litestream reset`**: Clears corrupted local LTX state for a database. See `cmd/litestream/reset.go`\n- **`auto-recover` config**: Replica option that automatically resets local state on LTX errors. Disabled by default. See `replica.go`\n- **Retention enabled by default**: `Store.RetentionEnabled` is `true` by default. Disable only when cloud lifecycle policies handle cleanup. See `store.go`\n- **IPC socket disabled by default**: Control socket is off by default. Enable with `socket.enabled: true` in config. See `server.go`\n- **`$PID` config expansion**: Config files support `$PID` to expand to the current process ID, plus standard `$ENV_VAR` expansion. See `cmd/litestream/main.go`\n- **`litestream ltx -level`**: Use `-level 0`–`9` or `-level all` to inspect specific compaction levels. See `cmd/litestream/ltx.go`\n- **Return errors, don't log them**: Always return errors to callers. Never `log.Printf(err)` and continue — this silently hides failures in a disaster recovery tool. Only use DEBUG log for best-effort operations where failure doesn't affect correctness and a valid fallback exists (e.g., reading SHM mxFrame optimization hint). See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling)\n\n## Layer Boundaries\n\n| Layer | File | Responsibility |\n|-------|------|----------------|\n| DB | `db.go` | Database state, restoration, WAL monitoring, library API (`SyncStatus`, `SyncAndWait`, `EnsureExists`) |\n| Replica | `replica.go` | Replication mechanics only |\n| Storage | `**/replica_client.go` | Backend implementations (includes `ReplicaClientV3` for v0.3.x restore) |\n| IPC | `server.go` | Unix socket control API (register/unregister, /txid, pprof) |\n| Leasing | `leaser.go`, `s3/leaser.go` | Distributed lease acquisition via conditional writes |\n\nDatabase state logic belongs in DB layer, not Replica layer.\n\n## Quick Reference\n\n**Build:**\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\n```\n\n**Code quality:**\n\n```bash\npre-commit run --all-files\n```\n\n## Documentation\n\n| Document | When to Read |\n|----------|--------------|\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Deep component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Adding storage backends |\n| [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) | Provider-specific S3/cloud configs |\n\n## Checklist\n\nBefore submitting changes:\n\n- [ ] Read relevant docs above\n- [ ] Follow patterns in [docs/PATTERNS.md](docs/PATTERNS.md)\n- [ ] Test with race detector (`go test -race`)\n- [ ] Run `pre-commit run --all-files`\n- [ ] For page iteration: test with >1GB databases\n- [ ] Show investigation evidence in PR (see [AI_PR_GUIDE.md](AI_PR_GUIDE.md))\n","CLAUDE.md":"# CLAUDE.md - Claude Code Configuration\n\nClaude-specific optimizations for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Critical Coding Rules\n\n- **Always return errors, never log and continue.** The only exception is DEBUG logging for best-effort operations that don't affect correctness. This is the #1 cause of PR review feedback. See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling) for the full decision framework.\n\n## Context Window\n\nWith Claude's large context window, load documentation as needed:\n\n- Start with [AGENTS.md](AGENTS.md) for overview and checklist\n- Load [docs/PATTERNS.md](docs/PATTERNS.md) when writing code\n- Load [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) for WAL/page work\n- Load [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) for storage backend configs\n\n## Claude-Specific Resources\n\n### Specialized Agents (.claude/agents/)\n\n- `sqlite-expert.md` - SQLite WAL and page management\n- `replica-client-developer.md` - Storage backend implementation\n- `ltx-compaction-specialist.md` - LTX format and compaction\n- `test-engineer.md` - Testing strategies\n- `performance-optimizer.md` - Performance optimization\n\n### Commands (.claude/commands/)\n\n- `/analyze-ltx` - Analyze LTX file structure\n- `/debug-ipc` - Debug IPC Unix socket issues\n- `/debug-wal` - Debug WAL replication issues\n- `/test-compaction` - Test compaction scenarios\n- `/trace-replication` - Trace replication flow\n- `/validate-replica` - Validate replica client\n- `/add-storage-backend` - Create new storage backend\n- `/fix-common-issues` - Diagnose common problems\n- `/run-comprehensive-tests` - Execute full test suite\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","GEMINI.md":"# GEMINI.md - Gemini Code Assist Configuration\n\nGemini-specific configuration for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Before Contributing\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n\n## File Exclusions\n\nCheck `.aiexclude` for patterns of files that should not be shared with Gemini.\n\n## Gemini Strengths for This Project\n\n- **Test generation** - Creating comprehensive test suites\n- **Documentation** - Generating and updating docs\n- **Code review** - Identifying issues and security concerns\n- **Local codebase awareness** - Enable for full repository understanding\n\n## Documentation\n\nLoad as needed:\n\n- [docs/PATTERNS.md](docs/PATTERNS.md) - Code patterns when writing code\n- [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) - For WAL/page work\n- [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) - For test generation\n\n## Critical Rules\n\n- **Lock page at 1GB** - Skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","llms.txt":"# Litestream\n\nDisaster recovery tool for SQLite. Replicates WAL changes to S3, GCS, Azure, SFTP, or local filesystem.\n\n## Quick Start for AI Contributors\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n4. Show investigation evidence in PRs\n\n## PR Checklist\n\n- [ ] Evidence of problem (logs, file patterns)\n- [ ] Clear scope (what PR does/doesn't do)\n- [ ] Runnable test commands\n- [ ] Race detector tested (`go test -race`)\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [AGENTS.md](AGENTS.md) | Project overview, critical rules |\n| [AI_PR_GUIDE.md](AI_PR_GUIDE.md) | PR templates, common mistakes |\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, 1GB lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Storage backends |\n\n## Core Files\n\n| File | Purpose |\n|------|---------|\n| `db.go` | Database monitoring, WAL, checkpoints |\n| `replica.go` | Replication management |\n| `store.go` | Multi-database coordination |\n| `replica_client.go` | Storage backend interface |\n\n## Storage Backends\n\n- `s3/replica_client.go` - AWS S3\n- `gs/replica_client.go` - Google Cloud Storage\n- `abs/replica_client.go` - Azure Blob Storage\n- `sftp/replica_client.go` - SFTP\n- `file/replica_client.go` - Local filesystem\n- `nats/replica_client.go` - NATS JetStream\n\n## Critical Concepts\n\n- **Lock page at 1GB** - Always skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Single replica per DB** - One destination per database\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Build\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - Litestream AI Agent Guide\n\nLitestream is a disaster recovery tool for SQLite that runs as a background process, monitors the WAL, converts changes to immutable LTX files, and replicates them to cloud storage. It uses `modernc.org/sqlite` (pure Go, no CGO required).\n\n## Before You Start\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) for contribution requirements\n2. Check [CONTRIBUTING.md](CONTRIBUTING.md) for what we accept (bug fixes welcome, features need discussion)\n3. Review recent PRs for current patterns\n\n## Critical Rules\n\n- **Lock page at 1GB**: SQLite reserves page at 0x40000000. Always skip it. See [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md)\n- **LTX files are immutable**: Never modify after creation. See [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md)\n- **Single replica per database**: Each DB replicates to exactly one destination\n- **Use `litestream ltx`**: Not `litestream wal` (deprecated)\n- **Use `litestream reset`**: Clears corrupted local LTX state for a database. See `cmd/litestream/reset.go`\n- **`auto-recover` config**: Replica option that automatically resets local state on LTX errors. Disabled by default. See `replica.go`\n- **Retention enabled by default**: `Store.RetentionEnabled` is `true` by default. Disable only when cloud lifecycle policies handle cleanup. See `store.go`\n- **IPC socket disabled by default**: Control socket is off by default. Enable with `socket.enabled: true` in config. See `server.go`\n- **`$PID` config expansion**: Config files support `$PID` to expand to the current process ID, plus standard `$ENV_VAR` expansion. See `cmd/litestream/main.go`\n- **`litestream ltx -level`**: Use `-level 0`–`9` or `-level all` to inspect specific compaction levels. See `cmd/litestream/ltx.go`\n- **Return errors, don't log them**: Always return errors to callers. Never `log.Printf(err)` and continue — this silently hides failures in a disaster recovery tool. Only use DEBUG log for best-effort operations where failure doesn't affect correctness and a valid fallback exists (e.g., reading SHM mxFrame optimization hint). See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling)\n\n## Layer Boundaries\n\n| Layer | File | Responsibility |\n|-------|------|----------------|\n| DB | `db.go` | Database state, restoration, WAL monitoring, library API (`SyncStatus`, `SyncAndWait`, `EnsureExists`) |\n| Replica | `replica.go` | Replication mechanics only |\n| Storage | `**/replica_client.go` | Backend implementations (includes `ReplicaClientV3` for v0.3.x restore) |\n| IPC | `server.go` | Unix socket control API (register/unregister, /txid, pprof) |\n| Leasing | `leaser.go`, `s3/leaser.go` | Distributed lease acquisition via conditional writes |\n\nDatabase state logic belongs in DB layer, not Replica layer.\n\n## Quick Reference\n\n**Build:**\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\n```\n\n**Code quality:**\n\n```bash\npre-commit run --all-files\n```\n\n## Documentation\n\n| Document | When to Read |\n|----------|--------------|\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Deep component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Adding storage backends |\n| [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) | Provider-specific S3/cloud configs |\n\n## Checklist\n\nBefore submitting changes:\n\n- [ ] Read relevant docs above\n- [ ] Follow patterns in [docs/PATTERNS.md](docs/PATTERNS.md)\n- [ ] Test with race detector (`go test -race`)\n- [ ] Run `pre-commit run --all-files`\n- [ ] For page iteration: test with >1GB databases\n- [ ] Show investigation evidence in PR (see [AI_PR_GUIDE.md](AI_PR_GUIDE.md))\n","category":"root","tokens":981},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md - Claude Code Configuration\n\nClaude-specific optimizations for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Critical Coding Rules\n\n- **Always return errors, never log and continue.** The only exception is DEBUG logging for best-effort operations that don't affect correctness. This is the #1 cause of PR review feedback. See [docs/PATTERNS.md](docs/PATTERNS.md#error-handling) for the full decision framework.\n\n## Context Window\n\nWith Claude's large context window, load documentation as needed:\n\n- Start with [AGENTS.md](AGENTS.md) for overview and checklist\n- Load [docs/PATTERNS.md](docs/PATTERNS.md) when writing code\n- Load [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) for WAL/page work\n- Load [docs/PROVIDER_COMPATIBILITY.md](docs/PROVIDER_COMPATIBILITY.md) for storage backend configs\n\n## Claude-Specific Resources\n\n### Specialized Agents (.claude/agents/)\n\n- `sqlite-expert.md` - SQLite WAL and page management\n- `replica-client-developer.md` - Storage backend implementation\n- `ltx-compaction-specialist.md` - LTX format and compaction\n- `test-engineer.md` - Testing strategies\n- `performance-optimizer.md` - Performance optimization\n\n### Commands (.claude/commands/)\n\n- `/analyze-ltx` - Analyze LTX file structure\n- `/debug-ipc` - Debug IPC Unix socket issues\n- `/debug-wal` - Debug WAL replication issues\n- `/test-compaction` - Test compaction scenarios\n- `/trace-replication` - Trace replication flow\n- `/validate-replica` - Validate replica client\n- `/add-storage-backend` - Create new storage backend\n- `/fix-common-issues` - Diagnose common problems\n- `/run-comprehensive-tests` - Execute full test suite\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","category":"root","tokens":448},{"name":"GEMINI.md","path":"GEMINI.md","title":"GEMINI.md","content":"# GEMINI.md - Gemini Code Assist Configuration\n\nGemini-specific configuration for Litestream. See [AGENTS.md](AGENTS.md) for project documentation.\n\n## Before Contributing\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n\n## File Exclusions\n\nCheck `.aiexclude` for patterns of files that should not be shared with Gemini.\n\n## Gemini Strengths for This Project\n\n- **Test generation** - Creating comprehensive test suites\n- **Documentation** - Generating and updating docs\n- **Code review** - Identifying issues and security concerns\n- **Local codebase awareness** - Enable for full repository understanding\n\n## Documentation\n\nLoad as needed:\n\n- [docs/PATTERNS.md](docs/PATTERNS.md) - Code patterns when writing code\n- [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) - For WAL/page work\n- [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) - For test generation\n\n## Critical Rules\n\n- **Lock page at 1GB** - Skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Quick Commands\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","category":"root","tokens":333},{"name":"llms.txt","path":"llms.txt","title":"llms.txt","content":"# Litestream\n\nDisaster recovery tool for SQLite. Replicates WAL changes to S3, GCS, Azure, SFTP, or local filesystem.\n\n## Quick Start for AI Contributors\n\n1. Read [AI_PR_GUIDE.md](AI_PR_GUIDE.md) - PR quality requirements\n2. Read [AGENTS.md](AGENTS.md) - Project overview and checklist\n3. Check [CONTRIBUTING.md](CONTRIBUTING.md) - What we accept\n4. Show investigation evidence in PRs\n\n## PR Checklist\n\n- [ ] Evidence of problem (logs, file patterns)\n- [ ] Clear scope (what PR does/doesn't do)\n- [ ] Runnable test commands\n- [ ] Race detector tested (`go test -race`)\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [AGENTS.md](AGENTS.md) | Project overview, critical rules |\n| [AI_PR_GUIDE.md](AI_PR_GUIDE.md) | PR templates, common mistakes |\n| [docs/PATTERNS.md](docs/PATTERNS.md) | Code patterns and anti-patterns |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Component details |\n| [docs/SQLITE_INTERNALS.md](docs/SQLITE_INTERNALS.md) | WAL format, 1GB lock page |\n| [docs/LTX_FORMAT.md](docs/LTX_FORMAT.md) | Replication format |\n| [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) | Test strategies |\n| [docs/REPLICA_CLIENT_GUIDE.md](docs/REPLICA_CLIENT_GUIDE.md) | Storage backends |\n\n## Core Files\n\n| File | Purpose |\n|------|---------|\n| `db.go` | Database monitoring, WAL, checkpoints |\n| `replica.go` | Replication management |\n| `store.go` | Multi-database coordination |\n| `replica_client.go` | Storage backend interface |\n\n## Storage Backends\n\n- `s3/replica_client.go` - AWS S3\n- `gs/replica_client.go` - Google Cloud Storage\n- `abs/replica_client.go` - Azure Blob Storage\n- `sftp/replica_client.go` - SFTP\n- `file/replica_client.go` - Local filesystem\n- `nats/replica_client.go` - NATS JetStream\n\n## Critical Concepts\n\n- **Lock page at 1GB** - Always skip page at 0x40000000\n- **LTX files are immutable** - Never modify after creation\n- **Single replica per DB** - One destination per database\n- **Layer boundaries** - DB handles state, Replica handles replication\n\n## Build\n\n```bash\ngo build -o bin/litestream ./cmd/litestream\ngo test -race -v ./...\npre-commit run --all-files\n```\n","category":"root","tokens":530}]}