tidied up CLAUDE.md

quietlight

Apr 30, 2026, 11:36 PM

VYNOHQJWFL6ZEKFLASJAZZIHN4S3NJJECKANT7JNSXPJN3KC2DJAC

Dependencies

• [2] DS22DKV3 added shell script integration tests.
• [3] KZKLAINJ run out of space on nest, cleaned out

Change contents

• edit in CLAUDE.md at line 10
  [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`
• edit in CLAUDE.md at line 11
  [3.1195589]→[3.1195589:1195594](∅→∅)
  − ---

  −
• replacement in CLAUDE.md at line 16
  [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.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.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.1196589]→[3.1196589:1196656](∅→∅)
  − ├── cmd/ # MCP adapters + CLI commands
  [3.1196589]

  [3.1196656]
  + ├── cmd/ # CLI commands
• replacement in CLAUDE.md at line 42
  [3.1196670]→[3.1196670:1196726](∅→∅)
  − ├── tools/ # tools (MCP-free)
  [3.1196670]

  [3.1196726]
  + ├── tools/ # tools
• edit in CLAUDE.md at line 45
  [3.1196839]→[3.1196839:1196895](∅→∅)
  − ├── resources/schema.go # Schema resources
• edit in CLAUDE.md at line 57
  [3.1197033]→[3.1197033:1197098](∅→∅)
  − ### MCP Server

  − ```bash

  − ./skraak mcp --db ./db/skraak.duckdb

  − ```

  −
• edit in CLAUDE.md at line 68
  [3.1197342]→[3.1197342:1197511](∅→∅),[3.1197511]→[2.23108:23239](∅→∅),[2.23239]→[3.1197511:1197641](∅→∅),[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
  [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` |
• edit in CLAUDE.md at line 79
  [3.1197892]

  [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
• edit in CLAUDE.md at line 90
  [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**