Customer Zero to External Product and Marketplace Specification

Status: Governing derived implementation specification
Date: 2026-07-29
Authority: ARCHITECTURE_LOCK.md, IMPLEMENTATION_CONTRACT_v1.1.md,
CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md,
IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md and
FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md

The code-facing implementation handoff for the hosted Customer Zero/Plugin
repository is CUSTOMER_ZERO_HOSTED_PLUGIN_CODE_BRIEF.md. The matching full
browser Workbench and MCP handoff is
BROWSER_FRONTEND_AND_MCP_PRODUCT_CODE_BRIEF.md.

1. Decision

IntegrateWise is implemented for Customer Zero first and then promoted to
external customers from the same versioned product line.

There are:

• one shared Platform;
• one entity-based Spine contract;
• one Gateway and identity boundary;
• one public IW Spine Tools contract of exactly 19 semantic tools;
• two Product repositories/surfaces;
• two audience profiles;
• two marketplace distribution categories;
• four runtime profiles.

There are not separate Customer Zero and external-customer products, schemas,
agents, tool semantics or execution systems.

                           ONE INTEGRATEWISE PLATFORM
                                      │
                     Gateway · Identity · Activation
                    Operational Spine · Canonical Spine
                  Projection · Twin · Capability · Governance
                           Hermes · Sync · Audit
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
          Hosted/Plugin Product repo          Browser Frontend repo
                    │                                   │
         ┌──────────┴──────────┐             ┌──────────┴──────────┐
         │                     │             │                     │
 Customer Zero Plugin   External Plugin   Customer Zero MCP   External MCP
       profile              profile       Workbench profile   Workbench profile

Customer Zero is the first production tenant and the proving environment. It is
not a code fork, demo database, shared credential pool or template whose data is
copied to customers.

2. The three classifications

The words repository, audience and marketplace describe different
dimensions. They must not be collapsed into one label.

2.1 Repository

Repository answers: Which Product surface owns the presentation?

Repository	Primary responsibility
Hosted Application / Plugin repository (currently the Customer Zero application repository)	Focused host-embedded application, MCP App resources, Plugin package, skills, templates and host hand-off
Frontend repository	Full browser Workbench, tables, pages, canvases, Platform modules, administration and MCP-marketplace browser launch
Platform repository	Gateway, identity resolution, Activation, Integration, Pipeline, Operational Spine, Canonical Spine, Projection, Twin, Capability, Governance, Hermes, Sync, public MCP and internal MCP Pool

2.2 Audience

Audience answers: Whose tenant and entitlements are active?

Audience profile	Tenant behavior
Customer Zero	Resolves authenticated IntegrateWise operators to tenant iw-customer-zero; uses production-grade IntegrateWise-owned connections and policies
External Product	Resolves every authenticated installation/user to its own customer tenant, workspace, membership, policy and connection bindings

2.3 Marketplace category

Marketplace answers: How does the user discover and enter the Product?

Marketplace category	Published artifact	Primary surface
Plugin marketplace / directory	IW-Spine-Network Plugin	Focused embedded host UI controlled by ChatGPT/Codex or another compatible AI host
MCP marketplace / registry	IW-Spine-Network MCP	Remote 19-tool MCP with text/JSON fallback, optional focused widgets and Open Workbench

The IntegrateWise Connector Marketplace is a third, internal Product
function. It is the provider-connection tray after IntegrateWise has been
installed. It is not the Plugin package or the MCP package.

3. The four runtime profiles

Profile ID	Audience	Entry category	Product surface	Tenant resolution	Capability exposure
cz-plugin	Customer Zero	Private/staged Plugin installation	Embedded hosted application	Server resolves iw-customer-zero from membership and installation binding	Public 19 tools for Product work; internal operator capabilities only through separately governed Platform administration
external-plugin	External users	Public Plugin marketplace/directory	Embedded hosted application	Host installation + IW identity resolve customer tenant/workspace	Public 19 tools plus capabilities explicitly permitted by tenant Discovery
cz-mcp-workbench	Customer Zero	Private/staged MCP connection	Remote MCP + full browser Workbench	OAuth identity resolves iw-customer-zero	Public 19 tools for parity; internal MCP Pool remains a separate operator-only Platform module
external-mcp-workbench	External users	Public MCP marketplace/registry	Remote MCP + full browser Workbench	OAuth identity resolves customer tenant/workspace	Public 19 tools plus permitted tenant capabilities; no internal Pool topology

