Bump client version to 2.2.1

Fix search human-mode output to match engine API response
The Go client struct expected a nested document object and top-level page/section fields, but the engine returns flat results with metadata in chunk_metadata. This caused empty display for title, type, tags, page, and section in human output mode. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 16:18:06 +01:00 · 2026-04-02 16:17:35 +01:00 · 2026-04-02 16:02:00 +01:00 · 2026-03-31 20:50:17 +01:00 · 2026-03-31 20:48:22 +01:00 · 2026-03-30 07:26:16 +01:00
38 changed files with 1204 additions and 326 deletions
@@ -1,2 +1,3 @@
 examples/
-.claude/
+.claude/
 __pycache__/
@@ -0,0 +1,100 @@
 # Developer Guide
 Instructions for building from source, releasing, and contributing to kb.
 ## Building from source
 ### Engine
 ```bash
 cd engine
 # NVIDIA GPU
 KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d
 # AMD GPU (ROCm)
 KB_DATA_PATH=~/kb-data docker compose -f compose.rocm.yaml up -d
 ```
 ### Client
 ```bash
 cd client
 make build    # produces ./kb binary
 make all      # or cross-compile: dist/kb-{os}-{arch}
 ```
 ## Building and releasing
 Client and engine are versioned independently via `client/VERSION` and `engine/VERSION`. Each has its own release script and git tag prefix.
 ### Release client
 ```bash
 ./release-client.sh --gitea              # patch bump, release via Gitea
 ./release-client.sh --github --minor     # minor bump, release via GitHub
 ./release-client.sh --gitea --no-increment  # release current version as-is
 ./release-client.sh --gitea --dry-run    # preview without doing anything
 ```
 Creates tag `client-vX.Y.Z`, builds Go binaries for all platforms, and creates a Gitea/GitHub release with binaries attached.
 The client embeds a `MinEngineVersion` (from `client/MIN_ENGINE_VERSION`) and will hard-fail if the connected engine is too old.
 ### Release engine
 ```bash
 ./release-engine.sh --gitea              # patch bump, release via Gitea
 ./release-engine.sh --github --minor     # minor bump, release via GitHub
 ./release-engine.sh --gitea --no-increment  # release current version as-is
 ./release-engine.sh --gitea --dry-run    # preview without doing anything
 ```
 Creates tag `engine-vX.Y.Z`, builds NVIDIA and ROCm Docker images, creates a Gitea/GitHub release, and pushes images to the registry.
 ### Checking versions
 ```bash
 # Client
 kb --version
 # Engine
 curl http://localhost:8000/api/v1/status | jq .version
 ```
 ### Docker images
 Images are pushed to `docker.dcglab.co.uk/dcg/kb/engine` with tags:
 - `engine-v2.0.6-nvidia` / `engine-v2.0.6-rocm` — versioned
 - `latest-nvidia` / `latest-rocm` — latest release
 Override the registry and org via environment variables:
 ```bash
 REGISTRY=ghcr.io IMAGE_ORG=myorg ./release-engine.sh --github
 ```
 ## API reference
 All endpoints are under `/api/v1/`. Requires `Authorization: Bearer <key>` header when `KB_API_KEY` is set.
 | Method | Endpoint | Description |
 |---|---|---|
 | `GET` | `/health` | Health check (bypasses auth) |
 | `POST` | `/search` | Hybrid search (JSON body) |
 | `POST` | `/jobs` | Upload file/note for ingestion (multipart, returns 202 or 409 if duplicate) |
 | `GET` | `/jobs` | List ingestion jobs |
 | `GET` | `/jobs/{id}` | Job details |
 | `GET` | `/documents` | List documents |
 | `GET` | `/documents/{id}` | Document details with chunks |
 | `GET` | `/documents/{id}/file` | Download original file |
 | `DELETE` | `/documents/{id}` | Remove a document (and stored file) |
 | `PUT` | `/documents/{id}/tags` | Add/remove tags |
 | `GET` | `/tags` | List all tags |
 | `GET` | `/status` | Engine status, GPU info, DB stats |
 | `POST` | `/reindex` | Re-embed all chunks |
 ## Future: ROCm runtime migration
 The `onnxruntime-rocm` execution provider was removed from onnxruntime as of v1.23. AMD is pushing toward the **MIGraphX execution provider** as the replacement for ROCm GPU inference. When upgrading onnxruntime beyond v1.22, the ROCm Dockerfile will need to switch from `onnxruntime-rocm` to `onnxruntime` with the MIGraphX EP and install the `migraphx` runtime libraries instead.
@@ -2,7 +2,7 @@
 Personal knowledge base with hybrid search (full-text + semantic vector search).
-v2 uses a client-server architecture: a **FastAPI engine** running in Docker (with GPU acceleration) and a lightweight **Go CLI client** that talks to it over HTTP.
+v2 uses a client-server architecture: a **FastAPI engine** running in Docker (with optional GPU acceleration) and a lightweight **Go CLI client** that talks to it over HTTP.
 ## Architecture
@@ -10,7 +10,7 @@ v2 uses a client-server architecture: a **FastAPI engine** running in Docker (wi
 Go CLI (kb) ──HTTP──▶ FastAPI Engine (Docker) ──▶ SQLite + GPU
 ```
- **Engine**: Keeps the embedding model warm in GPU memory. Handles search, ingestion, and document management via REST API. Runs in Docker with NVIDIA or AMD GPU support.
+- **Engine**: Keeps the embedding model warm in memory. Handles search, ingestion, and document management via REST API. Runs in Docker with NVIDIA GPU, AMD GPU (ROCm), or CPU-only support.
 - **Client**: Single static Go binary. No Python, no ML dependencies, instant startup. Talks to the engine over HTTP.
 - **Storage**: Single SQLite database with FTS5 (keyword search) and sqlite-vec (vector search). Portable via bind mount — just copy the data directory between hosts.
@@ -43,59 +43,33 @@ docker run -d --name kb-engine \
  -e KB_API_KEY=your-secret-key \
  --restart unless-stopped \
  docker.dcglab.co.uk/dcg/kb/engine:latest-rocm
 # CPU only (no GPU required — smaller image)
 docker run -d --name kb-engine \
  -p 8000:8000 \
  -v ~/kb-data:/data \
  -e KB_MODEL=all-MiniLM-L6-v2 \
  -e KB_API_KEY=your-secret-key \
  --restart unless-stopped \
  docker.dcglab.co.uk/dcg/kb/engine:latest-cpu
 ```
-Or use a compose file — create `compose.yaml`:
+Or use a compose file from the repo:
 ```yaml
 services:
  kb-engine:
    image: docker.dcglab.co.uk/dcg/kb/engine:latest-nvidia  # or latest-rocm
    runtime: nvidia  # remove for ROCm
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    # For ROCm, replace the above runtime/deploy block with:
    # devices:
    #   - "/dev/kfd"
    #   - "/dev/dri"
    # group_add:
    #   - "video"
    ports:
      - "${KB_PORT:-8000}:8000"
    volumes:
      - ${KB_DATA_PATH:-./data}:/data
    environment:
      - KB_MODEL=${KB_MODEL:-all-MiniLM-L6-v2}
      - KB_DEVICE=${KB_DEVICE:-auto}
      - KB_INGEST_DEVICE=${KB_INGEST_DEVICE:-auto}
      - KB_API_KEY=${KB_API_KEY:-}
      - KB_SEARCH_THRESHOLD=${KB_SEARCH_THRESHOLD:-0.01}
      - HF_HUB_OFFLINE=${HF_HUB_OFFLINE:-}
    restart: unless-stopped
 ```
 ```bash
 KB_DATA_PATH=~/kb-data docker compose up -d
 ```
 **From source** (for development):
 ```bash
 cd engine
 # NVIDIA GPU
-KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d
+KB_DATA_PATH=~/kb-data docker compose -f engine/compose.nvidia.yaml up -d
 # AMD GPU (ROCm)
-KB_DATA_PATH=~/kb-data docker compose -f compose.rocm.yaml up -d
+KB_DATA_PATH=~/kb-data docker compose -f engine/compose.rocm.yaml up -d
 # CPU only
 KB_DATA_PATH=~/kb-data docker compose -f engine/compose.cpu.yaml up -d
 ```
-The engine will download the embedding model on first start (~90MB) and load it onto the GPU. Check readiness:
+See [DEVELOPER.md](DEVELOPER.md) to run the engine from source.
 The engine will download the embedding model on first start (~90MB) and load it into memory (GPU or CPU). Check readiness:
 ```bash
 curl http://localhost:8000/api/v1/health
@@ -129,13 +103,7 @@ chmod +x kb
 sudo mv kb /usr/local/bin/
 ```
-**From source** (for development):
+See [DEVELOPER.md](DEVELOPER.md) to build the client from source.
 ```bash
 cd client
 make build    # produces ./kb binary
 make all      # or cross-compile: dist/kb-{os}-{arch}
 ```
 ### 3. Configure the client
@@ -152,9 +120,9 @@ Override via environment variables (`KB_ENGINE_URL`, `KB_API_KEY`) or CLI flags
 ### 4. Use it
 ```bash
-# Quick notes (shorthand — no subcommand needed)
+# Add notes
-kb "Always restart nginx after config changes"
+kb addnote "Always restart nginx after config changes"
-kb "Server room is building 3, floor 2" --tags ops
+kb addnote "Server room is building 3, floor 2" --tags ops
 # Add files (async — uploads and exits immediately)
 kb addfile ~/docs/manual.pdf --tags admin
@@ -212,82 +180,7 @@ rsync -a ~/kb-data/ user@target:/home/user/kb-data/
 KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d
 ```
-Data is GPU-vendor-agnostic — you can ingest on NVIDIA and serve from AMD (or vice versa) with the same data directory.
+Data is device-agnostic — you can ingest on NVIDIA and serve from AMD or CPU (or any combination) with the same data directory.
 ## API reference
 All endpoints are under `/api/v1/`. Requires `Authorization: Bearer <key>` header when `KB_API_KEY` is set.
 | Method | Endpoint | Description |
 |---|---|---|
 | `GET` | `/health` | Health check (bypasses auth) |
 | `POST` | `/search` | Hybrid search (JSON body) |
 | `POST` | `/jobs` | Upload file/note for ingestion (multipart, returns 202 or 409 if duplicate) |
 | `GET` | `/jobs` | List ingestion jobs |
 | `GET` | `/jobs/{id}` | Job details |
 | `GET` | `/documents` | List documents |
 | `GET` | `/documents/{id}` | Document details with chunks |
 | `GET` | `/documents/{id}/file` | Download original file |
 | `DELETE` | `/documents/{id}` | Remove a document (and stored file) |
 | `PUT` | `/documents/{id}/tags` | Add/remove tags |
 | `GET` | `/tags` | List all tags |
 | `GET` | `/status` | Engine status, GPU info, DB stats |
 | `POST` | `/reindex` | Re-embed all chunks |
 ## Building and releasing
 Client and engine are versioned independently via `client/VERSION` and `engine/VERSION`. Each has its own release script and git tag prefix.
 ### Release client
 ```bash
 ./release-client.sh --gitea              # patch bump, release via Gitea
 ./release-client.sh --github --minor     # minor bump, release via GitHub
 ./release-client.sh --gitea --no-increment  # release current version as-is
 ./release-client.sh --gitea --dry-run    # preview without doing anything
 ```
 Creates tag `client-vX.Y.Z`, builds Go binaries for all platforms, and creates a Gitea/GitHub release with binaries attached.
 The client embeds a `MinEngineVersion` (from `client/MIN_ENGINE_VERSION`) and will hard-fail if the connected engine is too old.
 ### Release engine
 ```bash
 ./release-engine.sh --gitea              # patch bump, release via Gitea
 ./release-engine.sh --github --minor     # minor bump, release via GitHub
 ./release-engine.sh --gitea --no-increment  # release current version as-is
 ./release-engine.sh --gitea --dry-run    # preview without doing anything
 ```
 Creates tag `engine-vX.Y.Z`, builds NVIDIA and ROCm Docker images, creates a Gitea/GitHub release, and pushes images to the registry.
 ### Checking versions
 ```bash
 # Client
 kb --version
 # Engine
 curl http://localhost:8000/api/v1/status | jq .version
 ```
 ### Docker images
 Images are pushed to `docker.dcglab.co.uk/dcg/kb/engine` with tags:
 - `engine-v2.0.6-nvidia` / `engine-v2.0.6-rocm` — versioned
 - `latest-nvidia` / `latest-rocm` — latest release
 Override the registry and org via environment variables:
 ```bash
 REGISTRY=ghcr.io IMAGE_ORG=myorg ./release-engine.sh --github
 ```
 ## Future: ROCm runtime migration
 The `onnxruntime-rocm` execution provider was removed from onnxruntime as of v1.23. AMD is pushing toward the **MIGraphX execution provider** as the replacement for ROCm GPU inference. When upgrading onnxruntime beyond v1.22, the ROCm Dockerfile will need to switch from `onnxruntime-rocm` to `onnxruntime` with the MIGraphX EP and install the `migraphx` runtime libraries instead.
 ## Claude Code skill
@@ -10,14 +10,14 @@ Search, manage, and add to the user's personal knowledge base containing PDFs, W
 - User asks "how do I..." style questions that their knowledge base likely covers
 - User wants to save a note, add a file, or manage their knowledge base
-## Quick notes
+## Adding notes
 ```bash
-kb "remember to update DNS records"                # add a note
+kb addnote "remember to update DNS records"                # add a note
-kb "server room is building 3, floor 2" --tags ops # add a tagged note
+kb addnote "server room is building 3, floor 2" --tags ops # add a tagged note
 ```
-Bare text without a subcommand is treated as a note and submitted for ingestion.
+The note text must be a single quoted argument.
 ## Search (primary use case)
@@ -79,6 +79,12 @@ kb jobs --status failed --format json    # filter by status
 kb jobs <job_id> --format json           # job details
 ```
 ## Examples
 ```bash
 kb examples                              # show common usage examples
 ```
 ## Engine status and maintenance
 ```bash
@@ -102,18 +108,14 @@ All commands support:
    {
      "chunk_id": 1423,
      "score": 0.031,
      "score_breakdown": {"fts": 0.016, "vector": 0.015},
      "text": "To install the latest version of git from source...",
-      "source": {
+      "chunk_index": 3,
-        "document_id": 42,
+      "chunk_metadata": {"page": 12},
-        "title": "Git Admin Guide",
+      "title": "Git Admin Guide",
-        "path": "/home/user/docs/git-admin.pdf",
+      "doc_type": "pdf",
-        "type": "pdf",
+      "source_path": "/home/user/docs/git-admin.pdf",
-        "page": 12,
+      "created_at": "2026-03-15T10:30:00",
-        "chunk_index": 3,
+      "tags": ["git", "admin"]
        "total_chunks": 28,
        "tags": ["git", "admin"]
      }
    }
  ],
  "total_matches": 47,
