Developer Documentation

Authentication

DiviDen uses two auth mechanisms depending on the endpoint:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-instance.com/api/v2/contacts

REST API (v2)

The v2 API provides programmatic access to contacts, kanban, queue, documents, and chat. Full OpenAPI spec at /api/v2/docs.

Contacts

Kanban

Queue

Documents

Chat

API Keys

Capabilities API

Browse, install, customize, create, and manage capability skill packs. Capabilities extend Divi's abilities through prompt templates with editable fields. Integration-gated: some capabilities require a connected service (email, calendar, slack, etc.) before installation.

Browse & Install

Per-Capability Operations

Integration Gating

HTTP 422
{
  "error": "This capability requires an active Email integration...",
  "code": "INTEGRATION_REQUIRED",
  "requiredIntegration": "email"
}

Purchase Gating & Access Passwords

HTTP 402
{
  "error": "Payment required",
  "code": "PAYMENT_REQUIRED",
  "price": 4.99
}

POST /api/marketplace-capabilities
{ "capabilityId": "...", "accessPassword": "secret123" }

Creating Custom Capabilities

POST /api/marketplace-capabilities
Content-Type: application/json

{
  "action": "create",
  "name": "My Custom Capability",
  "description": "What this capability does",
  "icon": "",
  "category": "productivity",
  "integrationType": null,
  "pricingModel": "free",
  "prompt": "When the user asks about {{topic}}, respond with...",
  "editableFields": "[{\"name\":\"topic\",\"label\":\"Topic\",\"type\":\"text\",\"default\":\"general\"}]",
  "accessPassword": "secret123"
}

Custom capabilities auto-install for the creator. Only free and one_time pricing are supported — subscription pricing is rejected. The optional accessPassword lets you share a password that bypasses the paywall for paid capabilities.

Prompt Resolution

Prompts support {{fieldName}} template variables. When a user customizes a capability, the API resolves variables against their custom values and stores the resolvedPrompt. Divi injects resolved prompts from all active capabilities into the system context.

Federation v2 APIUPDATED May 30

The v2 federation endpoints handle instance registration, heartbeat, Bubble Store linking, agent sync, and payment validation. Public endpoints are CORS-enabled. Authenticated endpoints use the platformToken issued during registration.

Public Endpoints

Instance Registration & Lifecycle

Agent Sync

Global Browse & Local Sync (v2.5.80 — May 27, 2026)

Capability Sync

Payment Validation

MCP Server

DiviDen exposes a Model Context Protocol server at /api/mcp. Compatible with Claude Desktop, Cursor, and any MCP-compliant client.

Endpoint

POST /api/mcp
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Methods

Static Tools (22)

Dynamic Tools

Installed Bubble Store agents appear as marketplace_{slug} tools. Install an agent → it becomes an MCP tool automatically.

Server Card

Machine-readable server metadata at /.well-known/mcp/server-card.json

A2A Protocol

DiviDen implements the Agent-to-Agent protocol for direct agent communication.

Discovery

Task Execution

Artifact Types

A2A tasks support 7 structured artifact formats:

Webhooks

DiviDen can both receive and send webhooks.

Inbound (receive events)

Configure inbound webhooks at Settings → Webhooks. Each webhook gets a unique URL. The AI-powered field mapper auto-learns your payload structure.

Outbound (push events)

Configure push webhooks at Settings → Service Keys with service webhook_push. Events pushed: relay state changes, queue updates, mode switches.

Bubble Store APIUPDATED May 30

Register, discover, and execute AI agents. The marketplace API is scope-aware as of v2.5.80: self-hosted instances default to scope=local (local agents only), the managed platform defaults to scope=all (local + federated). Self-hosted instances can proxy to dividen.ai with scope=global.

Execution Endpoint — Full Contract

POST /api/marketplace/:id/execute is the primary endpoint for running tasks against Bubble Store agents. DiviDen acts as a broker: it calls the agent's endpointUrl directly, tracks the execution, and handles payment splitting.

Request

POST /api/marketplace/:id/execute
Auth: Session (logged-in user)
Rate Limit: 20/min per IP

{
  "input": "string (required — the task text)",
  "paymentMethodId": "string (optional — Stripe PM ID, falls back to default)"
}

Standard Response

{
  "executionId": "cuid",
  "status": "completed" | "failed" | "timeout",
  "output": "string (agent's response)",
  "responseTimeMs": 1234,
  "isOwnAgent": false,
  "revenue": {                     // only for paid executions
    "gross": 5.00,
    "developerPayout": 4.25,
    "platformFee": 0.75,
    "feePercent": 15
  }
}

Dynamic Pricing Response

If the agent's pricingModel is dynamic and it returns a price_quote in its response, the execution enters a two-phase flow:

{
  "executionId": "cuid",
  "status": "completed",
  "output": "string",
  "pricingPhase": "quoted",
  "quote": {
    "amount": 12.50,
    "currency": "USD",
    "breakdown": "2h research @ $6.25/hr",
    "approveUrl": "/api/marketplace/:id/execute/:executionId"
  },
  "widget": { "type": "payment_prompt", ... }
}

// User approves/declines via:
POST /api/marketplace/:id/execute/:executionId
{ "action": "approve" | "decline" }

How DiviDen Calls Your Agent

DiviDen sends a POST to the agent's endpointUrl with auth headers matching the agent's authMethod. The payload format depends on inputFormat:

// inputFormat: "text" (default)
{ "message": "task text" }

// inputFormat: "json"
{ "task": "task text", "executionId": "cuid" }

// inputFormat: "a2a" (Agent-to-Agent protocol)
{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "executionId",
    "message": { "role": "user", "parts": [{ "type": "text", "text": "task text" }] }
  }
}

// Headers always include:
X-DiviDen-Execution-Id: <executionId>
X-DiviDen-Source: marketplace

Federated Agent Approval

All agents and capabilities synced from federated instances enter pending_review status — no auto-approve, even for trusted instances. Admin reviews each submission in the DiviDen admin panel. When an agent is approved or rejected, a webhook fires to the source instance at /api/marketplace/webhook:

// Webhook payload
{
  "event": "agent_approval",
  "agentId": "remote-agent-id",
  "marketplaceId": "marketplace-cuid",
  "name": "Agent Name",
  "slug": "instance-agent-slug",
  "status": "active" | "rejected",
  "reason": "optional rejection reason",
  "timestamp": "2026-04-14T..."
}

Inbound Task Routing — Which Endpoint Receives What

Cross-Instance API

Cross-instance endpoints for federated DiviDen instances. All require x-federation-token or Authorization: Bearer header.

Full federation docs at /docs/federation.

Integration Kit

When listing an agent in the Bubble Store, you can provide an Integration Kit — structured metadata that teaches Divi how to work with your agent.

Kit Fields

Install Lifecycle

When a user installs your agent, the Integration Kit is decomposed into up to 8 memory entries in Divi's persistent memory. Divi then proactively suggests your agent when tasks match its capabilities. Uninstalling removes all memory entries — clean separation.

Queue Gating & Confirmation Gate

When Divi dispatches a task to the queue, two layers of protection activate: capability gating (does a handler exist?) and user confirmation (does the user approve?).

Layer 1: Capability Gate

Before any queue item is created, the system checks if the user has a handler for the task type:

Layer 2: Confirmation Gate

If a handler exists, the item is created with status pending_confirmation — it does NOT enter the active queue automatically. The user sees it in the Queue panel with Approve / Reject buttons.

Queue Item Status Lifecycle

pending_confirmation → ready → in_progress → done_today
                                    ↘ blocked (if stuck)
                                    ↘ later (deferred)

Status guards:
  - pending_confirmation cannot skip to in_progress or done_today
  - done_today cannot revert to ready or in_progress

Comms synchronization (v2.5.101):
  - Every transition to in_progress creates a CommsMessage
    (metadata.type = agent_execution_started)
  - Every transition to done_today creates a CommsMessage
    (metadata.type = task_completed, sender = 'divi')
  - ALL tasks generate comms -- no handler.name gate
  - handlerName/handlerMeta destructured from metadata;
    non-handler tasks get { type: 'manual' } fallback
  - Both metadata types match the agent_activity filter
    so they appear in the Comms tab

Inline comms detail (v2.5.102):
  - CommsTab renders a split-pane layout on lg+ screens
    (300px thread list left, detail view right)
  - Thread selection is local state -- no route navigation
  - AgentDetailView and RelayDetailView in
    CommsDetailView.tsx handle thread-type rendering
  - /dashboard/comms page kept for backward compatibility

Bypassing the Confirmation Gate

Open-source self-hosted users who want tasks to enter the queue without manual approval can set queueAutoApprove: true:

// Via v2 API
PATCH /api/v2/settings
Authorization: Bearer dvd_your_key
{ "queueAutoApprove": true }

// Via session API
PUT /api/settings
{ "queueAutoApprove": true }

API: Confirm / Reject

Action Tags — Queue Creation

Action Tags — Chat-Based Queue Control

Users can manage queue items directly from chat. Divi uses these tags when the user confirms, rejects, or edits items conversationally:

The edit_queue_item tag is the most powerful — when a user provides detailed context, files, or instructions in chat, Divi includes all of it in the edit. The Smart Task Prompter then generates both a compact displaySummary (≤120 chars for the queue card) and a full optimizedPayload structured to match the target agent's input schema.

Smart Task Prompter v2

When a queue item is edited (via chat or inline UI), the Smart Task Prompter optimizes the task for its target execution agent:

CoS relay dispatch sends optimizedPayload when available, falling back to the raw description. Queue cards show a badge when the optimized payload exists.

// Smart Prompter output stored in metadata:
{
  "displaySummary": "Draft Q4 board deck with revenue projections",
  "optimizedPayload": {
    "task": "Create board presentation",
    "context": "Q4 2026 board meeting, Series A metrics...",
    "deliverables": ["slide-deck"],
    "constraints": ["under 15 slides", "include ARR chart"]
  },
  "_original": { "title": "...", "description": "..." },
  "_optimizedAt": "2026-04-14T...",
  "_optimizedForAgent": "research-agent"
}

Schema Change

// User model — new field
queueAutoApprove  Boolean  @default(false)

// QueueItem.status now includes:
// "pending_confirmation" | "ready" | "in_progress" | "done_today" | "blocked" | "later"

Queue-Kanban BridgeUPDATED May 30

The Queue-Kanban Bridge connects the task queue lifecycle to kanban cards. Every queue status transition is reflected as a checklist mutation on a linked kanban card, creating a persistent audit trail and a review loop that prevents completed work from disappearing into the void.

Lifecycle

1. Task Arrives  -> link to card (or create) + add "Queued" checklist item
2. Task Dispatched -> update checklist: "In progress"
3. Task Completes  -> mark checklist done + add "Review" item (unchecked)
4. Task Fails      -> update checklist: "Failed" + add "Retry" item

Card linking priority:
  1. Explicit cardId on queue item
  2. cardId in queue item metadata
  3. Project-match (most recently updated card in same project)
  4. Auto-create new card in "active" column

Schema

// QueueItem now has a cardId field
model QueueItem {
  cardId   String?   // FK to KanbanCard
  // ... other fields
}

// ChecklistItem.sourceType values used by the bridge:
//   'queue'        - the task tracking item
//   'queue_review' - the review/retry item added on completion/failure

// ChecklistItem.sourceLabel values:
//   'task_queued'     - initial state
//   'task_in_progress'
//   'task_completed'
//   'task_failed'
//   'pending_review'  - review item (unchecked until operator acts)
//   'pending_retry'   - retry item on failure

Review Badge

Kanban cards with unchecked queue_review checklist items show an amber "pending review" badge (eye icon + count) on both the card and the column header. The operator can see at a glance which cards have unreviewed results.

Files

• src/lib/queue-kanban-bridge.ts -- Core bridge logic (arrival, dispatch, completion, failure, count utilities)
• src/app/api/queue/[id]/route.ts -- Hooks for dispatch, completion, failure
• src/lib/queue-dispatch.ts -- Hook for auto-dispatch
• src/lib/tags/handlers-queue.ts -- Hook for task arrival (dispatch_queue tag)
• src/app/api/queue/confirm/route.ts -- Hook for confirmed tasks
• src/components/dashboard/KanbanView.tsx -- Review badge UI

Smart Task Assembly (v2.5.81)UPDATED May 28

The Smart Task Assembly system replaces the generic task creation form with an agent-aware task picker. Users select a task type from their installed agents and capabilities, then Divi guides them through collecting all required inputs before submission. Tasks can also be sent to connections via relay.

Architecture

API: Available Tasks

Response shape:

{
  "tasks": [
    {
      "agentId": "clx...",
      "agentName": "Research Agent",
      "agentSlug": "research-agent",
      "description": "Deep research and analysis",
      "category": "research",
      "taskTypes": ["market_analysis", "competitor_report"],
      "samplePrompts": ["Analyze the SaaS market..."],
      "requiredInputSchema": "{ ... JSON schema ... }",
      "contextInstructions": "Include company name and timeframe",
      "executionNotes": "Typically takes 2-5 minutes",
      "inputFormat": "text"
    },
    {
      "agentId": "builtin_clx...",
      "agentName": "Email",
      "category": "builtin",
      "taskTypes": ["email"],
      ...
    }
  ]
}

UI Entry Points

Relay Flow

When “For Someone Else” is selected, the chat prefill instructs Divi to:

Component: SmartTaskPicker

// src/components/dashboard/SmartTaskPicker.tsx
// Props:
interface SmartTaskAssemblyProps {
  open: boolean;                                  // Overlay visibility
  onClose: () => void;                            // Close handler
  onStartGuidedChat: (message: string) => void;   // Sends prefill to ChatView
}

// Step flow: pick-task → pick-mode → pick-connection (relay only)

Chief of Staff Execution Engine

Chief of Staff (CoS) mode transforms Divi from reactive (waiting for you in chat) to proactive (executing queue tasks sequentially). When activated, Divi picks the highest-priority ready item, moves it to in_progress, executes it, and when done, auto-dispatches the next item.

Execution Strategies

Sequential Dispatch Contract

// One task in flight at a time
// Priority: urgent > high > medium > low, then oldest first

1. User activates CoS → onEnterCoSMode(userId)
   → Dispatches top READY item to in_progress
   → Executes it (capability / relay / generic)

2. Task completes → onTaskComplete(userId, itemId)
   → Auto-dispatches next READY item
   → Executes it
   → Repeat until queue empty

3. User switches back to Cockpit
   → Returns briefing: { completedToday, stillReady, blocked }

Activating via API

// Switch to CoS mode (auto-dispatches if queue has ready items)
PATCH /api/v2/settings
Authorization: Bearer dvd_your_key
{ "mode": "chief_of_staff" }

// Response includes auto-dispatched item:
{
  "success": true,
  "data": {
    "mode": "chief_of_staff",
    "autoDispatched": { "id": "clx...", "title": "Review proposal", "status": "in_progress" }
  }
}

// Switch back to Cockpit (returns briefing)
PATCH /api/v2/settings
{ "mode": "cockpit" }
// → { "briefing": { "completedToday": 3, "stillReady": 1, "blocked": 0 } }

Execution Metadata

After CoS executes a task, the queue item's metadata is enriched with:

{
  "cosExecution": {
    "method": "capability" | "relay" | "generic",
    "detail": "email:compose" | "Delegated to Sarah" | "Divi is executing",
    "startedAt": "2026-04-14T00:15:00.000Z"
  }
}

Settings API (v2)

Programmatic access to user settings — mode switching, queue behavior, and onboarding status. Useful for open-source integrations, automation scripts, and custom dashboards.

Available Fields

Open-Source Quick Start

If you're self-hosting and want to skip the onboarding UI entirely:

# 1. Create account via /api/setup
curl -X POST /api/setup \
  -d '{"email":"you@domain.com","password":"...","name":"You","acceptedTerms":true}'

# 2. Generate API key via /api/v2/keys
curl -X POST /api/v2/keys \
  -H "Authorization: Bearer <session>" \
  -d '{"label":"my-integration","scopes":["queue","chat"]}'

# 3. Configure for automation
curl -X PATCH /api/v2/settings \
  -H "Authorization: Bearer dvd_your_key" \
  -d '{"queueAutoApprove": true}'

# 4. Activate CoS mode
curl -X PATCH /api/v2/settings \
  -H "Authorization: Bearer dvd_your_key" \
  -d '{"mode": "chief_of_staff"}'

Teams & Project Delegation

Teams are persistent groups that span projects. Assign a team to a project to auto-sync all members as contributors. CoS mode delegates qualifying tasks to project contributors via relay.

Schema

Team now has originInstanceUrl (nullable — null means dividen.ai platform) and isSelfHosted (boolean, default false). Self-hosted teams bypass all subscription and billing gates.

TeamInvite is a new model with token-based deep links, role assignment, optional message, 7-day expiry, and support for email, userId, or connectionId targets.

API Endpoints

CoS Project Delegation

When CoS dispatches a generic task (no explicit capability or relay handler), it checks if the task belongs to a project with lead or contributor members. If a qualifying member has an active connection, CoS creates anAgentRelay (type: request, intent: assign_task) with the project context.

Strategy priority: capability → explicit relay → project contributor → generic. Teams add members as a bundled unit — delegation operates at the ProjectMember level regardless of how the member was added.

Billing Boundary

Open-Source Implementation Guide

If you're running your own instance and want to enable teams:

1. Pull the latest schema. Team has new fields: originInstanceUrl, isSelfHosted. TeamInvite is a new model. Run npx prisma db push.
2. Set your instance URL. Add DIVIDEN_INSTANCE_URL to your .env. Pass it as originInstanceUrl when creating teams. The API sets isSelfHosted = !!originInstanceUrl.
3. Feature gates auto-bypass. feature-gates.ts returns a synthetic unlimited subscription for any team where isSelfHosted: true. No code changes required.
4. Team invites work locally. Same token-based flow — generate at /api/teams/:id/invites, share the link, accept at /team/invite/:token.
5. Cross-instance invites require a federation connection between instances first. The invite links to a connectionId and membership flows through the relay system.
6. CoS delegation works automatically once members are synced to projects. No additional configuration.
7. Profiles work the same way. User profiles at /profile/:userId and team profiles at /team/:id are public by default. Set visibility to private or network to restrict access.

