@andespindola/brainlink 0.1.0-beta.8 → 0.1.0-beta.80

package/AGENTS.md

@@ -6,19 +6,19 @@ This file tells coding agents and AI assistants how to use this repository.
 
 Brainlink is a local-first knowledge memory for agents.
 
-It reads a Markdown vault, extracts `[[wiki links]]` and `#tags`, builds a local SQLite full-text index, and returns compact context packages that agents can inject into prompts.
+It reads a Markdown vault, extracts `[[wiki links]]` and `#tags`, builds a local file index at `.brainlink/index.json`, and returns compact context packages that agents can inject into prompts.
 
 ## Source Of Truth
 
 Markdown files are the source of truth.
 
-The SQLite database at `.brainlink/brainlink.db` is a derived index. It can be deleted and rebuilt with:
+The JSON index at `.brainlink/index.json` is derived. It can be deleted and rebuilt with:
 
 ```bash
 npm run dev -- index --vault ./vault
 ```
 
-Do not store permanent knowledge only in SQLite.
+Do not store permanent knowledge only in index artifacts.
 
 By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vault. Passing `--vault` or setting `vault` in `brainlink.config.json` intentionally selects a custom vault such as `./vault`.
 
@@ -83,6 +83,9 @@ Use watch mode while editing notes:
 ```bash
 npm run dev -- server --vault ./vault --watch
 npm run dev -- watch --vault ./vault
+npm run dev -- bench --vault ./vault
+npm run dev -- bench --vault ./vault --watch
+npm run dev -- pack-backup --vault ./vault
 ```
 
 Start MCP over stdio:
@@ -107,10 +110,10 @@ npm run dev -- doctor --vault ./vault
 
 - Keep domain rules in `src/domain`.
 - Keep use cases in `src/application`.
-- Keep filesystem and SQLite details in `src/infrastructure`.
+- Keep filesystem and index details in `src/infrastructure`.
 - Keep CLI concerns in `src/cli`.
 - Prefer pure functions for parsing, ranking, formatting, and transformation.