3.1 Parity rule

Customer Zero must prove the same customer-facing contracts external users will
receive:

• the same Plugin UI resource contract;
• the same MCP tool names, schemas and responses;
• the same discovery envelope;
• the same Four Buttons and human approval boundary;
• the same entity and projection contracts;
• the same Operational-to-Canonical lifecycle;
• the same failure, revoke and reconciliation semantics.

Customer Zero may additionally operate internal Platform modules because
IntegrateWise is also operating the Platform. Those operator privileges are not
part of either public marketplace package.

4. Shared Platform core

Both repositories and all four profiles communicate with the same Platform
contract:

Identity or host installation
→ Gateway
→ tenant + user + workspace + role resolution
→ Configuration
→ Integration
→ Activation
→ Discovery
→ Pipeline
→ Operational Spine
→ Projection / Context
→ Workbench or Plugin UI
→ Twin at THINK
→ Capability proposal
→ Governance approval
→ Hermes execution
→ provider outcome
→ Triage / reconciliation
→ governed promotion
→ Canonical Spine
→ projection refresh

The Platform remains Cloudflare-hosted even when a Product surface is deployed
on Vercel, Netlify, a Plugin host, an IDE or another application platform.

Neither Product repository owns:

• Fortress or canonical truth;
• provider OAuth tokens or API keys;
• raw connector runtimes;
• the internal MCP Pool;
• canonical writers;
• tenant policy authority;
• model/provider selection authority;
• approval-token minting;
• Hermes execution.

5. Hosted Application / Plugin repository

5.1 What it owns

The hosted application repository owns:

• the IW-Spine-Network Plugin package;
• MCP App UI resources and host bridge integration;
• focused views for current work, context, network status, search, proposal,
  approval and progress;
• Open Workbench hand-off;
• Plugin-specific skills and optional templates;
• Plugin listing metadata and reviewer fixtures;
• installation, consent and activation presentation;
• tenant-scoped surface operational state, event outbox, idempotency records,
  agent working memory and reconstructable projection caches;
• Customer Zero and external audience configuration profiles;
• typed contracts generated from the Platform contract.

5.2 What it does not own

It does not own:

• an independent authoritative Platform backend or canonical database;
• Customer Zero source credentials;
• external customer credentials;
• direct provider calls;
• direct Canonical Spine/Neon writes;
• direct Hermes or internal MCP Pool calls;
• host DOM, cookies, storage or unrelated host-app credentials;
• autonomous action approval.

5.3 Required repository shape

The exact framework may vary, but the responsibility split must be visible:

apps/
  plugin-surface/             # focused embedded UI
packages/
  plugin-manifest/            # listing and install metadata
  plugin-resources/           # MCP App resource declarations
  plugin-skills/              # governed workflow skills
  platform-client/            # generated public MCP/resource types
profiles/
  customer-zero/              # non-secret C0 policy/feature references
  external/                   # customer-safe defaults
tests/
  contract/
  host-sandbox/
  clean-install/

Secrets and tenant identities are injected by the deployment/identity layer.
They are never committed under profiles/.

5.4 Plugin request path

User clicks IW-Spine-Network Plugin
→ host verifies installation policy
→ Plugin initiates IW OAuth
→ Gateway resolves installation, user, tenant and workspace
→ Activation applies the selected versioned profile
→ host receives declared IW tools/resources
→ host renders the focused IW surface
→ user intent is sent through the host MCP App bridge
→ public IW tool is called
→ response returns to host and embedded UI

ChatGPT or another AI host owns the conversation, its native agents, its
schedules and its declared cross-app composition. IntegrateWise owns its Spine
context, Twin reasoning, capability resolution, governance and execution
contracts.

6. Frontend repository

6.1 What it owns

The frontend repository owns the complete browser Workbench:

• onboarding and activation presentation;
• shared sidebar and RBAC-projected navigation;
• Home, My Work, Communications, Personal and Work projections;
• tables, pages, database-style views and editable canvases;
• Platform and Administration modules permitted by Discovery;
• drafts, optimistic state, local UI preferences and bounded client caches;
• one typed Gateway client;
• MCP-marketplace Open Workbench entry and resume state;
• Customer Zero and external audience presentation profiles.