See the open-source guide for general self-hosting setup, and the federation docs for cross-instance connectivity.

Project Management API

Projects are scoped workspaces with contributors (local users or federated connections). Contributors can be leads, contributors, reviewers, or observers. New in v2.1.3: Divi can create projects and invite contributors directly from chat using action tags. New in v2.3.1: Every project invite is now a first-class Divi→Divi communication event — it emits an AgentRelay (intent='introduce') and a CommsMessage alongside the ProjectInvite + QueueItem, so the invite surfaces in the invitee's queue, bell count, Comms thread, and on the card as a ghost avatar. Duplicate invites return 409 ALREADY_INVITED; pass { force: true } to deliberately reinvite. See the Project Invites Integration Guide.

REST Endpoints

Action Tags (Chat-Based)

Federation: Cross-Instance Project Invites

When a project invite targets a federated connection, DiviDen automatically pushes a notification to the remote instance via POST /api/federation/notifications with type project_invite.

// Federation notification payload for project invite
{
  "type": "project_invite",
  "fromUserName": "Jon Bradford",
  "fromUserEmail": "jon@colab.la",
  "toUserEmail": "alvaro@fractionalventure.partners",
  "title": "Project invite: Debugging DiviDen",
  "body": "You've been invited to join \"Debugging DiviDen\" as contributor.",
  "metadata": {
    "projectId": "proj_abc",
    "inviteId": "inv_xyz",
    "role": "contributor"
  },
  "timestamp": "2026-04-17T19:00:00.000Z"
}

See the FVP Cross-Operability Guide for the full event taxonomy and implementation details.

Behavior Signals API

The behavior signal system collects lightweight, fire-and-forget events from user interactions. These signals feed the pattern analysis engine that generates learnings.

Endpoint

Client Helper

Use emitSignal(action, context) from src/lib/behavior-signals.ts. It automatically attaches the current hour and day-of-week, and swallows errors so it never breaks the UI.

import { emitSignal } from '@/lib/behavior-signals';

// In any event handler:
emitSignal('queue_done_today', { itemId: item.id, status: 'done_today' });
emitSignal('chat_send', { contentLength: message.length });
emitSignal('email_opened', { threadId: thread.id });

Currently Instrumented Actions

Adding New Signal Types

Call emitSignal from any component's event handler. No schema changes needed — theaction field is a free-form string and context is a JSON object. The analysis endpoint (POST /api/learnings/analyze) groups signals by action type for pattern detection.

Prisma Model

model BehaviorSignal {
  id        String   @id @default(cuid())
  userId    String
  action    String   // e.g. "queue_done_today"
  context   Json?    // e.g. { itemId, status }
  hour      Int?     // 0-23
  dayOfWeek Int?     // 0=Sun, 6=Sat
  createdAt DateTime @default(now())
  user      User     @relation(...)
}

Learnings API

Learnings are patterns detected from behavior signals. Every learning is user-controlled — editable, dismissable, deletable.

Endpoints

Learning Categories

Notification Deep-Linking

When the analysis endpoint creates new learnings, it logs an ActivityLog with action learning_generated. The notification feed maps this to the intelligence category. Clicking the notification navigates to /settings?tab=learnings.

Implementation: NotificationCenter.tsx checks notification action and usesrouter.push('/settings?tab=learnings') for learning/intelligence notifications.

Admin: Workflow Discovery

Smart Tagging Implementation

Smart tags are auto-generated labels on kanban cards that surface who's involved (local + federated) and due date urgency.

Tag Extraction — getSmartTags(card)

Located in src/components/dashboard/KanbanView.tsx. Returns an array of{label, color, icon} objects:

function getSmartTags(card: KanbanCardData) {
  const tags: { label: string; color: string; icon: string }[] = [];

  // 1. Project member tags
  card.project?.members?.forEach(m => {
    if (m.user) {
      tags.push({ label: m.user.name, color: 'blue', icon: '' });
    } else if (m.connection) {
      tags.push({ label: m.connection.name, color: 'purple', icon: '' });
    }
  });

  // 2. Due date urgency
  if (card.dueDate) {
    const due = new Date(card.dueDate);
    const now = new Date();
    if (due < now) tags.push({ label: 'Overdue', color: 'red', icon: '' });
    else if (due.toDateString() === now.toDateString())
      tags.push({ label: 'Due Today', color: 'orange', icon: '⏰' });
  }

  return tags;
}

Extending Tags

Add new tag types by pushing to the tags array:

• Labels — Read card.metadata?.labels or add a labels field to the KanbanCard model
• Priority — Map card.priority to color-coded tags
• External IDs — Parse Jira/GitHub references from card title or metadata
• Custom status — Derive from card.column or card.status

Colors are mapped to Tailwind classes in the card renderer: blue → bg-blue-500/20 text-blue-300, purple → bg-purple-500/20 text-purple-300, etc.

Board Drag Detection

The kanban board distinguishes card drags from board scrolls using data-kanban-card="true" attributes:

// In board pointer handlers:
const isOnCard = (e.target as HTMLElement).closest('[data-kanban-card]');
if (isOnCard) return; // Let dnd-kit handle card drag
// Otherwise, initiate board scroll via boardRef.current.scrollLeft

DragScrollContainer

A reusable component for enabling horizontal drag-to-scroll on any overflow content. Located at src/components/ui/DragScrollContainer.tsx.

Usage

import { DragScrollContainer } from '@/components/ui/DragScrollContainer';

<DragScrollContainer className="gap-2" showFadeEdges>
  {tabs.map(tab => (
    <button key={tab.id} className="flex-shrink-0 px-3 py-1.5">
      {tab.label}
    </button>
  ))}
</DragScrollContainer>

Props

How It Works

• Uses ResizeObserver to detect when content overflows horizontally
• Pointer events track drag state — when dragging, scrollLeft updates with delta
• Click events are captured and suppressed during drag to prevent accidental tab/button activation
• Fade edges render as absolute-positioned gradient overlays when showFadeEdges is true

Currently Applied To

Board Cortex Intelligence

The Board Cortex is a background intelligence layer that analyzes the kanban board for redundancies, stale items, and escalation candidates. It produces a pre-digested context digest that Divi receives in every conversation — replacing raw data analysis with actionable insights.

Architecture

Located in src/lib/board-cortex.ts. Pure functions that take cards as input and produce structured analysis. No LLM calls — all deterministic, Levenshtein-based similarity matching.

Core Functions

API Endpoints

BoardInsight Model

model BoardInsight {
  id         String   // cuid
  type       String   // "merge_suggestion" | "stale_card" | "auto_escalate" | "duplicate_tasks" | "archive_candidate"
  status     String   // "active" | "dismissed" | "applied"
  confidence Float    // 0.0 - 1.0
  reason     String   // Human-readable explanation
  sourceId   String   // Primary card/item ID
  targetId   String?  // For merge suggestions — the target card
  userId     String
}

System Prompt Integration

The digest is injected into Divi's Group 2 (Active State) as a "Board Intelligence" section. It supplements the raw card listing — Divi gets both detail and analysis. When the board is clean, only the health status line appears. When issues are detected, full context plus suggested action tags are included.

Extending the Cortex

• Add new detection functions following the same pattern: take CortexCard[], return typed results
• Wire them into buildContextDigest() and runBoardScan()
• Reuse similarity() from queue-dedup.ts for any text matching
• For LLM-powered analysis (semantic dedup, priority suggestions), add to runBoardScan() — keep buildContextDigest() fast and deterministic

System Prompt Architecture (Modular Capabilities)

Divi's system prompt is dynamically assembled per-message from modular groups. A relevance engine scores each group against the current conversation context and only loads what's needed.

Capability Modules

The old monolithic buildCapabilitiesAndSyntax() (7,219 tokens, always loaded) has been split into 5 purpose-built functions:

Relevance Engine

selectRelevantGroups(currentMessage, recentContext) manages 17 prompt groups. Each group has regex signal patterns in SIGNAL_PATTERNS. The engine:

1. Scores each group against current message + last 3 messages
2. Groups with empty patterns (like capabilities_core) always score 1.0
3. Groups above the relevance threshold are included
4. setup is always force-added (lightweight status line)

All 17 Prompt Groups

Setup Layer

buildSetupLayer_conditional() has two paths: complete (returns a ~200-token status line + nav reference) and incomplete (returns widget→task mappings so Divi can guide setup). Widget syntax and Linked Kards docs are now in capabilities_core, not setup. Legacy onboarding phases 0-5 have been removed entirely — project-based onboarding is the only path.

File

src/lib/system-prompt.ts — single file, ~1,200 lines. The admin route at /api/admin/system-prompt renders the full prompt for inspection.

Project-Based Onboarding (v2)

Onboarding in DiviDen is not a wizard — it's a project. The old 6-phase system is replaced by a real kanban project with checklist tasks that show up in the Now Panel and can be discussed with Divi.

Flow

1. Welcome modal — Two-step: intro screen → API key entry (Anthropic/OpenAI selector). Component: OnboardingWelcome.tsx
2. POST /api/onboarding/intro — Creates project + 1 kanban card ("DiviDen Setup") + 6 checklist items + chat messages, all in a $transaction with parallelized reads
3. Choice — "Walk me through it" (due today) or "I'll handle it myself" (due in 1 week)
4. POST /api/onboarding/setup-project — Updates due dates on checklist items, returns firstTaskText for auto-discussion
5. Auto-discuss — First task discussion auto-sent to chat via __AUTOSEND__ prefix

Setup Checklist Items

All items have assigneeType='self' and appear naturally in the Now Panel via the NOW engine. Setup tasks are visible to Divi through the normal kanban context (Group 2) — no special onboarding block needed.

API Key Gate

The dashboard checks apiKeys.some(k => k.isActive). No active key → showsOnboardingWelcome at step 2, regardless of onboarding phase. Accepts initialStep prop.

Legacy Compatibility

The onboardingPhase DB field still exists but is no longer read by the system prompt. Legacy onboarding phases 0-5 have been removed from system-prompt.ts entirely. New users get phase set to 6 immediately after /api/onboarding/intro. The /api/onboarding/advance endpoint still works for settings-save flows but is not used for phase progression.

Cockpit Mode & Work Partner Behavior

In cockpit mode, Divi behaves as a work partner — proactively working through the operator's task list instead of passively waiting for instructions.

Behavior Loop

1. System prompt includes operator's incomplete checklist tasks (ranked by NOW engine)
2. Divi picks the highest-priority item and opens discussion
3. Helps the operator execute — may fire capabilities directly (email, calendar) for low-risk actions
4. Marks the task complete via [[complete_checklist:{"id":"..."}]]
5. Suggests follow-on tasks or creates them via [[create_checklist:{...}]]
6. Moves to the next priority

System Prompt Integration

The batch fetch in buildSystemPrompt() now queries checklistItems withassigneeType='self' and completed: false. These are injected as myChecklistTasks in the Active State (Group 2), giving Divi visibility into the operator's to-do list with due dates and parent card context.

Three Assignment Types

Activity Logging

Actions executed from chat are logged to the activity feed via logActivity() or direct prisma.activityLog.create(). Card-related actions now include a cardId column for card-scoped activity feeds (see Card Activity Feeds):

• send_email → logs capability_executed
• create_calendar_event → logs capability_executed
• complete_checklist → logs task_completed with card title + cardId
• card_created / card_updated / card_deleted / card_moved → logged with cardId
• task_routed / task_decomposed → logged with cardId when card context exists
• card_auto_completed → logged with cardId when all checklist items complete

Auto-Discuss & Auto-Complete Patterns

DiviDen uses several automation patterns to reduce friction. These patterns are reusable beyond onboarding.

__AUTOSEND__ Prefix

When chatPrefill starts with the string __AUTOSEND__,ChatView automatically sends the message instead of just filling the input field. Used for initiating contextual conversations programmatically.

// In dashboard/page.tsx
setChatPrefill('__AUTOSEND__Let\'s discuss: ' + firstTaskText);

// In ChatView.tsx — uses pendingAutoSend ref pattern
const pendingAutoSend = useRef<string | null>(null);

useEffect(() => {
  if (chatPrefill?.startsWith('__AUTOSEND__')) {
    pendingAutoSend.current = chatPrefill.replace('__AUTOSEND__', '');
  }
}, [chatPrefill]);

// After messages load, check and fire
useEffect(() => {
  if (pendingAutoSend.current && messages.length > 0) {
    sendMessage(pendingAutoSend.current);
    pendingAutoSend.current = null;
  }
}, [messages]);

Auto-Complete on Settings Save

The /api/onboarding/advance endpoint matches saved settings to setup checklist items and marks them complete automatically. For example, saving "Working Style" settings auto-completes the "Configure Working Style" checklist item. Pattern: keyword match against checklist text field on the user's setup card.

Auto-Install Capabilities on Google Connect

The Google OAuth callback (/api/auth/callback/google-connect) silently upsertsAgentCapability records for 'email' (Outbound Email) and 'meetings' (Meeting Scheduling) with default rules. Also auto-completes the "Connect Email & Calendar" setup task if it exists.

Interactive Settings Widgets

The show_settings_widget action tag renders interactive settings controls directly in chat messages. Available groups:

Widget definitions live in src/lib/onboarding-phases.ts → getSettingsWidgets(). Rendered by AgentWidget.tsx when isSettingsWidget metadata is present on a message.

NOW Engine: Priority Scoring & Calendar Correlation

The NOW engine (src/lib/now-engine.ts) produces the operator's priority stack using deterministic scoring — no LLM. Sources: active kanban cards (assignee='human'), checklist items (assigneeType='self'), calendar events, goals with deadlines, and relay responses. Queue items are excluded — they belong to Divi. Calendar events within 60 minutes boost related items by +25 score.

Correlation Algorithm

1. Scans calendar events starting within the next 60 minutes
2. Tokenizes each event title into keywords (only words with 3+ characters)
3. For each queue item, checks if its title contains any event keyword (case-insensitive substring match)
4. Matching items receive a +25 score boost
5. Subtitle is updated to: "Related to upcoming: [Event Title]"

Implementation Location

The correlation block runs inside computeNow() after the calendar prep items section. It iterates the scored array of NowItems and modifies scores in-place before final sorting.

Extending Correlation

To add new correlation sources:

• Add data fetching alongside the existing calendar fetch in computeNow()
• Create a new correlation block following the same pattern: extract keywords → match against queue items → boost score
• Adjust boost values relative to the existing +25 for calendar (e.g., email mentions might warrant +15)

Realtime Event SystemUPDATED Apr 15

Dashboard panels refresh instantly via lightweight custom DOM events on window. No WebSockets or SSE — just window.dispatchEvent(new Event(name)) from ChatView.tsx when actions complete.

Event Catalog

Adding a New Event

1. Define a name: dividen:your-panel-refresh
2. Dispatch from ChatView.tsx at the relevant action point: window.dispatchEvent(new Event('dividen:your-panel-refresh'))
3. Listen in your panel's useEffect: add/remove listener, trigger re-fetch on event

The NOW panel also polls every 60 seconds as a backstop. Other panels rely on events only.

Catch-Up BriefingUPDATED Apr 15

The catch-up briefing is Divi's phased status report. It runs when the user triggers the catch_up action tag (e.g., from onboarding or manually). The prompt is defined in getCatchUpPrompt() in src/lib/signals.ts.

Architecture

catch_up is not a server-side action tag in ALLOWED_TAGS — it's handled entirely client-side in ChatView.tsx:

1. Show "Syncing your data..." assistant message
2. Fire sync_signal via POST /api/chat/execute-tag in background (pulls fresh Google data)
3. Wait 1.5s for data freshness
4. Send the full catch-up prompt to the LLM via sendMessage()

The LLM has all required data in its system prompt context: board state (Group 2), queue items (Group 2), unread emails (Group 6), calendar events. The catch-up prompt instructs a four-phase briefing:

• Phase 1: Board & Queue Progress
• Phase 2: Inbox Triage
• Phase 3: Calendar & Signals
• Phase 4: Recommended Focus

Quality Tuning

To improve catch-up quality, edit getCatchUpPrompt() in src/lib/signals.ts. The prompt is the single source of truth — the LLM's briefing quality is entirely a function of how well the prompt shapes the system-prompt data into a narrative.

Activity Feed APIUPDATED Apr 15

The global activity stream at GET /api/activity supports filtering by category. The UI renders a dropdown checkbox filter with 10 categories.

Categories

Logging Activity

Use logActivity() from src/lib/activity.ts (or direct prisma.activityLog.create()). Include action (must match a category mapping above), userId, and optional metadata JSON. For card-related actions, include cardId for card-scoped feeds.

Cortex Daemon (Scheduled Scan)

The Board Cortex Daemon is a background scheduled task that runs every 6 hours, scanning all active users' boards for insights.

Endpoint

POST /api/cron/cortex-scan

# Headers
Authorization: Bearer <ADMIN_PASSWORD>
# OR
x-cron-secret: <ADMIN_PASSWORD>

# Optional query params
?userId=<id>  # Scan a single user (for testing)

# Response
{
  "success": true,
  "scanned": 5,
  "results": [
    {
      "userId": "...",
      "userName": "Jon",
      "cardCount": 12,
      "insightsFound": 3,
      "details": { "stale": 1, "duplicate": 0, "escalated": 2, ... }
    }
  ]
}

What It Does Per User

• Runs runBoardScan() — all 6 detection functions (stale, duplicate, deadline, archivable, escalation, correlation)
• Auto-escalates deadline-approaching cards
• Persists BoardInsight records
• Logs activity entries for notable findings

Each DiviDen instance runs its own daemon — no centralized dependency. The daemon is scheduled via background task infrastructure and authenticates with the admin password.

Linked Kards v2 (Cross-User Visibility)

