@notis_ai/cli 0.2.18 → 0.2.20

package/src/runtime/app-platform.js

@@ -1,45 +1,40 @@
 /**
  * App platform utilities for the Notis CLI.
  *
- * Handles project scaffolding, validation, building, and linking. This is the
- * CLI-side counterpart to @notis/sdk -- it reads notis.config.ts, runs the
- * Vite build, and packages the bundle for deployment.
+ * Handles project scaffolding, validation, building, and Space source pulls.
+ * This is the CLI-side counterpart to @notis/sdk -- it reads notis.config.ts,
+ * runs the Vite build, and packages the bundle for deployment.
  */
 
-import { spawn } from 'node:child_process';
-import { 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 { spawn, spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants as fsConstants, copyFileSync, cpSync, existsSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+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 } from './app-boundary-validator.js';
-import { CHANGELOG_MERGE_DATE, readAppChangelog } from './app-changelog.js';
+import { validateArtifactBoundary } from './app-boundary-validator.js';
+import { HOST_ONLY_SDK_FILES, RETIRED_SDK_FILES } from './retired-sdk-files.js';
+import { assertSourceRoot } from './source-root.js';
 
 const NOTIS_DIR = '.notis';
-const STATE_FILE = join(NOTIS_DIR, 'state.json');
+const SPACE_SOURCE_FILE = join(NOTIS_DIR, 'space-source.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 TEMPLATE_SDK_DIR = join(CLI_ROOT, 'dist', 'sdk');
+// Spaces install only types and build-time entries; the host provides the SDK
+// at runtime (scripts/build-space-sdk.js).
+const SPACE_SDK_DIR = join(CLI_ROOT, 'dist', 'space-sdk');
 const SOURCE_COPY_EXCLUDES = new Set([
   'node_modules',
   '.notis',
   '.git',
+  '.context',
   'dist',
   'tsconfig.tsbuildinfo',
   '.DS_Store',
@@ -55,45 +50,17 @@ const SCAFFOLD_COPY_EXCLUDES = new Set([
   'coverage',
   '.next',
   '.turbo',
+  // The CLI reads its own template/.harness theme; projects never use a copy.
+  '.harness',
 ]);
-// 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.
@@ -124,17 +91,72 @@ export function resolveBuiltBundleDir(projectDir) {
   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{')
+/**
+ * Same-length copy of `css` in which comments become spaces and quoted strings
+ * and attribute selectors become word characters, so selector matching never
+ * sees text inside them and a word written there still blocks a match after it.
+ */
+function maskCssForSelectorMatching(css) {
+  let masked = '';
+  let index = 0;
+  const skipString = (from) => {
+    const quote = css[from];
+    let end = from + 1;
+    while (end < css.length && css[end] !== quote && css[end] !== '\n') end += css[end] === '\\' ? 2 : 1;
+    return Math.min(end + 1, css.length);
+  };
+  while (index < css.length) {
+    const char = css[index];
+    if (char === '\\') {
+      // An escaped character (`.w-\\[100px\\]`) is part of a name, never a string or attribute opener.
+      masked += css.slice(index, index + 2);
+      index += 2;
+    } else if (char === '/' && css[index + 1] === '*') {
+      const close = css.indexOf('*/', index + 2);
+      const end = close === -1 ? css.length : close + 2;
+      masked += css.slice(index, end).replace(/[^\n]/g, ' ');
+      index = end;
+    } else if (char === '"' || char === "'") {
+      const end = skipString(index);
+      masked += 'x'.repeat(end - index);
+      index = end;
+    } else if (char === '[') {
+      let end = index + 1;
+      while (end < css.length && css[end] !== ']') {
+        end = css[end] === '"' || css[end] === "'" ? skipString(end) : end + (css[end] === '\\' ? 2 : 1);
+      }
+      end = Math.min(end + 1, css.length);
+      masked += 'x'.repeat(end - index);
+      index = end;
+    } else {
+      masked += char;
+      index += 1;
+    }
+  }
+  return masked;
+}
+
+// Standalone `html`, `:root` and `body` type selectors right before a block.
+// A name inside a class, id, custom property or escaped utility (`.sl-kind-html`,
+// `#body`, `--html`, `.md\:root`) never matches, nor does text in a comment,
+// string or attribute selector.
+const SHADOW_GLOBAL_SELECTOR = /(?:(?<![\w\-.#:\\])html|(?<![\w\-\\]):root)\s*(?:,\s*:host\s*)?\{|(?<![\w\-.#:\\])body\s*\{/g;
+
+export function normalizeShadowScopedCss(css) {
+  const masked = maskCssForSelectorMatching(css);
+  let output = '';
+  let last = 0;
+  for (const match of masked.matchAll(SHADOW_GLOBAL_SELECTOR)) {
+    output += css.slice(last, match.index);
+    // Keep defaults on both the Portal shadow host and the app root used
+    // by the standalone harness. Removing :root erases Tailwind v4 theme
+    // variables in previews, collapsing spacing, type sizes and controls.
     // 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]{');
+    output += match[0].startsWith('body') ? '[data-notis-app-root]{' : '[data-notis-app-root],:host{';
+    last = match.index + match[0].length;
+  }
+  return output + css.slice(last);
 }
 
 function normalizeBundleStylesheets(projectDir) {
@@ -165,35 +187,38 @@ function normalizeBundleStylesheets(projectDir) {
 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, '(');
+    .replace(/import\s*{([^}]+)}\s+from\s+['"]@notis\/sdk\/config['"]\s*;?/g, (_statement, names) => {
+      const declarations = [];
+      for (const imported of names.split(',').map(value => value.trim()).filter(Boolean)) {
+        if (imported.startsWith('type ')) continue;
+        const match = imported.match(/^(defineNotisApp|defineSpace|defineSpaces)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+        if (!match) throw usageError(`Unsupported configuration helper: ${imported}`);
+        declarations.push(`const ${match[2] || match[1]} = (value) => value;`);
+      }
+      return declarations.join('\n');
+    });
 }
 
 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.
+  // temp .mjs file we emit below. The config helpers are identity functions,
+  // so replacing the import with local identity functions 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(stripped, {
-      compilerOptions: {
-        module: ts.ModuleKind.ESNext,
-        target: ts.ScriptTarget.ES2020,
-      },
-      fileName: configPath,
-    });
-    return transpiled.outputText;
-  } catch {
-    return stripped;
+    const { transformSync } = createRequire(import.meta.url)('esbuild');
+    return transformSync(stripped, { loader: 'ts', format: 'esm', target: 'es2020', sourcefile: configPath }).code;
+  } catch (error) {
+    throw usageError(`Failed to parse ${configPath}: ${error.message}`);
   }
 }
 
-export async function loadAppConfig(projectDir) {
-  const configPaths = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'];
+export async function loadAppConfig(projectDir, { file = null } = {}) {
+  const configPaths = file ? [file] : ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'];
+  if (file && (!Object.hasOwn(collectSourceFiles(projectDir), file) || !/\.(?:ts|js|mjs)$/.test(file))) {
+    throw usageError('Choose an existing configuration file inside this source project.');
+  }
   let configPath = null;
 
   for (const name of configPaths) {
@@ -208,12 +233,13 @@ export async function loadAppConfig(projectDir) {
     throw usageError('No notis.config.ts found in project directory.');
   }
 
-  // For .js/.mjs files, import directly. For .ts, we need transpilation.
-  if (configPath.endsWith('.ts')) {
+  // Identity config helpers work for every extension without asking Node to
+  // execute raw TypeScript from an embedded SDK package.
+  {
     const source = readFileSync(configPath, 'utf-8');
-    const jsSource = transpileTsConfigSource(source, configPath);
+    const jsSource = configPath.endsWith('.ts') ? transpileTsConfigSource(source, configPath) : stripNotisSdkImports(source);
 
-    const tmpPath = join(dirname(configPath), '._notis_config_tmp.mjs');
+    const tmpPath = join(dirname(configPath), `._notis_config_${randomUUID()}.mjs`);
     mkdirSync(dirname(tmpPath), { recursive: true });
     writeFileSync(tmpPath, jsSource);
     try {
@@ -235,347 +261,15 @@ export async function loadAppConfig(projectDir) {
     }
   }
 
-  const mod = await import(`file://${configPath}`);
-  return mod.default || mod;
-}
-
-// ---------------------------------------------------------------------------
-// Project validation
-// ---------------------------------------------------------------------------
-
-export function detectProjectProblems(projectDir) {
-  const problems = [];
-
-  if (!existsSync(join(projectDir, 'package.json'))) {
-    problems.push('Missing package.json');
-  }
-
-  const hasViteConfig = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']
-    .some((name) => existsSync(join(projectDir, name)));
-  if (!hasViteConfig) {
-    problems.push('Missing vite.config file');
-  }
-
-  if (!existsSync(join(projectDir, 'app'))) {
-    problems.push('Missing app/ directory');
-  }
-
-  const hasNotisConfig = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs']
-    .some((name) => existsSync(join(projectDir, name)));
-  if (!hasNotisConfig) {
-    problems.push('Missing notis.config.ts');
-  }
-
-  return problems;
-}
-
-export function detectProjectWarnings(projectDir, appConfig = null) {
-  const warnings = [];
-
-  if (!existsSync(join(projectDir, 'components.json'))) {
-    warnings.push('Missing components.json -- shadcn is not configured.');
-  }
-
-  const hasTailwind = ['tailwind.config.ts', 'tailwind.config.js', 'tailwind.config.cjs']
-    .some((name) => existsSync(join(projectDir, name)));
-  if (!hasTailwind) {
-    warnings.push('Missing Tailwind config.');
-  }
-
-  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 },
@@ -603,749 +297,78 @@ export async function runProjectScript({ projectDir, scriptName, env = {}, stdio
 }
 
 /**
- * Derive an export name from a route path.
- * '/' -> 'index', '/inbox' -> 'inbox', '/my-tasks' -> 'myTasks'
- */
-export function exportNameFromPath(routePath) {
-  if (routePath === '/') return 'index';
-  const slug = routePath.replace(/^\//, '').replace(/\//g, '-');
-  const identifier = slug
-    .split(/[^A-Za-z0-9_$]+/)
-    .filter(Boolean)
-    .map((part, index) => {
-      const lower = part.toLowerCase();
-      if (index === 0) return lower;
-      return lower.charAt(0).toUpperCase() + lower.slice(1);
-    })
-    .join('');
-  if (!identifier) return 'route';
-  return /^[A-Za-z_$]/.test(identifier) ? identifier : `r${identifier}`;
-}
-
-function slugFromPath(routePath) {
-  if (routePath === '/') return 'index';
-  return routePath.replace(/^\//, '').replace(/\//g, '-');
-}
-
-/**
- * Auto-detect routes from the app/ directory by scanning for page.tsx files.
- */
-function autoDetectRoutes(projectDir) {
-  const appDir = join(projectDir, 'app');
-  const routes = [];
-
-  function scan(dir, pathPrefix) {
-    if (!existsSync(dir)) return;
-    const entries = readdirSync(dir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
-
-      if (entry.isDirectory()) {
-        scan(join(dir, entry.name), `${pathPrefix}/${entry.name}`);
-      } else if (entry.name === 'page.tsx' || entry.name === 'page.jsx' || entry.name === 'page.js') {
-        const routePath = pathPrefix || '/';
-        const slug = slugFromPath(routePath);
-        routes.push({
-          path: routePath,
-          slug,
-          name: slug === 'index' ? 'Home' : slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
-          default: routePath === '/',
-          export_name: exportNameFromPath(routePath),
-        });
-      }
-    }
-  }
-
-  scan(appDir, '');
-  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,
-    export_name: route.exportName || route.export_name || exportNameFromPath(route.path),
-  }));
-  return routes.length > 0 ? routes : autoDetectRoutes(projectDir);
-}
-
-/**
- * Generate the _entry.tsx file that re-exports each route's page component.
- */
-function generateEntryFile(projectDir, routes) {
-  const entryDir = join(projectDir, NOTIS_DIR);
-  mkdirSync(entryDir, { recursive: true });
-
-  // Also re-export the layout if it exists
-  const lines = [];
-  const layoutPath = join(projectDir, 'app', 'layout.tsx');
-  if (existsSync(layoutPath)) {
-    lines.push(`export { default as __AppShell } from '../app/layout';`);
-  }
-
-  for (const route of routes) {
-    const pagePath = route.path === '/' ? '../app/page' : `../app${route.path}/page`;
-    lines.push(`export { default as ${route.export_name} } from '${pagePath}';`);
-  }
-
-  const entryPath = join(entryDir, '_entry.tsx');
-  writeFileSync(entryPath, lines.join('\n') + '\n');
-  return entryPath;
-}
-
-export async function prepareArtifactBuild(projectDir) {
-  validateProjectBoundary(projectDir);
-  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.
- */
-export function generateManifest(appConfig, projectDir) {
-  const routes = resolveConfiguredRoutes(appConfig, projectDir).map((route) => {
-    const entry = {
-      path: 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,
-    };
-    if (route.tool_access) {
-      entry.tool_access = route.tool_access;
-    }
-    return entry;
-  });
-
-  // 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: 4,
-    app: {
-      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,
-  };
-}
-
-/**
- * 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 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,
-  };
-}
-
-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);
-}
-
-/**
- * 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}`);
-    }
-
-    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/.
+ * Build a bundle in place: `prepare` writes the entry file and manifest, the
+ * build script packages into .notis/output/, then the build receipt is saved.
+ * Space builds supply `prepare` (see space-platform.js).
  */
-export async function buildArtifact(projectDir, { stdio = 'inherit' } = {}) {
-  await prepareArtifactBuild(projectDir);
-
-  // Run Vite build
-  await runProjectScript({
-    projectDir,
-    scriptName: 'build',
-    stdio,
-  });
+export async function buildArtifact(projectDir, { stdio = 'inherit', prepare,
+  finalize = null, executable = true, refreshSdk = true, runBuild = runProjectScript } = {}) {
+  if (typeof prepare !== 'function') {
+    throw new TypeError('buildArtifact needs a prepare step that writes the entry file and manifest.');
+  }
+  projectDir = realpathSync(assertSourceRoot(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.
+  if (refreshSdk) syncEmbeddedSdk(projectDir);
+  const sourceHash = appFilesDigest(collectSourceFiles(projectDir));
+  await prepare(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']
+    : [];
+  // runBuild defaults to the PATH npm script. A confined caller supplies a pinned runner instead.
+  if (executable) await runBuild({ projectDir, scriptName: 'build', args, stdio });
+
+  withAppReleaseWorkspace(projectDir, () => {}, { expected: workspace });
 
   // Verify the canonical `.notis/output/bundle` packaging contract.
   const builtBundleDir = resolveBuiltBundleDir(projectDir);
-  if (!builtBundleDir) {
+  if (executable && !builtBundleDir) {
     throw usageError(
       'Vite build did not produce app.js in .notis/output/bundle. Check your vite.config.ts.',
     );
   }
   normalizeBundleStylesheets(projectDir);
-  copyMetadataAssets(projectDir);
+  if (finalize) await finalize(projectDir);
+  withAppReleaseWorkspace(projectDir, () => {}, { expected: workspace });
 
   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) };
 }
 
 /**
  * Read the manifest from a built project.
- */
-export function readManifest(projectDir) {
-  const manifestPath = join(projectDir, MANIFEST_FILE);
-  if (!existsSync(manifestPath)) {
-    throw usageError('No manifest found. Run "notis apps build" first.');
-  }
-  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
-// ---------------------------------------------------------------------------
-
-const PROFILE_LINK_FIELDS = new Set([
-  'app_id',
-  'linked_at',
-  'deployed_at',
-  'version',
-  'dev_app_id',
-  'dev_linked_at',
-  'auto_linked_at',
-  'cloud_computer_shell_consent',
-]);
-
-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 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 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),
-  };
-}
-
-function readStateWriteLockOwner(lockPath) {
-  try {
-    return readFileSync(join(lockPath, 'owner'), 'utf8').trim();
-  } catch {
-    return null;
-  }
-}
-
-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;
-  }
-
-  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 readManifest(projectDir) {
+  const manifestPath = join(projectDir, MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    throw usageError('No manifest found. Run "notis spaces build" first.');
   }
-}
-
-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.');
+  return JSON.parse(readFileSync(manifestPath, 'utf-8'));
 }
 
 // ---------------------------------------------------------------------------
@@ -1353,31 +376,17 @@ export function requireLinkedAppId(projectDir, explicitAppId, profileKey = null)
 // ---------------------------------------------------------------------------
 
 /**
- * Scaffold a new Notis app project from the SDK template or from a published
- * Store app downloaded from the public registry repository.
+ * Scaffold a new project from the SDK template.
  */
-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();
-  }
+export async function scaffoldProject({ projectDir, appName }) {
+  return scaffoldProjectFromDir({
+    projectDir,
+    appName,
+    templateDir: join(CLI_ROOT, 'template'),
+  });
 }
 
-function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir }) {
+function scaffoldProjectFromDir({ projectDir, appName, templateDir }) {
   const sourceDir = resolve(templateDir);
   const requestedProjectDir = resolve(projectDir);
   if (!existsSync(sourceDir)) {
@@ -1404,14 +413,14 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
     assertPullTargetIdentity('.', parentIdentity);
     const lockedTargetIdentity = captureScaffoldTargetIdentity(targetName);
     if (!pullTargetIdentitiesMatch(initialTargetIdentity, lockedTargetIdentity)) {
-      throw usageError(`App scaffold target changed before copying: ${requestedProjectDir}`);
+      throw usageError(`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 usageError(`Scaffold target changed before copying: ${requestedProjectDir}`);
         }
         throw error;
       }
@@ -1422,7 +431,7 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
       activeTargetIdentity,
       captureScaffoldTargetIdentity('.'),
     )) {
-      throw usageError(`App scaffold target changed before copying: ${requestedProjectDir}`);
+      throw usageError(`Scaffold target changed before copying: ${requestedProjectDir}`);
     }
     mkdirSync(scaffoldLockName, { mode: 0o700 });
     writeFileSync(
@@ -1441,55 +450,11 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
     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);
-        }
-      }
-      if (/devSlug\s*:/.test(config)) {
-        config = config.replace(/devSlug\s*:\s*(['"`])[\s\S]*?\1/, `devSlug: ${slugName}`);
-      } else {
-        config = config.replace(
-          /name\s*:\s*(['"`])[\s\S]*?\1/,
-          (nameDeclaration) => `${nameDeclaration},\n  devSlug: ${slugName}`,
-        );
-      }
-      config = removeConfigArrayProperty(config, 'screenshots');
-      writeFileSync(configPath, config);
-    }
-
-    resetScaffoldChangelog(projectDir, appName);
-
     assertPullParentIdentity(parentDir, canonicalParent, parentIdentity);
     assertPullTargetIdentity(requestedProjectDir, activeTargetIdentity);
     const stageRoot = realpathSync(stageName);
@@ -1521,7 +486,7 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
           installedDirectory,
           capturePullTargetIdentity('.'),
         )) {
-          throw usageError(`App scaffold destination changed during installation: ${relativePath}`);
+          throw usageError(`Scaffold destination changed during installation: ${relativePath}`);
         }
         try {
           for (const name of readdirSync(sourcePath)) {
@@ -1541,7 +506,7 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
             parentIdentity,
             capturePullTargetIdentity('.'),
           )) {
-            throw usageError(`App scaffold destination changed during installation: ${parentRelativePath || '.'}`);
+            throw usageError(`Scaffold destination changed during installation: ${parentRelativePath || '.'}`);
           }
         }
         return;
@@ -1611,7 +576,7 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
     } catch (error) {
       cleanupStage = false;
       throw usageError(
-        `App scaffold was installed, but staging cleanup failed; recovery files were retained at `
+        `Scaffold was installed, but staging cleanup failed; recovery files were retained at `
         + `${join(requestedProjectDir, stageName)}: `
         + `${error instanceof Error ? error.message : String(error)}`,
       );
@@ -1655,26 +620,6 @@ function scaffoldProjectFromDir({ projectDir, appName, fromSlug, templateDir })
   return { projectDir: requestedProjectDir };
 }
 
-function normalizeScaffoldPackageScripts(pkg) {
-  const scripts = pkg?.scripts;
-  if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {
-    return;
-  }
-  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 });
@@ -1682,7 +627,7 @@ function captureScaffoldTargetIdentity(targetDir) {
       throw usageError(`Refusing to scaffold through an unsafe target: ${targetDir}`);
     }
     if (readdirSync(targetDir).length > 0) {
-      throw usageError(`App scaffold target must be empty: ${targetDir}`);
+      throw usageError(`Scaffold target must be empty: ${targetDir}`);
     }
     return { exists: true, dev: targetStat.dev, ino: targetStat.ino };
   } catch (error) {
@@ -1691,76 +636,6 @@ function captureScaffoldTargetIdentity(targetDir) {
   }
 }
 
-/**
- * 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)) {
@@ -1790,21 +665,315 @@ function ensureScaffoldLocalSdk(projectDir, pkg) {
   }
 
   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 });
+  cpSync(TEMPLATE_SDK_DIR, localSdkDir, { recursive: true, dereference: true,
+    filter: (source) => !HOST_ONLY_SDK_FILES.includes(relative(TEMPLATE_SDK_DIR, source).split(sep).join('/')) });
+}
+
+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 public SDK identical to the SDK this CLI ships,
+ * excluding host-only mounting code. The copy is a mirror by contract (the parity test in the CLI keeps
+ * the bundled artifact generated from 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. The refresh owns
+ * only packages/sdk/{package.json,tsconfig.json,src/<template files>} and the
+ * exact retired copies of a real source; a folder without a source marker
+ * (the Notis repository's own packages/sdk, for one) is refused untouched.
+ *
+ * `prune` (Spaces) makes the mirror exact instead: every owned file the
+ * template does not ship (packages/sdk/tsconfig.json, src/* and dist/*, the
+ * Space SDK's Node test runtime) is removed.
+ */
+export function syncEmbeddedSdk(projectDir, { log = null, templateSdkDir = TEMPLATE_SDK_DIR, retiredFiles = RETIRED_SDK_FILES, prune = false } = {}) {
+  const canonicalProjectDir = realpathSync(assertSourceRoot(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);
+  // listFilesRecursive skips every dist/ folder; an exact mirror owns the top-level one.
+  const listOwned = (dir) => [...listFilesRecursive(dir),
+    ...(prune ? listFilesRecursive(join(dir, 'dist')).map((relPath) => `dist/${relPath}`) : [])];
+  const templateFiles = listOwned(canonicalTemplateDir).filter(
+    (relPath) => !HOST_ONLY_SDK_FILES.includes(relPath)
+      && (relPath === 'package.json' || relPath === 'tsconfig.json' || relPath.startsWith('src/') || relPath.startsWith('dist/')),
+  );
+  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;
+  }
+
+  function retireFile(segments, digests) {
+    if (segments.length > 1) return inDirectory(segments[0], () => retireFile(segments.slice(1), digests));
+    const name = segments[0];
+    let before;
+    try { before = lstatSync(name, { bigint: true }); }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+    if (!before.isFile() || before.isSymbolicLink()) throw usageError(`Refusing an unsafe retired SDK target: ${name}`);
+    const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+      const bytes = readStablePinnedFile(descriptor, before, `Retired SDK file ${name}`);
+      if (!digests.includes(createHash('sha256').update(bytes).digest('hex'))) return false;
+      // Capture the exact directory entry before removing anything. A newly
+      // created replacement at the original path is never overwritten.
+      const temporary = `.notis-sdk-retired-${randomUUID()}`;
+      renameSync(name, temporary);
+      try {
+        const captured = lstatSync(temporary, { bigint: true });
+        if (captured.dev !== before.dev || captured.ino !== before.ino) {
+          throw usageError(`SDK file changed during retirement: ${name}`);
+        }
+        const capturedDescriptor = openSync(temporary, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+          if (!readStablePinnedFile(capturedDescriptor, captured, `Retired SDK file ${name}`).equals(bytes)) {
+            throw usageError(`SDK file changed during retirement: ${name}`);
+          }
+        } finally { closeSync(capturedDescriptor); }
+        unlinkSync(temporary);
+      } catch (error) {
+        // O_EXCL hard-link restoration preserves an independently-created
+        // replacement as well as the captured local bytes.
+        try { linkSync(temporary, name); unlinkSync(temporary); } catch { /* Retain the captured file for reconciliation. */ }
+        throw error;
+      }
+      return true;
+    } finally { closeSync(descriptor); }
+  }
+
+  // Unlink one directory entry relative to the pinned cwd; never follows a link.
+  function removeFile(segments) {
+    if (segments.length > 1) return inDirectory(segments[0], () => removeFile(segments.slice(1)));
+    try { unlinkSync(segments[0]); return true; }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  }
+
+  function removeEmptyDirectories() {
+    for (const entry of readdirSync('.', { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      inDirectory(entry.name, removeEmptyDirectories);
+      try { rmdirSync(entry.name); }
+      catch (error) { if (error.code !== 'ENOTEMPTY' && error.code !== 'EEXIST' && error.code !== 'ENOENT') throw error; }
+    }
+  }
+
+  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);
+      for (const [relPath, digests] of Object.entries(retiredFiles)) {
+        if (!templateSet.has(relPath) && retireFile(relPath.split('/'), digests) === true) changed.push(relPath);
+      }
+      foreign = listOwned('.').filter((relPath) => (relPath.startsWith('src/') || (prune && (relPath === 'tsconfig.json' || relPath.startsWith('dist/'))))
+        && !templateSet.has(relPath));
+      if (prune) {
+        for (const relPath of foreign) {
+          if (removeFile(relPath.split('/'))) changed.push(relPath);
+        }
+        foreign = [];
+        inDirectory('src', removeEmptyDirectories);
+        inDirectory('dist', removeEmptyDirectories);
+        try { rmdirSync('dist'); }
+        catch (error) { if (error.code !== 'ENOTEMPTY' && error.code !== 'EEXIST' && error.code !== 'ENOENT') throw error; }
+      }
+      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 };
+}
+
+/**
+ * A Space's packages/sdk is exactly the package this CLI ships for Spaces
+ * (dist/space-sdk): host-module types, the build-time and pure entries, and a
+ * Node-only runtime for the Space's own tests. A Space view never loads SDK
+ * code of its own, so the mirror is pruned, not merged.
+ */
+export function syncSpaceSdk(projectDir, { log = null, templateSdkDir = SPACE_SDK_DIR, updateLock = updatePackageLock } = {}) {
+  if (!existsSync(join(templateSdkDir, 'package.json'))) {
+    throw usageError(`Space SDK not found at ${templateSdkDir}. Ensure @notis_ai/cli is installed correctly.`);
+  }
+  const result = syncEmbeddedSdk(projectDir, { log, templateSdkDir, retiredFiles: {}, prune: true });
+  if (result.reason) return result;
+  const manifest = JSON.parse(readFileSync(join(templateSdkDir, 'package.json'), 'utf-8'));
+  return { ...result, lockfile: reconcileSdkLockfile(realpathSync(projectDir), { manifest, log, updateLock }) };
+}
+
+// The package.json fields npm records for a linked package. `npm ci` checks a
+// lock against the linked package.json, so a changed SDK dependency makes it
+// refuse a lock written for the previous SDK.
+const LOCKED_MANIFEST_FIELDS = ['name', 'version', 'dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta'];
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+/** True when a lock entry records exactly this manifest (an absent map equals an empty one). */
+export function lockRecordsManifest(entry, manifest) {
+  if (!entry || typeof entry !== 'object') return false;
+  return LOCKED_MANIFEST_FIELDS.every((field) => {
+    const absent = field === 'name' || field === 'version' ? null : {};
+    return canonicalJson(entry[field] ?? absent) === canonicalJson(manifest[field] ?? absent);
+  });
+}
+
+// The lock only: no install scripts, node_modules untouched. One quick retry
+// keeps an offline machine from waiting out npm's minute-long default backoff,
+// and npm still answers from its cache when the network is down.
+const LOCK_UPDATE_ARGS = Object.freeze(['install', '--package-lock-only', '--ignore-scripts', '--no-audit', '--no-fund',
+  '--fetch-retries=1', '--fetch-retry-mintimeout=1000']);
+
+function updatePackageLock(projectDir) {
+  const result = spawnSync('npm', [...LOCK_UPDATE_ARGS], {
+    cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 180_000, shell: process.platform === 'win32',
+  });
+  if (result.error) {
+    return { ok: false, detail: result.error.code === 'ETIMEDOUT' ? 'npm did not finish within 3 minutes' : result.error.message };
+  }
+  if (result.status === 0) return { ok: true };
+  return { ok: false, detail: npmFailureReason(`${result.stderr || ''}\n${result.stdout || ''}`) || `npm exited with code ${result.status}` };
+}
+
+/** npm's reason in one line: its first error line that is not code/syscall/errno metadata, a stack frame or the log pointer. */
+export function npmFailureReason(output) {
+  const lines = String(output || '').split('\n').map((line) => line.trim()).filter(Boolean);
+  const meaningful = (line) => line && !/^(code|syscall|errno)\s/.test(line) && !/^at\s/.test(line) && !/complete log of this run/i.test(line);
+  const errors = lines.filter((line) => /^npm (error|ERR!)/.test(line)).map((line) => line.replace(/^npm (error|ERR!)\s*/, ''));
+  return errors.find(meaningful) || lines.find(meaningful) || '';
 }
 
-// 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(\/|$))/;
+/**
+ * Keep package-lock.json in step with the mirrored @notis/sdk so `npm ci`
+ * accepts it. npm runs only when the lock's packages/sdk record differs from
+ * the mirrored manifest (`npm install --package-lock-only`: the lock only,
+ * no scripts, node_modules untouched). A failure, such as an offline
+ * machine, is a warning: the sync and the build or pull that ran it continue,
+ * and the next sync retries.
+ */
+export function reconcileSdkLockfile(projectDir, { manifest, log = null, updateLock = updatePackageLock } = {}) {
+  const emit = typeof log === 'function' ? log : (message) => process.stderr.write(`${message}\n`);
+  const lockPath = join(projectDir, 'package-lock.json');
+  const readLock = () => JSON.parse(readFileSync(lockPath, 'utf-8'));
+  let project, lock;
+  try {
+    project = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    lock = readLock();
+  } catch {
+    return 'absent'; // No npm lock to keep, or one npm itself reports as unreadable.
+  }
+  const spec = project?.dependencies?.['@notis/sdk'] ?? project?.devDependencies?.['@notis/sdk'];
+  if (typeof spec !== 'string' || !/^file:(\.\/)?packages\/sdk\/?$/.test(spec)) return 'unlinked';
+  if (!lock?.packages || typeof lock.packages !== 'object') return 'unsupported'; // lockfileVersion 1
+  if (lockRecordsManifest(lock.packages['packages/sdk'], manifest)) return 'current';
+  const outcome = updateLock(projectDir);
+  let current = false;
+  try { current = lockRecordsManifest(readLock().packages?.['packages/sdk'], manifest); } catch { /* Reported below. */ }
+  if (outcome.ok && current) {
+    emit(`Updated package-lock.json for @notis/sdk ${manifest.version}. Run npm install to bring node_modules up to date.`);
+    return 'updated';
+  }
+  emit(`Warning: package-lock.json still records the previous @notis/sdk dependencies, so npm ci will refuse it${outcome.detail ? ` (${outcome.detail})` : ''}. `
+    + 'Everything else continues; run npm install in this project once the npm registry is reachable.');
+  return 'stale';
+}
 
 function readStablePinnedFile(descriptor, expectedStat, label) {
   const before = fstatSync(descriptor, { bigint: true });
@@ -1850,10 +1019,6 @@ 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')
@@ -1996,7 +1161,7 @@ function copyScaffoldSource(sourceDir, targetDir) {
 export function collectArtifactFiles(projectDir) {
   const outputDir = join(projectDir, OUTPUT_DIR);
   if (!existsSync(outputDir)) {
-    throw usageError('No build output found. Run "notis apps build" first.');
+    throw usageError('No build output found. Run "notis spaces build" first.');
   }
 
   validateArtifactBoundary(readArtifactFiles(projectDir));
@@ -2006,6 +1171,7 @@ export function collectArtifactFiles(projectDir) {
   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()) {
@@ -2026,6 +1192,7 @@ function shouldExcludeSourceEntry(name) {
     SOURCE_COPY_EXCLUDES_CASEFOLDED.has(casefolded)
     || casefolded.startsWith('.notis-app-pull-')
     || casefolded.startsWith('.notis-app-scaffold-')
+    || casefolded.startsWith('._notis_config_')
     || casefolded.startsWith('.env')
     || casefolded.endsWith('.pyc')
     || casefolded.endsWith('.pyo')
@@ -2162,7 +1329,8 @@ function parsePaxPath(data) {
 }
 
 function extractTarGz(buffer, targetDir) {
-  const tar = gunzipSync(buffer);
+  // Source snapshots allow 256 MiB of files plus bounded tar/PAX metadata.
+  const tar = gunzipSync(buffer, { maxOutputLength: 320 * 1024 * 1024 });
   let offset = 0;
   let pendingPaxPath = null;
   const extractedPaths = new Map();
@@ -2261,7 +1429,7 @@ 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}`);
+      throw usageError(`Refusing to pull Space source through an unsafe target: ${targetDir}`);
     }
     return { exists: true, dev: targetStat.dev, ino: targetStat.ino };
   } catch (error) {
@@ -2273,7 +1441,7 @@ function capturePullTargetIdentity(targetDir) {
 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}`);
+    throw usageError(`Space source pull target changed while the download was in progress: ${targetDir}`);
   }
 }
 
@@ -2289,7 +1457,7 @@ function assertPullParentIdentity(parentDir, canonicalParent, expectedIdentity)
   try {
     currentCanonicalParent = realpathSync(parentDir);
   } catch {
-    throw usageError(`App source pull parent changed while the download was in progress: ${parentDir}`);
+    throw usageError(`Space source pull parent changed while the download was in progress: ${parentDir}`);
   }
   if (
     currentCanonicalParent !== canonicalParent
@@ -2298,7 +1466,7 @@ function assertPullParentIdentity(parentDir, canonicalParent, expectedIdentity)
       expectedIdentity,
     )
   ) {
-    throw usageError(`App source pull parent changed while the download was in progress: ${parentDir}`);
+    throw usageError(`Space source pull parent changed while the download was in progress: ${parentDir}`);
   }
 }
 
@@ -2319,7 +1487,7 @@ async function withPullTargetLock(targetDir, callback) {
       capturePullTargetIdentity(canonicalTarget),
     )
   ) {
-    throw usageError(`App source pull target changed before locking: ${requestedTarget}`);
+    throw usageError(`Space source pull target changed before locking: ${requestedTarget}`);
   }
   const lockDirectory = join(canonicalParent, `.${basename(canonicalTarget)}.notis-pull-lock`);
   const ownerId = `${process.pid}.${randomUUID()}`;
