spine-framework 0.5.0-rc.4 → 0.5.0-rc.6

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/validate-app.ts

@@ -20,6 +20,7 @@
 
 import { Command } from 'commander'
 import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from 'fs'
+import { createHash } from 'crypto'
 import { join, dirname, resolve, isAbsolute, sep } from 'path'
 import { fileURLToPath } from 'url'
 // CIL[DOC-VECTOR type="context" content="purpose='Provide module-level imports for the validate-app CLI command'; No verified external callers; imports: none"]
@@ -127,6 +128,14 @@ interface Manifest {
     parent_account?: string
     default_workspace_name?: boolean
   }
+  route_prefix?: string
+  preview_domain?: string
+  prod_domain?: string
+  preview_route_prefix?: string
+  prod_route_prefix?: string
+  agent?: {
+    skill_prefix?: string
+  }
 }
 // CIL[DOC-VECTOR type="context" content="purpose='Define the shape of an app manifest'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -337,7 +346,8 @@ function validateAllowedDirectories(appPath: string): void {
   const allowedDirs = [
     'pages', 'components', 'hooks', 'utils', 'functions',
     'seed', 'public', 'lib', 'views', 'docs', 'mcp',
-    'migrations', 'migrations-archive', 'tests'
+    'migrations', 'migrations-archive', 'tests', 'installer',
+    'agent', 'src'
   ]
   
   const entries = readdirSync(appPath, { withFileTypes: true })
