@dinoxx/dinox-cli 2.1.1 → 2.3.0

package/dist/commands/savedViews/index.js

@@ -1,95 +1,65 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
-import { readStringOrFile } from '../../utils/argValue.js';
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
 import { registerCommandGroup } from '../descriptor/register.js';
+import { assertExclusive, parseIntegerOption, parseNonNegativeIntegerOption, parsePositiveIntegerOption, parseTimeZoneOption, readJsonOption, requiredArgument, } from '../domain/options.js';
 import { commandStale, printStaleCacheWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS, } from '../schema/globalOptions.js';
 import { WRITE_DURABILITY_OPTION } from '../writeDurability.js';
-import { validateSavedViewConfig, validateSavedViewFilter, } from './model.js';
-import { countSavedViewRows, createSavedView, deleteSavedView, getSavedView, getSavedViewFieldCatalog, inspectCreateSavedView, inspectDeleteSavedView, inspectUpdateSavedView, listSavedViews, querySavedView, updateSavedView, } from './repo.js';
+import { SAVED_VIEW_LAYOUTS, validateSavedViewConfig, validateSavedViewFilter, } from './model.js';
+import { countSavedViewRows, createSavedView, deleteSavedView, getNoteDetailSections, getSavedView, getSavedViewAnalytics, listSavedViewFields, listSavedViews, previewCreateSavedView, previewDeleteSavedView, previewUpdateSavedView, querySavedView, updateSavedView, } from './repo.js';
 const VIEW_GLOBAL_OPTIONS = [
     ...FORMAT_OPTIONS,
     ...OFFLINE_OPTIONS,
     ...REQUIRE_SYNC_OPTIONS,
     ...SYNC_TIMEOUT_OPTIONS,
 ];
-function parseIntegerOption(value) {
-    const normalized = value.trim();
-    if (!/^-?\d+$/.test(normalized)) {
-        throw new DinoxError('Expected an integer', { code: 'USAGE_ERROR' });
-    }
-    const parsed = Number(normalized);
-    if (!Number.isSafeInteger(parsed)) {
-        throw new DinoxError('Expected a safe integer', { code: 'USAGE_ERROR' });
-    }
-    return parsed;
-}
-function parsePositiveIntegerOption(value) {
-    const parsed = parseIntegerOption(value);
-    if (parsed <= 0)
-        throw new DinoxError('Expected a positive integer', { code: 'USAGE_ERROR' });
-    return parsed;
-}
-function parseNonNegativeIntegerOption(value) {
-    const parsed = parseIntegerOption(value);
-    if (parsed < 0)
-        throw new DinoxError('Expected a non-negative integer', { code: 'USAGE_ERROR' });
-    return parsed;
-}
-async function readJsonOption(value, label) {
-    let raw;
-    try {
-        raw = await readStringOrFile(value);
-    }
-    catch (error) {
-        throw new DinoxError(`Failed to read ${label}`, { code: 'USAGE_ERROR', cause: error });
-    }
-    try {
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        throw new DinoxError(`${label} must be valid JSON`, {
-            code: 'USAGE_ERROR',
-            cause: error,
-            suggestion: `Pass inline JSON or use @file. See \`dino schema view.create --format json\`.`,
-        });
-    }
-}
+const TIME_ZONE_OPTION = {
+    flags: '--time-zone <iana>',
+    description: 'IANA time zone for dynamic date filters (isToday, isThisWeek, withinLastDays); defaults to the system zone',
+    parser: parseTimeZoneOption,
+    type: 'string',
+};
+const LAYOUT_OPTION_DESCRIPTION = `View layout (${SAVED_VIEW_LAYOUTS.join(', ')}); overrides config.layout`;
 export async function parseSavedViewFilterOption(value) {
     if (value === undefined)
         return undefined;
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new DinoxError('--filter requires inline JSON or @file', { code: 'USAGE_ERROR' });
-    }
-    return validateSavedViewFilter(await readJsonOption(value, 'Saved view filter'));
+    return validateSavedViewFilter(await readJsonOption(value, '--filter', 'view.create'));
 }
 export async function parseSavedViewConfigOption(value) {
     if (value === undefined)
         return undefined;
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new DinoxError('--config requires inline JSON or @file', { code: 'USAGE_ERROR' });
+    return validateSavedViewConfig(await readJsonOption(value, '--config', 'view.create'));
+}
+function parseLayoutOption(value) {
+    const normalized = value.trim();
+    if (!SAVED_VIEW_LAYOUTS.includes(normalized)) {
+        throw new DinoxError(`--layout must be one of ${SAVED_VIEW_LAYOUTS.join(', ')}`, { code: 'USAGE_ERROR' });
     }
-    return validateSavedViewConfig(await readJsonOption(value, 'Saved view config'));
+    return normalized;
 }