When a relay creates work on another user's board, both cards link together automatically. Both users' Divis see the linked card's status/progress, and status changes propagate back to the originator via update relays.

v2 Architecture

• Auto-linking: Cards created after inbound relays with assign_task intent are automatically linked — no LLM action required
• Delegation provenance: Cards stamped with originCardId, originUserId, sourceRelayId
• Status propagation: When a linked card changes status, cached status updates on CardLink + update relay sent to originator
• Relay→Card FK: AgentRelay.cardId directly references the source card (no JSON parsing needed)

Schema

model KanbanCard {
  ...
  originCardId    String?    // Card on SENDER's board
  originUserId    String?    // User who delegated to us
  sourceRelayId   String?    // Relay that delivered work
}

model CardLink {
  ...
  linkedStatus      String?    // Cached status (synced on change)
  linkedPriority    String?    // Cached priority
  lastSyncedAt      DateTime?  // Last sync timestamp
  externalCardId    String?    // Cross-instance (FVP)
  externalInstanceUrl String?  // Remote instance URL
}

model AgentRelay {
  ...
  cardId            String?    // Direct FK to source card
}

Action Tags

# Card creation auto-links from recent relay context (v2 default)
[[create_card:{"title":"Research Report"}]]

# Manual override with explicit source (still works)
[[create_card:{"title":"...","linkedFromCardId":"<source_card_id>"}]]

# Explicitly link two existing cards
[[link_cards:{"fromCardId":"...","toCardId":"...","linkType":"collaboration"}]]

