@dinoxx/dinox-cli 2.13.1 → 2.15.0

package/dist/commands/notes/detailContent.js

@@ -0,0 +1,62 @@
+import { DinoxError } from '../../utils/errors.js';
+const CONTENT_FIELDS = { md: 'content_md', text: 'content_text', json: 'content_json' };
+/** Fields that --max-chars shortens; content_json is a document and is never cut. */
+const TRUNCATABLE_FIELDS = ['content_md', 'content_text'];
+/** Parses `--content md,text,json|none` (default: all three, as before). */
+export function parseNoteContentShape(content, maxChars) {
+    let formats = new Set(['md', 'text', 'json']);
+    if (content !== undefined) {
+        const requested = String(content).split(',').map((value) => value.trim().toLowerCase()).filter(Boolean);
+        formats = new Set();
+        for (const value of requested) {
+            if (value === 'none' && requested.length === 1)
+                break;
+            if (!(value in CONTENT_FIELDS)) {
+                throw new DinoxError(`Invalid --content value: ${value}`, {
+                    code: 'INVALID_ARGUMENT',
+                    recoverable: true,
+                    suggestion: 'Use a comma-separated list of md, text, json, or none.',
+                });
+            }
+            formats.add(value);
+        }
+        if (requested.length === 0) {
+            throw new DinoxError('--content needs md, text, json, or none', { code: 'INVALID_ARGUMENT', recoverable: true });
+        }
+    }
+    let limit = null;
+    if (maxChars !== undefined) {
+        limit = Number(maxChars);
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new DinoxError('--max-chars must be a positive integer', { code: 'INVALID_ARGUMENT', recoverable: true });
+        }
+    }
+    return { formats, maxChars: limit };
+}
+/**
+ * Keeps the requested content fields and shortens Markdown / plain text to
+ * `maxChars` characters (whole code points). `content_truncated` reports
+ * whether anything was cut, so an agent knows to fetch more.
+ */
+export function shapeNoteContent(note, shape) {
+    const shaped = { ...note };
+    for (const [format, field] of Object.entries(CONTENT_FIELDS)) {
+        if (!shape.formats.has(format))
+            delete shaped[field];
+    }
+    if (shape.maxChars === null)
+        return shaped;
+    let truncated = false;
+    for (const field of TRUNCATABLE_FIELDS) {
+        const value = shaped[field];
+        if (typeof value !== 'string')
+            continue;
+        const characters = Array.from(value);
+        if (characters.length <= shape.maxChars)
+            continue;
+        shaped[field] = characters.slice(0, shape.maxChars).join('');
+        truncated = true;
+    }
+    shaped.content_truncated = truncated;
+    return shaped;
+}

package/dist/commands/notes/export.js

@@ -3,9 +3,11 @@ import path from 'node:path';
 import { stringify as stringifyYaml } from 'yaml';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printHumanReadableBlock, printSuccess, toJson, } from '../../utils/output.js';
