nano-brain 2026.1.0

package/openspec/changes/codebase-indexing/tasks.md

@@ -0,0 +1,56 @@
+## 1. Types and Configuration
+
+- [x] 1.1 Add `CodebaseConfig` interface to `src/types.ts` with fields: `enabled: boolean`, `exclude?: string[]`, `extensions?: string[]`, `maxFileSize?: string`, `maxSize?: string`
+- [x] 1.2 Add optional `codebase?: CodebaseConfig` field to `CollectionConfig` interface in `src/types.ts`
+- [x] 1.3 Add `CodebaseIndexResult` interface to `src/types.ts` with fields: `filesScanned`, `filesIndexed`, `filesSkippedUnchanged`, `filesSkippedTooLarge`, `filesSkippedBudget`, `chunksCreated`, `storageUsedBytes`, `maxSizeBytes`
+- [x] 1.4 Add `codebase` stats to `IndexHealth` interface: `codebase?: { enabled: boolean; documents: number; chunks: number; extensions: string[]; excludeCount: number; storageUsed: number; maxSize: number }`
+
+## 2. Codebase Scanner Module
+
+- [x] 2.1 Create `src/codebase.ts` with built-in default exclude patterns, project type marker file map
+- [x] 2.2 Implement `detectProjectType(workspaceRoot: string): string[]` — check marker files, return merged extensions list, always include `.md`
+- [x] 2.3 Implement `loadGitignorePatterns(workspaceRoot: string): string[]` — parse `.gitignore` from workspace root, return patterns array, return empty array if file missing
+- [x] 2.4 Implement `mergeExcludePatterns(config: CodebaseConfig, workspaceRoot: string): string[]` — merge config excludes + .gitignore + built-in defaults into single array
+- [x] 2.5 Implement `resolveExtensions(config: CodebaseConfig, workspaceRoot: string): string[]` — return config extensions if set, otherwise auto-detect from project type
+- [x] 2.6 Implement `scanCodebaseFiles(workspaceRoot: string, config: CodebaseConfig): Promise<{ files: string[]; skippedTooLarge: number }>` — use fast-glob with resolved extensions as pattern and merged excludes as ignore, filter by maxFileSize (default 5MB), return absolute paths
+- [x] 2.7 Implement `indexCodebase(store, workspaceRoot, config, projectHash, embedder?): Promise<CodebaseIndexResult>` — scan files, compute hashes, skip unchanged, chunk with `chunkSourceCode`, index via store, deactivate deleted files, embed new chunks, enforce maxSize budget
+
+## 3. Source Code Chunker
+
+- [x] 3.1 Add `findSourceCodeBreakPoints(content: string): BreakPoint[]` to `src/chunker.ts` — score structural boundaries: double blank lines (score 90), function/class/type definitions at line start (score 80), single blank lines (score 40), import/export blocks (score 60), regular line breaks (score 1)
+- [x] 3.2 Add `chunkSourceCode(content: string, hash: string, filePath: string, workspaceRoot: string, options?: ChunkOptions): MemoryChunk[]` to `src/chunker.ts` — split using source code break points, prepend metadata header (`File:`, `Language:`, `Lines:`) to each chunk, use same target size (3600 chars) and overlap (540 chars) as markdown chunker
+- [x] 3.3 Add `inferLanguage(filePath: string): string` helper — map file extension to language name (`.ts` → `typescript`, `.py` → `python`, `.go` → `go`, etc.)
+
+## 4. Watcher Integration
+
+- [x] 4.1 Add `codebaseConfig?: CodebaseConfig` and `workspaceRoot?: string` and `projectHash?: string` fields to `WatcherOptions` interface in `src/watcher.ts`
+- [x] 4.2 In `setupWatcher()`, when `codebaseConfig?.enabled`, add workspace root as additional chokidar watch target with merged exclude patterns as `ignored` option
+- [x] 4.3 In watcher file change handlers (`add`, `change`, `unlink`), check if file matches codebase extensions (not just `.md`) and trigger `handleFileChange` accordingly
+- [x] 4.4 In `triggerReindex()`, after collection reindex loop, if codebase is enabled, call `indexCodebase()` for the workspace root
+
+## 5. MCP Server Integration
+
+- [x] 5.1 Register `memory_index_codebase` tool in `src/server.ts` — no required params, calls `indexCodebase()`, returns `CodebaseIndexResult` summary with storage usage. If codebase not enabled, return error message.
+- [x] 5.2 Update `memory_status` handler in `src/server.ts` to include codebase stats section (enabled, document count, storage used/limit, resolved extensions, exclude count) when codebase is enabled
+- [x] 5.3 Load codebase config from `CollectionConfig.codebase` at server startup and pass to watcher setup
+
+## 6. Storage Budget
+
+- [x] 6.1 Add `maxSize?: string` to `CodebaseConfig` (default 2GB)
+- [x] 6.2 Add `getCollectionStorageSize(collection: string): number` to Store interface and implement in `src/store.ts`
+- [x] 6.3 Enforce budget in `indexCodebase()` — track cumulative storage, skip files when over limit
+- [x] 6.4 Report storage usage in `getCodebaseStats()` and `formatStatus()`
+
+## 7. Tests
+
+- [ ] 7.1 Add unit tests for `detectProjectType()` — Node.js, Python, Go, Rust, multi-marker, no-marker scenarios
+- [ ] 7.2 Add unit tests for `loadGitignorePatterns()` — existing .gitignore, missing .gitignore, complex patterns
+- [ ] 7.3 Add unit tests for `mergeExcludePatterns()` — all three sources, missing sources, deduplication
+- [ ] 7.4 Add unit tests for `resolveExtensions()` — explicit config, auto-detect, fallback
+- [ ] 7.5 Add unit tests for `chunkSourceCode()` — TypeScript file, Python file, small file (single chunk), large file (multiple chunks with overlap), metadata header format
+- [ ] 7.6 Add unit tests for `findSourceCodeBreakPoints()` — function defs, class defs, blank lines, import blocks
+- [ ] 7.7 Add unit tests for `inferLanguage()` — all supported extensions, unknown extension
+- [ ] 7.8 Add unit tests for `scanCodebaseFiles()` — respects exclude patterns, respects extensions, skips files over maxFileSize
+- [ ] 7.9 Add integration test for `indexCodebase()` — indexes files, skips unchanged, detects deleted, tags with projectHash, enforces budget
+- [ ] 7.10 Add integration test for `memory_index_codebase` MCP tool — enabled case, disabled case
+- [ ] 7.11 Add integration test for `getCollectionStorageSize()` — returns correct size for collection