-- Do not make SQLite the canonical storage layer.
+- Do not make index artifacts the canonical storage layer.
 - Do not add comments with emojis.
 - Keep JSON output backwards compatible where possible.
 

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.1.0-beta.4
+
+- Added bootstrap session-state persistence in `$BRAINLINK_HOME/session-state.json` for vault/agent readiness tracking.
+- Added MCP `brainlink_policy` tool and default bootstrap enforcement for read tools.
+- Added `agent install --self-test` diagnostics and bootstrap readiness details in `agent status`.
+- Added `agent upgrade` for legacy installations to reapply latest MCP/plugin defaults with self-test diagnostics.
+- Added `config doctor --fix` safe autofix mode with dry-run default behavior.
+- Added detailed per-file migration reporting through `migrate-vault --report`.
+- Added `quickstart` command to run plug-and-play vault + bootstrap + agent setup in one flow.
+- Added structured MCP `nextActions` in bootstrap/policy/preflight responses for automatic client continuation.
+- Added default MCP read auto-bootstrap behavior controlled by `brainlink_policy.autoBootstrapOnRead`.
+- Added default MCP startup bootstrap behavior controlled by `brainlink_policy.autoBootstrapOnStartup`.
+- Added CLI MCP policy presets through `blink agent policy --preset fully-auto|strict`.
+- Added write-time non-orphan enforcement by auto-linking notes without wiki edges to agent hub notes.
+- Added MCP `brainlink_policy` presets (`fully-auto`, `strict`) for one-call policy switching.
+- Added MCP write connectivity metadata in `brainlink_add_note`/`brainlink_add_file` responses.
+- Added MCP `brainlink_recommendations` tool for plug-and-play workflow guidance.
+- Improved graph/index robustness by splitting oversized paragraphs into bounded chunks and dropping self-referential links.
+- Added `agentProfiles` configuration support so CLI and MCP can resolve per-agent defaults for mode/limit/tokens.
+- Added short-lived hybrid search cache with automatic invalidation on index changes.
+- Added `stats --extended` observability output with storage, quality and latency probes.
+- Added `docs/QUICKSTART.md` and aligned README/agent docs with the latest CLI/MCP flows.
+- Added middle-out context assembly so chunk selection expands around the strongest note chunk.
+- Added compressed-space pack prefiltering (token bloom index) before `.blpk` decryption and scan.
+- Improved graph UI auto-fit and viewport recovery so loaded nodes are re-centered when zoom/pan drifts to empty canvas.
+- Added cross-platform native desktop GUI auto-open for `blink server` (macOS Swift/WebKit, Windows PowerShell WinForms, Linux Python GTK/WebKit2), with app-window/browser fallback.
+- Changed Linux default UI launch to app-window/browser for lighter startup; Linux native GUI is now opt-in via `BRAINLINK_LINUX_NATIVE_GUI=1`.
+- Added native GUI parent-process monitoring so GUI windows close automatically when `blink server` stops.
+- Improved non-mac browser detection fallback to try installed Edge/Chrome/Firefox/Chromium candidates before system default open.
+- Improved graph filter rendering to keep hub anchor nodes visible (`Memory Hub`/`MOC`/high-degree fallback) for coherent relationship context.
+- Fixed graph modal content loading by correcting agent query parameter composition for `/api/graph-node` and `/api/graph-filter` requests.
+- Improved 50k+ graph rendering performance with viewport-aware spatial node culling, cached render visibility, and node-adjacent edge selection to avoid full graph scans every frame.
+- Added incremental vault indexing with file snapshots to reuse unchanged documents/chunks/embeddings, plus adaptive search-pack rebuild thresholds to avoid full re-compression on small edits.
+- Reduced large-graph HTTP payload size with compact `/api/graph-layout` encoding for high-node vaults and capped transmitted edges to improve UI load responsiveness.
+- Added aggressive graph LOD clustering when zoomed out, dynamic per-zoom edge render budgets, and a dedicated frontend worker for off-main-thread graph filter matching.
+- Improved Linux browser fallback launch stability by auto-applying Chromium compatibility flags (`--ozone-platform=x11`, `--disable-gpu`, `--disable-features=Vulkan,VaapiVideoDecoder`, `--disable-background-networking`) for app-window/browser modes.
+- Improved massive-graph UI responsiveness with stricter render budgets, adaptive heavy-graph frame throttling, reduced interaction hit-test frequency, and URL-first agent selection on initial graph load.
+- Improved 50k+ graph LOD behavior so zoomed-out views render lightweight cluster overviews and progressively reveal nodes/edges only as zoom increases.
+- Added `blink bench` with realtime index phase telemetry and per-run compressed-pack analysis (input/output bytes, ratio, saved space, rebuild reason and duration), including continuous watch mode.
+- Added tunable single-stage search-pack compression settings (`searchPack.rowChunkSize`, `searchPack.compressionLevel`, `searchPack.useDictionary`).
+- Added benchmark guardrails for compression savings and latency regression (`searchPack.guardrailMinSavingsPercent`, `searchPack.guardrailMaxLatencyRegressionPercent`), reported in `blink bench`.
+- Added `blink pack-backup` for offline second-stage compression backups of encrypted `.blpk` packs, outside the online query path.
+- Hardened Linux browser launch flags for Ubuntu 26 Chromium/Wayland compatibility (`--disable-vulkan`, `--use-gl=swiftshader`, `--ozone-platform-hint=x11`).
+- Improved pack resilience by auto-repairing missing search-pack manifests from existing `.blpk` files, avoiding unnecessary full repacks on small incremental updates.
+- Updated Linux graph auto-open behavior to prioritize the system default browser (`xdg-open`) before explicit browser fallbacks.
+- Removed implicit Chromium dependency in Linux auto-open flow; app-window launch is now opt-in (`BRAINLINK_LINUX_APP_WINDOW=1`).
+
+## 0.1.0-beta.3
+
+- Added CLI configuration commands for effective vault management, including `config where`, `config get`, `config doctor` and `config set-vault`.
+- Added explicit `migrate-vault` command with `--dry-run` preview and conflict-preserving copy behavior.
+- Added one-command agent setup through `agent install` plus `agent status` diagnostics.
+- Added MCP `brainlink_bootstrap` default entrypoint guidance for plug-and-play agent memory flows.
+- Added migration coverage for S3 bucket vault targets.
+- Updated architecture and agent-usage documentation to reflect current CLI/MCP behavior and configuration precedence.
+
 ## 0.1.0-beta.2
 
 - Added MCP installation guidance for direct server configuration and local client stores.
