@taurgis/bonsai 3.2.2 → 4.0.0

package/README.md

@@ -141,7 +141,7 @@ npx @taurgis/bonsai inspect <url>
 
 ### `list`
 
-List cached artifacts by metadata filters (`--topic`, `--tags`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content.
+List cached artifacts by metadata filters (`--topic`, `--tags`, `--url`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content. The default `--json`/`--toon` row is a minimal 4-field shape (`sourceUrls`, `topic`, `freshness`, `tokenEstimate`); pass `--full` for every metadata field. Running `bonsai` with no arguments at all is shorthand for `bonsai list`.
 
 ```bash
 npx @taurgis/bonsai list [flags]
@@ -149,7 +149,7 @@ npx @taurgis/bonsai list [flags]
 
 ### `prune`
 
-Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, or `--url`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
+Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, `--url`, `--topic`, or `--tags`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
 
 ```bash
 npx @taurgis/bonsai prune --older-than 90d --dry-run

package/agents/agents/salesforce-docs-researcher.agent.md

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What Salesforce topic should I research in official docs?'
 metadata:
-  version: '2.1.0'
+  version: '2.2.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -20,7 +20,7 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 
 ## Invocation
 
-Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
+Run Bonsai as `npx @taurgis/bonsai ...`. Add `--toon` when you need structured output at a lower token cost; `--json` is also available if you specifically need JSON (mutually exclusive with `--toon`).
 
 If you are operating in a read-only/plan mode (no filesystem writes allowed), add `--read-only` (alias `--plan`) to every Bonsai call, or export `BONSAI_READ_ONLY=1` (or `BONSAI_PLAN_MODE=1`) once for the session — fetches still run, but nothing is persisted to the local cache or config. See "Read-only / Plan Mode" below.
 
@@ -45,7 +45,7 @@ If you are operating in a read-only/plan mode (no filesystem writes allowed), ad
 For structured output:
 
 ```bash
-npx @taurgis/bonsai <official-url> --format detailed --json
+npx @taurgis/bonsai <official-url> --format detailed --toon
 ```
 
 ## Working with Salesforce Sites
@@ -109,4 +109,4 @@ Return:
 - Cache status or validation timestamp when Bonsai output provides it.
 - Gaps or uncertainty where official docs do not answer the question.
 
-Keep stdout clean when using `--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.
+Keep stdout clean when using `--toon`/`--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.

package/bin/cli.mjs

@@ -7,7 +7,7 @@ import updateNotifier from 'update-notifier';
 import { createRequire } from 'node:module';
 
 import { normalizeArgv } from '../dist/lib/argv.js';
-import { VALUE_TAKING_FLAG_TOKENS } from '../dist/lib/cli-flag-manifest.js';
+import { VALUE_TAKING_FLAG_TOKENS, KNOWN_COMMAND_ROOT_TOKENS } from '../dist/lib/cli-flag-manifest.js';
 import { exitWithPreflight } from '../dist/lib/cli-emit.js';
 import { tryUnknownHelpOutput } from '../dist/lib/help-preflight.js';
 import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
@@ -23,7 +23,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
 // process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
-const result = normalizeArgv(rawArgv, { valueTakingFlags: VALUE_TAKING_FLAG_TOKENS });
+const result = normalizeArgv(rawArgv, {
+  valueTakingFlags: VALUE_TAKING_FLAG_TOKENS,
+  knownCommandRoots: KNOWN_COMMAND_ROOT_TOKENS,
+});
 const root = __dirname + '/../';
 
 if (result.earlyExit) {
@@ -41,8 +44,8 @@ if (jsonMeta) {
 }
 
 // Only notify after the earlyExit fast-path so the notifier never fires before
-// a usage-error envelope exits. Also skip under --json so agent callers never see stderr noise.
-if (!process.argv.includes('--json')) {
+// a usage-error envelope exits. Also skip under --json/--toon so agent callers never see stderr noise.
+if (!process.argv.includes('--json') && !process.argv.includes('--toon')) {
   updateNotifier({ pkg }).notify();
 }
 

package/dist/base-command.d.ts

@@ -17,11 +17,24 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      */
     static baseFlags: {
         'read-only': Interfaces.BooleanFlag<boolean>;
+        toon: Interfaces.BooleanFlag<boolean>;
     };
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
     parsedArgv: string[];
     init(): Promise<void>;
+    /**
+     * Treat `--toon` as machine mode too, so every existing `!this.jsonEnabled()` human-output branch
+     * across every command (table rendering, tips, empty-state guidance) is suppressed under `--toon`
+     * for free, exactly as it already is under `--json`.
+     */
+    jsonEnabled(): boolean;
+    /**
+     * Real `--json` keeps oclif's own colorized-JSON rendering untouched (zero regression risk).
+     * `--toon` (and no real `--json`) re-encodes the identical envelope as TOON instead — same data,
+     * ~40% fewer tokens for callers who opted in.
+     */
+    protected logJson(json: unknown): void;
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
      * but our warnings (secret-redirect, stale-serve, prune failures) are
@@ -29,6 +42,30 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /**
+     * Sanitize the human-readable error surface before handing off to oclif. Error text throughout
+     * this CLI routinely echoes raw user input back (a rejected URL, `--ttl`, an unknown config key)
+     * so the message stays actionable, but that value is untrusted per the repo's trust-boundary
+     * rules — the same reasoning that already strips ANSI/control bytes from cached content before
+     * terminal render (see `sanitizeForTerminal`). Left unsanitized, a value containing raw escape
+     * bytes would replay as a terminal-injection attack the moment the rejected command's own error
+     * is printed. `--json` is untouched: `JSON.stringify` already escapes control characters, and the
+     * raw value there preserves exact input for programmatic callers.
+     */
+    error(input: string | Error, options: {
+        code?: string;
+        exit: false;
+    } & Errors.PrettyPrintableError): void;
+    error(input: string | Error, options?: {
+        code?: string;
+        exit?: number;
+    } & Errors.PrettyPrintableError): never;
+    /**
+     * Human-mode-only contextual next-step suggestion after a successful command, mirroring the
+     * "Try this:" pattern already used on errors. A no-op under `--json`/`--toon`: the envelope's
+     * `data` is self-describing, so machine callers get no prose.
+     */
+    protected tip(message: string): void;
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     protected get readOnly(): boolean;
     /**

package/dist/base-command.js

@@ -1,11 +1,24 @@
-import { Command, Errors, Flags, toConfiguredId } from '@oclif/core';
-import { invalidEnvOverrideWarnings, resolveReadOnly } from './lib/config/index.js';
+import { Command, Errors, Flags, toConfiguredId, ux } from '@oclif/core';
+import { encode } from '@toon-format/toon';
+import { invalidConfigFileWarnings, invalidEnvOverrideWarnings, resolveReadOnly, } from './lib/config/index.js';
 import { CLI_FLAG_DESCRIPTIONS } from './lib/cli-presentation.js';
+import { formatTip, sanitizeForTerminal } from './lib/text.js';
 import { enrichErrorForDisplay, resolveExitCode, prepareCliError, EXIT_OK, EXIT_STALE_SERVED, } from './lib/cli-error-policy.js';
-import { buildEnvelope, enrichCacheMissEnvelope, enrichRowErrorEnvelope, formatErrorForJson, } from './lib/envelope.js';
+import { buildEnvelope, enrichCacheMissEnvelope, enrichRowErrorEnvelope } from './lib/envelope.js';
 import { enrichParseError } from './lib/parse-error-ux.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
 import { failInvalidUrl } from './lib/research/cli-io.js';
+/**
+ * Mirrors oclif's own `--json` argv-scan (respecting a `--` pass-through boundary) so `--toon`
+ * gets identical treatment: present in argv, regardless of parse state.
+ */
+function argvHasFlag(argv, flag) {
+    const passThroughIndex = argv.indexOf('--');
+    const flagIndex = argv.indexOf(flag);
+    return passThroughIndex === -1
+        ? flagIndex !== -1
+        : flagIndex !== -1 && flagIndex < passThroughIndex;
+}
 /**
  * Shared base for every Bonsai command. Enables oclif's native `--json` flag,
  * parses args/flags once in `init()` so commands read `this.args`/`this.flags`
@@ -26,6 +39,10 @@ export class BaseCommand extends Command {
             default: false,
             description: CLI_FLAG_DESCRIPTIONS.readOnly,
         }),
+        toon: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.toon,
+        }),
     };
     flags;
     args;
@@ -42,11 +59,52 @@ export class BaseCommand extends Command {
         this.flags = flags;
         this.args = args;
         this.parsedArgv = argv;
+        // --json and --toon both claim the machine-output seat; picking one silently over the other
+        // would surprise a caller who set both by mistake, so reject the combination outright. Reuses
+        // the existing CONFLICTING_FLAGS code (not a new one) — the catalog already documents it as the
+        // one code for "choose one of the mutually exclusive options", regardless of which flags.
+        if (this.flags?.['json'] && this.flags?.['toon']) {
+            this.error('Cannot combine --json and --toon: pick one output format.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+                suggestions: ['Pass only one of --json or --toon'],
+            });
+        }
         // Surface a set-but-invalid BONSAI_* override once per run. Resolution silently drops such a
         // value, so without this a typo'd env var would take no effect with no signal. Warnings go to
         // stderr (even under --json), so machine output stays clean.
         for (const warning of invalidEnvOverrideWarnings(process.env))
             this.warn(warning);
+        // Same signal for a corrupted or hand-edited config file: parsing silently degrades to `{}`
+        // (or drops just the offending key), which would otherwise mask the problem entirely.
+        for (const warning of invalidConfigFileWarnings(this.config.configDir, process.cwd(), this.config.bin)) {
+            this.warn(warning);
+        }
+    }
+    /**
+     * Treat `--toon` as machine mode too, so every existing `!this.jsonEnabled()` human-output branch
+     * across every command (table rendering, tips, empty-state guidance) is suppressed under `--toon`
+     * for free, exactly as it already is under `--json`.
+     */
+    jsonEnabled() {
+        // Mirrors oclif's own enableJsonFlag guard (every command in this CLI sets it, but the base
+        // class's contract shouldn't silently break if a future command ever opts out).
+        return (super.jsonEnabled() ||
+            (Boolean(this.ctor?.enableJsonFlag) && argvHasFlag(this.argv, '--toon')));
+    }
+    /**
+     * Real `--json` keeps oclif's own colorized-JSON rendering untouched (zero regression risk).
+     * `--toon` (and no real `--json`) re-encodes the identical envelope as TOON instead — same data,
+     * ~40% fewer tokens for callers who opted in.
+     */
+    logJson(json) {
+        if (super.jsonEnabled()) {
+            super.logJson(json);
+            return;
+        }
+        // this.log() no-ops whenever jsonEnabled() is true (by design, everywhere else in this CLI) —
+        // ux.stdout writes directly, matching how oclif's own default logJson bypasses that guard too.
+        ux.stdout(encode(json));
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
@@ -58,6 +116,35 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    error(input, options = {}) {
+        if (!this.jsonEnabled()) {
+            if (typeof input === 'string')
+                input = sanitizeForTerminal(input);
+            if (options.suggestions) {
+                options = { ...options, suggestions: options.suggestions.map(sanitizeForTerminal) };
+            }
+        }
+        // `exit: false` is oclif's non-throwing error render (see `errorRow` on the CliIo port and
+        // `mapUrlsAllowingBatchErrors`/prune's per-row failures, all of which route through here for the
+        // same terminal-injection sanitization above). Destructure `exit` into its own binding so
+        // narrowing it to the `false` literal actually narrows the object passed to `super.error()` into
+        // each of oclif's two overloads — narrowing a property read alone (`options.exit === false`)
+        // doesn't narrow the enclosing object's type, only a local variable's.
+        const { exit, ...rest } = options;
+        if (exit === false)
+            return super.error(input, { ...rest, exit });
+        return super.error(input, { ...rest, exit });
+    }
+    /**
+     * Human-mode-only contextual next-step suggestion after a successful command, mirroring the
+     * "Try this:" pattern already used on errors. A no-op under `--json`/`--toon`: the envelope's
+     * `data` is self-describing, so machine callers get no prose.
+     */
+    tip(message) {
+        if (this.jsonEnabled())
+            return;
+        this.warn(formatTip(message));
+    }
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     get readOnly() {
         return resolveReadOnly({ flag: Boolean(this.flags?.['read-only']), env: process.env });
@@ -108,6 +195,7 @@ export class BaseCommand extends Command {
                 configDir: this.config.configDir,
                 cwd: process.cwd(),
                 dataDir: this.config.dataDir,
+                readOnly: this.readOnly,
                 url,
                 ...extra,
             });
@@ -131,6 +219,7 @@ export class BaseCommand extends Command {
             warn: (msg) => void this.warn(msg),
             log: (msg) => this.log(msg),
             error: (msg, opts) => this.error(msg, opts),
+            errorRow: (msg, opts) => this.error(msg, { ...opts, exit: false }),
         };
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
@@ -187,10 +276,12 @@ export class BaseCommand extends Command {
             catch (err) {
                 if (!batch || !(err instanceof Errors.CLIError))
                     throw err;
-                // Mirror the single-URL error format (message + Code: + Try this:) rather than a bare
-                // message, so a row failure in a batch is exactly as actionable as it is standalone.
+                // Render with the same "Error:" formatting as a single-URL failure (this.error's exit:false
+                // form prints the CLIError's own message/Code/Try this and returns instead of throwing) rather
+                // than this.warn, since a row failure still fails the command overall (status/inspect batch
+                // exit code, JSON ok:false) and should never read as merely a warning.
                 if (!this.jsonEnabled())
-                    this.warn(formatErrorForJson(err));
+                    this.error(err, { exit: false });
                 results.push(failureRow(url, err));
             }
         }

package/dist/commands/config/base.js

@@ -11,6 +11,7 @@ export class ConfigCommand extends BaseCommand {
             this.error('--global and --local are mutually exclusive.', {
                 exit: 2,
                 code: 'CONFLICTING_FLAGS',
+                suggestions: ['Pass --global or --local, not both.'],
             });
         }
     }

package/dist/commands/config/get.js

@@ -1,10 +1,10 @@
 import { Args } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { formatConfigEntry, resolveConfigEntry, validKeysHint } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntry, keyValuesHint } from '../../lib/config/index.js';
 export default class ConfigGet extends ConfigCommand {
     static id = 'config get';
     static summary = 'Get a research configuration value';
-    static description = `Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. \`fetch --storage\`) > env var > project file > user file > built-in default.\n\nValid keys: ${validKeysHint()}.`;
+    static description = `Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. \`fetch --storage\`) > env var > project file > user file > built-in default.\n\nValid keys: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'get the effective storage mode',

package/dist/commands/config/list.js

@@ -1,9 +1,9 @@
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { formatConfigEntry, resolveConfigEntries, validKeysHint } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntries, keyValuesHint } from '../../lib/config/index.js';
 export default class ConfigList extends ConfigCommand {
     static id = 'config list';
     static summary = 'List research configuration values';
-    static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${validKeysHint()}.`;
+    static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'show all effective config values',

package/dist/commands/config/set.js

@@ -1,12 +1,12 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, validKeysHint } from '../../lib/config/index.js';
+import { KEY_META, keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigSet extends ConfigCommand {
     static id = 'config set';
     static summary = 'Set a research configuration key';
     static description = 'Persist a configuration value. Writes user-level config by default; pass --local for project-level config (.bonsai.json in cwd).\n\n' +
-        `Valid keys: ${validKeysHint()}. The inline form \`<key>=<value>\` is also accepted.`;
+        `Valid keys: ${keyValuesHint()}. The inline form \`<key>=<value>\` is also accepted.`;
     static examples = [
         {
             description: 'store research cache in the current project',

package/dist/commands/config/unset.js

@@ -1,11 +1,11 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { validKeysHint } from '../../lib/config/index.js';
+import { keyValuesHint } from '../../lib/config/index.js';
 import { persistConfigPatch } from '../../lib/config-persist.js';
 export default class ConfigUnset extends ConfigCommand {
     static id = 'config unset';
     static summary = 'Remove a research configuration key';
-    static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${validKeysHint()}.`;
+    static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'remove the user-level storage setting',

package/dist/commands/fetch.js

@@ -18,6 +18,10 @@ export default class FetchCommand extends BaseCommand {
             description: 'cache a volatile page with compressed JSON output',
             command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
         },
+        {
+            description: 'fetch multiple URLs in one batch (space-separated)',
+            command: '<%= config.bin %> https://docs.nestjs.com/ https://docs.nestjs.com/first-steps',
+        },
     ];
     static strict = false;
     static args = {

package/dist/commands/inspect.js

@@ -6,6 +6,7 @@ import { getArtifactPath, scanCacheDirs } from '../lib/research/storage.js';
 import { artifactMatchesUrlFilter } from '../lib/research/url.js';
 import { colors } from '../lib/color.js';
 import { formatHumanField } from '../lib/cli-presentation.js';
+import { sanitizeForTerminal } from '../lib/text.js';
 /** Inspect a cached artifact and its section children. */
 export default class ResearchInspect extends BaseCommand {
     static id = 'inspect';
@@ -20,6 +21,10 @@ export default class ResearchInspect extends BaseCommand {
             description: 'inspect cached metadata as JSON',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
         },
+        {
+            description: 'inspect multiple URLs in one batch (space-separated)',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api',
+        },
     ];
     static strict = false;
     static args = {
@@ -110,6 +115,7 @@ export default class ResearchInspect extends BaseCommand {
             this.logMetadata(cached.metadata);
             if (sections.length)
                 this.logSections(sections);
+            this.tip(`${this.config.bin} status ${normalizedUrl} to check freshness.`);
             const sep = batchSeparator(this.parsedArgv.length > 1);
             if (sep)
                 this.log(sep);
@@ -130,14 +136,17 @@ export default class ResearchInspect extends BaseCommand {
                 this.log(formatHumanField(key, colors.bold(JSON.stringify(val))));
             }
             else {
-                this.log(formatHumanField(key, colors.bold(String(val))));
+                const display = typeof val === 'string' ? sanitizeForTerminal(val) : String(val);
+                this.log(formatHumanField(key, colors.bold(display)));
             }
         }
     }
     logSections(sections) {
         this.log(colors.cyan(`--- Sections (${sections.length}) ---`));
         for (const s of sections) {
-            this.log(`${colors.cyan(s.headingPath || '')} [${colors.yellow(s.anchor || '')}] (${colors.magenta(String(s.tokenEstimate.detailed || 0))} tokens) ${colors.gray(s.cacheKey)}`);
+            const headingPath = sanitizeForTerminal(s.headingPath || '');
+            const anchor = sanitizeForTerminal(s.anchor || '');
+            this.log(`${colors.cyan(headingPath)} [${colors.yellow(anchor)}] (${colors.magenta(String(s.tokenEstimate.detailed || 0))} tokens) ${colors.gray(s.cacheKey)}`);
         }
     }
     // Section children link back via parent_cache_key; list the active ones for this page (T-22).

package/dist/commands/list.d.ts

@@ -1,15 +1,16 @@
 import { BaseCommand } from '../base-command.js';
-import type { ListRow } from '../lib/cli-result-types.js';
+import type { ListRow, ListRowMinimal } from '../lib/cli-result-types.js';
 /** List cached research artifacts by metadata filters. */
 export default class ResearchList extends BaseCommand<typeof ResearchList> {
     static id: string;
     static summary: string;
     static description: string;
     /**
-     * When `--json` results were capped by `--limit`, attached to the success envelope so agents can
-     * detect truncation without scraping prose (#91 / AUDIT_71_FINAL #73 deferred).
+     * Aggregate counts (and an explicit empty/truncation signal) attached to the success envelope so
+     * agents get a cache-wide summary without a separate round trip (AXI principles: pre-computed
+     * aggregates, definitive empty states). Always set by `run()` before it returns.
      */
-    private jsonTruncation;
+    private jsonSummary;
     static examples: {
         description: string;
         command: string;
@@ -22,17 +23,19 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         '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>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    private matchesTopic;
-    private matchesTags;
     private matchesFilters;
     private scanCacheDirForList;
     private hasActiveFilters;
     private logListResults;
-    /** Empty-cache / no-match tip (human mode only; --json returns `data: []` with no messaging). */
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
     private emitEmptyListGuidance;
-    run(): Promise<ListRow[]>;
-    /** Attach `truncation` when the returned `data` array was capped by `--limit`. */
+    run(): Promise<ListRow[] | ListRowMinimal[]>;
+    /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */
     protected toSuccessJson(data: unknown): Record<string, unknown>;
 }