package/openspec/specs/mcp-integration-testing/spec.md

@@ -0,0 +1,50 @@
+## Requirements
+
+### Requirement: Integration test infrastructure
+The project SHALL have an integration test file that exercises MCP tool handlers against a real SQLite database with real FTS5 indexes and real sqlite-vec tables.
+
+#### Scenario: Test setup creates real database with indexed documents
+- **WHEN** the integration test suite starts
+- **THEN** a temporary SQLite database is created with sqlite-vec loaded
+- **THEN** at least 2 test documents are indexed with FTS5 entries
+- **THEN** the MCP server's tool handlers are initialized with the real store
+
+#### Scenario: Test teardown cleans up
+- **WHEN** the integration test suite completes
+- **THEN** the temporary database file is deleted
+- **THEN** no test artifacts remain on disk
+
+### Requirement: Search integration tests
+Integration tests SHALL verify that `memory_search` works end-to-end with real FTS5 queries.
+
+#### Scenario: Search finds indexed document
+- **WHEN** `memory_search` handler is called with a query matching an indexed document
+- **THEN** the response contains the matching document with title, path, and snippet
+
+#### Scenario: Search with hyphenated query
+- **WHEN** `memory_search` handler is called with query `nano-brain`
+- **THEN** the response completes without error
+- **THEN** results include documents containing the term
+
+#### Scenario: Search with collection filter
+- **WHEN** `memory_search` handler is called with a collection filter
+- **THEN** only documents from that collection are returned
+
+#### Scenario: Search with empty query
+- **WHEN** `memory_search` handler is called with an empty string query
+- **THEN** the response returns empty results without error
+
+### Requirement: Update integration tests
+Integration tests SHALL verify that `memory_update` works end-to-end.
+
+#### Scenario: Update indexes new files
+- **WHEN** a new markdown file is added to a collection directory
+- **THEN** calling the `memory_update` handler indexes the new file
+- **THEN** the file is searchable via `memory_search`
+
+### Requirement: Status integration tests
+Integration tests SHALL verify that `memory_status` returns accurate information.
+
+#### Scenario: Status reflects indexed documents
+- **WHEN** documents have been indexed
+- **THEN** `memory_status` handler returns correct document count and collection info

