spine-framework 0.3.144 → 0.4.0

package/config/tsconfig.functions.json

@@ -0,0 +1,42 @@
+{
+  // Typecheck for the ASSEMBLED functions layout.
+  //
+  // Function sources (.framework/functions, custom/functions,
+  // custom/apps/<app>/functions) are merged flat into
+  // .assembled/netlify/functions by scripts/assemble-functions.sh. Their
+  // imports only resolve in that layout:
+  //   - './_shared/*' resolves to the assembled _shared/ sibling dir
+  //   - './<other-function>' resolves to other flat-assembled files
+  //   - '@shared/*' is a runtime/bundler alias → assembled _shared/
+  // So this config checks the assembled output, not the source trees. Run:
+  //   npx tsc --noEmit -p config/tsconfig.functions.json
+  // (Intentionally NOT in tsconfig.json's references — `tsc -b` would require
+  // composite+emit and fail the vite build on unrelated functions errors.)
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "types": ["node"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["../.assembled/netlify/functions/_shared/*"],
+      "@/*": ["../.assembled/netlify/functions/*"]
+    }
+  },
+  "include": ["../.assembled/netlify/functions"],
+  "exclude": [
+    "../node_modules",
+    "../.assembled/netlify/functions/_quarantine"
+  ]
+}

package/config/tsconfig.json

@@ -21,21 +21,49 @@
     "baseUrl": ".",
     "paths": {
       "@/*": ["../.assembled/src/*"],              // Assembled frontend
-      "@core/*": ["../.framework/src/*"],     // Core source
-      "@custom/*": ["../custom/*"], // Custom source
+      "@core/*": ["../.framework/src/*"],          // Core source (same tree as .assembled/src base layer)
+      "@custom/*": ["../custom/*"],                // Custom source
       "@shared/*": ["../.framework/functions/_shared/*"] // Shared functions (resolved at runtime via assembly)
     }
   },
-  "include": [".assembled/src", ".framework/functions"],
+  // NOTE: include/exclude paths are relative to THIS directory (config/), so
+  // everything real needs a "../" prefix — the previous values silently
+  // matched nothing and typecheck covered zero files.
+  //
+  // Coverage: assembled frontend, framework source, and every custom app's
+  // index.tsx + source tree (components/pages/hooks/lib/utils/views).
+  // Function code is deliberately EXCLUDED here — both .framework/functions
+  // and custom/apps/​*/functions assume the assembled flat layout
+  // (./_shared/* sibling imports only resolve post-assembly). Typecheck them
+  // separately against the assembled output:
+  //   npx tsc --noEmit -p config/tsconfig.functions.json
+  "include": [
+    "../.assembled/src",
+    "../.framework/src",
+    "../custom/apps",
+    "../custom/components",
+    "../custom/hooks"
+  ],
   "exclude": [
     "node_modules",
     "dist",
-    "netlify/functions",
-    "supabase",
-    "scripts",
-    ".netlify",
-    ".assembled/src",
-    "custom/functions"
+    "../node_modules",
+    "../dist",
+    "../netlify",
+    "../supabase",
+    "../scripts",
+    "../.netlify",
+    "../.framework/functions",
+    "../.assembled/netlify",
+    "../custom/functions",
+    "../custom/apps/*/functions",
+    "../custom/apps/*/seed",
+    "../custom/apps/*/public",
+    "../custom/apps/*/docs",
+    "../custom/apps/*/mcp",
+    "../custom/apps/*/migrations-archive",
+    "../custom/apps/*/node_modules",
+    "../custom/apps/*/dist"
   ],
   "references": [{ "path": "./tsconfig.node.json" }]
 }

package/config/vite.config.ts

@@ -2,10 +2,39 @@ import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import path from 'path'
 
