@taurgis/bonsai 4.0.0 → 4.1.1

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;
@@ -71,6 +72,36 @@ export interface ListSummary {
     /** 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 {
@@ -110,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/{commands/config/base.d.ts → lib/config-command.d.ts}

@@ -1,9 +1,13 @@
 import { Command } from '@oclif/core';
-import { BaseCommand } from '../../base-command.js';
-import type { ConfigKey, ConfigScope } from '../../lib/config/index.js';
+import { BaseCommand } from '../base-command.js';
+import type { ConfigKey, ConfigScope } from './config/index.js';
+import { scopeFlags } from './scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
+ *
+ * Lives outside `src/commands` so oclif's file-based command discovery does not
+ * publish it as `config base`.
  */
 export declare abstract class ConfigCommand<T extends typeof Command> extends BaseCommand<T> {
     protected assertScopeFlagsExclusive(global?: boolean, local?: boolean): void;
@@ -16,10 +20,4 @@ export declare abstract class ConfigCommand<T extends typeof Command> extends Ba
     protected validateConfigKeyAndScope(key: string | undefined, global?: boolean, local?: boolean): asserts key is ConfigKey;
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
-export declare function configScopeFlags(descriptions: {
-    global: string;
-    local: string;
-}): {
-    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-};
+export declare const configScopeFlags: typeof scopeFlags;

package/dist/{commands/config/base.js → lib/config-command.js}

@@ -1,19 +1,17 @@
-import { Flags, toConfiguredId } from '@oclif/core';
-import { BaseCommand } from '../../base-command.js';
-import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
+import { toConfiguredId } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { isKnownKey, suggestKey, validKeysHint } from './config/index.js';
+import { assertScopeFlagsExclusive, scopeFlags } from './scope-flags.js';
 /**
  * Shared base for the four `config` subcommands: the mutually-exclusive
  * scope-flag guard, the binary write-scope helper, and known-key validation.
+ *
+ * Lives outside `src/commands` so oclif's file-based command discovery does not
+ * publish it as `config base`.
  */
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {
-        if (global && local) {
-            this.error('--global and --local are mutually exclusive.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-                suggestions: ['Pass --global or --local, not both.'],
-            });
-        }
+        assertScopeFlagsExclusive(this.error.bind(this), global, local);
     }
     /** `--local` writes/reads the project file; otherwise the user-level file. */
     writeScope(local) {
@@ -58,13 +56,4 @@ export class ConfigCommand extends BaseCommand {
     }
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
-export function configScopeFlags(descriptions) {
-    return {
-        global: Flags.boolean({ char: 'g', description: descriptions.global }),
-        local: Flags.boolean({
-            description: descriptions.local,
-            aliases: ['project'],
-            charAliases: ['p'],
-        }),
-    };
-}
+export const configScopeFlags = scopeFlags;

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/research/context-dashboard.d.ts

@@ -0,0 +1,19 @@
+import type { ContextDashboard } from '../cli-result-types.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export declare const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export declare function buildContextDashboard(readRoots: string[], currentTime: Date, options?: {
+    limit?: number;
+    persistIndex?: boolean;
+}): ContextDashboard;

package/dist/lib/research/context-dashboard.js

@@ -0,0 +1,43 @@
+import { scanCacheDirs } from './storage.js';
+import { evaluateFreshness } from './freshness.js';
+/** Entries beyond this count are still counted in `total`/`byFreshness`, just not listed. */
+export const CONTEXT_DASHBOARD_DEFAULT_LIMIT = 5;
+/**
+ * Builds the directory-scoped cache summary shown by `bonsai context` and injected by the
+ * `setup`-installed SessionStart hooks (AXI principle 7: ambient session-start context). Reuses
+ * the same scan/freshness primitives as `list` so the two commands can never disagree about what
+ * "active" or "fresh" means; unlike `list`, this applies no filters and always includes every
+ * matched artifact in `total`/`byFreshness`, previewing only the most recent `limit` in `entries`.
+ *
+ * @param readRoots - Data dirs to scan, in lookup order (see {@link loadStoreRoots}).
+ * @param currentTime - Clock used for freshness evaluation.
+ * @param options.limit - Max entries to preview; the count itself is never truncated.
+ * @param options.persistIndex - Whether to persist the search-index sidecar (false under read-only).
+ */
+export function buildContextDashboard(readRoots, currentTime, options = {}) {
+    const limit = options.limit ?? CONTEXT_DASHBOARD_DEFAULT_LIMIT;
+    const rows = scanCacheDirs(readRoots, (artifact) => {
+        if (artifact.metadata.status !== 'active')
+            return null;
+        // Section children are sub-chunks of a page, not something a dashboard should list on its
+        // own — same exclusion `list` applies (see list.ts's scanCacheDirForList).
+        if (artifact.metadata.artifact_type === 'section')
+            return null;
+        return {
+            topic: artifact.metadata.topic,
+            sourceUrls: artifact.metadata.source_urls,
+            freshness: evaluateFreshness(artifact.metadata, currentTime, null),
+            recencyKey: artifact.metadata.validated_at ?? artifact.metadata.fetched_at ?? null,
+        };
+    }, { persistIndex: options.persistIndex ?? true });
+    rows.sort((a, b) => new Date(b.recencyKey ?? 0).getTime() - new Date(a.recencyKey ?? 0).getTime());
+    const byFreshness = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        byFreshness[row.freshness]++;
+    const entries = rows.slice(0, limit).map((row) => ({
+        topic: row.topic,
+        sourceUrls: row.sourceUrls,
+        freshness: row.freshness,
+    }));
+    return { total: rows.length, byFreshness, shown: entries.length, entries };
+}