@@ -160,7 +162,7 @@ Use filters when the question implies a specific domain:
 - Always use `--format json` for machine parsing
 - The `score` field is relative, not absolute — compare scores within a result set
- `source.page` is only present for PDF documents
+- `chunk_metadata.page` is only present for PDF documents
- `source.section_header` is only present for markdown documents with headers
+- `chunk_metadata.section_header` is only present for markdown documents with headers
 - Results are already ranked by relevance (hybrid FTS + vector search)
 - Duplicate files are detected at upload time (HTTP 409) — the client handles this gracefully
@@ -1 +1 @@
-2.1.1
+2.2.1
@@ -206,53 +206,3 @@ func uploadFile(client *api.Client, path, tags string) (*uploadResult, error) {
 	return &uploadResult{Raw: result}, nil
 }
 func submitNote(client *api.Client, note, tags string) error {
 	fields := map[string]string{
 		"note": note,
 	}
 	if tags != "" {
 		fields["tags"] = tags
 	}
 	resp, err := client.PostMultipart("/api/v1/jobs", fields, nil)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 	if resp.StatusCode == http.StatusConflict {
 		var result interface{}
 		if err := api.DecodeJSON(resp, &result); err != nil {
 			return fmt.Errorf("failed to decode response: %w", err)
 		}
 		if output.IsJSON() {
 			output.PrintJSON(result)
 		} else {
 			if m, ok := result.(map[string]interface{}); ok {
 				if docID, ok := m["document_id"].(float64); ok {
 					fmt.Printf("Already imported: %s (doc ID: %.0f)\n", m["title"], docID)
 				} else if jobID, ok := m["job_id"].(float64); ok {
 					fmt.Printf("Already queued: %s (job ID: %.0f)\n", m["title"], jobID)
 				}
 			}
 		}
 		return nil
 	}
 	if err := api.CheckError(resp); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 	var result interface{}
 	if err := api.DecodeJSON(resp, &result); err != nil {
 		return fmt.Errorf("failed to decode response: %w", err)
 	}
 	if output.IsJSON() {
 		output.PrintJSON(result)
 	} else {
 		fmt.Println("Queued: note")
 	}
 	return nil
 }
@@ -0,0 +1,88 @@
 package cmd
 import (
 	"fmt"
 	"net/http"
 	"os"
 	"github.com/kb-search/kb/internal/api"
 	"github.com/kb-search/kb/internal/output"
 	"github.com/spf13/cobra"
 )
 var addnoteCmd = &cobra.Command{
 	Use:   "addnote <text>",
 	Short: "Add a text note to the knowledge base",
 	Args: func(cmd *cobra.Command, args []string) error {
 		if len(args) == 0 {
 			return fmt.Errorf("requires a note text argument\n\n  Usage: kb addnote \"your note text here\"")
 		}
 		if len(args) > 1 {
 			return fmt.Errorf("accepts 1 arg but received %d — quote your note text, e.g. kb addnote \"your note text here\"", len(args))
 		}
 		return nil
 	},
 	RunE:  runAddnote,
 }
 func init() {
 	addnoteCmd.Flags().String("tags", "", "tags (comma-separated)")
 	rootCmd.AddCommand(addnoteCmd)
 }
 func runAddnote(cmd *cobra.Command, args []string) error {
 	tags, _ := cmd.Flags().GetString("tags")
 	client := api.NewClient()
 	return submitNote(client, args[0], tags)
 }
 func submitNote(client *api.Client, note, tags string) error {
 	fields := map[string]string{
 		"note": note,
 	}
 	if tags != "" {
 		fields["tags"] = tags
 	}
 	resp, err := client.PostMultipart("/api/v1/jobs", fields, nil)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 	if resp.StatusCode == http.StatusConflict {
 		var result interface{}
 		if err := api.DecodeJSON(resp, &result); err != nil {
 			return fmt.Errorf("failed to decode response: %w", err)
 		}
 		if output.IsJSON() {
 			output.PrintJSON(result)
 		} else {
 			if m, ok := result.(map[string]interface{}); ok {
 				if docID, ok := m["document_id"].(float64); ok {
 					fmt.Printf("Already imported: %s (doc ID: %.0f)\n", m["title"], docID)
 				} else if jobID, ok := m["job_id"].(float64); ok {
 					fmt.Printf("Already queued: %s (job ID: %.0f)\n", m["title"], jobID)
 				}
 			}
 		}
 		return nil
 	}
 	if err := api.CheckError(resp); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 	var result interface{}
 	if err := api.DecodeJSON(resp, &result); err != nil {
 		return fmt.Errorf("failed to decode response: %w", err)
 	}
 	if output.IsJSON() {
 		output.PrintJSON(result)
 	} else {
 		fmt.Println("Queued: note")
 	}
 	return nil
 }
@@ -11,9 +11,9 @@ var examplesCmd = &cobra.Command{
 	Short: "Show common usage examples",
 	Args:  cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Print(`Quick notes:
+		fmt.Print(`Add notes:
-  kb "Remember to update DNS records"
+  kb addnote "Remember to update DNS records"
-  kb "Server room is building 3" --tags ops
+  kb addnote "Server room is building 3" --tags ops
 Add files:
  kb addfile report.pdf
@@ -3,7 +3,6 @@ package cmd
 import (
 	"fmt"
 	"os"
 	"strings"
 	"github.com/kb-search/kb/internal/api"
 	"github.com/kb-search/kb/internal/config"
@@ -23,10 +22,9 @@ var (
 )
 var rootCmd = &cobra.Command{
-	Use:   "kb [\"note text\" | command]",
+	Use:   "kb [command]",
 	Short: "kb-search CLI client",
 	Long:  "A CLI client for the kb-search v2 engine API.\nRun 'kb examples' for common usage patterns.",
 	Args: cobra.ArbitraryArgs,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		if err := config.Load(); err != nil {
 			return err
@@ -34,44 +32,14 @@ var rootCmd = &cobra.Command{
 		config.ApplyFlags(flagEngine, flagFormat, flagAPIKey)
 		return nil
 	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) == 0 {
 			return cmd.Help()
 		}
 		if len(args) == 1 {
 			return fmt.Errorf("unknown command %q\nTo add a note, use: kb \"%s ...\" or pass multiple words", args[0], args[0])
 		}
 		note := strings.Join(args, " ")
 		tags, _ := cmd.Flags().GetString("tags")
 		client := api.NewClient()
 		return submitNote(client, note, tags)
 	},
 }
 func init() {
 	api.SetVersionInfo(Version, MinEngineVersion)
 	rootCmd.Version = Version
 	rootCmd.SetUsageTemplate(`Quick note taking (must be more than one word):
  kb "note text here" [flags]
 Normal usage:
  kb [command] [flags]{{if .HasAvailableSubCommands}}
 Available Commands:{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
 Flags:
 {{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
 Global Flags:
 {{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}
 Use "{{.CommandPath}} [command] --help" for more information about a command.
 `)
 	rootCmd.PersistentFlags().StringVar(&flagEngine, "engine", "", "engine API URL")
 	rootCmd.PersistentFlags().StringVar(&flagFormat, "format", "", "output format (human|json)")
 	rootCmd.PersistentFlags().StringVar(&flagAPIKey, "api-key", "", "API key for authentication")
 	rootCmd.Flags().String("tags", "", "tags for note shorthand (comma-separated)")
 }
 // Execute runs the root command.
@@ -6,36 +6,6 @@ import (
 	"testing"
 )
 func TestRootCmd_SingleWordRejected(t *testing.T) {
 	rootCmd.SetArgs([]string{"infow"})
 	var stderr bytes.Buffer
 	rootCmd.SetErr(&stderr)
 	err := rootCmd.Execute()
 	if err == nil {
 		t.Fatal("expected error for single bare word, got nil")
 	}
 	errMsg := err.Error()
 	if !strings.Contains(errMsg, `unknown command "infow"`) {
 		t.Errorf("expected error to mention unknown command, got: %s", errMsg)
 	}
 	if !strings.Contains(errMsg, "multiple words") {
 		t.Errorf("expected error to suggest multiple words, got: %s", errMsg)
 	}
 }
 func TestRootCmd_MultipleWordsNotRejected(t *testing.T) {
 	rootCmd.SetArgs([]string{"remember", "to", "update", "dns"})
 	err := rootCmd.Execute()
 	// Will fail at API call (no server), but should NOT be the "unknown command" error
 	if err != nil && strings.Contains(err.Error(), "unknown command") {
 		t.Errorf("multi-word input should not be rejected as unknown command, got: %s", err.Error())
 	}
 }
 func TestRootCmd_NoArgs_ShowsHelp(t *testing.T) {
 	rootCmd.SetArgs([]string{})
@@ -52,3 +22,48 @@ func TestRootCmd_NoArgs_ShowsHelp(t *testing.T) {
 		t.Errorf("expected help output, got: %s", output)
 	}
 }
 func TestRootCmd_UnknownCommand_ReturnsError(t *testing.T) {
 	rootCmd.SetArgs([]string{"notacommand"})
 	var stderr bytes.Buffer
 	rootCmd.SetErr(&stderr)
 	err := rootCmd.Execute()
 	if err == nil {
 		t.Fatal("expected error for unknown command, got nil")
 	}
 	errMsg := err.Error()
 	if !strings.Contains(errMsg, "unknown command") {
 		t.Errorf("expected 'unknown command' error, got: %s", errMsg)
 	}
 }
 func TestAddnoteCmd_NoArgs_ReturnsError(t *testing.T) {
 	rootCmd.SetArgs([]string{"addnote"})
 	err := rootCmd.Execute()
 	if err == nil {
 		t.Fatal("expected error for addnote with no args, got nil")
 	}
 	errMsg := err.Error()
 	if !strings.Contains(errMsg, "requires a note text argument") {
 		t.Errorf("expected 'requires a note text argument' error, got: %s", errMsg)
 	}
 }
 func TestAddnoteCmd_TooManyArgs_ReturnsError(t *testing.T) {
 	rootCmd.SetArgs([]string{"addnote", "hello", "world"})
 	err := rootCmd.Execute()
 	if err == nil {
 		t.Fatal("expected error for addnote with too many args, got nil")
 	}
 	errMsg := err.Error()
 	if !strings.Contains(errMsg, "quote your note text") {
 		t.Errorf("expected 'accepts 1 arg' error, got: %s", errMsg)
 	}
 }
@@ -67,15 +67,12 @@ func runSearch(cmd *cobra.Command, args []string) error {
 	var result struct {
 		Results []struct {
-			Score    float64 `json:"score"`
+			Score         float64                `json:"score"`
-			Document struct {
+			Title         string                 `json:"title"`
-				Title string `json:"title"`
+			DocType       string                 `json:"doc_type"`
-				Type  string `json:"doc_type"`
+			Tags          []string               `json:"tags"`
-				Tags  []string `json:"tags"`
+			ChunkMetadata map[string]interface{} `json:"chunk_metadata"`
-			} `json:"document"`
+			Text          string                 `json:"text"`
 			Page    interface{} `json:"page"`
 			Section string      `json:"section"`
 			Text    string      `json:"text"`
 		} `json:"results"`
 	}
@@ -103,26 +100,28 @@ func runSearch(cmd *cobra.Command, args []string) error {
 			snippet = snippet[:200] + "..."
 		}
-		fmt.Printf("\n%d. [%.4f] %s\n", i+1, r.Score, r.Document.Title)
+		fmt.Printf("\n%d. [%.4f] %s\n", i+1, r.Score, r.Title)
 		location := ""
-		if r.Page != nil {
+		if page, ok := r.ChunkMetadata["page"]; ok && page != nil {
-			location = fmt.Sprintf("Page %v", r.Page)
+			location = fmt.Sprintf("Page %v", page)
 		}
-		if r.Section != "" {
+		if section, ok := r.ChunkMetadata["section_header"]; ok && section != nil {
-			if location != "" {
+			if s, ok := section.(string); ok && s != "" {
-				location += " / "
+				if location != "" {
 					location += " / "
 				}
 				location += s
 			}
 			location += r.Section
 		}
 		if location != "" {
 			fmt.Printf("   Location: %s\n", location)
 		}
-		if r.Document.Type != "" {
+		if r.DocType != "" {
-			fmt.Printf("   Type: %s\n", r.Document.Type)
+			fmt.Printf("   Type: %s\n", r.DocType)
 		}
-		if len(r.Document.Tags) > 0 {
+		if len(r.Tags) > 0 {
-			fmt.Printf("   Tags: %s\n", joinStrings(r.Document.Tags))
+			fmt.Printf("   Tags: %s\n", joinStrings(r.Tags))
 		}
 		fmt.Printf("   %s\n", snippet)
 	}
@@ -0,0 +1,36 @@
 FROM ubuntu:24.04
 ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.12 python3.12-venv python3.12-dev python3-pip \
    libpoppler-cpp-dev poppler-utils \
    libgl1 libglib2.0-0 \
    build-essential curl \
    && rm -rf /var/lib/apt/lists/*
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 WORKDIR /app
 COPY pyproject.toml ./
 COPY kb/ kb/
 COPY main.py ./
 COPY VERSION ./
 RUN uv venv .venv && \
    . .venv/bin/activate && \
    uv pip install -e . && \
    uv pip install "sentence-transformers[onnx]" && \
    uv pip install --reinstall torch torchvision --index-url https://download.pytorch.org/whl/cpu
 ENV PATH="/app/.venv/bin:$PATH"
 ENV VIRTUAL_ENV="/app/.venv"
 ENV KB_DEVICE=cpu
 ENV KB_INGEST_DEVICE=cpu
 ENV KB_DATA_DIR=/data
 EXPOSE 8000
 VOLUME ["/data"]
 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -0,0 +1,17 @@
 services:
  kb-engine:
    build:
      context: .
      dockerfile: Dockerfile.cpu
    ports:
      - "${KB_PORT:-8000}:8000"
    volumes:
      - ${KB_DATA_PATH:-./data}:/data
    environment:
      - KB_MODEL=${KB_MODEL:-all-MiniLM-L6-v2}
      - KB_DEVICE=cpu
      - KB_INGEST_DEVICE=cpu
      - KB_API_KEY=${KB_API_KEY:-}
      - KB_SEARCH_THRESHOLD=${KB_SEARCH_THRESHOLD:-0.01}
      - HF_HUB_OFFLINE=${HF_HUB_OFFLINE:-}
    restart: unless-stopped
@@ -0,0 +1,4 @@
 #!/bin/bash
 docker stop engine-kb-engine-1
 KB_MODEL=BAAI/bge-base-en-v1.5 KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d --build
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-03-29
@@ -0,0 +1,69 @@
 ## Context
 When a document is ingested, the worker chunks its content and stores each chunk's text in the `chunks` table. FTS5 triggers index that text, and the embedding model embeds it. The document title is stored only in `documents.title` — it never participates in search. This means short documents (or documents whose content lacks the title keywords) are invisible to queries that match the title.
 The reindex endpoint (`POST /api/v1/reindex`) currently reads `chunks.text` and re-embeds it. Any fix must apply consistently at both ingestion and reindex time.
 ## Goals / Non-Goals
 **Goals:**
 - Document titles are searchable via both FTS5 and vector search
 - Section header breadcrumbs (when present in chunk metadata) are also searchable
 - Search results continue to return the original chunk text (no title prefix in the `text` field returned to clients)
 - Existing documents become searchable by title after a `kb reindex`
 - No schema-breaking migration — additive column only
 **Non-Goals:**
 - Changing the chunking strategies themselves (note, markdown, code, docling)
 - Adding a separate title-search endpoint or client-side title filtering
 - Changing the search result JSON structure
 ## Decisions
 ### 1. Add an `enriched_text` column to the `chunks` table
 Store the title-prefixed text in a new `chunks.enriched_text` column alongside the existing `chunks.text`. The `text` column remains the raw chunk content (used for display in search results). The `enriched_text` column holds `"{title}\n\n{section_header}\n\n{text}"` (with section_header omitted when absent).
 **Why not just modify `chunks.text`?** The title would then appear in every search result's text field, which is redundant (title is already a separate field) and would confuse consumers that display results.
 **Why not reconstruct enriched text on-the-fly at search time?** FTS5 uses an external content table and triggers — it needs a real column to index. Reconstructing via JOIN at FTS query time would defeat the purpose of the FTS index.
 ### 2. Point FTS5 at `enriched_text` instead of `text`
 Update the FTS5 virtual table definition and its sync triggers to index `enriched_text` rather than `text`. This is the core change that makes titles searchable via keyword search.
 Since FTS5 external content tables cannot be ALTERed, existing databases require a rebuild: drop and recreate `chunks_fts` and its triggers, then repopulate. This is handled as a schema migration in `init_schema`.
 ### 3. Embed `enriched_text` instead of `text`
 At ingestion time, pass `enriched_text` values to `embed_texts()` instead of raw chunk text. At reindex time, read `enriched_text` from the database. This makes titles searchable via vector similarity too.
 ### 4. Build enriched text in the worker, not in the ingest modules
 The enrichment format is: `"{title}\n\n{chunk_text}"` or `"{title} > {section_header}\n\n{chunk_text}"` when a section header exists in chunk metadata.
 This happens in `worker._process_job()` after chunking and before embedding/insertion. The ingest modules remain unchanged — they continue to return raw chunk text and metadata.
 ### 5. Schema migration adds `enriched_text` and rebuilds FTS
 The `init_schema` function will:
 1. Add `enriched_text TEXT` column to `chunks` if missing
 2. Backfill `enriched_text` from existing data (join with `documents.title` and chunk metadata)
 3. Drop and recreate `chunks_fts` to index `enriched_text` instead of `text`
 4. Recreate the FTS sync triggers
 This is safe because the migration only runs when the column is missing (first startup after upgrade). The backfill uses a single UPDATE...FROM query.
 ## Risks / Trade-offs
 **Slightly larger database** — Each chunk stores the title string twice (once in `enriched_text`, once via the document FK). For a typical KB with short titles this is negligible (< 1% size increase).
 → Acceptable for the search quality improvement.
 **FTS rebuild on upgrade** — First startup after upgrade will rebuild the FTS index, which takes a few seconds for large KBs.
 → This is a one-time cost and happens automatically.
 **Embedding drift** — Existing vector embeddings won't include title context until `kb reindex` is run. The FTS backfill happens automatically, but vectors require an explicit reindex.
 → Document this in release notes. The FTS improvement alone is a significant win even without reindexing vectors.
 **Title changes not propagated** — If a document's title were ever updated, `enriched_text` would be stale. Currently the engine has no title-update endpoint, so this is not a concern.
 → No mitigation needed now. If title editing is added later, it should update enriched_text.
@@ -0,0 +1,28 @@
 ## Why
 Short documents and notes are unsearchable when the user's query matches the document title but not the chunk content. For example, a document titled "Suitcase Locks" containing only "Steve = 1234 / Theresa = 4567" is invisible to both FTS and vector search for the query "suitcase locks". This is because chunk text — the only thing indexed and embedded — does not include the document title. This is a standard RAG deficiency that most pipelines solve by prepending title context to each chunk.
 ## What Changes
 - **Prepend document title to chunk text at ingestion time**: Before embedding and FTS indexing, each chunk's text will be prefixed with the document title (e.g., `"Suitcase Locks\n\n Steve = 363..."`). This ensures the title participates in both full-text and semantic search.
 - **Include section header context in chunk text**: For chunks that have a `section_header` in their metadata, prepend the header breadcrumb too (e.g., `"DCG Lab Hardware > GRIMDAWN > motherboard\n\nMSI X870 Tomahawk..."`). This improves search for queries that reference section names.
 - **Store the raw chunk text separately from the enriched text**: The original chunk text (without title prefix) must remain accessible so that search results don't display the prepended title redundantly — the title is already returned as a separate field.
 - **Reindex command must apply the same enrichment**: When `kb reindex` re-embeds all chunks, it must reconstruct the enriched text (title + section header + chunk text) from stored metadata.
 ## Capabilities
 ### New Capabilities
 - `chunk-enrichment`: Prepending document title and section context to chunk text before indexing and embedding, while preserving the original text for display.
 ### Modified Capabilities
 - `engine-api`: The search endpoint's returned `text` field must continue to show the original chunk text (without the prepended title), so no visible API change, but the internal indexing behaviour changes. The reindex endpoint must apply enrichment consistently.
 ## Impact
 - **Engine ingestion pipeline** (`worker.py`): The `_process_job` function must build enriched text from title + section headers + chunk text before passing to `embed_texts()` and `insert_chunk()`.
 - **Database schema** (`database.py`): Need to store both raw `text` (for display) and enriched `text` (for FTS/embedding), or reconstruct enriched text at index time. Simplest approach: store raw text in `chunks.text`, use enriched text only for FTS content and embedding vectors.
 - **FTS triggers** (`database.py`): The FTS5 external content table currently mirrors `chunks.text`. If we add an `enriched_text` column, the FTS index should be built from that instead.
 - **Reindex flow** (`worker.py` / `database.py`): Must reconstruct enriched text by joining chunk metadata with document title.
 - **Search result enrichment** (`routes/search.py`): No change needed — results already return `chunks.text` (raw) and `documents.title` separately.
 - **All four ingest modules** (`note.py`, `markdown.py`, `code.py`, `docling_pipeline.py`): No changes needed — enrichment happens after chunking, in the worker.
 - **Existing documents**: Require a `reindex` to benefit from the new enrichment. No data migration needed since the original text is preserved.
@@ -0,0 +1,75 @@
 ## ADDED Requirements
 ### Requirement: Chunk text enrichment with document title
 The engine SHALL prepend the document title to each chunk's text before FTS indexing and vector embedding. The enriched text SHALL be stored in a dedicated `enriched_text` column on the `chunks` table. The original chunk text SHALL remain in the `text` column for display purposes.
 The enrichment format SHALL be:
 - Without section header: `"{title}\n\n{chunk_text}"`
 - With section header: `"{title} > {section_header}\n\n{chunk_text}"`
 Where `section_header` is the value from the chunk's metadata `section_header` field, when present.
 #### Scenario: Note ingestion with title enrichment
 - **WHEN** a note titled "Suitcase Locks" with content "Steve = 363" is ingested
 - **THEN** the `chunks.text` column SHALL contain "Steve = 363" and the `chunks.enriched_text` column SHALL contain "Suitcase Locks\n\nSteve = 363"
 #### Scenario: Markdown chunk with section header enrichment
 - **WHEN** a markdown document titled "DCG Lab Hardware" produces a chunk with section_header "GRIMDAWN > motherboard" and text "MSI X870 Tomahawk"
 - **THEN** the `chunks.enriched_text` SHALL contain "DCG Lab Hardware > GRIMDAWN > motherboard\n\nMSI X870 Tomahawk"
 #### Scenario: Chunk without section header
 - **WHEN** a document titled "Docker Tips" produces a chunk with no section_header in metadata and text "dbash() { docker exec -it $1 bash; }"
 - **THEN** the `chunks.enriched_text` SHALL contain "Docker Tips\n\ndbash() { docker exec -it $1 bash; }"
 ---
 ### Requirement: FTS5 indexes enriched text
 The FTS5 virtual table `chunks_fts` SHALL index the `enriched_text` column instead of the `text` column. All FTS sync triggers (insert, update, delete) SHALL operate on `enriched_text`.
 #### Scenario: FTS search matches document title
 - **WHEN** a user searches for "suitcase locks" and a document titled "Suitcase Locks" exists with chunk text "Steve = 363"
 - **THEN** the FTS5 search SHALL return that chunk as a match
 #### Scenario: FTS search still matches chunk content
 - **WHEN** a user searches for "MSI X870" and a chunk contains that text in its body
 - **THEN** the FTS5 search SHALL return that chunk as a match (enrichment does not break content matching)
 ---
 ### Requirement: Vector embeddings use enriched text
 The embedding model SHALL receive `enriched_text` (not raw `text`) when generating vectors during both initial ingestion and reindex operations.
 #### Scenario: Vector search matches document title
 - **WHEN** a user searches semantically for "luggage combination codes" and a document titled "Suitcase Locks" exists
 - **THEN** the vector search SHALL return that chunk with higher similarity than it would without title enrichment
 #### Scenario: Reindex uses enriched text
 - **WHEN** `POST /api/v1/reindex` is called
 - **THEN** the engine SHALL read `enriched_text` from the chunks table and embed that (not `text`)
 ---
 ### Requirement: Schema migration adds enriched_text column
 On startup, `init_schema` SHALL add the `enriched_text` column to the `chunks` table if it does not exist. It SHALL then backfill `enriched_text` for all existing chunks by joining with `documents.title` and parsing chunk metadata for section headers. It SHALL rebuild the FTS5 table and triggers to index `enriched_text`.
 #### Scenario: First startup after upgrade
 - **WHEN** the engine starts and `chunks.enriched_text` column does not exist
 - **THEN** the engine SHALL add the column, backfill all rows, drop and recreate `chunks_fts` to index `enriched_text`, and recreate the FTS sync triggers
 #### Scenario: Subsequent startup
 - **WHEN** the engine starts and `chunks.enriched_text` column already exists
 - **THEN** the engine SHALL not perform any migration and start normally
 ---
 ### Requirement: Search results return raw text
 Search results SHALL continue to return the original chunk text (from `chunks.text`) in the `text` field, not the enriched text. The document title is already returned as a separate `title` field.
 #### Scenario: Search result text field
 - **WHEN** a search returns a chunk from document "Suitcase Locks" with raw text "Steve = 363"
 - **THEN** the result `text` field SHALL be "Steve = 363" (not "Suitcase Locks\n\nSteve = 363")
@@ -0,0 +1,31 @@
 ## MODIFIED Requirements
 ### Requirement: Background ingestion worker
 The engine SHALL run a background worker that processes queued jobs. The worker SHALL process one job at a time. For each job, it SHALL: detect document type, run the appropriate chunking pipeline (Docling for PDFs, header-based for Markdown, AST-based for code, whole-text for notes), build enriched text by prepending the document title (and section header when present) to each chunk's text, generate embeddings using the enriched text and the resident model, insert chunks (with both raw text and enriched text) and vectors into the database, and move the original file to persistent storage.
 #### Scenario: Successful PDF ingestion
 - **WHEN** the background worker picks up a queued PDF job
 - **THEN** it SHALL update the job status to `processing`, run Docling conversion and chunking, build enriched text for each chunk by prepending the document title, embed all chunks using enriched text, insert document and chunks into the database, move the staged file to `{data_dir}/documents/{content_hash}.pdf`, update `documents.stored_path` with the permanent path, store the original filename in `documents.original_filename`, update the job status to `done` with the resulting document_id and chunk count, and clean up the staging entry
 #### Scenario: Ingestion failure
 - **WHEN** the background worker encounters an error during processing (e.g., corrupt PDF)
 - **THEN** it SHALL update the job status to `failed` with the error message, delete the staged file, and continue processing the next queued job
 #### Scenario: Search during active ingestion
 - **WHEN** a search request arrives while the background worker is processing a job
 - **THEN** the search SHALL execute without blocking (SQLite WAL mode) and return results from already-ingested documents
 ---
 ### Requirement: Engine status and reindex
 The engine SHALL provide status information and support re-embedding all chunks. The `version` field in the status response SHALL always be present and SHALL reflect the engine's release version as read from the `VERSION` file. This field is the contract used by clients for compatibility checking.
 #### Scenario: Get engine status
 - **WHEN** a client sends `GET /api/v1/status`
 - **THEN** the engine SHALL return JSON with `version` (string, from VERSION file), model_name, embedding_dim, GPU device info, database stats (document count by type, total chunks, DB size), and queue stats (queued/processing job count)
 #### Scenario: Trigger reindex
 - **WHEN** a client sends `POST /api/v1/reindex`
 - **THEN** the engine SHALL re-embed all existing chunks using the `enriched_text` column and the currently loaded model, and return progress information. This operation SHALL NOT block search queries.
@@ -0,0 +1,33 @@
 ## 1. Schema Migration
 - [x] 1.1 Add `enriched_text TEXT` column to `chunks` table in `database.py:init_schema` (with migration check for existing DBs)
 - [x] 1.2 Write backfill query: `UPDATE chunks SET enriched_text = ... FROM documents` joining title and parsing chunk metadata for section_header
 - [x] 1.3 Drop and recreate `chunks_fts` virtual table to index `enriched_text` instead of `text`
 - [x] 1.4 Update FTS sync triggers (`chunks_ai`, `chunks_ad`, `chunks_au`) to use `enriched_text`
 ## 2. Enrichment Helper
 - [x] 2.1 Create `build_enriched_text(title: str, chunk_text: str, metadata: dict | None) -> str` helper function in `worker.py` (or a shared util) that formats `"{title} > {section_header}\n\n{chunk_text}"` or `"{title}\n\n{chunk_text}"`
 ## 3. Ingestion Pipeline
 - [x] 3.1 Update `worker._process_job()` to build enriched text for each chunk after chunking
 - [x] 3.2 Pass enriched text to `embed_texts()` instead of raw chunk text
 - [x] 3.3 Pass enriched text to `database.insert_chunk()` as the new `enriched_text` parameter
 - [x] 3.4 Update `database.insert_chunk()` to accept and store `enriched_text`
 ## 4. Reindex
 - [x] 4.1 Update `routes/reindex.py` to read `enriched_text` from chunks table and embed that instead of `text`
 ## 5. Search Results
 - [x] 5.1 Verify `search.py:_enrich()` returns `chunks.text` (raw) not `enriched_text` — no change expected, but confirm
 ## 6. Testing
 - [x] 6.1 Test: ingest a short note with a descriptive title, search by title keywords, confirm it is found
 - [x] 6.2 Test: ingest a markdown doc, search by section header, confirm chunks are found
 - [x] 6.3 Test: verify search result `text` field does not contain the prepended title
 - [x] 6.4 Test: run `reindex`, verify enriched text is used for new embeddings
 - [x] 6.5 Test: verify schema migration backfills enriched_text for pre-existing chunks on startup
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-03-31
@@ -0,0 +1,52 @@
 ## Context
 README.md currently serves as a single documentation file for both users and developers. It contains ~290 lines mixing installation/usage instructions with build-from-source steps, release scripts, Docker image internals, and developer notes (e.g., ROCm migration plans). There is no DEVELOPER.md or CONTRIBUTING.md file.
 ## Goals / Non-Goals
 **Goals:**
 - Separate user-facing documentation (README.md) from developer-facing documentation (DEVELOPER.md)
 - README.md should answer: "What is this? How do I install it? How do I use it?"
 - DEVELOPER.md should answer: "How do I build from source? How do I release? How do I contribute?"
 - Provide a clear cross-reference link between the two files
 **Non-Goals:**
 - Rewriting or improving documentation content itself (just moving it)
 - Creating additional docs files (CONTRIBUTING.md, architecture docs, etc.)
 - Changing any code, build scripts, or CI configuration
 ## Decisions
 ### 1. Single DEVELOPER.md file (not multiple docs files)
 All developer content goes into one top-level DEVELOPER.md rather than a `docs/` directory or separate CONTRIBUTING.md / BUILDING.md files. The total developer content is small enough (~80 lines) that splitting further would be unnecessary overhead. A single file at the repo root is immediately discoverable.
 **Alternative considered**: `docs/` directory with multiple files. Rejected because the content volume doesn't justify the structure, and root-level DEVELOPER.md is a well-known convention.
 ### 2. Content split boundary
 Content stays in README.md if it's needed by someone who just wants to **run** kb. Content moves to DEVELOPER.md if it's only needed by someone who wants to **build, modify, or release** kb.
 Specifically moving to DEVELOPER.md:
 - "From source" subsections under both engine and client install
 - Entire "Building and releasing" section (release scripts, version checking, Docker image tags, registry overrides)
 - "Future: ROCm runtime migration" developer note
 Staying in README.md:
 - Architecture overview (helps users understand what they're running)
 - Pre-built image / release install instructions
 - Client configuration
 - Usage examples
 - Engine configuration table
 - Data portability
 - API reference
 - Claude Code skill reference
 ### 3. Cross-reference approach
 A short note in README.md's Quick Start section pointing to DEVELOPER.md for building from source. No back-link needed from DEVELOPER.md since developers will naturally find README.md first.
 ## Risks / Trade-offs
 - **[Stale cross-references]** If DEVELOPER.md sections are renamed, the link from README.md could break. Mitigation: link to the file, not to a specific anchor.
 - **[Discoverability]** Some users who want to build from source might miss DEVELOPER.md. Mitigation: explicit "See DEVELOPER.md" callout in the Quick Start section where "from source" instructions used to be.
@@ -0,0 +1,28 @@
 ## Why
 README.md currently mixes user-facing content (what kb does, how to install and use it) with developer-facing content (building from source, releasing, Docker image internals, architecture deep-dives). Users looking for quick-start instructions have to scroll past release scripts and build commands. Developers looking for contribution/build info have to hunt through user docs. Splitting these into README.md (users) and DEVELOPER.md (developers/contributors) follows standard open-source convention and makes both audiences' experience cleaner.
 ## What Changes
 - **Trim README.md** to focus on user-facing content: what kb is, how to install (from pre-built images/releases), how to configure, how to use, engine configuration reference, data portability, and API reference.
 - **Remove "from source" build instructions** from README.md (both engine and client sections).
 - **Remove "Building and releasing" section** from README.md entirely.
 - **Remove "Future: ROCm runtime migration"** developer note from README.md.
 - **Create DEVELOPER.md** containing: building engine from source, building client from source, release process (client and engine), Docker image details, version checking, ROCm migration notes, and any other contributor-oriented content.
 - **Add a link** from README.md to DEVELOPER.md for developers who want to build from source or contribute.
 ## Capabilities
 ### New Capabilities
 - `developer-docs`: Developer-facing documentation covering building from source, releasing, and contributing.
 ### Modified Capabilities
 (none - no spec-level behavior changes, this is a documentation restructuring)
 ## Impact
 - **Files modified**: `README.md` (trimmed)
 - **Files created**: `DEVELOPER.md` (new)
 - **No code changes**: purely documentation restructuring
 - **No API changes**: no functional impact
@@ -0,0 +1,63 @@
 ## ADDED Requirements
 ### Requirement: DEVELOPER.md exists at repo root
 The repository SHALL have a `DEVELOPER.md` file at the project root containing all developer-facing documentation.
 #### Scenario: File exists
 - **WHEN** a developer navigates to the repository root
 - **THEN** a `DEVELOPER.md` file SHALL be present
 ### Requirement: DEVELOPER.md contains build-from-source instructions
 DEVELOPER.md SHALL contain instructions for building both the engine and client from source.
 #### Scenario: Engine build from source
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include instructions for starting the engine from source using compose files (both NVIDIA and ROCm)
 #### Scenario: Client build from source
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include instructions for building the client binary from source using `make build` and `make all`
 ### Requirement: DEVELOPER.md contains release process
 DEVELOPER.md SHALL document the release process for both client and engine, including release scripts, version bumping, and Docker image tagging.
 #### Scenario: Client release documentation
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include `release-client.sh` usage with flag options (--gitea, --github, --minor, --no-increment, --dry-run)
 #### Scenario: Engine release documentation
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include `release-engine.sh` usage with flag options and Docker image tag conventions
 #### Scenario: Version checking
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include how to check client and engine versions
 ### Requirement: DEVELOPER.md contains developer notes
 DEVELOPER.md SHALL include any forward-looking developer notes such as migration plans or technical debt items.
 #### Scenario: ROCm migration note
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include the ROCm runtime migration note about onnxruntime and MIGraphX
 ### Requirement: README.md excludes developer-only content
 README.md SHALL NOT contain build-from-source instructions, release processes, or developer-only notes.
 #### Scenario: No from-source build steps in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "From source" subsections under engine or client installation
 #### Scenario: No release section in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "Building and releasing" section
 #### Scenario: No developer notes in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "Future: ROCm runtime migration" section
 ### Requirement: README.md cross-references DEVELOPER.md
 README.md SHALL include a link to DEVELOPER.md for users who want to build from source or contribute.
 #### Scenario: Developer link in quick start
 - **WHEN** a user reads the Quick Start section of README.md
 - **THEN** there SHALL be a note pointing to DEVELOPER.md for building from source
@@ -0,0 +1,17 @@
 ## 1. Create DEVELOPER.md
 - [x] 1.1 Create DEVELOPER.md at repo root with engine build-from-source instructions (compose.nvidia.yaml and compose.rocm.yaml)
 - [x] 1.2 Add client build-from-source instructions (make build, make all)
 - [x] 1.3 Add "Building and releasing" section: release-client.sh and release-engine.sh usage with all flag options
 - [x] 1.4 Add version checking instructions (kb --version, curl status endpoint)
 - [x] 1.5 Add Docker image tag conventions and registry override documentation
 - [x] 1.6 Add "Future: ROCm runtime migration" developer note
 ## 2. Trim README.md
 - [x] 2.1 Remove "From source (for development)" subsection under engine quick start
 - [x] 2.2 Remove "From source (for development)" subsection under client installation
 - [x] 2.3 Remove entire "Building and releasing" section
 - [x] 2.4 Remove "Future: ROCm runtime migration" section
 - [x] 2.5 Add cross-reference note to DEVELOPER.md in the Quick Start section for building from source
 - [x] 2.6 Move API reference section from README.md to DEVELOPER.md
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-03-31
@@ -0,0 +1,51 @@
 ## Context
 The kb client currently overloads the root Cobra command to handle both command dispatch and implicit note ingestion. Any unrecognized multi-word input is silently submitted as a note via `POST /api/v1/jobs`. This was introduced to reduce friction for note-taking but has proven error-prone — typos in commands create unwanted notes. A single-word guard was added but multi-word typos still slip through.
 The root command has: custom `ArbitraryArgs` validation, a `RunE` with arg-count branching, a `--tags` flag for the note shorthand, a custom usage template with `isRootCmd` template function, and `submitNote()` living in `add.go`.
 ## Goals / Non-Goals
 **Goals:**
 - Eliminate accidental note creation from mistyped commands
 - Provide a clean, explicit `addnote` command that pairs with existing `addfile`
 - Revert root command to standard Cobra behaviour (no custom args, no custom template)
 - Keep the same API contract — `POST /api/v1/jobs` with `note` field unchanged
 **Non-Goals:**
 - Changing the engine API
 - Modifying `addfile` behaviour
 - Adding new content types (url, bookmark, etc.)
 - Backward compatibility shim for `kb "text"` syntax
 ## Decisions
 ### 1. New `addnote` command in its own file
 Create `client/cmd/addnote.go` with a `cobra.Command` that takes `ExactArgs(1)` — a single quoted string. This mirrors `addfile` which also takes `ExactArgs(1)`.
 **Rationale**: Keeps each command in its own file (consistent with the existing pattern). `ExactArgs(1)` means the user must quote multi-word notes, which is unambiguous and avoids the flag-parsing edge cases that plagued the implicit shorthand.
 **Alternative considered**: Joining `ArbitraryArgs` like the old shorthand. Rejected — this is exactly the ambiguity we're removing.
 ### 2. Move `submitNote()` from `add.go` to `addnote.go`
 The function is only used by the addnote command, so it belongs in the same file.
 **Rationale**: `add.go` becomes purely about file operations (it already is, aside from hosting `submitNote()`). Clean separation.
 ### 3. Fully revert root command to Cobra defaults
 Remove: `ArbitraryArgs`, custom `RunE` (replace with nil — Cobra shows help by default), `--tags` flag on root, custom usage template, `isRootCmd` template function.
 **Rationale**: The root command should do one thing — dispatch to subcommands. All the custom logic was there to support the implicit shorthand which is being removed.
 ### 4. `addnote` gets its own `--tags` flag
 The `--tags` flag moves from the root command to `addnote`, matching how `addfile` already has its own `--tags` flag.
 ## Risks / Trade-offs
 - **Breaking change for existing users** → Mitigated by clear error messaging. If someone types `kb "some text"`, Cobra will say "unknown command". The `examples` command will show the new syntax.
 - **Slightly more typing for notes** (`kb addnote "text"` vs `kb "text"`) → Acceptable trade-off for eliminating accidental ingestion. Tab-completion helps.
 - **Scripts using old syntax will break** → This is intentional. The old syntax was a foot-gun.
@@ -0,0 +1,32 @@
 ## Why
 The implicit note shorthand (`kb "some text"`) makes it too easy to accidentally add notes when mistyping commands. Despite the single-word guard, any multi-word typo (e.g. `kb lisst --type pdf`) silently creates a note. The root command doing double-duty as both command dispatcher and note ingester undermines user trust. Reverting to explicit, structured add commands eliminates accidental ingestion and gives every content type a clear, discoverable verb.
 ## What Changes
 - **New `addnote` command**: `kb addnote <text>` takes a single quoted positional argument and submits it as a note. Supports `--tags`. The `submitNote()` logic moves from `root.go` to a new `addnote.go` command file.
 - **Remove implicit note shorthand**: The root command reverts to standard Cobra behaviour — no `ArbitraryArgs`, no special arg-count logic, no `--tags` flag on root. Unknown input gets Cobra's default "unknown command" error.
 - **Remove custom usage template**: The root command no longer needs the `isRootCmd` template logic. Standard Cobra usage template for all commands.
 - **Update examples**: `examples.go` updated to show `kb addnote` instead of bare `kb "text"`.
 - **Update tests**: Remove implicit note shorthand tests, add `addnote` command tests.
 - **`addfile` unchanged**: Stays exactly as-is.
 - **BREAKING**: `kb "note text"` no longer works. Users must use `kb addnote "note text"`.
 ## Capabilities
 ### New Capabilities
 _(none)_
 ### Modified Capabilities
 - `go-client`: The "Implicit note shorthand" requirement is removed entirely and replaced by a new "Add note command" requirement. The "Add command (file and note ingestion)" requirement description is updated to reflect `addnote` / `addfile` as the two ingestion commands. The root command reverts to standard Cobra behaviour with no custom arg handling or usage template.
 ## Impact
 - `client/cmd/root.go` — remove `ArbitraryArgs`, `RunE` note logic, `--tags` flag, custom usage template, `isRootCmd` template func
 - `client/cmd/add.go` — `submitNote()` function moves to new `addnote.go` (or stays in `add.go` alongside `addfile` — design decision)
 - `client/cmd/addnote.go` — new file defining the `addnote` command
 - `client/cmd/examples.go` — update example text
 - `client/cmd/root_test.go` — remove implicit note shorthand tests, add standard Cobra behaviour tests
 - No engine changes — the API contract (`POST /api/v1/jobs` with `note` field) is unchanged
@@ -0,0 +1,87 @@
 ## ADDED Requirements
 ### Requirement: Add note command
 The client SHALL provide a `kb addnote <text>` command that submits a text note to the engine for ingestion. The command SHALL take exactly one positional argument (the note text) and support a `--tags` flag for comma-separated tags. The note SHALL be submitted via `POST /api/v1/jobs` with the `note` field in a multipart request.
 #### Scenario: Add a note
 - **WHEN** the user runs `kb addnote "remember to update DNS records"`
 - **THEN** the client SHALL submit the text as a note via `POST /api/v1/jobs` and print `Queued: note`
 #### Scenario: Add a note with tags
 - **WHEN** the user runs `kb addnote "server room is building 3" --tags ops`
 - **THEN** the client SHALL submit the note with the specified tags
 #### Scenario: Add a note with JSON output
 - **WHEN** the user runs `kb addnote "my note" --format json`
 - **THEN** the client SHALL output the raw JSON response from the engine
 #### Scenario: Duplicate note detection
 - **WHEN** the user runs `kb addnote "my note"` and the engine returns HTTP 409
 - **THEN** the client SHALL display the duplicate information (document ID or job ID) and exit with code 0
 #### Scenario: Missing argument
 - **WHEN** the user runs `kb addnote` with no arguments
 - **THEN** the client SHALL display an error indicating that the note text argument is required
 #### Scenario: Too many arguments
 - **WHEN** the user runs `kb addnote remember to update dns` (unquoted, multiple args)
 - **THEN** the client SHALL display an error indicating that exactly one argument is required, with a hint to quote the text
 ## MODIFIED Requirements
 ### Requirement: Add command (file and note ingestion)
 The client SHALL provide a `kb addfile` command that uploads files to the engine for async ingestion. The command SHALL validate file extensions before uploading and reject unsupported types. The client SHALL handle duplicate rejection (HTTP 409) and display the existing document information. Notes are handled by the separate `addnote` command — `addfile` is exclusively for file uploads.
 #### Scenario: Add a single file
 - **WHEN** the user runs `kb addfile report.pdf`
 - **THEN** the client SHALL validate the file extension, upload the file via `POST /api/v1/jobs` (multipart), print "Queued: report.pdf", and exit
 #### Scenario: Add a file with tags
 - **WHEN** the user runs `kb addfile manual.pdf --tags car,maintenance`
 - **THEN** the client SHALL include the tags in the multipart upload metadata
 #### Scenario: Add a directory recursively
 - **WHEN** the user runs `kb addfile ~/documents/ --recursive`
 - **THEN** the client SHALL discover all supported files in the directory tree, upload each one sequentially, and print "Queued: N files"
 #### Scenario: Unsupported file extension
 - **WHEN** the user runs `kb addfile photo.jpg`
 - **THEN** the client SHALL print an error listing supported extensions and exit with a non-zero code without making any API call
 #### Scenario: Duplicate file rejected (already ingested)
 - **WHEN** the user runs `kb addfile report.pdf` and the engine returns HTTP 409 with `{"error": "duplicate", "document_id": 42, "title": "report.pdf"}`
 - **THEN** the client SHALL print "Already imported: report.pdf (doc ID: 42)" and exit with code 0
 #### Scenario: Duplicate file rejected (in-flight job)
 - **WHEN** the user runs `kb addfile report.pdf` and the engine returns HTTP 409 with `{"error": "duplicate", "job_id": 7, "title": "report.pdf"}`
 - **THEN** the client SHALL print "Already queued: report.pdf (job ID: 7)" and exit with code 0
 #### Scenario: Duplicate file in recursive add
 - **WHEN** the user runs `kb addfile ~/documents/ --recursive` and some files are rejected as duplicates
 - **THEN** the client SHALL print the duplicate message for each rejected file, continue uploading remaining files, and include a summary (e.g., "Queued: 5 files, 2 duplicates skipped")
 #### Scenario: Duplicate with JSON output
 - **WHEN** the user runs `kb addfile report.pdf --format json` and the engine returns HTTP 409
 - **THEN** the client SHALL output the raw JSON response from the engine including the document_id and title
 #### Scenario: Add with JSON output
 - **WHEN** the user runs `kb addfile report.pdf --format json`
 - **THEN** the client SHALL output the JSON response from the engine including the job_id
 #### Scenario: File not found
 - **WHEN** the user runs `kb addfile nonexistent.pdf`
 - **THEN** the client SHALL print an error and exit with a non-zero code without making any API call
 #### Scenario: Upload failure
 - **WHEN** the upload fails (network error, engine returns 4xx/5xx other than 409)
 - **THEN** the client SHALL print the error and exit with a non-zero code
 ## REMOVED Requirements
 ### Requirement: Implicit note shorthand
 **Reason**: The implicit shorthand caused accidental note creation from mistyped commands. Any unrecognized multi-word input was silently ingested as a note. Replaced by the explicit `addnote` command.
 **Migration**: Replace `kb "note text"` with `kb addnote "note text"`. Replace `kb "note text" --tags foo` with `kb addnote "note text" --tags foo`.
@@ -0,0 +1,29 @@
 ## 1. Create addnote command
 - [x] 1.1 Create `client/cmd/addnote.go` with `addnoteCmd` using `ExactArgs(1)`, `--tags` flag, and `RunE` calling `submitNote()`
 - [x] 1.2 Move `submitNote()` function from `client/cmd/add.go` to `client/cmd/addnote.go`
 ## 2. Revert root command to standard Cobra behaviour
 - [x] 2.1 Remove `ArbitraryArgs`, custom `RunE` logic, and `--tags` flag from root command in `client/cmd/root.go`
 - [x] 2.2 Remove custom usage template and `isRootCmd` template function — let Cobra use its default template
 - [x] 2.3 Set root command to show help when called with no args (standard Cobra `RunE` returning `cmd.Help()` or nil)
 ## 3. Update examples and help text
 - [x] 3.1 Update `client/cmd/examples.go` to show `kb addnote` syntax instead of `kb "text"` shorthand
 - [x] 3.2 Update root command `Long` description to remove reference to note shorthand
 ## 4. Update tests
 - [x] 4.1 Remove implicit note shorthand tests from `client/cmd/root_test.go` (`TestRootCmd_SingleWordRejected`, `TestRootCmd_MultipleWordsNotRejected`)
 - [x] 4.2 Add test for `addnote` command (verify it wires up correctly, takes exactly one arg)
 - [x] 4.3 Add test that root command with unknown args returns an error (standard Cobra behaviour)
 - [x] 4.4 Verify `addfile` tests still pass (no changes expected)
 ## 5. Build and verify
 - [x] 5.1 Run `go build` and verify all commands appear in `kb --help`
 - [x] 5.2 Run `go test ./...` and verify all tests pass
 - [x] 5.3 Verify `kb addnote --help` shows correct usage line and flags
 - [x] 5.4 Verify `kb addfile --help` is unchanged
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-04-02
@@ -0,0 +1,41 @@
 ## Context
 The engine's `/api/v1/search` endpoint returns flat result objects:
 ```json
 {
  "chunk_id": 123,
  "score": 0.031,
  "text": "...",
  "chunk_index": 3,
  "chunk_metadata": {"page": 12, "section_header": "Installation"},
  "title": "Git Admin Guide",
  "doc_type": "pdf",
  "source_path": "/home/user/docs/git-admin.pdf",
  "created_at": "2026-03-15T10:30:00",
  "tags": ["git", "admin"]
 }
 ```
 The Go client's human-mode struct in `client/cmd/search.go` incorrectly expects a nested `document` object and top-level `page`/`section` fields. This causes all metadata to display as zero values.
 ## Goals / Non-Goals
 **Goals:**
 - Fix the search result struct to match the flat engine response
 - Extract `page` and `section_header` from `chunk_metadata` for human display
 - Maintain identical JSON output (already passes through raw response)
 **Non-Goals:**
 - Changing the engine API response format
 - Adding new display fields beyond what was originally intended
 ## Decisions
 **Flatten the struct to match API response.** The result struct will have `Title`, `DocType`, `Tags` as top-level fields (matching `title`, `doc_type`, `tags` JSON keys). `ChunkMetadata` will be decoded as `map[string]interface{}` to extract `page` and `section_header` dynamically, since its contents vary by document type.
 **Why not a typed ChunkMetadata struct?** The metadata keys depend on the ingestion pipeline (PDFs have `page`, markdown has `section_header`, code may have others in future). A map is more resilient to engine-side additions.
 ## Risks / Trade-offs
 - [Minimal risk] If the engine adds new top-level fields, the Go struct silently ignores them — this is existing behavior and acceptable for human-mode display.
@@ -0,0 +1,24 @@
 ## Why
 The Go client's human-mode search output struct expects a nested `document` object and top-level `page`/`section` fields, but the engine API returns flat results with `title`, `doc_type`, `tags` at the result level and `page`/`section_header` inside `chunk_metadata`. This means human-mode display shows empty values for title, type, tags, page, and section.
 ## What Changes
 - Fix the Go client search result struct to match the flat engine API response format
 - Extract `page` and `section_header` from the `chunk_metadata` map instead of expecting them as top-level fields
 - Human-mode output will correctly display document title, type, tags, page number, and section header
 ## Capabilities
 ### New Capabilities
 (none)
 ### Modified Capabilities
 - `go-client`: Fix search result parsing to match actual engine API response shape
 ## Impact
 - `client/cmd/search.go` — struct definition and display logic
 - No API changes, no breaking changes — this is a bug fix aligning the client with the existing API contract
@@ -0,0 +1,40 @@
 ## MODIFIED Requirements
 ### Requirement: Search command
 The client SHALL provide a `kb search <query>` command that sends the query to the engine and displays results.
 #### Scenario: Human-readable search output
 - **WHEN** the user runs `kb search "how to change oil"`
 - **THEN** the client SHALL POST to `/api/v1/search`, and display results in a human-readable format showing rank, score, document title, page/section, doc type, tags, and a text snippet
 - **THEN** the client SHALL parse search results as flat objects with top-level `title`, `doc_type`, `tags`, `score`, `text`, `chunk_index` fields
 - **THEN** the client SHALL extract `page` from `chunk_metadata` when present (PDF documents)
 - **THEN** the client SHALL extract `section_header` from `chunk_metadata` when present (markdown documents)
 #### Scenario: JSON search output
 - **WHEN** the user runs `kb search "query" --format json`
 - **THEN** the client SHALL output the raw JSON response from the engine
 #### Scenario: Search with filters
 - **WHEN** the user runs `kb search "brakes" --tags maintenance --type pdf --top 3`
 - **THEN** the client SHALL include the filters in the API request body
 #### Scenario: Search mode flags
 - **WHEN** the user runs `kb search "error" --fts-only`
 - **THEN** the client SHALL set `fts_only: true` in the request body
 #### Scenario: PDF result with page number
 - **WHEN** a search result has `chunk_metadata` containing `{"page": 12}`
 - **THEN** the human output SHALL display "Page 12" in the location line
 #### Scenario: Markdown result with section header
 - **WHEN** a search result has `chunk_metadata` containing `{"section_header": "Installation > Prerequisites"}`
 - **THEN** the human output SHALL display "Installation > Prerequisites" in the location line
 #### Scenario: Result with both page and section
 - **WHEN** a search result has `chunk_metadata` containing both `page` and `section_header`
 - **THEN** the human output SHALL display both separated by " / "
 #### Scenario: Result with no location metadata
 - **WHEN** a search result has empty `chunk_metadata` or no page/section keys
 - **THEN** the human output SHALL omit the location line entirely
@@ -0,0 +1,14 @@
 ## 1. Fix search result struct
 - [x] 1.1 Replace nested `Document` struct with flat fields (`Title`, `DocType`, `Tags`) matching engine JSON keys
 - [x] 1.2 Add `ChunkMetadata map[string]interface{}` field to capture `chunk_metadata`
 ## 2. Fix display logic
 - [x] 2.1 Update title/type/tags references in the display loop to use the new flat fields
 - [x] 2.2 Extract `page` from `ChunkMetadata` map (replacing top-level `Page` field)
 - [x] 2.3 Extract `section_header` from `ChunkMetadata` map (replacing top-level `Section` field)
 ## 3. Verify
 - [x] 3.1 Build the client and verify it compiles cleanly
@@ -0,0 +1,61 @@
 ### Requirement: DEVELOPER.md exists at repo root
 The repository SHALL have a `DEVELOPER.md` file at the project root containing all developer-facing documentation.
 #### Scenario: File exists
 - **WHEN** a developer navigates to the repository root
 - **THEN** a `DEVELOPER.md` file SHALL be present
 ### Requirement: DEVELOPER.md contains build-from-source instructions
 DEVELOPER.md SHALL contain instructions for building both the engine and client from source.
 #### Scenario: Engine build from source
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include instructions for starting the engine from source using compose files (both NVIDIA and ROCm)
 #### Scenario: Client build from source
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include instructions for building the client binary from source using `make build` and `make all`
 ### Requirement: DEVELOPER.md contains release process
 DEVELOPER.md SHALL document the release process for both client and engine, including release scripts, version bumping, and Docker image tagging.
 #### Scenario: Client release documentation
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include `release-client.sh` usage with flag options (--gitea, --github, --minor, --no-increment, --dry-run)
 #### Scenario: Engine release documentation
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include `release-engine.sh` usage with flag options and Docker image tag conventions
 #### Scenario: Version checking
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include how to check client and engine versions
 ### Requirement: DEVELOPER.md contains developer notes
 DEVELOPER.md SHALL include any forward-looking developer notes such as migration plans or technical debt items.
 #### Scenario: ROCm migration note
 - **WHEN** a developer reads DEVELOPER.md
 - **THEN** it SHALL include the ROCm runtime migration note about onnxruntime and MIGraphX
 ### Requirement: README.md excludes developer-only content
 README.md SHALL NOT contain build-from-source instructions, release processes, or developer-only notes.
 #### Scenario: No from-source build steps in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "From source" subsections under engine or client installation
 #### Scenario: No release section in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "Building and releasing" section
 #### Scenario: No developer notes in README
 - **WHEN** a user reads README.md
 - **THEN** there SHALL be no "Future: ROCm runtime migration" section
 ### Requirement: README.md cross-references DEVELOPER.md
 README.md SHALL include a link to DEVELOPER.md for users who want to build from source or contribute.
 #### Scenario: Developer link in quick start
 - **WHEN** a user reads the Quick Start section of README.md
 - **THEN** there SHALL be a note pointing to DEVELOPER.md for building from source
@@ -53,6 +53,9 @@ The client SHALL provide a `kb search <query>` command that sends the query to t
 #### Scenario: Human-readable search output
 - **WHEN** the user runs `kb search "how to change oil"`
 - **THEN** the client SHALL POST to `/api/v1/search`, and display results in a human-readable format showing rank, score, document title, page/section, doc type, tags, and a text snippet
 - **THEN** the client SHALL parse search results as flat objects with top-level `title`, `doc_type`, `tags`, `score`, `text`, `chunk_index` fields
 - **THEN** the client SHALL extract `page` from `chunk_metadata` when present (PDF documents)
 - **THEN** the client SHALL extract `section_header` from `chunk_metadata` when present (markdown documents)
 #### Scenario: JSON search output
 - **WHEN** the user runs `kb search "query" --format json`
@@ -66,49 +69,57 @@ The client SHALL provide a `kb search <query>` command that sends the query to t
 - **WHEN** the user runs `kb search "error" --fts-only`
 - **THEN** the client SHALL set `fts_only: true` in the request body
 #### Scenario: PDF result with page number
 - **WHEN** a search result has `chunk_metadata` containing `{"page": 12}`
 - **THEN** the human output SHALL display "Page 12" in the location line
 #### Scenario: Markdown result with section header
 - **WHEN** a search result has `chunk_metadata` containing `{"section_header": "Installation > Prerequisites"}`
 - **THEN** the human output SHALL display "Installation > Prerequisites" in the location line
 #### Scenario: Result with both page and section
 - **WHEN** a search result has `chunk_metadata` containing both `page` and `section_header`
 - **THEN** the human output SHALL display both separated by " / "
 #### Scenario: Result with no location metadata
 - **WHEN** a search result has empty `chunk_metadata` or no page/section keys
 - **THEN** the human output SHALL omit the location line entirely
 ---
-### Requirement: Implicit note shorthand
+### Requirement: Add note command
-The client SHALL treat bare string arguments (with no subcommand) as an implicit note only when **more than one argument** is provided. `kb "my note"` SHALL behave identically to submitting a note via `POST /api/v1/jobs`. All persistent flags (`--format`, `--engine`, `--api-key`) and the root `--tags` flag SHALL work with the shorthand form. A single bare word SHALL be rejected with an error message.
+The client SHALL provide a `kb addnote <text>` command that submits a text note to the engine for ingestion. The command SHALL take exactly one positional argument (the note text) and support a `--tags` flag for comma-separated tags. The note SHALL be submitted via `POST /api/v1/jobs` with the `note` field in a multipart request.
-#### Scenario: Quick note via bare argument
+#### Scenario: Add a note
- **WHEN** the user runs `kb "remember to update DNS"`
+- **WHEN** the user runs `kb addnote "remember to update DNS records"`
 - **THEN** the client SHALL submit the text as a note via `POST /api/v1/jobs` and print `Queued: note`
-#### Scenario: Bare argument with tags
+#### Scenario: Add a note with tags
- **WHEN** the user runs `kb "server room is building 3" --tags ops`
+- **WHEN** the user runs `kb addnote "server room is building 3" --tags ops`
 - **THEN** the client SHALL submit the note with the specified tags
-#### Scenario: Bare argument with JSON output
+#### Scenario: Add a note with JSON output
- **WHEN** the user runs `kb "my note" --format json`
+- **WHEN** the user runs `kb addnote "my note" --format json`
 - **THEN** the client SHALL output the raw JSON response from the engine
-#### Scenario: Bare argument duplicate detection
+#### Scenario: Duplicate note detection
- **WHEN** the user runs `kb "my note"` and the engine returns HTTP 409
+- **WHEN** the user runs `kb addnote "my note"` and the engine returns HTTP 409
- **THEN** the client SHALL handle the duplicate response identically to the previous `kb add --note` behaviour
+- **THEN** the client SHALL display the duplicate information (document ID or job ID) and exit with code 0
-#### Scenario: Multiple unquoted words
+#### Scenario: Missing argument
- **WHEN** the user runs `kb remember to update dns` (without quotes)
+- **WHEN** the user runs `kb addnote` with no arguments
- **THEN** the client SHALL join all arguments into a single note string and submit it
+- **THEN** the client SHALL display an error indicating that the note text argument is required
-#### Scenario: Single bare word rejected
+#### Scenario: Too many arguments
- **WHEN** the user runs `kb infow` (a single unrecognized word)
+- **WHEN** the user runs `kb addnote remember to update dns` (unquoted, multiple args)
- **THEN** the client SHALL print to stderr: `Unknown command "infow". Run 'kb --help' for available commands.` followed by a hint about note usage, and exit with a non-zero code
+- **THEN** the client SHALL display an error indicating that exactly one argument is required, with a hint to quote the text
 #### Scenario: No interference with subcommands
 - **WHEN** the user runs `kb search "query"` or any other existing subcommand
 - **THEN** the client SHALL route to the subcommand as before — the implicit note shorthand SHALL NOT interfere
 #### Scenario: No arguments
 - **WHEN** the user runs `kb` with no arguments
 - **THEN** the client SHALL display the help text
 ---
 ### Requirement: Add command (file and note ingestion)
-The client SHALL provide a `kb addfile` command that uploads files to the engine for async ingestion. The command SHALL validate file extensions before uploading and reject unsupported types. The client SHALL handle duplicate rejection (HTTP 409) and display the existing document information. The command SHALL NOT handle notes — notes are submitted via the implicit note shorthand (`kb "text"`).
+The client SHALL provide a `kb addfile` command that uploads files to the engine for async ingestion. The command SHALL validate file extensions before uploading and reject unsupported types. The client SHALL handle duplicate rejection (HTTP 409) and display the existing document information. Notes are handled by the separate `addnote` command — `addfile` is exclusively for file uploads.
 #### Scenario: Add a single file
 - **WHEN** the user runs `kb addfile report.pdf`
@@ -111,9 +111,11 @@ else
    echo "==> Engine version: $VERSION (no increment)"
 fi
-TAG="engine-v${VERSION}"
+GIT_TAG="engine-v${VERSION}"
 DOCKER_TAG="v${VERSION}"
-echo "    Tag:       $TAG"
+echo "    Git tag:   $GIT_TAG"
 echo "    Image tag: $DOCKER_TAG"
 echo "    Registry:  $IMAGE_BASE"
 echo "    Forge CLI: $FORGE"
 echo "    Dry run:   $DRY_RUN"
@@ -125,8 +127,8 @@ echo ""
 echo "==> Pre-flight checks"
 if [[ "$DRY_RUN" == false ]]; then
-    if git -C "$SCRIPT_DIR" rev-parse "$TAG" &>/dev/null; then
+    if git -C "$SCRIPT_DIR" rev-parse "$GIT_TAG" &>/dev/null; then
-        echo "Error: tag $TAG already exists"
+        echo "Error: tag $GIT_TAG already exists"
        exit 1
    fi
 fi
@@ -148,29 +150,32 @@ fi
 #──────────────────────────────────────────────────────────────────────
 echo "==> Building Docker engine images ($VERSION)"
-NVIDIA_IMAGE="${IMAGE_BASE}/engine:${TAG}-nvidia"
+NVIDIA_IMAGE="${IMAGE_BASE}/engine:${DOCKER_TAG}-nvidia"
-ROCM_IMAGE="${IMAGE_BASE}/engine:${TAG}-rocm"
+ROCM_IMAGE="${IMAGE_BASE}/engine:${DOCKER_TAG}-rocm"
 CPU_IMAGE="${IMAGE_BASE}/engine:${DOCKER_TAG}-cpu"
 NVIDIA_LATEST="${IMAGE_BASE}/engine:latest-nvidia"
 ROCM_LATEST="${IMAGE_BASE}/engine:latest-rocm"
 CPU_LATEST="${IMAGE_BASE}/engine:latest-cpu"
 run docker build -t "$NVIDIA_IMAGE" -t "$NVIDIA_LATEST" -f "$ENGINE_DIR/Dockerfile.nvidia" "$ENGINE_DIR"
 run docker build -t "$ROCM_IMAGE" -t "$ROCM_LATEST" -f "$ENGINE_DIR/Dockerfile.rocm" "$ENGINE_DIR"
 run docker build -t "$CPU_IMAGE" -t "$CPU_LATEST" -f "$ENGINE_DIR/Dockerfile.cpu" "$ENGINE_DIR"
 echo ""
 #──────────────────────────────────────────────────────────────────────
 # 4. Commit, tag, and push
 #──────────────────────────────────────────────────────────────────────
-echo "==> Committing and tagging $TAG"
+echo "==> Committing and tagging $GIT_TAG"
 if [[ "$INCREMENT" == true ]]; then
    run git -C "$SCRIPT_DIR" add "$VERSION_FILE"
    run git -C "$SCRIPT_DIR" commit -m "Bump engine version to $VERSION"
 fi
-run git -C "$SCRIPT_DIR" tag -a "$TAG" -m "Release $TAG"
+run git -C "$SCRIPT_DIR" tag -a "$GIT_TAG" -m "Release $GIT_TAG"
 run git -C "$SCRIPT_DIR" push origin HEAD
-run git -C "$SCRIPT_DIR" push origin "$TAG"
+run git -C "$SCRIPT_DIR" push origin "$GIT_TAG"
 echo ""
@@ -179,7 +184,7 @@ echo ""
 #──────────────────────────────────────────────────────────────────────
 echo "==> Creating release via $FORGE"
-RELEASE_TITLE="Engine $TAG"
+RELEASE_TITLE="Engine $GIT_TAG"
 RELEASE_NOTES="## Docker images
 \`\`\`bash
@@ -188,16 +193,19 @@ docker pull ${NVIDIA_IMAGE}
 # AMD GPU (ROCm)
 docker pull ${ROCM_IMAGE}
 # CPU only
 docker pull ${CPU_IMAGE}
 \`\`\`"
 if [[ "$FORGE" == "gh" ]]; then
-    run gh release create "$TAG" \
+    run gh release create "$GIT_TAG" \
        --title "$RELEASE_TITLE" \
        --notes "$RELEASE_NOTES"
 elif [[ "$FORGE" == "tea" ]]; then
    run tea release create \
-        --tag "$TAG" \
+        --tag "$GIT_TAG" \
        --title "$RELEASE_TITLE" \
        --note "$RELEASE_NOTES"
 fi
@@ -213,10 +221,13 @@ run docker push "$NVIDIA_IMAGE"
 run docker push "$NVIDIA_LATEST"
 run docker push "$ROCM_IMAGE"
 run docker push "$ROCM_LATEST"
 run docker push "$CPU_IMAGE"
 run docker push "$CPU_LATEST"
 echo ""
-echo "==> Release $TAG complete!"
+echo "==> Release $GIT_TAG complete!"
 echo ""
 echo "    Images:"
 echo "      $NVIDIA_IMAGE"
 echo "      $ROCM_IMAGE"
 echo "      $CPU_IMAGE"
Author	SHA1	Message	Date
steve	adeba21712	Bump client version to 2.2.1	2026-04-02 16:18:06 +01:00
steve	2d179af557	Fix search human-mode output to match engine API response The Go client struct expected a nested document object and top-level page/section fields, but the engine returns flat results with metadata in chunk_metadata. This caused empty display for title, type, tags, page, and section in human output mode. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 16:17:35 +01:00
steve	a6bab5e55e	Add CPU-only Docker image and fix release tag naming - Add Dockerfile.cpu and compose.cpu.yaml for CPU-only deployments - Use sentence-transformers[onnx] + CPU-only torch for ~4x smaller image - Fix release script: separate git tags (engine-v) from Docker tags (v) - Add CPU image to release build/push pipeline - Update README with CPU deployment instructions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 16:02:00 +01:00
steve	c5191df9c0	Bump client version to 2.2.0	2026-03-31 20:50:17 +01:00
steve	afbe270181	Replace implicit note shorthand with explicit addnote command and split README Two changes: 1. structured-add-commands: The implicit note shorthand (kb "text") caused accidental note creation from mistyped commands. Replaced with explicit kb addnote <text> command. Root command reverts to standard Cobra behaviour. Updated examples, tests, SKILL.md, and specs. 2. split-readme-developer-docs: Moved build-from-source instructions, release process, API reference, and ROCm migration notes from README.md into a new DEVELOPER.md. README now links to DEVELOPER.md for dev workflows. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-31 20:48:22 +01:00
steve	9e957f1a9a	Added pycache to gitignore	2026-03-30 07:26:16 +01:00
steve	bbe6a5e909	Add dev-up script and archive kb-title-in-chunks change Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-30 07:25:22 +01:00