membot 0.4.1 → 0.5.0

package/.claude/skills/membot.md

@@ -125,6 +125,7 @@ Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --
 | `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
 | `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
 | `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+| `membot config <subcommand>`          | Host-side config management (`get` / `set` / `unset` / `list` / `path`). **Don't run** — this is for the human operator, not for agents |
 
 ## Output formats
 

package/.cursor/rules/membot.mdc

@@ -125,6 +125,7 @@ Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --
 | `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
 | `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
 | `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+| `membot config <subcommand>`          | Host-side config management (`get` / `set` / `unset` / `list` / `path`). **Don't run** — this is for the human operator, not for agents |
 
 ## Output formats
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Tahler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,7 @@
 
 > Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.
 
+[![npm](https://img.shields.io/npm/v/membot.svg)](https://www.npmjs.com/package/membot)
 [![license](https://img.shields.io/github/license/evantahler/membot.svg)](./LICENSE)
 
 `membot` is a single-binary CLI and MCP server that gives AI agents a persistent, versioned, searchable context store. Files (markdown, PDFs, DOCX, HTML, URLs, agent-authored notes) are ingested, converted to markdown, chunked, embedded **locally** with `@huggingface/transformers` (WASM, no cloud calls), and indexed in DuckDB with hybrid search (semantic vector + BM25). Every change creates a new version — nothing is overwritten in place.
@@ -63,6 +64,7 @@ The skill files describe the discover → ingest → search → read → write w
 | `membot prune --before <ts>`    | Permanently drop non-current versions older than cutoff (irreversible)            |
 | `membot serve`                  | Run the MCP server (stdio default; `--http <port>` for HTTP)                      |
 | `membot reindex`                | Rebuild the FTS keyword index over current chunks                                 |
+| `membot config <subcommand>`    | Get / set values in `~/.membot/config.json` (`get`, `set`, `unset`, `list`, `path`) |
 | `membot mcpx <subcommand>`      | Forward to the bundled `mcpx` CLI for managing remote MCP servers                 |
 | `membot skill install`          | Install the Claude Code / Cursor agent skill                                      |
 
@@ -100,9 +102,20 @@ Add `--watch` (and optional `--tick <sec>`) to also run the refresh daemon, whic
   - `~/.membot/index.duckdb` — all content, blobs, chunks, embeddings, and metadata.
   - `~/.membot/models/` — cached embedding model weights (`Xenova/bge-small-en-v1.5`, 384-dim).
   - `~/.membot/logs/` — daemon logs when running `serve --watch`.
-- **Config file:** `~/.membot/config.json` (optional; defaults are sane).
+- **Config file:** `~/.membot/config.json` (optional; defaults are sane). Edit it directly or via `membot config`:
+
+  ```bash
+  membot config list                                            # show every value (secrets masked)
+  membot config set llm.anthropic_api_key sk-ant-...            # enable LLM-fallback paths
+  membot config set chunker.target_chars 800                    # tweak any nested value
+  membot config get llm.anthropic_api_key --show-secrets        # reveal the masked key
+  membot config unset chunker.target_chars                      # back to schema default
+  membot config path                                            # print the absolute config path
+  ```
+
+  Values are written with file mode `0600`. `ANTHROPIC_API_KEY` set in the environment still wins on read, so existing env-var setups keep working.
 - **Environment variables:**
-  - `ANTHROPIC_API_KEY` — optional. Enables LLM fallback for messy / scanned input (vision captions for images, last-resort markdown conversion). Without it, the pipeline degrades to deterministic native conversion.
+  - `ANTHROPIC_API_KEY` — optional. Enables LLM fallback for messy / scanned input (vision captions for images, last-resort markdown conversion). Without it, the pipeline degrades to deterministic native conversion. Equivalent to `membot config set llm.anthropic_api_key ...`; the env var takes precedence on read.
   - `MEMBOT_HOME` — override the data directory.
   - `NO_COLOR`, `CI`, `FORCE_COLOR` — standard output controls.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "membot",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
 	"type": "module",
 	"exports": {

package/src/cli.ts

@@ -4,6 +4,7 @@ import { bold, cyan, dim, green, yellow } from "ansis";
 import { program } from "commander";
 import pkg from "../package.json" with { type: "json" };
 import { registerCheckUpdateCommand } from "./commands/check-update.ts";
+import { registerConfigCommand } from "./commands/config.ts";
 import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerReindexCommand } from "./commands/reindex.ts";
 import { registerServeCommand } from "./commands/serve.ts";
@@ -57,6 +58,7 @@ for (const op of OPERATIONS) {
 
 registerServeCommand(program);
 registerReindexCommand(program);
+registerConfigCommand(program);
 registerMcpxCommand(program);
 registerSkillCommand(program);
 registerCheckUpdateCommand(program);

package/src/commands/config.ts

@@ -0,0 +1,494 @@
+import type { Command } from "commander";
+import { z } from "zod";
+import { loadConfig, saveConfig } from "../config/loader.ts";
+import { type MembotConfig, MembotConfigSchema } from "../config/schemas.ts";
+import { ENV } from "../constants.ts";
+import { HelpfulError, isHelpfulError, mapKindToExit } from "../errors.ts";
+import { renderCliError } from "../mount/commander.ts";
+import { colors, renderTable } from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+import { detectMode, isJson, setMode } from "../output/tty.ts";
+
+/**
+ * The set of value shapes any config leaf can take. Mirrors the zod leaf
+ * types used in `MembotConfigSchema` — extend this when the schema gains a
+ * new primitive (e.g. arrays, enums).
+ */
+export type ConfigFieldKind = "string" | "number" | "boolean" | "null" | "unknown";
+
+/**
+ * Single source of truth for "what does this config key look like?":
+ * - `path` — dot-notation address (e.g. `llm.anthropic_api_key`)
+ * - `kind` — runtime value shape, derived from the zod schema
+ * - `nullable` — whether `null` is a legal value
+ * - `is_secret` — declared at the schema level via `.meta({ secret: true })`;
+ *   drives masking on every read path
+ */
+export interface ConfigField {
+	path: string;
+	kind: ConfigFieldKind;
+	nullable: boolean;
+	is_secret: boolean;
+}
+
+interface ConfigGetOptions {
+	showSecrets?: boolean;
+}
+
+/**
+ * Register the `membot config` parent command and its subcommands
+ * (`get`, `set`, `unset`, `list`, `path`). All subcommands read from and
+ * write to `~/.membot/config.json` via the existing `loadConfig` /
+ * `saveConfig` helpers, so dot-paths, defaults, and env-var precedence
+ * stay consistent with the rest of membot.
+ */
+export function registerConfigCommand(program: Command): void {
+	const config = program.command("config").description("Get and set membot config values in ~/.membot/config.json");
+
+	config
+		.command("get")
+		.argument("[key]", "dot-notation key (e.g. llm.anthropic_api_key); omit to print all values")
+		.option("--show-secrets", "print secret values (e.g. API keys) unmasked")
+		.description("Print a config value at the given dot-notation key, or all values if no key is given")
+		.action(async (key: string | undefined, opts: ConfigGetOptions) => {
+			await runSubcommand(program, async () => {
+				if (key === undefined) {
+					await runList(opts);
+				} else {
+					await runGet(key, opts);
+				}
+			});
+		});
+
+	config
+		.command("set")
+		.argument("<key>", "dot-notation key (e.g. llm.anthropic_api_key)")
+		.argument("<value>", 'JSON literal (42, true, null, "text") or raw string')
+		.description("Set a config value at the given dot-notation key. Persists to ~/.membot/config.json")
+		.action(async (key: string, value: string) => {
+			await runSubcommand(program, async () => {
+				await runSet(key, value);
+			});
+		});
+
+	config
+		.command("unset")
+		.argument("<key>", "dot-notation key (e.g. chunker.target_chars)")
+		.description("Reset a config value to its schema default")
+		.action(async (key: string) => {
+			await runSubcommand(program, async () => {
+				await runUnset(key);
+			});
+		});
+
+	config
+		.command("list")
+		.option("--show-secrets", "print secret values (e.g. API keys) unmasked")
+		.description("Print every config value (table on a TTY, JSON otherwise). Secrets masked by default")
+		.action(async (opts: ConfigGetOptions) => {
+			await runSubcommand(program, async () => {
+				await runList(opts);
+			});
+		});
+
+	config
+		.command("path")
+		.description("Print the absolute path to the config file")
+		.action(async () => {
+			await runSubcommand(program, async () => {
+				await runPath();
+			});
+		});
+}
+
+/**
+ * Apply global flags to the output mode (so `--json` / `--no-color` /
+ * `CI=true` are honored) and turn any thrown error into a uniform
+ * `renderCliError` + appropriate exit code.
+ */
+async function runSubcommand(program: Command, fn: () => Promise<void>): Promise<void> {
+	const globalOpts = program.optsWithGlobals<{
+		json?: boolean;
+		verbose?: boolean;
+		color?: boolean;
+	}>();
+	setMode(
+		detectMode({
+			json: globalOpts.json,
+			verbose: globalOpts.verbose,
+			noColor: globalOpts.color === false,
+		}),
+	);
+	try {
+		await fn();
+	} catch (err) {
+		renderCliError(err);
+		process.exit(isHelpfulError(err) ? mapKindToExit(err.kind) : 1);
+	}
+}
+
+/** Print a single config value at `key`, masked unless `--show-secrets`. */
+export async function runGet(key: string, opts: ConfigGetOptions): Promise<void> {
+	resolveSchemaPath(MembotConfigSchema, key);
+	const { config } = await loadConfig();
+	const raw = getValueAt(config, key);
+	const value = opts.showSecrets ? raw : maskIfSecret(key, raw);
+	if (isJson()) {
+		process.stdout.write(`${JSON.stringify(value)}\n`);
+		return;
+	}
+	process.stdout.write(`${formatScalar(value)}\n`);
+}
+
+/**
+ * Coerce + validate + persist `value` at `key`. Coercion rule: try
+ * `JSON.parse(value)` first (so `42` / `true` / `null` work); fall back to
+ * the raw string. Validation runs the full `MembotConfigSchema` parse, so
+ * type errors surface a precise hint.
+ */
+export async function runSet(key: string, rawValue: string): Promise<void> {
+	resolveSchemaPath(MembotConfigSchema, key);
+	const coerced = coerceValue(rawValue);
+
+	const { config, configPath } = await loadConfig();
+	const draft = structuredClone(config);
+	setValueAt(draft, key, coerced);
+
+	const validated = validateOrThrow(draft, key);
+	await saveConfig(configPath, validated);
+
+	if (isJson()) {
+		process.stdout.write(
+			`${JSON.stringify({ ok: true, key, value: maskIfSecret(key, getValueAt(validated, key)) })}\n`,
+		);
+	} else {
+		const display = formatScalar(maskIfSecret(key, getValueAt(validated, key)));
+		logger.info(`set ${key} = ${display}`);
+	}
+
+	// If a user just persisted the API key while ANTHROPIC_API_KEY is also set
+	// in the environment, the env wins on read — surface that so they don't
+	// wonder why their new value isn't taking effect.
+	if (key === "llm.anthropic_api_key" && process.env[ENV.ANTHROPIC_API_KEY]?.trim()) {
+		logger.warn(
+			`note: ANTHROPIC_API_KEY is set in your environment and overrides the file at read time. Unset it (\`unset ANTHROPIC_API_KEY\`) to use the value you just saved.`,
+		);
+	}
+}
+
+/** Reset `key` to whatever `MembotConfigSchema` produces from `{}`. */
+export async function runUnset(key: string): Promise<void> {
+	resolveSchemaPath(MembotConfigSchema, key);
+	const defaults = MembotConfigSchema.parse({});
+	const defaultValue = getValueAt(defaults, key);
+
+	const { config, configPath } = await loadConfig();
+	const draft = structuredClone(config);
+	setValueAt(draft, key, defaultValue);
+
+	const validated = validateOrThrow(draft, key);
+	await saveConfig(configPath, validated);
+
+	if (isJson()) {
+		process.stdout.write(`${JSON.stringify({ ok: true, key, value: maskIfSecret(key, defaultValue) })}\n`);
+	} else {
+		logger.info(`unset ${key} → ${formatScalar(maskIfSecret(key, defaultValue))}`);
+	}
+}
+
+/** Print every key/value pair. JSON mode → nested config object; TTY → table. */
+async function runList(opts: ConfigGetOptions): Promise<void> {
+	const { config } = await loadConfig();
+	if (isJson()) {
+		const masked = opts.showSecrets ? config : maskAllSecrets(config);
+		process.stdout.write(`${JSON.stringify(masked, null, 2)}\n`);
+		return;
+	}
+	const paths = enumerateSchemaPaths(MembotConfigSchema);
+	const rows = paths.map((p) => {
+		const raw = getValueAt(config, p);
+		const value = opts.showSecrets ? raw : maskIfSecret(p, raw);
+		return [colors.cyan(p), formatScalar(value)];
+	});
+	process.stdout.write(`${renderTable(["key", "value"], rows)}\n`);
+}
+
+/** Print the absolute path to the config file. */
+async function runPath(): Promise<void> {
+	const { configPath } = await loadConfig();
+	if (isJson()) {
+		process.stdout.write(`${JSON.stringify({ path: configPath })}\n`);
+		return;
+	}
+	process.stdout.write(`${configPath}\n`);
+}
+
+/**
+ * Walk a dotted path through `MembotConfigSchema` and return the leaf zod
+ * type. Descends into `ZodObject.shape` and transparently unwraps
+ * `ZodDefault` / `ZodOptional` / `ZodNullable`. Throws `HelpfulError` if any
+ * segment doesn't exist, with a "did you mean" suggestion derived from the
+ * full set of valid paths.
+ */
+export function resolveSchemaPath(schema: z.ZodTypeAny, dottedPath: string): z.ZodTypeAny {
+	const segments = dottedPath.split(".").filter((s) => s.length > 0);
+	if (segments.length === 0) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: "config key is required",
+			hint: "Pass a dot-notation key, e.g. `membot config get llm.anthropic_api_key`. Run `membot config list` for the full set.",
+		});
+	}
+
+	let current = unwrapSchema(schema);
+	const traversed: string[] = [];
+	for (const segment of segments) {
+		if (!(current instanceof z.ZodObject)) {
+			throw unknownKeyError(dottedPath, traversed.join("."));
+		}
+		const shape = current.shape as Record<string, z.ZodTypeAny>;
+		const next = shape[segment];
+		if (!next) {
+			throw unknownKeyError(dottedPath, [...traversed, segment].join("."));
+		}
+		traversed.push(segment);
+		current = unwrapSchema(next);
+	}
+	return current;
+}
+
+/**
+ * Build the `HelpfulError` for an unknown key. Includes a "did you mean"
+ * suggestion when there's an obvious near-match (Levenshtein distance ≤ 2).
+ */
+function unknownKeyError(badPath: string, _matchedPrefix: string): HelpfulError {
+	const valid = enumerateSchemaPaths(MembotConfigSchema);
+	const suggestion = nearestPath(badPath, valid);
+	const baseHint = "Run `membot config list` to see all valid keys.";
+	const hint = suggestion ? `Did you mean \`${suggestion}\`? ${baseHint}` : baseHint;
+	return new HelpfulError({
+		kind: "input_error",
+		message: `unknown config key: ${badPath}`,
+		hint,
+	});
+}
+
+/** Return the closest known path within Levenshtein distance 2, or null. */
+function nearestPath(target: string, candidates: readonly string[]): string | null {
+	let best: { path: string; distance: number } | null = null;
+	for (const c of candidates) {
+		const d = levenshtein(target, c);
+		if (d <= 2 && (!best || d < best.distance)) best = { path: c, distance: d };
+	}
+	return best?.path ?? null;
+}
+
+function levenshtein(a: string, b: string): number {
+	if (a === b) return 0;
+	if (a.length === 0) return b.length;
+	if (b.length === 0) return a.length;
+	const prev = new Array<number>(b.length + 1);
+	const curr = new Array<number>(b.length + 1);
+	for (let j = 0; j <= b.length; j++) prev[j] = j;
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min((curr[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+		}
+		for (let j = 0; j <= b.length; j++) prev[j] = curr[j] ?? 0;
+	}
+	return prev[b.length] ?? 0;
+}
+
+/**
+ * Strip every layer of `ZodDefault` / `ZodOptional` / `ZodNullable`. Zod 4
+ * types `.unwrap()` as the lower-level `$ZodType` rather than `ZodType`, so
+ * we cast back through `unknown` — the runtime instance is a real `ZodType`.
+ */
+function unwrapSchema(t: z.ZodTypeAny): z.ZodTypeAny {
+	let cur = t;
+	while (cur instanceof z.ZodDefault || cur instanceof z.ZodOptional || cur instanceof z.ZodNullable) {
+		cur = cur.unwrap() as unknown as z.ZodTypeAny;
+	}
+	return cur;
+}
+
+/**
+ * Walk every wrapper layer of a zod leaf (default / optional / nullable)
+ * and return: the innermost type, whether `null` is legal, and the merged
+ * `.meta()` from every layer (outer layers win on conflict).
+ *
+ * Zod 4's `.meta()` is bound to the specific layer where it was declared —
+ * `.meta({secret:true}).default("")` and `.default("").meta({secret:true})`
+ * land it on different wrappers — so we have to scan all of them.
+ */
+function walkLeaf(t: z.ZodTypeAny): {
+	leaf: z.ZodTypeAny;
+	nullable: boolean;
+	meta: Record<string, unknown>;
+} {
+	let cur = t;
+	let nullable = false;
+	const layers: z.ZodTypeAny[] = [cur];
+	while (cur instanceof z.ZodDefault || cur instanceof z.ZodOptional || cur instanceof z.ZodNullable) {
+		if (cur instanceof z.ZodNullable) nullable = true;
+		cur = cur.unwrap() as unknown as z.ZodTypeAny;
+		layers.push(cur);
+	}
+	let meta: Record<string, unknown> = {};
+	// inner-to-outer merge so outer layers (declared closer to the user) win
+	for (const layer of layers) {
+		const layerMeta = (layer as { meta?: () => Record<string, unknown> | undefined }).meta?.();
+		if (layerMeta) meta = { ...meta, ...layerMeta };
+	}
+	return { leaf: cur, nullable, meta };
+}
+
+/** Map a zod leaf type to its `ConfigFieldKind` discriminator. */
+function inferKind(leaf: z.ZodTypeAny): ConfigFieldKind {
+	if (leaf instanceof z.ZodString) return "string";
+	if (leaf instanceof z.ZodNumber) return "number";
+	if (leaf instanceof z.ZodBoolean) return "boolean";
+	if (leaf instanceof z.ZodNull) return "null";
+	return "unknown";
+}
+
+/**
+ * Recursively enumerate every leaf in a zod schema as a `ConfigField`. This
+ * is the single source of truth for what's gettable / settable / maskable —
+ * adding a new field to `MembotConfigSchema` (and tagging it with
+ * `.meta({secret:true})` if appropriate) is enough to make every path here
+ * pick it up automatically.
+ */
+export function enumerateSchemaFields(schema: z.ZodTypeAny, prefix = ""): ConfigField[] {
+	const root = unwrapSchema(schema);
+	if (!(root instanceof z.ZodObject)) {
+		if (!prefix) return [];
+		const { leaf, nullable, meta } = walkLeaf(schema);
+		return [{ path: prefix, kind: inferKind(leaf), nullable, is_secret: meta.secret === true }];
+	}
+	const out: ConfigField[] = [];
+	const shape = root.shape as Record<string, z.ZodTypeAny>;
+	for (const key of Object.keys(shape)) {
+		const child = shape[key] as z.ZodTypeAny;
+		const childUnwrapped = unwrapSchema(child);
+		const path = prefix ? `${prefix}.${key}` : key;
+		if (childUnwrapped instanceof z.ZodObject) {
+			out.push(...enumerateSchemaFields(childUnwrapped, path));
+		} else {
+			const { leaf, nullable, meta } = walkLeaf(child);
+			out.push({ path, kind: inferKind(leaf), nullable, is_secret: meta.secret === true });
+		}
+	}
+	return out;
+}
+
+/** Backward-compatible wrapper: just the dotted paths, no metadata. */
+export function enumerateSchemaPaths(schema: z.ZodTypeAny, prefix = ""): string[] {
+	return enumerateSchemaFields(schema, prefix).map((f) => f.path);
+}
+
+/**
+ * Field index built once from `MembotConfigSchema` at module load. Every
+ * read/write path consults this instead of duplicating schema introspection.
+ */
+const FIELD_INDEX: ReadonlyMap<string, ConfigField> = new Map(
+	enumerateSchemaFields(MembotConfigSchema).map((f) => [f.path, f]),
+);
+
+/** Look up the `ConfigField` for a known dotted path, or `undefined`. */
+export function getField(path: string): ConfigField | undefined {
+	return FIELD_INDEX.get(path);
+}
+
+/** Read the value at a dotted path from a plain object. */
+function getValueAt(obj: unknown, dottedPath: string): unknown {
+	let cur: unknown = obj;
+	for (const segment of dottedPath.split(".")) {
+		if (cur === null || typeof cur !== "object") return undefined;
+		cur = (cur as Record<string, unknown>)[segment];
+	}
+	return cur;
+}
+
+/**
+ * Set the value at a dotted path on a plain object, creating intermediate
+ * objects as needed. Mutates `obj` in place.
+ */
+function setValueAt(obj: Record<string, unknown>, dottedPath: string, value: unknown): void {
+	const segments = dottedPath.split(".");
+	let cur: Record<string, unknown> = obj;
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i] as string;
+		const next = cur[seg];
+		if (next === null || typeof next !== "object") {
+			cur[seg] = {};
+		}
+		cur = cur[seg] as Record<string, unknown>;
+	}
+	cur[segments[segments.length - 1] as string] = value;
+}
+
+/**
+ * Try `JSON.parse` (so `42`, `true`, `null`, `"foo"` all coerce correctly);
+ * fall back to the raw string when the value isn't valid JSON.
+ */
+function coerceValue(raw: string): unknown {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+
+/**
+ * Reparse the entire draft against `MembotConfigSchema`. On failure, throw
+ * a `HelpfulError` whose hint names the offending dot-path and shows the
+ * zod error message — far more useful than zod's raw issue array.
+ */
+function validateOrThrow(draft: unknown, key: string): MembotConfig {
+	const result = MembotConfigSchema.safeParse(draft);
+	if (result.success) return result.data;
+	const issue = result.error.issues.find((i) => i.path.join(".") === key) ?? result.error.issues[0];
+	const issuePath = issue?.path.join(".") ?? key;
+	const issueMessage = issue?.message ?? result.error.message;
+	throw new HelpfulError({
+		kind: "input_error",
+		message: `invalid value for ${issuePath}: ${issueMessage}`,
+		hint: `Run \`membot config get ${issuePath}\` to see the current value, or \`membot config unset ${issuePath}\` to reset to default.`,
+		details: result.error.issues,
+		cause: result.error,
+	});
+}
+
+/**
+ * Mask a value for display when its `ConfigField.is_secret` is true.
+ * Non-secret paths and unknown paths pass through unchanged.
+ */
+export function maskIfSecret(path: string, value: unknown): unknown {
+	if (!getField(path)?.is_secret) return value;
+	if (typeof value !== "string" || value.length === 0) return value;
+	if (value.length <= 11) return "****";
+	return `${value.slice(0, 7)}...${value.slice(-4)}`;
+}
+
+/** Walk a config object and mask every secret field in place. */
+function maskAllSecrets(config: MembotConfig): MembotConfig {
+	const clone = structuredClone(config) as Record<string, unknown>;
+	for (const field of FIELD_INDEX.values()) {
+		if (!field.is_secret) continue;
+		const current = getValueAt(clone, field.path);
+		setValueAt(clone, field.path, maskIfSecret(field.path, current));
+	}
+	return clone as MembotConfig;
+}
+
+/** Render a scalar (or null/undefined/object) for human-readable output. */
+function formatScalar(value: unknown): string {
+	if (value === null) return colors.dim("null");
+	if (value === undefined) return colors.dim("(unset)");
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return JSON.stringify(value);
+}

package/src/config/loader.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { chmod, mkdir } from "node:fs/promises";
 import { resolve } from "node:path";
 import { defaultMembotHome, ENV, FILES } from "../constants.ts";
 import { asHelpful, HelpfulError } from "../errors.ts";
@@ -74,17 +74,19 @@ function resolveDataDir(flag?: string): string {
 }
 
 /**
- * Persist config to disk, with the Anthropic API key blanked out — the env
- * var (`ANTHROPIC_API_KEY`) is the source of truth, never the file. Writing
- * the key to disk would land it in shell history, dotfile syncs, and
- * accidental commits.
+ * Persist config to disk and chmod 0600 so the file is owner-read-only —
+ * `llm.anthropic_api_key` may be present, and we don't want it world-readable.
+ * `loadConfig` still lets `ANTHROPIC_API_KEY` (env) override the file at read
+ * time, so an env-var-only setup keeps working unchanged.
  */
 export async function saveConfig(configPath: string, config: MembotConfig): Promise<void> {
-	const safe: MembotConfig = {
-		...config,
-		llm: { ...config.llm, anthropic_api_key: "" },
-	};
-	await Bun.write(configPath, `${JSON.stringify(safe, null, 2)}\n`);
+	await Bun.write(configPath, `${JSON.stringify(config, null, 2)}\n`);
+	try {
+		await chmod(configPath, 0o600);
+	} catch {
+		// chmod is best-effort: filesystems without unix permissions (e.g. some
+		// Windows scenarios) silently fail, and that's acceptable.
+	}
 }
 
 /**

package/src/config/schemas.ts

@@ -8,7 +8,7 @@ export const ChunkerConfigSchema = z.object({
 });
 
 export const LlmConfigSchema = z.object({
-	anthropic_api_key: z.string().default(""),
+	anthropic_api_key: z.string().meta({ secret: true }).default(""),
 	converter_model: z.string().default(DEFAULTS.CONVERTER_MODEL),
 	chunker_model: z.string().default(DEFAULTS.CHUNKER_MODEL),
 	describer_model: z.string().default(DEFAULTS.DESCRIBER_MODEL),

package/src/ingest/embedder.ts

@@ -63,6 +63,16 @@ async function getPipeline(model: string): Promise<FeatureExtractionPipeline> {
 	return p;
 }
 
+/**
+ * Options for `embed()`. `onProgress` fires once after each batch finishes
+ * with `(done, total)` chunk counts so callers can drive a spinner / progress
+ * bar — ONNX WASM holds the JS thread for hundreds of ms per batch and would
+ * otherwise leave nanospinner's setInterval starved between updates.
+ */
+export interface EmbedOptions {
+	onProgress?: (done: number, total: number) => void;
+}
+
 /**
  * Embed an array of texts to L2-normalized vectors with the configured
  * model. Throws a HelpfulError when the model's dimension doesn't match
@@ -71,8 +81,16 @@ async function getPipeline(model: string): Promise<FeatureExtractionPipeline> {
  * Inputs are sliced into windows of EMBEDDING_BATCH_SIZE so a single
  * forward pass never has to allocate activations for arbitrarily many
  * chunks — large files (hundreds of chunks) otherwise OOM the WASM heap.
+ *
+ * Between batches we yield a macrotask (`setTimeout(0)`) so the event loop
+ * can flush nanospinner renders and stderr writes — without that, the spinner
+ * visibly freezes for the entire embed phase on large files.
  */
-export async function embed(texts: string[], model: string = EMBEDDING_MODEL): Promise<number[][]> {
+export async function embed(
+	texts: string[],
+	model: string = EMBEDDING_MODEL,
+	opts: EmbedOptions = {},
+): Promise<number[][]> {
 	if (texts.length === 0) return [];
 	const extractor = await getPipeline(model);
 	const out: number[][] = [];
@@ -88,6 +106,10 @@ export async function embed(texts: string[], model: string = EMBEDDING_MODEL): P
 			});
 		}
 		for (const vec of data) out.push(vec);
+		opts.onProgress?.(out.length, texts.length);
+		// Yield a macrotask so nanospinner's setInterval and any queued
+		// stderr writes get a chance to run between batches.
+		await new Promise<void>((resolve) => setTimeout(resolve, 0));
 	}
 	return out;
 }

