feat: parse all Go CLIs with flaggy; dump bash complete

AGENTS.md

@@ -48,7 +48,7 @@ bin/postgres/ query.go (read-only YAML)
 bin/git/      import.go (go-git history; Python shim execs it)
 bin/web/      search.go (SearXNG; Python shim execs it)
 bin/reasoner/ bakeoff.go (D18 CPU OpenAI tool-call bake-off)
-internal/     shared Go (brain/rank is cgo-free; facts D16; chats; gitlog; websearch; reasoner; duckstats)
+internal/     shared Go (brain/rank is cgo-free; facts D16; cli flaggy D23; chats; gitlog; websearch; reasoner; duckstats)
 bin/qa/       stats.go (DuckDB quantiles / JSONL count; gcc CGO, not Zig)
 bin/watch/    corpus watcher (used by bin/brain/watch.go)
 bin/tools/    vendored python libs behind bin/* (kblib, yamlout, websearch)
@@ -89,6 +89,7 @@ bin/facts/crm.go [--dry-run]                       # proof person↔company/comp
 bin/kb/search "query" [--repo X]                  # deprecated wrapper → bin/brain/search.go
 bin/brain/search.go "query" [--root facts|info]   # deduction search → YAML
 bin/brain/search.go "query" --no-web              # local graph only
+source <(./bin/cli/complete.go bash)              # flaggy completions (D23)
 eval "$(bin/cgo/zig env)"                         # Zig cc + liblbug (not gcc)
 bin/brain/index.go --rebuild [--with-mail] [--with-facts] [--with-chats]
 bin/brain/add.go --text T --root facts --source "a.md x b.md"  # incremental write

PLAN.md

@@ -8,7 +8,8 @@ Status: **v1 in** (epic [#16](https://git.produktor.io/eSlider/2dph/issues/16) c
 v2 board: milestone [v2](https://git.produktor.io/eSlider/2dph/milestone/13) —
 OCR [#6](https://git.produktor.io/eSlider/2dph/issues/6) in,
 [#29](https://git.produktor.io/eSlider/2dph/issues/29) OQ1 in,
-[#30](https://git.produktor.io/eSlider/2dph/issues/30) OQ3 in.
+[#30](https://git.produktor.io/eSlider/2dph/issues/30) OQ3 in,
+[#34](https://git.produktor.io/eSlider/2dph/issues/34) D23 in.
 Gap: [docs/roadmap.md](docs/roadmap.md).
 
 ## What
@@ -51,6 +52,7 @@ detective method: **a fact needs ≥2 independent sources or it is
 | D20 | agent API | OpenAPI + MCP are generated from the same `internal/httpapi.Ops` table as `bin/brain/serve.go` handlers. `GET /openapi.json`, `POST /mcp` (JSON-RPC tools/list + tools/call). Tool names match OpenAPI paths (`search`/`get`/`stats`/`audit`/`ingest`). |
 | D21 | CGO | Ladybug/tokenizers CGO is compiled with **Zig** (`bin/cgo/zcc` → `zig cc -target …-linux-gnu`), not gcc. `bin/cgo/zig` pins Zig 0.14.1 + liblbug 0.19.1 + libtokenizers 1.27.0. Compose `target: api` has no CPython; write/rebuild is profile `index`. |
 | D22 | analytics | **duckdb-go** in-process (`internal/duckstats`, `bin/qa/stats.go`) for quantiles/JSONL. Links with **gcc/g++**, not Zig. Ladybug stays the graph; web-search cache stays modernc sqlite. Slice small structured docs with **mikefarah/yq**, not kislyuk/jq. [#30](https://git.produktor.io/eSlider/2dph/issues/30). |
+| D23 | CLI | **flaggy** (`github.com/integrii/flaggy`, 0 deps). Flags at any position. Wrapper `internal/cli`. Bash complete: `source <(./bin/cli/complete.go bash)`. No cobra, no stdlib `flag` in Go tools. Search does not intercept the word `completion`. [#34](https://git.produktor.io/eSlider/2dph/issues/34). |
 
 ## Architecture
 
@@ -67,7 +69,8 @@ detective method: **a fact needs ≥2 independent sources or it is
     brain/add.go            incremental leaf write (no rebuild)
     brain/get.go stats.go eval.go  # Go read (cgo); Python bin/kb/* CI fallback
     brain/watch.go
-    brain/search.go         deduction: facts → info → web-search
+    brain/search.go         deduction: facts → info → web
+    cli/complete.go         flaggy bash/zsh/fish complete (D23)
     brain/serve.go          HTTP API in-process + OpenAPI/MCP (D20); Zig CGO (D21)
     cgo/zig zcc zc++        CGO toolchain (zig cc, not gcc)
     mail/import.go          JSON → markdown (no brain write)

bin/cli/complete.go

@@ -0,0 +1,91 @@
+//usr/bin/env go run "$0" "$@"; exit
+//
+// bin/cli/complete.go - dump flaggy shell completions for all Go shebang tools (D23).
+//
+//	source <(./bin/cli/complete.go bash)
+//	./bin/cli/complete.go zsh|fish|powershell|nushell
+//
+// Search does not steal the word "completion"; this binary dumps scripts.
+// NOTE: never run `gofmt -w` on this file — it breaks the shebang.
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	mailsync "github.com/eSlider/2dph/bin/mail/sync"
+	"github.com/eSlider/2dph/internal/brain/rank"
+	"github.com/eSlider/2dph/internal/chats"
+	"github.com/eSlider/2dph/internal/cli"
+	"github.com/eSlider/2dph/internal/gitlog"
+	"github.com/eSlider/2dph/internal/mdleaves"
+	"github.com/eSlider/2dph/internal/ocr"
+	"github.com/eSlider/2dph/internal/reasoner"
+	"github.com/eSlider/2dph/internal/websearch"
+	"github.com/integrii/flaggy"
+)
+
+func tools() []cli.Tool {
+	return []cli.Tool{
+		{Path: "bin/brain/search.go", Name: "brain-search", New: rank.Parser},
+		{Path: "bin/brain/get.go", Name: "brain-get", New: func() *flaggy.Parser {
+			o := rank.GetOptions{}
+			return rank.GetParser(&o)
+		}},
+		{Path: "bin/brain/stats.go", Name: "brain-stats", New: rank.StatsParser},
+		{Path: "bin/brain/eval.go", Name: "brain-eval", New: rank.EvalParser},
+		{Path: "bin/web/search.go", Name: "web-search", New: websearch.Parser},
+		{Path: "bin/git/import.go", Name: "git-import", New: gitlog.Parser},
+		{Path: "bin/markdown/import.go", Name: "markdown-import", New: mdleaves.Parser},
+		{Path: "bin/qa/stats.go", Name: "qa-stats", New: cli.QAParser},
+		{Path: "bin/reasoner/bakeoff.go", Name: "reasoner-bakeoff", New: reasoner.Parser},
+		{Path: "bin/mail/ocr.go", Name: "mail-ocr", New: ocr.Parser},
+		{Path: "bin/mail/sync.go", Name: "mail-sync", New: mailsync.Parser},
+		{Path: "bin/chats/sync.go", Name: "chats-sync", New: chats.SyncParser},
+		{Path: "bin/chats/import.go", Name: "chats-import", New: chats.ImportParser},
+		{Path: "bin/chats/facts.go", Name: "chats-facts", New: chats.FactsParser},
+		{Path: "bin/chats/apply.go", Name: "chats-apply", New: chats.ApplyParser},
+	}
+}
+
+func main() {
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	shell := "bash"
+	if len(args) > 0 {
+		switch args[0] {
+		case "bash", "zsh", "fish", "powershell", "nushell":
+			shell = args[0]
+		case "-h", "--help", "help":
+			fmt.Fprintln(os.Stderr, "usage: bin/cli/complete.go [bash|zsh|fish|powershell|nushell]")
+			return 0
+		default:
+			fmt.Fprintf(os.Stderr, "cli/complete: unknown shell %q\n", args[0])
+			return 2
+		}
+	}
+	if shell == "bash" {
+		fmt.Print(cli.BashScript(tools()))
+		return 0
+	}
+	var b strings.Builder
+	for _, t := range tools() {
+		p := t.New()
+		p.Name = t.Name
+		switch shell {
+		case "zsh":
+			b.WriteString(flaggy.GenerateZshCompletion(p))
+		case "fish":
+			b.WriteString(flaggy.GenerateFishCompletion(p))
+		case "powershell":
+			b.WriteString(flaggy.GeneratePowerShellCompletion(p))
+		case "nushell":
+			b.WriteString(flaggy.GenerateNushellCompletion(p))
+		}
+	}
+	fmt.Print(b.String())
+	return 0
+}

bin/git/import.go

@@ -16,9 +16,8 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"strconv"
-	"time"
 
+	cliparse "github.com/eSlider/2dph/internal/cli"
 	"github.com/eSlider/2dph/internal/cmdbin"
 	"github.com/eSlider/2dph/internal/gitlog"
 )
@@ -28,49 +27,16 @@ func main() {
 }
 
 func run(args []string) int {
-	var repo, root, since string
-	limit := 0
-	jsonOut := false
-	i := 0
-	for i < len(args) {
-		a := args[i]
-		switch {
-		case a == "--json":
-			jsonOut = true
-		case a == "--limit" && i+1 < len(args):
-			i++
-			n, err := strconv.Atoi(args[i])
-			if err != nil || n < 0 {
-				fmt.Fprintf(os.Stderr, "git/import: --limit must be a non-negative integer\n")
-				return 2
-			}
-			limit = n
-		case a == "--since" && i+1 < len(args):
-			i++
-			since = args[i]
-		case a == "--root" && i+1 < len(args):
-			i++
-			root = args[i]
-		case a == "-h" || a == "--help":
-			fmt.Fprintln(os.Stderr, `usage: bin/git/import.go [REPO] [--json] [--limit N] [--since DATE] [--root DIR]`)
-			return 0
-		case len(a) > 0 && a[0] != '-':
-			repo = a
-		default:
-			fmt.Fprintf(os.Stderr, "git/import: unknown flag %s\n", a)
-			return 2
-		}
-		i++
+	c, err := gitlog.ParseArgs(args)
+	if err != nil {
+		return cliparse.Fail(err)
 	}
+	repo, root, since, limit, jsonOut := c.Repo, c.Root, c.Since, c.Limit, c.JSONOut
 
-	var sinceT time.Time
-	if since != "" {
-		var err error
-		sinceT, err = parseSince(since)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "git/import: %v\n", err)
-			return 2
-		}
+	sinceT, err := gitlog.ParseSince(since)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "git/import: %v\n", err)
+		return 2
 	}
 
 	repos := []string{}
@@ -132,12 +98,3 @@ func run(args []string) int {
 	}
 	return 0
 }
-
-func parseSince(s string) (time.Time, error) {
-	for _, layout := range []string{time.RFC3339, "2006-01-02"} {
-		if t, err := time.Parse(layout, s); err == nil {
-			return t, nil
-		}
-	}
-	return time.Time{}, fmt.Errorf("cannot parse --since %q", s)
-}

bin/mail/ocr.go

@@ -17,6 +17,7 @@ import (
 	"os"
 	"strings"
 
+	cliparse "github.com/eSlider/2dph/internal/cli"
 	"github.com/eSlider/2dph/internal/ocr"
 )
 
@@ -25,15 +26,12 @@ func main() {
 }
 
 func run(args []string) int {
-	if len(args) != 1 || strings.HasPrefix(args[0], "-") {
-		fmt.Fprintln(os.Stderr, `usage: bin/mail/ocr.go <image|pdf>`)
-		return 2
+	c, err := ocr.ParseArgs(args)
+	if err != nil {
+		return cliparse.Fail(err)
 	}
-	path := args[0]
-	var (
-		text string
-		err  error
-	)
+	path := c.Path
+	var text string
 	if strings.HasSuffix(strings.ToLower(path), ".pdf") {
 		text, err = ocr.PDFFile(path)
 	} else {