@notis_ai/cli 0.2.1 → 0.2.3

package/src/command-specs/apps.js

@@ -25,6 +25,8 @@ import {
   writeLinkedState,
   requireLinkedAppId,
   scaffoldProject,
+  loadScaffoldCatalog,
+  inspectListingReadiness,
   collectArtifactFiles,
   collectSourceFiles,
   directDeploy,
@@ -44,6 +46,7 @@ import {
 import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
 import {
+  localNotisToolSlug,
   nextIdempotencyKey,
   runToolCommand,
   toolConflictToError,
@@ -52,8 +55,11 @@ import {
 const DEFAULT_DEV_PORT = 5173;
 const DEV_HEARTBEAT_INTERVAL_MS = 10_000;
 const CONFIG_FILENAMES = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'];
-const ENSURE_DEV_APP_INSTALLATION_TOOL = 'notis-default-ensure_dev_app_installation';
-const GET_APP_TOOL = 'notis-default-get_app';
+const ENSURE_DEV_APP_INSTALLATION_TOOL = 'LOCAL_NOTIS_ENSURE_DEV_APP_INSTALLATION';
+const GET_APP_TOOL = 'LOCAL_NOTIS_GET_APP';
+const LIST_APPS_TOOL = 'LOCAL_NOTIS_LIST_APPS';
+const CREATE_APP_TOOL = 'LOCAL_NOTIS_CREATE_APP';
+const SAVE_APP_FILES_TOOL = 'LOCAL_NOTIS_SAVE_APP_FILES';
 
 // ---------------------------------------------------------------------------
 // Formatters
@@ -68,6 +74,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 +170,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 +196,29 @@ function pickDefaultRouteSlug(manifest) {
   return firstWithSlug ? firstWithSlug.slug : null;
 }
 
-export function buildDevelopmentDesktopUrl() {
-  return 'notis://apps?tab=development';
+const DESKTOP_DEEP_LINK_SCHEME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export function resolveDevelopmentDesktopScheme(env = process.env) {
+  // Mirror the desktop app's own scheme resolution (electron main + forge config):
+  // local dev launches register `notis-dev`, while installed prod/beta builds claim
+  // `notis`. Hardcoding `notis` here is what made `apps dev` open the installed
+  // prod/beta app instead of the local dev app.
+  const scheme = (env.NOTIS_DESKTOP_DEEP_LINK_SCHEME || '').trim();
+  return DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
+}
+
+export function buildDevelopmentDesktopUrl(appHref = null, scheme = 'notis') {
+  const route = String(appHref || '/store').replace(/^\/+/, '');
+  const normalizedScheme = DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
+  return `${normalizedScheme}://${route || 'store'}`;
+}
+
+export function shouldOpenDevelopmentTab(options = {}) {
+  // Commander stores the negatable `--no-open` flag as `options.open === false`;
+  // it never sets `options.noOpen`. Reading the non-existent `noOpen` key meant
+  // `--no-open` was silently ignored and `apps dev` always ran `open notis://…`,
+  // which macOS routes to the installed prod/beta desktop app.
+  return options.open !== false;
 }
 
 function buildAppHref({ appSlug, appId, manifest }) {
@@ -279,13 +333,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' &&
+        localNotisToolSlug(call?.args?.name) === 'LOCAL_NOTIS_DATABASE_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 LOCAL_NOTIS_DATABASE_QUERY for "${databaseSlug}".`,
         details: { databaseSlug },
       });
     }
@@ -341,7 +398,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 +427,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,13 +448,30 @@ 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,
-    toolName: 'notis_list_apps',
+    toolName: LIST_APPS_TOOL,
   });
   const apps = result.payload.apps || [];
   const hasAccess = apps.some((app) => (app.app_id || app.id) === appId);
@@ -396,7 +487,7 @@ async function assertDirectDeployAccess(runtime, appId) {
 async function appsListHandler(ctx) {
   const result = await runToolCommand({
     runtime: ctx.runtime,
-    toolName: 'notis_list_apps',
+    toolName: LIST_APPS_TOOL,
   });
   const apps = result.payload.apps || [];
   return ctx.output.emitSuccess({
@@ -409,13 +500,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 +517,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',
+    toolName: CREATE_APP_TOOL,
     arguments_: {
       name: ctx.args.name,
-      description: ctx.options.description || undefined,
-      icon,
+      description: appConfig?.description || undefined,
+      icon: appConfig?.icon || undefined,
     },
     mutating: true,
     idempotencyKey,
@@ -490,25 +594,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 +622,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 +658,19 @@ async function appsDevHandler(ctx) {
       }),
     };
   });
-  const developmentTabUrl = buildDevelopmentDesktopUrl();
+  const developmentTabUrl = buildDevelopmentDesktopUrl(
+    apps[0]?.appHref,
+    resolveDevelopmentDesktopScheme(),
+  );
+  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 +721,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}`),
       '',
@@ -596,7 +737,7 @@ async function appsDevHandler(ctx) {
     ].join('\n'),
   });
 
-  if (!ctx.options.noOpen) {
+  if (shouldOpenDevelopmentTab(ctx.options)) {
     openInBrowser(developmentTabUrl);
   }
 
@@ -665,7 +806,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 +820,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 +859,7 @@ async function appsVerifyHandler(ctx) {
     }));
 
     let results;
-    const warnings = [];
+    const warnings = [...listingWarnings];
     if (noBrowser) {
       results = urls.map(({ route, url }) => ({
         route: route.slug,
@@ -905,10 +1051,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 +1082,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' },
@@ -936,12 +1100,13 @@ async function appsDeployHandler(ctx) {
   try {
     result = await runToolCommand({
       runtime: ctx.runtime,
-      toolName: 'notis_save_app_files',
+      toolName: SAVE_APP_FILES_TOOL,
       arguments_: {
         app_id: appId,
         files,
         source_files: sourceFiles,
         manifest,
+        ...(baseVersion !== undefined ? { base_version: baseVersion } : {}),
       },
       mutating: true,
       idempotencyKey,
@@ -968,6 +1133,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 +1152,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 +1176,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
@@ -1037,27 +1212,46 @@ export const appsCommandSpecs = [
     examples: ['notis apps list', 'notis apps list --json'],
     mutates: false,
     idempotent: true,
-    backend_call: { type: 'tool', name: 'notis_list_apps' },
+    backend_call: { type: 'tool', name: LIST_APPS_TOOL },
     handler: appsListHandler,
   },
   {
     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,32 +1261,29 @@ 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,
-    backend_call: { type: 'tool', name: 'notis_create_app' },
+    backend_call: { type: 'tool', name: CREATE_APP_TOOL },
     handler: appsCreateHandler,
   },
   {
     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 +1366,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.' },
@@ -1211,7 +1403,7 @@ export const appsCommandSpecs = [
     examples: ['notis apps deploy', 'notis apps deploy --skip-build', 'notis apps deploy --app-id abc123', 'notis apps deploy --direct'],
     mutates: true,
     idempotent: true,
-    backend_call: { type: 'tool', name: 'notis_save_app_files' },
+    backend_call: { type: 'tool', name: SAVE_APP_FILES_TOOL },
     handler: appsDeployHandler,
   },
   {