+// CIL[BEGIN stable_id="~/config/vite.config.ts:module:config" type="config" identity="vite-config" parent="~/config/vite.config.ts"]
+// CIL[DOC-MACRO purpose="Vite build/dev config for Spine: assembled src root, /api proxy to Netlify dev, manual vendor chunks, @/ @core @custom @shared aliases."]
+// CIL[DOC-RESPONSIBILITY responsibility="Point Vite at .assembled/src, wire SPA fallback middleware, public dir, PostCSS (config/postcss.config.cjs), and dev-server fs/proxy settings."]
+// CIL[DOC-CONTEXT module="build-config" layer="build" related_files="scripts/assemble-frontend.sh,config/postcss.config.cjs,netlify.toml"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-NOTE type="gotcha" content="css.postcss must reference postcss.config.cjs — the .js filename does not exist on disk."]
+// CIL[END stable_id="~/config/vite.config.ts:module:config"]
+
 // Vite config for Spine - assembled src as working root
 export default defineConfig({
   plugins: [
     react(),
+    {
+      name: 'spa-fallback-first',
+      configureServer(server) {
+        // Runs before Vite's transform middleware. Browser navigation to an
+        // app route like /demo would otherwise resolve to demo/index.tsx
+        // (directory index) and be served as a JS module instead of the SPA.
+        server.middlewares.use((req, _res, next) => {
+          const accept = req.headers.accept || ''
+          const pathname = (req.url || '').split('?')[0]
+          if (
+            req.method === 'GET' &&
+            accept.includes('text/html') &&
+            !/\.[a-zA-Z0-9]+$/.test(pathname)
+          ) {
+            req.url = '/index.html'
+          }
+          next()
+        })
+      },
+    },
   ],
 
   // Root directory for the assembled app
@@ -70,8 +99,8 @@ export default defineConfig({
   // Environment directory (project root for .env files)
   envDir: path.resolve(__dirname, '..'),
   
-  // PostCSS configuration
+  // PostCSS configuration (file on disk is postcss.config.cjs — must match exactly)
   css: {
-    postcss: path.resolve(__dirname, 'postcss.config.js'),
+    postcss: path.resolve(__dirname, 'postcss.config.cjs'),
   },
 })

package/netlify.toml

@@ -1,11 +1,11 @@
 [build]
-  command = "npm run build"
+  command = "npm run assemble && npm run build"
   publish = "dist"
   functions = ".assembled/netlify/functions"
 
   [build.environment]
     # Supabase VITE variables are meant to be public in the browser
-    SECRETS_SCAN_OMIT_KEYS = "VITE_SUPABASE_URL,VITE_SUPABASE_ANON_KEY,VITE_DB_SCHEMA,VITE_APP_NAME,VITE_ENVIRONMENT,SUPABASE_URL,DB_SCHEMA"
+    SECRETS_SCAN_OMIT_KEYS = "VITE_SUPABASE_URL,VITE_SUPABASE_ANON_KEY,VITE_DB_SCHEMA,VITE_APP_NAME,VITE_ENVIRONMENT,SUPABASE_URL,DB_SCHEMA,APP_BASE_URL,SITE_URL"
     SECRETS_SCAN_OMIT_PATHS = ".framework/.xenv,.framework/.xenv.test"
 
 # Spine functions configuration - assembled from .framework + custom
@@ -13,6 +13,10 @@
   directory = ".assembled/netlify/functions"
   included_files = [".assembled/netlify/functions/_shared/**"]
   node_bundler = "esbuild"
+  # typescript.js trips a flaky esbuild printer panic under parallel function
+  # bundling (cil-*, ai-agents, custom_case_analysis). Ship it unbundled —
+  # it's a real dependency loaded lazily at runtime.
+  external_node_modules = ["typescript"]
 
 [dev]
   command = "bash scripts/netlify-dev-wrapper.sh"
@@ -20,11 +24,15 @@
   port = 8888
   targetPort = 3001
   autoLaunch = false
-  startTimeout = 60
+  startTimeout = 300
 
 [functions."trigger-scheduler"]
   schedule = "* * * * *"
 
+# NOTE: app-specific schedules were removed — the root netlify.toml serves the
+# monorepo and must stay generic. Scheduled functions belong to each app's own
+# deployed Netlify config; app installers declare their own custom_* sections.
+
 # CIL ingestion passes are long-running — extend timeout for local dev
 # TODO: migrate to background functions for production
 [functions."cil-ingest"]
@@ -33,6 +41,21 @@
 [functions."cil-embeddings"]
   timeout = 300
 
+[functions."cil-callmap"]
+  timeout = 60
+
+# CIL agent can need multiple LLM tool-call rounds for broad questions
+[functions."cil-agent"]
+  timeout = 120
+
+# ai-agents run action drives multi-turn research steps (retrieval + tools + LLM)
+[functions."ai-agents"]
+  timeout = 120
+
+# kb reindex ingests an entire published corpus (batched, ~10 items in flight)
+[functions."kb"]
+  timeout = 120
+
 [[redirects]]
   from = "/*"
   to = "/index.html"
@@ -47,3 +70,8 @@
     Referrer-Policy = "strict-origin-when-cross-origin"
     Permissions-Policy = "camera=(), microphone=(), geolocation=()"
     X-XSS-Protection = "1; mode=block"
+    # CSP: 'unsafe-inline' in script-src is required by the Vite dev
+    # preamble and module-preload; challenges.cloudflare.com covers
+    # Turnstile. Supabase needs https + wss for realtime. No
+    # upgrade-insecure-requests — local dev runs over plain HTTP.
+    Content-Security-Policy = "default-src 'self'; script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' data: https://fonts.gstatic.com; img-src 'self' data: https: blob:; connect-src 'self' https://*.supabase.co wss://*.supabase.co https://api.netlify.com https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; object-src 'none'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.144",
+  "version": "0.4.0",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {
@@ -8,31 +8,40 @@
   },
   "files": [
     "bin/",
-    "scripts/",
+    "scripts/assemble.sh",
+    "scripts/assemble-frontend.sh",
+    "scripts/assemble-functions.sh",
+    "scripts/dev-netlify.sh",
+    "scripts/dev-clean.sh",
+    "scripts/netlify-dev-wrapper.sh",
+    "scripts/verify-integrity.sh",
+    "scripts/build-manifest.sh",
+    "scripts/checksum-manifest.mts",
+    "scripts/verify-manifest.mts",
+    "scripts/boundary-check.sh",
+    "scripts/verify-install.ts",
     "config/",
+    "!config/*.tsbuildinfo",
+    "!config/deno.lock",
+    "!config/package-lock.json",
+    "templates/project/",
+    "vitest.config.ts",
     "netlify.toml",
-    "spine.config.json",
-    ".framework/cli/bin.js",
-    ".framework/cli/",
-    ".framework/docs/",
-    ".framework/functions/",
-    ".framework/migrations/*.sql",
-    ".framework/public/",
-    ".framework/scripts/",
-    ".framework/seeds/",
-    ".framework/src/",
-    ".framework/index.html",
-    ".framework/README.md",
-    "custom/.devin/",
-    "custom/README.md",
-    "docs/APPS.md",
-    "docs/ARCHITECTURE.md",
-    "docs/INSTALL.md",
-    "docs/README.md",
-    "docs/spine-core--api-reference.md",
-    "docs/design-schema-spec.md",
-    "docs/dev-guides/",
-    "docs/npm-packages-plan.md",
+    ".env.example",
+    ".framework/",
+    "!.framework/migrations/archive/",
+    "!.framework/functions/_quarantine/",
+    "!.framework/tests/integration/",
+    "!.framework/public/spine.config.json",
+    "!**/*.tsbuildinfo",
+    "!**/.DS_Store",
+    "!**/.env",
+    "!**/.env.local",
+    "!**/.env.production",
+    "!**/.env.development",
+    "!**/.env.test",
+    "!**/.xenv",
+    "!**/.xenv.*",
     "README.md",
     "LICENSE.md"
   ],
@@ -57,13 +66,15 @@
   "scripts": {
     "spine-framework": "tsx .framework/cli/index.ts",
     "dev": "vite --config config/vite.config.ts",
+    "dev:netlify": "bash scripts/dev-netlify.sh",
+    "dev:stop": "bash scripts/dev-clean.sh",
     "assemble": "bash scripts/assemble.sh",
     "assemble:frontend": "bash scripts/assemble-frontend.sh",
     "assemble:functions": "bash scripts/assemble-functions.sh",
     "manifest": "bash scripts/build-manifest.sh",
     "verify": "bash scripts/verify-integrity.sh",
     "prebuild": "npm run assemble && npm run verify",
-    "build": "tsc -b config/tsconfig.json && vite build --config config/vite.config.ts",
+    "build": "vite build --config config/vite.config.ts",
     "preview": "vite preview --config config/vite.config.ts",
     "lint": "eslint .",
     "app-install": "tsx scripts/app-install-cli.ts",
@@ -75,12 +86,18 @@
     "test:boundary": "bash scripts/boundary-check.sh",
     "docs": "typedoc --entryPoints .framework/functions/_shared/index.ts --out docs/generated",
     "mcp": "tsx --env-file=.env .framework/mcp/index.ts",
-    "mcp:spine-framework": "tsx --env-file=.env .framework/mcp/index.ts"
+    "mcp:spine-framework": "tsx --env-file=.env .framework/mcp/index.ts",
+    "prepack": "node custom/npm/scripts/prepack-framework.mjs stage",
+    "postpack": "node custom/npm/scripts/prepack-framework.mjs clean",
+    "cil:migrate-markers": "tsx .framework/scripts/cil-migrate-markers.ts",
+    "typecheck": "tsc -b config/tsconfig.json",
+    "typecheck:functions": "tsc --noEmit -p config/tsconfig.functions.json"
   },
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
     "@heroicons/react": "^2.2.0",
+    "@marsidev/react-turnstile": "^1.1.0",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-avatar": "^1.1.3",
     "@radix-ui/react-dialog": "^1.1.6",
@@ -115,6 +132,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "commander": "^12.0.0",
     "dagre": "^0.8.5",
     "date-fns": "^4.1.0",
     "dompurify": "^3.4.13",
@@ -153,6 +171,7 @@
     "tiptap-markdown": "^0.9.0",
     "tsx": "^4.21.0",
     "tw-animate-css": "^1.4.0",
+    "typescript": "~5.6.2",
     "vaul": "^1.1.2",
     "ws": "^8.18.0"
   },
@@ -168,14 +187,12 @@
     "@vitejs/plugin-react": "^4.3.4",
     "ajv": "^8.12.0",
     "autoprefixer": "^10.4.20",
-    "commander": "^12.0.0",
     "js-yaml": "^4.1.0",
+    "netlify-cli": "27.8.0",
     "postcss": "^8.5.1",
     "react-refresh": "^0.14.0",
     "tailwindcss": "^3.4.17",
-    "tsx": "^4.21.0",
     "typedoc": "^0.27.0",
-    "typescript": "~5.6.2",
     "vite": "^6.0.11",
     "vitest": "^2.1.9"
   },

