spine-framework 0.3.104 → 0.3.106

package/.framework/functions/_shared/agent-runner.ts

@@ -45,6 +45,7 @@
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
 import { emitAudit } from './audit'
+import { create as createRecord } from '../admin-data'
 
 // ─── TYPES ───────────────────────────────────────────────────────────────
 
@@ -472,16 +473,28 @@ async function buildContext(
 /**
  * Retrieves relevant documents from the `embeddings` table for RAG.
  *
- * Uses Supabase full-text search (`textSearch`) on `content`. Falls back
- * to returning an empty array on error (never throws).
- * Future: replace with vector similarity search when embedding service is wired.
+ * Strategy (tiered):
+ *   1. Generate a query embedding via the OpenAI embeddings API.
+ *   2. Call the `match_embeddings` Postgres RPC (vector cosine similarity).
+ *   3. Deduplicate by document_id — keep best-matching chunk per article.
+ *   4. Enrich with item titles from the `items` table.
+ *   5. Fall back to full-text search if the embedding API is unavailable or
+ *      the RPC call fails (guarantees graceful degradation in dev/test).
  *
- * @param query - User message text to search against
- * @param knowledgeSources - Array of document UUIDs to filter the search
- * @param accountId - Account scope for the embeddings lookup
- * @returns Promise<any[]> — array of embedding rows (content, metadata)
- * @throws never — returns [] on failure
- * @sideEffects DB read: embeddings table
+ * Account scoping:
+ *   - Always includes the requesting account's embeddings.
+ *   - Always includes the platform KB account (spine-system), excluding
+ *     rows where metadata.security_level = 'restricted'.
+ *   - `knowledgeSources` optionally narrows to specific document UUIDs
+ *     (prompt_config.knowledge_sources); omit or pass [] for full scope.
+ *
+ * @param query - User message text to embed and search
+ * @param knowledgeSources - Optional document UUIDs to restrict search scope
+ * @param accountId - Requesting account for scoped access
+ * @returns Promise<any[]> — enriched result rows (id, title, content, similarity)
+ * @throws never — falls back to text search or [] on any failure
+ * @sideEffects HTTP call to OpenAI embeddings API (if API key present)
+ * @sideEffects DB read: match_embeddings RPC + items table
  * @calledBy buildContext (if promptConfig.knowledge_sources is non-empty)
  */
 async function retrieveKnowledge(
@@ -489,27 +502,113 @@ async function retrieveKnowledge(
   knowledgeSources: string[],
   accountId: string
 ): Promise<any[]> {
-  // For now, we'll need the query embedding - this requires calling an embedding service
-  // In production, this would call the same embedding model used to create embeddings
-  // For now, we'll do a text search fallback
+  const SIMILARITY_THRESHOLD = 0.15
+  const MATCH_COUNT = 8
 
-  const { data: docs, error } = await adminDb
-    .from('embeddings')
-    .select('*')
-    .eq('account_id', accountId)
-    .in('document_id', knowledgeSources)
-    .textSearch('content', query, {
-      type: 'websearch',
-      config: 'english'
+  // ── Tier 1: vector similarity via match_embeddings RPC ──────────────────
+  try {
+    const apiKey = process.env.OPENAI_API_KEY || process.env.LLM_API_KEY
+    const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1'
+
+    if (!apiKey) throw new Error('no_api_key')
+
+    // Resolve platform account ID at runtime — no hardcoded UUIDs
+    const { data: platformAccount } = await adminDb
+      .from('accounts')
+      .select('id')
+      .eq('slug', 'spine-system')
+      .maybeSingle()
+
+    const accountIds: string[] = [accountId]
+    if (platformAccount?.id && platformAccount.id !== accountId) {
+      accountIds.push(platformAccount.id)
+    }
+
+    // Generate query embedding
+    const embedRes = await fetch(`${baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ model: 'text-embedding-3-small', input: query }),
     })
-    .limit(5)
+    if (!embedRes.ok) throw new Error(`embed_api_${embedRes.status}`)
+    const embedJson: any = await embedRes.json()
+    const queryEmbedding: number[] = embedJson.data?.[0]?.embedding || []
+    if (!queryEmbedding.length) throw new Error('empty_embedding')
+
+    // Call vector RPC
+    const { data: matches, error: rpcError } = await adminDb.rpc('match_embeddings', {
+      query_embedding: `[${queryEmbedding.join(',')}]`,
+      match_count: MATCH_COUNT * 3,
+      filter_account_ids: accountIds,
+      filter_vector_type: 'semantic',
+      similarity_threshold: SIMILARITY_THRESHOLD,
+    })
+    if (rpcError) throw new Error(`rpc_${rpcError.message}`)
 
-  if (error) {
-    console.error('Knowledge retrieval failed:', error)
-    return []
-  }
+    // Filter: security_level restriction for cross-account results
+    const filtered = (matches || []).filter((r: any) => {
+      if (r.similarity < SIMILARITY_THRESHOLD) return false
+      if (r.account_id === accountId) return true
+      return r.metadata?.security_level !== 'restricted'
+    })
+
+    // Optionally narrow to knowledgeSources doc IDs
+    const scoped = knowledgeSources.length > 0
+      ? filtered.filter((r: any) => knowledgeSources.includes(r.document_id))
+      : filtered
 
-  return docs || []
+    // Deduplicate — best chunk per document
+    const bestByDoc = new Map<string, any>()
+    for (const r of scoped) {
+      const existing = bestByDoc.get(r.document_id)
+      if (!existing || r.similarity > existing.similarity) bestByDoc.set(r.document_id, r)
+    }
+    const deduped = [...bestByDoc.values()]
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, MATCH_COUNT)
+
+    if (deduped.length === 0) return []
+
+    // Enrich with item titles
+    const { data: items } = await adminDb
+      .from('items')
+      .select('id, title, description')
+      .in('id', deduped.map((r: any) => r.document_id))
+
+    const itemMap = new Map((items || []).map((i: any) => [i.id, i]))
+    return deduped.map((r: any) => ({
+      document_id: r.document_id,
+      content: r.content,
+      metadata: r.metadata,
+      similarity: r.similarity,
+      title: itemMap.get(r.document_id)?.title || '',
+    }))
+
+  } catch (vectorErr: any) {
+    // ── Tier 2: full-text fallback ──────────────────────────────────────
+    if (vectorErr.message !== 'no_api_key') {
+      console.warn('retrieveKnowledge vector search failed, falling back to text search:', vectorErr.message)
+    }
+
+    const baseQuery = adminDb
+      .from('embeddings')
+      .select('document_id, content, metadata, account_id')
+      .eq('account_id', accountId)
+      .eq('metadata->>vector_type', 'semantic')
+      .textSearch('content', query, { type: 'websearch', config: 'english' })
+      .limit(5)
+
+    const q = knowledgeSources.length > 0
+      ? baseQuery.in('document_id', knowledgeSources)
+      : baseQuery
+
+    const { data: docs, error } = await q
+    if (error) {
+      console.error('Knowledge retrieval fallback failed:', error)
+      return []
+    }
+    return docs || []
+  }
 }
 
 /**
@@ -1068,6 +1167,17 @@ async function handleEscalation(
  * @sideEffects DB write: messages table
  * @calledBy runAgent (user message + agent response)
  */
+// Module-level cache so we only look up the message type_id once per cold-start
+let _messageTypeId: string | null = null
+
+async function getMessageTypeId(): Promise<string> {
+  if (_messageTypeId) return _messageTypeId
+  const { data } = await adminDb.from('types').select('id').eq('slug', 'message').maybeSingle()
+  if (!data?.id) throw new Error('Type "message" not found in types table')
+  _messageTypeId = data.id
+  return _messageTypeId
+}
+
 async function saveMessage(
   threadId: string,
   content: string,
@@ -1075,23 +1185,30 @@ async function saveMessage(
   data: any,
   ctx: CoreContext
 ): Promise<any> {
-  const { data: message, error } = await adminDb
-    .from('messages')
-    .insert({
-      thread_id: threadId,
-      account_id: ctx.accountId,
-      person_id: messageType === 'human' ? ctx.principal?.id : null,
-      content,
-      content_format: 'text',
-      data: {
-        message_type: messageType,
-        ...data
-      },
-      created_at: new Date().toISOString()
-    })
-    .select()
-    .single()
+  const [typeId, { count }] = await Promise.all([
+    getMessageTypeId(),
+    adminDb.from('messages').select('id', { count: 'exact', head: true }).eq('thread_id', threadId),
+  ])
+  const sequence = (count ?? 0) + 1
+  const direction = messageType === 'human' ? 'inbound' : 'outbound'
+
+  // Use admin-data's create() so design_schema + validation_schema are stamped
+  // from the type record — ensuring the permission engine returns full rows.
+  const message = await createRecord(ctx, {
+    entity: 'messages',
+    type_id: typeId,
+    thread_id: threadId,
+    person_id: messageType === 'human' ? ctx.principal?.id : null,
+    content,
+    direction,
+    sequence,
+    visibility: 'internal',
+    data: {
+      message_type: messageType,
+      ...data
+    },
+  })
 
-  if (error) throw new Error(`Failed to save message: ${error.message}`)
+  if (!message?.id) throw new Error('Failed to save message')
   return message
 }

package/.framework/migrations/001_schema.sql

@@ -105,6 +105,7 @@ CREATE TABLE IF NOT EXISTS public.threads (
 CREATE TABLE IF NOT EXISTS public.messages (
   id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
   type_id uuid NOT NULL, thread_id uuid NOT NULL,
+  account_id uuid REFERENCES public.accounts(id),
   content text NOT NULL, direction text DEFAULT 'outbound',
   sequence integer NOT NULL, visibility text DEFAULT 'internal',
   data jsonb DEFAULT '{}', is_active boolean DEFAULT true,

package/.framework/migrations/022_route_prefix_domain_unique.sql

@@ -0,0 +1,21 @@
+-- Migration 022: Allow multiple apps to share a route_prefix when they have
+-- different prod_domains (i.e. they are served from different subdomains).
+--
+-- Before: UNIQUE(route_prefix) WHERE is_active AND route_prefix IS NOT NULL
+--   → only one app could claim "/" across the entire database
+--
+-- After:  UNIQUE(route_prefix, COALESCE(prod_domain, '')) WHERE is_active AND route_prefix IS NOT NULL
+--   → two apps can both use "/" as long as they have different prod_domains
+--   → apps with no prod_domain still get a unique slot (COALESCE maps NULL → '')
+--
+-- This is required to support multiple domain-scoped apps (e.g. Cortex on
+-- cortex.spine-framework.com and Portal on portal.spine-framework.com) that
+-- each serve from the root path "/" of their respective domains.
+
+-- Drop the old single-column unique index
+DROP INDEX IF EXISTS idx_apps_route_prefix;
+
+-- Create the new composite unique index
+CREATE UNIQUE INDEX IF NOT EXISTS idx_apps_route_prefix_domain
+  ON public.apps(route_prefix, COALESCE(prod_domain, ''))
+  WHERE is_active = true AND route_prefix IS NOT NULL;

package/.framework/migrations/023_match_embeddings_rpc.sql

@@ -0,0 +1,78 @@
+-- Migration 023: match_embeddings RPC for vector similarity search
+--
+-- Provides the `match_embeddings` Postgres function used by:
+--   - custom_kb-embeddings.ts (handleSearchEmbeddings)
+--   - agent-runner.ts (retrieveKnowledge — after upgrade)
+--
+-- Requires the `vector` extension (enabled in migration 002).
+-- Uses cosine distance (<=>). Returns rows ordered best-first.
+
+-- ============================================
+-- HNSW INDEX (idempotent)
+-- ============================================
+-- Create HNSW index on the embedding column for fast approximate nearest-neighbour search.
+-- Skip if it already exists (Postgres 15+ supports IF NOT EXISTS for indexes).
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_indexes
+    WHERE schemaname = 'public'
+      AND tablename  = 'embeddings'
+      AND indexname  = 'embeddings_embedding_hnsw_idx'
+  ) THEN
+    EXECUTE 'CREATE INDEX embeddings_embedding_hnsw_idx
+             ON public.embeddings
+             USING hnsw (embedding vector_cosine_ops)
+             WITH (m = 16, ef_construction = 64)';
+  END IF;
+END
+$$;
+
+-- ============================================
+-- match_embeddings RPC
+-- ============================================
+CREATE OR REPLACE FUNCTION public.match_embeddings(
+  query_embedding     vector(1536),
+  match_count         int            DEFAULT 10,
+  filter_account_ids  uuid[]         DEFAULT NULL,
+  filter_vector_type  text           DEFAULT NULL,
+  similarity_threshold float         DEFAULT 0.15
+)
+RETURNS TABLE (
+  id              uuid,
+  document_id     text,
+  content         text,
+  metadata        jsonb,
+  account_id      uuid,
+  similarity      float
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    e.id,
+    e.document_id,
+    e.content,
+    e.metadata,
+    e.account_id,
+    1 - (e.embedding <=> query_embedding) AS similarity
+  FROM public.embeddings e
+  WHERE
+    -- account scope filter (NULL = no filter — platform-wide search)
+    (filter_account_ids IS NULL OR e.account_id = ANY(filter_account_ids))
+    -- vector type filter (NULL = all types)
+    AND (filter_vector_type IS NULL OR e.metadata->>'vector_type' = filter_vector_type)
+    -- similarity gate (cosine similarity = 1 - cosine distance)
+    AND (1 - (e.embedding <=> query_embedding)) >= similarity_threshold
+  ORDER BY e.embedding <=> query_embedding   -- ascending distance = descending similarity
+  LIMIT match_count;
+END;
+$$;
+
+-- Grant execute to authenticated and service roles
+GRANT EXECUTE ON FUNCTION public.match_embeddings(vector, int, uuid[], text, float) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.match_embeddings(vector, int, uuid[], text, float) TO service_role;
+GRANT EXECUTE ON FUNCTION public.match_embeddings(vector, int, uuid[], text, float) TO anon;

package/.framework/migrations/024_messages_account_id.sql

@@ -0,0 +1,9 @@
+-- Migration 024: Add account_id to messages table
+-- messages was the only runtime table missing account_id.
+-- Required by admin-data's create() (which stamps account_id on all runtime records)
+-- and by RLS policies that scope rows to an account.
+
+ALTER TABLE public.messages
+  ADD COLUMN IF NOT EXISTS account_id uuid REFERENCES public.accounts(id);
+
+CREATE INDEX IF NOT EXISTS idx_messages_account_id ON public.messages(account_id);

package/LICENSE.md

@@ -1,32 +1,37 @@
-Spine Framework Internal Use License 1.0.0
-Source-available. Free for internal use. Commercial rights reserved.
+# Spine Framework Internal Use License 1.0.0
+
+**Source-available. Free for internal use. Commercial rights reserved.**
 
 This license is based on the structure and intent of the PolyForm Internal Use License 1.0.0, but it has been modified for Spine Framework. This is not the unmodified PolyForm Internal Use License.
 
-Required Notice
+## Required Notice
+
 Required Notice: Copyright © 2026 Dahl Ventures Inc. All rights reserved.
 
-1. Acceptance
+## 1. Acceptance
+
 In order to receive any license under these terms, you must agree to these terms as both strict obligations and conditions to all licenses granted to you.
 
 If you do not agree to these terms, you do not have permission to use, copy, modify, run, install, access, or create works based on Spine Framework.
 
-2. Definitions
-Software means Spine Framework, including its source code, object code, packages, modules, templates, schemas, migrations, configuration files, documentation, examples, command-line tools, SDKs, application packs, and related materials provided by the licensor.
+## 2. Definitions
+
+**Software** means Spine Framework, including its source code, object code, packages, modules, templates, schemas, migrations, configuration files, documentation, examples, command-line tools, SDKs, application packs, and related materials provided by the licensor.
 
-Licensor means the legal owner of Spine Framework.
+**Licensor** means the legal owner of Spine Framework.
 
-You means the individual or legal entity receiving the Software.
+**You** means the individual or legal entity receiving the Software.
 
-Your Company means the legal entity on whose behalf you use the Software, including that entity's employees and authorized contractors.
+**Your Company** means the legal entity on whose behalf you use the Software, including that entity's employees and authorized contractors.
 
-Internal Business Use means use of the Software solely inside Your Company for Your Company's own internal business operations, internal workflows, internal applications, internal data, internal users, and internal customers or accounts.
+**Internal Business Use** means use of the Software solely inside Your Company for Your Company's own internal business operations, internal workflows, internal applications, internal data, internal users, and internal customers or accounts.
 
-Third Party means any person or legal entity other than You or Your Company.
+**Third Party** means any person or legal entity other than You or Your Company.
 
-Commercial License means a separate written agreement signed by the Licensor that grants rights beyond this license.
+**Commercial License** means a separate written agreement signed by the Licensor that grants rights beyond this license.
+
+## 3. Copyright License
 
-3. Copyright License
 The Licensor grants You a copyright license to do everything with the Software that would otherwise infringe the Licensor's copyright, but only for Internal Business Use and only as permitted by these terms.
 
 You may install, run, access, evaluate, test, configure, and use the Software for Internal Business Use.
@@ -35,84 +40,99 @@ You may copy the Software only as reasonably necessary for Internal Business Use
 
 You may not distribute the Software except as expressly allowed in these terms.
 
-4. Changes and New Works
+## 4. Changes and New Works
+
 The Licensor grants You a copyright license to modify the Software and create new works based on the Software, but only for Internal Business Use.
 
 You may create internal applications, extensions, workflows, integrations, automations, schemas, roles, agents, triggers, pipelines, dashboards, reports, and other internal business systems using the Software.
 
 You may not distribute, sell, sublicense, transfer, lease, rent, host for others, white-label, resell, or commercially exploit any modified version, derivative work, extension, application pack, template, or implementation of the Software except under a Commercial License.
 
-5. Internal Contractors
+## 5. Internal Contractors
+
 Your Company may allow employees and contractors to access and use the Software solely on behalf of Your Company and solely for Your Company's Internal Business Use.
 
 Contractors do not receive any independent right to use the Software for themselves, their other clients, their own products, or any Third Party.
 
 Your Company is responsible for all use of the Software by its employees, contractors, agents, and representatives.
 
-6. Your Data and Application-Specific Work
+## 6. Your Data and Application-Specific Work
+
 As between You and the Licensor, You own Your Company's data, records, content, prompts, business logic, customer records, internal workflows, and application-specific code that You independently create using the Software.
 
 These terms do not give the Licensor ownership of Your Company's data or independently created application-specific business content.
 
 However, ownership of Your Company's data or application-specific work does not give You the right to distribute, resell, white-label, host, or commercially exploit the Software or any portion of the Software except as allowed by these terms or a Commercial License.
 
-7. Prohibited Uses
+## 7. Prohibited Uses
+
 You may not do any of the following without a Commercial License:
 
-Sell, resell, sublicense, rent, lease, lend, transfer, assign, publish, or distribute the Software.
-Offer the Software, or any modified version of the Software, to Third Parties as software, infrastructure, a framework, a platform, a service, or a hosted product.
-Offer the Software as SaaS, PaaS, IaaS, framework-as-a-service, backend-as-a-service, workflow-as-a-service, automation-as-a-service, AI-agent platform, managed service, support service, or similar commercial service.
-White-label, private-label, rebrand, or remove Spine Framework identity from the Software in order to provide it to Third Parties.
-Embed, bundle, package, or include the Software in any product, service, appliance, marketplace offering, application pack, starter kit, template library, SDK, CLI, distribution, or managed implementation made available to Third Parties.
-Use the Software to operate, power, support, or provide a product or service for Third Parties where those Third Parties receive access to the Software or to functionality substantially provided by the Software.
-Use the Software to build, operate, or improve a competing framework, platform, marketplace, application generator, agentic software infrastructure product, or commercial development infrastructure product.
-Provide implementation, consulting, hosting, support, customization, training, migration, or managed services for the Software to Third Parties as a paid or commercial offering, except as expressly authorized by the Licensor.
-Remove, alter, obscure, or bypass copyright notices, license notices, attribution, trademarks, branding, license keys, license checks, usage limits, or technical protection measures included in the Software.
-Use the Software in violation of law, regulation, third-party rights, or these terms.
-8. Examples of Permitted Use
+1. Sell, resell, sublicense, rent, lease, lend, transfer, assign, publish, or distribute the Software.
+2. Offer the Software, or any modified version of the Software, to Third Parties as software, infrastructure, a framework, a platform, a service, or a hosted product.
+3. Offer the Software as SaaS, PaaS, IaaS, framework-as-a-service, backend-as-a-service, workflow-as-a-service, automation-as-a-service, AI-agent platform, managed service, support service, or similar commercial service.
+4. White-label, private-label, rebrand, or remove Spine Framework identity from the Software in order to provide it to Third Parties.
+5. Embed, bundle, package, or include the Software in any product, service, appliance, marketplace offering, application pack, starter kit, template library, SDK, CLI, distribution, or managed implementation made available to Third Parties.
+6. Use the Software to operate, power, support, or provide a product or service for Third Parties where those Third Parties receive access to the Software or to functionality substantially provided by the Software.
+7. Use the Software to build, operate, or improve a competing framework, platform, marketplace, application generator, agentic software infrastructure product, or commercial development infrastructure product.
+8. Provide implementation, consulting, hosting, support, customization, training, migration, or managed services for the Software to Third Parties as a paid or commercial offering, except as expressly authorized by the Licensor.
+9. Remove, alter, obscure, or bypass copyright notices, license notices, attribution, trademarks, branding, license keys, license checks, usage limits, or technical protection measures included in the Software.
+10. Use the Software in violation of law, regulation, third-party rights, or these terms.
+
+## 8. Examples of Permitted Use
+
 The following are permitted under this license, provided they are solely for Internal Business Use:
 
-A company installs Spine Framework to build its own internal CRM.
-A company uses Spine Framework to operate an internal customer support portal for its own support team and its own customers.
-A company modifies Spine Framework for its internal workflows, roles, permissions, automations, pipelines, and integrations.
-A company lets its employees and authorized contractors configure, maintain, and support its internal Spine Framework installation.
-A company creates internal dashboards, agents, knowledge bases, audit trails, and operational tools on top of Spine Framework.
-9. Examples Requiring a Commercial License
+1. A company installs Spine Framework to build its own internal CRM.
+2. A company uses Spine Framework to operate an internal customer support portal for its own support team and its own customers.
+3. A company modifies Spine Framework for its internal workflows, roles, permissions, automations, pipelines, and integrations.
+4. A company lets its employees and authorized contractors configure, maintain, and support its internal Spine Framework installation.
+5. A company creates internal dashboards, agents, knowledge bases, audit trails, and operational tools on top of Spine Framework.
+
+## 9. Examples Requiring a Commercial License
+
 The following are not permitted under this license and require a Commercial License:
 
-Selling Spine Framework or a modified version of Spine Framework.
-Offering Spine Framework as a hosted SaaS product.
-Offering a white-labeled application built on Spine Framework to customers.
-Packaging Spine Framework into a commercial starter kit, template, marketplace app, agency offering, or developer platform.
-Running Spine Framework for multiple clients as a managed service provider, agency, consultant, systems integrator, or outsourcing firm.
-Embedding Spine Framework into a product sold to customers.
-Forking Spine Framework to launch a competing framework, backend, app platform, AI-agent platform, or development infrastructure product.
-Publishing modified Spine Framework source code to a public repository.
-Giving a customer, client, partner, reseller, or affiliate a copy of Spine Framework.
-10. Distribution
+1. Selling Spine Framework or a modified version of Spine Framework.
+2. Offering Spine Framework as a hosted SaaS product.
+3. Offering a white-labeled application built on Spine Framework to customers.
+4. Packaging Spine Framework into a commercial starter kit, template, marketplace app, agency offering, or developer platform.
+5. Running Spine Framework for multiple clients as a managed service provider, agency, consultant, systems integrator, or outsourcing firm.
+6. Embedding Spine Framework into a product sold to customers.
+7. Forking Spine Framework to launch a competing framework, backend, app platform, AI-agent platform, or development infrastructure product.
+8. Publishing modified Spine Framework source code to a public repository.
+9. Giving a customer, client, partner, reseller, or affiliate a copy of Spine Framework.
+
+## 10. Distribution
+
 You may not distribute the Software, modified versions of the Software, or works based on the Software to any Third Party except as expressly permitted by these terms or a Commercial License.
 
 You may share copies of the Software with employees and contractors of Your Company only as necessary for Internal Business Use and only if they are bound by obligations consistent with these terms.
 
 Any copy of the Software must include this license and all Required Notices.
 
-11. Trademarks
+## 11. Trademarks
+
 This license does not grant You any right to use the Licensor's names, trademarks, service marks, logos, product names, domain names, or branding except as necessary to identify the Software for Internal Business Use.
 
 You may not use Spine Framework branding in a way that suggests sponsorship, endorsement, partnership, certification, resale authorization, or commercial authorization without written permission from the Licensor.
 
-12. Patent License
+## 12. Patent License
+
 The Licensor grants You a patent license for the Software that covers patent claims the Licensor can license, or later becomes able to license, that You would infringe by using the Software as permitted by these terms.
 
-13. Patent Defense
+## 13. Patent Defense
+
 If You make any written claim that the Software infringes or contributes to infringement of any patent, Your patent license for the Software ends immediately.
 
 If Your Company makes such a claim, Your Company's patent license ends immediately.
 
-14. Fair Use and Other Legal Rights
+## 14. Fair Use and Other Legal Rights
+
 You may have fair use, fair dealing, or other rights under applicable law. These terms do not limit rights that the law does not allow these terms to limit.
 
-15. No Other Rights
+## 15. No Other Rights
+
 These terms do not allow You to sublicense, transfer, assign, or delegate any license granted under these terms except as expressly allowed here.
 
 These terms do not prevent the Licensor from granting licenses to anyone else.
@@ -121,43 +141,51 @@ These terms do not imply any license other than the licenses expressly granted h
 
 All rights not expressly granted are reserved by the Licensor.
 
-16. Violations and Cure
+## 16. Violations and Cure
+
 The first time You are notified in writing that You have violated these terms, or done anything with the Software not covered by these terms, Your licenses can continue if You:
 
-come into full compliance with these terms;
-take practical steps to correct past violations; and
-complete both within 32 days of receiving written notice.
+1. come into full compliance with these terms;
+2. take practical steps to correct past violations; and
+3. complete both within 32 days of receiving written notice.
+
 If You do not satisfy those requirements, all licenses granted to You under these terms end immediately.
 
 For any later violation, all licenses granted to You under these terms end immediately without any cure period.
 
-17. Termination
-When Your licenses end, You must stop all use of the Software and destroy all copies of the Software in Your possession or control, except copies you are legally required to retain for archival, compliance, or legal purposes.
+## 17. Termination
+
+When Your licenses end, You must stop all use of the Software and destroy all copies of the Software in Your possession or control, except copies You are legally required to retain for archival, compliance, or legal purposes.
 
 Sections concerning ownership, prohibited uses, trademarks, patent defense, no other rights, violations, termination, no warranty, limitation of liability, and general terms survive termination.
 
-18. No Warranty
+## 18. No Warranty
+
 As far as the law allows, the Software is provided as is and as available, without any warranty or condition, express or implied.
 
 The Licensor disclaims all warranties and conditions, including warranties of merchantability, fitness for a particular purpose, title, non-infringement, availability, accuracy, security, and quiet enjoyment.
 
-19. Limitation of Liability
+## 19. Limitation of Liability
+
 As far as the law allows, the Licensor will not be liable to You for any indirect, incidental, special, consequential, exemplary, punitive, or other damages arising out of these terms or the Software.
 
 As far as the law allows, the Licensor will not be liable for lost profits, lost revenue, lost savings, lost data, business interruption, security incidents, procurement of substitute services, or loss of goodwill.
 
 The Licensor's total liability arising out of these terms or the Software will not exceed the amount You paid the Licensor for the Software during the 12 months before the event giving rise to liability, or USD $100 if You paid nothing.
 
-20. Commercial Licensing
+## 20. Commercial Licensing
+
 Rights not granted under this license may be available under a separate Commercial License from the Licensor.
 
 A Commercial License is required for resale, redistribution, SaaS, managed services, white-label use, OEM use, marketplace distribution, partner use, commercial hosting, commercial support offerings, or any use outside Internal Business Use.
 
 To request commercial rights, contact:
 
-spine-framework.com
-webmaster@spine-framework.com
-21. License Updates
+ - spine-framework.com
+ - webmaster@spine-framework.com
+
+## 21. License Updates
+
 The Licensor may publish updated versions of this license from time to time.
 
 Each release, package, download, or copy of the Software is governed by the license terms included with that release, package, download, or copy, unless You and the Licensor have signed a separate written agreement.
@@ -168,7 +196,8 @@ The Licensor may require acceptance of updated license terms as a condition of r
 
 Nothing in this section gives You rights to continue using future versions of the Software under earlier license terms.
 
-22. General Terms
+## 22. General Terms
+
 If any part of these terms is held unenforceable, the rest remains in effect as far as the law allows.
 
 Failure by the Licensor to enforce any term is not a waiver.
@@ -177,7 +206,8 @@ Any waiver must be in writing and signed by the Licensor.
 
 These terms are the entire license terms for the Software unless You and the Licensor have signed a separate written agreement.
 
-23. Plain-English Summary
+## 23. Plain-English Summary
+
 This summary is not part of the legal license.
 
 You may use Spine Framework inside your own company for your own internal business operations.

package/docs/README.md

@@ -1,170 +1,136 @@
-# Spine Framework
+# Spine - Internal Dev Repo
 
-**A multi-tenant, modular application platform for modern SaaS systems.**
+**A multi-tenant, event-driven operational OS for modern SaaS systems.**
 
-Spine Framework provides the operational backbone — identity, data modeling, permissions, real-time sync, and extensibility — so you can build vertical applications faster.
+Spine is not a CRM, a helpdesk, or a workflow tool. It is the operational nervous system underneath applications — the central coordination layer that handles identity, state machines, audit trails, event emission, automation, webhooks, semantic intelligence, and theming so that vertical products don't have to rebuild these primitives.
 
-## What Spine Provides
+> See [docs/MANIFESTO.md](docs/MANIFESTO.md) for the full design philosophy.
 
-| Primitive | Purpose |
-|-----------|---------|
-| **Accounts** | Multi-tenant organizations with RLS isolation |
-| **People** | Users with cross-account identities |
-| **Items** | Typed records (deals, tickets, posts, custom entities) |
-| **Types** | Runtime-defined schemas with permissions |
-| **Apps** | Modular feature packages |
-| **Realtime** | Live subscriptions to data changes |
-| **RLS Security** | Row-level security with role-based access |
+## What Spine Knows
 
-## Quick Start
+| Primitive | Not Domain-Specific |
+|---|---|
+| Accounts | Not "companies" or "clients" |
+| Persons | Not "employees" or "candidates" |
+| Workflow Items | Not "deals" or "jobs" |
+| Events | Not "notifications" |
+| Automation Rules | Not "zapier zaps" |
+| Embeddings | Not "documents" |
 
-```bash
-# Create new project
-npm init spine-framework@next
-
-# Or add to existing project
-npm install spine-framework@next
-
-# Start development
-npm run dev
-```
-
-## Installation
-
-See [INSTALL.md](INSTALL.md) for detailed setup instructions.
+Spine provides the operational backbone. Your vertical product provides the meaning.
 
 ## Architecture
 
-Spine Framework is built on:
+- **Frontend**: React 18 + Vite + TailwindCSS + shadcn/ui
+- **API**: Netlify Functions (TypeScript)
+- **Database**: Supabase Postgres + pgvector
+- **Auth**: Supabase Auth (JWT) — browser handles login/session; all data access via API
 
-- **Frontend**: React 18 + TypeScript + Tailwind CSS + Vite
-- **Backend**: Supabase (PostgreSQL + Auth + Realtime)
-- **Edge**: Netlify/Vercel Edge Functions
-- **Extension**: Custom workspace pattern
+### Core Principles
 
-Read [ARCHITECTURE.md](ARCHITECTURE.md) for the full technical overview.
+- **Event-driven**: Every state change produces an outbox event. Every event can trigger automations and webhooks.
+- **Multi-tenant**: Every row scoped by `account_id`. Every request resolves person, account, and role context.
+- **Automation-native**: Automation rules are first-class primitives with condition evaluation and action execution.
+- **Audit-first**: Every write emits `audit_log` (before/after diff) and `activity_event` records. Nothing mutates silently.
+- **AI-aware**: Multi-vector embeddings (pgvector) with auto-indexing on write and semantic search.
+- **API-first**: Frontend never touches the database. All reads/writes go through Netlify Functions.
+- **RBAC**: Two-tier — `account_role` (admin/operator/member) + `system_role` (system_admin/system_operator/support_operator).
 
-## Project Structure
+## Modules
 
-```
-my-spine-app/
-├── .framework/          # Framework core (read-only)
-│   ├── src/            # React components & pages
-│   ├── migrations/     # Database migrations
-│   └── scripts/        # CLI & build tools
-├── custom/             # Your custom code
-│   ├── apps/          # Installed apps (portal, cortex, etc.)
-│   ├── components/    # Shared components
-│   ├── functions/     # Edge functions
-│   └── migrations/    # Custom migrations
-├── docs/              # Documentation
-└── package.json
-```
-
-## Core Principles
-
-1. **Framework-Agnostic Core** — Base platform knows nothing of specific apps
-2. **App-Defined Data** — Types, roles, and schemas defined by apps
-3. **Custom Workspace** — Extensions in `custom/` without modifying core
-4. **RLS-First Security** — All permissions enforced at database level
-
-## Apps
+| Module | Description |
+|---|---|
+| **Identity & Tenancy** | Accounts, persons, profiles, memberships, invites, RBAC, auto-provisioning |
+| **Workflow Engine** | Definitions, stage builder, items, kanban, stage transitions, automation rules |
+| **Support** | Tickets, threaded messages, knowledge base articles |
+| **Activity & Audit** | Append-only activity feed + immutable audit log |
+| **Integrations** | Outbox events, webhook subscriptions, HMAC-signed deliveries with retry/backoff/dead-letter |
+| **Automation** | Event-triggered rules with conditions, actions (transition, emit, webhook, update) |
+| **Intelligence** | Multi-vector embeddings, auto-embed on write, semantic search UI |
+| **Theming** | DB-stored tokens, 3 presets (Clean/Bold/Muted), live Theme Editor |
 
-Spine Framework is extended through apps:
+## Setup
 
-- **portal** — Customer portal with courses, community, support
-- **cortex** — AI-powered CRM, knowledge base, and support
-- **Your App** — Build and install custom apps
-
-See [APPS.md](APPS.md) for app development guide.
-
-## Development
+> ### TODO
+> - [ ] Enable **Leaked password protection** in Supabase: Dashboard → **Auth → Settings → Password security**.
 
 ### Prerequisites
 
 - Node.js 18+
-- PostgreSQL 14+ (or Supabase account)
-- npm or yarn
+- Netlify CLI (`npm i -g netlify-cli`)
+- Supabase project (with pgvector enabled)
 
-### Local Setup
+### Environment Variables
 
-```bash
-# Install dependencies
-npm install
+Copy `.env.example` to `.env` and fill in:
 
-# Configure environment
-cp .framework/.env.example .env
-# Edit .env with your Supabase credentials
-
-# Apply database migrations
-npx spine-cli db:migrate
-
-# Start dev server
-npm run dev
+```
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
 ```
 
-### Installing Apps
+### Database Setup
 
-```bash
-# From npm
-npm install spine-framework-cortex@next
-npx spine-cli app:install cortex
+Apply migrations in order (001–016) via Supabase SQL editor or CLI:
 
-# From local package
-npx spine-cli app:install ./custom/npm/my-app
+```bash
+# Each file in supabase/migrations/ should be applied sequentially
 ```
 
-### Creating Custom Apps
+### Local Development
 
 ```bash
-# Scaffold new app
-npx spine-cli app:create my-app
-
-# Define types in custom/apps/my-app/seed/types.json
-# Create pages in custom/apps/my-app/pages/
-# Wire up routes in custom/apps/my-app/index.tsx
-
-# Install and test
-npx spine-cli app:install ./custom/apps/my-app
-npm run dev
+npm install
+netlify dev
 ```
 
-## Documentation
+This starts:
+- Vite dev server on port 5173
+- Netlify Functions proxy on port 8888
+- App at `http://localhost:8888`
 
-| Document | Description |
-|----------|-------------|
-| [INSTALL.md](INSTALL.md) | Installation guide |
-| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture |
-| [APPS.md](APPS.md) | App development |
-| [spine-core--api-reference.md](spine-core--api-reference.md) | API reference |
-| [dev-guides/](dev-guides/) | Step-by-step tutorials |
+New users are auto-provisioned on first login — no manual database setup required.
 
-## CLI Commands
+### Build
 
 ```bash
-npx spine-cli init              # Initialize new project
-npx spine-cli db:migrate        # Apply migrations
-npx spine-cli db:seed           # Apply seed data
-npx spine-cli app:install <name> # Install an app
-npx spine-cli app:create <name>  # Create new app scaffold
+npm run build
 ```
 
-## npm Packages
-
-| Package | Description |
-|---------|-------------|
-| `spine-framework` | Core framework |
-| `spine-framework-portal` | Customer portal app |
-| `spine-framework-cortex` | CRM & support app |
-
-All packages use the `@next` tag for pre-release versions.
-
-## License
-
-MIT License — see LICENSE file for details.
+## Project Structure
 
-## Support
+```
+├── core/                         # Canonical Spine runtime (DO NOT EDIT)
+│   ├── functions/               # 59 endpoint handlers
+│   │   ├── _shared/              # Shared utilities (middleware, db, audit, etc.)
+│   │   └── *.ts                  # Core API endpoints
+│   └── src/                     # Core React frontend
+│       ├── components/           # UI components (ui/, layout/, shared/, etc.)
+│       ├── pages/                # Route pages (admin, portal, public)
+│       ├── lib/                  # Utilities (api, auth, config, theme, etc.)
+│       └── hooks/                # React hooks (useAuth, useCustomFields, etc.)
+├── custom/                       # Your extensions (MODIFY FREELY)
+│   ├── functions/               # Custom serverless functions (override/extend core)
+│   └── src/                     # Custom frontend code
+│       └── manifest/routes.ts   # Custom route + nav registrations
+├── src/                         # Assembled frontend output (auto-generated, .gitignored)
+├── netlify/functions/            # Assembled API output (auto-generated, .gitignored)
+├── supabase/
+│   └── migrations/              # 33 SQL migrations
+├── scripts/
+│   ├── assemble-functions.sh     # Merge core/functions + custom/functions
+│   ├── assemble-frontend.sh     # Merge core/src + custom/src → src/
+│   ├── build-manifest.sh         # Generate integrity hashes
+│   └── verify-integrity.sh       # Verify core integrity
+├── docs/
+│   ├── MANIFESTO.md              # Design philosophy
+│   ├── FRONTEND.md               # Frontend architecture
+│   ├── EXTENDING.md              # Extension guide
+│   └── API.md                    # API reference
+├── netlify.toml
+└── package.json
+```
 
-- Documentation: `docs/`
-- Issues: https://github.com/spine-framework/spine/issues
-- Discussions: https://github.com/spine-framework/spine/discussions
+# Testing GIT flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.104",
+  "version": "0.3.106",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {
@@ -28,6 +28,9 @@
     ".framework/migrations/019_triggers_unique_constraint.sql",
     ".framework/migrations/020_get_account_apps_role_filter.sql",
     ".framework/migrations/021_app_domains.sql",
+    ".framework/migrations/022_route_prefix_domain_unique.sql",
+    ".framework/migrations/023_match_embeddings_rpc.sql",
+    ".framework/migrations/024_messages_account_id.sql",
     ".framework/public/",
     ".framework/scripts/",
     ".framework/seeds/",

package/scripts/boundary-check.sh

@@ -18,8 +18,9 @@ echo ""
 VIOLATIONS=0
 
 # Check 1: Core importing from custom/ directory
+# Only flag actual import/require statements — comments and docs are fine
 echo "1. Checking for imports from custom/ in core..."
-if grep -r "from.*custom/\|import.*@custom" .framework/ --include="*.ts" --include="*.tsx" --exclude-dir=tests 2>/dev/null; then
+if grep -rE "^\s*(import|export).*['\"].*custom/|require\(['\"].*custom/" .framework/ --include="*.ts" --include="*.tsx" --exclude-dir=tests 2>/dev/null; then
     echo "   ❌ FAIL: Core files import from custom/"
     VIOLATIONS=$((VIOLATIONS + 1))
 else
@@ -48,8 +49,11 @@ fi
 echo ""
 
 # Check 3: App-specific references in core
+# Only flag actual code (imports, JSX, logic) — comments, JSDoc, and string literals in examples are fine
 echo "3. Checking for app-specific references in core..."
-APP_REFS=$(grep -r "cortex\|funnel\|support-triage\|kb-chunker\|portal-signals" .framework/src/ --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "manifest.json\|webhook-registry" || true)
+APP_REFS=$(grep -rE "^\s*(import|export|from|<[A-Z])" .framework/src/ --include="*.ts" --include="*.tsx" 2>/dev/null \
+  | grep -E "cortex|funnel|support-triage|kb-chunker|portal-signals" \
+  | grep -v "manifest\.json\|webhook-registry" || true)
 if [ -n "$APP_REFS" ]; then
     echo "   ❌ FAIL: App-specific references found in core:"
     echo "$APP_REFS"