package/openspec/specs/mcp-server/spec.md

@@ -0,0 +1,75 @@
+## Purpose
+
+MCP server providing persistent memory tools (search, status, update, get) for AI coding agents via the Model Context Protocol.
+## Requirements
+### Requirement: ESM module compliance
+All source files in `src/` SHALL use ESM `import` syntax exclusively. No `require()` calls SHALL exist in any TypeScript source file.
+
+#### Scenario: Server starts under Node.js ESM runtime
+- **WHEN** the MCP server is started via `node bin/cli.js mcp`
+- **THEN** the server starts without `require is not defined` errors
+- **THEN** all tool handlers execute without CJS/ESM compatibility errors
+
+#### Scenario: No require() in source files
+- **WHEN** running `grep -r "require(" src/` on the source directory
+- **THEN** zero matches are returned (excluding comments and string literals)
+
+### Requirement: Dynamic collection config reload
+The `memory_update` tool handler SHALL reload the collection configuration file on every invocation, not use the cached startup value.
+
+#### Scenario: Collection added after server start
+- **WHEN** a user adds a collection via CLI (`collection add`) while the MCP server is running
+- **THEN** calling `memory_update` through MCP indexes documents from the newly added collection
+- **THEN** no server restart is required
+
+#### Scenario: Collection removed after server start
+- **WHEN** a user removes a collection via CLI while the MCP server is running
+- **THEN** calling `memory_update` through MCP no longer indexes documents from the removed collection
+
+### Requirement: All MCP tool handlers return valid responses
+Every registered MCP tool SHALL return a valid JSON-RPC response for valid inputs, never an unhandled exception.
+
+#### Scenario: memory_search with valid query
+- **WHEN** `memory_search` is called with `{"query": "test"}` via JSON-RPC
+- **THEN** a valid response with `content` array is returned
+
+#### Scenario: memory_update with configured collections
+- **WHEN** `memory_update` is called via JSON-RPC with collections configured
+- **THEN** a valid response with reindex summary is returned, not a runtime error
+
+#### Scenario: memory_status returns health info
+- **WHEN** `memory_status` is called via JSON-RPC
+- **THEN** a valid response with document count, chunk count, and collection info is returned
+
+### Requirement: Search tools support workspace filtering
+The `memory_search`, `memory_vsearch`, and `memory_query` MCP tools SHALL accept an optional `workspace` parameter. When omitted, results are scoped to the current workspace and global documents. When set to `"all"`, results include all workspaces.
+
+#### Scenario: memory_search with default workspace scoping
+- **WHEN** `memory_search` is called with `{"query": "test"}` and no `workspace` parameter
+- **THEN** results are filtered to `currentProjectHash` and `'global'` documents only
+
+#### Scenario: memory_vsearch with workspace="all"
+- **WHEN** `memory_vsearch` is called with `{"query": "test", "workspace": "all"}`
+- **THEN** results include documents from all workspaces
+
+#### Scenario: memory_query with specific workspace
+- **WHEN** `memory_query` is called with `{"query": "test", "workspace": "abc123def456"}`
+- **THEN** results are filtered to `project_hash = 'abc123def456'` and `project_hash = 'global'`
+
+### Requirement: memory_status reports storage usage
+The `memory_status` tool SHALL report per-workspace document counts and total storage size, in addition to existing health information.
+
+#### Scenario: memory_status with workspace data
+- **WHEN** `memory_status` is called after documents from multiple workspaces are indexed
+- **THEN** the response includes a breakdown of document counts per workspace (projectHash)
+- **THEN** the response includes total storage size (DB + sessions directory)
+- **THEN** the response includes storage limit configuration (maxSize, retention, minFreeDisk)
+
+### Requirement: Search tool parameter schema includes workspace
+The MCP tool registration for `memory_search`, `memory_vsearch`, and `memory_query` SHALL include `workspace` in their input schema as an optional string parameter with description explaining the scoping behavior.
+
+#### Scenario: Tool schema advertises workspace parameter
+- **WHEN** an MCP client lists available tools
+- **THEN** `memory_search`, `memory_vsearch`, and `memory_query` each show a `workspace` parameter in their input schema
+- **THEN** the parameter description explains: omit for current workspace, `"all"` for cross-workspace search
+

package/openspec/specs/search-pipeline/spec.md

@@ -0,0 +1,29 @@
+## Requirements
+
+### Requirement: FTS5 query sanitization
+The `searchFTS` function SHALL sanitize user queries before passing them to FTS5 `MATCH`. All user-provided query strings MUST be treated as literal search text, never as FTS5 syntax.
+
+#### Scenario: Query containing hyphenated words
+- **WHEN** user searches for `nano-brain`
+- **THEN** the search treats the entire hyphenated term as a literal phrase, not as `opencode NOT memory`
+
+#### Scenario: Query containing FTS5 column names
+- **WHEN** user searches for `memory architecture`
+- **THEN** the search treats `memory` as a search term, not as a column reference
+- **THEN** no `no such column` error is thrown
+
+#### Scenario: Query containing FTS5 operators
+- **WHEN** user searches for `AND OR NOT NEAR`
+- **THEN** the search treats these as literal words, not as FTS5 boolean operators
+
+#### Scenario: Query containing double quotes
+- **WHEN** user searches for `he said "hello"`
+- **THEN** internal double quotes are escaped and the search completes without SQL error
+
+#### Scenario: Empty or whitespace-only query
+- **WHEN** user searches for `   ` or empty string
+- **THEN** the search returns an empty result set without error
+
+#### Scenario: Normal multi-word query
+- **WHEN** user searches for `sqlite vector search`
+- **THEN** the search returns documents containing those terms, ranked by BM25 relevance

package/openspec/specs/storage-limits/spec.md

@@ -0,0 +1,94 @@
+# storage-limits Specification
+
+## Purpose
+TBD - created by archiving change workspace-scoped-memory-and-storage-limits. Update Purpose after archive.
+## Requirements
+### Requirement: Storage configuration with safe defaults
+The `config.yml` SHALL support a `storage` section with `maxSize`, `retention`, and `minFreeDisk` fields. All fields SHALL be optional with safe defaults: `maxSize: 2GB`, `retention: 90d`, `minFreeDisk: 100MB`.
+
+#### Scenario: Config with all storage fields
+- **WHEN** config.yml contains `storage: { maxSize: "1GB", retention: "30d", minFreeDisk: "200MB" }`
+- **THEN** the server uses those values for eviction and disk safety
+
+#### Scenario: Config with no storage section
+- **WHEN** config.yml has no `storage` section
+- **THEN** the server uses defaults: maxSize=2GB, retention=90d, minFreeDisk=100MB
+
+#### Scenario: Config with partial storage section
+- **WHEN** config.yml contains `storage: { maxSize: "500MB" }`
+- **THEN** `maxSize` is 500MB, `retention` defaults to 90d, `minFreeDisk` defaults to 100MB
+
+### Requirement: Human-readable size and duration parsing
+The storage config parser SHALL accept human-readable size strings (`500MB`, `2GB`, `1TB`) and duration strings (`30d`, `90d`, `1y`). Invalid values SHALL cause a warning log and fall back to defaults.
+
+#### Scenario: Valid size string
+- **WHEN** `maxSize` is set to `"2GB"`
+- **THEN** it is parsed as 2,147,483,648 bytes
+
+#### Scenario: Valid duration string
+- **WHEN** `retention` is set to `"30d"`
+- **THEN** it is parsed as 30 days (2,592,000,000 milliseconds)
+
+#### Scenario: Invalid size string
+- **WHEN** `maxSize` is set to `"banana"`
+- **THEN** a warning is logged: `[storage] Invalid maxSize "banana", using default 2GB`
+- **THEN** the default value of 2GB is used
+
+### Requirement: Retention-based eviction
+During each harvest cycle, the system SHALL delete session markdown files older than the `retention` period and remove their corresponding documents from the SQLite database.
+
+#### Scenario: Session older than retention period
+- **WHEN** a session file has mtime older than `retention` (e.g., 91 days old with 90d retention)
+- **THEN** the session markdown file is deleted from disk
+- **THEN** the corresponding document rows are removed from the `documents` table
+
+#### Scenario: Session within retention period
+- **WHEN** a session file has mtime within the `retention` period (e.g., 30 days old with 90d retention)
+- **THEN** the session file is not deleted
+- **THEN** the document rows remain in the database
+
+### Requirement: Size-based eviction
+After retention eviction, if total storage (SQLite DB + sessions directory) still exceeds `maxSize`, the system SHALL delete the oldest remaining session files until total size is under the limit.
+
+#### Scenario: Storage exceeds maxSize after retention eviction
+- **WHEN** total storage is 2.5GB and `maxSize` is 2GB after retention eviction
+- **THEN** the oldest session files are deleted one by one
+- **THEN** deletion stops when total size drops below 2GB
+
+#### Scenario: Storage under maxSize
+- **WHEN** total storage is 1.5GB and `maxSize` is 2GB
+- **THEN** no size-based eviction occurs
+
+### Requirement: Original session JSON is never deleted
+Eviction SHALL only remove harvested markdown files and their database entries. The original OpenCode session JSON files in `~/.local/share/opencode/storage/` SHALL never be touched by eviction.
+
+#### Scenario: Session evicted
+- **WHEN** a session is evicted due to retention or size limits
+- **THEN** only the harvested markdown file in `~/.nano-brain/sessions/` is deleted
+- **THEN** the original JSON in `~/.local/share/opencode/storage/sessions/` remains untouched
+
+### Requirement: Disk safety guard
+Before any write operation (harvest, reindex, embed), the system SHALL check available disk space. If free disk space is below `minFreeDisk`, all write operations SHALL be skipped and a warning logged.
+
+#### Scenario: Disk space below minFreeDisk
+- **WHEN** available disk space is 50MB and `minFreeDisk` is 100MB
+- **THEN** harvest, reindex, and embed operations are skipped
+- **THEN** a warning is logged: `[storage] Disk space critically low (<100MB free), skipping writes`
+
+#### Scenario: Disk space above minFreeDisk
+- **WHEN** available disk space is 500MB and `minFreeDisk` is 100MB
+- **THEN** all write operations proceed normally
+
+#### Scenario: statfs unavailable
+- **WHEN** `os.statfs()` is not available (older Node.js or restricted environment)
+- **THEN** the disk check is skipped with a warning: `[storage] statfs unavailable, disk safety check disabled`
+- **THEN** all other storage limits (maxSize, retention) still function normally
+
+### Requirement: Orphan embedding cleanup
+Periodically (every 10 harvest cycles), the system SHALL remove embedding vectors whose corresponding documents no longer exist in the `documents` table.
+
+#### Scenario: Document deleted but embedding remains
+- **WHEN** a document is evicted and its row removed from `documents`
+- **THEN** on the next orphan cleanup cycle, the corresponding embedding vector is removed
+- **THEN** no orphaned embeddings accumulate indefinitely
+

package/openspec/specs/workspace-scoping/spec.md

