spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/cli/commands/init.ts

@@ -20,6 +20,8 @@ import {
   mergePackageJson,
   writeFrozenManifest,
   sanitizePackageName,
+  syncAgentFiles,
+  collectAgentFileHashes,
 } from '../lib/project-files.ts'
 // CIL[END stable_id="~/.framework/cli/commands/init.ts:module_header:module_header"]
 
@@ -137,11 +139,23 @@ export function registerInitCommands(program: Command) {
           console.log('  ✓ spine.config.json written (neutral template)')
         }
 
-        // 8. Frozen integrity manifest — version + framework-owned dep inventory
+        // 8. Agent assets — AGENTS.md framework block + .devin/skills/spine-*
+        const agentActions = syncAgentFiles({
+          pkgRoot: PACKAGE_ROOT,
+          projectRoot: target,
+          entries: profile.agent_files ?? [],
+          version: frameworkVersion,
+        })
+        for (const a of agentActions) {
+          console.log(`  ✓ ${a.rel} (${a.action}${a.detail ? ` — ${a.detail}` : ''})`)
+        }
+
+        // 9. Frozen integrity manifest — version + framework-owned dep inventory
         const manifest = writeFrozenManifest({
           projectRoot: target,
           frameworkVersion,
           frameworkDeps: merged.frameworkDeps,
+          agentFiles: collectAgentFileHashes(target, profile.agent_files ?? []),
         })
         console.log(`  ✓ .spine-manifest.json written (${manifest.fileCount} protected files, frozen)`)
 
@@ -158,6 +172,11 @@ export function registerInitCommands(program: Command) {
         console.log('  5. npx spine-framework migrate')
         console.log('  6. npm run dev:netlify')
         console.log()
+        console.log('Docs + agent assets:')
+        console.log('  - Instruction book: .framework/src/instructions/README.md')
+        console.log('  - Agent rules:      AGENTS.md (framework block refreshes on upgrade)')
+        console.log('  - Agent skills:     .devin/skills/spine-*')
+        console.log()
       } catch (err: any) {
         console.error('\n❌ Init failed:', err.message)
         if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)

package/.framework/cli/commands/install-app.ts