6.2 What it does not own

The frontend repository does not define separate department schemas or
customer-specific tables. It does not persist competing business truth.

It cannot call:

• Neon or any canonical database;
• provider APIs;
• credential storage;
• internal Worker services;
• the internal MCP Pool;
• Hermes;
• canonical writers.

6.3 Required repository shape

apps/
  workbench/                  # full browser application
packages/
  ui/                         # shared visual components
  projection-renderer/        # renders typed Projection contracts
  platform-client/            # one generated Gateway client
  workbench-state/            # drafts/preferences/bounded local state
profiles/
  customer-zero/              # C0 module defaults and branding references
  external/                   # customer-safe Product defaults
tests/
  contract/
  rbac/
  tenant-isolation/
  mcp-launch/

6.4 Browser request path

Browser session
→ Clerk authentication
→ typed Gateway client
→ GET /api/v1/workspace/discovery
→ tenant/user/RBAC/entitlement resolution
→ sidebar + projections + capabilities compose
→ projection reads and user intents
→ Platform responses populate tables/pages/canvases

/api/v1/workspace/discovery is the first canonical read for the browser and
for AI-driven composition. The browser does not determine its tenant, role,
permissions or internal service routes.

7. Audience profiles

Audience profiles are server-selected, signed deployment configuration. They
are not user-editable browser environment variables.

7.1 Customer Zero profile

audience_profile          = customer_zero
activation_profile        = iw-customer-zero@<version>
tenant_resolution         = membership_and_installation
expected_tenant           = iw-customer-zero
connector_ownership       = integratewise_operations
internal_admin_visibility = RBAC-gated
data_classification       = production_internal

Customer Zero:

• uses real IntegrateWise operational systems;
• has its own production credentials, queues, caches, evidence and audit;
• may expose Platform operator modules only to authorized IntegrateWise roles;
• cannot be used as generic development or marketplace-review data;
• proves the external Product contract before promotion.

The tenant value is verified after server-side membership resolution. A browser
or Plugin request cannot establish authority by sending
x-tenant-id: iw-customer-zero.

7.2 External profile

audience_profile          = external
activation_profile        = tenant-default@<version>
tenant_resolution         = identity_installation_membership
expected_tenant           = dynamic
connector_ownership       = customer
internal_admin_visibility = false
data_classification       = tenant_policy

External installation:

• creates or resolves a logically isolated tenant, account, workspace,
  membership and Spine Network inside the existing IntegrateWise-managed shared
  Platform;
• copies only versioned definitions/defaults from the proven activation
  profile;
• never copies Customer Zero records, memory, credentials, queues, cache,
  evidence or audit;
• presents provider choices through Connector Marketplace;
• derives projections from identity, RBAC, industry, department, role,
  connectors, data availability and policy.

8. Configuration and feature selection

The same build artifact must serve both audience profiles. Differences are
resolved through server-authoritative configuration:

Configuration	Customer Zero	External
Tenant	Fixed expected tenant after membership proof	Dynamically resolved customer tenant
Branding	IntegrateWise operational profile	Product/tenant branding policy
Platform modules	Operator modules permitted by RBAC	Customer-safe modules only
Internal MCP Pool	Operator-only Platform administration	Never exposed
Public tools	Exact 19-tool contract	Exact 19-tool contract
Connectors	IntegrateWise-owned real connections	Customer-selected connections
Models	Platform model policy	Tenant-entitled model policy
Projections	C0 roles and business context	Tenant RBAC × role × department × industry × available data
Data	C0 production tenant	Isolated customer tenant
Approval	Mandatory	Mandatory

Do not maintain long-lived customer-zero and external branches. Use one
trunk, versioned packages, profile validation and promotion.

9. Identity, authentication and consent

There is one identity node and one Platform authorization boundary.

9.1 Browser

Clerk session
→ Gateway validates token
→ resolves user, organisation, tenant, workspace and membership
→ injects trusted internal assertions
→ downstream services enforce RBAC and tenant scope

9.2 Plugin