package/scripts/assemble-frontend.sh

@@ -1,89 +1,172 @@
 #!/usr/bin/env bash
 
-# Frontend Assembly - Merge .framework/src + custom/apps/*/src → .assembled/src
+# CIL[BEGIN stable_id="~/scripts/assemble-frontend.sh:module:script" type="script" identity="assemble-frontend" parent="~/scripts/assemble-frontend.sh"]
+# CIL[DOC-MACRO purpose="Assemble .framework/src base layer + each custom app under .assembled/src/<app-slug>/ and merge public assets with collision detection, for the Vite build."]
+# CIL[DOC-RESPONSIBILITY responsibility="Stage core src, per-app dirs (verbatim, no basename flattening), index.html path fix, _redirects, and public assets; then mtime-preserving rsync into .assembled/src and public/."]
+# CIL[DOC-CONTEXT module="assembly" layer="build" related_files="scripts/assemble-functions.sh,scripts/assemble.sh,config/vite.config.ts,.framework/src/components/CustomAppLoader.tsx"]
+# CIL[DOC-CONTRACT inputs=".framework/src,.framework/public,custom/apps/*,spine.config.json; env SPINE_PROJECT_ROOT (fixture override for tests)" outputs=".assembled/src + merged public/; exit 1 on public-path collision" errors="hard error naming both sources when two public assets share a relative path with different content" side_effects="rewrites .assembled/src and public/"]
+# CIL[DOC-MICRO logic_summary="Temp-dir staging → core copy → per-app rsync with excludes (functions/seed/public/node_modules/dist/dotfiles) → public manifest-tracked collision check → rsync -rlc (no -t) publish." notable_decisions="identical duplicate public assets skip silently; root spine.config.json wins over framework template; no .gitkeep rsync exclude so --delete can remove stale dirs"]
+# CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+# CIL[DOC-STABILITY stability="stable"]
+# CIL[DOC-NOTE type="invariant" content="import.meta.glob('../../../custom/apps/*/index.tsx') in CustomAppLoader must keep resolving — app dirs are copied verbatim under src/<slug>/, never flattened by basename."]
+# CIL[END stable_id="~/scripts/assemble-frontend.sh:module:script"]
+
+# Frontend Assembly - Merge .framework/src + custom/apps/* → .assembled/src
 #
 # Purpose: Create unified frontend source directory for Vite build process.