@@ -17,8 +73,8 @@
 ## 0.1.0-alpha.0
 
 - Added local-first Markdown vault indexing.
-- Added SQLite FTS, local semantic retrieval, wiki links, backlinks and graph retrieval.
-- Added SQLite semantic bucket indexing to narrow vector candidates for larger vaults.
+- Added local full-text indexing, local semantic retrieval, wiki links, backlinks and graph retrieval.
+- Added semantic candidate bucket indexing to narrow vector candidates for larger vaults.
 - Optimized title/link resolution with precomputed agent-scoped title maps.
 - Added CLI, JSON output, HTTP API and graph UI.
 - Added vault diagnostics: stats, broken links, orphans, validation and doctor.

package/CONTRIBUTING.md

@@ -22,7 +22,7 @@ npm run pack:smoke
 ## Design Rules
 
 - Markdown files are the source of truth.
-- SQLite is a derived index and must remain rebuildable.
+- Local index artifacts are derived and must remain rebuildable.
 - Domain parsing, graph analysis and layout should stay pure and testable.
-- CLI, HTTP, filesystem and SQLite code are adapters around application use cases.
+- CLI, HTTP, filesystem and index code are adapters around application use cases.
 - MCP integration should live outside this package by wrapping the CLI with `--json`.

package/COPYRIGHT.md

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Substructa
+
+This project is licensed under the MIT License.
+
+See [LICENSE](./LICENSE) for full terms.

package/README.md

@@ -52,11 +52,15 @@ LLMs do not have infinite context. Brainlink gives agents an external memory lay
 1. Durable knowledge is written as Markdown.
 2. Notes are connected with `[[wiki links]]`.
 3. Concepts are classified with `#tags`.
-4. Brainlink builds a local SQLite index with FTS records and local embeddings.
+4. Brainlink builds a local JSON index (`.brainlink/index.json`) and private encrypted search packs.
 5. Agents query the index before responding.
 6. Brainlink returns compact, source-backed context.
 
-Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable index.
+Markdown is the source of truth. `.brainlink/index.json` is a rebuildable index artifact.
+After each index run, Brainlink also writes private encrypted search packs at `.brainlink/search-packs/*.blpk` to preserve fast retrieval and portable recovery.
+Online retrieval always uses a single compression stage per pack; optional second-stage compression is reserved for offline backup artifacts only.
+Pack decryption uses a Brainlink key from `$BRAINLINK_HOME/keys` or from `BRAINLINK_SEARCH_PACK_KEY` when explicitly configured.
+Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/context access.
 
 ## Features
 
@@ -64,8 +68,12 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 - Obsidian-compatible `[[wiki links]]` and `#tags`.
 - Weighted graph edges so agents can rank relationship importance and priority.
 - Backlinks, broken-link reports, orphan detection and validation.
-- Full-text, semantic and hybrid retrieval modes.
-- SQLite-backed semantic candidate buckets for larger vaults.
+- Full-text, semantic and hybrid retrieval on a local file index.
+- Middle-out context assembly around the strongest chunk per document.
+- In-process index and context caching with automatic invalidation on index updates.
+- Compressed-space prefiltering for `.blpk` packs before decryption and scan.
+- Incremental indexing that reprocesses only changed markdown files and reuses existing chunks/embeddings for unchanged notes.
+- Adaptive compressed-pack rebuild policy to keep indexing fast during small edit batches.
 - Agent namespaces under `agents/<agent-id>/`.
 - S3-compatible bucket vaults through `s3://bucket/prefix` URIs.
 - CLI with machine-readable `--json` output.
