spine-framework 0.3.125 → 0.3.127

package/.framework/src/pages/admin/AIAgentsPage.tsx

@@ -1,18 +1,21 @@
-/**
- * @module src/pages/admin/AIAgentsPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin list page for AI agents. Fetches all agents via
- * `/api/ai-agents?action=list`, applies client-side search, agent-type
- * filter (`chat` | `analysis` | `automation` | `custom`), and sort.
- * Renders inside `AdminListPage` with stat cards and a sortable table.
- * Row clicks navigate to `/spine-framework/admin/configs/ai-agents/:id`.
- *
- * @seeAlso src/pages/admin/AIAgentDetailPage.tsx
- */
 
+
+
+// CIL[BEGIN chunk_id="aiagentspage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for AIAgentsPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, UI components, and utilities"]
+// CIL[DOC-CONTEXT module="AIAgentsPage" layer="presentation" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React state management, routing, API hooks, UI components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { Cpu, CheckCircle, Clock } from 'lucide-react';
@@ -22,7 +25,21 @@ import { apiFetch } from '../../lib/api'
 import { AdminListPage } from '../../components/admin/AdminListPage'
 import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
 import { Badge } from '../../components/ui/badge'
-
+// CIL[END chunk_id="aiagentspage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="aiagentspage_interface_aiagent_1783668265" type="interface" identity="AIAgent" parent="none"]
+// CIL[DOC-MACRO purpose="Define AIAgent data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for AI agent objects"]
+// CIL[DOC-CONTEXT module="AIAgentsPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/layout/Sidebar.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AIAgent interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete AI agent structure with model config and metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/src/components/layout/Sidebar.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface AIAgent {
   id: string
   name: string
@@ -45,7 +62,21 @@ interface AIAgent {
   app_id?: string
   metadata?: Record<string, any>
 }
-
+// CIL[END chunk_id="aiagentspage_interface_aiagent_1783668265"]
+// CIL[BEGIN chunk_id="aiagentspage_function_aiagentspage_1783668265" type="function" identity="AIAgentsPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main AIAgentsPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render AI agent management interface with filtering, sorting, and stats"]
+// CIL[DOC-CONTEXT module="AIAgentsPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="API failures" side_effects="Navigation, API calls"]
+// CIL[DOC-MICRO logic_summary="Manages state, fetches AI agents, handles filtering/sorting, renders table" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, .framework/src/components/layout/Sidebar.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function AIAgentsPage() {
   const navigate = useNavigate()
   