-# - .framework/src is the canonical Spine frontend
-# - custom/apps/*/src are your application sources
-# - Vite expects a single src directory, so we assemble at build time
+# - .framework/src is the canonical Spine frontend (base layer at root)
+# - each custom/apps/<app> is copied to .assembled/src/<app-slug>/ VERBATIM —
+#   no basename flattening (two apps' components/ must never merge silently)
+# - custom app index resolution uses import.meta.glob('../../../custom/apps/*/index.tsx')
+#   in .framework/src/components/CustomAppLoader.tsx — assembled app dirs exist
+#   for @/(@core)-style imports and layout consistency, not for the glob
 #
 # Process:
-# 1. Clean target directory
-# 2. Copy core src files
-# 3. Overlay custom src files (overwrites existing)
+# 1. Assemble into temp directory first
+# 2. Copy core src files (base layer)
+# 3. Copy each app to <app-slug>/, excluding functions/, seed/, public/,
+#    node_modules, dist, and dotfiles
+# 4. Merge public assets with same-relative-path collision detection
+# 5. rsync -c into target so unchanged files keep their mtimes — Vite then only
+#    reloads modules that actually changed instead of every file
+#
+# SPINE_PROJECT_ROOT (optional): override the project root — used by the
+# fixture-based unit tests; production use leaves it unset.
 #
