@notis_ai/cli 0.2.1 → 0.2.2

package/src/command-specs/apps.js

@@ -25,6 +25,8 @@ import {
   writeLinkedState,
   requireLinkedAppId,
   scaffoldProject,
+  loadScaffoldCatalog,
+  inspectListingReadiness,
   collectArtifactFiles,
   collectSourceFiles,
   directDeploy,
@@ -68,6 +70,15 @@ function appsTable(apps) {
   ]);
 }
 
+function scaffoldsTable(scaffolds) {
+  return formatTable(scaffolds, [
+    { label: 'Slug', value: (scaffold) => scaffold.slug || '' },
+    { label: 'Name', value: (scaffold) => scaffold.name || scaffold.slug || '' },
+    { label: 'Category', value: (scaffold) => (scaffold.categories || [])[0] || '' },
+    { label: 'Tagline', value: (scaffold) => scaffold.tagline || scaffold.description || '' },
+  ]);
+}
+
 function hasNotisConfig(dir) {
   return CONFIG_FILENAMES.some((name) => existsSync(join(dir, name)));
 }
@@ -155,6 +166,24 @@ function buildDevInstallSlug(appName) {
   return base.endsWith('-dev') ? base : `${base}-dev`;
 }
 
+function timingMs(startedAt) {
+  return Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+}
+
+function logAppsTiming(label, details = {}) {
+  const suffix = Object.entries(details)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(' ');
+  process.stderr.write(`[notis apps timing] ${label}${suffix ? ` ${suffix}` : ''}\n`);
+}
+
+function nextDevInstallIdempotencyKey(globalOptions = {}, devSlug) {
+  if (globalOptions.idempotencyKey) {
+    return `${globalOptions.idempotencyKey}:${devSlug}`;
+  }
+  return nextIdempotencyKey(globalOptions);
+}
+
 function pickDefaultRouteSlug(manifest) {
   const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
   const explicit = routes.find((route) => route && route.default && typeof route.slug === 'string');
@@ -163,8 +192,9 @@ function pickDefaultRouteSlug(manifest) {
   return firstWithSlug ? firstWithSlug.slug : null;
 }
 
-export function buildDevelopmentDesktopUrl() {
-  return 'notis://apps?tab=development';
+export function buildDevelopmentDesktopUrl(appHref = null) {
+  const route = String(appHref || '/store').replace(/^\/+/, '');
+  return `notis://${route || 'store'}`;
 }
 
 function buildAppHref({ appSlug, appId, manifest }) {
@@ -279,13 +309,16 @@ function assertHarnessResult(result, route, databaseSlugs) {
   }
   for (const databaseSlug of databaseSlugs) {
     const seen = (result.runtimeCalls || []).some(
-      (call) => call?.op === 'queryDatabase' && call?.args?.databaseSlug === databaseSlug,
+      (call) =>
+        call?.op === 'callTool' &&
+        call?.args?.name === 'notis-default-query' &&
+        call?.args?.arguments?.database_slug === databaseSlug,
     );
     if (!seen) {
       assertions.push({
         ok: false,
         code: 'missing_database_query',
-        message: `Route "${route.slug}" did not call queryDatabase for "${databaseSlug}".`,
+        message: `Route "${route.slug}" did not call notis-default-query for "${databaseSlug}".`,
         details: { databaseSlug },
       });
     }
@@ -341,7 +374,26 @@ function buildManifestForDev(appConfig) {
   };
 }
 
-async function ensureDevInstall({ ctx, appConfig, projectDir, idempotencyKey }) {
+export function buildEnsureDevInstallArguments({ appConfig, manifest, linkedState }) {
+  const devSlug = buildDevInstallSlug(appConfig.name);
+  const arguments_ = {
+    dev_slug: devSlug,
+    name: appConfig.name,
+    manifest,
+  };
+  if (linkedState?.dev_app_id) {
+    arguments_.app_id = linkedState.dev_app_id;
+  }
+  return arguments_;
+}
+
+export async function ensureDevInstall({
+  ctx,
+  appConfig,
+  projectDir,
+  idempotencyKey,
+  runTool = runToolCommand,
+}) {
   if (!appConfig.name) {
     throw usageError(`notis.config.ts in ${projectDir} must define a non-empty name.`);
   }
@@ -351,14 +403,12 @@ async function ensureDevInstall({ ctx, appConfig, projectDir, idempotencyKey })
   }
 
   const manifest = buildManifestForDev(appConfig);
-  const ensureResult = await runToolCommand({
+  const linkedState = readLinkedState(projectDir);
+  const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState });
+  const ensureResult = await runTool({
     runtime: ctx.runtime,
     toolName: ENSURE_DEV_APP_INSTALLATION_TOOL,
-    arguments_: {
-      dev_slug: devSlug,
-      name: appConfig.name,
-      manifest,
-    },
+    arguments_: ensureArguments,
     mutating: true,
     idempotencyKey,
   });
@@ -374,9 +424,26 @@ async function ensureDevInstall({ ctx, appConfig, projectDir, idempotencyKey })
     projectDir,
     manifest,
     created: ensureResult.payload.created || false,
+    linkedAppId: linkedState?.app_id || null,
+    databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
 
+function databaseMaterializationWarnings(apps) {
+  const warnings = [];
+  for (const app of apps) {
+    const unresolved = app.databaseMaterialization?.unresolved || [];
+    if (!unresolved.length) {
+      continue;
+    }
+    warnings.push(
+      `${app.name}: database slug${unresolved.length === 1 ? '' : 's'} ${unresolved.join(', ')} ` +
+      'could not be created because no store snapshot schema exists. Create them manually or link to a store-installed app.',
+    );
+  }
+  return warnings;
+}
+
 async function assertDirectDeployAccess(runtime, appId) {
   const result = await runToolCommand({
     runtime,
@@ -409,13 +476,16 @@ async function appsListHandler(ctx) {
 
 async function appsInitHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || ctx.args.name.toLowerCase().replace(/[^a-z0-9]+/g, '-'));
+  const fromSlug = ctx.options.from || null;
 
-  scaffoldProject({ projectDir, appName: ctx.args.name });
+  scaffoldProject({ projectDir, appName: ctx.args.name, fromSlug });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { project_dir: projectDir, app_name: ctx.args.name },
-    humanSummary: `Scaffolded "${ctx.args.name}" in ${projectDir}`,
+    data: { project_dir: projectDir, app_name: ctx.args.name, scaffold: fromSlug },
+    humanSummary: fromSlug
+      ? `Scaffolded "${ctx.args.name}" from ${fromSlug} in ${projectDir}`
+      : `Scaffolded "${ctx.args.name}" in ${projectDir}`,
     hints: [
       { command: `cd ${projectDir} && npm install`, reason: 'Install dependencies' },
       { command: `cd ${projectDir} && notis apps dev`, reason: 'Start the real-portal dev workflow' },
@@ -423,19 +493,29 @@ async function appsInitHandler(ctx) {
   });
 }
 
+async function appsScaffoldsListHandler(ctx) {
+  const scaffolds = loadScaffoldCatalog();
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { scaffolds },
+    humanSummary: scaffolds.length
+      ? `Found ${scaffolds.length} bundled scaffolds`
+      : 'No bundled scaffolds found. Run the CLI build step to generate the scaffold catalog.',
+    renderHuman: () => (scaffolds.length ? scaffoldsTable(scaffolds) : 'No bundled scaffolds found.'),
+  });
+}
+
 async function appsCreateHandler(ctx) {
   const projectDir = ctx.args.dir ? resolveProjectDir(ctx.args.dir) : null;
+  const appConfig = projectDir ? await loadAppConfig(projectDir) : null;
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
-  const icon = ctx.options.icon
-    ? (ctx.options.icon.startsWith('lucide:') ? ctx.options.icon : `lucide:${ctx.options.icon}`)
-    : undefined;
   const result = await runToolCommand({
     runtime: ctx.runtime,
     toolName: 'notis_create_app',
     arguments_: {
       name: ctx.args.name,
-      description: ctx.options.description || undefined,
-      icon,
+      description: appConfig?.description || undefined,
+      icon: appConfig?.icon || undefined,
     },
     mutating: true,
     idempotencyKey,
@@ -490,25 +570,26 @@ async function appsDevHandler(ctx) {
   const mode = getCliMode();
   const identity = decodeJwtSub(ctx.runtime.jwt);
   if (!identity) {
-    throw usageError('Could not determine the current user from the CLI auth token. Run `notis auth login` from the desktop app and retry.');
+    throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
   }
   const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
   const sessionId = randomUUID();
 
-  const registered = [];
+  const candidates = [];
   for (const projectDir of appDirs) {
     const appConfig = await loadAppConfig(projectDir);
-    const info = await ensureDevInstall({
-      ctx,
-      appConfig,
-      projectDir,
-      idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
-    });
-    registered.push(info);
+    if (!appConfig.name) {
+      throw usageError(`notis.config.ts in ${projectDir} must define a non-empty name.`);
+    }
+    const devSlug = buildDevInstallSlug(appConfig.name);
+    if (!devSlug) {
+      throw usageError(`notis.config.ts name in ${projectDir} must slugify to a non-empty value.`);
+    }
+    candidates.push({ appConfig, devSlug, projectDir });
   }
 
   const seenSlugs = new Map();
-  for (const app of registered) {
+  for (const app of candidates) {
     if (seenSlugs.has(app.devSlug)) {
       throw usageError(
         `Multiple apps slugify to "${app.devSlug}" (${seenSlugs.get(app.devSlug).projectDir} and ${app.projectDir}). Rename one in notis.config.ts.`,
@@ -517,6 +598,30 @@ async function appsDevHandler(ctx) {
     seenSlugs.set(app.devSlug, app);
   }
 
+  const registrationStartedAt = process.hrtime.bigint();
+  const registered = await Promise.all(
+    candidates.map(async ({ appConfig, devSlug, projectDir }) => {
+      const appStartedAt = process.hrtime.bigint();
+      try {
+        return await ensureDevInstall({
+          ctx,
+          appConfig,
+          projectDir,
+          idempotencyKey: nextDevInstallIdempotencyKey(ctx.globalOptions, devSlug),
+        });
+      } finally {
+        logAppsTiming('ensure-dev-install', {
+          slug: devSlug,
+          ms: timingMs(appStartedAt).toFixed(1),
+        });
+      }
+    }),
+  );
+  logAppsTiming('ensure-dev-install:all', {
+    apps: registered.length,
+    ms: timingMs(registrationStartedAt).toFixed(1),
+  });
+
   const apps = registered.map((app) => {
     const bundleBaseUrl = `http://127.0.0.1:${port}/a/${app.devSlug}`;
     return {
@@ -529,10 +634,16 @@ async function appsDevHandler(ctx) {
       }),
     };
   });
-  const developmentTabUrl = buildDevelopmentDesktopUrl();
+  const developmentTabUrl = buildDevelopmentDesktopUrl(apps[0]?.appHref);
+  const warnings = databaseMaterializationWarnings(apps);
 
   const devServer = await startAppDevServer({
-    apps: apps.map((app) => ({ slug: app.devSlug, projectDir: app.projectDir, appId: app.appId })),
+    apps: apps.map((app) => ({
+      slug: app.devSlug,
+      projectDir: app.projectDir,
+      appId: app.appId,
+      userId: identity,
+    })),
     port,
   });
 
@@ -583,12 +694,15 @@ async function appsDevHandler(ctx) {
         bundle_base_url: app.bundleBaseUrl,
         app_href: app.appHref,
         created: app.created,
+        linked_app_id: app.linkedAppId,
+        database_materialization: app.databaseMaterialization,
       })),
     },
+    warnings,
     humanSummary: [
       `Running apps dev against ${apiBase} as ${identity} (mode: ${mode})`,
       '',
-      `Development tab: ${developmentTabUrl}`,
+      `Open in desktop: ${developmentTabUrl}`,
       '',
       ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
       '',
@@ -665,7 +779,7 @@ async function appsVerifyHandler(ctx) {
   let linkedState = null;
   if (mode === 'live') {
     if (!ctx.runtime.jwt) {
-      throw usageError('Live verify mode requires CLI auth. Run `notis auth login` and retry.');
+      throw usageError('Live verify mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
     linkedState = readLinkedState(projectDir);
     if (!linkedState?.app_id) {
@@ -679,6 +793,11 @@ async function appsVerifyHandler(ctx) {
 
   const manifest = readManifest(projectDir);
   const appConfig = await loadAppConfig(projectDir);
+  const listing = inspectListingReadiness(projectDir, appConfig);
+  if (listing.errors.length) {
+    throw usageError(`Listing metadata has problems:\n${listing.errors.map((error) => `  - ${error}`).join('\n')}`);
+  }
+  const listingWarnings = listing.warnings;
   const routes = routeSelection(manifest, parseRouteSlugs(ctx.options.routes));
   const port = parsePort(ctx.options.port) || await getAvailablePort();
   const appSlug = slugify(appConfig.name || manifest.app?.name || 'app') || 'app';
@@ -713,7 +832,7 @@ async function appsVerifyHandler(ctx) {
     }));
 
     let results;
-    const warnings = [];
+    const warnings = [...listingWarnings];
     if (noBrowser) {
       results = urls.map(({ route, url }) => ({
         route: route.slug,
@@ -905,10 +1024,27 @@ async function appsPullHandler(ctx) {
   });
 }
 
+function updateLinkedDeployState(projectDir, linkedState, appId, version) {
+  if (!linkedState || linkedState.app_id !== appId || !Number.isFinite(version)) {
+    return;
+  }
+  writeLinkedState(projectDir, {
+    ...linkedState,
+    app_id: appId,
+    version,
+    linked_at: linkedState.linked_at || new Date().toISOString(),
+    deployed_at: new Date().toISOString(),
+  });
+}
+
 async function appsDeployHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const appId = requireLinkedAppId(projectDir, ctx.options.appId);
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const linkedState = readLinkedState(projectDir);
+  const baseVersion = linkedState?.app_id === appId && Number.isFinite(linkedState?.version)
+    ? linkedState.version
+    : undefined;
 
   // Build if needed
   if (!ctx.options.skipBuild) {
@@ -919,6 +1055,7 @@ async function appsDeployHandler(ctx) {
   if (ctx.options.direct) {
     await assertDirectDeployAccess(ctx.runtime, appId);
     const { version } = await directDeploy(projectDir, appId);
+    updateLinkedDeployState(projectDir, linkedState, appId, version);
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
       data: { app_id: appId, version, mode: 'direct' },
@@ -942,6 +1079,7 @@ async function appsDeployHandler(ctx) {
         files,
         source_files: sourceFiles,
         manifest,
+        ...(baseVersion !== undefined ? { base_version: baseVersion } : {}),
       },
       mutating: true,
       idempotencyKey,
@@ -968,6 +1106,7 @@ async function appsDeployHandler(ctx) {
 
       try {
         const { version } = await directDeploy(projectDir, appId);
+        updateLinkedDeployState(projectDir, linkedState, appId, version);
         return ctx.output.emitSuccess({
           command: ctx.spec.command_path.join(' '),
           data: { app_id: appId, version, mode: 'direct-fallback' },
@@ -986,6 +1125,7 @@ async function appsDeployHandler(ctx) {
     throw error;
   }
 
+  updateLinkedDeployState(projectDir, linkedState, appId, Number(result.payload.version));
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
@@ -1009,13 +1149,21 @@ async function appsDoctorHandler(ctx) {
     problems.push('Failed to load notis.config.ts');
   }
   const warnings = detectProjectWarnings(projectDir, appConfig);
+  let listing = null;
+  if (appConfig) {
+    try {
+      listing = inspectListingReadiness(projectDir, appConfig);
+    } catch (error) {
+      warnings.push(error instanceof Error ? error.message : String(error));
+    }
+  }
 
   const linkedState = readLinkedState(projectDir);
   const status = problems.length ? 'unhealthy' : warnings.length ? 'warnings' : 'healthy';
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { status, problems, warnings, linked: linkedState, config: appConfig },
+    data: { status, problems, warnings, linked: linkedState, config: appConfig, listing },
     humanSummary: problems.length
       ? `Found ${problems.length} problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`
       : warnings.length
@@ -1043,21 +1191,40 @@ export const appsCommandSpecs = [
   {
     command_path: ['apps', 'init'],
     summary: 'Scaffold a new Notis app project.',
-    when_to_use: 'Start a new Notis app. Creates a Vite + React project with @notis/sdk pre-configured.',
+    when_to_use: 'Start a new Notis app. Use --from with a bundled scaffold when one is close to the desired app; otherwise creates the bare Vite + React project.',
     args_schema: {
       arguments: [
         { token: '<name>', description: 'Display name for the app.' },
         { token: '[dir]', key: 'dir', description: 'Target directory (defaults to kebab-case of name).' },
       ],
-      options: [],
+      options: [
+        { flags: '--from <slug>', description: 'Start from a bundled scaffold listed by `notis apps scaffolds list`.' },
+      ],
     },
-    examples: ['notis apps init "Mind the Flo"', 'notis apps init "My App" ./my-app'],
+    examples: [
+      'notis apps scaffolds list',
+      'notis apps init "Mind the Flo"',
+      'notis apps init "My CRM" --from notis-database',
+      'notis apps init "My App" ./my-app',
+    ],
     mutates: true,
     idempotent: false,
     require_auth: false,
     backend_call: { type: 'local', name: 'scaffold_project' },
     handler: appsInitHandler,
   },
+  {
+    command_path: ['apps', 'scaffolds', 'list'],
+    summary: 'List bundled Notis app scaffolds.',
+    when_to_use: 'Discover the fixed scaffold catalog shipped with the CLI before starting a new app.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis apps scaffolds list', 'notis apps init "My App" --from notis-database'],
+    mutates: false,
+    idempotent: true,
+    require_auth: false,
+    backend_call: { type: 'local', name: 'list_scaffolds' },
+    handler: appsScaffoldsListHandler,
+  },
   {
     command_path: ['apps', 'create'],
     summary: 'Create a new remote Notis app and optionally link a local project to it.',
@@ -1067,14 +1234,11 @@ export const appsCommandSpecs = [
         { token: '<name>', description: 'Display name for the remote app.' },
         { token: '[dir]', key: 'dir', description: 'Project directory to link after creation (default: do not link).' },
       ],
-      options: [
-        { flags: '--description <text>', description: 'Optional app description.' },
-        { flags: '--icon <lucide:icon>', description: 'Optional Lucide icon, for example lucide:dices.' },
-      ],
+      options: [],
     },
     examples: [
       'notis apps create "My App"',
-      'notis apps create "My App" . --description "Internal tool" --icon lucide:layout-dashboard',
+      'notis apps create "My App" .',
     ],
     mutates: true,
     idempotent: false,
@@ -1085,14 +1249,14 @@ export const appsCommandSpecs = [
     command_path: ['apps', 'dev'],
     summary: 'Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.',
     when_to_use:
-      'Run this inside a single app or a monorepo root with apps/<name>/notis.config.ts. It discovers every app, starts the local bundle server, registers desktop-local dev sessions, and opens the Electron Portal Development tab.',
+      'Run this inside a single app or a monorepo root with apps/<name>/notis.config.ts. It discovers every app, starts the local bundle server, registers desktop-local dev sessions, and opens the Electron Portal to the local development app.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory or monorepo root (default: current dir).' },
       ],
       options: [
         { flags: '--port <number>', description: `Local bundle server port (default: ${DEFAULT_DEV_PORT}).` },
-        { flags: '--no-open', description: 'Do not auto-open the desktop Portal Development tab.' },
+        { flags: '--no-open', description: 'Do not auto-open the desktop Portal local development app.' },
       ],
     },
     examples: [
@@ -1175,7 +1339,8 @@ export const appsCommandSpecs = [
   {
     command_path: ['apps', 'pull'],
     summary: 'Download a Notis app source snapshot into a local project folder.',
-    when_to_use: 'Edit an installed app locally. Pulls the persisted source and links the directory to the app.',
+    when_to_use:
+      'Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.',
     args_schema: {
       arguments: [
         { token: '<app-id>', description: 'Remote app ID to pull.' },

package/src/command-specs/helpers.js

@@ -1,13 +1,6 @@
-import { createInterface } from 'node:readline/promises';
 import { randomUUID } from 'node:crypto';
 import { CliError, EXIT_CODES, usageError } from '../runtime/errors.js';
 import { callTool, httpRequest } from '../runtime/transport.js';
-import {
-  DEFAULT_PROFILE,
-  ensureProfile,
-  loadConfig,
-  saveConfig,
-} from '../runtime/profiles.js';
 
 export function parseJson(value, label) {
   try {
@@ -41,16 +34,6 @@ export function normalizeToolkits(value) {
     .filter(Boolean);
 }
 
-export async function promptForJwt() {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const jwt = await rl.question('Paste your Notis JWT: ');
-    return jwt.trim();
-  } finally {
-    rl.close();
-  }
-}
-
 export function nextIdempotencyKey(globalOptions) {
   return globalOptions.idempotencyKey || randomUUID();
 }
@@ -105,49 +88,6 @@ export async function healthCheck(runtime) {
   });
 }
 
-export function updateStoredProfile({
-  profileName,
-  jwt,
-  apiBase,
-  authMode,
-  refreshToken,
-  accessExpiresAt,
-  refreshExpiresAt,
-  setCurrent = true,
-}) {
-  let config = ensureProfile(loadConfig(), profileName || DEFAULT_PROFILE);
-  const resolvedName = profileName || DEFAULT_PROFILE;
-  config.profiles[resolvedName] = {
-    ...config.profiles[resolvedName],
-    ...(jwt ? { jwt } : {}),
-    ...(apiBase ? { api_base: apiBase } : {}),
-    ...(authMode ? { auth_mode: authMode } : {}),
-    ...(refreshToken ? { refresh_token: refreshToken } : {}),
-    ...(typeof accessExpiresAt === 'number'
-      ? { access_expires_at: accessExpiresAt }
-      : {}),
-    ...(typeof refreshExpiresAt === 'number'
-      ? { refresh_expires_at: refreshExpiresAt }
-      : {}),
-  };
-  if (setCurrent) {
-    config.current_profile = resolvedName;
-  }
-  saveConfig(config);
-  return config;
-}
-
-export function clearStoredJwt(profileName) {
-  const config = ensureProfile(loadConfig(), profileName || DEFAULT_PROFILE);
-  delete config.profiles[profileName || DEFAULT_PROFILE].jwt;
-  delete config.profiles[profileName || DEFAULT_PROFILE].auth_mode;
-  delete config.profiles[profileName || DEFAULT_PROFILE].refresh_token;
-  delete config.profiles[profileName || DEFAULT_PROFILE].access_expires_at;
-  delete config.profiles[profileName || DEFAULT_PROFILE].refresh_expires_at;
-  saveConfig(config);
-  return config;
-}
-
 export async function fetchToolSchema(runtime, toolName, rawToolkits) {
   const toolkits = normalizeToolkits(rawToolkits);
   const result = await runToolCommand({

package/src/command-specs/index.js

@@ -1,20 +1,14 @@
-import { authCommandSpecs } from './auth.js';
 import { appsCommandSpecs } from './apps.js';
-import { dbCommandSpecs } from './db.js';
 import { toolsCommandSpecs } from './tools.js';
 import { metaCommandSpecs } from './meta.js';
 
 export const GROUP_SUMMARIES = {
-  auth: 'Authentication and profile management.',
   apps: 'Develop, build, and deploy Notis Apps.',
-  db: 'List, query, and update native Notis Databases.',
   tools: 'Discover and execute generic tools exposed through Notis.',
 };
 
 export const COMMAND_SPECS = [
-  ...authCommandSpecs,
   ...appsCommandSpecs,
-  ...dbCommandSpecs,
   ...toolsCommandSpecs,
   ...metaCommandSpecs,
 ];

package/src/command-specs/meta.js

@@ -29,10 +29,10 @@ async function doctorHandler(ctx) {
 
   const hints = [];
   if (checks.auth === 'missing') {
-    hints.push({ command: 'notis auth login --jwt <token>', reason: 'Configure credentials' });
+    hints.push({ command: 'Open the Notis desktop app and sign in', reason: 'Configure CLI credentials' });
   }
   if (checks.health === 'error') {
-    hints.push({ command: 'notis auth status', reason: 'Check API base URL configuration' });
+    hints.push({ command: 'Open the Notis desktop app and sign in again', reason: 'Refresh local CLI configuration' });
   }
   if (checks.tool_roundtrip === 'error') {
     hints.push({ command: 'notis whoami', reason: 'Verify your account and permissions' });
@@ -117,7 +117,7 @@ export const metaCommandSpecs = [
     output_schema: 'Returns profile, api_base, user_id, toolkit count, and CLI version.',
     mutates: false,
     idempotent: true,
-    related_commands: ['notis auth status --verify', 'notis doctor'],
+    related_commands: ['notis doctor'],
     backend_call: { type: 'tool', name: 'notis_find_toolkits' },
     handler: whoamiHandler,
   },
@@ -130,7 +130,8 @@ export const metaCommandSpecs = [
     output_schema: 'Returns config, auth, health, and roundtrip check statuses.',
     mutates: false,
     idempotent: true,
-    related_commands: ['notis auth status --verify', 'notis tools toolkits'],
+    require_auth: false,
+    related_commands: ['notis tools toolkits'],
     backend_call: { type: 'health+tool_roundtrip' },
     handler: doctorHandler,
   },
@@ -139,10 +140,10 @@ export const metaCommandSpecs = [
     summary: 'Describe a first-class CLI command in detail.',
     when_to_use: 'Use this when an agent or human needs the exact shape, examples, and semantics of a command.',
     args_schema: {
-      arguments: [{ token: '<command...>', key: 'commandPath', description: 'Command path to describe, such as "apps push".' }],
+      arguments: [{ token: '<command...>', key: 'commandPath', description: 'Command path to describe, such as "apps deploy".' }],
       options: [],
     },
-    examples: ['notis describe apps push', 'notis describe db query'],
+    examples: ['notis describe apps deploy', 'notis describe tools exec'],
     output_schema: 'Returns the command spec metadata for the requested command.',
     mutates: false,
     idempotent: true,