@taurgis/bonsai 3.2.2 → 4.1.0

package/dist/lib/cli-presentation.d.ts

@@ -1,3 +1,4 @@
+import type { TokenEstimate } from './research/schema.js';
 /** Shared flag/help copy so identical flags read identically across commands. */
 export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly freshnessTierPolicy: "freshness tier policy";
@@ -8,17 +9,23 @@ export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly maxAge: "maximum cache age to accept (e.g. \"2h\", \"7d\", \"6m\")";
     readonly fetchStorage: "override where this result is cached (secrets always stored globally)";
     readonly importStorage: "override where this note is cached (secrets always stored globally)";
-    readonly fetchTopic: "main research topic for metadata";
-    readonly importTopic: "main topic for this research note";
+    readonly fetchTopic: "main research topic for metadata (max 200 chars)";
+    readonly importTopic: "main topic for this research note (max 200 chars)";
     readonly filterTopic: "exact topic (case-insensitive)";
-    readonly fetchTags: "taxonomic tags for this research (can be repeated)";
-    readonly importTags: "taxonomic tags (can be repeated)";
+    readonly fetchTags: "taxonomic tags for this research (can be repeated, max 100 chars each)";
+    readonly importTags: "taxonomic tags (can be repeated, max 100 chars each)";
     readonly filterTags: "tags to require (must match all)";
     readonly format: "output format";
     readonly readOnly: "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE";
+    readonly toon: "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json";
     readonly sourceUrlGlob: "source URL glob (case-insensitive, supports * wildcard)";
     readonly listArtifactType: "artifact type; section children are omitted from list - use inspect to see them";
     readonly pruneArtifactType: "artifact type to prune, including section children";
+    readonly listFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)";
+    readonly searchQuery: "keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set";
+    readonly searchMatchAny: "match any query term instead of requiring all of them (OR instead of AND)";
+    readonly searchArtifactType: "artifact type; section children are omitted from search - use inspect to see them";
+    readonly searchFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)";
 };
 /** One human-readable label/value pair for CLI stdout. */
 export type HumanField = readonly [label: string, value: string];
@@ -37,3 +44,17 @@ export declare function formatHumanField(label: string, value: string): string;
  * @returns Formatted lines in the same order.
  */
 export declare function formatHumanFields(fields: readonly HumanField[]): string[];
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export declare function formatResultRowHeader(index: number, topic: string | null, cacheKey: string): string;
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowTokens(tokenEstimate: TokenEstimate): string;
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowSourceUrls(sourceUrls: readonly string[]): string;

package/dist/lib/cli-presentation.js

@@ -1,4 +1,6 @@
 import { colors } from './color.js';
+import { MAX_TAG_LENGTH, MAX_TOPIC_LENGTH } from './research/metadata-flags.js';
+import { NO_TOPIC_LABEL, sanitizeForTerminal } from './text.js';
 const HUMAN_LABEL_WIDTH = 25;
 // Repeated verbatim across several flag descriptions; single-use wording lives inline below.
 const DURATION_EXAMPLES = 'e.g. "2h", "7d", "6m"';