@@ -2344,11 +1512,11 @@ async function withPullTargetLock(targetDir, callback) {
         throw statError;
       }
       if (lockStat.isSymbolicLink() || !lockStat.isDirectory()) {
-        throw usageError(`Refusing to use unsafe app source pull lock: ${lockDirectory}`);
+        throw usageError(`Refusing to use unsafe Space source pull lock: ${lockDirectory}`);
       }
       if (Date.now() >= deadline) {
         throw usageError(
-          `Timed out waiting to pull app source into ${targetDir}. `
+          `Timed out waiting to pull Space source into ${targetDir}. `
           + `If no pull process is running, remove the orphaned lock: ${lockDirectory}`,
         );
       }
@@ -2359,7 +1527,7 @@ async function withPullTargetLock(targetDir, callback) {
   try {
     const assertOwnership = () => {
       if (readPullLockOwner(lockDirectory)?.id !== ownerId) {
-        throw usageError(`Lost the app source pull lock for ${targetDir}.`);
+        throw usageError(`Lost the Space source pull lock for ${targetDir}.`);
       }
     };
     const assertParentIdentity = () => assertPullParentIdentity(
@@ -2370,7 +1538,7 @@ async function withPullTargetLock(targetDir, callback) {
     assertParentIdentity();
     const lockedTargetIdentity = capturePullTargetIdentity(canonicalTarget);
     if (!pullTargetIdentitiesMatch(initialRequestedIdentity, lockedTargetIdentity)) {
-      throw usageError(`App source pull target changed before locking: ${requestedTarget}`);
+      throw usageError(`Space source pull target changed before locking: ${requestedTarget}`);
     }
     return await callback(
       assertOwnership,
@@ -2389,6 +1557,28 @@ async function withPullTargetLock(targetDir, callback) {
   }
 }
 
+function assertPullStatePathSafe(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, SPACE_SOURCE_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 async function pullAppSource(args) {
   const targetDir = resolve(args.targetDir);
   return withPullTargetLock(
@@ -2408,55 +1598,39 @@ export async function pullAppSource(args) {
 }
 
 async function pullAppSourceUnlocked({
-  apiBase,
-  jwt,
-  appId,
   targetDir,
   version = 'latest',
   force = false,
-  profileKey = null,
-  expectedUpdatedAt = null,
+  downloadSource,
+  sourceLink,
 }, 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.`);
+      throw usageError(`Target directory is not empty: ${targetDir}. Pull into a new or empty directory.`);
     }
   }
 
-  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 data = await response.json().catch(() => ({}));
-    throw usageError(typeof data?.error === 'string' ? data.error : `Failed to pull app source (${response.status}).`);
-  }
-
-  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 { archiveBuffer, revision: pulledVersion } = await downloadSource();
   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.');
+    throw usageError('The Space source response did not identify a valid positive version.');
   }
   if (requestedVersion !== null && (!Number.isInteger(requestedVersion) || requestedVersion <= 0)) {
-    throw usageError(`Invalid app source version: ${version}`);
+    throw usageError(`Invalid Space source version: ${version}`);
   }
   if (
     requestedVersion !== null
     && pulledVersion !== requestedVersion
   ) {
     throw usageError(
-      `Requested app source version ${requestedVersion}, but the server returned version ${pulledVersion}.`,
+      `Requested Space source version ${requestedVersion}, but the server returned version ${pulledVersion}.`,
     );
   }
-  const linkedVersion = pulledVersion;
-  const archiveBuffer = Buffer.from(await response.arrayBuffer());
   assertParentIdentity();
   assertLockOwnership();
 
@@ -2489,7 +1663,7 @@ async function pullAppSourceUnlocked({
         mkdirSync(targetName);
       } catch (error) {
         if (error?.code === 'EEXIST') {
-          throw usageError(`App source pull target changed while the download was in progress: ${targetDir}`);
+          throw usageError(`Space source pull target changed while the download was in progress: ${targetDir}`);
         }
         throw error;
       }
@@ -2502,13 +1676,13 @@ async function pullAppSourceUnlocked({
         || activeTargetIdentity.ino !== initialTargetIdentity.ino
       )
     ) {
-      throw usageError(`App source pull target changed while the download was in progress: ${targetDir}`);
+      throw usageError(`Space source pull target changed while the download was in progress: ${targetDir}`);
     }
     assertLockOwnership();
     process.chdir(targetName);
     assertPullTargetIdentity('.', activeTargetIdentity);
     const targetRoot = '.';
-    assertLinkedStatePathSafe(targetRoot);
+    assertPullStatePathSafe(targetRoot);
     const preservedPaths = collectPullPreservedPaths(targetRoot);
 
     const transactionName = basename(mkdtempSync(join('.', '.notis-app-pull-')));
@@ -2524,11 +1698,11 @@ async function pullAppSourceUnlocked({
     extractTarGz(archiveBuffer, stageDir);
     const stagedEntries = readdirSync(stageDir);
     if (stagedEntries.length === 0) {
-      throw usageError('The app source archive did not contain any editable source files.');
+      throw usageError('The Space source archive did not contain any editable source files.');
     }
 
-    const previousStatePath = join(targetRoot, STATE_FILE);
-    const backupStatePath = join(backupDir, STATE_FILE);
+    const previousStatePath = join(targetRoot, SPACE_SOURCE_FILE);
+    const backupStatePath = join(backupDir, SPACE_SOURCE_FILE);
     const hadPreviousState = existsSync(previousStatePath);
     if (hadPreviousState) {
       mkdirSync(dirname(backupStatePath), { recursive: true });
@@ -2578,12 +1752,13 @@ async function pullAppSourceUnlocked({
       }
       assertPullTargetIdentity(targetDir, activeTargetIdentity);
       assertLockOwnership();
-      writeLinkedState(targetRoot, {
-        app_id: appId,
-        ...(Number.isFinite(linkedVersion) ? { version: linkedVersion } : {}),
-        expected_updated_at: expectedUpdatedAt,
-        linked_at: new Date().toISOString(),
-      }, profileKey);
+      withAppReleaseWorkspace(targetRoot, () => {
+        const temporary = `.space-source-${randomUUID()}.json`;
+        try {
+          writeFileSync(temporary, JSON.stringify({ ...sourceLink, revision: pulledVersion }), { flag: 'wx', mode: 0o600 });
+          renameSync(temporary, basename(SPACE_SOURCE_FILE));
+        } finally { rmSync(temporary, { force: true }); }
+      }, { create: true });
       assertPullTargetIdentity(targetDir, activeTargetIdentity);
       assertLockOwnership();
     } catch (error) {
@@ -2657,19 +1832,19 @@ async function pullAppSourceUnlocked({
         );
       }
       throw usageError(
-        `App source was updated, but transaction cleanup failed; recovery files were retained at `
+        `Space source was updated, but transaction cleanup failed; recovery files were retained at `
         + `${transactionDisplayPath}: ${cleanupMessage}`,
       );
     }
   }
 
-  return { projectDir: targetDir, version: pulledVersion || version };
+  return { projectDir: targetDir, version: pulledVersion };
 }
 
 function readArtifactFiles(projectDir) {
   const outputDir = join(projectDir, OUTPUT_DIR);
   if (!existsSync(outputDir)) {
-    throw usageError('No build output found. Run "notis apps build" first.');
+    throw usageError('No build output found. Run "notis spaces build" first.');
   }
 
   const files = {};
@@ -2691,233 +1866,238 @@ function readArtifactFiles(projectDir) {
   return files;
 }
 
-// ---------------------------------------------------------------------------
-// Direct deploy (bypasses backend server)
-// ---------------------------------------------------------------------------
+/** 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');
+}
 
-/**
- * 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;
-      }
-      break;
+/** 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 spaces 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);
+  }
+}
+
+function freezePinnedArtifactSnapshot(workspace, files, sourceFiles) {
+  for (const [source, entries] of [[true, sourceFiles], [false, files]]) {
+    for (const [path, encoded] of Object.entries(entries)) {
+      const segments = path.split('/');
+      if (!path || path.includes('\\') || path.includes('\0') || segments.some(part => !part || part === '.' || part === '..')
+        || (source && segments.some(part => ['.notis', '.context', '.git', 'node_modules'].includes(part) || part.startsWith('.env')))
+        || typeof encoded !== 'string') throw usageError('Unsafe frozen source or artifact path.');
+    }
+  }
+  // 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);
     }
   }
-
-  // Derive URL from subdomain if needed
-  if (!supabaseUrl && supabaseSubdomain) {
-    supabaseUrl = `https://${supabaseSubdomain}.supabase.co`;
-  }
-
-  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.',
-    );
+  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 = files['manifest.json'] ? JSON.parse(Buffer.from(files['manifest.json'], 'base64').toString('utf8')) : null;
+    process.once('exit', close);
+    return { projectDir: frozenDir, files, sourceFiles, manifest, close };
+  } catch (error) {
+    try { close(); } catch { /* Retain owned staging if its parent identity changed. */ }
+    throw error;
   }
-
-  return { supabaseUrl, supabaseKey };
 }
 
-/**
- * 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,
-  });
+/** Freeze a selected source slice using the same pinned-directory writer as releases. */
+export function freezeSourceWorkspace(projectDir, sourceFiles) {
+  return withAppReleaseWorkspace(projectDir, workspace => freezePinnedArtifactSnapshot(workspace, {}, sourceFiles), { create: true });
+}
 
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    throw new Error(`Storage upload failed (${response.status}): ${text}`);
-  }
+function selectedBuildName(key) {
+  if (typeof key !== 'string' || !/^[a-z][a-z0-9_-]{0,99}$/.test(key)) throw usageError('Choose a valid selected build key.');
+  return `space-build-${key}.json`;
 }
 
-async function ensureStorageBucket(supabaseUrl, supabaseKey, bucket, options = {}) {
-  const encodedBucket = encodeURIComponent(bucket);
-  const headers = {
-    'Authorization': `Bearer ${supabaseKey}`,
-    'apikey': supabaseKey,
-  };
-  const inspectResponse = await fetch(`${supabaseUrl}/storage/v1/bucket/${encodedBucket}`, {
-    headers,
-  });
-  if (inspectResponse.ok) {
-    return;
-  }
-  if (inspectResponse.status !== 404) {
-    const text = await inspectResponse.text().catch(() => '');
-    throw new Error(`Failed to inspect storage bucket ${bucket} (${inspectResponse.status}): ${text}`);
-  }
-
-  const createResponse = await fetch(`${supabaseUrl}/storage/v1/bucket`, {
-    method: 'POST',
-    headers: {
-      ...headers,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      id: bucket,
-      name: bucket,
-      public: Boolean(options.public),
-    }),
+/** Immutable bytes, not another authoring project or installed dependency tree. */
+export function saveSelectedBuild(projectDir, key, release) {
+  return withAppReleaseWorkspace(projectDir, () => {
+    const name = selectedBuildName(key), temporary = `.${name}-${randomUUID()}`;
+    const snapshot = { version: 1, key, files: release.files, sourceFiles: release.sourceFiles,
+      source_hash: appFilesDigest(release.sourceFiles), artifact_hash: appFilesDigest(release.files) };
+    try {
+      writeFileSync(temporary, JSON.stringify(snapshot), { flag: 'wx', mode: 0o600 });
+      renameSync(temporary, name);
+    } finally { rmSync(temporary, { force: true }); }
+    return join(projectDir, NOTIS_DIR, name);
+  }, { create: true });
+}
+
+export function prepareSelectedBuild(projectDir, key, sourceFiles) {
+  return withAppReleaseWorkspace(projectDir, workspace => {
+    const name = selectedBuildName(key);
+    let before;
+    try { before = lstatSync(name, { bigint: true }); } catch (error) {
+      if (error.code === 'ENOENT') throw usageError('Selected Space build is missing or stale. Build it again.');
+      throw error;
+    }
+    if (!before.isFile() || before.isSymbolicLink()) throw usageError('Unsafe selected build receipt.');
+    const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    let snapshot;
+    try { snapshot = JSON.parse(readStablePinnedFile(descriptor, before, 'Selected build receipt').toString('utf8')); }
+    finally { closeSync(descriptor); }
+    if (snapshot.version !== 1 || snapshot.key !== key || !snapshot.files || !snapshot.sourceFiles
+      || snapshot.source_hash !== appFilesDigest(sourceFiles) || snapshot.source_hash !== appFilesDigest(snapshot.sourceFiles)
+      || snapshot.artifact_hash !== appFilesDigest(snapshot.files)) throw usageError('Selected Space build is missing or stale. Build it again.');
+    validateArtifactBoundary(Object.fromEntries(Object.entries(snapshot.files).map(([path, encoded]) => [path, Buffer.from(encoded, 'base64')])));
+    return freezePinnedArtifactSnapshot(workspace, snapshot.files, snapshot.sourceFiles);
   });
-  if (createResponse.ok) {
-    return;
-  }
-
-  const text = await createResponse.text().catch(() => '');
-  if (createResponse.status === 409 || /already exists|duplicate/i.test(text)) {
-    return;
-  }
-  throw new Error(`Failed to create storage bucket ${bucket} (${createResponse.status}): ${text}`);
 }
 
-/**
- * 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,
-    },
+/** A diagnostic, never an approval stamp or a replacement for exact-byte checks. */
+export function saveSpaceVerification(projectDir, diagnostic) {
+  return withAppReleaseWorkspace(projectDir, (workspace) => {
+    const name = `space-verification-${randomUUID()}.json`;
+    writeFileSync(name, JSON.stringify(diagnostic, null, 2), { flag: 'wx', mode: 0o600 });
+    return join(workspace.projectDir, '.notis', name);
   });
-  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 },
-      ...appRowFieldsFromManifest(manifest),
-      updated_at: new Date().toISOString(),
-    }),
+/** Retain the original CAS after an uncertain publish response, across CLI exits. */
+export function spacePublicationIntent(projectDir, identity, create = null) {
+  const name = `space-publish-${createHash('sha256').update(JSON.stringify(identity)).digest('hex')}.json`;
+  return withAppReleaseWorkspace(projectDir, () => {
+    if (create) {
+      const temporary = `.${name}-${randomUUID()}`;
+      try {
+        writeFileSync(temporary, JSON.stringify(create), { flag: 'wx', mode: 0o600 });
+        try { linkSync(temporary, name); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      } finally { rmSync(temporary, { force: true }); }
+    }
+    let before;
+    try { before = lstatSync(name, { bigint: true }); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (!before.isFile() || before.isSymbolicLink()) throw usageError('Unsafe Space publication receipt.');
+    const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try { return JSON.parse(readStablePinnedFile(descriptor, before, 'Space publication receipt').toString('utf8')); }
+    finally { closeSync(descriptor); }
   });
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    throw new Error(`Failed to update app version: ${response.status} ${text}`);
-  }
 }
 
-const CONTENT_TYPE_MAP = {
-  '.js': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.html': 'text/html',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-};
-
-/**
- * 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 artifactFiles = readArtifactFiles(projectDir);
-  const sourceFiles = readSourceFiles(projectDir);
-  validateArtifactBoundary(artifactFiles);
+function spaceStateFileName(name) {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*\.json$/.test(name)) throw usageError('Unsafe local Space state file name.');
+  return name;
+}
 
-  // Get current version and increment
-  const { currentVersion } = await getAppCurrentVersion(supabaseUrl, supabaseKey, appId);
-  const newVersion = currentVersion + 1;
+/** Read one local-only JSON state file under the pinned .notis directory; null when absent. */
+export function readSpaceStateFile(projectDir, name) {
+  spaceStateFileName(name);
+  if (!existsSync(join(resolve(projectDir), NOTIS_DIR))) return null;
+  return withAppReleaseWorkspace(projectDir, () => {
+    let before;
+    try { before = lstatSync(name, { bigint: true }); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (!before.isFile() || before.isSymbolicLink()) throw usageError(`Unsafe local Space state file: ${name}.`);
+    const descriptor = openSync(name, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try { return JSON.parse(readStablePinnedFile(descriptor, before, `Space state file ${name}`).toString('utf8')); }
+    finally { closeSync(descriptor); }
+  });
+}
 
-  // Upload all files from the output directory
-  const bucket = 'app-code';
-  await ensureStorageBucket(supabaseUrl, supabaseKey, bucket, { public: false });
-  await ensureStorageBucket(supabaseUrl, supabaseKey, 'app-source', { public: false });
+/** Replace one local-only JSON state file atomically inside the pinned .notis directory. */
+export function writeSpaceStateFile(projectDir, name, value) {
+  spaceStateFileName(name);
+  return withAppReleaseWorkspace(projectDir, (workspace) => {
+    const temporary = `.${name}-${randomUUID()}`;
+    try {
+      writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+      renameSync(temporary, name);
+    } finally { rmSync(temporary, { force: true }); }
+    return join(workspace.projectDir, NOTIS_DIR, name);
+  }, { create: true });
+}
 
-  async function uploadDir(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);
-      } 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);
+/** 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;
       }
-    }
-  }
-
-  await uploadDir(join(projectDir, OUTPUT_DIR), '');
-
-  for (const [relPath, content] of Object.entries(sourceFiles)) {
-    const ext = relPath.includes('.') ? `.${relPath.split('.').pop()}` : '';
-    const contentType = CONTENT_TYPE_MAP[ext] || 'application/octet-stream';
-    const storagePath = `${appId}/v${newVersion}/${relPath}`;
-    await uploadToStorage(supabaseUrl, supabaseKey, 'app-source', storagePath, content, contentType);
+      if (receipt?.source_hash !== appFilesDigest(sourceFiles) || receipt?.artifact_hash !== appFilesDigest(files)) {
+        throw usageError('Build output is missing or stale. Run notis spaces build before deploying.');
+      }
+      return release = freezePinnedArtifactSnapshot(workspace, files, sourceFiles);
+    });
+  } 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,
-    source_storage_bucket: 'app-source',
-    source_storage_prefix: storagePrefix,
-  };
-  await updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, deployManifest);
-
-  return { version: newVersion };
 }