@dinoxx/dinox-cli 2.13.1 → 2.15.0

package/dist/commands/boxes/index.js

@@ -1,3 +1,5 @@
+import { WRITE_DURABILITY_OPTION } from '../writeDurability.js';
+import { completeWrite, WRITE_RECEIPT_FIELDS } from '../writeReceipt.js';
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
@@ -5,7 +7,7 @@ import { buildBoxAddDryRunPreview, buildBoxMutationDryRunPreview } from '../writ
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { commandStale, printStaleCacheWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
+import { commandStale, printStaleCacheWarning, syncBeforeCommand, resolveWriteDurabilityForRuntime, withCommandRuntime, } from '../runtime.js';
 import { assertWriteConfirmationProvided, parseExpectedCount } from '../writeConfirmation.js';
 import { addBox, inspectAddBox, listBoxes } from './repo.js';
 import { getBoxStats, getBoxTree, inspectBoxCleanup, mergeBox, moveBox, renameBox, } from './operations.js';
@@ -54,6 +56,7 @@ async function runBoxAdd(context) {
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     await withCommandRuntime(context, async (runtime) => {
+        const durability = resolveWriteDurabilityForRuntime(runtime, context.options.durability);
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime, { syncTokenIndex: true });
         const description = typeof context.options.description === 'string' ? context.options.description : undefined;
@@ -77,8 +80,7 @@ async function runBoxAdd(context) {
             description,
             color,
         });
-        await waitForMutationUpload(runtime);
-        const payload = { ok: true, stale: commandStale(runtime), ...result };
+        const payload = { ok: true, ...(await completeWrite(runtime, durability)), ...result };
         if (structuredOutput) {
             printSuccess(payload);
             return;
@@ -89,9 +91,10 @@ async function runBoxAdd(context) {
 }
 async function withBoxWriteRuntime(context, run) {
     return withCommandRuntime(context, async (runtime) => {
+        const durability = resolveWriteDurabilityForRuntime(runtime, context.options.durability);
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime, { syncTokenIndex: true });
-        return run({ runtime, userId: identity.userId });
+        return run({ runtime, userId: identity.userId, durability });
     });
 }
 function requireArg(value, message) {
@@ -104,7 +107,7 @@ function requireArg(value, message) {
 async function runBoxRename(context) {
     const path = requireArg(context.args.path, 'Box path is required');
     const newName = requireArg(context.args.newName, 'New box name is required');
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await renameBox(runtime.db, { path, newName, userId }, { dryRun: Boolean(context.options.dryRun) });
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -119,8 +122,7 @@ async function runBoxRename(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxMove(context) {
@@ -129,7 +131,7 @@ async function runBoxMove(context) {
     if (!to) {
         throw new DinoxError('--to is required');
     }
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await moveBox(runtime.db, { path, to, userId }, { dryRun: Boolean(context.options.dryRun) });
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -144,8 +146,7 @@ async function runBoxMove(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxMerge(context) {
@@ -159,7 +160,7 @@ async function runBoxMerge(context) {
         expectedCount,
     };
     assertWriteConfirmationProvided('Box merge', writeOptions);
-    await withBoxWriteRuntime(context, async ({ runtime, userId }) => {
+    await withBoxWriteRuntime(context, async ({ runtime, userId, durability }) => {
         const result = await mergeBox(runtime.db, { from, to, userId }, writeOptions);
         if (dryRun) {
             printDryRunPreview(buildBoxMutationDryRunPreview({
@@ -180,8 +181,7 @@ async function runBoxMerge(context) {
             }), runtime);
             return;
         }
-        await waitForMutationUpload(runtime);
-        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+        printSuccess({ ok: true, ...(await completeWrite(runtime, durability)), ...result });
     });
 }
 async function runBoxCleanup(context) {
@@ -234,7 +234,7 @@ export const boxCommandGroup = {
                 { flags: '--name <string>', description: 'Box path (alternative to positional path)' },
                 { flags: '--description <string>', description: 'Box purpose/usage description' },
                 { flags: '--color <string>', description: 'Box color' },
-                { flags: '--dry-run', description: 'Preview the write without executing it' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' },
             ],
             schema: {
                 path: 'box.add',
@@ -244,7 +244,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Box creation acknowledgement',
-                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color', 'restored', 'createdNodes', 'restoredNodes', 'stale'],
+                    fields: ['id', 'name', 'path', 'parentId', 'description', 'color', 'restored', 'createdNodes', 'restoredNodes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box add "Work/Inbox" --description "用于存放待整理的想法和资料" --format json --dry-run'],
             },
@@ -291,7 +291,7 @@ export const boxCommandGroup = {
                 { syntax: '<path>', description: 'Existing box path' },
                 { syntax: '<new-name>', description: 'New leaf name' },
             ],
-            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            options: [WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' }],
             schema: {
                 path: 'box.rename',
                 risk: 'write',
@@ -300,7 +300,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box rename result',
-                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box rename "Work/Inbox" "Ideas" --format json --dry-run'],
             },
@@ -312,7 +312,7 @@ export const boxCommandGroup = {
             arguments: [{ syntax: '<path>', description: 'Existing box path' }],
             options: [
                 { flags: '--to <parent-path>', description: 'Target parent box path', required: true, type: 'string' },
-                { flags: '--dry-run', description: 'Preview the write without executing it' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it' },
             ],
             schema: {
                 path: 'box.move',
@@ -322,7 +322,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box move result',
-                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', 'stale'],
+                    fields: ['id', 'fromPath', 'toPath', 'updatedBoxes', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: ['dino box move "Inbox" --to "Work" --format json --dry-run'],
             },
@@ -338,7 +338,7 @@ export const boxCommandGroup = {
             options: [
                 { flags: '--expected-count <n>', description: 'Required for real writes; must equal source boxes plus notes affected', type: 'number' },
                 { flags: '--confirm', description: 'Required for real writes after reviewing a dry run', type: 'boolean' },
-                { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
+                WRITE_DURABILITY_OPTION, { flags: '--dry-run', description: 'Preview the write without executing it', type: 'boolean' },
             ],
             schema: {
                 path: 'box.merge',
@@ -348,7 +348,7 @@ export const boxCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Zettel box merge result',
-                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedBoxIds', 'updatedNotes', 'affectedCount', 'stale'],
+                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedBoxIds', 'updatedNotes', 'affectedCount', ...WRITE_RECEIPT_FIELDS],
                 },
                 examples: [
                     'dino box merge "Work/Inbox" "Work/Archive" --format json --dry-run',

package/dist/commands/doctor.d.ts

@@ -5,7 +5,7 @@ import { resolveConfig } from '../config/resolve.js';
 import type { ResolvedDinoxConfig } from '../config/types.js';
 import { shutdownDaemonForExclusiveAccess } from '../daemon/client.js';
 import { restartDaemonLocked } from '../daemon/index.js';
-import { acquireDaemonStartLock } from '../daemon/pid.js';
+import { acquireDaemonExclusiveIntentLock, acquireDaemonStartLock } from '../daemon/pid.js';
 import type { DaemonPidInfo } from '../daemon/pid.js';
 import { type DaemonPingResult } from '../daemon/types.js';
 import { connectPowerSync } from '../powersync/runtime.js';
@@ -89,6 +89,8 @@ type DoctorRuntime = {
     daemonBefore: DoctorDaemonSnapshot;
     daemonWasStopped: boolean;
     releaseDaemonStartLock: () => Promise<void>;
+    /** Held while doctor owns the database; see acquireDaemonExclusiveIntentLock. */
+    releaseIntentLock?: () => Promise<void>;
     daemonStartLockReleased: boolean;
     released: boolean;
 };
@@ -102,6 +104,7 @@ type DoctorPreparationDependencies = {
     resolveConfig: typeof resolveConfig;
     hydrateAuthIdentity: typeof hydrateResolvedAuthIdentity;
     acquireDaemonStartLock: typeof acquireDaemonStartLock;
+    acquireDaemonIntentLock: typeof acquireDaemonExclusiveIntentLock;
     captureDaemonSnapshot: typeof captureDaemonSnapshot;
     shutdownDaemon: typeof shutdownDaemonForExclusiveAccess;
     connectPowerSync: typeof connectPowerSync;

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@ import { loadConfig } from '../config/store.js';
 import { fingerprintDaemonRuntimeConfig, resolveConfig } from '../config/resolve.js';
 import { getDaemonInfo, isDaemonFresh, shutdownDaemonForExclusiveAccess } from '../daemon/client.js';
 import { restartDaemonLocked } from '../daemon/index.js';
-import { acquireDaemonStartLock, getDaemonSocketPath, isProcessRunning, readPid, } from '../daemon/pid.js';
+import { acquireDaemonExclusiveIntentLock, acquireDaemonStartLock, getDaemonSocketPath, isProcessRunning, readPid, } from '../daemon/pid.js';
 import { DEFAULT_DAEMON_PORT } from '../daemon/types.js';
 import { closePowerSyncAndReleaseOwner, connectPowerSync, getStatusSnapshot, waitForUploadQueueEmpty, } from '../powersync/runtime.js';
 import { inspectNoteTokenIndex, rebuildNoteTokenIndex, } from '../powersync/tokenIndex.js';
@@ -20,6 +20,7 @@ const doctorPreparationDependencies = {
     resolveConfig,
     hydrateAuthIdentity: hydrateResolvedAuthIdentity,
     acquireDaemonStartLock,
+    acquireDaemonIntentLock: acquireDaemonExclusiveIntentLock,
     captureDaemonSnapshot,
     shutdownDaemon: shutdownDaemonForExclusiveAccess,
     connectPowerSync,
@@ -39,6 +40,14 @@ function doctorTimeoutMs(globals, config) {
 export async function prepareDoctorRuntime(context, overrides = {}) {
     const dependencies = { ...doctorPreparationDependencies, ...overrides };
     const releaseDaemonStartLock = await dependencies.acquireDaemonStartLock(parseSyncTimeoutMs(context.globals.syncTimeout) ?? DEFAULT_DOCTOR_TIMEOUT_MS);
+    let releaseIntentLock;
+    const releaseIntent = async () => {
+        const release = releaseIntentLock;
+        releaseIntentLock = undefined;
+        await release?.().catch((error) => {
+            printHumanReadableWarning(`warning: failed to release daemon intent lock: ${errorMessage(error)}`);
+        });
+    };
     try {
         const rawConfig = await dependencies.loadConfig();
         const baseConfig = dependencies.resolveConfig(rawConfig);
@@ -56,6 +65,7 @@ export async function prepareDoctorRuntime(context, overrides = {}) {
                 authError = errorMessage(error);
             }
         }
+        releaseIntentLock = await dependencies.acquireDaemonIntentLock(timeoutMs);
         const daemonBefore = await dependencies.captureDaemonSnapshot();
         const daemonDbPath = daemonBefore.info ? getPowerSyncDbPath(daemonBefore.info.userId) : null;
         const targetDbPath = getPowerSyncDbPath(config.auth.userId);
@@ -83,6 +93,7 @@ export async function prepareDoctorRuntime(context, overrides = {}) {
                         daemonBefore,
                         daemonWasStopped,
                         releaseDaemonStartLock,
+                        releaseIntentLock,
                         daemonStartLockReleased: false,
                         released: false,
                     };
@@ -109,16 +120,19 @@ export async function prepareDoctorRuntime(context, overrides = {}) {
                 daemonBefore,
                 daemonWasStopped,
                 releaseDaemonStartLock,
+                releaseIntentLock,
                 daemonStartLockReleased: false,
                 released: false,
             };
         }
         catch (error) {
+            await releaseIntent();
             await restoreStoppedDoctorDaemon(config, daemonBefore, daemonWasStopped, dependencies.restartDaemon);
             throw error;
         }
     }
     catch (error) {
+        await releaseIntent();
         await releaseDaemonStartLock().catch((releaseError) => {
             printHumanReadableWarning(`warning: failed to release daemon lifecycle lock: ${errorMessage(releaseError)}`);
         });
@@ -357,6 +371,11 @@ export async function releaseDoctorRuntime(runtime) {
     }
     await closePowerSyncAndReleaseOwner(runtime.db, runtime.releaseOwner);
     runtime.released = true;
+    const releaseIntentLock = runtime.releaseIntentLock;
+    runtime.releaseIntentLock = undefined;
+    await releaseIntentLock?.().catch((error) => {
+        printHumanReadableWarning(`warning: failed to release daemon intent lock: ${errorMessage(error)}`);
+    });
 }
 export async function releaseDoctorDaemonStartLock(runtime) {
     if (runtime.daemonStartLockReleased) {

package/dist/commands/graph/index.js

@@ -4,6 +4,7 @@ import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
 import { DinoxError } from '../../utils/errors.js';
 import { printSuccess } from '../../utils/output.js';
+import { localCommandExecution, requestContext } from '../../utils/requestContext.js';
 import { commandStale, syncBeforeCommand, withCommandRuntime } from '../runtime.js';
 import { getBacklinks, getGraphStats, getOutlinks, getRelatedNotes } from './repo.js';
 const GRAPH_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...REQUIRE_SYNC_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
@@ -26,7 +27,7 @@ function parseDepth(value) {
 }
 async function runGraphCommand(context, onlineAction, offlineAction) {
     const globals = context.globals;
-    if (Boolean(globals.offline) || Boolean(globals.requireSync)) {
+    if (requestContext.getStore()?.daemon || localCommandExecution.getStore() || Boolean(globals.offline) || Boolean(globals.requireSync)) {
         await withCommandRuntime(context, async (runtime) => {
             await syncBeforeCommand(runtime);
             printSuccess({

package/dist/commands/mcp.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { type McpCommandGroup } from '../gateway/mcpGroups.js';
+import type { CommandDescriptor } from './descriptor/types.js';
+export declare function parseMcpGroups(raw: unknown): McpCommandGroup[] | undefined;
+export declare const mcpCommandDescriptor: CommandDescriptor;
+export declare function registerMcpCommand(program: Command): void;

package/dist/commands/mcp.js

@@ -0,0 +1,47 @@
+import { MCP_COMMAND_GROUPS } from '../gateway/mcpGroups.js';
+import { DinoxError } from '../utils/errors.js';
+import { registerStandaloneCommand } from './descriptor/register.js';
+/** `--groups` names: the command group, with `stats` for meta.stats. */
+const GROUP_NAMES = new Map(MCP_COMMAND_GROUPS.map((group) => [group === 'meta.stats' ? 'stats' : group, group]));
+export function parseMcpGroups(raw) {
+    if (raw === undefined)
+        return undefined;
+    const names = String(raw).split(',').map((name) => name.trim().toLowerCase()).filter(Boolean);
+    const unknown = names.filter((name) => !GROUP_NAMES.has(name));
+    if (names.length === 0 || unknown.length > 0) {
+        throw new DinoxError(`--groups must list some of: ${[...GROUP_NAMES.keys()].join(', ')}`, {
+            code: 'INVALID_ARGUMENT',
+            recoverable: true,
+            details: { invalid: unknown, allowed: [...GROUP_NAMES.keys()] },
+        });
+    }
+    return [...new Set(names.map((name) => GROUP_NAMES.get(name)))];
+}
+async function runMcp(context) {
+    const groups = parseMcpGroups(context.options.groups);
+    const { serveStandaloneMcpOverStdio } = await import('../gateway/mcpServer.js');
+    await serveStandaloneMcpOverStdio({ readOnly: context.options.readOnly === true, groups });
+}
+export const mcpCommandDescriptor = {
+    name: 'mcp',
+    description: 'Serve Dinox commands as MCP tools over stdio for MCP clients (Claude Desktop, Cursor, ...)',
+    options: [
+        { flags: '--read-only', description: 'Expose only read actions', type: 'boolean' },
+        {
+            flags: '--groups <names>',
+            description: `Comma-separated tool groups to expose (${[...GROUP_NAMES.keys()].join(', ')}); default all`,
+        },
+    ],
+    schema: {
+        path: 'mcp',
+        risk: 'write',
+        auth: 'required',
+        globalOptions: [],
+        output: { type: 'structured', summary: 'MCP JSON-RPC over stdio until stdin closes', fields: [] },
+        examples: ['dino mcp', 'dino mcp --read-only --groups note,todo,graph'],
+    },
+    action: (context) => runMcp(context),
+};
+export function registerMcpCommand(program) {
+    registerStandaloneCommand(program, mcpCommandDescriptor);
+}

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/contentPatch.js

@@ -11,6 +11,7 @@ import { nowIsoUtc } from '../../utils/time.js';
 import { deriveImageDetailFromContentJson } from '../todo/contentModel.js';
 import { applyJsonPatchToDocument, buildNoteContentBlocks, buildNoteContentOutline, getNoteContentHash, parseStoredNoteDocument, projectNoteContent, } from './contentEngine.js';
 import { parseStoredTags } from './repo.js';
+import { resolveUserPath } from '../../utils/requestContext.js';
 const READ_TOKEN_TTL_MS = 30 * 60 * 1000;
 const MAX_STORED_READ_TOKENS = 500;
 const TOKEN_STORE_FILE = 'note-content-read-tokens.json';
@@ -111,7 +112,7 @@ async function loadTokenStore(nowMs = Date.now()) {
     const filePath = tokenStorePath();
     let tokens = [];
     try {
-        const raw = await fs.readFile(filePath, 'utf8');
+        const raw = await fs.readFile(resolveUserPath(filePath), 'utf8');
         const parsed = JSON.parse(raw);
         if (Array.isArray(parsed.tokens)) {
             tokens = parsed.tokens.filter((token) => typeof token?.token === 'string' &&

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 {};