docs: point issues at Gitea origin (D15).

GitHub stays the public clone for PRs and Actions. Work board is
https://git.produktor.io/eSlider/2dph/issues.

.github/workflows/ci.yml

@@ -19,10 +19,6 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-go@v5
-        with:
-          go-version-file: go.mod
-
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
@@ -36,19 +32,23 @@ jobs:
           bash -n bin/db/psql-yq
           bash -n bin/db/ssh-tunnel
           bash -n bin/docker-entrypoint
-          bash -n bin/kb/search
 
       - name: Python unit tests (offline, vendored tools)
         run: |
           uv run python -m unittest discover -s bin/tools -t .
 
-      - name: Go tests (root module, no ladybug cgo)
+      - name: Go tests (server + watch packages)
         run: |
           go vet ./...
           go test ./... -count=1
 
-      - name: brain ranking tests (no cgo / no ladybug)
+      - name: kbsearch ranking tests (no cgo / no ladybug)
-        run: go test ./internal/brain/rank -count=1
+        working-directory: bin/kbsearch
+        run: go test ./rank -count=1
+
+      - name: Go tests (chats nested module)
+        working-directory: bin/chats
+        run: go test ./... -count=1
 
       - name: facts/audit self (lexicon consistency, no network)
         run: |

.gitignore

@@ -10,4 +10,3 @@ __pycache__/
 .env
 .secrets/
 lib-ladybug/
-go.work.local

AGENTS.md

@@ -35,10 +35,10 @@ Read first: [PLAN](PLAN.md) → [docs](docs/).
 PLAN.md       decisions + execution + open questions
 docs/         published docs
 skills/       in-project agent skills (vendored, no external links)
-bin/          self-describing tools bin/{subject}/{method}.go (shebang)
+bin/          self-describing tools bin/{subject}/{method} (shebang)
-bin/brain/    search.go, serve.go; libs in internal/brain and internal/httpapi
+bin/serve.go  async Go HTTP server entry (self-executing go run shebang)
-internal/     shared Go (brain/rank is cgo-free)
+bin/watch/    corpus watcher Go package (mtimes, no inotify deps)
-bin/watch/    corpus watcher (internal via bin/brain/watch later)
+bin/server/   async Go HTTP server (goroutines, bounded worker pool)
 bin/mail/     mail pipeline: sync (Go), import (md), index_mail (rebuild)
 bin/tools/    vendored python libs behind bin/* (kblib, yamlout, websearch)
 bin/docker-entrypoint  container entrypoint (brain index|search|serve|watch)
@@ -74,8 +74,7 @@ bin/mail/index_mail                                                     # rebuil
 ```bash
 bin/facts/audit ["self"|"facts"|"info"|"stale"]   # 2-source + staleness gate
 bin/facts/crm [--dry-run]                         # proof person↔company/company↔project (ooCRM × corpus SoT)
-bin/kb/search "query" [--repo X]                  # deprecated wrapper → bin/brain/search.go
+bin/kb/search "query" [--hop N] [--repo X]        # deduction search → YAML
-bin/brain/search.go "query" [--root facts|info]   # deduction search → YAML
 bin/md/tables                                     # what the graph holds → YAML
 bin/brain/deduce "question"                       # thinking wrapper
 ```

PLAN.md

@@ -37,7 +37,7 @@ detective method: **a fact needs ≥2 independent sources or it is
 | D11 | strong/weak | `root` column: `facts` (strong) vs `info` (weak). Answer is `confirmed` only from facts root. |
 | D12 | transactional | facts and info split by root but **written in the same Ladybug transaction (ACID)** on every write. |
 | D13 | portfolio | start graph `(Person:eslider)-[:HAS]->(Portfolio)`, associate other natural/juristic persons later. |
-| D14 | tooling style | `bin/{subject}/{method}.go` shebang (e.g. `bin/brain/search.go`). Shared code in `internal/`. One root `go.mod` + `go.work`. No `bin/*/main.go`, no nested modules. |
+| D14 | tooling style | `bin/{subject}/{method}` self-describing: shebang line 1, usage comment from line 2. Go shebang: `///usr/bin/env go run "$0" "$@"; exit`. |
 | D15 | repo | Gitea [`eSlider/2dph`](https://git.produktor.io/eSlider/2dph) is origin + [issues](https://git.produktor.io/eSlider/2dph/issues). GitHub `eSlider/2dph` is the public clone (PRs + Actions CI). No direct `main` pushes. TDD → PR → CI green → merge. |
 | D16 | contradictions | ≥2 yes vs ≥2 no → unrelated sources conflict → hypothesis → `(not confirmed)`. Resolution (authority, staleness adjudication) = **v2**, tracked as open question. |
 

bin/brain/doc.go

@@ -1,3 +0,0 @@
-// Commands in this directory are shebang mains (search.go).
-// search.go is behind the system_ladybug build tag (cgo).
-package main

bin/brain/search.go

@@ -1,23 +0,0 @@
-//usr/bin/env go run -tags=system_ladybug "$0" "$@"; exit
-//go:build cgo && system_ladybug
-//
-// bin/brain/search.go - deduction search over the 2dph brain.
-//
-//	./bin/brain/search.go "query" [--root facts|info] [--repo P] [-n N] [--json]
-//	./bin/brain/search.go serve [port]
-//	./bin/brain/search.go --list-model
-//
-// Needs CGO + libladybug (CGO_CFLAGS/CGO_LDFLAGS). Prefer the wrapper
-// bin/kb/search which sets those and builds a binary for the embed daemon.
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"os"
-
-	"github.com/eSlider/2dph/internal/brain"
-)
-
-func main() {
-	os.Exit(brain.Main(os.Args[1:]))
-}

