If called by `cmd/`, it goes in `tools/`. If called by `tools/`, it goes in `utils/`.

**Dependency rule:** packages may only import packages below them in this list:

Enforced by `depguard` in `.golangci.yml`. A package may only import from packages **below** it:

main.go          → CLI dispatcher (import | sql | dataset | ...)
cmd/*.go         → CLI commands (flags → tools → JSON output)
tools/*.go       → CLI tools: sql, export, cluster, dataset, location, pattern, time, prepend
tools/calls/     → Call processing (filesystem .data/WAV, NO database access)
tools/import/    → Import operations (bulk, file, files, segments, unstructured; defines own DB interfaces)
tui/             → Interactive classify UI
db/              → Database connection + types + transactions (defines local mutator interface)
mapping/         → Mapping file types + loader (leaf package, shared by tools/calls/ and tools/import/)
utils/*.go       → Reusable helpers (leaf package, no database/sql import, no `*Input`/`*Output` structs)

main.go
cmd/             → tools, tools/calls, tools/import, tui
tools/           → db, audio, wav, spectrogram, astro, mapping, utils
tools/calls/     → db, audio, wav, spectrogram, mapping, utils   (NO DB access in practice)
tools/import/    → db, wav, astro, mapping, utils                (defines own Mutator/Reader)
tui/             → audio, wav, spectrogram, utils                (NO db, NO cmd)
db/              → wav (GainLevel only), utils (Placeholders only)
spectrogram/     → audio, wav
wav/             → audio, astro, utils
audio/           → (stdlib + go-dsp)
astro/           → (stdlib + suncalc)
mapping/         → (stdlib)
utils/           → (stdlib only — true leaf)

**DB interface convention:** Each consumer defines its own minimal interface (Mutator, Reader, MappingQuerier, etc.) using `*Context` method variants. No god-interfaces in `db/`. Two near-identical interfaces in two packages beats the wrong abstraction.

**DB interface convention:** Each consumer defines its own minimal interface (`Mutator`, `Reader`, `Querier`, etc.) using `*Context` method variants only. No god-interfaces in `db/`. Two near-identical interfaces in two packages beats the wrong abstraction.
**`utils/` invariants:** no `database/sql` import, no `skraak/*` import, no `*Input`/`*Output` structs.

    # - depguard

    - depguard

    # depguard:
    #   rules:
    #     # Package dependency rules — see CLAUDE.md "Package Organization"
    #     # Packages may only import packages below them in the list:
    #     #   cmd → tools, tools/calls, tools/import, tui, utils, db
    #     #   tools/calls → utils, db
    #     #   tools/import → utils, db
    #     #   tools → utils, db
    #     #   tui → tools/calls, utils
    #     #   db → utils
    #     #   utils → (nothing — leaf package)
    #     utils:
    #       files:
    #         - "**/utils/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "utils is the leaf package"
    #         - pkg: "skraak/tools"
    #           desc: "utils is the leaf package"
    #         - pkg: "skraak/tui"
    #           desc: "utils is the leaf package"
    #         - pkg: "skraak/db"
    #           desc: "utils is the leaf package"
    #     db:
    #       files:
    #         - "**/db/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "db may only import utils"
    #         - pkg: "skraak/tools"
    #           desc: "db may only import utils"
    #         - pkg: "skraak/tui"
    #           desc: "db may only import utils"
    #     tui:
    #       files:
    #         - "**/tui/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "tui must not import cmd"
    #         - pkg: "skraak/db"
    #           desc: "tui must not import db"
    #         - pkg: "skraak/tools$"
    #           desc: "tui must import from tools/calls, not tools"
    #     calls:
    #       files:
    #         - "**/tools/calls/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "tools/calls must not import cmd"
    #         - pkg: "skraak/tools"
    #           desc: "tools/calls must not import parent package"
    #         - pkg: "skraak/tui"
    #           desc: "tools/calls must not import tui"
    #     import:
    #       files:
    #         - "**/tools/import/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "tools/import must not import cmd"
    #         - pkg: "skraak/tools"
    #           desc: "tools/import must not import parent package"
    #         - pkg: "skraak/tui"
    #           desc: "tools/import must not import tui"
    #     tools:
    #       files:
    #         - "**/tools/*.go"
    #       deny:
    #         - pkg: "skraak/cmd"
    #           desc: "tools must not import cmd"
    #         - pkg: "skraak/tui"
    #           desc: "tools must not import tui"
    #         - pkg: "skraak/tools/calls"
    #           desc: "tools must not import tools/calls (sub-package)"
    #         - pkg: "skraak/tools/import"
    #           desc: "tools must not import tools/import (sub-package)"

    depguard:
      rules:
        # Package dependency rules — see CLAUDE.md "Package Organization".
        # A package may only import packages BELOW it in the layered graph:
        #   cmd → tools, tools/calls, tools/import, tui, db, audio, wav, spectrogram, astro, mapping, utils
        #   tools/calls → db, audio, wav, spectrogram, mapping, utils
        #   tools/import → db, wav, astro, mapping, utils
        #   tools → db, audio, wav, spectrogram, astro, mapping, utils
        #   tui  → audio, wav, spectrogram, utils
        #   db   → wav, utils
        #   spectrogram → audio, wav
        #   wav  → audio, astro, utils
        #   audio, astro, mapping, utils → (no skraak/* imports)
        utils:
          files: ["**/utils/*.go"]
          deny:
            - { pkg: "skraak/", desc: "utils is the leaf package — no skraak/* imports" }
        mapping:
          files: ["**/mapping/*.go"]
          deny:
            - { pkg: "skraak/", desc: "mapping is a leaf package — no skraak/* imports" }
        audio:
          files: ["**/audio/*.go"]
          deny:
            - { pkg: "skraak/", desc: "audio is a leaf package — no skraak/* imports" }
        astro:
          files: ["**/astro/*.go"]
          deny:
            - { pkg: "skraak/", desc: "astro is a leaf package — no skraak/* imports" }
        wav:
          files: ["**/wav/*.go"]
          deny:
            - { pkg: "skraak/cmd",         desc: "wav must not import cmd" }
            - { pkg: "skraak/tools",       desc: "wav must not import tools" }
            - { pkg: "skraak/tui",         desc: "wav must not import tui" }
            - { pkg: "skraak/db",          desc: "wav must not import db" }
            - { pkg: "skraak/spectrogram", desc: "wav must not import spectrogram" }
        spectrogram:
          files: ["**/spectrogram/*.go"]
          deny:
            - { pkg: "skraak/cmd",     desc: "spectrogram must not import cmd" }
            - { pkg: "skraak/tools",   desc: "spectrogram must not import tools" }
            - { pkg: "skraak/tui",     desc: "spectrogram must not import tui" }
            - { pkg: "skraak/db",      desc: "spectrogram must not import db" }
            - { pkg: "skraak/utils",   desc: "spectrogram should only depend on audio + wav" }
            - { pkg: "skraak/astro",   desc: "spectrogram should only depend on audio + wav" }
            - { pkg: "skraak/mapping", desc: "spectrogram should only depend on audio + wav" }
        db:
          files: ["**/db/*.go"]
          deny:
            - { pkg: "skraak/cmd",         desc: "db may only import wav + utils" }
            - { pkg: "skraak/tools",       desc: "db may only import wav + utils" }
            - { pkg: "skraak/tui",         desc: "db may only import wav + utils" }
            - { pkg: "skraak/spectrogram", desc: "db may only import wav + utils" }
        tui:
          files: ["**/tui/*.go"]
          deny:
            - { pkg: "skraak/cmd",          desc: "tui must not import cmd" }
            - { pkg: "skraak/db",           desc: "tui must not import db" }
            - { pkg: "skraak/tools$",       desc: "tui must import from tools/calls, not tools" }
            - { pkg: "skraak/tools/import", desc: "tui must not import tools/import" }
        calls:
          files: ["**/tools/calls/*.go"]
          deny:
            - { pkg: "skraak/cmd",          desc: "tools/calls must not import cmd" }
            - { pkg: "skraak/tools$",       desc: "tools/calls must not import parent tools package" }
            - { pkg: "skraak/tools/import", desc: "tools/calls must not import tools/import (sibling)" }
            - { pkg: "skraak/tui",          desc: "tools/calls must not import tui" }
        import:
          files: ["**/tools/import/*.go"]
          deny:
            - { pkg: "skraak/cmd",          desc: "tools/import must not import cmd" }
            - { pkg: "skraak/tools$",       desc: "tools/import must not import parent tools package" }
            - { pkg: "skraak/tools/calls",  desc: "tools/import must not import tools/calls (sibling)" }
            - { pkg: "skraak/tui",          desc: "tools/import must not import tui" }
        tools:
          files: ["**/tools/*.go"]
          deny:
            - { pkg: "skraak/cmd",          desc: "tools must not import cmd" }
            - { pkg: "skraak/tui",          desc: "tools must not import tui" }
            - { pkg: "skraak/tools/calls",  desc: "tools must not import tools/calls (sub-package)" }
            - { pkg: "skraak/tools/import", desc: "tools must not import tools/import (sub-package)" }