quietlight/skraakCLI - Change VYNOHQJWFL6ZEKFLASJAZZIHN4S3NJJECKANT7JNSXPJN3KC2DJAC

tidied up CLAUDE.md

Created by quietlight on April 30, 2026

VYNOHQJWFL6ZEKFLASJAZZIHN4S3NJJECKANT7JNSXPJN3KC2DJAC

Dependencies

In channels

main

Change contents

Deletion in CLAUDE.md at line 10 [3.1194773]

B:BD[3.1195076] → [3.1195076:1195588]


---
## 🚨 Critical Database Safety
### ALWAYS Use Test Database for Testing
**CORRECT:**
```bash
cd shell_scripts
./test_sql.sh ../db/test.duckdb > test.txt 2>&1
```
- `db/skraak.duckdb` = **PRODUCTION** (1.4M files)
- `db/test.duckdb` = **TEST** (safe for testing)
- **Always specify test.duckdb explicitly**
### Testing Best Practices
- **Always pipe to file** (prevents token overflow from large output)
- Navigate to `shell_scripts/` before running tests
- Verify: `rg '"result":' test.txt | wc -l`

Deletion in CLAUDE.md at line 11 [3.1194773]
B:BD[3.1195589] → [3.1195589:1195594]
```
---
```

Replacement in CLAUDE.md at line 16 [3.1194773]

B:BD[3.1195803] → [3.1195803:1195946]

- **`tools/`** - MCP/CLI tools (one file per tool, defines input/output types)
- **`cmd/mcp.go`** - MCP adapters (only file importing MCP SDK)

[3.1195803]

[3.1195946]

- **`tools/`** - CLI tools (one file per tool, defines input/output types)

Replacement in CLAUDE.md at line 26 [3.1194773]

B:BD[3.1196121] → [3.1196121:1196264]

main.go          → CLI dispatcher (mcp | import | sql | dataset | ...)
cmd/mcp.go       → MCP server + thin adapters (ONLY MCP SDK import)

[3.1196121]

[3.1196264]

main.go          → CLI dispatcher (import | sql | dataset | ...)

Replacement in CLAUDE.md at line 28 [3.1194773]

B:BD[3.1196332] → [3.1196332:1196402]

tools/*.go       → Core logic (plain Go structs, no MCP dependency)

[3.1196332]

[3.1196402]

tools/*.go       → Core logic (plain Go structs)

Replacement in CLAUDE.md at line 40 [3.1194773]

B:BD[3.1196589] → [3.1196589:1196656]

├── cmd/                       # MCP adapters + CLI commands

[3.1196589]

[3.1196656]

├── cmd/                       # CLI commands

Replacement in CLAUDE.md at line 42 [3.1194773]
B:BD[3.1196670] → [3.1196670:1196726]
```
├── tools/                     # tools (MCP-free)
```
[3.1196670]
[3.1196726]
```
├── tools/                     # tools
```
Deletion in CLAUDE.md at line 45 [3.1194773]
B:BD[3.1196839] → [3.1196839:1196895]
```
├── resources/schema.go        # Schema resources
```
Deletion in CLAUDE.md at line 57 [3.1194773]
B:BD[3.1197033] → [3.1197033:1197098]
```
### MCP Server
```bash
./skraak mcp --db ./db/skraak.duckdb
```
```

Deletion in CLAUDE.md at line 68 [3.1194773]

B:BD[3.1197342] → [3.1197342:1197511]

B:BD[3.1197511] → [2.23108:23239]

∅:D[2.23239] → [3.1197511:1197641]

B:BD[3.1197511] → [3.1197511:1197641]


### Shell Scripts (in shell_scripts/)
All scripts default to `../db/test.duckdb`:
```bash
cd shell_scripts
./test_sql.sh ../db/test.duckdb > test.txt 2>&1 # SQL tool
./test_cluster_import.sh      # cluster_import.go integration
./test_mapping_validation.sh  # ValidateMappingAgainstDB integration
# Verify
rg '"result":' test.txt | wc -l     # Count successes
rg '"isError":true' test.txt | wc -l  # Count expected errors
```

Replacement in CLAUDE.md at line 71 [3.1194773]

B:BD[2.23282] → [2.23282:23493]

| File | Why Skipped |
|------|------------|
| `utils/audio_player.go` | Thin wrapper over `oto` (requires audio hardware). No testable logic without hardware; `Resample` already covered in `resample_test.go` |

[2.23282]

[3.1197641]

`utils/audio_player.go` is a thin wrapper over `oto` (requires audio hardware). No testable logic without hardware; `Resample` already covered in `resample_test.go` |

Insertion in CLAUDE.md at line 79 [3.1194773]

[3.1197892]

```
### Shell Scripts (in shell_scripts/)
```
# make sure db/test.duckdb available and FK's applied.
# 550 line output, beware token overflow
# runs all unit tests and shell script integration tests
make test

Insertion in CLAUDE.md at line 90 [3.1194773]

[3.1197897]

 🚨 Critical Database Safety
**ALWAYS Use Test Database for Testing**
```bash
cd shell_scripts
./test_sql.sh ../db/test.duckdb > test.txt 2>&1
```
- `db/skraak.duckdb` = **PRODUCTION**
- `db/test.duckdb` = **TEST** (safe for testing)
- **Always specify test.duckdb explicitly**