bin/brain/serve.go

@@ -1,26 +0,0 @@
-//usr/bin/env go run -tags=brain_serve "$0" "$@"; exit
-//go:build brain_serve
-//
-// bin/brain/serve.go - HTTP API for the 2dph brain.
-//
-//	KB_ROOT=/path/to/2dph ./bin/brain/serve.go
-//	KB_SEARCH_CMD=... KB_WORKERS=4 KB_PORT=8630 ./bin/brain/serve.go
-//
-// Default search backend is var/bin/brain-search (Go), not Python.
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"os"
-
-	"github.com/eSlider/2dph/internal/httpapi"
-)
-
-func main() {
-	if os.Getenv("KB_ROOT") == "" {
-		if wd, err := os.Getwd(); err == nil {
-			os.Setenv("KB_ROOT", wd)
-		}
-	}
-	httpapi.Run()
-}

bin/chats/go.mod

@@ -0,0 +1,3 @@
+module github.com/eSlider/2dph/bin/chats
+
+go 1.25.0

bin/doc.go

@@ -1,2 +0,0 @@
-// Deprecated shebang mains at bin root (serve.go is tagged brain_serve).
-package main

bin/kb/search

@@ -1,37 +1,34 @@
 #!/usr/bin/env bash
-# bin/kb/search — deprecated wrapper. Use bin/brain/search.go.
+# bin/kb/search - Go deduction search over the brain (model served by daemon).
-# Sets CGO for ladybug, builds a binary (embed daemon needs a real executable),
+# Builds the kbsearch binary on first run / when source changes, then execs it.
-# then execs it. Prints one deprecation line.
 set -euo pipefail
 
-ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+KB="$(cd "$(dirname "$0")/../.." && pwd)"
-BIN="$ROOT/var/bin/brain-search"
+BIN="$KB/var/bin/kbsearch"
-SRC="$ROOT/internal/brain"
+SRC="$KB/bin/kbsearch"
-CMD="$ROOT/bin/brain"
 
-mkdir -p "$ROOT/var/bin"
+mkdir -p "$KB/var/bin"
 
+# Rebuild if binary missing or any .go source newer
 need_build=0
 if [ ! -x "$BIN" ]; then
     need_build=1
 else
+    # Check if any .go in kbsearch is newer than binary
     while IFS= read -r -d '' f; do
         if [ "$f" -nt "$BIN" ]; then
             need_build=1
             break
         fi
-	done < <(find "$SRC" "$CMD" -name '*.go' -print0 2>/dev/null)
+    done < <(find "$SRC" -name '*.go' -print0 2>/dev/null)
 fi
 
 if [ "$need_build" -eq 1 ]; then