-function requiredViewId(context) {
-    const id = context.args.id?.trim();
-    if (!id)
-        throw new DinoxError('Saved view id is required', { code: 'USAGE_ERROR' });
-    return id;
+function inspectionOutput(inspection) {
+    return {
+        view: inspection.view,
+        valid: inspection.valid,
+        ...(inspection.valid ? {} : { error: inspection.error }),
+    };
 }
-function assertExclusiveOptions(options) {
-    const conflicts = [
-        [Boolean(options.emoji !== undefined && options.clearEmoji), '--emoji cannot be used with --clear-emoji'],
-        [Boolean(options.templateId !== undefined && options.clearTemplate), '--template-id cannot be used with --clear-template'],
-        [Boolean(options.groupId !== undefined && options.clearGroup), '--group-id cannot be used with --clear-group'],
-        [Boolean(options.sortRank !== undefined && options.clearSortRank), '--sort-rank cannot be used with --clear-sort-rank'],
-        [Boolean(options.pinnedAt !== undefined && options.unpin), '--pinned-at cannot be used with --unpin'],
-    ];
-    const conflict = conflicts.find(([active]) => active);
-    if (conflict)
-        throw new DinoxError(conflict[1], { code: 'USAGE_ERROR' });
+function printPreview(command, action, summary, preview, runtime) {
+    const target = preview.before?.view ?? preview.after?.view;
+    printDryRunPreview({
+        dry_run: true,
+        command,
+        action,
+        risk: 'write',
+        summary,
+        ...(target ? { targets: [{ id: target.id, name: target.name }] } : {}),
+        changes: {
+            before: preview.before ? inspectionOutput(preview.before) : null,
+            after: preview.after ? inspectionOutput(preview.after) : null,
+        },
+    }, runtime);
 }
 async function runViewList(context) {
     const limit = context.options.limit;
@@ -102,7 +72,7 @@ async function runViewList(context) {
             return;
         }
         for (const view of views) {
-            printHumanReadableLine(`${view.id}\t${view.emoji ?? ''}\t${view.name}${view.valid ? '' : '\t[invalid]'}`);
+            printHumanReadableLine(`${view.id}\t${view.emoji ?? ''}\t${view.layout ?? ''}\t${view.name}${view.valid ? '' : '\t[invalid]'}`);
         }
         if (views.length === 0)
             printHumanReadableLine('No saved views found.');
@@ -110,19 +80,19 @@ async function runViewList(context) {
     });
 }
 async function runViewGet(context) {
-    const id = requiredViewId(context);
+    const id = requiredArgument(context.args.id, 'Saved view id');
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
-        const view = await getSavedView(runtime.db, { id, userId: identity.userId });
-        printSuccess({ ok: true, stale: commandStale(runtime), view });
+        const inspection = await getSavedView(runtime.db, { id, userId: identity.userId });
+        printSuccess({ ok: true, stale: commandStale(runtime), ...inspectionOutput(inspection) });
     });
 }
 async function runViewFields(context) {
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
-        const fields = await getSavedViewFieldCatalog(runtime.db, identity.userId);
+        const fields = await listSavedViewFields(runtime.db, identity.userId);
         if (getRequestedStructuredOutputFormat()) {
             printSuccess({ ok: true, stale: commandStale(runtime), count: fields.length, fields });
             return;
@@ -134,9 +104,10 @@ async function runViewFields(context) {
     });
 }
 async function runViewQuery(context) {
-    const viewId = requiredViewId(context);
+    const viewId = requiredArgument(context.args.id, 'Saved view id');
     const limit = context.options.limit;
     const offset = context.options.offset;
+    const timeZone = context.options.timeZone;
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
@@ -145,6 +116,7 @@ async function runViewQuery(context) {
             userId: identity.userId,
             limit,
             offset,
+            timeZone,
         });
         if (getRequestedStructuredOutputFormat()) {
             printSuccess({ ok: true, stale: commandStale(runtime), ...result });
@@ -158,11 +130,12 @@ async function runViewQuery(context) {
     });
 }
 async function runViewCount(context) {
-    const viewId = requiredViewId(context);
+    const viewId = requiredArgument(context.args.id, 'Saved view id');
+    const timeZone = context.options.timeZone;
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
-        const totalCount = await countSavedViewRows(runtime.db, { viewId, userId: identity.userId });
+        const totalCount = await countSavedViewRows(runtime.db, { viewId, userId: identity.userId, timeZone });
         if (getRequestedStructuredOutputFormat()) {
             printSuccess({ ok: true, stale: commandStale(runtime), viewId, totalCount });
             return;
@@ -171,134 +144,159 @@ async function runViewCount(context) {
         printStaleCacheWarning(runtime);
     });
 }