host installation identity
+ IW OAuth identity
+ consented scopes
→ Gateway installation binding
→ tenant/workspace membership
→ permitted tools/resources

9.3 MCP

OAuth protected-resource discovery
→ authorization server
→ user consent
→ tenant-bound access token
→ exact permitted 19-tool catalog

Required lifecycle events are:

installation.created
installation.authorized
tenant.resolved
activation.started
activation.completed
consent.updated
connection.bound
installation.suspended
installation.revoked

API keys are limited to approved CLI/service scenarios. They are not the
default marketplace or browser authentication path.

10. Tenant, Spine and data contract

Every operational and canonical record is scoped by the applicable identity
tuple:

tenant_id
tenant_account_id
spine_network_id
workspace_id
entity_id or runtime_record_id
source_connection_id
provenance

The schema remains entity-based and tenant-level. Role, department and industry
change projection and activation configuration; they do not create department
databases or physical UI tables.

10.1 Operational and canonical split

source/host/provider event
→ Flow A/B/C/D classification
→ deterministic Normalizer
→ Triage organization
→ Operational Spine
→ search/index/context projection
→ proposal or promotion queue
→ human approval where required
→ Governed Spine Writer
→ Canonical Spine
→ operational rehydration

Operational state is bounded and reconstructable. Canonical truth persists in
the Fortress. Customer Zero and external tenants use the same lifecycle with
different tenant scope.

11. Discovery and connection behavior

Discovery is capability discovery, not credential discovery.

The response must distinguish:

Origin	Meaning
iw_direct	Provider connected through IntegrateWise Connector Marketplace
host_composed	Host can compose another app in the current session/conversation
host_delegated	Host and user/admin explicitly delegated a persistent capability to IW

If a host has ten or twenty connected applications, IntegrateWise does not
automatically receive their credentials or an unrestricted app inventory.

A persistent Spine Network binding requires:

• an IW direct connection; or
• a supported host delegation contract;
• explicit user/admin consent;
• tenant and provider-workspace resolution;
• capability and authority scope;
• provenance and revocation behavior.

Duplicate connections are grouped only when tenant, provider, provider account,
provider workspace, user/account authority and provenance match. The UI shows
each origin and the selected precedence or merge policy.

12. Plugin versus MCP marketplace

Concern	Plugin marketplace	MCP marketplace
Package	IW-Spine-Network Plugin	IW-Spine-Network MCP
Discovery	Plugin directory/host marketplace	MCP registry/directory/client
Primary controller	AI host	MCP client or IntegrateWise browser Workbench
UI	Focused sandboxed embedded UI	Text/JSON by default; optional widgets; full browser Workbench
Conversation/model	Host owns conversation and native model	Client owns its model; Workbench uses Platform model policy
Tool boundary	Exact 19 IW Spine Tools behind the Plugin	Exact 19 IW Spine Tools directly exposed
Host apps	Session composition or explicit delegation	Not assumed; use direct IW connections/delegation
Full tables/pages/canvas	Launch Workbench or bounded widget only	Full experience in browser Workbench
Offline/ordinary client	Host-specific	Meaningful text/JSON fallback required
Internal MCP Pool	Never published	Never published
Approval	Human approval mandatory	Human approval mandatory

The Plugin is the embedded daily-use entry. The MCP package is the universal
protocol entry plus standalone browser Product.

13. Frontend-to-Platform contract

Both Product repositories consume versioned public contracts. They do not know
internal service topology.

13.1 Browser transport

NEXT_PUBLIC_IW_API_URL
→ one typed Gateway client
→ authenticated versioned endpoints

13.2 Plugin transport

MCP App host bridge
→ declared public IW tool/resource
→ OAuth-protected MCP server
→ Gateway/Platform

13.3 Response requirements

Every response carries or resolves:

• contract version;
• request/correlation identifier;
• tenant/workspace scope;
• freshness and partial/degraded state;
• provenance/evidence references;
• allowed actions and approval requirements;
• pagination/version where applicable;
• no secrets or internal topology.

13.4 Interaction rule

user click
→ active entity/projection/selection intent
→ Context assembly + Search
→ OODA Observe/Orient
→ Twin participates at THINK only when useful
→ ranked linked entities/documents/signals/actions return
→ user may edit draft or request action
→ Decide/Approve remains explicit

