spine-framework 0.3.76 → 0.3.78

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

@@ -65,24 +65,33 @@ export function registerInstallAppCommands(program: Command) {
 
         // 4. Copy app files to custom/apps/<slug>/
         const appDest = join(PROJECT_ROOT, 'custom/apps', appSlug)
-        if (!existsSync(appDest)) {
+        const isReinstall = existsSync(appDest)
+        if (!isReinstall) {
           mkdirSync(appDest, { recursive: true })
         }
 
-        // Copy all allowed directories and files
+        // On reinstall, preserve the developer's local manifest.json — it is
+        // the source of truth for route_prefix and other project-level config.
+        // All other files are updated from npm as normal.
         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) {
           const src = join(pkgPath, entry)
-          if (existsSync(src)) {
-            console.log(`    Copying ${entry}`)
-            cpSync(src, join(appDest, entry), { recursive: true })
+          if (!existsSync(src)) continue
+
+          // Preserve local manifest on reinstall — developer owns it after first install
+          if (entry === 'manifest.json' && isReinstall) {
+            console.log(`    Preserving local manifest.json (use update-db-app to sync changes)`)
+            continue
           }
+
+          console.log(`    Copying ${entry}`)
+          cpSync(src, join(appDest, entry), { recursive: true })
         }
         console.log(`  ✓ App files copied to custom/apps/${appSlug}/`)
 
@@ -206,6 +215,80 @@ export function registerInstallAppCommands(program: Command) {
     })
 }
 
