@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/commands/import.js

@@ -1,38 +1,28 @@
-import { Args, Errors, Flags } from '@oclif/core';
-import { createHash } from 'node:crypto';
+import { Args, Flags } from '@oclif/core';
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { BaseCommand } from '../base-command.js';
-import { normalizeUrl } from '../lib/research/url.js';
-import { deriveCacheKey } from '../lib/research/cache-key.js';
-import { getArtifactPath } from '../lib/research/storage.js';
-import { loadStoreRoots } from '../lib/research/store-roots.js';
-import { writeArtifactSecurely } from '../lib/research/secure-write.js';
-import { loadSummaryLevel } from '../lib/config/index.js';
-import { durationFlagError, getPolicy } from '../lib/research/freshness.js';
-import { buildCompressed } from '../lib/research/compress.js';
-import { sanitizePromptInjection } from '../lib/research/prompt-injection.js';
-import { applyAutoTags } from '../lib/research/keywords.js';
-import { estimateTokens } from '../lib/research/token-estimate.js';
+import { finishImportCommandService, prepareImportCommandService, } from '../lib/research/import-command-service.js';
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+/** Import research notes from a file or stdin. */
 export default class ResearchImport extends BaseCommand {
     static id = 'import';
-    static summary = 'Import agent-supplied clean Markdown notes into the local cache.';
-    static description = 'Accepts a synthesized Markdown note via stdin and registers it under the single target URL or multiple source URLs.';
+    static summary = 'Import agent-supplied Markdown into cache';
+    static description = 'Store supplied Markdown under one URL or a multi-source research note, using the same freshness and storage metadata as fetched pages.';
     static examples = [
         {
-            description: 'import detailed research for a single URL via stdin',
-            command: 'echo "# My Article" | <%= config.bin %> import https://example.com/docs --stdin',
+            description: 'import detailed research for one URL from stdin',
+            command: 'printf "# My Article\\n" | <%= config.bin %> import https://example.com/docs --stdin --ttl 7d',
         },
         {
-            description: 'import research synthesized from multiple source URLs',
+            description: 'import a research note synthesized from multiple source URLs',
             command: 'echo "# Synthesized" | <%= config.bin %> import --stdin --topic "React docs" --source-url https://react.dev/a --source-url https://react.dev/b',
         },
         {
-            description: 'import research from a local Markdown file',
+            description: 'import research from a Markdown file',
             command: '<%= config.bin %> import https://example.com/docs --file path/to/notes.md',
         },
         {
-            description: 'import research from stdin using the standard file placeholder',
+            description: 'import research from stdin with the file placeholder',
             command: 'cat notes.md | <%= config.bin %> import https://example.com/docs --file -',
         },
     ];
@@ -43,7 +33,7 @@ export default class ResearchImport extends BaseCommand {
             // this, the Markdown piped for `--stdin` is swallowed into `url`, making multi-source import
             // (`import --stdin --source-url ...`) wrongly look like it also got a positional URL.
             ignoreStdin: true,
-            description: 'the single source URL of the page (only for single-source import)',
+            description: 'single source URL for single-source import',
         }),
     };
     static flags = {
@@ -52,37 +42,42 @@ export default class ResearchImport extends BaseCommand {
             default: false,
         }),
         file: Flags.string({
-            description: 'path to a Markdown file containing research notes to import, or "-" for stdin',
+            char: 'f',
+            description: 'Markdown file to import, or "-" for stdin',
         }),
         'input-format': Flags.option({
-            description: 'format of the input provided',
+            description: 'input content format',
             options: ['compressed', 'detailed'],
             default: 'detailed',
         })(),
         topic: Flags.string({
             char: 't',
-            description: 'the main topic for this research note',
+            description: CLI_FLAG_DESCRIPTIONS.importTopic,
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'taxonomic tags (can be repeated)',
+            description: CLI_FLAG_DESCRIPTIONS.importTags,
             multiple: true,
         }),
         tier: Flags.option({
-            description: 'freshness tier policy',
+            description: CLI_FLAG_DESCRIPTIONS.freshnessTierPolicy,
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         'source-url': Flags.string({
-            description: 'repeated source URLs for multi-source import',
+            description: 'source URLs for multi-source import (can be repeated)',
             multiple: true,
         }),
         ttl: Flags.string({
             char: 'l',
-            description: 'predicted lifespan of the data (e.g. "24h", "7d")',
+            description: CLI_FLAG_DESCRIPTIONS.importTtl,
+        }),
+        'dry-run': Flags.boolean({
+            description: 'validate import without writing cache',
+            default: false,
         }),
         storage: Flags.option({
-            description: 'override where this note is cached (secrets always stored globally)',
+            description: CLI_FLAG_DESCRIPTIONS.importStorage,
             options: ['global', 'project'],
         })(),
     };
@@ -92,7 +87,8 @@ export default class ResearchImport extends BaseCommand {
     stdinIsInteractive() {
         return process.stdin.isTTY === true;
     }
-    async readStdin(limitBytes = 1024 * 1024) {
+    // The byte limit is owned by the import service (INPUT_LIMIT_BYTES) and always passed in.
+    async readStdin(limitBytes) {
         return new Promise((resolve, reject) => {
             let data = '';
             let bytesRead = 0;
@@ -119,49 +115,6 @@ export default class ResearchImport extends BaseCommand {
             });
         });
     }
-    getSourceUrls(hasMulti, multiUrls, singleUrl) {
-        const urls = hasMulti ? multiUrls : singleUrl ? [singleUrl] : [];
-        const normalized = urls.map((u) => {
-            try {
-                return normalizeUrl(u);
-            }
-            catch (err) {
-                // Shared exit point: a forgotten scheme reports MISSING_URL_SCHEME like every other command,
-                // while genuinely malformed input stays INVALID_URL.
-                this.failInvalidUrl(u, err.message);
-            }
-        });
-        return hasMulti ? normalized.sort() : normalized;
-    }
-    validateSourceMode(hasSingle, hasMulti, multiUrls) {
-        if (hasSingle && hasMulti) {
-            this.error('Cannot specify both positional <url> and --source-url flags.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-            });
-        }
-        if (!hasSingle && !hasMulti) {
-            this.error('Must specify either positional <url> (for single-source) or --source-url (for multi-source) import.', { exit: 2, code: 'MISSING_URL' });
-        }
-        if (hasMulti && !this.flags.topic) {
-            this.error('Multi-source import requires the --topic flag.', {
-                exit: 2,
-                code: 'MISSING_TOPIC',
-            });
-        }
-        if (!this.flags.stdin && !this.flags.file) {
-            this.error('Either --stdin or --file <path> must be specified to import content.', {
-                exit: 2,
-                code: 'MISSING_INPUT',
-            });
-        }
-        if (this.flags.stdin && this.flags.file) {
-            this.error('Cannot specify both --stdin and --file <path>. Choose one.', {
-                exit: 2,
-                code: 'CONFLICTING_FLAGS',
-            });
-        }
-    }
     fsExistsSync(filePath) {
         return fs.existsSync(filePath);
     }
@@ -171,220 +124,39 @@ export default class ResearchImport extends BaseCommand {
     fsReadFileSync(filePath) {
         return fs.readFileSync(filePath, 'utf8');
     }
-    stdinImportSuggestions() {
-        const bin = this.config.bin;
-        return [
-            `Pipe Markdown content, e.g. cat notes.md | ${bin} import <url> --stdin`,
-            `Or use the standard stdin placeholder: cat notes.md | ${bin} import <url> --file -`,
-            `Or read from a file: ${bin} import <url> --file notes.md`,
-        ];
-    }
-    /** Non-interactive stdin that never receives data (open pipe with no writer) must not hang forever. */
-    async readStdinWithGuard(limitBytes = 1024 * 1024) {
-        if (this.stdinIsInteractive()) {
-            this.error('No data piped to --stdin.', {
-                exit: 2,
-                code: 'MISSING_STDIN',
-                suggestions: this.stdinImportSuggestions(),
-            });
-        }
-        const timeoutMs = 1000;
-        let rawInput = '';
-        try {
-            rawInput = await Promise.race([
-                this.readStdin(limitBytes),
-                new Promise((_, reject) => setTimeout(() => reject(new Error('STDIN_TIMEOUT')), timeoutMs)),
-            ]);
-        }
-        catch (err) {
-            if (err.message === 'STDIN_TIMEOUT') {
-                this.error('No stdin data received. Pipe content or use --file.', {
-                    exit: 2,
-                    code: 'MISSING_STDIN',
-                    suggestions: this.stdinImportSuggestions(),
-                });
-            }
-            if (err.message.includes('stdin size limit exceeded')) {
-                this.error(err.message, { exit: 1, code: 'STDIN_TOO_LARGE' });
-            }
-            // Genuine stream failure reading stdin → I/O failure (exit 1).
-            this.error(err.message, { exit: 1, code: 'IO_ERROR' });
-        }
-        return rawInput;
-    }
-    readAndValidateFile(filePath) {
-        if (!this.fsExistsSync(filePath)) {
-            this.error(`File does not exist: ${filePath}`, { exit: 2, code: 'FILE_NOT_FOUND' });
-        }
-        const stat = this.fsStatSync(filePath);
-        if (!stat.isFile()) {
-            this.error(`Path is not a file: ${filePath}`, { exit: 2, code: 'NOT_A_FILE' });
-        }
-        if (stat.size > 1024 * 1024) {
-            this.error('File size limit exceeded (max 1 MiB).', { exit: 1, code: 'FILE_TOO_LARGE' });
-        }
-        const content = this.fsReadFileSync(filePath);
-        if (!content.trim()) {
-            this.error('Empty file content provided.', { exit: 2, code: 'EMPTY_INPUT' });
-        }
-        return content;
-    }
-    async readAndValidateInput() {
-        const fileReadsStdin = this.flags.file === '-';
-        if (this.flags.stdin || fileReadsStdin) {
-            const rawInput = await this.readStdinWithGuard();
-            if (!rawInput.trim()) {
-                this.error('Empty stdin content provided.', { exit: 2, code: 'EMPTY_INPUT' });
-            }
-            return rawInput;
-        }
-        if (this.flags.file) {
-            const filePath = path.resolve(this.flags.file);
-            try {
-                return this.readAndValidateFile(filePath);
-            }
-            catch (err) {
-                // readAndValidateFile raises usage errors (missing/not-a-file/empty) via this.error,
-                // which throw CLIErrors carrying their own exit code and message — preserve those.
-                // Only an unexpected read failure becomes a wrapped I/O failure (exit 1).
-                if (err instanceof Errors.CLIError)
-                    throw err;
-                this.error(`Failed to read file: ${err.message}`, { exit: 1, code: 'IO_ERROR' });
-            }
-        }
-        this.error('No input source specified.', { exit: 2, code: 'MISSING_INPUT' });
-    }
-    deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls) {
-        if (hasSingle) {
-            return deriveCacheKey(singleNormalizedUrl);
-        }
-        const normalizedTopic = this.flags.topic.trim().toLowerCase();
-        const combinedString = [normalizedTopic, ...sourceUrls].join('|');
-        return createHash('sha256').update(combinedString).digest('hex');
+    serviceArgs() {
+        return { url: this.args.url };
     }
-    buildImportArtifact(hasSingle, singleNormalizedUrl, sourceUrls, cacheKey, rawInput) {
-        const currentTime = new Date();
-        const tier = this.flags.tier;
-        const ttl = this.flags.ttl || null;
-        const { freshWindowMs } = getPolicy(tier, ttl);
-        const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
-        const inputFormat = this.flags['input-format'];
-        const detailed = sanitizePromptInjection(rawInput);
-        // A caller-supplied compressed input is trusted as-is; only a detailed import is condensed here,
-        // and it shares the same buildCompressed policy (structural pass + extractive fallback) as fetch.
-        const compressed = inputFormat === 'detailed'
-            ? buildCompressed(detailed, loadSummaryLevel(this.config.configDir, process.cwd()))
-            : rawInput;
-        const contentHash = createHash('sha256').update(detailed).digest('hex');
-        const metadata = {
-            schema_version: 1,
-            artifact_type: hasSingle ? 'source' : 'research_note',
-            source_url: hasSingle ? this.args.url : '',
-            source_urls: sourceUrls,
-            normalized_url: singleNormalizedUrl,
-            cache_key: cacheKey,
-            topic: this.flags.topic || null,
-            tags: this.flags.tags || [],
-            format_available: ['compressed', 'detailed'],
-            tier,
-            ttl,
-            fetched_at: null,
-            validated_at: currentTime.toISOString(),
-            stale_after: staleAfterTime.toISOString(),
-            capture_method: 'agent_supplied',
-            extraction_status: 'agent_supplied',
-            extraction_confidence: 'high',
-            quality_notes: ['agent-supplied research import'],
-            supplied_at: currentTime.toISOString(),
-            supplied_by: null,
-            etag: null,
-            last_modified: null,
-            content_hash: contentHash,
-            token_estimate: {
-                compressed: estimateTokens(compressed),
-                detailed: estimateTokens(detailed),
-            },
-            status: 'active',
-            site_module_id: null,
-            docs_engine: null,
-            docs_framework: null,
-            source_doc_url: null,
-            search_provider: null,
-            parent_cache_key: null,
-            section_anchor: null,
-            section_heading_path: null,
+    serviceFlags() {
+        return {
+            stdin: this.flags.stdin,
+            file: this.flags.file,
+            inputFormat: this.flags['input-format'],
+            topic: this.flags.topic,
+            tags: this.flags.tags,
+            tier: this.flags.tier,
+            sourceUrls: this.flags['source-url'] || [],
+            ttl: this.flags.ttl,
+            storage: this.flags.storage,
         };
-        // Auto-tag from the content when the caller supplied none, so imported notes stay searchable by
-        // keyword without forcing manual tagging. Explicit --tags always win (handled in applyAutoTags).
-        return applyAutoTags({
-            metadata,
-            summary: `Synthesized research for ${hasSingle ? singleNormalizedUrl : this.flags.topic}`,
-            compressed,
-            detailed,
-            provenance: `Imported via agent-supplied research at ${currentTime.toISOString()}`,
-        });
     }
     async run() {
-        const hasSingle = Boolean(this.args.url);
-        const multiUrls = this.flags['source-url'] || [];
-        const hasMulti = multiUrls.length > 0;
-        const ttlErr = durationFlagError('--ttl', this.flags.ttl);
-        if (ttlErr)
-            this.error(ttlErr, { exit: 2, code: 'INVALID_DURATION' });
-        this.validateSourceMode(hasSingle, hasMulti, multiUrls);
-        const rawInput = await this.readAndValidateInput();
-        const sourceUrls = this.getSourceUrls(hasMulti, multiUrls, this.args.url);
-        const singleNormalizedUrl = hasSingle ? sourceUrls[0] || '' : '';
-        const cacheKey = this.deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls);
-        const artifact = this.buildImportArtifact(hasSingle, singleNormalizedUrl, sourceUrls, cacheKey, rawInput);
-        const roots = loadStoreRoots({
-            configDir: this.config.configDir,
-            cwd: process.cwd(),
-            dataDir: this.config.dataDir,
-            flagOverride: this.flags.storage,
-        });
-        const dryRun = this.effectiveDryRun(false);
-        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact, { dryRun });
-        const storagePath = getArtifactPath(writeResult.dataDir, cacheKey);
-        if (writeResult.redirected) {
-            this.warn(`Detected ${writeResult.secretLabel} in the imported content; stored in the global cache instead of the project to avoid committing secrets.`);
-        }
-        if (!this.jsonEnabled()) {
-            this.log(dryRun
-                ? `[dry-run] Would import research artifact.`
-                : `Successfully imported research artifact.`);
-            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
-            this.log(`${'Storage Path:'.padEnd(25)} ${storagePath}`);
-        }
-        const inputFormat = this.flags['input-format'];
-        return {
-            schemaVersion: 1,
-            command: 'import',
-            dryRun,
-            cache: {
-                key: cacheKey,
-                status: dryRun ? 'would_import' : 'imported',
-                freshness: 'fresh',
-                path: storagePath,
-                storage: roots.mode,
-                redirectedToGlobal: writeResult.redirected,
-            },
-            source: {
-                url: hasSingle ? this.args.url : '',
-                normalizedUrl: singleNormalizedUrl,
-                captureMethod: 'agent_supplied',
-                extractionStatus: 'agent_supplied',
-                extractionConfidence: 'high',
-                qualityNotes: artifact.metadata.quality_notes,
-                fetchedAt: null,
-                validatedAt: artifact.metadata.validated_at,
-                staleAfter: artifact.metadata.stale_after,
+        const args = this.serviceArgs();
+        const flags = this.serviceFlags();
+        const io = this.cliIo();
+        const prepared = await prepareImportCommandService({
+            args,
+            flags,
+            io,
+            input: {
+                stdinIsInteractive: () => this.stdinIsInteractive(),
+                readStdin: (limitBytes) => this.readStdin(limitBytes),
+                fsExistsSync: (filePath) => this.fsExistsSync(filePath),
+                fsStatSync: (filePath) => this.fsStatSync(filePath),
+                fsReadFileSync: (filePath) => this.fsReadFileSync(filePath),
             },
-            format: inputFormat,
-            tokenEstimate: inputFormat === 'compressed'
-                ? artifact.metadata.token_estimate.compressed
-                : artifact.metadata.token_estimate.detailed,
-            content: inputFormat === 'compressed' ? artifact.compressed : artifact.detailed,
-        };
+        });
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        return finishImportCommandService(prepared, dryRun, io);
     }
 }

package/dist/commands/inspect.d.ts

@@ -1,4 +1,5 @@
 import { BaseCommand } from '../base-command.js';
+/** Inspect a cached artifact and its section children. */
 export default class ResearchInspect extends BaseCommand<typeof ResearchInspect> {
     static id: string;
     static summary: string;
@@ -12,9 +13,14 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static stdoutIsPrimaryData: boolean;
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
     run(): Promise<unknown>;
+    private inspectOne;
+    private missResult;
+    private findExistingNoteContaining;
+    private missGuidance;
+    private hitResult;
     private logMetadata;
     private logSections;
-    private inspectSingleTarget;
     private findSections;
 }

package/dist/commands/inspect.js

@@ -1,18 +1,23 @@
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
-import { scanCacheDirs } from '../lib/research/storage.js';
+import { finalizeBatch, isBatchReadFailure, urlValidationErrorRow } from '../lib/batch.js';
+import { batchSeparator, cacheMissHint, formatCacheTargetHeader } from '../lib/cache-view.js';
+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';
+/** Inspect a cached artifact and its section children. */
 export default class ResearchInspect extends BaseCommand {
     static id = 'inspect';
-    static summary = 'Inspect cached research metadata for a URL.';
-    static description = 'Inspects local storage and displays full frontmatter metadata for the URL (without printing the content body).';
+    static summary = 'Inspect cached research metadata for a URL';
+    static description = 'Show frontmatter metadata and section children for cached URLs without printing content.';
     static examples = [
         {
-            description: 'inspect cached research metadata for a specific URL',
+            description: 'inspect cached metadata for a URL',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
         },
         {
-            description: 'output the full metadata as JSON for use by other tools',
+            description: 'inspect cached metadata as JSON',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
         },
     ];
@@ -20,75 +25,121 @@ export default class ResearchInspect extends BaseCommand {
     static args = {
         url: Args.string({
             required: true,
-            description: 'the URL to inspect',
+            description: 'URL to inspect',
         }),
     };
     static stdoutIsPrimaryData = true;
+    toSuccessJson(data) {
+        return this.batchReadSuccessJson(data);
+    }
     async run() {
-        const urls = this.parsedArgv;
-        const results = [];
-        const missingUrls = [];
-        for (const url of urls) {
-            const target = this.resolveResearchTargetOrFail(url);
-            if (!target.located) {
-                missingUrls.push(target.normalizedUrl);
-                continue;
-            }
-            results.push(this.inspectSingleTarget(target, urls.length > 1));
-        }
-        if (missingUrls.length > 0) {
-            const firstMissing = missingUrls[0];
-            const suggestions = missingUrls.map((u) => `Fetch and cache it first: ${this.config.bin} ${u}`);
-            this.error(`No cached research found for URL: ${firstMissing}` +
-                (missingUrls.length > 1 ? ` and ${missingUrls.length - 1} other URLs` : ''), {
-                exit: 1,
-                code: 'CACHE_MISS',
-                suggestions,
-            });
-        }
-        return urls.length === 1 ? results[0] : results;
+        const results = this.mapUrlsAllowingBatchErrors(this.parsedArgv, (url) => this.inspectOne(url), urlValidationErrorRow);
+        return finalizeBatch(results, isBatchReadFailure);
     }
-    logMetadata(metadata) {
-        this.log(colors.cyan(`--- Metadata ---`));
-        for (const [key, val] of Object.entries(metadata)) {
-            const paddedKey = colors.cyan((key + ':').padEnd(Math.max(25, key.length + 2)));
-            if (typeof val === 'object' && val !== null) {
-                this.log(`${paddedKey} ${colors.bold(JSON.stringify(val))}`);
-            }
-            else {
-                this.log(`${paddedKey} ${colors.bold(String(val))}`);
+    inspectOne(url) {
+        const target = this.resolveResearchTargetOrFail(url);
+        return target.located ? this.hitResult(target) : this.missResult(target);
+    }
+    missResult(target) {
+        const artifactPath = getArtifactPath(target.roots.writeRoot, target.cacheKey);
+        const existingNote = this.findExistingNoteContaining(target.roots.readRoots, target.normalizedUrl);
+        if (!this.jsonEnabled()) {
+            for (const line of formatCacheTargetHeader(target, [['Status', colors.red('miss')]], artifactPath)) {
+                this.log(line);
             }
+            this.warn(this.missGuidance(target.normalizedUrl, existingNote));
+            const sep = batchSeparator(this.parsedArgv.length > 1);
+            if (sep)
+                this.log(sep);
         }
+        return {
+            cacheKey: target.cacheKey,
+            cachePath: artifactPath,
+            normalizedUrl: target.normalizedUrl,
+            status: 'miss',
+            metadata: null,
+            sections: [],
+            partOfExistingNote: existingNote,
+        };
     }
-    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)}`);
-        }
+    // A URL with no cache key of its own can still be a secondary `--source-url` of an already
+    // imported multi-source research_note (those key off topic+content, not any one URL — see
+    // docs/reference/cache-protocol.md). Without this check, the generic "fetch and cache it" miss
+    // hint would steer the caller into creating an unrelated duplicate entry instead of finding the
+    // note that already covers this URL (discoverable today via `list --url`).
+    //
+    // ponytail: `status` and `fetch` have the same blind spot on a miss (they'd still suggest a
+    // fetch/refetch for a URL that's really a secondary source of an existing note) but aren't
+    // patched here — `status` is meant to stay a cheap pre-flight check, and `fetch`'s miss path
+    // already does real work (an actual network fetch) rather than just reporting a status, so
+    // adding a full cache scan to either changes their cost profile more than this fix's scope
+    // warrants. Extend this same scan to those commands if the gap proves costly in practice.
+    findExistingNoteContaining(readRoots, normalizedUrl) {
+        const matches = scanCacheDirs(readRoots, (artifact) => {
+            const meta = artifact.metadata;
+            if (meta.status !== 'active')
+                return null;
+            if (!artifactMatchesUrlFilter(meta, normalizedUrl))
+                return null;
+            return {
+                cacheKey: meta.cache_key,
+                artifactType: meta.artifact_type,
+                topic: meta.topic,
+                sourceUrls: meta.source_urls,
+            };
+        }, { persistIndex: !this.readOnly });
+        return matches[0] ?? null;
     }
-    inspectSingleTarget(target, showSeparator) {
-        const { cacheKey, located, roots } = target;
+    missGuidance(normalizedUrl, existingNote) {
+        if (!existingNote)
+            return cacheMissHint(this.config.bin, normalizedUrl);
+        return [
+            `${normalizedUrl} has no cache entry of its own, but it is a source of an existing ${existingNote.artifactType} (cache key: ${existingNote.cacheKey}).`,
+            `Find it with: ${this.config.bin} list --url "${normalizedUrl}"`,
+        ].join('\n');
+    }
+    hitResult(target) {
+        const { cacheKey, located, roots, normalizedUrl } = target;
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`${colors.cyan('Cache Key:'.padEnd(25))} ${colors.bold(cacheKey)}`);
-            this.log(`${colors.cyan('Cache Path:'.padEnd(25))} ${colors.gray(artifactPath)}`);
+            for (const line of formatCacheTargetHeader(target, [], artifactPath)) {
+                this.log(line);
+            }
             this.logMetadata(cached.metadata);
-            if (sections.length) {
+            if (sections.length)
                 this.logSections(sections);
-            }
-            if (showSeparator) {
-                this.log('='.repeat(40));
-            }
+            const sep = batchSeparator(this.parsedArgv.length > 1);
+            if (sep)
+                this.log(sep);
         }
         return {
             cacheKey,
             cachePath: artifactPath,
+            normalizedUrl,
+            status: 'hit',
             metadata: cached.metadata,
             sections,
         };
     }
+    logMetadata(metadata) {
+        this.log(colors.cyan(`--- Metadata ---`));
+        for (const [key, val] of Object.entries(metadata)) {
+            if (typeof val === 'object' && val !== null) {
+                this.log(formatHumanField(key, colors.bold(JSON.stringify(val))));
+            }
+            else {
+                this.log(formatHumanField(key, colors.bold(String(val))));
+            }
+        }
+    }
+    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)}`);
+        }
+    }
     // Section children link back via parent_cache_key; list the active ones for this page (T-22).
     findSections(readRoots, parentKey) {
         return scanCacheDirs(readRoots, (artifact) => {
@@ -101,6 +152,6 @@ export default class ResearchInspect extends BaseCommand {
                 headingPath: meta.section_heading_path,
                 tokenEstimate: meta.token_estimate,
             };
-        }).sort((a, b) => (a.headingPath ?? '').localeCompare(b.headingPath ?? ''));
+        }, { persistIndex: !this.readOnly }).sort((a, b) => (a.headingPath ?? '').localeCompare(b.headingPath ?? ''));
     }
 }