@@ -73,6 +81,14 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 - Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
+- Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
+- Large graph canvas rendering batches regular nodes and edges to reduce per-frame draw calls while keeping selected and hovered items highlighted.
+- Large graph layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
+- Large-segment layout spacing now grows logarithmically to keep initial visual density consistent between medium and very large vaults (for example, ~1k vs ~50k notes).
+- Zoomed-out graph LOD clusters dense regions and progressively expands the focused viewport as zoom increases, including very large vaults.
+- Graph reset starts in macro "galaxy" overview mode and progressively reveals nearby nodes as zoom increases, including smaller vaults.
+- Graph filtering runs in a dedicated browser worker to keep the UI thread responsive during heavy datasets.
+- Edge rendering budgets adapt to zoom level to prevent frame spikes on large graph panoramas.
 
 ## Install
 
@@ -106,6 +122,8 @@ npx @andespindola/brainlink@latest --help
 
 This section is written for agents. If you are an AI agent operating in a user workspace, use this workflow to install and use Brainlink without requiring the user to run commands manually.
 
+For a condensed setup path, see [docs/QUICKSTART.md](./docs/QUICKSTART.md).
+
 ### 1. Check Whether Brainlink Is Installed
 
 ```bash
@@ -280,7 +298,7 @@ export BRAINLINK_S3_FORCE_PATH_STYLE=1
 
 Bucket vaults mirror Markdown into a local cache under
 `$BRAINLINK_HOME/bucket-cache`. The bucket remains canonical; the local
-`.brainlink/brainlink.db` stays a disposable index. Run `index` after remote
+`.brainlink/index.json` stays a disposable index artifact. Run `index` after remote
 bucket changes before relying on `search`, `context`, graph or validation
 commands. Watch mode is only supported for local filesystem vaults.
 
@@ -296,7 +314,7 @@ vault/
     research-agent/
       source-review-policy.md
   .brainlink/
-    brainlink.db
+    index.json
 ```
 
 Permanent data:
@@ -306,7 +324,7 @@ Permanent data:
 
 Rebuildable data:
 
-- `.brainlink/brainlink.db`
+- `.brainlink/index.json`
 - full-text records
 - local embedding vectors
 - local embedding buckets
@@ -380,6 +398,36 @@ Example MCP client configuration:
 }
 ```
 
+### One-Command Agent Setup
+
+If your agent runtime is Codex-compatible, run:
+
+```bash
+blink agent install --self-test
+blink agent upgrade
+```
+
+This configures `~/.codex/config.toml` with Brainlink MCP (`brainlink-mcp`) so Brainlink is available by default in agent sessions.
+`agent install` and `agent upgrade` also apply the MCP `fully-auto` bootstrap policy by default (`enforceBootstrap`, `enforceContextFirst`, `autoBootstrapOnRead`, `autoBootstrapOnStartup` all enabled).
+
+If you are inside this repository and want plugin gallery setup too:
+
+```bash
+blink agent install --plugin-path ./plugins/brainlink
+```
+
+To verify:
+
+```bash
+blink agent status
+```
+
+For fully automated first run (vault index + health + bootstrap readiness + agent integration):
+
+```bash
+blink quickstart --query "what should I know before this task?" --json
+```
+
 For a locked-down setup, allowlist the vaults that MCP clients may access:
 
 ```json
@@ -475,8 +523,13 @@ Restart the client after changing marketplace or MCP configuration so it reloads
 
 Available tools:
 
+- `brainlink_bootstrap`: plug-and-play entrypoint that runs index + health checks and can return context in one call.
+- `brainlink_policy`: read or update bootstrap/context-first policy, including presets (`preset: "fully-auto" | "strict"`).
+- `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order.
 - `brainlink_context`: read indexed context for a task or question.
 - `brainlink_search`: search indexed notes.
+- `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
+- `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
 - `brainlink_index`: rebuild the vault index.
@@ -487,7 +540,15 @@ Available tools:
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
-The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]`. `brainlink_add_note` and `brainlink_add_file` reindex by default and include the index result when enabled.
+For the most automatic workflow, start MCP sessions with `brainlink_bootstrap` (optionally with `query`) and then continue with `brainlink_context`/`brainlink_add_note`.
+By default, Brainlink enforces context-first for MCP reads (`enforceContextFirst=true`): non-context read tools return preflight until `brainlink_context` is called for the vault/agent session.
+By default, MCP startup already runs bootstrap on the configured default vault/agent (`autoBootstrapOnStartup=true`), so sessions begin warm.
+By default, Brainlink enforces bootstrap and auto-runs it for read tools when session state is missing or stale (`autoBootstrapOnRead=true`).
+If you disable `autoBootstrapOnRead` through `brainlink_policy`, read tools return a preflight instruction with suggested `brainlink_bootstrap` arguments.
+`brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so MCP clients can continue automatically without custom parsing.
+For one-call planning, use `brainlink_recommendations` to get the recommended tool sequence for the current vault/agent/query.
+
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]`. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink guarantees at least one edge per new note by auto-linking when needed.
 
 Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
 