14. Agents and model responsibility

Agents and models are part of the Platform contract even when the Product is
rendered inside an AI host.

Function	Owner
Host conversation, host-native agents and schedules	Plugin host
Triage classification, linking, prioritization and memory candidates	IntegrateWise Platform
Twin reasoning at THINK	IntegrateWise Platform
Capability discovery and resolution	Capability Fabric
Action authority	Human + Governance
Execution coordination	Hermes
Provider/model route, fallback, privacy and budget	Configuration/model policy
Outcome verification and reconciliation	Pipeline, Triage, Sync and Governed Spine Writers

The hosted UI and browser UI display agent state and invoke governed
capabilities. They do not instantiate uncontrolled authoritative agents.

15. Deployment topology

15.1 Development

• isolated non-production infrastructure;
• synthetic tenants and credentials;
• Plugin and MCP test hosts;
• no Customer Zero production data;
• visible demo/test state only.

15.2 Customer Zero

• production Platform partition and tenant iw-customer-zero;
• real Customer Zero connector bindings;
• private/staged Plugin package;
• private/staged MCP package and browser Workbench;
• production observability, audit, revocation and rollback;
• internal operator modules behind RBAC.

15.3 External Product

• shared multi-tenant Platform with strict isolation by default;
• separate logical customer tenant, connection and evidence scope inside the
  IntegrateWise-managed Platform account/environment;
• public Plugin and MCP packages;
• browser Workbench deployed as the external Product;
• dedicated physical partition only when approved enterprise isolation policy
  requires it.

Marketplace installation performs logical tenant activation and profile
compilation. It does not clone the Platform per click.

15.4 Initial shared-SaaS provisioning

No code, Worker, database, queue, bucket or frontend is deployed during ordinary
user onboarding.

Plugin install or MCP/browser signup
→ authenticate user
→ resolve or create logical tenant_account_id
→ resolve or create tenant_id
→ create workspace and membership
→ allocate stable spine_network_id
→ apply activation-profile definitions
→ initialize tenant-scoped operational state
→ start connector consent/discovery
→ return Discovery and render the Product

“Allocated in our tenant” means allocated inside the
IntegrateWise-managed shared SaaS environment. It does not mean placing
external users inside the Customer Zero tenant iw-customer-zero. Every
external organisation—or personal account where applicable—still receives a
separate logical tenant boundary enforced by Gateway, database policies,
connection bindings, queues/caches and audit scope.

15.5 Later dedicated-partition migration

The logical tenant identity remains stable if a customer later requires
dedicated infrastructure because of usage, data volume, connector load,
latency, residency, compliance or enterprise policy.

shared logical tenant
→ migration eligibility and approval
→ provision dedicated target partition
→ copy and verify tenant-scoped canonical/evidence state
→ replay bounded operational deltas
→ update server-side tenant routing
→ cut over with stable tenant_id and spine_network_id
→ verify, monitor and retain rollback window

Product code, Plugin manifests, MCP tool contracts and frontend URLs do not
change during this migration. Only the Platform’s trusted tenant-routing and
storage bindings change.

16. Customer Zero-first implementation sequence

Phase 1 — Shared contracts

1. Freeze exact 19 tools, resource schemas, UI intents and discovery envelope.
2. Generate typed clients/resources for both Product repositories.
3. Implement one identity, tenant and installation binding contract.
4. Implement versioned Customer Zero and external activation profiles.

Phase 2 — Customer Zero Plugin

1. Build focused embedded UI.
2. Connect it through the host MCP App bridge.
3. Install privately in the Customer Zero host workspace.
4. Resolve iw-customer-zero through identity/membership.
5. Prove host composition, direct connections and explicit delegation.
6. Prove proposal, approval, Hermes and outcome reconciliation.

Phase 3 — Customer Zero MCP and Workbench

1. Deploy OAuth-protected remote MCP.
2. Verify exactly 19 tools.
3. Implement text/JSON fallback and optional widgets.
4. Launch the Customer Zero browser Workbench.
5. Prove discovery-first composition, RBAC and entity projections.
6. Prove internal Pool remains separate from the public MCP.

Phase 4 — Externalization

