@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/lib/research/freshness.js

@@ -1,8 +1,26 @@
 const HOUR_MS = 3600 * 1000;
 const DAY_MS = 24 * HOUR_MS;
+/** Calendar multipliers used when parsing duration units (`w`/`m`/`y`). */
+const DAYS_PER_WEEK = 7;
+const DAYS_PER_MONTH = 30;
+const DAYS_PER_YEAR = 365;
+/** Default freshness windows by tier (days). Grace is the additional serve-stale window. */
+const STANDARD_FRESH_DAYS = 30;
+const STANDARD_GRACE_DAYS = 14;
+const STABLE_FRESH_DAYS = 180;
+const STABLE_GRACE_DAYS = 60;
+const VOLATILE_FRESH_DAYS = 7;
+const VOLATILE_GRACE_DAYS = 5;
+/** Shared unit hint for parse failures and empty-duration rejection. */
+const DURATION_FORMAT_HINT = `Use a whole number plus a unit: ` +
+    `h (hours), d (days), w (weeks), m (months), or y (years), e.g. '2h', '7d', '6m'.`;
 /**
- * Parses simple TTL duration strings to milliseconds. The unit `m` is months (not minutes); the
- * smallest unit is hours, since sub-hour cache lifespans are not meaningful for research artifacts.
+ * Parses a TTL/duration string into milliseconds.
+ * The unit `m` means months (not minutes); the smallest unit is hours.
+ *
+ * @param ttl - Whole number plus unit (`h`/`d`/`w`/`m`/`y`).
+ * @returns Duration in milliseconds.
+ * @throws {Error} When the format is invalid or the duration is zero.
  */
 export function parseTtlToMs(ttl) {
     const match = ttl.match(/^(\d+)([hdwmy])$/);
@@ -10,35 +28,44 @@ export function parseTtlToMs(ttl) {
         // Deliberately does not start with "Invalid": durationFlagError wraps this as
         // "Invalid <flag>: <message>", and a leading "Invalid" here produced a "Invalid --ttl:
         // Invalid TTL format" stutter.
-        throw new Error(`Duration "${ttl}" is not a valid format. Use a whole number plus a unit: ` +
-            `h (hours), d (days), w (weeks), m (months), or y (years), e.g. '24h', '7d', '6m'.`);
+        throw new Error(`Duration "${ttl}" is not a valid format. ${DURATION_FORMAT_HINT}`);
     }
-    const val = parseInt(match[1] || '', 10);
+    const amount = parseInt(match[1] || '', 10);
     const unit = match[2] || '';
+    // Zero-length durations would match every entry (age >= 0) and turn prune filters into a wipe.
+    if (amount === 0) {
+        throw new Error(`Duration "${ttl}" must be greater than zero.`);
+    }
     switch (unit) {
         case 'h':
-            return val * HOUR_MS;
+            return amount * HOUR_MS;
         case 'd':
-            return val * DAY_MS;
+            return amount * DAY_MS;
         case 'w':
-            return val * 7 * DAY_MS;
+            return amount * DAYS_PER_WEEK * DAY_MS;
         case 'm':
-            return val * 30 * DAY_MS;
+            return amount * DAYS_PER_MONTH * DAY_MS;
         case 'y':
-            return val * 365 * DAY_MS;
+            return amount * DAYS_PER_YEAR * DAY_MS;
         default:
             return 0;
     }
 }
 /**
- * Validate a duration-valued flag. Returns an actionable error message that names the
- * offending flag when the value is malformed, or null when the flag is absent or valid.
- * Callers map a non-null message onto `this.error(msg, { exit: 2 })`, so every command
- * reports the same parse failure while naming the exact flag the user passed.
+ * Validate a duration-valued flag.
+ *
+ * @param flag - Flag token for the error message (e.g. `--ttl`).
+ * @param value - Raw flag value, or `undefined` when omitted.
+ * @returns Actionable error message, or `null` when absent/valid.
  */
 export function durationFlagError(flag, value) {
-    if (!value)
+    // Absent is fine; empty/whitespace is almost always a shell-quoting mistake and must not
+    // silently mean "no override" (unlike a truly omitted flag).
+    if (value === undefined)
         return null;
+    if (value.trim() === '') {
+        return `Invalid ${flag}: Duration must not be empty. ${DURATION_FORMAT_HINT}`;
+    }
     try {
         parseTtlToMs(value);
         return null;
@@ -48,36 +75,48 @@ export function durationFlagError(flag, value) {
     }
 }
 /**
- * Derives the active freshness policy based on the tier and optional TTL override.
+ * Derives the active freshness policy from a tier and optional TTL override.
+ * When a TTL override is set, grace scales proportionally to the tier's default ratio.
+ *
+ * @param tier - Freshness tier (`stable` / `standard` / `volatile`).
+ * @param ttlOverride - Optional TTL string replacing the tier's fresh window.
+ * @returns Fresh and grace windows in milliseconds.
  */
-export function getPolicy(tier, ttlOverride) {
-    let freshWindowMs = 30 * DAY_MS;
-    let graceWindowMs = 14 * DAY_MS;
+export function resolveFreshnessPolicy(tier, ttlOverride) {
+    let freshWindowMs = STANDARD_FRESH_DAYS * DAY_MS;
+    let graceWindowMs = STANDARD_GRACE_DAYS * DAY_MS;
     if (tier === 'stable') {
-        freshWindowMs = 180 * DAY_MS;
-        graceWindowMs = 60 * DAY_MS;
+        freshWindowMs = STABLE_FRESH_DAYS * DAY_MS;
+        graceWindowMs = STABLE_GRACE_DAYS * DAY_MS;
     }
     else if (tier === 'volatile') {
-        freshWindowMs = 7 * DAY_MS;
-        graceWindowMs = 5 * DAY_MS;
+        freshWindowMs = VOLATILE_FRESH_DAYS * DAY_MS;
+        graceWindowMs = VOLATILE_GRACE_DAYS * DAY_MS;
     }
-    const activeTtl = ttlOverride;
-    if (activeTtl) {
-        freshWindowMs = parseTtlToMs(activeTtl);
-        const defaultFresh = tier === 'stable' ? 180 * DAY_MS : tier === 'volatile' ? 7 * DAY_MS : 30 * DAY_MS;
-        const defaultGrace = tier === 'stable' ? 60 * DAY_MS : tier === 'volatile' ? 5 * DAY_MS : 14 * DAY_MS;
+    if (ttlOverride) {
+        const defaultFresh = freshWindowMs;
+        const defaultGrace = graceWindowMs;
+        freshWindowMs = parseTtlToMs(ttlOverride);
         graceWindowMs = Math.floor(freshWindowMs * (defaultGrace / defaultFresh));
     }
     return { freshWindowMs, graceWindowMs };
 }
 /**
  * Evaluates the freshness status of a cached artifact.
+ * `ttlOverride` / `tierOverride` let status (and similar read-only checks) evaluate "what if"
+ * policies without mutating the stored metadata. When omitted, the artifact's own tier/TTL win.
+ *
+ * @param meta - Artifact metadata providing timestamps, tier, and stored TTL.
+ * @param currentTime - Clock used for age calculation.
+ * @param ttlOverride - Optional TTL replacing the stored TTL for this evaluation.
+ * @param tierOverride - Optional tier replacing the stored tier for this evaluation.
+ * @returns `fresh`, `stale_grace`, or `stale_expired`.
  */
-export function evaluateFreshness(meta, currentTime, ttlOverride) {
+export function evaluateFreshness(meta, currentTime, ttlOverride, tierOverride) {
     const fetched = meta.fetched_at ? new Date(meta.fetched_at).getTime() : 0;
     const validated = meta.validated_at ? new Date(meta.validated_at).getTime() : 0;
     const baseTime = Math.max(fetched, validated);
-    const { freshWindowMs, graceWindowMs } = getPolicy(meta.tier, ttlOverride || meta.ttl);
+    const { freshWindowMs, graceWindowMs } = resolveFreshnessPolicy(tierOverride ?? meta.tier, ttlOverride || meta.ttl);
     const ageMs = currentTime.getTime() - baseTime;
     if (ageMs <= freshWindowMs) {
         return 'fresh';
@@ -88,7 +127,12 @@ export function evaluateFreshness(meta, currentTime, ttlOverride) {
     return 'stale_expired';
 }
 /**
- * Checks if the cached entry's age exceeds the specified max-age duration.
+ * Checks whether the cached entry's age exceeds the specified max-age duration.
+ *
+ * @param cached - Artifact (or metadata bag) with fetch/validate timestamps.
+ * @param currentTime - Clock used for age calculation.
+ * @param maxAge - Duration string, or `undefined` to skip the check.
+ * @returns `true` when max-age is set and exceeded.
  */
 export function checkMaxAgeExpired(cached, currentTime, maxAge) {
     if (!maxAge)
@@ -101,3 +145,19 @@ export function checkMaxAgeExpired(cached, currentTime, maxAge) {
     const ageMs = currentTime.getTime() - baseTime;
     return ageMs > parseTtlToMs(maxAge);
 }
+/**
+ * Freshness for a cached artifact, applying `--max-age` before the tier/TTL windows.
+ *
+ * @param cached - Artifact with full metadata.
+ * @param currentTime - Clock used for age calculation.
+ * @param options.ttl - Optional TTL override.
+ * @param options.maxAge - Optional max-age duration; when exceeded returns `stale_expired`.
+ * @param options.tier - Optional tier override.
+ * @returns `fresh`, `stale_grace`, or `stale_expired`.
+ */
+export function evaluateFreshnessWithMaxAge(cached, currentTime, options = {}) {
+    if (checkMaxAgeExpired(cached, currentTime, options.maxAge)) {
+        return 'stale_expired';
+    }
+    return evaluateFreshness(cached.metadata, currentTime, options.ttl, options.tier);
+}

package/dist/lib/research/import-command-service.d.ts

@@ -0,0 +1,56 @@
+import type { StorageMode } from '../config/index.js';
+import type { ResearchArtifact } from './schema.js';
+import { type StoreRoots } from './store-roots.js';
+import { type CliIo } from './cli-io.js';
+/** Minimal file-stat shape used by import input hooks. */
+export interface ImportCommandFileStat {
+    isFile(): boolean;
+    size: number;
+}
+/** Injected IO hooks so import stays testable without a live TTY. */
+export interface ImportCommandInputHooks {
+    stdinIsInteractive(): boolean;
+    readStdin(limitBytes: number): Promise<string>;
+    fsExistsSync(filePath: string): boolean;
+    fsStatSync(filePath: string): ImportCommandFileStat;
+    fsReadFileSync(filePath: string): string;
+}
+/** Parsed flags for one import command invocation. */
+export interface ImportCommandFlags {
+    stdin: boolean;
+    file?: string;
+    inputFormat: 'compressed' | 'detailed';
+    topic?: string;
+    tags?: string[];
+    tier: 'stable' | 'standard' | 'volatile';
+    sourceUrls: string[];
+    ttl?: string;
+    storage?: StorageMode;
+}
+/** Positional args for one import command invocation. */
+export interface ImportCommandArgs {
+    url?: string;
+}
+/** Validated import inputs ready for persistence. */
+export interface PreparedImportCommand {
+    args: ImportCommandArgs;
+    artifact: ResearchArtifact;
+    cacheKey: string;
+    flags: ImportCommandFlags;
+    hasSingle: boolean;
+    roots: StoreRoots;
+    singleNormalizedUrl: string;
+    sourceUrls: string[];
+}
+/**
+ * Validate the request, read and validate the input content, and build the artifact — everything
+ * up to (but excluding) the cache write, so the command can resolve dry-run mode in between.
+ */
+export declare function prepareImportCommandService(opts: {
+    args: ImportCommandArgs;
+    flags: ImportCommandFlags;
+    io: CliIo;
+    input: ImportCommandInputHooks;
+}): Promise<PreparedImportCommand>;
+/** Persist (or dry-run preview) a prepared import and return the command's `--json` data payload. */
+export declare function finishImportCommandService(prepared: PreparedImportCommand, dryRun: boolean, io: CliIo): unknown;

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

@@ -0,0 +1,381 @@
+import { Errors } from '@oclif/core';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { loadSummaryLevel } from '../config/index.js';
+import { buildCompressed } from './compress.js';
+import { durationFlagError, resolveFreshnessPolicy } from './freshness.js';
+import { applyAutoTags } from './keywords.js';
+import { persistArtifact } from './persist-artifact.js';
+import { sanitizePromptInjection } from './prompt-injection.js';
+import { getArtifactPath } from './storage.js';
+import { loadStoreRoots } from './store-roots.js';
+import { estimateTokens } from './token-estimate.js';
+import { deriveCacheKey } from './cache-key.js';
+import { normalizeUrl } from './url.js';
+import { failInvalidUrl } from './cli-io.js';
+import { formatHumanFields } from '../cli-presentation.js';
+const INPUT_LIMIT_BYTES = 1024 * 1024;
+// ponytail: 1s stdin idle timeout is enough for piped agent input; raise if interactive paste
+// workflows need longer before the read aborts.
+const STDIN_TIMEOUT_MS = 1000;
+/**
+ * Validate the request, read and validate the input content, and build the artifact — everything
+ * up to (but excluding) the cache write, so the command can resolve dry-run mode in between.
+ */
+export async function prepareImportCommandService(opts) {
+    const { args, flags, input, io } = opts;
+    const hasSingle = Boolean(args.url);
+    const hasMulti = flags.sourceUrls.length > 0;
+    const ttlErr = durationFlagError('--ttl', flags.ttl);
+    if (ttlErr)
+        io.error(ttlErr, { exit: 2, code: 'INVALID_DURATION' });
+    validateSourceMode(hasSingle, hasMulti, flags, io);
+    const rawInput = await readAndValidateInput(flags, input, io);
+    const sourceUrls = getSourceUrls(hasMulti, flags.sourceUrls, args.url, io);
+    const singleNormalizedUrl = hasSingle ? sourceUrls[0] || '' : '';
+    const cacheKey = deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls, flags);
+    const artifact = buildImportArtifact({
+        hasSingle,
+        singleUrl: args.url,
+        singleNormalizedUrl,
+        sourceUrls,
+        cacheKey,
+        rawInput,
+        flags,
+        io,
+    });
+    const roots = loadStoreRoots({
+        configDir: io.configDir,
+        cwd: io.cwd,
+        dataDir: io.dataDir,
+        flagOverride: flags.storage,
+    });
+    return {
+        args,
+        artifact,
+        cacheKey,
+        flags,
+        hasSingle,
+        roots,
+        singleNormalizedUrl,
+        sourceUrls,
+    };
+}
+/** Persist (or dry-run preview) a prepared import and return the command's `--json` data payload. */
+export function finishImportCommandService(prepared, dryRun, io) {
+    const { args, artifact, cacheKey, flags, hasSingle, roots, singleNormalizedUrl, sourceUrls } = prepared;
+    const writeResult = persistArtifact({
+        roots,
+        cacheKey,
+        artifact,
+        dryRun,
+        kind: 'import',
+    });
+    const storagePath = getArtifactPath(writeResult.dataDir, cacheKey);
+    if (writeResult.redirectWarning) {
+        io.warn(writeResult.redirectWarning);
+    }
+    if (!io.json) {
+        logImportHumanSuccess(io, {
+            dryRun,
+            cacheKey,
+            storagePath,
+            hasSingle,
+            flags,
+            sourceUrls,
+        });
+    }
+    return {
+        schemaVersion: 1,
+        command: 'import',
+        dryRun,
+        cache: {
+            key: cacheKey,
+            status: dryRun ? 'would_import' : 'imported',
+            freshness: 'fresh',
+            path: storagePath,
+            storage: roots.mode,
+            redirectedToGlobal: writeResult.redirected,
+        },
+        artifactType: artifact.metadata.artifact_type,
+        topic: artifact.metadata.topic,
+        sourceUrls,
+        source: {
+            // Multi-source notes have no single primary URL -- expose null plus sourceUrls above.
+            url: hasSingle ? args.url : null,
+            normalizedUrl: hasSingle ? singleNormalizedUrl : null,
+            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,
+        },
+        format: flags.inputFormat,
+        tokenEstimate: flags.inputFormat === 'compressed'
+            ? artifact.metadata.token_estimate.compressed
+            : artifact.metadata.token_estimate.detailed,
+        content: flags.inputFormat === 'compressed' ? artifact.compressed : artifact.detailed,
+    };
+}
+function logImportHumanSuccess(io, opts) {
+    const { dryRun, cacheKey, storagePath, hasSingle, flags, sourceUrls } = opts;
+    io.log(dryRun
+        ? `[dry-run] Would import research artifact.`
+        : `Successfully imported research artifact.`);
+    const fields = [
+        ['Cache Key', cacheKey],
+        ['Storage Path', storagePath],
+    ];
+    let topic;
+    if (!hasSingle) {
+        topic = resolvedTopic(flags);
+        fields.push(['Topic', topic], ['Source URLs', sourceUrls.join(', ')]);
+    }
+    for (const line of formatHumanFields(fields))
+        io.log(line);
+    if (topic) {
+        io.log(`\nTip: find it again with ${io.bin} list --topic "${topic}"`);
+    }
+}
+function importSourceSuggestions(bin) {
+    return [
+        `Single-source import: ${bin} import https://example.com/docs --file notes.md`,
+        `Multi-source import: ${bin} import --source-url https://example.com/a --topic "Topic" --file notes.md`,
+    ];
+}
+function stdinImportSuggestions(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`,
+    ];
+}
+function validateSourceMode(hasSingle, hasMulti, flags, io) {
+    if (hasSingle && hasMulti) {
+        io.error('Cannot specify both positional <url> and --source-url flags.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: [
+                'Use the positional URL for single-source import, or use only --source-url for multi-source import.',
+            ],
+        });
+    }
+    if (!hasSingle && !hasMulti) {
+        io.error('Must specify either positional <url> (for single-source) or --source-url (for multi-source) import.', { exit: 2, code: 'MISSING_URL', suggestions: importSourceSuggestions(io.bin) });
+    }
+    if (hasMulti && !resolvedTopic(flags)) {
+        io.error('Multi-source import requires the --topic flag.', {
+            exit: 2,
+            code: 'MISSING_TOPIC',
+            suggestions: [`Add a topic: ${io.bin} import --source-url <url> --topic "Topic"`],
+        });
+    }
+    if (!flags.stdin && !flags.file) {
+        io.error('Either --stdin or --file <path> must be specified to import content.', {
+            exit: 2,
+            code: 'MISSING_INPUT',
+            suggestions: stdinImportSuggestions(io.bin),
+        });
+    }
+    if (flags.stdin && flags.file) {
+        io.error('Cannot specify both --stdin and --file. Choose one input source.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: [
+                'Pipe content with --stdin, or read a file with --file notes.md; do not pass both.',
+            ],
+        });
+    }
+}
+async function readStdinWithGuard(input, io) {
+    if (input.stdinIsInteractive()) {
+        io.error('No data piped to --stdin.', {
+            exit: 2,
+            code: 'MISSING_STDIN',
+            suggestions: stdinImportSuggestions(io.bin),
+        });
+    }
+    let rawInput = '';
+    try {
+        rawInput = await Promise.race([
+            input.readStdin(INPUT_LIMIT_BYTES),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('STDIN_TIMEOUT')), STDIN_TIMEOUT_MS)),
+        ]);
+    }
+    catch (err) {
+        if (err.message === 'STDIN_TIMEOUT') {
+            io.error('No stdin data received. Pipe content or use --file.', {
+                exit: 2,
+                code: 'MISSING_STDIN',
+                suggestions: stdinImportSuggestions(io.bin),
+            });
+        }
+        if (err.message.includes('stdin size limit exceeded')) {
+            io.error(err.message, {
+                exit: 1,
+                code: 'STDIN_TOO_LARGE',
+                suggestions: ['Reduce the input below 1 MiB, or split the note into smaller imports.'],
+            });
+        }
+        // Genuine stream failure reading stdin -> I/O failure (exit 1).
+        io.error(err.message, {
+            exit: 1,
+            code: 'IO_ERROR',
+            suggestions: ['Retry with --file notes.md if stdin is unreliable in this shell.'],
+        });
+    }
+    return rawInput;
+}
+function readAndValidateFile(filePath, input, io) {
+    if (!input.fsExistsSync(filePath)) {
+        io.error(`File does not exist: ${filePath}`, {
+            exit: 2,
+            code: 'FILE_NOT_FOUND',
+            suggestions: ['Check the path, or pipe content with --stdin.'],
+        });
+    }
+    const stat = input.fsStatSync(filePath);
+    if (!stat.isFile()) {
+        io.error(`Path is not a file: ${filePath}`, {
+            exit: 2,
+            code: 'NOT_A_FILE',
+            suggestions: ['Pass a Markdown file path, or pipe content with --stdin.'],
+        });
+    }
+    if (stat.size > INPUT_LIMIT_BYTES) {
+        io.error('File size limit exceeded (max 1 MiB).', {
+            exit: 1,
+            code: 'FILE_TOO_LARGE',
+            suggestions: ['Reduce the file below 1 MiB, or split the note into smaller imports.'],
+        });
+    }
+    const content = input.fsReadFileSync(filePath);
+    if (!content.trim()) {
+        io.error('Empty file content provided.', {
+            exit: 2,
+            code: 'EMPTY_INPUT',
+            suggestions: ['Provide non-empty Markdown content.'],
+        });
+    }
+    return content;
+}
+async function readAndValidateInput(flags, input, io) {
+    const fileReadsStdin = flags.file === '-';
+    if (flags.stdin || fileReadsStdin) {
+        const rawInput = await readStdinWithGuard(input, io);
+        if (!rawInput.trim()) {
+            io.error('Empty stdin content provided.', {
+                exit: 2,
+                code: 'EMPTY_INPUT',
+                suggestions: stdinImportSuggestions(io.bin),
+            });
+        }
+        return rawInput;
+    }
+    // validateSourceMode already required --stdin or --file.
+    const filePath = resolve(flags.file);
+    try {
+        return readAndValidateFile(filePath, input, io);
+    }
+    catch (err) {
+        // readAndValidateFile raises usage errors via io.error, which throw CLIErrors carrying their
+        // own exit code and message -- preserve those. Only an unexpected read failure is wrapped.
+        if (err instanceof Errors.CLIError)
+            throw err;
+        io.error(`Failed to read file: ${err.message}`, {
+            exit: 1,
+            code: 'IO_ERROR',
+            suggestions: ['Check file permissions, or pipe content with --stdin.'],
+        });
+    }
+}
+/** Trimmed --topic, or null when absent/whitespace-only. */
+function resolvedTopic(flags) {
+    const topic = flags.topic?.trim();
+    return topic || null;
+}
+function getSourceUrls(hasMulti, multiUrls, singleUrl, io) {
+    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.
+            failInvalidUrl(io.error, u, err.message);
+        }
+    });
+    // Deduplicate after normalization so repeated --source-url values do not inflate the key.
+    return hasMulti ? [...new Set(normalized)].sort() : normalized;
+}
+function deriveImportCacheKey(hasSingle, singleNormalizedUrl, sourceUrls, flags) {
+    if (hasSingle) {
+        return deriveCacheKey(singleNormalizedUrl);
+    }
+    const combinedString = [resolvedTopic(flags).toLowerCase(), ...sourceUrls].join('|');
+    return createHash('sha256').update(combinedString).digest('hex');
+}
+function buildImportArtifact(opts) {
+    const { hasSingle, singleUrl, singleNormalizedUrl, sourceUrls, cacheKey, rawInput, flags, io } = opts;
+    const currentTime = new Date();
+    const ttl = flags.ttl || null;
+    const { freshWindowMs } = resolveFreshnessPolicy(flags.tier, ttl);
+    const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
+    const detailed = sanitizePromptInjection(rawInput);
+    // Always sanitize -- agent-supplied notes are untrusted regardless of density. When the caller
+    // already provided compressed Markdown, keep that body; otherwise condense the detailed import.
+    const compressed = flags.inputFormat === 'detailed'
+        ? buildCompressed(detailed, loadSummaryLevel(io.configDir, io.cwd))
+        : detailed;
+    const contentHash = createHash('sha256').update(detailed).digest('hex');
+    const metadata = {
+        schema_version: 1,
+        artifact_type: hasSingle ? 'source' : 'research_note',
+        source_url: hasSingle ? singleUrl : '',
+        source_urls: sourceUrls,
+        normalized_url: singleNormalizedUrl,
+        cache_key: cacheKey,
+        topic: resolvedTopic(flags),
+        tags: flags.tags || [],
+        format_available: ['compressed', 'detailed'],
+        tier: flags.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,
+    };
+    // 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 : resolvedTopic(flags)}`,
+        compressed,
+        detailed,
+        provenance: `Imported via agent-supplied research at ${currentTime.toISOString()}`,
+    });
+}

package/dist/lib/research/keywords.js

@@ -2,6 +2,7 @@
 // supplies no tags. This is a deliberately simple term-frequency heuristic.
 // ponytail: TF + stopwords + heading boost. Ceiling: no phrase/entity detection, English-only
 // stopwords. Upgrade path: swap in RAKE/YAKE or an LLM pass behind the same extractKeywords() API.
+import { stripSecrets } from './secret-scan.js';
 const AUTO_TAG_NOTE = 'auto-generated tags via keyword extraction';
 // Common English function words plus a few markdown/doc-noise words. Kept inline (no dependency)
 // because the list is small and stable.
@@ -151,7 +152,10 @@ export function tokenize(text) {
     return raw.map((w) => w.replace(/^[.\-]+|[.\-]+$/g, '')).filter(Boolean);
 }
 function cleanNoise(text) {
-    return text
+    // Strip secrets before code fences/URLs so a credential embedded in either still gets caught —
+    // and before tokenize() lowercases/splits the text, which would hide case-sensitive or
+    // underscore-anchored secret patterns (AKIA…, ghp_…, AIza…) from detection.
+    return stripSecrets(text)
         .replace(/```[\s\S]*?```/g, ' ')
         .replace(/`[^`]*`/g, ' ')
         .replace(/https?:\/\/\S+/g, ' ');

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

@@ -1,6 +1,17 @@
+/**
+ * Drops empty anchor links (e.g. `[](url)`) from Markdown. These arise from icon-only heading
+ * permalinks and ReadMe query-param chips that carry no text content, wasting tokens.
+ * Images (`![](url)`) are intentionally not matched.
+ *
+ * @param markdown - Markdown text to clean.
+ * @returns Markdown with text-less links removed.
+ */
+export declare function dropEmptyLinks(markdown: string): string;
 /**
  * Converts HTML content to clean, deterministic Markdown.
  * Configured to use ATX-style headings (#) and fenced code blocks (```), with GFM tables.
+ *
+ * @param html - HTML string to convert.
+ * @returns Clean Markdown with empty links stripped.
  */
-export declare function dropEmptyLinks(markdown: string): string;
 export declare function htmlToMarkdown(html: string): string;