@andespindola/brainlink 0.1.0-beta.1 → 0.1.0-beta.11

package/docs/AGENT_USAGE.md

@@ -39,9 +39,19 @@ $HOME/.brainlink/vault
 
 `blink server` follows the same rule, so it serves the default Brainlink vault instead of the current working directory.
 
-Use `--vault <path>` for a one-off custom vault, or set `vault` in `brainlink.config.json` / `.brainlink.json` for a workspace-level custom default. Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhere else.
+Use `--vault <path>` for a one-off custom vault, or set `vault` in config for a persistent default.
+Configuration precedence is:
+
+1. global: `$BRAINLINK_HOME/brainlink.config.json` (or `$HOME/.brainlink/brainlink.config.json`)
+2. local: `./brainlink.config.json`
+3. local legacy: `./.brainlink.json`
+
+Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhere else.
+
+Use `blink config where` and `blink config doctor` to inspect active paths and effective source.
 
 You can also set `defaultAgent` in `brainlink.config.json` / `.brainlink.json` (for example `"defaultAgent": "coding-agent"`). When set, CLI commands and MCP calls reuse it when `--agent`/`agent` is not passed.
+You can set `agentProfiles` to define per-agent defaults for `defaultSearchMode`, `defaultSearchLimit` and `defaultContextTokens`.
 
 `autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
 
@@ -246,7 +256,7 @@ cp docs/templates/agent-note-template.md /tmp/agent-note.md
 When using MCP, use this compact sequence for the same memory discipline:
 
 1. Bootstrap context:
-   - `brainlink_context` with `agent`, `query`, `mode: hybrid`, `limit`.
+   - `brainlink_bootstrap` with `agent`, optional `query`, `mode: hybrid`, `limit`.
 2. Capture durable decisions:
    - `brainlink_add_note` or `brainlink_add_file` with explicit `[[wiki links]]` and `#tags`.
 3. Run maintenance before handoff or before the next step:
@@ -341,7 +351,57 @@ $HOME/.brainlink/vault/
   .brainlink/
 ```
 
-`blink init ./vault` creates a custom vault instead.
+`blink init ./vault` creates a custom vault instead. If the custom vault is empty and the default `$HOME/.brainlink/vault` already has Markdown memory, Brainlink copies that content into the custom vault and reindexes it. Use `blink init ./vault --no-migrate-existing` to intentionally start empty, or `blink init ./vault --migrate-from <old-vault>` to migrate from a specific previous vault. Existing target files are not overwritten; conflicting source files are preserved with a `.conflict-<timestamp>` suffix.
+
+### Configure Defaults
+
+```bash
+blink config where
+blink config get vault
+blink config doctor
+blink config doctor --fix
+blink config set-vault /absolute/path/to/vault
+blink config set-vault /absolute/path/to/vault --global
+```
+
+`config set-vault` updates Brainlink config through CLI. By default it writes local `brainlink.config.json`, appends the vault to `allowedVaults`, and migrates markdown when the target is empty.
+
+### Migrate Vaults Explicitly
+
+```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
+```
+
+Use `--dry-run` to preview `copied`, `conflicted`, `unchanged` before writing files.
+
+### Install Agent Integration
+
+```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 install --plugin-path ./plugins/brainlink
+blink agent status
+```
+
+`agent install` configures Brainlink MCP in `~/.codex/config.toml` so compatible agents can use Brainlink by default.
+Use `agent upgrade` on legacy installations to reapply the latest defaults and run self-test diagnostics.
+Use `agent policy --preset fully-auto` to keep startup/read auto-bootstrap enabled, or `agent policy --preset strict` to force explicit bootstrap calls.
+
+### Quickstart Plug-And-Play
+
+```bash
+blink quickstart --json
+blink quickstart --vault ./team-vault --agent coding-agent --query "architecture decisions" --json
+blink quickstart --vault ./team-vault --mcp-only --json
+```
+
+`quickstart` runs index, doctor, stats and validation, marks bootstrap readiness for MCP sessions, optionally returns context, and updates agent integration by default.
 
 ### Add A Note
 
@@ -356,6 +416,7 @@ blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 This creates a slugged Markdown file with frontmatter and a heading.
 
 The CLI blocks common secret patterns by default. Do not use `--allow-sensitive` unless the vault is intentionally protected.
+Brainlink also auto-connects notes that have no `[[wiki links]]` by adding a fallback edge to an agent hub note, so new memory does not stay disconnected.
 
 For agent-private memory:
 
@@ -395,6 +456,7 @@ blink search "authentication token policy" --vault ./vault --mode semantic --jso
 ```
 
 This returns matching chunks with title, source path, score, `textScore`, `semanticScore`, `searchMode`, and content.
+If `--mode`/`--limit` are omitted, Brainlink resolves those values from the active agent profile before global defaults.
 
 Search modes:
 
