membot 0.0.1 → 0.1.1

package/src/search/keyword.ts

@@ -0,0 +1,62 @@
+import { rebuildFts } from "../db/chunks.ts";
+import type { DbConnection } from "../db/connection.ts";
+
+export interface KeywordHit {
+	logical_path: string;
+	version_id: string;
+	chunk_index: number;
+	chunk_content: string;
+	search_text: string;
+	score: number;
+}
+
+interface RawKeywordRow {
+	row_key: string;
+	logical_path: string;
+	version_id: string;
+	chunk_index: number;
+	chunk_content: string;
+	search_text: string;
+	bm25_score: number;
+	[key: string]: unknown;
+}
+
+/**
+ * BM25 keyword search over `chunks.search_text` via the FTS extension.
+ * Returns an empty list when FTS isn't available on this platform — the
+ * hybrid layer treats missing keyword hits as "no signal" and degrades
+ * to semantic-only.
+ */
+export async function searchKeyword(
+	db: DbConnection,
+	query: string,
+	options: { limit?: number; pathPrefix?: string } = {},
+): Promise<KeywordHit[]> {
+	const result = await rebuildFts(db);
+	if (result.kind !== "rebuilt") return [];
+
+	const limit = options.limit ?? 50;
+	try {
+		const sql = `SELECT row_key, logical_path, version_id, chunk_index,
+		                   chunk_content, search_text,
+		                   fts_main__current_chunks_fts.match_bm25(row_key, ?1) AS bm25_score
+		            FROM _current_chunks_fts
+		           WHERE fts_main__current_chunks_fts.match_bm25(row_key, ?1) IS NOT NULL
+		             ${options.pathPrefix ? "AND logical_path LIKE ?2" : ""}
+		           ORDER BY bm25_score DESC
+		           LIMIT ${Number(limit)}`;
+		const rows: RawKeywordRow[] = options.pathPrefix
+			? await db.queryAll<RawKeywordRow>(sql, query, `${options.pathPrefix}%`)
+			: await db.queryAll<RawKeywordRow>(sql, query);
+		return rows.map((r) => ({
+			logical_path: r.logical_path,
+			version_id: String(r.version_id),
+			chunk_index: Number(r.chunk_index),
+			chunk_content: r.chunk_content,
+			search_text: r.search_text,
+			score: Number(r.bm25_score),
+		}));
+	} catch {
+		return [];
+	}
+}

package/src/search/semantic.ts

@@ -0,0 +1,56 @@
+import { EMBEDDING_DIMENSION } from "../constants.ts";
+import type { DbConnection } from "../db/connection.ts";
+
+export interface SemanticHit {
+	logical_path: string;
+	version_id: string;
+	chunk_index: number;
+	chunk_content: string;
+	search_text: string;
+	score: number;
+}
+
+interface RawSemanticRow {
+	logical_path: string;
+	version_id: string;
+	chunk_index: number;
+	chunk_content: string;
+	search_text: string;
+	distance: number;
+	[key: string]: unknown;
+}
+
+/**
+ * Cosine-similarity search over the chunks' embedding vectors. Searches
+ * `current_chunks` (latest non-tombstoned per logical_path) by default;
+ * pass `includeHistory=true` to search every version.
+ */
+export async function searchSemantic(
+	db: DbConnection,
+	queryVec: number[],
+	options: { limit?: number; pathPrefix?: string; includeHistory?: boolean } = {},
+): Promise<SemanticHit[]> {
+	const limit = options.limit ?? 50;
+	const view = options.includeHistory ? "chunks" : "current_chunks";
+	const prefixClause = options.pathPrefix ? `WHERE logical_path LIKE ?2` : "";
+	const sql = `SELECT logical_path,
+	                   CAST(version_id AS VARCHAR) AS version_id,
+	                   chunk_index, chunk_content, search_text,
+	                   array_cosine_distance(embedding, ?1::FLOAT[${EMBEDDING_DIMENSION}]) AS distance
+	            FROM ${view}
+	            ${prefixClause}
+	            ORDER BY distance ASC
+	            LIMIT ${Number(limit)}`;
+	const rows: RawSemanticRow[] = options.pathPrefix
+		? await db.queryAll<RawSemanticRow>(sql, queryVec, `${options.pathPrefix}%`)
+		: await db.queryAll<RawSemanticRow>(sql, queryVec);
+
+	return rows.map((r) => ({
+		logical_path: r.logical_path,
+		version_id: String(r.version_id),
+		chunk_index: Number(r.chunk_index),
+		chunk_content: r.chunk_content,
+		search_text: r.search_text,
+		score: 1 - Number(r.distance),
+	}));
+}