@@ -507,16 +568,35 @@ blink server --host 127.0.0.1 --port 4321 --watch
 ```
 
 By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
+By default, `blink server` tries to open the graph in a native desktop GUI window:
+- macOS: Swift + WebKit
+- Windows: PowerShell WinForms WebBrowser
+- Linux: optional Python GTK + WebKit2 (requires `python3` + `gi` + `WebKit2`)
+
+On Linux, native GUI is disabled by default for better startup performance. Enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable on your system, it falls back to dedicated app-window mode and then to the default browser.
+For Chromium-family browsers on Linux (`chromium`, `chromium-browser`, `google-chrome`, `microsoft-edge`, `brave-browser`), Brainlink now auto-applies compatibility flags during launch (`--ozone-platform=x11`, `--ozone-platform-hint=x11`, `--disable-gpu`, `--disable-vulkan`, `--use-gl=swiftshader`, `--disable-features=Vulkan,VaapiVideoDecoder`, `--disable-background-networking`) to avoid common Wayland/Vulkan/VAAPI startup issues.
+On Linux, Brainlink opens the graph through the system default browser first (`xdg-open`), then `$BROWSER`/detected browsers as fallback. Chromium-family app-window mode is optional via `BRAINLINK_LINUX_APP_WINDOW=1`.
+Use `--no-open` to keep it headless.
+When native GUI is used, the GUI window automatically closes when the `blink server` process stops.
 
 The graph UI shows:
 
 - notes as nodes
 - `[[wiki links]]` as weighted edges
-- backlinks and outgoing links
-- full Markdown content for the selected note
+- details opened on node click (tags, outgoing links, backlinks, full Markdown content)
 - neutral graph nodes with segment/group metadata
-- agent selector for isolated views
+- agent selector (id-only labels) for isolated views
+- graph filter matches title, path, tags and note content
+- graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
 - realtime refresh while `--watch` is enabled
+- graph controls for zoom in, zoom out, fit visible nodes and reset-to-fit-all
+- wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
+- keyboard shortcuts: `+` zoom in, `-` zoom out, `0` reset fit
+- double-click on canvas zooms in at cursor position
+- floating graph totals (notes, links, tags) below the Brainlink title
+- large-graph rendering safeguards (batched canvas drawing, edge draw caps, lower redraw rate, zoom-aware interaction)
+- massive-graph LOD progression: very low zoom uses spatial overview sampling plus hub-neighborhood edge previews to preserve whole-vault shape and orientation, then progressively raises the focused node budget as zoom increases so dense local areas keep nearby notes and links visible
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 
@@ -535,6 +615,7 @@ Routes:
 - `GET /api/agents`
 - `GET /api/graph`
 - `GET /api/graph-layout`
+- `GET /api/graph-node?id=<node-id>`
 - `GET /api/search?q=<query>&limit=10&mode=hybrid`
 - `GET /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid`
 - `GET /api/links`
@@ -556,6 +637,79 @@ Read routes accept `agent=<agent-id>`:
 
 Every command works with either `brainlink` or `blink`.
 
+### `agent`
+
+```bash
+blink agent install
+blink agent install --self-test
+blink agent upgrade
+blink agent policy --preset fully-auto
+blink agent policy --preset strict
+blink agent policy --enforce-context-first false
+blink agent install --plugin-path ./plugins/brainlink
+blink agent install --mcp-only --allowed-vaults "/absolute/vault,/absolute/team-vault"
+blink agent status
+```
+
+Installs/checks agent integration. `install` writes Brainlink MCP config into `~/.codex/config.toml`.
+When plugin files are available, it also links Brainlink plugin files into `~/plugins/brainlink` and updates `~/.agents/plugins/marketplace.json`.
+With `--self-test`, install also validates MCP block presence, command wiring and local plugin registration signals.
+Use `agent upgrade` on legacy installations to reapply current defaults and run the same self-test diagnostics.
+Use `agent policy --preset fully-auto` for plug-and-play defaults, or `agent policy --preset strict` to require explicit bootstrap calls.
+Both presets keep `enforceContextFirst=true` so Brainlink stays the primary context source for MCP sessions.
+
+### `quickstart`
+
+```bash
+blink quickstart --json
+blink quickstart --vault ./team-vault --agent coding-agent --query "architecture decisions" --json
+blink quickstart --vault ./team-vault --mcp-only --json
+```
+
+Runs index + doctor + stats + validation, refreshes bootstrap session readiness, optionally returns context for a query, and (by default) upgrades local agent integration for plug-and-play MCP usage.
+When `--mode`, `--limit` or `--tokens` are omitted, quickstart uses agent profile defaults when available.
+
+### `config`
+
+```bash
+blink config where
+blink config get vault
+blink config doctor
+blink config doctor --fix
+blink config set-vault /absolute/path/to/existing-vault
+blink config set-vault /absolute/path/to/existing-vault --migrate-from ~/.brainlink/vault
+blink config set-vault "s3://my-memory-bucket/brainlink" --global
+```
+
+`config set-vault` writes configuration through CLI (no manual file edits required).  
+By default it writes local config (`./brainlink.config.json`), appends the vault to `allowedVaults`, and migrates Markdown memory from the current configured vault when the target is empty.  
+Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrate` to skip migration, and `--no-index` to skip post-migration indexing.
+`config doctor` is dry-run by default; use `--fix` to apply safe config normalization and allowlist fixes.
+
+### `migrate-vault`
+
+```bash
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --dry-run
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault
+blink migrate-vault --from ~/.brainlink/vault --to "s3://my-memory-bucket/brainlink"
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --report ./migration-report.json
+```
+
+Runs explicit markdown migration between vaults while preserving conflicts as `.conflict-<timestamp>` files.  
+Use `--dry-run` to preview `copied`, `conflicted` and `unchanged` counts before writing.
+
+### `db-import`
+
+```bash
+blink db-import --vault ./team-vault
+blink db-import --vault ./team-vault --db ./legacy/brainlink.db
+blink db-import --vault ./team-vault --db ./legacy/brainlink.db --table legacy_notes --dry-run
+```
+
+Imports durable memory from a legacy SQLite database into Markdown notes (`agents/<agent-id>/*.md`) and reindexes by default.
+When `--db` is omitted, Brainlink auto-detects common legacy paths such as `<vault>/.brainlink/brainlink.db`.
+Use `--agent <id>` to force all imported rows into one namespace, `--limit` for incremental imports, `--dry-run` to preview without writing files, and `--no-index` to defer reindexing.
+
 ### `init`
 
 ```bash
@@ -579,6 +733,29 @@ blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 `--content` and `--content-file` are mutually exclusive. Add `--no-auto-index` when you want to defer reindexing.
 
 Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are blocked by default; use `--allow-sensitive` only for an intentionally protected vault.
+To avoid disconnected memory, Brainlink auto-adds a fallback wiki edge when a note is written without links, creating agent hub notes when needed.
+`add` also returns `possibleDuplicates` (exact hash + semantic candidates) so agents can resolve duplicate memory right after writes.
+
+### `dedupe`
+
+```bash
+blink dedupe --vault ./vault --json
+blink dedupe --vault ./vault --agent coding-agent --limit 20 --min-score 0.92 --json
+blink dedupe --vault ./vault --no-semantic --json
+```
+
+Detects `possibleDuplicate` pairs using exact content hashes and optional semantic similarity.
+
+### `dedupe-resolve`
+
+```bash
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action merge --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action link --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action ignore --json
+```
+
+Resolves a duplicate pair with `merge`, `link` or `ignore`.
+When action is not `merge`, Brainlink still creates a low-priority related edge (`#related-to`) so notes remain connected.
 
 ### `index`
 