package/dist/lib/research/fetch-command-service.js

@@ -343,6 +343,16 @@ function logHumanFetchResult(input) {
         io.warn(`${normalizedUrl}: ${warning}`);
     }
     io.log(resultData.content);
+    // AXI content-truncation: only nudge toward the escape hatch when something was actually
+    // condensed — `detailedTokenEstimate` equals `tokenEstimate` whenever `format` is already
+    // `detailed`, or when compression happened to produce no smaller result.
+    if (resultData.format === 'compressed' &&
+        typeof resultData.tokenEstimate === 'number' &&
+        typeof resultData.detailedTokenEstimate === 'number' &&
+        resultData.detailedTokenEstimate > resultData.tokenEstimate) {
+        io.warn(formatTip(`${io.bin} ${normalizedUrl} --format detailed for the full ${resultData.detailedTokenEstimate}-token ` +
+            `version (currently showing ${resultData.tokenEstimate}).`));
+    }
     if (!dryRun) {
         io.warn(formatTip(`${io.bin} inspect ${normalizedUrl} for cached metadata.`));
     }

package/dist/lib/research/fetch-result.d.ts

@@ -57,6 +57,7 @@ export declare function buildFetchResultData(input: FetchResultInput): {
     searchProvider: string | null;
     format: "compressed" | "detailed";
     tokenEstimate: number | null;
+    detailedTokenEstimate: number | null;
     content: string;
 };
 export interface FetchFailureGuidance {

package/dist/lib/research/fetch-result.js

@@ -75,6 +75,10 @@ export function buildFetchResultData(input) {
         tokenEstimate: format === 'compressed'
             ? artifact.metadata.token_estimate.compressed
             : artifact.metadata.token_estimate.detailed,
+        // Always the true detailed count, even when `format` is `compressed` (AXI content-truncation
+        // principle: show the total size so the agent knows how much a `--format detailed` re-fetch
+        // would add, without a second round trip). Equals `tokenEstimate` when nothing was truncated.
+        detailedTokenEstimate: artifact.metadata.token_estimate.detailed,
         content,
     };
 }

package/dist/lib/research/fetcher.d.ts