-# Dependencies: standard bash utilities, find, cp, rsync
+# Dependencies: standard bash utilities, find, cp, rsync, cmp
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+# Canonicalize (-P resolves symlinks) — consistent with assemble-functions.sh
+# and safe when the repo itself is reached through a symlinked path.
+PROJECT_ROOT="$(cd "${SPINE_PROJECT_ROOT:-$(dirname "$SCRIPT_DIR")}" && pwd -P)"
 
 CORE_SRC_DIR="$PROJECT_ROOT/.framework/src"
 CUSTOM_SRC_DIR="$PROJECT_ROOT/custom/apps"
 TARGET_SRC_DIR="$PROJECT_ROOT/.assembled/src"
+VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
+TMP_ROOT="$PROJECT_ROOT/.frontend-assemble-tmp"
+TMP_SRC_DIR="$TMP_ROOT/src"
+TMP_PUBLIC_DIR="$TMP_ROOT/public"
+# rel-path → source-file map for public-asset collision errors
+PUBLIC_MANIFEST="$TMP_ROOT/public-manifest.tsv"
 
 echo "🔧 Assembling frontend → $TARGET_SRC_DIR"
 
-# 1. Clean target (except .gitkeep if exists)
-if [ -d "$TARGET_SRC_DIR" ]; then
-  find "$TARGET_SRC_DIR" -mindepth 1 -not -name '.gitkeep' -delete 2>/dev/null || true
-else
-  mkdir -p "$TARGET_SRC_DIR"
-fi
+# 1. Stage into temp dir
+rm -rf "$TMP_ROOT"
+mkdir -p "$TMP_SRC_DIR" "$TMP_PUBLIC_DIR"
+: > "$PUBLIC_MANIFEST"
 
 # 2. Copy core src (base layer)
 if [ -d "$CORE_SRC_DIR" ]; then