@@ -142,7 +142,7 @@ interface SpineConfig {
 // CIL[DOC-AUDIENCE audience="internal"]
 
 import type { Command } from 'commander'
-import { existsSync, readFileSync, mkdirSync, cpSync, writeFileSync, realpathSync, statSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, cpSync, writeFileSync, realpathSync, statSync, readdirSync, rmSync } from 'fs'
 import { resolve, dirname, join, basename, isAbsolute, sep } from 'path'
 import { fileURLToPath } from 'url'
 import { execSync } from 'child_process'
@@ -319,6 +319,165 @@ const SPINE_CONFIG_PATH = join(PROJECT_ROOT, 'spine.config.json')
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 
 
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:appcopyentries:constant" type="constant" identity="APP_COPY_ENTRIES" parent="none"]
+// CIL[DOC-MACRO purpose="Single allowlist of package entries copied into custom/apps/<slug>/ on install and update"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the shared copy allowlist so install-app and update-app cannot drift apart"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/validate-app.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="readonly string[] of top-level package entries" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Union of both commands' previous lists plus entries real apps ship (lib/views/docs/installer/mcp/migrations/tests/standalone.config.json); 'agent' is handled separately by syncAppAgentAssets" notable_decisions="['shared_allowlist_prevents_drift','agent_staged_not_copied_verbatim']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+const APP_COPY_ENTRIES: readonly string[] = [
+  'index.tsx', 'manifest.json', 'package.json', 'standalone.config.json',
+  'pages', 'components', 'hooks', 'utils', 'lib', 'views', 'docs',
+  'functions', 'api', 'seed', 'public', 'installer', 'mcp',
+  'migrations', 'migrations-archive', 'tests', 'agent',
+]
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:appcopyentries:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:agentskillprefixre:constant" type="constant" identity="AGENT_SKILL_PREFIX_RE" parent="none"]
+// CIL[DOC-MACRO purpose="Validation regex for manifest agent.skill_prefix"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the single source of truth for the skill-prefix rule shared by install and validate paths"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/validate-app.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="RegExp matching 1-8 char lowercase-alphanumeric prefixes starting with a letter" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="/^[a-z][a-z0-9]{0,7}$/ — letter first, then up to 7 lowercase letters or digits" notable_decisions="['exported_for_shared_use']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+export const AGENT_SKILL_PREFIX_RE = /^[a-z][a-z0-9]{0,7}$/
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:agentskillprefixre:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:syncappagentassets:function" type="function" identity="syncAppAgentAssets" parent="none"]
+// CIL[DOC-MACRO purpose="Sync an installed app's staged agent assets (agent/skills, agent/instructions) to their live locations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Copy agent/skills/<prefix>_* to custom/.devin/skills/ and agent/instructions to the app's src/instructions/, enforcing the manifest-declared skill prefix"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/validate-app.ts,.framework/cli/lib/project-files.ts"]
+// CIL[DOC-CONTRACT inputs="appDir (installed app dir), appSlug" outputs="void" errors="Throws when agent/skills exists without manifest.agent.skill_prefix, a dir violates <prefix>_ naming, or SKILL.md name mismatches its dir" side_effects="writes custom/.devin/skills and app src/instructions"]
+// CIL[DOC-MICRO logic_summary="No-op without an agent/ dir; requires manifest.agent.skill_prefix /^[a-z][a-z0-9]{0,7}$/ when skills are staged; fails on cross-app prefix collisions by scanning installed manifests; copies instructions to src/instructions" notable_decisions="['fail_closed_on_missing_prefix','prefix_scoped_ownership']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function syncAppAgentAssets(appDir: string, appSlug: string): void {
+  const agentDir = join(appDir, 'agent')
+  if (!existsSync(agentDir)) return
+
+  const stagedSkills = join(agentDir, 'skills')
+  const stagedInstructions = join(agentDir, 'instructions')
+  const hasSkills = existsSync(stagedSkills)
+  const hasInstructions = existsSync(stagedInstructions)
+  if (!hasSkills && !hasInstructions) return
+
+  const manifest: Record<string, any> = JSON.parse(readFileSync(join(appDir, 'manifest.json'), 'utf8'))
+  const prefix = manifest.agent?.skill_prefix
+
+  if (hasSkills) {
+    if (typeof prefix !== 'string' || !AGENT_SKILL_PREFIX_RE.test(prefix)) {
+      throw new Error(`manifest.json agent.skill_prefix for "${appSlug}" is required (^[a-z][a-z0-9]{0,7}$) when the package ships agent/skills/`)
+    }
+
+    for (const other of readdirSync(join(PROJECT_ROOT, 'custom', 'apps'), { withFileTypes: true })) {
+      if (!other.isDirectory() || other.name === appSlug) continue
+      const otherManifest = join(PROJECT_ROOT, 'custom', 'apps', other.name, 'manifest.json')
+      try {
+        const m = JSON.parse(readFileSync(otherManifest, 'utf8'))
+        if (m.agent?.skill_prefix === prefix) {
+          throw new Error(`skill_prefix "${prefix}" is already used by app "${other.name}" — prefixes must be unique across installed apps`)
+        }
+      } catch (e: any) {
+        if (e.message?.includes('skill_prefix')) throw e
+      }
+    }
+
+    const skillsDest = join(PROJECT_ROOT, 'custom', '.devin', 'skills')
+    for (const dir of readdirSync(stagedSkills, { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue
+      if (!dir.name.startsWith(`${prefix}_`)) {
+        throw new Error(`agent/skills/${dir.name} does not match the declared prefix "${prefix}_"`)
+      }
+      const skillFile = join(stagedSkills, dir.name, 'SKILL.md')
+      if (!existsSync(skillFile)) {
+        throw new Error(`agent/skills/${dir.name} is missing SKILL.md`)
+      }
+      const nameMatch = /^name:\s*(.+)$/m.exec(readFileSync(skillFile, 'utf8'))
+      if (!nameMatch || nameMatch[1].trim() !== dir.name) {
+        throw new Error(`agent/skills/${dir.name}/SKILL.md name field must equal its directory name "${dir.name}"`)
+      }
+      cpSync(join(stagedSkills, dir.name), join(skillsDest, dir.name), { recursive: true })
+      console.log(`    Skill installed: custom/.devin/skills/${dir.name}`)
+    }
+  }
+
+  if (hasInstructions) {
+    const instrDest = join(appDir, 'src', 'instructions')
+    mkdirSync(instrDest, { recursive: true })
+    cpSync(stagedInstructions, instrDest, { recursive: true })
+    console.log(`    Instructions installed: custom/apps/${appSlug}/src/instructions/`)
+  }
+}
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:syncappagentassets:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:removeappagentskills:function" type="function" identity="removeAppAgentSkills" parent="none"]
+// CIL[DOC-MACRO purpose="Remove an app's prefix-scoped skills from custom/.devin/skills on uninstall"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delete only the skill dirs owned by the uninstalled app's declared skill_prefix"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/install-app.ts"]
+// CIL[DOC-CONTRACT inputs="appDir, appSlug" outputs="void" errors="none" side_effects="removes custom/.devin/skills/<prefix>_* dirs"]
+// CIL[DOC-MICRO logic_summary="Reads manifest.agent.skill_prefix from the app dir before deletion; globs <prefix>_* dirs and removes them; never touches unowned dirs" notable_decisions="['prefix_glob_scoped_removal']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function removeAppAgentSkills(appDir: string, appSlug: string): void {
+  try {
+    const manifest: Record<string, any> = JSON.parse(readFileSync(join(appDir, 'manifest.json'), 'utf8'))
+    const prefix = manifest.agent?.skill_prefix
+    if (typeof prefix !== 'string' || !prefix) return
+    const skillsDir = join(PROJECT_ROOT, 'custom', '.devin', 'skills')
+    if (!existsSync(skillsDir)) return
+    for (const dir of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (dir.isDirectory() && dir.name.startsWith(`${prefix}_`)) {
+        rmSync(join(skillsDir, dir.name), { recursive: true, force: true })
+        console.log(`  ✓ Removed skill custom/.devin/skills/${dir.name}`)
+      }
+    }
+  } catch {
+    console.log(`  ○ No agent.skill_prefix for "${appSlug}" — no skills to remove`)
+  }
+}
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:removeappagentskills:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:islocalpackagespec:function" type="function" identity="isLocalPackageSpec" parent="none"]
+// CIL[DOC-MACRO purpose="Detect package specs that resolve to a local path instead of an npm registry name"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return true for file:, ./, ../, / and *.tgz specs so commands can skip registry-only syntax like @latest"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/install-app.ts"]
+// CIL[DOC-CONTRACT inputs="packageName: string (the CLI <package> argument)" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Path-shaped specs (file:, dot-relative, absolute, .tgz) are local; everything else is a registry spec" notable_decisions="['local_specs_have_no_version_tag']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function isLocalPackageSpec(packageName: string): boolean {
+  return packageName.startsWith('file:')
+    || packageName.startsWith('.')
+    || packageName.startsWith('/')
+    || packageName.endsWith('.tgz')
+}
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:islocalpackagespec:function"]
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/install-app.ts:resolvepackagedirname:function" type="function" identity="resolvePackageDirName" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve the node_modules directory name an install spec lands under"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map install-app/update-app/uninstall-app <package> args — registry names (plain or scoped), tarball paths, and file:/path dirs — to the name npm uses for node_modules/<name>"]
+// CIL[DOC-CONTEXT module="install-app" layer="cli" related_files=".framework/cli/commands/install-app.ts"]
+// CIL[DOC-CONTRACT inputs="packageName: string" outputs="npm package name (may be scoped, e.g. @scope/name)" errors="throws if a tarball or directory spec has no readable package.json" side_effects="execSync tar for .tgz specs"]
+// CIL[DOC-MICRO logic_summary="Tarballs yield their embedded package/package.json name via tar -xOf; file:/path and relative/absolute dirs read package.json directly; registry specs strip only the trailing @version so scoped names survive" notable_decisions="['tarball_name_comes_from_the_package_not_the_filename','split_on_last_at_preserves_scopes']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function resolvePackageDirName(packageName: string): string {
+  let spec = packageName
+  if (spec.startsWith('file:')) spec = spec.slice(5)
+  if (spec.endsWith('.tgz')) {
+    const json = execSync(`tar -xOf "${spec}" package/package.json`, { cwd: PROJECT_ROOT, encoding: 'utf8' })
+    return JSON.parse(json).name
+  }
+  if (spec.startsWith('.') || spec.startsWith('/')) {
+    return JSON.parse(readFileSync(join(PROJECT_ROOT, spec, 'package.json'), 'utf8')).name
+  }
+  return packageName.replace(/@[^@/]+$/, '')
+}
+// CIL[END stable_id="~/.framework/cli/commands/install-app.ts:resolvepackagedirname:function"]
+
 // CIL[DOC-MACRO purpose="Command registration and installation handler for Spine Framework apps."]
 // CIL[DOC-RESPONSIBILITY responsibility="Registers a command to install a Spine Framework app from npm and handles the installation process, including file copying and database migrations. This function ensures that the app is properly set up within the project environment."]
 // CIL[DOC-CONTEXT module="install-app" layer="app-specific" related_files=".framework/cli/commands/migrate.js"]