@@ -589,6 +766,38 @@ blink index --vault ./vault
 
 Rebuilds the local index from Markdown files.
 
+### `bench`
+
+```bash
+blink bench --vault ./vault
+blink bench --vault ./vault --watch
+blink bench --vault ./vault --watch --debounce 500
+blink bench --vault ./vault --json
+```
+
+Runs indexing with realtime phase telemetry (`start`, `scan`, `parse`, `embed`, `persist`, `packs`, `complete`) and prints a benchmark summary at the end of each run.
+
+Summary includes compression behavior for `.blpk` packs when rebuild happens:
+- pack rebuild reason
+- pack count and pack build duration
+- uncompressed input bytes vs compressed output bytes
+- saved percentage
+- objective guardrails (minimum savings and maximum latency regression thresholds)
+
+Use `--watch` to keep benchmarking incremental reindex runs after Markdown changes (local filesystem vaults only).
+When `.brainlink/search-packs/manifest.json` is missing but `.blpk` files exist, Brainlink repairs the manifest first and avoids unnecessary full pack rebuild on small edits.
+
+### `pack-backup`
+
+```bash
+blink pack-backup --vault ./vault
+blink pack-backup --vault ./vault --output ./vault/.brainlink/backups/custom.blpkbak.gz
+blink pack-backup --vault ./vault --json
+```
+
+Creates an offline backup artifact of encrypted search packs with a second compression pass.
+This is intentionally outside the online retrieval path (`index`, `search`, `context`).
+
 ### `agents`
 
 ```bash
@@ -607,13 +816,17 @@ blink search "query" --vault ./vault --mode semantic --json
 ```
 
 Runs retrieval over indexed chunks.