-async function runViewCreate(context) {
-    const options = context.options;
-    const name = options.name?.trim() ?? '';
-    if (!name)
-        throw new DinoxError('Saved view name is required. Use --name <string>.', { code: 'USAGE_ERROR' });
-    const [filter, config] = await Promise.all([
-        parseSavedViewFilterOption(options.filter),
-        parseSavedViewConfigOption(options.config),
-    ]);
+async function runViewAnalytics(context) {
+    const viewId = requiredArgument(context.args.id, 'Saved view id');
+    const timeZone = context.options.timeZone;
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
-        const input = {
-            userId: identity.userId,
-            name,
-            emoji: options.emoji,
-            filter,
-            config,
-            templateId: options.templateId,
-            groupId: options.groupId,
-            sortRank: options.sortRank,
-            pinnedAt: options.pinnedAt,
-        };
-        if (options.dryRun) {
-            const plan = await inspectCreateSavedView(runtime.db, input);
-            printDryRunPreview({
-                dry_run: true,
-                command: 'dino view create',
-                action: 'create_saved_view',
-                risk: 'write',
-                summary: `Create saved view "${name}".`,
-                inputs: { name, ...(filter ? { filter } : {}), ...(config ? { config } : {}) },
-                changes: plan.changes,
-            }, runtime);
+        const analytics = await getSavedViewAnalytics(runtime.db, { viewId, userId: identity.userId, timeZone });
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, stale: commandStale(runtime), viewId, ...analytics });
             return;
         }
-        const view = await createSavedView(runtime.db, input);
-        const receipt = await waitForMutationUpload(runtime, { durability: options.durability });
+        for (const stat of analytics.stats) {
+            printHumanReadableLine(`stat\t${stat.id}\t${stat.unavailable ? 'unavailable' : String(stat.value)}`);
+        }
+        for (const chart of analytics.charts) {
+            printHumanReadableLine(`chart\t${chart.id}\t${chart.unavailable ? 'unavailable' : `${chart.rows.length} rows`}`);
+        }
+        for (const item of analytics.summary) {
+            printHumanReadableLine(`summary\t${item.column}\t${item.aggregation}\t${item.unavailable ? 'unavailable' : String(item.value)}`);
+        }
+        if (analytics.stats.length + analytics.charts.length + analytics.summary.length === 0) {
+            printHumanReadableLine('This view has no stats, charts, or summary configured.');
+        }
+        printStaleCacheWarning(runtime);
+    });
+}
+async function runViewNoteDetail(context) {
+    const noteId = requiredArgument(context.args.noteId, 'Note id');
+    const limit = context.options.limit;
+    const timeZone = context.options.timeZone;
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime);
+        const sections = await getNoteDetailSections(runtime.db, { noteId, userId: identity.userId, limit, timeZone });
         if (getRequestedStructuredOutputFormat()) {
-            printSuccess({ ok: true, stale: commandStale(runtime), view, ...receipt });
+            printSuccess({ ok: true, stale: commandStale(runtime), noteId, count: sections.length, sections });
             return;
         }
-        printHumanReadableLine(view.id);
+        for (const section of sections) {
+            printHumanReadableLine(`${section.viewId}\t${section.emoji ?? ''}\t${section.name}\t${section.totalCount} notes`);
+            for (const row of section.rows)
+                printHumanReadableLine(`  ${row.id}\t${row.title ?? ''}`);
+        }
+        if (sections.length === 0)
+            printHumanReadableLine('No saved view embeds this note.');
         printStaleCacheWarning(runtime);
     });
 }
