@notis_ai/cli 0.2.5 → 0.2.7

package/src/runtime/app-changelog.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const APP_CHANGELOG_FILE = 'CHANGELOG.md';
+export const CHANGELOG_MERGE_DATE = '{PR_MERGE_DATE}';
+
+const ENTRY_HEADING = /^##\s+\[([^\]]+)]\s+-\s+(\{PR_MERGE_DATE\}|\d{4}-\d{2}-\d{2})\s*$/;
+
+function validCalendarDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
+export function parseAppChangelog(markdown, { sourcePath = APP_CHANGELOG_FILE } = {}) {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const entries = [];
+  const errors = [];
+  let current = null;
+
+  function finishCurrent() {
+    if (!current) return;
+    entries.push({
+      title: current.title,
+      date: current.date,
+      body: current.body.join('\n').trim(),
+    });
+  }
+
+  for (const [index, line] of lines.entries()) {
+    // Only a level-2 heading (`## ...`, not `###`/`####`) can start a release
+    // entry; deeper sub-section headings are legitimate release-body content.
+    if (!/^##(?!#)/.test(line)) {
+      if (current) current.body.push(line);
+      continue;
+    }
+
+    const match = line.match(ENTRY_HEADING);
+    if (!match) {
+      errors.push(
+        `${sourcePath}:${index + 1} must use \`## [Release title] - YYYY-MM-DD\` or \`## [Release title] - {PR_MERGE_DATE}\`.`,
+      );
+      continue;
+    }
+
+    finishCurrent();
+    const title = match[1].trim();
+    const date = match[2];
+    if (!title) {
+      errors.push(`${sourcePath}:${index + 1} must include a release title inside square brackets.`);
+    }
+    if (date !== CHANGELOG_MERGE_DATE && !validCalendarDate(date)) {
+      errors.push(`${sourcePath}:${index + 1} contains an invalid calendar date.`);
+    }
+    current = { title, date, body: [] };
+  }
+  finishCurrent();
+
+  if (entries.length === 0 && errors.length === 0) {
+    errors.push(
+      `${sourcePath} must include at least one \`## [Release title] - YYYY-MM-DD\` entry.`,
+    );
+  }
+
+  return { source_path: sourcePath, entries, errors, exists: true };
+}
+
+export function readAppChangelog(projectDir) {
+  const path = join(projectDir, APP_CHANGELOG_FILE);
+  if (!existsSync(path)) {
+    return {
+      source_path: APP_CHANGELOG_FILE,
+      entries: [],
+      errors: [`${APP_CHANGELOG_FILE} is required for Store publication.`],
+      exists: false,
+    };
+  }
+  return parseAppChangelog(readFileSync(path, 'utf-8'));
+}

package/src/runtime/app-dev-server.js

@@ -216,7 +216,7 @@ function findHarnessRoute(manifest, routeSlug) {
   return routes.find((route) => route?.slug === routeSlug) || null;
 }
 
-function buildHarnessDescriptor({ state, manifest, appConfig, route }) {
+function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario = null }) {
   const databases = normalizeDatabaseDescriptors(
     Array.isArray(appConfig?.databases) && appConfig.databases.length
       ? appConfig.databases
@@ -246,14 +246,28 @@ function buildHarnessDescriptor({ state, manifest, appConfig, route }) {
       collection: route.collection || null,
     },
     databases,
-    context: { collectionItem: null },
+    context: { collectionItem: null, screenshotScenario: scenario },
     tools,
   };
 }
 