@@ -414,6 +424,23 @@ function validateDevinDirectory(appPath: string): void {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stable]
 function validateRoutes(appPath: string, manifest: Manifest): void {
+  // Host-keyed mount overrides: an override prefix only makes sense with its
+  // domain trigger, and both must be root-relative.
+  const pairs: [keyof Manifest, keyof Manifest][] = [
+    ['prod_route_prefix', 'prod_domain'],
+    ['preview_route_prefix', 'preview_domain'],
+  ]
+  for (const [prefixKey, domainKey] of pairs) {
+    const prefix = manifest[prefixKey] as string | undefined
+    if (prefix === undefined) continue
+    if (typeof prefix !== 'string' || !prefix.startsWith('/')) {
+      throw new ValidationError(`❌ manifest.json ${prefixKey} "${prefix}" must start with /`)
+    }
+    if (!manifest[domainKey]) {
+      throw new ValidationError(`❌ manifest.json ${prefixKey} requires ${domainKey} — the override has no trigger host without it`)
+    }
+  }
+
   if (!manifest.route_prefix) {
     console.warn('⚠️  manifest.json is missing route_prefix — install-app will default to /{slug}')
     return
@@ -642,6 +669,7 @@ function validateOwnedTypes(appPath: string, manifest: Manifest): void {
 // 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/validate-app.ts:validateownedtypes:function"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateknowledgeenvelope:function" type="function" identity="validateKnowledgeEnvelope" parent="~/.framework/cli/commands/validate-app.ts"]
 // CIL[DOC-MACRO purpose="Validate the manifest knowledge envelope and seed prompt-config picks"]
 // CIL[DOC-RESPONSIBILITY responsibility="Check config.knowledge shape and verify seeded prompt_configs' retrieval_policy picks stay inside the envelope — an agent may narrow the app envelope but never widen it"]
 // CIL[DOC-CONTEXT module="validate-app" layer="cli" related_files=".framework/functions/_shared/kb.ts"]
@@ -740,6 +768,103 @@ function validateKnowledgeEnvelope(appPath: string, manifest: Manifest): void {
 }
 // CIL[END stable_id="~/.framework/cli/commands/validate-app.ts:validateknowledgeenvelope:function"]
 
+// CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateagentdirectory:function" type="function" identity="validateAgentDirectory" parent="~/.framework/cli/commands/validate-app.ts"]
+// CIL[DOC-AUDIENCE audience="CLI engineers and framework maintainers"]
+// CIL[DOC-MACRO purpose="Validate the app's staged agent/ directory (skills and instructions)"]
+// CIL[DOC-RESPONSIBILITY responsibility="Enforce skill prefix naming and SKILL.md name/dir equality, markdown-only instructions, and warn when staged assets drift from their live copies"]
+// CIL[DOC-CONTEXT module="validate-app" layer="cli" related_files=".framework/cli/commands/install-app.ts"]
+// CIL[DOC-CONTRACT inputs="appPath: string, manifest: Manifest" outputs="void" errors="ValidationError on missing skill_prefix, prefix mismatch, missing SKILL.md, or non-markdown instructions" side_effects="logs warnings to stdout on staged-vs-live drift"]
+// CIL[DOC-MICRO logic_summary="agent/skills requires manifest.agent.skill_prefix; every staged dir must start <prefix>_ and its SKILL.md name must equal the dir name; agent/instructions may only contain .md; sha1 snapshots of staged trees are compared to live custom/.devin/skills and src/instructions" notable_decisions="['drift_is_a_warning_not_an_error','skill_prefix_fail_closed']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function validateAgentDirectory(appPath: string, manifest: Manifest): void {
+  const agentPath = join(appPath, 'agent')
+  if (!existsSync(agentPath)) return
+
+  const skillsPath = join(agentPath, 'skills')
+  const instructionsPath = join(agentPath, 'instructions')
+
+  if (existsSync(skillsPath)) {
+    const prefix = manifest.agent?.skill_prefix
+    if (typeof prefix !== 'string' || !/^[a-z][a-z0-9]{0,7}$/.test(prefix)) {
+      throw new ValidationError(
+        `❌ agent/skills/ requires manifest.json agent.skill_prefix matching /^[a-z][a-z0-9]{0,7}$/`
+      )
+    }
+    for (const dir of readdirSync(skillsPath, { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue
+      if (!dir.name.startsWith(`${prefix}_`)) {
+        throw new ValidationError(
+          `❌ agent/skills/${dir.name} must start with the declared prefix "${prefix}_"`
+        )
+      }
+      const skillFile = join(skillsPath, dir.name, 'SKILL.md')
+      if (!existsSync(skillFile)) {
+        throw new ValidationError(`❌ 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 ValidationError(
+          `❌ agent/skills/${dir.name}/SKILL.md name must equal its directory name "${dir.name}"`
+        )
+      }
+    }
+  }
+
+  if (existsSync(instructionsPath)) {
+    const checkMarkdownOnly = (dirPath: string): void => {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        const full = join(dirPath, entry.name)
+        if (entry.isDirectory()) checkMarkdownOnly(full)
+        else if (!entry.name.endsWith('.md')) {
+          throw new ValidationError(
+            `❌ agent/instructions may only contain .md files — found ${entry.name}`
+          )
+        }
+      }
+    }
+    checkMarkdownOnly(instructionsPath)
+  }
+
+  // Staged copies should match their live counterparts — drift means one
+  // side was edited without re-staging (or the live install is stale).
+  const snapshot = (root: string): Map<string, string> => {
+    const out = new Map<string, string>()
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name)
+        if (entry.isDirectory()) walk(full)
+        else out.set(full.slice(root.length + 1), createHash('sha1').update(readFileSync(full)).digest('hex'))
+      }
+    }
+    if (existsSync(root)) walk(root)
+    return out
+  }
+  const sameTree = (a: Map<string, string>, b: Map<string, string>): boolean =>
+    a.size === b.size && [...a].every(([k, v]) => b.get(k) === v)
+
+  if (existsSync(skillsPath)) {
+    const liveSkillsRoot = join(appPath, '..', '..', '.devin', 'skills')
+    for (const dir of readdirSync(skillsPath, { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue
+      if (!sameTree(snapshot(join(skillsPath, dir.name)), snapshot(join(liveSkillsRoot, dir.name)))) {
+        console.warn(`⚠️  agent/skills/${dir.name} differs from live custom/.devin/skills/${dir.name} — re-stage or reinstall`)
+      }
+    }
+  }
+
+  if (existsSync(instructionsPath)) {
+    if (!sameTree(snapshot(instructionsPath), snapshot(join(appPath, 'src', 'instructions')))) {
+      console.warn(`⚠️  agent/instructions differs from src/instructions — re-stage before packaging`)
+    }
+  }
+
+  if (existsSync(skillsPath) || existsSync(instructionsPath)) {
+    console.log(`✅ agent/ staged assets valid`)
+  }
+}
+// CIL[END stable_id="~/.framework/cli/commands/validate-app.ts:validateagentdirectory:function"]
+
 // CIL[BEGIN stable_id="~/.framework/cli/commands/validate-app.ts:validateAppStructure:function" type="function" identity="validateAppStructure" parent="~/.framework/cli/commands/validate-app.ts"]
 // CIL[DOC-AUDIENCE audience="CLI engineers and framework maintainers"]
 // CIL[DOC-MACRO purpose="Run the full app structure validation pipeline"]
@@ -755,6 +880,7 @@ export function validateAppStructure(appPath: string): void {
   validateRequiredFiles(appPath, manifest)
   validateAllowedDirectories(appPath)
   validateDevinDirectory(appPath)
+  validateAgentDirectory(appPath, manifest)
   validateRoutes(appPath, manifest)
   validateManifestComponents(appPath, manifest)
   validateSeedBlock(appPath, manifest)

package/.framework/functions/_shared/app-manifest.ts

@@ -49,6 +49,8 @@ export interface AppManifest {
   auth_required?: boolean
   preview_domain?: string
   prod_domain?: string
+  preview_route_prefix?: string
+  prod_route_prefix?: string
 }
 // CIL[DOC-VECTOR type="context" content="purpose='Describes the runtime configuration shape of a Spine app manifest'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]

package/.framework/functions/_shared/permissions.ts

@@ -376,6 +376,8 @@ class _PermissionEngineInternal {
         required_roles: record.required_roles,
         preview_domain: record.preview_domain,
         prod_domain: record.prod_domain,
+        preview_route_prefix: record.preview_route_prefix,
+        prod_route_prefix: record.prod_route_prefix,
         is_active: record.is_active,
         is_system: record.is_system,
         renderer: record.renderer,
@@ -735,6 +737,8 @@ class _PermissionEngineInternal {
         required_roles: record.required_roles,
         preview_domain: record.preview_domain,
         prod_domain: record.prod_domain,
+        preview_route_prefix: record.preview_route_prefix,
+        prod_route_prefix: record.prod_route_prefix,
         is_active: record.is_active,
         is_system: record.is_system,
         renderer: record.renderer,

package/.framework/functions/admin-data.ts

@@ -106,6 +106,16 @@ const PERMISSIONS_ALL = {
 // CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:VALID_ENTITIES:constant" type="constant" identity="VALID_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'item_progress', 'logs', 'test_runs', 'observability', 'test_cases', 'types', 'link_types', 'ai_agents', 'prompt_configs']
 // CIL[END stable_id="~/.framework/functions/admin-data.ts:VALID_ENTITIES:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:ENTITIES_WITHOUT_IS_ACTIVE:constant" type="constant" identity="ENTITIES_WITHOUT_IS_ACTIVE" parent="none"]
+// CIL[DOC-MACRO purpose="Entities whose table has no is_active column — the default soft-delete filter must skip them"]
+// CIL[DOC-RESPONSIBILITY responsibility="List VALID_ENTITIES tables lacking is_active so the list handler only applies the default is_active filter where the column exists"]
+// CIL[DOC-CONTEXT module="admin-data" layer="functions" related_files=".framework/migrations/001_core_schema.sql"]
+// CIL[DOC-CONTRACT inputs="none" outputs="readonly Set<string> of entity names" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="links, attachments, watchers, logs, and observability have no is_active column; applying the default filter to them yields 42703 column-does-not-exist" notable_decisions="['explicit_is_active_param_still_errors_on_these_tables']"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+const ENTITIES_WITHOUT_IS_ACTIVE = new Set(['links', 'attachments', 'watchers', 'logs', 'observability'])
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:ENTITIES_WITHOUT_IS_ACTIVE:constant"]
 // CIL[DOC-MACRO purpose="VALID_ENTITIES constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the VALID_ENTITIES constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -295,8 +305,10 @@ export const list = createHandler(async (ctx, _body) => {
       })
 
       // Soft-deleted rows are hidden by default — pass is_active=false or
-      // include_inactive=true to see them.
-      if (filters.is_active === undefined && include_inactive !== 'true') {
+      // include_inactive=true to see them. Entities without an is_active
+      // column (links, attachments, watchers, logs, observability) skip the
+      // default filter — it would 500 with 42703 column-does-not-exist.
+      if (filters.is_active === undefined && include_inactive !== 'true' && !ENTITIES_WITHOUT_IS_ACTIVE.has(entity)) {
         query = query.eq('is_active', true)
       }
 

package/.framework/functions/apps.ts

@@ -93,12 +93,25 @@ export const list = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
-  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
-
   const userRoles = ctx.principal?.roles || []
   const isSysAdmin = userRoles.includes('system_admin')
+  const isSystem = isSysAdmin || (ctx.principal?.isInternal === true && !ctx.accountId)
+
+  // get_account_apps is service-role-only — the account boundary is enforced
+  // here. A scoped caller may only resolve apps inside its access set
+  // (own account plus descendants); the query param alone never widened that.
+  if (!isSystem && targetAccountId !== ctx.accountId) {
+    const { data: accessible, error: accessErr } = await adminDb
+      .rpc('get_accessible_accounts', { actor_id: ctx.principal?.id })
+    const ids = (accessible || []).map((r: any) => r.account_id ?? r)
+    if (accessErr || !ids.includes(targetAccountId)) {
+      const e: any = new Error('Account not accessible')
+      e.statusCode = 403
+      throw e
+    }
+  }
 
-  const { data, error: err } = await db
+  const { data, error: err } = await adminDb
     .rpc('get_account_apps', {
       account_id: targetAccountId,
       include_system: include_system !== 'false',
@@ -204,7 +217,7 @@ export const getSchema = createHandler(async (ctx, body) => {
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[BEGIN stable_id="~/.framework/functions/apps.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/apps.ts"]
 export const create = createHandler(async (ctx, body) => {
-  const { slug, name, description, icon, color, version, app_type, source, owner_account_id, config, nav_items, min_role, required_roles, integration_deps, metadata, route_prefix, renderer } = body
+  const { slug, name, description, icon, color, version, app_type, source, owner_account_id, config, nav_items, min_role, required_roles, integration_deps, metadata, route_prefix, renderer, preview_domain, prod_domain, preview_route_prefix, prod_route_prefix } = body
 
   if (!slug || !name) {
     throw new Error('slug and name are required')
@@ -259,6 +272,10 @@ export const create = createHandler(async (ctx, body) => {
       metadata: metadata || {},
       route_prefix: route_prefix !== undefined ? route_prefix : ('/' + slug),
       renderer: renderer || 'generic',
+      preview_domain: preview_domain ?? null,
+      prod_domain: prod_domain ?? null,
+      preview_route_prefix: preview_route_prefix ?? null,
+      prod_route_prefix: prod_route_prefix ?? null,
       is_active: true,
       is_system: false
     })

package/.framework/functions/embeddings.ts

@@ -1448,7 +1448,7 @@ export const cleanup = createHandler(async (ctx, body) => {
 // CIL[DOC-RESPONSIBILITY responsibility="Returns embeddings whose vectors are within a threshold of a query embedding."]
 // CIL[DOC-CONTEXT module="embeddings" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/embeddings.ts"]
 // CIL[DOC-CONTRACT inputs="ctx: RequestContext, body: { query_embedding, model_id?, limit?, threshold? }" outputs="{ results, count, model_id, threshold }" errors="throws if account or query_embedding missing, or RPC fails" side_effects="executes a database RPC"]
-// CIL[DOC-MICRO logic_summary="Validates account and query_embedding, calls the search_similar_embeddings RPC, and returns the results, count, model, and threshold." notable_decisions="none"]
+// CIL[DOC-MICRO logic_summary="Validates account and query_embedding, calls the match_embeddings RPC via adminDb, and returns the results, count, model, and threshold." notable_decisions="adminDb (service role) required — the RPC is service-role-only; scoping is enforced here via filter_account_ids"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="developers"]
@@ -1474,10 +1474,12 @@ export const searchSimilar = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
-  const { data, error: err } = await ctx.db.rpc('match_embeddings', {
+  // adminDb (service role): match_embeddings is revoked from anon/authenticated.
+  // Scoping is enforced here — non-system callers may not widen the corpus
+  // beyond their own account.
+  const { data, error: err } = await adminDb.rpc('match_embeddings', {
     query_embedding,
     match_count: parseInt(limit.toString()),
-    // Scoped callers may not widen the corpus beyond their own account.
     filter_account_ids: isSystem ? (filter_account_ids ?? null) : [ctx.accountId],
     filter_vector_type: filter_vector_type ?? null,
     similarity_threshold: parseFloat(threshold.toString()),

package/.framework/functions/observability.ts

@@ -468,7 +468,7 @@ export const cleanupOldLogs = createHandler(async (ctx, body) => {
     throw new Error('System admin required')
   }
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await adminDb
     .rpc('cleanup_old_logs', {
       p_retention_days: parseInt(days.toString()) || 30,
     })