spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/cli/commands/doctor.ts

@@ -11,9 +11,12 @@
 import type { Command } from 'commander'
 import { buildCliContext, handleError } from '../context.ts'
 import { adminDb } from '../../functions/_shared/index.ts'
-import { readFileSync, existsSync, readdirSync } from 'fs'
-import { resolve, dirname } from 'path'
+import { collectMigrations } from './migrate.ts'
+import { readFileSync, existsSync } from 'fs'
+import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { findAgentsBlock, agentsBlockVersion } from '../lib/project-files.ts'
+import { hashEntry } from '../../../scripts/checksum-manifest.mts'
 
 // CIL[DOC-VECTOR type="context" content="purpose='Provides CLI commands for the doctor (system health) functionality, integrating with CLI context and shared database functions.'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -131,7 +134,27 @@ async function checkEnvironment(): Promise<CheckResult> {
     }
   }
 
-  
+  const bad = required.filter(v => /your[-_]|placeholder|change-?me|^<[^>]*>|^xxx/i.test(process.env[v]!))
+  if (bad.length > 0) {
+    return {
+      name: 'environment',
+      status: 'fail',
+      message: `Placeholder values still set: ${bad.join(', ')} — replace with real Supabase credentials`,
+      details: { bad },
+      fixable: true
+    }
+  }
+
+  if (!/^https:\/\/[a-z0-9-]+\.supabase\.co/.test(process.env.SUPABASE_URL || '')) {
+    return {
+      name: 'environment',
+      status: 'fail',
+      message: 'SUPABASE_URL must look like https://<project-ref>.supabase.co',
+      details: {},
+      fixable: true
+    }
+  }
+
   const xenvPath = resolve(__dirname, '../../.xenv')
   const hasXenv = existsSync(xenvPath)
 
@@ -142,6 +165,7 @@ async function checkEnvironment(): Promise<CheckResult> {
     details: { has_xenv: hasXenv, vars_present: required.length }
   }
 }
+
 // CIL[DOC-VECTOR type="context" content="purpose='Validates required environment variables and optional .xenv file presence.'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
 // 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"]