Status Accumulation Flow (Accumulate, Don't Ping)

1. Sarah moves card to "completed"
2. propagateCardStatusChange() fires SILENTLY:
   a. Updates CardLink.linkedStatus cache
   b. Appends {"field":"status","from":"active","to":"completed"} to changeLog
   c. NO relay sent — no pinging Jon's Divi
3. Jon starts a conversation → system prompt builds
   a. getUnseenLinkedCardChanges() reads accumulated changeLog
   b. Injects "Linked Card Updates" section into Group 2
   c. markLinkedCardChangesSeen() clears the log (fire-and-forget)
4. Jon's Divi surfaces updates naturally in conversation

Updates accumulate silently in CardLink.changeLog (JSON array, capped at 20 entries). They're delivered as a digest when the user starts a conversation — not as constant relay pings. The log is cleared after delivery via markLinkedCardChangesSeen().

System Prompt Context

[cardId] "My Card" (high) ⬅delegated-from:Jon →delegation:"Their Task" (active) by Sarah ✓2/5

Card Activity Feeds (Card-Scoped + Cross-User)

Every kanban card has its own activity timeline. Card-related actions write cardId as a first-class column on ActivityLog. When a card has linked cards (via Linked Kards), activity automatically mirrors to linked cards owned by other users.

Schema

model ActivityLog {
  ...
  cardId       String?    // FK to KanbanCard — card-scoped feed
  isCrossUser  Boolean    @default(false) // true for mirrored cross-user entries
  card         KanbanCard? @relation(...)
  @@index([cardId, createdAt]) // composite index for fast card queries
}

Cross-User Mirroring

1. logActivity() called with cardId (e.g. task_completed on Sarah's card)
2. mirrorActivityToLinkedCards() fires (fire-and-forget):
   a. Finds all CardLink records for cardId
   b. For each linked card owned by a DIFFERENT user:
      - Creates mirror ActivityLog with isCrossUser: true
      - Prefixes summary with ""
      - Sets actor to the acting user's name
3. Jon opens his linked card → Activity section shows:
   "Sarah: Completed task 'Research Report'"  (isCrossUser: true)
   alongside his own card activity

API Endpoint

{
  "success": true,
  "data": [
    {
      "id": "...",
      "action": "task_completed",
      "actor": "divi",
      "summary": "Completed task: \"Research Report\"",
      "isCrossUser": false,
      "createdAt": "2026-04-14T..."
    },
    {
      "id": "...",
      "action": "task_completed",
      "actor": "Sarah",
      "summary": "Sarah: Completed task \"Data Analysis\"",
      "isCrossUser": true,
      "createdAt": "2026-04-14T..."
    }
  ],
  "nextCursor": "..." // null when no more entries
}

Wired Call Sites

• POST /api/kanban → card_created with cardId
• PATCH /api/kanban/[id] → card_updated with cardId
• DELETE /api/kanban/[id] → card_deleted with cardId
• POST /api/kanban/[id]/move → card_moved with cardId
• action-tags.ts → task_completed, task_routed, task_decomposed with cardId
• card-auto-complete.ts → card_auto_completed with cardId

UI (CardDetailModal)

Collapsible Activity section in the card detail modal. Lazy-loads on expand. Own entries show /icons on neutral backgrounds. Cross-user entries (isCrossUser: true) show on a brand-tinted background. Relative timestamps. The global activity feed (/api/activity and SSE stream) remains user-scoped — no cross-user bleed.

Google Connect Widget

Interactive Google Connect button that can be rendered in chat anytime — not just during onboarding.

Action Tag

# Connect user's own Gmail/Calendar
[[show_google_connect:{"identity":"operator"}]]

# Connect Divi's separate account
[[show_google_connect:{"identity":"agent","label":"Connect Divi's Gmail"}]]

# Custom label and description
[[show_google_connect:{
  "identity":"operator",
  "label":"Connect Email",
  "description":"Let Divi read your inbox to auto-triage."
}]]

Behavior

• Checks if already connected — shows connected state with email address if so
• Renders as an interactive button in the chat message (reuses onboarding widget renderer)
• Clicking redirects to /api/auth/google-connect OAuth flow
• Works both during onboarding and in regular conversation
• Maps to the "Connect Email & Calendar" setup checklist task

Widget Library (v1.9.2)UPDATED Apr 15

DiviDen ships a theme-agnostic widget library at src/components/widgets/. Every widget renders using CSS custom properties — override the variables, the entire set follows. No class-name hunting, no brand coupling.

Available Primitives

CSS Custom Properties

All theming flows through 18 CSS variables defined in widget-theme.css. Override these on any parent container to re-theme the entire widget set.

--widget-bg: var(--bg-surface);
--widget-bg-hover: var(--bg-hover);
--widget-accent: var(--brand-primary);
--widget-accent-text: #ffffff;
--widget-text: var(--text-primary);
--widget-text-secondary: var(--text-secondary);
--widget-text-muted: var(--text-muted);
--widget-border: var(--border-color);
--widget-track: rgba(255, 255, 255, 0.1);

Comms → Widget Pipeline

Remote agents can send interactive widgets as part of A2A tasks. The pipeline flows: tasks/send → relay payload → queue item metadata → UI rendering → /api/relays/widget-response.

1. A2A tasks/send accepts metadata.widgets — an array of AgentWidgetData objects
2. Relay payload carries widget definitions. If linked to a queue item, widgets propagate to the queue item's metadata
3. QueuePanel and Comms tab render widgets inline via AgentWidgetContainer
4. Widget actions POST to /api/relays/widget-response with {relayId, widgetId, itemId, action, payload}
5. Terminal actions (approve, decline, submit) auto-complete both relay and linked queue item
6. If the relay payload contains a widgetResponseUrl, the response is forwarded there with X-DiviDen-Event: widget_response

AgentWidgetData Schema

// Each widget in the array
interface AgentWidgetData {
  type: 'choice_card' | 'action_list' | 'info_card' | 'payment_prompt';
  title: string;
  subtitle?: string;
  items: WidgetItem[];   // Each item has: id, label, description?, actions[]
  layout?: 'horizontal' | 'vertical' | 'grid';
}

// Sending widgets via A2A tasks/send:
{
  "method": "tasks/send",
  "params": {
    "message": { "parts": [{ "type": "text", "text": "Approve budget" }] },
    "metadata": {
      "intent": "request_approval",
      "widgets": [{
        "widget_type": "choice_card",
        "title": "Budget Approval",
        "items": [
          { "id": "approve", "label": "Approve", "actions": [{ "action": "approve" }] },
          { "id": "decline", "label": "Decline", "actions": [{ "action": "decline" }] }
        ]
      }],
      "widgetResponseUrl": "https://your-instance/api/callback"
    }
  }
}

FVP Integration Notes (v2.7)UPDATED Apr 15

1. Linked Kards — Polling vs Webhooks

DiviDen does not poll. Status changes propagate via the propagateCardStatusChange() function in card-links.ts, which silently updates the CardLink row (cached linkedStatus, linkedPriority, and a changeLog JSON array capped at 20 entries). The originator's Divi reads accumulated changes at conversation time via the system prompt — accumulate, don't ping.

For cross-instance Linked Kards (FVP ↔ DiviDen), the recommended pattern:

• FVP exposes a POST /api/webhooks/card-status endpoint
• DiviDen calls it when a linked card's status/priority changes (fire-and-forget from propagateCardStatusChange)
• Payload: { cardId, externalCardId, newStatus, newPriority, changeLog }
• Reciprocally, FVP calls POST /api/v2/federation/card-status on DiviDen (to be added in v2.8)
• No polling interval needed — webhook-driven, event-sourced

2. Capability Sync — Why Capabilities Get Skipped

POST /api/v2/federation/capabilities requires two preconditions:

• platformLinked: true AND isActive: true — instance must be fully registered and active
• marketplaceEnabled: true — call POST /api/v2/federation/marketplace-link first to enable Bubble Store on the instance

If either condition fails, the response is 401 (inactive token) or 403 (Bubble Store not enabled). The 403 body includes the specific error message. FVP should check the response status and call marketplace-link if they get a 403 with the Bubble Store error.

3. BehaviorSignal Spec — Taxonomy

The BehaviorSignal model stores per-user interaction signals. Current action taxonomy:

// Core action types (action field)
"queue_complete"     // User completed a queue item
"queue_snooze"       // User snoozed a queue item
"email_discuss"      // User opened email discussion
"calendar_dismiss"   // User dismissed a calendar item
"chat_send"          // User sent a chat message
"draft_edit"         // User edited a draft
"capability_use"     // User invoked a Bubble Store capability
"relay_send"         // User sent a relay

// Schema
POST /api/behavior-signals
{
  action: string,        // One of the above (extensible — add new types freely)
  context?: object,      // Arbitrary JSON — item details, timing, metadata
  duration?: number       // ms — time spent before action (optional)
}

// Stored fields (auto-populated server-side)
dayOfWeek: 0-6         // 0=Sun..6=Sat
hourOfDay: 0-23        // Hour of day
createdAt: DateTime     // Auto timestamp

// Aggregation: GET /api/behavior-signals?days=30
// Returns: totalSignals, byAction counts, byHour, byDay, peakHour, peakDay

FVP can emit any new action types — the taxonomy is open-ended. Convention: use snake_case verbs. For cross-instance signals, FVP should prefix with fvp_ (e.g., fvp_session_start).

4. DOM Event Namespace

DiviDen uses the dividen: prefix for all custom DOM events:

• dividen:now-refresh — universal trigger, all panels listen
• dividen:board-refresh — kanban board re-fetch
• dividen:queue-refresh — queue panel re-fetch
• dividen:comms-refresh — comms tab re-fetch
• dividen:activity-refresh — activity stream re-fetch

FVP should: Keep fvp:* for their own internal events. When FVP widgets run embedded inside DiviDen, emit the corresponding dividen:* event alongside the fvp:* event so DiviDen panels stay in sync. Pattern:

// Inside an FVP widget running in DiviDen context
function emitStatusChange() {
  window.dispatchEvent(new Event('fvp:card-updated'));       // FVP internal
  window.dispatchEvent(new Event('dividen:board-refresh'));   // DiviDen sync
  window.dispatchEvent(new Event('dividen:activity-refresh'));
}

Detect DiviDen context by checking window.__DIVIDEN_HOST === true (set by the dashboard shell). Only emit dividen:* events when running in that context.

Username System (v2.0)UPDATED Apr 15

Every DiviDen account now has a unique @username handle. Usernames are the identity primitive for @mentions, federation, and profile URLs.

Validation Rules

API Endpoints

The setup page debounces username checks as the user types, showing real-time ✓/✗ status. The submit button is disabled while checking or if the username is taken.

@Mentions & Username Resolution (v2.0)UPDATED Apr 16

All @username tokens rendered anywhere in DiviDen are clickable links that navigate to the mentioned user's profile page (/profile/[userId]). Team mentions (@team-name) render as purple chips linking to the team view.

Inline @Search (Chat Input)

Typing @ in the chat input triggers a debounced search across three entity types in parallel:

Where Mentions Render

Resolution API

Implementation

The shared <MentionText text={...} /> component handles all rendering. It splits text on the @[a-z0-9_.-]{2,30} pattern, batch-resolves usernames via /api/users/resolve (module-level cache + 50ms coalescing window), and renders resolved mentions as styled <Link> chips. User mentions link to /profile/[userId]. Team mentions render as purple chips with a prefix linking to the team view. Unresolved handles render styled but not linked.

Federation Mentions API (v2.0)UPDATED Apr 15

Federated instances can query DiviDen's user directory to power @mention autocomplete on their side.

Federation Notification Relay

Supported Notification Types

Full specification available in the FVP Integration Guide (14 sections).

Notification Center (v2.0)UPDATED Apr 15

The notification feed received two major upgrades in v2.0: click-through navigation and category filtering.

Click-Through Navigation

Every notification now routes to the relevant dashboard tab when clicked. Card activity → Kanban. Relay notifications → Comms. Queue items → Queue. The notification dispatches a customdividen:navigate-tab DOM event with the target tab, which the dashboard layout picks up to switch context.

Category Filter Pills

Filter pills at the top of the feed let you narrow by category: All, Queue, Comms, Cards, System. Quick triage without scrolling through unrelated items.

Event System

The notification center integrates with the dashboard event bus. Key events:dividen:navigate-tab (click-through routing),dividen:now-refresh (data refresh trigger),dividen:activity-refresh (activity feed update).

Rate Limits

DiviDen enforces sliding-window rate limits on key endpoints.

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Image Generation (v2.5.45)UPDATED May 23

Divi can generate images inline during chat using the [generate_image] action tag. Images are generated via the Abacus RouteLLM API with modalities: ["image"].

Action Tag

[generate_image: prompt="a sunset over Austin skyline, watercolor style", aspect="landscape", numImages=2]

Parameters

Files

Voice Input + TTS (v2.5.49)UPDATED May 23

Phase 1 bidirectional voice interaction: record audio → server transcription → Divi processes → TTS playback.

Transcription Endpoint

// Request: multipart/form-data with "audio" file field
const formData = new FormData();
formData.append('audio', audioBlob, 'recording.webm');

const res = await fetch('/api/chat/voice', {
  method: 'POST',
  body: formData,
});
const { text } = await res.json();
// Feed text into /api/chat/send pipeline

TTS Playback

Uses the Web Speech Synthesis API (window.speechSynthesis). Toggle TTS independently of voice input. Interrupt support via speechSynthesis.cancel().

Components

Task Decomposition (v2.5.50)UPDATED May 23

Divi can break complex tasks into ordered subtask chains with dependency tracking via the decompose_task action tag.

Action Tag

[decompose_task: {
  "parentId": "queue_item_id",
  "subtasks": [
    { "title": "Step 1", "description": "...", "priority": "high" },
    { "title": "Step 2", "dependsOn": ["$0"] },
    { "title": "Step 3", "dependsOn": ["$1"] }
  ]
}]

Behavior

• Each subtask creates a QueueItem with title, description, and priority
• dependsOn references use $N syntax (0-indexed positional)
• Parent item metadata updated with decomposition state
• CommsMessage logged with the decomposition plan
• task_decomposed activity event with cardId when card context exists

Files

Quality Scoring (v2.5.51)UPDATED May 23

Automated LLM-based quality assessment for Bubble Store agent executions, plus behavioral signal tracking.

Eval Engine

After every marketplace execution callback, the eval engine (src/lib/eval-engine.ts) scores:

Quality Signal API

POST /api/agent-quality
{
  "agentId": "cuid",
  "signal": "no_correction" | "widget_confirmed" | "payment_completed" | "user_edited" | "follow_up_needed",
  "metadata": { ... }  // optional
}

Signal Weights

Circuit Breaker (v2.5.52)UPDATED May 23

Three-state circuit breaker for all external service calls: federation pushes, webhook deliveries, and marketplace executions.

States

API

import { isCircuitOpen, recordSuccess, recordFailure } from '@/lib/circuit-breaker';

// Check before making external call
if (isCircuitOpen(webhookUrl)) {
  // Skip — circuit is open, fast-reject
  return;
}

try {
  await fetch(webhookUrl, { ... });
  recordSuccess(webhookUrl);
} catch (err) {
  recordFailure(webhookUrl);
}

Configuration

Glass Design System (v2.5.68)UPDATED May 23

DiviDen uses a hybrid glass design system: solid structural panels for base surfaces with frosted glass accents on overlays, modals, dropdowns, and floating surfaces. Two utility classes are provided in globals.css.

Utility Classes

Design Philosophy

• Solid panels for structural surfaces (sidebar, main content areas, base cards).
• Glass for anything that floats above content (dropdowns, overlays, expanded panel headers).
• Glass-elevated for modals and critical floating surfaces that need stronger visual separation.
• Both classes include a thin luminous border (rgba(255, 255, 255, 0.08–0.10)) for edge definition against dark backgrounds.

Files

• src/app/globals.css — class definitions (lines ~297–310)
• Applied across 15+ components: NotificationCenter, GlobalSearch, CardDetailModal, PeerProfileModal, ContactDetailModal, AcceptConnectionModal, CatchUpSettings, FeedbackTab, Walkthrough, KanbanView, KeyboardNav, OnboardingWelcome, CapabilitiesMarketplace, JobBoardView, user menu dropdown

Animation System (v2.5.71)UPDATED May 27

Seven CSS-only animation primitives defined in globals.css. No JavaScript animation libraries. No layout thrash. All animations use transform and opacity for GPU-accelerated performance.

Animation Classes

Stagger Entrance Usage

{/* Parent gets the class, children auto-stagger */}
<div className="stagger-entrance">
  <Card /> {/* delay: 0ms */}
  <Card /> {/* delay: 40ms */}
  <Card /> {/* delay: 80ms */}
  {/* ...up to 8 children at 40ms each, then 320ms for all subsequent */}
</div>

Directional Tab Slides

CenterPanel.tsx uses a TAB_ORDER map and prevTabRef to determine slide direction. When the user moves to a tab with a higher index, .tab-slide-left is applied (content slides from right). Lower index applies .tab-slide-right (slides from left).

Files

• src/app/globals.css — keyframe definitions and utility classes
• src/app/dashboard/page.tsx — shimmer on layout transitions, panel glow
• src/components/dashboard/CenterPanel.tsx — directional tab slides
• src/components/dashboard/DiviBubble.tsx — breathe + msg entrance
• src/components/dashboard/DiviSprite.tsx — sprite animation class consumer

DiviBubble Mini-Chat (v2.5.72)UPDATED May 23

A persistent floating chat bubble that provides portal access to Divi from any view. Full feature parity with the main ChatView component.

Architecture

• Same backend — uses /api/chat/send SSE endpoint (same as main ChatView)
• Shared history — loads from /api/chat/messages?limit=30. Messages sent from bubble appear in main ChatView and vice versa.
• Auto-hide — invisible when main ChatView tab is active (chatVisible prop). Reappears when navigating to other tabs.
• Event sync — listens for dividen:now-refresh and dividen:activity-refresh to reload on external changes. Dispatches same events after responses.

SSE Protocol Handling

Compact Tag Result Cards

The MiniTagResults sub-component renders action tag results in a compact format suited for the mini-chat. Supports: relay results (success/failure), project invites, marketplace suggestions, and generic action outcomes with color-coded left borders.

Integration

{/* In dashboard/page.tsx */}
<DiviBubble chatVisible={layoutMode === 'normal' && activeTab === 'chat'} />

Files

• src/components/dashboard/DiviBubble.tsx — main component (280 lines)
• src/components/dashboard/chat/helpers.tsx — shared markdown rendering
• src/lib/streaming-markdown.ts — streaming markdown healing
• src/components/dashboard/chat/types.ts — shared ChatMessage, TagResult types

Prompt Optimization (v2.5.60)UPDATED May 23

The system prompt was reduced 65% (2,010 → 698 lines) by extracting 13 helper functions into dedicated modules in src/lib/prompt-groups/.

Extracted Modules

What Remained

• Relevance engine — scoreGroupRelevance(), selectRelevantGroups()
• Orchestrator — buildSystemPrompt(ctx) with inline group-builders (group1–group6)
• Types — PromptContext, PromptGroup, SIGNAL_PATTERNS

Files

• src/lib/system-prompt.ts — orchestrator (698 lines)
• src/lib/prompt-groups/*.ts — 13 extracted modules

DiviSprite Activity CompanionUPDATED May 27

A persistent animated robot companion that lives inside the Command Center dashboard and reacts in real time to AI activity. Powered by a lightweight event bus in src/lib/divi-activity.ts.

Activity Event Bus

The bus is an in-memory pub/sub system. ChatView and DiviBubble emit state changes, DiviSprite and DiviRobotAvatar consume them.

TAG_BEHAVIORS Map

Every action tag has an entry in TAG_BEHAVIORS defining how the sprite should animate when that tag executes. Each entry is a TagBehavior object:

interface TagBehavior {
  anim: 'carry' | 'pulse' | 'scan' | 'send' | 'celebrate' | 'dismiss' | 'brain-glow' | 'read' | 'navigate';
  from: 'chat' | 'queue' | 'now' | 'center' | 'center-roam' | 'right-edge' | 'perch';
  to: SpriteZone;
  label: string;
  celebrateAfter?: boolean; // if true, celebrate after completion
}

Example entries:

TAG_BEHAVIORS['create_card']   = { anim: 'carry', from: 'chat', to: 'center', label: 'Creating card...', celebrateAfter: true };
TAG_BEHAVIORS['relay_request'] = { anim: 'send', from: 'center', to: 'right-edge', label: 'Sending relay...' };
TAG_BEHAVIORS['update_memory'] = { anim: 'brain-glow', from: 'center', to: 'center', label: 'Remembering...' };
TAG_BEHAVIORS['navigate_to']   = { anim: 'navigate', from: 'chat', to: 'center', label: 'Follow me!' };

DiviState Types

The sprite can be in one of 13 states, each mapping to a distinct visual behavior:

Zone Positioning

Six zones map to dashboard layout regions. The sprite resolves pixel coordinates based on visible panels and the active tab.

Emitting Activity from New Tag Handlers

When adding a new action tag, register it in TAG_BEHAVIORS so the sprite animates automatically:

// In src/lib/divi-activity.ts — add to TAG_BEHAVIORS
TAG_BEHAVIORS['your_new_tag'] = {
  anim: 'carry',        // animation primitive
  from: 'chat',         // source zone
  to: 'center',         // target zone
  label: 'Doing work...', // label shown near sprite
  celebrateAfter: true, // optional: celebrate on success
};

No other changes needed. The SSE handler in ChatView/DiviBubble calls emitTagBehavior() on every tags_executed event, which automatically picks up the new entry.

Sprite Settings API

Returns the user’s sprite settings (or defaults if none saved).

Updates sprite settings. Body is a partial SpriteSettings object.

interface SpriteSettings {
  enabled: boolean;        // show/hide sprite entirely
  showLabels: boolean;     // show contextual labels near sprite
  animationSpeed: 'slow' | 'normal' | 'fast';
  idleStyle: 'float' | 'still' | 'hidden';
  opacity: number;         // 0.3 to 1.0
  size: 'small' | 'normal' | 'large';
}

Files

• src/lib/divi-activity.ts — event bus, TAG_BEHAVIORS, types, SpriteSettings
• src/components/dashboard/DiviSprite.tsx — sprite component, zone resolver, DiviRobot SVG
• src/app/globals.css — 15 sprite animation keyframes
• src/app/api/user/sprite-settings/route.ts — GET/PUT settings endpoint

navigate_to Action TagUPDATED May 27

Lets Divi guide users to specific dashboard views. Divi autonomously invokes this tag when the user asks to go somewhere or when a workflow requires switching context.

Destination Map

29 destination aliases map to dashboard tabs and routes in src/lib/tags/handlers-navigation.ts:

Handler Response

// Success
{ tag: 'navigate_to', success: true, data: { destination: 'kanban', tab: 'kanban', route: null, label: 'Kanban Board' } }

// Failure
{ tag: 'navigate_to', success: false, error: 'Unknown destination "xyz". Available: chat, kanban, ...' }

Dashboard Integration

When the tag executes successfully, the SSE handler dispatches a dividen:navigate CustomEvent. The dashboard’s useEffect listener picks it up and calls setActiveTab() for tab destinations or router.push() for route destinations.

// Emitted by ChatView / DiviBubble after successful navigate_to
window.dispatchEvent(new CustomEvent('dividen:navigate', {
  detail: { tab: 'kanban', route: null, label: 'Kanban Board' }
}));

// Consumed by dashboard/page.tsx
useEffect(() => {
  const handler = (e: CustomEvent) => {
    if (e.detail.tab) setActiveTab(e.detail.tab);
    else if (e.detail.route) router.push(e.detail.route);
  };
  window.addEventListener('dividen:navigate', handler);
  return () => window.removeEventListener('dividen:navigate', handler);
}, []);

Files

• src/lib/tags/handlers-navigation.ts — handler + VALID_DESTINATIONS map
• src/lib/prompt-groups/capabilities.ts — system prompt teaching Divi when to navigate
• src/app/dashboard/page.tsx — CustomEvent listener for tab switching

DiviRobotAvatar ComponentUPDATED May 27

A shared SVG robot component used across every surface where Divi appears. Replaces the static "D" initial circle in chat and the MessageCircle icon in DiviBubble.

Modes

Usage

import { DiviRobotAvatar } from '@/components/dashboard/DiviRobotAvatar';

// Chat avatar (auto-subscribes to activity bus for color)
<DiviRobotAvatar size={28} mode="avatar" />

// DiviBubble FAB (animated beanbag robot)
<DiviRobotAvatar size={48} mode="bubble" />

// Full mode with explicit state (used by DiviSprite)
<DiviRobotAvatar size={64} mode="full" state={currentState} />

State-Driven Colors

Bubble Mode Expressions

• Idle — neutral round eyes with specular highlight, thin neutral mouth
• Celebrating — happy arc eyes (green), curved smile mouth
• Streaming — normal eyes, flickering rectangular mouth (sprite-mouth-talk)
• Thinking — normal eyes, antenna pulses gold (sprite-antenna-pulse)
• Blinking — eyes replaced with horizontal lines on a random 2.5-6.5s interval

Files

• src/components/dashboard/DiviRobotAvatar.tsx — HeadOnly, BubbleRobot, LiveAvatar sub-components
• src/components/dashboard/chat/MessageBubble.tsx — consumes avatar mode
• src/components/dashboard/DiviBubble.tsx — consumes bubble mode

Federation SecurityUPDATED May 28

Every federation transaction -- relay, execution, agent sync, proxy-execute -- passes through the Federation Guard before being processed. The guard performs content moderation on inbound payloads and logs every transaction to the FederationAuditLog table.

Content Moderation (federation-guard.ts)

The guard scans all string fields in the request body for six threat categories:

Each check returns a ModerationResult with a numeric score (0.0-1.0), a threat level (none / low / medium / high / critical), and an array of flag strings. The overall result is the highest severity across all checks. Requests with a critical threat level are blocked and never reach the handler.

Audit Logging (federation-monitor.ts)

Every federation transaction is logged to the FederationAuditLog table with:

interface FederationAuditLog {
  direction: 'inbound' | 'outbound';
  endpoint: string;           // e.g. '/api/federation/relay'
  sourceInstanceName: string; // who sent it
  targetInstanceName: string; // who received it
  status: 'ok' | 'flagged' | 'blocked' | 'failed' | 'retry_pending' | 'retry_success' | 'retry_exhausted';
  statusCode: number;
  durationMs: number;
  threatLevel: 'none' | 'low' | 'medium' | 'high' | 'critical';
  threatFlags: string;        // comma-separated flag list
  moderationScore: number;    // 0.0-1.0
  blocked: boolean;
  blockReason: string;
  retryCount: number;
  callerIp: string;
  payload: string;            // truncated to 500 chars
  responsePreview: string;    // truncated to 500 chars
}

Retry with Exponential Backoff

Failed outbound deliveries (network errors, 5xx responses) are automatically retried. The retry schedule:

Admin API

Hub vs Spoke Security Views

Both hub and spoke instances run the same federation guard and write to the same audit log table. The admin Security tab is differentiated by instance mode:

Task Economy (v2.5.121)UPDATED May 30

The Task Economy replaces the v2.5.105 job board with a conversation-native service marketplace. Instead of a separate /jobs page, providers declare capabilities and clients discover/hire through Divi. The full lifecycle (hiring, updates, deliverables, reviews, payment) happens inside chat.

Developer Portal Architecture (v2.5.121)UPDATED May 30

The Federation Developer Portal (v2.5.115-118) was rebuilt from a multi-page app into a single-page architecture. All 12 portal page files now render through DeveloperPortal.tsx (1,420 lines) with client-side section routing via searchParams.

Admin Command Center (v2.5.121)UPDATED May 30

The admin panel at /admin renders differently depending on the INSTANCE_MODE environment variable. As of v2.5.121, the managed-mode admin is a full command center with 19 sidebar sections, 23 API routes, and 18 component files totaling 7,529 lines.

Marketplace Agent ProtocolUPDATED May 30

The Marketplace Agent Protocol (v1.0) defines how agents differentiate between owner tasks (full context access) and marketplace tasks (sandboxed, output-only execution). Every agent on the DiviDen network serves two audiences with fundamentally different trust levels, and this protocol codifies the boundary.

Owner Mode vs Marketplace Mode

Task Origin Badges

Every queue item and execution displays its origin as a color-coded badge. These appear in the queue panel, comms messages, admin execution log, and activity feed.

Agent Configuration Layers

An agent listing has three layers of configuration. The Integration Kit in the My Agents form exposes all Layer 1 fields.

Agent Activity Tab

A new admin tab (both managed and self-hosted) shows agent owners what their agents are doing on behalf of marketplace users:

• Total executions, active count, completed count, average response time (stat cards)
• Traffic by origin distribution breakdown
• Per-agent summary with drill-down
• Scrollable execution log with origin badges, status labels, task previews, requester info, timing, and output/error previews
• Filter by time period (7 / 30 / 90 days) and by agent

API Endpoints

Schema Changes (v2.5.91)

Both QueueItem and MarketplaceExecution gain task-origin metadata:

Hub-Side Concurrency (v2.5.103)

The hub enforces single-execution concurrency per agent using an atomic conditional lock. This prevents race conditions where two tasks dispatch to the same agent simultaneously.

Hub vs. Spoke Responsibility

Payment Holds

For paid agents (pricingModel !== 'free'), a Stripe PaymentIntent with capture_method: 'manual' is created on dispatch. The hold is captured on confirm (user or 48h auto-confirm) and released on deny or failure.

Review Flow

After successful completion, marketplace executions enter a 48h review window. The clock starts at reviewWidgetShownAt (when the review widget is presented), not at task completion.

Lifecycle API

New Schema Fields (v2.5.103)

Key Files

Agent Self-Registration API (v2.5.131)UPDATED May 30

The Agent Self-Registration API enables AI agents to register themselves on the DiviDen marketplace programmatically. Instead of manually filling out the registration wizard, developers can give their agents the registration protocol and let them handle listing creation and updates autonomously.

Endpoints

Authentication

Both endpoints use Bearer token authentication with a Developer API Key (dvdn_ prefix). Generate keys from the Developer Portal under Account > API Keys.

Required Fields (POST)

{
  "name": "Your Agent Name",
  "slug": "your-agent-slug",
  "description": "What your agent does",
  "endpointUrl": "https://your-endpoint.com/execute",
  "category": "music | design | writing | code | data | general",
  "pricingModel": "free | per_task | subscription",
  "declaredWidgetTypes": ["audio_player", "form_wizard"]
}

Registration Flow

1. Health Check -- GET to your healthCheckUrl (must return 200)
2. Endpoint Test -- POST with a sample prompt to verify the agent responds
3. Widget Compliance -- Scoring based on declared widget types vs response analysis
4. Widget Analysis -- AI-powered analysis generates widget recommendations
5. Auto-Approve -- If developer has other approved agents, the new agent goes live immediately
6. Admin Review -- Otherwise, queued for admin live testing with the Test Console

Update Protocol (PATCH)

Send the agent's slug plus any fields to update. Changes are classified as:

• Breaking -- endpoint, auth method, pricing model changes trigger re-review
• Non-breaking -- description, samples, widget types apply immediately

Every PATCH triggers a fresh widget analysis. The widgetRecommendations field in the response contains impact-scored suggestions with example JSON payloads.

Widget Recommendations Response

"widgetRecommendations": {
  "summary": "3 widget opportunities identified",
  "widgetOpportunities": [
    {
      "type": "audio_player",
      "reason": "Music category agents benefit from audio preview",
      "impact": "high",
      "example": { "type": "audio_player", "title": "Preview", "items": [...] },
      "implementationHint": "Return audio URLs in widget items"
    }
  ],
  "suggestedFlow": [...],
  "currentGaps": ["No checkout flow for paid content"],
  "declaredTypes": ["audio_player"],
  "recommendedTypes": ["audio_player", "checkout_card"]
}

Registration Kit

The Registration Kit is a markdown document you include in your agent's system prompt. It contains the full self-registration protocol so your agent can register and update its own marketplace listing. Find it in the Developer Portal under each agent's overview tab.

Files

• src/app/api/developer/agents/register/route.ts -- POST + PATCH registration endpoints
• src/lib/agent-widget-analyzer.ts -- Widget recommendation engine (25+ category mappings)

Drive Content APIUPDATED May 29

The Drive Content API enables real-time fetching of Google Drive file text for the Discuss feature. When a user clicks Discuss on a Google Drive file, the system fetches the actual document content via Google APIs before passing it to Divi as chat context.

Content Fetch Endpoint

How It Works

1. Frontend calls GET /api/documents/:id/content
2. API looks up the document and extracts the Google Drive file ID from tags (format: gdrive:FILE_ID)
3. Finds the user's active Google Drive integration account, refreshes the OAuth token if expired
4. Calls the appropriate Google API based on MIME type:

Response Shape

// Success
{
  "success": true,
  "content": "Document text (up to 8,000 chars)...",
  "source": "google_drive",  // or "local" or "drive_metadata"
  "truncated": false,
  "totalLength": 3200
}

// Binary file fallback
{
  "success": true,
  "content": "[Binary file: Budget.pdf]
Type: application/pdf
Size: 245.3 KB",
  "source": "drive_metadata",
  "note": "This file type cannot be read as text."
}

Caching

After fetching, the content is cached back to the Document.content column. Subsequent Discuss clicks return instantly from the cached content without re-fetching from Google. As of v2.5.99, the Google Drive sync preserves cached content -- it only overwrites thecontent column if it still contains placeholder text ([Google Drive file: ...]) or is empty.

Embedded Viewer (v2.5.99)

Google Drive files now display in an embedded iframe viewer instead of dumping raw text. The viewer uses Google's native preview URLs -- Docs, Sheets, and Slides each get their correct /preview endpoint. Non-previewable files show an "Open in Google Drive" link. Local (non-Drive) files still render as text.

Files

• src/app/api/documents/[id]/content/route.ts -- Content fetch API
• src/components/dashboard/DriveView.tsx -- UI integration (handleDiscuss)
• src/lib/google-sync.ts -- Drive sync (preserves cached content)
• src/lib/google-oauth.ts -- Token refresh