package/src/types/text-modules.d.ts

@@ -0,0 +1,9 @@
+declare module "*.md" {
+	const content: string;
+	export default content;
+}
+
+declare module "*.mdc" {
+	const content: string;
+	export default content;
+}

package/src/update/background.ts

@@ -0,0 +1,73 @@
+import { cyan, dim, yellow } from "ansis";
+import pkg from "../../package.json" with { type: "json" };
+import { DEFAULTS, ENV } from "../constants.ts";
+import { loadUpdateCache, saveUpdateCache } from "./cache.ts";
+import { checkForUpdate, needsCheck, type UpdateCache } from "./checker.ts";
+
+/** Format a multi-line stderr update notice (yellow header + dim changelog + cyan call-to-action). */
+function formatNotice(currentVersion: string, latestVersion: string, changelog?: string): string {
+	const lines: string[] = ["", yellow(`Update available: ${currentVersion} → ${latestVersion}`)];
+
+	if (changelog) {
+		lines.push("");
+		lines.push(dim(changelog));
+	}
+
+	lines.push("");
+	lines.push(cyan("Run `membot upgrade` to update"));
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+/**
+ * Non-blocking background update check. Returns a formatted notice string when
+ * an update is available, or `null` otherwise. Honors `MEMBOT_NO_UPDATE_CHECK`,
+ * skips itself for the upgrade/check-update commands, and only fires in TTY.
+ * Never throws.
+ */
+export async function maybeCheckForUpdate(): Promise<string | null> {
+	try {
+		if (process.env[ENV.NO_UPDATE_CHECK] === "1") return null;
+
+		const args = process.argv.slice(2);
+		const command = args.find((a) => !a.startsWith("-"));
+		if (command === "check-update" || command === "upgrade") return null;
+
+		if (!(process.stderr.isTTY ?? false)) return null;
+
+		const cache = await loadUpdateCache();
+
+		if (!needsCheck(cache)) {
+			if (cache?.hasUpdate) {
+				return formatNotice(pkg.version, cache.latestVersion, cache.changelog);
+			}
+			return null;
+		}
+
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), DEFAULTS.UPDATE_CHECK_TIMEOUT_MS);
+
+		try {
+			const info = await checkForUpdate(pkg.version, controller.signal);
+
+			const newCache: UpdateCache = {
+				lastCheckAt: new Date().toISOString(),
+				latestVersion: info.latestVersion,
+				hasUpdate: info.hasUpdate,
+				changelog: info.changelog,
+			};
+			await saveUpdateCache(newCache);
+
+			if (info.hasUpdate) {
+				return formatNotice(pkg.version, info.latestVersion, info.changelog);
+			}
+		} finally {
+			clearTimeout(timeout);
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}

package/src/update/cache.ts

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+import { defaultMembotHome } from "../constants.ts";
+import type { UpdateCache } from "./checker.ts";
+
+/** Path to the JSON file that holds the latest update-check result. */
+function updateCachePath(): string {
+	return join(defaultMembotHome(), "update.json");
+}
+
+/** Load the cached update-check result, or `undefined` if missing/unreadable. */
+export async function loadUpdateCache(): Promise<UpdateCache | undefined> {
+	try {
+		const file = Bun.file(updateCachePath());
+		if (!(await file.exists())) return undefined;
+		return JSON.parse(await file.text()) as UpdateCache;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Persist a fresh update-check result. Silent on write failure (e.g. permission denied). */
+export async function saveUpdateCache(cache: UpdateCache): Promise<void> {
+	try {
+		await Bun.write(updateCachePath(), `${JSON.stringify(cache, null, 2)}\n`);
+	} catch {
+		// Ignore write failures (e.g. permissions)
+	}
+}
+
+/** Empty the cache file so the next check is forced to refetch. */
+export async function clearUpdateCache(): Promise<void> {
+	try {
+		const file = Bun.file(updateCachePath());
+		if (await file.exists()) {
+			await Bun.write(updateCachePath(), "");
+		}
+	} catch {
+		// Ignore
+	}
+}

package/src/update/checker.ts

@@ -0,0 +1,117 @@
+import pkg from "../../package.json" with { type: "json" };
+import { DEFAULTS } from "../constants.ts";
+
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
+const GITHUB_REPO = pkg.repository.url.replace(/^https:\/\/github\.com\//, "").replace(/\.git$/, "");
+
+export interface UpdateInfo {
+	currentVersion: string;
+	latestVersion: string;
+	hasUpdate: boolean;
+	aheadOfLatest: boolean;
+	changelog?: string;
+}
+
+export interface UpdateCache {
+	lastCheckAt: string;
+	latestVersion: string;
+	hasUpdate: boolean;
+	changelog?: string;
+}
+
+export type InstallMethod = "npm" | "bun" | "binary" | "local-dev";
+
+/** Compare two semver strings. Returns true if latest > current. */
+export function isNewerVersion(current: string, latest: string): boolean {
+	return Bun.semver.order(current, latest) === -1;
+}
+
+/** Fetch the latest version from the npm registry. Falls back to the bundled version on error. */
+export async function fetchLatestVersion(signal?: AbortSignal): Promise<string> {
+	try {
+		const res = await fetch(NPM_REGISTRY_URL, { signal });
+		if (!res.ok) return pkg.version;
+		const data = (await res.json()) as { version: string };
+		return data.version;
+	} catch {
+		return pkg.version;
+	}
+}
+
+/** Fetch changelog text from GitHub releases between two versions. Returns undefined when unavailable. */
+export async function fetchChangelog(
+	fromVersion: string,
+	toVersion: string,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	try {
+		const res = await fetch(`https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=20`, {
+			signal,
+			headers: { Accept: "application/vnd.github.v3+json" },
+		});
+		if (!res.ok) return undefined;
+
+		const releases = (await res.json()) as Array<{
+			tag_name: string;
+			body: string | null;
+		}>;
+
+		const relevant = releases.filter((r) => {
+			const v = r.tag_name.replace(/^v/, "");
+			return isNewerVersion(fromVersion, v) && !isNewerVersion(toVersion, v);
+		});
+
+		if (relevant.length === 0) return undefined;
+
+		return relevant
+			.map((r) => `## ${r.tag_name}\n${r.body ?? ""}`)
+			.join("\n\n")
+			.trim();
+	} catch {
+		return undefined;
+	}
+}
+
+/** Check npm for a newer version and fetch its changelog if present. Never throws. */
+export async function checkForUpdate(currentVersion: string, signal?: AbortSignal): Promise<UpdateInfo> {
+	const latestVersion = await fetchLatestVersion(signal);
+	const hasUpdate = isNewerVersion(currentVersion, latestVersion);
+	const aheadOfLatest = isNewerVersion(latestVersion, currentVersion);
+
+	let changelog: string | undefined;
+	if (hasUpdate) {
+		changelog = await fetchChangelog(currentVersion, latestVersion, signal);
+	}
+
+	return { currentVersion, latestVersion, hasUpdate, aheadOfLatest, changelog };
+}
+
+/** Returns true if the cache is missing or older than UPDATE_CHECK_INTERVAL_MS. */
+export function needsCheck(cache?: UpdateCache): boolean {
+	if (!cache?.lastCheckAt) return true;
+	return Date.now() - new Date(cache.lastCheckAt).getTime() > DEFAULTS.UPDATE_CHECK_INTERVAL_MS;
+}
+
+/**
+ * Detect how membot was installed by inspecting `process.execPath` and `process.argv[1]`.
+ * Used to pick the right upgrade strategy: package-manager reinstall vs binary download
+ * vs no-op for source checkouts.
+ */
+export function detectInstallMethod(): InstallMethod {
+	const script = process.argv[1] ?? "";
+	const execPath = process.execPath;
+
+	if (script.includes("src/cli.ts") && !script.includes("node_modules")) {
+		return "local-dev";
+	}
+
+	if (!execPath.includes("bun") && !execPath.includes("node")) {
+		return "binary";
+	}
+
+	if (script.includes(".bun/install") || script.includes(".bun/bin")) {
+		return "bun";
+	}
+
+	return "npm";
+}

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:www.arcade.dev)"
-    ]
-  }
-}