@@ -202,15 +226,15 @@ async function checkDatabase(): Promise<CheckResult> {
 // CIL[DOC-MACRO purpose="Compares local migration files against applied database migrations."]
 // CIL[DOC-RESPONSIBILITY responsibility="Identify pending or missing database migrations."]
 // CIL[DOC-CONTEXT module="doctor" layer="app-specific" related_files=".framework/cli/commands/doctor.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="[]" outputs="Promise<CheckResult>" errors="[]" side_effects="Reads migration directory and queries schema_migrations."]
-// CIL[DOC-MICRO logic_summary="List local SQL files, query applied migration versions, and report any local files not yet applied." notable_decisions="Returns warn for pending migrations and fail when the directory or query errors."]
+// CIL[DOC-CONTRACT inputs="[]" outputs="Promise<CheckResult>" errors="[]" side_effects="Collects local migration files and queries _spine_migrations."]
+// CIL[DOC-MICRO logic_summary="List local SQL files via collectMigrations (framework + custom), query applied filenames from _spine_migrations, and report any local files not yet applied." notable_decisions="Returns warn for pending migrations — including when the tracking table does not exist yet — and fail only on unexpected query errors."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 
 async function checkMigrations(): Promise<CheckResult> {
-  const migrationsDir = resolve(__dirname, '../../migrations_dayzero')
+  const migrationFiles = collectMigrations(false)
 
-  if (!existsSync(migrationsDir)) {
+  if (migrationFiles.length === 0) {
     return {
       name: 'migrations',
       status: 'fail',
@@ -219,36 +243,37 @@ async function checkMigrations(): Promise<CheckResult> {
     }
   }
 
-  const localFiles = readdirSync(migrationsDir)
-    .filter(f => f.endsWith('.sql'))
-    .sort()
-
   try {
     const { data, error } = await adminDb
-      .schema('public' as any)
-      .from('schema_migrations' as any)
-      .select('version')
+      .from('_spine_migrations' as any)
+      .select('filename')
 
     if (error) {
-      return {
-        name: 'migrations',
-        status: 'fail',
-        message: `Cannot query applied migrations: ${error.message}`,
-        details: { error: error.message },
-        fixable: false
+      // A missing tracking table means `migrate` has never run on this
+      // database — every file is pending, which is a warn, not a query error.
+      const tableMissing = error.code === '42P01' ||
+        /does not exist|schema cache/i.test(error.message)
+      if (!tableMissing) {
+        return {
+          name: 'migrations',
+          status: 'fail',
+          message: `Cannot query applied migrations: ${error.message}`,
+          details: { error: error.message },
+          fixable: false
+        }
       }
     }
 
-    const applied = (data || []).map((r: any) => r.version)
+    const applied = (data || []).map((r: any) => r.filename)
     const appliedSet = new Set(applied)
-    const pending = localFiles.filter(f => !appliedSet.has(f.replace('.sql', '')))
+    const pending = migrationFiles.filter(f => !appliedSet.has(f.name))
 
     if (pending.length > 0) {
       return {
         name: 'migrations',
         status: 'warn',
-        message: `${pending.length} pending migrations: ${pending.join(', ')}`,
-        details: { pending: pending.map(f => f.replace('.sql', '')), applied: applied.length },
+        message: `${pending.length} pending migrations: ${pending.map(f => f.name).join(', ')}`,
+        details: { pending: pending.map(f => f.name.replace('.sql', '')), applied: applied.length },
         fixable: true
       }
     }
@@ -335,6 +360,83 @@ async function checkIntegrity(): Promise<CheckResult> {
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/cli/commands/doctor.ts:checkIntegrity:function"]
 
+/**
+ * Verify the agent assets init/upgrade install: AGENTS.md carries a
+ * spine-framework marker block whose version matches the manifest's
+ * framework_version, and every spine-* skill file listed under the
+ * manifest's `agent_files` map exists and hashes clean.
+ *
+ * All mismatches are WARNINGS, never failures — agent assets are
+ * refreshable state (`npx spine-framework upgrade` re-syncs them), and
+ * customer edits outside the markers / non-spine-* skills must never
+ * degrade health. Runs from process.cwd() (the project root).
+ */
+async function checkAgentFiles(): Promise<CheckResult> {
+  const root = process.cwd()
+  const manifestPath = join(root, '.spine-manifest.json')
+
+  let manifest: any = null
+  try {
+    if (existsSync(manifestPath)) manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch {
+    manifest = null
+  }
+  const agentFiles: Record<string, string> = manifest?.agent_files ?? {}
+  const expectedVersion: string | null = manifest?.framework_version ?? null
+  const problems: string[] = []
+
+  // AGENTS.md — marker block presence + version agreement.
+  const agentsPath = join(root, 'AGENTS.md')
+  if ('AGENTS.md' in agentFiles || existsSync(agentsPath)) {
+    if (!existsSync(agentsPath)) {
+      problems.push('AGENTS.md missing (manifest expects it)')
+    } else {
+      const text = readFileSync(agentsPath, 'utf8')
+      const range = findAgentsBlock(text.split(/\r?\n/))
+      if (!range) {
+        problems.push('AGENTS.md has no spine-framework marker block')
+      } else {
+        const blockVersion = agentsBlockVersion(text)
+        if (expectedVersion && blockVersion && blockVersion !== expectedVersion) {
+          problems.push(`AGENTS.md block is v${blockVersion}, project is v${expectedVersion}`)
+        }
+      }
+    }
+  }
+
+  // spine-* skills — existence + hash vs manifest agent_files entries.
+  for (const [rel, hash] of Object.entries(agentFiles)) {
+    if (rel === 'AGENTS.md') continue
+    const abs = join(root, rel)
+    if (!existsSync(abs)) { problems.push(`${rel} missing`); continue }
+    try {
+      if (hashEntry({ rel, abs, symlink: false }) !== hash) {
+        problems.push(`${rel} modified`)
+      }
+    } catch {
+      problems.push(`${rel} unreadable`)
+    }
+  }
+
+  if (problems.length) {
+    return {
+      name: 'agent_files',
+      status: 'warn',
+      message: `Agent asset drift: ${problems.join('; ')}`,
+      details: { problems },
+      fixable: true,
+    }
+  }
+  const count = Object.keys(agentFiles).length
+  return {
+    name: 'agent_files',
+    status: 'pass',
+    message: count
+      ? `Agent assets in sync (${count} manifest entries)`
+      : 'No agent assets tracked — this framework version predates agent_files',
+  }
+}
+
 // CIL[BEGIN stable_id="~/.framework/cli/commands/doctor.ts:checkTestRuns:function" type="function" identity="checkTestRuns" parent="~/.framework/cli/commands/doctor.ts"]
 // CIL[DOC-MACRO purpose="Fetches the latest test run from the database."]
 // CIL[DOC-RESPONSIBILITY responsibility="Report the status of the most recent test suite execution."]
@@ -351,7 +453,7 @@ async function checkTestRuns(): Promise<CheckResult> {
       .select('suite, status, started_at')
       .order('started_at', { ascending: false })
       .limit(1)
-      .single()
+      .maybeSingle()
 
     if (error) {
       return {
@@ -502,7 +604,7 @@ async function tryFix(check: CheckResult): Promise<string> {
       return 'Please set missing environment variables in .xenv or export them'
 
     case 'migrations':
-      return 'Run `npx spine migrations apply` or use Supabase CLI to apply pending migrations'
+      return 'Run `npx spine-framework migrate` to apply pending migrations'
 
     case 'integrity':
       return 'Run `npm run manifest` to regenerate the integrity manifest'
@@ -513,6 +615,9 @@ async function tryFix(check: CheckResult): Promise<string> {
     case 'runtime_wiring':
       return 'Fix the dangling trigger/pipeline references listed in details (re-install the owning app or correct the type_slug / pipeline reference)'
 
+    case 'agent_files':
+      return 'Run `npx spine-framework upgrade` to re-sync AGENTS.md and .devin/skills/spine-*'
+
     default:
       return 'No automatic fix available'
   }
@@ -613,6 +718,7 @@ export function registerDoctorCommands(program: Command) {
         }
 
         checks.push(await checkIntegrity())
+        checks.push(await checkAgentFiles())
 
         
         const failed = checks.filter(c => c.status === 'fail').length

package/.framework/cli/commands/generate.ts

@@ -1,322 +1,62 @@
 // CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/generate.ts"]
 // CIL[DOC-AUDIENCE audience="internal, cli-users"]
-// CIL[DOC-MACRO purpose="Provide CLI commands for generating database types, handler stubs, and UI page stubs"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies and expose module-level constants for the generate command"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="module-level imports and constants" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports Commander, CLI context helpers, adminDb, fs/path, url utilities and module constants" notable_decisions="ESM-compatible __filename and __dirname constants"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
-
+// CIL[DOC-MACRO purpose="Deprecated stub: the legacy 'generate' scaffold was removed; the command stays registered so callers get a clear migration message instead of writes to a dead v2-custom/ tree"]
+// CIL[DOC-RESPONSIBILITY responsibility="Register the 'generate' command and fail fast with guidance"]
+// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/create-app.ts,.framework/cli/commands/validate-schema.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="registered deprecated command" errors="always exits non-zero when invoked" side_effects="prints removal notice to stderr"]
+// CIL[DOC-MICRO logic_summary="Prints a removal notice pointing at create-app, the admin UI, and validate-schema, then exits with code 1" notable_decisions="Not aliased to create-app: generate created a type record + v2-custom stubs, create-app scaffolds custom/apps/<slug>/ — different semantics"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY deprecated]
 
 import type { Command } from 'commander'
-import { buildCliContext, handleError } from '../context.ts'
-import { adminDb } from '../../functions/_shared/index.ts'
-import { existsSync, mkdirSync, writeFileSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-
-// CIL[DOC-VECTOR type="context" content="purpose='Provide CLI commands for generating database types, handler stubs, and UI page stubs'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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/generate.ts:module_header:module_header"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:__filename:constant" type="constant" identity="__filename" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-MACRO purpose="Derive the current module's file path for ESM modules"]
-// CIL[DOC-RESPONSIBILITY responsibility="Hold the resolved __filename for path operations"]
-// CIL[DOC-STABILITY stability="internal"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="string __filename" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Calls fileURLToPath on import.meta.url" notable_decisions=""]
-const __filename = fileURLToPath(import.meta.url)
-// CIL[END stable_id="~/.framework/cli/commands/generate.ts:__filename:constant"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:__dirname:constant" type="constant" identity="__dirname" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-VECTOR type="context" content="purpose='Derive the current module's file path for ESM modules'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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[DOC-MACRO purpose="Derive the current module's directory name for relative path resolution"]
-// CIL[DOC-RESPONSIBILITY responsibility="Hold the resolved __dirname for directory operations"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-STABILITY stability="internal"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-CONTRACT inputs="none" outputs="string __dirname" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Applies dirname to the resolved __filename" notable_decisions=""]
-const __dirname = dirname(__filename)
-// CIL[END stable_id="~/.framework/cli/commands/generate.ts:__dirname:constant"]
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:PROJECT_ROOT:constant" type="constant" identity="PROJECT_ROOT" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-VECTOR type="context" content="purpose='Derive the current module's directory name for relative path resolution'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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[DOC-MACRO purpose="Resolve the absolute project root directory for file operations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Hold the resolved project root path for stub generation"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="string PROJECT_ROOT" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Resolves __dirname three levels up to reach project root" notable_decisions=""]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
-const PROJECT_ROOT = resolve(__dirname, '../../../')
-// CIL[DOC-VECTOR type="context" content="purpose='Resolve the absolute project root directory for file operations'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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/generate.ts:PROJECT_ROOT:constant"]
-
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:generateType:function" type="function" identity="generateType" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-MACRO purpose="Generate a new database type and create handler and UI page stubs"]
-// CIL[DOC-RESPONSIBILITY responsibility="Check for existing type, insert a new record, and write handler and page stub files"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="ctx: any, slug: string, options: any" outputs="Promise<void>" errors="Error on DB check/insert failure; skip if type exists" side_effects="Writes to the database and filesystem"]
-// CIL[DOC-MICRO logic_summary="Builds name/kind/description, checks for an existing type, inserts the design schema, and writes handler and page files unless present or force=true" notable_decisions="Defaults kind to 'item' and status options to open/in_progress/closed"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
-async function generateType(ctx: any, slug: string, options: any): Promise<void> {
-  const name = options.name || slug.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ')
-  const kind = options.kind || 'item'
-  const description = options.description || `${name} type generated by spine CLI`
-
-  console.log(`\n🔧 Generating type '${slug}'...`)
-
-  const { data: existing, error: checkErr } = await adminDb
-    .from('types')
-    .select('id')
-    .eq('slug', slug)
-    .eq('kind', kind)
-    .single()
-
-  if (checkErr && checkErr.code !== 'PGRST116') {
-    throw new Error(`Failed to check existing type: ${checkErr.message}`)
-  }
-
-  if (existing) {
-    console.log(`  ⚠️  Type '${slug}' already exists (skipping DB creation)`)
-  } else {
-    const designSchema = {
-      fields: {
-        title: {
-          type: 'string',
-          required: true,
-          label: 'Title',
-          description: `Title for this ${name}`
-        },
-        status: {
-          type: 'select',
-          options: ['open', 'in_progress', 'closed'],
-          default: 'open',
-          label: 'Status'
-        }
-      },
-      layout: {
-        detail: ['title', 'status'],
-        list: ['title', 'status']
-      }
-    }
-
-    const { error: insertErr } = await adminDb
-      .from('types')
-      .insert({
-        kind,
-        slug,
-        name,
-        description,
-        design_schema: designSchema,
-        validation_schema: {},
-        ownership: 'system',
-        is_active: true
-      })
-
-    if (insertErr) {
-      throw new Error(`Failed to create type: ${insertErr.message}`)
-    }
-
-    console.log('  ✓ Type record created')
-  }
-
-  const handlerPath = resolve(PROJECT_ROOT, `v2-custom/functions/${slug}.ts`)
-
-  if (existsSync(handlerPath) && !options.force) {
-    console.log(`  ⚠️  Handler stub already exists: ${handlerPath}`)
-  } else {
-    const handlerCode = generateHandlerStub(slug, kind, name)
-    writeFileSync(handlerPath, handlerCode)
-    console.log(`  ✓ Handler stub created: v2-custom/functions/${slug}.ts`)
-  }
 
-  const pageDir = resolve(PROJECT_ROOT, `v2-custom/src/pages/${slug}`)
-  const pagePath = resolve(pageDir, 'index.tsx')
-
-  if (existsSync(pagePath) && !options.force) {
-    console.log(`  ⚠️  UI page stub already exists: ${pagePath}`)
-  } else {
-    mkdirSync(pageDir, { recursive: true })
-    const pageCode = generatePageStub(slug, name, kind)
-    writeFileSync(pagePath, pageCode)
-    console.log(`  ✓ UI page stub created: v2-custom/src/pages/${slug}/index.tsx`)
-  }
-
-  console.log(`\n✅ Type '${slug}' generation complete!`)
-  console.log(`   Next steps:`)
-  console.log(`   1. Edit v2-custom/functions/${slug}.ts to implement custom logic`)
-  console.log(`   2. Edit v2-custom/src/pages/${slug}/index.tsx to customize the UI`)
-  console.log(`   3. Run 'spine dev' to see your changes`)
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Generate a new database type and create handler and UI page stubs'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-VECTOR type="context" content="purpose='Deprecated stub for the removed generate scaffold'; 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/generate.ts:generateType:function"]
-
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:generateHandlerStub:function" type="function" identity="generateHandlerStub" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-MACRO purpose="Generate a custom API handler stub string for a type"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a templated handler function using createHandler"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="slug: string, kind: string, name: string" outputs="string handler code" errors="Error for unsupported HTTP method at runtime" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Builds a handler template with a switch for GET/POST/PATCH/DELETE methods" notable_decisions="Uses new Date().toISOString() in the generated header comment"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY experimental]
-function generateHandlerStub(slug: string, kind: string, name: string): string {
-  return `/**
- * @module ${slug}
- * @audience custom
- * @layer api-handler
- * @stability experimental
- *
- * Custom handler for ${name} (${kind} type).
- * Generated by spine CLI on ${new Date().toISOString()}.
- *
- * Extend this handler to add custom logic for your type.
- */
-
-import { createHandler } from '../v2-core/functions/_shared/middleware'
-
-export const handler = createHandler(async (ctx) => {
-  const method = ctx.query?.method || 'GET'
-
-  switch (method) {
-    case 'GET':
-      return { message: '${name} handler - GET not implemented' }
-
-    case 'POST':
-      return { message: '${name} handler - POST not implemented' }
 
-    case 'PATCH':
-      return { message: '${name} handler - PATCH not implemented' }
-
-    case 'DELETE':
-      return { message: '${name} handler - DELETE not implemented' }
-
-    default:
-      throw new Error('Unsupported method: ' + method)
-  }
-})
-`
-}
-// CIL[DOC-VECTOR type="context" content="purpose='Generate a custom API handler stub string for a type'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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/generate.ts:generateHandlerStub:function"]
-
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:generatePageStub:function" type="function" identity="generatePageStub" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-MACRO purpose="Generate a React page stub string for a type"]
-// CIL[DOC-RESPONSIBILITY responsibility="Return a React component template that fetches and displays record data"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="slug: string, name: string, kind: string" outputs="string React component code" errors="Error on failed API fetch at runtime" side_effects="none (generated string only)"]
-// CIL[DOC-MICRO logic_summary="Builds a React page template using useParams, useApi, and apiFetch" notable_decisions="Uses new Date().toISOString() in the generated header comment"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY experimental]
-function generatePageStub(slug: string, name: string, kind: string): string {
-  return `/**
- * @page ${slug}/index
- * @audience custom
- * @layer page
- * @stability experimental
- *
- * UI page for ${name} (${kind} type).
- * Generated by spine CLI on ${new Date().toISOString()}.
- */
-
-import React from 'react'
-import { useParams } from 'react-router-dom'
-import { useApi } from '../../v2-core/src/hooks/useApi'
-import { apiFetch } from '../../v2-core/src/lib/api'
+// CIL[DOC-MACRO purpose="Register the deprecated 'generate' command so invocations fail with a clear removal notice"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wire the deprecated generate command into the program"]
+// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/create-app.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="always exits 1 on invocation" side_effects="Registers a command and prints guidance to stderr"]
+// CIL[DOC-MICRO logic_summary="Defines 'generate [slug]' whose action prints the removal notice and exits 1" notable_decisions="Exit 1 (non-zero) so scripts fail loudly rather than silently writing nothing"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY deprecated]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:registerGenerateCommands:function" type="function" identity="registerGenerateCommands" parent="~/.framework/cli/commands/generate.ts"]
+export function registerGenerateCommands(program: Command) {
+  program
+    .command('generate [slug]')
+    .description('Removed — legacy v2 scaffold no longer exists (prints migration guidance)')
+    .action(() => {
+      console.error(`
+❌ 'spine-framework generate' was removed.
 
-export default function ${name.replace(/\s+/g, '')}Page() {
-  const { id } = useParams()
+   The old scaffold wrote type/handler/page stubs into a 'v2-custom/' tree
+   and emitted a legacy design_schema shape — neither exists in this layout.
 
-  const { data, loading, error } = useApi(
-    () => apiFetch('/.netlify/functions/${slug}' + (id ? '?id=' + id : '')),
-    { immediate: true }
-  )
+   To get the same outcome today:
 
-  if (loading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
+   • New app:        spine-framework create-app <slug>
+                     (scaffolds custom/apps/<slug>/ + registers the app)
 
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold mb-4">${name}</h1>
-      <pre className="bg-gray-100 p-4 rounded">
-        {JSON.stringify(data, null, 2)}
-      </pre>
-      <p className="mt-4 text-gray-600">
-        Edit v2-custom/src/pages/${slug}/index.tsx to customize this page.
-      </p>
-    </div>
-  )
-}
-`
-}
-// CIL[END stable_id="~/.framework/cli/commands/generate.ts:generatePageStub:function"]
+   • New type:       author design_schema JSON, then either
+                     - create it in the admin UI (Spine Admin → Types), or
+                     - POST it to /api/types
+                     Validate first: spine-framework validate-schema <file.json>
 
-// CIL[BEGIN stable_id="~/.framework/cli/commands/generate.ts:registerGenerateCommands:function" type="function" identity="registerGenerateCommands" parent="~/.framework/cli/commands/generate.ts"]
-// CIL[DOC-VECTOR type="context" content="purpose='Generate a React page stub string for a type'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// 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[DOC-MACRO purpose="Register the generate CLI command with the Commander program"]
-// CIL[DOC-RESPONSIBILITY responsibility="Wire the generate command, options, and action into the program"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/generate" layer="app-specific" related_files=".framework/cli/commands/generate.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
-// CIL[DOC-CONTRACT inputs="program: Command" outputs="void" errors="none (handled by handleError)" side_effects="Adds command and action to the program"]
-// CIL[DOC-MICRO logic_summary="Attaches the 'generate <slug>' command with options and an async action that builds context and calls generateType" notable_decisions="Defaults kind to 'item' and passes parsed options to generateType"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stable]
-export function registerGenerateCommands(program: Command) {
-  program
-    .command('generate <slug>')
-    .description('Generate type, handler, and UI stubs')
-    .option('--name <name>', 'Human-readable name')
-    .option('--kind <kind>', 'Type kind', 'item')
-    .option('--description <description>', 'Type description')
-    .option('--force', 'Overwrite existing files', false)
-    .action(async (slug, opts) => {
-      try {
-        const ctx = await buildCliContext()
-        await generateType(ctx, slug, opts)
-      } catch (err: any) {
-        handleError(err)
-      }
+   • Custom logic:   put functions in custom/apps/<slug>/functions/ — they are
+                     picked up by 'npm run assemble' automatically.
+`)
+      process.exit(1)
     })
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Register the generate CLI command with the Commander program'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[END stable_id="~/.framework/cli/commands/generate.ts:registerGenerateCommands:function"]
+// CIL[DOC-VECTOR type="context" content="purpose='Register the deprecated generate command'; 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/generate.ts:registerGenerateCommands:function"]