@@ -65,3 +65,14 @@ export declare function fetchStaticHtml(url: string, options?: FetchOptions): Pr
  * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
  */
 export declare function fetchText(url: string, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Same DNS, redirect, and status checks as {@link fetchText}, but the body is cancelled once the
+ * status line is known. Use this to reject HTTP 404 before a browser render without downloading
+ * the document.
+ *
+ * @param url - Absolute URL to probe.
+ * @param options - Optional timeout, redirect cap, and headers.
+ * @returns The final HTTP status.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
+ */
+export declare function fetchStatus(url: string, options?: FetchOptions): Promise<number>;

package/dist/lib/research/fetcher.js

@@ -264,3 +264,29 @@ export async function fetchStaticHtml(url, options = {}) {
 export async function fetchText(url, options = {}) {
     return fetchWithRedirects(url, options, processTextResponse);
 }
+/**
+ * Same DNS, redirect, and status checks as {@link fetchText}, but the body is cancelled once the
+ * status line is known. Use this to reject HTTP 404 before a browser render without downloading
+ * the document.
+ *
+ * @param url - Absolute URL to probe.
+ * @param options - Optional timeout, redirect cap, and headers.
+ * @returns The final HTTP status.
+ * @throws {Error} On unsafe DNS, HTTP failure, or redirect limits.
+ */
+export async function fetchStatus(url, options = {}) {
+    const result = await fetchWithRedirects(url, options, async (res, _limit, currentUrl) => {
+        await res.body?.cancel().catch(() => { });
+        assertOk(res);
+        return {
+            status: res.status,
+            contentType: null,
+            etag: null,
+            lastModified: null,
+            finalUrl: currentUrl,
+            responseSize: 0,
+            content: '',
+        };
+    });
+    return result.status;
+}

package/dist/lib/research/list-row.d.ts

@@ -0,0 +1,15 @@
+import type { ListFreshness, ListRow } from '../cli-result-types.js';
+import type { ResearchArtifact } from './schema.js';
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export declare function toListRow(artifact: ResearchArtifact, filePath: string, freshness: ListRow['freshness']): ListRow;
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export declare function countByFreshness(rows: readonly {
+    freshness: ListFreshness;
+}[]): Record<ListFreshness, number>;

package/dist/lib/research/list-row.js

@@ -0,0 +1,31 @@
+/**
+ * Maps a parsed artifact to the shared page-level row shape (`ListRow`) that `list` and `search`
+ * both return — single source of truth so the two commands' JSON row schemas can never drift on
+ * which metadata fields a "row" exposes.
+ */
+export function toListRow(artifact, filePath, freshness) {
+    return {
+        cacheKey: artifact.metadata.cache_key,
+        path: filePath,
+        artifactType: artifact.metadata.artifact_type,
+        sourceUrls: artifact.metadata.source_urls,
+        topic: artifact.metadata.topic,
+        tags: artifact.metadata.tags,
+        freshness,
+        captureMethod: artifact.metadata.capture_method,
+        tokenEstimate: artifact.metadata.token_estimate,
+        qualityNotes: artifact.metadata.quality_notes,
+        fetchedAt: artifact.metadata.fetched_at,
+        validatedAt: artifact.metadata.validated_at,
+    };
+}
+/**
+ * Counts rows per freshness tier for the `list`/`search` envelope's `summary.byFreshness` — single
+ * source of truth so the two commands' aggregate always agree on the shape and the counting logic.
+ */
+export function countByFreshness(rows) {
+    const counts = { fresh: 0, stale_grace: 0, stale_expired: 0 };
+    for (const row of rows)
+        counts[row.freshness]++;
+    return counts;
+}

package/dist/lib/research/metadata-filters.d.ts

@@ -1,4 +1,4 @@
-import type { ResearchArtifactMetadata } from './schema.js';
+import type { ArtifactType, CaptureMethod, ResearchArtifactMetadata } from './schema.js';
 /** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
 export declare function matchesTopicFilter(meta: Pick<ResearchArtifactMetadata, 'topic'>, topic: string | undefined): boolean;
 /** Whether an artifact's tags satisfy a `--tags` filter (case-insensitive, must match all). */
@@ -16,3 +16,24 @@ export declare function emptyTopicFilterError(topic: string | undefined): string
  * matches any artifact's tags — silently returning zero results with no signal. Fail fast instead.
  */
 export declare function emptyTagsFilterError(tags: string[] | undefined): string | undefined;
+/** The metadata filter flags `list` and `search` both expose, beyond content/topic search. */
+export interface CommonMetadataFilterFlags {
+    topic?: string;
+    tags?: string[];
+    url?: string;
+    artifactType?: ArtifactType;
+    captureMethod?: CaptureMethod;
+    freshness?: 'fresh' | 'stale_grace' | 'stale_expired';
+}
+/**
+ * Shared page-level metadata filter combinator for `list` and `search` (topic/tags/url/artifact
+ * type/capture method/freshness) — single source of truth so the two commands can never drift on
+ * what "matches the given filters" means.
+ */
+export declare function matchesCommonMetadataFilters(meta: ResearchArtifactMetadata, freshness: 'fresh' | 'stale_grace' | 'stale_expired', flags: CommonMetadataFilterFlags): boolean;
+/**
+ * Whether any of the shared metadata filter flags was passed — used to pick empty-result guidance
+ * ("no matches for your filters" vs. "the cache is empty"). `search` combines this with its own
+ * `--query` check; `list` has no filters beyond these, so it uses the result directly.
+ */
+export declare function hasActiveMetadataFilters(flags: CommonMetadataFilterFlags): boolean;

package/dist/lib/research/metadata-filters.js

@@ -1,3 +1,4 @@
+import { artifactMatchesUrlFilter } from './url.js';
 /** Whether an artifact's topic matches a `--topic` filter (case-insensitive exact match). */
 export function matchesTopicFilter(meta, topic) {
     if (!topic)
@@ -35,3 +36,36 @@ export function emptyTagsFilterError(tags) {
         return undefined;
     return '--tags must be non-empty values (e.g. "react").';
 }
+/**
+ * Shared page-level metadata filter combinator for `list` and `search` (topic/tags/url/artifact
+ * type/capture method/freshness) — single source of truth so the two commands can never drift on
+ * what "matches the given filters" means.
+ */
+export function matchesCommonMetadataFilters(meta, freshness, flags) {
+    if (!matchesTopicFilter(meta, flags.topic))
+        return false;
+    if (!matchesTagsFilter(meta, flags.tags))
+        return false;
+    if (flags.url && !artifactMatchesUrlFilter(meta, flags.url))
+        return false;
+    if (flags.artifactType && meta.artifact_type !== flags.artifactType)
+        return false;
+    if (flags.captureMethod && meta.capture_method !== flags.captureMethod)
+        return false;
+    if (flags.freshness && freshness !== flags.freshness)
+        return false;
+    return true;
+}
+/**
+ * Whether any of the shared metadata filter flags was passed — used to pick empty-result guidance
+ * ("no matches for your filters" vs. "the cache is empty"). `search` combines this with its own
+ * `--query` check; `list` has no filters beyond these, so it uses the result directly.
+ */
+export function hasActiveMetadataFilters(flags) {
+    return Boolean(flags.topic ||
+        (flags.tags && flags.tags.length > 0) ||
+        flags.freshness ||
+        flags.artifactType ||
+        flags.captureMethod ||
+        flags.url);
+}

package/dist/lib/research/regression.js

@@ -117,7 +117,12 @@ const LEAKAGE_PATTERNS = [
     { label: 'base64-image', re: /data:image\/[a-z]+;base64,/i },
     { label: 'skip-to-content', re: /skip to (?:main )?content/i },
     { label: 'on-this-page', re: /^on this page$/im },
-    { label: 'theme-toggle', re: /(?:toggle|switch to) (?:dark|light|the)? ?(?:mode|theme)/i },
+    // "dark"/"light" or the word "theme" is required. An optional group also matched
+    // "switch to mode" after inline code was stripped from "switch to `history` mode".
+    {
+        label: 'theme-toggle',
+        re: /(?:toggle|switch to) (?:the )?(?:dark|light)(?: mode)?|(?:toggle|switch to) (?:the )?theme/i,
+    },
     {
         label: 'cookie-consent',
         re: /(?:accept all cookies|we use cookies|cookie (?:policy|preferences|settings))/i,

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

@@ -11,6 +11,8 @@ export type CaptureMethod = (typeof CAPTURE_METHODS)[number];
 export declare const ARTIFACT_TYPES: readonly ["source", "research_note", "index", "section"];
 /** Classification of a research artifact's role. */
 export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export declare const PAGE_LEVEL_ARTIFACT_TYPES: ("source" | "research_note" | "index")[];
 /** Full metadata block stored alongside every cached research artifact. */
 export interface ResearchArtifactMetadata {
     schema_version: number;

package/dist/lib/research/schema.js

@@ -12,3 +12,7 @@ export const CAPTURE_METHODS = [
 // index; `section` = a heading-level child of a page. Command flag `options` derive from this.
 /** All recognized artifact types. `index` = navigation hub or llms.txt; `section` = heading-level child of a page. */
 export const ARTIFACT_TYPES = ['source', 'research_note', 'index', 'section'];
+// Shared by `list` and `search`: both report pages, never the `section` chunks a page is split
+// into (a single fetch can yield dozens) — `inspect` is where a page's sections are discoverable.
+/** Artifact types `list`/`search` report: every type except the heading-level `section` child. */
+export const PAGE_LEVEL_ARTIFACT_TYPES = ARTIFACT_TYPES.filter((type) => type !== 'section');

package/dist/lib/research/search-match.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** A field a query term can match against, in priority order (most to least specific). */
+export type SearchMatchField = 'topic' | 'tags' | 'summary' | 'compressed';
+/** Fields of an artifact that `search --query` matches against. */
+export interface SearchableFields {
+    topic: string | null;
+    tags: string[];
+    summary: string;
+    compressed: string;
+}
+/** Result of scoring one artifact against a tokenized query. */
+export interface SearchMatch {
+    score: number;
+    matchedFields: SearchMatchField[];
+}
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export declare function tokenizeSearchQuery(query: string): string[];
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export declare function emptySearchQueryError(query: string | undefined): string | undefined;
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export declare function scoreSearchMatch(fields: SearchableFields, terms: readonly string[], matchAny: boolean): SearchMatch | null;
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export declare function extractSearchSnippet(fields: Pick<SearchableFields, 'summary' | 'compressed'>, terms: readonly string[]): string | null;