{"slug":"strategy/product-strategy/v0-definitive-spec","title":"Historical v0 Definitive Specification — Superseded","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/v0-definitive-spec.mdx","bytes":75826,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** HISTORICAL IMPLEMENTATION HANDOFF\n> **Current frontend authority:** [`docs/frontend-v0/README.md`](frontend-v0/README.md)\n> plus\n> [`FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md`](architecture/FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md).\n>\n> Do not implement the domain-first shell, permanent Twin sidebar, direct\n> service mapping or older environment claims below.\n\n# Original Snapshot: IntegrateWise v0 Definitive Specification\n\n**Status:** Canonical v0 implementation handoff \n**Date:** July 24, 2026 \n**Scope:** Complete infrastructure mapping, environment management, service adapters, end-to-end schema, persistent workspace behavior, MCP boundary, and explicit sidebar-to-schema mapping\n\n---\n\n## 1. Document Status\n\nThis document is the definitive v0 spec for the frontend, Twin, agents, memory, capabilities, continuity, and Spine network. It replaces fragmented drafts.\n\n- **Frontend baseline:** PR #99 branch `v0/nirmal-it90-cff4a009`\n- **Backend authority:** Hermes-aligned platform services and canonical architecture documentation\n- **Purpose:** Align v0 frontend with approved product architecture using existing resources only\n\n---\n\n## 2. Canonical Product Law\n\n> **Twin is the user-facing cognitive orchestrator. Agents are delegated specialists. Capabilities are governed actions. The continuity runtime provides durable execution beneath Twin. Triage controls generated writes. The Spine owns canonical truth.**\n\nOwnership chain:\n\n```text\nUser → Twin → Context Builder → Knowledge + Memory + Search → Agent/Capability Resolver → Governance → Execution → Continuity Runtime → Triage → Approved Spine Mutation → Projection Refresh → Twin Reports Outcome\n```\n\nThe user experiences one intelligent actor: **Twin**. Internal services remain implementation mechanisms beneath Twin.\n\n---\n\n## 3. Core Workbench Spine\n\nThe Workbench is the persistent user workspace. Everything else—Twin, agents, memory, capabilities, continuity, governance—operates through the Workbench or on behalf of the Workbench.\n\n### 3.1 Workbench Ownership Law\n\n```text\nWorkspace\n ↓\nWorkbench Shell\n ↓\nWorkbench Definition\n ↓\nRole / Department / Industry Projection\n ↓\nEntity / Relationship / Activity / Task / Signal / Evidence / Document / Artifact / Memory / Approval / Continuity\n ↓\nTwin contextual layer\n ↓\nAgent / Capability / Governance / Execution\n```\n\nRules:\n\n- The Workbench owns user context, role, department, industry, workspace, organization, and active session state.\n- The Workbench never exposes raw database tables.\n- The Workbench consumes projections from the Spine and backend services only.\n- The Workbench never bypasses Governance, Triage, or Pipeline for canonical writes.\n- The Workbench is the only durable surface the user returns to after leaving or refreshing.\n\n### 3.2 Core Workbench Entities\n\nThese are the mandatory core entities for v0:\n\n| Entity | Owner | Description |\n| ----------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| User | Tenancy | Authenticated person; owns preferences, roles, and personal context |\n| Organization | Platform | Top-level tenant boundary; owns billing, policy, and governance scope |\n| Workspace | Platform | Operational environment for a user or team; owns domain, department, and active connections |\n| Role | Platform | Permission and capability scope; drives projection behavior |\n| Department | Platform | Organizational unit; drives routing and data visibility |\n| Industry | Platform | Market segment; influences schema, capability policy, and projections |\n| Entity | Spine | Canonical operational object: account, contact, deal, ticket, project, knowledge item, decision, policy, capability, signal, memory, conversation |\n| Relationship | Spine | Canonical relationship between entities with confidence and validity period |\n| Activity | Spine | Operational primitive: task, message, meeting, call, notification, approval |\n| Task | Product | Executable unit of work assigned to user, agent, or workflow |\n| Note | Spine | User-authored memory or observation |\n| Knowledge Document | Knowledge | Explicit reusable document with chunking and embeddings |\n| Artifact | Store | Document, image, generated asset, or evidence file stored via Blob/R2 |\n| Signal | Signals | Operational condition requiring attention: risk, renewal, anomaly, approval needed, insight |\n| Evidence | Spine | Immutable attachment or reference tied to an entity or event |\n| Event | Spine | Append-only record of every meaningful mutation with provenance |\n| Governance Request | Platform | Approval, rejection, or policy decision tied to a capability or mutation |\n| Continuity Session | Continuity | Durable execution context for Twin, agent, workflow, or approval wait |\n| Agent Run | Agent Runtime | Delegated execution with bounded context, capability assignment, and outcome |\n| Capability Invocation | Capability | Governed business action with policy evaluation, execution target, and evidence |\n| Embedding/Vector Record | Knowledge | Server-side embedding for semantic retrieval of entities, memories, documents, and chunks |\n\n### 3.3 Workbench Projection Contract\n\nThe Workbench receives projection responses only. Direct table access is forbidden.\n\n```ts\ninterface WorkbenchProjection {\n tenantId: string;\n workspaceId: string;\n userId: string;\n role: string;\n department: string;\n industry?: string;\n activeDomain: string;\n activeSection: string;\n hydration: {\n stage: \"instant\" | \"operational\" | \"deep\" | \"complete\";\n progress: number;\n };\n overview: {\n activeEntities: number;\n openWorkItems: number;\n overdueWorkItems: number;\n pendingApprovals: number;\n activeSignals: number;\n activeDocuments: number;\n activeMemories: number;\n activeCapabilities: number;\n activeAgents: number;\n activeContinuityItems: number;\n };\n entities: EntityProjection[];\n relationships: RelationshipProjection[];\n activities: ActivityProjection[];\n tasks: TaskProjection[];\n signals: SignalProjection[];\n documents: DocumentProjection[];\n artifacts: ArtifactProjection[];\n memories: MemoryProjection[];\n approvals: ApprovalProjection[];\n continuity: ContinuityProjection[];\n evidence: EvidenceProjection[];\n events: EventProjection[];\n}\n```\n\n### 3.4 Workbench State Model\n\nEvery workbench surface must support:\n\n- Uninitialized\n- Loading\n- Hydrating\n- Ready\n- Empty\n- Degraded\n- Blocked\n- Approval Required\n- Disconnected\n- Stale\n- Failed\n- Retrying\n- Completed\n\nThe UI must never collapse these into a generic spinner or generic error.\n\nExample:\n\n```text\nHydrating\nThe initial Salesforce account structure is ready.\nHistorical activities are still loading.\nTwin can already analyze active opportunities.\n```\n\n### 3.5 Workbench Routing Law\n\n```text\nauth.role + auth.department + tenant.industry + activeDomain\n ↓\nproduct.workbench_definitions\n ↓\nview_config\n ↓\nWorkbenchShell\n ↓\nDomain / Entity / Task / Signal / Knowledge / Memory / Approval / Continuity surfaces\n```\n\nRouting rules:\n\n- Work view is strictly one chosen domain; no universal default for work.\n- Personal domain has default behavior.\n- Cross-functional views are explicit and governed by role and department.\n- L1/L2/L4/L7 must not appear as user-facing navigation.\n\n### 3.6 Workbench Shell Layout\n\n```text\n┌─────────────────────────────────────────────────────────┐\n│ Top Bar: Workspace | Search | Twin | Alerts | User │\n├───────────────┬─────────────────────────┬───────────────┤\n│ Domain Nav │ Main Workbench │ Twin Sidebar │\n│ │ │ │\n│ Home │ Projection-driven │ Ask │\n│ Accounts │ operational content │ Analyze │\n│ Tasks │ │ Recommend │\n│ Signals │ │ Delegate │\n│ Knowledge │ │ Continue │\n│ Memory │ │ Review │\n│ Agents │ │ Remember │\n│ Capabilities │ │ │\n│ Continuity │ │ │\n│ Approvals │ │ │\n│ Connectors │ │ │\n└───────────────┴─────────────────────────┴───────────────┘\n```\n\n### 3.7 Workbench Data Flow\n\n```text\nUser intent\n ↓\nAppShell / WorkbenchShell\n ↓\nContext Builder\n ↓\nGateway / Projection Engine\n ↓\nSpine + Knowledge + Memory + Signals + Tasks + Approvals + Continuity\n ↓\nGoverned read model\n ↓\nWorkbench surface\n ↓\nTwin contextual layer\n ↓\nAgent / Capability / Governance / Execution\n ↓\nPipeline/Triage for candidate writes\n ↓\nApproved Spine mutation\n ↓\nProjection refresh\n ↓\nWorkbench updates\n```\n\n### 3.8 Workbench ↔ Twin Mapping\n\n| Workbench Section | Twin Function | Twin Reads | Twin Writes |\n| ----------------- | ------------------------ | --------------------------------------------------- | ------------------------------------ |\n| Home | Orient, recommend | Projection overview, signals, tasks, approvals | None |\n| Accounts/Entities | Explain, analyze | Entity 360, relationships, evidence, tasks, signals | Candidate memory, candidate proposal |\n| Tasks | Plan, delegate, continue | Task list, continuity state, agent runs | Delegated work, continuity action |\n| Signals | Explain, recommend | Active signals, entity context, knowledge | None |\n| Knowledge | Explain, recommend | Documents, chunks, embeddings, entity links | None |\n| Memory | Remember, review | Personal, work, organization, candidate memory | Memory candidate |\n| Agents | Delegate, review | Agent registry, run state, context, evidence | Agent task |\n| Capabilities | Act, plan | Capability registry, policy, approval state | Proposed action |\n| Continuity | Continue, review | Workflow state, retry state, checkpoint | Continuity action |\n| Approvals | Review, act | Governance requests, evidence, capability | Approval decision |\n\n### 3.9 Workbench ↔ Agent/Memory/Continuity Mapping\n\n| Workbench Event | Agent Action | Memory Action | Continuity Action |\n| ---------------------- | ------------------- | ---------------------- | ---------------------- |\n| Open entity detail | Optional agent read | Read permitted memory | None |\n| Twin recommends action | None | None | None |\n| User approves proposal | None | None | Schedule execution |\n| Twin delegates work | Execute task | Read working memory | Checkpoint/resume |\n| Agent returns result | Return result | Write episodic memory | Update execution state |\n| Triage review | None | Promote candidate | None |\n| Continuity retry | None | None | Retry/backoff |\n| Cancel execution | Pause/stop | Archive working memory | Cancel workflow |\n\n---\n\n## 4. IW Shared Environment Registry\n\nAll IntegrateWise applications share one centrally managed environment and secret stack. Applications do not receive raw provider credentials. They receive IntegrateWise API endpoints and client identifiers only.\n\n### 4.1 Central Configuration Model\n\n```text\nIW Shared Environment\n├── Database\n├── Object storage\n├── Redis/cache\n├── Queues\n├── Vector storage\n├── AI providers\n├── Authentication\n├── Connector credentials\n└── Internal service endpoints\n```\n\nThis registry is defined once and consumed by:\n\n- IW Spine Network\n- Connector Marketplace\n- Work-Bench\n- Connector Runtime\n- Memory Services\n- Twin\n- Intelligence Services\n- Development Applications\n\nImplementation status: shared environment module scaffolded in `packages/config`; frontend public env surface stabilized as `apps/web/src/lib/shared-env.ts`. Full rotation/policy enforcement is pending while backend adapter layer is built.\n\n### 4.2 Public Application Environment\n\nFrontend and public applications receive only IntegrateWise variables from the shared module:\n\n```env\nNEXT_PUBLIC_IW_API_URL=https://gateway.integratewise.ai\nNEXT_PUBLIC_IW_AUTH_URL=\nNEXT_PUBLIC_IW_CLIENT_ID=\nNEXT_PUBLIC_IW_ENVIRONMENT=development\n```\n\nFallback behavior:\n\n- If `NEXT_PUBLIC_IW_API_URL` is missing, the client defaults to `https://gateway.integratewise.ai`.\n- Seed fallback is disabled unless `NEXT_PUBLIC_IW_SPINE_SEED_FALLBACK=1`.\n\nThey must not receive:\n\n- `DATABASE_URL`\n- `SUPABASE_URL`\n- `BLOB_READ_WRITE_TOKEN`\n- `UPSTASH_REDIS_REST_URL`\n- `CLOUDFLARE_ACCOUNT_ID`\n- `R2_ACCESS_KEY_ID`\n- `AI_GATEWAY_API_KEY`\n- `DESCOPE_MANAGEMENT_KEY`\n- Any other raw provider credential\n\n### 4.3 Server-Side Application Environment\n\nServer-side applications receive IntegrateWise service credentials only:\n\n```env\nIW_API_URL=https://api.integratewise.ai\nIW_SERVICE_TOKEN=...\nIW_ENVIRONMENT=production\n```\n\nThey do not receive underlying provider credentials directly. Provider credentials are injected by the central secret manager into the shared runtime.\n\n### 4.4 Central Secret Manager\n\n```text\nCentral Secret Manager\n ↓\nEnvironment profile\n ↓\nService-specific permitted secrets\n```\n\nProfiles:\n\n- `development`\n- `test`\n- `production`\n\nEach profile contains:\n\n- Shared infrastructure endpoints\n- Shared secret references\n- Service-specific permissions\n- Versioning and rotation policy\n- Health and capability status\n\n### 4.5 Service Permissions\n\nEach service receives only the secrets it requires:\n\n```text\nproduction\n├── spine\n├── memory\n├── connectors\n├── intelligence\n├── marketplace\n└── workbench\n```\n\nThe central registry owns:\n\n- Credential creation and rotation\n- Environment profile promotion\n- Service permission grants\n- Health and capability checks\n- Audit of secret access\n\n### 4.6 Simple Rule\n\n```text\nConfigure infrastructure once\n→ expose IntegrateWise APIs\n→ reuse them across every application\n```\n\nThe base rule is:\n\n> **One centrally managed environment and secret stack for all IntegrateWise applications.**\n\n### 4.7 Adapter Contract\n\nServer-side service adapters read from the central registry. They do not read from individual application environment variables.\n\n```ts\ninterface ServiceAdapters {\n neon: NeonAdapter;\n blob: BlobAdapter;\n redis: RedisAdapter;\n r2: R2Adapter;\n aiGateway: AIGatewayAdapter;\n}\n```\n\nAll adapters are initialized from centrally managed configuration. Application code never touches raw provider credentials.\n\n---\n\n## 5. Infrastructure Tools Mapping\n\n### 3.1 Cloudflare Data and Edge Infrastructure\n\n| Tool | v0 Role | Constraints | Access Pattern |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| **D1** | Operational cache: active context, idempotency, projection snapshots, runtime state, edge operational indexes | Not canonical business truth; rebuildable from Postgres/Neon | Server-side via Gateway/Workers; browser never writes D1 directly |\n| **KV** | Short-lived hot projections, sessions, connector status, invalidation state | Not canonical; transient and cacheable | Server-side; browser sees only projection freshness |\n| **R2** | Large artifacts, generated assets, vector/index files, documents, immutable evidence | S3-compatible API until Cloudflare Worker bindings are available | Server-mediated access only; signed retrieval; never expose raw R2 URLs with credentials |\n| **Vectorize / EmbedGoal** | Embedding storage and retrieval for entities, memories, knowledge chunks | Does not own canonical truth | Server-side embedding pipeline; browser sees only search results |\n\n### 3.2 External Infrastructure\n\n| Tool | v0 Role | Constraints |\n| --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- |\n| **Neon / Postgres** | Canonical durable Spine, relationships, evidence, events, activities, governance artifacts | Sole authoritative source for operational truth |\n| **Vercel Blob** | User documents and images via private access and signed/server-mediated retrieval | Client never holds write tokens |\n| **Upstash Redis** | Cache, transient Twin context, rate limiting, sessions, live workbench state | Not primary database |\n| **Vercel AI Gateway** | Server-side AI model routing, current model catalog, tool execution, structured responses | All AI calls server-side; keys never exposed to browser |\n\n### 3.3 Infrastructure Law\n\n- No browser component writes D1, KV, R2, Vectorize, Neon, Redis, or Blob directly.\n- All data access is server-side, tenant-scoped, auditable, and provider-neutral.\n- D1/KV are operational caches only. Neon/R2 are canonical.\n- Failed live projections must not silently become demo seed data.\n\n---\n\n## 4. Environment Variable Management\n\n### 4.1 Required Environment Variables\n\nAdd these through v0’s environment-variable manager. Do not place credentials in source or chat.\n\n| Variable | Purpose | Owner |\n| -------------------------- | ------------------------- | -------------- |\n| `DATABASE_URL` | Neon/Postgres connection | Backend/DevOps |\n| `BLOB_READ_WRITE_TOKEN` | Vercel Blob access | Backend/DevOps |\n| `UPSTASH_REDIS_REST_URL` | Redis REST endpoint | Backend/DevOps |\n| `UPSTASH_REDIS_REST_TOKEN` | Redis REST token | Backend/DevOps |\n| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare account for R2 | Backend/DevOps |\n| `R2_ACCESS_KEY_ID` | R2 access key | Backend/DevOps |\n| `R2_SECRET_ACCESS_KEY` | R2 secret key | Backend/DevOps |\n| `R2_BUCKET_NAME` | R2 bucket name | Backend/DevOps |\n| `R2_ENDPOINT` | R2 S3-compatible endpoint | Backend/DevOps |\n| `AI_GATEWAY_API_KEY` | Vercel AI Gateway key | Backend/DevOps |\n\n### 4.2 Validation and Status Endpoint\n\nAdd server-only validation and a capability/status endpoint:\n\n```\nGET /api/v1/capabilities/status\n```\n\nReturns:\n\n```json\n{\n \"neon\": { \"configured\": true, \"healthy\": true },\n \"blob\": { \"configured\": true, \"healthy\": true },\n \"redis\": { \"configured\": true, \"healthy\": false, \"reason\": \"timeout\" },\n \"r2\": { \"configured\": true, \"healthy\": true },\n \"aiGateway\": { \"configured\": true, \"healthy\": true }\n}\n```\n\nNo secrets are exposed. Only presence and health.\n\n### 4.3 Secrets Policy\n\n- Secrets never reach client bundles or logs.\n- Unavailable providers degrade to clear setup/error states.\n- Frontend receives only configuration presence and health status.\n\n---\n\n## 5. Server-Side Service Adapters\n\nEach provider sits behind an internal interface so existing resources can be replaced without changing workspace features.\n\n### 5.1 Neon Adapter\n\nResponsibilities:\n\n- Durable Spine entities, relationships, evidence, events, activities\n- Department/role projections\n- Notes, knowledge records, workbench items\n- Audit/activity events\n\nInterface:\n\n```ts\ninterface NeonAdapter {\n query(sql: string, params?: unknown[]): Promise;\n transaction(fn: (client: NeonAdapter) => Promise): Promise;\n}\n```\n\n### 5.2 Blob Adapter\n\nResponsibilities:\n\n- User documents and images\n- Private access\n- Signed/server-mediated retrieval\n\nInterface:\n\n```ts\ninterface BlobAdapter {\n upload(key: string, body: Buffer, contentType: string): Promise;\n signedUrl(key: string, expiresInSeconds: number): Promise;\n}\n```\n\n### 5.3 Redis Adapter\n\nResponsibilities:\n\n- Cache\n- Transient Twin context\n- Rate limiting\n- Sessions\n- Live workbench state\n\nInterface:\n\n```ts\ninterface RedisAdapter {\n get(key: string): Promise;\n set(key: string, value: string, ttlSeconds?: number): Promise;\n del(key: string): Promise;\n}\n```\n\n### 5.4 R2 Adapter\n\nResponsibilities:\n\n- Large artifacts\n- Generated assets\n- Vector/index files\n- Content objects\n\nInterface:\n\n```ts\ninterface R2Adapter {\n put(key: string, body: Buffer, contentType: string): Promise;\n get(key: string): Promise;\n signedGetUrl(key: string, expiresInSeconds: number): Promise;\n}\n```\n\n### 5.5 AI Gateway Adapter\n\nResponsibilities:\n\n- Server-side model routing\n- Current model catalog\n- Tool execution\n- Structured responses\n\nInterface:\n\n```ts\ninterface AIGatewayAdapter {\n complete(prompt: string, options?: { model?: string; tools?: string[] }): Promise;\n stream(prompt: string): Promise>;\n}\n```\n\n### 5.6 Adapter Registry\n\n```ts\ninterface ServiceAdapters {\n neon: NeonAdapter;\n blob: BlobAdapter;\n redis: RedisAdapter;\n r2: R2Adapter;\n aiGateway: AIGatewayAdapter;\n}\n```\n\nAll adapters are initialized server-side from validated environment variables.\n\n---\n\n## 6. Complete End-to-End Schema\n\n### 6.1 Schema Design Rules\n\n- One source of truth per domain.\n- No duplicate tables for the same concept.\n- Tenant isolation enforced on every table.\n- Immutable provenance on canonical entities.\n- Candidate state separated from approved state.\n- Embeddings stored server-side; browser never sees raw vector math.\n\n### 6.2 Canonical Schemas\n\nUse the existing `sql-migrations/081_neon_workbench_spine_v1.sql` as the primary Neon schema source. It already defines:\n\n- `platform.tenants`\n- `platform.tenant_config`\n- `platform.connector_connections`\n- `platform.capabilities`\n- `platform.governance_requests`\n- `platform.outbox_events`\n- `spine.entities`\n- `spine.relationships`\n- `spine.evidence`\n- `spine.events`\n- Plus knowledge, continuity, and product schemas\n\nSupabase migration `supabase/migrations/20260723000001_spine_core.sql` is legacy public-schema parity and must not be treated as concurrent source of truth. Frontend migrations must align with the Neon canonical schema above.\n\n### 6.3 Schema Inventory by Sidebar Section\n\n| Sidebar Section | Primary Tables | Secondary Tables | Schema Owner |\n| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------- |\n| Home | `spine.entities`, `spine.events`, `spine.signals` | `platform.tenant_config` | spine / product |\n| My Work | `spine.entities`, `product.work_items`, `spine.relationships` | `spine.events` | product |\n| Inbox | `spine.entities`, `spine.signals`, `continuity.sessions` | `platform.outbox_events` | spine / continuity |\n| Tasks | `product.tasks`, `product.work_items`, `spine.entities` | `spine.events`, `continuity.sessions` | product |\n| My Queue | `product.work_items`, `platform.outbox_events` | `continuity.sessions` | product / platform |\n| Approvals | `platform.governance_requests`, `spine.events` | `platform.outbox_events` | platform |\n| Notifications | `spine.events`, `continuity.sessions` | `platform.connector_connections` | spine / continuity |\n| Recent Work | `spine.events`, `spine.entities` | `product.work_items` | spine |\n| Favorites | `spine.entities`, `spine.relationships` | `product.work_items` | spine |\n| Communications | `spine.evidence`, `spine.entities`, `knowledge.documents` | `spine.events` | spine / knowledge |\n| Activity Feed | `spine.events`, `spine.activities` | `spine.signals` | spine |\n| Email | `spine.evidence` | `spine.relationships` | spine |\n| Calendar | `spine.entities`, `spine.events` | `spine.signals` | spine |\n| Meetings | `spine.entities`, `spine.events`, `continuity.sessions` | `spine.evidence` | spine / continuity |\n| Chat | `spine.evidence`, `continuity.sessions` | `spine.entities` | spine / continuity |\n| Calls | `spine.evidence`, `spine.events` | `spine.relationships` | spine |\n| Documents Shared | `spine.evidence`, `knowledge.documents` | `r2` artifacts | spine / knowledge |\n| Personal | `spine.entities`, `spine.memories` | `continuity.sessions` | spine / continuity |\n| Notes | `spine.memories`, `spine.evidence` | `r2` artifacts | spine |\n| Knowledge Base | `knowledge.documents`, `knowledge.chunks`, `knowledge.embeddings` | `spine.entities` | knowledge |\n| Brainstorming Sessions | `continuity.sessions`, `spine.memories`, `spine.events` | `knowledge.documents` | continuity / knowledge |\n| Activity | `spine.events`, `spine.activities` | `spine.signals` | spine |\n| Finance Manager | `spine.entities`, `spine.signals`, `spine.events` | `platform.capabilities` | spine |\n| Work - Route Based on Role _ Department _ Industry | `product.workbench_views`, `product.view_registry`, `spine.entities`, `spine.relationships` | `platform.tenant_config` | product |\n| Platform | `platform.capabilities`, `platform.connector_connections`, `platform.tenant_config` | `platform.outbox_events` | platform |\n| Integration Manager | `platform.connections`, `platform.integrations` | `spine.signals` | platform |\n| Connector Marketplace | `spine_connector_registry`, `spine_marketplace_apps`, `spine_app_installs` | `platform.connector_connections` | platform / spine |\n| Activation Hub | `platform.tenant_config`, `platform.connections`, `spine.entities` | `spine.events` | platform |\n| Capability Manager | `platform.capabilities`, `platform.governance_requests` | `platform.outbox_events` | platform |\n| MCP Pool | `platform.mcp_sessions`, `platform.mcp_tools`, `platform.mcp_invocations` | `platform.capabilities` | platform |\n| AI Models | `platform.ai_models`, `platform.ai_usage` | `platform.tenant_config` | platform |\n| Knowledge | `knowledge.documents`, `knowledge.chunks`, `knowledge.embeddings` | `spine.entities` | knowledge |\n| Memory & Continuity | `spine.memories`, `continuity.sessions`, `spine.events` | `platform.governance_requests` | spine / continuity |\n| Automation | `platform.capabilities`, `platform.workflows`, `continuity.sessions` | `platform.outbox_events` | platform |\n| Pipelines | `platform.pipelines`, `platform.pipeline_runs`, `spine.entities` | `spine.events` | platform |\n| Governance | `platform.governance_requests`, `spine.events`, `platform.outbox_events` | `platform.capabilities` | platform |\n| Observability | `spine.events`, `platform.outbox_events`, `spine.signals` | `spine.activities` | spine / platform |\n| Administration | `platform.tenants`, `platform.tenant_config`, `platform.users`, `platform.roles`, `platform.permissions` | `spine.events` | platform |\n| Organizations | `platform.organizations`, `platform.tenant_config` | `spine.entities` | platform |\n| Users | `platform.users`, `platform.workspace_members` | `spine.entities` | platform |\n| Roles | `platform.roles`, `platform.role_scopes` | `platform.tenant_config` | platform |\n| Permissions | `platform.permissions`, `platform.role_scopes` | `platform.capabilities` | platform |\n| Audit | `spine.events`, `platform.audit_log` | `spine.evidence` | spine / platform |\n| Billing | `platform.billing_accounts`, `platform.billing_events` | `platform.tenant_config` | platform |\n| Deployments | `platform.deployments`, `platform.environment_config` | `platform.outbox_events` | platform |\n| API Keys | `platform.api_keys`, `platform.tenants` | `platform.outbox_events` | platform |\n| Security | `platform.security_policies`, `platform.audit_log` | `spine.events` | platform |\n\n### 6.4 Core Table Definitions\n\n#### platform.tenants\n\n```sql\nid TEXT PRIMARY KEY,\ncanonical_id TEXT NOT NULL UNIQUE,\nname TEXT NOT NULL,\nslug TEXT NOT NULL UNIQUE,\nstatus TEXT NOT NULL DEFAULT 'active',\nsettings JSONB NOT NULL DEFAULT '{}',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### platform.tenant_config\n\n```sql\ntenant_id TEXT PRIMARY KEY REFERENCES platform.tenants(id),\nrole TEXT NOT NULL,\ndepartment TEXT NOT NULL,\nindustry TEXT,\nschema_version TEXT NOT NULL DEFAULT 'spine-v1',\nactive_domains TEXT[] NOT NULL DEFAULT '{}',\ndepth_matrix JSONB NOT NULL DEFAULT '{}',\ncapability_policy JSONB NOT NULL DEFAULT '{}',\nonboarding_state TEXT NOT NULL DEFAULT 'active',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### spine.entities\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\ncanonical_id TEXT NOT NULL,\nentity_type TEXT NOT NULL,\nversion INTEGER NOT NULL CHECK (version > 0),\nstatus TEXT NOT NULL DEFAULT 'active',\nname TEXT,\ndomain TEXT,\nindustry TEXT,\nscope JSONB NOT NULL DEFAULT '{}',\ndata JSONB NOT NULL DEFAULT '{}',\nmetadata JSONB NOT NULL DEFAULT '{}',\nprovenance JSONB NOT NULL DEFAULT '{}',\nvalid_from TIMESTAMPTZ NOT NULL DEFAULT now(),\nvalid_until TIMESTAMPTZ,\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\ncreated_by TEXT,\nsearch_document TSVECTOR GENERATED ALWAYS AS (...),\nUNIQUE (tenant_id, canonical_id, version)\n```\n\n#### spine.relationships\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nsource_canonical_id TEXT NOT NULL,\nsource_type TEXT NOT NULL,\ntarget_canonical_id TEXT NOT NULL,\ntarget_type TEXT NOT NULL,\nrelationship_type TEXT NOT NULL,\nconfidence NUMERIC(4,3) NOT NULL DEFAULT 1.0,\nmetadata JSONB NOT NULL DEFAULT '{}',\nvalid_from TIMESTAMPTZ NOT NULL DEFAULT now(),\nvalid_until TIMESTAMPTZ,\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\ncreated_by TEXT\n```\n\n#### spine.evidence\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\ncanonical_id TEXT,\nevidence_type TEXT NOT NULL,\ntitle TEXT NOT NULL,\nexcerpt TEXT,\nsource_provider TEXT,\nsource_reference TEXT,\nstorage_provider TEXT,\nstorage_key TEXT,\nmime_type TEXT,\ncontent_hash TEXT,\nmetadata JSONB NOT NULL DEFAULT '{}',\ncaptured_at TIMESTAMPTZ NOT NULL DEFAULT now(),\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### spine.events\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nsubject_kind TEXT NOT NULL,\nsubject_id TEXT NOT NULL,\ncanonical_id TEXT,\nevent_type TEXT NOT NULL,\nactor_type TEXT NOT NULL,\nactor_id TEXT,\ncorrelation_id TEXT,\nevidence_ids UUID[] NOT NULL DEFAULT '{}',\npayload JSONB NOT NULL DEFAULT '{}',\noccurred_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### platform.governance_requests\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\ncapability_key TEXT NOT NULL,\nsubject_kind TEXT NOT NULL,\nsubject_id TEXT NOT NULL,\nrequested_by TEXT NOT NULL,\nrequest_payload JSONB NOT NULL DEFAULT '{}',\ndecision TEXT NOT NULL DEFAULT 'pending',\ndecided_by TEXT,\ndecision_reason TEXT,\napproval_token TEXT UNIQUE,\nexpires_at TIMESTAMPTZ,\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\ndecided_at TIMESTAMPTZ\n```\n\n#### platform.outbox_events\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nevent_type TEXT NOT NULL,\nsubject_kind TEXT NOT NULL,\nsubject_id TEXT NOT NULL,\ndestination_provider TEXT,\ncapability_key TEXT,\npayload JSONB NOT NULL DEFAULT '{}',\ngovernance_request_id UUID REFERENCES platform.governance_requests(id),\nstatus TEXT NOT NULL DEFAULT 'awaiting_approval',\nattempts INTEGER NOT NULL DEFAULT 0,\nnext_attempt_at TIMESTAMPTZ,\ndelivered_at TIMESTAMPTZ,\nlast_error TEXT,\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### knowledge.documents\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\ntitle TEXT NOT NULL,\nbody TEXT,\nmetadata JSONB NOT NULL DEFAULT '{}',\nstatus TEXT NOT NULL DEFAULT 'draft',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### knowledge.chunks\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ndocument_id UUID NOT NULL REFERENCES knowledge.documents(id),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\ncontent TEXT NOT NULL,\nembedding vector(1536),\nmetadata JSONB NOT NULL DEFAULT '{}',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### spine.memories\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nscope TEXT NOT NULL DEFAULT 'org',\nuser_id TEXT,\nentity_id TEXT,\nkind TEXT NOT NULL DEFAULT 'note',\ntitle TEXT,\ncontent TEXT NOT NULL,\nfields JSONB NOT NULL DEFAULT '{}',\nembedding vector(1536),\nvisibility TEXT NOT NULL DEFAULT 'private',\nsource TEXT NOT NULL DEFAULT 'manual',\nprovenance JSONB NOT NULL DEFAULT '{}',\ncreated_by TEXT,\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### continuity.sessions\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nsession_type TEXT NOT NULL,\nsubject_id TEXT,\nstatus TEXT NOT NULL DEFAULT 'active',\ncontext JSONB NOT NULL DEFAULT '{}',\nresult JSONB NOT NULL DEFAULT '{}',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now()\n```\n\n#### product.workbench_views\n\n```sql\nid UUID PRIMARY KEY DEFAULT gen_random_uuid(),\ntenant_id TEXT NOT NULL REFERENCES platform.tenants(id),\nrole TEXT NOT NULL,\ndepartment TEXT NOT NULL,\nindustry TEXT,\nview_key TEXT NOT NULL,\nview_config JSONB NOT NULL DEFAULT '{}',\ncreated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nupdated_at TIMESTAMPTZ NOT NULL DEFAULT now(),\nUNIQUE (tenant_id, role, department, industry, view_key)\n```\n\n---\n\n## 7. Workspace Data and Action Layer\n\n### 7.1 Data Layer\n\nThe workspace data layer is tenant-aware and server-side.\n\nResponsibilities:\n\n- Define and evolve schemas for users, roles, departments, workbench views, entities, links, notes, knowledge documents, files, actions, Twin suggestions, and audit records\n- Provide route handlers and server actions for real CRUD and workflow operations\n- Enforce tenant, role, department, and cross-functional access boundaries on every server operation\n- Keep all migrations in `migrations/` or `sql-migrations/` with canonical source in `081_neon_workbench_spine_v1.sql`\n\n### 7.2 Action Layer\n\nServer actions and route handlers must:\n\n- Require authenticated tenant context\n- Validate tenant and role membership before every operation\n- Emit `spine.events` for every meaningful mutation\n- Write canonical state only through governed contracts\n- Return projected responses, never raw internal tables\n\n### 7.3 CRUD Contracts\n\n| Action | Method | Path | Contract |\n| ----------------------- | ------ | -------------------------------- | ---------------------- |\n| List entities | GET | `/api/v1/entities` | Projection response |\n| Get entity | GET | `/api/v1/entities/:id` | Entity 360 projection |\n| Create entity | POST | `/api/v1/entities` | Governed creation |\n| Update entity | PATCH | `/api/v1/entities/:id` | Governed mutation |\n| List tasks | GET | `/api/v1/tasks` | Task projection |\n| Create task | POST | `/api/v1/tasks` | Governed creation |\n| Update task | PATCH | `/api/v1/tasks/:id` | Governed mutation |\n| List memories | GET | `/api/v1/memories` | Memory projection |\n| Create memory candidate | POST | `/api/v1/memory/candidates` | Candidate only |\n| List knowledge | GET | `/api/v1/knowledge` | Knowledge projection |\n| Upload artifact | POST | `/api/v1/artifacts` | Signed server-mediated |\n| List approvals | GET | `/api/v1/approvals` | Approval projection |\n| Decide approval | POST | `/api/v1/approvals/:id/decision` | Governed decision |\n| Twin interact | POST | `/api/v1/twin/interact` | Twin contract |\n| Agent create task | POST | `/api/v1/agents/:id/tasks` | Governed delegation |\n| Continuity status | GET | `/api/v1/continuity` | Continuity projection |\n\n---\n\n## 8. Connect the UI to Real Workspace Behavior\n\n### 8.1 Replacement Rules\n\nReplace fixture-only and static-dashboard behavior with persistent flows:\n\n- Notes: CRUD via `/api/v1/memories` and `/api/v1/memory/candidates`\n- Knowledge Base: CRUD via `/api/v1/knowledge` with chunking and embedding pipeline\n- Files/Content: Upload/download via `/api/v1/artifacts` through Blob/R2 adapters\n- Workbench interactions: All routed through projection APIs\n- Pipeline/Account/Entity detail: Open working surface with related records, files, meetings, tasks, actions aggregated from connected tools\n- Twin: Contextual inside each work surface; proactive, source-linked suggestions; explicit user-controlled execution\n\n### 8.2 Role-Department-Industry Routing\n\nWork section routing:\n\n```text\nlogged-in role + department + industry\n ↓\nproduct.workbench_views lookup\n ↓\nview_config projection\n ↓\ndomain/entity task routing\n ↓\nentity detail surface with related records\n```\n\n### 8.3 Twin Contextual Integration\n\nTwin is not a separate chat sidebar. Twin is contextual inside each work surface:\n\n- Proactive suggestions based on current entity/task/document\n- Source-linked evidence\n- Explicit user-controlled execution\n- Continuity state visible in context\n\n---\n\n## 9. MCP Connector Boundary\n\n### 9.1 Local Implementation\n\n- Implement and test the MCP connector contract locally in the project\n- Use the supplied IntegrateWise MCP URL and tenant context only through server-side configuration\n- Add provider health checks, capability discovery, tenant envelopes, auditable tool execution, and safe failure states\n\n### 9.2 Public Contract\n\nThe public MCP remains the 19-tool Spine contract only:\n\n1. `get_my_continuity`\n2. `get_active_context`\n3. `get_my_focus`\n4. `get_context`\n5. `get_changes`\n6. `get_related`\n7. `get_history`\n8. `get_commitments`\n9. `get_decisions`\n10. `get_permitted_memory`\n11. `get_relevant_knowledge`\n12. `ask_twin`\n13. `assign_twin`\n14. `get_prepared_work`\n15. `get_available_actions`\n16. `prepare_action`\n17. `get_action_plan`\n18. `approve_action`\n19. `store_in_spine`\n\n### 9.3 Marketplace Block\n\nMarketplace publication/install remains a separate release step blocked until the Vercel team suspension is resolved or an active team owns the listing. No workaround or replacement account will be created.\n\n---\n\n## 10. Sidebar Structure to Schema Mapping\n\nThis is the definitive mapping of every sidebar item to backend tables, services, and API contracts.\n\n### 10.1 Top-Level Navigation\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |\n| Home | `spine.entities`, `spine.events`, `spine.signals`, `platform.tenant_config` | `gateway`, `spine`, `projection-engine`, `store`, `signals` | `SharedWorkbench`, `/api/v1/projections/workspace` |\n| My Work | `spine.entities`, `product.work_items`, `spine.relationships` | `gateway`, `spine`, `projection-engine`, `task-management` | `/api/v1/projections/workspace`, `/api/v1/tasks` |\n| Inbox | `spine.entities`, `spine.signals`, `continuity.sessions`, `platform.outbox_events` | `gateway`, `spine`, `signals`, `continuity` | `/api/v1/signals`, `/api/v1/continuity` |\n| Tasks | `product.tasks`, `product.work_items`, `spine.entities`, `spine.events` | `gateway`, `spine`, `task-management`, `workflow` | `/api/v1/tasks`, `/api/v1/projections/entity/:id` |\n| My Queue | `product.work_items`, `platform.outbox_events`, `continuity.sessions` | `gateway`, `workflow`, `task-management`, `continuity` | `/api/v1/continuity`, `/api/v1/tasks` |\n| Approvals | `platform.governance_requests`, `spine.events`, `platform.outbox_events` | `gateway`, `govern`, `workflow`, `task-management` | `/api/v1/approvals`, `/api/v1/approvals/:id/decision` |\n| Notifications | `spine.events`, `continuity.sessions`, `platform.connector_connections` | `gateway`, `spine`, `continuity`, `signals` | `/api/v1/signals`, `/api/v1/continuity` |\n| Recent Work | `spine.events`, `spine.entities`, `product.work_items` | `gateway`, `spine`, `projection-engine` | `/api/v1/projections/workspace` |\n| Favorites | `spine.entities`, `spine.relationships`, `product.work_items` | `gateway`, `spine`, `projection-engine` | `/api/v1/projections/workspace` |\n\n### 10.2 Communications\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ---------------- | ------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |\n| Activity Feed | `spine.events`, `spine.activities`, `spine.signals` | `gateway`, `spine`, `signals`, `telemetry` | `/api/v1/signals`, `/api/v1/events` |\n| Email | `spine.evidence`, `spine.relationships` | `gateway`, `spine`, `projection-engine` | `/api/v1/projections/entity/:id` |\n| Calendar | `spine.entities`, `spine.events`, `spine.signals` | `gateway`, `spine`, `projection-engine`, `workflow` | `/api/v1/projections/entity/:id` |\n| Meetings | `spine.entities`, `spine.events`, `continuity.sessions`, `spine.evidence` | `gateway`, `spine`, `continuity`, `projection-engine` | `/api/v1/projections/entity/:id` |\n| Chat | `spine.evidence`, `continuity.sessions`, `spine.entities` | `gateway`, `spine`, `continuity` | `/api/v1/projections/entity/:id` |\n| Calls | `spine.evidence`, `spine.events`, `spine.relationships` | `gateway`, `spine` | `/api/v1/projections/entity/:id` |\n| Documents Shared | `spine.evidence`, `knowledge.documents`, `r2` artifacts | `gateway`, `spine`, `knowledge`, `store` | `/api/v1/artifacts`, `/api/v1/projections/entity/:id` |\n\n### 10.3 Personal\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ---------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |\n| Notes | `spine.memories`, `spine.evidence`, `r2` artifacts | `gateway`, `spine`, `continuity`, `store` | `/api/v1/memories`, `/api/v1/artifacts` |\n| Knowledge Base | `knowledge.documents`, `knowledge.chunks`, `knowledge.embeddings`, `spine.entities` | `gateway`, `spine`, `knowledge`, `mcp-connector` | `/api/v1/knowledge`, public MCP `get_relevant_knowledge` |\n| Brainstorming Sessions | `continuity.sessions`, `spine.memories`, `spine.events`, `knowledge.documents` | `gateway`, `continuity`, `knowledge`, `intelligence` | `/api/v1/twin/interact`, `/api/v1/memory/candidates` |\n| Activity | `spine.events`, `spine.activities`, `spine.signals` | `gateway`, `spine`, `signals` | `/api/v1/signals`, `/api/v1/events` |\n\n### 10.4 Finance Manager\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| --------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |\n| Finance Manager | `spine.entities`, `spine.signals`, `spine.events`, `platform.capabilities` | `gateway`, `spine`, `projection-engine`, `govern` | `/api/v1/projections/workspace`, `/api/v1/capabilities` |\n\n### 10.5 Work - Route Based on Role _ Department _ Industry\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------- |\n| Work (View 1..View N) | `product.workbench_views`, `product.view_registry`, `spine.entities`, `spine.relationships`, `platform.tenant_config` | `gateway`, `spine`, `projection-engine`, `store` | `/api/v1/projections/workspace`, `SharedWorkbench` contract |\n\nRouting rule:\n\n```text\nauth.role + auth.department + tenant.industry\n ↓\nproduct.workbench_views\n ↓\nview_config\n ↓\ndomain projection\n```\n\n### 10.6 Platform\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| --------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------- |\n| Integration Manager | `platform.connections`, `platform.integrations`, `spine.signals` | `gateway`, `connector`, `integration-management-mcp`, `provider-management-mcp` | `/api/v1/connections`, `/api/v1/integrations` |\n| Connector Marketplace | `spine_connector_registry`, `spine_marketplace_apps`, `spine_app_installs`, `platform.connector_connections` | `gateway`, `integration-management-mcp`, `mcp-pool` | `/api/v1/marketplace/apps`, `/api/v1/connections` |\n| Activation Hub | `platform.tenant_config`, `platform.connections`, `spine.entities`, `spine.events` | `gateway`, `tenants`, `pipeline`, `spine` | `/api/v1/activation/complete-onboarding` |\n| Capability Manager | `platform.capabilities`, `platform.governance_requests`, `platform.outbox_events` | `gateway`, `mcp-pool`, `integration-management-mcp`, `govern` | `/api/v1/capabilities`, `/api/v1/approvals` |\n| MCP Pool | `platform.mcp_sessions`, `platform.mcp_tools`, `platform.mcp_invocations`, `platform.capabilities` | `gateway`, `mcp-connector`, `mcp-pool` | Internal `/api/v1/mcp/*` only; admin observability only |\n| AI Models | `platform.ai_models`, `platform.ai_usage`, `platform.tenant_config` | `gateway`, `intelligence`, `hermes`, `iw-agent-runtime` | `/api/v1/models`, `/api/v1/ai/usage` |\n\n### 10.7 Knowledge\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |\n| Knowledge | `knowledge.documents`, `knowledge.chunks`, `knowledge.embeddings`, `spine.entities` | `gateway`, `spine`, `knowledge`, `mcp-connector` | `/api/v1/knowledge`, public MCP `get_relevant_knowledge` |\n\n### 10.8 Memory & Continuity\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |\n| Memory & Continuity | `spine.memories`, `continuity.sessions`, `spine.events`, `platform.governance_requests` | `gateway`, `spine`, `continuity`, `knowledge`, `govern` | `/api/v1/memory`, `/api/v1/memory/candidates`, `/api/v1/continuity` |\n\n### 10.9 Automation\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |\n| Automation | `platform.capabilities`, `platform.workflows`, `continuity.sessions`, `platform.outbox_events` | `gateway`, `mcp-pool`, `integration-management-mcp`, `govern`, `hermes`, `workflow` | `/api/v1/capabilities`, `/api/v1/continuity` |\n\n### 10.10 Pipelines\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------ | -------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------- |\n| Pipelines | `platform.pipelines`, `platform.pipeline_runs`, `spine.entities`, `spine.events` | `gateway`, `pipeline`, `connector`, `normalizer` | `/api/v1/pipelines`, `/api/v1/projections/entity/:id` |\n\n### 10.11 Governance\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------- |\n| Governance | `platform.governance_requests`, `spine.events`, `platform.outbox_events`, `platform.capabilities` | `gateway`, `govern`, `workflow`, `task-management` | `/api/v1/approvals`, `/api/v1/approvals/:id/decision` |\n\n### 10.12 Observability\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------- |\n| Observability | `spine.events`, `platform.outbox_events`, `spine.signals`, `spine.activities` | `gateway`, `spine`, `signals`, `telemetry`, `workflow` | `/api/v1/signals`, `/api/v1/events` |\n\n### 10.13 Administration\n\n| Sidebar Item | Tables | Backend Services | API Contract |\n| ------------- | -------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------- |\n| Organizations | `platform.organizations`, `platform.tenant_config`, `spine.entities` | `gateway`, `admin`, `tenants` | `/api/v1/admin/organizations` |\n| Users | `platform.users`, `platform.workspace_members`, `spine.entities` | `gateway`, `admin`, `tenants` | `/api/v1/admin/users` |\n| Roles | `platform.roles`, `platform.role_scopes`, `platform.tenant_config` | `gateway`, `admin`, `tenants` | `/api/v1/admin/roles` |\n| Permissions | `platform.permissions`, `platform.role_scopes`, `platform.capabilities` | `gateway`, `admin`, `tenants` | `/api/v1/admin/permissions` |\n| Audit | `spine.events`, `platform.audit_log`, `spine.evidence` | `gateway`, `spine`, `admin`, `govern` | `/api/v1/audit/events` |\n| Billing | `platform.billing_accounts`, `platform.billing_events`, `platform.tenant_config` | `gateway`, `billing`, `tenants` | `/api/v1/admin/billing` |\n| Deployments | `platform.deployments`, `platform.environment_config`, `platform.outbox_events` | `gateway`, `admin`, `telemetry` | `/api/v1/admin/deployments` |\n| API Keys | `platform.api_keys`, `platform.tenants`, `platform.outbox_events` | `gateway`, `admin`, `tenants` | `/api/v1/admin/api-keys` |\n| Security | `platform.security_policies`, `platform.audit_log`, `spine.events` | `gateway`, `admin`, `govern` | `/api/v1/admin/security` |\n\n---\n\n## 11. Twin Mapping by Sidebar\n\nTwin is available across all operational routes. Twin actions, memory use, capability resolution, and continuity state are mapped per section in Section 10.\n\nCanonical Twin actions:\n\n- Ask: reads context, memory, knowledge; no writes\n- Analyze: reads projections and evidence; optional agent read\n- Recommend: resolves capabilities; policy preview only\n- Plan: resolves capabilities and agents; draft only, no write\n- Delegate: creates agent task; assigns context and capabilities; continuity checkpoint\n- Act: invokes governed capability; requires approval when policy demands\n- Continue: resumes continuity workflow; reconciles state\n- Review: inspects governance, execution, memory, evidence\n- Remember: creates memory candidate; requires triage approval\n\n---\n\n## 12. Agent Mapping by Sidebar\n\nAgent activation occurs only through Twin or governed workflow.\n\n| Sidebar Section | Agent Responsibility | Backend Service |\n| --------------- | ----------------------------------------------------------------- | ------------------------------------------- |\n| Agents surface | Agent selection, task creation, capability assignment, monitoring | `agent-registry`, `iw-agent-runtime` |\n| Delegated work | Execution monitoring, outcome summary, learned outcomes | `task-management`, `workflow`, `continuity` |\n| Twin handoff | Agent results returned to Twin for summarization and triage | `intelligence`, `hermes` |\n| Twin sidebar | Agent status within Twin context | `iw-agent-runtime`, `continuity` |\n\nAgent invariants:\n\n- Agents do not read canonical Spine directly.\n- Agents do not write canonical state.\n- Agents do not promote their own memory.\n- Agents do not approve their own actions.\n- Agents may not bypass Twin, Governance, or Triage.\n\n---\n\n## 13. Memory Mapping by Sidebar\n\n| Sidebar Section | Memory Scope | Backend Table | Promotion Path |\n| ---------------------- | --------------------------------- | ----------------------------------------- | ------------------------------------------ |\n| Notes | Personal Memory, User Work Memory | `spine.memories` | Candidate → Triage → Governance → Approved |\n| Knowledge Base | Organization Memory | `knowledge.documents`, `knowledge.chunks` | Candidate → Triage → Pipeline → Spine |\n| Brainstorming Sessions | Candidate Memory | `continuity.sessions`, `spine.memories` | Candidate → Triage |\n| Memory & Continuity | All scopes | `spine.memories`, `continuity.sessions` | Candidate → Triage → Governance |\n| Twin sidebar | Relevant memory refs | `spine.memories` | Read-only projection |\n\n---\n\n## 14. Continuity Mapping by Sidebar\n\n| Sidebar Section | Continuity State | Backend Table | User-Facing Language |\n| --------------- | ------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ |\n| My Queue | queued, waiting-approval | `product.work_items`, `platform.outbox_events` | Twin is continuing this work |\n| Approvals | waiting-approval | `platform.governance_requests` | Twin needs your decision |\n| Continuity | scheduled, running, retrying, paused, completed, failed | `continuity.sessions`, `workflow` | Twin is working / waiting / retrying / completed |\n| Notifications | continuity updates | `spine.events`, `continuity.sessions` | Twin completed the delegated work |\n| Twin sidebar | active continuity IDs | `continuity.sessions` | Twin will resume after dependency completes |\n\n---\n\n## 15. Capability Mapping by Sidebar\n\n| Sidebar Section | Capability Responsibility | Backend Table | Backend Service |\n| ----------------------------- | ------------------------------------- | --------------------------------------------- | ---------------------------------------- |\n| Platform / Capability Manager | Discovery, enablement, policy | `platform.capabilities` | `mcp-pool`, `integration-management-mcp` |\n| Twin sidebar | Resolve, invoke, monitor, summarize | `platform.capabilities` | `mcp-pool`, `govern`, `hermes` |\n| Automation | Workflow and capability orchestration | `platform.workflows`, `platform.capabilities` | `workflow`, `mcp-pool`, `govern` |\n| Governance | Approval-required capabilities | `platform.governance_requests` | `govern`, `workflow` |\n\nCapability Registry hidden fields:\n\n- Execution target\n- Risk classification\n- Approval requirements\n- Audit requirements\n\n---\n\n## 16. Spine Network Mapping by Sidebar\n\n| Sidebar Section | Spine Network Responsibility | Backend Tables | Backend Services |\n| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |\n| Home | Governed read models, Entity 360, timeline, tasks, signals | `spine.entities`, `spine.relationships`, `spine.signals`, `spine.events` | `spine`, `projection-engine`, `store`, `gateway` |\n| Work | Entity and relationship projections | `spine.entities`, `spine.relationships`, `spine.events` | `spine`, `projection-engine` |\n| Knowledge | Knowledge entities and chunks | `knowledge.documents`, `knowledge.chunks`, `spine.entities` | `knowledge`, `spine` |\n| Memory & Continuity | Memory and session projections | `spine.memories`, `continuity.sessions`, `spine.events` | `spine`, `continuity` |\n| Administration | Tenant config, schema config, connection config | `platform.tenants`, `platform.tenant_config`, `platform.connector_connections` | `tenants`, `pipeline`, `spine` |\n\nSpine invariants:\n\n- No browser component writes Neon directly.\n- Pipeline promotion is the sole canonical Spine writer.\n- D1/KV are operational caches only.\n- Failed live projections must not silently become demo seed data.\n\n---\n\n## 17. Duplicate Removal and Canonical Source Rules\n\n- Use `sql-migrations/081_neon_workbench_spine_v1.sql` as the canonical Neon schema.\n- Supabase public schema migration is legacy parity only.\n- Do not create second Spine tables in frontend-owned server routes.\n- Do not duplicate tenant/organization/user schemas across apps.\n- Do not introduce new top-level architecture categories outside the documented 60-core inventory.\n\n---\n\n## 18. Verification and Rollout\n\n### 18.1 Verification Checklist\n\n- [ ] Type checks/build pass\n- [ ] Migration validation against `081_neon_workbench_spine_v1.sql`\n- [ ] Adapter health checks for Neon, Blob, Redis, R2, AI Gateway\n- [ ] CRUD tests for entities, tasks, memories, knowledge, artifacts\n- [ ] Tenant isolation tests for all schemas\n- [ ] AI tool-call tests through AI Gateway adapter\n- [ ] Browser tests for:\n - [ ] Notes\n - [ ] Knowledge Base\n - [ ] File upload\n - [ ] Pipeline/entity detail\n - [ ] Contextual Twin suggestions\n - [ ] Role-based workbench routing\n- [ ] Confirm secrets never reach client bundles or logs\n- [ ] Confirm unavailable providers degrade to clear setup/error states\n\n### 18.2 Rollout Sequence\n\n1. Merge backend adapters and validation endpoint\n2. Apply canonical migrations\n3. Wire frontend to real APIs by sidebar section\n4. Enable Twin contextual surfaces\n5. Enable memory, triage, agent, continuity, and capability surfaces\n6. Remove provisional frontend-owned provisioning APIs\n7. Validate marketplace publication prerequisites without publishing\n\n### 18.3 Post-Vercel Restoration\n\nAfter Vercel access is restored:\n\n- Sync environment variables\n- Deploy and verify production bindings\n- Complete Marketplace publication flow\n\n---\n\n## 19. Constraints\n\n- Existing resources are connected by credentials; no new provider account is created automatically.\n- Cloudflare Workers/bindings cannot be provisioned from this project without Cloudflare account authorization; this phase uses R2 through its S3-compatible server API. Worker deployment follows once Cloudflare access is available.\n- Vercel Marketplace installation and MCP listing publication cannot complete while the owning Vercel team is suspended.\n- All data access is server-side, tenant-scoped, auditable, and provider-neutral.\n- L1/L2/L4/L7 must not appear as user-facing product navigation.\n- Legacy runtime aliases must not be introduced as new canonical frontend dependencies.\n\n---\n\n## 20. Acceptance Criteria\n\n### 20.1 Frontend Ownership\n\n- No provider SDK imported in frontend\n- No direct provider API calls\n- No direct canonical database reads\n- No service-role credentials in frontend runtime\n- No direct Spine writes\n- No direct memory promotion\n- No direct agent capability invocation outside platform contracts\n\n### 20.2 Twin\n\n- Twin is available across all operational Workbench routes\n- Twin receives active context\n- Twin responses include evidence\n- Twin can propose actions\n- Twin can delegate to agents\n- Twin displays continuity state\n- Twin submits candidates to Triage\n\n### 20.3 Agents\n\n- Agent activation occurs only through Twin or governed workflow\n- Agent receives bounded context\n- Agent receives explicit capabilities\n- Agent execution is auditable\n- Agent cannot write canonical state\n- Agent result returns to Twin\n\n### 20.4 Memory\n\n- All memory is scoped\n- Candidate memory is distinguishable from approved memory\n- Promotion requires Triage\n- Organisation memory requires governance\n- Agent memory is isolated by run and policy\n\n### 20.5 Capabilities\n\n- Capabilities are business-oriented\n- Every capability declares risk\n- Every write capability passes policy\n- Destructive capability requires approval\n- Execution results produce evidence\n\n### 20.6 Continuity\n\n- Long-running work survives a user session\n- Approval waits are durable\n- Retry state is visible\n- Agent pause/resume is supported\n- Completion returns to Twin\n\n### 20.7 Spine\n\n- Canonical writes pass through governed mutation contracts\n- Every write includes provenance\n- Projections refresh after approved changes\n- Twin and agents only read projections\n"}