@taurgis/bonsai 1.0.5 → 1.0.6

package/dist/commands/fetch.js

@@ -1,4 +1,4 @@
-import { Args, Flags } from '@oclif/core';
+import { Args, Flags, ux } from '@oclif/core';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -12,7 +12,6 @@ import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
 import { fetchRenderedHtml } from '../lib/research/browser.js';
 import { capturePage } from '../lib/research/capture.js';
 import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { detectSite } from '../sites/index.js';
 const CAPTURE_DEPS = {
@@ -27,66 +26,66 @@ export default class FetchCommand extends BaseCommand {
     static description = 'Scrapes the specified URL, strips HTML boilerplate, converts the semantic payload into clean Markdown format, and caches the result locally using dynamic TTL rules.\n\nUsually invoked via the shorthand `bonsai <url>` rather than `bonsai fetch <url>`.';
     static examples = [
         {
-            description: 'Research a URL with detailed output, tagged with topic and tags',
+            description: 'research a URL with detailed output, tagged with topic and tags',
             command: '<%= config.bin %> https://docs.nestjs.com/ --topic "Backend Frameworks" --tags "Node" --tags "NestJS" --format detailed --ttl 30d',
         },
         {
-            description: 'Research a volatile page with compressed output and short TTL, returned as JSON',
+            description: 'research a volatile page with compressed output and short TTL, returned as JSON',
             command: '<%= config.bin %> https://news.ycombinator.com/ --format compressed --ttl 2h --json',
         },
     ];
     static args = {
         url: Args.string({
             required: true,
-            description: 'The full HTTP/HTTPS URL of the web page to research.',
+            description: 'the full HTTP/HTTPS URL of the web page to research',
         }),
     };
     static flags = {
         topic: Flags.string({
             char: 't',
-            description: 'The main category/topic of the research for metadata tagging.',
+            description: 'the main category/topic of the research for metadata tagging',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Taxonomic tags for this research (can be repeated).',
+            description: 'taxonomic tags for this research (can be repeated)',
             multiple: true,
         }),
         format: Flags.option({
             char: 'f',
-            description: 'Desired data density.',
+            description: 'desired data density',
             options: ['compressed', 'detailed'],
             default: 'compressed',
         })(),
         tier: Flags.option({
-            description: 'Freshness tier policy.',
+            description: 'freshness tier policy',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m".',
+            description: 'predicted lifespan: number + h/d/w/m/y (m = months), e.g. "2h", "7d", "6m"',
         }),
         'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g., "1d", "30d").',
+            description: 'maximum age of cache to accept (e.g., "1d", "30d")',
         }),
         force: Flags.boolean({
-            description: 'Force a fresh fetch, ignoring any cached entries.',
+            description: 'force a fresh fetch, ignoring any cached entries',
             default: false,
         }),
         'dry-run': Flags.boolean({
-            description: 'Perform validation and fetch without saving to local cache.',
+            description: 'perform validation and fetch without saving to local cache',
             default: false,
         }),
         'allow-stale': Flags.boolean({
-            description: 'Allow serving stale cache if the remote server is unreachable.',
+            description: 'allow serving stale cache if the remote server is unreachable',
             default: false,
         }),
         rendered: Flags.boolean({
-            description: 'Force using a browser-rendered scraping path for dynamic pages.',
+            description: 'force using a browser-rendered scraping path for dynamic pages',
             default: false,
         }),
         storage: Flags.option({
-            description: 'Override where this result is cached (overrides configured default). Secret-bearing pages are always stored globally.',
+            description: 'override where this result is cached (secrets always stored globally)',
             options: ['global', 'project'],
         })(),
     };
