Status: HISTORICAL IMPLEMENTATION HANDOFF
Current frontend authority: docs/frontend-v0/README.md,
FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md
and TWIN_BEHAVIOR.md.

Do not implement the permanent Twin sidebar/panel or one-to-one UI/table
authority described below.

Original Snapshot: IntegrateWise v0 Frontend Spec

Status: Definitive alignment spec
Date: July 23, 2026
Scope: Frontend surfaces, backend service mapping, Twin/agent/memory/triage/continuity/capabilities/Spine network integration, interaction flow, and exhaustive one-to-one and cross-mapping tables for v0

---

1. Context

v0 is the first aligned frontend release after the canonical architecture correction. Its purpose is not to add new platform concepts, but to make the existing frozen product doctrine executable through one identity path, one public continuity contract, one truth path, one projection path, and one governed execution path.

The user must never be asked to explain context already held by the Spine Network. Twin inherits permitted active context, reads governed evidence, prepares work, and stays silent when there is no material contribution. All durable execution, approval, memory promotion, and canonical writes remain in the backend.

---

2. Current State of the Codebase

2.1 Frontend

• Marketing, auth, onboarding, and authenticated workbench routes exist under apps/web/src/app.
• AppShell.tsx manages stage flow: login → signup → provisioning → loading → workspace.
• Route rendering is centralized in apps/web/src/app/_components/route-views.tsx.
• Department/module routing is derived from @integratewise/workbench-config in apps/web/src/app/_lib/workbench-routes.ts.
• Reusable workbench views exist under packages/ui/src/views/*.tsx.

2.2 Backend Services

Canonical deployable services:

Service	Canonical Role
gateway	Public entry, JWT/tenant routing, projections, capability routing
pipeline	Normalization, triage, promotion, canonical writes
spine	Canonical read model and internal Spine operations
tenants	Tenant lifecycle, workspace context, plan limits
mcp-connector / mcp-pool	Inbound/outbound MCP pool, tenant-scoped tool routing
integration-management-mcp / provider-management-mcp	Integration and provider MCP surfaces
connector / connector-sync	Provider adapters, OAuth, sync, credential wall
normalizer / schema-ai	Schema discovery, normalization, canonical mapping
knowledge / continuity	Knowledge base, memory lifecycle, continuity substrate
intelligence / hermes / iw-agent-runtime	AI routing, orchestration, agent runtime
signals / telemetry	Signal interpretation, observability
govern / workflow / task-management	Approval, workflow, task accountability
store / admin / folder-watcher / webhook-ingress	Projection persistence, admin, telemetry, webhooks

Legacy aliases such as think, act, l2, and historical twin-orchestrator references are not canonical runtime entry points and must not be introduced as new frontend dependencies.

---

3. Correct Platform Sequence

User intent
  ↓
Twin
  ↓
Context Builder
  ↓
User / Work / Organization Memory
  ↓
Knowledge and AI Search
  ↓
Capability and Agent Resolver
  ↓
Governance
  ↓
Agent or capability execution
  ↓
Continuity runtime
  ↓
Triage candidates
  ↓
Approved Spine writes
  ↓
Updated projections
  ↓
Twin reports the result

Frontend ownership rules:

• The user interacts with Twin, not internal orchestrators.
• The Workbench renders governed projections only.
• Approval, execution, continuity, and memory promotion happen in the backend.
• The frontend never writes canonical state directly.

---

4. Frontend Surfaces and Functions

Frontend Surface	v0 Function	Owner
Marketing	Discovery, sign-in/sign-up, onboarding entry	Marketing
Onboarding	Intent capture, domain selection, connector setup, activation	Platform
Workbench shell	Navigation, context propagation, role-aware layout, Twin entry	Platform
Domain views	Projection-based operational surfaces	Platform
Twin sidebar/panel	Ask, analyze, explain, recommend, plan, delegate, act, continue, review, remember	Twin
Governance surface	Approval queue, proposal review, evidence, decision capture	Governance
Knowledge surface	Knowledge search, extraction feedback, document review	Knowledge
Memory surface	Memory triage, promotion review, contradiction review	Memory
Agents surface	Agent selection, task monitoring, outcome review	Twin/Agents
Capabilities surface	Capability discovery, execution, approval-state visibility	Capability Fabric
Continuity surface	Workflow status, retry/escalation state, completion tracking	Continuity
Admin surface	Users, roles, policies, connections, integrations, models, billing	Administration

---

5. Backend Service Mapping

Frontend Surface	Primary Backend Services	Secondary Backend Services
Marketing	gateway, tenants, mcp-connector	provider-management-mcp
Onboarding	gateway, tenants, pipeline, spine	integration-management-mcp, connector
Workbench shell	gateway, spine, projection-engine	store, signals, telemetry
Domain views	gateway, spine, pipeline	knowledge, signals
Twin sidebar/panel	intelligence, hermes, iw-agent-runtime	mcp-connector, knowledge, continuity
Governance surface	govern, workflow	gateway, task-management
Knowledge surface	knowledge	pipeline, spine, mcp-connector
Memory surface	continuity, knowledge	govern, pipeline, spine
Agents surface	iw-agent-runtime, agent-registry	intelligence, hermes, task-management
Capabilities surface	mcp-pool, integration-management-mcp	govern, hermes, provider-management-mcp
Continuity surface	workflow, task-management, continuity	hermes, signals, telemetry
Admin surface	gateway, admin, tenants	store, billing, provider-management-mcp

---

6. Twin Ownership

Twin is the primary intelligent actor visible to the user.

Twin responsibilities:

• Understands user intent
• Retrieves governed context
• Reasons over Knowledge and Memory
• Recommends actions
• Activates agents
• Selects capabilities
• Delegates work
• Requests approvals
• Tracks delegated outcomes
• Explains evidence and decisions
• Maintains continuity from the user’s perspective

Frontend implication: Every major surface is Twin-mediated. The Workbench never exposes raw backend control surfaces without Twin framing.

---

7. Agent Interaction Model

Agents do not independently control the user experience. Agents are activated and coordinated through Twin.

Interaction rule:

User
  ↓
Twin
  ↓
Agent Registry
  ↓
Agent selection
  ↓
Context assignment
  ↓
Capability assignment
  ↓
Governed execution
  ↓
Result returned to Twin

Agent invariants:

• Agents do not read canonical Spine directly.
• Agents do not write canonical state.
• Agents do not promote their own memory.
• Agents do not approve their own actions.
• Agents may not bypass Twin, Governance, or Triage.

Frontend implication: Agent surfaces must always show Twin as the supervisor. Execution histories and outcomes are surfaced under Twin review, not as standalone agent control panels.

---

8. Memory Mapping

Twin reads permission-filtered memory projections.

Memory Scope	Frontend Exposure	Twin Use	Backend Dependency
Personal Memory	Memory surface, Twin context	User preferences and private context	continuity
User Work Memory	Role and assignment context	Work context	continuity, knowledge
Work Memory	Account/project/task history	Operational context	spine, continuity
Organization Memory	Approved institutional knowledge	Reference context	knowledge, pipeline
Agent Working Memory	Active delegated execution state	Execution context	iw-agent-runtime, task-management
Agent Episodic Memory	Previous run outcomes	Outcome review	continuity, task-management
Candidate Memory	Unapproved material, triage queue	Review and promotion recommendation	continuity, govern

Promotion path:

Twin insight
  ↓
Memory candidate
  ↓
Triage
  ↓
Governance
  ↓
Approved memory

Frontend implication:

• Twin surfaces read memory projections.
• Triage surfaces review candidates.
• Promotion is always backend-governed.

---

9. Triage Mapping

Frontend Section	Triage Responsibility	Backend Dependency
Memory triage	Candidate review, contradiction review, promotion	continuity, govern, pipeline
Knowledge triage	Extraction feedback, document review, promotion	knowledge, pipeline
Outcome triage	Execution outcomes, learning candidates	hermes, pipeline, spine

Triage rule:

• Only triage and governance may promote material into canonical Spine.
• Twin may recommend promotion only.

Frontend implication: Triage surfaces must be review-only for Twin. Submission paths are governed and approval-gated.

---

10. Continuity Mapping

User-facing continuity language:

• Twin is continuing this work
• Twin is waiting for approval
• Twin will resume after dependency completes
• Twin retried the failed action
• Twin completed the delegated workflow
• Twin needs your decision

Internal continuity language:

• Workflow runtime
• Continuation service
• Scheduler
• Queue
• Durable checkpoint
• Orchestration engine

Frontend Section	Continuity Responsibility	Backend Dependency
Continuity surface	Workflow status, retry, resume, completion	workflow, task-management, continuity
Twin continuity	Twin-reported durable execution state	hermes, workflow
Agent continuity	Agent pause/resume, checkpoint, outcome return	iw-agent-runtime, task-management

Frontend implication: Continuity is presented as a Twin state, not as raw infrastructure. The frontend never exposes queue names, durable object identities, or internal scheduler state.

---

11. Capabilities Mapping

Twin is the primary capability consumer.

Frontend Section	Capability Responsibility	Backend Dependency
Capabilities surface	Discovery, execution, approval visibility	mcp-pool, integration-management-mcp
Twin capability use	Resolve, invoke, monitor, summarize	mcp-pool, govern, hermes
Agent capability assignment	Scoped capability assignment and execution	agent-registry, iw-agent-runtime, mcp-pool

Capability Registry exposes:

• Capability identity
• Purpose
• Inputs/outputs
• Required scopes
• Compatible agents
• Execution target
• Risk classification
• Approval requirements
• Audit requirements

Frontend implication: Capabilities are surfaced as governed actions. Discovery is permission-scoped. Execution requires approval flow where policy demands.

---

12. Spine Network Mapping

Frontend Section	Spine Network Responsibility	Backend Dependency
Workbench projections	Governed read models, Entity 360, timeline, search	spine, projection-engine, store
Twin context	Permission-filtered memory and knowledge projections	spine, continuity, knowledge
Governance and approval	Proposal and approval artifacts, evidence	govern, spine, workflow
Admin and configuration	Tenant config, schema config, connection config	tenants, pipeline, spine

Spine invariants:

• No browser component, Twin runtime, MCP tool, connector, or projection component writes Neon directly.
• Pipeline promotion is the sole canonical Spine writer.
• D1/KV are operational caches only; Neon/R2 are canonical.

Frontend implication: Every read path goes through Gateway and Projection Engine. Direct Spine schema access is forbidden from the browser surface.

---

13. MCP Pool and Integration Mapping

Public MCP is the 19-tool Spine contract only. Broader MCP Pool and capability registries remain internal.

Frontend Function	Public/Internal	Backend Service
Twin Ask	Public	mcp-connector
Twin Act	Public via Twin surface	mcp-connector, govern, hermes
Knowledge retrieval	Public	mcp-connector
Memory retrieval	Public	mcp-connector
Capability execution	Internal	mcp-pool, integration-management-mcp
Provider invocation	Internal	provider-management-mcp, connector, connector-sync

Frontend implication:

• The browser never chooses MCP transport.
• The browser never sees provider credential state.
• The browser never calls provider APIs directly after approval.

---

14. Activation and Connector Mapping

Frontend Section	Activation Responsibility	Backend Dependency
Onboarding activation	Intent, domain, identity, initial connection	gateway, tenants, pipeline, spine
Connector setup	OAuth, scopes, health, sync schedule	connector, integration-management-mcp, provider-management-mcp
Marketplaces	Discovery of available apps/connectors	integration-management-mcp, mcp-pool

Frontend implication:

• Onboarding collects intent and domain only.
• Connector setup results in governed connection state, not raw credentials.
• Integration management is exposed through approved capability surfaces.

---

15. Existing UI Component and Route Mapping

15.1 Routes and Shells

Frontend Path/Surface	Existing File	v0 Purpose
/	apps/web/src/app/page.tsx	Marketing home
/app	apps/web/src/app/app/[...segments]/page.tsx	Authenticated app shell
/app/admin	apps/web/src/app/admin/page.tsx	Admin surface
/app/administration	apps/web/src/app/administration/page.tsx	Administration workbench
/app/governance	apps/web/src/app/governance/page.tsx	Governance queue
/app/knowledge	apps/web/src/app/knowledge/page.tsx	Knowledge surface
/app/marketplace	apps/web/src/app/marketplace/page.tsx	Marketplace entry
/app/onboarding	apps/web/src/app/onboarding/page.tsx	Onboarding flow
/app/settings	apps/web/src/app/settings/page.tsx	Settings surface
/workbench/:department	apps/web/src/app/workbench/[department]/page.tsx	Role-aware workbench
/workspace/:department	apps/web/src/app/workspace/[department]/page.tsx	Workspace domain view
/domains	apps/web/src/app/domains/page.tsx	Domain routing shell
Auth entry/callback	apps/web/src/components/core/auth/*	Clerk/Descope auth entry and callback
Layout/shell	apps/web/src/AppShell.tsx	Authenticated layout, stage flow, providers
Route rendering	apps/web/src/app/_components/route-views.tsx	Dynamic route mounts
Workbench routing config	apps/web/src/app/_lib/workbench-routes.ts	Department/module routing manifest

15.2 Workbench UI Components

Existing Component/View	v0 Workbench Section	Mapping
packages/ui/src/views/home-view.tsx	Workbench Home	Twin primary surface + workspace projection
packages/ui/src/views/tasks-view.tsx	Tasks	Task runtime + continuity state
packages/ui/src/views/knowledge-view.tsx	Knowledge	Knowledge service + AI search
packages/ui/src/views/clients-view.tsx	Accounts	Entity 360 + spine projection
packages/ui/src/views/deals-view.tsx	Opportunities	Entity 360 + spine projection
packages/ui/src/views/projects-view.tsx	Projects	Entity 360 + task runtime
packages/ui/src/views/settings-view.tsx	Settings	Admin/tenant configuration
packages/ui/src/views/governance-view.tsx	Governance	Approval queue, policy evidence
packages/ui/src/views/integrations-view.tsx	Integrations	Integration Manager + MCP Pool
packages/ui/src/views/insights-view.tsx	Intelligence	Signal Engine + projections
packages/ui/src/views/brainstorming-view.tsx	Twin drafting	Memory + knowledge + triage candidates
packages/ui/src/views/iq-hub-view.tsx	Intelligence hub	AI search + reasoning + recommendations
packages/ui/src/views/sessions-view.tsx	Twin session/continuity	Continuity + memory + execution history

15.3 Twin and Cognitive Surfaces

Existing views that map to Twin roles:

• brainstorming-view.tsx → Twin draft/review
• iq-hub-view.tsx → Intelligence hub
• sessions-view.tsx → Twin session/continuity

Definitive v0 addition needed:

• A dedicated Twin sidebar/panel in AppShell.tsx that exposes Ask, Analyze, Explain, Recommend, Plan, Delegate, Act, Continue, Review, Remember.
• The sidebar receives current user, tenant, workspace, selected entity, task, document, conversation, active section, available capabilities, relevant memory, and pending approvals.

---

16. One-to-One Mapping: Frontend Function ↔ Backend Service

#	Frontend Function	Backend Service	API/Contract
1	Marketing pages	gateway, tenants	Public routes, onboarding discovery
2	Authentication	gateway, tenants	Clerk JWT validation, tenant resolution
3	Onboarding	gateway, tenants, pipeline	/api/v1/workspace/profile, activation routes
4	Domain routing	gateway, spine	Projection Engine responses
5	Workbench home	spine, projection-engine, store	SharedWorkbench contracts
6	Tasks	task-management, workflow, gateway	Task/projection APIs
7	Knowledge search	knowledge, mcp-connector	Public Spine MCP get_relevant_knowledge
8	Memory triage	continuity, govern, pipeline	Memory candidate → promotion contracts
9	Twin ask	intelligence, hermes, mcp-connector	ask_twin, context assembly
10	Twin delegate	iw-agent-runtime, hermes, task-management	Agent task creation and monitoring
11	Twin act	govern, hermes, mcp-pool	prepare_action, approve_action, execution
12	Governance approvals	govern, workflow, task-management	Approval/proposal APIs
13	Capabilities browse	mcp-pool, integration-management-mcp	Capability registry/resolver
14	Continuity status	workflow, task-management, continuity	Workflow/continuity APIs
15	Admin users/roles	admin, tenants, gateway	Admin API
16	Admin integrations	provider-management-mcp, integration-management-mcp	Connection/registry APIs
17	Webhook ingestion	webhook-ingress, gateway	Webhook routes, signature verification
18	Entity 360	spine, projection-engine, store	Entity projections, memory, tasks
19	Signal/telemetry	signals, telemetry	Signal streams, telemetry APIs
20	MCP discovery	mcp-connector	Public 19-tool Spine MCP

---

17. Cross-Mapping: Twin + Memory + Agents + Continuity + Capabilities

#	Frontend Event	Twin Action	Agent Action	Memory Action	Continuity Action	Capability Action	Backend Service Path
1	User asks question	Retrieve context, explain	None	Read permitted memory	None	None	mcp-connector → intelligence → continuity
2	Twin recommends action	Build proposal	None	None	None	Resolve capability	intelligence → mcp-pool
3	User approves proposal	Summarize decision	None	None	Schedule execution	Invoke capability	govern → hermes → workflow
4	Twin delegates to agent	Select agent, assign context	Execute task	Read working memory	Checkpoint/resume	Assign capability	iw-agent-runtime → task-management
5	Agent returns result	Summarize outcome	Return result	Write episodic memory	Update execution state	None	intelligence → continuity → spine
6	Triage review	Recommend promotion	None	Promote candidate	None	None	continuity → govern → pipeline
7	Continuity retry	Notify user	None	None	Retry/backoff	None	workflow → continuity → hermes
8	Cancel execution	Explain cancellation	Pause/stop	Archive working memory	Cancel workflow	Revoke capability token	task-management → workflow → govern
9	Memory contradiction	Explain conflict	None	Surface contradiction	None	None	continuity → knowledge → spine
10	Knowledge promotion	Recommend promotion	None	None	None	None	knowledge → pipeline → spine

---

18. Cross-Mapping: Frontend Section ↔ Backend Service ↔ UI Component

#	Frontend Section	UI Components/Routes	Backend Services
1	Home/Workbench	home-view.tsx, tasks-view.tsx, AppShell.tsx	spine, projection-engine, task-management, store, gateway
2	Knowledge	knowledge-view.tsx, /knowledge route	knowledge, pipeline, mcp-connector
3	Memory	brainstorming-view.tsx, memory triage UI	continuity, govern, pipeline
4	Governance	governance-view.tsx, /governance route	govern, workflow, task-management
5	Integrations	integrations-view.tsx	integration-management-mcp, provider-management-mcp, connector
6	Agents	Agent task panel, execution history, iq-hub-view.tsx	iw-agent-runtime, intelligence, task-management
7	Capabilities	Capability browser, action plan, approval flow	mcp-pool, govern, hermes
8	Continuity	Workflow status, retry/escalation panel, sessions-view.tsx	workflow, continuity, hermes
9	Admin	admin/page.tsx, /administration	admin, tenants, gateway
10	Marketing	Marketing shell, platform, pricing, solutions	gateway, tenants, mcp-connector
11	Twin panel	Twin sidebar in AppShell.tsx	intelligence, hermes, iw-agent-runtime, mcp-connector, knowledge, continuity
12	Entity 360	Entity detail views, Entity 360 panels	spine, projection-engine, store

---

19. Interaction Flow by Day

Day	User Journey	Frontend Section	Backend Services Involved
0	Discovers platform, signs up	Marketing / Auth	gateway, tenants
0	Onboards domain and connectors	Onboarding	gateway, tenants, pipeline, spine, connector
1	Enters workbench, sees projections	Workbench shell / Home	spine, projection-engine, store, gateway
1	Asks Twin for context	Twin sidebar	mcp-connector, intelligence, continuity, knowledge
2	Reviews memory and knowledge	Knowledge / Memory	knowledge, continuity, spine
2	Approves proposed actions	Governance	govern, workflow, task-management
3	Assigns delegated work to agent	Agents / Twin	iw-agent-runtime, agent-registry, task-management
3	Monitors continuity and outcomes	Continuity / Twin	workflow, continuity, hermes, signals
4	Reviews triage candidates	Memory / Governance	continuity, govern, pipeline
4	Uses discovered capabilities	Capabilities	mcp-pool, integration-management-mcp, govern
5	Configures integrations and admin	Admin / Integrations	admin, tenants, provider-management-mcp, integration-management-mcp

---

20. v0 Build Order

1. Twin sidebar/panel in AppShell.tsx
2. Twin Workbench core routes and projections
3. Memory triage surface
4. Governance approval queue surface
5. Agent task and execution surface
6. Continuity status surface
7. Capability discovery and execution surface
8. Knowledge surface alignment
9. Admin surface alignment
10. Marketing-to-onboarding handoff alignment

---

21. Stop-Ship Invariants for v0

• Frontend must not invoke provider APIs directly after approval; Hermes coordinates approved external execution.
• Frontend must not write canonical Spine state directly.
• D1/KV are operational caches only; they must not be described or used as canonical business truth.
• Public MCP remains the 19-tool Spine contract only; broader MCP Pool and capability registries remain internal.
• Twin is the canonical cognitive and interaction layer; continuity runtime is internal durable execution.
• Agents are delegated specialists only; they may not read canonical Spine, write canonical state, promote memory, or approve their own actions.
• Failed live projections must not silently become demo seed data.
• L1/L2/L4/L7 must not appear as user-facing product navigation.
• Legacy runtime aliases must not be introduced as new canonical frontend dependencies.