-  # Ensure subdirectories are copied properly
-  cp -r "$CORE_SRC_DIR"/* "$TARGET_SRC_DIR"/ 2>/dev/null || true
+  cp -r "$CORE_SRC_DIR"/* "$TMP_SRC_DIR"/ 2>/dev/null || true
   echo "  ✓ Core: $(find "$CORE_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' | wc -l | tr -d ' ') files"
 else
   echo "  ⚠ Core: $CORE_SRC_DIR not found"
 fi
 
-# 4. Copy public files from .framework
+# 3. Copy index.html, fixing the script src path for assembled structure
 if [ -f "$PROJECT_ROOT/.framework/index.html" ]; then
-  # Copy and fix the script src path for assembled structure
-  sed 's|/src/main.tsx|./main.tsx|g' "$PROJECT_ROOT/.framework/index.html" > "$TARGET_SRC_DIR/index.html"
+  sed 's|/src/main.tsx|./main.tsx|g' "$PROJECT_ROOT/.framework/index.html" > "$TMP_SRC_DIR/index.html"
   echo "  ✓ Core: index.html (paths fixed)"
 fi
 
-# 3. Copy public assets from .framework
-# Vite's publicDir is set to PROJECT_ROOT/public (i.e. ../public relative to .assembled/src)
-# so static files must go there to be served at the root URL
-VITE_PUBLIC_DIR="$PROJECT_ROOT/public"
+# 4. Stage a public-asset source dir into TMP_PUBLIC_DIR with collision
+# detection. The SAME relative path may never come from two different sources:
+# - identical content → skip silently (duplicate copy is harmless)
+# - differing content → hard error naming both source files
+stage_public_dir() {
+  local src_dir="$1"
+  local f rel staged prev
+  while IFS= read -r -d '' f; do
+    rel="${f#"$src_dir"/}"
+    staged="$TMP_PUBLIC_DIR/$rel"
+    if [ -e "$staged" ]; then
+      if cmp -s "$f" "$staged"; then
+        continue
+      fi
+      prev="$(awk -F '\t' -v r="$rel" '$1 == r { print $2; exit }' "$PUBLIC_MANIFEST")"
+      echo "  ✗ Public asset collision: '$rel' is provided by both" >&2
+      echo "      - $prev" >&2
+      echo "      - $f" >&2
+      echo "    Rename one of them — public/ merges flat, last-wins is forbidden." >&2
+      exit 1
+    fi
+    mkdir -p "$(dirname "$staged")"
+    cp "$f" "$staged"
+    printf '%s\t%s\n' "$rel" "$f" >> "$PUBLIC_MANIFEST"
+  done < <(find "$src_dir" -type f ! -name '.*' -print0 | sort -z)
+}
+
+# 5. Framework public assets merge first — Vite's publicDir is
+# PROJECT_ROOT/public, so static files must land there to be served at root URL
 if [ -d "$PROJECT_ROOT/.framework/public" ]; then
-  mkdir -p "$VITE_PUBLIC_DIR"
-  cp -r "$PROJECT_ROOT/.framework/public"/* "$VITE_PUBLIC_DIR/" 2>/dev/null || true
+  stage_public_dir "$PROJECT_ROOT/.framework/public"
   echo "  ✓ Core: $(find "$PROJECT_ROOT/.framework/public" -type f | wc -l | tr -d ' ') public files"
 fi
 
-# 3.5. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
+# 6. Copy _redirects to Vite-served root for Netlify dev (served from .assembled/src root)
 if [ -f "$PROJECT_ROOT/.framework/public/_redirects" ]; then
-  cp "$PROJECT_ROOT/.framework/public/_redirects" "$TARGET_SRC_DIR/_redirects"
+  cp "$PROJECT_ROOT/.framework/public/_redirects" "$TMP_SRC_DIR/_redirects"
   echo "  ✓ Core: _redirects copied to Vite-served directory for Netlify dev"
 fi
 
-# 3.6. Copy spine.config.json to Vite publicDir so it's served at /spine.config.json
+# 7. Per-app copy: custom/apps/<app> → .assembled/src/<app-slug>/ verbatim.
+# Excluded: functions (goes to .assembled/netlify/functions), seed, public
+# (merged into /public above), node_modules, dist, dotfiles.
+CUSTOM_COUNT=0
+if [ -d "$CUSTOM_SRC_DIR" ]; then
+  for app_dir in "$CUSTOM_SRC_DIR"/*/; do
+    [ -d "$app_dir" ] || continue
+    slug="$(basename "$app_dir")"
+
+    rsync -a \
+      --exclude='functions' \
+      --exclude='seed' \
+      --exclude='public' \
+      --exclude='node_modules' \
+      --exclude='dist' \
+      --exclude='.*' \
+      "$app_dir" "$TMP_SRC_DIR/$slug/"
+
+    # App public assets merge into /public AFTER framework public; a same
+    # relative path in two sources (or vs framework) is a hard error above.
+    if [ -d "$app_dir/public" ]; then
+      stage_public_dir "$app_dir/public"
+    fi
+
+    app_count=$(find "$TMP_SRC_DIR/$slug" -name '*.tsx' -o -name '*.ts' -o -name '*.css' 2>/dev/null | wc -l | tr -d ' ')
+    CUSTOM_COUNT=$((CUSTOM_COUNT + app_count))
+    echo "  ✓ $slug: $app_count files → src/$slug/"
+  done
+fi
+if [ "$CUSTOM_COUNT" -eq 0 ]; then
+  echo "  ○ Custom: (empty)"
+fi
+
+# 8. spine.config.json → staged public (root config, served at /spine.config.json).
+# The ROOT copy is the instance config and intentionally wins over the
+# framework template of the same name (framework/public/spine.config.json).
 if [ -f "$PROJECT_ROOT/spine.config.json" ]; then
