@dinoxx/dinox-cli 2.14.0 → 2.16.0

package/dist/commands/notes/actions.js

@@ -1,4 +1,5 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
+import { encodeCursor, resolveCursorOffset } from '../../utils/cursor.js';
 import { canonicalizeBidlinksInMarkdown } from '../../utils/bidlinkCanonicalization.js';
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { generateId } from '../../utils/id.js';
@@ -17,6 +18,7 @@ import { buildNoteSearchResponse, normalizeDaysForMeta } from './searchResponse.
 import { parseMutationListInput, parseNoteType, parsePreviewLineCount, parseSearchLimit, parseSearchListInput, parseSearchOffset, parseStarredOption, parseStringInput, parseStringListInput, parseTargetNoteIds, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
 import { readNoteProperties } from '../properties/repo.js';
 import { createNoteWithSeed, previewNoteCreateProperties, resolveNoteCreateSeed } from './createFromTemplate.js';
+import { parseNoteContentShape, shapeNoteContent } from './detailContent.js';
 function toPublicNoteContext(note) {
     if (!note) {
         return null;
@@ -249,8 +251,20 @@ export async function runNoteSearch({ command, options, args, globals }) {
         : { values: [], isExplicitEmptyArray: false };
     const sqlExpression = typeof searchOptions.sql === 'string' ? searchOptions.sql.trim() : '';
     const limit = parseSearchLimit(searchOptions.limit);
-    const offset = parseSearchOffset(searchOptions.offset);
     const fields = parseNoteSearchFields(searchOptions.fields, '--fields');
+    // Raw option values, not the resolved range: `--days` must not change the hash between pages.
+    const cursorQuery = {
+        keyword,
+        includeDeleted: Boolean(searchOptions.includeDeleted),
+        tags: tagsExpression,
+        from: searchOptions.from,
+        to: searchOptions.to,
+        days: searchOptions.days,
+        starred,
+        boxes: boxInput,
+        sql: sqlExpression,
+    };
+    const offset = resolveCursorOffset(searchOptions.cursor, parseSearchOffset(searchOptions.offset), 'note.search', cursorQuery);
     const execParams = {
         keyword,
         includeDeleted: Boolean(searchOptions.includeDeleted),
@@ -278,6 +292,7 @@ export async function runNoteSearch({ command, options, args, globals }) {
         includeDeleted: Boolean(searchOptions.includeDeleted),
         limit,
         offset,
+        nextCursor: (nextOffset) => encodeCursor('note.search', nextOffset, cursorQuery),
         fields,
         tagsExpression: tagsExpression || undefined,
         createdAtFrom,
@@ -349,6 +364,7 @@ export async function runNotePreview({ command, options, args }) {
 }
 export async function runNoteDetail({ command, options, args }) {
     const detailOptions = options;
+    const contentShape = parseNoteContentShape(detailOptions.content, detailOptions.maxChars);
     await withNoteDatabase(command, async (runtime) => {
         const { db } = runtime;
         await syncBeforeNoteCommand(runtime);
@@ -359,7 +375,7 @@ export async function runNoteDetail({ command, options, args }) {
         if (missing.length > 0) {
             throw new DinoxError(ids.length === 1 ? `Note not found: ${missing[0]}` : `Notes not found: ${missing.join(', ')}`);
         }
-        const publicNotes = notes.map((note) => toPublicNoteDetail(note));
+        const publicNotes = notes.map((note) => shapeNoteContent(toPublicNoteDetail(note), contentShape));
         printSuccess({
             stale: commandStale(runtime),
             count: publicNotes.length,

package/dist/commands/notes/descriptors.js

@@ -1,11 +1,28 @@
 import { registerCommandGroup } from '../descriptor/register.js';
-import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, PROGRESS_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { WRITE_DURABILITY_OPTION } from '../writeDurability.js';
 import { runNoteCreate, runNoteDelete, runNoteDetail, runNoteGet, runNoteMove, runNotePreview, runNoteSearch, runNoteStar, runNoteTag, runNoteUnstar, runNoteUpdate, } from './actions.js';
 import { runNoteBulk as runNoteBulkAction } from './bulk.js';
 import { runNoteContentRead, runNotePatch } from './contentPatchCommand.js';
 import { runNoteExport } from './export.js';
+import { runNoteContext, runNoteSemantic, runNoteSimilar, SEMANTIC_LIMITS } from './semantic.js';
 const NOTE_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
+// Semantic commands query the online index; they refuse --offline.
+const NOTE_SEMANTIC_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
+const SEMANTIC_FILTER_OPTIONS = [
+    { flags: '--tags <string|@file>', description: 'Only notes with all these tags (JSON array or comma list; child tags included)', type: 'string' },
+    { flags: '--boxes <string|@file>', description: 'Only notes in any of these box paths or unique names (JSON array or comma list)', type: 'string' },
+    { flags: '--from <date>', description: 'created_at start (YYYY-MM-DD or ISO datetime)', type: 'string' },
+    { flags: '--to <date>', description: 'created_at end (YYYY-MM-DD or ISO datetime)', type: 'string' },
+    { flags: '--days <n>', description: 'Recent N days by created_at; mutually exclusive with --from/--to', type: 'number' },
+];
+const SEMANTIC_MODE_OPTION = {
+    flags: '--mode <mode>',
+    description: 'hybrid (meaning + keywords, default), semantic (meaning only), or keyword',
+    type: 'string',
+    enum: ['hybrid', 'semantic', 'keyword'],
+};
+const SEMANTIC_NOTE_FIELDS = ['id', 'title', 'tags', 'boxes', 'created_at', 'is_starred', 'score', 'section', 'heading_path', 'snippet', 'matched_source', 'matches', 'in_local_cache'];
 const NOTE_WRITE_RECEIPT_FIELDS = [
     'durability',
     'upload_queue_remaining',
@@ -42,6 +59,7 @@ export const noteCommandGroup = {
                 { flags: '--sql <expr>', description: 'SQL-like expression over id/content_md/summary/tags/zettel_boxes/created_at/type/is_starred', type: 'string' },
                 { flags: '--limit <n>', description: 'Maximum returned notes', type: 'number' },
                 { flags: '--offset <n>', description: 'Result offset for pagination', type: 'number', defaultValue: 0 },
+                { flags: '--cursor <token>', description: 'Continue from meta.pagination.next_cursor of the previous page (same query)' },
                 { flags: '--fields <list>', description: 'Comma-separated fields: id,title,summary,tags,created_at,starred_at,boxes,is_starred', type: 'string[]' },
                 { flags: '--include-deleted', description: 'Include soft-deleted notes', type: 'boolean' },
             ],
@@ -60,10 +78,90 @@ export const noteCommandGroup = {
                 examples: [
                     'dino note search "AI" --days 7 --format json',
                     'dino note search --tags "(work OR life) AND NOT archived" --format json',
+                    'dino note search "AI" --cursor <meta.pagination.next_cursor> --format json',
                 ],
             },
             action: runNoteSearch,
         },
+        {
+            name: 'semantic',
+            description: 'Find notes by meaning through the Dinox semantic index (online)',
+            arguments: [{ syntax: '<query>', description: 'Natural-language query' }],
+            options: [
+                SEMANTIC_MODE_OPTION,
+                { flags: '--limit <n>', description: `Maximum returned notes (1-${SEMANTIC_LIMITS.search.max}, default ${SEMANTIC_LIMITS.search.default})`, type: 'number' },
+                ...SEMANTIC_FILTER_OPTIONS,
+                { flags: '--include-resources', description: 'Also match attachments (PDFs, images, web clips); hits report their parent note', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.semantic',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_SEMANTIC_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Notes ranked by semantic relevance, one entry per note with its best-matching snippet',
+                    entity: 'semantic_note',
+                    fields: SEMANTIC_NOTE_FIELDS,
+                    metaFields: ['query', 'mode', 'returned_count', 'limit', 'include_resources', 'dropped_deleted_count', 'applied_filters'],
+                },
+                examples: [
+                    'dino note semantic "how I planned the Q3 launch" --format json',
+                    'dino note semantic "sleep and productivity" --tags health --days 90 --limit 20 --format json',
+                ],
+            },
+            action: runNoteSemantic,
+        },
+        {
+            name: 'similar',
+            description: 'Find notes semantically similar to a note (online)',
+            arguments: [{ syntax: '<id>', description: 'Note id' }],
+            options: [
+                { flags: '--limit <n>', description: `Maximum returned notes (1-${SEMANTIC_LIMITS.similar.max}, default ${SEMANTIC_LIMITS.similar.default})`, type: 'number' },
+            ],
+            schema: {
+                path: 'note.similar',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_SEMANTIC_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Semantically similar notes, excluding the note itself',
+                    entity: 'semantic_note',
+                    fields: SEMANTIC_NOTE_FIELDS,
+                    metaFields: ['note_id', 'returned_count', 'limit', 'dropped_deleted_count'],
+                },
+                examples: ['dino note similar <id> --limit 10 --format json'],
+            },
+            action: runNoteSimilar,
+        },
+        {
+            name: 'context',
+            description: 'Assemble cited, token-budgeted context from notes to answer a question (online)',
+            arguments: [{ syntax: '<query>', description: 'Question to gather context for' }],
+            options: [
+                SEMANTIC_MODE_OPTION,
+                { flags: '--max-tokens <n>', description: `Context token budget (1-${SEMANTIC_LIMITS.contextTokens.max}, default ${SEMANTIC_LIMITS.contextTokens.default})`, type: 'number' },
+                { flags: '--max-notes <n>', description: `Maximum notes contributing blocks (1-${SEMANTIC_LIMITS.contextGroups.max}, default ${SEMANTIC_LIMITS.contextGroups.default})`, type: 'number' },
+                { flags: '--limit <n>', description: `Retrieved chunks before assembly (1-${SEMANTIC_LIMITS.contextTopK.max}, default ${SEMANTIC_LIMITS.contextTopK.default})`, type: 'number' },
+                ...SEMANTIC_FILTER_OPTIONS,
+                { flags: '--notes-only', description: 'Leave attachments out of the context', type: 'boolean' },
+            ],
+            schema: {
+                path: 'note.context',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: NOTE_SEMANTIC_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Context blocks (content with note id and citations) ready to ground an answer',
+                    fields: ['blocks.ref', 'blocks.note_id', 'blocks.title', 'blocks.role', 'blocks.score', 'blocks.token_count', 'blocks.content', 'blocks.citations'],
+                    metaFields: ['query', 'mode', 'returned_count', 'context_tokens', 'max_tokens', 'dropped_deleted_count'],
+                },
+                examples: ['dino note context "what did I decide about pricing?" --max-tokens 4000 --format json'],
+            },
+            action: runNoteContext,
+        },
         {
             name: 'get',
             description: 'Get lightweight note context by id without exposing full note content',
@@ -107,7 +205,11 @@ export const noteCommandGroup = {
             name: 'detail',
             description: 'Get full note details for one or more ids',
             arguments: [{ syntax: '[id]', description: 'Optional note id when reading a single note' }],
-            options: [{ flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' }],
+            options: [
+                { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--content <formats>', description: 'Content fields to return: comma-separated md,text,json, or none (default: all three)', type: 'string' },
+                { flags: '--max-chars <n>', description: 'Shorten content_md and content_text to n characters; sets content_truncated', type: 'number' },
+            ],
             schema: {
                 path: 'note.detail',
                 risk: 'read',
@@ -116,9 +218,13 @@ export const noteCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Ordered full-note collection with freshness metadata',
-                    fields: ['stale', 'count', 'notes.id', 'notes.title', 'notes.content_md', 'notes.content_text', 'notes.content_json', 'notes.properties', 'notes.is_pub', 'notes.starred_at', 'notes.is_starred', 'notes.tags', 'notes.boxes', 'notes.created_at', 'notes.updated_at', 'notes.is_del'],
+                    fields: ['stale', 'count', 'notes.id', 'notes.title', 'notes.content_md', 'notes.content_text', 'notes.content_json', 'notes.content_truncated', 'notes.properties', 'notes.is_pub', 'notes.starred_at', 'notes.is_starred', 'notes.tags', 'notes.boxes', 'notes.created_at', 'notes.updated_at', 'notes.is_del'],
                 },
-                examples: ['dino note detail <id> --format json', 'dino note detail --ids @/tmp/note-ids.txt --format json'],
+                examples: [
+                    'dino note detail <id> --format json',
+                    'dino note detail <id> --content md --max-chars 4000 --format json',
+                    'dino note detail --ids @/tmp/note-ids.txt --format json',
+                ],
             },
             action: runNoteDetail,
         },
@@ -137,7 +243,7 @@ export const noteCommandGroup = {
                 path: 'note.export',
                 risk: 'read',
                 auth: 'required',
-                globalOptions: NOTE_GLOBAL_OPTIONS,
+                globalOptions: [...NOTE_GLOBAL_OPTIONS, ...PROGRESS_OPTIONS],
                 output: {
                     type: 'structured',
                     summary: 'Export payload or file write acknowledgement for note backup/migration',

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

@@ -0,0 +1,19 @@
+declare const CONTENT_FIELDS: {
+    readonly md: "content_md";
+    readonly text: "content_text";
+    readonly json: "content_json";
+};
+type NoteContentFormat = keyof typeof CONTENT_FIELDS;
+export type NoteContentShape = {
+    formats: ReadonlySet<NoteContentFormat>;
+    maxChars: number | null;
+};
+/** Parses `--content md,text,json|none` (default: all three, as before). */
+export declare function parseNoteContentShape(content: unknown, maxChars: unknown): NoteContentShape;
+/**
+ * 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 declare function shapeNoteContent(note: Record<string, unknown>, shape: NoteContentShape): Record<string, unknown>;
+export {};

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,6 +3,7 @@ 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';
@@ -167,6 +168,7 @@ export async function writeExportFiles(args) {
         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) {
@@ -183,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;
 }
@@ -203,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 {};