spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/timers.md

@@ -0,0 +1,82 @@
+---
+title: Timers
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/timers.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TimersPage.tsx
+  - .framework/src/pages/admin/TimerDetailPage.tsx
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+---
+
+## What this is for
+
+A **timer** is a scheduled job that invokes a pipeline when it comes due — Spine's recurring/one-off background task primitive. `system-cron` (invoked every minute by the `trigger-scheduler` Netlify scheduled function) asks the `get_due_timers` RPC for due timers and runs each one's pipeline.
+
+## Fields and settings
+
+- **Name** — string. Display name; required (`name` and `timer_type` are the API's required fields).
+- **Type** — select: `interval`, `cron`, `once`. **Stored but not read by the scheduler** — it labels intent only; see Downstream effects.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select. The pipeline invoked when the timer fires. `get_due_timers` skips rows where `pipeline_id IS NULL`, so a blank pipeline means the timer never runs.
+- **Active** — checkbox. Inactive timers are skipped by `get_due_timers`.
+- **Description** — string, optional.
+- **Config (JSON)** — the schedule. The only key the rescheduler reads today is `interval_minutes` (minutes between runs). The form seeds `{ "schedule": "", "interval_seconds": 3600 }` — neither key is honored by the current RPCs.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- `get_due_timers` returns active timers with `pipeline_id IS NOT NULL` and `next_execution <= now()`. The timers API arms `next_execution` automatically on create/activate when `config.interval_minutes` (or `interval_seconds`) resolves to a positive interval — or pass `next_execution` explicitly.
+- `update_timer_after_run` reschedules `next_execution = now() + interval` only when `config.interval_minutes` is a positive number; otherwise it sets `next_execution = NULL` and the timer becomes one-shot/dead. `timer_type`, `interval_seconds`, `schedule`, and `run_at` are ignored by the RPC.
+- Each firing also stamps `last_execution` and increments `execution_count` / `success_count` / `failure_count` — the source of the list page's Executions and Success Rate columns.
+- True cron expressions live on the separate `public.schedules` table (read by `get_due_schedules`), not on `timers` — a `cron`-type timer is a label, not a working cron.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Hourly sync",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 60 }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Nightly-ish rollup",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 1440 },
+  "metadata": { "owner": "platform", "notes": "fires ~daily once next_execution is seeded" }
+}
+```
+
+## Example
+
+A support app keeps an `interval` timer with `interval_minutes: 360` to re-check stale tickets every six hours, and a second timer whose `interval_minutes` was left blank to run a one-off backfill — after its first fire, `update_timer_after_run` writes `next_execution = NULL` so it never re-fires.
+
+## Core files
+
+- `.framework/functions/timers.ts` — API (list/get/create/update/delete; does not set `next_execution`)
+- `.framework/functions/system-cron.ts` — per-tick driver: calls `get_due_timers`, runs `runPipeline` as a `timer:<id>` principal, then `update_timer_after_run`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point that delegates to `system-cron`
+- `.framework/migrations/068_cron_schedule_timer_rpcs.sql` — the `get_due_timers` / `update_timer_after_run` RPCs
+- `.framework/src/pages/admin/TimersPage.tsx` / `TimerDetailPage.tsx` — admin UI
+- Table: `public.timers` (`timer_type`, `pipeline_id`, `next_execution`, `execution_count` added by migration 020)
+
+## Agent notes
+
+- The list's "Next Execution" column shows `Not scheduled` when `next_execution` is NULL — an active timer in that state cannot fire until it is re-armed (edit its interval or toggle it off/on).
+- A timer with a blank `pipeline_id` saves fine but is filtered out by `get_due_timers` — always pick the pipeline.
+- To arm a new timer, set `next_execution` in the DB (e.g. `now() + interval`); after the first successful run, `interval_minutes` keeps it rescheduling.
+- "Success Rate" is `success_count / execution_count`; failures still reschedule — a broken pipeline does not stop the cadence.

package/.framework/src/instructions/triggers.md

@@ -0,0 +1,69 @@
+---
+title: Triggers
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/triggers.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TriggersPage.tsx
+  - .framework/src/pages/admin/TriggerDetailPage.tsx
+  - .framework/migrations/064_episode_leases.sql
+---
+
+## What this is for
+
+A **trigger** listens for a Spine event and, when active, hands the event payload to a pipeline for processing. It is the link between emitted platform events (e.g. `item_created`) and the workflows that react to them.
+
+## Fields and settings
+
+- **Name** — string. Display name; missing name prevents saving.
+- **Event Type** — string. The event to listen to, e.g. `item_created`. Must match the emitted event name **exactly** — a typo means the trigger never fires.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select, required at create (`name`, `event_type`, `pipeline_id` are all required by the API). The pipeline invoked when the trigger fires; a stale ID means the queued execution fails instead of running.
+- **Active** — checkbox. Inactive triggers are skipped at fire time — matching events produce no run.
+- **Description** — string, optional.
+- **Config (JSON)** — trigger-engine configuration, e.g. filters or payload mapping.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- The trigger engine (`admin-data` writes → `_shared/trigger-engine`) matches emitted events to active triggers by `event_type`; real event names use underscores — `item_created`, `item_updated`, `item_deleted`, `thread_created`, `message_created`, etc. (see the `EventType` union in `_shared/trigger-engine.ts`).
+- `config` filters narrow which matching events actually invoke the pipeline.
+- A wrong or stale `pipeline_id` means the trigger fires, queues an execution row, and the run fails — check Pipeline Executions, not just the trigger, when "nothing happened".
+
+## Minimal configuration
+
+```json
+{
+  "name": "On item created",
+  "event_type": "item_created",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true
+}
+```
+
+## Full configuration
+
+Adds `config` with payload filters (e.g. match only `item_created` where `type_slug = "ticket"`), field mappings into the pipeline input, and `metadata` documenting the contract the event producer is expected to emit.
+
+## Example
+
+A support app fires `item_created` filtered to `type_slug = "ticket"`; the trigger invokes its triage pipeline, which assigns the ticket and posts a thread message. A second trigger on `item_updated` handles SLA warnings — both share the same pipeline pattern but different filters.
+
+## Core files
+
+- `.framework/functions/triggers.ts` — API
+- `.framework/functions/_shared/trigger-engine.ts` — event matching and dispatch to `pipeline-runner-background`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point (delegates to `system-cron`)
+- `.framework/src/pages/admin/TriggersPage.tsx` / `TriggerDetailPage.tsx` — admin UI
+- Table: `public.triggers`
+
+## Agent notes
+
+- Event names are `<entity>_<past tense>` (`item_created`, `message_deleted`, ...) — the Event Type input's own placeholder still shows the stale `item.created` form; use underscores.
+- `config` filters (`entity_type`, `type_slug`, `filters` with `$eq`/`$ne`/`$gt`/etc.) narrow which matching events actually invoke the pipeline.
+- The list's "Total Fires" stat and "Fires"/"Last Fired" columns count trigger firings (the `record_trigger_fire` RPC), not successful pipeline runs — a trigger can fire while its pipeline fails.
+- `config` must be a JSON **object**, not a string — the second most common save failure after event-type typos.

package/.framework/src/instructions/types.md

@@ -0,0 +1,93 @@
+---
+title: Types
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/types.ts
+  - .framework/src/pages/admin/TypesPage.tsx
+  - .framework/src/pages/admin/TypeDetailPage.tsx
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/migrations/015_types_kind_slug_unique.sql
+---
+
+## What this is for
+
+A **type** is the design schema for a runtime record kind. It defines the fields, default list/detail views, record permissions, icon, and color that the generic admin and runtime UIs use to create, validate, and display records. Every `items`/`threads`/`messages`/etc. record is stamped with its type's `design_schema` at creation.
+
+## Fields and settings
+
+- **Name** — string. Display label for the type. Empty name blocks save.
+- **Slug** — string. URL-friendly identifier, unique per `kind`. Callers resolve types by slug; duplicates break `resolveTypeId`/`.single()` lookups. Rarely change after records exist.
+- **Description** — string, optional. Human-readable context.
+- **Kind** — select: `item`, `account`, `person`, `thread`, `message`, `link`, `attachment`, `watcher`. Determines which runtime table the type governs.
+- **Ownership** — select: `system` (platform types, protected from deletion), `app` (owned by an app), `tenant` (account-specific).
+- **Is Active** — checkbox. Inactive types are hidden from lists and cannot have records created.
+- **App ID** — select. Required whenever ownership is not `system` — the form rejects save otherwise.
+- **Icon / Color** — UI presentation stored on the `types` row.
+- **Design Schema (JSON)** — the full schema: `fields`, `views` (`default_list`, `default_detail`), `record_permissions`, `scope`, `functionality`.
+- **Validation Schema** — read-only, regenerated from `design_schema` on every save by the API.
+
+**Downstream effects**
+
+- Generic list/detail pages render directly from `views`. A missing `default_list`/`default_detail` or unknown `display_type` breaks those pages.
+- `record_permissions` is the **base, most restrictive grant**: if a role can read/update a record, all fields default to read/write. `fields.*.permissions` only *loosen* access per field or restrict `system: true` fields.
+- `system: true` fields are read from `record.<field>`; non-system fields from `record.data.<field>`.
+- Changing `data_type` on a field with existing records does not migrate data — old values remain until rewritten.
+- Type seeds use `conflict: "kind,slug"` with `inject_app_id: false` — types are global, not duplicated per app install.
+
+## Minimal configuration
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title": { "data_type": "text", "label": "Title", "required": true, "system": true }
+  },
+  "views": {
+    "default_list": {
+      "type": "list", "display": "table", "label": "List",
+      "fields": {
+        "title": { "sortable": true, "display_type": "text" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail", "label": "Detail",
+      "sections": [{ "title": "Details", "fields": { "title": { "display_type": "input" } } }]
+    }
+  },
+  "record_permissions": { "system_admin": ["create", "read", "update", "delete"] },
+  "functionality": null
+}
+```
+
+## Full configuration
+
+Adds typed fields, select `options`, per-field `permissions` overrides, multiple views with sorting/badges, and per-role record grants (`admin`, `member`). See the [design schema reference](reference/design-schema.md) for the full `data_type` list (`text`, `number`, `select`, `multiselect`, `reference`, `json`, `date`, `boolean`, ...) and `display_type` list (`badge`, `timestamp`, `select`, `currency`, ...).
+
+## Example
+
+A support app defines a `ticket` type (kind `item`, ownership `app`): `title` (system text), `status` (select: open/pending/closed), `priority` (select), `assignee_id` (reference). `record_permissions` grants `system_admin` all actions, `admin` create/read/update, `member` read. `fields.assignee_id.permissions` loosens `write` to `member` so agents can self-assign.
+
+## Core files
+
+- `.framework/functions/types.ts` — API (list/get/create/update/delete; regenerates `validation_schema`)
+- `.framework/src/pages/admin/TypesPage.tsx` / `TypeDetailPage.tsx` — admin UI
+- `.framework/src/components/app-shell/GenericListPage.tsx` / `GenericDetailPage.tsx` — generic renderer
+- `.framework/functions/_shared/permissions.ts` — record/field permission evaluation
+- [Design schema reference](reference/design-schema.md) — full field/view schema reference in this book
+- Table: `public.types`
+
+## Agent notes
+
+- Never hand-edit `validation_schema`; change `design_schema` and the API regenerates it.
+- Slug uniqueness is per `(kind, slug)` — reuse across kinds is fine, reuse within a kind breaks lookups.
+- Every field needs `data_type`, `label`, `required`; `select`/`multiselect`/`radio` also need `options`.
+- Don't add `fields.*.permissions` unless overriding the base grant — the common mistake is re-stating record-level permissions per field.
+- Custom apps CRUD runtime records through `/api/admin-data` — never custom wrappers.

