spine-framework 0.4.3 → 0.4.4

package/.framework/migrations/068_cron_schedule_timer_rpcs.sql

@@ -0,0 +1,251 @@
+-- Migration 068: bootstrap the RPCs system-cron expects
+--
+-- system-cron calls nine Postgres functions that were documented as
+-- "bootstrapped by framework migrations" but never created — every tick
+-- hard-failed on get_due_schedules with
+--   "Could not find the function public.get_due_schedules(p_now) in the
+--    schema cache"
+-- This migration creates the missing RPCs against the existing
+-- schedules / timers / schedule_executions / pipeline_executions / logs
+-- tables.
+--
+-- Honest limits (the tables are half-designed — schedules has no
+-- config/delegated_scopes columns and there is no cron-expression
+-- evaluator in the DB):
+--   * get_due_schedules returns delegated_scopes=NULL and config='{}'
+--     (the cron handler already tolerates both).
+--   * update_schedule_after_run reschedules only the every-N-minutes
+--     cron form ('*/N * * * *'); anything else gets next_run_at=NULL so
+--     a schedule can never re-fire every tick forever.
+--   * update_timer_after_run reschedules when
+--     config->>'interval_minutes' is a positive number, else NULL.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql:module:migration" type="migration" identity="cron-schedule-timer-rpcs" parent="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql"]
+-- CIL[DOC-MACRO purpose="Create the nine Postgres RPCs system-cron invokes for schedules, timers, threshold metrics and log cleanup"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Provide get_due_schedules, validate_schedule_creator, update_schedule_after_run, get_due_timers, update_timer_after_run, get_error_rate, get_latency_percentiles, get_pipeline_stats, cleanup_old_logs"]
+-- CIL[DOC-CONTEXT module="system-cron" layer="schema" related_files=".framework/functions/system-cron.ts"]
+-- CIL[DOC-CONTRACT inputs="timestamptz/uuid/bool/int params per function" outputs="setof rows or scalars matching the shapes system-cron reads" errors="none — SECURITY DEFINER, stable where read-only" side_effects="update_schedule_after_run/update_timer_after_run mutate schedule/timer rows; cleanup_old_logs deletes old logs"]
+-- CIL[DOC-MICRO logic_summary="Simple SELECT/UPDATE/DELETE implementations; cron reschedule limited to '*/N * * * *', timers honor config->>'interval_minutes', everything else next_*=NULL to prevent infinite re-fire" notable_decisions="No speculative cron parser — a NULL next_run_at is a safe one-shot stop until the feature gets a real scheduler model"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="system-admin"]
+-- CIL[END stable_id="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql:module:migration"]
+
+-- ── schedules ─────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_due_schedules(p_now timestamptz)
+RETURNS TABLE (
+  schedule_id uuid,
+  action_id uuid,
+  account_id uuid,
+  machine_principal_id uuid,
+  delegated_scopes jsonb,
+  config jsonb
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    s.id,
+    s.action_id,
+    s.account_id,
+    s.machine_principal_id,
+    NULL::jsonb,
+    '{}'::jsonb
+  FROM public.schedules s
+  WHERE s.is_active
+    AND s.next_run_at IS NOT NULL
+    AND s.next_run_at <= p_now
+$$;
+
+CREATE OR REPLACE FUNCTION public.validate_schedule_creator(p_schedule_id uuid)
+RETURNS TABLE (is_valid boolean, error_message text)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    EXISTS (
+      SELECT 1 FROM public.schedules s
+      WHERE s.id = p_schedule_id AND s.is_active
+    ),
+    CASE
+      WHEN NOT EXISTS (SELECT 1 FROM public.schedules s WHERE s.id = p_schedule_id)
+        THEN 'schedule not found'
+      WHEN NOT EXISTS (SELECT 1 FROM public.schedules s WHERE s.id = p_schedule_id AND s.is_active)
+        THEN 'schedule is not active'
+      ELSE NULL
+    END
+$$;
+
+CREATE OR REPLACE FUNCTION public.update_schedule_after_run(
+  p_schedule_id uuid,
+  p_success boolean,
+  p_error_message text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_cron text;
+  v_minutes integer;
+BEGIN
+  SELECT cron_expression INTO v_cron FROM public.schedules WHERE id = p_schedule_id;
+
+  -- Only the every-N-minutes form is reschedulable here; a full cron
+  -- evaluator does not exist in the DB. Anything else becomes a
+  -- one-shot (NULL next_run_at) rather than re-firing every tick.
+  v_minutes := NULL;
+  IF v_cron ~ '^\*/(\d+) \* \* \* \*$' THEN
+    v_minutes := substring(v_cron FROM '^\*/(\d+)')::integer;
+  END IF;
+
+  UPDATE public.schedules
+  SET
+    last_run_at = now(),
+    next_run_at = CASE
+      WHEN v_minutes IS NOT NULL THEN now() + make_interval(mins => v_minutes)
+      ELSE NULL
+    END,
+    updated_at = now()
+  WHERE id = p_schedule_id;
+END;
+$$;
+
+-- ── timers ────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_due_timers(p_now timestamptz)
+RETURNS TABLE (
+  timer_id uuid,
+  pipeline_id uuid,
+  account_id uuid,
+  app_id uuid,
+  name text,
+  execution_count integer,
+  created_by uuid
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    t.id,
+    t.pipeline_id,
+    t.account_id,
+    t.app_id,
+    t.name,
+    COALESCE(t.execution_count, 0),
+    t.created_by
+  FROM public.timers t
+  WHERE t.is_active
+    AND t.pipeline_id IS NOT NULL
+    AND t.next_execution IS NOT NULL
+    AND t.next_execution <= p_now
+$$;
+
+CREATE OR REPLACE FUNCTION public.update_timer_after_run(
+  p_timer_id uuid,
+  p_success boolean,
+  p_error_message text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_interval numeric;
+BEGIN
+  SELECT CASE
+    WHEN config->>'interval_minutes' ~ '^\d+(\.\d+)?$'
+      THEN (config->>'interval_minutes')::numeric
+    ELSE NULL
+  END INTO v_interval
+  FROM public.timers WHERE id = p_timer_id;
+
+  UPDATE public.timers
+  SET
+    last_execution = now(),
+    execution_count = COALESCE(execution_count, 0) + 1,
+    success_count = COALESCE(success_count, 0) + CASE WHEN p_success THEN 1 ELSE 0 END,
+    failure_count = COALESCE(failure_count, 0) + CASE WHEN p_success THEN 0 ELSE 1 END,
+    next_execution = CASE
+      WHEN v_interval IS NOT NULL AND v_interval > 0
+        THEN now() + make_interval(mins => v_interval::double precision)
+      ELSE NULL
+    END,
+    updated_at = now()
+  WHERE id = p_timer_id;
+END;
+$$;
+
+-- ── threshold metrics ─────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_error_rate(p_window_minutes integer)
+RETURNS TABLE (error_rate numeric)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT CASE WHEN count(*) = 0 THEN 0
+    ELSE round(count(*) FILTER (WHERE outcome = 'failure' OR level = 'error')::numeric * 100 / count(*), 2)
+  END
+  FROM public.logs
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_latency_percentiles(p_window_minutes integer)
+RETURNS TABLE (p50 numeric, p95 numeric, p99 numeric)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    percentile_cont(0.50) WITHIN GROUP (ORDER BY duration_ms)::numeric,
+    percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms)::numeric,
+    percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms)::numeric
+  FROM public.logs
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+    AND duration_ms IS NOT NULL
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_pipeline_stats(p_window_minutes integer)
+RETURNS TABLE (total_success bigint, total_failure bigint)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    count(*) FILTER (WHERE status = 'completed'),
+    count(*) FILTER (WHERE status = 'failed')
+  FROM public.pipeline_executions
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+$$;
+
+-- ── log retention ─────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.cleanup_old_logs(p_retention_days integer DEFAULT 90)
+RETURNS TABLE (deleted_count bigint)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  RETURN QUERY
+  WITH deleted AS (
+    DELETE FROM public.logs
+    WHERE created_at < now() - make_interval(days => p_retention_days)
+    RETURNING 1
+  )
+  SELECT count(*) FROM deleted;
+END;
+$$;

package/.framework/schemas/spine.config.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://spine-framework.dev/schemas/spine.config.schema.json",
+  "title": "Spine Framework instance config",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "branding": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Instance branding applied to framework-owned pages (login, register, setup, sidebars) plus document.title and favicon. All keys optional; absent block falls back to Spine defaults.",
+      "properties": {
+        "app_name": {
+          "type": "string",
+          "description": "Display name used in headings and logo alt text, e.g. 'Answer Once'"
+        },
+        "title": {
+          "type": "string",
+          "description": "document.title and sidebar wordmark; defaults to app_name"
+        },
+        "logo_url": {
+          "type": "string",
+          "description": "Public asset path for the brand logo, e.g. '/answer-once-logo.svg'"
+        },
+        "favicon_url": {
+          "type": "string",
+          "description": "Public asset path swapped into link[rel=icon] at runtime"
+        }
+      }
+    },
+    "registration": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "default_app": { "type": "string" },
+        "default_role": { "type": "string" },
+        "allow_url_override": { "type": "boolean" },
+        "default_app_by_role": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "apps": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "roles": { "type": "array", "items": { "type": "string" } },
+              "default_role": { "type": "string" },
+              "path": { "type": "string" },
+              "enabled": { "type": "boolean" },
+              "account_strategy": { "type": "string", "enum": ["new", "existing"] },
+              "parent_account": { "type": "string" },
+              "target_account": { "type": "string" },
+              "allow_domain_join": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/.framework/src/App.tsx

@@ -14,6 +14,7 @@
 import { Suspense, lazy, useEffect } from 'react'
 import { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-dom'
 import { useAuth } from './contexts/AuthContext'
+import { useBranding } from './hooks/useBranding'
 import { LoadingSpinner } from './components/ui/LoadingSpinner'
 import { LoginPage } from './pages/auth/LoginPage'
 import { RegisterPage } from './pages/auth/RegisterPage'
@@ -65,13 +66,14 @@ const AdminApp = lazy(() => import('./apps/admin/index'))
 // CIL[DOC-NOTE type="change" content="Batch4b: authenticated-but-unplaced users (falsy account_id, not pending) are routed to /register?resume=1 for all paths so RegisterPage can finish placement — they no longer fall through to NotFound"]
 function App() {
   const { user, isLoading } = useAuth()
+  const branding = useBranding()
 
   if (isLoading) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-slate-50">
         <div className="text-center">
           <LoadingSpinner className="w-8 h-8 mx-auto mb-4" />
-          <p className="text-slate-600">Loading Spine...</p>
+          <p className="text-slate-600">Loading {branding.app_name}...</p>
         </div>
       </div>
     )

package/.framework/src/components/admin/AdminSidebar.tsx

@@ -59,6 +59,7 @@ import {
   SidebarRail,
 } from "../ui/sidebar"
 import { Button } from "../ui/button"
+import { useBranding } from "../../hooks/useBranding"
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible"
 // CIL[DOC-VECTOR type="context" content="purpose='Provides React, router, icons, and UI component imports for the admin sidebar module'; No verified external callers; imports: .framework/src/components/ui/sidebar.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/collapsible.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -175,6 +176,7 @@ const navigationSections = [
 // CIL[DOC-STABILITY stability="stable"]
 
 export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  const branding = useBranding()
   const location = useLocation()
 
   const isActive = (url: string) => {
@@ -188,9 +190,9 @@ export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>)
           <SidebarMenuItem>
             <SidebarMenuButton size="lg" asChild>
               <Link to="/spine-framework/admin/configs/types">
-                <img src="/spine-logo.svg" alt="Spine Framework" className="h-8 w-auto shrink-0" />
+                <img src={branding.logo_url} alt={branding.app_name} className="h-8 w-auto shrink-0" />
                 <div className="flex flex-col gap-0.5 leading-none">
-                  <span className="font-semibold whitespace-nowrap">Spine Framework</span>
+                  <span className="font-semibold whitespace-nowrap">{branding.title}</span>
                 </div>
               </Link>
             </SidebarMenuButton>

package/.framework/src/components/app-shell/GenericAppShell.tsx

@@ -12,6 +12,7 @@ import { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-
 import { AppRecord } from '../../hooks/useApps'
 import { GenericListPage } from './GenericListPage'
 import { GenericDetailPage } from './GenericDetailPage'
+import { useBranding } from '../../hooks/useBranding'
 // CIL[DOC-VECTOR type="context" content="purpose='Module imports and re-exports for the GenericAppShell component'; No verified external callers; imports: .framework/src/hooks/useApps.ts,.framework/src/components/app-shell/GenericListPage.tsx,.framework/src/components/app-shell/GenericDetailPage.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"]
@@ -76,6 +77,7 @@ export function GenericAppShell({ app }: GenericAppShellProps) {
   const navigate = useNavigate()
   const location = useLocation()
   const [sidebarOpen, setSidebarOpen] = useState(false)
+  const branding = useBranding()
 
   const navItems: NavItem[] = (app.nav_items || []) as NavItem[]
 
@@ -98,7 +100,7 @@ export function GenericAppShell({ app }: GenericAppShellProps) {
         ${sidebarOpen ? 'translate-x-0' : '-translate-x-full'}
       `}>
         <div className="flex items-center gap-3 h-16 px-6 border-b border-slate-200">
-          <img src="/spine-logo.svg" alt="Spine Framework" className="h-8 w-auto shrink-0" />
+          <img src={branding.logo_url} alt={branding.app_name} className="h-8 w-auto shrink-0" />
           <div>
             <h2 className="font-semibold text-slate-900 text-sm">{app.name}</h2>
             {app.description && (

package/.framework/src/components/auth/TurnstileWidget.tsx

@@ -16,12 +16,15 @@ export const turnstileEnabled = !!SITE_KEY
 export function TurnstileWidget({ onToken }: { onToken: (token: string | null) => void }) {
   if (!SITE_KEY) return null
   return (
-    <Turnstile
-      siteKey={SITE_KEY}
-      onSuccess={onToken}
-      onExpire={() => onToken(null)}
-      onError={() => onToken(null)}
-    />
+    <div className="flex justify-center">
+      <Turnstile
+        siteKey={SITE_KEY}
+        options={{ theme: 'light' }}
+        onSuccess={onToken}
+        onExpire={() => onToken(null)}
+        onError={() => onToken(null)}
+      />
+    </div>
   )
 }
 // CIL[END stable_id="~/.framework/src/components/auth/TurnstileWidget.tsx:module_header:module_header"]

package/.framework/src/components/kb/KBArticleEditor.tsx

@@ -1,4 +1,12 @@
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Schema-driven knowledge-article editor — loads a record's design_schema and renders view/edit/new modes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load type schema + article record, render main fields (title/content/description) plus a metadata sidebar, and handle save/publish/delete"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=".framework/src/components/ui/RichTextEditor.tsx, .framework/src/components/shared/SchemaFields.tsx, .framework/functions/_shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="KBArticleEditorProps (typeSlug, mode, articleId, onPublish?, sidebarFieldNames?, ...)" outputs="React editor view" errors="inline banner" side_effects="admin-data get/create/update/remove, optional custom onPublish or /api/kb publish"]
+// CIL[DOC-MICRO logic_summary="Fields split into main (title, content) and sidebar (everything else, optionally allowlisted via sidebarFieldNames); handleSave always saves first, then publishes via onPublish or /api/kb?action=publish; header wraps and truncates gracefully so long titles/dates never clip or overlap the action buttons" notable_decisions="custom onPublish callers save at current status — the backend decides publication after validation so a hard-failing draft never becomes published"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
 
 
 
@@ -49,6 +57,13 @@ import { ArrowLeft, Save, Send, Trash, X, Edit } from 'lucide-react'
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBArticleEditorProps:interface" type="interface" identity="KBArticleEditorProps" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Props interface for KBArticleEditor"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare mode, record id, permission flags, callbacks, publish overrides, and the sidebar field allowlist"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="onPublish replaces the default /api/kb publish call; sidebarFieldNames filters the metadata sidebar (empty array hides it entirely while still seeding formData)" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface KBArticleEditorProps {
   typeSlug: string
   typeName?: string
@@ -109,6 +124,13 @@ export interface KBArticleEditorProps {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBRecord:interface" type="interface" identity="KBRecord" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Minimal runtime-record shape the editor consumes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type the article record's id/title/status/created_at plus an open data bag"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Loose shape — extra record fields pass through the index signature" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface KBRecord {
   id: string
   title: string
@@ -146,6 +168,13 @@ interface KBRecord {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:getFieldDefault:function" type="function" identity="getFieldDefault" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Default value for a schema field when no record value exists"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map data_type to a sensible empty value: [] for multiselect/array, false for booleans, null for numbers/dates, first option for selects, '' otherwise"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="def: schema field definition" outputs="default value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Branch on data_type; select/radio take the first option's value" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function getFieldDefault(def: any): any {
   if (def.data_type === 'multiselect' || (def.data_type === 'array' && def.options)) return []
   if (def.data_type === 'boolean' || def.data_type === 'checkbox' || def.data_type === 'switch') return false
@@ -189,6 +218,13 @@ function getFieldDefault(def: any): any {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:initialFormData:function" type="function" identity="initialFormData" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Seed the form's initial values from schema + existing record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hydrate every schema field from the record (system fields top-level, data fields under record.data) or fall back to field defaults"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="schema, record|null" outputs="formData object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="New records additionally get status='draft' and empty title/content/description" notable_decisions="system:true fields read record[field] directly; others read record.data[field]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function initialFormData(schema: any, record: KBRecord | null): Record<string, any> {
   const values: Record<string, any> = {}
   Object.entries(schema?.fields || {}).forEach(([fieldName, fieldDef]: [string, any]) => {
@@ -237,6 +273,13 @@ function initialFormData(schema: any, record: KBRecord | null): Record<string, a
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBArticleEditor:component" type="component" identity="KBArticleEditor" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Render and operate the schema-driven article editor"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load schema+record, hydrate formData, render the wrapping header, main fields, and metadata sidebar, and run save/publish/delete flows"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=".framework/src/components/ui/RichTextEditor.tsx, .framework/src/components/shared/SchemaFields.tsx"]
+// CIL[DOC-CONTRACT inputs="KBArticleEditorProps" outputs="editor JSX" errors="save/publish/delete failures in an inline banner" side_effects="admin-data CRUD, kb publish or custom onPublish callback"]
+// CIL[DOC-MICRO logic_summary="Header uses flex-wrap + min-w-0/truncate so title, badge and date wrap instead of clipping behind the buttons; onFormChange fires only for post-init edits via a ref flag; publish saves first then delegates to onPublish or /api/kb?action=publish" notable_decisions="DOMPurify sanitizes stored rich text in view mode (stored-XSS defense)"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function KBArticleEditor({
   typeSlug,
   typeName,
@@ -486,27 +529,27 @@ export function KBArticleEditor({
 
   return (
     <div className="flex flex-col h-full">
-      <div className="px-6 py-3 border-b border-border shrink-0 flex items-center justify-between gap-4">
-        <div className="flex items-center gap-3 min-w-0">
+      <div className="px-6 py-3 border-b border-border shrink-0 flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
+        <div className="flex items-center gap-3 min-w-0 flex-wrap">
           {onBack && (
             <Button variant="ghost" size="sm" onClick={onBack} className="gap-1 text-muted-foreground">
               <ArrowLeft className="h-3.5 w-3.5" /> KB
             </Button>
           )}
-          <h1 className="text-base font-semibold truncate">
+          <h1 className="text-base font-semibold truncate max-w-[44ch]">
             {isCreating ? `New ${typeName || typeSlug}` : (record?.title || 'Edit Article')}
           </h1>
           {!isCreating && record && (
-            <div className="hidden sm:flex items-center gap-2">
+            <div className="hidden sm:flex items-center gap-2 shrink-0">
               <Badge variant={record.status === 'published' ? 'default' : 'outline'} className="text-xs">
                 {record.status || 'draft'}
               </Badge>
-              <span className="text-xs text-muted-foreground">{formatDateTime(record.created_at)}</span>
+              <span className="text-xs text-muted-foreground whitespace-nowrap">{formatDateTime(record.created_at)}</span>
             </div>
           )}
         </div>
 
-        <div className="flex items-center gap-2 shrink-0">
+        <div className="flex items-center gap-2 flex-wrap">
           {mode === 'view' && articleId && canEdit && (
             <Button size="sm" variant="outline" onClick={() => articleId && onEdit?.(articleId)} className="gap-1">
               <Edit className="h-3.5 w-3.5" /> Edit

package/.framework/src/components/layout/Layout.tsx

@@ -11,6 +11,7 @@
 import React, { useState } from 'react'
 import { Sidebar, SidebarContent } from './Sidebar'
 import { useAuth } from '../../contexts/AuthContext'
+import { useBranding } from '../../hooks/useBranding'
 import { useLocation } from 'react-router-dom'
 // CIL[DOC-VECTOR type="context" content="purpose='Module imports and top-level declarations for the Layout component.'; No verified external callers; imports: .framework/src/components/layout/Sidebar.tsx,.framework/src/contexts/AuthContext.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -50,6 +51,7 @@ interface LayoutProps {
 export function Layout({ children }: LayoutProps) {
   const [sidebarOpen, setSidebarOpen] = useState(false)
   const { user, logout } = useAuth()
+  const branding = useBranding()
   const location = useLocation()
 
   const isActive = (href: string) =>
@@ -87,8 +89,8 @@ export function Layout({ children }: LayoutProps) {
           </svg>
         </button>
         <div className="flex items-center gap-3">
-          <img src="/spine-logo.svg" alt="Spine Framework" className="h-8 w-auto" />
-          <span className="text-lg font-semibold tracking-tight text-slate-900 whitespace-nowrap">Spine Framework</span>
+          <img src={branding.logo_url} alt={branding.app_name} className="h-8 w-auto" />
+          <span className="text-lg font-semibold tracking-tight text-slate-900 whitespace-nowrap">{branding.title}</span>
         </div>
       </div>
 

package/.framework/src/components/layout/Sidebar.tsx

@@ -18,6 +18,7 @@
 import { useState } from 'react'
 import { Link, useLocation } from 'react-router-dom'
 import { useAuth } from '../../contexts/AuthContext'
+import { useBranding } from '../../hooks/useBranding'
 import { Popover, PopoverTrigger, PopoverContent } from '../ui/popover'
 import { 
   Home, 
@@ -249,6 +250,7 @@ function classNames(...classes: (string | false | undefined)[]) {
 // CIL[DOC-NOTE type="param" content="open: boolean - whether the sidebar is open"]
 // CIL[DOC-NOTE type="param" content="onClose: () => void - callback to close the sidebar"]
 export function Sidebar({ open, onClose }: SidebarProps) {
+  const branding = useBranding()
   return (
     <>
       <div className={classNames(open && 'fixed inset-0 z-40 flex')}> 
@@ -271,8 +273,8 @@ export function Sidebar({ open, onClose }: SidebarProps) {
               </div>
               <div className="h-0 flex-1 overflow-y-auto pt-5">
                 <div className="flex flex-shrink-0 items-center gap-2 px-4">
-                  <img src="/spine-logo.svg" alt="Spine Framework" className="h-8 w-auto" />
-                  <span className="text-xl font-bold text-sidebar-foreground whitespace-nowrap">Spine Framework</span>
+                  <img src={branding.logo_url} alt={branding.app_name} className="h-8 w-auto" />
+                  <span className="text-xl font-bold text-sidebar-foreground whitespace-nowrap">{branding.title}</span>
                 </div>
                 <SidebarContent onNavClick={onClose} />
               </div>

package/.framework/src/hooks/useBranding.ts

@@ -0,0 +1,47 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useBranding.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useBranding.ts"]
+// CIL[DOC-MACRO purpose="React hook exposing resolved instance branding and applying it to the document"]
+// CIL[DOC-RESPONSIBILITY responsibility="Give framework components the instance brand (name, logo, favicon, title) and keep document.title/favicon in sync"]
+// CIL[DOC-CONTEXT module="framework-hooks" layer="hook" related_files=".framework/src/lib/branding.ts,spine.config.json"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding" errors="load failures resolve to defaults" side_effects="document.title and favicon mutation via applyBrandingToDocument"]
+// CIL[DOC-MICRO logic_summary="Seeds state from the module cache, kicks the shared loadBranding fetch, updates state when it resolves, and applies document effects on every change" notable_decisions="every consumer applies document effects — idempotent, so pages that render a logo also fix the tab title/favicon"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework developers"]
+
+import { useEffect, useState } from 'react'
+import {
+  applyBrandingToDocument,
+  getCachedBranding,
+  loadBranding,
+  type SpineBranding,
+} from '../lib/branding'
+// CIL[END stable_id="~/.framework/src/hooks/useBranding.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useBranding.ts:usebranding:hook" type="hook" identity="useBranding" parent="~/.framework/src/hooks/useBranding.ts"]
+// CIL[DOC-MACRO purpose="Return the resolved SpineBranding and sync document.title/favicon"]
+// CIL[DOC-RESPONSIBILITY responsibility="Bridge the cached branding loader into React state"]
+// CIL[DOC-CONTEXT module="framework-hooks" layer="hook" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding (defaults until fetch resolves)" errors="none" side_effects="triggers shared /spine.config.json fetch; mutates document head"]
+// CIL[DOC-MICRO logic_summary="useState seeded by getCachedBranding; effect calls loadBranding then setBranding; second effect applies branding to the document whenever it changes" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function useBranding(): SpineBranding {
+  const [branding, setBranding] = useState<SpineBranding>(getCachedBranding)
+
+  useEffect(() => {
+    let active = true
+    loadBranding().then(resolved => {
+      if (active) setBranding(resolved)
+    })
+    return () => {
+      active = false
+    }
+  }, [])
+
+  useEffect(() => {
+    applyBrandingToDocument(branding)
+  }, [branding])
+
+  return branding
+}
+// CIL[END stable_id="~/.framework/src/hooks/useBranding.ts:usebranding:hook"]