-	echo "Building brain/search..." >&2
+    echo "Building kbsearch..." >&2
-	(
+    (cd "$SRC" && \
-		cd "$ROOT" &&
+        CGO_CFLAGS="-I$KB/lib-ladybug" \
-			CGO_CFLAGS="-I$ROOT/lib-ladybug" \
+        CGO_LDFLAGS="-L$KB/lib-ladybug -Wl,-rpath,$KB/lib-ladybug" \
-			CGO_LDFLAGS="-L$ROOT/lib-ladybug -Wl,-rpath,$ROOT/lib-ladybug" \
+        go build -tags system_ladybug -o "$BIN" .) || exit 1
-			go build -tags system_ladybug -o "$BIN" ./bin/brain
-	) || exit 1
 fi
 
-echo "bin/kb/search is deprecated; use bin/brain/search.go" >&2
 exec "$BIN" "$@"

bin/kbsearch/brain.go

@@ -1,6 +1,5 @@
-//go:build cgo && system_ladybug
+// Brain connection management using go-ladybug.
-
+package main
-package brain
 
 import (
 	"fmt"

bin/kbsearch/go.mod

@@ -0,0 +1,23 @@
+module github.com/eSlider/2dph/bin/kbsearch
+
+go 1.26.0
+
+require (
+	github.com/LadybugDB/go-ladybug v0.17.0
+	github.com/chewxy/math32 v1.11.2
+	github.com/daulet/tokenizers v1.27.0
+)
+
+require (
+	github.com/apache/arrow-go/v18 v18.6.0 // indirect
+	github.com/goccy/go-json v0.10.6 // indirect
+	github.com/google/flatbuffers v25.12.19+incompatible // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/pierrec/lz4/v4 v4.1.26 // indirect
+	github.com/shopspring/decimal v1.4.0 // indirect
+	github.com/zeebo/xxh3 v1.1.0 // indirect
+	golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
+	golang.org/x/sys v0.43.0 // indirect
+)

bin/kbsearch/go.sum

@@ -0,0 +1,44 @@
+github.com/LadybugDB/go-ladybug v0.17.0 h1:RXDbkBjrbRmLdEbhGl4CLOIEzSt09gbP0n9UbKDEfwI=
+github.com/LadybugDB/go-ladybug v0.17.0/go.mod h1:GeIXmE8XyF5TFS94NAuTag7vgCC+no/HTBMRA6Rd5Cs=
+github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
+github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/apache/arrow-go/v18 v18.6.0 h1:GX/Jyd3R7mCLiECAwY9FWbbaYblie2WXBSz4Sw8fNpM=
+github.com/apache/arrow-go/v18 v18.6.0/go.mod h1:gm3MiPpY82fLYK5VKPB3WoJbsiLVDfT7flD5/vHReKw=
+github.com/apache/thrift v0.22.0 h1:r7mTJdj51TMDe6RtcmNdQxgn9XcyfGDOzegMDRg47uc=
+github.com/apache/thrift v0.22.0/go.mod h1:1e7J/O1Ae6ZQMTYdy9xa3w9k+XHWPfRvdPyJeynQ+/g=
+github.com/chewxy/math32 v1.11.2 h1:IufN08Zwr1NKuWfY+4Tz55BcwKmyKKNdOP7KtumehnM=
+github.com/chewxy/math32 v1.11.2/go.mod h1:dOB2rcuFrCn6UHrze36WSLVPKtzPMRAQvBvUwkSsLqs=
+github.com/daulet/tokenizers v1.27.0 h1:MmFYAEDFz69s/nNQfHg59DWqHz3v94m99kEZ/JbL+s4=
+github.com/daulet/tokenizers v1.27.0/go.mod h1:YjFY1o1HGMyWkQgbXJDghhvke/yFDp2vGdIO2hYs4MQ=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
+github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/google/flatbuffers v25.12.19+incompatible h1:haMV2JRRJCe1998HeW/p0X9UaMTK6SDo0ffLn2+DbLs=
+github.com/google/flatbuffers v25.12.19+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/pierrec/lz4/v4 v4.1.26 h1:GrpZw1gZttORinvzBdXPUXATeqlJjqUG/D87TKMnhjY=
+github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
+github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
+github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+golang.org/x/exp v0.0.0-20260112195511-716be5621a96 h1:Z/6YuSHTLOHfNFdb8zVZomZr7cqNgTJvA8+Qz75D8gU=
+golang.org/x/exp v0.0.0-20260112195511-716be5621a96/go.mod h1:nzimsREAkjBCIEFtHiYkrJyT+2uy9YZJB7H1k68CXZU=
+golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

bin/kbsearch/main.go

@@ -0,0 +1,46 @@
+// bin/kbsearch - the Go implementation of bin/kb/search (nested module so the
+// root `go test ./...` and CI never compile it against native ladyships).
+//
+// Usage (built/run by ./bin/kb/search):
+//
+//	kbsearch "query" [--root facts|info] [--repo P] [-n N] [--json]
+//	kbsearch serve [port]           start the embedding daemon
+//	kbsearch --list-model           print the resolved model dir
+//
+// The potion-multilingual model is loaded only in `serve`; a CLI reuses the
+// daemon over localhost HTTP (KBSEARCH_PORT, default 17830) and starts one in
+// the background when none answers. KBSEARCH_NO_DAEMON=1 skips that and embeds
+// in-process instead.
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+)
+
+func main() {
+	if len(os.Args) > 1 && os.Args[1] == "serve" {
+		port := 17830
+		if len(os.Args) > 2 {
+			if p, err := strconv.Atoi(os.Args[2]); err == nil {
+				port = p
+			}
+		}
+		if err := serve(port); err != nil {
+			log.Fatalf("kbsearch serve: %v", err)
+		}
+		return
+	}
+	if len(os.Args) > 1 && os.Args[1] == "--list-model" {
+		dir, err := modelDir()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+		fmt.Println(dir)
+		return
+	}
+	os.Exit(runSearch(os.Args[1:]))
+}