1. Remove every fixed Customer Zero assumption from customer-facing code.
2. Install the same artifacts into a synthetic clean external tenant.
3. Verify dynamic tenant resolution and customer-owned connectors.
4. Verify no C0 data, credential, cache, queue, evidence or audit crossover.
5. Verify external module and capability visibility.

Phase 5 — Publication

1. Freeze the exact Customer Zero-verified versions.
2. Produce Plugin and MCP listing assets.
3. Submit IW-Spine-Network Plugin.
4. Publish IW-Spine-Network MCP.
5. Verify public installation into a new tenant.
6. Monitor, support, version, revoke and deprecate through governed releases.

17. Promotion rule

source commit
→ CI and contract tests
→ Development artifacts
→ Customer Zero private installation
→ Customer Zero evidence
→ version freeze
→ external clean-tenant test
→ Plugin/MCP submission-ready
→ public publication

Only code, manifests, definitions, schemas and versioned activation defaults
are promoted. Tenant data and runtime state never cross environments.

Rollback returns both Product repositories and Platform contracts to the last
compatible version. Plugin, MCP, frontend and Gateway compatibility must be
recorded in the release manifest.

18. Customer Zero exit gates

Customer Zero is complete only when all of the following are proven:

Shared Platform

• Gateway, identity, Neon, D1, KV, R2, queues and secrets are healthy;
• Development and Customer Zero resources are isolated;
• migration ledger and schema verification pass;
• tenant/RBAC negative tests pass;
• no frontend or Plugin direct-service bypass exists.

Plugin

• clean private install succeeds;
• OAuth, consent, resume and revoke succeed;
• embedded UI renders under host sandbox/CSP;
• no host DOM or credential inheritance occurs;
• explicit delegation and direct connector paths are distinguishable;
• approval and outcome lifecycle is visible.

MCP and browser

• protected-resource metadata is correct;
• exact 19-tool catalog is returned;
• ordinary-client fallback is meaningful;
• Open Workbench preserves authenticated tenant context safely;
• discovery is the first Workbench read;
• all visible modules are projection/RBAC-backed.

Data and execution

• one connector completes consent, mapping, hydration, delta sync, health,
  revoke and reconciliation;
• Flow A/B/C/D classification is traceable;
• idempotency, retry, DLQ, replay and ambiguous outcomes are proven;
• promotion queue and human approval protect canonical truth;
• Hermes cannot execute without a scoped approval token;
• provider outcome re-enters Triage and refreshes projections.

19. External Product release gates

External publication additionally requires:

• clean installation into an unrelated tenant;
• dynamic identity and tenant resolution;
• Customer Zero isolation proof;
• customer-owned credential lifecycle;
• tenant-specific connector and projection availability;
• duplicate connection/provenance behavior;
• privacy, terms, support, screenshots and reviewer evidence;
• rate limits, quotas, monitoring and incident ownership;
• revocation, deletion, export and offboarding behavior;
• compatible Plugin, MCP, frontend and Platform version matrix.

20. Stop-ship conditions

Do not publish or begin the external testing event if:

• Customer Zero and external code have diverged into product forks;
• a Product repository contains credentials or canonical business truth;
• tenant authority is accepted from a browser/header without membership proof;
• the Plugin or MCP exposes anything other than the approved public tool
  contract;
• the Plugin claims automatic access to other host-app credentials;
• the MCP package lacks ordinary-client fallback or browser Workbench launch;
• Customer Zero state is copied into an external tenant;
• internal MCP Pool topology is exposed;
• Twin, an agent, a host or an auto-tuner can bypass human approval;
• a Product surface calls providers, databases, Hermes or internal services
  directly;
• a Customer Zero-only feature is silently required for the external Product.

21. Definition of done

The implementation is done when:

1. both Product repositories build once and deploy with Customer Zero or
   external server-selected profiles;
2. both marketplace artifacts use the same exact 19-tool Platform contract;
3. Customer Zero runs daily work through both the Plugin and browser Workbench;
4. the same versions install into a clean external tenant without code changes;
5. tenant data, credentials and runtime state remain isolated;
6. every visible read and action maps to a versioned Platform contract;
7. every external action remains human-approved, governed, audited and
   reconciled;
8. Plugin and MCP publication packages pass their respective review and
   installation gates.