+If `--mode` or `--limit` is omitted, Brainlink resolves values from the current agent profile before falling back to global defaults.
 
 Modes:
 
-- `hybrid`: default; combines SQLite FTS with local embedding similarity.
-- `fts`: exact lexical retrieval through SQLite FTS.
+- `hybrid`: default; combines lexical matching with local embedding similarity.
+- `fts`: exact lexical retrieval from the file index.
 - `semantic`: local deterministic embedding similarity only.
 
+Hybrid results are cached in-memory for a short TTL and invalidated automatically when the local index file changes.
+Context selection uses a middle-out strategy: it starts from the strongest chunk in a note and expands to neighboring chunks while respecting token budget.
+
 ### `context`
 
 ```bash
@@ -623,6 +836,7 @@ blink context "question" --vault ./vault --agent coding-agent --mode hybrid --js
 ```
 
 Builds a compact context package for an agent.
+Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
 
 ### `links`
 
@@ -656,9 +870,11 @@ Prints indexed graph data. Edges include `weight` and `priority` so agents can c
 ```bash
 blink stats --vault ./vault
 blink stats --vault ./vault --agent coding-agent --json
+blink stats --vault ./vault --agent coding-agent --extended --json
 ```
 
 Prints vault metrics.
+Use `--extended` to include storage footprint, link quality ratios and observability probes (`index`, `search`, `context` latencies).
 
 ### `broken-links`
 
@@ -690,7 +906,7 @@ Validates graph health. The command exits non-zero when required checks fail.
 blink doctor --vault ./vault
 ```
 
-Runs environment and vault checks.
+Runs environment and vault checks. When vault has zero markdown and zero indexed documents, `doctor` prints recommended next steps (add note, inspect config source, migrate memory).
 
 ### `watch`
 
@@ -705,9 +921,15 @@ Watches Markdown files and rebuilds the index when notes change.
 ```bash
 blink server --watch
 blink server --vault ./vault --watch