+  // update-db-app
+  program
+    .command('update-db-app <slug>')
+    .description('Sync local manifest.json changes to the database (no npm, no file changes)')
+    .action(async (slug: string) => {
+      console.log(`\nSyncing manifest to DB for: ${slug}\n`)
+      loadEnv()
+
+      const appDir = join(PROJECT_ROOT, 'custom/apps', slug)
+      const manifestPath = join(appDir, 'manifest.json')
+
+      if (!existsSync(manifestPath)) {
+        console.error(`❌ No app found at custom/apps/${slug}/manifest.json`)
+        console.error(`   Run install-app first: npx spine-framework install-app spine-framework-${slug}`)
+        process.exit(1)
+      }
+
+      const supabaseUrl = process.env.SUPABASE_URL
+      const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY
+
+      if (!supabaseUrl || !serviceRoleKey) {
+        console.error('❌ SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set')
+        process.exit(1)
+      }
+
+      let manifest: Record<string, any> = {}
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      } catch {
+        console.error(`❌ Could not parse manifest.json`)
+        process.exit(1)
+      }
+
+      const db = createClient(supabaseUrl, serviceRoleKey, { auth: { persistSession: false } })
+
+      const { data: appRow, error: appErr } = await db
+        .from('apps')
+        .upsert(
+          {
+            slug,
+            name: manifest.name ?? slug,
+            description: manifest.description ?? '',
+            version: manifest.version ?? '1.0.0',
+            nav_items: manifest.nav_items ?? [],
+            app_type: 'custom',
+            source: 'npm',
+            is_active: true,
+            route_prefix: manifest.route_prefix ?? ('/' + slug),
+            renderer: manifest.renderer ?? 'custom',
+            required_roles: manifest.required_roles ?? (manifest.min_role ? [manifest.min_role] : []),
+            min_role: manifest.required_roles?.[0] ?? manifest.min_role ?? null,
+          },
+          { onConflict: 'slug' }
+        )
+        .select('id')
+        .single()
+
+      if (appErr || !appRow?.id) {
+        console.error(`❌ Failed to update app row: ${appErr?.message ?? 'no id returned'}`)
+        process.exit(1)
+      }
+
+      console.log(`  ✓ apps row updated (route_prefix: ${manifest.route_prefix ?? '/' + slug})`)
+
+      // Update registration config in spine.config.json if declared
+      if (manifest.registration?.enabled) {
+        updateRegistrationConfig(slug, manifest.registration)
+      }
+
+      console.log(`\n✅ ${slug} DB synced from local manifest.\n`)
+      console.log(`Next: npm run assemble && netlify dev\n`)
+    })
+}
+
 // ─── HELPERS ────────────────────────────────────────────────────────────────
 
 function resolveAppSlug(pkgPath: string, pkgName: string): string {
@@ -286,48 +369,66 @@ async function seedApp(appDir: string, appSlug: string) {
   const appId = appRow.id
   console.log(`  ✓ App registered (id: ${appId})`)
 
-  // Seed types
-  const typesPath = join(appDir, 'seed/types.json')
-  if (existsSync(typesPath)) {
-    const types = JSON.parse(readFileSync(typesPath, 'utf8'))
-    console.log(`  Seeding ${types.length} type(s) for ${appSlug}...`)
-    for (const type of types) {
-      const { error } = await db
-        .from('types')
-        .upsert({ ...type, app_id: appId }, { onConflict: 'app_id,kind,slug' })
-      if (error) console.warn(`    ⚠ type ${type.slug}: ${error.message}`)
-    }
-    console.log(`  ✓ Types seeded`)
+  // ── Manifest-driven seed loop ─────────────────────────────────────────────
+  // If manifest declares a `seed` array, use it. Each entry:
+  //   { file, table, conflict, inject_app_id? }
+  // inject_app_id defaults to true — set false for tables with no app_id column.
+  //
+  // Fallback: if no manifest.seed, use legacy hardcoded behavior so existing
+  // apps without a seed block continue to work.
+  // ─────────────────────────────────────────────────────────────────────────
+
+  interface SeedEntry {
+    file: string
+    table: string
+    conflict: string
+    inject_app_id?: boolean
   }
 
-  // Seed roles
-  const rolesPath = join(appDir, 'seed/roles.json')
-  if (existsSync(rolesPath)) {
-    const roles = JSON.parse(readFileSync(rolesPath, 'utf8'))
-    console.log(`  Seeding ${roles.length} role(s) for ${appSlug}...`)
-    for (const role of roles) {
-      const { error } = await db
-        .from('roles')
-        .upsert({ ...role, app_id: appId }, { onConflict: 'app_id,slug' })
-      if (error) console.warn(`    ⚠ role ${role.slug}: ${error.message}`)
+  const seedEntries: SeedEntry[] = Array.isArray(manifest.seed)
+    ? manifest.seed
+    : [
+        // Legacy fallback — matches pre-019 behavior
+        { file: 'seed/roles.json',      table: 'roles',      conflict: 'app_id,slug' },
+        { file: 'seed/types.json',       table: 'types',      conflict: 'app_id,kind,slug' },
+        { file: 'seed/link-types.json',  table: 'link_types', conflict: 'app_id,slug' },
+      ]
+
+  for (const entry of seedEntries) {
+    const filePath = join(appDir, entry.file)
+    if (!existsSync(filePath)) {
+      console.log(`  ○ ${entry.file} not found, skipping`)
+      continue
+    }
+
+    let records: Record<string, any>[]
+    try {
+      records = JSON.parse(readFileSync(filePath, 'utf8'))
+    } catch {
+      console.warn(`  ⚠ Could not parse ${entry.file}, skipping`)
+      continue
     }
-    console.log(`  ✓ Roles seeded`)
-  }
 
-  // Seed link-types
-  const linkTypesPath = join(appDir, 'seed/link-types.json')
-  if (existsSync(linkTypesPath)) {
-    const linkTypes = JSON.parse(readFileSync(linkTypesPath, 'utf8'))
-    if (linkTypes.length > 0) {
-      console.log(`  Seeding ${linkTypes.length} link type(s) for ${appSlug}...`)
-      for (const lt of linkTypes) {
-        const { error } = await db
-          .from('link_types')
-          .upsert({ ...lt, app_id: appId }, { onConflict: 'app_id,slug' })
-        if (error) console.warn(`    ⚠ link_type ${lt.slug}: ${error.message}`)
+    if (!Array.isArray(records) || records.length === 0) {
+      console.log(`  ○ ${entry.file} is empty, skipping`)
+      continue
+    }
+
+    const injectAppId = entry.inject_app_id !== false // default true
+    console.log(`  Seeding ${records.length} record(s) from ${entry.file} → ${entry.table}...`)
+
+    for (const record of records) {
+      const row = injectAppId ? { ...record, app_id: appId } : { ...record }
+      const { error } = await db
+        .from(entry.table)
+        .upsert(row, { onConflict: entry.conflict })
+      if (error) {
+        const label = record.slug ?? record.name ?? JSON.stringify(record).slice(0, 40)
+        console.warn(`    ⚠ ${entry.table} "${label}": ${error.message}`)
       }
-      console.log(`  ✓ Link types seeded`)
     }
+
+    console.log(`  ✓ ${entry.table} seeded`)
   }
 }
 

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

@@ -8,11 +8,21 @@ import { fileURLToPath } from 'url'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
+interface SeedEntry {
+  file: string
+  table: string
+  conflict: string
+  inject_app_id?: boolean
+}
+
 interface Manifest {
   name: string
   slug: string
   version: string
   app_type: 'full' | 'ui' | 'backend' | 'data'
+  entry_point?: string
+  sidebar_component?: string
+  seed?: SeedEntry[]
   registration?: {
     enabled?: boolean
     default_role?: string
@@ -25,6 +35,7 @@ interface Manifest {
 interface PackageJson {
   name: string
   version: string
+  private?: boolean
   files?: string[]
   spine?: {
     type?: string
@@ -170,6 +181,107 @@ function validateDevinDirectory(appPath: string): void {
   }
 }
 
+function validateRoutes(appPath: string, manifest: Manifest): void {
+  if (!manifest.route_prefix) {
+    console.warn('⚠️  manifest.json is missing route_prefix — install-app will default to /{slug}')
+    return
+  }
+
+  const prefix = manifest.route_prefix === '/' ? null : manifest.route_prefix
+
+  if (!Array.isArray((manifest as any).routes)) return
+
+  for (const route of (manifest as any).routes as string[]) {
+    if (prefix && route.startsWith(prefix)) {
+      throw new ValidationError(
+        `❌ manifest.json route "${route}" must be root-relative (should not include route_prefix "${prefix}"). Use "${route.replace(prefix, '') || '/'}" instead.`
+      )
+    }
+    if (!route.startsWith('/')) {
+      throw new ValidationError(
+        `❌ manifest.json route "${route}" must start with /`
+      )
+    }
+  }
+
+  // nav_items paths must also be root-relative
+  if (Array.isArray((manifest as any).nav_items)) {
+    const checkNavItem = (item: any) => {
+      if (item.path && prefix && item.path.startsWith(prefix)) {
+        throw new ValidationError(
+          `❌ manifest.json nav_items path "${item.path}" must be root-relative (should not include route_prefix "${prefix}"). Use "${item.path.replace(prefix, '') || '/'}" instead.`
+        )
+      }
+      if (Array.isArray(item.children)) {
+        for (const child of item.children) checkNavItem(child)
+      }
+    }
+    for (const item of (manifest as any).nav_items) checkNavItem(item)
+  }
+}
+
+function validateManifestComponents(appPath: string, manifest: Manifest): void {
+  // entry_point — if declared, the file must exist
+  if (manifest.entry_point) {
+    const ep = manifest.entry_point.replace(/^\.\//, '')
+    if (!existsSync(join(appPath, ep))) {
+      throw new ValidationError(`❌ manifest.json entry_point "${manifest.entry_point}" does not exist`)
+    }
+  }
+
+  // sidebar_component — if declared, the file must exist
+  if (manifest.sidebar_component) {
+    const sc = manifest.sidebar_component.replace(/^\.\//, '')
+    if (!existsSync(join(appPath, sc))) {
+      throw new ValidationError(`❌ manifest.json sidebar_component "${manifest.sidebar_component}" does not exist`)
+    }
+  }
+
+  // registration — account_strategy "existing" requires target_account
+  if (manifest.registration?.account_strategy === 'existing' && !manifest.registration?.target_account) {
+    throw new ValidationError(`❌ manifest.json registration.account_strategy is "existing" but target_account is not set`)
+  }
+}
+
+function validateSeedBlock(appPath: string, manifest: Manifest): void {
+  if (!manifest.seed) return // optional — legacy apps without seed block are fine
+
+  if (!Array.isArray(manifest.seed)) {
+    throw new ValidationError('❌ manifest.json seed must be an array')
+  }
+
+  for (const entry of manifest.seed) {
+    if (!entry.file || !entry.table || !entry.conflict) {
+      throw new ValidationError(
+        `❌ manifest.json seed entry missing required field(s) (file, table, conflict): ${JSON.stringify(entry)}`
+      )
+    }
+    const filePath = join(appPath, entry.file)
+    if (!existsSync(filePath)) {
+      throw new ValidationError(`❌ manifest.json seed entry file "${entry.file}" does not exist`)
+    }
+    // Verify the file is valid JSON and an array
+    try {
+      const contents = JSON.parse(readFileSync(filePath, 'utf8'))
+      if (!Array.isArray(contents)) {
+        throw new ValidationError(`❌ Seed file "${entry.file}" must export a JSON array`)
+      }
+    } catch (err: any) {
+      if (err instanceof ValidationError) throw err
+      throw new ValidationError(`❌ Seed file "${entry.file}" is not valid JSON: ${err.message}`)
+    }
+  }
+}
+
+function validatePackagePublishability(packageJson: PackageJson): void {
+  if (packageJson.private === true) {
+    throw new ValidationError('❌ package.json has "private": true — app cannot be published to npm')
+  }
+  if (packageJson.private === undefined) {
+    console.warn('⚠️  package.json is missing "private": false — add it to confirm the package is publishable')
+  }
+}
+
 function validatePackageFiles(appPath: string, packageJson: PackageJson): void {
   const { files = [] } = packageJson
   
@@ -202,13 +314,25 @@ function validateApp(appPath: string): void {
     
     validateRequiredFiles(appPath, manifest)
     console.log(`✅ Required files present for app_type: ${manifest.app_type}`)
-    
+
+    validateRoutes(appPath, manifest)
+    console.log(`✅ manifest.json routes and nav_items are root-relative`)
+
+    validateManifestComponents(appPath, manifest)
+    console.log(`✅ manifest.json entry_point, sidebar_component, and registration valid`)
+
+    validateSeedBlock(appPath, manifest)
+    console.log(`✅ manifest.json seed block valid`)
+
     validateAllowedDirectories(appPath)
     console.log(`✅ No unknown directories found`)
-    
+
     validateDevinDirectory(appPath)
     console.log(`✅ .devin/ directory valid (if present)`)
-    
+
+    validatePackagePublishability(packageJson)
+    console.log(`✅ package.json publishability valid`)
+
     validatePackageFiles(appPath, packageJson)
     console.log(`✅ package.json files array checked`)
     

package/.framework/src/App.tsx

@@ -64,18 +64,23 @@ function AuthenticatedRouter() {
     )
   }
 
-  // Sort: explicit prefixes first, root (/) last
+  // Sort: longer explicit prefixes first (most specific), root (/) last so it
+  // doesn't swallow other routes. spine-framework reserved namespace excluded.
   const sorted = [...apps]
     .filter(app => app.slug !== 'spine-framework' && !app.route_prefix?.startsWith('/spine-framework'))
     .sort((a, b) => {
-      if (a.route_prefix === '/') return 1
+      if (a.route_prefix === '/') return 1   // root always last
       if (b.route_prefix === '/') return -1
       return (b.route_prefix?.length || 0) - (a.route_prefix?.length || 0)
     })
 
-  // Determine default redirect: first app with a route_prefix, or fall back to dashboard
+  // Determine default redirect:
+  //   - If an app owns root ('/'), redirect there directly
+  //   - Otherwise use the first non-root app's prefix
+  //   - Fall back to /dashboard if no apps installed
+  const rootApp = sorted.find(app => app.route_prefix === '/')
   const defaultApp = sorted.find(app => app.route_prefix && app.route_prefix !== '/')
-  const defaultRedirect = defaultApp?.route_prefix || '/dashboard'
+  const defaultRedirect = rootApp ? '/' : (defaultApp?.route_prefix || '/dashboard')
 
   return (
     <Suspense fallback={<div className="min-h-screen flex items-center justify-center"><LoadingSpinner /></div>}>

package/.framework/src/hooks/useAppPath.ts

@@ -0,0 +1,38 @@
+import { useCurrentApp } from '../contexts/AppContext'
+
+/**
+ * Returns a helper function that prepends the current app's route_prefix
+ * to a root-relative path.
+ *
+ * Use this instead of hardcoding absolute paths in app components so that
+ * changing `route_prefix` in manifest.json (and running update-db-app) is
+ * the only change needed to move an app to a new URL location.
+ *
+ * @example
+ * const appPath = useAppPath()
+ * appPath('/dashboard')      // → '/cortex/dashboard'  (if prefix is /cortex)
+ * appPath('/crm/accounts')   // → '/cortex/crm/accounts'
+ * appPath('/')               // → '/cortex'
+ *
+ * // With route_prefix = '/'
+ * appPath('/dashboard')      // → '/dashboard'
+ * appPath('/crm/accounts')   // → '/crm/accounts'
+ */
+export function useAppPath(): (path: string) => string {
+  const app = useCurrentApp()
+
+  // Normalize: '/' prefix means the app owns root — no prefix to prepend.
+  // Any other prefix is prepended as-is (trailing slash stripped).
+  const prefix =
+    !app.route_prefix || app.route_prefix === '/'
+      ? ''
+      : app.route_prefix.replace(/\/$/, '')
+
+  return (path: string): string => {
+    // path should be root-relative (start with /)
+    // If the caller passes '/' return just the prefix (or '/' if no prefix)
+    if (path === '/') return prefix || '/'
+    const normalized = path.startsWith('/') ? path : `/${path}`
+    return `${prefix}${normalized}`
+  }
+}

package/custom/.devin/AGENT.md

@@ -0,0 +1,357 @@
+# Spine Framework — Custom Apps Agent Guide
+
+This document explains the structure, contract, and tooling for apps under `custom/apps/`. Read this before touching any app code.
+
+---
+
+## Directory Layout
+
+Every app lives at `custom/apps/{slug}/` and must follow this structure:
+
+```
+custom/apps/{slug}/
+├── package.json          # npm identity + spine metadata block
+├── manifest.json         # runtime contract — the source of truth
+├── index.tsx             # default export: root React component
+├── components/           # app-level shared components (sidebar, cards, etc.)
+├── pages/                # route-mapped page components
+│   └── {section}/
+│       └── SomePage.tsx
+├── functions/            # Netlify function handlers scoped to this app
+├── hooks/                # React hooks
+├── utils/                # Pure utility functions
+├── public/               # Static assets copied to PROJECT_ROOT/public/ at assemble time
+└── seed/                 # Data seeded into the DB on install
+    ├── roles.json
+    ├── types.json
+    ├── link-types.json
+    └── (any other declared seed files)
+```
+
+No other top-level directories are allowed. `validate-app` will fail on unknown directories.
+
+---
+
+## package.json — Required Shape
+
+```json
+{
+  "name": "spine-framework-{slug}",
+  "version": "X.Y.Z",
+  "private": false,
+  "description": "...",
+  "peerDependencies": {
+    "spine-framework": ">=0.1.0"
+  },
+  "files": [
+    "index.tsx",
+    "manifest.json",
+    "seed/",
+    "pages/",
+    "components/",
+    "hooks/",
+    "utils/",
+    "functions/",
+    "public/",
+    "README.md"
+  ],
+  "scripts": {
+    "validate": "npx spine-framework validate-app ."
+  },
+  "spine": {
+    "type": "app",
+    "slug": "{slug}",
+    "manifestPath": "manifest.json"
+  }
+}
+```
+
+**Rules:**
+- `"private": false` is required — apps must be publishable to npm
+- `files` must include every directory that exists in the app
+- `version` must match `manifest.json` version exactly
+- `spine.slug` must match `manifest.json` slug exactly
+- Package name convention: `spine-framework-{slug}`
+
+---
+
+## manifest.json — Full Contract
+
+```json
+{
+  "name": "My App",
+  "slug": "my-app",
+  "description": "...",
+  "version": "X.Y.Z",
+  "app_type": "full",
+  "route_prefix": "/my-app",
+  "required_roles": ["role-slug"],
+  "routes": ["/", "/page"],
+  "nav_items": [
+    { "title": "Home", "path": "/", "icon": "Home", "order": 1 }
+  ],
+  "features": ["feature-a", "feature-b"],
+  "dependencies": ["items", "accounts"],
+  "entry_point": "./index.tsx",
+  "sidebar_component": "./components/MyAppSidebar.tsx",
+  "seed": [
+    { "file": "seed/roles.json",     "table": "roles",      "conflict": "app_id,slug" },
+    { "file": "seed/types.json",      "table": "types",      "conflict": "app_id,kind,slug" },
+    { "file": "seed/link-types.json", "table": "link_types", "conflict": "app_id,slug" }
+  ],
+  "registration": {
+    "enabled": true,
+    "default_role": "role-slug",
+    "redirect_path": "/my-app",
+    "account_strategy": "new"
+  }
+}
+```
+
+### Field Reference
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | yes | Display name — written to `apps.name` in DB |
+| `slug` | yes | Unique identifier — written to `apps.slug` |
+| `version` | yes | Must match `package.json` version |
+| `app_type` | yes | One of: `full`, `ui`, `backend`, `data` |
+| `route_prefix` | yes | Where the app is mounted (e.g. `/cortex`, `/`, `/workspace`). Single source of truth for routing. |
+| `required_roles` | yes | Array of role slugs required to access the app |
+| `routes` | recommended | Root-relative paths the app handles — **must NOT include route_prefix** |
+| `nav_items` | recommended | Root-relative sidebar nav paths — **must NOT include route_prefix** |
+| `entry_point` | yes (full/ui) | Path to root React component (relative to app root) |
+| `sidebar_component` | yes (full/ui) | Path to sidebar component — used by AppWrapper |
+| `seed` | yes | Declares all seed files (see below) |
+| `registration` | if app supports self-registration | Controls `spine.config.json` registration entry |
+
+### `app_type` values
+
+- `full` — has UI (pages, components) and backend (functions). Requires `index.tsx`, `pages/`, `functions/`
+- `ui` — frontend only. Requires `index.tsx`, `pages/`
+- `backend` — functions only. Requires `functions/`
+- `data` — schema/seed only. No UI or functions required
+
+---
+
+## Dynamic route_prefix
+
+`route_prefix` in `manifest.json` is the **single source of truth** for where an app is served. Changing it and running `update-db-app` is the only step needed to move an app to a different URL.
+
+### How it flows
+
+1. `manifest.json` declares `"route_prefix": "/cortex"` (or `/`, or anything)
+2. `install-app` / `update-db-app` writes it to `apps.route_prefix` in the DB
+3. `App.tsx` reads all app records and mounts each at `{route_prefix}/*`
+4. Inside the app, `useAppPath()` prepends the prefix to all links — no hardcoded paths
+
+### Rules for routes and nav_items
+
+Routes and nav_items must be **root-relative** — declared from the app's own root, not the full URL:
+
+```json
+// CORRECT
+"route_prefix": "/cortex",
+"routes": ["/", "/dashboard", "/crm/accounts"],
+"nav_items": [{ "title": "Dashboard", "path": "/dashboard" }]
+
+// WRONG — validate-app will reject these
+"routes": ["/cortex", "/cortex/dashboard", "/cortex/crm/accounts"],
+"nav_items": [{ "title": "Dashboard", "path": "/cortex/dashboard" }]
+```
+
+### useAppPath() hook
+
+All absolute links inside an app must use `useAppPath()` instead of hardcoded strings:
+
+```tsx
+import { useAppPath } from '@core/hooks/useAppPath'
+
+function MyComponent() {
+  const appPath = useAppPath()
+
+  return <a href={appPath('/dashboard')}>Dashboard</a>
+  // → '/cortex/dashboard' if route_prefix is /cortex
+  // → '/dashboard'        if route_prefix is /
+}
+```
+
+Use `useAppPath()` in: sidebar nav arrays, breadcrumbs, `navigate()` calls, any `<Link>` with an absolute path.
+
+### Changing an app's location
+
+```bash
+# 1. Edit manifest.json
+"route_prefix": "/"   # was "/cortex"
+
+# 2. Sync to DB (no npm, no file changes)
+npx spine-framework update-db-app cortex
+
+# 3. Rebuild and serve
+npm run assemble && netlify dev
+```
+
+That's the entire workflow. No code changes needed.
+
+---
+
+## Seed Block
+
+The `seed` array in `manifest.json` declares every file to be seeded into the DB at install time. `install-app` reads this array and runs a generic upsert loop — no hardcoded file names.
+
+### Seed entry format
+
+```json
+{ "file": "seed/roles.json", "table": "roles", "conflict": "app_id,slug" }
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `file` | yes | Path relative to app root |
+| `table` | yes | Supabase table name |
+| `conflict` | yes | Column(s) for `onConflict` upsert (comma-separated) |
+| `inject_app_id` | no | Default `true` — set `false` for tables without `app_id` |
+
+### Common conflict keys
+
+| Table | conflict |
+|-------|----------|
+| `roles` | `app_id,slug` |
+| `types` | `app_id,kind,slug` |
+| `link_types` | `app_id,slug` |
+| `triggers` | `app_id,name` |
+
+### Seed file format
+
+Every seed file must be a JSON array. Each object maps to one DB row. Do NOT include `id` or `app_id` — these are set by the framework at install time.
+
+```json
+[
+  {
+    "slug": "my-role",
+    "name": "My Role",
+    "description": "...",
+    "permissions": ["*"],
+    "is_system": true,
+    "is_active": true,
+    "is_protected": false
+  }
+]
+```
+
+All seed files must be idempotent — safe to run against an existing DB without creating duplicates.
+
+---
+
+## registration block
+
+Controls how users self-register for this app. Written to `spine.config.json` by `install-app`.
+
+```json
+"registration": {
+  "enabled": true,
+  "default_role": "member",
+  "redirect_path": "/portal",
+  "account_strategy": "new"
+}
+```
+
+| `account_strategy` | Behavior |
+|--------------------|----------|
+| `new` | Creates a new account per registering user (customer-facing apps) |
+| `existing` | Assigns user to an existing account — requires `target_account` |
+| `choice` | User chooses at registration |
+
+If `account_strategy` is `existing`, `target_account` (account slug) is required.
+
+---
+
+## CLI Commands
+
+```bash
+# Install an app from npm (first time)
+npx spine-framework install-app spine-framework-{slug}
+npx spine-framework install-app spine-framework-{slug}@next  # pre-release
+
+# Sync local manifest.json changes to the DB (no npm, no file changes)
+# Use this after changing route_prefix, nav_items, registration, etc.
+npx spine-framework update-db-app {slug}
+
+# Validate an app before publishing
+npx spine-framework validate-app custom/apps/{slug}
+# or from inside the app directory:
+npm run validate
+
+# Uninstall an app
+npx spine-framework uninstall-app spine-framework-{slug}
+
+# Update app code from npm (preserves local manifest.json)
+npx spine-framework update-app spine-framework-{slug}
+```
+
+**Key distinction:**
+- `install-app` = get/update code from npm. After first install, `manifest.json` is preserved — the developer owns it.
+- `update-db-app` = push local manifest changes to DB. No npm involved.
+
+`validate-app` checks:
+- `manifest.json` present, valid JSON, all required fields
+- `package.json` present, versions match, `"private": false`
+- Required files exist for `app_type`
+- `entry_point` and `sidebar_component` files exist (if declared)
+- `seed` block entries are valid and all declared files exist
+- `registration.account_strategy: "existing"` has `target_account`
+- No unknown directories
+- `.devin/` present → must contain `AGENTS.md` or `AGENT.md`
+- All directories in `files` array are present
+
+---
+
+## Assemble
+
+`assemble-frontend.sh` and `assemble-functions.sh` pick up app files at build time:
+
+- `functions/` → assembled into the Netlify functions directory
+- `public/` → copied to `PROJECT_ROOT/public/` (Vite's publicDir)
+- `pages/`, `components/`, `hooks/`, `utils/` → assembled into `.assembled/src/{slug}/`
+
+**Important:** `public/` assets must go to `PROJECT_ROOT/public/`, not `.assembled/src/public/`. This was a known bug fixed in `spine-framework@0.3.76`.
+
+---
+
+## Publishing
+
+Apps are published independently to npm, separate from `spine-framework`.
+
+```bash
+# From inside custom/apps/{slug}/
+npm version patch   # bump version (must match manifest.json!)
+# Also bump version in manifest.json to match
+npm publish --tag next --access public   # pre-release
+npm publish --tag latest --access public # stable release
+```
+
+Always publish with `--tag next` for development/testing. Promote to `--tag latest` only when stable and tested E2E in a dogfood project.
+
+Version must be kept in sync between `package.json` and `manifest.json` — `validate-app` will fail if they differ.
+
+---
+
+## Current Apps
+
+| Slug | Package | Description |
+|------|---------|-------------|
+| `cortex` | `spine-framework-cortex` | Internal workspace: CRM, Support, Community, KB |
+| `portal` | `spine-framework-portal` | Customer-facing: Tickets, KB, Courses, Community |
+
+---
+
+## Adding a New App
+
+1. Create `custom/apps/{slug}/` with the directory structure above
+2. Write `package.json` and `manifest.json` following the templates above
+3. Write `index.tsx` exporting the root React component
+4. Write `components/{Slug}Sidebar.tsx` and declare it as `sidebar_component`
+5. Write seed files and declare them in the `seed` block
+6. Run `npm run validate` — fix all errors before proceeding
+7. Publish with `--tag next`
+8. Test E2E: `npx spine-framework install-app spine-framework-{slug}@next`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.76",
+  "version": "0.3.78",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {