@andespindola/brainlink 0.1.0-beta.6 → 0.1.0-beta.60

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,12 @@ 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 layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
+- Zoomed-out graph LOD now clusters dense regions and progressively expands nodes as zoom increases.
+- 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 +120,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 +296,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 +312,7 @@ vault/
     research-agent/
       source-review-policy.md
   .brainlink/
-    brainlink.db
+    index.json
 ```
 
 Permanent data:
@@ -306,7 +322,7 @@ Permanent data:
 
 Rebuildable data:
 
-- `.brainlink/brainlink.db`
+- `.brainlink/index.json`
 - full-text records
 - local embedding vectors
 - local embedding buckets
@@ -380,6 +396,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 +521,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 +538,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 +566,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 (edge draw caps, lower redraw rate, zoom-aware interaction)
+- massive-graph LOD progression: zoomed-out views prefer lightweight clusters, then progressively reveal nodes and edges as zoom increases
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 
@@ -535,6 +613,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,14 +635,89 @@ 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
 blink init
 blink init ./vault
+blink init ./team-vault --migrate-from ~/.brainlink/vault
 ```
 
 Initializes vault metadata. Without an argument, Brainlink initializes the default vault at `$HOME/.brainlink/vault`.
+When initializing an empty custom vault, existing Markdown content from the default vault is copied into it and reindexed so context is not left behind. Use `--no-migrate-existing` to start with an empty custom vault, or `--migrate-from <vault>` to copy from a specific source. Existing target files are never overwritten; conflicting source files are preserved with a `.conflict-<timestamp>` suffix.
 
 ### `add`
 
@@ -577,6 +731,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`
 
@@ -587,6 +764,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
@@ -605,13 +814,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
@@ -621,6 +834,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`
 
@@ -654,9 +868,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`
 
@@ -688,7 +904,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`
 
@@ -703,9 +919,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`.
 
@@ -725,7 +947,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
 {
@@ -739,11 +967,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.
 
@@ -840,7 +1086,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:
@@ -852,7 +1098,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.
@@ -863,7 +1108,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.
@@ -879,7 +1124,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).
 
@@ -890,6 +1135,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.