agentsbestfriend 0.12.0 → 0.13.0

package/README.md

@@ -1,26 +1,30 @@
-# agentsbestfriend
+# AgentsBestFriend (abf)
 
 Give your AI coding agents superpowers — a local [MCP](https://modelcontextprotocol.io/) server for fast, token-efficient code navigation, search & analysis.
 
-Works with **VS Code Copilot**, **Cursor**, **Claude Code/Desktop**, **Codex**, **Cline**, **Zed**, and any other MCP-compatible agent.
+Works with **VS Code Copilot**, **Cursor**, **Claude Code/Desktop**, **Codex**, **Cline**, **Zed**, **Gemini CLI**, **Goose**, **OpenCode**, and any other MCP-compatible agent.
 
-## What it does
+---
 
-AI agents waste tokens re-reading files and searching blindly. ABF gives them purpose-built tools that return exactly what they need:
+## Why?
 
-| Tool | Purpose |
+AI coding agents waste tokens re-reading files and searching blindly. ABF gives them purpose-built tools that return exactly what they need — in compact, structured responses that preserve context.
+
+## Tools
+
+| Tool | What it does |
 |---|---|
-| `abf_search` | Code search — exact (ripgrep), keyword-ranked, or semantic |
-| `abf_symbols` | Functions, classes, exports in a file (AST-based) |
-| `abf_chunk` | Smart file chunk by symbol name or line range |
-| `abf_project_overview` | Tech stack, structure, dependencies at a glance |
+| `abf_search` | Code search — exact (ripgrep), keyword-ranked, or semantic (embedding-based) |
+| `abf_symbols` | Functions, classes, exports in a file (AST-based for TS/JS, regex for Python) |
+| `abf_chunk` | Smart file chunk by symbol name, chunk index, or file overview |
+| `abf_project_overview` | Tech stack, folder structure, key dependencies at a glance |
 | `abf_dependencies` | Import graph — who imports what |
 | `abf_impact` | Find all usages of a symbol across the project |
-| `abf_git` | Commits, blame, diff (recent/staged/unstaged) |
-| `abf_file_summary` | Search LLM-generated file summaries |
-| `abf_conventions` | Detected naming & style conventions |
-| `abf_index` | Index status & rebuild |
-| `abf_ping` | Health check |
+| `abf_git` | Git log, blame, diff (recent/staged/unstaged) |
+| `abf_file_summary` | Full-text search across LLM-generated file summaries (FTS5, OR/AND mode) |
+| `abf_conventions` | Detected naming, structure, and formatting conventions |
+| `abf_index` | Index status, rebuild, incremental update, or trigger re-summarization |
+| `abf_ping` | Health check — returns version and project root |
 
 ## Install
 
@@ -31,36 +35,34 @@ npm install -g agentsbestfriend
 ### Prerequisites
 
 - **Node.js** ≥ 20
-- **ripgrep** — `brew install ripgrep` / `apt install ripgrep`
+- **ripgrep** — `brew install ripgrep` (macOS) / `apt install ripgrep` (Linux)
 - **git**
-- **Ollama** (optional, for summaries & semantic search) — [ollama.com](https://ollama.com)
+- **Ollama** (optional) — for summaries & semantic search: [ollama.com](https://ollama.com)
 
 ## Quick Start
 
 ```bash
-# Initialize a project (indexes files, optionally installs MCP for your agents)
 abf init
-
-# Or initialize a specific path
-abf init /path/to/project
-
-# Check everything is working
-abf doctor
 ```
 
-During `abf init`, you'll be asked whether to install ABF as an MCP server for your coding agents. Pick the agents you use (Cursor, VS Code, Claude Code, etc.) and ABF handles the rest via [add-mcp](https://github.com/neondatabase/add-mcp).
+`abf init` walks you through everything:
+
+1. **Indexes your project** — discovers and indexes all files via `git ls-files`
+2. **Generates LLM summaries & embeddings** (if Ollama is running) — with live `(12/80)` progress
+3. **Adds `.abf/` to `.gitignore`** — prompts before writing
+4. **Installs ABF as an MCP server** for your agents — you pick which agents (Cursor, VS Code, Claude Code, etc.) and whether to use `npx agentsbestfriend start` (always latest) or `abf start` (local install)
 
 ### Manual Agent Setup
 
-If you prefer to configure manually, add ABF as a stdio MCP server:
+If you prefer to configure manually, add ABF as a stdio MCP server. Using `npx` is recommended — it always runs the latest published version without requiring a global install:
 
 **VS Code / GitHub Copilot** (`.vscode/mcp.json`):
 ```json
 {
   "servers": {
     "abf": {
-      "command": "abf",
-      "args": ["start"]
+      "command": "npx",
+      "args": ["agentsbestfriend", "start"]
     }
   }
 }
@@ -71,8 +73,8 @@ If you prefer to configure manually, add ABF as a stdio MCP server:
 {
   "mcpServers": {
     "abf": {
-      "command": "abf",
-      "args": ["start"]
+      "command": "npx",
+      "args": ["agentsbestfriend", "start"]
     }
   }
 }
@@ -83,51 +85,64 @@ If you prefer to configure manually, add ABF as a stdio MCP server:
 {
   "mcpServers": {
     "abf": {
-      "command": "abf",
-      "args": ["start"]
+      "command": "npx",
+      "args": ["agentsbestfriend", "start"]
     }
   }
 }
 ```
 
+> Set `ABF_PROJECT_ROOT` in the `env` block if the agent does not pass its working directory automatically.
+
 ## CLI Commands
 
 ```
-abf start         Start MCP server in stdio mode (used by agents)
-abf init [path]   Initialize index & optionally install MCP for agents
-abf index [path]  Re-index a project
-abf status [path] Show index status
-abf config        Interactive configuration editor
-abf doctor        System health checks (Node, ripgrep, git, Ollama)
-abf portal        Interactive terminal dashboard
+abf start             Start MCP server in stdio mode (used by agents)
+abf init [path]       Index project, set up .gitignore entry, install MCP for agents
+abf skill [path]      Install or update the ABF workflow skill for your coding agents
+abf index [path]      Re-index a project (incremental by default)
+abf status [path]     Show index stats
+abf config            Interactive configuration editor
+abf doctor            Health checks (Node, ripgrep, git, Ollama)
+abf portal            Interactive TUI dashboard
 ```
 
 ## How It Works
 
-ABF maintains a lightweight SQLite index (`.abf/index.db`) per project containing:
-
-- **File metadata** — paths, hashes, languages, line counts
-- **Symbols** — functions, classes, interfaces, types extracted via AST (ts-morph for TS/JS, regex for Python & others)
-- **Imports** — dependency edges between files
-- **Summaries** — LLM-generated file descriptions (optional, via Ollama)
-- **Embeddings** — vectors for semantic search (optional, via Ollama)
+ABF maintains a lightweight SQLite index (`.abf/index.db`) inside each project root. The index is built once and updated incrementally — only changed files are re-processed. A file watcher keeps it current as you edit.
 
-The index updates incrementally — only changed files are re-processed.
+| Table | Contents |
+|---|---|
+| `files` | Paths, hashes, languages, line counts, LLM summaries |
+| `symbols` | Functions, classes, interfaces, types (AST-extracted) |
+| `imports` | Dependency edges between files |
+| `embeddings` | Float32 vectors for semantic search (chunked for large files) |
+| `file_chunks` | Smart chunks aligned to symbol boundaries |
+| `files_fts` | FTS5 full-text index over summaries |
 
 ## Optional: LLM Enrichment
 
-With [Ollama](https://ollama.com) running locally, ABF can generate file summaries and embeddings for semantic search:
+With [Ollama](https://ollama.com) running locally, ABF generates file summaries and embeddings:
 
 ```bash
-ollama pull qwen2.5-coder:1.5b    # summaries
-ollama pull nomic-embed-text       # embeddings
+ollama pull qwen2.5-coder:1.5b    # file summaries
+ollama pull nomic-embed-text       # embeddings / semantic search
 ```
 
-Without Ollama, all tools work normally — semantic search falls back to keyword mode.
+Both `abf init` and `abf portal → Re-index` show live progress:
+
+```
+◆  Generating LLM summaries... (14/80)
+◆  Generating embeddings... (28/80)
+```
+
+Large files are automatically split into chunks for embedding — no context-length errors.
+
+Without Ollama, all tools still work normally. Semantic search falls back to keyword mode.
 
 ## Configuration
 
-Global config at `~/.abf/config.json`. Edit with `abf config` or `abf portal`.
+Global config at `~/.abf/config.json`. Edit interactively with `abf config` or via `abf portal`.
 
 ```json
 {
@@ -142,7 +157,8 @@ Global config at `~/.abf/config.json`. Edit with `abf config` or `abf portal`.
   "indexing": {
     "autoWatch": true,
     "respectGitignore": true,
-    "maxFileSizeKb": 512
+    "maxFileSizeKb": 512,
+    "excludedPatterns": ["*.min.js", "*.min.css", "*.map", "*.lock"]
   },
   "search": {
     "defaultMaxResults": 20
@@ -150,9 +166,50 @@ Global config at `~/.abf/config.json`. Edit with `abf config` or `abf portal`.
 }
 ```
 
+## Architecture
+
+```
+AgentsBestFriend/
+├── packages/
+│   ├── core/     Shared logic — DB, config, search, analysis, indexer, LLM
+│   ├── server/   MCP server (11 tools)
+│   └── cli/      Commander.js CLI + TUI portal
+├── turbo.json
+└── package.json
+```
+
+Built with Turborepo + pnpm workspaces. Core modules:
+
+| Module | Purpose |
+|---|---|
+| `@abf/core/db` | Drizzle ORM + SQLite (WAL, FTS5) |
+| `@abf/core/config` | Zod-validated config |
+| `@abf/core/search` | ripgrep, keyword scorer, semantic (cosine similarity) |
+| `@abf/core/analysis` | ts-morph AST, conventions detector, project overview |
+| `@abf/core/indexer` | git ls-files discovery, incremental pipeline, file watcher |
+| `@abf/core/llm` | Ollama client, summary & chunked embedding pipelines |
+| `@abf/core/git` | Git CLI wrapper |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Type-check
+pnpm type-check
+```
+
 ## Links
 
 - **GitHub**: [github.com/TheRealFloatDev/AgentsBestFriend](https://github.com/TheRealFloatDev/AgentsBestFriend)
+- **npm**: [npmjs.com/package/agentsbestfriend](https://npmjs.com/package/agentsbestfriend)
 - **Issues**: [github.com/TheRealFloatDev/AgentsBestFriend/issues](https://github.com/TheRealFloatDev/AgentsBestFriend/issues)
 - **MCP Spec**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
 

package/assets/skills/abf/SKILL.md

@@ -1,211 +1,173 @@
 ---
 name: abf
-description: "Use AgentsBestFriend (ABF) MCP tools for codebase navigation, search, and analysis instead of native file-reading tools. USE WHEN: exploring unfamiliar code, understanding architecture, searching across files, tracing imports/dependencies, analyzing change impact, reading large files, or needing project context. Prefer ABF tools over read_file, grep_search, semantic_search, and list_dir for multi-file workflows — they return pre-structured, token-efficient results in a single call."
+description: "MANDATORY: AgentsBestFriend (ABF) MCP tools are connected and MUST be used for ALL code navigation, search, and analysis. NEVER use read_file, grep_search, semantic_search, or list_dir for exploring code — ABF tools are faster, return structured results, and use 50–80% fewer tokens. USE FOR: any file reading, code search, symbol lookup, dependency tracing, impact analysis, git history, or architecture questions. Load this skill IMMEDIATELY whenever working in a codebase."
 ---
 
-# AgentsBestFriend (ABF) — Codebase Navigation Skill
+# AgentsBestFriend (ABF) — MANDATORY Code Navigation
 
-ABF is a local MCP server that provides AI-optimized tools for navigating, searching, and analyzing code repositories. These tools return structured, compact results that save 50–80% of tokens compared to manually reading files.
+> **CRITICAL**: ABF MCP tools are available and MUST be your default for all code exploration.  
+> Using `read_file`, `grep_search`, or `list_dir` when ABF tools exist is **always wrong**.
 
-## When to Use ABF Tools
-
-**Always prefer ABF tools when you need to:**
+---
 
-- Understand a project's structure or tech stack
-- Search for code across files (exact, keyword, or semantic)
-- Read specific functions or classes from large files
-- Trace imports, dependencies, or reverse dependencies
-- Assess the impact of changing a symbol
-- Get multi-file context around an entry point
+## ABSOLUTE RULES
 
-**Use native tools only when:**
+1. **NEVER call `read_file` to explore code** — use `abf_chunk` (by symbol) or `abf_symbols` first
+2. **NEVER call `grep_search`** — use `abf_search` (exact/keyword/semantic modes)
+3. **NEVER call `list_dir`** — use `abf_project_overview` or `abf_dependencies`
+4. **NEVER call `semantic_search`** — use `abf_search mode: "semantic"` or `abf_file_summary`
+5. **ALWAYS start a new codebase with `abf_project_overview`** — not by listing directories
+6. **ALWAYS use `abf_impact` before modifying a symbol** — never guess what depends on it
+7. **ALWAYS use `abf_conventions` before writing new code** — not by reading config files
 
-- Making edits to files (ABF is read-only)
-- Checking for lint/compile errors
-- Running terminal commands
-- The ABF MCP server is not connected
+---
 
-## Decision Matrix
+## Quick Decision Reference
+
+| What you want to do              | CORRECT tool                | WRONG approach                         |
+| -------------------------------- | --------------------------- | -------------------------------------- |
+| Understand the project           | `abf_project_overview`      | `list_dir` + reading package.json      |
+| Find a function/class definition | `abf_search` mode: exact    | `grep_search`                          |
+| Read a specific function         | `abf_chunk` symbol: "name"  | `read_file` entire file                |
+| See what a file exports          | `abf_symbols`               | `read_file` + manual scan              |
+| Find files about a topic         | `abf_search` mode: keyword  | multiple `semantic_search` calls       |
+| Trace what a file imports        | `abf_dependencies`          | `grep_search` for import statements    |
+| Who calls this function?         | `abf_impact` symbol: "name" | `grep_search` with manual filtering    |
+| Understand project style         | `abf_conventions`           | reading eslint + tsconfig + prettier   |
+| Get context around a file        | `abf_context_bundle`        | 5–10 `read_file` + `abf_symbols` calls |
+| Search file descriptions         | `abf_file_summary`          | no native equivalent                   |
+| Git history / blame / diff       | `abf_git`                   | `run_in_terminal` with git commands    |
+| Index status or rebuild          | `abf_index`                 | nothing                                |
 
-| Task                                              | ABF Tool                     | Instead of                                                             |
-| ------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------- |
-| Orient in a new project                           | `abf_project_overview`       | Reading README + listing directories + checking package.json           |
-| Find where something is defined                   | `abf_search` (exact mode)    | `grep_search`                                                          |
-| Find files related to a concept                   | `abf_search` (keyword mode)  | Multiple `semantic_search` + `grep_search` calls                       |
-| Read a specific function from a large file        | `abf_chunk` with symbol name | `read_file` (which loads entire file or requires guessing line ranges) |
-| List all exports of a file                        | `abf_symbols`                | `read_file` and scanning manually                                      |
-| Understand what a file imports and who imports it | `abf_dependencies`           | Multiple `grep_search` calls for import statements                     |
-| Get multi-file context around one entry point     | `abf_context_bundle`         | 5–10 calls to `read_file` + `abf_symbols` + `abf_dependencies`         |
-| Find all usages of a function/class               | `abf_impact`                 | `grep_search` with manual filtering                                    |
-| Understand project conventions                    | `abf_conventions`            | Reading multiple config files manually                                 |
-| Search by file purpose/description                | `abf_file_summary`           | No native equivalent                                                   |
-| Check git history or blame                        | `abf_git`                    | `run_in_terminal` with git commands                                    |
-| Persist notes / context across sessions           | `abf_notes`                  | External files, comments, or memory tools                              |
+---
 
-## Recommended Workflows
+## Workflows
 
-### 1. First Contact with a Codebase
+### Starting work on any codebase
 
 ```
-1. abf_project_overview              → architecture, tech stack, entry points
-2. abf_conventions                   → coding style, patterns, naming
-3. abf_search (keyword: "main topic") → find relevant files
+1. abf_project_overview          ← ALWAYS first — architecture, stack, entry points
+2. abf_conventions               ← style, patterns, naming before writing anything
+3. abf_search (keyword mode)     ← find relevant files for the task
 ```
 
-### 2. Understanding a Specific File
+### Reading code in a file
 
 ```
-1. abf_symbols (file)               → see all exports/functions at a glance
-2. abf_chunk (file, symbol: "name") → read just the function you care about
-3. abf_dependencies (file)          → see what it imports and who imports it
+1. abf_symbols (file)            ← see all exports/functions first
+2. abf_chunk (symbol: "name")    ← read exactly the function you need
+                                    only use read_file if you need the ENTIRE file
 ```
 
-### 3. Deep Dive into a Feature
+### Understanding a feature
 
 ```
-1. abf_context_bundle (entry file, depth: 2, include: "smart")
-   → full source of entry + signatures of all dependencies in ONE call
-2. If needed: abf_chunk to read specific dependency functions
+abf_context_bundle (entry file, depth: 2)
+← full source of entry + signatures of all deps in ONE call
+← replaces 5–10 read_file calls
 ```
 
-### 4. Change Impact Analysis
+### Before changing anything
 
 ```
-1. abf_impact (symbol: "functionName")  → all files and lines referencing it
-2. abf_context_bundle (entry, focus_symbol: "functionName", reverse: true)
-   → focused view of the function + its callers
+abf_impact (symbol: "functionName")
+← ALL files and lines that reference it — never skip this
 ```
 
-### 5. Searching for Code
+### Searching for code
 
 ```
-- Know the exact name?       → abf_search mode: "exact"
-- Exploring a concept?       → abf_search mode: "keyword"
-- Describe what you need?    → abf_file_summary (searches LLM-generated descriptions)
-- Semantic similarity?       → abf_search mode: "semantic" (requires Ollama)
+Exact name known?    → abf_search mode: "exact"
+Exploring a concept? → abf_search mode: "keyword"
+By file purpose?     → abf_file_summary (searches LLM descriptions)
+Semantic match?      → abf_search mode: "semantic"
 ```
 
-### 6. Cross-Session Memory
-
-```
-1. abf_notes action: "save" (title, content, tags)  → persist decisions, context, TODOs
-2. abf_notes action: "search" (query)                → recall notes by keyword (FTS5)
-3. abf_notes action: "list" (tag: "architecture")    → browse notes by tag
-4. abf_notes action: "update" / "delete"              → maintain your notepad
-```
+---
 
 ## Tool Reference
 
-### abf_project_overview
-
-**When:** Starting work on a project, or when asked "what does this project do?"
-**Saves:** Reading README + package.json + listing directories manually (3–5 calls → 1)
+### `abf_project_overview`
 
-- Returns: tech stack, frameworks, entry points, directory structure, language distribution, architectural patterns
-- No index required — works immediately
+Returns tech stack, frameworks, entry points, folder structure, language distribution, architectural patterns.  
+**Required params:** none  
+**Use it:** at the start of every new task in an unfamiliar codebase.
 
-### abf_search
+### `abf_search`
 
-**When:** Looking for code, files, or patterns across the project
-**Saves:** Multiple grep_search or semantic_search calls
+- `mode: "exact"` — ripgrep regex, returns matching lines with context
+- `mode: "keyword"` — ranks every file by keyword density, best for exploration
+- `mode: "semantic"` — embedding similarity (requires Ollama index)
+- `path_filter` — narrow scope (e.g. `"src/**/*.ts"`)
 
-- `mode: "exact"` — ripgrep-powered, supports regex, returns matching lines with context
-- `mode: "keyword"` — scores every file by keyword density, best for exploration
-- `mode: "semantic"` — embedding similarity (requires Ollama + index with embeddings)
-- Use `path_filter` to narrow scope (e.g. `"src/**/*.ts"`)
+### `abf_chunk`
 
-### abf_context_bundle
+Read a specific function/class without loading the full file.
 
-**When:** You need to understand a file in the context of its dependencies
-**Saves:** 5–10 calls to read_file + abf_symbols + abf_dependencies (biggest saver)
+- `symbol: "functionName"` → returns the full body of that symbol
+- No symbol → returns a chunk map; then use `chunk_index` for a specific section
 
-- `include: "smart"` (default) — full source for entry, signatures for deps
-- `include: "signatures"` — compact type signatures only (minimal tokens)
-- `include: "full"` — full source code for all files up to depth
-- `focus_symbol` — only follows imports relevant to one function/class
-- `reverse: true` — also shows who imports this file
-- `depth: 0–4` — how far to follow the import graph
+### `abf_symbols`
 
-### abf_chunk
+All exports, functions, classes, interfaces in a file with line ranges.  
+Call this before `abf_chunk` to see what's available.
 
-**When:** You need to read a specific function/class from a file without loading the entire file
-**Saves:** read_file loading hundreds of irrelevant lines
+### `abf_context_bundle`
 
-- Call with `symbol: "functionName"` to get its full source code directly
-- Call without symbol first to get a chunk overview, then use `chunk_index` to retrieve specific sections
+**Biggest token saver.** Returns entry file + signatures/source of all its imports in one call.
 
-### abf_symbols
-
-**When:** You need to see what a file exports without reading its full content
-**Saves:** read_file + mentally parsing the file structure
-
-- Returns: function signatures, classes, interfaces, types, variables with line ranges
-- Shows export status (★ = exported) and nesting
-
-### abf_dependencies
-
-**When:** Tracing what a file imports or finding who depends on it
-**Saves:** Multiple grep_search calls for import statements
-
-- Returns both imports and reverse dependencies (imported_by)
-
-### abf_impact
-
-**When:** Assessing how widely a symbol is used before changing it
-**Saves:** grep_search + manual filtering of false positives
+- `include: "smart"` (default) — full source for entry, signatures for deps
+- `include: "full"` — full source for everything
+- `focus_symbol` — only follow imports relevant to one function
+- `depth: 0–4` — how far to follow the import graph
 
-- Returns all files and specific lines that reference the symbol
-- Classifies usage type (call, import, type reference, etc.)
+### `abf_dependencies`
 
-### abf_file_summary
+Returns both imports (what this file uses) and reverse dependencies (who imports this file).
 
-**When:** Searching by file purpose rather than exact code text
-**Saves:** No native equivalent — unique capability
+### `abf_impact`
 
-- Full-text search across LLM-generated file descriptions
-- Requires summaries to be generated first (`abf_index` action: summarize)
+All files and specific lines that reference a symbol.  
+**Always call before modifying a function, class, or exported type.**
 
-### abf_conventions
+### `abf_conventions`
 
-**When:** Understanding project style before making changes
-**Saves:** Reading eslint, tsconfig, prettier, and other config files manually
+Detected naming patterns, design patterns, folder structure conventions — with confidence scores and examples.
 
-- Detects naming patterns, design patterns, folder structure conventions
-- Returns confidence scores and examples
+### `abf_file_summary`
 
-### abf_git
+Full-text search across LLM-generated file descriptions (FTS5/BM25 ranked).  
+Use when you want to find files by purpose, not by exact code text.
 
-**When:** Checking history, blame, or diffs
-**Saves:** Running git commands in terminal and parsing output
+- `match_mode: "or"` (default) — broader results
+- `match_mode: "and"` — stricter matching
 
-- Actions: log, file_history, blame, diff
-- Structured output ready for analysis
+### `abf_git`
 
-### abf_index
+Structured git output — no terminal needed.
 
-**When:** Managing the ABF index
+- `action: "log"` — recent commits
+- `action: "file_history"` — commits touching a file
+- `action: "blame"` — line-by-line authorship
+- `action: "diff"` — staged, unstaged, or between commits
 
-- `status` — check index health
-- `rebuild` — full re-index
-- `update` — incremental update
-- `summarize` — generate LLM summaries (requires Ollama)
+### `abf_index`
 
-### abf_ping
+- `action: "status"` — index health and file count
+- `action: "rebuild"` — full re-index
+- `action: "update"` — incremental update
+- `action: "summarize"` — generate LLM summaries (requires Ollama)
 
-**When:** Verifying ABF is running
+### `abf_ping`
 
-- Returns server version, project root, and status
+Returns server version and project root. Use to verify ABF is connected.
 
-### abf_notes
+---
 
-**When:** Persisting context, decisions, TODOs, or any information across agent sessions
-**Saves:** External scratch files, scattered comments, or relying on memory tools
+## When ABF Tools Are NOT Needed
 
-- `action: "save"` — create a note with title, content, and optional comma-separated tags
-- `action: "get"` — retrieve a note by ID or exact title
-- `action: "list"` — browse all notes, optionally filtered by tag
-- `action: "search"` — full-text search (FTS5 with BM25 ranking); supports AND/OR mode
-- `action: "update"` — update title, content, or tags on an existing note by ID
-- `action: "delete"` — remove a note by ID
-- Stored in `.abf/notes.db` — survives re-indexing
-- Project-scoped: each project has its own notepad
+- **Writing/editing files** — ABF is read-only; use your normal edit tools
+- **Running tests or build commands** — use the terminal
+- **Checking lint/type errors** — use native diagnostic tools
+- **ABF is not connected** — fall back to native tools, then reconnect with `abf start`
+- **ABF returned no useful result** — if you already called the appropriate ABF tool and the output didn't answer your question (e.g. `abf_search` returned nothing, `abf_chunk` didn't find the symbol), fall back to native tools for that specific lookup. Do not skip ABF preemptively — only fall back _after_ ABF has been tried.