@@ -13,17 +15,23 @@ export const CLI_FLAG_DESCRIPTIONS = {
     maxAge: `maximum cache age to accept (${DURATION_EXAMPLES})`,
     fetchStorage: `override where this result is cached (${SECRET_STORAGE_NOTE})`,
     importStorage: `override where this note is cached (${SECRET_STORAGE_NOTE})`,
-    fetchTopic: 'main research topic for metadata',
-    importTopic: 'main topic for this research note',
+    fetchTopic: `main research topic for metadata (max ${MAX_TOPIC_LENGTH} chars)`,
+    importTopic: `main topic for this research note (max ${MAX_TOPIC_LENGTH} chars)`,
     filterTopic: 'exact topic (case-insensitive)',
-    fetchTags: 'taxonomic tags for this research (can be repeated)',
-    importTags: 'taxonomic tags (can be repeated)',
+    fetchTags: `taxonomic tags for this research (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
+    importTags: `taxonomic tags (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
     filterTags: 'tags to require (must match all)',
     format: 'output format',
     readOnly: '(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE',
+    toon: 'emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json',
     sourceUrlGlob: 'source URL glob (case-insensitive, supports * wildcard)',
     listArtifactType: 'artifact type; section children are omitted from list - use inspect to see them',
     pruneArtifactType: 'artifact type to prune, including section children',
+    listFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)',
+    searchQuery: 'keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set',
+    searchMatchAny: 'match any query term instead of requiring all of them (OR instead of AND)',
+    searchArtifactType: 'artifact type; section children are omitted from search - use inspect to see them',
+    searchFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)',
 };
 function formatHumanLabel(label) {
     const text = `${label}:`;
@@ -48,3 +56,25 @@ export function formatHumanField(label, value) {
 export function formatHumanFields(fields) {
     return fields.map(([label, value]) => formatHumanField(label, value));
 }
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export function formatResultRowHeader(index, topic, cacheKey) {
+    const topicStr = topic ? colors.cyan(sanitizeForTerminal(topic)) : colors.gray(NO_TOPIC_LABEL);
+    const keyStr = colors.bold(cacheKey);
+    return `${index + 1}. [${topicStr}] Key: ${keyStr}`;
+}
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowTokens(tokenEstimate) {
+    return `   Tokens: compressed=${colors.bold(String(tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(tokenEstimate?.detailed || 0))}`;
+}
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowSourceUrls(sourceUrls) {
+    return `   Source URLs: ${colors.gray(sourceUrls.join(', '))}\n`;
+}

package/dist/lib/cli-result-types.d.ts

@@ -1,5 +1,6 @@
 /** Shared machine-facing write/result shapes for CLI JSON envelopes. */
 import type { ArtifactType, CaptureMethod, ResearchArtifactMetadata, TokenEstimate } from './research/schema.js';
+import type { SearchMatchField } from './research/search-match.js';
 /** Result of `config set` / `config unset` for the JSON envelope. */
 export interface ConfigWriteResult {
     key: string;
@@ -33,7 +34,7 @@ export type CacheHitStatus = 'hit' | 'miss' | 'stale' | 'refreshed' | 'revalidat
 export type FreshnessState = 'fresh' | 'stale_grace' | 'stale_expired' | 'none';
 /** Freshness values that appear on list rows (an entry always exists). */
 export type ListFreshness = Exclude<FreshnessState, 'none'>;
-/** One row in `list --json` output. */
+/** One row in `list --json` output when `--full` is passed. */
 export interface ListRow {
     cacheKey: string;
     path: string;
@@ -48,6 +49,60 @@ export interface ListRow {
     fetchedAt: string | null;
     validatedAt: string | null;
 }
+/**
+ * Default `list --json`/`--toon` row: the fields an agent needs to judge relevance and act next
+ * (fetch/inspect the source, gauge freshness, budget tokens) without the full metadata dump.
+ * Pass `--full` for every field on {@link ListRow}.
+ */
+export interface ListRowMinimal {
+    sourceUrls: string[];
+    topic: string | null;
+    freshness: ListFreshness;
+    tokenEstimate: TokenEstimate;
+}
+/** Aggregate counts attached to `list`'s envelope so agents skip extra round trips. */
+export interface ListSummary {
+    /** Entries matching the given filters, before `--limit` truncation. */
+    total: number;
+    /** Entries actually returned in `data` (after `--limit`). */
+    shown: number;
+    limit: number;
+    /** True when `total > shown`, i.e. more entries matched than `--limit` allowed through. */
+    truncated: boolean;
+    /** Explicit signal for `total === 0`, so an empty `data: []` is never ambiguous. */
+    empty: boolean;
+    byFreshness: Record<ListFreshness, number>;
+    /**
+     * A copy-pasteable next invocation that reproduces the caller's own filters with a raised
+     * `--limit`, so a truncated result never leaves an agent to guess the syntax for "show me more."
+     * `null` when `truncated` is false.
+     */
+    nextCommand: string | null;
+}
+/** One row in `search --json` output when `--full` is passed. */
+export interface SearchRow extends ListRow {
+    /** Relevance score (0 when `--query` was omitted); see `search-match.ts` for the weighting. */
+    score: number;
+    /** Fields the query matched against; empty when `--query` was omitted. */
+    matchedFields: SearchMatchField[];
+    /** Excerpt around the first content match, or `null` when only topic/tags matched (or no query). */
+    snippet: string | null;
+}
+/**
+ * Default `search --json`/`--toon` row: enough to judge relevance (score, which fields matched, a
+ * short content excerpt) without the full metadata dump. Pass `--full` for every field on
+ * {@link SearchRow}.
+ */
+export interface SearchRowMinimal extends ListRowMinimal {
+    score: number;
+    matchedFields: SearchMatchField[];
+    snippet: string | null;
+}
+/** Aggregate counts attached to `search`'s envelope so agents skip extra round trips. */
+export interface SearchSummary extends ListSummary {
+    /** Whether `--query` was passed; when false every row scores 0 and results are recency-sorted. */
+    queried: boolean;
+}
 /** Section child summary nested under an inspect hit. */
 export interface InspectSectionRow {
     cacheKey: string;
@@ -86,3 +141,31 @@ export interface StatusRow {
     freshness: FreshnessState;
     action: 'would_fetch' | 'would_revalidate' | 'would_return_cached';
 }
+/** One entry in the `context` dashboard's recency-ordered preview. */
+export interface ContextDashboardEntry {
+    topic: string | null;
+    sourceUrls: string[];
+    freshness: ListFreshness;
+}
+/**
+ * Directory-scoped cache summary for `context` (AXI principle 7: ambient session-start context).
+ * `entries` is capped to a small preview; `total`/`byFreshness` always cover every matched
+ * artifact so the cap never hides the true count.
+ */
+export interface ContextDashboard {
+    total: number;
+    byFreshness: Record<ListFreshness, number>;
+    shown: number;
+    entries: ContextDashboardEntry[];
+}
+/** Agents `setup` knows how to install a SessionStart hook for. */
+export type SetupAgent = 'claude-code' | 'codex';
+/** Result of `setup <agent>` for the JSON envelope. */
+export interface SetupResult {
+    agent: SetupAgent;
+    scope: 'user' | 'project';
+    path: string;
+    binCommand: string;
+    status: 'installed' | 'repaired' | 'unchanged' | 'would_install' | 'would_repair';
+    dryRun: boolean;
+}

package/dist/lib/color.d.ts

@@ -18,3 +18,5 @@ export declare const colors: {
     gray: (t: string) => string;
     magenta: (t: string) => string;
 };
+/** Shared fresh/stale_grace/stale_expired → color mapping for `list` and `context`'s human output. */
+export declare const FRESHNESS_COLOR: Record<'fresh' | 'stale_grace' | 'stale_expired', (t: string) => string>;

package/dist/lib/color.js

@@ -34,3 +34,9 @@ export const colors = {
     gray: (t) => color(t, '\x1b[90m'),
     magenta: (t) => color(t, '\x1b[35m'),
 };
+/** Shared fresh/stale_grace/stale_expired → color mapping for `list` and `context`'s human output. */
+export const FRESHNESS_COLOR = {
+    fresh: colors.green,
+    stale_grace: colors.yellow,
+    stale_expired: colors.red,
+};

package/dist/lib/common-metadata-filter-flags.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Metadata filter flags shared by `list` and `search` (topic/tags/url/freshness/artifact
+ * type/capture method) — single source of truth so the two commands' flag definitions can never
+ * drift apart. `artifactTypeDescription` is the one piece that differs: each command names itself
+ * in its own `--artifact-type` help text (`list`/`search` currently, via `CLI_FLAG_DESCRIPTIONS`).
+ */
+export declare function commonMetadataFilterFlags(artifactTypeDescription: string): {
+    topic: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    tags: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    freshness: import("@oclif/core/interfaces").OptionFlag<"fresh" | "stale_grace" | "stale_expired" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | "route_markdown" | "github_source" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};

package/dist/lib/common-metadata-filter-flags.js

@@ -0,0 +1,37 @@
+import { Flags } from '@oclif/core';
+import { CLI_FLAG_DESCRIPTIONS } from './cli-presentation.js';
+import { CAPTURE_METHODS, PAGE_LEVEL_ARTIFACT_TYPES } from './research/schema.js';
+/**
+ * Metadata filter flags shared by `list` and `search` (topic/tags/url/freshness/artifact
+ * type/capture method) — single source of truth so the two commands' flag definitions can never
+ * drift apart. `artifactTypeDescription` is the one piece that differs: each command names itself
+ * in its own `--artifact-type` help text (`list`/`search` currently, via `CLI_FLAG_DESCRIPTIONS`).
+ */
+export function commonMetadataFilterFlags(artifactTypeDescription) {
+    return {
+        topic: Flags.string({
+            char: 't',
+            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: CLI_FLAG_DESCRIPTIONS.filterTags,
+            multiple: true,
+        }),
+        url: Flags.string({
+            description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
+        }),
+        freshness: Flags.option({
+            description: 'freshness state',
+            options: ['fresh', 'stale_grace', 'stale_expired'],
+        })(),
+        'artifact-type': Flags.option({
+            description: artifactTypeDescription,
+            options: PAGE_LEVEL_ARTIFACT_TYPES,
+        })(),
+        'capture-method': Flags.option({
+            description: 'capture method',
+            options: CAPTURE_METHODS,
+        })(),
+    };
+}

package/dist/lib/config/index.d.ts

@@ -1,5 +1,5 @@
-export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, type ResolveReadOnlyInput, } from './resolve.js';
 import { type ConfigKey, type ConfigValues, type ResolvedConfig, type StorageMode, type SummaryLevel } from './schema.js';
 /**

package/dist/lib/config/index.js

@@ -1,5 +1,5 @@
-export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
 import { parseEnvStorage, parseEnvSummary, resolveStorageMode, resolveSummaryLevel, } from './resolve.js';

package/dist/lib/config/io.d.ts

@@ -4,5 +4,14 @@ export declare const USER_CONFIG_FILENAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAME = ".bonsai.json";
 export declare function readUserConfig(configDir: string | undefined): Partial<ConfigValues>;
 export declare function readProjectConfig(cwd: string): Partial<ConfigValues>;
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export declare function invalidConfigFileWarnings(configDir: string | undefined, cwd: string, bin: string): string[];
 export declare function writeUserConfig(configDir: string, patch: Partial<ConfigValues>): void;
 export declare function writeProjectConfig(cwd: string, patch: Partial<ConfigValues>): void;

package/dist/lib/config/io.js

@@ -5,43 +5,93 @@ import { KEY_META, ALL_KEYS } from './schema.js';
 /** Global, user-level config lives in the OCLIF config dir; project config sits at the repo root. */
 export const USER_CONFIG_FILENAME = 'config.json';
 export const PROJECT_CONFIG_FILENAME = '.bonsai.json';
-/** Parse a config file, keeping only known keys with valid values. Invalid input degrades to {}. */
-function parseConfigFile(raw) {
+/**
+ * Parse a config file, keeping only known keys with valid values. Unparseable JSON, a non-object
+ * top level, or an invalid value for a known key degrades that part to "absent" rather than
+ * throwing — callers that only need values (`readUserConfig`/`readProjectConfig`) ignore
+ * `warnings`; {@link invalidConfigFileWarnings} surfaces them so the degradation is never silent.
+ */
+function parseConfigFile(filePath, raw, scopeFlag, bin) {
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-            return {};
-        const obj = parsed;
-        const result = {};
-        for (const key of ALL_KEYS) {
-            const val = obj[key];
-            if (val !== undefined && KEY_META[key].isValid(val)) {
-                Object.assign(result, { [key]: val });
-            }
-        }
-        return result;
+        parsed = JSON.parse(raw);
     }
     catch {
-        return {};
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: not valid JSON. Using the configured value or default instead. ` +
+                    `Fix the file by hand, or overwrite it with ${bin} config set <key> <value> ${scopeFlag}.`,
+            ],
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: expected a JSON object at the top level. Using the configured value or default instead.`,
+            ],
+        };
+    }
+    const obj = parsed;
+    const values = {};
+    const warnings = [];
+    for (const key of ALL_KEYS) {
+        const val = obj[key];
+        if (val === undefined)
+            continue;
+        if (KEY_META[key].isValid(val)) {
+            Object.assign(values, { [key]: val });
+        }
+        else {
+            const validValues = KEY_META[key].values;
+            const validValuesHint = validValues ? ` Valid values: ${validValues.join(', ')}.` : '';
+            warnings.push(`Ignoring "${key}" in ${filePath}: invalid value ${JSON.stringify(val)}.${validValuesHint} ` +
+                `Using the configured value or default instead.`);
+        }
     }
+    return { values, warnings };
 }
-function readConfigFile(filePath) {
+// Only the "fix it" suggestion in a warning message names the binary; every value-only caller
+// below (readUserConfig/readProjectConfig, and transitively write*Config) discards warnings
+// entirely, so this default never reaches a user — it's a placeholder for an unused code path,
+// not a claim about the real bin name. invalidConfigFileWarnings passes the real `this.config.bin`.
+const DEFAULT_BIN = 'bonsai';
+function readConfigFile(filePath, scopeFlag, bin = DEFAULT_BIN) {
     if (!existsSync(filePath))
-        return {};
+        return { values: {}, warnings: [] };
+    let raw;
     try {
-        return parseConfigFile(readFileSync(filePath, 'utf-8'));
+        raw = readFileSync(filePath, 'utf-8');
     }
     catch {
-        return {};
+        return { values: {}, warnings: [] };
     }
+    return parseConfigFile(filePath, raw, scopeFlag, bin);
 }
 export function readUserConfig(configDir) {
     if (!configDir)
         return {};
-    return readConfigFile(join(configDir, USER_CONFIG_FILENAME));
+    return readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global').values;
 }
 export function readProjectConfig(cwd) {
-    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME));
+    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local').values;
+}
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export function invalidConfigFileWarnings(configDir, cwd, bin) {
+    const warnings = [];
+    if (configDir) {
+        warnings.push(...readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global', bin).warnings);
+    }
+    warnings.push(...readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local', bin).warnings);
+    return warnings;
 }
 function writeAtomically(filePath, data) {
     atomicWriteFile(filePath, JSON.stringify(data, null, 2) + '\n');

package/dist/lib/config/schema.d.ts

@@ -29,3 +29,5 @@ export declare function isKnownKey(key: string): key is ConfigKey;
 export declare function suggestKey(input: string): ConfigKey | undefined;
 /** Comma-joined valid key list for error messages, kept in one place. */
 export declare function validKeysHint(): string;
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export declare function keyValuesHint(): string;

package/dist/lib/config/schema.js

@@ -40,3 +40,10 @@ export function suggestKey(input) {
 export function validKeysHint() {
     return ALL_KEYS.join(', ');
 }
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export function keyValuesHint() {
+    return ALL_KEYS.map((key) => {
+        const { values } = KEY_META[key];
+        return values ? `${key} (${values.join('|')})` : key;
+    }).join(', ');
+}

package/dist/lib/envelope.js

@@ -1,4 +1,5 @@
 import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+import { pluralize } from './text.js';
 /** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
 export function stableErrorCodeFrom(err) {
     const e = err;
@@ -117,8 +118,9 @@ export function enrichCacheMissEnvelope(envelope, data, bin) {
         exitCode: EXIT_RUNTIME_FAILURE,
         message: (first, failures) => {
             const url = first.normalizedUrl ?? '';
-            return failures.length > 1
-                ? `Cache miss for ${url} and ${failures.length - 1} other URLs`
+            const otherCount = failures.length - 1;
+            return otherCount > 0
+                ? `Cache miss for ${url} and ${otherCount} other ${pluralize(otherCount, 'URL', 'URLs')}`
                 : `Cache miss for ${url}`;
         },
         // A URL that is already a secondary source of a different cached artifact must not be pointed
@@ -141,8 +143,13 @@ export function enrichRowErrorEnvelope(envelope, data) {
             return row.error ?? null;
         },
         code: (first) => first.code ?? 'FETCH_FAILED',
-        message: (first, failures) => (first.message ?? '') +
-            (failures.length > 1 ? `\n…and ${failures.length - 1} other URL failure(s)` : ''),
+        message: (first, failures) => {
+            const otherCount = failures.length - 1;
+            const suffix = otherCount > 0
+                ? `\n…and ${otherCount} other URL ${pluralize(otherCount, 'failure', 'failures')}`
+                : '';
+            return (first.message ?? '') + suffix;
+        },
         suggestions: (failures) => failures[0]?.suggestions,
         ref: (first) => first.ref,
         exitCode: EXIT_RUNTIME_FAILURE,

package/dist/lib/next-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds a suggested next CLI invocation for a truncated `list`/`search` result — a copy-pasteable
+ * command that reproduces the caller's own filters with a raised `--limit`, so the caller never has
+ * to guess the syntax for "show me more." Surfaced as `summary.nextCommand` in the JSON/TOON
+ * envelope and as a human-mode tip.
+ */
+/**
+ * @param bin - The CLI's own binary name (`this.config.bin`).
+ * @param commandId - The command to suggest (`list` or `search`).
+ * @param argv - The current invocation's raw argv (`this.argv`), reused as-is so the suggestion can
+ *   never drift from whatever filters/flags the caller actually passed.
+ * @param newLimit - The `--limit` value to suggest.
+ * @returns A copy-pasteable shell command string.
+ */
+export declare function buildNextLimitCommand(bin: string, commandId: string, argv: readonly string[], newLimit: number): string;

package/dist/lib/next-command.js

@@ -0,0 +1,40 @@
+/**
+ * Builds a suggested next CLI invocation for a truncated `list`/`search` result — a copy-pasteable
+ * command that reproduces the caller's own filters with a raised `--limit`, so the caller never has
+ * to guess the syntax for "show me more." Surfaced as `summary.nextCommand` in the JSON/TOON
+ * envelope and as a human-mode tip.
+ */
+// Never valid to suggest back to a caller: `--limit` is being replaced by the new value, and
+// `--identity` is a hidden, undocumented flag only ever injected by the bare-invocation argv
+// rewrite (see argv.ts) — carrying it into a suggested command would leak an internal detail.
+const DROPPED_FLAGS = new Set(['--limit', '--identity']);
+// Tokens made only of these characters are safe to print bare in a shell command; anything else
+// (spaces, quotes, glob patterns like `*`) is double-quoted so the suggestion stays copy-pasteable.
+const SAFE_BARE_TOKEN = /^[A-Za-z0-9_@%+.:,/-]+$/;
+function quoteShellArgIfNeeded(token) {
+    if (SAFE_BARE_TOKEN.test(token))
+        return token;
+    return `"${token.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+/**
+ * @param bin - The CLI's own binary name (`this.config.bin`).
+ * @param commandId - The command to suggest (`list` or `search`).
+ * @param argv - The current invocation's raw argv (`this.argv`), reused as-is so the suggestion can
+ *   never drift from whatever filters/flags the caller actually passed.
+ * @param newLimit - The `--limit` value to suggest.
+ * @returns A copy-pasteable shell command string.
+ */
+export function buildNextLimitCommand(bin, commandId, argv, newLimit) {
+    const kept = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--limit') {
+            i++; // also drop its value
+            continue;
+        }
+        if (token.startsWith('--limit=') || DROPPED_FLAGS.has(token))
+            continue;
+        kept.push(quoteShellArgIfNeeded(token));
+    }
+    return [bin, commandId, ...kept, '--limit', String(newLimit)].join(' ');
+}

package/dist/lib/prune-flags.d.ts

@@ -14,6 +14,8 @@ export interface PruneFlagInput {
     inactive?: string;
     artifactType?: string;
     url?: string;
+    topic?: string;
+    tags?: string[];
     dryRun: boolean;
     yes: boolean;
     readOnly: boolean;

package/dist/lib/prune-flags.js

@@ -1,16 +1,22 @@
 import { emptyUrlFilterError } from './research/url.js';
 import { durationFlagError } from './research/freshness.js';
+import { emptyTopicFilterError, emptyTagsFilterError } from './research/metadata-filters.js';
 function missingFilterError(input) {
     // Treat an explicitly passed empty string as "filter was attempted" so `--older-than ''`
     // is not misreported as MISSING_FILTER (durationError rejects it as INVALID_DURATION).
+    // `tags` is the one array-valued flag here: oclif never parses a bare `--tags` into `[]` (a
+    // multiple string flag requires a value per occurrence), so a non-empty array is the correct
+    // "was this filter attempted" test, mirroring the `!== undefined` check used for every scalar flag.
     if (input.olderThan !== undefined ||
         input.inactive !== undefined ||
         input.artifactType !== undefined ||
-        input.url !== undefined) {
+        input.url !== undefined ||
+        input.topic !== undefined ||
+        (input.tags?.length ?? 0) > 0) {
         return null;
     }
     return {
-        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, or --url.',
+        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, --url, --topic, or --tags.',
         code: 'MISSING_FILTER',
         suggestions: [`Preview age-based pruning: ${input.bin} prune --older-than 30d --dry-run`],
     };
@@ -41,10 +47,14 @@ function mutationSafetyError(input) {
     if (!input.readOnly && !input.dryRun && !input.yes) {
         const olderThanPart = input.olderThan ? ` --older-than ${input.olderThan}` : '';
         const urlPart = input.url ? ` --url "${input.url}"` : '';
+        const topicPart = input.topic ? ` --topic "${input.topic}"` : '';
+        const tagsPart = (input.tags ?? []).map((tag) => ` --tags "${tag}"`).join('');
         return {
             message: 'Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.',
             code: 'SAFETY_CHECK_REQUIRED',
-            suggestions: [`Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}`],
+            suggestions: [
+                `Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}${topicPart}${tagsPart}`,
+            ],
         };
     }
     return null;
@@ -66,9 +76,11 @@ function durationError(input) {
  * @returns Error descriptor for `this.error`, or `null`.
  */
 export function pruneFlagError(input) {
-    const urlErr = emptyUrlFilterError(input.url);
-    if (urlErr)
-        return { message: urlErr, code: 'INVALID_FLAG_VALUE' };
+    const flagValueErr = emptyUrlFilterError(input.url) ??
+        emptyTopicFilterError(input.topic) ??
+        emptyTagsFilterError(input.tags);
+    if (flagValueErr)
+        return { message: flagValueErr, code: 'INVALID_FLAG_VALUE' };
     // Duration before missing-filter so `--older-than ''` reports INVALID_DURATION, not MISSING_FILTER.
     return durationError(input) ?? missingFilterError(input) ?? mutationSafetyError(input);
 }

package/dist/lib/research/artifact-index.js

@@ -39,7 +39,13 @@ function getOrUpdateIndexEntry(filePath, cached, onChanged) {
         return cached;
     }
     try {
-        const entry = { sig, artifact: parseArtifactShallow(readFileSync(filePath, 'utf-8')) };
+        const artifact = parseArtifactShallow(readFileSync(filePath, 'utf-8'));
+        // Mirrors the same guard in storage.ts's scanCacheDir: parseArtifact never throws on a foreign
+        // or garbled *.md file that merely has `---`/`---` fences, it just defaults cache_key to ''. Treat
+        // that the same as a parse failure so it's skipped rather than indexed as a phantom entry.
+        if (!artifact.metadata.cache_key)
+            return undefined;
+        const entry = { sig, artifact };
         onChanged();
         return entry;
     }