package/CLAUDE.md

@@ -1,139 +0,0 @@
-# CLAUDE.md — `ctx`
-
-Guidance for Claude Code when working in this repo. Pair with `docs/plan.md` (the source-of-truth design doc).
-
-## What this project is
-
-`ctx` is a standalone Bun CLI + MCP server that gives AI agents a persistent, versioned, searchable context store. Files (markdown, PDF, DOCX, HTML, URLs) are ingested, converted to markdown, chunked, embedded locally with `@huggingface/transformers` (WASM, 384-dim `Xenova/bge-small-en-v1.5`), and indexed in DuckDB with hybrid search (vector + BM25). Every agent-visible artifact is a row in `files`, addressed by a virtual `logical_path` — there is **no** on-disk tree of stored content.
-
-Reference projects (read these to understand the conventions before changing anything):
-
-- `/Users/evan/workspace/botholomew` — origin of the context system. The chunker, embedder, fetcher, markdown-converter, and hybrid search live in `src/context/` and `src/tools/search/`.
-- `/Users/evan/workspace/mcpx` — the project this one mirrors for layout, build, distribution, logger, and CLI shape.
-
-## Hard constraints
-
-- **Bun-only.** No Node-only deps. `bun build --compile` produces standalone binaries; the runtime must not require Bun installed.
-- **Local embeddings only.** `@huggingface/transformers` WASM, `Xenova/bge-small-en-v1.5`, 384-dim. Never reach for cloud embedding APIs (OpenAI/Voyage/Cohere/Anthropic embeddings) even if a reference project uses them.
-- **DuckDB is the only store.** Content AND original bytes live in rows (`files.content`, `blobs.bytes`), not in a filesystem tree. `~/.ctx/index.duckdb` holds everything except cached model weights. The DB will get large — that's accepted.
-- **Append-only versioning.** Every ingest, refresh that finds new bytes, write, or rename creates a new `(logical_path, version_id)` row. `version_id` is a `TIMESTAMP` (ms precision). Default queries flow through `current_files` / `current_chunks` views. Delete = tombstone, not a row removal.
-- **MCP defaults to current.** Every MCP tool acts on the latest non-tombstoned version unless `version` is passed explicitly.
-- **Mcpx invocations are persisted.** When `ctx_add` fetches a remote URL via mcpx, store `fetcher_server`, `fetcher_tool`, and `fetcher_args` on the row so refresh re-invokes the exact same tool — never re-route through the agent.
-- **Native conversion first, LLM fallback for messy/binary input.** `unpdf`, `mammoth`, `turndown` handle the common cases. Tesseract WASM (`tesseract.js`) does OCR for `image/*` and for PDFs whose text extraction came back empty. Claude vision captions images; Claude markdown-converter is the last-resort fallback. Missing `ANTHROPIC_API_KEY` is not a hard error — the pipeline degrades to deterministic surrogates.
-- **Textual surrogate is the universal interface.** Every artifact (markdown, PDF, image, audio, anything) produces a markdown body that flows through chunking + embedding + FTS. Original bytes live in `blobs` and are reachable via `ctx_read bytes=true`. Search has zero special cases for binary content.
-- **Always describe.** `files.description` is generated for every ingested file, including plain markdown. The string `<logical_path>\n<description>\n\n<chunk_content>` is what gets embedded and FTS-indexed (stored as `chunks.search_text`); `chunks.chunk_content` keeps the raw body for clean snippet rendering.
-- **`ctx_add` accepts directories and globs.** Single arg, polymorphic: file path, directory (recursive walk, symlinks followed via realpath dedupe), glob (`docs/**/*.md`), URL, or `inline:<text>`. Each matched entry becomes its own version under its own logical_path; partial failures are reported per-entry, not all-or-nothing.
-- **CLI auto-renders for the environment.** TTY → spinners, progress bars, ANSI colors. Piped/`--json`/`CI=true`/`NO_COLOR` → JSON to stdout, structured logs to stderr, no ANSI bytes. One code path; `src/output/tty.ts` is the single source of truth for which mode is active.
-- **All errors are `HelpfulError`.** Bare `throw new Error(...)` is forbidden. `HelpfulError` requires a non-empty `hint` (statically and at runtime); the hint must name the next action concretely. The same hint string lands in front of both humans (CLI stderr) and LLMs (MCP `structuredContent.error.hint` and the rendered text content).
-
-## Architecture at a glance
-
-```
-ctx_add ──► local-reader OR fetcher (mcpx) ──► converter (mime dispatch)
-                                                    │
-                                                    ▼
-                                       chunker ──► embedder (WASM)
-                                                    │
-                                                    ▼
-                                       db.files.insertVersion + db.chunks.insertForVersion
-                                                    │
-                                                    ▼
-                                       FTS index rebuild (current_chunks)
-
-ctx_refresh ──► re-read source ──► sha256 compare
-                                       │
-                          unchanged ◄──┴──► changed ──► same pipeline as ctx_add
-                          (status only)        (creates new version_id)
-```
-
-Daemon mode (`ctx serve --watch`) ticks every `tick_interval_sec` and runs the no-arg refresh path against rows whose `refresh_frequency_sec` has elapsed.
-
-## Layout
-
-```
-src/
-  cli.ts                # commander entry; iterates operations registry
-  sdk.ts                # programmatic API for embedding ctx
-  context.ts            # AppContext: config + db + embedder + mcpx + logger
-  constants.ts          # CTX_HOME, EMBEDDING_DIMENSION=384, defaults
-  operations/           # ★ one file per user-facing capability; single source of truth
-    types.ts            # Operation<I,O>, defineOperation()
-    index.ts            # ordered registry; cli + mcp both iterate this
-    add.ts list.ts tree.ts read.ts write.ts search.ts remove.ts
-    move.ts refresh.ts info.ts versions.ts diff.ts prune.ts
-  mount/
-    mcp.ts              # mountAsMcpTool — registers an Operation as an MCP tool
-    commander.ts        # mountAsCommanderCommand — registers an Operation as a CLI subcommand
-    zod-to-cli.ts       # introspects zod schema → commander .argument()/.option() calls
-  commands/             # CLI-only commands with no MCP equivalent (serve, reindex)
-  config/               # zod schema + loader (~/.ctx/config.json)
-  db/                   # DuckDB connection, migrations, files.ts, chunks.ts
-  ingest/               # source-resolver (file/dir/glob/url/inline), local-reader, fetcher, chunker, embedder, describer, search-text, converter/ (pdf/docx/html/image/text/ocr/llm)
-  search/               # semantic.ts, keyword.ts, hybrid.ts (RRF)
-  refresh/              # runner.ts (per-row), scheduler.ts (daemon)
-  mcp/                  # server.ts, instructions.ts
-  output/               # tty.ts (mode detection), logger.ts (spinner-aware), progress.ts (multi-entry bar), formatter.ts (table/markdown/json)
-  errors.ts             # HelpfulError class — the only error type allowed in handlers
-test/                   # bun test, _preload.ts applies transformers patch
-patches/                # @huggingface/transformers WASM patch (copy from mcpx)
-scripts/                # apply-transformers-patch.sh (pre-build hook)
-docs/plan.md            # source-of-truth design
-```
-
-## Coding conventions
-
-- **One Operation, two surfaces.** Every user-facing capability is a single `Operation` in `src/operations/` with a zod input schema, zod output schema, description string, and handler. The MCP server and the commander CLI both consume this — never write a tool description twice, never define an input shape twice. The description string is the LLM-facing docstring AND the `--help` text. Field-level help comes from `.describe()` on each zod field.
-- **Zod everywhere.** Operation I/O schemas, config schema, fetcher response shapes. Use `.describe()` on every field — that text is what the agent and human both read.
-- **Errors are `HelpfulError` only.** See `src/errors.ts`. Required fields: `kind`, `message`, `hint`. The constructor refuses an empty hint at runtime, and the type system refuses to omit it at compile time. The mount adapters render `kind` + `message` + `hint` for both surfaces — humans see colorized output on a TTY, LLMs get the same fields back as MCP `structuredContent.error`. Hint quality bar: name a concrete next action (a command to run, a flag to set, a path to check). Vague hints like "Check your config" should fail review.
-- **No log-and-rethrow.** Errors propagate to the mount boundary, are rendered there exactly once, then exit. Logging the error before throwing produces double-output and breaks JSON-mode parseability.
-- **Spinners & progress are advisory.** Operations call `ctx.progress.tick(...)` and `ctx.logger.info(...)` without checking whether they're rendered. The renderer in `src/output/` decides; non-interactive mode coerces both into stderr lines or no-ops.
-- **No duplicated handlers.** If you find yourself writing logic in `src/commands/*.ts` that an MCP tool would also want, it belongs in `src/operations/` instead. The only legitimate `src/commands/*.ts` files are CLI-only behaviors with no agent-facing meaning (`serve`, `reindex`).
-- **Logger, not console.** Use `src/output/logger.ts` (spinner-aware, JSON/TTY-aware). `console.log` in production code is a bug.
-- **Colors via `ansis`, spinners via `nanospinner`.** Same as mcpx.
-- **No premature abstractions.** Three similar lines beat a generic helper. Don't build for hypothetical fetchers, hypothetical embedders, or hypothetical storage backends.
-
-## Tool / command descriptions
-
-Operation descriptions are the user interface — for the LLM AND for the human running `ctx <cmd> --help`. The same string is shown in both places. Every operation description follows this shape:
-
-1. Bash-equivalent prefix where applicable: `[[ bash equivalent: cat ]]`.
-2. One-line purpose.
-3. When-to-use guidance — what to call before/after, what tool to prefer instead in adjacent cases.
-4. Constraints, recovery hints, and links to other operations by name.
-
-Server-level `instructions` (the string handed to the MCP client when it connects) is defined in `src/mcp/instructions.ts`. It frames the discovery → ingest → consume → write workflow and explicitly tells the agent how versioning, refresh, and the `version` parameter behave. CLI users get the same framing through `ctx --help` (commander's top-level help). Update both that file and `docs/plan.md` together if you change the operation surface.
-
-## Testing
-
-- `bun test`. Test preload at `test/_preload.ts` applies the transformers WASM patch.
-- Use a real ephemeral DuckDB file per test (don't mock the DB).
-- Real fixtures for converters (`test/fixtures/sample.pdf`, `sample.docx`, `sample.html`).
-- Mock the network only for fetcher tests; everything else hits the real local pipeline.
-- Versioning paths to cover: insert creates v1, refresh-unchanged creates no new version, refresh-changed creates v2, `current_files` returns v2, explicit `version=v1` returns v1, tombstone hides from `current_files` but `versions` still lists it, `prune --before` drops non-current rows.
-
-## Build & distribution
-
-- Pre-build: `scripts/apply-transformers-patch.sh` (copy verbatim from mcpx).
-- Build: `bun build --compile --minify --sourcemap ./src/cli.ts --outfile dist/ctx`.
-- Targets: darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64, windows-arm64.
-- Distribution: `install.sh` / `install.ps1` mirror mcpx; published to NPM as well.
-
-## Things to avoid
-
-- Re-introducing a filesystem store under `~/.ctx/context/`. The store is rows.
-- Cloud embeddings. Local WASM only.
-- Mutating an existing version's `content` / `content_sha256` / `chunks`. Those fields are immutable once the row is written — corrections are new versions.
-- Re-routing a remote refresh through the LLM/agent. Replay the stored `fetcher_*` columns directly via mcpx.
-- Tools that return content blobs without a `version_id` — every read-shaped response must echo which version it served.
-- A separate `ctx_read_blob` tool. Bytes are reachable via `ctx_read` with `bytes=true`. One read tool, one mental model.
-- Embedding `chunk_content` raw. Always embed `search_text` (the prepended `<path>\n<description>\n\n<body>`) — that's what `chunks.search_text` holds and what FTS is built on.
-- Aborting a directory/glob ingest because one entry failed. Stream per-entry results; report failures alongside successes.
-- Throwing `new Error(...)` anywhere in `src/operations/`, `src/ingest/`, `src/db/`, `src/refresh/`, or `src/mcp/`. Always `HelpfulError`. Wrap external errors with `asHelpful(cause, context, hint, kind)`.
-- Writing colorized output unconditionally. Always go through `src/output/` so non-interactive callers get clean JSON.
-- A `HelpfulError` whose hint just paraphrases the message ("File not found. Hint: file is missing."). Hint must name a concrete next step — a command, a flag, a path to inspect.
-- **Defining a tool description in two places.** If you catch yourself writing copy in `src/mcp/...` that also exists in `src/commands/...`, stop — make it an `Operation`.
-- Hand-rolling a JSON Schema for an MCP tool. Always derive it from the zod input schema via the mount adapter.
-
-## When in doubt
-
-Read `docs/plan.md`. If the plan and code disagree, the plan wins until a deliberate update lands in both.