│   ├── mcp.go                 # MCP server (only file with MCP SDK)
│   ├── import.go, sql.go      # CLI commands

│   ├── skraak.duckdb          # Production ⚠️
│   └── test.duckdb            # Test ✅
├── tools/                     # 11 tools (MCP-free)
│   ├── time.go, sql.go        # Read tools (2)
│   ├── dataset.go, location.go, cluster.go, pattern.go  # Write tools (4)
│   ├── import_{files,file,ml_selections,unstructured}.go, bulk_file_import.go  # Import (5)

├── tools/                     # tools (MCP-free)

│   ├── cluster_import.go      # Centralized import logic (553 lines)
│   ├── validation.go          # Input validation
│   ├── astronomical.go        # Solar/civil night, moon phase
│   ├── audiomoth_parser.go   # AudioMoth WAV comment parsing
│   ├── filename_parser.go    # Filename timestamp parsing + timezone
│   ├── selection_parser.go   # ML selection parsing
│   ├── wav_metadata.go       # WAV header parsing
│   ├── xxh64.go              # XXH64 hash
│   └── *_test.go             # 170+ tests, 91.5% coverage

---
## Available Tools
### Read Tools (2)
- `get_current_time` - System time with timezone
- `execute_sql` - Generic SQL SELECT queries (supports JOINs, aggregates, CTEs)
  - Security: Read-only database + keyword validation
  - Limits: Default 1000 rows (max 10000)
### Write Tools (4)
- `create_or_update_dataset` - Omit `id` to create, provide `id` to update
- `create_or_update_location` - GPS + timezone
- `create_or_update_cluster` - Recording groups
- `create_or_update_pattern` - Record/sleep cycles
### Import Tools (4 MCP tools, 1 CLI-only)
**Dataset type requirements:**
- Structured imports: `import_audio_files`, `bulk_file_import`, `import_ml_selections`
- Unstructured imports: `import_unstructured`
**MCP Tools:**
- `import_audio_files` - Batch import folder → cluster
- `bulk_file_import` - CSV-driven multi-location import
- `import_ml_selections` - ML detection folders (`Clips_{filter}_{date}/Species/CallType/*.wav`)
**CLI-only:**
- `import file` - Single file import (use `skraak import file --db ... --path /path/to/file.wav`)
- `import_unstructured` - No location/cluster hierarchy
**Import pipeline:**
- AudioMoth comment → filename → file modtime (timestamp fallback chain)
- XXH64 hash, metadata extraction, astronomical calculations
- Centralized logic in `utils/cluster_import.go`
## Resources & Prompts

### Resources
- `schema://full` - Complete 348-line schema
- `schema://table/{table_name}` - Individual table definitions
### Prompts
Six SQL workflow templates:
1. `query_active_datasets` - Dataset querying
2. `explore_database_schema` - Schema exploration
3. `explore_location_hierarchy` - Hierarchy navigation
4. `query_location_data` - Location analysis
5. `analyze_cluster_files` - File analysis
6. `system_status_check` - Health check
All teach SQL patterns with examples (SELECT, JOIN, GROUP BY, aggregates).

## SQL 
**Best practices:** `WHERE active = true`, use parameterized queries for IDs, use `LEFT JOIN` to include parent records, use `COUNT(DISTINCT)` when joining.
---

# Entity management
./skraak create dataset --db ./db/test.duckdb --name "Test" --type unstructured
./skraak create location --db ./db/test.duckdb --dataset abc123 --name "Site A" --lat -36.85 --lon 174.76 --timezone Pacific/Auckland
./skraak create cluster --db ./db/test.duckdb --dataset abc123 --location loc456 --name "2024-01" --sample-rate 250000
# Import
./skraak import file --db ./db/test.duckdb --dataset abc123 --location loc456 --cluster clust789 --path /path/to/file.wav
./skraak import folder --db ./db/test.duckdb --dataset abc123 --location loc456 --cluster clust789 --path /path/to/folder
./skraak import bulk --db ./db/test.duckdb --dataset abc123 --csv import.csv --log progress.log
# Utilities
./skraak xxhash --file recording.wav
./skraak metadata --file recording.wav
./skraak time

---
## Event Log

All mutating SQL operations logged to `<database>.events.jsonl` for backup synchronization.
**What's logged:**
- INSERT, UPDATE, DELETE operations
- On successful commit only (rollbacks discarded)
**Replay on backup:**
```bash
skraak replay events --db backup.duckdb --log skraak.duckdb.events.jsonl
skraak replay events --db backup.duckdb --log events.jsonl --dry-run
skraak replay events --db backup.duckdb --log events.jsonl --last 10
```
**Key files:**
- `db/tx_logger.go` - Transaction wrapper for logging
- `cmd/replay.go` - Replay CLI command
---
## Dataset Export
Export a dataset with all related data to a new DuckDB database.
```bash
skraak export dataset --db skraak.duckdb --id abc123 --output export.duckdb
skraak export dataset --db skraak.duckdb --id abc123 --output export.duckdb --dry-run
```
**Use cases:** Collaboration, testing (small DB vs 1.5 GB), archival
**Key files:**
- `tools/export.go` - Export logic with table manifest
- `db/schema.go` - Schema utilities (DDL extraction, FK ordering)
---
## Common Issues
- **Query too large:** Use `LIMIT` (default 1000, max 10000)
- **Server exits immediately:** Normal - runs in stdio mode (waits for MCP input)
- **SQL syntax error:** use schema resources
---
## Claude Desktop Configuration
`~/.config/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "skraak": {
      "command": "/home/david/go/src/skraak/skraak",
      "args": ["mcp", "--db", "/home/david/go/src/skraak/db/skraak.duckdb"]
    }
  }
}
```
Restart Claude Desktop after changes.