Current

IntegrateWise — Customer Zero and External Product Split Specification

Status: Current
Date: 2026-07-29
Authority: HERMES.md, ROUND_EXECUTION_SEQUENCE.md, IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md

1. Purpose

This document defines the canonical three runtime profiles for IntegrateWise:

Dev Internal
Customer Zero
External Product

It specifies:

The three runtime profiles inside one codebase
The two frontend activation modes inside one app
The two marketplace lanes: Plugin marketplace vs MCP marketplace
How the platform repo maps to all profiles

2. Canonical Runtime Profiles

Path	Audience	Isolation	Purpose
Dev Internal	IW engineers	Local workstation, full DB access, seed data	Build, debug, prove end-to-end
Customer Zero	IW’s own production tenant (`iw-customer-zero`)	Isolated tenant, isolated operational partition	Prove the exact runtime shape external users will receive
Product to Users / External GTM	External customers	Tenant-isolated shared Platform or dedicated deployment	Public install/connect via Vercel/Cursor/MCP Directory/ChatGPT

Rule: The platform repo is the single source of truth for all three profiles. The split is runtime-context-driven, not branch-driven. Customer Zero is not a separate product; it is the reference activation profile. External users receive the same software, parameterized by tenant.

3. Repository Split Strategy

One repository, integratewise-live, serves all three profiles. The split is tenant/runtime-context-driven, not branch-driven.

integratewise-live/
├── services/
│   ├── gateway/
│   ├── spine/
│   ├── mcp-connector/
│   └── ...
├── apps/web/
├── packages/
├── marketplace/
├── docs/
└── migrations/

Rule: Every commit must be valid for all three profiles unless explicitly gated by tenant/context headers.

3.1 Single Codebase, Three Runtime Profiles

Profile	How selected	Tenant	Data	Deployment
Dev Internal	Local env / seed auth	Local dev tenant	Local Neon or Docker Postgres; seed data allowed	Local Workers / turbo dev
Customer Zero	Header `x-tenant-id: iw-customer-zero` or dedicated host `customer-zero.integratewise.ai`	`iw-customer-zero`	Real isolated operational partition; real providers, real audit, real queues	Cloudflare Workers + dedicated Neon database
External Product	Header `x-tenant-id: <external-tenant>` or marketplace installation JWT	`<tenant-slug>` generated at install/activation	Tenant-isolated data in shared schema; strict row-level isolation	Cloudflare Workers shared stateless deployment + shared Neon with RLS, or dedicated physical deployment if approved isolation policy requires

3.2 Feature/Config Gating

IF profile == Dev Internal
  → allow local seed data, local DB, full diagnostic routes, internal pool access
  → skip production-only gates
ELSE IF tenant == 'iw-customer-zero'
  → enable internal telemetry, raw diagnostic routes, debug surfaces, seed tools
  → allow internal-only connector bindings
ELSE IF profile == External Product
  → disable diagnostic routes
  → enforce 19-tool public contract only
  → enforce scoped OAuth
  → enforce approval-required governance

Implementation: Gate by tenant_id + request.origin + JWT aud. Do not branch code.

4. Frontend Split Strategy

apps/web is a single Next.js application with two runtime contexts.

4.1 Single App, Two Activation Modes

Mode	Trigger	URL pattern	Behavior
Customer Zero	Login with `@integratewise.ai` email or `x-tenant-id: iw-customer-zero`	`/app/platform`	Full admin surfaces, internal connector tray, raw audit, seed data controls, 55-tool internal MCP pool visibility
External Product	Marketplace installation JWT or external email domain	`/app/platform`	Reduced 19-tool surface, no internal diagnostics, no raw pool visibility, tenant-scoped projections only

4.2 Frontend Boundary Rules

Customer Zero frontend may call the full Gateway surface, including internal diagnostics, because the operator is IW itself.
External Product frontend must call only NEXT_PUBLIC_IW_API_URL and must never:
- call databases directly
- call providers directly
- call Hermes directly
- call the internal MCP Pool directly
- infer architecture or reconstruct tenant state from URL/client hints
Both modes share the same PlatformShell.tsx, PlatformNav.tsx, and component tree. Differences are rendered by server-resolved identity/roles in /api/v1/workspace/discovery.