-async function runViewUpdate(context) {
-    const id = requiredViewId(context);
-    const options = context.options;
-    assertExclusiveOptions(options);
+async function readWriteInput(options) {
     const [filter, config] = await Promise.all([
         parseSavedViewFilterOption(options.filter),
         parseSavedViewConfigOption(options.config),
     ]);
-    const inputPatch = {
+    return {
         ...(options.name === undefined ? {} : { name: options.name }),
         ...(options.clearEmoji ? { emoji: null } : options.emoji === undefined ? {} : { emoji: options.emoji }),
         ...(filter === undefined ? {} : { filter }),
         ...(config === undefined ? {} : { config }),
+        ...(options.layout === undefined ? {} : { layout: parseLayoutOption(options.layout) }),
         ...(options.clearTemplate ? { templateId: null } : options.templateId === undefined ? {} : { templateId: options.templateId }),
         ...(options.clearGroup ? { groupId: null } : options.groupId === undefined ? {} : { groupId: options.groupId }),
         ...(options.clearSortRank ? { sortRank: null } : options.sortRank === undefined ? {} : { sortRank: options.sortRank }),
         ...(options.unpin ? { pinnedAt: null } : options.pinnedAt === undefined ? {} : { pinnedAt: options.pinnedAt }),
     };
+}
+async function runViewCreate(context) {
+    const options = context.options;
+    const name = options.name?.trim() ?? '';
+    if (!name)
+        throw new DinoxError('Saved view name is required. Use --name <string>.', { code: 'USAGE_ERROR' });
+    const patch = await readWriteInput(options);
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
-        const input = { id, userId: identity.userId, ...inputPatch };
+        const input = { ...patch, userId: identity.userId, name };
         if (options.dryRun) {
-            const plan = await inspectUpdateSavedView(runtime.db, input);
-            printDryRunPreview({
-                dry_run: true,
-                command: 'dino view update',
-                action: 'update_saved_view',
-                risk: 'write',
-                summary: `Update saved view "${plan.target?.name ?? id}".`,
-                targets: plan.target ? [{ id: plan.target.id, name: plan.target.name }] : undefined,
-                changes: plan.changes,
-            }, runtime);
+            const preview = await previewCreateSavedView(runtime.db, input);
+            printPreview('dino view create', 'create_saved_view', `Create saved view "${name}".`, preview, runtime);
             return;
         }
-        const view = await updateSavedView(runtime.db, input);
+        const inspection = await createSavedView(runtime.db, input);
         const receipt = await waitForMutationUpload(runtime, { durability: options.durability });
         if (getRequestedStructuredOutputFormat()) {
-            printSuccess({ ok: true, stale: commandStale(runtime), view, ...receipt });
+            printSuccess({ ok: true, stale: commandStale(runtime), ...inspectionOutput(inspection), ...receipt });
             return;
         }
-        printHumanReadableLine(view.id);
+        printHumanReadableLine(inspection.view.id);
+        printStaleCacheWarning(runtime);
+    });
+}
+async function runViewUpdate(context) {
+    const id = requiredArgument(context.args.id, 'Saved view id');
+    const options = context.options;
+    assertExclusive([
+        [options.emoji !== undefined && Boolean(options.clearEmoji), '--emoji cannot be used with --clear-emoji'],
+        [options.templateId !== undefined && Boolean(options.clearTemplate), '--template-id cannot be used with --clear-template'],
+        [options.groupId !== undefined && Boolean(options.clearGroup), '--group-id cannot be used with --clear-group'],
+        [options.sortRank !== undefined && Boolean(options.clearSortRank), '--sort-rank cannot be used with --clear-sort-rank'],
+        [options.pinnedAt !== undefined && Boolean(options.unpin), '--pinned-at cannot be used with --unpin'],
+    ]);
+    const patch = await readWriteInput(options);
+    if (Object.keys(patch).length === 0) {
+        throw new DinoxError('At least one saved-view field must be updated', { code: 'USAGE_ERROR' });
+    }
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime);
+        const input = { ...patch, id, userId: identity.userId };
+        if (options.dryRun) {
+            const preview = await previewUpdateSavedView(runtime.db, input);
+            printPreview('dino view update', 'update_saved_view', `Update saved view "${preview.before?.view.name ?? id}".`, preview, runtime);
+            return;
+        }
+        const inspection = await updateSavedView(runtime.db, input);
+        const receipt = await waitForMutationUpload(runtime, { durability: options.durability });
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, stale: commandStale(runtime), ...inspectionOutput(inspection), ...receipt });
+            return;
+        }
+        printHumanReadableLine(inspection.view.id);
         printStaleCacheWarning(runtime);
     });
 }
 async function runViewDelete(context) {
-    const id = requiredViewId(context);
+    const id = requiredArgument(context.args.id, 'Saved view id');
     const options = context.options;
     await withCommandRuntime(context, async (runtime) => {
         const identity = await resolveAuthIdentity(runtime.config);
         await syncBeforeCommand(runtime);
         const input = { id, userId: identity.userId };
         if (options.dryRun) {
-            const plan = await inspectDeleteSavedView(runtime.db, input);
-            printDryRunPreview({
-                dry_run: true,
-                command: 'dino view delete',
-                action: 'delete_saved_view',
-                risk: 'write',
-                summary: `Soft-delete saved view "${plan.target?.name ?? id}".`,
-                targets: plan.target ? [{ id: plan.target.id, name: plan.target.name }] : undefined,
-                changes: plan.changes,
-            }, runtime);
+            const preview = await previewDeleteSavedView(runtime.db, input);
+            printPreview('dino view delete', 'delete_saved_view', `Soft-delete saved view "${preview.before?.view.name ?? id}".`, preview, runtime);
             return;
         }
-        const view = await deleteSavedView(runtime.db, input);
+        const inspection = await deleteSavedView(runtime.db, input);
         const receipt = await waitForMutationUpload(runtime, { durability: options.durability });
         if (getRequestedStructuredOutputFormat()) {
-            printSuccess({ ok: true, stale: commandStale(runtime), deleted: true, view, ...receipt });
+            printSuccess({ ok: true, stale: commandStale(runtime), deleted: true, view: inspection.view, ...receipt });
             return;
         }
-        printHumanReadableLine(`Deleted ${view.id}`);
+        printHumanReadableLine(`Deleted ${inspection.view.id}`);
         printStaleCacheWarning(runtime);
     });
 }
