{"slug":"platform/13-marketplace-onboarding-and-persona-architecture","title":"IntegrateWise — Marketplace Onboarding & Persona Architecture (Final Spec)","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/13-marketplace-onboarding-and-persona-architecture.mdx","bytes":107390,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **EXTRACTED / NOT CANONICAL.** Useful marketplace/persona source material, but\n> its L1–L4, permanent Twin panel, Descope, D1-canonical and schema-variant\n> language is superseded. Current marketplace and frontend contracts live in\n> [`../architecture/CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`](../architecture/CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md)\n> and\n> [`../architecture/FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md`](../architecture/FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md).\n\n## The Threshold Question First\n\nDoes ChatGPT pass the user's role, department, or industry when they install an IntegrateWise app from its marketplace?\n\n**No. Marketplace OAuth passes identity only, never business context.**\n\nWhat `ChatGPT's` app-install OAuth (and Claude's connector OAuth, and Perplexity's app OAuth) actually return to IntegrateWise:\n\n| OAuth claim                        | Source                                                                         | What we get                           | What it does                                           |\n| ---------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------ |\n| `email`                            | User's ChatGPT account                                                         | ✅ Yes                                | Anchor for tenant user record                          |\n| `name`                             | User's ChatGPT account                                                         | ✅ Yes                                | Display label                                          |\n| `sub` (assistant-internal user-id) | ChatGPT's app framework                                                        | ✅ Yes                                | Stable user-id across re-installs                      |\n| `picture`                          | ChatGPT profile                                                                | ✅ Yes                                | Avatar                                                 |\n| Tenant-domain claim (org claim)    | Sometimes — only if user is on ChatGPT Enterprise with org directories enabled | ⚠️ Maybe                              | Most marketplace installs do not pass this             |\n| Business role (Sales/CS/RevOps…)   | —                                                                              | ❌ No                                 | ChatGPT has no concept of business role                |\n| Department                         | —                                                                              | ❌ No                                 | ChatGPT does not know org structure                    |\n| Industry                           | —                                                                              | ❌ No                                 | Not in any OAuth scope ChatGPT provides                |\n| Company name / size                | —                                                                              | ❌ No                                 | Not in any OAuth scope                                 |\n| Tools the user wants to connect    | —                                                                              | ❌ No (user selects after onboarding) | Connector auth is a separate OAuth round-trip per tool |\n\nChatGPT — and every other marketplace in the model — is an **AI assistant**, not an **identity provider**. It authenticates _who you are on that assistant_. It does not authenticate _who you are at your company_.\n\nThis means the marketplace entry path cannot resolve Spine Context, cannot hydrate RBAC, cannot hydrate `tenant_spine_config`, and cannot derive the persona-shaped workbench without an **onboarding phase**. The onboarding is not optional. It is the architectural bridge between OAuth and Spine.\n\n---\n\n## The Onboarding Phase — The Bridge Between Marketplace OAuth and Inline Capability\n\nThe onboarding phase has three sequential duties, each with a hard architectural contract:\n\n### Duty 1 — Capture persona context the marketplace cannot provide\n\nThe onboarding interstitial must capture, in this exact order:\n\n1. **Use Case** — Personal / Work / Business. This decides the workspace model (single-user vs. tenant).\n2. **Industry** — one of 11 (SaaS/Tech, Professional Services, Healthcare, Education, Manufacturing, Automotive, Retail/Commerce, Financial Services, Logistics, Media, Public Sector) + Other with freeform. This decides the **base resource layer** of the Spine (entity vocabulary, compliance flags, vertical connectors).\n3. **Department** — one of 12 (Sales, Marketing, RevOps, Customer Success, Support, Engineering, Product, Finance, Legal, HR, Supply Chain, Service Operations). This decides the **functional trait** layer (KPI set, connector suggestions, dashboard module set, Twin greeting lineage).\n4. **Sub-role** — department-scoped (e.g. Sales→AE/SDR/Manager; CS→CSM/CS-Lead/VP; HR→HRBP/HR-Ops/CHRO; Eng→IC/Manager/Director/VP). This decides the **default Twin greeting** template, the **default capability set** on the workbench, and the **default governance posture** (what auto-executes vs. what surfaces).\n5. **Company-size tier** — 1–10, 11–50, 51–200, 201–500, 501–1k, 1k–5k, 5k+. This decides connector quotas, default sync cadence (5-min free vs. 15-min enterprise), and Twin proposal volume cap.\n6. **Connectors** — minimum the Continuity Bridge (logged-in user as identity source), then up to 5 storage connectors (Google Drive, OneDrive, Notion, Confluence, Slack History), MCP servers (the user's existing MCPs), AI providers (Claude/GPT/Gemini routing prefix), and Native Connectors (CRM, support, etc.) **None of which the marketplace OAuth can pre-resolve.**\n\n### Duty 2 — Hydrate RBAC\n\nSpine Context cannot exist without a `role` on the user record. The single artifact the onboarding commits is:\n\n```\nrbac_users:        { user_id, tenant_id, role_id, level, scope }\nrbac_roles:        { role_id, tenant_id, name, capabilities[], inherits[] }\nrbac_permissions:  { perm_id, name, scope, gate_posture }\n```\n\nThe first user (always the installer) gets `role = owner` by default. The role determines **which capabilities the Twin can invoke without escalating** — and the Twin only sees the persona's capability set, never another department's. The Maya persona (Sales/AE) cannot onboard an HRBP capability. The Nadia persona (HR/HRBP) cannot onboard a Rollback Engineering capability. **RBAC scoping is the persona barrier.**\n\n### Duty 3 — Hydrate the tenant schema (`tenant_spine_config`)\n\nThe 12 × 11 matrix is encoded into a single row:\n\n```\ntenant_spine_config:\n  tenant_id         UUID  PK\n  industry          TEXT  -- 11 valid values + Other\n  department        TEXT  -- 12 valid values\n  sub_role          TEXT  -- persona-derived\n  user_type         TEXT  -- personal | business | executive\n  company_size      TEXT  -- 1-10..5k+\n  enabled_entities  TEXT[] -- derived from industry × department\n  north_star_metric TEXT  -- derived from department\n  schema_version    TEXT\n  governance_posture JSONB -- default sync modes, default confidence thresholds, default capability gates per persona\n  twin_greeting_id  TEXT  -- which GREETING_LINES entry to fire on first surface\n```\n\nThis row is the **single artifact that makes the rest of the platform persona-shaped**. Commit it once during onboarding. Every projection, every Twin greeting, every capability surfacing, every morning brief reads from this row.\n\n### Where the onboarding runs (UX location)\n\nPer the doctrine (\"Distribution is ingress\"): the onboarding interstitial **runs inside the marketplace trial**, not after the user bounces to a separate web app. Two viable implementations:\n\n- **(A) MCP tool-based onboarding** — `iw.onboard` tool with structured input schema (input rendered by ChatGPT), simple/cross-assistant but constrained by ChatGPT's form affordances.\n- **(B) Webview interstitial** — short redirect to `app.integratewise.ai/onboard?jwt=…`, full 4-step wizard reused from the web app, post-completion the webview posts back and the Marketplace MCP reconnects with `onboarding_complete=true`.\n\nRecommended: **Option B** — reusable, full UI depth, single component (`apps/web/src/components/activation/onboarding/`), no ChatGPT-form dependency.\n\n### The connector onboarding exception\n\nOAuth against an external tool (Salesforce, HubSpot, Slack, Zendesk) **cannot run inside ChatGPT** because that requires a SaaS-provider consent screen, not an AI-assistant one. The onboarding step that says \"Connect your world\" runs the **Descope outbound connection authorization** (canonical authorization authority where supported; Nango retained as dormant compatibility for providers Descope outbound does not yet support), which redirects out of the marketplace (specifically by OAuth design) to Salesforce/HubSpot/Slack's own consent pages. This is per-tool, per-tenant, with `connectionId = tenant_id` for isolation.\n\nThe five-minute gating holds: OAuth (5s) → Onboarding interstitial (60s) → First connector Nango OAuth (45s) → Creamy layer pull + Pipeline 8 stages + Spine writes (60s under p99 2-second normalizer) → Dashboard renders. **Under 5 minutes from \"Add IntegrateWise\" to first data on the workbench.**\n\n---\n\n## Point 1 — Initial Onboarding (4–7 Step, Persona-Shaped)\n\n### What the code defines\n\n`onboarding-flow.tsx` canonically implements a 4-step wizard:\n\n1. **Workspace Type** — Personal / Work / Business\n2. **Profile** — Industry (11 options) + Department (12 grouped) + Company Size\n3. **Goals** — Primary goal (organize / insights / context / team / automate / docs) + Workspace Name\n4. **Connect** — 5 connector groups (Continuity Bridge required; Nango OAuth; MCP; AI Providers; API/Custom)\n\n### What the v2 doctrine specifies (S1–S9 phases behind the wizard)\n\n| Phase                           | System event                                        | Persona artifact                                 |\n| ------------------------------- | --------------------------------------------------- | ------------------------------------------------ |\n| S1 — Identity                   | Gateway RS256 JWT issued                            | User record + tenant_id                          |\n| S1 — Org Discovery              | Use Case + Industry + Department → canonical domain | `tenant_spine_config` row                        |\n| S1 — Reality Connections        | Nango OAuth + MCP + API tagged Flow A/B/C           | Connector records with sync-mode defaults        |\n| S2–S5 — Spine Hydration         | Creamy layer (60s) → 8-stage Pipeline → D1 Spine    | Persona-shape workbench (not empty)              |\n| S7 — Memory Activation          | Continuity pipeline begins                          | Conversation/Org/Personal memory live            |\n| Gateway — Projection Generation | Spine Context → nav, modules, entity views, metrics | L1 Workbench renders                             |\n| S8 — Governance Activation      | HARD GATE live                                      | AI may think/propose, never act without approval |\n| S9 — Continuity Activation      | Context shared across every AI, tool, session       | Twin greets first                                |\n\n### What the target 7-step shape refines to\n\nThe spine-architecture-departments doc specifies the _target_ 7-step flow (backend already accepts all 7 fields even if UI is shorter today):\n\n```\nStep 0  Usage Type      personal/work/business       → workspace model\nStep 1  Industry        11 options + Other           → progressive hydration starts\nStep 2  Department/Role 12 grouped + sub-role        → layer department entities + metrics\nStep 3  Company Size    1-5k+ tiers                  → tier + connector suggestions\nStep 4  Tools/Connectors 5 connector groups          → depth_matrix_snapshot, creamy if OAuth done\nStep 5  Desired Outcome primary goal selector        → first AI insights personalisation\nStep 6  Workspace Name  freeform label               → tenant_spine_config final write\n```\n\n### Why this matters for marketplace\n\nMarketplace OAuth cannot pre-seed any of Steps 0–6 except user identity. **Onboarding must run inline in the marketplace trial**, between the OAuth callback and the first data load. **Skipping onboarding = empty, undifferentiated workbench = churn inside the 5-minute window.**\n\n---\n\n## Point 2 — 12 Departments × 11 Industries × Careful Workbench Consolidation\n\n### The matrix\n\n**12 Departments (functional trait layer):**\n\n```\n1.  Sales              → CTX_SALES      Pipeline, deals, accounts, contacts, stakeholders, activity log\n2.  Marketing          → CTX_MARKETING  Content, campaigns, channels, audiences, attribution, assets\n3.  RevOps             → CTX_BIZOPS     Cross-team reconciliation, forecast, quota, coverage, process\n4.  Customer Success   → CTX_CS         Health, renewal, expansion, adoption, NPS, QBR\n5.  Support            → CTX_SUPPORT    Tickets, SLAs, escalations, deflection, agent load\n6.  Engineering        → CTX_TECH       Incidents, deploys, sprints, PRs, on-call, post-mortem\n7.  Product            → CTX_PM         Roadmap, features, adoption, A/B, feedback\n8.  Finance            → CTX_FINANCE    Invoices, recurring rev, comp, budget, audit, tax\n9.  Legal              → CTX_LEGAL      Contracts, NDAs, compliance, disputes, IP\n10. HR                 → CTX_HR         Hiring, comp, flight risk, engagement, performance\n11. Supply Chain       → CTX_SUPPLY_CHAIN Inventory, logistics, vendors, lead time, ETA\n12. Service Operations → CTX_SERVICE_OPS Field service, dispatch, uptime, technicians\n```\n\n**11 Industries (base resource layer):**\n\n```\n1.  SaaS / Technology        arr, mrr, churn_rate, nrr, ltv, cac\n2.  Professional Services    billable_hours, utilization, client_engagement, partner_track\n3.  Healthcare              contracts, hipaa_status, baa, procurement_stage, ehr_id\n4.  Education                enrollment, semester, graduation_rate, cohort, course_id\n5.  Manufacturing            production_line, down_minutes, machine_data, factory_sla\n6.  Automotive               vin, recall, service_history, dealer_id\n7.  Retail / Commerce        sku, order, fulfillment, return_rate, channel_perf\n8.  Financial Services       kyc, regulatory_breach_window, audit_trail, position_id, pii_grade\n9.  Logistics                shipment, route, carrier, eta, exception_code\n10. Media                    content_id, view, watch_time, audience_segment, ad_pacing\n11. Public Sector            case_id, clearance_level, constituent, jurisdiction\n```\n\n### The derivation principle\n\n```\nSpine Schema = f(Industry, Department)\n\nIndustry   = base resource type (entity vocabulary, compliance, vertical connectors)\nDepartment = functional trait     (KPI set, department connectors, module set, Twin greeting)\n```\n\nSo a Sales record in Healthcare ≠ a Sales record in SaaS:\n\n- SaaS Sales: deal with `arr, mrr, churn_risk, technical_blocker`\n- Healthcare Sales: contract with `contract_value, procurement_stage, hipaa_status, baa_id`\n\nSame `deal` entity type, different canonical fields, different compliance posture, different connector set.\n\n### Careful consolidation of workbenches (the design doctrine)\n\nThe workbench _component_ is one set of React components (L1 surface, Entity card, KPI tile, Twin panel, Capability chip). The workbench _data projection_ is persona-shaped. **One codebase, six T0 personas, twelve departments, eleven industries, 132 schema variants derived at runtime — not 132 code paths.**\n\nConsolidation rules:\n\n1. **T0 departments get full Spine schema coverage**: Sales, Marketing, RevOps, CS, Engineering, Finance. These are the marketplace listing doors. ~85% of install volume in year one.\n2. **T1 departments get functional coverage**: Support, Product, HR, Legal, Service Operations.\n3. **T2 departments get lighter coverage**: Supply Chain. Ship in months 12–18 once T0/T1 prove the architecture.\n4. **All 12 × 11 share the same Spine, the same Pipeline, the same Twin engine, the same Memory pipeline, the same Governance gate.** Persona-specific workbench surfaces are projections off the same entity graph.\n\n### Where the matrix lives in code\n\n```\napps/web/src/config/domains/domain-types.ts:\n  - 12 domain projections (sales, marketing, customer-success, etc.)\n  - Each has its own sidebar nav, dashboards, views\n  - Each has a spineProjection (which entities to surface)\n  - Each has suggestedConnectors (per industry)\n  - Each has KPIs (department-specific)\n  - Each has a Twin greeting lineage\n```\n\n`tenant_spine_config` (D1, migration 054) is the per-tenant derivation result.\n\n---\n\n## Point 3 — Daily Motion\n\n### What runs without the user (L0.5 — Always-On Operating Layer)\n\nThe L0.5 layer runs continuously in the background. The user does not invoke it. It produces the morning brief.\n\n| Component                                | Cadence                        | What it produces                                                           |\n| ---------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- |\n| `TwinAgent` Durable Object               | Daily 05:00 cron per tenant    | Yesterday's signal review, morning brief draft, action proposals batched   |\n| `TenantBrainDO`                          | Continuous                     | Pending approvals, active signals, HITL 15-min timeout, pause/resume state |\n| Connector-sync (delta cron)              | 5 min free / 15 min enterprise | Delta pull of changed records from connected tools                         |\n| Connector Nango webhooks                 | Real-time for SaaS support     | `auth.created` triggers creamy immediate sync                              |\n| Pipeline (consolidated normalizer+spine) | Per queue message              | Records normalized + Spine written                                         |\n| Memory Triage Bot                        | Continuous                     | New observations classified (fact/playbook/decision/relationship/noise)    |\n| Memory Evolution                         | Hourly                         | Pattern detection on accumulated observations                              |\n| Twin hydration                           | Per Twin chat open             | Cascade: screens + Spine + memory + conversation → prompt                  |\n| Promotion Queue scan                     | Hourly                         | High-confidence candidates surfaced for user approval                      |\n\n### What the user sees when they open the workbench in the morning\n\nTwelve `GREETING_LINES` entries (one per CTX\\_\\*) shape the morning voice. Each greeting contains four ingredients: `overnight` (what Twin found), `critical` (one thing that can't wait), `invite` (an engagement question), `chips` (3–4 one-click actions).\n\n**Sales (Maya, AE, SaaS):** 06:00 pipeline scout. \"Coverage at 3.1× against 4× — 5 deals slipped, 3 cold >14d. CFO reply waiting on Skyline.\"\n**Customer Success (Sana, CSM, Healthcare):** \"Renewal Watchdog scanned 47 accounts. Mercy Health BAA stalled 18 days at stage 4. Lisa Wong pattern matches 3 prior cases.\"\n**RevOps (Arjun, Lead, Financial Services):** \"6 reconciliation issues pending. 4 deals slipping Q3→Q4 where Accounting has them in Q3. Forecast variance 2.3% from yesterday.\"\n**Marketing (Lila, Content Marketer, Retail):** \"Winter launch post staged in Sanity. Hero image unsigned in DAM. Last teaser pulled 1,400 organic visits — want me to compose launch from Notion draft + assets?\"\n**Engineering (Tomás, EM, Manufacturing):** \"P1 incident on Helix — bulk export timing out 02:14 UTC, deploy correlation 0.83. Rollback candidate ready. Sprint burndown 4 days behind.\"\n**Finance (FP&A):** \"ARR rollup: $1.42M committed, 0.7% variance from yesterday. Three renewal forecast missing rev-rec mapping. NetSuite delta: 4 invoices unsettled.\"\n**HR (Nadia, HRBP, Professional Services):** \"Engagement survey declining 4 weeks in consulting practice. 11 flight-risk people I can defend with evidence — show me the defense?\"\n**Product (PM):** \"Adoption funnel drop at step 3 (post-trial activation). 6 feature requests correlated to the drop. Beta cohort engagement +12% over cohort 1.\"\n**Support (Manager):** \"P0 queue clear. P1 backlog 12. SLA breach risk on 3 enterprise tickets. 1 deflection pattern emerging: 'export to CSV' returning empty rows.\"\n**Legal (Counsel):** \"3 NDAs awaiting counter-signature >48h. 1 contract redline mismatched vs. playbook. Compliance check: SOC2 evidence pack 12 days from due date.\"\n**Supply Chain (Manager):** \"Carrier exception rate +14% on Route-7. Lead time slipped on 2 critical SKUs. Sourcing alternative flagged for Vendor-204.\"\n**Service Operations (Field Manager):** \"4 dispatch slots unassigned in NE region. 1 SLA at risk (customer contract × technician availability). Uptime anomaly on tower 14 resolved.\"\n\n### The invariant\n\n**Every greeting is grounded in the Spine, sourced from the connector canonical state, and acted on by invocation through the Capability Fabric. None of it is fabricated. If Twin cannot defend the greeting (insufficient Spine data, no connector activity in 24h), it says so honestly.**\n\n---\n\n## Point 4 — L1 Layer: Proactive AI Without Re-Asking Context\n\n### The two behaviours, split architecturally\n\n**L1 data load — NOT OODA — mechanical pipeline behaviour.**\n**L1 AI on top of data — OODA — agent behaviour.**\n\nThe L1 workbench renders the Spine projection. This is mechanical:\n\n```\nSpine D1 partition loaded\n     →\n${department}_${industry}_data projection\n     →\nDOMAIN_CONTENT_MAP[domain]\n     →\nWorkbench entity tables, KPI tiles, cards, list views\n     →\nUser sees Maya's Skyline deal, Sana's Mercy Health, Tomás's Helix incident — pre-filled, not empty.\n```\n\nNo AI reasoning, no OODA loop, no agent. **The Pipeline handled it because its content was certain.**\n\nThe moment the user is _looking_ at an entity, AI runs OODA on the data the _user can already see_:\n\n```\nObserve   — Twin reads the entity currently displayed in L1\n            + the L2 signal layer (anomalies, missing-activity, pattern matches)\n            + L4 memory (approved playbooks related to this entity or persona)\nOrient    — pattern matching against historical patterns for this entity type\n            + comparison against the persona's industry × department behaviour norms\n            + risk/expansion probability given the entity's current state\nDecide    — generate a proposal with confidence score\n            + select the right verb: act / surface / wait / discard\nAct       — engine proposes. The user (or governance gate) decides.\n```\n\nThe crucial architectural stance: **observation happens on the screen state, the Spine, the Connector Hub's last sync, and the Memory layer — never via a clarifying question to the user.** If the Twin needs to confirm a date, it reads the entity on screen. If it needs context for the deal, it reads the last assistant-cached conversation. If it needs to know the user role, it reads the JWT + `tenant_spine_config`. **Proactivity is wired, not interrogative.**\n\n**The doctrine v2 names this: \"Continuity over asking. The Twin never re-asks for context that is already on your screen, already in the Spine, already inferred from the conversation, or already established by an earlier action in the session.\"**\n\n### What the user never sees\n\nThe user does not see \"What would you like help with today?\" — the Twin greets first. The user does not see \"Which deal are you asking about?\" — the Twin reasons about the deal on screen. The user does not see \"Can you tell me who you are?\" — the JWT, role, tenant, sub-role are all already minted. The user does not see \"Connect Salesforce first\" without knowing why — the Twin says \"Connect Salesforce to read deal stages for 47 accounts; ten accounts in your commit block on it.\"\n\n### Capability invocations visible inline\n\nThe L1 workbench is a capable surface. Buttons on entity cards are **Capability Fabric invocations**, not navigation. Every capability declares: input schema, output schema, required scopes, allowed sync modes, default confidence threshold, default governance posture, evidence-chain template.\n\n```\nMark Lead Active       → writes to Spine, soft-sync to HubSpot/Salesforce (default)\nUpdate Stage            → writes to Spine, soft-sync to Salesforce (default)\nLog Activity            → writes to Spine, real-sync (governance allows)\nView Contact            → Spine read + LinkedIn enrichment + HubSpot fetch\nCall Contact            → engages dialer (Twilio/Plivo), audit logged\nDraft Outreach          → Twin proposes email body, governance gate, soft-send\nDraft Email Reply       → reads email thread from Gmail, drafts inline\nSchedule Meeting        → writes to Spine + Google Calendar (real-sync)\nUpdate Health Score     → writes to Spine, soft-sync if insurance/compliance\nMark Renewal Risk ↑    → gated, high governance posture for sensitive entities\nSet Red-Time           → requires approval at level ≥ 0.92 confidence\nSync to SFDC (real-time) → audit logged, throughput logged\n```\n\nEach capability is a real registered action on the Capability Fabric. Each has confidence threshold and governance posture by tenant default.\n\n---\n\n## Point 5 — L2/L3 — Twin Interaction, Fully User-Based OODA\n\n### L2 — Intelligence Overlay (Observe + Orient)\n\nThe L2 layer is the read-side OODA. It surfaces pre-emptive intelligence without any LLM call required. It is fast, cached, deterministic where possible.\n\n| L2 element                                   | OODA phase | Source                                                                      |\n| -------------------------------------------- | ---------- | --------------------------------------------------------------------------- |\n| Signals (anomalies, risks, missing-activity) | Observe    | Connector-sync delta feeds + S6 intelligence service scans Spine            |\n| Insights (synthesized observations)          | Orient     | Pattern-matching against historical data + Twin-promoted playbooks          |\n| Think traces (hypothesis candidates)         | Orient     | L4 memory recall against current entity context                             |\n| Context (assembled entity view)              | Orient     | S9 Continuity Bridge assembly                                               |\n| Evidence ribbons                             | Orient     | Source citations: \"via Salesforce\", \"via Zendesk\", \"via Memory 3 weeks ago\" |\n\n**L2 is read-heavy. No mutations. No proposals fired.** A user can promote an L2 insight to a L3 Twin proposal, which transitions the conversation into the full Decide → Act OODA loop.\n\n### L3 — Twin Workbench (full OODA)\n\nL3 is where the Twin reasons, proposes, and waits for human signal. The activation gate fires first:\n\n```\nevaluateActivation:\n  if (memory_records.total < 3) → BLOCK, render hydration message\n  if (memory_records.promoted < 1) → BLOCK, render staging state\n  if (unresolved governance violations) → BLOCK, render audit summary\n  else → PROCEED to context assembly\n```\n\nThis is the **hands-off safety invariant**: Twin will not reason with hallucinated memory.\n\nPassed → parallel context assembly:\n\n```\ngraph LR\nA[User message] --> B[Continuity retrieval]\nB --> C{Activation passed?}\nC -- No --> D[Hydration block]\nC -- Yes --> E[aiSearch: semantic knowledge]\nE --> F[conversationalSearch: past chat sessions]\nF --> G[mcpSearch: connector-spine resources]\nA --> H{Engineering intent?}\nH -- Yes --> I[spineReadEngineering: D1 build_data partitioning]\nH -- No --> J[Skip engineering read]\nE --> K[DO SQLite: 10 warm turns]\nF --> K\nG --> K\nK --> L[Learned profile: daily-reflected communication style]\nL --> M[Construct system prompt]\nM --> N[gatewayChat: LLM inference]\nN --> O[Propose with confidence + evidence + alternatives]\n```\n\n**The activation gate, the hydration assembly, the learned profile — all of these are explicit decisions in the Twin pipeline, not defaults.** Twin speaks first only when its context is defensible.\n\n### Per-persona Twin grammar\n\nThe hydration pipeline is identical across personas. **Inputs are persona-shaped:**\n\n| Persona            | aiSearch sources                           | conversationalSearch scope              | mcpSearch scope                              | Engineering query?                 | DO warm turns     | Learned profile                                                                                             |\n| ------------------ | ------------------------------------------ | --------------------------------------- | -------------------------------------------- | ---------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| Maya (Sales/AE)    | CRM field schema, deal-stage playbooks     | Last 14d of her chat sessions           | Salesforce, HubSpot, Slack, Gmail, Calendar  | No                                 | Her last 10 turns | \"Terse. Action-oriented. Inline next step. No preamble.\"                                                    |\n| Sana (CS/Health)   | BAA playbooks, healthcare compliance notes | Last 21d of her chat + customer threads | Gainsight, Zendesk, Notion, Slack, CertifyMD | No                                 | Her last 10 turns | \"Case-law-style reasoning. Cited evidence. One decision at a time. High caution near PHI.\"                  |\n| Tomás (Eng/Mfg)    | incident-pattern notes, post-mortems       | Last 14d of his chats + Slack on-call   | Jira, PagerDuty, GitHub, Datadog             | **Yes** — spined engineering reads | His last 10 turns | \"Tactical. Time-stamped. Action + rollback candidate + verification step.\"                                  |\n| Nadia (HR/ProServ) | flight-risk playbooks, comp edge patterns  | Last 30d (governance-scoped)            | Workday, Lattice, survey vendor              | No                                 | Her last 10 turns | \"High-censorship. Personal-data confidential. Never surfaces without 0.94+ confidence. One name at a time.\" |\n\n**Same Twin, persona-shaped hydration, persona-shaped grammar, persona-shaped governance.** This is the consolidation.\n\n### The irreducible human agency\n\nEven when the Twin can defend an action with high confidence, it does not execute:\n\n- **High confidence (≥ 0.85)** → auto-approve (governance posture: low-risk entities) or surface with one-click approve (posture: medium-risk entities)\n- **Medium confidence (0.70–0.85)** → surface on My Desk, human reviews\n- **Low confidence (< 0.70)** → discarded\n\nThe Twin is a reasoning layer that proposes. **The human is the decider.** Approval is mid-process, before execution; tokens are mint-bound to tenant, action, scope, confidence, sync mode. Audit-trail mandatory.\n\n---\n\n## Point 6 — Memory Surfaced Inside the Knowledge Layer (L4)\n\n### The 8-layer memory pipeline\n\n```\nL1 Twin Memory (cognitive working memory)\n   ↓ Chat threads, sessions, reasoning chains, conversational data\nL2 Memory Intake (incoming observations)\n   ↓ Slack, meetings, email, docs, chat, voice, agent outputs\nL3 Triage Bot (classify, deduplicate, score)\n   ↓ Is this: memory | noise | policy | fact | decision | relationship\nL4 Memory Evolution (the compounding engine)\n   ↓ Observation → Pattern → Insight → Playbook → Institutional Knowledge\nL5 Promotion Queue (nothing enters org memory automatically)\n   ↓ \"Renewal Risk Pattern\" | Confidence 94% | Evidence 17 accounts | Persona\nL6 Human Approval (the doctrine: Truth you own. AI you rent. Approval in between.)\n   ↓ Approve / Reject / Request Changes / Annotate\nL7 Organizational Memory (durable, curated, governed)\n   ↓ Approved facts, decisions, playbooks, policies, relationships, outcomes\nL8 Knowledge (documents, runbooks, research, templates, SOPs)\n```\n\nThe three-axis separation:\n\n```\nSPINE    = What IS     (truth)        Accounts, contacts, deals, tickets, events\nMEMORY   = What it MEANS (meaning)    \"Silent champion + open P1 = renewal risk\"\nKNOWLEDGE = What we know (docs)       Playbooks, runbooks, SOPs, templates\n```\n\n### What lives where in the UI\n\n`L4` is the **Knowledge & Memory Workbench** — a separate navigation surface. From the spine-doctrine:\n\n```\nTwin (Reasoning Layer)\n├── Chat\n├── Conversations\n├── Sessions\n├── Voice\n├── Working Memory\n├── Agents\n├── Skills\n├── Workflows\n├── Executions\n├── Models\n├── Tools\n└── Logs\n\nContinuity (Meaning Layer)            ← THIS IS WHERE MEMORY LIVES IN THE UI\n├── Intake\n├── Triage\n├── Evolution\n├── Promotion Queue      ← THE single most important surface\n├── Organizational Memory\n├── Knowledge            ← DOCUMENTS, PLAYBOOKS, RUNBOOKS, Sops\n├── Continuity Graph\n└── Metrics\n```\n\nThe Knowledge Layer surfaces memory.\n\n**L4 components:**\n\n- **Semantic search** across org memory + promoted knowledge + documents + Twin chat sessions.\n- **Categories** — Playbooks, SOWs & Contracts, Runbooks, Research, Templates. Visibility: Private / Team / Public.\n- **Memory organization** — tags, categories, promoted knowledge tagged by confidence + evidence-trail.\n- **Governance status** — staging → approved → published. The visual state of every memory card carries its lifecycle state.\n- **Pinned items, full document excerpts, semantic search.**\n\nThe Promotion Queue **is the single most important screen in IntegrateWise**: it is where AI learns, human approves, organization remembers. It is a per-persona queue — Maya sees sales pattern candidates; Sana sees compliance pattern candidates; Nadia sees flight-risk pattern candidates.\n\n### Persona-shaped memory surfacing\n\nThe Knowledge Layer is the same component with persona-shaped data:\n\n- **Maya's L4**: Sales playbooks (negotiation tactics, security-questionnaire patterns, technical-blocker recovery), updated sales SOPs, links to CRM contexts.\n- **Sana's L4**: CS playbooks (renewal motion, BAA patterns, QBR templates), healthcare-compliance guardrails.\n- **Tomás's L4**: incident post-mortems, deploy-window playbooks, on-call rotation SOPs.\n- **Nadia's L4**: flight-risk playbooks, comp-band edge cases, engagement-survey interpretation guides.\n\nThe Twin surface pulls _from_ the Knowledge Layer when constructing proposals. The Memory layer feeds the Twin. The Twin writes _into_ the Intake layer. The Promotion Queue catches what rises. The Knowledge layer stores what stays.\n\n---\n\n## Point 7 — Brainstorming Layer (Twin Memory, Conversational AI Chat Data)\n\n### What it is\n\nThe Brainstorming Layer is the **Twin Memory** layer — cognitive working memory holding conversational AI chat data. It is the _raw material_ the Organizational Memory is built from.\n\nWhat sits in the Brainstorming Layer per persona:\n\n- **Maya**: ChatGPT conversations about her deals, her Airtable notes, her Slack thread participation. These are the conversational artifacts she's already producing.\n- **Sana**: Her Claude conversations about customer escalations, her Notion QBR outlines, her Zendesk ticket analysis chats. Plus memo-style writing she did with Twin.\n- **Lila**: Perplexity research queries about industry trends, her Notion drafts annotated through Twin, her Slack brand channel conversations.\n- **Nadia**: People-confidential conversations she had with Twin or via email — _all governed_: Triage is hit first, only non-PHI pattern fragments survive, and only with approval do they shape Persona memory.\n\n### The flow per Twin chat session\n\n```\nUser message  →  Twin Reasoning (L3)  →  Response (proposal + grounded evidence)\n                  │                          │\n                  ▼                          ▼\n           warm-turns DO SQLite       emitTriageInput(intent + message + proposed)\n                  │                          │\n                  ▼                          ▼\n           conversation_turns table   MEMORY INTAKE QUEUE\n                                         │\n                                         ▼\n                                    TRIAGE BOT\n                                    classify: fact | decision | observation | relationship | noise\n                                    score: confidence 0–1\n                                    derive: persona-tag, industry-tag, evidence ribbon\n\n                                  confidence ≥ 0.85, evidence ≥ 2 sources\n                                         │\n                                         ▼\n                                  EVOLUTION ENGINE\n                                  Observation + Evidence → Pattern candidate\n                                         │\n                                         ▼ (hours/days)\n                                  Promotion Queue entry\n                                  \"Renewal Risk Pattern\"\n                                  Confidence 0.86\n                                  Evidence: 17 accounts across 8 weeks\n                                         │\n                                         ▼\n                                  User approves / rejects / annotates\n                                         │\n                                         ▼\n                                  ORGANIZATIONAL MEMORY\n                                  Now reusable across whole tenant\n```\n\n### Why it is essential and persona-distinct\n\nThe Brainstorming Layer is **the layer where AI's value compounds**. Without it, every Twin chat is ephemeral. With it, every chat session is an observation candidate that _may_ become a knowledge artifact that _will_ serve the whole tenant. **Without the Brainstorming Layer, IntegrateWise is a great AI assistant. With it, IntegrateWise is an AI assistant that builds the company's own institutional intelligence from its actual work.**\n\nPersona distinction: the Triage Bot's classification logic is department-tagged. Maya's chat messages get triaged as [sales: observation|decision|fact|relationship|playbook candidate]. Sana's get [cs: observation|decision|fact|playbook candidate, healthcare: phi_flag]. Tomás's get [eng: incident|deploy-pattern|post-mortem candidate]. Nadia's get [hr: people-observation|playbook candidate, governance: scope-restricted].\n\nWithout the persona tags, the Promotion Queue would be undifferentiated. **The Brainstorming Layer is persona-aware from intake onward.**\n\n---\n\n## Point 8 — AI Chat: Spine-Grounded Insights and Suggestions\n\n### The original doctrine, restored\n\nThe AI Chat was never meant to be \"a chat.\" It was meant to be **a Spine-grounded conversational surface** where every response is:\n\n- Sourced (every claim has a `via` citation)\n- Confidenced (every recommendation shows a `confidence: 0.86` line)\n- Actionable (every reply ends with a one-click capability chip)\n- Proactive (Twin speaks first on entity load; doesn't wait for a question)\n\nThe L3 Twin chat component (per `twin-chat.tsx`) supports `Message` types with:\n\n```\ncontent      — fallback text\nblocks       — callout / entity card / list / reference list / separator\nevidence     — EvidenceSource[] with source + timestamp + confidence\nentity       — EntitySnapshot (inline entity card on the reply)\nmemoryRefs   — which memory entries were used in forming this reply\nmemoryCommit — what was learned from this exchange\nactions      — Approve | View | Link chips on the message\ntable        — inline structured data (headers + rows)\n```\n\n**The scaffolding is intact. The doctrine is intact. What was eroded in later builds:** the live data wiring. Mock greetings, mock evidence, mock entity snapshots. The fresh build must restore live data binding from Spine reads, Connector Hub status, Memory layer promotion state, and Connector canonical state.\n\n### What Spine-grounded chat looks like, per persona\n\n**Maya opens Twin chat, Skyline in panel:**\n\n> _\"Should I move Skyline to Stage 4?\"_\n>\n> **Twin:** \"I am not sure. Here is what I have.\n> **CRM**: stage = Negotiation, last activity 8 days ago.\n> **Slack**: VP Eng asked about SOC 2 Tuesday. No reply yet.\n> **Email**: CFO replied 11:42 PM with one open question — deployment timeline.\n> **Memory (my playbooks)**: You have moved 4 deals to Stage 4 in Q3. In 3/4, buyer's CFO signed off first. In the 4th, the deal slipped.\n>\n> **Recommended action (confidence 0.74)**:\n>\n> 1. Today's reply handles the CFO's deployment timeline question.\n> 2. After CFO replies, move to Stage 4 with a soft SOC 2 follow-up.\n>\n> Chips: [Approve / Revise / Discard]\"\n\n**Sana opens Twin chat, Mercy Health in panel:**\n\n> _\"Should I escalate Mercy's BAA?\"_\n>\n> **Twin:** \"Here is what I have.\n> **Compliance**: BAA stage 4 for 18 days. Counterparty counsel = Lisa Wong.\n> **Memory (my playbooks)**: 3 BAA cases in 8 weeks involved Lisa Wong. Mean stall = 60 days. Pattern confidence 0.81.\n> **Playbook (Lisa Wong)**: Recommend escalation to SVP Legal counsel at parent org at day 30.\n>\n> **Recommended action (confidence 0.86)**:\n> Escalate today. Drafted email to SVP Legal at Mercy's parent. Audit-logged.\n>\n> Chips: [Approve / Revise / Discard]\"\n\n**Same Twin, persona-shaped hydration, identical Message block types, identical governance, identical provenance.** This is the consolidation.\n\n### What was erased in later builds — and how to restore it\n\n| Original vision                                             | Erosion                                                         | Restoration                                                               |\n| ----------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| Twin greets proactively with overnight brief per department | ✅ Greeting scaffolding intact (12 entries) but content is mock | Wire live reads from Spine + Connector Hub last-sync state                |\n| Every answer has sources cited                              | ✅ `EvidenceSource[]` type + render                             | Connect `evidence` to live connector fetch timestamps + journal entries   |\n| Proposals embedded in chat                                  | ✅ `actions` array on messages                                  | Wire to proposal-service + Capability Fabric invocation                   |\n| Entity snapshots inline                                     | ✅ `EntitySnapshot` render                                      | Connect to D1 entity reads through the canonical entity-type-to-table map |\n| Memory refs visible                                         | ✅ `memoryRefs` + `memoryCommit`                                | Connect to Memory layer L7 (Organizational Memory) + Triage per-message   |\n| Source-grounded \"via GitHub / via Salesforce\"               | ✅ panel component renders                                      | Connect to real connector sync status indicators                          |\n| Confidence shown, not hidden                                | ✅ `confidence: 0.86%` rendering                                | Connect to live AI inference calibration                                  |\n| One-action-at-a-time, actionable                            | ✅ recommendation + chips                                       | Connect to Capability Fabric persona-aware chips                          |\n| User approves before any execution                          | ✅ Approve button → Bench                                       | Wire to L7 governance token minting + audit                               |\n\nThe architecture, components, types, and render code are all in place. The live data binding is the work — and that work is the difference between IntegrateWise as a product and IntegrateWise as a demo.\n\n---\n\n## Capabilities in the Workspace — Inline Actions, Sync Modes, Cross-Tool Composition\n\n### The doctrine\n\nThe L1 workbench is not a viewer. The buttons on the workbench are **Capability Fabric invocations**, not navigation. Every action a user can take on an entity card is a registered capability with:\n\n- Input/output schema\n- Required Spine context scopes\n- Allowed sync modes (soft / real / both)\n- Default confidence threshold\n- Default governance posture\n- Evidence chain template\n- Audit log entry shape\n\n### Capability invocation surfaces\n\n```\nWorkbench (L1)        — entity card buttons, list row actions\nEntity Twin Panel     — Accept & act chip → capability invocation\nTwin chat (L3)        — message.actions → capability invocation\nCLI (L4)              — `iw capability <name> --context <entity>`\nSlack/Teams (Layer 8) — shortcut button → capability invocation\nMobile (L1)           — touch-target capability button\n```\n\n**One capability, every surface.**\n\n### Three sync modes per capability\n\nThe Integration Hub writes every mutation through one of three governance-aware paths:\n\n| Mode                                              | Behaviour                                                                                                                                                                                                                                     | When used                                                                                                                                                                            |\n| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Soft sync (write staging)**                     | User acts in workbench → Spine written atomically → Connector Hub enqueues downstream write → background worker reconciles against the source tool. The user sees the result inside seconds. The tool sees the change when its adapter ticks. | Default for sensitive entities (healthcare compliance, finance audit-trail entities, HR people records). Manages latency-insensitive mutability.                                     |\n| **Real sync (write-through)**                     | User acts in workbench → Spine written atomically AND source tool called via `connector-{provider}` adapter → both succeed → commit logged. Failure in either triggers rollback + audit.                                                      | Default for daily-use mutations (Sales activities, support tickets, message sends). Manages user expectation of \"stuff I just did is now in Salesforce / Slack / Zendesk right now.\" |\n| **Propose → Approve → Execute (Twin governance)** | Twin proposes a high-risk mutation → user approves → governance token minted → both Spine AND source tool written in same transaction → audit-trail entry written.                                                                            | Default for high-stakes mutations (mark renewal risk, mark at-risk-leaning, change account ownership, fire rollback, change comp band).                                              |\n\nThe user's tenant IT sets the **per-capability default sync mode** during onboarding, not per-action in the moment. Persona defaults are pre-configured:\n\n- **Sales**: real sync for activity logs, soft sync for SFDC writes, propose for \"mark at risk\"\n- **CS (Healthcare)**: soft sync for HIPAA-adjacent entities, real sync for routine CS updates, propose for \"mark renewal risk\"\n- **HR**: real sync for skip-level calendar updates, propose for any \"mark flight risk,\" suggest-only for comp\n- **Eng**: real sync for incident acknowledgment (on-call hates latency), propose for rollback, propose for production deploy outside window\n\n### Cross-tool field composition — the Website Manager\n\nThe Website Manager is **the canonical demonstration of cross-tool field fusion inside the workbench**. From the screenshot-grounded doctrine:\n\n> _\"Website manager should be a point where it shows the number of user visits, the blog content, linking the content, images, and so multiple\"_\n\nThis is **one workbench surface, fusing five tools' canonical state, governed by the same Twin, capable of one-click inline actions**.\n\n| Surface tile         | Composed from                                      | What it does                                                 |\n| -------------------- | -------------------------------------------------- | ------------------------------------------------------------ |\n| **Total Pages**      | Sanity / Contentful + WordPress schema             | Live count                                                   |\n| **Monthly Visitors** | Cloudflare Analytics + Plausible                   | Aggregate, hovered-trend visualised                          |\n| **SEO Health**       | Ahrefs / Semrush + Search Console                  | Score                                                        |\n| **Uptime**           | StatusCake + Cloudflare health checks              | Pass/fail banner                                             |\n| **Traffic Chart**    | GA4 + Plausible + UTM tools                        | Visitors over time, total + unique                           |\n| **Core Web Vitals**  | PageSpeed + Search Console                         | LCP / FID / CLS with thresholds                              |\n| **Device Breakdown** | GA4 + Plausible                                    | Desktop / Mobile / Tablet %                                  |\n| **Traffic Sources**  | Analytics + UTM                                    | Organic / Direct / Social / Referral / Paid                  |\n| **SEO Issues**       | Search Console + Semrush crawl                     | Type, message, severity, fix-it link                         |\n| **Top Pages**        | Sanity CMS + GA4                                   | Title, path, traffic, status, \"Edit\" chip                    |\n| **Recent Edits**     | Sanity + Ghost + Webflow                           | Page, action, author, time                                   |\n| **Posts list**       | Notion drafts + Sanity published + Ghost scheduled | Title, status, view count, comments, SEO score               |\n| **Asset Library**    | ImageKit / DAM / Cloudinary                        | Image, video, document counts, dimensions, \"Used in N pages\" |\n| **Campaigns**        | Marketo / HubSpot + GA4 + Plausible                | Active campaigns, attribution, conversion                    |\n\n### The Schedule Blog Post capability — composed invocation\n\nThe capability `schedule_blog_post` declares its input as multiple systems' fields:\n\n```\ninputs:\n  draft_content: <from Notion draft ID>\n  canonical_image: <from ImageKit ID>\n  publish_target: <to Sanity via CMS adapter>\n  social_amplification: <to Buffer / native social APIs>\n  email_blast: <to HubSpot / Customer.io>\n  analytics_tile: <Plausible / GA4 attribution link>\n  seo_check: <via Semrush cheat sheet>\n```\n\nCompose, gate, execute:\n\n1. **Read inputs** across Notion, ImageKit, Buffer, HubSpot, Plausible.\n2. **Brand compliance check** — Twin compares draft to user's brand voice playbook (Memory layer).\n3. **Brand gate failure?** — Twin flags the diff. User approves modification or proceeds without (Softer mode = bypass; default = block-with-suggestion).\n4. **Gather all writes** into one orchestration plan.\n5. **Approve once** — single Token mint.\n6. **Atomic commit across all systems** — single transaction, single audit entry.\n7. **Capability complete** — user sees in their workbench view, all systems updated, audit logged.\n\nCapabilities compose across tools. Workbench is capable. Persona-aware. Governed. **This is the action-doctrine of IntegrateWise made visible in the L1 surface.**\n\n### Recap table — Where every capability lives\n\n| Capability family           | Surfaces it lives on                | Sync mode by default                    | Persona        |\n| --------------------------- | ----------------------------------- | --------------------------------------- | -------------- |\n| `mark_lead_active`          | Sale entity card                    | Soft sync to CRM                        | Sales          |\n| `view_contact`              | Contact card                        | Read; no mutation                       | All            |\n| `update_field`              | Field-level edit on any entity      | Soft sync default                       | Persona-shaped |\n| `log_activity`              | Activity timeline chip              | Real sync (audit expectation)           | Sales, CS, HR  |\n| `draft_outreach`            | Outreach chip                       | Twin proposes; soft-send to email       | Sales, CS      |\n| `schedule_call`             | Calendar chip                       | Real sync to Calendar                   | Sales, CS, HR  |\n| `mark_renewal_risk`         | Renewal card chip                   | Propose-gate (≥ 0.85)                   | CS, RevOps     |\n| `update_health_score`       | Health tile                         | Soft sync external CRM                  | CS             |\n| `schedule_blog_post`        | Website Manager chip                | Composed capability; brand gate; atomic | Marketing      |\n| `swap_image`                | Asset Library chip → page reference | Real sync to CMS + DAM                  | Marketing      |\n| `mark_campaign_active`      | Campaign chip                       | Real sync UTM + CRM                     | Marketing      |\n| `acknowledge_incident`      | Incident timeline chip              | Real sync (on-call latency-sensitive)   | Engineering    |\n| `pre_draft_rollback`        | Incident chip                       | Propose-gate                            | Engineering    |\n| `schedule_post_mortem`      | Incident chip                       | Real sync Calendar + Notion             | Engineering    |\n| `mark_person_flight_risk`   | Person card chip                    | Propose-gate + governance               | HR             |\n| `update_comp_band_edge`     | Person card chip                    | Propose-gate + multi-approval           | HR             |\n| `schedule_skip_level`       | Person card chip                    | Real sync Calendar                      | HR             |\n| `update_pipeline_coverage`  | Pipeline chip                       | Twin computes, soft-sync forecast       | RevOps         |\n| `flag_reconciliation_delta` | Pipeline chip                       | Propose-gate (cross-team)               | RevOps         |\n| `close_invoice`             | Invoice chip                        | Real sync NetSuite/Stripe               | Finance        |\n| `sign_contract`             | Contract chip                       | Propose-gate + e-signature flow         | Legal          |\n| `update_vendor_status`      | Vendor chip                         | Soft sync                               | Supply Chain   |\n| `dispatch_field_service`    | Service chip                        | Real sync                               | Service Ops    |\n\nEvery capability has a persona-aware home, a default sync mode, a default confidence threshold, and a default governance posture. The Hub routes them; the Twin proposes them; the user approves them; the Audit logs them.\n\n---\n\n## Closing — The Integrated Schema\n\nThe marketplace user is Maya, Sana, Tomás, Nadia, Lila, or Arjun — one of six personas. They install from a marketplace listing targeting their persona. OAuth passes identity only. Onboarding captures what OAuth cannot. `tenant_spine_config` commits. D1 Spine partitions load from the connector canonical state. L1 workbench renders persona-shaped projections. L2 signals fire read-side over Spine without LLM. L3 Twin hydration assembles persona sources through the activation gate. L4 Knowledge surfaces memory from the 8-layer pipeline. The Brainstorming Layer holds the conversational working memory. The Capability Fabric executes inline actions through three sync modes, governed per tenant default.\n\nProactivity is wired, never interrogative.\n\n**Truth you own. AI you rent. Approval in between. Continuity over asking.**\n\nThat is the entire marketplace onboarding × persona design, grounded in the source code, the doctrinal foundation of IntegrateWise.txt, and the structural reality that ChatGPT and Claude authenticators cannot and will not pass persona context — only an in-place onboarding phase can.\n\n# IntegrateWise Onboarding & Persona-First Design — Final Doc\n\n---\n\n## 1. The Marketplace Threshold Question (Read This First)\n\n**ChatGPT does not pass role, department, industry, or company size.** OAuth from ChatGPT/Claude/Perplexity to IntegrateWise passes only:\n\n| Field                           | Source                      | Verdict                             |\n| ------------------------------- | --------------------------- | ----------------------------------- |\n| `email`                         | Assistant account           | ✅ Yes                              |\n| `name`                          | Assistant profile           | ✅ Yes                              |\n| `sub`                           | Assistant-internal user-id  | ✅ Yes                              |\n| `picture`                       | Assistant profile           | ✅ Yes                              |\n| Org/company claim               | Sometimes (Enterprise only) | ⚠️ Maybe                            |\n| Business **role**               | —                           | ❌ **No**                           |\n| **Department**                  | —                           | ❌ **No**                           |\n| **Industry**                    | —                           | ❌ **No**                           |\n| Company **size**                | —                           | ❌ **No**                           |\n| Tool connections the user wants | —                           | ❌ **No (chosen AFTER onboarding)** |\n\nChatGPT — and Claude, and Perplexity — are AI assistants, not identity providers. They authenticate _who you are on the assistant_, not _who you are at your company_. **Therefore the onboarding phase must run inline inside the marketplace trial** — between OAuth callback and first data load — to:\n\n1. Capture the persona context the marketplace OAuth cannot provide.\n2. Hydrate RBAC (role → capabilities → governance posture).\n3. Hydrate `tenant_spine_config` (industry × department → Spine schema variant).\n\nWithout this, the workbench renders **empty and undifferentiated**, which kills the 5-minute value window and the marketplace GTM motion.\n\n---\n\n## 2. The Onboarding Phase — Three Duties\n\n### Duty 1: Capture Persona Context\n\nSix fields captured in order (each one commits progressively — no big form):\n\n| Step | Field                                                                                                                                                           | What it decides                                                                           |\n| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| 0    | Use Case — Personal / Work / Business                                                                                                                           | Workspace model (single-user vs. tenant)                                                  |\n| 1    | Industry — 11 + Other                                                                                                                                           | Base resource layer: entity vocabulary, compliance flags, vertical connectors             |\n| 2    | Department — 12 (Sales / Marketing / RevOps / CS / Support / Eng / Product / Finance / Legal / HR / Supply Chain / Service Ops) + sub-role                      | Functional trait: KPIs, dashboard modules, Twin greeting lineage                          |\n| 3    | Sub-role — e.g., Sales→AE/SDR/Manager ; CS→CSM/Lead/VP ; HR→HRBP/HR-Ops/CHRO ; Eng→IC/Manager/Director/VP                                                       | Twin greeting template, default capability set, default governance posture                |\n| 4    | Company Size — 1–10 / 11–50 / 51–200 / 201–500 / 501–1k / 1k–5k / 5k+                                                                                           | Connector quotas, sync cadence (5-min free / 15-min enterprise), Twin proposal volume cap |\n| 5    | Connectors — Continuity Bridge (required) + 5 storage (Drive/OneDrive/Notion/Confluence/Slack History) + MCP servers + AI providers + Native (CRM/Support/etc.) | Per-tenant connector matrix                                                               |\n\n### Duty 2: Hydrate RBAC\n\nSingle artifact: **role → capabilities → governance posture mapping**.\n\n```\nrbac_users       { user_id, tenant_id, role_id, level, scope }\nrbac_roles       { role_id, tenant_id, name, capabilities[], inherits[] }\nrbac_permissions { perm_id, name, scope, gate_posture }\n```\n\nThe first user always gets `role = owner`. RBAC is the **persona barrier** — Maya (Sales/AE) cannot onboard HRBP capabilities; Nadia (HR/HRBP) cannot onboard Rollback Engineering capabilities. The Twin only sees the persona's reachable capability set.\n\n### Duty 3: Hydrate `tenant_spine_config`\n\nOne row in D1 makes the rest of the platform persona-shaped at render time:\n\n```\ntenant_spine_config\n  tenant_id          UUID PK\n  industry           TEXT        -- 11 valid + Other\n  department         TEXT        -- 12 valid\n  sub_role           TEXT        -- persona-derived\n  user_type          TEXT        -- personal|business|executive\n  company_size       TEXT        -- 1-10..5k+\n  enabled_entities   TEXT[]      -- derived from industry × department\n  north_star_metric  TEXT        -- derived from department\n  schema_version     TEXT\n  governance_posture JSONB       -- default sync modes, default confidence thresholds, default capability gates\n  twin_greeting_id   TEXT        -- which GREETING_LINES entry fires first\n```\n\nThis row drives: L1 workbench surface, L2 Intelligence Overlay signals, L3 Twin hydration sources, L4 Knowledge category surfacing, Capability Fabric per-surface defaulting, Governance posture.\n\n### Where the Onboarding Runs (UX)\n\n| Option                            | UX                                                                                                                                  | Trade-off                                                                                    |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| **(A) MCP tool-based onboarding** | `iw.onboard` tool with structured input schema → ChatGPT renders the form itself                                                    | Stays fully inside ChatGPT but constrained by ChatGPT's form schema                          |\n| **(B) Webview interstitial**      | Short redirect to `app.integratewise.ai/onboard?jwt=…` → reuses the existing 4-step wizard → posts completion back → MCP reconnects | Full UI depth, reusable, single component (`apps/web/src/components/activation/onboarding/`) |\n\n**Recommended: B.** One component, full UI depth, no ChatGPT-form dependency.\n\n### The 5-Minute Hard Gate\n\nOAuth (5s) → Onboarding Interstitial (60s) → First connector Nango OAuth (45s) → Creamy layer pull + Pipeline 8 stages + Spine writes (60s, p99 normalizer 2s) → Dashboard renders. **Under 5 minutes from \"Add IntegrateWise\" to first persona-shaped data on the workbench.**\n\n---\n\n## 3. Twelve Departments × Eleven Industries — The Persona Matrix\n\n### 12 Departments (Functional Trait Layer)\n\n| #   | Department         | CTX Enum         | Workbench essence                                                         |\n| --- | ------------------ | ---------------- | ------------------------------------------------------------------------- |\n| 1   | Sales              | CTX_SALES        | Pipeline, deals, accounts, contacts, stakeholders, activity log           |\n| 2   | Marketing          | CTX_MARKETING    | Content, campaigns, channels, audiences, attribution, assets              |\n| 3   | RevOps             | CTX_BIZOPS       | Cross-team reconciliation, forecast, quota, coverage, process bottlenecks |\n| 4   | Customer Success   | CTX_CS           | Health, renewal, expansion, adoption, NPS, QBR                            |\n| 5   | Support            | CTX_SUPPORT      | Tickets, SLAs, escalations, deflection, agent load                        |\n| 6   | Engineering        | CTX_TECH         | Incidents, deploys, sprints, PRs, on-call, post-mortem                    |\n| 7   | Product            | CTX_PM           | Roadmap, features, adoption, A/B, feedback                                |\n| 8   | Finance            | CTX_FINANCE      | Invoices, recurring rev, comp, budget, audit, tax                         |\n| 9   | Legal              | CTX_LEGAL        | Contracts, NDAs, compliance, disputes, IP                                 |\n| 10  | HR                 | CTX_HR           | Hiring, comp, flight risk, engagement, performance                        |\n| 11  | Supply Chain       | CTX_SUPPLY_CHAIN | Inventory, logistics, vendors, lead time, ETA                             |\n| 12  | Service Operations | CTX_SERVICE_OPS  | Field service, dispatch, uptime, technicians                              |\n\n### 11 Industries (Base Resource Layer)\n\n| #   | Industry              | Industry-specific fields                                              |\n| --- | --------------------- | --------------------------------------------------------------------- |\n| 1   | SaaS / Technology     | `arr`, `mrr`, `churn_rate`, `nrr`, `ltv`, `cac`                       |\n| 2   | Professional Services | `billable_hours`, `utilization`, `client_engagement`, `partner_track` |\n| 3   | Healthcare            | `hipaa_status`, `baa_id`, `procurement_stage`, `ehr_id`               |\n| 4   | Education             | `enrollment`, `graduation_rate`, `cohort`, `course_id`                |\n| 5   | Manufacturing         | `production_line`, `down_minutes`, `machine_data`, `factory_sla`      |\n| 6   | Automotive            | `vin`, `recall`, `service_history`, `dealer_id`                       |\n| 7   | Retail / Commerce     | `sku`, `order`, `fulfillment`, `return_rate`, `channel_perf`          |\n| 8   | Financial Services    | `kyc`, `regulatory_breach_window`, `audit_trail`, `pii_grade`         |\n| 9   | Logistics             | `shipment`, `route`, `carrier`, `eta`, `exception_code`               |\n| 10  | Media                 | `content_id`, `watch_time`, `audience_segment`, `ad_pacing`           |\n| 11  | Public Sector         | `case_id`, `clearance_level`, `constituent`, `jurisdiction`           |\n\n### The Derivation Principle\n\n```\nSpine Schema = f(Industry, Department)\n\nIndustry   = base resource layer (entity vocab, compliance, vertical connectors)\nDepartment = functional trait      (KPI set, module set, Twin greeting lineage)\n```\n\nSales in Healthcare ≠ Sales in SaaS:\n\n- **SaaS Sales:** deal with `arr`, `mrr`, `churn_risk`, `technical_blocker`\n- **Healthcare Sales:** contract with `contract_value`, `procurement_stage`, `hipaa_status`, `baa_id`\n\nSame `deal` entity type. Different canonical fields, different compliance posture, different connector set.\n\n### Careful Consolidation of Workbenches\n\n**One component library. Persona-shaped data projection. Not 132 workbenches.**\n\nThe workbench component (L1 surface, Entity card, KPI tile, Twin panel, Capability chip) is **one set of React components**. The workbench data projection reads from `tenant_spine_config` and surfaces the persona-shaped slice. **One codebase × 6 T0 personas × 12 departments × 11 industries × 132 schema variants derived at runtime.**\n\n- **T0 (ship first)** — Sales, Marketing, RevOps, CS, Engineering, Finance. ~85% of install volume in year one.\n- **T1 (ship 6–12 months)** — Support, Product, HR, Legal, Service Ops.\n- **T2 (ship 12–18 months)** — Supply Chain.\n\nAll 12 × 11 share **the same Spine**, **the same Pipeline**, **the same Twin engine**, **the same Memory pipeline**, **the same Governance gate**. Persona-specific surfaces are projections of the same entity graph.\n\n---\n\n## 4. Daily Motion — Persona-Aware, Always On\n\n### L0.5 Always-On Operating Layer (runs without the user)\n\n| Component                                  | Cadence                        | Output                                                                     |\n| ------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------- |\n| `TwinAgent` Durable Object                 | Daily 05:00 cron per tenant    | Yesterday's signal review, morning brief draft, action proposals batched   |\n| `TenantBrainDO`                            | Continuous                     | Pending approvals, active signals, HITL 15-min timeout, pause/resume state |\n| Connector-sync (delta cron)                | 5 min free / 15 min enterprise | Delta pull of changed records from connected tools                         |\n| Connector Nango webhooks                   | Real-time for SaaS support     | `auth.created` triggers immediate creamy sync                              |\n| Pipeline (consolidated normalizer + spine) | Per queue message              | Records normalized → Spine written                                         |\n| Memory Triage Bot                          | Continuous                     | New observations classified (fact/playbook/decision/relationship/noise)    |\n| Memory Evolution                           | Hourly                         | Pattern detection on accumulated observations                              |\n| Twin hydration                             | Per Twin chat open             | Cascade: screens + Spine + memory + conversation → prompt                  |\n| Promotion Queue scan                       | Hourly                         | High-confidence candidates surfaced for user approval                      |\n\n### What the user sees when they open the workbench in the morning\n\nEach persona-shaped greeting contains four parts:\n\n- **`overnight`** — what Twin found\n- **`critical`** — one thing that can't wait\n- **`invite`** — an engagement question\n- **`chips`** — 3–4 one-click capability actions\n\n**Example greetings (per CTX\\_\\*)** — these are the canonical morning voices:\n\n| Persona                                    | Morning Greeting (abridged)                                                                                                                              |\n| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Sales (Maya, AE, SaaS)                     | \"Pipeline Scout ran at 6 AM. Coverage at 3.1× against 4× — 5 deals slipped, 3 going cold. CFO reply waiting on Skyline. Want me to draft the CFO reply?\" |\n| CS (Sana, CSM, Healthcare)                 | \"Renewal Watchdog scanned 47 accounts. Mercy Health BAA stalled 18 days at stage 4. Lisa Wong pattern matches 3 prior cases.\"                            |\n| RevOps (Arjun, Lead, Financial Services)   | \"6 reconciliation issues pending. 4 deals slipping Q3→Q4 where Accounting has them in Q3. Forecast variance 2.3% from yesterday.\"                        |\n| Marketing (Lila, Content Marketer, Retail) | \"Winter launch post staged in Sanity. Hero image unsigned in DAM. Last teaser pulled 1,400 organic visits — compose launch from Notion draft?\"           |\n| Engineering (Tomás, EM, Manufacturing)     | \"P1 incident on Helix — bulk export timing out 02:14 UTC, deploy correlation 0.83. Rollback candidate ready. Sprint burndown 4 days behind.\"             |\n| Finance (FP&A)                             | \"ARR rollup $1.42M committed, 0.7% variance. 3 renewal forecasts missing rev-rec mapping. NetSuite delta: 4 invoices unsettled.\"                         |\n| HR (Nadia, HRBP, Professional Services)    | \"Engagement declining 4 weeks in consulting practice. 11 flight-risk people I can defend with evidence — show me the defense?\"                           |\n| Product (PM)                               | \"Adoption funnel drops at step 3 (post-trial activation). 6 feature requests correlate. Beta cohort engagement +12% over cohort 1.\"                      |\n| Support (Manager)                          | \"P0 queue clear. P1 backlog 12. SLA breach risk on 3 enterprise tickets. Deflection pattern: 'export to CSV' returning empty rows.\"                      |\n| Legal (Counsel)                            | \"3 NDAs awaiting counter-signature >48h. 1 contract redline vs. playbook. SOC2 evidence pack 12 days from due date.\"                                     |\n| Supply Chain (Manager)                     | \"Carrier exception rate +14% on Route-7. Lead time slipped on 2 critical SKUs. Sourcing alternative flagged for Vendor-204.\"                             |\n| Service Ops (Field Manager)                | \"4 dispatch slots unassigned in NE region. 1 SLA at risk. Uptime anomaly on tower 14 resolved.\"                                                          |\n\n**Invariant:** Every greeting is grounded in the Spine, sourced from canonical state, and acted on through the Capability Fabric. **No fabrication.** If Twin cannot defend a greeting (insufficient Spine data, no connector activity in 24h), it says so honestly.\n\n---\n\n## 5. L1 Layer — Proactive AI Without Re-Asking\n\n### Two Distinct Behaviours\n\n| Behaviour                                                              | OODA?                                          | Why                                                                  |\n| ---------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |\n| **L1 data load — Spine → workbench**                                   | ❌ **No OODA** — mechanical pipeline certainty | Data is canonically known; the Pipeline handles it deterministically |\n| **L1 AI on loaded data — observing the entity the user is looking at** | ✅ **OODA** — proactive agent                  | Decisions under uncertainty require agent reasoning                  |\n\n### L1 Data Load Path (No OODA)\n\n```\nSpine D1 partition loaded\n     →\n${department}_${industry}_data projection\n     →\nDOMAIN_CONTENT_MAP[domain]\n     →\nWorkbench entity tables, KPI tiles, cards, list views\n     →\nUser sees Maya's Skyline deal, Sana's Mercy Health, Tomás's Helix incident — pre-filled, not empty.\n```\n\n### L1 AI Path (OODA on what the user is looking at)\n\n```\nObserve   — Twin reads the entity on screen\n            + the L2 signal layer (anomalies, missing-activity, pattern matches)\n            + L4 memory (approved playbooks related to this entity or persona)\nOrient    — pattern matching against historical patterns for this entity type\n            + comparison against the persona's industry × department norms\n            + risk/expansion probability given the entity's current state\nDecide    — generate a proposal with confidence score\n            + select the right verb: act / surface / wait / discard\nAct       — engine proposes. The user (or governance gate) decides.\n```\n\n### Core Doctrine: Proactivity Is Wired, Not Interrogative\n\n**The user never sees \"What would you like help with today?\"** — Twin greets first.\n**The user never sees \"Which deal are you asking about?\"** — Twin reasons about the deal on screen.\n**The user never sees \"Can you tell me who you are?\"** — JWT, role, tenant, sub-role are all minted.\n**The user never sees \"Connect Salesforce first\" without knowing why** — Twin explains: \"Connect Salesforce to read deal stages for 47 accounts; ten accounts in your commit block on it.\"\n\n**v2 Doctrine: \"Continuity over asking.\"** The Twin never re-asks for context that is already on screen, already in the Spine, already inferred from the conversation, or already established by an earlier action in the session.\n\n---\n\n## 6. L2/L3 — Twin Interaction, Fully User-Based OODA\n\n### L2 — Intelligence Overlay (Observe + Orient, no LLM required, cached)\n\n| L2 Element                                   | OODA Phase | Source                                                                      |\n| -------------------------------------------- | ---------- | --------------------------------------------------------------------------- |\n| Signals (anomalies, risks, missing-activity) | Observe    | Connector-sync delta + S6 intelligence scans Spine                          |\n| Insights (synthesized observations)          | Orient     | Pattern matching against historical data + Twin-promoted playbooks          |\n| Think traces (hypothesis candidates)         | Orient     | L4 memory recall against current entity context                             |\n| Context (assembled entity view)              | Orient     | S9 Continuity Bridge assembly                                               |\n| Evidence ribbons                             | Orient     | Source citations: \"via Salesforce\", \"via Zendesk\", \"via Memory 3 weeks ago\" |\n\n**L2 is read-heavy. No mutations. No proposals fired.** A user can promote an L2 insight to L3 Twin proposal — that transitions into the full Decide → Act OODA loop.\n\n### L3 — Twin Workbench (Full OODA)\n\nActivation gate first:\n\n```\nevaluateActivation:\n  if (memory_records.total < 3)          → BLOCK, render hydration message\n  if (memory_records.promoted < 1)       → BLOCK, render staging state\n  if (unresolved governance violations)  → BLOCK, render audit summary\n  else                                   → PROCEED to context assembly\n```\n\nPassed → parallel context assembly (identical pipeline, persona-shaped inputs):\n\n```\ngraph LR\nA[User message] --> B[Continuity retrieval]\nB --> C{Activation passed?}\nC -- No --> D[Hydration block]\nC -- Yes --> E[aiSearch: semantic knowledge]\nE --> F[conversationalSearch: past chat sessions]\nF --> G[mcpSearch: connector-spine resources]\nA --> H{Engineering intent?}\nH -- Yes --> I[spineReadEngineering: D1 build_data partitioning]\nH -- No --> J[Skip engineering read]\nE --> K[DO SQLite: 10 warm turns]\nF --> K\nG --> K\nK --> L[Learned profile: daily-reflected communication style]\nL --> M[Construct system prompt]\nM --> N[gatewayChat: LLM inference]\nN --> O[Propose with confidence + evidence + alternatives]\n```\n\n### Per-Persona Twin Grammar (Same Pipeline, Persona Inputs)\n\n| Persona            | aiSearch sources                           | conversationalSearch                    | mcpSearch                                    | Eng intent? | DO warm     | Learned Profile                                                        |\n| ------------------ | ------------------------------------------ | --------------------------------------- | -------------------------------------------- | ----------- | ----------- | ---------------------------------------------------------------------- |\n| Maya (Sales/AE)    | CRM field schema, deal-stage playbooks     | Last 14d of her chat sessions           | SFDC, HubSpot, Slack, Gmail, Calendar        | No          | Her last 10 | \"Terse. Action-oriented. Inline next step. No preamble.\"               |\n| Sana (CS/Health)   | BAA playbooks, healthcare compliance notes | Last 21d of her chat + customer threads | Gainsight, Zendesk, Notion, Slack, CertifyMD | No          | Her last 10 | \"Case-law-style. Cited evidence. One decision. High caution near PHI.\" |\n| Tomás (Eng/Mfg)    | incident-pattern notes, post-mortems       | Last 14d of his chats + Slack on-call   | Jira, PagerDuty, GitHub, Datadog             | **Yes**     | His last 10 | \"Tactical. Time-stamped. Action + rollback + verification.\"            |\n| Nadia (HR/ProServ) | flight-risk playbooks, comp edge patterns  | Last 30d (governance-scoped)            | Workday, Lattice, survey vendor              | No          | Her last 10 | \"High-censorship. Compact. 0.94+ confidence only.\"                     |\n\n**Same Twin engine, persona-shaped hydration, persona-shaped grammar, persona-shaped governance.** That is the careful consolidation.\n\n### Irreducible Human Agency\n\nEven at high confidence, Twin does **not** execute:\n\n| Confidence | Posture                                                                          |\n| ---------- | -------------------------------------------------------------------------------- |\n| ≥ 0.85     | Auto-approve (low-risk entities) or surface with one-click approve (medium-risk) |\n| 0.70–0.85  | Surface on My Desk — human reviews                                               |\n| < 0.70     | Discarded                                                                        |\n\nThe Twin is a reasoning layer that **proposes**. **The human is the decider.** Approval is midprocess, before execution. Tokens mint-bound to tenant + action + scope + confidence + sync mode. Audit-trail mandatory.\n\n---\n\n## 7. Memory Surfaced Inside the Knowledge Layer (L4)\n\n### 8-Layer Memory Pipeline\n\n```\nL1 Twin Memory            (cognitive working memory — chat threads, sessions, reasoning chains)\n   ↓\nL2 Memory Intake          (incoming observations — Slack, meetings, email, docs, chat, voice)\n   ↓\nL3 Triage Bot             (classify, dedupe, score: memory|noise|policy|fact|decision|relationship)\n   ↓\nL4 Memory Evolution       (Observation → Pattern → Insight → Playbook → Institutional Knowledge)\n   ↓\nL5 Promotion Queue        (candidate + confidence + evidence)\n   ↓\nL6 Human Approval         (Truth you own. AI you rent. Approval in between.)\n   ↓\nL7 Organizational Memory  (approved facts, decisions, playbooks, policies, relationships, outcomes)\n   ↓\nL8 Knowledge              (documents, runbooks, research, templates, SOPs)\n```\n\n### Three-Axis Separation\n\n```\nSPINE    = What IS (truth)        Accounts, contacts, deals, tickets, events\nMEMORY   = What it MEANS          \"Silent champion + open P1 = renewal risk\"\nKNOWLEDGE = What we know          Playbooks, runbooks, SOPs, templates\n```\n\n### Where Memory Lives in the UI\n\n`L4` is the **Knowledge & Memory Workbench** — a separate navigation surface:\n\n```\nTwin (Reasoning Layer)\n├── Chat\n├── Conversations\n├── Sessions\n├── Voice\n├── Working Memory\n├── Agents\n├── Skills\n├── Workflows\n├── Executions\n├── Models\n├── Tools\n└── Logs\n\nContinuity (Meaning Layer)             ← MEMORY LIVES HERE\n├── Intake\n├── Triage\n├── Evolution\n├── Promotion Queue      ← THE single most important surface\n├── Organizational Memory\n├── Knowledge            ← documents, playbooks, runbooks\n├── Continuity Graph\n└── Metrics\n```\n\n**The Promotion Queue is \"the single most important screen in IntegrateWise\"** — it is where AI learns, human approves, organization remembers. Per-persona queue: Maya sees sales pattern candidates, Sana sees compliance pattern candidates, Nadia sees flight-risk pattern candidates.\n\n### L4 Component Functionality\n\n- Semantic search across org memory + promoted knowledge + documents + Twin chat sessions.\n- Categories — Playbooks, SOWs & Contracts, Runbooks, Research, Templates.\n- Visibility — Private / Team / Public.\n- Memory organization — tags, categories, prominence-tagged by confidence + evidence trail.\n- Governance status — staging → approved → published. Every memory card carries its lifecycle state.\n- Pinned items, full document excerpts, semantic search.\n\n### Persona-Shaped Memory Surfacing\n\nSame component, persona-shaped data:\n\n| Persona      | L4 Surface Content                                                                                                        |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------- |\n| Maya (Sales) | Sales playbooks (negotiation tactics, security-questionnaire patterns, technical-blocker recovery), sales SOPs, CRM links |\n| Sana (CS)    | Renewal motion playbooks, BAA patterns, QBR templates, healthcare compliance guardrails                                   |\n| Tomás (Eng)  | Incident post-mortems, deploy-window playbooks, on-call rotation SOPs                                                     |\n| Nadia (HR)   | Flight-risk playbooks, comp-band edge cases, engagement-survey interpretation                                             |\n\n**Twins surface ON the Knowledge Layer. Memory writes INTO the Intake layer. Promotion Queue catches what rises. Knowledge layer stores what stays.**\n\n---\n\n## 8. Brainstorming Layer (Twin Memory — Conversational AI Chat Data)\n\n### What the Brainstorming Layer Is\n\nThe Brainstorming Layer is the **Twin Memory** layer — cognitive working memory holding **conversational AI chat data**. It is the _raw material_ from which Organizational Memory is built.\n\n### What Sits Per Persona\n\n| Persona | Brainstorming Contents                                                                                                                                                                  |\n| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Maya    | ChatGPT/Claude conversations about her deals, Airtable notes, Slack thread participation                                                                                                |\n| Sana    | Claude conversations about customer escalations, Notion QBR outlines, Zendesk ticket analysis chats                                                                                     |\n| Lila    | Perplexity research queries, Notion drafts annotated through Twin, Slack brand channel conversations                                                                                    |\n| Nadia   | People-confidential conversations with Twin or via email — _all governed_: Triage is hit first, only non-PHI pattern fragments survive, only with approval do they shape persona memory |\n\n### Flow Per Twin Chat Session\n\n```\nUser message → Twin Reasoning (L3) → Response (proposal + grounded evidence + chips)\n     │                                    │\n     ▼                                    ▼\nwarm-turns DO SQLite                  emitTriageInput(intent + message + proposed)\n(conversation_turns table)              │\n     │                                  ▼\n     │                            MEMORY INTAKE QUEUE\n     │                                  │\n     │                                  ▼\n     │                            TRIAGE BOT\n     │                            classify: fact | decision | observation | relationship | noise\n     │                            score: confidence 0–1\n     │                            derive: persona-tag, industry-tag, evidence ribbon\n     │                                  │\n     │                            conf ≥ 0.85, evidence ≥ 2 sources\n     │                                  ▼\n     │                            EVOLUTION ENGINE\n     │                            Observation + Evidence → Pattern candidate\n     │                                  │\n     │                            (hours/days pass)\n     │                                  ▼\n     │                            PROMOTION QUEUE entry\n     │                            \"Renewal Risk Pattern\" | conf 0.86 | 17 accounts\n     │                                  │\n     │                                  ▼\n     │                            User approves / rejects / annotates\n     │                                  │\n     │                                  ▼\n     │                            ORGANIZATIONAL MEMORY\n     │                            Now reusable across whole tenant\n```\n\n### Why It Is Essential, Persona-Distinct\n\n- **Without the Brainstorming Layer**, every Twin chat is ephemeral.\n- **With it**, every chat is an observation candidate that _may_ become a knowledge artifact that _will_ serve the whole tenant.\n- **Without the Brainstorming Layer**, IntegrateWise is a great AI assistant.\n- **With it**, IntegrateWise is an AI assistant that **builds the company's own institutional intelligence from its actual work**.\n\n**Persona distinction:** Triage Bot classification is department-tagged. Maya's messages → `[sales: observation|decision|fact|relationship|playbook candidate]`. Sana's → `[cs: observation|decision|fact|playbook candidate, healthcare: phi_flag]`. Tomás's → `[eng: incident|deploy-pattern|post-mortem candidate]`. Nadia's → `[hr: people-observation|playbook candidate, governance: scope-restricted]`. **Brainstorming Layer is persona-aware from intake onward.**\n\n---\n\n## 9. AI Chat — Spine-Grounded Insights and Suggestions (Recovering the Original Vision)\n\n### The Original Vision, Restored\n\nThe AI Chat was never meant to be \"a chat.\" It was meant to be a **Spine-grounded conversational surface** where every response is:\n\n- **Sourced** — every claim has a `via` citation.\n- **Confidenced** — every recommendation shows `confidence: 0.86`.\n- **Actionable** — every reply ends with a one-click capability chip.\n- **Proactive** — Twin speaks first on entity load; doesn't wait for a question.\n\n### Message Type Architecture (already intact)\n\n```\nMessage {\n  content      — fallback text\n  blocks[]     — callout | entity card | list | reference list | separator\n  evidence[]   — EvidenceSource with source + timestamp + confidence\n  entity       — EntitySnapshot (inline entity card on the reply)\n  memoryRefs[] — which memory entries informed the reply\n  memoryCommit — what was learned from this exchange\n  actions[]    — Approve | View | Link chips on the message\n  table        — inline structured data (headers + rows)\n}\n```\n\n### Example: Spine-Grounded Twin Chat Per Persona\n\n**Maya opens Twin chat, Skyline in panel:**\n\n> _\"Should I move Skyline to Stage 4?\"_\n>\n> **Twin:** \"I am not sure. Here is what I have.\n> **CRM**: stage = Negotiation, last activity 8 days ago.\n> **Slack**: VP Eng asked about SOC 2 Tuesday. No reply yet.\n> **Email**: CFO replied 11:42 PM with one open question — deployment timeline.\n> **Memory (my playbooks)**: You have moved 4 deals to Stage 4 in Q3. In 3/4, buyer's CFO signed off first. In the 4th, the deal slipped.\n>\n> **Recommended action (confidence 0.74)**:\n>\n> 1. Today's reply handles the CFO's deployment timeline question.\n> 2. After CFO replies, move to Stage 4 with a soft SOC 2 follow-up.\n>\n> Chips: [Approve / Revise / Discard]\"\n\n**Sana opens Twin chat, Mercy Health in panel:**\n\n> _\"Should I escalate Mercy's BAA?\"_\n>\n> **Twin:** \"Here is what I have.\n> **Compliance**: BAA stage 4 for 18 days. Counterparty counsel = Lisa Wong.\n> **Memory (my playbooks)**: 3 BAA cases in 8 weeks involved Lisa Wong. Mean stall = 60 days. Pattern conf 0.81.\n> **Playbook (Lisa Wong)**: Recommend escalation to SVP Legal counsel at parent org at day 30.\n>\n> **Recommended action (confidence 0.86)**:\n> Escalate today. Drafted email to SVP Legal at Mercy's parent. Audit-logged.\n>\n> Chips: [Approve / Revise / Discard]\"\n\n**Same Twin engine. Persona-shaped hydration. Identical Message block types. Identical governance. Identical provenance.** That is the careful consolidation.\n\n### What Was Eroded in Later Builds, and How to Restore It\n\n| Original Vision                                             | Erosion                                                         | Restoration                                                             |\n| ----------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |\n| Twin greets proactively with overnight brief per department | ✅ Greeting scaffolding intact (12 entries) but content is mock | Wire live reads from Spine + Connector Hub last-sync state              |\n| Every answer has sources cited                              | ✅ `EvidenceSource[]` type + render                             | Connect `evidence` to live connector fetch timestamps + journal entries |\n| Proposals embedded in chat                                  | ✅ `actions[]` array on messages                                | Wire to `proposal-service` + Capability Fabric invocation               |\n| Entity snapshots inline                                     | ✅ `EntitySnapshot` render                                      | Connect to D1 entity reads through canonical entity-type-to-table map   |\n| Memory refs visible                                         | ✅ `memoryRefs` + `memoryCommit`                                | Connect to Memory layer L7 + Triage per-message                         |\n| Source-grounded \"via GitHub / via Salesforce\"               | ✅ Panel component renders                                      | Connect to real connector sync status indicators                        |\n| Confidence shown, not hidden                                | ✅ `confidence: 0.86%` rendering                                | Connect to live AI inference calibration                                |\n| One-action-at-a-time, actionable                            | ✅ Recommendation + chips                                       | Connect to Capability Fabric persona-aware chips                        |\n| User approves before any execution                          | ✅ Approve button → Bench                                       | Wire to L7 governance token minting + audit                             |\n\n**The architecture, components, types, render code — all intact. The live data binding is the work.** That binding is the difference between IntegrateWise as a product and IntegrateWise as a demo.\n\n---\n\n## 10. Capabilities in the Workspace — Inline Actions, Sync Modes, Cross-Tool Composition\n\n### The Doctrine\n\n**L1 workbench is not a viewer. Buttons on the workbench are Capability Fabric invocations**, not navigation. Every action a user can take on an entity card is a registered capability with:\n\n- Input/output schema\n- Required Spine context scopes\n- Allowed sync modes (soft / real / both)\n- Default confidence threshold\n- Default governance posture\n- Evidence chain template\n- Audit log entry shape\n\n### Capability Invocation Surfaces\n\n```\nWorkbench (L1)        — entity card buttons, list row actions\nEntity Twin Panel     — Accept & act chip → capability invocation\nTwin chat (L3)        — message.actions → capability invocation\nCLI (L4)              — `iw capability <name> --context <entity>`\nSlack/Teams (Layer 8) — shortcut button → capability invocation\nMobile (L1)           — touch-target capability button\n```\n\n**One capability, every surface.**\n\n### Three Sync Modes Per Capability\n\n| Mode                                              | Behaviour                                                                                                                                                                                                  | Default for                                                                                                                           |\n| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| **Soft sync (write staging)**                     | User acts in workbench → Spine written atomically → Connector Hub enqueues downstream → background worker reconciles to source tool. User sees result in seconds. Tool sees change when its adapter ticks. | Healthcare compliance entities, finance audit-trail entities, HR people records — latency-insensitive, mutability-sensitive           |\n| **Real sync (write-through)**                     | User acts → Spine written atomically AND source tool called via connector adapter → both succeed → commit logged. Failure triggers rollback + audit.                                                       | Daily-use mutations (Sales activities, support tickets, message sends) where \"I acted, it should be live now\" is the user expectation |\n| **Propose → Approve → Execute (Twin governance)** | Twin proposes → user approves → governance token minted → Spine AND source tool written in same transaction → audit-trail logged                                                                           | High-stakes mutations (mark at-risk, change ownership, fire rollback, change comp band)                                               |\n\n**The user's IT sets the per-capability default sync mode during onboarding, not per-action in the moment.** Persona defaults pre-configured:\n\n| Persona         | Soft                               | Real                        | Propose                                |\n| --------------- | ---------------------------------- | --------------------------- | -------------------------------------- |\n| Sales           | SFDC writes                        | Activity logs               | \"mark at-risk\", \"remove from forecast\" |\n| CS (Healthcare) | HIPAA-adjacent entities (BAA, PHI) | Routine CS updates          | \"mark renewal risk\"                    |\n| HR              | Comp band updates                  | Skip-level calendar updates | Any \"mark flight risk\"                 |\n| Eng             | Sprint status writes               | Incident acknowledgment     | Rollbacks, post-window deploys         |\n\n### Example Capabilities and Their Workbench Surfaces\n\n| Capability                  | Surface                        | Sync Mode                         | Persona        |\n| --------------------------- | ------------------------------ | --------------------------------- | -------------- |\n| `mark_lead_active`          | Sale entity card               | Soft sync to CRM                  | Sales          |\n| `view_contact`              | Contact card                   | Read; no mutation                 | All            |\n| `update_field`              | Field-level edit on any entity | Soft sync default                 | Persona-shaped |\n| `log_activity`              | Activity timeline chip         | Real sync                         | Sales, CS, HR  |\n| `draft_outreach`            | Outreach chip                  | Twin proposes; soft-send to email | Sales, CS      |\n| `schedule_call`             | Calendar chip                  | Real sync to Calendar             | Sales, CS, HR  |\n| `mark_renewal_risk`         | Renewal card chip              | Propose-gate (≥ 0.85)             | CS, RevOps     |\n| `update_health_score`       | Health tile                    | Soft sync external CRM            | CS             |\n| `schedule_blog_post`        | Website Manager chip           | Composed; brand gate; atomic      | Marketing      |\n| `swap_image`                | Asset Library → page ref       | Real sync to CMS + DAM            | Marketing      |\n| `mark_campaign_active`      | Campaign chip                  | Real sync UTM + CRM               | Marketing      |\n| `acknowledge_incident`      | Incident timeline              | Real sync (latency-sensitive)     | Eng            |\n| `pre_draft_rollback`        | Incident chip                  | Propose-gate                      | Eng            |\n| `schedule_post_mortem`      | Incident chip                  | Real sync Calendar + Notion       | Eng            |\n| `mark_person_flight_risk`   | Person card chip               | Propose-gate + governance         | HR             |\n| `update_comp_band_edge`     | Person card chip               | Propose-gate + multi-approval     | HR             |\n| `schedule_skip_level`       | Person card chip               | Real sync Calendar                | HR             |\n| `update_pipeline_coverage`  | Pipeline chip                  | Twin computes; soft-sync forecast | RevOps         |\n| `flag_reconciliation_delta` | Pipeline chip                  | Propose-gate (cross-team)         | RevOps         |\n| `close_invoice`             | Invoice chip                   | Real sync NetSuite/Stripe         | Finance        |\n| `sign_contract`             | Contract chip                  | Propose-gate + e-signature        | Legal          |\n\n### Cross-Tool Field Composition — The Website Manager (Canonical Example)\n\nThe Website Manager is **the canonical demonstration of cross-tool field fusion inside one workbench surface**. From the doctrine:\n\n> _\"Website manager should be a point where it shows the number of user visits, the blog content, linking the content, images, and so multiple.\"_\n\nOne Persona (Lila / Marketing × Retail / Commerce). One workbench surface. **Five tools' canonical state fused**, governed by the same Twin, capable of one-click inline actions.\n\n| Surface Tile         | Composed From                                                                                       |\n| -------------------- | --------------------------------------------------------------------------------------------------- |\n| **Total Pages**      | Sanity / Contentful + WordPress schema                                                              |\n| **Monthly Visitors** | Cloudflare Analytics + Plausible                                                                    |\n| **SEO Health**       | Ahrefs / Semrush + Search Console                                                                   |\n| **Uptime**           | StatusCake + Cloudflare health checks                                                               |\n| **Traffic Chart**    | GA4 + Plausible + UTM tools                                                                         |\n| **Core Web Vitals**  | PageSpeed + Search Console (LCP/FID/CLS with thresholds)                                            |\n| **Device Breakdown** | GA4 + Plausible (Desktop/Mobile/Tablet %)                                                           |\n| **Traffic Sources**  | Analytics + UTM (Organic/Direct/Social/Referral/Paid)                                               |\n| **SEO Issues**       | Search Console + Semrush crawl (type/message/severity/fix-it link)                                  |\n| **Top Pages**        | Sanity CMS + GA4 (title, path, traffic, status, \"Edit\" chip)                                        |\n| **Recent Edits**     | Sanity + Ghost + Webflow (page, action, author, time)                                               |\n| **Posts List**       | Notion drafts + Sanity published + Ghost scheduled (title, status, view count, comments, SEO score) |\n| **Asset Library**    | ImageKit / DAM / Cloudinary (image/video/document, dimensions, \"Used in N pages\")                   |\n| **Campaigns**        | Marketo / HubSpot + GA4 + Plausible (active, attribution, conversion)                               |\n\n### The `schedule_blog_post` Capability — Composed Invocation\n\nInputs pulled from multiple systems:\n\n```\ninputs:\n  draft_content:        <from Notion draft ID>\n  canonical_image:      <from ImageKit ID>\n  publish_target:       <to Sanity via CMS adapter>\n  social_amplification: <to Buffer / native social APIs>\n  email_blast:          <to HubSpot / Customer.io>\n  analytics_tile:       <Plausible / GA4 attribution link>\n  seo_check:            <via Semrush cheat sheet>\n```\n\nCompose, gate, execute:\n\n1. **Read inputs** across Notion, ImageKit, Buffer, HubSpot, Plausible.\n2. **Brand compliance check** — Twin compares draft to user's brand voice playbook (Memory layer).\n3. **Brand gate failure?** — Twin flags diff. User approves modification or proceeds without (« Softer mode » / bypass).\n4. **Gather all writes** into one orchestration plan.\n5. **Approve once** — single token mint.\n6. **Atomic commit across all systems** — single transaction, single audit entry.\n7. **Capability complete** — user sees in workbench view, all systems updated, audit logged.\n\n**Capabilities compose across tools. Workbench is capable. Persona-aware. Governed.** That is the action-doctrine of IntegrateWise made visible in L1.\n\n---\n\n## Closing — The Integrated Schema\n\nThe marketplace user is Maya, Sana, Tomás, Nadia, Lila, or Arjun — one of six personas. They install from a marketplace listing targeting their persona. OAuth passes identity only. **Onboarding captures what OAuth cannot.** `tenant_spine_config` commits. D1 Spine partitions load from the connector canonical state. L1 workbench renders persona-shaped projections. L2 signals fire read-side over Spine without LLM. L3 Twin hydration assembles persona sources through the activation gate. L4 Knowledge surfaces memory from the 8-layer pipeline. The Brainstorming Layer holds conversational working memory. The Capability Fabric executes inline actions through three sync modes, governed per tenant default.\n\n**L1 data load: not OODA. L1 AI on loaded data: OODA, proactive, no re-asking. L2: read-side Observe + Orient. L3: full OODA, user-contextual, activation-gated.**\n\n**Truth you own. AI you rent. Approval in between. Continuity over asking.**\n\nThat is the entire marketplace onboarding × persona design, grounded in the source code, the IntegrateWise doctrinal foundation, and the **structural reality that ChatGPT and Claude authenticators cannot and will not pass persona context** — only an in-place onboarding phase can.\n"}