5. Marketplace Lane Definitions

5.1 Plugin Marketplace Lane

Attribute	Value
Lane name	Plugin marketplace / directory
Host environment	ChatGPT, Codex, compatible AI hosts
Publication artifact	Not a separate package
User experience	User installs IW-Spine-Network from the MCP marketplace; ChatGPT renders a thin IW-created overlay UI inside ChatGPT
Control model	ChatGPT is the operator; IW is the governed interface
Capability discovery	Host-composed + host-delegated + IW-direct, through supported host contracts
Credential inheritance	Never automatic; only explicit host delegation or direct IW connector binding
UI surface	Thin overlay widgets: active work/context, Spine status, approval confirmation, execution progress, Open Workbench
Fallback	Text/JSON if host does not support MCP App widgets

Rule: There is no IW-Spine-Network Plugin package published separately. The plugin-lane description in old docs is superseded.

5.2 MCP Marketplace Lane

Attribute	Value
Lane name	MCP marketplace / registry / directory
Host environment	Any MCP-compatible client: Cursor, Windsurf, Claude Desktop, Vercel Agent Tools, custom clients
Publication artifact	`IW-Spine-Network MCP`
User experience	User connects the remote MCP server; browser Workbench launches for full control
Control model	User operates through IW Workbench or host MCP client; IW governs all actions
Capability discovery	`iw_direct` primary; host composition/delegation if supported
Credential inheritance	Never; only explicit IW connector bindings
UI surface	Full standalone browser Workbench
Fallback	Text/JSON guaranteed

Rule: This is the only published marketplace artifact.

5.3 MCP Marketplace → ChatGPT Special Case

When the MCP marketplace install flow appears inside ChatGPT:

ChatGPT remains the conversational controller
ChatGPT may render an IW-hosted overlay widget inside its sandbox
That widget is thin: evidence display, approval confirmation, progress
ChatGPT uses the widget to call IW tools; ChatGPT does not receive IW credentials, internal pools, or provider access
The underlying publication is still IW-Spine-Network MCP

6. Customer Zero Implementation

6.1 Definition

Customer Zero is IntegrateWise’s own production tenant, identified by tenant_id = iw-customer-zero. It is not a test tenant. It is not shared. It is the reference activation profile.

6.2 What Runs in Customer Zero

Full Cloudflare Worker stack: Gateway, Spine, MCP Connector, Intelligence, Knowledge, Hermes, Pipeline, Governance State, MCP Pool
Dedicated/isolated Neon operational data
Real provider connectors (initial set: GitHub, Notion, Slack, Salesforce, HubSpot, Jira, Confluence, Coda, Google Calendar, Google Drive, Asana, Monday, Zendesk, Intercom, Stripe, Snowflake, BigQuery, Postgres, MySQL, GitLab, OpenAI, Anthropic, Perplexity)
Real OAuth + Clerk identity
Real queue/DLQ/audit
Full 19-tool public MCP surface
Internal diagnostic surfaces exposed only to @integratewise.ai identities

6.3 Customer Zero Platform Repo Mapping

Component	Service/Path	Customer Zero Behavior
Gateway	`services/gateway/src/index.ts`	Resolves `iw-customer-zero` tenant from Clerk JWT or trusted `x-tenant-id`; rewrites to internal Spine/MCP Connector; allows internal diagnostic routes
Spine	`services/spine/src/neon-workbench.ts`	Queries dedicated Customer Zero Neon database; full workbench/activities/entities/knowledge/memories; no row-level tenant restriction beyond single-tenant DB
MCP Connector	`services/mcp-connector/src/continuity-bridge.ts`	Exposes 19 public tools + internal 4 tools; `createContinuityBridgeServer` called with internal scope; diagnostic `/v1/continuity-bridge/*` routes active
Web App	`apps/web`	Full admin UI, internal connector tray, raw audit, seed data, 55-tool internal MCP pool visible to IW staff
Platform Shell	`apps/web/src/components/platform/PlatformShell.tsx`	Renders all 12 surfaces including Governance with Twin rail, KPI strip, capability actions, full action strips
Marketplace Install	`/api/v1/marketplace/installations/*`	Customer Zero is pre-installed; installation state shows `active`
Workspace Discovery	`/api/v1/workspace/discovery`	Returns Customer Zero workspace: all projections, all capabilities, all connectors, all approvals, all continuity