package/.framework/src/lib/branding.ts

@@ -0,0 +1,128 @@
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Instance branding resolved from spine.config.json — app name, logo, favicon, document title"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load the optional branding block from /spine.config.json once per session, merge it over Spine defaults, and apply favicon/title to the document"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/hooks/useBranding.ts,spine.config.json,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding resolved object; applyBrandingToDocument performs DOM mutation" errors="fetch or parse failures fall back to DEFAULT_BRANDING" side_effects="HTTP GET /spine.config.json (single cached request); document.title and link[rel=icon] mutation"]
+// CIL[DOC-MICRO logic_summary="Module-level cache plus single inflight fetch; resolveBranding fills missing keys with defaults; applyBrandingToDocument sets document.title and swaps the favicon link href" notable_decisions="Branding lives in instance-owned spine.config.json so framework upgrades can never overwrite app branding; index.html keeps the Spine default and the runtime swap handles app-branded instances"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework developers"]
+// CIL[DOC-NOTE type="contract" content="branding is a top-level sibling of registration in spine.config.json. All keys optional; absent block yields DEFAULT_BRANDING so bare framework installs stay Spine-branded."]
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:spinebranding:interface" type="interface" identity="SpineBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Resolved instance branding shape"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type for the branding block after defaults are applied"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="app_name drives headings and logo alt; title drives document.title and wordmark text; logo_url and favicon_url are public/ asset paths" notable_decisions="title falls back to app_name, then to 'Spine Framework' when no branding block exists"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export interface SpineBranding {
+  app_name: string
+  title: string
+  logo_url: string
+  favicon_url: string
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:spinebranding:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:default_branding:constant" type="constant" identity="DEFAULT_BRANDING" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Spine Framework default branding used when spine.config.json has no branding block"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the fallback brand so the framework is self-branded out of the box"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding constant" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Matches the static values in .framework/index.html (title 'Spine Framework', favicon /spine-logo.svg)" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export const DEFAULT_BRANDING: SpineBranding = {
+  app_name: 'Spine',
+  title: 'Spine Framework',
+  logo_url: '/spine-logo.svg',
+  favicon_url: '/spine-logo.svg',
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:default_branding:constant"]
+
+let cached: SpineBranding | null = null
+let inflight: Promise<SpineBranding> | null = null
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:resolvebranding:function" type="function" identity="resolveBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Merge a raw branding block over defaults"]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce a complete SpineBranding from a possibly partial branding config value"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="raw: unknown (config.branding)" outputs="SpineBranding" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Each key falls back independently; title falls back to the resolved app_name so app-branded instances get a sane tab title without duplicating config" notable_decisions="non-string values treated as absent"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+function resolveBranding(raw: unknown): SpineBranding {
+  const b = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const appName = typeof b.app_name === 'string' && b.app_name ? b.app_name : DEFAULT_BRANDING.app_name
+  const configuredTitle = typeof b.title === 'string' && b.title ? b.title : null
+  return {
+    app_name: appName,
+    title: configuredTitle ?? (b.app_name ? appName : DEFAULT_BRANDING.title),
+    logo_url: typeof b.logo_url === 'string' && b.logo_url ? b.logo_url : DEFAULT_BRANDING.logo_url,
+    favicon_url:
+      typeof b.favicon_url === 'string' && b.favicon_url ? b.favicon_url : DEFAULT_BRANDING.favicon_url,
+  }
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:resolvebranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:loadbranding:function" type="function" identity="loadBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Fetch and cache the instance branding from /spine.config.json"]
+// CIL[DOC-RESPONSIBILITY responsibility="Perform a single fetch per session and memoize the resolved branding"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/src/hooks/useBranding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Promise<SpineBranding>" errors="network/parse failures resolve to DEFAULT_BRANDING" side_effects="one HTTP GET /spine.config.json per session"]
+// CIL[DOC-MICRO logic_summary="Returns cached value if present; otherwise shares one inflight promise across callers; any failure caches defaults so a missing config never retries per component" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function loadBranding(): Promise<SpineBranding> {
+  if (cached) return Promise.resolve(cached)
+  if (!inflight) {
+    inflight = fetch('/spine.config.json')
+      .then(res => (res.ok ? res.json() : null))
+      .then(config => {
+        cached = resolveBranding(config?.branding)
+        return cached
+      })
+      .catch(() => {
+        cached = DEFAULT_BRANDING
+        return cached
+      })
+  }
+  return inflight
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:loadbranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:getcachedbranding:function" type="function" identity="getCachedBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Synchronous read of resolved branding, or defaults before the fetch lands"]
+// CIL[DOC-RESPONSIBILITY responsibility="Give render paths a branding value without awaiting"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="cached ?? DEFAULT_BRANDING" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function getCachedBranding(): SpineBranding {
+  return cached ?? DEFAULT_BRANDING
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:getcachedbranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:applybrandingtodocument:function" type="function" identity="applyBrandingToDocument" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Apply resolved branding to document.title and the favicon link"]
+// CIL[DOC-RESPONSIBILITY responsibility="Swap the framework-shipped favicon/title for instance branding at runtime"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="branding: SpineBranding" outputs="void" errors="none" side_effects="sets document.title; rewrites or creates link[rel~=icon] in document.head"]
+// CIL[DOC-MICRO logic_summary="Idempotent DOM mutation — safe to call on every branding state change from every consumer" notable_decisions="runtime swap keeps .framework/index.html a static framework-owned file that upgrades can replace freely"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function applyBrandingToDocument(branding: SpineBranding): void {
+  if (branding.title) document.title = branding.title
+  if (!branding.favicon_url) return
+  let link = document.querySelector<HTMLLinkElement>('link[rel~="icon"]')
+  if (!link) {
+    link = document.createElement('link')
+    link.rel = 'icon'
+    document.head.appendChild(link)
+  }
+  link.href = branding.favicon_url
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:applybrandingtodocument:function"]