@@ -0,0 +1,70 @@
+# workspace-scoping Specification
+
+## Purpose
+TBD - created by archiving change workspace-scoped-memory-and-storage-limits. Update Purpose after archive.
+## Requirements
+### Requirement: Workspace detection from PWD
+The MCP server SHALL compute a `projectHash` from `process.cwd()` at startup using `sha256(cwd).substring(0, 12)`. This hash SHALL be stored as `currentProjectHash` on the server context and used for all default search filtering.
+
+#### Scenario: Server starts in a workspace directory
+- **WHEN** the MCP server starts with `PWD=/Users/alice/projects/my-app`
+- **THEN** `currentProjectHash` is set to the first 12 characters of `sha256("/Users/alice/projects/my-app")`
+- **THEN** the hash is consistent across restarts in the same directory
+
+#### Scenario: Hash matches harvester convention
+- **WHEN** the MCP server computes `currentProjectHash` for a workspace
+- **THEN** the hash matches the directory name used by the harvester for that workspace's sessions (`sessions/{projectHash}/*.md`)
+
+### Requirement: Document-level project tagging
+The `documents` table SHALL have a `project_hash TEXT` column. Every document indexed from a session file SHALL be tagged with the projectHash extracted from its file path. Non-session documents (MEMORY.md, daily logs) SHALL be tagged with `'global'`.
+
+#### Scenario: New document indexed from session file
+- **WHEN** a document is indexed from path `sessions/abc123def456/session-title.md`
+- **THEN** the document's `project_hash` column is set to `abc123def456`
+
+#### Scenario: New document indexed from non-session file
+- **WHEN** a document is indexed from `MEMORY.md` or a daily log file
+- **THEN** the document's `project_hash` column is set to `'global'`
+
+#### Scenario: Document path does not match session pattern
+- **WHEN** a document is indexed from a path that does not match `sessions/{hash}/*.md`
+- **THEN** the document's `project_hash` column is set to `'global'`
+
+### Requirement: Database migration for existing documents
+On startup, the store SHALL add the `project_hash` column if it does not exist, then backfill existing documents by extracting the projectHash from their file paths.
+
+#### Scenario: First startup after upgrade
+- **WHEN** the store opens a database that lacks the `project_hash` column
+- **THEN** the column is added via `ALTER TABLE documents ADD COLUMN project_hash TEXT DEFAULT 'global'`
+- **THEN** existing documents with paths matching `sessions/{hash}/*.md` are updated with the correct projectHash
+- **THEN** existing documents not matching the pattern retain `project_hash = 'global'`
+
+#### Scenario: Subsequent startup
+- **WHEN** the store opens a database that already has the `project_hash` column
+- **THEN** no migration runs
+- **THEN** no data is modified
+
+### Requirement: Default search scoping to current workspace
+All search operations SHALL filter results to documents matching `currentProjectHash` or `'global'` by default. This ensures searches return only results relevant to the current workspace plus cross-project notes.
+
+#### Scenario: Search without workspace parameter
+- **WHEN** `memory_search` is called with `{"query": "authentication"}` and no `workspace` parameter
+- **THEN** only documents with `project_hash = currentProjectHash` or `project_hash = 'global'` are returned
+- **THEN** documents from other workspaces are excluded
+
+#### Scenario: Global documents always included
+- **WHEN** a search is performed with default workspace scoping
+- **THEN** MEMORY.md entries and daily logs (tagged `'global'`) are included in results
+- **THEN** session documents from other workspaces are excluded
+
+### Requirement: Cross-workspace search opt-in
+All search tools SHALL accept an optional `workspace` parameter. When set to `"all"`, search results SHALL include documents from all workspaces. When set to a specific hash, results SHALL be filtered to that workspace plus `'global'`.
+
+#### Scenario: Search with workspace="all"
+- **WHEN** `memory_search` is called with `{"query": "auth", "workspace": "all"}`
+- **THEN** documents from all workspaces are included in results
+
+#### Scenario: Search with specific workspace hash
+- **WHEN** `memory_search` is called with `{"query": "auth", "workspace": "abc123def456"}`
+- **THEN** only documents with `project_hash = 'abc123def456'` or `project_hash = 'global'` are returned
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "nano-brain",
+  "version": "2026.1.0",
+  "type": "module",
+  "bin": {
+    "nano-brain": "./bin/cli.js"
+  },
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "bun src/index.ts",
+    "start": "node bin/cli.js",
+    "mcp": "node bin/cli.js mcp",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:esm": "! grep -r 'require(' src/ --include='*.ts'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.3",
+    "node-llama-cpp": "^3.3.3",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "tsx": "^4.21.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "bun-types": "^1.3.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/site/build.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, readdirSync, watchFile, statSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const SITE_DIR = __dirname
+const ROOT_DIR = resolve(SITE_DIR, '..')
+const PARTIALS_DIR = join(SITE_DIR, 'partials')
+const OUTPUT = join(ROOT_DIR, 'index.html')
+
+function readFile(path) {
+  return readFileSync(path, 'utf-8')
+}
+
+function build() {
+  const start = Date.now()
+
+  let shell = readFile(join(SITE_DIR, 'shell.html'))
+  const styles = readFile(join(SITE_DIR, 'styles.css'))
+  const script = readFile(join(SITE_DIR, 'script.js'))
+
+  shell = shell.replace('{{styles}}', styles)
+  shell = shell.replace('{{script}}', script)
+
+  shell = shell.replace(/\{\{partial:([a-z0-9-]+)\}\}/g, (_match, name) => {
+    const partialPath = join(PARTIALS_DIR, `_${name}.html`)
+    try {
+      return readFile(partialPath).trimEnd()
+    } catch (err) {
+      console.error(`  ❌ Missing partial: ${partialPath}`)
+      process.exit(1)
+    }
+  })
+
+  writeFileSync(OUTPUT, shell, 'utf-8')
+
+  const size = statSync(OUTPUT).size
+  const kb = (size / 1024).toFixed(1)
+  const ms = Date.now() - start
+  console.log(`  ✅ Built index.html (${kb} KB) in ${ms}ms`)
+}
+
+console.log('🔨 Building nano-brain landing page...')
+build()
+
+if (process.argv.includes('--watch')) {
+  console.log('👀 Watching for changes...')
+
+  const watchTargets = [
+    join(SITE_DIR, 'shell.html'),
+    join(SITE_DIR, 'styles.css'),
+    join(SITE_DIR, 'script.js'),
+    ...readdirSync(PARTIALS_DIR).map((f) => join(PARTIALS_DIR, f)),
+  ]
+
+  for (const file of watchTargets) {
+    watchFile(file, { interval: 300 }, () => {
+      console.log(`  🔄 Changed: ${file.replace(ROOT_DIR + '/', '')}`)
+      build()
+    })
+  }
+}