+blink server --vault ./vault --watch --no-open
 ```
 
 Starts the local read-only graph UI and HTTP API.
+By default, it tries to open a native desktop GUI window for the graph URL.
+On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
+If native GUI launch is unavailable, it falls back to dedicated app-window mode and then browser open.
+When fallback opens Chromium-family browsers on Linux, Brainlink automatically uses compatibility launch flags for stable rendering on Ubuntu/Wayland setups.
+Use `--no-open` to skip that behavior.
 
 The HTTP server only binds to loopback hosts such as `127.0.0.1`, `localhost` or `::1`.
 
@@ -727,7 +949,13 @@ npm run --silent dev -- context "question" --vault ./vault --json
 
 ## Configuration
 
-Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current working directory. If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HOME/.brainlink/vault`.
+Brainlink merges configuration in this order:
+
+1. Global: `$BRAINLINK_HOME/brainlink.config.json` (or `$HOME/.brainlink/brainlink.config.json` by default)
+2. Local: `brainlink.config.json` in the current working directory
+3. Local legacy compatibility: `.brainlink.json` in the current working directory
+
+If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HOME/.brainlink/vault`.
 
 ```json
 {
@@ -741,11 +969,29 @@ Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current wo
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
-  "chunkSize": 1200
+  "chunkSize": 1200,
+  "searchPack": {
+    "rowChunkSize": 5000,
+    "compressionLevel": 5,
+    "useDictionary": true,
+    "guardrailMinSavingsPercent": 8,
+    "guardrailMaxLatencyRegressionPercent": 5
+  },
+  "agentProfiles": {
+    "coding-agent": {
+      "defaultSearchMode": "semantic",
+      "defaultSearchLimit": 8,
+      "defaultContextTokens": 2400
+    },
+    "*": {
+      "defaultSearchMode": "hybrid"
+    }
+  }
 }
 ```
 
 `defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
+`agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit` and `tokens` per agent automatically, then fallback to global defaults.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 
@@ -842,7 +1088,7 @@ src/
   application/      use cases
   cli/              command-line adapter
   domain/           pure knowledge rules
-  infrastructure/   filesystem and SQLite adapters
+  infrastructure/   filesystem and index adapters
 ```
 
 Detailed notes:
@@ -854,7 +1100,6 @@ Detailed notes:
 ## Current Limits
 
 - Semantic search uses deterministic local embeddings, not a remote model provider.
-- Semantic search uses SQLite embedding buckets to narrow candidates before cosine scoring.
 - `embeddingProvider` currently supports `local` and `none`.
 - Link resolution is title-based inside each agent namespace, with `shared` as fallback.
 - HTTP API is local and unauthenticated.
@@ -865,7 +1110,7 @@ Detailed notes:
 The `0.1.0-beta` line is intended to stabilize the local-first memory loop:
 
 - Markdown as durable memory.
-- SQLite FTS plus local embeddings and semantic buckets as rebuildable retrieval index.
+- Rebuildable file index plus local embeddings and encrypted pack exports.
 - CLI as the primary agent interface.
 - HTTP graph API and frontend as inspection tools.
 - Agent namespaces to avoid context mixing.
@@ -881,7 +1126,7 @@ Brainlink is local-first by default.
 - Brainlink HTTP is localhost-only and refuses non-loopback hosts.
 - Brainlink blocks common secret patterns by default when adding notes. Use `--allow-sensitive` only for intentional, protected vaults.
 - Do not store secrets, credentials, API keys or regulated personal data unless the vault is protected by your own storage controls.
-- Treat `.brainlink/brainlink.db` as disposable derived data.
+- Treat `.brainlink/index.json` and `.brainlink/search-packs/` as disposable derived artifacts.
 
 See [SECURITY.md](SECURITY.md).
 
@@ -892,6 +1137,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT. See [LICENSE](LICENSE).
+Copyright (c) 2026 Substructa. See [COPYRIGHT.md](COPYRIGHT.md).
 
 ### Memory Optimization Loop (1-7)
 

package/SECURITY.md

@@ -7,7 +7,7 @@ Brainlink is local-first.
 - The HTTP server binds to `127.0.0.1` by default.
 - The HTTP server always refuses non-loopback hosts.
 - The HTTP server is read-only and does not expose note creation, indexing or update routes.
-- The SQLite database is a derived local index.
+- Local index artifacts (`.brainlink/index.json` and `.brainlink/search-packs/`) are derived data.
 - Markdown files are user-owned source data.
 - Brainlink-created Markdown files use `0600` permissions.
 - Brainlink-created directories and `.brainlink` use `0700` permissions.