@@ -371,7 +530,7 @@ export function registerInstallAppCommands(program: Command) {
         console.log('  ✓ npm install complete')
 
         
-        const pkgSlug = packageName.split('@')[0] // strip version
+        const pkgSlug = resolvePackageDirName(packageName)
         const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
 
         if (!existsSync(pkgPath)) {
@@ -392,14 +551,9 @@ export function registerInstallAppCommands(program: Command) {
         }
 
         
-        const allowedEntries = [
-          'index.tsx', 'manifest.json', 'package.json',
-          'pages', 'components', 'hooks', 'utils', 'functions', 'seed', 'public'
-        ]
-
         console.log(`  Copying files from ${pkgPath} to ${appDest}`)
 
-        for (const entry of allowedEntries) {
+        for (const entry of APP_COPY_ENTRIES) {
           const src = join(pkgPath, entry)
           if (!existsSync(src)) continue
 
@@ -415,6 +569,9 @@ export function registerInstallAppCommands(program: Command) {
         console.log(`  ✓ App files copied to custom/apps/${appSlug}/`)
 
         
+        syncAppAgentAssets(appDest, appSlug)
+
+        
         console.log('  Running migrations...')
         const migrateResult = await runMigrations({ frameworkOnly: false })
         if (migrateResult === null) {
@@ -468,14 +625,14 @@ export function registerInstallAppCommands(program: Command) {
       console.log(`\nUninstalling app: ${packageName}\n`)
       loadEnv()
 
-      const pkgSlug = packageName.split('@')[0]
+      const pkgSlug = resolvePackageDirName(packageName)
       const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
       const appSlug = resolveAppSlug(pkgPath, pkgSlug)
       const appDir = join(PROJECT_ROOT, 'custom/apps', appSlug)
 
       try {
         if (existsSync(appDir)) {
-          const { rmSync } = await import('fs')
+          removeAppAgentSkills(appDir, appSlug)
           rmSync(appDir, { recursive: true, force: true })
           console.log(`  ✓ Removed custom/apps/${appSlug}/`)
         } else {
@@ -501,12 +658,12 @@ export function registerInstallAppCommands(program: Command) {
       loadEnv()
 
       try {
-        execSync(`npm install ${packageName}@latest --save`, {
+        execSync(`npm install ${isLocalPackageSpec(packageName) ? packageName : `${packageName}@latest`} --save`, {
           cwd: PROJECT_ROOT,
           stdio: 'inherit',
         })
 
-        const pkgSlug = packageName.split('@')[0]
+        const pkgSlug = resolvePackageDirName(packageName)
         const pkgPath = join(PROJECT_ROOT, 'node_modules', pkgSlug)
         const appSlug = resolveAppSlug(pkgPath, pkgSlug)
         const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
@@ -515,13 +672,16 @@ export function registerInstallAppCommands(program: Command) {
           mkdirSync(appDest, { recursive: true })
         }
 
-        for (const entry of ['index.tsx', 'manifest.json', 'pages', 'components', 'hooks', 'api', 'seed']) {
+        for (const entry of APP_COPY_ENTRIES) {
           const src = join(pkgPath, entry)
           if (existsSync(src)) {
+            if (entry === 'manifest.json' && existsSync(join(appDest, 'manifest.json'))) continue
             cpSync(src, join(appDest, entry), { recursive: true })
           }
         }
 
+        syncAppAgentAssets(appDest, appSlug)
+
         
         const manifestPath = join(appDest, 'manifest.json')
         let manifest: Record<string, any> = {}
@@ -1195,6 +1355,14 @@ function preflightAppInputs(appDir: string, appSlug: string, configPath: string)
   if (manifest.config !== undefined && manifest.config !== null && !isPlainObject(manifest.config)) {
     throw new Error(`manifest.json config for "${appSlug}" must be an object`)
   }
+  if (manifest.agent !== undefined && manifest.agent !== null) {
+    if (!isPlainObject(manifest.agent)) {
+      throw new Error(`manifest.json agent for "${appSlug}" must be an object`)
+    }
+    if (manifest.agent.skill_prefix !== undefined && !AGENT_SKILL_PREFIX_RE.test(manifest.agent.skill_prefix)) {
+      throw new Error(`manifest.json agent.skill_prefix for "${appSlug}" must match ${AGENT_SKILL_PREFIX_RE}`)
+    }
+  }
   if (manifest.owned_types !== undefined) {
     if (!Array.isArray(manifest.owned_types) || manifest.owned_types.some((s: any) => typeof s !== 'string' || !s.trim())) {
       throw new Error(`manifest.json owned_types for "${appSlug}" must be an array of non-empty strings`)
@@ -1483,6 +1651,8 @@ function appRowPayload(manifest: Record<string, any>, appSlug: string, existingC
     min_role: manifest.required_roles?.[0] ?? manifest.min_role ?? null,
     preview_domain: manifest.preview_domain ?? null,
     prod_domain: manifest.prod_domain ?? null,
+    preview_route_prefix: manifest.preview_route_prefix ?? null,
+    prod_route_prefix: manifest.prod_route_prefix ?? null,
     config: mergedConfig,
     metadata: manifest.metadata ?? undefined,
   }

package/.framework/cli/commands/migrate.ts

@@ -22,15 +22,14 @@ import type { Command } from 'commander'
 import { existsSync, readdirSync, readFileSync } from 'fs'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:module_header:module_header"]
 // CIL[DOC-VECTOR type="context" content="purpose='Provides the migrate command for applying database migrations to a Supabase project.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:module_header:module_header"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Defines the current module file path."]
 // CIL[DOC-RESPONSIBILITY responsibility="Derives __filename from the module import meta URL."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -39,6 +38,7 @@ import { fileURLToPath } from 'url'
 // CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
 // CIL[DOC-MICRO logic_summary="Converts import.meta.url to a file path and assigns to __filename." notable_decisions="none"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/migrate.ts"]
 const __filename = fileURLToPath(import.meta.url)
 // CIL[END stable_id="~/.framework/cli/commands/migrate.ts:__filename:constant"]
 // CIL[DOC-CONTEXT module="unknown" layer="unknown" related_files=".framework/cli/commands/migrate.ts"]
@@ -48,7 +48,6 @@ const __filename = fileURLToPath(import.meta.url)
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Defines the current module directory."]
 // CIL[DOC-RESPONSIBILITY responsibility="Derives __dirname from __filename."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -57,9 +56,9 @@ const __filename = fileURLToPath(import.meta.url)
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-MICRO logic_summary="Computes the directory of the current file and assigns to __dirname." notable_decisions="none"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/migrate.ts"]
 const __dirname = dirname(__filename)
 // CIL[END stable_id="~/.framework/cli/commands/migrate.ts:__dirname:constant"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PACKAGE_ROOT:constant" type="constant" identity="PACKAGE_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-VECTOR type="context" content="purpose='Defines the current module directory.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
@@ -74,6 +73,7 @@ const __dirname = dirname(__filename)
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PACKAGE_ROOT:constant" type="constant" identity="PACKAGE_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
 const PACKAGE_ROOT = resolve(__dirname, '../../../')
 // CIL[END stable_id="~/.framework/cli/commands/migrate.ts:PACKAGE_ROOT:constant"]
 // CIL[DOC-VECTOR type="context" content="purpose='Defines the package root path.'; No verified external callers; imports: none"]
@@ -82,7 +82,6 @@ const PACKAGE_ROOT = resolve(__dirname, '../../../')
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Defines the project root path."]
 // CIL[DOC-RESPONSIBILITY responsibility="Uses the current working directory as the project root."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -91,17 +90,17 @@ const PACKAGE_ROOT = resolve(__dirname, '../../../')
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/migrate.ts"]
 const PROJECT_ROOT = process.cwd()
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant"]
 // CIL[DOC-VECTOR type="context" content="purpose='Defines the project root path.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:PROJECT_ROOT:constant"]
 
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface" type="interface" identity="MigrateOptions" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Declares the migrate command options."]
 // CIL[DOC-RESPONSIBILITY responsibility="Types the CLI flags and optional db password."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -110,20 +109,20 @@ const PROJECT_ROOT = process.cwd()
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface" type="interface" identity="MigrateOptions" parent="~/.framework/cli/commands/migrate.ts"]
 interface MigrateOptions {
   dbPassword?: string
   dryRun: boolean
   frameworkOnly: boolean
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Declares the migrate command options.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:MigrateOptions:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function" type="function" identity="runMigrations" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Applies pending SQL migration files to the Supabase database and tracks which have been applied."]
 // CIL[DOC-RESPONSIBILITY responsibility="Executes migrations safely in transactions and records them in the tracking table."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -132,6 +131,7 @@ interface MigrateOptions {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function" type="function" identity="runMigrations" parent="~/.framework/cli/commands/migrate.ts"]
 export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Promise<{ applied: number; skipped: number; failed: number } | null> {
   const supabaseUrl = process.env.SUPABASE_URL
   if (!supabaseUrl || supabaseUrl.includes('placeholder') || supabaseUrl.includes('your-project')) {
@@ -139,7 +139,7 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
   }
 
   const dbPassword = process.env.SUPABASE_DB_PASSWORD
-  if (!dbPassword) {
+  if (!dbPassword && !process.env.SUPABASE_DB_URL) {
     return null
   }
 
@@ -167,13 +167,17 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
   if (migrationFiles.length === 0) return { applied: 0, skipped: 0, failed: 0 }
 
   const { default: pg } = await import('pg')
-  const client = new pg.Client({
-    user: 'postgres',
-    password: dbPassword,
-    host: `db.${projectRef}.supabase.co`,
-    port: 5432,
-    database: 'postgres',
-  })
+  const client = new pg.Client(
+    process.env.SUPABASE_DB_URL
+      ? { connectionString: process.env.SUPABASE_DB_URL }
+      : {
+          user: 'postgres',
+          password: dbPassword,
+          host: `db.${projectRef}.supabase.co`,
+          port: 5432,
+          database: 'postgres',
+        }
+  )
   await client.connect()
 
   let applied = 0, skipped = 0, failed = 0
@@ -224,15 +228,14 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
 
   return { applied, skipped, failed }
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Applies pending SQL migration files to the Supabase database and tracks which have been applied.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:runMigrations:function"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:migrateCommand:function" type="function" identity="migrateCommand" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="CLI action that collects, optionally dry-runs, and applies framework migrations."]
 // CIL[DOC-RESPONSIBILITY responsibility="Validates environment, loads .env, handles dry run, and prints result."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -241,6 +244,7 @@ export async function runMigrations(opts: { frameworkOnly?: boolean } = {}): Pro
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:migrateCommand:function" type="function" identity="migrateCommand" parent="~/.framework/cli/commands/migrate.ts"]
 async function migrateCommand(options: MigrateOptions): Promise<void> {
   console.log('\nRunning Spine Framework migrations...\n')
 
@@ -265,13 +269,14 @@ async function migrateCommand(options: MigrateOptions): Promise<void> {
   }
 
   const dbPassword = options.dbPassword || process.env.SUPABASE_DB_PASSWORD
-  if (!dbPassword) {
+  if (!dbPassword && !process.env.SUPABASE_DB_URL) {
     console.error('❌ SUPABASE_DB_PASSWORD is not set.\n')
     if (!envExists) {
       console.error('  No .env file found. Run: npx spine-framework init')
     } else {
       console.error('  Edit .env and add: SUPABASE_DB_PASSWORD=your-db-password')
       console.error('  Or pass it directly: npx spine-framework migrate --db-password <password>')
+      console.error('  Or a full connection string (pooler/IPv4): SUPABASE_DB_URL=postgres://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com:5432/postgres')
     }
     console.error('\n  Get it from: https://supabase.com/dashboard/project/_/settings/database')
     process.exit(1)
@@ -313,12 +318,12 @@ async function migrateCommand(options: MigrateOptions): Promise<void> {
 
   console.log('\n✅ All migrations applied successfully!\n')
   console.log('Next steps:')
-  console.log('  npx spine-framework install-app <app-package>')
-  console.log('  npm install && npm run assemble && netlify dev\n')
+  console.log('  npm install && npm run dev:netlify')
+  console.log('  (optional) npx spine-framework install-app <app-package> — only for')
+  console.log('  additional app packs; core/admin apps are already seeded\n')
 }
 // CIL[END stable_id="~/.framework/cli/commands/migrate.ts:migrateCommand:function"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function" type="function" identity="registerMigrateCommands" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-VECTOR type="context" content="purpose='CLI action that collects, optionally dry-runs, and applies framework migrations.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
@@ -333,6 +338,7 @@ async function migrateCommand(options: MigrateOptions): Promise<void> {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function" type="function" identity="registerMigrateCommands" parent="~/.framework/cli/commands/migrate.ts"]
 export function registerMigrateCommands(program: Command) {
   program
     .command('migrate')
@@ -350,15 +356,14 @@ export function registerMigrateCommands(program: Command) {
       }
     })
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Registers the migrate command with the Commander program.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:registerMigrateCommands:function"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function" type="function" identity="loadEnv" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Loads key=value pairs from the project .env file into process.env."]
 // CIL[DOC-RESPONSIBILITY responsibility="Reads .env without overwriting existing environment variables."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -367,6 +372,7 @@ export function registerMigrateCommands(program: Command) {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function" type="function" identity="loadEnv" parent="~/.framework/cli/commands/migrate.ts"]
 function loadEnv() {
   const envPath = join(PROJECT_ROOT, '.env')
   if (!existsSync(envPath)) return
@@ -381,15 +387,14 @@ function loadEnv() {
     if (key && !(key in process.env)) process.env[key] = val
   }
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Loads key=value pairs from the project .env file into process.env.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:loadEnv:function"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function" type="function" identity="collectMigrations" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Collects SQL migration files from framework and custom directories."]
 // CIL[DOC-RESPONSIBILITY responsibility="Sorts and returns file paths for pending migrations, optionally including custom migrations."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -398,6 +403,7 @@ function loadEnv() {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function" type="function" identity="collectMigrations" parent="~/.framework/cli/commands/migrate.ts"]
 export function collectMigrations(frameworkOnly: boolean): { name: string; path: string }[] {
   const files: { name: string; path: string }[] = []
 
@@ -426,15 +432,14 @@ export function collectMigrations(frameworkOnly: boolean): { name: string; path:
 
   return files
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Collects SQL migration files from framework and custom directories.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:collectMigrations:function"]
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function" type="function" identity="splitSqlStatements" parent="~/.framework/cli/commands/migrate.ts"]
 // CIL[DOC-MACRO purpose="Splits SQL into executable statements while preserving dollar-quoted blocks."]
 // CIL[DOC-RESPONSIBILITY responsibility="Removes single-line comments, splits on semicolons, restores protected dollar-quoted blocks, and returns trimmed statements."]
 // CIL[DOC-CONTEXT module="cli" layer="framework" related_files=".framework/cli/commands/migrate.ts"]
@@ -443,6 +448,7 @@ export function collectMigrations(frameworkOnly: boolean): { name: string; path:
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="engineers"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function" type="function" identity="splitSqlStatements" parent="~/.framework/cli/commands/migrate.ts"]
 export function splitSqlStatements(sql: string): string[] {
   // Single-pass scanner: a ; only ends a statement in normal state. Comments
   // are dropped; string literals, quoted identifiers, and dollar-quoted blocks
@@ -497,10 +503,10 @@ export function splitSqlStatements(sql: string): string[] {
   if (tail) statements.push(tail + ';')
   return statements
 }
+// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Splits SQL into executable statements while preserving dollar-quoted blocks.'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/cli/commands/migrate.ts:splitSqlStatements:function"]