package/site/partials/_api.html

@@ -0,0 +1,83 @@
+      <section id="api" class="fade-in">
+        <h2 class="section-title">API Reference</h2>
+        <p class="section-subtitle">MCP tools for hybrid search, retrieval, and maintenance.</p>
+        <div class="grid api-grid">
+          <div class="api-card">
+            <h4><span class="chip">memory_search</span></h4>
+            <p>BM25 keyword search.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_vsearch</span></h4>
+            <p>Semantic vector search using embeddings.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_query</span></h4>
+            <p>Full hybrid search with query expansion, RRF fusion, and LLM reranking.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">minScore</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_get</span></h4>
+            <p>Retrieve document by path or docid (#abc123).</p>
+            <div class="params">
+              <span class="chip">id (required)</span>
+              <span class="chip">fromLine</span>
+              <span class="chip">maxLines</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_multi_get</span></h4>
+            <p>Batch retrieve by glob pattern.</p>
+            <div class="params">
+              <span class="chip">pattern (required)</span>
+              <span class="chip">maxBytes (default 50000)</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_write</span></h4>
+            <p>Write to daily log or MEMORY.md.</p>
+            <div class="params">
+              <span class="chip">content (required)</span>
+              <span class="chip">target ("daily" or "memory")</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_status</span></h4>
+            <p>Show index health, collections, model status.</p>
+            <div class="params">
+              <span class="chip">no params</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_update</span></h4>
+            <p>Trigger immediate reindex of all collections.</p>
+            <div class="params">
+              <span class="chip">no params</span>
+            </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_index_codebase</span></h4>
+            <p>Index source files in the current workspace.</p>
+            <div class="params">
+              <span class="chip">root (optional)</span>
+            </div>
+          </div>
+          </div>
+        </div>
+      </section>