@@ -56,7 +87,6 @@ export function AIAgentsPage() {
   const [sortKey, setSortKey] = useState('name')
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc')
 
-  // Fetch AI agents from API
   const { data: agents, loading } = useApi<AIAgent[]>(
     async (params) => {
       const response = await apiFetch('/api/ai-agents?action=list', { signal: params?.signal })
@@ -103,7 +133,6 @@ export function AIAgentsPage() {
   console.log('AIAgentsPage - agents:', agents)
   console.log('AIAgentsPage - filteredAgents:', filteredAgents)
 
-  // Helper functions
   const getAgentBadgeColor = (agentType: string) => {
     switch (agentType) {
       case 'chat':
@@ -136,7 +165,6 @@ export function AIAgentsPage() {
     navigate(`/spine-framework/admin/configs/ai-agents/${agent.id}`)
   }
 
-  // Sort agents
   const sortedAgents = [...(filteredAgents || [])].sort((a, b) => {
     let aValue: any = a[sortKey as keyof AIAgent]
     let bValue: any = b[sortKey as keyof AIAgent]
@@ -316,3 +344,4 @@ export function AIAgentsPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="aiagentspage_function_aiagentspage_1783668265"]

package/.framework/src/pages/admin/APIKeyDetailPage.tsx

@@ -1,6 +1,22 @@
-/**
- * @module src/pages/admin/APIKeyDetailPage
- */
+
+
+
+
+// CIL[BEGIN chunk_id="apikeydetailpage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for APIKeyDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, routing, and UI components"]
+// CIL[DOC-CONTEXT module="APIKeyDetailPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React state management, routing, UI components, and utilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { Button } from '../../components/ui/button'
@@ -16,31 +32,80 @@ import { ArrowLeft, Key, RefreshCw, Trash2, AlertCircle, Copy, Check } from 'luc
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="apikeydetailpage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="apikeydetailpage_interface_apikey_1783668265" type="interface" identity="APIKey" parent="none"]
+// CIL[DOC-MACRO purpose="Define APIKey data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for API key objects"]
+// CIL[DOC-CONTEXT module="APIKeyDetailPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="APIKey interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete API key structure with permissions and metadata" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface APIKey {
   id: string
   name: string
-  key_type: 'public' | 'private'
+  integration_id?: string
+  app_id?: string
+  key_type: 'inbound' | 'outbound' | 'internal' | 'cli'
   key_value?: string
   key_prefix: string
   is_active: boolean
   permissions?: Record<string, any>
+  scopes?: string[]
   rate_limit: number
   expires_at?: string
   last_used_at?: string
   usage_count: number
-  integration_id?: string
+  machine_type?: string
+  is_internal?: boolean
   metadata?: Record<string, any>
   created_by_person?: { id: string; full_name: string; email: string }
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="apikeydetailpage_interface_apikey_1783668265"]
+// CIL[BEGIN chunk_id="apikeydetailpage_constant_key_type_options_1783668265" type="constant" identity="KEY_TYPE_OPTIONS" parent="none"]
+// CIL[DOC-MACRO purpose="Define API key type options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure available key type choices"]
+// CIL[DOC-CONTEXT module="APIKeyDetailPage" layer="constants" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/migrations/025_retype_threads_messages.sql\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Key type options" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines private and public key type options with descriptions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: constants. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/migrations/025_retype_threads_messages.sql, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const KEY_TYPE_OPTIONS = [
-  { value: 'private', label: 'Private (Server-side)' },
-  { value: 'public', label: 'Public (Client-side)' }
+  { value: 'inbound', label: 'Inbound (External callers to Spine)' },
+  { value: 'outbound', label: 'Outbound (Spine to external services)' },
+  { value: 'internal', label: 'Internal (Spine-to-Spine)' },
+  { value: 'cli', label: 'CLI / Script' }
 ]
-
+// CIL[END chunk_id="apikeydetailpage_constant_key_type_options_1783668265"]
+// CIL[BEGIN chunk_id="apikeydetailpage_function_apikeydetailpage_1783668265" type="function" identity="APIKeyDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main APIKeyDetailPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render API key detail view with create/edit functionality"]
+// CIL[DOC-CONTEXT module="APIKeyDetailPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="API failures" side_effects="Navigation, API calls"]
+// CIL[DOC-MICRO logic_summary="Manages CRUD operations for API keys with form validation and key generation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function APIKeyDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -48,13 +113,17 @@ export function APIKeyDetailPage() {
 
   const [formData, setFormData] = useState({
     name: '',
-    key_type: 'private' as 'public' | 'private',
+    integration_id: '',
+    app_id: '',
+    key_type: 'inbound' as 'inbound' | 'outbound' | 'internal' | 'cli',
     key_prefix: 'sk_',
     rate_limit: 1000,
     expires_at: '',
-    integration_id: '',
     permissions: {},
+    scopes: '[]',
     metadata: {},
+    machine_type: 'integration',
+    is_internal: false,
     is_active: true
   })
   const [permissionsJson, setPermissionsJson] = useState('{}')
@@ -79,13 +148,17 @@ export function APIKeyDetailPage() {
     if (apiKey) {
       setFormData({
         name: apiKey.name || '',
-        key_type: apiKey.key_type || 'private',
+        integration_id: apiKey.integration_id || '',
+        app_id: apiKey.app_id || '',
+        key_type: apiKey.key_type || 'inbound',
         key_prefix: apiKey.key_prefix || 'sk_',
         rate_limit: apiKey.rate_limit || 1000,
         expires_at: apiKey.expires_at ? apiKey.expires_at.split('T')[0] : '',
-        integration_id: apiKey.integration_id || '',
         permissions: apiKey.permissions || {},
+        scopes: JSON.stringify(apiKey.scopes || [], null, 2),
         metadata: apiKey.metadata || {},
+        machine_type: apiKey.machine_type || 'integration',
+        is_internal: apiKey.is_internal || false,
         is_active: apiKey.is_active
       })
       setPermissionsJson(JSON.stringify(apiKey.permissions || {}, null, 2))
@@ -99,9 +172,12 @@ export function APIKeyDetailPage() {
     try {
       let permissions = {}
       let metadata = {}
+      let scopes: string[] = []
       try { permissions = JSON.parse(permissionsJson) } catch {}
       try { metadata = JSON.parse(metadataJson) } catch {}
-      const body = { ...formData, permissions, metadata }
+      try { scopes = JSON.parse(formData.scopes) } catch {}
+      const { key_prefix: _kp, ...rest } = formData
+      const body = { ...rest, permissions, scopes, metadata }
       const response = await apiFetch('/api/api-keys', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -144,6 +220,49 @@ export function APIKeyDetailPage() {
           <Button variant="ghost" onClick={() => navigate(-1)}><ArrowLeft className="h-5 w-5" /></Button>
           <h1 className="text-2xl font-bold">{apiKey.name}</h1>
         </div>
+        <PageInstructions
+        description="Create an API key and set its permissions, rate limits, and expiration."
+        sections={[
+          { title: 'What this API key controls', content: 'API keys authenticate callers to Spine. A key controls which callers are accepted, how fast they can call, and which permissions they carry.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string, required. A human-readable label. Missing name blocks creation.</li>
+            <li><strong>Integration ID</strong> — string. Optional UUID of the integration this key is for.</li>
+            <li><strong>App ID</strong> — string. Optional UUID of the owning app.</li>
+            <li><strong>Key Type</strong> — select. inbound, outbound, internal, or cli. Determines which direction the key is used and how it is validated.</li>
+            <li><strong>Prefix</strong> — string. The public prefix that appears before the generated secret. Default is "sk_". The create API may override this with the generated prefix.</li>
+            <li><strong>Rate Limit (requests/min)</strong> — number 1-10000. Enforces a cap on calls per minute. Missing or 0 may prevent usage.</li>
+            <li><strong>Expires At</strong> — date. Optional expiration. After this date the key is rejected.</li>
+            <li><strong>Machine Type</strong> — string. The machine principal type, e.g. integration.</li>
+            <li><strong>Internal</strong> — checkbox. Marks a key for internal service-to-service use.</li>
+            <li><strong>Active</strong> — checkbox. Inactive keys are rejected.</li>
+            <li><strong>Permissions (JSON)</strong> — JSON object. Defines allowed actions/resources. Invalid JSON fails creation.</li>
+            <li><strong>Scopes (JSON)</strong> — JSON array of scope strings. Invalid JSON fails creation.</li>
+            <li><strong>Metadata (JSON)</strong> — JSON object. Optional notes such as environment. Invalid JSON fails creation.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>inbound</strong>: External callers into Spine APIs.</li>
+            <li><strong>outbound</strong>: Spine calling external services.</li>
+            <li><strong>internal</strong>: Service-to-service calls within Spine.</li>
+            <li><strong>cli</strong>: Scripts or command-line tooling.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>API gateway validates the key on every call. An inactive, expired, or missing key is rejected.</li>
+            <li>Rate limits are enforced at the edge; a misconfigured limit may throttle or deny callers.</li>
+            <li>Permission JSON is parsed and used for authorization checks. Badly shaped permissions may grant too much or too little access.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>Only create mode is available; existing keys are shown read-only with the value masked.</li>
+            <li>Fill Name, Key Type, and Rate Limit. Provide valid JSON for Permissions and Metadata.</li>
+            <li>Submit the form. A one-time key is generated and shown; copy it immediately because it cannot be retrieved again.</li>
+            <li>Validation checks required fields, rate limit range, and valid JSON.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Forgetting to copy the generated key before leaving the page.</li>
+            <li>Entering Permissions as a comma-separated list instead of JSON.</li>
+            <li>Setting Rate Limit to 0, which blocks all requests.</li>
+          </ul> },
+        ]}
+      />
         <Card><CardContent className="p-6">
           <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
             <div className="flex justify-between"><span className="text-muted-foreground">Key Type</span><span>{apiKey.key_type}</span></div>
@@ -178,18 +297,68 @@ export function APIKeyDetailPage() {
         <Button variant="ghost" onClick={() => navigate(-1)}><ArrowLeft className="h-5 w-5" /></Button>
         <h1 className="text-2xl font-bold">Create API Key</h1>
       </div>
+      <PageInstructions
+        description="Create an API key and set its permissions, rate limits, and expiration."
+        sections={[
+          { title: 'What this API key controls', content: 'API keys authenticate callers to Spine. A key controls which callers are accepted, how fast they can call, and which permissions they carry.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string, required. A human-readable label. Missing name blocks creation.</li>
+            <li><strong>Integration ID</strong> — string. Optional UUID of the integration this key is for.</li>
+            <li><strong>App ID</strong> — string. Optional UUID of the owning app.</li>
+            <li><strong>Key Type</strong> — select. inbound, outbound, internal, or cli. Determines which direction the key is used and how it is validated.</li>
+            <li><strong>Prefix</strong> — string. The public prefix that appears before the generated secret. Default is "sk_". The create API may override this with the generated prefix.</li>
+            <li><strong>Rate Limit (requests/min)</strong> — number 1-10000. Enforces a cap on calls per minute. Missing or 0 may prevent usage.</li>
+            <li><strong>Expires At</strong> — date. Optional expiration. After this date the key is rejected.</li>
+            <li><strong>Machine Type</strong> — string. The machine principal type, e.g. integration.</li>
+            <li><strong>Internal</strong> — checkbox. Marks a key for internal service-to-service use.</li>
+            <li><strong>Active</strong> — checkbox. Inactive keys are rejected.</li>
+            <li><strong>Permissions (JSON)</strong> — JSON object. Defines allowed actions/resources. Invalid JSON fails creation.</li>
+            <li><strong>Scopes (JSON)</strong> — JSON array of scope strings. Invalid JSON fails creation.</li>
+            <li><strong>Metadata (JSON)</strong> — JSON object. Optional notes such as environment. Invalid JSON fails creation.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>inbound</strong>: External callers into Spine APIs.</li>
+            <li><strong>outbound</strong>: Spine calling external services.</li>
+            <li><strong>internal</strong>: Service-to-service calls within Spine.</li>
+            <li><strong>cli</strong>: Scripts or command-line tooling.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>API gateway validates the key on every call. An inactive, expired, or missing key is rejected.</li>
+            <li>Rate limits are enforced at the edge; a misconfigured limit may throttle or deny callers.</li>
+            <li>Permission JSON is parsed and used for authorization checks. Badly shaped permissions may grant too much or too little access.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>Only create mode is available; existing keys are shown read-only with the value masked.</li>
+            <li>Fill Name, Key Type, and Rate Limit. Provide valid JSON for Permissions and Metadata.</li>
+            <li>Submit the form. A one-time key is generated and shown; copy it immediately because it cannot be retrieved again.</li>
+            <li>Validation checks required fields, rate limit range, and valid JSON.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Forgetting to copy the generated key before leaving the page.</li>
+            <li>Entering Permissions as a comma-separated list instead of JSON.</li>
+            <li>Setting Rate Limit to 0, which blocks all requests.</li>
+          </ul> },
+        ]}
+      />
       {error && <Alert variant="destructive"><AlertCircle className="h-4 w-4" /><AlertTitle>Error</AlertTitle><AlertDescription>{error}</AlertDescription></Alert>}
       <form onSubmit={handleSubmit} className="space-y-6">
         <Card><CardContent className="p-6 space-y-4">
           <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
             <div className="space-y-2"><Label>Name *</Label><Input value={formData.name} onChange={e => setFormData({...formData, name: e.target.value})} required placeholder="e.g., Production API Key" /></div>
-            <div className="space-y-2"><Label>Key Type</Label><Select value={formData.key_type} onValueChange={v => setFormData({...formData, key_type: v as 'public' | 'private'})}><SelectTrigger><SelectValue /></SelectTrigger><SelectContent>{KEY_TYPE_OPTIONS.map(opt => <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>)}</SelectContent></Select></div>
+            <div className="space-y-2"><Label>Key Type</Label><Select value={formData.key_type} onValueChange={v => setFormData({...formData, key_type: v as 'inbound' | 'outbound' | 'internal' | 'cli'})}><SelectTrigger><SelectValue /></SelectTrigger><SelectContent>{KEY_TYPE_OPTIONS.map(opt => <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>)}</SelectContent></Select></div>
+            <div className="space-y-2"><Label>Integration ID</Label><Input value={formData.integration_id} onChange={e => setFormData({...formData, integration_id: e.target.value})} placeholder="Optional integration UUID" /></div>
+            <div className="space-y-2"><Label>App ID</Label><Input value={formData.app_id} onChange={e => setFormData({...formData, app_id: e.target.value})} placeholder="Optional app UUID" /></div>
             <div className="space-y-2"><Label>Prefix</Label><Input value={formData.key_prefix} onChange={e => setFormData({...formData, key_prefix: e.target.value})} placeholder="e.g., sk_" /></div>
             <div className="space-y-2"><Label>Rate Limit (requests/min)</Label><Input type="number" value={formData.rate_limit} onChange={e => setFormData({...formData, rate_limit: parseInt(e.target.value)})} min={1} max={10000} /></div>
             <div className="space-y-2"><Label>Expires At</Label><Input type="date" value={formData.expires_at} onChange={e => setFormData({...formData, expires_at: e.target.value})} /></div>
+            <div className="space-y-2"><Label>Machine Type</Label><Input value={formData.machine_type} onChange={e => setFormData({...formData, machine_type: e.target.value})} placeholder="e.g., integration" /></div>
+          </div>
+          <div className="flex flex-wrap items-center gap-6">
+            <div className="flex items-center gap-2"><Checkbox id="active" checked={formData.is_active} onCheckedChange={c => setFormData({...formData, is_active: c === true})} /><Label htmlFor="active">Active</Label></div>
+            <div className="flex items-center gap-2"><Checkbox id="is_internal" checked={formData.is_internal} onCheckedChange={c => setFormData({...formData, is_internal: c === true})} /><Label htmlFor="is_internal">Internal</Label></div>
           </div>
-          <div className="flex items-center gap-2"><Checkbox id="active" checked={formData.is_active} onCheckedChange={c => setFormData({...formData, is_active: c === true})} /><Label htmlFor="active">Active</Label></div>
           <div className="space-y-2"><Label>Permissions (JSON)</Label><Textarea value={permissionsJson} onChange={e => setPermissionsJson(e.target.value)} rows={4} className="font-mono text-sm" placeholder='{"resources": ["read", "write"]}' /></div>
+          <div className="space-y-2"><Label>Scopes (JSON array)</Label><Textarea value={formData.scopes} onChange={e => setFormData({...formData, scopes: e.target.value})} rows={3} className="font-mono text-sm" placeholder='["read:items"]' /></div>
           <div className="space-y-2"><Label>Metadata (JSON)</Label><Textarea value={metadataJson} onChange={e => setMetadataJson(e.target.value)} rows={3} className="font-mono text-sm" placeholder='{"env": "production"}' /></div>
         </CardContent></Card>
         <div className="flex justify-end gap-3"><Button type="button" variant="outline" onClick={() => navigate(-1)}>Cancel</Button><Button type="submit" disabled={isSubmitting}>{isSubmitting ? 'Creating...' : 'Create API Key'}</Button></div>
@@ -197,3 +366,4 @@ export function APIKeyDetailPage() {
     </div>
   )
 }
+// CIL[END chunk_id="apikeydetailpage_function_apikeydetailpage_1783668265"]

package/.framework/src/pages/admin/APIKeysPage.tsx

@@ -1,32 +1,51 @@
-/**
- * @module src/pages/admin/APIKeysPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin list page for API keys. Fetches all keys via
- * `/api/api-keys?action=list`, applies client-side search, type filter
- * (`public` | `private`), and sort. Key values are never shown in the
- * list — only the prefix. Renders inside `AdminListPage`. Row clicks
- * navigate to `/spine-framework/admin/configs/api-keys/:id`.
- *
- * @seeAlso src/pages/admin/APIKeyDetailPage.tsx
- */
 
+
+
+// CIL[BEGIN chunk_id="apikeyspage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for APIKeysPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, UI components, and utilities"]
+// CIL[DOC-CONTEXT module="APIKeysPage" layer="presentation" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React state management, UI components, API hooks" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React, { useState } from 'react'
 import { Plus, Key, CheckCircle, Clock, ShieldCheck, RefreshCw } from 'lucide-react';
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { Button } from '../../components/ui/button'
 import { AdminListPage } from '../../components/admin/AdminListPage'
 import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
+
+import { PageInstructions } from '../../components/admin/PageInstructions'
 import { formatDateTime } from '../../lib/utils'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
-
+// CIL[END chunk_id="apikeyspage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="apikeyspage_interface_apikey_1783668265" type="interface" identity="APIKey" parent="none"]
+// CIL[DOC-MACRO purpose="Define APIKey data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for API key objects"]
+// CIL[DOC-CONTEXT module="APIKeysPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/layout/Sidebar.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="APIKey interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete API key structure with metadata and usage" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/src/components/layout/Sidebar.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface APIKey {
   id: string
   name: string
-  key_type: 'public' | 'private'
+  key_type: 'inbound' | 'outbound'
   is_active: boolean
   last_used_at?: string
   expires_at?: string
@@ -44,7 +63,21 @@ interface APIKey {
   }
   created_at: string
 }
-
+// CIL[END chunk_id="apikeyspage_interface_apikey_1783668265"]
+// CIL[BEGIN chunk_id="apikeyspage_function_apikeyspage_1783668265" type="function" identity="APIKeysPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main APIKeysPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render API key management interface with filtering, sorting, and stats"]
+// CIL[DOC-CONTEXT module="APIKeysPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="API failures" side_effects="Navigation, API calls"]
+// CIL[DOC-MICRO logic_summary="Manages state, fetches API keys, handles filtering/sorting, renders table" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, .framework/src/components/layout/Sidebar.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function APIKeysPage() {
   const [searchTerm, setSearchTerm] = useState('')
   const [selectedStatus, setSelectedStatus] = useState('all')
@@ -121,8 +154,8 @@ export function APIKeysPage() {
       iconColor: 'text-green-500'
     },
     {
-      title: 'Private Keys',
-      value: (apiKeys || []).filter(k => k.key_type === 'private').length,
+      title: 'Inbound Keys',
+      value: (apiKeys || []).filter(k => k.key_type === 'inbound').length,
       icon: ShieldCheck,
       iconColor: 'text-purple-500'
     },
@@ -146,8 +179,8 @@ export function APIKeysPage() {
 
   const typeOptions = [
     { value: 'all', label: 'All Types' },
-    { value: 'public', label: 'Public' },
-    { value: 'private', label: 'Private' }
+    { value: 'inbound', label: 'Inbound' },
+    { value: 'outbound', label: 'Outbound' }
   ]
 
   const filters = [
@@ -169,6 +202,7 @@ export function APIKeysPage() {
     <AdminListPage
       title="API Keys"
       description="Manage API keys and access tokens"
+      noPageInstructions
       newButtonText="Generate API Key"
       newButtonHref="/spine-framework/admin/configs/api-keys/new"
       statsCards={statsCards}
@@ -181,6 +215,47 @@ export function APIKeysPage() {
       emptyMessage="No API keys found"
       emptyIcon={Key}
     >
+      <PageInstructions
+        title="API key usage instructions"
+        description="API keys are generated tokens that authenticate external callers or service-to-service calls. The full key is shown once after creation. Copy it immediately and store it securely."
+        sections={[
+          { title: '1. Inbound webhooks (authenticate callers to Spine)', content: (
+            <div className="space-y-2">
+              <p className="text-sm text-slate-600">
+                Create an <code className="text-xs bg-muted px-1 rounded">inbound</code> key, optionally bound to an Integration. Send the key in the request header to <code className="text-xs bg-muted px-1 rounded">/api/integration-routes</code>:
+              </p>
+              <pre className="text-xs bg-muted p-2 rounded overflow-auto font-mono">{`X-Api-Key: sk_...`}</pre>
+              <p className="text-sm text-slate-600">
+                The Integration Broker will validate the key and route the event to the adapter defined by the integration.
+              </p>
+            </div>
+          )},
+          { title: '2. Outbound / service calls (use a key instead of an env var)', content: (
+            <div className="space-y-2">
+              <p className="text-sm text-slate-600">
+                You can use a literal key value in an integration's <code className="text-xs bg-muted px-1 rounded">credentials</code> instead of <code className="text-xs bg-muted px-1 rounded">env_var</code>. Create a key, copy the value, and paste it into the integration's credentials JSON with <code className="text-xs bg-muted px-1 rounded">source: "value"</code>:
+              </p>
+              <pre className="text-xs bg-muted p-2 rounded overflow-auto font-mono">{JSON.stringify({ api_token: { source: 'value', value: 'sk_...' } }, null, 2)}</pre>
+            </div>
+          )},
+          { title: '3. Key types', content: (
+            <div className="space-y-2">
+              <ul className="text-sm text-slate-600 list-disc list-inside space-y-1">
+                <li><strong>inbound</strong> — external services calling Spine (webhooks, API clients).</li>
+                <li><strong>outbound</strong> — Spine services calling another system, often linked to an integration.</li>
+                <li><strong>internal</strong> — internal Spine function-to-function calls.</li>
+                <li><strong>cli</strong> — command-line scripts and tooling.</li>
+              </ul>
+            </div>
+          )},
+          { title: '4. Rate limits, scopes, and expiration', content: (
+            <p className="text-sm text-slate-600">
+              Use <code className="text-xs bg-muted px-1 rounded">rate_limit</code> to throttle usage, set <code className="text-xs bg-muted px-1 rounded">expires_at</code> for short-lived keys, and define <code className="text-xs bg-muted px-1 rounded">permissions</code> / <code className="text-xs bg-muted px-1 rounded">scopes</code> as JSON arrays to restrict what the key can do.
+            </p>
+          )},
+        ]}
+      />
+
       {sortedKeys.length === 0 ? (
         <div className="p-8 text-center">
           <Key className="mx-auto h-12 w-12 text-slate-400" />
@@ -259,7 +334,7 @@ export function APIKeysPage() {
                 </td>
                 <td className="px-6 py-4 whitespace-nowrap">
                   <span className={`inline-flex px-2 py-0.5 text-xs font-medium rounded-md ${
-                    key.key_type === 'private'
+                    key.key_type === 'inbound'
                       ? 'bg-purple-100 text-purple-700'
                       : 'bg-blue-100 text-blue-700'
                   }`}>
@@ -301,3 +376,4 @@ export function APIKeysPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="apikeyspage_function_apikeyspage_1783668265"]