package/src/ingest/ingest.ts

@@ -54,6 +54,13 @@ export interface IngestResult {
 export interface IngestCallbacks {
 	onEntryStart?: (label: string) => void;
 	onEntryComplete?: (entry: IngestEntryResult) => void;
+	/**
+	 * Fires for sub-step progress within a single entry (e.g. "embedding
+	 * 32/168"). The callback runs many times per entry and is intended for
+	 * driving an interactive spinner — non-interactive callers should ignore
+	 * it to avoid log spam.
+	 */
+	onEntryProgress?: (label: string, sublabel: string) => void;
 }
 
 /**
@@ -140,23 +147,27 @@ async function ingestInline(
 		source_sha256: sha,
 	};
 	try {
-		const versionId = await persistVersion(ctx, {
-			logicalPath,
-			sourceType: "inline",
-			sourcePath: null,
-			sourceMtimeMs: null,
-			sourceSha: sha,
-			blobSha: null,
-			mime: "text/markdown",
-			bytes: null,
-			markdown: text,
-			fetcher: "inline",
-			fetcherServer: null,
-			fetcherTool: null,
-			fetcherArgs: null,
-			refreshSec,
-			changeNote: input.change_note ?? null,
-		});
+		const versionId = await persistVersion(
+			ctx,
+			{
+				logicalPath,
+				sourceType: "inline",
+				sourcePath: null,
+				sourceMtimeMs: null,
+				sourceSha: sha,
+				blobSha: null,
+				mime: "text/markdown",
+				bytes: null,
+				markdown: text,
+				fetcher: "inline",
+				fetcherServer: null,
+				fetcherTool: null,
+				fetcherArgs: null,
+				refreshSec,
+				changeNote: input.change_note ?? null,
+			},
+			(done, total) => callbacks?.onEntryProgress?.(logicalPath, `embedding ${done}/${total}`),
+		);
 		result.version_id = versionId;
 	} catch (err) {
 		result.status = "failed";
@@ -217,22 +228,26 @@ async function ingestUrl(
 			}
 		}
 
-		const versionId = await pipelineForBytes(ctx, {
-			logicalPath,
-			bytes: fetched.bytes,
-			mime: fetched.mimeType,
-			source: url,
-			sourceType: "remote",
-			sourcePath: url,
-			sourceMtimeMs: null,
-			sourceSha: fetched.sha256,
-			fetcher: fetched.fetcher,
-			fetcherServer: fetched.fetcherServer,
-			fetcherTool: fetched.fetcherTool,
-			fetcherArgs: fetched.fetcherArgs,
-			refreshSec,
-			changeNote: input.change_note ?? null,
-		});
+		const versionId = await pipelineForBytes(
+			ctx,
+			{
+				logicalPath,
+				bytes: fetched.bytes,
+				mime: fetched.mimeType,
+				source: url,
+				sourceType: "remote",
+				sourcePath: url,
+				sourceMtimeMs: null,
+				sourceSha: fetched.sha256,
+				fetcher: fetched.fetcher,
+				fetcherServer: fetched.fetcherServer,
+				fetcherTool: fetched.fetcherTool,
+				fetcherArgs: fetched.fetcherArgs,
+				refreshSec,
+				changeNote: input.change_note ?? null,
+			},
+			(done, total) => callbacks?.onEntryProgress?.(url, `embedding ${done}/${total}`),
+		);
 		result.version_id = versionId;
 	} catch (err) {
 		result.status = "failed";
@@ -299,22 +314,26 @@ async function ingestLocalFiles(
 				}
 			}
 
-			const versionId = await pipelineForBytes(ctx, {
-				logicalPath,
-				bytes: local.bytes,
-				mime: local.mimeType,
-				source: entry.absPath,
-				sourceType: "local",
-				sourcePath: entry.absPath,
-				sourceMtimeMs: local.mtimeMs,
-				sourceSha: local.sha256,
-				fetcher: "local",
-				fetcherServer: null,
-				fetcherTool: null,
-				fetcherArgs: null,
-				refreshSec,
-				changeNote: input.change_note ?? null,
-			});
+			const versionId = await pipelineForBytes(
+				ctx,
+				{
+					logicalPath,
+					bytes: local.bytes,
+					mime: local.mimeType,
+					source: entry.absPath,
+					sourceType: "local",
+					sourcePath: entry.absPath,
+					sourceMtimeMs: local.mtimeMs,
+					sourceSha: local.sha256,
+					fetcher: "local",
+					fetcherServer: null,
+					fetcherTool: null,
+					fetcherArgs: null,
+					refreshSec,
+					changeNote: input.change_note ?? null,
+				},
+				(done, total) => callbacks?.onEntryProgress?.(entry.relPathFromBase, `embedding ${done}/${total}`),
+			);
 			result.version_id = versionId;
 		} catch (err) {
 			result.status = "failed";
@@ -353,9 +372,14 @@ interface PipelineParams {
  * Run the bytes-in / version-out pipeline: store the blob, convert to
  * markdown, describe, chunk, embed, and write a new files row + chunks
  * rows under a fresh version_id. Returns the version_id so callers can
- * report it back.
+ * report it back. The optional `onEmbedProgress` is forwarded to the
+ * embedder so callers can drive a spinner during the slow phase.
  */
-async function pipelineForBytes(ctx: AppContext, p: PipelineParams): Promise<string> {
+async function pipelineForBytes(
+	ctx: AppContext,
+	p: PipelineParams,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<string> {
 	await upsertBlob(ctx.db, {
 		sha256: p.sourceSha,
 		mime_type: p.mime,
@@ -367,24 +391,28 @@ async function pipelineForBytes(ctx: AppContext, p: PipelineParams): Promise<str
 	const markdown = conversion.markdown;
 	const contentSha = sha256Hex(new TextEncoder().encode(markdown));
 
-	return persistVersion(ctx, {
-		logicalPath: p.logicalPath,
-		sourceType: p.sourceType,
-		sourcePath: p.sourcePath,
-		sourceMtimeMs: p.sourceMtimeMs,
-		sourceSha: p.sourceSha,
-		blobSha: p.sourceSha,
-		mime: p.mime,
-		bytes: p.bytes,
-		markdown,
-		contentSha,
-		fetcher: p.fetcher,
-		fetcherServer: p.fetcherServer,
-		fetcherTool: p.fetcherTool,
-		fetcherArgs: p.fetcherArgs,
-		refreshSec: p.refreshSec,
-		changeNote: p.changeNote,
-	});
+	return persistVersion(
+		ctx,
+		{
+			logicalPath: p.logicalPath,
+			sourceType: p.sourceType,
+			sourcePath: p.sourcePath,
+			sourceMtimeMs: p.sourceMtimeMs,
+			sourceSha: p.sourceSha,
+			blobSha: p.sourceSha,
+			mime: p.mime,
+			bytes: p.bytes,
+			markdown,
+			contentSha,
+			fetcher: p.fetcher,
+			fetcherServer: p.fetcherServer,
+			fetcherTool: p.fetcherTool,
+			fetcherArgs: p.fetcherArgs,
+			refreshSec: p.refreshSec,
+			changeNote: p.changeNote,
+		},
+		onEmbedProgress,
+	);
 }
 
 interface PersistParams {
@@ -412,13 +440,17 @@ interface PersistParams {
  * embedded text per chunk is `<path>\n<description>\n\n<body>`, stored
  * verbatim as `chunks.search_text` and later FTS-indexed.
  */
-async function persistVersion(ctx: AppContext, p: PersistParams): Promise<string> {
+async function persistVersion(
+	ctx: AppContext,
+	p: PersistParams,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<string> {
 	const description = await describe(p.logicalPath, p.mime, p.markdown, ctx.config.llm);
 	const chunks = chunkDeterministic(p.markdown, ctx.config.chunker);
 	const searchTexts = chunks.map((c) => buildSearchText(p.logicalPath, description, c.content));
 	let embeddings: number[][];
 	try {
-		embeddings = await embed(searchTexts, ctx.config.embedding_model);
+		embeddings = await embed(searchTexts, ctx.config.embedding_model, { onProgress: onEmbedProgress });
 	} catch (err) {
 		throw asHelpful(
 			err,

package/src/operations/add.ts

@@ -138,6 +138,7 @@ Pass \`logical_path\` to override. For a multi-source / directory / glob walk it
 		const callbacks: IngestCallbacks = {
 			onEntryStart: (label) => ctx.progress.tick(label),
 			onEntryComplete: (entry) => ctx.progress.entry(formatEntryLine(entry)),
+			onEntryProgress: (_label, sublabel) => ctx.progress.update(sublabel),
 		};
 
 		for (const outcome of outcomes) {

package/src/operations/refresh.ts

@@ -60,7 +60,9 @@ export const refreshOperation = defineOperation({
 		for (const path of targets) {
 			ctx.progress.tick(path);
 			try {
-				const r = await refreshOne(ctx, path, input.force);
+				const r = await refreshOne(ctx, path, input.force, (done, total) =>
+					ctx.progress.update(`embedding ${done}/${total}`),
+				);
 				out.push(r);
 			} catch (err) {
 				out.push({ logical_path: path, status: "failed", error: err instanceof Error ? err.message : String(err) });

package/src/output/progress.ts

@@ -15,6 +15,13 @@ import { isSilent, useSpinner } from "./tty.ts";
 export interface Progress {
 	start(total: number, label?: string): void;
 	tick(label: string): void;
+	/**
+	 * Re-render the active spinner with the most recent `tick` label plus an
+	 * extra suffix (e.g. "embedding 32/168") without advancing the counter.
+	 * No-op in non-interactive / silent / JSON modes — sub-step progress is
+	 * deliberately TTY-only so CI logs don't get one line per inner batch.
+	 */
+	update(suffix: string): void;
 	entry(line: string): void;
 	done(summary?: string): void;
 	fail(summary?: string): void;
@@ -51,25 +58,28 @@ function truncateLabel(label: string, max = LABEL_MAX): string {
 export function createProgress(): Progress {
 	let total = 0;
 	let count = 0;
+	let lastLabel = "";
 	let spinner: ReturnType<typeof logger.startSpinner> | null = null;
 
 	const interactive = useSpinner();
 	const silent = isSilent();
 
-	const renderSpinnerText = (label: string): string => {
+	const renderSpinnerText = (label: string, suffix?: string): string => {
 		const bar = renderBar(count, total);
 		const pct = total > 0 ? Math.floor((count / total) * 100) : 0;
-		const tail = label ? ` — ${truncateLabel(label)}` : "";
-		return `${bar} ${count}/${total} (${pct}%)${tail}`;
+		const labelTail = label ? ` — ${truncateLabel(label)}` : "";
+		const suffixTail = suffix ? ` — ${suffix}` : "";
+		return `${bar} ${count}/${total} (${pct}%)${labelTail}${suffixTail}`;
 	};
 
 	return {
 		start(t: number, label?: string) {
 			total = t;
 			count = 0;
+			lastLabel = label ?? "";
 			if (silent) return;
 			if (interactive) {
-				const initial = renderSpinnerText(label ?? "");
+				const initial = renderSpinnerText(lastLabel);
 				spinner = logger.startSpinner(initial);
 			} else if (label) {
 				logger.info(`${label}: 0/${total}`);
@@ -77,6 +87,7 @@ export function createProgress(): Progress {
 		},
 		tick(label: string) {
 			count += 1;
+			lastLabel = label;
 			if (silent) return;
 			if (interactive && spinner) {
 				spinner.update(renderSpinnerText(label));
@@ -84,6 +95,11 @@ export function createProgress(): Progress {
 				logger.info(`[${count}/${total}] ${label}`);
 			}
 		},
+		update(suffix: string) {
+			if (silent) return;
+			if (!interactive || !spinner) return;
+			spinner.update(renderSpinnerText(lastLabel, suffix));
+		},
 		entry(line: string) {
 			if (silent) return;
 			logger.info(line);

package/src/refresh/runner.ts

@@ -24,9 +24,16 @@ export interface RefreshOutcome {
  * via the persisted mcpx invocation), and creates a new version only if
  * the source bytes changed. Always updates `refreshed_at` and
  * `last_refresh_status` on the row. Returns a per-path outcome — never
- * throws unless the path doesn't exist.
+ * throws unless the path doesn't exist. The optional `onEmbedProgress`
+ * callback is forwarded to the embedder so interactive callers (e.g. the
+ * `refresh` operation) can drive a spinner during the slow phase.
  */
-export async function refreshOne(ctx: AppContext, logicalPath: string, force = false): Promise<RefreshOutcome> {
+export async function refreshOne(
+	ctx: AppContext,
+	logicalPath: string,
+	force = false,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<RefreshOutcome> {
 	const cur = await getCurrent(ctx.db, logicalPath);
 	if (!cur) {
 		throw new HelpfulError({
@@ -42,10 +49,10 @@ export async function refreshOne(ctx: AppContext, logicalPath: string, force = f
 
 	try {
 		if (cur.source_type === "local") {
-			return await refreshLocal(ctx, cur, force);
+			return await refreshLocal(ctx, cur, force, onEmbedProgress);
 		}
 		if (cur.source_type === "remote") {
-			return await refreshRemote(ctx, cur, force);
+			return await refreshRemote(ctx, cur, force, onEmbedProgress);
 		}
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -74,7 +81,12 @@ interface CurrentRow {
 }
 
 /** Local-file refresh: stat-then-sha gate before re-running the pipeline. */
-async function refreshLocal(ctx: AppContext, cur: CurrentRow, force: boolean): Promise<RefreshOutcome> {
+async function refreshLocal(
+	ctx: AppContext,
+	cur: CurrentRow,
+	force: boolean,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<RefreshOutcome> {
 	if (!cur.source_path) {
 		throw new HelpfulError({
 			kind: "input_error",
@@ -92,26 +104,35 @@ async function refreshLocal(ctx: AppContext, cur: CurrentRow, force: boolean): P
 		return { logical_path: cur.logical_path, status: "unchanged" };
 	}
 
-	const versionId = await runPipelineForRefresh(ctx, {
-		logicalPath: cur.logical_path,
-		bytes: local.bytes,
-		mime: local.mimeType,
-		source: cur.source_path,
-		sourceType: "local",
-		sourcePath: cur.source_path,
-		sourceMtimeMs: local.mtimeMs,
-		sourceSha: local.sha256,
-		fetcher: "local",
-		fetcherServer: null,
-		fetcherTool: null,
-		fetcherArgs: null,
-		refreshSec: cur.refresh_frequency_sec,
-	});
+	const versionId = await runPipelineForRefresh(
+		ctx,
+		{
+			logicalPath: cur.logical_path,
+			bytes: local.bytes,
+			mime: local.mimeType,
+			source: cur.source_path,
+			sourceType: "local",
+			sourcePath: cur.source_path,
+			sourceMtimeMs: local.mtimeMs,
+			sourceSha: local.sha256,
+			fetcher: "local",
+			fetcherServer: null,
+			fetcherTool: null,
+			fetcherArgs: null,
+			refreshSec: cur.refresh_frequency_sec,
+		},
+		onEmbedProgress,
+	);
 	return { logical_path: cur.logical_path, status: "ok", new_version_id: versionId };
 }
 
 /** Remote refresh: replay the persisted mcpx invocation, or plain HTTP. */
-async function refreshRemote(ctx: AppContext, cur: CurrentRow, force: boolean): Promise<RefreshOutcome> {
+async function refreshRemote(
+	ctx: AppContext,
+	cur: CurrentRow,
+	force: boolean,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<RefreshOutcome> {
 	if (!cur.source_path) {
 		throw new HelpfulError({
 			kind: "input_error",
@@ -129,21 +150,25 @@ async function refreshRemote(ctx: AppContext, cur: CurrentRow, force: boolean):
 		return { logical_path: cur.logical_path, status: "unchanged" };
 	}
 
-	const versionId = await runPipelineForRefresh(ctx, {
-		logicalPath: cur.logical_path,
-		bytes: fetched.bytes,
-		mime: fetched.mimeType,
-		source: cur.source_path,
-		sourceType: "remote",
-		sourcePath: cur.source_path,
-		sourceMtimeMs: null,
-		sourceSha: fetched.sha256,
-		fetcher: cur.fetcher === "mcpx" ? "mcpx" : "http",
-		fetcherServer: fetched.fetcherServer,
-		fetcherTool: fetched.fetcherTool,
-		fetcherArgs: fetched.fetcherArgs,
-		refreshSec: cur.refresh_frequency_sec,
-	});
+	const versionId = await runPipelineForRefresh(
+		ctx,
+		{
+			logicalPath: cur.logical_path,
+			bytes: fetched.bytes,
+			mime: fetched.mimeType,
+			source: cur.source_path,
+			sourceType: "remote",
+			sourcePath: cur.source_path,
+			sourceMtimeMs: null,
+			sourceSha: fetched.sha256,
+			fetcher: cur.fetcher === "mcpx" ? "mcpx" : "http",
+			fetcherServer: fetched.fetcherServer,
+			fetcherTool: fetched.fetcherTool,
+			fetcherArgs: fetched.fetcherArgs,
+			refreshSec: cur.refresh_frequency_sec,
+		},
+		onEmbedProgress,
+	);
 	return { logical_path: cur.logical_path, status: "ok", new_version_id: versionId };
 }
 
@@ -237,7 +262,11 @@ interface PipelineParams {
  * fields (`change_note='refresh: source updated'`) aren't accidentally
  * applied to first-time ingests.
  */
-async function runPipelineForRefresh(ctx: AppContext, p: PipelineParams): Promise<string> {
+async function runPipelineForRefresh(
+	ctx: AppContext,
+	p: PipelineParams,
+	onEmbedProgress?: (done: number, total: number) => void,
+): Promise<string> {
 	await upsertBlob(ctx.db, {
 		sha256: p.sourceSha,
 		mime_type: p.mime,
@@ -250,7 +279,7 @@ async function runPipelineForRefresh(ctx: AppContext, p: PipelineParams): Promis
 	const description = await describe(p.logicalPath, p.mime, markdown, ctx.config.llm);
 	const chunks = chunkDeterministic(markdown, ctx.config.chunker);
 	const searchTexts = chunks.map((c) => buildSearchText(p.logicalPath, description, c.content));
-	const embeddings = await embed(searchTexts, ctx.config.embedding_model);
+	const embeddings = await embed(searchTexts, ctx.config.embedding_model, { onProgress: onEmbedProgress });
 
 	const versionId = millisIso(Date.now());
 	const contentSha = sha256Hex(new TextEncoder().encode(markdown));