@taurgis/bonsai 3.2.2 → 4.1.0

package/dist/base-command.js

@@ -1,11 +1,25 @@
-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 { colors } from './lib/color.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 +40,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 +60,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 +117,43 @@ 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));
+    }
+    /**
+     * Human-mode tip for a truncated `list`/`search` result: the copy-pasteable command that raises
+     * `--limit` (see `next-command.ts`). A no-op when nothing was truncated (`nextCommand` is `null`).
+     */
+    tipNextCommand(nextCommand) {
+        if (nextCommand)
+            this.tip(`see the rest: ${colors.cyan(nextCommand)}`);
+    }
     /** 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 +204,7 @@ export class BaseCommand extends Command {
                 configDir: this.config.configDir,
                 cwd: process.cwd(),
                 dataDir: this.config.dataDir,
+                readOnly: this.readOnly,
                 url,
                 ...extra,
             });
@@ -131,6 +228,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 +285,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.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import type { ConfigKey, ConfigScope } from '../../lib/config/index.js';
+import { scopeFlags } from '../../lib/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.
@@ -16,10 +17,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

@@ -1,18 +1,14 @@
-import { Flags, toConfiguredId } from '@oclif/core';
+import { toConfiguredId } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
+import { assertScopeFlagsExclusive, scopeFlags } from '../../lib/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.
  */
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {
-        if (global && local) {
-            this.error('--global and --local are mutually exclusive.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-            });
-        }
+        assertScopeFlagsExclusive(this.error.bind(this), global, local);
     }
     /** `--local` writes/reads the project file; otherwise the user-level file. */
     writeScope(local) {
@@ -57,13 +53,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/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/context.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../base-command.js';
+import type { ContextDashboard } from '../lib/cli-result-types.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand<typeof Context> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static stdoutIsPrimaryData: boolean;
+    private logDashboard;
+    run(): Promise<ContextDashboard>;
+}

package/dist/commands/context.js

@@ -0,0 +1,65 @@
+import { BaseCommand } from '../base-command.js';
+import { loadStoreRoots } from '../lib/research/store-roots.js';
+import { buildContextDashboard } from '../lib/research/context-dashboard.js';
+import { NO_TOPIC_LABEL, formatTip, pluralize, sanitizeForTerminal } from '../lib/text.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+/**
+ * Compact, directory-scoped cache summary (AXI principle 7: ambient session-start context).
+ * Plain-text human output is deliberately short — it's meant to be piped verbatim into a
+ * SessionStart hook's `additionalContext` by `bonsai setup`, so every line here is also a
+ * reasonable thing for an agent to read unprompted at the start of a session.
+ */
+export default class Context extends BaseCommand {
+    static id = 'context';
+    static summary = 'Show a compact cache dashboard for ambient session context';
+    static description = 'Print a short summary of the current research cache: total entries, a freshness ' +
+        'breakdown, and the most recently touched pages. This is what `bonsai setup` wires into a ' +
+        "SessionStart hook, so a session starts with the cache's state already visible.";
+    static examples = [
+        {
+            description: 'preview what a SessionStart hook would show',
+            command: '<%= config.bin %> context',
+        },
+        {
+            description: 'get the dashboard as JSON',
+            command: '<%= config.bin %> context --json',
+        },
+    ];
+    static stdoutIsPrimaryData = true;
+    logDashboard(dashboard) {
+        if (this.jsonEnabled())
+            return;
+        if (dashboard.total === 0) {
+            this.log(`${this.config.bin} cache: 0 entries found.`);
+            this.log(formatTip(`populate the cache: ${colors.cyan(`${this.config.bin} <url>`)}`));
+            return;
+        }
+        const { fresh, stale_grace: staleGrace, stale_expired: staleExpired } = dashboard.byFreshness;
+        this.log(`${this.config.bin} cache: ${dashboard.total} ${pluralize(dashboard.total, 'entry', 'entries')} ` +
+            `(${fresh} fresh, ${staleGrace} stale_grace, ${staleExpired} stale_expired)`);
+        for (const entry of dashboard.entries) {
+            const topicStr = entry.topic
+                ? colors.cyan(sanitizeForTerminal(entry.topic))
+                : colors.gray(NO_TOPIC_LABEL);
+            const freshnessStr = FRESHNESS_COLOR[entry.freshness](entry.freshness);
+            const url = entry.sourceUrls[0] ?? '';
+            this.log(`- [${topicStr}] ${freshnessStr} — ${colors.gray(url)}`);
+        }
+        if (dashboard.total > dashboard.shown) {
+            this.log(formatTip(`see all ${dashboard.total} entries: ${colors.cyan(`${this.config.bin} list`)}`));
+        }
+        this.log(formatTip(`research a new page: ${colors.cyan(`${this.config.bin} <url>`)}`));
+    }
+    async run() {
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const dashboard = buildContextDashboard(roots.readRoots, new Date(), {
+            persistIndex: !this.readOnly,
+        });
+        this.logDashboard(dashboard);
+        return dashboard;
+    }
+}

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,38 +1,50 @@
 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;
     }[];
     static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        identity: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;
-        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    private matchesTopic;
-    private matchesTags;
+    /** The shared filter flags as `matchesCommonMetadataFilters`/`hasActiveMetadataFilters` expect them. */
+    private metadataFilterFlags;
     private matchesFilters;
     private scanCacheDirForList;
-    private hasActiveFilters;
+    /**
+     * Identity header for the AXI "home view" (bare `bonsai`, no args): the tool's own bin path and
+     * one-sentence description, shown before the live data so an agent orients on what it's looking
+     * at without a separate `--help` round trip. Human mode only — the hidden `--identity` flag is
+     * only ever set by the argv rewrite for a bare invocation; it is not documented for direct use.
+     */
+    private logIdentityHeader;
     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>;
 }