@@ -402,6 +464,8 @@ Search modes:
 - `fts`: lexical SQLite full-text search only.
 - `semantic`: local deterministic embedding similarity with SQLite bucket candidate narrowing.
 
+Hybrid results are cached in-memory for a short TTL and invalidated when `.brainlink/brainlink.db` changes.
+
 ### Build Agent Context
 
 ```bash
@@ -467,6 +531,8 @@ Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
 
 The frontend includes an agent selector. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
+Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom is anchored to the cursor. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open on click in a modal (tags, outgoing links, backlinks and Markdown content).
+
 The command reindexes by default, then serves:
 
 ```txt
@@ -518,19 +584,32 @@ Example MCP client configuration:
 
 Available MCP tools:
 
+- `brainlink_bootstrap`
+- `brainlink_policy`
+- `brainlink_recommendations`
 - `brainlink_context`
 - `brainlink_search`
 - `brainlink_add_note`
 - `brainlink_add_file`
 - `brainlink_index`
+- `brainlink_stats`
 - `brainlink_validate`
+- `brainlink_sync`
 - `brainlink_graph`
 - `brainlink_broken_links`
 - `brainlink_orphans`
 
+Recommended start of every memory-dependent task: call `brainlink_bootstrap` first, then `brainlink_context`. By default, Brainlink enforces context-first for non-context MCP reads (`enforceContextFirst=true`), and also enforces bootstrap with auto-bootstrap on reads when state is missing or stale (`autoBootstrapOnRead=true`).
+MCP startup also bootstraps the configured default vault/agent automatically (`autoBootstrapOnStartup=true`), so sessions start warm without manual calls.
+If `autoBootstrapOnRead` or `enforceContextFirst` are disabled through `brainlink_policy`, behavior is relaxed accordingly; otherwise read tools return preflight-required responses when requirements are not satisfied.
+`brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so clients can continue tool flows automatically.
+`brainlink_policy` also accepts policy presets (`fully-auto`, `strict`) so MCP clients can switch behavior in one call.
+`brainlink_recommendations` returns the suggested execution order so an agent can follow Brainlink best practices automatically.
+
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
 `brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