+import { reportProgress } from '../../utils/progress.js';
 import { commandStale, } from '../runtime.js';
 import { getNoteExportItems, } from './repo.js';
 import { parseTargetNoteIds, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
+import { resolveUserPath } from '../../utils/requestContext.js';
 export function parseExportFormat(value) {
     if (value === undefined || value === null || value === '') {
         return 'markdown';
@@ -107,7 +109,7 @@ async function pathExists(filePath) {
 }
 async function resolveOutputTargets(args) {
     const outputLooksLikeDirectory = /[\\/]$/.test(args.outputPath);
-    const outputPath = path.resolve(args.outputPath);
+    const outputPath = resolveUserPath(args.outputPath);
     if (args.notes.length === 1) {
         if (outputLooksLikeDirectory) {
             return [{
@@ -160,12 +162,13 @@ export async function writeExportFiles(args) {
         }
     }
     if (args.notes.length > 1) {
-        await fs.mkdir(path.resolve(args.outputPath), { recursive: true, mode: 0o700 });
+        await fs.mkdir(resolveUserPath(args.outputPath), { recursive: true, mode: 0o700 });
     }
     else {
         await fs.mkdir(path.dirname(targets[0].path), { recursive: true, mode: 0o700 });
     }
     const noteById = new Map(args.notes.map((note) => [note.id, note]));
+    let written = 0;
     for (const target of targets) {
         const note = noteById.get(target.id);
         if (!note) {
@@ -182,6 +185,7 @@ export async function writeExportFiles(args) {
         if (process.platform !== 'win32') {
             await fs.chmod(target.path, 0o600);
         }
+        reportProgress({ phase: 'write', current: ++written, total: targets.length });
     }
     return targets;
 }
@@ -202,6 +206,7 @@ export async function runNoteExport({ command, options, args }) {
         const { db } = runtime;
         await syncBeforeNoteCommand(runtime);
         const ids = await parseTargetNoteIds(args.id, exportOptions.ids, 'detail');
+        reportProgress({ phase: 'read', total: ids.length });
         const notes = await getNoteExportItems(db, ids);
         assertNoMissingNotes(ids, notes);
         assertActiveNotes(notes, Boolean(exportOptions.includeDeleted));

package/dist/commands/notes/repo/search.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
-import { type SearchNotesOptions, type SearchedNote } from './shared.js';
+import { type SearchNotesOptions, type SearchResultRow, type SearchedNote } from './shared.js';
 /**
  * JSON-safe note-search request. Box *names/paths* are carried (not resolved ids) so the
  * same payload can be executed either in-process or sent to the daemon over the wire;
@@ -39,4 +39,5 @@ type SearchNotesPageResult = {
     totalCount: number;
 };
 export declare function searchNotesPage(db: AbstractPowerSyncDatabase, query: string, options: SearchNotesPageOptions): Promise<SearchNotesPageResult>;
+export declare function enrichSearchRows(db: AbstractPowerSyncDatabase, rows: SearchResultRow[]): Promise<SearchedNote[]>;
 export {};

package/dist/commands/notes/repo/search.js

@@ -196,7 +196,7 @@ function appendPaginationParams(params, limit, offset) {
     }
     return [...params, limit, offset ?? 0];
 }
-async function enrichSearchRows(db, rows) {
+export async function enrichSearchRows(db, rows) {
     const allBoxIds = Array.from(new Set(rows.flatMap((row) => parseZettelBoxIds(row.zettel_boxes))));
     const boxNameMap = await loadZettelBoxNameMap(db, allBoxIds);
     return rows.map((row) => {

package/dist/commands/notes/repo/semantic.d.ts

@@ -0,0 +1,14 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { SearchedNote } from './shared.js';
+export type LocalNoteLookup = {
+    /** Live notes found in the local cache, by id. */
+    live: Map<string, SearchedNote>;
+    /** Ids the local cache knows to be deleted. */
+    deleted: Set<string>;
+};
+/**
+ * Looks up remote search hits in the local cache: live notes get the same
+ * fields as `note search`; deleted ones are reported so the caller can drop
+ * them. Ids missing locally appear in neither (not synced yet).
+ */
+export declare function lookupLocalNotes(db: AbstractPowerSyncDatabase, ids: string[]): Promise<LocalNoteLookup>;

package/dist/commands/notes/repo/semantic.js

@@ -0,0 +1,31 @@
+import { enrichSearchRows } from './search.js';
+const LOOKUP_CHUNK = 500;
+/**
+ * Looks up remote search hits in the local cache: live notes get the same
+ * fields as `note search`; deleted ones are reported so the caller can drop
+ * them. Ids missing locally appear in neither (not synced yet).
+ */
+export async function lookupLocalNotes(db, ids) {
+    const unique = Array.from(new Set(ids.filter(Boolean)));
+    const live = new Map();
+    const deleted = new Set();
+    for (let start = 0; start < unique.length; start += LOOKUP_CHUNK) {
+        const chunk = unique.slice(start, start + LOOKUP_CHUNK);
+        const rows = await db.getAll(`
+      SELECT n.id, n.title, n.summary, n.content_text, n.tags, n.zettel_boxes, n.created_at, n.starred_at,
+        CASE WHEN n.starred_at IS NOT NULL THEN 1 ELSE 0 END AS is_starred,
+        n.is_del
+      FROM c_note n
+      WHERE n.id IN (${chunk.map(() => '?').join(', ')})
+      `, chunk);
+        const liveRows = rows.filter((row) => {
+            const isDeleted = row.is_del !== null && Number(row.is_del) !== 0;
+            if (isDeleted && row.id)
+                deleted.add(row.id);
+            return !isDeleted;
+        });
+        for (const note of await enrichSearchRows(db, liveRows))
+            live.set(note.id, note);
+    }
+    return { live, deleted };
+}

package/dist/commands/notes/searchResponse.d.ts

@@ -9,6 +9,8 @@ export type NoteSearchResponse = {
             limit: number | null;
             offset: number;
             has_more: boolean;
+            /** Opaque token for the next page (`--cursor`); null on the last page. */
+            next_cursor: string | null;
         };
         fields: NoteSearchField[] | null;
         applied_filters: {
@@ -36,6 +38,7 @@ export type BuildNoteSearchResponseInput = {
     includeDeleted: boolean;
     limit?: number;
     offset?: number;
+    nextCursor?: (nextOffset: number) => string;
     fields?: NoteSearchField[];
     tagsExpression?: string;
     createdAtFrom?: string;

package/dist/commands/notes/searchResponse.js

@@ -32,6 +32,7 @@ export function buildNoteSearchResponse(input) {
                 limit,
                 offset,
                 has_more: hasMore,
+                next_cursor: hasMore && input.nextCursor ? input.nextCursor(offset + returnedCount) : null,
             },
             fields: input.fields && input.fields.length > 0 ? [...input.fields] : null,
             applied_filters: {

package/dist/commands/notes/semantic.d.ts

@@ -0,0 +1,116 @@
+import type { CommandExecutionContext } from '../descriptor/types.js';
+import { type LocalNoteLookup } from './repo/semantic.js';
+export declare const SEMANTIC_MODES: {
+    readonly hybrid: "hybrid";
+    readonly semantic: "semantic";
+    readonly keyword: "fts";
+};
+export type SemanticMode = keyof typeof SEMANTIC_MODES;
+export declare const SEMANTIC_LIMITS: {
+    readonly search: {
+        readonly default: 10;
+        readonly max: 60;
+    };
+    readonly similar: {
+        readonly default: 6;
+        readonly max: 20;
+    };
+    readonly contextTopK: {
+        readonly default: 12;
+        readonly max: 60;
+    };
+    readonly contextGroups: {
+        readonly default: 6;
+        readonly max: 20;
+    };
+    readonly contextTokens: {
+        readonly default: 2400;
+        readonly max: 16000;
+    };
+};
+type RagxAnchor = {
+    sourceType?: string | null;
+    sourceId?: string | null;
+};
+type RagxGroup = {
+    kind?: string | null;
+    id?: string | null;
+};
+export type RagxHit = {
+    anchor?: RagxAnchor | null;
+    group?: RagxGroup | null;
+    docTitle?: string | null;
+    sectionTitle?: string | null;
+    headingPath?: string[] | null;
+    snippet?: string | null;
+    scores?: {
+        final?: number | null;
+    } | null;
+};
+export type RagxContextBlock = {
+    ref?: string | null;
+    group?: RagxGroup | null;
+    title?: string | null;
+    retrievalRole?: string | null;
+    content?: string | null;
+    score?: number | null;
+    tokenCount?: number | null;
+    citations?: Array<{
+        anchor?: RagxAnchor | null;
+    }> | null;
+};
+export type SemanticNote = {
+    id: string;
+    title: string;
+    tags: string[];
+    boxes: string[];
+    created_at: string | null;
+    is_starred: boolean;
+    score: number | null;
+    section: string | null;
+    heading_path: string[];
+    snippet: string;
+    /** Whether the best match came from the note itself or from an attachment. */
+    matched_source: 'note' | 'resource';
+    /** Chunks of this note among the hits. */
+    matches: number;
+    /** False when the note is not in the local cache yet (fields come from the index). */
+    in_local_cache: boolean;
+};
+export type SemanticFilters = {
+    tags?: string[];
+    cardboxIds?: string[];
+    startDateTime?: string;
+    endDateTime?: string;
+    endExclusive?: false;
+};
+export declare function parseSemanticMode(value: unknown): SemanticMode;
+/**
+ * Folds ranked chunk hits into one entry per note (keeping the best chunk),
+ * fills in local fields, and drops notes the local cache knows are deleted.
+ */
+export declare function mergeHitsIntoNotes(hits: RagxHit[], lookup: LocalNoteLookup, limit: number): {
+    notes: SemanticNote[];
+    droppedDeleted: number;
+};
+/** Context blocks with the note id surfaced and blocks of locally deleted notes removed. */
+export declare function shapeContextBlocks(blocks: RagxContextBlock[], lookup: LocalNoteLookup): {
+    blocks: {
+        ref: string | null;
+        note_id: string | null;
+        title: string;
+        role: string | null;
+        score: number | null;
+        token_count: number | null;
+        content: string;
+        citations: {
+            source_type: string;
+            source_id: string;
+        }[];
+    }[];
+    droppedDeleted: number;
+};
+export declare function runNoteSemantic(context: CommandExecutionContext): Promise<void>;
+export declare function runNoteSimilar(context: CommandExecutionContext): Promise<void>;
+export declare function runNoteContext(context: CommandExecutionContext): Promise<void>;
+export {};

package/dist/commands/notes/semantic.js

@@ -0,0 +1,332 @@
+import { postRagx } from '../../ai/ragxClient.js';
+import { AI_SERVICE_URL } from '../../config/serviceEndpoints.js';
+import { DinoxError } from '../../utils/errors.js';
+import { clearPendingStructuredNoticeProvider, getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, setPendingStructuredNoticeProvider, } from '../../utils/output.js';
+import { commandStale, printStaleCacheWarning, syncBeforeCommand } from '../runtime.js';
+import { resolveZettelBoxIdsForSearch } from './repo/resolve.js';
+import { lookupLocalNotes } from './repo/semantic.js';
+import { parseSearchListInput, withNoteDatabase } from './runtime.js';
+import { parseCreatedAtRange } from './searchTime.js';
+const SEARCH_TIMEOUT_MS = 20_000;
+const CONTEXT_TIMEOUT_MS = 45_000;
+export const SEMANTIC_MODES = { hybrid: 'hybrid', semantic: 'semantic', keyword: 'fts' };
+export const SEMANTIC_LIMITS = {
+    search: { default: 10, max: 60 },
+    similar: { default: 6, max: 20 },
+    contextTopK: { default: 12, max: 60 },
+    contextGroups: { default: 6, max: 20 },
+    contextTokens: { default: 2_400, max: 16_000 },
+};
+function boundedInteger(value, flag, limits) {
+    if (value === undefined || value === null || value === '')
+        return limits.default;
+    const parsed = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > limits.max) {
+        throw new DinoxError(`${flag} must be an integer from 1 to ${limits.max}`, { code: 'INVALID_ARGUMENT', recoverable: true });
+    }
+    return parsed;
+}
+export function parseSemanticMode(value) {
+    const mode = typeof value === 'string' && value.trim() ? value.trim().toLowerCase() : 'hybrid';
+    if (!Object.prototype.hasOwnProperty.call(SEMANTIC_MODES, mode)) {
+        throw new DinoxError(`--mode must be one of: ${Object.keys(SEMANTIC_MODES).join(', ')}`, {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+        });
+    }
+    return mode;
+}
+function assertOnline(globals, command) {
+    if (globals.offline) {
+        throw new DinoxError(`${command} queries the Dinox semantic index online and cannot run with --offline`, {
+            code: 'USAGE_ERROR',
+            recoverable: true,
+            suggestion: 'Drop --offline, or use `dino note search <query> --offline --format json` for local keyword search.',
+        });
+    }
+}
+/** Resolves tag, box and date options into the backend's rag-filter-v1 fields. */
+async function resolveFilters(runtime, options) {
+    const tags = typeof options.tags === 'string' ? (await parseSearchListInput(options.tags, '--tags')).values : [];
+    const boxNames = typeof options.boxes === 'string' ? (await parseSearchListInput(options.boxes, '--boxes')).values : [];
+    const { createdAtFrom, createdAtTo } = parseCreatedAtRange({ from: options.from, to: options.to, days: options.days });
+    const cardboxIds = boxNames.length > 0 ? await resolveZettelBoxIdsForSearch(runtime.db, boxNames) : [];
+    return {
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(cardboxIds.length > 0 ? { cardboxIds } : {}),
+        // Local ranges end at an inclusive instant (end of day or now).
+        ...(createdAtFrom ? { startDateTime: createdAtFrom } : {}),
+        ...(createdAtTo ? { endDateTime: createdAtTo, endExclusive: false } : {}),
+    };
+}
+function noteIdOf(group) {
+    return group?.kind === 'note' && typeof group.id === 'string' && group.id ? group.id : null;
+}
+/**
+ * Folds ranked chunk hits into one entry per note (keeping the best chunk),
+ * fills in local fields, and drops notes the local cache knows are deleted.
+ */
+export function mergeHitsIntoNotes(hits, lookup, limit) {
+    const byId = new Map();
+    const dropped = new Set();
+    for (const hit of hits) {
+        const id = noteIdOf(hit.group);
+        if (!id)
+            continue;
+        if (lookup.deleted.has(id)) {
+            dropped.add(id);
+            continue;
+        }
+        const existing = byId.get(id);
+        if (existing) {
+            existing.matches += 1;
+            continue;
+        }
+        const local = lookup.live.get(id);
+        byId.set(id, {
+            id,
+            title: local?.title ?? hit.docTitle ?? '',
+            tags: local?.tags ?? [],
+            boxes: local?.zettel_boxes ?? [],
+            created_at: local?.created_at ?? null,
+            is_starred: local?.is_starred ?? false,
+            score: typeof hit.scores?.final === 'number' ? hit.scores.final : null,
+            section: hit.sectionTitle ?? null,
+            heading_path: Array.isArray(hit.headingPath) ? hit.headingPath : [],
+            snippet: hit.snippet ?? '',
+            matched_source: hit.anchor?.sourceType === 'resource' ? 'resource' : 'note',
+            matches: 1,
+            in_local_cache: Boolean(local),
+        });
+    }
+    return { notes: [...byId.values()].slice(0, limit), droppedDeleted: dropped.size };
+}
+/** Context blocks with the note id surfaced and blocks of locally deleted notes removed. */
+export function shapeContextBlocks(blocks, lookup) {
+    let droppedDeleted = 0;
+    const shaped = [];
+    for (const block of blocks) {
+        const noteId = noteIdOf(block.group);
+        if (noteId && lookup.deleted.has(noteId)) {
+            droppedDeleted += 1;
+            continue;
+        }
+        shaped.push({
+            ref: block.ref ?? null,
+            note_id: noteId,
+            title: (noteId ? lookup.live.get(noteId)?.title : undefined) ?? block.title ?? '',
+            role: block.retrievalRole ?? null,
+            score: typeof block.score === 'number' ? block.score : null,
+            token_count: typeof block.tokenCount === 'number' ? block.tokenCount : null,
+            content: block.content ?? '',
+            citations: (block.citations ?? [])
+                .map((citation) => citation.anchor)
+                .filter((anchor) => Boolean(anchor?.sourceType && anchor.sourceId))
+                .map((anchor) => ({ source_type: anchor.sourceType, source_id: anchor.sourceId })),
+        });
+    }
+    return { blocks: shaped, droppedDeleted };
+}
+/** Pending uploads have not reached the server index yet; say so instead of implying absence. */
+async function indexLagNotice(runtime) {
+    let pending = 0;
+    try {
+        pending = (await runtime.db.getUploadQueueStats(false)).count;
+    }
+    catch {
+        return null;
+    }
+    if (pending === 0)
+        return null;
+    return {
+        index_may_lag: {
+            message: 'Local changes are still uploading, so the semantic index may miss recent notes or edits. Absence from these results is not proof a note does not exist; confirm with `dino note search`.',
+            upload_queue_remaining: pending,
+        },
+    };
+}
+/**
+ * Shared flow: refuse --offline, then query the service while the local cache
+ * finishes catching up (needed to enrich and filter hits), and attach the
+ * index-lag notice to whatever is printed.
+ */
+async function withSemanticRuntime(context, label, remote, print) {
+    assertOnline(context.globals, label);
+    await withNoteDatabase(context.command, async (runtime) => {
+        const [result] = await Promise.all([
+            remote({ runtime, baseUrl: AI_SERVICE_URL, authorization: runtime.config.auth.authorization }),
+            syncBeforeCommand(runtime),
+        ]);
+        const notice = await indexLagNotice(runtime);
+        setPendingStructuredNoticeProvider(() => notice);
+        try {
+            await print(result, runtime, commandStale(runtime));
+        }
+        finally {
+            clearPendingStructuredNoticeProvider();
+        }
+    });
+}
+function printNoteLines(notes, runtime) {
+    for (const note of notes) {
+        printHumanReadableLine(`${note.id}\t${note.score === null ? '-' : note.score.toFixed(3)}\t${note.title}`);
+    }
+    printStaleCacheWarning(runtime);
+}
+export async function runNoteSemantic(context) {
+    const query = context.args.query?.trim() ?? '';
+    if (!query)
+        throw new DinoxError('A search query is required', { code: 'INVALID_ARGUMENT', recoverable: true });
+    const mode = parseSemanticMode(context.options.mode);
+    const limit = boundedInteger(context.options.limit, '--limit', SEMANTIC_LIMITS.search);
+    const includeResources = Boolean(context.options.includeResources);
+    await withSemanticRuntime(context, 'note semantic', async ({ runtime, baseUrl, authorization }) => {
+        const filters = await resolveFilters(runtime, context.options);
+        const data = await postRagx({
+            baseUrl,
+            authorization,
+            path: '/api/ragx/search',
+            timeoutMs: SEARCH_TIMEOUT_MS,
+            body: {
+                query,
+                mode: SEMANTIC_MODES[mode],
+                filters: { sourceTypes: includeResources ? ['note', 'resource'] : ['note'], ...filters },
+                // Ask for extra chunks: several can fold into one note, and deleted notes are dropped.
+                options: { topK: Math.min(SEMANTIC_LIMITS.search.max, limit * 2), dedupBySource: true, returnDiagnostics: false },
+            },
+        });
+        const hits = data?.hits ?? [];
+        const lookup = await lookupLocalNotes(runtime.db, hits.map((hit) => noteIdOf(hit.group) ?? ''));
+        return { filters, ...mergeHitsIntoNotes(hits, lookup, limit) };
+    }, async ({ filters, notes, droppedDeleted }, runtime, stale) => {
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({
+                stale,
+                meta: {
+                    query,
+                    mode,
+                    returned_count: notes.length,
+                    limit,
+                    include_resources: includeResources,
+                    dropped_deleted_count: droppedDeleted,
+                    applied_filters: {
+                        tags: filters.tags ?? [],
+                        box_ids: filters.cardboxIds ?? [],
+                        created_at_range: filters.startDateTime || filters.endDateTime
+                            ? { from: filters.startDateTime ?? null, to: filters.endDateTime ?? null }
+                            : null,
+                    },
+                },
+                notes,
+            });
+            return;
+        }
+        printNoteLines(notes, runtime);
+    });
+}
+export async function runNoteSimilar(context) {
+    const noteId = context.args.id?.trim() ?? '';
+    if (!noteId)
+        throw new DinoxError('Note id is required', { code: 'INVALID_ARGUMENT', recoverable: true });
+    const limit = boundedInteger(context.options.limit, '--limit', SEMANTIC_LIMITS.similar);
+    await withSemanticRuntime(context, 'note similar', async ({ runtime, baseUrl, authorization }) => {
+        const anchor = await lookupLocalNotes(runtime.db, [noteId]);
+        if (anchor.deleted.has(noteId)) {
+            throw new DinoxError(`Note not found: ${noteId}`, {
+                code: 'NOTE_NOT_FOUND',
+                recoverable: true,
+                suggestion: "Run 'dino note search <keyword>' to locate the note id.",
+            });
+        }
+        let data;
+        try {
+            data = await postRagx({
+                baseUrl,
+                authorization,
+                path: '/api/ragx/similar',
+                timeoutMs: SEARCH_TIMEOUT_MS,
+                body: {
+                    anchor: { sourceType: 'note', sourceId: noteId },
+                    targetSourceTypes: ['note'],
+                    topK: limit,
+                    excludeSameSource: true,
+                    options: { returnDiagnostics: false },
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof DinoxError && error.code === 'NOT_FOUND') {
+                throw new DinoxError(`Note is not in the semantic index yet: ${noteId}`, {
+                    code: 'NOTE_NOT_FOUND',
+                    recoverable: true,
+                    suggestion: 'New or just-edited notes are indexed shortly after they upload; retry later, or use `dino graph related <id> --format json` for link-based neighbours.',
+                });
+            }
+            throw error;
+        }
+        const items = (data?.items ?? []).filter((item) => noteIdOf(item.group) !== noteId);
+        const lookup = await lookupLocalNotes(runtime.db, items.map((item) => noteIdOf(item.group) ?? ''));
+        return mergeHitsIntoNotes(items, lookup, limit);
+    }, async ({ notes, droppedDeleted }, runtime, stale) => {
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({
+                stale,
+                meta: { note_id: noteId, returned_count: notes.length, limit, dropped_deleted_count: droppedDeleted },
+                notes,
+            });
+            return;
+        }
+        printNoteLines(notes, runtime);
+    });
+}
+export async function runNoteContext(context) {
+    const query = context.args.query?.trim() ?? '';
+    if (!query)
+        throw new DinoxError('A question or query is required', { code: 'INVALID_ARGUMENT', recoverable: true });
+    const mode = parseSemanticMode(context.options.mode);
+    const topK = boundedInteger(context.options.limit, '--limit', SEMANTIC_LIMITS.contextTopK);
+    const maxGroups = boundedInteger(context.options.maxNotes, '--max-notes', SEMANTIC_LIMITS.contextGroups);
+    const maxTokens = boundedInteger(context.options.maxTokens, '--max-tokens', SEMANTIC_LIMITS.contextTokens);
+    const includeResources = !context.options.notesOnly;
+    await withSemanticRuntime(context, 'note context', async ({ runtime, baseUrl, authorization }) => {
+        const filters = await resolveFilters(runtime, context.options);
+        const data = await postRagx({
+            baseUrl,
+            authorization,
+            path: '/api/ragx/context',
+            timeoutMs: CONTEXT_TIMEOUT_MS,
+            body: {
+                query,
+                intent: 'answer',
+                filters: { sourceTypes: includeResources ? ['note', 'resource'] : ['note'], ...filters },
+                plan: { searchMode: SEMANTIC_MODES[mode] },
+                options: { topK, maxGroups, maxContextTokens: maxTokens, includeDiagnostics: false },
+            },
+        });
+        const blocks = data?.contextBlocks ?? [];
+        const lookup = await lookupLocalNotes(runtime.db, blocks.map((block) => noteIdOf(block.group) ?? ''));
+        return { data, ...shapeContextBlocks(blocks, lookup) };
+    }, async ({ data, blocks, droppedDeleted }, runtime, stale) => {
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({
+                stale,
+                meta: {
+                    query,
+                    mode,
+                    returned_count: blocks.length,
+                    context_tokens: typeof data?.contextTokens === 'number' ? data.contextTokens : null,
+                    max_tokens: maxTokens,
+                    dropped_deleted_count: droppedDeleted,
+                },
+                blocks,
+            });
+            return;
+        }
+        for (const block of blocks) {
+            printHumanReadableLine(`## ${block.title}${block.note_id ? ` (${block.note_id})` : ''}`);
+            printHumanReadableLine(block.content);
+            printHumanReadableLine('');
+        }
+        printStaleCacheWarning(runtime);
+    });
+}