6.4 Customer Zero Activation Profile

Customer Zero is activated once, manually, by IW founders:

Provision iw-customer-zero tenant in tenants service
Create dedicated Neon database or schema with RLS bypass
Bind Clerk org/team to iw-customer-zero
Apply migration 035 + all subsequent migrations
Seed initial connectors, connectors catalog, connector installations
Enable internal MCP pool routes
Set IW_CUSTOMER_ZERO=true in Worker environment
Verify /api/v1/workspace/discovery returns full Customer Zero projection

After activation, Customer Zero is treated as a first-class production tenant.

7. External Product Implementation

7.1 Definition

External product is the same codebase and same workers, compiled and deployed for external tenants. No code fork. No separate frontend repo.

7.2 How It Differs from Customer Zero

Attribute	Customer Zero	External Product
Tenant ID	`iw-customer-zero` (hardcoded allowed, but resolved from auth)	Auto-generated at activation (`tenant-<slug>`)
Neon access	Dedicated DB or schema; no RLS needed	Shared DB with strict RLS; row-level tenant isolation enforced on every query
MCP Connector	19 public + 4 internal tools; diagnostic routes enabled	19 public tools only; internal 4 tools return 403/404; diagnostic routes disabled
Gateway	Allows internal routes; rewrites to internal MCP pool	Rewrites only to public Spine + public MCP pool; rejects internal paths
Web App	Full surfaces, internal tray, seed data	Reduced surfaces; no internal tray; no seed data; no raw pool
Marketplace	Pre-installed; `active` state	Install flow: OAuth → tenant creation → activation → `active`
Discovery	Returns everything	Returns only permitted projections, capabilities, connectors, approvals, continuity for that tenant
Approval	Optional for internal IW actors	Mandatory for all governed actions
OAuth scopes	Full internal scopes allowed	Strict scoped OAuth; `mcp:tools` is not a blanket grant
Telemetry	Full raw logs, internal metrics	Aggregated anonymized metrics; no internal stack traces

7.3 External Tenant Activation

External user installs IW-Spine-Network MCP from marketplace
→ OAuth handshake with Clerk
→ Gateway creates/activates tenant slug
→ tenants service records tenant, membership, roles
→ Activation applies Customer Zero-proven reference profile (same code path)
→ Spine creates tenant-scoped schema/rows in Neon
→ MCP Connector issues 19-tool scoped catalog
→ Browser Workbench launches at /app/platform
→ Host-compatible clients receive widgets through MCP App metadata

Rule: The same activateCustomerZeroProfile code path runs for external tenants. It is parameterized by tenant_id. Customer Zero just passes a fixed tenant_id.

8. Platform Repo Mapping

The platform repo (integratewise-live) owns all services, migrations, packages, marketplace definitions, and docs. It does not fork per lane.

8.1 Directory Ownership

Directory	Customer Zero	External Product
`services/gateway/`	Full route table including internal; allows `x-tenant-id: iw-customer-zero` bypass for inter-service calls	Public route table only; rejects internal paths
`services/spine/`	Full Neon queries; can cross tenant context for internal diagnostics	Row-level tenant isolation enforced in every query helper
`services/mcp-connector/`	19 + 4 tools; diagnostic routes; internal scope map	19 tools only; no diagnostics; strict public scope map
`services/tenants/`	Pre-seeded `iw-customer-zero`	Onboarding API: create/activate/resolve tenant
`services/governance-state/`	Full audit, approval, checkpoint	Same, scoped to tenant
`apps/web/`	Full 12-surface PlatformShell	Reduced 12-surface PlatformShell; internal surfaces return 403
`marketplace/apps/iw-spine-network.json`	Same manifest; debug metadata included	Same manifest; no debug metadata
`docs/`	Full internal docs	Public docs subset
`migrations/`	Applied once to shared or dedicated DB	Applied to shared DB; RLS policies enforced

8.2 Runtime Branching

Branching inside the platform repo must be by tenant_id or request.origin, never by separate code paths.