+`brainlink_add_note` and `brainlink_add_file` return `writeConnectivity` metadata and guarantee at least one edge for new notes.
 
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
@@ -541,6 +620,8 @@ export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```txt
 GET  /api/graph
 GET  /api/graph-layout
+GET  /api/graph-node?id=<node-id>
+GET  /api/graph-filter?q=<query>&limit=<n>
 GET  /api/search?q=<query>&limit=10&mode=hybrid
 GET  /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid
 GET  /api/links
@@ -553,6 +634,9 @@ GET  /api/validate
 
 The HTTP API is read-only. Use the CLI for writes and indexing.
 
+Brainlink maintains an automatic SQLite rollback snapshot at `.brainlink/brainlink.db.backup`. When `.brainlink/brainlink.db` is corrupted, Brainlink restores from snapshot automatically or recreates a clean index if no snapshot exists yet.
+Indexing also writes compressed search packs at `.brainlink/search-packs/*.jsonl.gz`; when SQLite cannot be opened, Brainlink falls back to pack-based search automatically.
+
 ## Agent Integration Contract
 
 Input:

package/docs/ARCHITECTURE.md

@@ -34,6 +34,8 @@ src/
 
   cli/
     commands/
+      agent-commands.ts
+      config-commands.ts
       read-commands.ts
       write-commands.ts
     main.ts
@@ -57,7 +59,13 @@ src/
       schema.ts
       search-reader.ts
     file-system-vault.ts
+    session-state.ts
     sqlite-index.ts
+
+  mcp/
+    main.ts
+    server.ts
+    tools.ts
 ```
 
 ## Domain
@@ -181,6 +189,10 @@ MCP client
 ```
 
 The MCP adapter stays thin. It validates tool inputs, resolves the configured vault and calls the same application use cases used by the CLI.
+At server startup, Brainlink runs a bootstrap pass on the configured default vault/agent, then keeps enforcing bootstrap policy on read tools.
+For MCP agents, non-context read tools also enforce context-first by default, requiring a recent `brainlink_context` call before additional reads.
+When `mode`/`limit`/`tokens` are omitted, MCP read tools resolve per-agent defaults from `agentProfiles` and then fallback to global config defaults.
+Session state is persisted in `$BRAINLINK_HOME/session-state.json` with independent bootstrap/context freshness per vault/agent so read tools can enforce bootstrap and context-first policies with optional automation.
 
 ## Link Resolution
 
@@ -287,10 +299,13 @@ Markdown keeps the system portable, inspectable, Git-friendly, and compatible wi
 ### SQLite As Local Index
 
 SQLite gives fast local search, local vector storage and rebuildable retrieval without forcing users to run external infrastructure.
+Hybrid retrieval also uses a short-lived in-memory cache keyed by vault/query/agent and invalidated by index file mtime to reduce repeated query latency.
+Brainlink also writes a local rollback snapshot (`.brainlink/brainlink.db.backup`) after successful indexing. On corruption detection (`quick_check`/SQLite malformed errors), Brainlink restores from snapshot automatically before reopening the index.
+Indexing additionally exports compressed pack files (`.brainlink/search-packs/*.jsonl.gz`) from indexed chunks. Search falls back to these packs when SQLite is unavailable, preserving retrieval continuity in degraded mode.
 
 ### CLI First
 
-The CLI is the smallest useful integration surface for agents. HTTP is a local inspection adapter, and MCP can be implemented outside this package by wrapping the CLI.
+The CLI is the smallest useful integration surface for agents. HTTP is a local inspection adapter, and Brainlink also ships a built-in MCP server (`brainlink-mcp`) that uses the same application use cases.
 
 ### Functional Core
 

package/docs/QUICKSTART.md

@@ -0,0 +1,104 @@
+# Quickstart
+
+Use this path when you want Brainlink running as agent memory with the smallest setup.
+
+## 1) Install Brainlink
+
+```bash
+npm install -g @andespindola/brainlink@latest
+```
+
+## 2) Install Agent Integration
+
+```bash
+blink agent install --self-test
+blink agent upgrade
+blink agent policy --preset fully-auto
+blink agent status
+```
+
+For local plugin gallery in this repository:
+
+```bash
+blink agent install --plugin-path ./plugins/brainlink --self-test
+```
+
+One-command setup and readiness check:
+
+```bash
+blink quickstart --query "what should I know before this task?" --json
+```
+
+## 3) Initialize Or Select Vault
+
+```bash
+blink init
+blink config where
+```
+
+To set a different default vault:
+
+```bash
+blink config set-vault /absolute/path/to/vault
+```
+
+Optional per-agent retrieval defaults in `brainlink.config.json`:
+
+```json
+{
+  "agentProfiles": {
+    "coding-agent": {
+      "defaultSearchMode": "semantic",
+      "defaultSearchLimit": 8,
+      "defaultContextTokens": 2400
+    }
+  }
+}
+```
+
+## 4) Run Bootstrap Before Work
+
+MCP clients should call `brainlink_bootstrap` first for each vault/agent session, then `brainlink_context`.
+By default, Brainlink enforces context-first for non-context read tools, so a fresh `brainlink_context` call is required before other MCP reads.
+Read tools auto-bootstrap by default when state is missing/stale, and bootstrap/preflight responses include structured `nextActions` for automatic client flows.
+MCP startup also runs bootstrap automatically for the configured default vault/agent.
+
+For CLI workflows:
+
+```bash
+blink context "what should I know before this task?" --mode hybrid --json
+```
+
+## 5) Write Durable Memory
+
+```bash
+blink add "Architecture Decision" --content "Use explicit [[Bounded Context]] links and #tags. #architecture #decision"
+```
+
+## 6) Validate Health
+
+```bash
+blink validate
+blink doctor
+blink stats --extended --json
+```
+
+## 7) Migrate Existing Memory (Optional)
+
+Preview first:
+
+```bash
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --dry-run --report ./migration-report.json
+```
+
+Apply:
+
+```bash
+blink migrate-vault --from ~/.brainlink/vault --to ./team-vault --report ./migration-report.json
+```
+
+S3 target:
+
+```bash
+blink migrate-vault --from ~/.brainlink/vault --to "s3://my-memory-bucket/brainlink" --dry-run
+```

package/docs/RELEASE.md

@@ -2,7 +2,7 @@
 
 Brainlink releases are built from the CLI package. Do not publish until the package name, npm account and version are confirmed.
 
-## Alpha Release Checklist
+## Beta Release Checklist
 
 1. Confirm `package.json` name, version, repository, license and bin entries.
 2. Run `npm install` from a clean checkout when dependencies changed.
@@ -51,9 +51,9 @@ The preferred path is the `Publish npm` GitHub Actions workflow:
 - GitHub Release `published`: runs checks, pack smoke, then publishes to npm with provenance.
 - Manual `workflow_dispatch`: runs a dry run by default. Disable `dry_run` only for an intentional manual publish.
 - Manual `workflow_dispatch` accepts an optional `dist_tag` override. Use `latest` only when the default npm install command should resolve to that version.
-- Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-alpha.1` publishes with `--tag alpha`.
+- Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-beta.1` publishes with `--tag beta`.
 
-On `main`, the publish job checks npm before publishing. If the version already exists, it automatically bumps the package inside the runner to the next available version before checks, packing and publishing. For example, `0.1.0-alpha.4` becomes `0.1.0-alpha.5`.
+On `main`, the publish job checks npm before publishing. If the version already exists, it automatically bumps the package inside the runner to the next available version before checks, packing and publishing. For example, `0.1.0-beta.4` becomes `0.1.0-beta.5`.
 
 The automatic bump is intentionally not pushed back to `main`. The branch stays protected, and npm remains the source of truth for the latest published package version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.11",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",