spine-framework 0.4.3 → 0.5.0-rc.4

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

@@ -1,42 +1,69 @@
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Module header for the admin API keys list page, importing dependencies and defining the page component scope."]
-// CIL[DOC-RESPONSIBILITY responsibility="Set up imports and module metadata for APIKeysPage."]
-// CIL[DOC-CONTEXT module="admin/api-keys" layer="page" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/PageInstructions.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Contains import statements for the page; no runtime logic." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="ai-coder"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/APIKeysPage.tsx"]
+/**
+ * @module   APIKeysPage
+ * @audience internal
+ * @layer    app-specific
+ * @stability stable
+ *
+ * This module represents the API Keys management page in the admin section of the application, allowing administrators to view, create, and manage API keys. INVARIANT: The user must have admin privileges to access this page.
+ * 
+ * It integrates with various UI components to provide a seamless user experience for key management.
+ *
+ * @seeAlso LoadingSpinner (provides loading feedback).
+ * @seeAlso Button (used for actions).
+ * @seeAlso AdminListPage (displays a list of API keys).
+ * @seeAlso useApi (custom hook for API interactions).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 
 
 import React, { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
 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[DOC-VECTOR type="context" content="purpose='Module header for the admin API keys list page, importing dependencies and defining the page component scope.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:module_header:module_header"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:apikey:interface" type="interface" identity="apikey" parent="none"]
-// CIL[DOC-MACRO purpose="Define the TypeScript shape of an API key record."]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide a typed interface for API key data."]
-// CIL[DOC-CONTEXT module="admin/api-keys" layer="page" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/PageInstructions.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/APIKeysPage.tsx"]
-// CIL[DOC-CONTRACT inputs="none" outputs="APIKey type definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Describes fields for an API key including id, name, key_type, is_active, usage, integration, and creator." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:APIKey:interface" type="interface" identity="APIKey" parent="~/.framework/src/pages/admin/APIKeysPage.tsx"]
+/**
+ * The APIKey interface defines the structure of an API key object used for managing access to services. It includes properties for identification, status, usage metrics, and associated integration details.
+ *
+ * @sideEffects none
+ * @stability   stable
+ * @cil-generated
+ */
 interface APIKey {
   id: string
   name: string
@@ -58,23 +85,39 @@ interface APIKey {
   }
   created_at: string
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Define the TypeScript shape of an API key record.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:apikey:interface"]
-
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:apikeyspage:function" type="function" identity="apikeyspage" parent="none"]
-// CIL[DOC-MACRO purpose="Render the admin API keys list page with search, filtering, sorting, and usage statistics."]
-// CIL[DOC-RESPONSIBILITY responsibility="Display and filter API keys; handle row navigation."]
-// CIL[DOC-CONTEXT module="admin/api-keys" layer="page" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/PageInstructions.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/APIKeysPage.tsx"]
-// CIL[DOC-CONTRACT inputs="none (React hook props and local state)" outputs="JSX page rendering" errors="Throws if API fetch fails (handled by useApi error state)" side_effects="Fetches /api/api-keys on mount; navigates on row click"]
-// CIL[DOC-MICRO logic_summary="Fetches API keys, applies search/status/type filters, sorts, and renders a SortableTableHeader table with stats cards and usage instructions." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+// CIL[END stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:APIKey:interface"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:APIKeysPage:component" type="component" identity="APIKeysPage" parent="~/.framework/src/pages/admin/APIKeysPage.tsx"]
+/**
+ * The APIKeysPage component manages the display and interaction with API keys, allowing users to filter, sort, and navigate to detailed views of individual keys. It fetches API keys from a server and provides statistics on their status and types.
+ *
+ * @macro       Component for managing and displaying API keys with filtering and sorting capabilities.
+ * @micro       Utilizes state management and hooks to handle API calls and dynamic updates based on user input.
+ * @outputSpec  JSX.Element
+ * @throws      Error — if the API fetch fails
+ * @sideEffects fetches data from external API endpoint '/api/api-keys?action=list'
+ * @stability   stable
+ * @calls       useApi, apiFetch, useNavigate
+ * @errorHandling throws an error if the API fetch fails
+ * @cil-generated
+ */
 export function APIKeysPage() {
+  const navigate = useNavigate()
   const [searchTerm, setSearchTerm] = useState('')
   const [selectedStatus, setSelectedStatus] = useState('all')
   const [selectedType, setSelectedType] = useState('all')
@@ -111,7 +154,7 @@ export function APIKeysPage() {
   }
 
   const handleRowClick = (key: APIKey) => {
-    window.location.href = `/spine-framework/admin/configs/api-keys/${key.id}`
+    navigate(`/spine-framework/admin/configs/api-keys/${key.id}`)
   }
 
   const sortedKeys = [...(filteredKeys || [])].sort((a, b) => {
@@ -198,7 +241,6 @@ 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}
@@ -211,47 +253,6 @@ 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" />
@@ -372,10 +373,10 @@ export function APIKeysPage() {
     </AdminListPage>
   )
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Render the admin API keys list page with search, filtering, sorting, and usage statistics.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:apikeyspage:function"]
+// CIL[END stable_id="~/.framework/src/pages/admin/APIKeysPage.tsx:APIKeysPage:component"]
+
+
+
+
+
+

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

@@ -1,4 +1,4 @@
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 // CIL[DOC-MACRO purpose="Top-level module for the admin threshold alerts configuration page"]
 // CIL[DOC-RESPONSIBILITY responsibility="Provide imports and module context for the AlertsConfigPage and AlertModal components"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="page" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
@@ -17,6 +17,7 @@
 
 import React, { useState } from 'react'
 import {
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:module_header:module_header"]
   Bell,
   Plus,
   Edit,
@@ -39,8 +40,6 @@ import { formatDateTime } from '../../lib/utils'
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:module_header:module_header"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:ThresholdAlert:interface"]
 // CIL[DOC-MACRO purpose="Describe the shape of a threshold alert record and its embedded data"]
 // CIL[DOC-RESPONSIBILITY responsibility="Define the ThresholdAlert TypeScript interface used across the alerts page"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="type" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -48,6 +47,7 @@ import { formatDateTime } from '../../lib/utils'
 // CIL[DOC-MICRO logic_summary="Declares fields for alert identity, title, status, metric, operator, threshold, window, optional pipeline linkage, and timestamps" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:ThresholdAlert:interface" type="interface" identity="ThresholdAlert" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 interface ThresholdAlert {
   id: string
   title: string
@@ -64,15 +64,14 @@ interface ThresholdAlert {
   created_at: string
   updated_at: string
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:ThresholdAlert:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Describe the shape of a threshold alert record and its embedded data'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/Modal.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:ThresholdAlert:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:Pipeline:interface"]
 // CIL[DOC-MACRO purpose="Describe a selectable pipeline reference"]
 // CIL[DOC-RESPONSIBILITY responsibility="Define the minimal Pipeline shape used for alert pipeline selection"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="type" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -80,20 +79,20 @@ interface ThresholdAlert {
 // CIL[DOC-MICRO logic_summary="Declares id and name fields for pipeline dropdown options" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:Pipeline:interface" type="interface" identity="Pipeline" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 interface Pipeline {
   id: string
   name: string
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:Pipeline:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Describe a selectable pipeline reference'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/Modal.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:Pipeline:interface"]
 
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:alert_constants:constants"]
 // CIL[DOC-MACRO purpose="Provide human-readable labels and units for alert metrics and operators"]
 // CIL[DOC-RESPONSIBILITY responsibility="Supply display maps for metric names, operators, and units used in the alert list and modal"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="presentation" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -101,30 +100,36 @@ interface Pipeline {
 // CIL[DOC-MICRO logic_summary="Defines METRIC_LABELS, OPERATOR_LABELS, and UNIT_LABELS records for rendering alert details" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:METRIC_LABELS:constant" type="constant" identity="METRIC_LABELS" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 const METRIC_LABELS: Record<string, string> = {
   error_rate: 'Error Rate',
   latency_p95: 'Latency (P95)',
   pipeline_failure_rate: 'Pipeline Failure Rate',
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:METRIC_LABELS:constant"]
 
 
 
 
 
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:OPERATOR_LABELS:constant" type="constant" identity="OPERATOR_LABELS" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 const OPERATOR_LABELS: Record<string, string> = {
   gt: '>',
   lt: '<',
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:OPERATOR_LABELS:constant"]
 
 
 
 
 
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:UNIT_LABELS:constant" type="constant" identity="UNIT_LABELS" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 const UNIT_LABELS: Record<string, string> = {
   error_rate: '%',
   latency_p95: 'ms',
   pipeline_failure_rate: '%',
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:UNIT_LABELS:constant"]
 
 
 
@@ -134,8 +139,6 @@ const UNIT_LABELS: Record<string, string> = {
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:alert_constants:constants"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertsConfigPage:component"]
 // CIL[DOC-MACRO purpose="Admin page for listing, creating, editing, toggling, and deleting threshold alerts"]
 // CIL[DOC-RESPONSIBILITY responsibility="Render the alert list, fetch alert and pipeline data, and handle alert CRUD interactions"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="page" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -143,10 +146,12 @@ const UNIT_LABELS: Record<string, string> = {
 // CIL[DOC-MICRO logic_summary="Loads alerts and pipelines with useApi, builds stat cards, renders AdminListPage, and provides handlers for save, delete, toggle, and edit actions" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertsConfigPage:component" type="component" identity="AlertsConfigPage" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 export function AlertsConfigPage() {
   const [isModalOpen, setIsModalOpen] = useState(false)
   const [editingAlert, setEditingAlert] = useState<ThresholdAlert | null>(null)
   const [isDeleting, setIsDeleting] = useState(false)
+  const [actionError, setActionError] = useState<string | null>(null)
 
   const { data: alerts, loading, error, refetch } = useApi<ThresholdAlert[]>(
     async () => {
@@ -205,7 +210,7 @@ export function AlertsConfigPage() {
       setEditingAlert(null)
       refetch()
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to save alert')
+      setActionError(err instanceof Error ? err.message : 'Failed to save alert')
     }
   }
 
@@ -219,7 +224,7 @@ export function AlertsConfigPage() {
       if (!response.ok) throw new Error('Failed to delete alert')
       refetch()
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to delete alert')
+      setActionError(err instanceof Error ? err.message : 'Failed to delete alert')
     }
   }
 
@@ -238,7 +243,7 @@ export function AlertsConfigPage() {
       if (!response.ok) throw new Error('Failed to toggle alert')
       refetch()
     } catch (err) {
-      window.alert(err instanceof Error ? err.message : 'Failed to toggle alert')
+      setActionError(err instanceof Error ? err.message : 'Failed to toggle alert')
     }
   }
 
@@ -308,6 +313,12 @@ export function AlertsConfigPage() {
       newButtonText="Create Alert"
       onNewClick={openCreateModal}
     >
+      {actionError && (
+        <div className="mx-6 mt-4 rounded-md bg-red-50 border border-red-200 px-4 py-3 text-sm text-red-700 flex justify-between items-center">
+          <span>{actionError}</span>
+          <button onClick={() => setActionError(null)} className="text-red-500 hover:text-red-700 font-medium">Dismiss</button>
+        </div>
+      )}
       {alerts && alerts.length === 0 ? (
         <div className="p-8 text-center">
           <Bell className="mx-auto h-12 w-12 text-muted-foreground" />
@@ -401,6 +412,7 @@ export function AlertsConfigPage() {
     </AdminListPage>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertsConfigPage:component"]
 
 
 // CIL[DOC-VECTOR type="context" content="purpose='Admin page for listing, creating, editing, toggling, and deleting threshold alerts'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/Modal.tsx"]
@@ -409,8 +421,6 @@ export function AlertsConfigPage() {
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertsConfigPage:component"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModalProps:interface"]
 // CIL[DOC-MACRO purpose="Props contract for the AlertModal form component"]
 // CIL[DOC-RESPONSIBILITY responsibility="Declare the properties passed to AlertModal"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="type" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -418,6 +428,7 @@ export function AlertsConfigPage() {
 // CIL[DOC-MICRO logic_summary="Defines isOpen, onClose, onSave, alert, and pipelines props for the alert edit/create modal" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModalProps:interface" type="interface" identity="AlertModalProps" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 interface AlertModalProps {
   isOpen: boolean
   onClose: () => void
@@ -425,15 +436,14 @@ interface AlertModalProps {
   alert: ThresholdAlert | null
   pipelines: Pipeline[]
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModalProps:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Props contract for the AlertModal form component'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/Modal.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModalProps:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModal:component"]
 // CIL[DOC-MACRO purpose="Modal form for creating and editing threshold alerts"]
 // CIL[DOC-RESPONSIBILITY responsibility="Render a controlled form, manage alert state, and call onSave with form data"]
 // CIL[DOC-CONTEXT module="admin/alerts" layer="component" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AlertsConfigPage.tsx"]
@@ -441,6 +451,7 @@ interface AlertModalProps {
 // CIL[DOC-MICRO logic_summary="Initializes form state, resets state when the alert or isOpen changes, and renders a form with metric, operator, threshold, window, optional pipeline, and active toggle fields" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModal:component" type="component" identity="AlertModal" parent="~/.framework/src/pages/admin/AlertsConfigPage.tsx"]
 function AlertModal({ isOpen, onClose, onSave, alert, pipelines }: AlertModalProps) {
   const [formData, setFormData] = useState({
     title: '',
@@ -624,10 +635,10 @@ function AlertModal({ isOpen, onClose, onSave, alert, pipelines }: AlertModalPro
     </Modal>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModal:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Modal form for creating and editing threshold alerts'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/Modal.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AlertsConfigPage.tsx:AlertModal:component"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]

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

@@ -1,4 +1,4 @@
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent=""]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/AppDetailPage.tsx"]
 // CIL[DOC-MACRO purpose="Top-level imports and module entry point for the AppDetailPage admin component."]
 // CIL[DOC-RESPONSIBILITY responsibility="Declare external dependencies for the App detail admin page."]
 // CIL[DOC-CONTEXT module="admin" layer="presentation" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/select.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
@@ -25,6 +25,7 @@ import { Card, CardContent, CardHeader, CardTitle } from '../../components/ui/ca
 import { Skeleton } from '../../components/ui/skeleton'
 import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert'
 import { 
+// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header"]
   Select,
   SelectContent,
   SelectItem,
@@ -33,16 +34,13 @@ import {
 } from '../../components/ui/select'
 import { ArrowLeft, Pencil, Trash2, AlertCircle } from 'lucide-react';
 import { formatDateTime } from '../../lib/utils'
-import { PageInstructions } from '../../components/admin/PageInstructions'
 // CIL[DOC-VECTOR type="context" content="purpose='Top-level imports and module entry point for the AppDetailPage admin component.'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/ui/button.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:App:interface" type="interface" identity="App" parent="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header"]
 // CIL[DOC-MACRO purpose="Define the App data contract used across the admin app detail page."]
 // CIL[DOC-RESPONSIBILITY responsibility="Provide a TypeScript type describing the shape of an app record."]
 // CIL[DOC-CONTEXT module="admin" layer="domain" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/select.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AppDetailPage.tsx"]
@@ -50,6 +48,7 @@ import { PageInstructions } from '../../components/admin/PageInstructions'
 // CIL[DOC-MICRO logic_summary="Declares the App interface with fields for metadata, configuration, and runtime settings." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:App:interface" type="interface" identity="App" parent="~/.framework/src/pages/admin/AppDetailPage.tsx"]
 interface App {
   id: string
   slug: string
@@ -78,15 +77,14 @@ interface App {
   created_by?: string
   account_id?: string
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:App:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Define the App data contract used across the admin app detail page.'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/ui/button.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:App:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:AppDetailPage:component" type="component" identity="AppDetailPage" parent="~/.framework/src/pages/admin/AppDetailPage.tsx:module_header:module_header"]
 // CIL[DOC-MACRO purpose="Render and manage the admin app create/edit/detail page."]
 // CIL[DOC-RESPONSIBILITY responsibility="Display app details, support editing and saving app configuration, and handle deletion."]
 // CIL[DOC-CONTEXT module="admin" layer="presentation" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/Modal.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/select.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/AppDetailPage.tsx"]
@@ -94,6 +92,7 @@ interface App {
 // CIL[DOC-MICRO logic_summary="Fetches app by id, manages edit state and JSON config, renders form fields, and persists changes via API." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:AppDetailPage:component" type="component" identity="AppDetailPage" parent="~/.framework/src/pages/admin/AppDetailPage.tsx"]
 export function AppDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -348,59 +347,6 @@ export function AppDetailPage() {
           )}
         </div>
       </div>
-
-      <PageInstructions
-        description="Configure an app, its metadata, and runtime settings."
-        sections={[
-          { title: 'What this app controls', content: 'An app is a registered application in Spine. It controls navigation visibility, which people can use it, and the JSON configuration that the app or its runtime types consume.' },
-          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
-            <li><strong>Name</strong> — string. The display name in the app switcher and registry.</li>
-            <li><strong>Slug</strong> — string. A unique URL-friendly identifier. Should be set at creation and rarely changed.</li>
-            <li><strong>Description</strong> — string. Optional short text shown in the app list.</li>
-            <li><strong>App Type</strong> — select. system, custom, or marketplace. Drives how the app is treated by the platform.</li>
-            <li><strong>Source</strong> — select. system, custom, or marketplace. Tracks where the app package came from.</li>
-            <li><strong>Min Role</strong> — select. member, admin, or owner. The lowest role that can see or access the app.</li>
-            <li><strong>Version</strong> — string. The current app version shown in the registry.</li>
-            <li><strong>Active</strong> — select true/false. Inactive apps are hidden and cannot be opened.</li>
-            <li><strong>System</strong> — select true/false. Marks apps that are part of the platform and should not be treated as tenant-managed.</li>
-            <li><strong>Icon</strong> — string. An icon name used by the UI. Invalid names show no icon.</li>
-            <li><strong>Color</strong> — select. The theme color for the app tile.</li>
-            <li><strong>Route Prefix</strong> — string. Optional URL prefix for the app (defaults to /slug).</li>
-            <li><strong>Renderer</strong> — select. generic, custom, or none. generic uses the design schema to render pages.</li>
-            <li><strong>Configuration (JSON)</strong> — JSON. Runtime configuration for the app or its generic renderer.</li>
-            <li><strong>Nav Items (JSON)</strong> — JSON. Array of navigation items for the app shell.</li>
-            <li><strong>Integration Deps (JSON)</strong> — JSON. Array of integration slugs the app depends on.</li>
-            <li><strong>Metadata (JSON)</strong> — JSON. Free-form metadata associated with the app.</li>
-          </ul> },
-          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
-            <li><strong>Type/Source</strong>: <em>system</em> for built-in apps, <em>custom</em> for account-built apps, <em>marketplace</em> for installed apps.</li>
-            <li><strong>Min Role</strong>: <em>member</em> is most permissive, <em>admin</em> for admins, <em>owner</em> for account owners.</li>
-            <li><strong>Active</strong>: choose Active to publish, Inactive to hide.</li>
-            <li><strong>System</strong>: choose System to protect the app from tenant deletion.</li>
-            <li><strong>Color</strong>: blue, green, red, yellow, purple, pink, indigo, gray, slate.</li>
-          </ul> },
-          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
-            <li>The app registry and shell navigation read these fields to decide which apps to show and who can open them.</li>
-            <li>Generic apps use the Configuration JSON and related types to render lists and detail pages.</li>
-            <li>Custom apps may read the slug and config to initialize routes. A missing slug or bad config can break the app.</li>
-          </ul> },
-          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
-            <li>In create mode, fill the App Information card and enter a unique slug, then choose Type, Source, and Min Role.</li>
-            <li>Edit the Configuration JSON with valid JSON; the form warns about invalid syntax on save.</li>
-            <li>Click Create to save, or Save Changes when editing. Use Delete to remove the app after a confirmation.</li>
-            <li>Validation checks required fields and that the Configuration JSON is parseable.</li>
-          </ol> },
-          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
-            <li>Reusing a slug that already exists, causing a unique constraint error.</li>
-
-
-            <li>Switching an app to Inactive while people are using it.</li>
-
-            <li>Pasting non-JSON text or trailing commas in the Configuration JSON.</li>
-          </ul> },
-        ]}
-      />
-
       <Card>
         <CardHeader>
           <CardTitle>App Information</CardTitle>
@@ -607,10 +553,10 @@ export function AppDetailPage() {
     </div>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:AppDetailPage:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Render and manage the admin app create/edit/detail page.'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/ui/button.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/AppDetailPage.tsx:AppDetailPage:component"]