-function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions }) {
+function harnessFixtures(projectDir, scenario) {
+  const fixtureConfig = readJsonFile(join(projectDir, 'metadata', 'screenshot-fixtures.json')) || {};
+  const scenarios = fixtureConfig.scenarios && typeof fixtureConfig.scenarios === 'object'
+    ? fixtureConfig.scenarios
+    : {};
+  return {
+    tools: fixtureConfig.tools && typeof fixtureConfig.tools === 'object' ? fixtureConfig.tools : {},
+    requests: fixtureConfig.requests && typeof fixtureConfig.requests === 'object' ? fixtureConfig.requests : {},
+    scenario: scenario && scenarios[scenario] && typeof scenarios[scenario] === 'object'
+      ? scenarios[scenario]
+      : null,
+  };
+}
+
+function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions, scenario = null }) {
   const template = readFileSync(HARNESS_TEMPLATE_PATH, 'utf-8');
-  const descriptor = buildHarnessDescriptor({ state, manifest, appConfig, route });
+  const descriptor = buildHarnessDescriptor({ state, manifest, appConfig, route, scenario });
   const routeExport = route.export_name || route.exportName || exportNameFromPath(route.path || '/');
   const replacements = {
     '{{REACT_VERSION}}': resolveHarnessReactVersion(state.projectDir),
@@ -262,6 +276,7 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions }
     '{{MODE}}': scriptJson(harnessOptions.mode || 'stub'),
     '{{API_BASE}}': scriptJson(harnessOptions.apiBase || null),
     '{{JWT}}': scriptJson(harnessOptions.jwt || null),
+    '{{FIXTURES}}': scriptJson(harnessFixtures(state.projectDir, scenario)),
   };
   let html = template;
   for (const [token, value] of Object.entries(replacements)) {
@@ -370,6 +385,7 @@ export async function startAppDevServer({
     }
 
     const routeSlug = url.searchParams.get('route') || '';
+    const scenario = url.searchParams.get('scenario') || null;
     const route = findHarnessRoute(manifest, routeSlug);
     if (!route) {
       res.writeHead(404, {
@@ -386,6 +402,7 @@ export async function startAppDevServer({
       appConfig,
       route,
       harnessOptions: harness,
+      scenario,
     });
     res.writeHead(200, {
       ...headers,

package/src/runtime/app-dev-sessions.js

@@ -7,6 +7,7 @@ import { CONFIG_DIR } from './profiles.js';
 export const DEFAULT_APP_DEV_SESSIONS_FILE = join(CONFIG_DIR, 'app-dev-sessions.json');
 export const APP_DEV_SESSIONS_FILE = DEFAULT_APP_DEV_SESSIONS_FILE;
 export const APP_DEV_SESSIONS_VERSION = 1;
+export const APP_DEV_SESSION_MOUNT_ACKS_VERSION = 1;
 
 /**
  * Walk up from `startDir` looking for a workspace-scoped dev-sessions registry.
@@ -54,6 +55,12 @@ export function getAppDevSessionsFile(filePath) {
   return DEFAULT_APP_DEV_SESSIONS_FILE;
 }
 
+export function getAppDevSessionMountAcksFile(sessionsFilePath) {
+  const resolvedSessionsFile = getAppDevSessionsFile(sessionsFilePath);
+  const parsed = parsePath(resolvedSessionsFile);
+  return join(parsed.dir, `${parsed.name}-mount-acks${parsed.ext || '.json'}`);
+}
+
 function normalizeSessions(raw) {
   if (!raw || typeof raw !== 'object' || !Array.isArray(raw.sessions)) {
     return [];
@@ -149,5 +156,96 @@ export function linkAppDevSessionTarget({ appId, devSlug, targetAppId, lastHeart
 export function removeAppDevSession(sessionId, filePath) {
   const registry = readAppDevSessions(filePath);
   registry.sessions = registry.sessions.filter((session) => session.sessionId !== sessionId);
-  return writeAppDevSessions(registry, filePath);
+  const result = writeAppDevSessions(registry, filePath);
+  removeAppDevSessionMountAcknowledgements(sessionId, filePath);
+  return result;
+}
+
+function normalizeMountAcknowledgements(raw) {
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.acknowledgements)) {
+    return [];
+  }
+  return raw.acknowledgements.filter((acknowledgement) =>
+    acknowledgement &&
+    typeof acknowledgement === 'object' &&
+    typeof acknowledgement.sessionId === 'string' &&
+    typeof acknowledgement.appId === 'string' &&
+    typeof acknowledgement.devSlug === 'string' &&
+    typeof acknowledgement.mountNonce === 'string' &&
+    typeof acknowledgement.acknowledgedAt === 'string' &&
+    acknowledgement.stage === 'listed',
+  );
+}
+
+export function readAppDevSessionMountAcknowledgements(sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  if (!existsSync(filePath)) {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return {
+      version: APP_DEV_SESSION_MOUNT_ACKS_VERSION,
+      acknowledgements: normalizeMountAcknowledgements(raw),
+    };
+  } catch {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+}
+
+function writeAppDevSessionMountAcknowledgements(registry, sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const normalized = {
+    version: APP_DEV_SESSION_MOUNT_ACKS_VERSION,
+    acknowledgements: normalizeMountAcknowledgements(registry),
+  };
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(normalized, null, 2), { mode: 0o600 });
+  renameSync(tempPath, filePath);
+  return normalized;
+}
+
+export function removeAppDevSessionMountAcknowledgements(sessionId, sessionsFilePath) {
+  const filePath = getAppDevSessionMountAcksFile(sessionsFilePath);
+  if (!existsSync(filePath)) {
+    return { version: APP_DEV_SESSION_MOUNT_ACKS_VERSION, acknowledgements: [] };
+  }
+  const registry = readAppDevSessionMountAcknowledgements(sessionsFilePath);
+  registry.acknowledgements = registry.acknowledgements.filter(
+    (acknowledgement) => acknowledgement.sessionId !== sessionId,
+  );
+  return writeAppDevSessionMountAcknowledgements(registry, sessionsFilePath);
+}
+
+function mountAcknowledgementKey(value) {
+  return `${value.sessionId}:${value.appId}:${value.devSlug}:${value.mountNonce}`;
+}
+
+export async function waitForAppDevSessionMountAcknowledgements(expectedSessions, options = {}) {
+  const expected = Array.isArray(expectedSessions) ? expectedSessions : [expectedSessions];
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(0, options.timeoutMs) : 15_000;
+  const pollIntervalMs = Number.isFinite(options.pollIntervalMs)
+    ? Math.max(1, options.pollIntervalMs)
+    : 100;
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const sleep = typeof options.sleep === 'function'
+    ? options.sleep
+    : (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+  const startedAt = now();
+
+  while (true) {
+    const registry = readAppDevSessionMountAcknowledgements(options.sessionsFilePath);
+    const acknowledgedKeys = new Set(registry.acknowledgements.map(mountAcknowledgementKey));
+    const missing = expected.filter((session) => !acknowledgedKeys.has(mountAcknowledgementKey(session)));
+    if (missing.length === 0) {
+      return { mounted: true, missing: [], acknowledgements: registry.acknowledgements };
+    }
+
+    const elapsedMs = now() - startedAt;
+    if (elapsedMs >= timeoutMs) {
+      return { mounted: false, missing, acknowledgements: registry.acknowledgements };
+    }
+    await sleep(Math.min(pollIntervalMs, timeoutMs - elapsedMs));
+  }
 }

package/src/runtime/app-platform.js

@@ -9,12 +9,13 @@
 import { spawn } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
 import { validateArtifactBoundary, validateProjectBoundary } from './app-boundary-validator.js';
+import { readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
@@ -35,6 +36,7 @@ export const NOTIS_APP_CATEGORIES = [
   'Product & Engineering',
   'Personal',
 ];
+export const MIN_LISTING_SCREENSHOTS = 3;
 const SOURCE_COPY_EXCLUDES = new Set([
   'node_modules',
   '.notis',
@@ -236,7 +238,7 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
   if (appConfig) {
     try {
       const listing = inspectListingReadiness(projectDir, appConfig);
-      warnings.push(...listing.warnings);
+      warnings.push(...listing.errors, ...listing.warnings);
     } catch (error) {
       warnings.push(error instanceof Error ? error.message : String(error));
     }
@@ -291,11 +293,10 @@ function pngDimensions(buffer) {
   };
 }
 
-function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6 }) {
+function imageAssetMeta(projectDir, relPath, { maxBytes }) {
   const fullPath = join(projectDir, relPath);
   const content = readFileSync(fullPath);
   const dimensions = pngDimensions(content);
-  const ratio = dimensions?.height ? dimensions.width / dimensions.height : null;
   const errors = [];
   const warnings = [];
 
@@ -305,10 +306,10 @@ function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6
   if (content.length > maxBytes) {
     errors.push(`${relPath} must be ${Math.round(maxBytes / 1024 / 1024)} MB or smaller.`);
   }
-  if (ratio !== null && (ratio < 1.3 || ratio > 1.9)) {
-    errors.push(`${relPath} should be close to a 16:10 aspect ratio.`);
-  } else if (ratio !== null && Math.abs(ratio - recommendedRatio) > 0.08) {
-    warnings.push(`${relPath} is not 2000x1250; 16:10 PNG is recommended.`);
+  if (!dimensions) {
+    errors.push(`${relPath} is not a valid PNG file.`);
+  } else if (dimensions.width !== 2000 || dimensions.height !== 1250) {
+    errors.push(`${relPath} must be exactly 2000x1250 pixels.`);
   }
 
   return {
@@ -346,33 +347,135 @@ export function discoverMetadataAssets(projectDir) {
   };
 }
 
+function normalizeConfiguredScreenshots(appConfig = null) {
+  if (!Array.isArray(appConfig?.screenshots) || appConfig.screenshots.length === 0) {
+    return null;
+  }
+  if (appConfig.screenshots.length > 6) {
+    throw usageError('Configure at most six listing screenshots.');
+  }
+
+  const seenPaths = new Set();
+  return appConfig.screenshots.map((entry, index) => {
+    const path = typeof entry?.path === 'string' ? entry.path.trim().replace(/\\/g, '/') : '';
+    const alt = typeof entry?.alt === 'string' ? entry.alt.trim() : '';
+    const route = typeof entry?.route === 'string' ? entry.route.trim() : '';
+    const scenario = typeof entry?.scenario === 'string' ? entry.scenario.trim() : '';
+    const focus = typeof entry?.focus === 'string' ? entry.focus.trim() : '';
+    const theme = typeof entry?.theme === 'string' ? entry.theme.trim().toLowerCase() : '';
+    if (!/^metadata\/screenshot-\d+\.png$/i.test(path)) {
+      throw usageError(`screenshots[${index}].path must match metadata/screenshot-N.png.`);
+    }
+    const expectedPath = `metadata/screenshot-${index + 1}.png`;
+    if (path !== expectedPath) {
+      throw usageError(`screenshots[${index}].path must be ${expectedPath} so capture order stays stable.`);
+    }
+    if (seenPaths.has(path)) {
+      throw usageError(`Duplicate listing screenshot path: ${path}`);
+    }
+    if (theme && theme !== 'light' && theme !== 'dark') {
+      throw usageError(`screenshots[${index}].theme must be light or dark.`);
+    }
+    seenPaths.add(path);
+    return {
+      path,
+      alt,
+      route: route || null,
+      scenario: scenario || null,
+      focus: focus || null,
+      theme: theme || 'light',
+    };
+  });
+}
+
+/** Resolve listing screenshot files in their configured editorial order. */
+export function resolveListingScreenshots(projectDir, appConfig = null) {
+  const discovered = discoverMetadataAssets(projectDir).screenshots;
+  const configured = normalizeConfiguredScreenshots(appConfig);
+  if (!configured) {
+    return discovered.map((asset) => ({
+      ...asset,
+      alt: null,
+      route: null,
+      scenario: null,
+      focus: null,
+      theme: 'light',
+    }));
+  }
+
+  const byPath = new Map(discovered.map((asset) => [asset.path.replace(/\\/g, '/'), asset]));
+  return configured.map((entry) => {
+    const asset = byPath.get(entry.path);
+    if (!asset) {
+      return {
+        ...entry,
+        content_type: 'image/png',
+        bytes: null,
+        width: null,
+        height: null,
+        errors: [`${entry.path} is configured but the file does not exist.`],
+        warnings: [],
+      };
+    }
+    return { ...asset, ...entry };
+  });
+}
+
 export function inspectListingReadiness(projectDir, appConfig = null) {
   const config = appConfig || {};
   const warnings = [];
   const errors = [];
-  const metadata = discoverMetadataAssets(projectDir);
+  const screenshots = resolveListingScreenshots(projectDir, config);
+  const metadata = { screenshots };
   const categories = normalizeCategories(config.categories || []);
+  const changelog = readAppChangelog(projectDir);
+  errors.push(...changelog.errors);
+
+  const packagePath = join(projectDir, 'package.json');
+  if (!existsSync(packagePath)) {
+    errors.push('package.json is required for Store publication.');
+  } else {
+    try {
+      const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      const notisAppVersion = String(packageJson.notisAppVersion || '').trim();
+      if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(notisAppVersion)) {
+        errors.push('package.json must include a semver `notisAppVersion` (for example, "0.1.0").');
+      }
+    } catch {
+      errors.push('package.json must contain valid JSON for Store publication.');
+    }
+  }
 
   if (!String(config.tagline || '').trim()) {
-    warnings.push('Listing tagline missing in notis.config.ts.');
+    errors.push('Listing tagline missing in notis.config.ts.');
   }
   if (categories.length === 0) {
-    warnings.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
+    errors.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
   }
-  if (metadata.screenshots.length < 3) {
-    warnings.push(`Listing screenshots: ${metadata.screenshots.length}/3 minimum in metadata/screenshot-N.png. Run \`notis apps screenshot\` to generate them.`);
+  if (metadata.screenshots.length < MIN_LISTING_SCREENSHOTS) {
+    errors.push(`Listing screenshots: ${metadata.screenshots.length}/${MIN_LISTING_SCREENSHOTS} minimum in metadata/screenshot-N.png. Run \`notis apps screenshot\` to generate them.`);
   }
   for (const screenshot of metadata.screenshots) {
     errors.push(...screenshot.errors);
     warnings.push(...screenshot.warnings);
+    if (!screenshot.alt) {
+      errors.push(`${screenshot.path} is missing descriptive alt text in notis.config.ts -> screenshots.`);
+    }
   }
 
   return {
-    ready: errors.length === 0 && Boolean(config.tagline) && categories.length > 0 && metadata.screenshots.length >= 1,
+    ready:
+      errors.length === 0 &&
+      Boolean(String(config.tagline || '').trim()) &&
+      categories.length > 0 &&
+      metadata.screenshots.length >= MIN_LISTING_SCREENSHOTS &&
+      metadata.screenshots.every((screenshot) => Boolean(screenshot.alt)) &&
+      changelog.entries.length > 0,
     warnings,
     errors,
     metadata,
     categories,
+    changelog,
   };
 }
 
@@ -606,9 +709,15 @@ export function generateManifest(appConfig, projectDir) {
 
   const databases = appConfig.databases || [];
   const categories = normalizeCategories(appConfig.categories || []);
-  const metadata = discoverMetadataAssets(projectDir);
+  const metadata = { screenshots: resolveListingScreenshots(projectDir, appConfig) };
   const appSlug = safeKebab(appConfig.name);
   const displayTitle = appConfig.title || appConfig.displayName || appConfig.name;
+  const skills = (Array.isArray(appConfig.skills) ? appConfig.skills : []).map((skill) => ({
+    key: skill.key,
+    path: String(skill.path || '').replace(/^\.\/+/, ''),
+    name: skill.name,
+    description: skill.description || null,
+  }));
   const listingMedia = {
     screenshots: metadata.screenshots.map((screenshot) => ({
       path: screenshot.path,
@@ -616,8 +725,27 @@ export function generateManifest(appConfig, projectDir) {
       width: screenshot.width,
       height: screenshot.height,
       bytes: screenshot.bytes,
+      alt: screenshot.alt || null,
+      theme: screenshot.theme || 'light',
     })),
   };
+  const changelog = readAppChangelog(projectDir);
+  if (changelog.exists && changelog.errors.length > 0) {
+    throw usageError(changelog.errors.join('\n'));
+  }
+  const latestChangelogEntry = changelog.entries[0] || null;
+  const legacyVersionNotes = latestChangelogEntry?.body
+    || appConfig.versionNotes
+    || appConfig.version_notes
+    || null;
+  let releaseVersion = null;
+  try {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    releaseVersion = String(packageJson.notisAppVersion || '').trim() || null;
+  } catch {
+    // Store readiness reports missing or malformed package metadata. Ordinary
+    // development builds remain usable without a Store release version.
+  }
 
   return {
     version: 1,
@@ -632,14 +760,23 @@ export function generateManifest(appConfig, projectDir) {
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      release_version: releaseVersion,
+      version_notes: legacyVersionNotes,
     },
     listing: {
       title: displayTitle,
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      version_notes: legacyVersionNotes,
+      ...(changelog.exists
+        ? {
+            changelog: {
+              source_path: changelog.source_path,
+              entries: changelog.entries,
+            },
+          }
+        : {}),
       media: listingMedia,
     },
     metadata: listingMedia,
@@ -650,9 +787,47 @@ export function generateManifest(appConfig, projectDir) {
     },
     databases,
     tools: appConfig.tools || [],
+    skills,
+    onboarding: appConfig.onboarding || null,
   };
 }
 
+export function resolveConfiguredAppSkills(appConfig, projectDir) {
+  const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
+  const projectRoot = resolve(projectDir);
+  const seenKeys = new Set();
+
+  return configured.map((skill, index) => {
+    const key = typeof skill?.key === 'string' ? skill.key.trim() : '';
+    const sourcePath = typeof skill?.path === 'string' ? skill.path.trim() : '';
+    const name = typeof skill?.name === 'string' ? skill.name.trim() : '';
+    if (!key || !sourcePath || !name) {
+      throw usageError(`skills[${index}] must define non-empty key, path, and name values.`);
+    }
+    if (seenKeys.has(key)) {
+      throw usageError(`Duplicate app skill key: ${key}`);
+    }
+    seenKeys.add(key);
+
+    const absolutePath = resolve(projectRoot, sourcePath);
+    const relativePath = relative(projectRoot, absolutePath).replace(/\\/g, '/');
+    if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
+      throw usageError(`App skill path must stay inside the project: ${sourcePath}`);
+    }
+    if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+
+    return {
+      key,
+      path: relativePath,
+      name,
+      description: typeof skill.description === 'string' ? skill.description.trim() : null,
+      skill_md: readFileSync(absolutePath, 'utf8'),
+    };
+  });
+}
+
 /**
  * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
  */
@@ -695,10 +870,14 @@ export function readManifest(projectDir) {
 
 function copyMetadataAssets(projectDir) {
   const metadataDir = join(projectDir, METADATA_DIR);
+  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
+  // Vite clears the bundle directory, not sibling listing media. Always make
+  // the packaged metadata an exact reflection of the source tree so removed
+  // placeholders can never survive into a later deploy.
+  rmSync(outputMetadataDir, { recursive: true, force: true });
   if (!existsSync(metadataDir)) {
     return;
   }
-  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
   mkdirSync(outputMetadataDir, { recursive: true });
   for (const entry of readdirSync(metadataDir, { withFileTypes: true })) {
     if (!entry.isFile()) continue;

package/src/runtime/desktop-auth.js

@@ -0,0 +1,93 @@
+import { CliError, EXIT_CODES } from './errors.js';
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function quoteShellArgument(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function defaultDesktopAppName(apiBase) {
+  try {
+    return new URL(apiBase).hostname === 'api-beta.notis.ai' ? 'Notis Beta' : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function getDesktopAuthRecovery(runtime) {
+  const desktopRunning = isPidRunning(runtime.desktopPid);
+  const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
+  let command = 'Start the Notis desktop app';
+  if (process.platform === 'darwin') {
+    command = `open -a ${quoteShellArgument(appName)}`;
+  }
+
+  return {
+    desktopRunning,
+    appName,
+    hints: [
+      {
+        command,
+        reason: desktopRunning
+          ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+          : `Start ${appName} to renew expired CLI authentication, then retry`,
+      },
+      {
+        command: 'notis doctor',
+        reason: 'Retry the auth and API checks after the desktop app is ready',
+      },
+    ],
+  };
+}
+
+export function createExpiredAuthError(runtime) {
+  if (runtime.credentialSource === 'env') {
+    return new CliError({
+      code: 'auth_expired',
+      message: 'NOTIS_JWT is expired',
+      exitCode: EXIT_CODES.auth,
+      details: { credential_source: 'env' },
+      hints: [
+        {
+          command: 'Set NOTIS_JWT to a fresh token',
+          reason: 'The explicit environment credential overrides desktop-managed auth',
+        },
+      ],
+    });
+  }
+
+  const recovery = getDesktopAuthRecovery(runtime);
+  return new CliError({
+    code: 'auth_expired',
+    message: 'Notis CLI authentication has expired',
+    exitCode: EXIT_CODES.auth,
+    details: {
+      credential_source: 'desktop',
+      desktop_running: recovery.desktopRunning,
+      desktop_app_name: recovery.appName,
+    },
+    hints: recovery.hints,
+  });
+}
+
+export function createInvalidAuthHints(runtime) {
+  if (runtime?.credentialSource === 'env') {
+    return [
+      {
+        command: 'Set NOTIS_JWT to a fresh token',
+        reason: 'The explicit environment credential was rejected',
+      },
+    ];
+  }
+  return getDesktopAuthRecovery(runtime || {}).hints;
+}