package/.framework/src/pages/NoAppPage.tsx

@@ -10,6 +10,7 @@
 
 import React from 'react'
 import { useAuth } from '../contexts/AuthContext'
+import { useBranding } from '../hooks/useBranding'
 // CIL[END stable_id="~/.framework/src/pages/NoAppPage.tsx:module_header:module_header"]
 
 // CIL[BEGIN stable_id="~/.framework/src/pages/NoAppPage.tsx:noapppage:component" type="component" identity="NoAppPage" parent="~/.framework/src/pages/NoAppPage.tsx"]
@@ -22,12 +23,13 @@ import { useAuth } from '../contexts/AuthContext'
 // CIL[DOC-STABILITY stability="experimental"]
 export function NoAppPage() {
   const { logout } = useAuth()
+  const branding = useBranding()
 
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
       <div className="max-w-md w-full text-center space-y-6">
         <div className="mx-auto flex items-center justify-center">
-          <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+          <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
         </div>
         <div className="space-y-2">
           <h1 className="text-2xl font-semibold text-slate-900">No apps yet</h1>

package/.framework/src/pages/NotFoundPage.tsx

@@ -1,35 +1,65 @@
 // CIL[BEGIN stable_id="~/.framework/src/pages/NotFoundPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-MACRO purpose="Import dependencies used by the NotFoundPage 404 component"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide React, react-router-dom Link, and lucide-react Home icon for the page"]
-// CIL[DOC-CONTEXT module=".framework/src/pages" layer="page" related_files=".framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-CONTRACT inputs="N/A" outputs="N/A" errors="N/A" side_effects="N/A"]
-// CIL[DOC-MICRO logic_summary="Imports React, Link, and Home icon; no runtime logic" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="Spine framework page authors"]
+/**
+ * @module   NotFoundPage
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module renders a Not Found page for the application, providing users with a friendly message when they navigate to an undefined route. It serves as a fallback UI component, enhancing user experience by guiding them back to the home page. INVARIANT: The Not Found page should always be accessible for any invalid routes.
+ *
+ * @seeAlso react-router-dom (provides routing capabilities).
+ * @seeAlso lucide-react (used for icons).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
+
 
 
 
 import React from 'react'
 import { Link } from 'react-router-dom'
 import { Home } from 'lucide-react';
-// CIL[DOC-VECTOR type="context" content="purpose='Import dependencies used by the NotFoundPage 404 component'; No verified external callers; imports: none"]
-// 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/NotFoundPage.tsx:module_header:module_header"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/pages/NotFoundPage.tsx:NotFoundPage:component" type="component" identity="NotFoundPage" parent="~/.framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-MACRO purpose="Render a friendly 404 not found page with a link back to sign in"]
-// CIL[DOC-RESPONSIBILITY responsibility="Display a centered 404 message and a Home icon link that navigates to /login"]
-// CIL[DOC-CONTEXT module=".framework/src/pages" layer="page" related_files=".framework/src/pages/NotFoundPage.tsx"]
-// CIL[DOC-CONTRACT inputs="None" outputs="JSX 404 page" errors="None" side_effects="None"]
-// CIL[DOC-MICRO logic_summary="Renders a full-screen 404 page with a heading, description, and a Link to /login" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="End users who reach an unknown route"]
+/**
+ * The NotFoundPage component displays a 404 error message when a page is not found, providing a user-friendly interface to guide users back to the home page.
+ *
+ * @macro       React functional component responsible for rendering a 404 error page.
+ * @micro       Utilizes JSX to structure the layout and styling of the error message and navigation link.
+ * @outputSpec  JSX.Element
+ * @sideEffects none
+ * @stability   internal
+ * @calls       Link
+ * @cil-generated
+ */
 export function NotFoundPage() {
   return (
     <div className="min-h-screen bg-slate-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
@@ -43,11 +73,11 @@ export function NotFoundPage() {
           
           <div className="mt-6">
             <Link
-              to="/login"
+              to="/"
               className="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md shadow-sm text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
             >
               <Home className="w-4 h-4 mr-2" />
-              Go to sign in
+              Go home
             </Link>
           </div>
         </div>
@@ -55,10 +85,11 @@ export function NotFoundPage() {
     </div>
   )
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Render a friendly 404 not found page with a link back to sign in'; No verified external callers; imports: none"]
-// 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/NotFoundPage.tsx:NotFoundPage:component"]
+// CIL[END stable_id="~/.framework/src/pages/NotFoundPage.tsx:NotFoundPage:component"]
+
+
+
+
+
+
+

package/.framework/src/pages/SetupPage.tsx

@@ -10,6 +10,7 @@
 
 import React from 'react'
 import { Link } from 'react-router-dom'
+import { useBranding } from '../hooks/useBranding'
 // CIL[DOC-VECTOR type="context" content="purpose='Declare module-level imports for the Setup page'; No verified external callers; imports: none"]
 // 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"]
@@ -28,15 +29,17 @@ import { Link } from 'react-router-dom'
 // CIL[DOC-STABILITY stable]
 
 export function SetupPage() {
+  const branding = useBranding()
+
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 py-12 px-4 sm:px-6 lg:px-8">
       <div className="max-w-lg w-full space-y-8">
         <div className="text-center">
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-3xl font-extrabold text-slate-900">
-            Welcome to Spine
+            Welcome to {branding.app_name}
           </h2>
           <p className="mt-2 text-sm text-slate-600">
             Your project is running but no apps are installed yet.