docs: name bin/brain/search.go; --hop is not a graph walk. (#10)

Published docs and skills still taught bin/kb/search --hop 1. Search lives
at bin/brain/search.go; --hop errors until File edges exist. A unittest
gates the SoT so the lie cannot return.

AGENTS.md

@@ -37,8 +37,7 @@ docs/         published docs
 skills/       in-project agent skills (vendored, no external links)
 bin/          self-describing tools bin/{subject}/{method}.go (shebang)
 bin/brain/    search.go, serve.go; libs in internal/brain and internal/httpapi
-bin/chats/    sync.go import.go facts.go apply.go; libs in internal/chats
+internal/     shared Go (brain/rank is cgo-free)
-internal/     shared Go (brain/rank is cgo-free; chats parsers too)
 bin/watch/    corpus watcher (internal via bin/brain/watch later)
 bin/mail/     mail pipeline: sync (Go), import (md), index_mail (rebuild)
 bin/tools/    vendored python libs behind bin/* (kblib, yamlout, websearch)

PLAN.md

@@ -57,8 +57,6 @@ detective method: **a fact needs ≥2 independent sources or it is
     brain/search.go         deduction: facts → info → web-search
     kb/get  kb/stats  kb/eval
     brain/serve.go          HTTP API (internal/httpapi)
-    chats/sync.go import.go facts.go apply.go
-                            (libs in internal/chats; no chats index)
     md/import  md/select  md/tables  md/gaps     (mistune)
     brain/extract  brain/audit   brain/deduce    (thinking wrapper)
     web/search               (vendored)

bin/chats/apply.go

@@ -1,19 +0,0 @@
-//usr/bin/env go run -tags=chats_apply "$0" "$@"; exit
-//go:build chats_apply
-//
-// bin/chats/apply.go - push extracted chat facts to OnlyOffice CRM.
-//
-//	./bin/chats/apply.go [--dry-run]
-//
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"os"
-
-	"github.com/eSlider/2dph/internal/chats"
-)
-
-func main() {
-	os.Exit(chats.RunApply(os.Args[1:]))
-}

bin/chats/apply_cmd.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"bytes"
@@ -24,7 +24,7 @@ type ooContact struct {
 	} `json:"commonData"`
 }
 
-func RunApply(args []string) int {
+func runApply(args []string) int {
 	fs := flag.NewFlagSet("chats apply", flag.ContinueOnError)
 	dryRun := fs.Bool("dry-run", false, "show what would be done without writing")
 	help := fs.Bool("help", false, "")
@@ -176,7 +176,7 @@ func RunApply(args []string) int {
 }
 
 func loadFacts() ([]ExtractedFact, error) {
-	factsPath := filepath.Join(Dir(), "facts", "chat-facts.json")
+	factsPath := filepath.Join(chatsDir(), "facts", "chat-facts.json")
 	data, err := os.ReadFile(factsPath)
 	if err != nil {
 		if os.IsNotExist(err) {

bin/chats/chats_test.go

@@ -3,7 +3,7 @@
 // These are integration tests using real data and real Telegram API (when
 // credentials are available). They follow the TDD workflow pattern:
 // sync → import → facts → verify.
-package chats
+package main
 
 import (
 	"encoding/json"
@@ -48,7 +48,7 @@ func TestChatsImport(t *testing.T) {
 	t.Cleanup(func() { os.Chdir(cwd) })
 	t.Setenv("KB_ROOT", dir)
 
-	exitCode := RunImport([]string{})
+	exitCode := runImport([]string{})
 	if exitCode != 0 {
 		t.Fatalf("import exit code %d", exitCode)
 	}
@@ -140,7 +140,7 @@ func TestChatsImportEmpty(t *testing.T) {
 	t.Cleanup(func() { os.Chdir(cwd) })
 	t.Setenv("KB_ROOT", dir)
 
-	exitCode := RunImport([]string{})
+	exitCode := runImport([]string{})
 	if exitCode == 0 {
 		t.Fatal("expected non-zero exit for empty data dir")
 	}
@@ -171,7 +171,7 @@ func TestChatsRoundTrip(t *testing.T) {
 	t.Cleanup(func() { os.Chdir(cwd) })
 	t.Setenv("KB_ROOT", dir)
 
-	if code := RunImport([]string{}); code != 0 {
+	if code := runImport([]string{}); code != 0 {
 		t.Fatalf("import exit %d", code)
 	}
 

bin/chats/doc.go

@@ -1,4 +0,0 @@
-// Commands in this directory are shebang mains (sync.go, import.go, facts.go,
-// apply.go), each behind an exclusive build tag so `go build ./bin/chats`
-// does not see two mains. Shared code lives in internal/chats.
-package main

bin/chats/facts.go

@@ -1,20 +0,0 @@
-//usr/bin/env go run -tags=chats_facts "$0" "$@"; exit
-//go:build chats_facts
-//
-// bin/chats/facts.go - extract phone/email/linkedin facts from JSONL.
-//
-//	./bin/chats/facts.go
-//
-// Writes var/chats/facts/. Does not index the brain.
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"os"
-
-	"github.com/eSlider/2dph/internal/chats"
-)
-
-func main() {
-	os.Exit(chats.RunFacts(os.Args[1:]))
-}

bin/chats/facts_cmd.go

@@ -1,11 +1,13 @@
-package chats
+package main
 
 import (
 	"bufio"
+	"bytes"
 	"encoding/json"
 	"flag"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -75,7 +77,7 @@ type ExtractedFact struct {
 	MessageID string `json:"message_id"`
 }
 
-func RunFacts(args []string) int {
+func runFacts(args []string) int {
 	fs := flag.NewFlagSet("chats facts", flag.ContinueOnError)
 	help := fs.Bool("help", false, "")
 	fs.SetOutput(os.Stderr)
@@ -87,7 +89,7 @@ func RunFacts(args []string) int {
 		return 0
 	}
 
-	root := Dir()
+	root := chatsDir()
 	telegramDir := filepath.Join(root, "telegram")
 
 	entries, err := os.ReadDir(telegramDir)
@@ -147,7 +149,7 @@ func RunFacts(args []string) int {
 	}
 	fmt.Printf("chats facts: saved to %s\n", factsPath)
 
-	writeFactsMarkdown(allFacts)
+	writeFactsToBrain(root, allFacts)
 
 	return 0
 }
@@ -271,10 +273,14 @@ func filterFacts(facts []ExtractedFact, factType string) []ExtractedFact {
 	return result
 }
 
-// writeFactsMarkdown stores a sidecar for humans. Brain ingest is
+func writeFactsToBrain(root string, facts []ExtractedFact) {
-// bin/brain/index.go (not this subject).
+	indexScript := filepath.Join(root, "bin", "kb", "index")
-func writeFactsMarkdown(facts []ExtractedFact) {
+	if _, err := os.Stat(indexScript); os.IsNotExist(err) {
-	mdDir := filepath.Join(Dir(), "facts")
+		fmt.Fprintf(os.Stderr, "chats facts: kb/index not found, skipping brain write\n")
+		return
+	}
+
+	mdDir := filepath.Join(chatsDir(), "facts")
 	if err := os.MkdirAll(mdDir, 0755); err != nil {
 		fmt.Fprintf(os.Stderr, "chats facts: mkdir %s: %v\n", mdDir, err)
 		return
@@ -282,7 +288,7 @@ func writeFactsMarkdown(facts []ExtractedFact) {
 
 	var sb strings.Builder
 	sb.WriteString("---\n")
-	sb.WriteString("root: info\n")
+	sb.WriteString("root: facts\n")
 	sb.WriteString("---\n\n")
 	sb.WriteString("# Chat-Derived Facts\n\n")
 	for _, f := range facts {
@@ -296,5 +302,15 @@ func writeFactsMarkdown(facts []ExtractedFact) {
 		fmt.Fprintf(os.Stderr, "chats facts: write %s: %v\n", factsMD, err)
 		return
 	}
-	fmt.Printf("chats facts: markdown %s (index via brain, not chats)\n", factsMD)
+
+	cmd := exec.Command(indexScript, "--corpus", mdDir, "--skip-indexes")
+	var outBuf, errBuf bytes.Buffer
+	cmd.Stdout = &outBuf
+	cmd.Stderr = &errBuf
+	cmd.Dir = root
+	if err := cmd.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "chats facts: brain index: %v\n%s", err, errBuf.String())
+		return
+	}
+	fmt.Printf("chats facts: written to brain (%s)\n", strings.TrimSpace(outBuf.String()))
 }

bin/chats/import.go

@@ -1,20 +0,0 @@
-//usr/bin/env go run -tags=chats_import "$0" "$@"; exit
-//go:build chats_import
-//
-// bin/chats/import.go - JSONL → markdown under var/chats/md/.
-//
-//	./bin/chats/import.go
-//
-// Conversion only. Brain ingest is bin/brain/index.go, not this command.
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"os"
-
-	"github.com/eSlider/2dph/internal/chats"
-)
-
-func main() {
-	os.Exit(chats.RunImport(os.Args[1:]))
-}

bin/chats/import_cmd.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"bufio"
@@ -13,7 +13,7 @@ import (
 	"strings"
 )
 
-func RunImport(args []string) int {
+func runImport(args []string) int {
 	fs := flag.NewFlagSet("chats import", flag.ContinueOnError)
 	help := fs.Bool("help", false, "")
 	fs.SetOutput(os.Stderr)
@@ -25,7 +25,7 @@ func RunImport(args []string) int {
 		return 0
 	}
 
-	root := Dir()
+	root := chatsDir()
 	mdRoot := filepath.Join(root, "md")
 	glob := filepath.Join(root, "telegram", "*", "messages.jsonl")
 

bin/chats/index_cmd.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+func runIndex(args []string) int {
+	fs := flag.NewFlagSet("chats index", flag.ContinueOnError)
+	help := fs.Bool("help", false, "")
+	fs.SetOutput(os.Stderr)
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	if *help {
+		fmt.Fprintln(os.Stderr, "usage: chats index")
+		return 0
+	}
+
+	root := repoRoot()
+	mdDir := filepath.Join(chatsDir(), "md")
+
+	_, err := os.Stat(mdDir)
+	if os.IsNotExist(err) {
+		fmt.Fprintf(os.Stderr, "chats index: no chat markdown at %s; run 'chats import' first\n", mdDir)
+		return 1
+	}
+
+	indexScript := filepath.Join(root, "bin", "kb", "index")
+	if _, err := os.Stat(indexScript); os.IsNotExist(err) {
+		fmt.Fprintf(os.Stderr, "chats index: %s not found\n", indexScript)
+		return 1
+	}
+
+	cmd := exec.Command(indexScript, "--corpus", mdDir)
+	var outBuf, errBuf bytes.Buffer
+	cmd.Stdout = &outBuf
+	cmd.Stderr = &errBuf
+	cmd.Dir = root
+
+	if err := cmd.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "chats index: %v\n%s", err, errBuf.String())
+		return 1
+	}
+	result := strings.TrimSpace(outBuf.String())
+	if result == "" {
+		result = strings.TrimSpace(errBuf.String())
+	}
+	fmt.Printf("chats index: %s\n", result)
+	return 0
+}

bin/chats/linkedin.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"bufio"

bin/chats/linkedin_test.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"errors"

bin/chats/main.go

@@ -0,0 +1,115 @@
+// bin/chats - sync, import, index, extract facts, and apply chat data
+// from Telegram, WhatsApp, LinkedIn into the brain and OnlyOffice CRM.
+//
+// Usage:
+//
+//	chats sync telegram   [--limit N] [--since DATE] [--phone PHONE]
+//	chats sync whatsapp   [--qr] [--limit N]
+//	chats sync linkedin   [--limit N]
+//	chats import                           # JSONL → MD (all sources)
+//	chats index                            # rebuild var/kb.lbug with chats
+//	chats facts                            # extract + cross-check
+//	chats apply          [--dry-run]       # push to OnlyOffice CRM
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+	cmd := os.Args[1]
+	args := os.Args[2:]
+	switch cmd {
+	case "sync":
+		if len(args) < 1 {
+			usage()
+			os.Exit(2)
+		}
+		platform := args[0]
+		platformArgs := args[1:]
+		switch platform {
+		case "telegram":
+			os.Exit(runSyncTelegram(platformArgs))
+		case "whatsapp":
+			fmt.Fprintf(os.Stderr, "chats: WhatsApp not implemented yet\n")
+			os.Exit(1)
+		case "linkedin":
+			os.Exit(runSyncLinkedIn(platformArgs))
+		default:
+			fmt.Fprintf(os.Stderr, "chats: unknown platform %q\n", platform)
+			os.Exit(2)
+		}
+	case "import":
+		os.Exit(runImport(args))
+	case "index":
+		os.Exit(runIndex(args))
+	case "facts":
+		os.Exit(runFacts(args))
+	case "apply":
+		os.Exit(runApply(args))
+	case "help", "-h", "--help":
+		usage()
+		return
+	default:
+		fmt.Fprintf(os.Stderr, "chats: unknown command %q\n", cmd)
+		usage()
+		os.Exit(2)
+	}
+}
+
+func usage() {
+	w := os.Stderr
+	fmt.Fprintln(w, `Usage: chats <command> [args]
+
+Commands:
+  sync telegram  [--limit N] [--since DATE] [--phone PHONE]
+  sync whatsapp  [--qr] [--limit N]
+  sync linkedin  [--limit N]
+  import                             JSONL → MD (all sources)
+  index                              rebuild var/kb.lbug with chats
+  facts                              extract + cross-check facts
+  apply             [--dry-run]      push to OnlyOffice CRM
+
+Output layout:
+  var/chats/<platform>/<chat_id>/messages.jsonl
+  var/chats/md/<platform>/<chat_name>/messages.md`)
+}
+
+// repoRoot locates the 2dph project root by walking up from the binary.
+func repoRoot() string {
+	if v := os.Getenv("KB_ROOT"); v != "" {
+		return v
+	}
+	wd, err := os.Getwd()
+	if err != nil {
+		return "."
+	}
+	for i := 0; i < 10; i++ {
+		if _, err := os.Stat(wd + "/var"); err == nil {
+			return wd
+		}
+		if _, err := os.Stat(wd + "/.git"); err == nil {
+			return wd
+		}
+		parent := wd
+		if idx := strings.LastIndex(wd, "/"); idx >= 0 {
+			parent = wd[:idx]
+		}
+		if parent == wd {
+			break
+		}
+		wd = parent
+	}
+	return "."
+}
+
+// chatsDir returns var/chats under the repo root.
+func chatsDir() string {
+	return repoRoot() + "/var/chats"
+}

bin/chats/mcpclient.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"bufio"

bin/chats/source.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"context"

bin/chats/sync.go

@@ -1,41 +0,0 @@
-//usr/bin/env go run -tags=chats_sync "$0" "$@"; exit
-//go:build chats_sync
-//
-// bin/chats/sync.go - download chat messages to var/chats/<platform>/.
-//
-//	./bin/chats/sync.go telegram [--limit N] [--phone PHONE]
-//	./bin/chats/sync.go linkedin [--limit N] [--refresh]
-//
-// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/eSlider/2dph/internal/chats"
-)
-
-func main() {
-	if len(os.Args) < 2 {
-		fmt.Fprintln(os.Stderr, `usage: bin/chats/sync.go telegram|linkedin [flags]`)
-		os.Exit(2)
-	}
-	platform := os.Args[1]
-	args := os.Args[2:]
-	switch platform {
-	case "telegram":
-		os.Exit(chats.RunSyncTelegram(args))
-	case "linkedin":
-		os.Exit(chats.RunSyncLinkedIn(args))
-	case "whatsapp":
-		fmt.Fprintln(os.Stderr, "chats: WhatsApp not implemented yet")
-		os.Exit(1)
-	case "help", "-h", "--help":
-		fmt.Fprintln(os.Stderr, `usage: bin/chats/sync.go telegram|linkedin [flags]`)
-		return
-	default:
-		fmt.Fprintf(os.Stderr, "chats: unknown platform %q\n", platform)
-		os.Exit(2)
-	}
-}

bin/chats/sync_cmd.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"context"
@@ -11,7 +11,7 @@ import (
 	"time"
 )
 
-func RunSyncTelegram(args []string) int {
+func runSyncTelegram(args []string) int {
 	fs := flag.NewFlagSet("chats sync telegram", flag.ContinueOnError)
 	limit := fs.Int("limit", 0, "max messages per chat (0 = all)")
 	phone := fs.String("phone", "", "phone number (default env TELEGRAM_PHONE)")
@@ -78,7 +78,7 @@ func RunSyncTelegram(args []string) int {
 	defer cancel()
 
 	start := time.Now()
-	if err := src.Sync(ctx, Dir(), *limit); err != nil {
+	if err := src.Sync(ctx, chatsDir(), *limit); err != nil {
 		fmt.Fprintf(os.Stderr, "chats sync telegram: %v\n", err)
 		return 1
 	}

bin/chats/sync_linkedin_cmd.go

@@ -1,4 +1,4 @@
-package chats
+package main
 
 import (
 	"context"
@@ -28,7 +28,7 @@ func checkLinkedInSession(userDataDir string) (bool, error) {
 	return false, nil
 }
 
-func RunSyncLinkedIn(args []string) int {
+func runSyncLinkedIn(args []string) int {
 	fs := flag.NewFlagSet("chats sync linkedin", flag.ContinueOnError)
 	limit := fs.Int("limit", 0, "max messages per conversation (0 = all)")
 	refresh := fs.Bool("refresh", false, "refresh session from live webtop browser before sync")
@@ -72,7 +72,7 @@ func RunSyncLinkedIn(args []string) int {
 	defer cancel()
 
 	start := time.Now()
-	if err := src.Sync(ctx, Dir(), *limit); err != nil {
+	if err := src.Sync(ctx, chatsDir(), *limit); err != nil {
 		fmt.Fprintf(os.Stderr, "chats sync linkedin: %v\n", err)
 		return 1
 	}

bin/tools/test_bin_layout.py

@@ -34,32 +34,3 @@ class BinLayoutTest(unittest.TestCase):
     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")
-
-    def test_chats_methods_are_shebangs_not_main(self) -> None:
-        chats = ROOT / "bin" / "chats"
-        self.assertFalse(
-            (chats / "main.go").exists(),
-            "bin/chats/main.go is a dispatcher, not a method",
-        )
-        self.assertFalse(
-            (chats / "index_cmd.go").exists(),
-            "chats index is a brain write hiding under the wrong subject",
-        )
-        for method in ("sync.go", "import.go", "facts.go", "apply.go"):
-            p = chats / method
-            self.assertTrue(p.is_file(), f"missing bin/chats/{method}")
-            first = p.read_text().splitlines()[0]
-            self.assertTrue(
-                first.startswith("//usr/bin/env go run"),
-                f"{method} shebang, got {first!r}",
-            )
-
-    def test_chats_lib_lives_in_internal(self) -> None:
-        self.assertTrue(
-            (ROOT / "internal" / "chats" / "linkedin.go").is_file(),
-            "LinkedIn parser must live in internal/chats",
-        )
-        self.assertFalse(
-            (ROOT / "bin" / "chats" / "linkedin.go").exists(),
-            "parser must not stay under bin/chats as a second main",
-        )

docs/chat-import-plan.md

@@ -15,10 +15,9 @@ OO_CLI                     (default: $HOME/go/bin/oo)
 ## Quick reference
 
 ```
-./bin/chats/sync.go telegram --limit 100
+./bin/chat sync telegram --limit 100
-./bin/chats/import.go
+./bin/chat import
-./bin/chats/facts.go
+./bin/chat index
-./bin/chats/apply.go --dry-run
+./bin/chat facts
+./bin/chat apply --dry-run
 ```
-
-JSONL → markdown only. Brain ingest is `bin/brain/index.go` (not a `chats index`).

docs/crm-associations-proof.md

@@ -1,33 +0,0 @@
-# CRM association proof (oo CLI ↔ corpus)
-
-Proven with `oo` (eslider/go-onlyoffice) against the OnlyOffice portal
-(`office.produktor.io`). Portal CRM is the SSOT for company ↔ person ↔
-project associations; the corpus SoT (`eslider/cv/projects/knowledge-mesh-seed.yaml`)
-is the second, independent source. Facts that can be backed by both are
-written to the brain under `root=facts` by `bin/facts/crm`.
-
-## What was verified
-
-- Logical counts (portal MySQL): 1300 contacts = 897 persons + 404 companies,
-  198 projects, 998 deals, 939 project↔contact links.
-- Every client company linked to a project has ≥1 person underneath.
-- Every person `company_id` resolves to an existing company.
-- Corpus org list (9) maps 1:1 onto CRM companies:
-  ProProdukt SL / produktor.io, Dyvenia, Immowelt AG, WhereGroup,
-  Keynote SIGOS, D2S/SYSTEMS, GRID, Pack und Cup, Markets Platform.
-- 78 person↔company association facts written to the brain
-  (`how=crm-crosscheck`, `type=association`). Recall@5 in `bin/kb/eval` = 1.0.
-
-## Mistakes found
-
-| # | Mistake | Fix |
-|---|---------|-----|
-| 1 | Duplicate legal entity `GoldenRatio.Exchange` (contact 759) vs `Golden Ratio Exchange` (763); 3 deals (211, 287, 559) were linked to 759 | `oo contacts merge 759 763` — 763 kept, 759 removed, deal links re-pointed to 763 |
-| 2 | `env/`-wide: OnlyOffice creds file used wrong UX (user `eslider`, password with `$2` suffix) making `oo` auth fail | `.env` fixed to `eslider@gmail.com` + clean password; `.env` stays gitignored |
-
-## Gates after fix
-
-- `uv run python -m unittest discover -s bin/tools -t .` → 26 tests OK
-- `bin/facts/audit self` + `bin/facts/audit db` → ok
-- `bin/kb/eval` → recall@5 = 1.0
-- `go test ./...` (bin/server + bin/watch) → ok

internal/chats/paths.go

@@ -1,39 +0,0 @@
-package chats
-
-import (
-	"os"
-	"strings"
-)
-
-// Root locates the 2dph project root (KB_ROOT, or walk up for var/ or .git).
-func Root() string {
-	if v := os.Getenv("KB_ROOT"); v != "" {
-		return v
-	}
-	wd, err := os.Getwd()
-	if err != nil {
-		return "."
-	}
-	for i := 0; i < 10; i++ {
-		if _, err := os.Stat(wd + "/var"); err == nil {
-			return wd
-		}
-		if _, err := os.Stat(wd + "/.git"); err == nil {
-			return wd
-		}
-		parent := wd
-		if idx := strings.LastIndex(wd, "/"); idx >= 0 {
-			parent = wd[:idx]
-		}
-		if parent == wd {
-			break
-		}
-		wd = parent
-	}
-	return "."
-}
-
-// Dir is var/chats under the project root.
-func Dir() string {
-	return Root() + "/var/chats"
-}