@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

package/src/runtime/app-platform.js

@@ -7,26 +7,150 @@
  */
 
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, readdirSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants as fsConstants, copyFileSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
+import { acquireScaffoldSource, loadScaffoldCatalog } from './app-registry-scaffolds.js';
+import { validateArtifactBoundary, validateProjectBoundary, validateProjectDesign } from './app-boundary-validator.js';
+import { CHANGELOG_MERGE_DATE, readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
 const OUTPUT_DIR = join(NOTIS_DIR, 'output');
 const BUNDLE_DIR = join(OUTPUT_DIR, 'bundle');
 const MANIFEST_FILE = join(OUTPUT_DIR, 'manifest.json');
+const METADATA_DIR = 'metadata';
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const TEMPLATE_SDK_DIR = join(CLI_ROOT, 'template', 'packages', 'sdk');
+export const NOTIS_APP_CATEGORIES = [
+  'Productivity',
+  'Sales & Marketing',
+  'Operations',
+  'Product & Engineering',
+  'Personal',
+];
+export const MIN_LISTING_SCREENSHOTS = 3;
+const SOURCE_COPY_EXCLUDES = new Set([
+  'node_modules',
+  '.notis',
+  '.git',
+  'dist',
+  'tsconfig.tsbuildinfo',
+  '.DS_Store',
+  // Interpreter droppings: a stray `python -m py_compile` in a skill's
+  // scripts/ directory must not ship version-specific bytecode in the bundle.
+  '__pycache__',
+]);
+const SOURCE_COPY_EXCLUDES_CASEFOLDED = new Set(
+  [...SOURCE_COPY_EXCLUDES].map((name) => name.toLocaleLowerCase('en-US')),
+);
+const SCAFFOLD_COPY_EXCLUDES = new Set([
+  ...SOURCE_COPY_EXCLUDES,
+  'coverage',
+  '.next',
+  '.turbo',
+]);
+// Listing media describes the scaffold's own Store entry, so a new project must
+// never inherit it. Scaffold packaging still ships these files -- only the
+// `apps init` copy drops them. Screenshots only: `screenshot-fixtures.json` is
+// not listing media, it is the stub data the dev harness serves, and dropping
+// it would make every route of a fresh project render its empty state.
+const SCAFFOLD_LISTING_MEDIA = /^metadata\/screenshot-\d+\.png$/i;
+const PULL_LOCK_TIMEOUT_MS = 30_000;
+const PULL_LOCK_POLL_MS = 25;
+const STATE_WRITE_LOCK_TIMEOUT_MS = 5_000;
+const STATE_WRITE_LOCK_STALE_MS = 2_000;
+const stateWriteLockWait = new Int32Array(new SharedArrayBuffer(4));
+// A directory-declared skill ships every supporting file to the sandbox, so it
+// needs a ceiling of its own. Kept well above the 512 KB SKILL.md limit so a
+// handful of scripts always fits, and far below the bundle machinery's own
+// limits so an accidental asset dump fails on the client with a clear message.
+export const MAX_APP_SKILL_BUNDLE_BYTES = 5 * 1024 * 1024;
 let appConfigImportNonce = 0;
 
 // ---------------------------------------------------------------------------
 // Project directory resolution
 // ---------------------------------------------------------------------------
 
+// Every Notis app the user did not deliberately place lives here, mirroring the
+// desktop's synced-skills root (~/.notis/skills). A default that depends on the
+// caller's working directory is unusable for agents: the shell sits wherever
+// the previous command left it, so `apps init` would scatter projects into
+// unrelated checkouts. Pass an explicit [dir] to override -- that is how an app
+// ends up in a tracked git repo or an existing monorepo.
+export const DEFAULT_APPS_ROOT = join(homedir(), NOTIS_DIR, 'apps');
+
+export function defaultAppProjectDir(slug) {
+  const safeSlug = String(slug || '').trim();
+  if (!safeSlug || safeSlug.includes('/') || safeSlug.includes('\\') || safeSlug.startsWith('.')) {
+    throw usageError(`Cannot derive a default project directory from "${slug}". Pass an explicit target directory.`);
+  }
+  return join(DEFAULT_APPS_ROOT, safeSlug);
+}
+
+// A `~/...` path only expands when a shell is involved. Agents routinely spawn
+// the CLI without one, and the documented default home is written with a tilde,
+// so expand it here instead of creating a literal "~" directory.
+export function expandHomePath(inputPath) {
+  const value = String(inputPath ?? '');
+  if (value === '~') {
+    return homedir();
+  }
+  if (value.startsWith('~/') || value.startsWith('~\\')) {
+    return join(homedir(), value.slice(2));
+  }
+  return value;
+}
+
 export function resolveProjectDir(inputDir = '.') {
-  return resolve(process.cwd(), inputDir);
+  return resolve(process.cwd(), expandHomePath(inputDir));
+}
+
+export function getBundleDir(projectDir) {
+  return join(projectDir, BUNDLE_DIR);
+}
+
+export function resolveBuiltBundleDir(projectDir) {
+  const bundleDir = getBundleDir(projectDir);
+  if (existsSync(join(bundleDir, 'app.js'))) {
+    return bundleDir;
+  }
+  return null;
+}
+
+function normalizeShadowScopedCss(css) {
+  return css
+    // Tailwind preflight emits `html,:host` in v3. Inside a shadow tree we want
+    // the shadow host itself to carry those defaults.
+    .replace(/html\s*,\s*:host\s*\{/g, ':host{')
+    .replace(/:root\s*,\s*:host\s*\{/g, ':host{')
+    .replace(/:root\s*\{/g, ':host{')
+    .replace(/html\s*\{/g, ':host{')
+    // Shadow trees do not contain a body element. Route those defaults to the
+    // app root contract instead so authors still get the expected reset.
+    .replace(/body\s*\{/g, '[data-notis-app-root]{');
+}
+
+function normalizeBundleStylesheets(projectDir) {
+  const bundleDir = join(projectDir, BUNDLE_DIR);
+  if (!existsSync(bundleDir)) {
+    return;
+  }
+
+  for (const entry of readdirSync(bundleDir)) {
+    if (!entry.endsWith('.css')) {
+      continue;
+    }
+    const cssPath = join(bundleDir, entry);
+    const normalizedCss = normalizeShadowScopedCss(readFileSync(cssPath, 'utf-8'));
+    writeFileSync(cssPath, normalizedCss);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -38,11 +162,24 @@ export function resolveProjectDir(inputDir = '.') {
  * approach: we read the file, transpile with the project's TypeScript compiler
  * when available, then evaluate as ESM.
  */
+function stripNotisSdkImports(source) {
+  return source
+    .replace(/import\s+type\s+[\s\S]*?from\s+['"][^'"]*['"]\s*;?/g, '')
+    .replace(/import\s*{[\s\S]*?\bdefineNotisApp\b[\s\S]*?}\s+from\s+['"]@notis\/sdk\/config['"]\s*;?/g, '')
+    .replace(/defineNotisApp\s*\(/g, '(');
+}
+
 function transpileTsConfigSource(source, configPath) {
+  // Strip the @notis/sdk/config import unconditionally. The SDK package often
+  // points its `exports` at raw .ts source, which Node cannot import from the
+  // temp .mjs file we emit below. `defineNotisApp` is just an identity helper,
+  // so removing the import and replacing the call with a parens-wrapped
+  // expression preserves the config value without ever resolving the SDK.
+  const stripped = stripNotisSdkImports(source);
   const requireFromConfig = createRequire(`file://${configPath}`);
   try {
     const ts = requireFromConfig('typescript');
-    const transpiled = ts.transpileModule(source, {
+    const transpiled = ts.transpileModule(stripped, {
       compilerOptions: {
         module: ts.ModuleKind.ESNext,
         target: ts.ScriptTarget.ES2020,
@@ -51,10 +188,7 @@ function transpileTsConfigSource(source, configPath) {
     });
     return transpiled.outputText;
   } catch {
-    return source
-      .replace(/import\s+type\s+[\s\S]*?from\s+['"][^'"]*['"]\s*;?/g, '')
-      .replace(/import\s*{[\s\S]*?\bdefineNotisApp\b[\s\S]*?}\s+from\s+['"]@notis\/sdk\/config['"]\s*;?/g, '')
-      .replace(/defineNotisApp\s*\(/, '(');
+    return stripped;
   }
 }
 
@@ -148,31 +282,322 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
     warnings.push('Missing Tailwind config.');
   }
 
-  if (appConfig && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)) {
+  const readsWorkspaceDatabases =
+    appConfig?.capabilities?.workspaceDatabases === 'read';
+  if (
+    appConfig
+    && !readsWorkspaceDatabases
+    && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)
+  ) {
     warnings.push('No database references declared in notis.config.ts.');
   }
 
+  if (appConfig) {
+    try {
+      const listing = inspectListingReadiness(projectDir, appConfig);
+      warnings.push(...listing.errors, ...listing.warnings);
+    } catch (error) {
+      warnings.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return warnings;
+}
+
+function safeKebab(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)+/g, '');
+}
+
+function jsStringLiteral(value) {
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function normalizeCategories(categories = []) {
+  if (!Array.isArray(categories)) {
+    return [];
+  }
+  const allowed = new Set(NOTIS_APP_CATEGORIES);
+  const normalized = [];
+  for (const category of categories) {
+    if (typeof category !== 'string' || !category.trim()) {
+      continue;
+    }
+    const trimmed = category.trim();
+    if (!allowed.has(trimmed)) {
+      throw usageError(
+        `Invalid Notis app category "${trimmed}". Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`,
+      );
+    }
+    if (!normalized.includes(trimmed)) {
+      normalized.push(trimmed);
+    }
+  }
+  return normalized;
+}
+
+function pngDimensions(buffer) {
+  const signature = '89504e470d0a1a0a';
+  if (!Buffer.isBuffer(buffer) || buffer.length < 24 || buffer.subarray(0, 8).toString('hex') !== signature) {
+    return null;
+  }
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+  };
+}
+
+function imageAssetMeta(projectDir, relPath, { maxBytes }) {
+  const fullPath = join(projectDir, relPath);
+  const content = readFileSync(fullPath);
+  const dimensions = pngDimensions(content);
+  const errors = [];
+  const warnings = [];
+
+  if (!relPath.toLowerCase().endsWith('.png')) {
+    errors.push(`${relPath} must be a PNG file.`);
+  }
+  if (content.length > maxBytes) {
+    errors.push(`${relPath} must be ${Math.round(maxBytes / 1024 / 1024)} MB or smaller.`);
+  }
+  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 {
+    path: relPath,
+    content_type: 'image/png',
+    bytes: content.length,
+    width: dimensions?.width ?? null,
+    height: dimensions?.height ?? null,
+    errors,
+    warnings,
+  };
+}
+
+export function discoverMetadataAssets(projectDir) {
+  const metadataDir = join(projectDir, METADATA_DIR);
+  const screenshots = [];
+
+  if (existsSync(metadataDir)) {
+    for (const entry of readdirSync(metadataDir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const match = /^screenshot-(\d+)\.png$/i.exec(entry.name);
+      if (!match) continue;
+      screenshots.push({
+        index: Number.parseInt(match[1], 10),
+        ...imageAssetMeta(projectDir, join(METADATA_DIR, entry.name), {
+          maxBytes: 2 * 1024 * 1024,
+        }),
+      });
+    }
+  }
+
+  screenshots.sort((a, b) => a.index - b.index);
+  return {
+    screenshots: screenshots.slice(0, 6),
+  };
+}
+
+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 };
+  });
+}
+
+/**
+ * Screenshot scenarios named in notis.config.ts that metadata/screenshot-fixtures.json
+ * does not define. A missing scenario is silent at capture time -- the harness
+ * simply falls back to the default fixtures -- so it is reported as a warning.
+ */
+export function findUnknownScreenshotScenarios(projectDir, screenshots = []) {
+  const named = screenshots.filter((entry) => entry?.scenario);
+  if (named.length === 0) {
+    return [];
+  }
+  const fixturesPath = join(projectDir, METADATA_DIR, 'screenshot-fixtures.json');
+  if (!existsSync(fixturesPath)) {
+    return ['metadata/screenshot-fixtures.json is missing, so screenshot scenarios cannot be applied.'];
+  }
+  let defined;
+  try {
+    const parsed = JSON.parse(readFileSync(fixturesPath, 'utf-8'));
+    const scenarios = parsed?.scenarios && typeof parsed.scenarios === 'object' ? parsed.scenarios : {};
+    defined = new Set(Object.keys(scenarios));
+  } catch {
+    return ['metadata/screenshot-fixtures.json is not valid JSON, so screenshot scenarios cannot be applied.'];
+  }
+  const warnings = [];
+  for (const entry of named) {
+    if (!defined.has(entry.scenario)) {
+      warnings.push(
+        `${entry.path} names scenario "${entry.scenario}", which metadata/screenshot-fixtures.json does not define.`,
+      );
+    }
+  }
   return warnings;
 }
 
+export function inspectListingReadiness(projectDir, appConfig = null) {
+  const config = appConfig || {};
+  const warnings = [];
+  const errors = [];
+  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()) {
+    errors.push('Listing tagline missing in notis.config.ts.');
+  }
+  if (categories.length === 0) {
+    errors.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
+  }
+  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(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,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Build
 // ---------------------------------------------------------------------------
 
-export async function runProjectScript({ projectDir, scriptName, env = {}, stdio = 'inherit' }) {
+export async function runProjectScript({ projectDir, scriptName, args = [], env = {}, stdio = 'inherit' }) {
   await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn('npm', ['run', scriptName], {
+    const child = spawn('npm', ['run', scriptName, ...(args.length ? ['--', ...args] : [])], {
       cwd: projectDir,
       stdio,
       env: { ...process.env, ...env },
     });
+    let capturedOutput = '';
+    for (const stream of [child.stdout, child.stderr]) {
+      stream?.on('data', (chunk) => {
+        capturedOutput += chunk.toString();
+      });
+    }
     child.on('error', rejectPromise);
     child.on('exit', (code) => {
       if (code === 0) {
         resolvePromise();
         return;
       }
-      rejectPromise(new Error(`npm run ${scriptName} failed with exit code ${code}`));
+      const detail = capturedOutput.trim();
+      rejectPromise(
+        new Error(
+          `npm run ${scriptName} failed with exit code ${code}${detail ? `:\n${detail}` : ''}`,
+        ),
+      );
     });
   });
 }
@@ -181,7 +606,7 @@ export async function runProjectScript({ projectDir, scriptName, env = {}, stdio
  * Derive an export name from a route path.
  * '/' -> 'index', '/inbox' -> 'inbox', '/my-tasks' -> 'myTasks'
  */
-function exportNameFromPath(routePath) {
+export function exportNameFromPath(routePath) {
   if (routePath === '/') return 'index';
   const slug = routePath.replace(/^\//, '').replace(/\//g, '-');
   const identifier = slug
@@ -236,11 +661,91 @@ function autoDetectRoutes(projectDir) {
   return routes;
 }
 
+function validateConfiguredRoutes(routes) {
+  if (routes.length === 0) {
+    return;
+  }
+
+  const slugSet = new Set();
+  let defaultCount = 0;
+
+  for (const route of routes) {
+    if (!route.slug || typeof route.slug !== 'string') {
+      throw usageError(`Route "${route.path}" must define a slug.`);
+    }
+    if (slugSet.has(route.slug)) {
+      throw usageError(`Duplicate route slug "${route.slug}".`);
+    }
+    slugSet.add(route.slug);
+    if (route.default) {
+      defaultCount += 1;
+    }
+    if (route.resourceDeepLinks !== undefined && typeof route.resourceDeepLinks !== 'boolean') {
+      throw usageError(`Route "${route.slug}" resourceDeepLinks must be a boolean.`);
+    }
+  }
+
+  if (defaultCount !== 1) {
+    throw usageError(`Expected exactly one default route, received ${defaultCount}.`);
+  }
+
+  for (const route of routes) {
+    if (route.parentSlug && !slugSet.has(route.parentSlug)) {
+      throw usageError(
+        `Route "${route.slug}" references unknown parentSlug "${route.parentSlug}".`,
+      );
+    }
+    const collection = route.collection || null;
+    if (
+      collection?.sidebar?.mode === 'tree' &&
+      (!collection.parentProperty || typeof collection.parentProperty !== 'string')
+    ) {
+      throw usageError(
+        `Tree collection route "${route.slug}" must define collection.parentProperty.`,
+      );
+    }
+  }
+
+  const childrenByParent = new Map();
+  for (const route of routes) {
+    if (!route.parentSlug) {
+      continue;
+    }
+    const children = childrenByParent.get(route.parentSlug) || [];
+    children.push(route.slug);
+    childrenByParent.set(route.parentSlug, children);
+  }
+
+  for (const route of routes) {
+    const seen = new Set([route.slug]);
+    let current = route.parentSlug || null;
+    while (current) {
+      if (seen.has(current)) {
+        throw usageError(`Route parent cycle detected at "${route.slug}".`);
+      }
+      seen.add(current);
+      current = routes.find((candidate) => candidate.slug === current)?.parentSlug || null;
+    }
+  }
+
+  for (const route of routes) {
+    if (
+      route.collection?.sidebar?.mode === 'tree' &&
+      (childrenByParent.get(route.slug) || []).length > 0
+    ) {
+      throw usageError(
+        `Tree collection route "${route.slug}" cannot also define static child routes.`,
+      );
+    }
+  }
+}
+
 function resolveConfiguredRoutes(appConfig, projectDir) {
   const configuredRoutes = Array.isArray(appConfig.routes) ? appConfig.routes : [];
+  validateConfiguredRoutes(configuredRoutes);
   const routes = configuredRoutes.map((route) => ({
     ...route,
-    slug: route.slug || slugFromPath(route.path),
+    slug: route.slug,
     export_name: route.exportName || route.export_name || exportNameFromPath(route.path),
   }));
   return routes.length > 0 ? routes : autoDetectRoutes(projectDir);
@@ -270,17 +775,35 @@ function generateEntryFile(projectDir, routes) {
   return entryPath;
 }
 
+export async function prepareArtifactBuild(projectDir, { enforceDesign = true, log = null } = {}) {
+  validateProjectBoundary(projectDir);
+  validateProjectDesign(projectDir, { enforce: enforceDesign, log });
+  const appConfig = await loadAppConfig(projectDir);
+  const detectedRoutes = resolveConfiguredRoutes(appConfig, projectDir);
+
+  generateEntryFile(projectDir, detectedRoutes);
+
+  const manifest = generateManifest(appConfig, projectDir);
+  const manifestPath = join(projectDir, MANIFEST_FILE);
+  mkdirSync(dirname(manifestPath), { recursive: true });
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+
+  return { appConfig, manifest, routes: detectedRoutes };
+}
+
 /**
  * Generate the manifest from app config and build output.
  */
-function generateManifest(appConfig, projectDir) {
+export function generateManifest(appConfig, projectDir) {
   const routes = resolveConfiguredRoutes(appConfig, projectDir).map((route) => {
     const entry = {
       path: route.path,
-      slug: route.slug || slugFromPath(route.path),
+      slug: route.slug,
       name: route.name,
       icon: route.icon || null,
+      parentSlug: route.parentSlug || null,
       default: route.default || false,
+      resourceDeepLinks: route.resourceDeepLinks === true,
       export_name: route.exportName || route.export_name || exportNameFromPath(route.path),
       collection: route.collection || null,
     };
@@ -290,57 +813,325 @@ function generateManifest(appConfig, projectDir) {
     return entry;
   });
 
-  const databases = appConfig.databases || [];
+  // Database entries may be a bare slug (structure only) or an object opting
+  // into shipping rows to installers. Normalize to the manifest's snake_case.
+  const databases = (appConfig.databases || []).map((entry) => {
+    if (typeof entry === 'string') return entry;
+    if (!entry || typeof entry !== 'object' || !entry.slug) return entry;
+    const seedDocuments = entry.seedDocuments ?? entry.seed_documents;
+    return seedDocuments === true ? { slug: entry.slug, seed_documents: true } : entry.slug;
+  });
+  const categories = normalizeCategories(appConfig.categories || []);
+  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: normalizeAppSkillManifestPath(skill.path),
+    name: skill.name,
+    description: skill.description || null,
+  }));
+  const listingMedia = {
+    screenshots: metadata.screenshots.map((screenshot) => ({
+      path: screenshot.path,
+      content_type: screenshot.content_type,
+      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,
-    spec_version: 3,
+    spec_version: 4,
     app: {
-      name: appConfig.name,
+      name: displayTitle,
+      slug: appSlug || null,
       description: appConfig.description || null,
       icon: appConfig.icon || null,
+      accent: appConfig.accent || null,
+      title: displayTitle,
+      tagline: appConfig.tagline || null,
+      categories,
+      author: appConfig.author || null,
+      release_version: releaseVersion,
+      version_notes: legacyVersionNotes,
     },
+    listing: {
+      title: displayTitle,
+      tagline: appConfig.tagline || null,
+      categories,
+      author: appConfig.author || null,
+      version_notes: legacyVersionNotes,
+      ...(changelog.exists
+        ? {
+            changelog: {
+              source_path: changelog.source_path,
+              entries: changelog.entries,
+            },
+          }
+        : {}),
+      media: listingMedia,
+    },
+    metadata: listingMedia,
     routes,
     bundle: {
       js: 'bundle/app.js',
       css: 'bundle/app.css',
     },
     databases,
+    capabilities: normalizeAppCapabilities(appConfig.capabilities),
     tools: appConfig.tools || [],
+    tool_bindings: normalizeAppToolBindings(appConfig.toolBindings),
+    skills,
+    onboarding: appConfig.onboarding || null,
   };
 }
 
 /**
- * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
+ * Keep the persisted app row's presentation metadata aligned with the bundle
+ * manifest. The app slug remains the stable identity; title/name is only the
+ * user-facing label.
  */
-export async function buildArtifact(projectDir) {
-  const appConfig = await loadAppConfig(projectDir);
+export function appRowFieldsFromManifest(manifest) {
+  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
+  const displayName = typeof app.title === 'string' && app.title.trim()
+    ? app.title.trim()
+    : typeof app.name === 'string' && app.name.trim()
+      ? app.name.trim()
+      : null;
+  return {
+    ...(displayName ? { name: displayName } : {}),
+    accent: app.accent ?? null,
+  };
+}
 
-  // Auto-detect or use configured routes
-  const detectedRoutes = resolveConfiguredRoutes(appConfig, projectDir);
+export function normalizeAppToolBindings(bindings) {
+  return (Array.isArray(bindings) ? bindings : [])
+    .map((binding) => {
+      const name = typeof binding?.name === 'string' ? binding.name.trim() : '';
+      const providerToolName =
+        typeof binding?.providerToolName === 'string' ? binding.providerToolName.trim() : '';
+      return name && providerToolName
+        ? { name, provider_tool_name: providerToolName }
+        : null;
+    })
+    .filter(Boolean);
+}
 
-  // Generate the entry file that re-exports all route page components
-  generateEntryFile(projectDir, detectedRoutes);
+/**
+ * Keeps only capabilities the platform actually understands, at the exact
+ * values it accepts. An unknown key or value is dropped rather than passed
+ * through, so a typo can never reach the server as a permission grant.
+ */
+export function normalizeAppCapabilities(capabilities) {
+  if (!capabilities || typeof capabilities !== 'object') {
+    return {};
+  }
+  const normalized = {};
+  if (capabilities.workspaceDatabases === 'read') {
+    normalized.workspaceDatabases = 'read';
+  }
+  if (capabilities.cloudComputer === 'read' || capabilities.cloudComputer === 'shell') {
+    normalized.cloudComputer = capabilities.cloudComputer;
+  }
+  return normalized;
+}
+
+/**
+ * Manifest form of a declared skill path: no leading `./`, no trailing slash.
+ * A directory declaration is the same string as the source-tree prefix the
+ * server matches the uploaded source files against.
+ */
+export function normalizeAppSkillManifestPath(sourcePath) {
+  return String(sourcePath || '').replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+/**
+ * Every packageable file under a declared skill directory, relative to that
+ * directory, in stable order. Excludes match `readSourceFiles` so the files a
+ * dev session sends inline are exactly the ones a deploy uploads as source.
+ */
+function readAppSkillDirectoryFiles(skillDir) {
+  const entries = [];
+
+  function walk(dir, prefix) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (shouldExcludeSourceEntry(entry.name) || entry.isSymbolicLink()) {
+        continue;
+      }
+      const fullPath = join(dir, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        entries.push({ path: relPath, absolutePath: fullPath });
+      }
+    }
+  }
+
+  walk(skillDir, '');
+  // Byte order, not locale order: the server sorts the same file set the same
+  // way before hashing it, so a dev session and a deploy agree on the hash.
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+export function resolveConfiguredAppSkills(appConfig, projectDir) {
+  const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
+  const projectRoot = resolve(projectDir);
+  const realProjectRoot = realpathSync(projectRoot);
+  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)) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+    if (lstatSync(absolutePath).isSymbolicLink()) {
+      throw usageError(`App skill entrypoint cannot be a symbolic link: ${sourcePath}`);
+    }
+    const realAbsolutePath = realpathSync(absolutePath);
+    const realRelativePath = relative(realProjectRoot, realAbsolutePath).replace(/\\/g, '/');
+    if (!realRelativePath || realRelativePath.startsWith('../') || realRelativePath === '..') {
+      throw usageError(`App skill path must stay inside the project after resolving links: ${sourcePath}`);
+    }
+
+    const description = typeof skill.description === 'string' ? skill.description.trim() : null;
+    const stats = statSync(absolutePath);
+    if (stats.isDirectory()) {
+      const entries = readAppSkillDirectoryFiles(absolutePath);
+      if (!entries.some((entry) => entry.path === 'SKILL.md')) {
+        throw usageError(`App skill directory must contain SKILL.md: ${sourcePath}`);
+      }
+      const bundleFiles = entries.map((entry) => ({
+        path: entry.path,
+        content: readFileSync(entry.absolutePath),
+      }));
+      const totalBytes = bundleFiles.reduce((total, entry) => total + entry.content.length, 0);
+      if (totalBytes > MAX_APP_SKILL_BUNDLE_BYTES) {
+        throw usageError(
+          `App skill "${key}" bundles ${totalBytes} bytes, above the ${MAX_APP_SKILL_BUNDLE_BYTES} byte limit.`,
+        );
+      }
+      const skillMd = bundleFiles.find((entry) => entry.path === 'SKILL.md');
+      return {
+        key,
+        path: relativePath,
+        name,
+        description,
+        skill_md: skillMd.content.toString('utf8'),
+        bundle_files: bundleFiles.map((entry) => ({
+          path: entry.path,
+          content_b64: entry.content.toString('base64'),
+        })),
+      };
+    }
+    if (!stats.isFile()) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
 
-  // Run Vite build
+    return {
+      key,
+      path: relativePath,
+      name,
+      description,
+      skill_md: readFileSync(absolutePath, 'utf8'),
+    };
+  });
+}
+
+/**
+ * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
+ */
+export async function buildArtifact(projectDir, { stdio = 'inherit' } = {}) {
+  projectDir = realpathSync(projectDir);
+  const workspace = withAppReleaseWorkspace(projectDir, (identity) => {
+    rmSync('build-receipt.json', { force: true });
+    return identity;
+  }, { create: true });
+  // SDK refresh is intentional source preparation, before the immutable build receipt.
+  syncEmbeddedSdk(projectDir);
+  const sourceHash = appFilesDigest(collectSourceFiles(projectDir));
+  await prepareArtifactBuild(projectDir);
+
+  // Historical source must round-trip byte-for-byte. Supply the compatible
+  // config loader at execution for the old canonical script, without editing
+  // pulled package.json files or interpreting custom shell commands.
+  const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+  const args = String(pkg.scripts?.build || '').trim() === 'vite build'
+    ? ['--configLoader', 'runner']
+    : [];
   await runProjectScript({
     projectDir,
     scriptName: 'build',
+    args,
+    stdio,
   });
 
-  // Verify output
-  const bundleDir = join(projectDir, BUNDLE_DIR);
-  const jsPath = join(bundleDir, 'app.js');
-  if (!existsSync(jsPath)) {
-    throw usageError('Vite build did not produce .notis/output/bundle/app.js. Check your vite.config.ts.');
+  withAppReleaseWorkspace(projectDir, () => {}, { expected: workspace });
+
+  // Verify the canonical `.notis/output/bundle` packaging contract.
+  const builtBundleDir = resolveBuiltBundleDir(projectDir);
+  if (!builtBundleDir) {
+    throw usageError(
+      'Vite build did not produce app.js in .notis/output/bundle. Check your vite.config.ts.',
+    );
   }
+  normalizeBundleStylesheets(projectDir);
+  copyMetadataAssets(projectDir);
 
-  // Generate manifest
-  const manifest = generateManifest(appConfig, projectDir);
-  const manifestPath = join(projectDir, MANIFEST_FILE);
-  mkdirSync(dirname(manifestPath), { recursive: true });
-  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  validateArtifactBoundary(readArtifactFiles(projectDir));
+
+  const manifest = readManifest(projectDir);
 
+  if (sourceHash !== appFilesDigest(collectSourceFiles(projectDir))) {
+    throw usageError('App source changed during the build. Build again before deploying.');
+  }
+  const receipt = JSON.stringify({
+    source_hash: sourceHash,
+    artifact_hash: appFilesDigest(collectArtifactFiles(projectDir)),
+  });
+  withAppReleaseWorkspace(projectDir, () => {
+    const temporary = `.build-receipt-${randomUUID()}`;
+    try {
+      writeFileSync(temporary, receipt, { flag: 'wx' });
+      renameSync(temporary, 'build-receipt.json');
+    } finally { rmSync(temporary, { force: true }); }
+  }, { expected: workspace });
   return { manifest, outputDir: join(projectDir, OUTPUT_DIR) };
 }
 
@@ -355,66 +1146,998 @@ export function readManifest(projectDir) {
   return JSON.parse(readFileSync(manifestPath, 'utf-8'));
 }
 
+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;
+  }
+  mkdirSync(outputMetadataDir, { recursive: true });
+  for (const entry of readdirSync(metadataDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!/^screenshot-\d+\.png$/i.test(entry.name)) {
+      continue;
+    }
+    cpSync(join(metadataDir, entry.name), join(outputMetadataDir, entry.name));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Linking
 // ---------------------------------------------------------------------------
 
-export function readLinkedState(projectDir) {
-  const statePath = join(projectDir, STATE_FILE);
-  if (!existsSync(statePath)) return null;
-  return JSON.parse(readFileSync(statePath, 'utf-8'));
+const PROFILE_LINK_FIELDS = new Set([
+  'app_id',
+  'linked_at',
+  'expected_updated_at',
+  'deployed_at',
+  'version',
+]);
+
+function splitLinkedState(state) {
+  const base = {};
+  const link = {};
+  for (const [key, value] of Object.entries(state || {})) {
+    if (key === 'profiles') continue;
+    (PROFILE_LINK_FIELDS.has(key) ? link : base)[key] = value;
+  }
+  return { base, link };
 }
 
-export function writeLinkedState(projectDir, state) {
-  const statePath = join(projectDir, STATE_FILE);
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+export function appLinkedStateProfileKey({ apiBase, userId }) {
+  const normalizedApi = String(apiBase || '').trim().replace(/\/$/, '');
+  const normalizedUser = String(userId || '').trim();
+  if (!normalizedApi || !normalizedUser) return null;
+  return Buffer.from(`${normalizedApi}\0${normalizedUser}`).toString('base64url');
 }
 
-export function requireLinkedAppId(projectDir, explicitAppId) {
-  if (explicitAppId) return explicitAppId;
-  const state = readLinkedState(projectDir);
-  if (state?.app_id) return state.app_id;
-  throw usageError('This project is not linked to a Notis app. Run "notis apps link <app-id> ." first.');
+export function readLinkedState(projectDir, profileKey = null) {
+  const statePath = join(projectDir, STATE_FILE);
+  assertLinkedStatePathSafe(projectDir);
+  if (!existsSync(statePath)) return null;
+  const raw = JSON.parse(readFileSync(statePath, 'utf-8'));
+  if (!profileKey) return raw;
+  const { base, link: legacyLink } = splitLinkedState(raw);
+  const profiles = raw?.profiles && typeof raw.profiles === 'object' ? raw.profiles : {};
+  const scoped = profiles[profileKey];
+  return {
+    ...base,
+    ...(scoped && typeof scoped === 'object' ? scoped : legacyLink),
+  };
 }
 
-// ---------------------------------------------------------------------------
-// Scaffolding
-// ---------------------------------------------------------------------------
-
-/**
- * Scaffold a new Notis app project from the SDK template.
- */
-export function scaffoldProject({ projectDir, appName }) {
-  const templateDir = resolve(
-    dirname(fileURLToPath(import.meta.url)),
-    '../../template',
-  );
+function readStateWriteLockOwner(lockPath) {
+  try {
+    return readFileSync(join(lockPath, 'owner'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
 
-  if (!existsSync(templateDir)) {
-    throw usageError(`SDK template not found at ${templateDir}. Ensure @notis_ai/cli is installed correctly.`);
+function reclaimStaleStateWriteLock(lockPath, observedOwner, observedMtimeMs) {
+  const quarantinePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+  try {
+    renameSync(lockPath, quarantinePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
   }
 
-  mkdirSync(projectDir, { recursive: true });
-  cpSync(templateDir, projectDir, { recursive: true });
+  let unchanged = false;
+  try {
+    const quarantinedStat = lstatSync(quarantinePath);
+    unchanged = readStateWriteLockOwner(quarantinePath) === observedOwner
+      && quarantinedStat.mtimeMs === observedMtimeMs;
+  } catch (error) {
+    try {
+      renameSync(quarantinePath, lockPath);
+    } catch {
+      // Fail closed below if the quarantined lock cannot be restored.
+    }
+    throw error;
+  }
+
+  if (!unchanged) {
+    try {
+      renameSync(quarantinePath, lockPath);
+    } catch {
+      throw usageError(`Notis app state lock changed while it was being recovered: ${lockPath}`);
+    }
+    return false;
+  }
+
+  rmSync(quarantinePath, { recursive: true, force: true });
+  return true;
+}
+
+function withStateWriteLock(statePath, callback) {
+  mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+  const lockPath = `${statePath}.write-lock`;
+  const ownerId = `${process.pid}.${randomUUID()}`;
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      try {
+        writeFileSync(join(lockPath, 'owner'), ownerId, { mode: 0o600, flag: 'wx' });
+      } catch (error) {
+        // A stale-lock recovery may have moved this candidate while the owner
+        // record was being written. Never remove a replacement writer's lock.
+        if (readStateWriteLockOwner(lockPath) === ownerId) {
+          rmSync(lockPath, { recursive: true, force: true });
+        }
+        throw error;
+      }
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = lstatSync(lockPath);
+        if (lockStat.isSymbolicLink() || !lockStat.isDirectory()) {
+          throw usageError(`Refusing unsafe Notis app state lock: ${lockPath}`);
+        }
+        const observedOwner = readStateWriteLockOwner(lockPath);
+        const ownerPidText = String(observedOwner || '').split('.')[0];
+        const ownerPid = /^\d+$/.test(ownerPidText) ? Number.parseInt(ownerPidText, 10) : null;
+        // PID liveness alone is insufficient: operating systems can reuse a
+        // crashed writer's PID for an unrelated process. A linked-state write
+        // is synchronous and normally holds this lock only for milliseconds,
+        // so an aged lock is stale even when that numeric PID now exists.
+        let stale = Date.now() - lockStat.mtimeMs >= STATE_WRITE_LOCK_STALE_MS;
+        if (!stale && Number.isInteger(ownerPid) && ownerPid > 0) {
+          try {
+            process.kill(ownerPid, 0);
+          } catch (ownerError) {
+            if (ownerError?.code === 'ESRCH') {
+              stale = true;
+            }
+          }
+        }
+        if (stale && reclaimStaleStateWriteLock(lockPath, observedOwner, lockStat.mtimeMs)) {
+          continue;
+        }
+      } catch (statError) {
+        if (statError?.code === 'ENOENT') continue;
+        throw statError;
+      }
+      if (Date.now() - startedAt >= STATE_WRITE_LOCK_TIMEOUT_MS) {
+        throw usageError(`Timed out waiting to update Notis app state: ${statePath}`);
+      }
+      Atomics.wait(stateWriteLockWait, 0, 0, 10);
+    }
+  }
+  try {
+    return callback();
+  } finally {
+    try {
+      if (readStateWriteLockOwner(lockPath) === ownerId) {
+        rmSync(lockPath, { recursive: true, force: true });
+      }
+    } catch {
+      // Never remove a lock that no longer belongs to this writer.
+    }
+  }
+}
+
+export function writeLinkedState(projectDir, state, profileKey = null) {
+  const statePath = join(projectDir, STATE_FILE);
+  assertLinkedStatePathSafe(projectDir);
+  return withStateWriteLock(statePath, () => {
+    let nextState = state;
+    if (profileKey) {
+      let current = {};
+      if (existsSync(statePath)) {
+        current = JSON.parse(readFileSync(statePath, 'utf-8'));
+      }
+      const { base: currentBase } = splitLinkedState(current);
+      const { base } = splitLinkedState(state);
+      const { link } = splitLinkedState(state);
+      const profiles = current?.profiles && typeof current.profiles === 'object'
+        ? { ...current.profiles }
+        : {};
+      profiles[profileKey] = link;
+      nextState = { ...currentBase, ...base, profiles };
+    }
+    const temporary = `${statePath}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(nextState, null, 2) + '\n');
+    renameSync(temporary, statePath);
+  });
+}
+
+function assertLinkedStatePathSafe(projectDir) {
+  const notisDir = join(projectDir, NOTIS_DIR);
+  try {
+    const directoryStat = lstatSync(notisDir);
+    if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+      throw usageError(`Refusing to use unsafe Notis state directory: ${notisDir}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+
+  const statePath = join(projectDir, STATE_FILE);
+  try {
+    const stateStat = lstatSync(statePath);
+    if (stateStat.isSymbolicLink() || !stateStat.isFile()) {
+      throw usageError(`Refusing to use unsafe Notis state file: ${statePath}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+export function requireLinkedAppId(projectDir, explicitAppId, profileKey = null) {
+  if (explicitAppId) return explicitAppId;
+  const state = readLinkedState(projectDir, profileKey);
+  if (state?.app_id) return state.app_id;
+  throw usageError('This project is not linked to a Notis app. Run "notis apps link <app-id> ." first.');
+}
+
+// ---------------------------------------------------------------------------
+// Scaffolding
+// ---------------------------------------------------------------------------
+
+/**
+ * Scaffold a new Notis app project from the SDK template or from a published
+ * Store app downloaded from the public registry repository.
+ */
+export async function scaffoldProject({ projectDir, appName, fromSlug = null }) {
+  let scaffoldSource = null;
+  if (fromSlug) {
+    scaffoldSource = await acquireScaffoldSource(fromSlug);
+    if (!scaffoldSource) {
+      const known = (await loadScaffoldCatalog()).map((entry) => entry.slug).join(', ') || 'none';
+      throw usageError(`Unknown scaffold "${fromSlug}". Available scaffolds: ${known}.`);
+    }
+  }
+  try {
+    return scaffoldProjectFromDir({
+      projectDir,
+      appName,
+      fromSlug,
+      templateDir: scaffoldSource ? scaffoldSource.dir : join(CLI_ROOT, 'template'),
+    });
+  } finally {
+    scaffoldSource?.cleanup();
+  }
+}
+
+function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir }) {
+  const sourceDir = resolve(templateDir);
+  const requestedProjectDir = resolve(projectDir);
+  if (!existsSync(sourceDir)) {
+    throw usageError(`SDK template not found at ${sourceDir}. Ensure @notis_ai/cli is installed correctly.`);
+  }
+
+  const parentDir = dirname(requestedProjectDir);
+  const targetName = basename(requestedProjectDir);
+  mkdirSync(parentDir, { recursive: true });
+  const canonicalParent = realpathSync(parentDir);
+  const parentIdentity = capturePullTargetIdentity(canonicalParent);
+  const initialTargetIdentity = captureScaffoldTargetIdentity(requestedProjectDir);
+  const previousCwd = process.cwd();
+  const previousCwdIdentity = capturePullTargetIdentity(previousCwd);
+  let cwdPinned = false;
+  let stageName = null;
+  let cleanupStage = true;
+  let activeTargetIdentity = null;
+  const scaffoldLockName = '.notis-app-scaffold-lock';
+  const scaffoldLockOwnerId = `${process.pid}.${randomUUID()}`;
+  try {
+    process.chdir(canonicalParent);
+    cwdPinned = true;
+    assertPullTargetIdentity('.', parentIdentity);
+    const lockedTargetIdentity = captureScaffoldTargetIdentity(targetName);
+    if (!pullTargetIdentitiesMatch(initialTargetIdentity, lockedTargetIdentity)) {
+      throw usageError(`App scaffold target changed before copying: ${requestedProjectDir}`);
+    }
+    if (!lockedTargetIdentity.exists) {
+      try {
+        mkdirSync(targetName);
+      } catch (error) {
+        if (error?.code === 'EEXIST') {
+          throw usageError(`App scaffold target changed before copying: ${requestedProjectDir}`);
+        }
+        throw error;
+      }
+    }
+    activeTargetIdentity = captureScaffoldTargetIdentity(targetName);
+    process.chdir(targetName);
+    if (!pullTargetIdentitiesMatch(
+      activeTargetIdentity,
+      captureScaffoldTargetIdentity('.'),
+    )) {
+      throw usageError(`App scaffold target changed before copying: ${requestedProjectDir}`);
+    }
+    mkdirSync(scaffoldLockName, { mode: 0o700 });
+    writeFileSync(
+      join(scaffoldLockName, 'owner'),
+      JSON.stringify({ id: scaffoldLockOwnerId }),
+      { mode: 0o600 },
+    );
+
+    stageName = basename(mkdtempSync(join('.', '.notis-app-scaffold-')));
+    projectDir = stageName;
+
+    copyScaffoldSource(sourceDir, projectDir);
+
+    // Update package.json with the app name
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      pkg.name = appName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+      // A scaffold creates a new app identity, even when its source comes from a
+      // versioned Store example. New apps must therefore start their own release
+      // history instead of inheriting the example app's registry version.
+      pkg.notisAppVersion = '0.1.0';
+      normalizeScaffoldPackageScripts(pkg);
+      ensureScaffoldLocalSdk(projectDir, pkg);
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      normalizeScaffoldLockfile(projectDir, pkg);
+    }
+
+    // Update notis.config.ts with the app name
+    const configPath = join(projectDir, 'notis.config.ts');
+    if (existsSync(configPath)) {
+      let config = readFileSync(configPath, 'utf-8');
+      const displayName = jsStringLiteral(appName);
+      const slugName = jsStringLiteral(safeKebab(appName) || 'my-notis-app');
+      if (fromSlug) {
+        if (/name\s*:/.test(config)) {
+          config = config.replace(/name\s*:\s*(['"`])[\s\S]*?\1/, `name: ${slugName}`);
+        }
+        if (/title\s*:/.test(config)) {
+          config = config.replace(/title\s*:\s*(['"`])[\s\S]*?\1/, `title: ${displayName}`);
+        } else {
+          config = config.replace(/name\s*:\s*(['"`])[\s\S]*?\1/, `name: ${slugName},\n  title: ${displayName}`);
+        }
+      } else {
+        if (/name\s*:/.test(config)) {
+          config = config.replace(/name\s*:\s*(['"`])[\s\S]*?\1/, `name: ${slugName}`);
+        }
+        if (/title\s*:/.test(config)) {
+          config = config.replace(/title\s*:\s*(['"`])[\s\S]*?\1/, `title: ${displayName}`);
+        } else {
+          config = config.replace(/'My Notis App'/, displayName);
+        }
+      }
+      config = removeConfigArrayProperty(config, 'screenshots');
+      writeFileSync(configPath, config);
+    }
+
+    resetScaffoldChangelog(projectDir, appName);
+
+    assertPullParentIdentity(parentDir, canonicalParent, parentIdentity);
+    assertPullTargetIdentity(requestedProjectDir, activeTargetIdentity);
+    const stageRoot = realpathSync(stageName);
+    const installedEntries = [];
+    const installedDirectoryIdentities = new Map([['', activeTargetIdentity]]);
+    const captureInstalledEntry = (entryPath) => {
+      const entryStat = lstatSync(entryPath, { bigint: true });
+      return {
+        exists: true,
+        path: entryPath,
+        dev: entryStat.dev,
+        ino: entryStat.ino,
+        directory: entryStat.isDirectory(),
+      };
+    };
+    const installExclusive = (sourcePath, destinationName, relativePath, parentIdentity) => {
+      const sourceStat = lstatSync(sourcePath);
+      if (sourceStat.isSymbolicLink()) {
+        throw usageError(`Refusing symlinked scaffold source entry: ${sourcePath}`);
+      }
+      if (sourceStat.isDirectory()) {
+        mkdirSync(destinationName, { mode: sourceStat.mode & 0o777 });
+        const installedDirectory = captureInstalledEntry(destinationName);
+        installedDirectory.path = relativePath;
+        installedEntries.push(installedDirectory);
+        installedDirectoryIdentities.set(relativePath, installedDirectory);
+        process.chdir(destinationName);
+        if (!pullTargetIdentitiesMatch(
+          installedDirectory,
+          capturePullTargetIdentity('.'),
+        )) {
+          throw usageError(`App scaffold destination changed during installation: ${relativePath}`);
+        }
+        try {
+          for (const name of readdirSync(sourcePath)) {
+            installExclusive(
+              join(sourcePath, name),
+              name,
+              `${relativePath}/${name}`,
+              installedDirectory,
+            );
+          }
+        } finally {
+          const parentRelativePath = dirname(relativePath) === '.' ? '' : dirname(relativePath);
+          process.chdir(parentRelativePath
+            ? join(requestedProjectDir, parentRelativePath)
+            : requestedProjectDir);
+          if (!pullTargetIdentitiesMatch(
+            parentIdentity,
+            capturePullTargetIdentity('.'),
+          )) {
+            throw usageError(`App scaffold destination changed during installation: ${parentRelativePath || '.'}`);
+          }
+        }
+        return;
+      }
+      if (!sourceStat.isFile()) {
+        throw usageError(`Refusing unsupported scaffold source entry: ${sourcePath}`);
+      }
+      copyFileSync(sourcePath, destinationName, fsConstants.COPYFILE_EXCL);
+      const installedFile = captureInstalledEntry(destinationName);
+      installedFile.path = relativePath;
+      installedEntries.push(installedFile);
+    };
+    try {
+      for (const name of readdirSync(stageName)) {
+        installExclusive(join(stageRoot, name), name, name, activeTargetIdentity);
+      }
+      assertPullParentIdentity(parentDir, canonicalParent, parentIdentity);
+      assertPullTargetIdentity(requestedProjectDir, activeTargetIdentity);
+    } catch (error) {
+      try {
+        for (const installed of installedEntries.reverse()) {
+          const parentRelativePath = dirname(installed.path) === '.' ? '' : dirname(installed.path);
+          const parentPath = parentRelativePath
+            ? join(requestedProjectDir, parentRelativePath)
+            : requestedProjectDir;
+          const expectedParentIdentity = installedDirectoryIdentities.get(parentRelativePath);
+          process.chdir(parentPath);
+          if (!expectedParentIdentity || !pullTargetIdentitiesMatch(
+            expectedParentIdentity,
+            capturePullTargetIdentity('.'),
+          )) {
+            throw usageError(
+              `Refusing to roll back a scaffold directory that changed concurrently: ${parentPath}`,
+            );
+          }
+          const entryName = basename(installed.path);
+          const current = captureInstalledEntry(entryName);
+          if (
+            current.dev !== installed.dev
+            || current.ino !== installed.ino
+            || current.directory !== installed.directory
+          ) {
+            throw usageError(
+              `Refusing to roll back a scaffold entry that changed concurrently: ${installed.path}`,
+            );
+          }
+          if (installed.directory) {
+            rmdirSync(entryName);
+          } else {
+            unlinkSync(entryName);
+          }
+        }
+      } catch (rollbackError) {
+        cleanupStage = false;
+        throw usageError(
+          `${error instanceof Error ? error.message : String(error)} `
+          + `Scaffold rollback failed; recovery files were retained at `
+          + `${join(requestedProjectDir, stageName)}: `
+          + `${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+        );
+      }
+      throw error;
+    }
+    try {
+      rmSync(stageName, { recursive: true, force: true });
+      stageName = null;
+    } catch (error) {
+      cleanupStage = false;
+      throw usageError(
+        `App scaffold was installed, but staging cleanup failed; recovery files were retained at `
+        + `${join(requestedProjectDir, stageName)}: `
+        + `${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  } finally {
+    try {
+      let targetPinnedForCleanup = false;
+      if (activeTargetIdentity) {
+        try {
+          process.chdir(requestedProjectDir);
+          targetPinnedForCleanup = pullTargetIdentitiesMatch(
+            activeTargetIdentity,
+            capturePullTargetIdentity('.'),
+          );
+        } catch {
+          targetPinnedForCleanup = false;
+        }
+      }
+      if (targetPinnedForCleanup && cleanupStage && stageName) {
+        rmSync(stageName, { recursive: true, force: true });
+      }
+      if (
+        targetPinnedForCleanup
+        && readPullLockOwner(scaffoldLockName)?.id === scaffoldLockOwnerId
+      ) {
+        rmSync(scaffoldLockName, { recursive: true, force: true });
+      }
+    } finally {
+      if (cwdPinned) {
+        const cwdMatchesPrevious = (
+          previousCwdIdentity.exists
+          && pullTargetIdentitiesMatch(previousCwdIdentity, capturePullTargetIdentity('.'))
+        );
+        if (!cwdMatchesPrevious) {
+          process.chdir(previousCwd);
+        }
+      }
+    }
+  }
+
+  return { projectDir: requestedProjectDir };
+}
 
-  // Update package.json with the app name
-  const pkgPath = join(projectDir, 'package.json');
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    pkg.name = appName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
-    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+function normalizeScaffoldPackageScripts(pkg) {
+  const scripts = pkg?.scripts;
+  if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {
+    return;
+  }
+  // The linked SDK exports TypeScript. Vite's bundled config loader externalizes
+  // that import to Node, which cannot load it on supported Node 18/20 runtimes.
+  // Normalize only canonical commands; never parse or rewrite custom shell code.
+  for (const [name, command] of Object.entries(scripts)) {
+    if (typeof command === 'string' && /^(vite|vite build|vite preview)$/.test(command.trim())) {
+      scripts[name] = `${command.trim()} --configLoader runner`;
+    }
+  }
+  const generateEntry = String(scripts['generate-entry'] || '').trim();
+  if (!/^tsx\s+\.\.\/\.\.\/scripts\/generate-entry\.ts\s+\.$/.test(generateEntry)) {
+    return;
+  }
+  for (const [name, command] of Object.entries(scripts)) {
+    if (name === 'generate-entry' || typeof command !== 'string') {
+      continue;
+    }
+    if (command.trim() === 'npm run generate-entry') {
+      delete scripts[name];
+    }
+  }
+  scripts['generate-entry'] = 'node -e ""';
+}
+
+function captureScaffoldTargetIdentity(targetDir) {
+  try {
+    const targetStat = lstatSync(targetDir, { bigint: true });
+    if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+      throw usageError(`Refusing to scaffold through an unsafe target: ${targetDir}`);
+    }
+    if (readdirSync(targetDir).length > 0) {
+      throw usageError(`App scaffold target must be empty: ${targetDir}`);
+    }
+    return { exists: true, dev: targetStat.dev, ino: targetStat.ino };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, dev: null, ino: null };
+    throw error;
   }
+}
 
-  // Update notis.config.ts with the app name
-  const configPath = join(projectDir, 'notis.config.ts');
-  if (existsSync(configPath)) {
-    let config = readFileSync(configPath, 'utf-8');
-    config = config.replace(/'My Notis App'/, `'${appName.replace(/'/g, "\\'")}'`);
-    writeFileSync(configPath, config);
+/**
+ * Drop `property: [ ... ]` from a notis.config.ts source.
+ *
+ * The scan tracks bracket depth while skipping string literals, so entries
+ * whose text contains a bracket (alt text, selectors) cannot end the array
+ * early. When the array cannot be resolved the source is returned untouched --
+ * a stale screenshots list is a warning at verify time, a broken config is not.
+ */
+function removeConfigArrayProperty(source, property) {
+  const start = source.search(new RegExp(`^[ \\t]*${property}[ \\t]*:[ \\t]*\\[`, 'm'));
+  if (start === -1) {
+    return source;
+  }
+  let index = source.indexOf('[', start);
+  let depth = 0;
+  let quote = null;
+  for (; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (char === '\\') {
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '\'' || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '[') {
+      depth += 1;
+    } else if (char === ']') {
+      depth -= 1;
+      if (depth === 0) {
+        break;
+      }
+    }
+  }
+  if (depth !== 0) {
+    return source;
+  }
+  let end = index + 1;
+  if (source[end] === ',') {
+    end += 1;
+  }
+  while (end < source.length && (source[end] === ' ' || source[end] === '\t')) {
+    end += 1;
+  }
+  if (source[end] === '\n') {
+    end += 1;
+  }
+  return source.slice(0, start) + source.slice(end);
+}
+
+/**
+ * A new project starts its own release history: the scaffold's entries describe
+ * releases of a different app.
+ */
+function resetScaffoldChangelog(projectDir, appName) {
+  const changelogPath = join(projectDir, 'CHANGELOG.md');
+  if (!existsSync(changelogPath)) {
+    return;
+  }
+  writeFileSync(
+    changelogPath,
+    `# ${appName} Changelog\n\n## [Initial Release] - ${CHANGELOG_MERGE_DATE}\n\n- First Store release.\n`,
+  );
+}
+
+function normalizeScaffoldLockfile(projectDir, pkg) {
+  const lockPath = join(projectDir, 'package-lock.json');
+  if (!existsSync(lockPath)) {
+    return;
+  }
+
+  const lockfile = JSON.parse(readFileSync(lockPath, 'utf-8'));
+  lockfile.name = pkg.name;
+  if (lockfile.packages?.['']) {
+    lockfile.packages[''].name = pkg.name;
+  }
+  writeFileSync(lockPath, JSON.stringify(lockfile, null, 2) + '\n');
+}
+
+function ensureScaffoldLocalSdk(projectDir, pkg) {
+  let shouldInstallLocalSdk = false;
+  for (const dependencyGroup of ['dependencies', 'devDependencies']) {
+    const dependencyValue = pkg[dependencyGroup]?.['@notis/sdk'];
+    if (typeof dependencyValue === 'string' && dependencyValue.startsWith('file:')) {
+      pkg[dependencyGroup]['@notis/sdk'] = 'file:./packages/sdk';
+      shouldInstallLocalSdk = true;
+    }
+  }
+
+  if (!shouldInstallLocalSdk) {
+    return;
+  }
+
+  const localSdkDir = join(projectDir, 'packages', 'sdk');
+  if (existsSync(join(localSdkDir, 'package.json'))) {
+    return;
+  }
+  if (!existsSync(join(TEMPLATE_SDK_DIR, 'package.json'))) {
+    throw usageError(`SDK template not found at ${TEMPLATE_SDK_DIR}. Ensure @notis_ai/cli is installed correctly.`);
+  }
+
+  mkdirSync(dirname(localSdkDir), { recursive: true });
+  cpSync(TEMPLATE_SDK_DIR, localSdkDir, { recursive: true, dereference: true });
+}
+
+function listFilesRecursive(dir, base = dir, results = []) {
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      listFilesRecursive(fullPath, base, results);
+    } else {
+      results.push(relative(base, fullPath).split(sep).join('/'));
+    }
+  }
+  return results;
+}
+
+/**
+ * Keep an app's embedded `packages/sdk` copy identical to the SDK this CLI
+ * ships. The copy is a mirror by contract (the parity test in the CLI keeps
+ * the template in step with packages/sdk), so an app never edits it; before
+ * this sync existed every app silently ran whatever SDK snapshot it was
+ * scaffolded with and never received hook or style updates.
+ *
+ * Files that exist locally but not in the template are left alone with a
+ * warning so a deliberate local addition is never destroyed.
+ */
+export function syncEmbeddedSdk(projectDir, { log = null, templateSdkDir = TEMPLATE_SDK_DIR } = {}) {
+  const canonicalProjectDir = realpathSync(projectDir);
+  const canonicalTemplateDir = resolve(templateSdkDir);
+  if (!existsSync(join(canonicalTemplateDir, 'package.json'))) {
+    return { updated: false, reason: 'no-template-sdk' };
+  }
+  const previousCwd = process.cwd();
+  const previousIdentity = capturePullTargetIdentity(previousCwd);
+  const projectIdentity = capturePullTargetIdentity(canonicalProjectDir);
+  const templateFiles = listFilesRecursive(canonicalTemplateDir).filter(
+    (relPath) => relPath === 'package.json' || relPath === 'tsconfig.json' || relPath.startsWith('src/'),
+  );
+  const changed = [];
+  let foreign = [];
+
+  // Pin each app-controlled parent as cwd before touching a child. Absolute
+  // path writes would follow a replaced packages/sdk or src directory link.
+  function inDirectory(name, callback, { create = false } = {}) {
+    const parentIdentity = capturePullTargetIdentity('.');
+    let identity = capturePullTargetIdentity(name);
+    if (!identity.exists) {
+      if (!create) return { updated: false, reason: 'no-embedded-sdk' };
+      mkdirSync(name);
+      identity = capturePullTargetIdentity(name);
+    }
+    process.chdir(name);
+    try {
+      assertPullTargetIdentity('.', identity);
+      return callback();
+    } finally {
+      process.chdir('..');
+      assertPullTargetIdentity('.', parentIdentity);
+    }
+  }
+
+  function mirrorFile(segments, source) {
+    if (segments.length > 1) {
+      return inDirectory(segments[0], () => mirrorFile(segments.slice(1), source), { create: true });
+    }
+    const name = segments[0];
+    let before;
+    try { before = lstatSync(name, { bigint: true }); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (before) {
+      if (before.isSymbolicLink() || !before.isFile()) {
+        throw usageError(`Refusing to refresh the SDK through an unsafe target: ${name}`);
+      }
+      const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+      try {
+        if (Buffer.compare(readStablePinnedFile(descriptor, before, `SDK file ${name}`), source) === 0) return false;
+      } finally { closeSync(descriptor); }
+    }
+    // Replace, never truncate: an app-controlled hard link must not modify
+    // another file. O_EXCL staging and rename are relative to the pinned cwd.
+    const temporary = `.notis-sdk-sync-${randomUUID()}`;
+    try {
+      writeFileSync(temporary, source, { flag: 'wx' });
+      renameSync(temporary, name);
+    } finally { rmSync(temporary, { force: true }); }
+    return true;
+  }
+
+  try {
+    process.chdir(canonicalProjectDir);
+    assertPullTargetIdentity('.', projectIdentity);
+    const result = inDirectory('packages', () => inDirectory('sdk', () => {
+      let packageStat;
+      try { packageStat = lstatSync('package.json'); }
+      catch (error) {
+        if (error.code === 'ENOENT') return { updated: false, reason: 'no-embedded-sdk' };
+        throw error;
+      }
+      if (packageStat.isSymbolicLink() || !packageStat.isFile()) {
+        throw usageError('Refusing to refresh the SDK through an unsafe package.json target.');
+      }
+      for (const relPath of templateFiles) {
+        const source = readFileSync(join(canonicalTemplateDir, relPath));
+        if (mirrorFile(relPath.split('/'), source)) changed.push(relPath);
+      }
+      const templateSet = new Set(templateFiles);
+      foreign = listFilesRecursive('.').filter((relPath) => relPath.startsWith('src/') && !templateSet.has(relPath));
+      return null;
+    }));
+    if (result) return result;
+    assertPullTargetIdentity('.', projectIdentity);
+  } finally {
+    process.chdir(previousCwd);
+    assertPullTargetIdentity('.', previousIdentity);
+  }
+
+  const templateVersion = JSON.parse(readFileSync(join(canonicalTemplateDir, 'package.json'), 'utf-8')).version;
+  const emit = typeof log === 'function' ? log : (message) => process.stderr.write(`${message}\n`);
+  if (changed.length > 0) {
+    emit(`Updated embedded @notis/sdk to ${templateVersion} (${changed.length} file${changed.length === 1 ? '' : 's'}).`);
+  }
+  for (const relPath of foreign) {
+    emit(`Warning: packages/sdk/${relPath} is not part of the @notis/sdk template and was left unchanged.`);
+  }
+  return { updated: changed.length > 0, changed, foreign, templateVersion };
+}
+
+// Registry bookkeeping shipped alongside a published app's source: the listing
+// descriptor and the rendered Store gallery describe the published app, so a
+// scaffold copy must not inherit them.
+const REGISTRY_ARTIFACTS = /^(notis-listing\.json$|screenshots(\/|$))/;
+
+function readStablePinnedFile(descriptor, expectedStat, label) {
+  const before = fstatSync(descriptor, { bigint: true });
+  if (
+    !before.isFile()
+    || before.dev !== expectedStat.dev
+    || before.ino !== expectedStat.ino
+  ) {
+    throw usageError(`${label} changed before it could be read.`);
+  }
+  const content = readFileSync(descriptor);
+  const after = fstatSync(descriptor, { bigint: true });
+  if (
+    after.dev !== before.dev
+    || after.ino !== before.ino
+    || after.size !== before.size
+    || after.mtimeNs !== before.mtimeNs
+    || after.ctimeNs !== before.ctimeNs
+  ) {
+    throw usageError(`${label} changed while it was being read.`);
+  }
+  return content;
+}
+
+function captureDirectoryRevision() {
+  const stat = statSync('.', { bigint: true });
+  return { dev: stat.dev, ino: stat.ino, mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs };
+}
+
+function assertDirectoryRevisionUnchanged(before, label) {
+  const after = captureDirectoryRevision();
+  if (
+    after.dev !== before.dev
+    || after.ino !== before.ino
+    || after.mtimeNs !== before.mtimeNs
+    || after.ctimeNs !== before.ctimeNs
+  ) {
+    throw usageError(`${label} changed while it was being read.`);
+  }
+}
+
+function copyScaffoldSource(sourceDir, targetDir) {
+  function shouldCopy(path) {
+    const name = path.split(/[\\/]/).pop();
+    if (!name) return true;
+    const relPath = relative(sourceDir, path).replace(/\\/g, '/');
+    if (SCAFFOLD_LISTING_MEDIA.test(relPath) || REGISTRY_ARTIFACTS.test(relPath)) {
+      return false;
+    }
+    return !SCAFFOLD_COPY_EXCLUDES.has(name)
+      && !name.toLocaleLowerCase('en-US').startsWith('.notis-app-scaffold-')
+      && !name.startsWith('.env')
+      && !/\.(test|spec)\.[cm]?[jt]sx?$/i.test(name);
+  }
+
+  const canonicalSource = realpathSync(sourceDir);
+  const sourceIdentity = capturePullTargetIdentity(canonicalSource);
+  const previousCwd = process.cwd();
+  const previousCwdIdentity = capturePullTargetIdentity(previousCwd);
+  const destinationIdentity = capturePullTargetIdentity(targetDir);
+  const snapshot = { directories: [], files: [] };
+
+  function snapshotCurrent(sourcePath, node, expectedDirectoryIdentity) {
+    if (!pullTargetIdentitiesMatch(expectedDirectoryIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Scaffold source directory changed while copying: ${sourcePath}`);
+    }
+    const directoryRevision = captureDirectoryRevision();
+    const parentIdentity = expectedDirectoryIdentity;
+    for (const name of readdirSync('.')) {
+      const logicalSourcePath = join(sourcePath, name);
+      if (!shouldCopy(logicalSourcePath)) {
+        continue;
+      }
+      const sourceStat = lstatSync(name, { bigint: true });
+      if (sourceStat.isSymbolicLink()) {
+        throw usageError(`Refusing symlinked scaffold source entry: ${logicalSourcePath}`);
+      }
+      if (sourceStat.isDirectory()) {
+        const childNode = {
+          name,
+          mode: Number(sourceStat.mode & 0o777n),
+          directories: [],
+          files: [],
+        };
+        node.directories.push(childNode);
+        process.chdir(name);
+        const childIdentity = capturePullTargetIdentity('.');
+        if (!pullTargetIdentitiesMatch(
+          { exists: true, dev: sourceStat.dev, ino: sourceStat.ino },
+          childIdentity,
+        )) {
+          throw usageError(`Scaffold source directory changed while copying: ${logicalSourcePath}`);
+        }
+        try {
+          snapshotCurrent(logicalSourcePath, childNode, childIdentity);
+        } finally {
+          process.chdir('..');
+          if (!pullTargetIdentitiesMatch(parentIdentity, capturePullTargetIdentity('.'))) {
+            throw usageError(`Scaffold source directory changed while copying: ${sourcePath}`);
+          }
+        }
+        continue;
+      }
+      if (!sourceStat.isFile()) {
+        throw usageError(`Refusing unsupported scaffold source entry: ${logicalSourcePath}`);
+      }
+      const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+      try {
+        node.files.push({
+          name,
+          mode: Number(sourceStat.mode & 0o777n),
+          content: readStablePinnedFile(
+            descriptor,
+            sourceStat,
+            `Scaffold source file ${logicalSourcePath}`,
+          ),
+        });
+      } finally {
+        closeSync(descriptor);
+      }
+    }
+    assertDirectoryRevisionUnchanged(directoryRevision, `Scaffold source directory ${sourcePath}`);
+  }
+
+  try {
+    process.chdir(canonicalSource);
+    snapshotCurrent(canonicalSource, snapshot, sourceIdentity);
+  } finally {
+    process.chdir(previousCwd);
+    if (!pullTargetIdentitiesMatch(previousCwdIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Working directory changed while copying scaffold source: ${previousCwd}`);
+    }
+  }
+
+  function writeSnapshot(node, logicalPath, expectedDirectoryIdentity) {
+    if (!pullTargetIdentitiesMatch(expectedDirectoryIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Scaffold destination changed while copying: ${logicalPath || '.'}`);
+    }
+    const parentIdentity = expectedDirectoryIdentity;
+    for (const directory of node.directories) {
+      mkdirSync(directory.name, { mode: directory.mode });
+      const directoryStat = lstatSync(directory.name, { bigint: true });
+      if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+        throw usageError(`Refusing unsafe scaffold destination: ${join(logicalPath, directory.name)}`);
+      }
+      process.chdir(directory.name);
+      const childIdentity = capturePullTargetIdentity('.');
+      if (!pullTargetIdentitiesMatch(
+        { exists: true, dev: directoryStat.dev, ino: directoryStat.ino },
+        childIdentity,
+      )) {
+        throw usageError(`Scaffold destination changed while copying: ${join(logicalPath, directory.name)}`);
+      }
+      try {
+        writeSnapshot(directory, join(logicalPath, directory.name), childIdentity);
+      } finally {
+        process.chdir('..');
+        if (!pullTargetIdentitiesMatch(parentIdentity, capturePullTargetIdentity('.'))) {
+          throw usageError(`Scaffold destination changed while copying: ${logicalPath || '.'}`);
+        }
+      }
+    }
+    for (const file of node.files) {
+      writeFileSync(file.name, file.content, { flag: 'wx', mode: file.mode });
+    }
   }
 
-  return { projectDir };
+  try {
+    process.chdir(targetDir);
+    if (!pullTargetIdentitiesMatch(destinationIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Scaffold destination changed while copying: ${targetDir}`);
+    }
+    writeSnapshot(snapshot, '', destinationIdentity);
+  } finally {
+    process.chdir(previousCwd);
+    if (!pullTargetIdentitiesMatch(previousCwdIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Working directory changed while copying scaffold source: ${previousCwd}`);
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -430,11 +2153,14 @@ export function collectArtifactFiles(projectDir) {
     throw usageError('No build output found. Run "notis apps build" first.');
   }
 
+  validateArtifactBoundary(readArtifactFiles(projectDir));
+
   const files = {};
 
   function walk(dir, prefix) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
+      if (entry.name.startsWith('.') || (!prefix && entry.name === 'verify.json')) continue;
       const fullPath = join(dir, entry.name);
       const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
@@ -449,176 +2175,873 @@ export function collectArtifactFiles(projectDir) {
   return files;
 }
 
-// ---------------------------------------------------------------------------
-// Direct deploy (bypasses backend server)
-// ---------------------------------------------------------------------------
+function shouldExcludeSourceEntry(name) {
+  const casefolded = String(name || '').toLocaleLowerCase('en-US');
+  return (
+    SOURCE_COPY_EXCLUDES_CASEFOLDED.has(casefolded)
+    || casefolded.startsWith('.notis-app-pull-')
+    || casefolded.startsWith('.notis-app-scaffold-')
+    || casefolded.startsWith('.env')
+    || casefolded.endsWith('.pyc')
+    || casefolded.endsWith('.pyo')
+  );
+}
 
-/**
- * Resolve Supabase credentials from the server/.env file in the repo workspace.
- * Falls back to environment variables.
- */
-function resolveSupabaseCredentials() {
-  const envPaths = [
-    resolve(process.cwd(), 'server/.env'),
-    resolve(process.cwd(), '../server/.env'),
-    resolve(process.cwd(), '../../server/.env'),
-  ];
-
-  let supabaseUrl = process.env.SUPABASE_URL;
-  let supabaseSubdomain = process.env.SUPABASE_SUBDOMAIN;
-  let supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_SERVICE_KEY;
-
-  for (const envPath of envPaths) {
-    if (existsSync(envPath)) {
-      const content = readFileSync(envPath, 'utf-8');
-      for (const line of content.split('\n')) {
-        const trimmed = line.trim();
-        if (trimmed.startsWith('#') || !trimmed.includes('=')) continue;
-        const eqIdx = trimmed.indexOf('=');
-        const key = trimmed.slice(0, eqIdx).trim();
-        let value = trimmed.slice(eqIdx + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-          value = value.slice(1, -1);
-        }
-        if (key === 'SUPABASE_URL' && !supabaseUrl) supabaseUrl = value;
-        if (key === 'SUPABASE_SUBDOMAIN' && !supabaseSubdomain) supabaseSubdomain = value;
-        if ((key === 'SUPABASE_SERVICE_ROLE_KEY' || key === 'SUPABASE_SERVICE_KEY') && !supabaseKey) supabaseKey = value;
+function readSourceFiles(projectDir) {
+  const files = {};
+  const canonicalProjectDir = realpathSync(projectDir);
+  const projectIdentity = capturePullTargetIdentity(canonicalProjectDir);
+  const previousCwd = process.cwd();
+  const previousCwdIdentity = capturePullTargetIdentity(previousCwd);
+
+  function walkCurrent(prefix, expectedDirectoryIdentity) {
+    if (!pullTargetIdentitiesMatch(expectedDirectoryIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`App source directory changed while packaging: ${prefix || '.'}`);
+    }
+    const directoryRevision = captureDirectoryRevision();
+    const parentIdentity = expectedDirectoryIdentity;
+    for (const name of readdirSync('.')) {
+      if (shouldExcludeSourceEntry(name)) {
+        continue;
+      }
+      const entryStat = lstatSync(name, { bigint: true });
+      if (entryStat.isSymbolicLink()) {
+        continue;
       }
+      const relPath = prefix ? `${prefix}/${name}` : name;
+      if (entryStat.isDirectory()) {
+        process.chdir(name);
+        const childIdentity = capturePullTargetIdentity('.');
+        if (!pullTargetIdentitiesMatch(
+          { exists: true, dev: entryStat.dev, ino: entryStat.ino },
+          childIdentity,
+        )) {
+          throw usageError(`App source directory changed while packaging: ${relPath}`);
+        }
+        try {
+          walkCurrent(relPath, childIdentity);
+        } finally {
+          process.chdir('..');
+          if (!pullTargetIdentitiesMatch(parentIdentity, capturePullTargetIdentity('.'))) {
+            throw usageError(`App source directory changed while packaging: ${prefix || '.'}`);
+          }
+        }
+      } else if (entryStat.isFile()) {
+        const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+          files[relPath] = readStablePinnedFile(
+            descriptor,
+            entryStat,
+            `App source file ${relPath}`,
+          );
+        } finally {
+          closeSync(descriptor);
+        }
+      }
+    }
+    assertDirectoryRevisionUnchanged(directoryRevision, `App source directory ${prefix || '.'}`);
+  }
+
+  try {
+    process.chdir(canonicalProjectDir);
+    walkCurrent('', projectIdentity);
+  } finally {
+    process.chdir(previousCwd);
+    if (!pullTargetIdentitiesMatch(previousCwdIdentity, capturePullTargetIdentity('.'))) {
+      throw usageError(`Working directory changed while packaging app source: ${previousCwd}`);
+    }
+  }
+  return files;
+}
+
+export function collectSourceFiles(projectDir) {
+  const files = readSourceFiles(projectDir);
+  const encoded = {};
+  for (const [relPath, content] of Object.entries(files)) {
+    encoded[relPath] = content.toString('base64');
+  }
+  return encoded;
+}
+
+function cleanTarPath(name) {
+  const cleaned = String(name || '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = cleaned.split('/').filter(Boolean);
+  if (!parts.length || parts.includes('..')) {
+    throw usageError(`Refusing to extract unsafe path from source archive: ${name}`);
+  }
+  return parts.join('/');
+}
+
+function parsePaxPath(data) {
+  if (data.length === 0 || data.length > 64 * 1024) {
+    throw usageError('Refusing to extract an invalid PAX source archive header.');
+  }
+  let offset = 0;
+  let path = null;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space <= offset) {
+      throw usageError('Refusing to extract a malformed PAX source archive header.');
+    }
+    const lengthText = data.subarray(offset, space).toString('ascii');
+    if (!/^\d+$/.test(lengthText)) {
+      throw usageError('Refusing to extract a malformed PAX source archive header.');
+    }
+    const recordLength = Number.parseInt(lengthText, 10);
+    const recordEnd = offset + recordLength;
+    if (recordLength <= space - offset + 3 || recordEnd > data.length || data[recordEnd - 1] !== 0x0a) {
+      throw usageError('Refusing to extract a malformed PAX source archive header.');
+    }
+    const record = data.subarray(space + 1, recordEnd - 1);
+    const equals = record.indexOf(0x3d);
+    if (equals <= 0) {
+      throw usageError('Refusing to extract a malformed PAX source archive header.');
+    }
+    const key = record.subarray(0, equals).toString('ascii');
+    if (key === 'path') {
+      try {
+        path = new TextDecoder('utf-8', { fatal: true }).decode(record.subarray(equals + 1));
+      } catch {
+        throw usageError('Refusing to extract a PAX source path with invalid UTF-8.');
+      }
+      if (!path || Buffer.byteLength(path, 'utf-8') > 4096) {
+        throw usageError('Refusing to extract an invalid PAX source path.');
+      }
+    }
+    offset = recordEnd;
+  }
+  if (!path) {
+    throw usageError('Refusing to extract a PAX source header without a path.');
+  }
+  return path;
+}
+
+function extractTarGz(buffer, targetDir) {
+  const tar = gunzipSync(buffer);
+  let offset = 0;
+  let pendingPaxPath = null;
+  const extractedPaths = new Map();
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    offset += 512;
+    if (header.every((byte) => byte === 0)) {
       break;
     }
+
+    const name = header.subarray(0, 100).toString('utf-8').replace(/\0.*$/, '');
+    const prefix = header.subarray(345, 500).toString('utf-8').replace(/\0.*$/, '');
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    const sizeRaw = header.subarray(124, 136).toString('utf-8').replace(/\0.*$/, '').trim();
+    const size = Number.parseInt(sizeRaw || '0', 8);
+    const typeFlag = header[156];
+    if (!Number.isSafeInteger(size) || size < 0 || offset + size > tar.length) {
+      throw usageError('Refusing to extract a malformed source archive entry size.');
+    }
+    const data = tar.subarray(offset, offset + size);
+    if (typeFlag === 120) {
+      if (pendingPaxPath !== null) {
+        throw usageError('Refusing to extract stacked PAX source archive headers.');
+      }
+      pendingPaxPath = parsePaxPath(data);
+      offset += Math.ceil(size / 512) * 512;
+      continue;
+    }
+
+    const relPath = cleanTarPath(pendingPaxPath || fullName);
+    pendingPaxPath = null;
+    const parts = relPath.split('/');
+    for (let index = 1; index <= parts.length; index += 1) {
+      const pathPrefix = parts.slice(0, index).join('/');
+      const casefoldedPath = pathPrefix.toLocaleLowerCase('en-US');
+      const priorPath = extractedPaths.get(casefoldedPath);
+      if (priorPath && priorPath !== pathPrefix) {
+        throw usageError(
+          `Refusing to extract case-colliding source archive paths: ${priorPath} and ${pathPrefix}`,
+        );
+      }
+      extractedPaths.set(casefoldedPath, pathPrefix);
+    }
+    if (relPath.split('/').some((part) => shouldExcludeSourceEntry(part))) {
+      throw usageError(`Refusing to extract local-only path from source archive: ${relPath}`);
+    }
+    const outputPath = join(targetDir, relPath);
+
+    if (typeFlag === 53) {
+      mkdirSync(outputPath, { recursive: true });
+    } else if (typeFlag === 0 || typeFlag === 48) {
+      mkdirSync(dirname(outputPath), { recursive: true });
+      writeFileSync(outputPath, data);
+    } else {
+      throw usageError(`Refusing to extract unsupported source archive entry: ${relPath}`);
+    }
+
+    offset += Math.ceil(size / 512) * 512;
   }
+  if (pendingPaxPath !== null) {
+    throw usageError('Refusing to extract a dangling PAX source archive header.');
+  }
+}
 
-  // Derive URL from subdomain if needed
-  if (!supabaseUrl && supabaseSubdomain) {
-    supabaseUrl = `https://${supabaseSubdomain}.supabase.co`;
+function collectPullPreservedPaths(targetDir) {
+  const paths = [];
+
+  function walk(dir, prefix) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink() || shouldExcludeSourceEntry(entry.name)) {
+        paths.push(relPath);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), relPath);
+      }
+    }
   }
 
-  if (!supabaseUrl || !supabaseKey) {
-    throw usageError(
-      'Cannot resolve Supabase credentials for direct deploy. ' +
-      'Ensure server/.env exists with SUPABASE_SUBDOMAIN (or SUPABASE_URL) and SUPABASE_SERVICE_KEY, ' +
-      'or set them as environment variables.',
-    );
+  if (existsSync(targetDir)) {
+    walk(targetDir, '');
   }
+  return paths;
+}
 
-  return { supabaseUrl, supabaseKey };
+function readPullLockOwner(lockDirectory) {
+  try {
+    return JSON.parse(readFileSync(join(lockDirectory, 'owner'), 'utf-8'));
+  } catch {
+    return null;
+  }
 }
 
-/**
- * Upload a file to Supabase Storage with upsert.
- */
-async function uploadToStorage(supabaseUrl, supabaseKey, bucket, storagePath, content, contentType) {
-  const url = `${supabaseUrl}/storage/v1/object/${bucket}/${storagePath}`;
-  const response = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${supabaseKey}`,
-      'Content-Type': contentType,
-      'x-upsert': 'true',
-    },
-    body: content,
-  });
+function capturePullTargetIdentity(targetDir) {
+  try {
+    const targetStat = lstatSync(targetDir, { bigint: true });
+    if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+      throw usageError(`Refusing to pull app source through an unsafe target: ${targetDir}`);
+    }
+    return { exists: true, dev: targetStat.dev, ino: targetStat.ino };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, dev: null, ino: null };
+    throw error;
+  }
+}
 
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    throw new Error(`Storage upload failed (${response.status}): ${text}`);
+function assertPullTargetIdentity(targetDir, expected) {
+  const current = capturePullTargetIdentity(targetDir);
+  if (!pullTargetIdentitiesMatch(current, expected)) {
+    throw usageError(`App source pull target changed while the download was in progress: ${targetDir}`);
   }
 }
 
-/**
- * Get the current app manifest version from the apps table.
- */
-async function getAppCurrentVersion(supabaseUrl, supabaseKey, appId) {
-  const encodedAppId = encodeURIComponent(appId);
-  const url = `${supabaseUrl}/rest/v1/apps?id=eq.${encodedAppId}&select=manifest`;
-  const response = await fetch(url, {
-    headers: {
-      'Authorization': `Bearer ${supabaseKey}`,
-      'apikey': supabaseKey,
-    },
+function pullTargetIdentitiesMatch(left, right) {
+  return (
+    left.exists === right.exists
+    && (!left.exists || (left.dev === right.dev && left.ino === right.ino))
+  );
+}
+
+function assertPullParentIdentity(parentDir, canonicalParent, expectedIdentity) {
+  let currentCanonicalParent;
+  try {
+    currentCanonicalParent = realpathSync(parentDir);
+  } catch {
+    throw usageError(`App source pull parent changed while the download was in progress: ${parentDir}`);
+  }
+  if (
+    currentCanonicalParent !== canonicalParent
+    || !pullTargetIdentitiesMatch(
+      capturePullTargetIdentity(canonicalParent),
+      expectedIdentity,
+    )
+  ) {
+    throw usageError(`App source pull parent changed while the download was in progress: ${parentDir}`);
+  }
+}
+
+async function withPullTargetLock(targetDir, callback) {
+  const requestedTarget = resolve(targetDir);
+  const parentDir = dirname(requestedTarget);
+  mkdirSync(parentDir, { recursive: true });
+  const canonicalParent = realpathSync(parentDir);
+  const canonicalParentIdentity = capturePullTargetIdentity(canonicalParent);
+  const initialRequestedIdentity = capturePullTargetIdentity(requestedTarget);
+  const canonicalTarget = initialRequestedIdentity.exists
+    ? realpathSync(requestedTarget)
+    : join(canonicalParent, basename(requestedTarget));
+  if (
+    initialRequestedIdentity.exists
+    && !pullTargetIdentitiesMatch(
+      initialRequestedIdentity,
+      capturePullTargetIdentity(canonicalTarget),
+    )
+  ) {
+    throw usageError(`App source pull target changed before locking: ${requestedTarget}`);
+  }
+  const lockDirectory = join(canonicalParent, `.${basename(canonicalTarget)}.notis-pull-lock`);
+  const ownerId = `${process.pid}.${randomUUID()}`;
+  const deadline = Date.now() + PULL_LOCK_TIMEOUT_MS;
+
+  for (;;) {
+    try {
+      mkdirSync(lockDirectory, { mode: 0o700 });
+      writeFileSync(
+        join(lockDirectory, 'owner'),
+        JSON.stringify({ id: ownerId, pid: process.pid, at: Date.now() }),
+        { mode: 0o600 },
+      );
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      let lockStat;
+      try {
+        lockStat = lstatSync(lockDirectory);
+      } catch (statError) {
+        if (statError?.code === 'ENOENT') continue;
+        throw statError;
+      }
+      if (lockStat.isSymbolicLink() || !lockStat.isDirectory()) {
+        throw usageError(`Refusing to use unsafe app source pull lock: ${lockDirectory}`);
+      }
+      if (Date.now() >= deadline) {
+        throw usageError(
+          `Timed out waiting to pull app source into ${targetDir}. `
+          + `If no pull process is running, remove the orphaned lock: ${lockDirectory}`,
+        );
+      }
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, PULL_LOCK_POLL_MS));
+    }
+  }
+
+  try {
+    const assertOwnership = () => {
+      if (readPullLockOwner(lockDirectory)?.id !== ownerId) {
+        throw usageError(`Lost the app source pull lock for ${targetDir}.`);
+      }
+    };
+    const assertParentIdentity = () => assertPullParentIdentity(
+      parentDir,
+      canonicalParent,
+      canonicalParentIdentity,
+    );
+    assertParentIdentity();
+    const lockedTargetIdentity = capturePullTargetIdentity(canonicalTarget);
+    if (!pullTargetIdentitiesMatch(initialRequestedIdentity, lockedTargetIdentity)) {
+      throw usageError(`App source pull target changed before locking: ${requestedTarget}`);
+    }
+    return await callback(
+      assertOwnership,
+      assertParentIdentity,
+      canonicalTarget,
+      lockedTargetIdentity,
+    );
+  } finally {
+    try {
+      if (readPullLockOwner(lockDirectory)?.id === ownerId) {
+        rmSync(lockDirectory, { recursive: true, force: true });
+      }
+    } catch {
+      // A reclaimed lock belongs to its new owner and must not be removed.
+    }
+  }
+}
+
+// Persist only an unfinished create intent. Concurrent/retried invocations share
+// its key; a fully read-back creation closes it so later new creations cannot
+// replay an app that was subsequently deleted.
+export function beginAppCreateIntent(identity, explicitKey = null) {
+  const identityHash = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+  const path = join(homedir(), '.notis', 'app-create-intents', `${identityHash}.json`);
+  return withStateWriteLock(path, () => {
+    let intent;
+    if (existsSync(path)) intent = JSON.parse(readFileSync(path, 'utf8'));
+    if (intent && explicitKey && intent.key !== explicitKey) {
+      throw usageError('An unfinished creation exists for this identity. Reconcile it before changing its idempotency key.');
+    }
+    if (!intent) {
+      intent = { key: explicitKey || `app-create-${randomUUID()}` };
+      writeFileSync(path, JSON.stringify(intent), { mode: 0o600 });
+    }
+    return { ...intent, complete() {
+      withStateWriteLock(path, () => {
+        if (existsSync(path) && JSON.parse(readFileSync(path, 'utf8')).key === intent.key) unlinkSync(path);
+      });
+    } };
   });
-  if (!response.ok) throw new Error(`Failed to get app version: ${response.status}`);
-  const rows = await response.json();
-  if (!rows.length) throw usageError(`App ${appId} not found.`);
-  const manifest = rows[0].manifest || {};
-  return { currentVersion: manifest.version || 0, manifest };
 }
 
-/**
- * Update the app manifest in the apps table.
- */
-async function updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, manifest) {
-  const encodedAppId = encodeURIComponent(appId);
-  const url = `${supabaseUrl}/rest/v1/apps?id=eq.${encodedAppId}`;
-  const response = await fetch(url, {
-    method: 'PATCH',
-    headers: {
-      'Authorization': `Bearer ${supabaseKey}`,
-      'apikey': supabaseKey,
-      'Content-Type': 'application/json',
-      'Prefer': 'return=minimal',
-    },
-    body: JSON.stringify({
-      manifest: { ...manifest, version: newVersion },
-      updated_at: new Date().toISOString(),
-    }),
+export async function pullAppSource(args) {
+  const targetDir = resolve(args.targetDir);
+  return withPullTargetLock(
+    targetDir,
+    (
+      assertLockOwnership,
+      assertParentIdentity,
+      canonicalTarget,
+      targetIdentity,
+    ) => pullAppSourceUnlocked(
+      { ...args, targetDir: canonicalTarget },
+      assertLockOwnership,
+      assertParentIdentity,
+      targetIdentity,
+    ),
+  );
+}
+
+async function pullAppSourceUnlocked({
+  apiBase,
+  jwt,
+  appId,
+  targetDir,
+  version = 'latest',
+  force = false,
+  profileKey = null,
+  expectedUpdatedAt = null,
+}, assertLockOwnership, assertParentIdentity, initialTargetIdentity) {
+  assertLockOwnership();
+  assertParentIdentity();
+  const targetWasNonEmpty = existsSync(targetDir) && readdirSync(targetDir).length > 0;
+  if (targetWasNonEmpty) {
+    if (!force) {
+      throw usageError(`Target directory is not empty: ${targetDir}. Pass --force to overwrite it.`);
+    }
+  }
+
+  const params = new URLSearchParams({ app_id: appId, version: String(version || 'latest') });
+  const response = await fetch(`${apiBase.replace(/\/$/, '')}/portal_apps/source?${params.toString()}`, {
+    headers: { Authorization: `Bearer ${jwt}` },
   });
   if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    throw new Error(`Failed to update app version: ${response.status} ${text}`);
+    const data = await response.json().catch(() => ({}));
+    throw usageError(typeof data?.error === 'string' ? data.error : `Failed to pull app source (${response.status}).`);
   }
-}
 
-const CONTENT_TYPE_MAP = {
-  '.js': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.html': 'text/html',
-};
+  const contentDisposition = response.headers.get('content-disposition') || '';
+  const versionMatch = /-v(\d+)\.tar\.gz/i.exec(contentDisposition);
+  const pulledVersion = versionMatch ? Number.parseInt(versionMatch[1], 10) : null;
+  const requestedVersion = String(version || 'latest') === 'latest'
+    ? null
+    : Number.parseInt(String(version), 10);
+  if (!Number.isInteger(pulledVersion) || pulledVersion <= 0) {
+    throw usageError('The app source response did not identify a valid positive version.');
+  }
+  if (requestedVersion !== null && (!Number.isInteger(requestedVersion) || requestedVersion <= 0)) {
+    throw usageError(`Invalid app source version: ${version}`);
+  }
+  if (
+    requestedVersion !== null
+    && pulledVersion !== requestedVersion
+  ) {
+    throw usageError(
+      `Requested app source version ${requestedVersion}, but the server returned version ${pulledVersion}.`,
+    );
+  }
+  const linkedVersion = pulledVersion;
+  const archiveBuffer = Buffer.from(await response.arrayBuffer());
+  assertParentIdentity();
+  assertLockOwnership();
+
+  // A failed download or malformed archive must never damage an existing
+  // checkout. Extract into a transaction directory under the pinned target,
+  // then replace
+  // only source-managed entries. Local-only state such as .git, .env files,
+  // dependencies, symlinks, build output, and .notis runtime directories is
+  // moved aside recursively and restored into the new source tree.
+  let cleanupTransaction = true;
+  let cwdPinned = false;
+  let transactionDir = null;
+  let transactionDisplayPath = null;
+  let operationError = null;
+  const previousCwd = process.cwd();
+  const previousCwdIdentity = capturePullTargetIdentity(previousCwd);
+  try {
+    const parentDir = dirname(targetDir);
+    const targetName = basename(targetDir);
+    const parentIdentity = capturePullTargetIdentity(parentDir);
+    assertParentIdentity();
+    process.chdir(parentDir);
+    cwdPinned = true;
+    assertPullTargetIdentity('.', parentIdentity);
+
+    assertParentIdentity();
+    assertPullTargetIdentity(targetName, initialTargetIdentity);
+    if (!initialTargetIdentity.exists) {
+      try {
+        mkdirSync(targetName);
+      } catch (error) {
+        if (error?.code === 'EEXIST') {
+          throw usageError(`App source pull target changed while the download was in progress: ${targetDir}`);
+        }
+        throw error;
+      }
+    }
+    const activeTargetIdentity = capturePullTargetIdentity(targetName);
+    if (
+      initialTargetIdentity.exists
+      && (
+        activeTargetIdentity.dev !== initialTargetIdentity.dev
+        || activeTargetIdentity.ino !== initialTargetIdentity.ino
+      )
+    ) {
+      throw usageError(`App source pull target changed while the download was in progress: ${targetDir}`);
+    }
+    assertLockOwnership();
+    process.chdir(targetName);
+    assertPullTargetIdentity('.', activeTargetIdentity);
+    const targetRoot = '.';
+    assertLinkedStatePathSafe(targetRoot);
+    const preservedPaths = collectPullPreservedPaths(targetRoot);
+
+    const transactionName = basename(mkdtempSync(join('.', '.notis-app-pull-')));
+    transactionDir = transactionName;
+    transactionDisplayPath = join(targetDir, transactionName);
+    const stageDir = join(transactionDir, 'stage');
+    const backupDir = join(transactionDir, 'backup');
+    const preservedDir = join(transactionDir, 'preserved');
+    mkdirSync(stageDir, { recursive: true });
+    mkdirSync(backupDir, { recursive: true });
+    mkdirSync(preservedDir, { recursive: true });
+
+    extractTarGz(archiveBuffer, stageDir);
+    const stagedEntries = readdirSync(stageDir);
+    if (stagedEntries.length === 0) {
+      throw usageError('The app source archive did not contain any editable source files.');
+    }
 
-/**
- * Deploy app bundle directly to Supabase storage, bypassing the backend server.
- */
-export async function directDeploy(projectDir, appId) {
-  const { supabaseUrl, supabaseKey } = resolveSupabaseCredentials();
-  const manifest = readManifest(projectDir);
+    const previousStatePath = join(targetRoot, STATE_FILE);
+    const backupStatePath = join(backupDir, STATE_FILE);
+    const hadPreviousState = existsSync(previousStatePath);
+    if (hadPreviousState) {
+      mkdirSync(dirname(backupStatePath), { recursive: true });
+      cpSync(previousStatePath, backupStatePath);
+    }
 
-  // Get current version and increment
-  const { currentVersion } = await getAppCurrentVersion(supabaseUrl, supabaseKey, appId);
-  const newVersion = currentVersion + 1;
+    const movedPreserved = [];
+    const movedOriginal = [];
+    const movedStaged = [];
+    const restoredPreserved = [];
+    try {
+      for (const relPath of preservedPaths) {
+        const preservedPath = join(preservedDir, relPath);
+        mkdirSync(dirname(preservedPath), { recursive: true });
+        renameSync(join(targetRoot, relPath), preservedPath);
+        movedPreserved.push(relPath);
+      }
+      assertPullTargetIdentity(targetDir, activeTargetIdentity);
+      assertLockOwnership();
+      const managedTargetEntries = readdirSync(targetRoot)
+        .filter((name) => name !== transactionName);
+      for (const name of managedTargetEntries) {
+        renameSync(join(targetRoot, name), join(backupDir, name));
+        movedOriginal.push(name);
+      }
+      assertPullTargetIdentity(targetDir, activeTargetIdentity);
+      assertLockOwnership();
+      for (const name of stagedEntries) {
+        renameSync(join(stageDir, name), join(targetRoot, name));
+        movedStaged.push(name);
+      }
+      assertPullTargetIdentity(targetDir, activeTargetIdentity);
+      assertLockOwnership();
+      for (const relPath of movedPreserved) {
+        const targetPath = join(targetRoot, relPath);
+        try {
+          lstatSync(targetPath);
+          throw usageError(
+            `Local-only path conflicts with pulled source: ${relPath}. Move it aside and retry.`,
+          );
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+        mkdirSync(dirname(targetPath), { recursive: true });
+        renameSync(join(preservedDir, relPath), targetPath);
+        restoredPreserved.push(relPath);
+      }
+      assertPullTargetIdentity(targetDir, activeTargetIdentity);
+      assertLockOwnership();
+      writeLinkedState(targetRoot, {
+        app_id: appId,
+        ...(Number.isFinite(linkedVersion) ? { version: linkedVersion } : {}),
+        ...(expectedUpdatedAt ? { expected_updated_at: expectedUpdatedAt } : {}),
+        linked_at: new Date().toISOString(),
+      }, profileKey);
+      assertPullTargetIdentity(targetDir, activeTargetIdentity);
+      assertLockOwnership();
+    } catch (error) {
+      try {
+        for (const relPath of restoredPreserved.reverse()) {
+          const preservedPath = join(preservedDir, relPath);
+          mkdirSync(dirname(preservedPath), { recursive: true });
+          renameSync(join(targetRoot, relPath), preservedPath);
+        }
+        for (const name of movedStaged.reverse()) {
+          renameSync(join(targetRoot, name), join(stageDir, name));
+        }
+        for (const name of movedOriginal.reverse()) {
+          renameSync(join(backupDir, name), join(targetRoot, name));
+        }
+        for (const relPath of movedPreserved.reverse()) {
+          const targetPath = join(targetRoot, relPath);
+          mkdirSync(dirname(targetPath), { recursive: true });
+          renameSync(join(preservedDir, relPath), targetPath);
+        }
+        if (hadPreviousState) {
+          cpSync(backupStatePath, previousStatePath);
+        } else {
+          rmSync(previousStatePath, { force: true });
+        }
+      } catch (rollbackError) {
+        cleanupTransaction = false;
+        throw usageError(
+          `${error instanceof Error ? error.message : String(error)} `
+          + `Rollback failed; recovery files were retained at ${transactionDisplayPath}: `
+          + `${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`,
+        );
+      }
+      throw error;
+    }
+  } catch (error) {
+    operationError = error;
+    throw error;
+  } finally {
+    let cleanupError = null;
+    try {
+      if (cleanupTransaction && transactionDir) {
+        rmSync(transactionDir, { recursive: true, force: true });
+      }
+    } catch (error) {
+      cleanupError = error;
+    } finally {
+      if (cwdPinned) {
+        const cwdMatchesTarget = (
+          previousCwdIdentity.exists
+          && pullTargetIdentitiesMatch(previousCwdIdentity, capturePullTargetIdentity('.'))
+        );
+        if (!cwdMatchesTarget) {
+          try {
+            process.chdir(previousCwd);
+          } catch {
+            // The command is about to return; never trade recovered source for a cwd error.
+          }
+        }
+      }
+    }
+    if (cleanupError) {
+      const cleanupMessage = cleanupError instanceof Error
+        ? cleanupError.message
+        : String(cleanupError);
+      if (operationError) {
+        throw usageError(
+          `${operationError instanceof Error ? operationError.message : String(operationError)} `
+          + `Transaction cleanup also failed; recovery files were retained at `
+          + `${transactionDisplayPath}: ${cleanupMessage}`,
+        );
+      }
+      throw usageError(
+        `App source was updated, but transaction cleanup failed; recovery files were retained at `
+        + `${transactionDisplayPath}: ${cleanupMessage}`,
+      );
+    }
+  }
+
+  return { projectDir: targetDir, version: pulledVersion || version };
+}
 
-  // Upload all files from the output directory
+function readArtifactFiles(projectDir) {
   const outputDir = join(projectDir, OUTPUT_DIR);
-  const bucket = 'app-code';
+  if (!existsSync(outputDir)) {
+    throw usageError('No build output found. Run "notis apps build" first.');
+  }
 
-  async function uploadDir(dir, prefix) {
+  const files = {};
+
+  function walk(dir, prefix) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
       const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
-        await uploadDir(fullPath, relPath);
+        walk(fullPath, relPath);
       } else {
-        const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop() : '';
-        const contentType = CONTENT_TYPE_MAP[ext] || 'application/octet-stream';
-        const content = readFileSync(fullPath);
-        const storagePath = `${appId}/v${newVersion}/${relPath}`;
-        await uploadToStorage(supabaseUrl, supabaseKey, bucket, storagePath, content, contentType);
+        files[relPath] = readFileSync(fullPath);
       }
     }
   }
 
-  await uploadDir(outputDir, '');
+  walk(outputDir, '');
+  return files;
+}
+
+/** Fingerprint exact source/artifact bytes, independent of directory enumeration order. */
+export function appFilesDigest(files) {
+  return createHash('sha256').update(JSON.stringify(Object.keys(files).sort().map((key) => [key, files[key]]))).digest('hex');
+}
+
+/** Run synchronous release bookkeeping relative to a pinned, real .notis directory. */
+function withAppReleaseWorkspace(projectDir, operation, { create = false, expected = null } = {}) {
+  const canonicalProjectDir = expected?.projectDir || realpathSync(projectDir);
+  const projectIdentity = expected?.projectIdentity || capturePullTargetIdentity(canonicalProjectDir);
+  const previousCwd = process.cwd();
+  const previousIdentity = capturePullTargetIdentity(previousCwd);
+  try {
+    process.chdir(canonicalProjectDir);
+    assertPullTargetIdentity('.', projectIdentity);
+    let notisIdentity = capturePullTargetIdentity(NOTIS_DIR);
+    if (!notisIdentity.exists && create) {
+      mkdirSync(NOTIS_DIR);
+      notisIdentity = capturePullTargetIdentity(NOTIS_DIR);
+    }
+    if (!notisIdentity.exists) throw usageError('No build workspace found. Run notis apps build first.');
+    if (expected) assertPullTargetIdentity(NOTIS_DIR, expected.notisIdentity);
+    process.chdir(NOTIS_DIR);
+    assertPullTargetIdentity('.', notisIdentity);
+    const value = operation({ projectDir: canonicalProjectDir, projectIdentity, notisIdentity });
+    assertPullTargetIdentity('.', notisIdentity);
+    assertPullTargetIdentity(canonicalProjectDir, projectIdentity);
+    assertPullTargetIdentity(join(canonicalProjectDir, NOTIS_DIR), notisIdentity);
+    return value;
+  } finally {
+    process.chdir(previousCwd);
+    assertPullTargetIdentity('.', previousIdentity);
+  }
+}
+
+/** Capture one checked build. Verification and upload must use these same bytes. */
+export function prepareAppRelease(projectDir) {
+  let release;
+  try {
+    return withAppReleaseWorkspace(projectDir, (workspace) => {
+      const sourceFiles = collectSourceFiles(workspace.projectDir);
+      const files = collectArtifactFiles(workspace.projectDir);
+      let receipt;
+      try {
+        const before = lstatSync('build-receipt.json', { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink()) throw usageError('Unsafe build receipt.');
+        const descriptor = openSync('build-receipt.json', fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try { receipt = JSON.parse(readStablePinnedFile(descriptor, before, 'Build receipt').toString('utf8')); }
+        finally { closeSync(descriptor); }
+      } catch (error) {
+        if (error?.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+      }
+      if (receipt?.source_hash !== appFilesDigest(sourceFiles) || receipt?.artifact_hash !== appFilesDigest(files)) {
+        throw usageError('Build output is missing or stale. Run notis apps build before deploying.');
+      }
+      // Nest under the source project so imports resolve its installed dependencies.
+      // Every staging write is relative to pinned directories, never a replaced parent path.
+      const frozenName = mkdtempSync('release-');
+      const frozenIdentity = capturePullTargetIdentity(frozenName);
+      const frozenDir = join(workspace.projectDir, NOTIS_DIR, frozenName);
+      let closed = false;
+      const close = () => {
+        process.removeListener('exit', close);
+        if (closed) return;
+        withAppReleaseWorkspace(workspace.projectDir, () => {
+          assertPullTargetIdentity(frozenName, frozenIdentity);
+          rmSync(frozenName, { recursive: true, force: true });
+        }, { expected: workspace });
+        closed = true;
+      };
+      function writeEntry(segments, content) {
+        const name = segments[0];
+        if (segments.length === 1) {
+          writeFileSync(name, content, { flag: 'wx' });
+          return;
+        }
+        const parentIdentity = capturePullTargetIdentity('.');
+        let identity = capturePullTargetIdentity(name);
+        if (!identity.exists) {
+          mkdirSync(name);
+          identity = capturePullTargetIdentity(name);
+        }
+        process.chdir(name);
+        try {
+          assertPullTargetIdentity('.', identity);
+          writeEntry(segments.slice(1), content);
+        } finally {
+          process.chdir('..');
+          assertPullTargetIdentity('.', parentIdentity);
+        }
+      }
+      try {
+        process.chdir(frozenName);
+        try {
+          assertPullTargetIdentity('.', frozenIdentity);
+          for (const [path, encoded] of Object.entries(sourceFiles)) {
+            writeEntry(path.split('/'), Buffer.from(encoded, 'base64'));
+          }
+          for (const [path, encoded] of Object.entries(files)) {
+            writeEntry([NOTIS_DIR, 'output', ...path.split('/')], Buffer.from(encoded, 'base64'));
+          }
+        } finally {
+          process.chdir('..');
+          assertPullTargetIdentity('.', workspace.notisIdentity);
+        }
+        const manifest = JSON.parse(Buffer.from(files['manifest.json'], 'base64').toString('utf8'));
+        process.once('exit', close);
+        release = { projectDir: frozenDir, files, sourceFiles, manifest, close };
+        return release;
+      } catch (error) {
+        try { close(); } catch { /* Retain owned staging if its parent identity changed. */ }
+        throw error;
+      }
+    });
+  } catch (error) {
+    try { release?.close(); } catch { /* Parent replacement retains staging, never follows it. */ }
+    throw error;
+  }
+}
 
-  // Update the app record -- include storage_prefix so the portal can resolve bundle URLs
-  const storagePrefix = `${appId}/v${newVersion}/`;
-  const deployManifest = {
-    ...manifest,
-    version: newVersion,
-    storage_bucket: bucket,
-    storage_prefix: storagePrefix,
+// ---------------------------------------------------------------------------
+// Standalone verification diagnostics, never deployment authority.
+// Deploy automatically verifies a frozen snapshot before upload; neither a
+// forged passing report nor an environment variable may bypass that check.
+// ---------------------------------------------------------------------------
+export const VERIFY_STAMP_FILE = join(OUTPUT_DIR, 'verify.json');
+
+export function computeArtifactHash(projectDir) {
+  const outputDir = join(projectDir, OUTPUT_DIR);
+  const bundleDir = join(outputDir, 'bundle');
+  const hash = createHash('sha256');
+  const files = listFilesRecursive(bundleDir).sort();
+  for (const relPath of files) {
+    hash.update(`bundle/${relPath}\0`);
+    hash.update(readFileSync(join(bundleDir, relPath)));
+    hash.update('\0');
+  }
+  const manifestPath = join(projectDir, MANIFEST_FILE);
+  if (existsSync(manifestPath)) {
+    hash.update('manifest.json\0');
+    hash.update(readFileSync(manifestPath));
+  }
+  if (files.length === 0 && !existsSync(manifestPath)) return null;
+  return hash.digest('hex');
+}
+
+export function writeVerifyStamp(projectDir, { ok, mode, summary, results }) {
+  const stamp = {
+    version: 1,
+    artifact_hash: computeArtifactHash(projectDir),
+    generated_at: new Date().toISOString(),
+    mode,
+    ok: Boolean(ok),
+    summary,
+    routes: (results || []).map((result) => ({
+      route: result.route,
+      status: result.status,
+      assertions: (result.assertions || []).map((assertion) => ({ code: assertion.code, message: assertion.message })),
+    })),
   };
-  await updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, deployManifest);
+  const stampPath = join(projectDir, VERIFY_STAMP_FILE);
+  mkdirSync(dirname(stampPath), { recursive: true });
+  writeFileSync(stampPath, JSON.stringify(stamp, null, 2) + '\n');
+  return stamp;
+}
 
-  return { version: newVersion };
+export function readVerifyStamp(projectDir) {
+  const stampPath = join(projectDir, VERIFY_STAMP_FILE);
+  if (!existsSync(stampPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(stampPath, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
 }