// Example: gateway route gating
const isInternalTenant = tenantId === "iw-customer-zero";
const isInternalOrigin = request.headers.get("x-origin")?.includes("integratewise.ai");

if (!isInternalTenant && !isInternalOrigin && isInternalRoute(path)) {
  return new Response("Forbidden", { status: 403 });
}

// Example: mcp-connector tool gating
const publicTools = PUBLIC_CONTINUITY_BRIDGE_TOOL_DEFINITIONS; // 19
const internalTools = INTERNAL_CONTINUITY_BRIDGE_TOOL_DEFINITIONS; // 4

if (tenantId === "iw-customer-zero") {
  server.setRequestHandler(ListToolsRequestSchema, () => ({
    tools: [...publicTools, ...internalTools],
  }));
} else {
  server.setRequestHandler(ListToolsRequestSchema, () => ({
    tools: publicTools,
  }));
}

9. Frontend Duality

9.1 Customer Zero Frontend

Route: /app/platform
Auth: Clerk with @integratewise.ai approved domain
Surfaces: all 12 surfaces active
Capability actions: full set including internal connectors, seed data, diagnostic actions
Projections: full unfiltered
Marketplace: shows installation state; can re-activate/reset external tenants
Twin panel: full silent Twin surface with internal proposal types
Action strip: reply, reply all, archive, compose, assign Twin, store in Spine, propose action, approve action, run diagnostic

9.2 External Product Frontend

Route: /app/platform
Auth: Clerk with external email domain or marketplace JWT
Surfaces: all 12 surfaces present, but internal surfaces return empty or reduced view
Capability actions: only permitted capabilities for that tenant
Projections: tenant-scoped, RBAC-filtered
Marketplace: installation entry point only; no admin controls
Twin panel: Ask Your Twin, Assign Your Twin, Review Twin’s Work only
Action strip: reply, reply all, archive, compose, propose action (requires approval), approve action (if authorized), store in Spine

9.3 Server-Resolved Identity

The frontend must not infer lane from URL or client hints. It must call /api/v1/workspace/discovery first and let the server return:

{
  "actor": {
    "tenant_id": "acme-corp",
    "user_id": "user_123",
    "email": "user@acme.com",
    "roles": ["admin"],
    "lane": "external_product"
  },
  "workspace": { ... },
  "available_surfaces": ["dashboard","marketplace","governance","twin","continuity"],
  "available_actions": ["reply","reply_all","archive","compose","propose_action","approve_action","store_in_spine"],
  "internal_surfaces": false,
  "internal_actions": false
}

Frontend renders conditionally from available_surfaces, available_actions, internal_surfaces, internal_actions.

10. Deployment Model

10.1 Customer Zero Deployment

Workers: dedicated or tagged with IW_CUSTOMER_ZERO=true
Database: dedicated Neon database or schema
Domains:
- gateway.integratewise.ai → Customer Zero Gateway
- workbench.integratewise.ai → Customer Zero Workbench
- marketplace.integratewise.ai → Customer Zero Marketplace
Auth: Clerk production org with @integratewise.ai domain
Secrets: Customer Zero secrets in Secret Store under CUSTOMER_ZERO_* namespace

10.2 External Product Deployment

Workers: shared stateless Platform Workers
Database: shared Neon with strict RLS
Domains:
- gateway.integratewise.ai → public Gateway (routes to shared workers)
- workbench.integratewise.ai → public Workbench
- marketplace.integratewise.ai → public Marketplace
Auth: Clerk production org with external domains + marketplace JWT
Secrets: per-tenant secrets in Secret Store under TENANT_<slug>_*

10.3 Deployment Isolation Matrix

Dimension	Customer Zero	External Product
Workers	Dedicated or tagged	Shared stateless
Database	Dedicated	Shared + RLS
Tenant ID	`iw-customer-zero`	Auto-generated
Auth domain	`@integratewise.ai`	External domains + marketplace
Internal routes	Exposed	Hidden
55-tool pool	Visible	Hidden
Diagnostic API	Enabled	Disabled
Seed data	Enabled	Disabled
Marketplace state	Pre-installed	Install → activate

11. Tenant Isolation Enforcement

11.1 Database Isolation

