tools: move CLI entry points to tools/cmd/ for consistent layout

Author: xaionaro@dx.center

CLAUDE.md

@@ -0,0 +1,30 @@
+# Project Instructions
+
+## Code Generation Pipeline
+
+This project uses a three-stage code generation pipeline (see README.md for details):
+
+1. **Stage 1 (`make specs`)**: `tools/cmd/specgen` + `c2ffi` extracts structured YAML specs from C headers into `spec/generated/`.
+2. **Stage 2 (`make capi`)**: `tools/cmd/capigen` generates raw CGo bindings in `capi/{module}/` from specs + manifests.
+3. **Stage 3 (`make idiomatic`)**: `tools/cmd/idiomgen` generates idiomatic Go packages from specs + overlays + templates.
+
+## Rules
+
+### Never edit generated bindings directly
+
+All files under `capi/{module}/` and `{module}/` (top-level idiomatic packages like `looper/`, `camera/`, `sensor/`, etc.) are generated. They contain `// Code generated by ... DO NOT EDIT.` headers.
+
+**Never edit these files.** Instead, modify the appropriate source:
+
+- To change **raw CGo bindings** (`capi/`): edit `capi/manifests/{module}.yaml` or `tools/pkg/capigen/`. Nobody else writes to
+  `capi/` but `capigen`!
+- To change **idiomatic Go API shape** (type names, method receivers, error handling): edit `spec/overlays/{module}.yaml`.
+- To change **generated code patterns** (struct layout, constructor/destructor shape, bridge code): edit `templates/*.tmpl`.
+- To change **spec extraction logic**: edit `tools/pkg/specgen/`.
+- To change **idiomatic generation logic**: edit `tools/pkg/idiomgen/` or `tools/pkg/overlaymodel/`.
+
+After modifying sources, regenerate with `make idiomatic` (or `make regen` for a full rebuild).
+
+### Examples must use only idiomatic bindings
+
+Code in `examples/` must import only the idiomatic top-level packages (e.g., `github.com/xaionaro-go/ndk/looper`, `github.com/xaionaro-go/ndk/camera`). Never import `capi/` packages or use `import "C"` / CGo directly in examples. If the idiomatic package is missing a needed function or type, add it via the overlay and regenerate rather than falling back to capi.

Makefile

@@ -27,7 +27,7 @@ specs:
 		manifest="capi/manifests/$$m.yaml"; \
 		[ -f "$$manifest" ] || continue; \
 		echo "specgen $$m (c2ffi)"; \
-		go run ./tools/specgen \
+		go run ./tools/cmd/specgen \
 			-manifest "$$manifest" \
 			-ndk-include "$(NDK_SYSROOT)" \
 			-c2ffi-bin "$(C2FFI_BIN)" \
@@ -42,7 +42,7 @@ capi:
 		[ -f "$$manifest" ] || continue; \
 		[ -f "$$spec" ] || continue; \
 		echo "capigen $$m"; \
-		go run ./tools/capigen \
+		go run ./tools/cmd/capigen \
 			-spec "$$spec" \
 			-manifest "$$manifest" \
 			-out "capi/$$m/"; \
@@ -53,7 +53,7 @@ specs-fixtures:
 	@for m in $(FIXTURE_MODULES); do \
 		case $$m in simple|edgecases) continue;; esac; \
 		echo "specgen $$m (fixture)"; \
-		go run ./tools/specgen \
+		go run ./tools/cmd/specgen \
 			-module $$m \
 			-pkg tools/pkg/specgen/testdata/$$m \
 			-out spec/generated/$$m.yaml; \
@@ -68,7 +68,7 @@ idiomatic:
 		goname=$$(grep 'go_name:' "$$overlay" | head -1 | awk '{print $$2}'); \
 		[ -z "$$goname" ] && goname="$$m"; \
 		echo "idiomgen $$m -> $$goname/"; \
-		go run ./tools/idiomgen \
+		go run ./tools/cmd/idiomgen \
 			-spec "$$spec" \
 			-overlay "$$overlay" \
 			-templates templates/ \

README.md

@@ -295,7 +295,7 @@ flowchart TD
 
 ### Stage 1: Spec Extraction (`make specs`)
 
-**Tool**: `tools/specgen` + `c2ffi` (external)
+**Tool**: `tools/cmd/specgen` + `c2ffi` (external)
 
 Parses NDK C headers via c2ffi and extracts a structured YAML specification containing types, enums, functions, callbacks, and structs.
 
@@ -344,7 +344,7 @@ functions:
 
 ### Stage 2: Raw CGo Bindings (`make capi`)
 
-**Tool**: `tools/capigen` (in-repo)
+**Tool**: `tools/cmd/capigen` (in-repo)
 
 Reads the generated spec YAML and manifest YAML, then produces raw CGo wrapper packages with type aliases, function wrappers, callback proxies, and enum constants.
 
@@ -360,7 +360,7 @@ Reads the generated spec YAML and manifest YAML, then produces raw CGo wrapper p
 
 ### Stage 3: Idiomatic Go Generation (`make idiomatic`)
 
-**Tool**: `tools/idiomgen` (in-repo)
+**Tool**: `tools/cmd/idiomgen` (in-repo)
 
 Merges the generated spec with a hand-written overlay and renders Go templates to produce the final user-facing packages.
 
@@ -513,10 +513,12 @@ flowchart TD
 .
 ├── Makefile                      # Build orchestration
 ├── tools/
-│   ├── specgen/                  # Stage 1: spec extraction via c2ffi
-│   ├── capigen/                  # Stage 2: CGo wrapper generator
-│   ├── idiomgen/                 # Stage 3: idiomatic Go generator
-│   ├── headerspec/               # Standalone header spec extraction tool
+│   ├── cmd/
+│   │   ├── specgen/              # Stage 1: spec extraction via c2ffi
+│   │   ├── capigen/              # Stage 2: CGo wrapper generator
+│   │   ├── idiomgen/             # Stage 3: idiomatic Go generator
+│   │   ├── headerspec/           # Standalone header spec extraction tool
+│   │   └── ndk-build/            # APK packaging tool
 │   └── pkg/
 │       ├── c2ffi/                # c2ffi invocation and JSON→spec conversion
 │       ├── capigen/              # CGo code generation from spec + manifest