+const WRITE_OUTPUT_FIELDS = ['view', 'valid', 'error', 'durability', 'upload_queue_remaining', 'stale'];
 export const savedViewCommandGroup = {
     name: 'view',
-    description: 'Manage and query saved table views',
+    description: 'Manage and query saved views (table, list, card) and their analytics',
     commands: [
         {
             name: 'list',
-            description: 'List active saved table views',
+            description: 'List active saved views',
             options: [
                 { flags: '--limit <n>', description: 'Maximum returned views (1-5000)', parser: parsePositiveIntegerOption, type: 'number', defaultValue: 200 },
             ],
@@ -307,28 +305,28 @@ export const savedViewCommandGroup = {
                 risk: 'read',
                 auth: 'required',
                 globalOptions: VIEW_GLOBAL_OPTIONS,
-                output: { type: 'structured', summary: 'Saved view catalog', fields: ['stale', 'count', 'views'] },
+                output: { type: 'structured', summary: 'Saved view catalog in desktop sidebar order; invalid rows are listed with valid=false', fields: ['stale', 'count', 'views'] },
                 examples: ['dino view list --format json'],
             },
             action: runViewList,
         },
         {
             name: 'get',
-            description: 'Get one saved view definition',
+            description: 'Get one saved view definition (stored rows the CLI cannot parse return valid=false with the raw JSON)',
             arguments: [{ syntax: '<id>', description: 'Saved view id' }],
             schema: {
                 path: 'view.get',
                 risk: 'read',
                 auth: 'required',
                 globalOptions: VIEW_GLOBAL_OPTIONS,
-                output: { type: 'structured', summary: 'Canonical saved view definition', fields: ['stale', 'view'] },
+                output: { type: 'structured', summary: 'Saved view definition with validity', fields: ['stale', 'view', 'valid', 'error'] },
                 examples: ['dino view get <id> --format json'],
             },
             action: runViewGet,
         },
         {
             name: 'fields',
-            description: 'List system and property fields available to saved views',
+            description: 'List system and property fields with their filter operators, sortability, and option ids',
             schema: {
                 path: 'view.fields',
                 risk: 'read',
@@ -346,14 +344,18 @@ export const savedViewCommandGroup = {
             options: [
                 { flags: '--limit <n>', description: 'Maximum returned notes (1-500)', parser: parsePositiveIntegerOption, type: 'number', defaultValue: 100 },
                 { flags: '--offset <n>', description: 'Result offset for pagination', parser: parseNonNegativeIntegerOption, type: 'number', defaultValue: 0 },
+                TIME_ZONE_OPTION,
             ],
             schema: {
                 path: 'view.query',
                 risk: 'read',
                 auth: 'required',
                 globalOptions: VIEW_GLOBAL_OPTIONS,
-                output: { type: 'structured', summary: 'Saved view page with projected configured columns', fields: ['stale', 'view', 'columns', 'totalCount', 'offset', 'limit', 'nextOffset', 'hasMore', 'rows'] },
-                examples: ['dino view query <id> --limit 50 --offset 0 --format json'],
+                output: { type: 'structured', summary: 'Saved view page with projected configured and computed columns', fields: ['stale', 'view', 'columns', 'totalCount', 'offset', 'limit', 'nextOffset', 'hasMore', 'rows'] },
+                examples: [
+                    'dino view query <id> --limit 50 --offset 0 --format json',
+                    'dino view query <id> --time-zone Asia/Shanghai --format json',
+                ],
             },
             action: runViewQuery,
         },
@@ -361,6 +363,7 @@ export const savedViewCommandGroup = {
             name: 'count',
             description: 'Count notes matching a saved view',
             arguments: [{ syntax: '<id>', description: 'Saved view id' }],
+            options: [TIME_ZONE_OPTION],
             schema: {
                 path: 'view.count',
                 risk: 'read',
@@ -371,44 +374,79 @@ export const savedViewCommandGroup = {
             },
             action: runViewCount,
         },
+        {
+            name: 'analytics',
+            description: 'Compute the stats, charts, and summary row configured on a saved view',
+            arguments: [{ syntax: '<id>', description: 'Saved view id' }],
+            options: [TIME_ZONE_OPTION],
+            schema: {
+                path: 'view.analytics',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: VIEW_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Aggregates over the full view scope (not the visible page)', fields: ['stale', 'viewId', 'stats', 'charts', 'summary', 'config'] },
+                examples: ['dino view analytics <id> --format json'],
+            },
+            action: runViewAnalytics,
+        },
+        {
+            name: 'note-detail',
+            description: 'List saved views embedded on a note (views with a noteDetail rule, $self bound to the note)',
+            arguments: [{ syntax: '<noteId>', description: 'Host note id' }],
+            options: [
+                { flags: '--limit <n>', description: 'Maximum rows per section (1-100)', parser: parsePositiveIntegerOption, type: 'number', defaultValue: 6 },
+                TIME_ZONE_OPTION,
+            ],
+            schema: {
+                path: 'view.note-detail',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: VIEW_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Note-detail sections with projected rows', fields: ['stale', 'noteId', 'count', 'sections'] },
+                examples: ['dino view note-detail <noteId> --format json'],
+            },
+            action: runViewNoteDetail,
+        },
         {
             name: 'create',
-            description: 'Create a canonical saved table view',
+            description: 'Create a saved view',
             options: [
                 { flags: '--name <string>', description: 'Saved view name', required: true, type: 'string' },
                 { flags: '--emoji <string>', description: 'Optional emoji or short icon text', type: 'string' },
-                { flags: '--filter <json|@file>', description: 'Canonical version 1 saved view filter JSON; defaults to no filter', type: 'string' },
-                { flags: '--config <json|@file>', description: 'Canonical version 1 saved view config JSON; defaults to title + updated_at', type: 'string' },
+                { flags: '--filter <json|@file>', description: 'Saved view filter JSON (version 1-3); defaults to no filter', type: 'string' },
+                { flags: '--config <json|@file>', description: 'Saved view config JSON (columns, sort, layout, noteDetail, stats, charts, computedColumns, summary); defaults to title + updated_at', type: 'string' },
+                { flags: '--layout <layout>', description: LAYOUT_OPTION_DESCRIPTION, type: 'string', enum: [...SAVED_VIEW_LAYOUTS] },
                 { flags: '--template-id <id>', description: 'Optional note template id associated with the view', type: 'string' },
                 { flags: '--group-id <id>', description: 'Optional saved view group id', type: 'string' },
-                { flags: '--sort-rank <n>', description: 'Explicit catalog sort rank', parser: parseIntegerOption, type: 'number' },
+                { flags: '--sort-rank <n>', description: 'Explicit catalog sort rank (defaults to the end of the sidebar)', parser: parseIntegerOption, type: 'number' },
                 { flags: '--pinned-at <timestamp>', description: 'Pinned timestamp', type: 'string' },
                 WRITE_DURABILITY_OPTION,
-                { flags: '--dry-run', description: 'Validate and preview the view without writing', type: 'boolean' },
+                { flags: '--dry-run', description: 'Validate and preview the stored view without writing', type: 'boolean' },
             ],
             schema: {
                 path: 'view.create',
                 risk: 'write',
                 auth: 'required',
                 globalOptions: VIEW_GLOBAL_OPTIONS,
-                output: { type: 'structured', summary: 'Created saved view definition or dry-run plan', fields: ['view', 'durability', 'upload_queue_remaining', 'stale'] },
+                output: { type: 'structured', summary: 'Created saved view definition or dry-run plan', fields: WRITE_OUTPUT_FIELDS },
                 examples: [
                     'dino view create --name "Recent notes" --format json --dry-run',
-                    'dino view create --name "Active projects" --filter @filter.json --config @config.json --format json',
+                    'dino view create --name "Reading list" --layout card --filter @filter.json --config @config.json --format json',
                 ],
             },
             action: runViewCreate,
         },
         {
             name: 'update',
-            description: 'Update a canonical saved table view',
+            description: 'Update a saved view; fields you do not pass are left as stored',
             arguments: [{ syntax: '<id>', description: 'Saved view id' }],
             options: [
                 { flags: '--name <string>', description: 'Replace the saved view name', type: 'string' },
                 { flags: '--emoji <string>', description: 'Replace emoji or short icon text', type: 'string' },
                 { flags: '--clear-emoji', description: 'Clear the saved view emoji', type: 'boolean' },
-                { flags: '--filter <json|@file>', description: 'Replace the canonical version 1 filter JSON', type: 'string' },
-                { flags: '--config <json|@file>', description: 'Replace the canonical version 1 config JSON', type: 'string' },
+                { flags: '--filter <json|@file>', description: 'Replace the filter JSON (version 1-3)', type: 'string' },
+                { flags: '--config <json|@file>', description: 'Replace the whole config JSON', type: 'string' },
+                { flags: '--layout <layout>', description: LAYOUT_OPTION_DESCRIPTION, type: 'string', enum: [...SAVED_VIEW_LAYOUTS] },
                 { flags: '--template-id <id>', description: 'Replace the associated note template id', type: 'string' },
                 { flags: '--clear-template', description: 'Clear the associated note template id', type: 'boolean' },
                 { flags: '--group-id <id>', description: 'Replace the saved view group id', type: 'string' },
@@ -418,16 +456,17 @@ export const savedViewCommandGroup = {
                 { flags: '--pinned-at <timestamp>', description: 'Replace the pinned timestamp', type: 'string' },
                 { flags: '--unpin', description: 'Clear the pinned timestamp', type: 'boolean' },
                 WRITE_DURABILITY_OPTION,
-                { flags: '--dry-run', description: 'Validate and preview the update without writing', type: 'boolean' },
+                { flags: '--dry-run', description: 'Validate and preview the stored view without writing', type: 'boolean' },
             ],
             schema: {
                 path: 'view.update',
                 risk: 'write',
                 auth: 'required',
                 globalOptions: VIEW_GLOBAL_OPTIONS,
-                output: { type: 'structured', summary: 'Updated saved view definition or dry-run plan', fields: ['view', 'durability', 'upload_queue_remaining', 'stale'] },
+                output: { type: 'structured', summary: 'Updated saved view definition or dry-run plan', fields: WRITE_OUTPUT_FIELDS },
                 examples: [
                     'dino view update <id> --filter @filter.json --format json --dry-run',
+                    'dino view update <id> --layout list --format json',
                     'dino view update <id> --name "Priority work" --unpin --format json',
                 ],
             },