-  mkdir -p "$VITE_PUBLIC_DIR"
-  cp "$PROJECT_ROOT/spine.config.json" "$VITE_PUBLIC_DIR/spine.config.json"
+  cp -f "$PROJECT_ROOT/spine.config.json" "$TMP_PUBLIC_DIR/spine.config.json"
   echo "  ✓ Config: spine.config.json copied to public/"
 fi
 
-# 6. Overlay custom src (overrides + additions)
-if [ -d "$CUSTOM_SRC_DIR" ]; then
-  # Copy files and subdirectories
-  cp -r "$CUSTOM_SRC_DIR"/* "$TARGET_SRC_DIR"/ 2>/dev/null || true
-  
-  # Handle subdirectories properly
-  find "$CUSTOM_SRC_DIR" -mindepth 1 -type d -exec sh -c 'dir="$1"; base=$(basename "$dir"); mkdir -p "'"$TARGET_SRC_DIR"'/$base" && cp -r "$dir"/* "'"$TARGET_SRC_DIR"'/$base/"' _ {} \; 2>/dev/null || true
-  
-  CUSTOM_COUNT=$(find "$CUSTOM_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' 2>/dev/null | wc -l | tr -d ' ')
-  echo "  ✓ Custom: $CUSTOM_COUNT files"
-else
-  echo "  ○ Custom: (empty)"
-fi
+# 9. Publish staged public assets. -c compares content checksums; deliberately
+# NO -t so unchanged files keep mtimes (see final sync note below).
+mkdir -p "$VITE_PUBLIC_DIR"
+rsync -rlc "$TMP_PUBLIC_DIR"/ "$VITE_PUBLIC_DIR"/
+
+# 10. Sync temp into place. -c compares content checksums; deliberately NO -t —
+# otherwise rsync "corrects" mtimes of unchanged files to the fresh temp-copy
+# time and Vite reloads the entire module graph on every assemble.
+mkdir -p "$TARGET_SRC_DIR"
+# No .gitkeep exclusion: .assembled/ is gitignored, and leftover .gitkeep
+# files inside stale dirs would make --delete treat them as non-empty.
+rsync -rlc --delete "$TMP_SRC_DIR"/ "$TARGET_SRC_DIR"/
+rm -rf "$TMP_ROOT"
 
 echo "  ✓ Assembled: $(find "$TARGET_SRC_DIR" -name '*.tsx' -o -name '*.ts' -o -name '*.css' | wc -l | tr -d ' ') total files"
 echo "✅ Done"