Customer Zero: direct connection, no RLS needed
External Product: every query includes tenant_id = $1 as the first bind parameter; RLS policy USING (tenant_id = current_setting('app.tenant_id')::text) enforced at database level

11.2 Gateway Isolation

Gateway overwrites caller-supplied tenant headers with verified JWT tenant
Internal x-tenant-id: iw-customer-zero is accepted only from trusted origins
External requests cannot forge Customer Zero identity

11.3 MCP Connector Isolation

ContinuityBridgeActor.tenant_id derived from Gateway, never from client
Tool scope map enforced per tenant
Internal tools require internal profile or iw-customer-zero tenant

11.4 Frontend Isolation

Frontend receives tenant context only from /api/v1/workspace/discovery
Frontend never stores tenant_id in URL, localStorage, or client state without server round-trip
Frontend never infers capabilities from URL or component visibility

12. Capability and Action Surface

12.1 Customer Zero Capabilities

Read/write/delete on all entities
Internal connector management
Diagnostic queries
Seed data import/export
Raw MCP pool invocation
All 19 public tools + 4 internal tools
Capability actions: reply, reply all, archive, compose, propose, approve, store_in_spine, project_context, relay_state, handoff_agent, delegate_action, run_diagnostic, reset_tenant, seed_data

12.2 External Product Capabilities

Read on permitted entities
Write only through governed proposals
No raw MCP pool
19 public tools only
Capability actions: reply, reply all, archive, compose, propose_action, approve_action, store_in_spine, ask_twin, assign_twin

12.3 Governance

Customer Zero: optional human approval for IW founders; internal actors can bypass with internal scope
External Product: human approval mandatory for all governed writes; no autonomous execution

13. Plugin Marketplace vs MCP Marketplace Summary

Dimension	Plugin Marketplace	MCP Marketplace
Published artifact	Not published separately	`IW-Spine-Network MCP`
Host	ChatGPT, Codex	Any MCP client + browser Workbench
UI	Thin overlay widgets	Full standalone browser Workbench
Control	ChatGPT operates; IW governs	User operates through IW Workbench
Discovery	Host composition + host delegation + IW-direct	IW-direct primary; host composition/delegation if supported
Credentials	Never inherited automatically	Never inherited automatically
Tools exposed	9-tool subset (chatgpt/claude/perplexity profile)	19-tool public contract
Approval	Mandatory	Mandatory
Fallback	Text/JSON	Text/JSON

14. Implementation Order for Claude Code / Claude Cowork

Round 1 — P0 contract/code alignment (current commit: 495a0295)
Round 2 — P0 infrastructure/auth: DNS/Clerk + single auth node + bindings audit
Round 3 — P1 Plugin + MCP + discovery: build both artifacts, implement discovery origins
Round 4 — P1 frontend/platform completion: enforce boundary, deploy discovery, remove direct calls
Round 5 — P1 Customer Zero testing: clean install, clean connect, governed action cycle, Flow A/B/C/D, aging, reconciliation
Round 6 — P2 publication: submit assets, Vercel native package, monitoring

Rule: Do not start Round 3 before Round 2’s auth/config prerequisites are committed. Do not start Round 5 before Round 4 is deployed to Customer Zero.

15. Acceptance Gates

Gate	Evidence required
P0 contract/code	`grep -R "IW-Continuity-Bridge"` returns zero hits in code; `typecheck` + `mcp-connector` + `gateway` tests pass
P0 infrastructure/auth	DNS resolves; Clerk JWT verifies; `tenants` service resolves `iw-customer-zero`; D1/KV/R2/secret bindings listed and present
P1 Plugin	`npm run build` succeeds; plugin OAuth flow completes in test; widget renders in host sandbox
P1 MCP	`server.json` validates; 19 tools listed; Open Workbench launch contract succeeds
P1 discovery	Three origins return distinct discovery payloads; duplicate detection works; credential scraping prevented
P1 frontend	`/api/v1/workspace/discovery` deployed; no `localhost` fallback in production build; no direct DB/provider calls in frontend bundle
P1 Customer Zero	Clean install into new tenant succeeds; exactly 19 public tools proven; governed action cycle end-to-end; Flow A/B/C/D proven
P2 publication	Marketplace listing live; Vercel native package installed; monitoring dashboard green