@@ -185,7 +184,7 @@ export default class FetchCommand extends BaseCommand {
     validateDurationFlags(ttl, maxAge) {
         for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
             if (msg)
-                this.error(msg, { exit: 2 });
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
     }
     // Re-emit a runtime fetch failure with actionable next steps. Deep fetch/extract code throws plain
@@ -197,7 +196,12 @@ export default class FetchCommand extends BaseCommand {
     emitFetchError(err, url) {
         const message = err instanceof Error ? err.message : String(err);
         const guidance = fetchFailureGuidance(message, url);
-        this.error(message, { exit: 1, suggestions: guidance?.suggestions, ref: guidance?.ref });
+        this.error(message, {
+            exit: 1,
+            code: 'FETCH_FAILED',
+            suggestions: guidance?.suggestions,
+            ref: guidance?.ref,
+        });
     }
     // Serves the cache when a fresh/revalidatable entry exists, otherwise fetches fresh. Reads fall
     // back project→global; the resolved artifact is returned with the dir it lives in / landed in.
@@ -254,27 +258,30 @@ export default class FetchCommand extends BaseCommand {
         const { url } = this.args;
         const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
         this.validateDurationFlags(ttl, maxAge);
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                flagOverride: this.flags.storage,
-                lookup: !this.flags.force,
-                url,
-            });
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
-        }
+        const target = this.resolveResearchTargetOrFail(url, {
+            flagOverride: this.flags.storage,
+            lookup: !this.flags.force,
+        });
         const { cacheKey, located, normalizedUrl, roots } = target;
         const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();
         try {
+            if (!this.jsonEnabled()) {
+                ux.action.start('Fetching ' + normalizedUrl);
+            }
             const { cacheStatus, freshnessState, artifact, storageDir, redirectedToGlobal } = await this.resolveArtifact(normalizedUrl, cacheKey, roots, tmpDir, currentTime, located, summaryLevel);
             this.persistSectionsIfFresh(tmpDir ?? storageDir, artifact, currentTime, cacheStatus, summaryLevel);
+            if (!this.jsonEnabled()) {
+                const CACHE_STATUS_LABEL = {
+                    hit: 'cached',
+                    miss: 'done',
+                    refreshed: 'refreshed',
+                    revalidated: 'revalidated',
+                    stale: 'served stale',
+                };
+                ux.action.stop(CACHE_STATUS_LABEL[cacheStatus] ?? cacheStatus);
+            }
             const content = format === 'compressed' ? artifact.compressed : artifact.detailed;
             const resultData = this.buildResultData(url, normalizedUrl, cacheKey, storageDir, roots.mode, cacheStatus, freshnessState, format, artifact, content, redirectedToGlobal);
             if (!this.jsonEnabled()) {
@@ -283,6 +290,9 @@ export default class FetchCommand extends BaseCommand {
             return resultData;
         }
         catch (err) {
+            if (!this.jsonEnabled()) {
+                ux.action.stop('failed');
+            }
             // Stale-serve (exit 5) signals via process.exitCode and never throws, so it bypasses this
             // path; only genuine fetch/extract failures land here and get classified guidance. Use the
             // normalized URL in hints so the copy-paste command is canonical (and never echoes raw,
@@ -367,10 +377,10 @@ function handleStaleRevalidationResult(command, revalResult) {
     if (revalResult.status !== 'stale')
         return;
     if (revalResult.allowed) {
-        command.warn(`Serving stale content: revalidation failed: ${revalResult.error}`);
+        command.warn(`Serving stale content within grace period: revalidation failed (${revalResult.error}).`);
     }
     else {
-        command.warn(`Serving stale content (exit 5): revalidation failed: ${revalResult.error}`);
+        command.warn(`Serving stale content within grace period (exit 5): revalidation failed (${revalResult.error}).`);
         process.exitCode = 5;
     }
 }

package/dist/commands/import.d.ts

@@ -30,6 +30,9 @@ export default class ResearchImport extends BaseCommand<typeof ResearchImport> {
     protected fsExistsSync(filePath: string): boolean;
     protected fsStatSync(filePath: string): fs.Stats;
     protected fsReadFileSync(filePath: string): string;
+    private stdinImportSuggestions;
+    /** Non-interactive stdin that never receives data (open pipe with no writer) must not hang forever. */
+    private readStdinWithGuard;
     private readAndValidateFile;
     private readAndValidateInput;
     private deriveImportCacheKey;

package/dist/commands/import.js

@@ -9,7 +9,7 @@ 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 { getPolicy } from '../lib/research/freshness.js';
+import { durationFlagError, getPolicy } from '../lib/research/freshness.js';
 import { buildCompressed } from '../lib/research/compress.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { estimateTokens } from '../lib/research/token-estimate.js';
@@ -19,15 +19,15 @@ export default class ResearchImport extends BaseCommand {
     static description = 'Accepts a synthesized Markdown note via stdin and registers it under the single target URL or multiple source URLs.';
     static examples = [
         {
-            description: 'Import detailed research for a single URL via stdin',
+            description: 'import detailed research for a single URL via stdin',
             command: 'echo "# My Article" | <%= config.bin %> import https://example.com/docs --stdin',
         },
         {
-            description: 'Import research synthesized from multiple source URLs',
+            description: 'import research 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 local Markdown file',
             command: '<%= config.bin %> import https://example.com/docs --file path/to/notes.md',
         },
     ];
@@ -38,46 +38,46 @@ 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: 'the single source URL of the page (only for single-source import)',
         }),
     };
     static flags = {
         stdin: Flags.boolean({
-            description: 'Read Markdown from stdin.',
+            description: 'read Markdown from stdin',
             default: false,
         }),
         file: Flags.string({
-            description: 'Path to a Markdown file containing research notes to import.',
+            description: 'path to a Markdown file containing research notes to import',
         }),
         'input-format': Flags.option({
-            description: 'Format of the input provided.',
+            description: 'format of the input provided',
             options: ['compressed', 'detailed'],
             default: 'detailed',
         })(),
         topic: Flags.string({
             char: 't',
-            description: 'The main topic for this research note.',
+            description: 'the main topic for this research note',
         }),
         tags: Flags.string({
             char: 'g',
-            description: 'Taxonomic tags (can be repeated).',
+            description: 'taxonomic tags (can be repeated)',
             multiple: true,
         }),
         tier: Flags.option({
-            description: 'Freshness tier policy.',
+            description: 'freshness tier policy',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         'source-url': Flags.string({
-            description: 'Repeated source URLs for multi-source import.',
+            description: 'repeated source URLs for multi-source import',
             multiple: true,
         }),
         ttl: Flags.string({
             char: 'l',
-            description: 'Predicted lifespan of the data (e.g. "24h", "7d").',
+            description: 'predicted lifespan of the data (e.g. "24h", "7d")',
         }),
         storage: Flags.option({
-            description: 'Override where this note is cached (overrides configured default). Secret-bearing notes are always stored globally.',
+            description: 'override where this note is cached (secrets always stored globally)',
             options: ['global', 'project'],
         })(),
     };
@@ -121,28 +121,38 @@ export default class ResearchImport extends BaseCommand {
                 return normalizeUrl(u);
             }
             catch (err) {
-                this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+                this.error(`Invalid URL: ${err.message}`, { exit: 2, code: 'INVALID_URL' });
             }
         });
         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 });