bin/kbsearch/model.go

@@ -1,11 +1,9 @@
-//go:build cgo && system_ladybug
-
 // StaticModel wraps the potion-multilingual-128m embedding model.
 //
 // Mirrors model2vec.StaticModel: tokenizer (daulet Unigram) + safetensors matrix.
 // Embed(text) applies the same preprocessing: median_token_length pre-truncation,
 // add_special_tokens=false, drop unk (id=1), truncate to 512, mean pool, L2 normalize +1e-32.
-package brain
+package main
 
 import (
 	"encoding/json"

bin/kbsearch/modeldir.go

@@ -1,4 +1,5 @@
-package brain
+// modelDir returns the resolved potion-multilingual-128m model directory.
+package main
 
 import (
 	"fmt"

bin/kbsearch/rank/args.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 )
 
-const Usage = `usage: bin/brain/search.go "query" [--root facts|info] [--repo REPO] [-n N] [--json]
+const Usage = `usage: kbsearch "query" [--root facts|info] [--repo REPO] [-n N] [--json]
-       bin/brain/search.go serve [port]
+       kbsearch serve [port]
-       bin/brain/search.go --list-model`
+       kbsearch --list-model`
 
 type Options struct {
 	Query     string

bin/kbsearch/rank/rank.go

@@ -1,4 +1,4 @@
-// Package rank is the cgo-free ranking and CLI parsing for brain search.
+// Package rank is the cgo-free ranking and CLI parsing for kbsearch.
 // CI can `go test ./rank` without the native ladybug library.
 package rank
 

bin/kbsearch/rank/rank_test.go

@@ -136,12 +136,6 @@ func TestListModelNeedsNoQuery(t *testing.T) {
 	}
 }
 
-func TestUsageNamesBrainSearch(t *testing.T) {
-	if !strings.Contains(Usage, "bin/brain/search.go") {
-		t.Fatalf("usage must name bin/brain/search.go, got:\n%s", Usage)
-	}
-}
-
 func TestFTSQueryOrdersByScoreDescending(t *testing.T) {
 	if !strings.Contains(FTSStmt, "ORDER BY score DESC") {
 		t.Fatalf("FTS query must order by score DESC, got:\n%s", FTSStmt)

bin/kbsearch/search.go

@@ -1,6 +1,5 @@
-//go:build cgo && system_ladybug
+// Hybrid FTS + vector search implementation, plus daemon client/server.
-
+package main
-package brain
 
 import (
 	"bytes"
@@ -19,7 +18,7 @@ import (
 	"time"
 
 	lbug "github.com/LadybugDB/go-ladybug"
-	"github.com/eSlider/2dph/internal/brain/rank"
+	"github.com/eSlider/2dph/bin/kbsearch/rank"
 )
 
 const defaultPort = 17830
@@ -29,7 +28,7 @@ const healthPath = "/health"
 func runSearch(args []string) int {
 	opt, err := rank.ParseArgs(args)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "brain/search: %v\n%s\n", err, rank.Usage)
+		fmt.Fprintf(os.Stderr, "kbsearch: %v\n%s\n", err, rank.Usage)
 		return 2
 	}
 	root, repo, limit, query := opt.Root, opt.Repo, opt.Limit, opt.Query
@@ -248,7 +247,7 @@ func serve(port int) error {
 	})
 
 	addr := fmt.Sprintf("127.0.0.1:%d", port)
-	log.Printf("brain search daemon listening on %s", addr)
+	log.Printf("kbsearch daemon listening on %s", addr)
 	return http.ListenAndServe(addr, mux)
 }
 
@@ -358,21 +357,3 @@ func ensureDaemon(port int) error {
 	}
 	return fmt.Errorf("daemon failed to start on port %d", port)
 }
