Blinkin 2.0 — Target Architecture

Derived from 32 superpowers specs · 2026-03-20 · Every box traces to a spec.

32
Specs
4
Surfaces
1
Unified Invoke
8
Trigger Types
3
Audit Tables
7
Context Types
4
Skill Standards
Based purely on the 32 specs in docs/superpowers/specs/. The architecture defines 4 surfaces sharing one Session Kernel, a unified /api/invoke boundary, Spaces as a first-class knowledge domain, a 3-table audit model, 8 trigger types, canary versioning, and the R2 Revenue Ready platform stack (Stripe + Auth0 + PostHog + Resend).

1. Full Architecture — As Specified

4 Surfaces → Session Kernel → Agent Runtime → Data Layer
100% 
graph TB
  subgraph SURFACES["4 SURFACES"]
    direction LR
    subgraph S1["Employee App"]
      Chat["Chat + Widgets"]
      SpaceUI["Space Assistant"]
      ControlPlane["Control Plane
Kanban Board"]
      MemPanel["Memory Panel"]
    end
    subgraph S2["Builder Workspace"]
      Journey["Journey"]
      Canvas["Canvas"]
      Inspector["Inspector"]
      Preview["Preview"]
      Publish["Publish"]
    end
    subgraph S3["Admin Console"]
      OrgSettings["Org Settings"]
      UsageDash["Usage Dashboard"]
      ProviderKeys["Provider Keys"]
      PolicyMgmt["Policy Profiles"]
    end
    subgraph S4["Published App Plane"]
      PubRuntime["Published Runtime
(immutable snapshot)"]
      EndUserChat["End-User Chat"]
      VersionRouter["Version Router
(canary / active)"]
    end
  end

  subgraph KERNEL["SESSION KERNEL"]
    direction LR
    InvokeAPI["/api/invoke
(unified boundary)"]
    SessionMgr["SessionRecord
FSM: created→active
⇄paused→completed"]
    ContextAssembly["Context Engine
assembleContextPrompt()"]
    PermPipeline["Permission Pipeline
PolicyProfileRecord"]
  end

  subgraph AGENTS["AGENT RUNTIME"]
    direction LR
    subgraph AgentCore["Agent Loop"]
      PlanAct["Plan → Act → Observe
→ Emit → Verify"]
      ProviderRouter["ProviderRouter
Claude · Gemini · GPT"]
      ToolRouter["Tool Router
CLI · API · Shell"]
    end
    subgraph SubAgents["Sub-Agent Layer"]
      InvokeAgent["invoke_agent
(sync, depth-1)"]
      KanbanAsync["Kanban Path
(async, long-running)"]
    end
    subgraph Workspace["Agent Workspace"]
      WSFiles["/data/workspaces/
{orgId}/{agentId}/"]
      Skills["skills/"]
      Memory["memory/"]
      Outputs["outputs/"]
    end
    ApprovalGate["ApprovalRequest
risk-tier gating"]
  end

  subgraph TRIGGERS["TRIGGER DAEMON"]
    direction LR
    Manual["manual"]
    Scheduled["scheduled
(cron)"]
    Webhook["webhook"]
    OnMessage["on_message"]
    Event["event"]
    Interval["interval"]
    Poll["poll"]
    Once["once"]
  end

  subgraph SPACES["SPACES DOMAIN"]
    direction LR
    SpaceRecord["SpaceRecord"]
    KnowledgeItems["SpaceKnowledgeItem
file · website · note
voice · youtube"]
    IntakePipeline["Intake Pipeline
upload → processing → ready"]
    RAGSearch["RAG Query API
/spaces/:id/knowledge/query"]
    HybridSearch["Hybrid Search
Vectorize + D1 FTS5"]
  end

  subgraph CONTEXT["BUSINESS CONTEXT"]
    direction LR
    OrgSkills["OrgSkillRecord
(SKILL.md frontmatter)"]
    AgentBindings["AgentSkillBinding"]
    Persona["Persona
(SOUL-like)"]
    WritingRules["Writing Rules"]
    BrandGuide["Brand Guidelines"]
    Templates["Templates"]
    SOPs["SOPs"]
    DomainKnow["Domain Knowledge"]
    Playbooks["Skill Playbooks"]
  end

  subgraph AUDIT["AUDIT & EVAL"]
    direction LR
    PlatformLog["PlatformAuditLog
(system events)"]
    AgentLog["AgentActivityLog
(tool calls, delegations)"]
    RunLog["RunEventLog
(immutable per-run)"]
    EvalLoop["EvalRuleSet
quality · accuracy
style · cost · feedback"]
  end

  subgraph PLATFORM["PLATFORM SERVICES (R2)"]
    direction LR
    Auth0["Auth0
JWT + RBAC + SSO"]
    Stripe["Stripe
Subscription +
Usage Metering"]
    PostHog["PostHog
Analytics"]
    Resend["Resend
Email"]
    Houston["Houston Protection
org budget · app rate
end-user abuse"]
    TenantMgr["Multi-Tenant
Manager"]
    EndUserID["End-User Identity
authenticated /
anonymous (SHA-256)"]
  end

  subgraph STORAGE["STORAGE"]
    direction LR
    SQLite["SQLite per Org
(dev)"]
    Postgres["PostgreSQL
(production)"]
    BlobStore["Blob Store
Local + S3/R2"]
    Vectorize["Cloudflare
Vectorize"]
    D1FTS["D1 FTS5
(BM25)"]
  end

  %% Connections: Surfaces → Kernel
  Chat -->|"POST"| InvokeAPI
  SpaceUI -->|"POST"| InvokeAPI
  EndUserChat -->|"POST"| InvokeAPI
  ControlPlane -->|"dispatch"| SessionMgr
  Publish -->|"creates"| PubRuntime
  VersionRouter -->|"resolves"| PubRuntime

  %% Kernel → Agent Runtime
  InvokeAPI --> SessionMgr
  SessionMgr --> ContextAssembly
  ContextAssembly --> PermPipeline
  PermPipeline --> PlanAct

  %% Agent internals
  PlanAct --> ProviderRouter
  PlanAct --> ToolRouter
  PlanAct -->|"high-risk"| ApprovalGate
  ApprovalGate -->|"SSE: approval.requested"| Chat
  PlanAct --> InvokeAgent
  InvokeAgent -->|"spawns"| PlanAct

  %% Triggers → Kernel
  TRIGGERS -->|"creates runs"| InvokeAPI

  %% Agent ↔ Spaces
  ToolRouter -->|"knowledge_search"| RAGSearch
  RAGSearch --> HybridSearch
  KnowledgeItems --> IntakePipeline
  HybridSearch --> Vectorize
  HybridSearch --> D1FTS

  %% Agent ↔ Context
  ContextAssembly -->|"loads skills"| OrgSkills
  ContextAssembly -->|"loads persona"| Persona
  ContextAssembly -->|"loads rules"| WritingRules

  %% Agent → Workspace
  ToolRouter -->|"workspace_read/write"| WSFiles

  %% Agent → Audit
  PlanAct -->|"emits events"| RunLog
  ToolRouter -->|"logs"| AgentLog

  %% Agent → Storage
  ToolRouter -->|"create_document"| BlobStore
  SessionMgr -->|"persists"| SQLite
  SessionMgr -->|"persists"| Postgres

  %% Platform services
  Auth0 -->|"validates"| InvokeAPI
  Houston -->|"rate-limits"| InvokeAPI
  Stripe -->|"metering"| SessionMgr
  EndUserID -->|"resolves"| PubRuntime

  %% Eval
  RunLog -->|"feeds"| EvalLoop

  %% Styling
  style SURFACES fill:#EEF2FF,stroke:#6366f1,stroke-width:2px
  style KERNEL fill:#FEF3C7,stroke:#f59e0b,stroke-width:2px
  style AGENTS fill:#FDF2F8,stroke:#ec4899,stroke-width:2px
  style TRIGGERS fill:#FFF7ED,stroke:#f97316,stroke-width:2px
  style SPACES fill:#E0F2FE,stroke:#0284c7,stroke-width:2px
  style CONTEXT fill:#F5F3FF,stroke:#8b5cf6,stroke-width:2px
  style AUDIT fill:#FEF2F2,stroke:#ef4444,stroke-width:2px
  style PLATFORM fill:#F8FAFC,stroke:#94a3b8,stroke-width:2px
  style STORAGE fill:#F0FDF4,stroke:#22c55e,stroke-width:2px

2. Invocation Flow — All Channels Converge

One public boundary: /api/invoke. Employee chat, published apps, triggers, and sub-agents all converge here. The Session Kernel creates a SessionRecord, assembles context, evaluates policy, then hands off to the Agent Loop. Spec sources: enterprise-agentic-platform-design, enterprise-agentic-platform-reconciled, session-lifecycle-design, approval-contract-design
Unified /api/invoke → Session → Agent Loop → Output
100% 
graph LR
  subgraph Channels["ALL CHANNELS"]
    EmpChat["Employee Chat"]
    PubApp["Published App"]
    Trigger["Trigger Daemon"]
    SubAgent["invoke_agent
(sub-agent)"]
    Kanban["Kanban Dispatch"]
  end

  Invoke["/api/invoke
(unified boundary)"]

  subgraph SessionK["SESSION KERNEL"]
    Session["SessionRecord
type: chat|app|work_item"]
    Run["InvocationRun"]
    CtxEng["Context Engine
Business Context
+ Space bindings
+ Agent Memory
+ Run Context"]
    Policy["Permission Pipeline
PolicyProfileRecord
tool allowlists"]
  end

  subgraph AgentRun["AGENT LOOP"]
    Plan["PLAN
structured steps"]
    Act["ACT
tool calls"]
    Observe["OBSERVE
evaluate result"]
    Emit["EMIT
SSE stream"]
    Verify["VERIFY
review agent"]
  end

  subgraph Approval["APPROVAL GATE"]
    Check["Risk tier check"]
    Pause["Session paused
approval.requested"]
    Decision["Approved /
Rejected"]
  end

  subgraph Output["OUTPUT"]
    TextDelta["text.delta"]
    WidgetSpec["widget.spec"]
    DocOp["document.op"]
    StatePatch["state.patch"]
    RunComplete["run.completed"]
  end

  EmpChat --> Invoke
  PubApp --> Invoke
  Trigger --> Invoke
  SubAgent --> Invoke
  Kanban --> Invoke

  Invoke --> Session --> Run --> CtxEng --> Policy

  Policy --> Plan --> Act
  Act --> Observe --> Emit
  Emit --> Verify
  Verify -->|"next step"| Plan
  Verify -->|"done"| Output

  Act -->|"high-risk tool"| Check
  Check -->|"medium/high/critical"| Pause
  Pause -->|"human decides"| Decision
  Decision -->|"approved"| Act
  Decision -->|"rejected"| Observe

  style Channels fill:#EEF2FF,stroke:#6366f1,stroke-width:2px
  style SessionK fill:#FEF3C7,stroke:#f59e0b,stroke-width:2px
  style AgentRun fill:#FDF2F8,stroke:#ec4899,stroke-width:2px
  style Approval fill:#FEF2F2,stroke:#ef4444,stroke-width:2px
  style Output fill:#ECFDF5,stroke:#10b981,stroke-width:2px
  style Invoke fill:#fff,stroke:#f59e0b,stroke-width:3px

3. Session Lifecycle — Finite State Machine

Sessions support pause/resume for approvals, multi-day workflows, and crash recovery. Three session types (chat, app, work_item) with different memory scopes and pause patterns. Spec source: session-lifecycle-design
SessionRecord State Machine
100% 
stateDiagram-v2
  [*] --> created
  created --> active : invoke starts
  active --> paused_for_approval : high-risk action
  active --> paused_for_input : needs user input
  active --> sleeping : scheduled resume
  paused_for_approval --> active : approved
  paused_for_approval --> failed : rejected
  paused_for_approval --> expired : 60min timeout
  paused_for_input --> active : user responds
  sleeping --> active : cron fires
  active --> completed : run finishes
  active --> failed : unrecoverable error
  expired --> [*]
  completed --> [*]
  failed --> [*]

4. Spaces & Knowledge Infrastructure

Spaces are a first-class domain. Knowledge items enter via 5 intake channels, process through backend pipelines, and become searchable via hybrid search (Vectorize cosine + D1 BM25). Agents consume Spaces read-only via RAG APIs. Spec sources: space-domain-foundation, space-agent-integration-contract, space-knowledge-intake, space-multi-upload, knowledge-infrastructure, audio-voice-ingestion, space-upload-tier-and-billing
Space Domain → Intake → Hybrid Search → Agent
100% 
graph TB
  subgraph Intake["5 INTAKE CHANNELS"]
    direction LR
    FileUp["File Upload
(multi-file)"]
    WebBatch["Website URLs
(batch queue)"]
    YouTube["YouTube URL"]
    Note["Note
(full text)"]
    Voice["Voice Note
(real audio)"]
  end

  subgraph Processing["BACKEND PIPELINE"]
    direction LR
    Scraper["Web Scraper
(Cloudflare Browser)"]
    Transcriber["Audio Transcriber
(Gemini / Deepgram)"]
    Chunker["Content Chunker"]
    Embedder["Embedding Pipeline
(Workers AI)"]
  end

  subgraph SpaceDomain["SPACE DOMAIN"]
    SpaceRec["SpaceRecord"]
    KI["SpaceKnowledgeItem
status: processing → ready"]
    Settings["SpaceSettings"]
    Access["SpaceAccessGrant
(sharing)"]
    ConvBind["SpaceConversationBinding"]
  end

  subgraph Search["HYBRID SEARCH"]
    SemanticLeg["Semantic Leg
Cloudflare Vectorize
(cosine similarity)"]
    KeywordLeg["Keyword Leg
D1 FTS5
(BM25)"]
    Merge["Merge
0.45 semantic
0.45 keyword
0.10 recency"]
  end

  subgraph Agents["AGENT CONSUMPTION"]
    direction LR
    ListAPI["GET /spaces/:id/knowledge
(list + filter)"]
    QueryAPI["POST /spaces/:id/knowledge/query
(RAG search)"]
    ToolCall["knowledge_search tool"]
  end

  subgraph Limits["UPLOAD TIER LIMITS"]
    direction LR
    HardLimit["hardLimitBytes
(technical safety)"]
    TierLimit["tierLimitBytes
(product tier)"]
    EffLimit["effective = min()"]
  end

  FileUp --> KI
  WebBatch --> KI
  YouTube --> KI
  Note -->|"ready immediately"| KI
  Voice --> KI

  KI -->|"website"| Scraper
  KI -->|"voice/audio"| Transcriber
  Scraper --> Chunker
  Transcriber --> Chunker
  KI -->|"file"| Chunker
  Chunker --> Embedder

  Embedder -->|"vectors"| SemanticLeg
  Embedder -->|"text"| KeywordLeg
  SemanticLeg --> Merge
  KeywordLeg --> Merge

  SpaceRec --- KI
  SpaceRec --- Settings
  SpaceRec --- Access
  SpaceRec --- ConvBind

  Merge --> QueryAPI
  KI --> ListAPI
  ToolCall --> QueryAPI

  FileUp --> EffLimit
  HardLimit --> EffLimit
  TierLimit --> EffLimit

  style Intake fill:#E0F2FE,stroke:#0284c7,stroke-width:2px
  style Processing fill:#FEF3C7,stroke:#f59e0b,stroke-width:2px
  style SpaceDomain fill:#E0F2FE,stroke:#0284c7,stroke-width:2px
  style Search fill:#F5F3FF,stroke:#8b5cf6,stroke-width:2px
  style Agents fill:#FDF2F8,stroke:#ec4899,stroke-width:2px
  style Limits fill:#F8FAFC,stroke:#94a3b8,stroke-width:1px

5. PR Text Studio — First Agentic App Pattern

4-agent team: Supervisor coordinates Briefing, Research, and Writer agents. Skills stored as OrgSkillRecord with progressive disclosure (index in prompt, full content via workspace_read). Multi-model routing: Perplexity for web research, Opus for reasoning, Gemini for multimodal. Spec source: pr-text-studio-design
PR Text Studio — 4-Agent Team
100% 
graph TB
  User["User
format + style + chat"]

  subgraph Team["PR TEXT STUDIO AGENT TEAM"]
    Supervisor["Supervisor Agent
(Claude Opus)
coordinates team"]
    Briefing["Briefing Agent
(Claude Sonnet)
parses instructions"]
    Research["Research Agent
(Gemini / Perplexity)
deep web search"]
    Writer["Writer Agent
(Claude Opus)
drafts text"]
  end

  subgraph Skills["PROGRESSIVE SKILL DISCLOSURE"]
    Index["Skill index in prompt
(lightweight)"]
    FullSkill["workspace_read()
loads full SKILL.md"]
  end

  subgraph Knowledge["KNOWLEDGE SPACE (optional)"]
    SpaceRAG["Bound Space
RAG search"]
  end

  subgraph Output["OUTPUT"]
    TipTap["TipTap Editor
(inline editing)"]
    WorkItem["WorkItemRecord
(audit trail)"]
    PDF["PDF Export"]
  end

  User -->|"chat"| Supervisor
  Supervisor -->|"invoke_agent"| Briefing
  Supervisor -->|"invoke_agent"| Research
  Supervisor -->|"invoke_agent"| Writer
  Briefing -->|"parsed brief"| Supervisor
  Research -->|"findings"| Supervisor
  Writer -->|"draft"| Supervisor

  Supervisor --> Index
  Index -->|"on demand"| FullSkill

  Research --> SpaceRAG

  Supervisor -->|"final output"| TipTap
  Supervisor -->|"logged"| WorkItem
  TipTap --> PDF

  style Team fill:#FDF2F8,stroke:#ec4899,stroke-width:2px
  style Skills fill:#F5F3FF,stroke:#8b5cf6,stroke-width:2px
  style Knowledge fill:#E0F2FE,stroke:#0284c7,stroke-width:1px
  style Output fill:#ECFDF5,stroke:#10b981,stroke-width:2px

6. Governance, Audit & Versioning

Three governance levels (workflow, action, reliability). Three audit tables for different audiences. Published apps use immutable versioned snapshots with canary traffic splitting and instant rollback. Spec sources: audit-event-taxonomy, approval-contract, published-app-versioning, security-audit, colleague-decision-ledger
3-Level Governance + 3-Table Audit + Canary Versioning
100% 
graph TB
  subgraph Gov["3-LEVEL GOVERNANCE"]
    direction TB
    subgraph G1["L1: Workflow Governance"]
      HITL["Human-in-the-Loop"]
      PeerReview["Peer Review"]
      ApprovalGates["Approval Gates"]
      RateLimits["Rate Limits"]
      CostCtrl["Cost Controls"]
      KillSwitch["Kill Switch"]
    end
    subgraph G2["L2: Action Governance"]
      PolicyEngine["PolicyProfileRecord
tool allowlists"]
      OutputValidation["Output Validation"]
      HashAudit["Hash-Chain Audit"]
      WidgetIsolation["Widget Isolation"]
    end
    subgraph G3["L3: Reliability (Phase 2)"]
      CircuitBreaker["Circuit Breaker"]
      SLO["SLO Enforcement"]
      ErrorBudget["Error Budget"]
      Replay["Replay Debugging"]
    end
  end

  subgraph Audit["3-TABLE AUDIT MODEL"]
    direction LR
    PAL["PlatformAuditLog
server lifecycle
user/org mgmt
policy changes"]
    AAL["AgentActivityLog
tool calls
delegations
approvals
(async, fire-and-forget)"]
    REL["RunEventLog
immutable per-run
every decision
context · model · tools
approval · sub-agent"]
  end

  subgraph Version["PUBLISHED APP VERSIONING"]
    direction LR
    Draft["draft"]
    Active["active"]
    Canary["canary
(traffic %)"]
    Archived["archived"]
    RolledBack["rolled_back"]
    Draft -->|"publish"| Active
    Active -->|"new version"| Canary
    Canary -->|"promote"| Active
    Canary -->|"rollback"| RolledBack
    Active -->|"superseded"| Archived
  end

  subgraph Audiences["AUDIT AUDIENCES"]
    direction LR
    PlatAdmin["Platform Admin"]
    OrgAdmin["Org Admin"]
    Compliance["Compliance Officer"]
  end

  PAL --> PlatAdmin
  AAL --> OrgAdmin
  REL --> Compliance

  REL -->|"feeds"| EvalLoop["Eval Loop"]

  style Gov fill:#FEF2F2,stroke:#ef4444,stroke-width:2px
  style Audit fill:#FEF3C7,stroke:#f59e0b,stroke-width:2px
  style Version fill:#EEF2FF,stroke:#6366f1,stroke-width:2px
  style Audiences fill:#F8FAFC,stroke:#94a3b8,stroke-width:1px

7. R2 Revenue Ready — Platform Services

The R2 commercial stack: Stripe for billing (subscription + usage metering), Auth0 for identity, PostHog for analytics, Resend for email. Houston 3-layer protection guards published apps. End-user identity supports both authenticated (JWT) and anonymous (SHA-256 fingerprint) modes. Spec sources: r2-revenue-ready-design, platform-defaults, customer-lifecycle, security-audit
R2 Stack — Billing, Auth, Analytics, Protection
100% 
graph TB
  subgraph Signup["SELF-SERVICE SIGNUP"]
    Landing["Landing Page"]
    Auth0Flow["Auth0
JWT + RBAC + SSO"]
    PlanSelect["Plan Selection
Free · Starter · Pro · Enterprise"]
    StripeCheckout["Stripe Checkout"]
    OrgCreated["Org Created +
Blinkin Assistant
provisioned"]
  end

  subgraph Billing["STRIPE BILLING"]
    Subscription["Subscription
(fixed price)"]
    UsageMeter["In-Process
Usage Metering"]
    StripeMeter["StripeMeter
dedup · late events
delta push"]
    Webhooks["Stripe Webhooks
invoice · payment
subscription"]
  end

  subgraph Protection["HOUSTON 3-LAYER PROTECTION"]
    OrgBudget["Layer 1: Org Budget Gate
monthly token ceiling"]
    AppRate["Layer 2: App Rate Limit
req/min per published app"]
    EndUserAbuse["Layer 3: End-User Abuse
per-user throttle"]
  end

  subgraph Identity["END-USER IDENTITY"]
    AuthMode["Authenticated
X-Blinkin-End-User-Id
(JWT shared secret)"]
    AnonMode["Anonymous
SHA-256(IP + UA + salt)
daily rotation"]
    MemScope["Memory Scope:
per-user (auth)
per-session (anon)"]
  end

  subgraph Services["PLATFORM SERVICES"]
    PostHog["PostHog
Product Analytics"]
    Resend["Resend
Email Templates
invite · reset · verify"]
    HealthCheck["Health Endpoints
/health + /health/ready"]
    Backup["Backup Cron
SQLite .backup()
+ rsync workspaces
30-day retention"]
  end

  subgraph Default["DEFAULT SUPER AGENT"]
    BlinkinAssist["Blinkin Assistant
Claude Sonnet 4.5
50k tokens/run
25 tool calls"]
    Tools["web_search
knowledge_search
read_article
memory tools
create_document"]
  end

  Landing --> Auth0Flow --> PlanSelect --> StripeCheckout --> OrgCreated
  OrgCreated --> BlinkinAssist
  BlinkinAssist --- Tools

  Subscription --> UsageMeter --> StripeMeter
  StripeMeter --> Webhooks

  OrgBudget --> AppRate --> EndUserAbuse

  AuthMode --> MemScope
  AnonMode --> MemScope

  style Signup fill:#EEF2FF,stroke:#6366f1,stroke-width:2px
  style Billing fill:#ECFDF5,stroke:#10b981,stroke-width:2px
  style Protection fill:#FEF2F2,stroke:#ef4444,stroke-width:2px
  style Identity fill:#FEF3C7,stroke:#f59e0b,stroke-width:2px
  style Services fill:#F8FAFC,stroke:#94a3b8,stroke-width:1px
  style Default fill:#FDF2F8,stroke:#ec4899,stroke-width:2px

8. Business Context & Skill Interoperability

Skills use a superset SKILL.md frontmatter format, importable from 4 standards (Agent Skills, OpenClaw, Claude Code, Clawith). OrgSkillRecord stores skills org-wide; AgentSkillBinding links agents to skills. Progressive disclosure: skill index in system prompt, full content loaded on demand via workspace_read(). Spec sources: standards-adoption-design, business-context-editor-design, agent-workspace-design
Skill Registry → Agent Binding → Progressive Loading
100% 
graph TB
  subgraph Standards["4 IMPORT STANDARDS"]
    direction LR
    AgentSkills["Agent Skills
(Anthropic)"]
    OpenClaw["OpenClaw
(SOUL.md)"]
    ClaudeCode["Claude Code
(skills/)"]
    Clawith["Clawith
(ClawHub)"]
  end

  Parser["ParsedSkillFrontmatter
(normalizes all 4)"]

  subgraph Registry["ORG SKILL REGISTRY"]
    OrgSkill["OrgSkillRecord
SKILL.md frontmatter:
name · category · version
risk-tier · source-standard
allowed-tools · content"]
    Versions["Version History"]
  end

  subgraph Binding["AGENT CONFIGURATION"]
    AgentDef["AgentDefinition
persona · model · tools
constraints · triggers"]
    SkillBind["AgentSkillBinding
(lightweight reference)"]
    ContextBind["Context Bindings
writing rules
brand · persona
templates · SOPs"]
  end

  subgraph Loading["PROGRESSIVE DISCLOSURE"]
    SysPrompt["System Prompt
(skill index only)"]
    OnDemand["workspace_read()
loads full SKILL.md
when agent needs it"]
    WSPath["/data/workspaces/
{orgId}/{agentId}/
skills/"]
  end

  subgraph Editor["BUSINESS CONTEXT EDITOR"]
    SkillList["Skills List
(per agent)"]
    SkillEditor["Skill Editor
(split pane:
metadata + markdown)"]
    ContextLib["Context Library
(org-level)"]
    BindingUI["Context Binding UI"]
    VersionUI["Version History"]
  end

  AgentSkills --> Parser
  OpenClaw --> Parser
  ClaudeCode --> Parser
  Clawith --> Parser
  Parser --> OrgSkill
  OrgSkill --> Versions

  AgentDef --> SkillBind
  SkillBind -->|"references"| OrgSkill
  AgentDef --> ContextBind

  SkillBind --> SysPrompt
  SysPrompt -->|"agent decides"| OnDemand
  OnDemand --> WSPath

  OrgSkill --> SkillList
  SkillList --> SkillEditor
  ContextBind --> BindingUI

  style Standards fill:#F8FAFC,stroke:#94a3b8,stroke-width:2px
  style Registry fill:#F5F3FF,stroke:#8b5cf6,stroke-width:2px
  style Binding fill:#FDF2F8,stroke:#ec4899,stroke-width:2px
  style Loading fill:#ECFDF5,stroke:#10b981,stroke-width:2px
  style Editor fill:#EEF2FF,stroke:#6366f1,stroke-width:2px

Component Index — Every Box Traced to a Spec

Surfaces

Employee App
Chat + Widgets, Space Assistant, Control Plane Kanban, Memory Panel, Review Inbox
Surface
enterprise-agentic-platform-design
Builder Workspace
Journey, Canvas, Inspector, Preview, Publish. Replaces old app-builder UX.
Surface
builder-convergence-design
Admin Console
Org settings, usage dashboard, provider keys, policy management
Surface
enterprise-agentic-platform-design
Published App Plane
Immutable PublishedRuntimeRecord, canary routing, end-user chat, version rollback
Surface
published-app-versioning-design

Session Kernel

/api/invoke
Unified public boundary. All channels converge. One invoke stack, no forks.
Contract
enterprise-agentic-platform-reconciled
SessionRecord
FSM: created→active↔paused→completed. Types: chat, app, work_item. Sticky version pinning.
Contract
session-lifecycle-design
InvocationRun
Single run within a session. Tracks token usage, tool calls, model selection.
Contract
enterprise-agentic-platform-design
Context Engine
assembleContextPrompt(): loads business context, space bindings, agent memory, run context
Runtime
enterprise-agentic-platform-design
Permission Pipeline
PolicyProfileRecord evaluated before every tool call. Tool allowlists per agent.
Runtime
enterprise-agentic-platform-reconciled

Agent Runtime

Agent Loop
Plan→Act→Observe→Emit→Verify. Extended with approval pause/resume.
Core
enterprise-agentic-platform-design
ProviderRouter
Multi-model: Claude (reasoning), Gemini (research), GPT, DeepSeek. Per-agent config.
Routing
pr-text-studio-design
invoke_agent
Sync sub-agent delegation. Depth-1 limit. Reuses AgentLoop.run(). 30s timeout.
Contract
sub-agent-communication-design
Agent Workspace
/data/workspaces/{orgId}/{agentId}/ with skills/, memory/, outputs/. 4 workspace tools.
Filesystem
agent-workspace-design
ApprovalRequest
Inline runtime approval. Risk tiers: low/medium/high/critical. 60-min timeout. SSE events.
Contract
approval-contract-design
Trigger Daemon
8 types: manual, scheduled, once, interval, on_message, webhook, event, poll. 60s heartbeat.
Runtime
trigger-system-design

Spaces & Knowledge

SpaceRecord
First-class domain. Catalog, workspace (AI Assistant + Knowledge + Settings tabs).
Domain
space-domain-foundation-design
SpaceKnowledgeItem
5 kinds: file, website, note, voice, youtube. Status: processing→ready→failed.
Domain
space-knowledge-intake-design
Hybrid Search
Vectorize (cosine 0.45) + D1 FTS5 (BM25 0.45) + recency (0.10). Fallback: lexical-only.
Search
knowledge-infrastructure-design
Space-Agent Integration
Read-only. AppConfig.boundSpaceIds. RAG query + list APIs. No bidirectional tracking.
Contract
space-agent-integration-contract
Upload Tiers
hardLimitBytes (safety) + tierLimitBytes (product). Free/Starter/Pro/Enterprise. Stripe mapping.
Billing
space-upload-tier-and-billing-design
Audio Ingestion
voice_note + audio file share pipeline. Separate transcript blob. Idempotent retry.
Pipeline
audio-voice-ingestion-design

Business Context & Skills

OrgSkillRecord
Superset SKILL.md frontmatter. Imports from 4 standards. Versioned. Org-wide.
Skill
standards-adoption-design
AgentSkillBinding
Lightweight reference from agent to org skill. Progressive disclosure.
Binding
standards-adoption-design
Context Editor UI
5 screens: Skills List, Skill Editor, Context Library, Binding UI, Version History.
UI
business-context-editor-design
7 Context Types
Writing Rules, Brand, Personas, Templates, SOPs, Domain Knowledge, Skill Playbooks
Context
enterprise-agentic-platform-design

Governance, Audit & Eval

3-Table Audit
PlatformAuditLog (system), AgentActivityLog (tool calls, fire-and-forget), RunEventLog (immutable per-run)
Audit
audit-event-taxonomy-design
Eval Loop
Run/version/agent-level scoring. Auto signals + human feedback. Configurable EvalRuleSet weights.
Eval
eval-loop-design
App Versioning
draft→active→canary→archived. Sticky sessions. Canary traffic %. Instant rollback.
Versioning
published-app-versioning-design
Security Controls
8 critical fixes: XSS sanitization, SSRF blocking, skill quarantine, CSRF, token budget enforcement
Security
security-audit
Decision Ledger
30+ locked decisions triaged: Lock Now / Default For Now / Defer. Canonical skill model confirmed.
Decisions
colleague-decision-ledger

Platform Services (R2)

Stripe Billing
Subscription + usage metering. StripeMeter for dedup/late events. 4 tiers.
R2
r2-revenue-ready-design
Auth0
JWT + RBAC + SSO. Self-service signup flow. Org context middleware.
R2
r2-revenue-ready-design
Houston Protection
3-layer: org budget gate, app rate limit, end-user abuse limiter
R2
r2-revenue-ready-design
End-User Identity
Authenticated (JWT header) + Anonymous (SHA-256 fingerprint). Memory: per-user vs per-session.
R2
platform-defaults
Blinkin Assistant
Default super-agent. Claude Sonnet 4.5. 50k tokens, 25 tool calls. Auto-provisioned per org.
Default
platform-defaults
Customer Lifecycle
Discovery→signup→first use→build agent→daily use→billing→cancellation→GDPR
Journey
customer-lifecycle
Operations
Health endpoints, SQLite backup cron (30-day retention), trigger heartbeat monitoring, workspace disk warnings
Ops
operations-playbook

The Core Thesis

Blinkin is not a product. Blinkin is a platform.

RegWatch Monitor, the Executive Editor, Podcast Studio — these are all Business Applications that run ON the Blinkin platform. Just as Salesforce is not "a CRM" but a platform on which Sales Cloud, Service Cloud, and custom apps run.

Every Organization Gets Its Own Computer.

Perplexity proved that when you combine precise search, multi-model orchestration, and agentic tool access, the AI IS the computer. Blinkin adapts this for enterprises: every org gets its own isolated, always-on Blinkin Computer — a secure sandbox with agents, business context, multi-model routing, and a complete audit trail.

Before (Blinkin 1.0)

An intelligence dashboard with AI features. One product, one use case, features bolted on. Every customer gets the same thing.

After (Blinkin 2.0)

An agentic-first platform where intelligence apps run. Customers build their own agents, their own apps, with their own business context. The platform is the product.

What Makes This Different

Agent Teams, Not Features
Every workflow is executed by a team of specialized agents (supervisor + workers), not by monolithic feature code. Agents can be swapped, upgraded, and composed independently.
Business Context Is the Moat
Without context, agents are generic. WITH your SOPs, brand voice, writing rules, personas, and domain knowledge, they become specialized team members. This is what makes switching costs real.
Skills, Not Rules Engines
Agent behavior is controlled via composable Skill files (SKILL.md), not complex rules engines. Skills are versioned, org-wide, and importable from 4 open standards (Agent Skills, OpenClaw, Claude Code, Clawith).
One Invoke Boundary
Employee chat, published apps, triggers, sub-agents — ALL channels converge on one endpoint: /api/invoke. No forks, no parallel stacks, no "but this surface works differently."
Multi-Model by Design
Not locked to one AI provider. Gemini for research (large context), Opus for reasoning, Haiku for speed, GPT where it excels. The right model for each subtask, configurable per agent.
Governance at Every Layer
Three governance levels: workflow (human-in-the-loop, approval gates), action (policy engine, tool allowlists), reliability (circuit breakers, SLOs). Plus a 3-table immutable audit trail.

The 4 Surfaces

Everything users see falls into exactly 4 surfaces, all sharing one kernel underneath.
1. Employee App
Where employees work daily. Chat with agents, browse Spaces (knowledge), monitor agent work on the Kanban board, review outputs in the Review Inbox. This is the "Bloomberg Terminal" experience.
Internal
2. Builder Workspace
Where creators build agents and apps. Journey → Canvas → Inspector → Preview → Publish. A unified builder replacing the old fragmented UX. Think Salesforce Setup.
Creator
3. Admin Console
Org settings, usage dashboards, provider API keys, policy management. The ops view for admins who manage billing, users, and security policies.
Admin
4. Published App Plane
End-user facing. Published apps run as immutable snapshots with canary routing, version rollback, and per-user identity. White-label capable. What customers' customers see.
End-User

The Critical Separation

Agent Configuration

Behavioral control — how the agent acts.
Contains: SOUL (persona), Skills, System Prompts, Memory.
Managed in: Agent profile / app configuration.
Accessed via: direct read from agent config store.
Example: format-blogpost.md, style-inspiring.md

Knowledge Spaces

Data retrieval — what the org knows.
Contains: Documents, PDFs, videos, audio, websites.
Managed in: Spaces sidebar.
Accessed via: RAG query (semantic + keyword search).
Example: Industry-Report.pdf, Brand-Guide.pdf

These must never be conflated. Skills are not knowledge items. Knowledge items are not skills. An agent's behavior (how to write a blog post) is a Skill. An agent's knowledge (industry reports to reference) lives in a Space.

Release Roadmap

Each release builds on the previous. Dependencies are strict — no skipping ahead.

R1

Kernel Bridge

Foundation — everything else depends on this
  • AgentInterface — versioned invoke contract, stable invocation boundary
  • SessionRecord — shared session envelope (FSM: created → active ↔ paused → completed)
  • InvocationRunRecord — execution record tracking what happened in a run
  • PublishedRuntimeRecord — immutable publish snapshot (published apps never read live mutable state)
  • /api/invoke — one unified invoke endpoint, all channels converge
↓
R1.5

Builder Convergence

Replace old app builder with unified builder UX on shared kernel
  • New builder shell replaces old AppBuilderPage
  • 5 surfaces: Journey, Canvas, Inspector, Preview, Publish
  • Hard constraints: no second builder source-of-truth, no second published runtime contract, no second invoke stack
  • Staged migration with feature flags, not big-bang cutover
  • New publish writes immutable PublishedRuntimeRecord (server-backed)
↓
R2

Revenue Ready

Make the platform commercially viable — billing, signup, protection
  • Stripe billing — subscription (fixed price) + usage-based overage metering
  • Self-service signup — Auth0 → Plan selection → Stripe Checkout → Org ready
  • Houston 3-layer protection — org budget gate, app rate limit, end-user abuse limiter
  • Admin dashboard — plan, usage, provider keys, published app limits
  • PostHog analytics — signup funnel, product events
  • Resend email — budget alerts, invite, reset, verify templates
  • End-user identity — authenticated (JWT) + anonymous (SHA-256 fingerprint)
  • Default super-agent — Blinkin Assistant auto-provisioned per org (Sonnet 4.5, 50k tokens)
  • Reuse: 60% from Zweistein (Stripe, Auth0, RBAC), StripeMeter patterns
↓
R2.5

First Agentic App + Builder Implementation

PR Text Studio (Use Case #1) proves the pattern for all future apps
  • PR Text Studio — 4-agent team (Supervisor + Briefing + Research + Writer)
  • Sub-agent communication — invoke_agent (sync, depth-1) + Kanban (async)
  • Progressive skill disclosure — index in prompt, full SKILL.md via workspace_read()
  • Agent workspace — scoped filesystem per agent (skills/, memory/, outputs/)
  • Approval contract — inline runtime approval with risk tiers
  • Trigger system — 8 types (cron, webhook, poll, event, etc.)
  • Business context editor — UI for managing skills, persona, context bindings
  • Session lifecycle — full FSM with pause/resume for approvals
  • Builder convergence implementation — new builder ships
  • Zweistein features: crawler backend, dashboard (recently used + favorites), voice (STT/TTS)
↓
R3

Scale & Intelligence

Direction only — not fully specced yet
  • Knowledge infrastructure — hybrid search (Cloudflare Vectorize + D1 FTS5)
  • Eval loop — automated quality scoring, canary comparison, optimization
  • Sandbox isolation — Firecracker microVM per org
  • External A2A — partner agents via A2A protocol (Linux Foundation standard)
  • Durable agent teams — Vercel Workflow as runtime engine
  • Circuit breakers & SLOs — reliability governance
  • External auth — end-user login for enterprise published apps
  • AI-generated UI (Controls) — agents generate React components from prompts
  • Marketplace — partner agents and skills marketplace

Spec Coverage

32 design specs exist in docs/superpowers/specs/. Every architectural decision, contract, and data model is documented and traceable. The specs cover: platform kernel, builder, revenue/billing, spaces/knowledge, agent workspace, sub-agent communication, triggers, approvals, sessions, audit, eval, versioning, security, standards adoption, business context, operations, defaults, customer lifecycle, and the first agentic app (PR Text Studio).

32 Locked Decisions

These are final. Not up for debate. Each was made deliberately during the design phase.

Platform Level

R2 Revenue Level

PR Text Studio (Use Case #1)

Builder Level

Key Technical Standards

A2A Protocol
Linux Foundation standard for agent-to-agent communication. Used internally and for partner agents.
Agent Skills Standard
Anthropic standard (agentskills.io) for agent capabilities. SKILL.md with YAML frontmatter as the base format.
OrgSkillRecord
Superset format. Normalizes imports from Agent Skills, OpenClaw, Claude Code, and Clawith/ClawHub.
CLI/API First
Tools accessed via CLI (0 token overhead) or REST API. MCP optional for enterprise audit. No protocol lock-in.

What to Build First

Strict dependency chain. Each item unblocks the next. No parallelizing across priorities.

P1

Merge R1 Kernel Bridge

Everything else depends on the unified invoke path, session model, and published runtime. 5 contracts: AgentInterface, SessionRecord, InvocationRunRecord, PublishedRuntimeRecord, /api/invoke. TDD approach. Plan exists: plans/2026-03-19-r1-kernel-bridge.md

Blocks: everything
P2

Space Domain Foundation

Already in progress by a colleague. The integration contract defines exactly what the agent side needs. SpaceRecord, SpaceKnowledgeItem, 5 intake channels, RAG query API. First-class knowledge management.

Blocks: knowledge search, PR Text Studio research agent
P3

Sub-Agent Communication

Decide and implement: invoke_agent (sync, depth-1, 30s timeout) for fast tasks + Kanban path for long-running. This blocks PR Text Studio and ALL multi-agent apps. The spec is ready.

Blocks: PR Text Studio, all multi-agent workflows
P4

R2 Revenue Ready

Port Stripe billing from Zweistein, build self-service signup flow, wire usage metering, implement Houston 3-layer protection. PostHog analytics, Resend email. Admin dashboard. Reuses 60% from existing code. ~1 week build.

Depends on: R1 Kernel Bridge merged
P5

PR Text Studio (First Agentic App)

The first real business application on the platform. Establishes the reusable pattern for ALL future agentic apps: how agent teams compose, how skills load, how agents communicate, how memory persists, how work items track. 4-agent team, progressive skill disclosure, multi-model routing, workspace filesystem.

Depends on: sub-agent communication, spaces, R1 kernel

P0 Blockers (Specs Ready, Need Implementation)

These 4 capabilities were identified as go-live blockers in the gap analysis. All have been fully specced. They need to be built as part of R2/R2.5.
Approval Contract
No inline runtime approval mechanism exists yet. Spec defines ApprovalRequest with risk tiers, 60-min timeout, SSE events.
P0 Blocker
approval-contract-design
Session Lifecycle
No start/pause/resume/fork semantics. Spec defines full FSM with 3 session types and Vercel Workflow as durable engine.
P0 Blocker
session-lifecycle-design
Business Context Editor
No UI for managing SOPs, brand, writing rules. Spec defines 5 screens: Skills List, Editor, Context Library, Binding UI, Versions.
P0 Blocker
business-context-editor-design
Sub-Agent Communication
No invoke_agent or sessions_send. Spec defines hybrid sync/async with depth-1 limit and resume support.
P0 Blocker
sub-agent-communication-design

What’s Well-Covered (No Gaps)

Agent definitions
Schema, mapping, presets — all implemented + tested
Solid
Widget rendering
17 components, WidgetSpec, action handler — production-ready
Solid
Control plane
Kanban board, work items, operator actions, scheduler — implemented
Solid
Policy foundation
PolicyProfileRecord, tool allowlists, audit log contracts
Solid
Billing design
R2 spec complete. Stripe + StripeMeter + Houston protection fully designed.
Solid
Space domain
7 specs covering foundation, intake, search, audio, tiers, agent integration
Solid
Memory concept
5 model-agnostic tools + Claude enhancement + 3-scope persistence
Solid
Security audit
14-spec + OWASP review complete. 8 critical, 10 high findings documented.
Solid