+            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 });
+            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 });
+            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 });
+            this.error('Cannot specify both --stdin and --file <path>. Choose one.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+            });
         }
     }
     fsExistsSync(filePath) {
@@ -154,51 +164,68 @@ 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 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 });
+            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 });
+            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 });
+            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 });
+            this.error('Empty file content provided.', { exit: 2, code: 'EMPTY_INPUT' });
         }
         return content;
     }
     async readAndValidateInput() {
         if (this.flags.stdin) {
-            // On an interactive terminal with nothing piped, reading stdin blocks forever waiting for EOF —
-            // a silent hang with no feedback. Fail fast with a usage error instead; piped/redirected input
-            // (the agent and CI path) has isTTY falsy and reads normally.
-            if (this.stdinIsInteractive()) {
-                this.error('No data piped to --stdin.', {
-                    exit: 2,
-                    suggestions: [
-                        'Pipe Markdown content, e.g. cat notes.md | bonsai import <url> --stdin',
-                        'Or read from a file: bonsai import <url> --file notes.md',
-                    ],
-                });
-            }
-            // Initialized so the post-catch read below never depends on this.error()'s `never` return type
-            // for definite assignment; the empty-content guard rejects '' as a usage error anyway.
-            let rawInput = '';
-            try {
-                rawInput = await this.readStdin();
-            }
-            catch (err) {
-                // Genuine stream/size failure reading stdin → I/O failure (exit 1).
-                this.error(err.message, { exit: 1 });
-            }
-            // Empty input is a usage error (exit 2), not an I/O failure — keep it out of the
-            // catch above so its exit code is not clobbered to 1.
+            const rawInput = await this.readStdinWithGuard();
             if (!rawInput.trim()) {
-                this.error('Empty stdin content provided.', { exit: 2 });
+                this.error('Empty stdin content provided.', { exit: 2, code: 'EMPTY_INPUT' });
             }
             return rawInput;
         }
@@ -213,10 +240,10 @@ export default class ResearchImport extends BaseCommand {
                 // 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 });
+                this.error(`Failed to read file: ${err.message}`, { exit: 1, code: 'IO_ERROR' });
             }
         }