-
-// Main is the bin/brain/search.go entry: search, serve, or --list-model.
-func Main(args []string) int {
-	if len(args) > 0 && args[0] == "serve" {
-		port := defaultPort
-		if len(args) > 1 {
-			if p, err := strconv.Atoi(args[1]); err == nil {
-				port = p
-			}
-		}
-		if err := serve(port); err != nil {
-			log.Printf("brain/search serve: %v", err)
-			return 1
-		}
-		return 0
-	}
-	return runSearch(args)
-}

bin/kbsearch/types.go

@@ -1,9 +1,10 @@
-package brain
+// Common types and helpers for kbsearch.
+package main
 
 import (
 	"os"
 
-	"github.com/eSlider/2dph/internal/brain/rank"
+	"github.com/eSlider/2dph/bin/kbsearch/rank"
 )
 
 func eps() string { return os.Getenv("KBTEST_EPS") }

bin/kbsearch/yaml.go

@@ -1,5 +1,5 @@
 // YAML emitter ported from bin/kb/yamlout.py — preserves insertion order.
-package brain
+package main
 
 import (
 	"fmt"

bin/serve.go

@@ -1,22 +1,27 @@
-//usr/bin/env go run -tags=brain_serve "$0" "$@"; exit
+//usr/bin/env go run "$0" "$@"; exit
-//go:build brain_serve
+// bin/serve.go - async Go HTTP server for the 2dph brain (see bin/server).
 //
-// bin/serve.go — deprecated; use bin/brain/serve.go.
+//	KB_ROOT=/path/to/2dph ./bin/serve.go        # serve the brain
+//	KB_SEARCH_CMD=... KB_WORKERS=4 KB_PORT=8630 ./bin/serve.go
+//
+// Shebang trick: the first line is a Go `//` comment; when executed, env runs
+// `go run "$0"` so this file doubles as an executable script. The real code
+// lives in the importable package (module path, never a relative import).
+// NOTE: never run `gofmt -w` on this file - it rewrites `//usr/bin/env` to
+// `// usr/...` and breaks the shebang.
 package main
 
 import (
-	"fmt"
 	"os"
 
-	"github.com/eSlider/2dph/internal/httpapi"
+	"github.com/eSlider/2dph/bin/server"
 )
 
 func main() {
-	fmt.Fprintln(os.Stderr, "bin/serve.go is deprecated; use bin/brain/serve.go")
+	if env := os.Getenv("KB_ROOT"); env == "" {
-	if os.Getenv("KB_ROOT") == "" {
 		if wd, err := os.Getwd(); err == nil {
 			os.Setenv("KB_ROOT", wd)
 		}
 	}
-	httpapi.Run()
+	server.Run()
 }

bin/server/server.go

@@ -2,10 +2,15 @@
 //
 // Async by design: every request runs on its own goroutine, and CPU-heavy
 // searches are serialized through a bounded worker pool (a counting
-// semaphore) so N requests can't spawn N search processes at once.
+// semaphore) so N requests can't spawn N Python interpreters at once.
 //
-// Used by bin/brain/serve.go.
+// Used by bin/serve.go which is a self-executing shebang script:
-package httpapi
+//
+//	///usr/bin/env go run "$0" "$@"; exit
+//	package main
+//	import "github.com/eSlider/2dph/bin/server"
+//	func main() { server.Run() }
+package server
 
 import (
 	"context"
@@ -95,8 +100,8 @@ func writeRaw(w http.ResponseWriter, code int, body []byte) {
 	w.Write(body)
 }
 
-// brainSearcher shells out to the Go brain-search binary (not Python).
+// brainSearcher shells out to bin/kb/search --json. A single python search
-// A single search is bounded and short-lived; the worker pool keeps at most N live.
+// is bounded and short-lived; the worker pool keeps at most N live.
 type brainSearcher struct {
 	cmdPath string
 	timeout time.Duration
@@ -117,18 +122,15 @@ func (b *brainSearcher) Search(ctx context.Context, query string, limit int) ([]
 	return out, nil
 }
 
-func defaultSearchCmd(root string) string {
+// Run starts the HTTP server. Reads env: KB_SEARCH_CMD (default bin/kb/search,
-	if env := os.Getenv("KB_SEARCH_CMD"); env != "" {
+// relative to the repo root given by KB_ROOT), KB_WORKERS (default 4), KB_PORT
-		return env
+// (default 8630).
-	}
-	return filepath.Join(root, "var", "bin", "brain-search")
-}
-
-// Run starts the HTTP server. Reads env: KB_SEARCH_CMD (default
-// $KB_ROOT/var/bin/brain-search), KB_WORKERS (default 4), KB_PORT (default 8630).
 func Run() {
 	root := os.Getenv("KB_ROOT")
-	searchPath := defaultSearchCmd(root)
+	searchPath := os.Getenv("KB_SEARCH_CMD")
+	if searchPath == "" {
+		searchPath = filepath.Join(root, "bin", "kb", "search")
+	}
 	workers := 4
 	if raw := os.Getenv("KB_WORKERS"); raw != "" {
 		if n, err := strconv.Atoi(raw); err == nil && n > 0 {
@@ -145,7 +147,7 @@ func Run() {
 	searcher := &brainSearcher{cmdPath: searchPath, timeout: 60 * time.Second}
 	handler := NewServer(searcher, workers)
 	addr := "127.0.0.1:" + strconv.Itoa(port)
-	log.Printf("serve: %s (workers=%d cmd=%s)", addr, workers, searchPath)
+	log.Printf("serve: %s (workers=%d)", addr, workers)
 	if err := http.ListenAndServe(addr, handler); err != nil {
 		log.Fatal(err)
 	}

bin/server/server_test.go

@@ -1,11 +1,10 @@
-package httpapi
+package server
 
 import (
 	"context"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -142,17 +141,6 @@ func TestSearchRejectsBadLimit(t *testing.T) {
 	}
 }
 
-func TestDefaultSearchCmdIsBrainNotPython(t *testing.T) {
-	t.Setenv("KB_SEARCH_CMD", "")
-	cmd := defaultSearchCmd("/repo")
-	if strings.Contains(strings.ToLower(cmd), "python") {
-		t.Fatalf("search path still python: %s", cmd)
-	}
-	if !strings.Contains(cmd, "brain") {
-		t.Fatalf("search path must be the Go brain binary, got %s", cmd)
-	}
-}
-
 func TestSearchTimeout(t *testing.T) {
 	fs := &fakeSearcher{delay: time.Second}
 	h := NewServer(fs, 1)

bin/tools/test_bin_layout.py

@@ -1,36 +0,0 @@
-"""D14 layout: bin/{subject}/{method}.go, libs in internal/, one go.mod."""
-from __future__ import annotations
-
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[2]
-
-
-class BinLayoutTest(unittest.TestCase):
-    def test_brain_search_shebang_exists(self) -> None:
-        p = ROOT / "bin" / "brain" / "search.go"
-        self.assertTrue(p.is_file(), "missing bin/brain/search.go")
-        first = p.read_text().splitlines()[0]
-        self.assertTrue(
-            first.startswith("//usr/bin/env go run"),
-            f"shebang first line, got {first!r}",
-        )
-
-    def test_no_nested_go_mod_under_bin(self) -> None:
-        nested = list((ROOT / "bin").rglob("go.mod"))
-        self.assertEqual(nested, [], f"nested go.mod files: {nested}")
-
-    def test_rank_lives_in_internal_brain(self) -> None:
-        self.assertTrue(
-            (ROOT / "internal" / "brain" / "rank" / "rank.go").is_file(),
-            "ranking must live in internal/brain/rank (cgo-free)",
-        )
-        self.assertFalse(
-            (ROOT / "bin" / "kbsearch").exists(),
-            "bin/kbsearch nested module must be gone",
-        )
-
-    def test_no_main_go_under_bin_brain(self) -> None:
-        main = ROOT / "bin" / "brain" / "main.go"
-        self.assertFalse(main.exists(), "bin/brain/main.go is not a method")

go.mod

@@ -1,25 +1,8 @@
 module github.com/eSlider/2dph
 
-go 1.26
+go 1.25.0
 
 require (
-	github.com/LadybugDB/go-ladybug v0.17.0
 	github.com/arran4/golang-ical v0.3.5
-	github.com/chewxy/math32 v1.11.2
-	github.com/daulet/tokenizers v1.27.0
 	golang.org/x/text v0.40.0
 )
-
-require (
-	github.com/apache/arrow-go/v18 v18.6.0 // indirect
-	github.com/goccy/go-json v0.10.6 // indirect
-	github.com/google/flatbuffers v25.12.19+incompatible // indirect
-	github.com/google/uuid v1.6.0 // indirect
-	github.com/klauspost/compress v1.18.5 // indirect
-	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
-	github.com/pierrec/lz4/v4 v4.1.26 // indirect
-	github.com/shopspring/decimal v1.4.0 // indirect
-	github.com/zeebo/xxh3 v1.1.0 // indirect
-	golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-)

go.sum

@@ -1,50 +1,14 @@
-github.com/LadybugDB/go-ladybug v0.17.0 h1:RXDbkBjrbRmLdEbhGl4CLOIEzSt09gbP0n9UbKDEfwI=
-github.com/LadybugDB/go-ladybug v0.17.0/go.mod h1:GeIXmE8XyF5TFS94NAuTag7vgCC+no/HTBMRA6Rd5Cs=
-github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
-github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
-github.com/apache/arrow-go/v18 v18.6.0 h1:GX/Jyd3R7mCLiECAwY9FWbbaYblie2WXBSz4Sw8fNpM=
-github.com/apache/arrow-go/v18 v18.6.0/go.mod h1:gm3MiPpY82fLYK5VKPB3WoJbsiLVDfT7flD5/vHReKw=
-github.com/apache/thrift v0.22.0 h1:r7mTJdj51TMDe6RtcmNdQxgn9XcyfGDOzegMDRg47uc=
-github.com/apache/thrift v0.22.0/go.mod h1:1e7J/O1Ae6ZQMTYdy9xa3w9k+XHWPfRvdPyJeynQ+/g=
 github.com/arran4/golang-ical v0.3.5 h1:bbz6ld4dC+MmCKiFfOd6SkmIGnhNMBACZ485ULh7p9A=
 github.com/arran4/golang-ical v0.3.5/go.mod h1:OnguFgjN0Hmx8jzpmWcC+AkHio94ujmLHKoaef7xQh8=
-github.com/chewxy/math32 v1.11.2 h1:IufN08Zwr1NKuWfY+4Tz55BcwKmyKKNdOP7KtumehnM=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
-github.com/chewxy/math32 v1.11.2/go.mod h1:dOB2rcuFrCn6UHrze36WSLVPKtzPMRAQvBvUwkSsLqs=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/daulet/tokenizers v1.27.0 h1:MmFYAEDFz69s/nNQfHg59DWqHz3v94m99kEZ/JbL+s4=
-github.com/daulet/tokenizers v1.27.0/go.mod h1:YjFY1o1HGMyWkQgbXJDghhvke/yFDp2vGdIO2hYs4MQ=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
-github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
-github.com/google/flatbuffers v25.12.19+incompatible h1:haMV2JRRJCe1998HeW/p0X9UaMTK6SDo0ffLn2+DbLs=
-github.com/google/flatbuffers v25.12.19+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
-github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
-github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
-github.com/pierrec/lz4/v4 v4.1.26 h1:GrpZw1gZttORinvzBdXPUXATeqlJjqUG/D87TKMnhjY=
-github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
-github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
-github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
-github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
-github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
-github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
-github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
-golang.org/x/exp v0.0.0-20260112195511-716be5621a96 h1:Z/6YuSHTLOHfNFdb8zVZomZr7cqNgTJvA8+Qz75D8gU=
-golang.org/x/exp v0.0.0-20260112195511-716be5621a96/go.mod h1:nzimsREAkjBCIEFtHiYkrJyT+2uy9YZJB7H1k68CXZU=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
 golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
-gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
-gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go.work

@@ -1,3 +0,0 @@
-go 1.26
-
-use .

internal/brain/doc.go

@@ -1,3 +0,0 @@
-// Package brain is deduction search over Ladybug (FTS + HNSW).
-// Query/embed code that needs cgo lives behind the system_ladybug tag.
-package brain