-        this.error('No input source specified.', { exit: 2 });
+        this.error('No input source specified.', { exit: 2, code: 'MISSING_INPUT' });
     }
     deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls) {
         if (hasSingle) {
@@ -292,6 +319,9 @@ export default class ResearchImport extends BaseCommand {
         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);
@@ -311,8 +341,8 @@ export default class ResearchImport extends BaseCommand {
         }
         if (!this.jsonEnabled()) {
             this.log(`Successfully imported research artifact.`);
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Storage Path: ${storagePath}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Storage Path:'.padEnd(25)} ${storagePath}`);
         }
         const inputFormat = this.flags['input-format'];
         return {

package/dist/commands/inspect.d.ts

@@ -3,6 +3,10 @@ export default class ResearchInspect extends BaseCommand<typeof ResearchInspect>
     static id: string;
     static summary: string;
     static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/commands/inspect.js

@@ -1,49 +1,54 @@
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { scanCacheDirs } from '../lib/research/storage.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
 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 examples = [
+        {
+            description: 'inspect cached research metadata for a specific URL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'output the full metadata as JSON for use by other tools',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --json',
+        },
+    ];
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to inspect.',
+            description: 'the URL to inspect',
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const { url } = this.args;
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                url,
-            });
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
-        }
+        const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         if (!located) {
-            this.error(`No cached research found for URL: ${normalizedUrl}`, { exit: 1 });
+            // inspect makes no network call, so the bare message reads like the network-failure case the
+            // exit-1 contract describes. Point at the fix instead: fetch the page so it lands in the cache.
+            this.error(`No cached research found for URL: ${normalizedUrl}`, {
+                exit: 1,
+                code: 'CACHE_MISS',
+                suggestions: [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`],
+            });
         }
         const cached = located.artifact;
         const artifactPath = located.path;
         const sections = this.findSections(roots.readRoots, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Cache Path:'.padEnd(25)} ${artifactPath}`);
             this.log(`--- Metadata ---`);
             for (const [key, val] of Object.entries(cached.metadata)) {
+                const paddedKey = (key + ':').padEnd(Math.max(25, key.length + 2));
                 if (typeof val === 'object' && val !== null) {
-                    this.log(`${key}: ${JSON.stringify(val)}`);
+                    this.log(`${paddedKey} ${JSON.stringify(val)}`);
                 }
                 else {
-                    this.log(`${key}: ${val}`);
+                    this.log(`${paddedKey} ${val}`);
                 }
             }
             if (sections.length) {

package/dist/commands/list.d.ts

@@ -11,8 +11,8 @@ export default class ResearchList extends BaseCommand<typeof ResearchList> {
         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>;
         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" | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'capture-method': import("@oclif/core/interfaces").OptionFlag<"static_fetch" | "browser_fallback" | "agent_supplied" | 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;