Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(diagrams): add source-backed architecture suite
trohitg0fa5287aef10
diff --git a/docs-internal/diagram-generation/README.md b/docs-internal/diagram-generation/README.mdnew file mode 100644index 00000000..14fb9422--- /dev/null+++ b/docs-internal/diagram-generation/README.md@@ -0,0 +1,34 @@+# OpenCompany diagram generation++This directory contains the source-backed specification, prompts, AI-generated raster drafts, and validation evidence for the v2 diagram suite. The editable, authoritative results live in `docs/diagrams/v2/`.++## Diagram IDs++| ID | Diagram |+|---|---|+| `01-system-context` | System context |+| `02-runtime-trust-topology` | Runtime and trust topology |+| `03-workflow-execution-routing` | Workflow execution routing |+| `04-durable-deployment-events` | Durable deployment and events |+| `05-plugin-agent-team-composition` | Plugin, model, agent, and team composition |+| `06-persistence-secret-plane` | Persistence and secret plane |+| `07-workspace-anatomy` | Workspace anatomy |+| `08-node-configuration-anatomy` | Node Configuration anatomy |+| `09-credentials-architecture` | Credentials architecture |+| `10-team-operations` | Team operations |+| `11-agent-context-memory` | Agent Context versus Memory |+| `12-master-skill-editor` | Master Skill Editor |+| `13-workspace-files` | Workspace files |+| `14-runtime-observability-dock` | Runtime observability dock |++## Artifact contract++- `specs/*.json` is the source of truth for components, directed relationships, exact labels, evidence paths, layout, and prompt additions.+- `prompt-pack.md` is generated from those specs and contains one dark generation prompt plus light-theme edit and repair prompts for every diagram.+- `drafts/{dark,light}/*.png` contains project-bound GPT Image drafts. They are references, not authoritative architecture documentation.+- `manifest.json` records the frozen source snapshot and per-diagram validation state.+- `validation-report.json` is generated by the validator.+- `visual-review.md` records the full-resolution and README-width inspection matrix.+- `docs/diagrams/v2/{dark,light}/*.svg` contains the editable authoritative diagrams. Existing public diagrams remain unchanged.++All diagrams use a `1920 × 1080` viewBox. Dark and light variants share one geometry specification.diff --git a/docs-internal/diagram-generation/drafts/dark/01-system-context.png b/docs-internal/diagram-generation/drafts/dark/01-system-context.pngnew file mode 100644index 00000000..77ff0f52Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/01-system-context.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/02-runtime-trust-topology.png b/docs-internal/diagram-generation/drafts/dark/02-runtime-trust-topology.pngnew file mode 100644index 00000000..49917614Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/02-runtime-trust-topology.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/03-workflow-execution-routing.png b/docs-internal/diagram-generation/drafts/dark/03-workflow-execution-routing.pngnew file mode 100644index 00000000..73afe4e8Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/03-workflow-execution-routing.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/04-durable-deployment-events.png b/docs-internal/diagram-generation/drafts/dark/04-durable-deployment-events.pngnew file mode 100644index 00000000..573fda7fBinary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/04-durable-deployment-events.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/05-plugin-agent-team-composition.png b/docs-internal/diagram-generation/drafts/dark/05-plugin-agent-team-composition.pngnew file mode 100644index 00000000..06bba60cBinary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/05-plugin-agent-team-composition.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/06-persistence-secret-plane.png b/docs-internal/diagram-generation/drafts/dark/06-persistence-secret-plane.pngnew file mode 100644index 00000000..5f10c03cBinary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/06-persistence-secret-plane.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/07-workspace-anatomy.png b/docs-internal/diagram-generation/drafts/dark/07-workspace-anatomy.pngnew file mode 100644index 00000000..2bf0f9b5Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/07-workspace-anatomy.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/08-node-configuration-anatomy.png b/docs-internal/diagram-generation/drafts/dark/08-node-configuration-anatomy.pngnew file mode 100644index 00000000..39624b32Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/08-node-configuration-anatomy.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/09-credentials-architecture.png b/docs-internal/diagram-generation/drafts/dark/09-credentials-architecture.pngnew file mode 100644index 00000000..26e05c2fBinary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/09-credentials-architecture.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/10-team-operations.png b/docs-internal/diagram-generation/drafts/dark/10-team-operations.pngnew file mode 100644index 00000000..388ff646Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/10-team-operations.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/11-agent-context-memory.png b/docs-internal/diagram-generation/drafts/dark/11-agent-context-memory.pngnew file mode 100644index 00000000..040eafddBinary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/11-agent-context-memory.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/12-master-skill-editor.png b/docs-internal/diagram-generation/drafts/dark/12-master-skill-editor.pngnew file mode 100644index 00000000..34894b15Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/12-master-skill-editor.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/13-workspace-files.png b/docs-internal/diagram-generation/drafts/dark/13-workspace-files.pngnew file mode 100644index 00000000..58312182Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/13-workspace-files.png differdiff --git a/docs-internal/diagram-generation/drafts/dark/14-runtime-observability-dock.png b/docs-internal/diagram-generation/drafts/dark/14-runtime-observability-dock.pngnew file mode 100644index 00000000..ebb481b2Binary files /dev/null and b/docs-internal/diagram-generation/drafts/dark/14-runtime-observability-dock.png differdiff --git a/docs-internal/diagram-generation/drafts/light/01-system-context.png b/docs-internal/diagram-generation/drafts/light/01-system-context.pngnew file mode 100644index 00000000..5ee84e43Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/01-system-context.png differdiff --git a/docs-internal/diagram-generation/drafts/light/02-runtime-trust-topology.png b/docs-internal/diagram-generation/drafts/light/02-runtime-trust-topology.pngnew file mode 100644index 00000000..c0daf6deBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/02-runtime-trust-topology.png differdiff --git a/docs-internal/diagram-generation/drafts/light/03-workflow-execution-routing.png b/docs-internal/diagram-generation/drafts/light/03-workflow-execution-routing.pngnew file mode 100644index 00000000..f12acaeeBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/03-workflow-execution-routing.png differdiff --git a/docs-internal/diagram-generation/drafts/light/04-durable-deployment-events.png b/docs-internal/diagram-generation/drafts/light/04-durable-deployment-events.pngnew file mode 100644index 00000000..6d003be6Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/04-durable-deployment-events.png differdiff --git a/docs-internal/diagram-generation/drafts/light/05-plugin-agent-team-composition.png b/docs-internal/diagram-generation/drafts/light/05-plugin-agent-team-composition.pngnew file mode 100644index 00000000..3ef250ceBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/05-plugin-agent-team-composition.png differdiff --git a/docs-internal/diagram-generation/drafts/light/06-persistence-secret-plane.png b/docs-internal/diagram-generation/drafts/light/06-persistence-secret-plane.pngnew file mode 100644index 00000000..e02f5bcdBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/06-persistence-secret-plane.png differdiff --git a/docs-internal/diagram-generation/drafts/light/07-workspace-anatomy.png b/docs-internal/diagram-generation/drafts/light/07-workspace-anatomy.pngnew file mode 100644index 00000000..4e3e2e22Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/07-workspace-anatomy.png differdiff --git a/docs-internal/diagram-generation/drafts/light/08-node-configuration-anatomy.png b/docs-internal/diagram-generation/drafts/light/08-node-configuration-anatomy.pngnew file mode 100644index 00000000..10628ec7Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/08-node-configuration-anatomy.png differdiff --git a/docs-internal/diagram-generation/drafts/light/09-credentials-architecture.png b/docs-internal/diagram-generation/drafts/light/09-credentials-architecture.pngnew file mode 100644index 00000000..27aa6906Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/09-credentials-architecture.png differdiff --git a/docs-internal/diagram-generation/drafts/light/10-team-operations.png b/docs-internal/diagram-generation/drafts/light/10-team-operations.pngnew file mode 100644index 00000000..954b91fbBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/10-team-operations.png differdiff --git a/docs-internal/diagram-generation/drafts/light/11-agent-context-memory.png b/docs-internal/diagram-generation/drafts/light/11-agent-context-memory.pngnew file mode 100644index 00000000..1e710d11Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/11-agent-context-memory.png differdiff --git a/docs-internal/diagram-generation/drafts/light/12-master-skill-editor.png b/docs-internal/diagram-generation/drafts/light/12-master-skill-editor.pngnew file mode 100644index 00000000..3c65f9daBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/12-master-skill-editor.png differdiff --git a/docs-internal/diagram-generation/drafts/light/13-workspace-files.png b/docs-internal/diagram-generation/drafts/light/13-workspace-files.pngnew file mode 100644index 00000000..e9a80cbdBinary files /dev/null and b/docs-internal/diagram-generation/drafts/light/13-workspace-files.png differdiff --git a/docs-internal/diagram-generation/drafts/light/14-runtime-observability-dock.png b/docs-internal/diagram-generation/drafts/light/14-runtime-observability-dock.pngnew file mode 100644index 00000000..ce297595Binary files /dev/null and b/docs-internal/diagram-generation/drafts/light/14-runtime-observability-dock.png differdiff --git a/docs-internal/diagram-generation/manifest.json b/docs-internal/diagram-generation/manifest.jsonnew file mode 100644index 00000000..5d72385f--- /dev/null+++ b/docs-internal/diagram-generation/manifest.json@@ -0,0 +1,1178 @@+{+ "schemaVersion": 1,+ "sourceSnapshot": {+ "commit": "5f7522250eae7b0d02ddfd8ee3740fdf5be4c25e",+ "description": "See source-snapshot.md"+ },+ "diagramCount": 14,+ "themes": [+ "dark",+ "light"+ ],+ "visualReview": {+ "status": "passed",+ "evidence": "docs-internal/diagram-generation/visual-review.md",+ "renderSizes": [+ "1920x1080",+ "960x540"+ ],+ "themes": [+ "dark",+ "light"+ ]+ },+ "diagrams": [+ {+ "id": "01-system-context",+ "title": "OpenCompany System Context",+ "diagramType": "C4 system context",+ "sourceReview": "reviewed",+ "components": [+ "workflow-authors",+ "workflow-operators",+ "opencompany",+ "llm-providers",+ "productivity-services",+ "messaging-channels",+ "connected-devices",+ "developer-services",+ "search-vector-stores"+ ],+ "relationships": [+ "r-authors-design",+ "r-operators-control",+ "r-opencompany-llm",+ "r-opencompany-productivity",+ "r-opencompany-messaging",+ "r-opencompany-devices",+ "r-opencompany-developer",+ "r-opencompany-search"+ ],+ "sourceRefs": [+ {+ "path": "README.md",+ "reason": "Product scope, workflow-builder positioning, supported integrations, and user-facing capabilities."+ },+ {+ "path": "server/nodes/groups.py",+ "reason": "Canonical node families that establish the external capability categories."+ },+ {+ "path": "server/config/credential_providers.json",+ "reason": "Configured provider catalogue for model, productivity, messaging, search, and developer integrations."+ },+ {+ "path": "server/main.py",+ "reason": "Authoritative application boundary and exposed HTTP, WebSocket, webhook, and MCP surfaces."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/01-system-context.png",+ "svg": "docs/diagrams/v2/dark/01-system-context.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/01-system-context.png",+ "svg": "docs/diagrams/v2/light/01-system-context.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "02-runtime-trust-topology",+ "title": "Runtime and Trust Topology",+ "diagramType": "C4 container and deployment hybrid",+ "sourceReview": "reviewed",+ "components": [+ "browser-spa",+ "opencompany-cli",+ "webhook-senders",+ "vite-dev",+ "fastapi-app",+ "rest-surface",+ "status-socket",+ "internal-socket",+ "mcp-surface",+ "webhook-ingress",+ "production-spa",+ "temporal-runtime",+ "nodejs-sidecar",+ "whatsapp-sidecar"+ ],+ "relationships": [+ "r-browser-vite",+ "r-vite-fastapi",+ "r-cli-fastapi",+ "r-browser-rest",+ "r-browser-status",+ "r-cli-mcp",+ "r-webhook-ingress",+ "r-surfaces-app",+ "r-status-app",+ "r-temporal-internal",+ "r-fastapi-temporal",+ "r-fastapi-nodejs",+ "r-fastapi-whatsapp",+ "r-fastapi-spa"+ ],+ "sourceRefs": [+ {+ "path": ".env.template",+ "reason": "Canonical service port block: app 5678, development backend 5679, Temporal UI/gRPC 5680/5681, Node.js 5682, WhatsApp 5683."+ },+ {+ "path": "client/vite.config.js",+ "reason": "Same-origin development topology and proxy prefixes from Vite 5678 to Uvicorn 5679."+ },+ {+ "path": "server/main.py",+ "reason": "FastAPI lifespan, routers, webhook route, MCP mount, lazy service startup, and production SPA serving."+ },+ {+ "path": "server/middleware/auth.py",+ "reason": "Authentication exclusions and separate protection for public webhooks, internal WebSocket, and MCP."+ },+ {+ "path": "server/routers/websocket.py",+ "reason": "Canonical /ws/status and /ws/internal endpoints and authenticated status-socket identity."+ },+ {+ "path": "server/services/authz/ws_surface.py",+ "reason": "Restricted /ws/internal handler allowlist and internal-only payload identity rule."+ },+ {+ "path": "server/services/cli_agent/mcp_server.py",+ "reason": "Per-batch bearer authentication and MCP-over-HTTP server surface."+ },+ {+ "path": "server/services/temporal/lifecycle.py",+ "reason": "Temporal client and worker lifecycle wiring."+ },+ {+ "path": "server/nodes/code/_runtime.py",+ "reason": "Lazy Node.js executor runtime configuration."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/02-runtime-trust-topology.png",+ "svg": "docs/diagrams/v2/dark/02-runtime-trust-topology.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/02-runtime-trust-topology.png",+ "svg": "docs/diagrams/v2/light/02-runtime-trust-topology.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "03-workflow-execution-routing",+ "title": "Workflow Execution Routing",+ "diagramType": "C4 dynamic flow",+ "sourceReview": "reviewed",+ "components": [+ "single-node-request",+ "whole-workflow-request",+ "routing-decision",+ "temporal-branch",+ "redis-parallel-branch",+ "sequential-branch",+ "parameter-preparation",+ "template-resolution",+ "plugin-dispatch",+ "validated-result",+ "output-store",+ "status-broadcast"+ ],+ "relationships": [+ "r-single-pipeline",+ "r-whole-routing",+ "r-routing-temporal",+ "r-routing-parallel",+ "r-routing-sequential",+ "r-temporal-node",+ "r-parallel-node",+ "r-sequential-node",+ "r-prepare-resolve",+ "r-resolve-dispatch",+ "r-dispatch-result",+ "r-result-store",+ "r-store-broadcast"+ ],+ "sourceRefs": [+ {+ "path": "server/services/workflow.py",+ "reason": "Authoritative single-node adapter and Temporal, Redis-parallel, sequential routing decision."+ },+ {+ "path": "server/services/node_executor.py",+ "reason": "Canonical parameter preparation, template resolution, plugin dispatch, and output storage pipeline."+ },+ {+ "path": "server/services/execution/executor.py",+ "reason": "In-process graph orchestration, dependency scheduling, retries, and node callback contract."+ },+ {+ "path": "server/services/temporal/executor.py",+ "reason": "Temporal graph execution adapter and durable workflow start path."+ },+ {+ "path": "server/services/temporal/workflow.py",+ "reason": "Durable graph workflow and activity routing."+ },+ {+ "path": "server/services/status_broadcaster.py",+ "reason": "Per-workflow execution and node status broadcasts."+ },+ {+ "path": "server/routers/workflow.py",+ "reason": "Internal Temporal node-execution endpoint still present in the current route surface."+ },+ {+ "path": "server/routers/websocket.py",+ "reason": "Interactive execute_node and execute_ai_node entry points."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/03-workflow-execution-routing.png",+ "svg": "docs/diagrams/v2/dark/03-workflow-execution-routing.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/03-workflow-execution-routing.png",+ "svg": "docs/diagrams/v2/light/03-workflow-execution-routing.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "04-durable-deployment-events",+ "title": "Durable Deployment and Events",+ "diagramType": "C4 dynamic and event flow",+ "sourceReview": "reviewed",+ "components": [+ "lifecycle-controls",+ "workflow-control-service",+ "generation-snapshot",+ "controller",+ "local-runtime-state",+ "push-trigger",+ "poll-trigger",+ "cron-trigger",+ "cloudevent",+ "event-dispatch",+ "trigger-registration",+ "child-graph-workflow",+ "cron-action-workflow",+ "execution-status"+ ],+ "relationships": [+ "r-controls-service",+ "r-service-snapshot",+ "r-snapshot-controller",+ "r-controls-controller",+ "r-service-local-state",+ "r-push-event",+ "r-event-dispatch",+ "r-dispatch-controller",+ "r-poll-controller",+ "r-cron-action",+ "r-registration-controller",+ "r-controller-child",+ "r-cron-child",+ "r-child-status",+ "r-cron-status"+ ],+ "sourceRefs": [+ {+ "path": "server/services/deployment/handlers.py",+ "reason": "Start, pause, resume, reset handlers, controller start/rebuild, signals, schedules, trigger state, and cleanup."+ },+ {+ "path": "server/services/deployment/control.py",+ "reason": "Revision-guarded generation allocation and sanitized immutable graph_snapshot rows."+ },+ {+ "path": "server/services/deployment/triggers.py",+ "reason": "Trigger preparation and push/poll registration contracts."+ },+ {+ "path": "server/services/temporal/workflow_control_workflow.py",+ "reason": "Long-lived controller, pause/resume/reset, trigger registration, event queue, poll loops, child spawning, and continue-as-new."+ },+ {+ "path": "server/services/events/envelope.py",+ "reason": "CloudEvents v1.0 WorkflowEvent envelope."+ },+ {+ "path": "server/services/events/dispatch.py",+ "reason": "Event-to-controller dispatch using Temporal visibility and on_event signals."+ },+ {+ "path": "server/services/temporal/schedules.py",+ "reason": "Durable cron schedule creation, pause/unpause, ownership and cleanup."+ },+ {+ "path": "server/nodes/scheduler/cron_scheduler/_workflow.py",+ "reason": "Cron action workflow that launches the snapshotted graph run."+ },+ {+ "path": "server/services/workflow.py",+ "reason": "Local deployment admission and legacy fallback state."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/04-durable-deployment-events.png",+ "svg": "docs/diagrams/v2/dark/04-durable-deployment-events.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/04-durable-deployment-events.png",+ "svg": "docs/diagrams/v2/light/04-durable-deployment-events.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "05-plugin-agent-team-composition",+ "title": "Plugin \u2192 Agent \u2192 Team Composition",+ "diagramType": "layered composition",+ "sourceReview": "reviewed",+ "components": [+ "base-node",+ "model-plugins",+ "chat-unifier",+ "agent-plugins",+ "context-node",+ "skill-nodes",+ "tool-nodes",+ "prepared-agent-call",+ "team-lead",+ "teammates",+ "task-manager",+ "durable-team"+ ],+ "relationships": [+ "r-base-model",+ "r-base-agent",+ "r-model-unifier",+ "r-agent-prepare",+ "r-context-prepare",+ "r-skills-prepare",+ "r-tools-prepare",+ "r-prepare-unifier",+ "r-teammates-lead",+ "r-lead-runtime",+ "r-lead-manager",+ "r-teammates-state",+ "r-manager-state"+ ],+ "sourceRefs": [+ {+ "path": "server/services/plugin/base.py",+ "reason": "Authoritative BaseNode contract, subclass registration, component kinds, Params/Output schemas, handles, and uiHints."+ },+ {+ "path": "server/nodes/model/_base.py",+ "reason": "ChatModelBase contract and standalone output-model node behavior."+ },+ {+ "path": "server/nodes/agent/_specialized.py",+ "reason": "Agent Params select provider and model and specialized agents share the agent execution surface."+ },+ {+ "path": "server/nodes/agent/_handles.py",+ "reason": "Canonical agent and team-lead handle topology for context, skills, tools, tasks, and teammates."+ },+ {+ "path": "server/services/plugin/edge_walker.py",+ "reason": "Connection discovery, intrinsic Task Manager binding, teammate descriptors, and delegation-tool construction."+ },+ {+ "path": "server/services/llm/unifier.py",+ "reason": "Shared provider registry and native-SDK LLM facade used by model and agent execution."+ },+ {+ "path": "server/services/agent_team.py",+ "reason": "Execution-scoped durable team creation and task/member lifecycle service."+ },+ {+ "path": "server/models/database.py",+ "reason": "Persistent AgentTeam, TeamMember, TeamTask, TeamTaskAttempt, message, and concurrency records."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/05-plugin-agent-team-composition.png",+ "svg": "docs/diagrams/v2/dark/05-plugin-agent-team-composition.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/05-plugin-agent-team-composition.png",+ "svg": "docs/diagrams/v2/light/05-plugin-agent-team-composition.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "06-persistence-secret-plane",+ "title": "Persistence & Secret Plane",+ "diagramType": "data and trust boundary",+ "sourceReview": "reviewed",+ "components": [+ "runtime-services",+ "database-service",+ "workflow-db",+ "credential-callers",+ "auth-service",+ "credential-caches",+ "credentials-database",+ "encryption-password",+ "encryption-service",+ "credentials-db"+ ],+ "relationships": [+ "r-runtime-database",+ "r-database-workflow",+ "r-plugin-auth",+ "r-auth-cache",+ "r-auth-credentials",+ "r-key-encryption",+ "r-credentials-encryption",+ "r-credentials-store"+ ],+ "sourceRefs": [+ {+ "path": "server/core/container.py",+ "reason": "Dependency wiring for Database, CredentialsDatabase, EncryptionService, CacheService, and AuthService."+ },+ {+ "path": "server/main.py",+ "reason": "Startup ordering: initialize credentials.db, load/create salt, then initialize encryption with the server-scoped key."+ },+ {+ "path": "server/core/database.py",+ "reason": "Authoritative async SQLModel service for workflow.db persistence."+ },+ {+ "path": "server/models/database.py",+ "reason": "Operational tables for workflows, node parameters/outputs, executions, context support, teams, tasks, and settings."+ },+ {+ "path": "server/services/auth.py",+ "reason": "Single credential access surface and the distinct API-key and OAuth display caches; refresh tokens bypass the process cache."+ },+ {+ "path": "server/core/credentials_database.py",+ "reason": "Separate encrypted SQLite schema with metadata, EncryptedAPIKey, and EncryptedOAuthToken tables."+ },+ {+ "path": "server/core/encryption.py",+ "reason": "Fernet field encryption and PBKDF2-SHA256 key derivation at 600,000 iterations."+ },+ {+ "path": "server/services/plugin/credential.py",+ "reason": "Plugin Credential.resolve path that obtains API keys or OAuth tokens through AuthService."+ },+ {+ "path": "server/core/config.py",+ "reason": "DATA_DIR-rooted workflow/credential database paths and API_KEY_ENCRYPTION_KEY configuration."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/06-persistence-secret-plane.png",+ "svg": "docs/diagrams/v2/dark/06-persistence-secret-plane.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/06-persistence-secret-plane.png",+ "svg": "docs/diagrams/v2/light/06-persistence-secret-plane.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "07-workspace-anatomy",+ "title": "Workspace Anatomy",+ "diagramType": "filesystem and consumer topology",+ "sourceReview": "reviewed",+ "components": [+ "workflow-record",+ "workspace-locator",+ "workspace-base",+ "workflow-workspace",+ "workspace-files",+ "workspace-skills",+ "cli-worktrees",+ "workspace-routes",+ "filesystem-media",+ "cli-agent-session"+ ],+ "relationships": [+ "r-workflow-locator",+ "r-locator-base",+ "r-base-workspace",+ "r-workspace-files",+ "r-workspace-skills",+ "r-workspace-worktrees",+ "r-routes-resolve",+ "r-filesystem-files",+ "r-skills-cli",+ "r-workspace-cli"+ ],+ "sourceRefs": [+ {+ "path": "server/core/paths.py",+ "reason": "Canonical DATA_DIR, workspaces_dir, workspace_dir, and shipped example-workflow path rules."+ },+ {+ "path": "server/services/workspace_locator.py",+ "reason": "Single immutable workflow-id to mutable slug translation and safe default-workspace policy."+ },+ {+ "path": "server/services/workflow.py",+ "reason": "Workflow service creation and injection of the resolved workspace directory into execution context."+ },+ {+ "path": "server/services/workflow_storage/handlers.py",+ "reason": "Workflow rename path that moves a slug-keyed workspace directory."+ },+ {+ "path": "server/routers/workspace.py",+ "reason": "Workspace file-serving and bounded upload routes using immutable workflow IDs and contained relative paths."+ },+ {+ "path": "server/nodes/filesystem/_backend.py",+ "reason": "WorkspaceBackend and resolve_within path normalization, symlink/junction containment, and atomic write boundary."+ },+ {+ "path": "server/services/media/workspace.py",+ "reason": "Media references and reads/writes rooted in the executor-injected workspace."+ },+ {+ "path": "server/nodes/agent/claude_code_agent/_skills.py",+ "reason": "Per-workflow .claude/skills materialization with support-file preservation and diff updates."+ },+ {+ "path": "server/services/cli_agent/session.py",+ "reason": "Per-node CLI worktree placement and workspace --add-dir behavior."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/07-workspace-anatomy.png",+ "svg": "docs/diagrams/v2/dark/07-workspace-anatomy.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/07-workspace-anatomy.png",+ "svg": "docs/diagrams/v2/light/07-workspace-anatomy.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "08-node-configuration-anatomy",+ "title": "Node Configuration Anatomy",+ "diagramType": "annotated panel flow",+ "sourceReview": "reviewed",+ "components": [+ "node-identity",+ "save-action",+ "run-action",+ "cancel-action",+ "close-action",+ "input-column",+ "parameters-column",+ "output-column",+ "node-spec",+ "parameter-state",+ "execution-service",+ "websocket-database"+ ],+ "relationships": [+ "r-spec-identity",+ "r-spec-parameters",+ "r-input-parameters",+ "r-parameters-draft",+ "r-save-draft",+ "r-run-execution",+ "r-execution-output",+ "r-websocket-output",+ "r-cancel-websocket",+ "r-draft-database"+ ],+ "sourceRefs": [+ {+ "path": "client/src/ParameterPanel.tsx",+ "reason": "Modal shell, selected-node identity, Run/Save/Cancel-or-Stop actions, canvas-lock gating, and per-node execution reducer."+ },+ {+ "path": "client/src/components/parameterPanel/ParameterPanelLayout.tsx",+ "reason": "Authoritative three-column composition and 0.7 / 1.6 / 0.7 flex proportions."+ },+ {+ "path": "client/src/components/parameterPanel/InputSection.tsx",+ "reason": "Connected upstream output/schema discovery, inherited config-node inputs, recursive variable rendering, and drag source behavior."+ },+ {+ "path": "client/src/components/parameterPanel/MiddleSection.tsx",+ "reason": "Schema parameter rendering and uiHints-selected specialized panels, Connected Skills, Token Usage, and Console sections."+ },+ {+ "path": "client/src/components/parameterPanel/OutputSection.tsx",+ "reason": "Local execution plus WebSocket status/output merge and execution_id deduplication."+ },+ {+ "path": "client/src/hooks/useParameterPanel.ts",+ "reason": "Defaults + saved-parameters edit buffer, dirty comparison, save, cancel/revert, and selected NodeSpec resolution."+ },+ {+ "path": "client/src/hooks/useNodeParamsQuery.ts",+ "reason": "TanStack Query get/save node-parameter contract and optimistic versioned cache update."+ },+ {+ "path": "client/src/services/executionService.ts",+ "reason": "Save-aware WebSocket node execution and normalized ExecutionResult contract."+ },+ {+ "path": "server/routers/websocket.py",+ "reason": "get_node_parameters, save_node_parameters, output/status, and event-wait cancellation request handlers."+ },+ {+ "path": "server/core/database.py",+ "reason": "Persistent node_parameters and node_outputs backing the panel's live and saved data."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/08-node-configuration-anatomy.png",+ "svg": "docs/diagrams/v2/dark/08-node-configuration-anatomy.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/08-node-configuration-anatomy.png",+ "svg": "docs/diagrams/v2/light/08-node-configuration-anatomy.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "09-credentials-architecture",+ "title": "Credentials Architecture",+ "diagramType": "layered-security-data-flow",+ "sourceReview": "reviewed",+ "components": [+ "credentials-modal",+ "client-state",+ "ws-handlers",+ "credential-registries",+ "status-broadcaster",+ "auth-service",+ "encryption-service",+ "credentials-db"+ ],+ "relationships": [+ "modal-uses-client-state",+ "client-calls-handlers",+ "handlers-dispatch-registry",+ "handlers-use-auth-service",+ "registry-stores-valid-result",+ "registry-publishes-status",+ "auth-publishes-mutation",+ "auth-canonical-crud",+ "db-uses-encryption",+ "broadcast-invalidates-client"+ ],+ "sourceRefs": [+ {+ "path": "client/src/components/credentials/CredentialsModal.tsx",+ "reason": "Defines the thin modal shell, server-owned catalogue consumption, searchable palette, and lazy panel dispatch."+ },+ {+ "path": "client/src/components/credentials/useCredentialPanel.ts",+ "reason": "Defines per-provider TanStack Query state and credential RPC actions without persisting plaintext in the UI store."+ },+ {+ "path": "server/services/credentials/handlers.py",+ "reason": "Implements registered validate, get, save, and delete WebSocket handlers and their mutation broadcasts."+ },+ {+ "path": "server/services/plugin/credential.py",+ "reason": "Defines declarative credential classes, provider-specific probes, runtime resolution, and validation dispatch."+ },+ {+ "path": "server/services/auth.py",+ "reason": "Defines the sole credential access service, separate API-key and OAuth caches, catalogue invalidation, and refresh-token non-caching rule."+ },+ {+ "path": "server/core/credentials_database.py",+ "reason": "Defines the canonical encrypted SQLite records, two-table storage split, and calls to EncryptionService."+ },+ {+ "path": "server/core/encryption.py",+ "reason": "Defines PBKDF2-SHA256 key derivation and the process-held Fernet encrypt/decrypt boundary."+ },+ {+ "path": "server/services/status_broadcaster.py",+ "reason": "Defines api_key_status and credential_catalogue_updated broadcasts consumed by connected clients."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/09-credentials-architecture.png",+ "svg": "docs/diagrams/v2/dark/09-credentials-architecture.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/09-credentials-architecture.png",+ "svg": "docs/diagrams/v2/light/09-credentials-architecture.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "10-team-operations",+ "title": "Team Operations",+ "diagramType": "state-machine-and-control-surfaces",+ "sourceReview": "reviewed",+ "components": [+ "team-lead",+ "task-manager",+ "agent-team-service",+ "human-views",+ "blocked",+ "queued",+ "running",+ "submitted",+ "accepted",+ "failed",+ "cancelled",+ "team-completed"+ ],+ "relationships": [+ "lead-calls-task-manager",+ "task-manager-uses-service",+ "human-manages-service",+ "service-updates-human",+ "service-assigns-ready",+ "dependencies-unblock",+ "worker-claims",+ "worker-submits",+ "lead-accepts",+ "worker-fails",+ "failed-requeues",+ "submitted-requeues",+ "cancelled-requeues",+ "accepted-finishes-team",+ "cancelled-is-resolved"+ ],+ "sourceRefs": [+ {+ "path": "server/nodes/tool/task_manager/__init__.py",+ "reason": "Defines the intrinsic model-facing operations, connected-teammate resolution, and trusted execution scope."+ },+ {+ "path": "server/services/agent_team.py",+ "reason": "Defines durable assignment, authorized mutation transitions, submission versus acceptance semantics, and finish-team gating."+ },+ {+ "path": "server/services/agent_teams/handlers.py",+ "reason": "Defines human WebSocket reads and revision-checked task management operations."+ },+ {+ "path": "server/services/temporal/agent_workflow.py",+ "reason": "Implements detached delegated task execution, concurrency permits, child completion, and terminal cleanup."+ },+ {+ "path": "client/src/components/parameterPanel/TaskManagerPanel.tsx",+ "reason": "Defines the operational task UI, status-specific actions, revision checks, execution history, and Temporal trace inspection."+ },+ {+ "path": "client/src/components/parameterPanel/TeamMonitorPanel.tsx",+ "reason": "Defines the read-only teammate and task snapshot, lifecycle counts, execution selector, and event-driven refresh."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/10-team-operations.png",+ "svg": "docs/diagrams/v2/dark/10-team-operations.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/10-team-operations.png",+ "svg": "docs/diagrams/v2/light/10-team-operations.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "11-agent-context-memory",+ "title": "Agent Context vs. Simple Memory",+ "diagramType": "side-by-side-comparison",+ "sourceReview": "reviewed",+ "components": [+ "context-node",+ "context-journal",+ "context-checkpoint",+ "agent-runtime",+ "memory-node",+ "memory-store",+ "memory-items"+ ],+ "relationships": [+ "context-binds-runtime",+ "runtime-appends-context",+ "journal-compacts",+ "checkpoint-replays",+ "memory-registers-tool",+ "runtime-invokes-memory",+ "memory-persists-items",+ "memory-returns-items"+ ],+ "sourceRefs": [+ {+ "path": "server/nodes/context/__init__.py",+ "reason": "Defines the visible system-managed Context policy node, output-context handle, compaction policy, and metadata-only output."+ },+ {+ "path": "server/nodes/context/_descriptor.py",+ "reason": "Defines generation-scoped Context descriptors, thread selection, and delegated-task isolation."+ },+ {+ "path": "server/services/agent_context/store.py",+ "reason": "Defines transactional append-only Context threads, epochs, revisions, journal events, and checkpoints."+ },+ {+ "path": "server/services/agent_context/compaction.py",+ "reason": "Defines provider-native versus portable compaction and exact replay-tail behavior under context pressure."+ },+ {+ "path": "server/nodes/context/_handlers.py",+ "reason": "Defines active-epoch journal inspection so Reset and Clear expose the fresh live epoch while retaining prior events as archived history."+ },+ {+ "path": "server/nodes/tool/simple_memory/__init__.py",+ "reason": "Defines Simple Memory V2 as an explicit locked-schema tool with remember, recall, list, get, update, and forget operations."+ },+ {+ "path": "server/services/memory/tool_store.py",+ "reason": "Defines isolated owner/workflow/node namespaces, versioned durable items, idempotent mutations, and lexical or embedding retrieval."+ },+ {+ "path": "client/src/components/parameterPanel/ContextPanel.tsx",+ "reason": "Defines the authorized exact-journal and active-replay inspector, including pressure, checkpoints, fork, export, and epoch clear."+ },+ {+ "path": "client/src/components/parameterPanel/MemoryToolPanel.tsx",+ "reason": "Defines human-authored durable facts, search, update, forget, and isolated bulk-clear controls."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/11-agent-context-memory.png",+ "svg": "docs/diagrams/v2/dark/11-agent-context-memory.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/11-agent-context-memory.png",+ "svg": "docs/diagrams/v2/light/11-agent-context-memory.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "12-master-skill-editor",+ "title": "Master Skill Editor",+ "diagramType": "product panel with configuration and runtime data flow",+ "sourceReview": "reviewed",+ "components": [+ "skill-ws-handlers",+ "builtin-skill-files",+ "user-skill-store",+ "tanstack-skill-cache",+ "skill-catalogue-pane",+ "instructions-editor-pane",+ "query-projection",+ "skills-config",+ "master-skill-expander",+ "agent-skill-runtime",+ "skill-status-projection"+ ],+ "relationships": [+ "handlers-scan-builtins",+ "handlers-crud-user-skills",+ "handlers-refresh-cache",+ "cache-builds-projection",+ "projection-populates-catalogue",+ "catalogue-selects-editor",+ "catalogue-writes-toggle",+ "editor-writes-instructions",+ "editor-user-skill-crud",+ "config-expands",+ "expander-builds-runtime",+ "runtime-publishes-status",+ "status-back-to-catalogue"+ ],+ "sourceRefs": [+ {+ "path": "client/src/components/parameterPanel/MasterSkillEditor.tsx",+ "reason": "Defines the split catalogue/editor surface, folder and user-skill queries, enable toggles, instruction editing, CRUD actions, skills_config writes, and runtime row badges."+ },+ {+ "path": "client/src/hooks/useFolderSkills.ts",+ "reason": "Defines the folderSkills TanStack query and scan_skill_folder metadata mapping used by the catalogue."+ },+ {+ "path": "server/services/skills/handlers.py",+ "reason": "Owns the list/scan/content handlers, user-skill CRUD, and lifecycle-producing mutation paths used by the editor."+ },+ {+ "path": "server/nodes/skill/master_skill/__init__.py",+ "reason": "Defines the passive Master Skill node, required assistant Skill entry, skills_config parameter shape, and editor UI hints."+ },+ {+ "path": "server/nodes/skill/_expander.py",+ "reason": "Expands enabled skills_config entries into per-skill descriptors for connected agents."+ },+ {+ "path": "server/services/skill_runtime.py",+ "reason": "Loads authoritative instructions progressively and publishes loading, loaded, used, or failed activity to the agent and exact Master Skill node."+ },+ {+ "path": "server/nodes/skill/master_skill/_events.py",+ "reason": "Defines the skill_lifecycle CloudEvent used to invalidate userSkills, folderSkills, and skillContent caches across clients."+ },+ {+ "path": "client/src/contexts/WebSocketContext.tsx",+ "reason": "Routes skill_lifecycle invalidation and live node-status data consumed by the editor."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/12-master-skill-editor.png",+ "svg": "docs/diagrams/v2/dark/12-master-skill-editor.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/12-master-skill-editor.png",+ "svg": "docs/diagrams/v2/light/12-master-skill-editor.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "13-workspace-files",+ "title": "Workspace Files",+ "diagramType": "product panel with transport and execution paths",+ "sourceReview": "reviewed",+ "components": [+ "workspace-panel-header",+ "workspace-browser",+ "workspace-file-actions",+ "gallery-node-parameters",+ "list-workspace-files-handler",+ "workspace-http-routes",+ "workspace-listing-service",+ "contained-workspace-root",+ "gallery-node-runtime",+ "gallery-file-ref-output"+ ],+ "relationships": [+ "header-opens-upload",+ "browser-activates-file",+ "browser-requests-listing",+ "handler-selects-listing-mode",+ "listing-reads-workspace",+ "actions-use-http",+ "http-reads-writes-workspace",+ "browser-controls-path",+ "actions-control-selection",+ "params-drive-gallery-run",+ "gallery-reuses-listing-service",+ "gallery-emits-output"+ ],+ "sourceRefs": [+ {+ "path": "client/src/components/parameterPanel/GalleryPanel.tsx",+ "reason": "Defines the Workspace Files header, upload action, preview, pinning, controlled path/selection parameters, and Gallery-panel integration."+ },+ {+ "path": "client/src/components/parameterPanel/gallery/WorkspaceBrowser.tsx",+ "reason": "Defines breadcrumbs, debounced workspace-wide search, grid/list views, refresh and polling, row activation, pinning, and drag payload behavior."+ },+ {+ "path": "server/nodes/filesystem/gallery/_handlers.py",+ "reason": "Defines list_workspace_files as the WebSocket listing/search channel and its workflow-root resolution."+ },+ {+ "path": "server/nodes/filesystem/gallery/_service.py",+ "reason": "Defines directory and recursive glob listing, caps, sorting, crumbs, self-sufficient FileRef rows, URLs, and preview verdicts."+ },+ {+ "path": "server/nodes/filesystem/gallery/__init__.py",+ "reason": "Defines Gallery node parameters and execution branches that emit workspace FileRef rows downstream."+ },+ {+ "path": "server/nodes/filesystem/_backend.py",+ "reason": "Provides the contained WorkspaceBackend used for ls/glob and safe workspace path handling."+ },+ {+ "path": "server/routers/workspace.py",+ "reason": "Defines the HTTP upload and file-content surface used for upload, preview, download, and Range reads."+ },+ {+ "path": "docs-internal/node-logic-flows/code_fs_process/gallery.md",+ "reason": "Documents the reviewed Gallery panel/execution contract and the separation between WebSocket listing and HTTP content."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/13-workspace-files.png",+ "svg": "docs/diagrams/v2/dark/13-workspace-files.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/13-workspace-files.png",+ "svg": "docs/diagrams/v2/light/13-workspace-files.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ },+ {+ "id": "14-runtime-observability-dock",+ "title": "Runtime Observability Dock",+ "diagramType": "runtime observability product panel and stream topology",+ "sourceReview": "reviewed",+ "components": [+ "console-node-producer",+ "terminal-log-producers",+ "chat-trigger-consumers",+ "status-broadcaster",+ "dock-ws-handlers",+ "workflow-history-db",+ "terminal-ring-buffer",+ "websocket-context-state",+ "chat-pane",+ "console-tab",+ "terminal-tab",+ "dock-preferences"+ ],+ "relationships": [+ "console-broadcasts-log",+ "runtime-broadcasts-terminal",+ "broadcaster-persists-console",+ "broadcaster-retains-terminal",+ "handlers-query-db",+ "handlers-query-terminal-cache",+ "handlers-dispatch-chat-trigger",+ "live-events-update-context",+ "handlers-hydrate-context",+ "chat-sends-handler-request",+ "context-renders-chat",+ "context-renders-console",+ "context-renders-terminal",+ "prefs-shape-chat-pane",+ "prefs-select-log-tab"+ ],+ "sourceRefs": [+ {+ "path": "client/src/components/ui/ConsolePanel.tsx",+ "reason": "Defines the collapsible, resizable Chat / Console dock, chat target selector, Console and Terminal tabs, filters, clear controls, auto-scroll, pretty-print, and persisted preferences."+ },+ {+ "path": "client/src/contexts/WebSocketContext.tsx",+ "reason": "Owns live chat/console/terminal arrays, reconnect and workflow-switch hydration, clear commands, send_chat_message, and 100/200-entry client caps."+ },+ {+ "path": "server/nodes/utility/console/__init__.py",+ "reason": "Produces structured Console-node log records and broadcasts them while passing workflow data through."+ },+ {+ "path": "server/services/status_broadcaster.py",+ "reason": "Persists and broadcasts Console logs, retains the last 100 in memory, and retains/broadcasts the last 200 Terminal logs."+ },+ {+ "path": "server/routers/websocket.py",+ "reason": "Defines workflow-scoped chat send/history/clear, Console history/clear, and Terminal history/clear request handlers."+ },+ {+ "path": "server/nodes/trigger/chat_trigger/_events.py",+ "reason": "Dispatches workflow-scoped chat_message_received CloudEvents to waiting chatTrigger consumers and the frontend."+ },+ {+ "path": "server/services/process_service.py",+ "reason": "Streams managed-process output into the Terminal log channel."+ },+ {+ "path": "server/core/logging.py",+ "reason": "Streams server logger records into the Terminal log broadcaster."+ },+ {+ "path": "docs-internal/node-logic-flows/chat_utility/console.md",+ "reason": "Documents the reviewed Console node record shape and StatusBroadcaster side effect consumed by the dock."+ }+ ],+ "artifacts": {+ "dark": {+ "draft": "docs-internal/diagram-generation/drafts/dark/14-runtime-observability-dock.png",+ "svg": "docs/diagrams/v2/dark/14-runtime-observability-dock.svg",+ "draftPresent": true,+ "svgPresent": true+ },+ "light": {+ "draft": "docs-internal/diagram-generation/drafts/light/14-runtime-observability-dock.png",+ "svg": "docs/diagrams/v2/light/14-runtime-observability-dock.svg",+ "draftPresent": true,+ "svgPresent": true+ }+ },+ "validationStatus": "validated"+ }+ ],+ "validationStatus": "validated"+}diff --git a/docs-internal/diagram-generation/prompt-pack.md b/docs-internal/diagram-generation/prompt-pack.mdnew file mode 100644index 00000000..7e605f7d--- /dev/null+++ b/docs-internal/diagram-generation/prompt-pack.md@@ -0,0 +1,1158 @@+# OpenCompany GPT Image prompt pack++Generated from the source-backed diagram specifications. Use the built-in GPT Image path one asset at a time. Dark drafts are generations; light drafts are edits of their approved dark counterpart. Generated text is non-authoritative—the SVG redraw is canonical.++## 01-system-context: OpenCompany System Context++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a precise C4 system-context diagram with OpenCompany centered inside a clearly labelled system boundary, two human actor cards on the left, and six external-system cards stacked on the right.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Workflow authors (person); Workflow operators (person); OpenCompany (software system); LLM providers (external system); Productivity services (external system); Messaging channels (external system); Connected devices (external system); Developer services (external system); Search and vector stores (external system)+Composition/framing: Left-to-right context map. Keep OpenCompany visually dominant in the middle. Route the two inbound human relationships into the left edge of OpenCompany and fan six labelled outbound relationships to a clean right-hand stack. Put the system-responsibility note beneath the central card.+Directed relationships:+- workflow-authors → opencompany: "Design and run automations" via Browser UI / CLI+- workflow-operators → opencompany: "Control deployed workflows" via Browser UI / WebSocket+- opencompany → llm-providers: "Requests inference" via Provider SDK / HTTPS+- opencompany → productivity-services: "Reads and updates work" via OAuth / HTTPS+- opencompany → messaging-channels: "Sends and receives messages" via Webhooks / RPC+- opencompany → connected-devices: "Invokes device actions" via RPC / platform APIs+- opencompany → developer-services: "Uses code and dev tools" via MCP / CLI / HTTPS+- opencompany → search-vector-stores: "Indexes and retrieves knowledge" via HTTPS / vector API+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["OpenCompany System Context", "Workflow authors", "Workflow operators", "OpenCompany", "LLM providers", "Productivity services", "Messaging channels", "Connected devices", "Developer services", "Search and vector stores", "Design and run automations", "Control deployed workflows", "Requests inference", "Reads and updates work", "Sends and receives messages", "Invokes device actions", "Uses code and dev tools", "Indexes and retrieves knowledge"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Treat OpenCompany as one software system at this abstraction level+- Show no internal containers or databases+- Keep all external systems outside the OpenCompany boundary+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- vendor logos+- unlisted integrations+- internal microservice detail+- bidirectional arrows+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "OpenCompany System Context"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "OpenCompany System Context"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 02-runtime-trust-topology: Runtime and Trust Topology++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Draw a deployment-aware runtime and trust topology for OpenCompany, showing clients on the left, the application and its security surfaces in the center, and Temporal plus lazy helper runtimes on the right.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Browser SPA (client); OpenCompany CLI (client); Webhook senders (external); Vite development server (container); FastAPI application (container); Protected REST API (interface); /ws/status (websocket); /ws/internal (websocket); /mcp/ide/mcp (MCP endpoint); /webhook/* (HTTP ingress); Production SPA assets (static content); Temporal server and worker (durable runtime); Node.js executor (lazy sidecar); WhatsApp RPC (lazy sidecar)+Composition/framing: Use three vertical trust zones. Place Vite and FastAPI high in the application zone, API and WebSocket surfaces in the middle, MCP/webhook/static surfaces below, and the trust-rules note at the bottom. Clearly distinguish development proxying from production SPA serving.+Directed relationships:+- browser-spa → vite-dev: "Loads SPA in development" via HTTP :5678+- vite-dev → fastapi-app: "Proxies /api /ws /webhook /health /mcp" via HTTP / WS :5679+- opencompany-cli → fastapi-app: "Launches and administers" via Typer / process+- browser-spa → rest-surface: "Calls protected routes" via HTTPS + JWT cookie+- browser-spa → status-socket: "Commands and receives status" via WebSocket + cookie+- opencompany-cli → mcp-surface: "Invokes scoped tools" via MCP over HTTP + Bearer+- webhook-senders → webhook-ingress: "Delivers provider events" via HTTPS webhook+- rest-surface → fastapi-app: "Dispatches request" via ASGI+- status-socket → fastapi-app: "Dispatches authenticated message" via ASGI WebSocket+- temporal-runtime → internal-socket: "Calls legacy node handlers" via WebSocket+- fastapi-app → temporal-runtime: "Starts workflows and polls tasks" via Temporal gRPC :5681+- fastapi-app → nodejs-sidecar: "Starts on demand and executes JavaScript" via HTTP :5682+- fastapi-app → whatsapp-sidecar: "Starts on demand and sends commands" via RPC :5683+- fastapi-app → production-spa: "Serves production fallback" via StaticFiles / HTML+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Runtime and Trust Topology", "Browser SPA", "OpenCompany CLI", "Webhook senders", "Vite development server", "FastAPI application", "Protected REST API", "/ws/status", "/ws/internal", "/mcp/ide/mcp", "/webhook/*", "Production SPA assets", "Temporal server and worker", "Node.js executor", "WhatsApp RPC", "Loads SPA in development", "Proxies /api /ws /webhook /health /mcp", "Launches and administers", "Calls protected routes", "Commands and receives status", "Invokes scoped tools", "Delivers provider events", "Dispatches request", "Dispatches authenticated message", "Calls legacy node handlers", "Starts workflows and polls tasks", "Starts on demand and executes JavaScript", "Starts on demand and sends commands", "Serves production fallback"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Show exact ports 5678, 5679, 5680, 5681, 5682 and 5683 only where specified+- Use a dashed line only for the legacy Temporal-to-/ws/internal path+- Make public, authenticated, bearer-scoped and internal-restricted boundaries visually distinct+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- Docker or Kubernetes assumptions+- microservices not present in the repository+- a public /ws/internal interpretation+- a removed /api/workflow/execute-node route+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Runtime and Trust Topology"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Runtime and Trust Topology"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 03-workflow-execution-routing: Workflow Execution Routing++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a source-accurate dynamic execution-routing diagram showing a direct single-node path, a whole-workflow routing decision with three ordered branches, and a shared six-stage NodeExecutor pipeline.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Single-node request (entry point); Whole-workflow run (entry point); WorkflowService routing (decision); Temporal branch (durable orchestrator); Redis-parallel branch (graph orchestrator); Sequential fallback (graph orchestrator); Prepare parameters (pipeline stage); Resolve templates (pipeline stage); Dispatch plugin operation (pipeline stage); Validated execution result (pipeline stage); Output store (persistence); Status broadcasts (observable result)+Composition/framing: Use three vertical bands: entries, graph orchestration, and NodeExecutor pipeline. Put the direct single-node connector above the graph router. Stack Temporal, Redis-parallel, and sequential branches in priority order. Arrange the pipeline as a compact two-column serpentine flow ending in output storage and status broadcasts.+Directed relationships:+- single-node-request → parameter-preparation: "Executes directly" via WorkflowService.execute_node+- whole-workflow-request → routing-decision: "Submits nodes, edges and identity" via WorkflowService.execute_workflow+- routing-decision → temporal-branch: "Chooses when requested and wired" via Temporal+- routing-decision → redis-parallel-branch: "Else chooses when parallel and Redis enabled" via in-process + Redis+- routing-decision → sequential-branch: "Otherwise falls back" via in-process+- temporal-branch → parameter-preparation: "Schedules node activities" via Temporal task queue+- redis-parallel-branch → parameter-preparation: "Calls node adapter with retries" via async callback+- sequential-branch → parameter-preparation: "Calls each ready node" via await+- parameter-preparation → template-resolution: "Passes validated parameters" via Python dict+- template-resolution → plugin-dispatch: "Builds handler context" via NodeContext+- plugin-dispatch → validated-result: "Returns standardized result" via ExecutionResult+- validated-result → output-store: "Persists successful outputs" via database callback+- output-store → status-broadcast: "Publishes execution state" via WebSocket broadcast+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Workflow Execution Routing", "Single-node request", "Whole-workflow run", "WorkflowService routing", "Temporal branch", "Redis-parallel branch", "Sequential fallback", "Prepare parameters", "Resolve templates", "Dispatch plugin operation", "Validated execution result", "Output store", "Status broadcasts", "Executes directly", "Submits nodes, edges and identity", "Chooses when requested and wired", "Else chooses when parallel and Redis enabled", "Otherwise falls back", "Schedules node activities", "Calls node adapter with retries", "Calls each ready node", "Passes validated parameters", "Builds handler context", "Returns standardized result", "Persists successful outputs", "Publishes execution state"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Preserve the routing precedence Temporal requested+wired, else parallel+Redis, else sequential+- Show that the single-node request bypasses graph routing+- Show all graph branches converging on the same NodeExecutor pipeline+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- claiming Redis is the executor itself+- claiming Temporal is always mandatory+- a removed public execute-node REST route+- parallel arrows without labels+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Workflow Execution Routing"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Workflow Execution Routing"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 04-durable-deployment-events: Durable Deployment and Events++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Build a deployment lifecycle and event-routing diagram that connects operator controls, revision-guarded generation snapshots, a long-lived Temporal controller, push/poll/cron trigger paths, and durable child graph runs.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Start · Pause · Resume · Reset (operator controls); WorkflowControlService (control service); Generation control row (durable data); WorkflowControlWorkflow (long-lived workflow); Local admission state (process projection); Push trigger (trigger definition); Poll trigger (trigger definition); Cron trigger (trigger definition); WorkflowEvent (CloudEvents 1.0); dispatch.emit (event router); Trigger registration (control signal); Child graph workflow (Temporal workflow); Cron action workflow (Temporal workflow); Run status and events (observable result)+Composition/framing: Use three vertical planes: control, trigger/event, and durable execution. Flow lifecycle commands and generation data down the left, push/poll/cron sources across the center, and child/cron workflows plus status on the right. Make the controller the visual hub without crossing connectors.+Directed relationships:+- lifecycle-controls → workflow-control-service: "Requests lifecycle transition" via WebSocket command+- workflow-control-service → generation-snapshot: "Allocates or CAS-updates" via workflow database+- generation-snapshot → controller: "Starts with immutable graph snapshot" via Temporal gRPC+- workflow-control-service → controller: "Updates pause/resume or signals reset" via Temporal Update / Signal+- workflow-control-service → local-runtime-state: "Projects admission state" via in-process+- push-trigger → cloudevent: "Normalizes inbound event" via CloudEvents 1.0+- cloudevent → event-dispatch: "Emits envelope" via async dispatch+- event-dispatch → controller: "Signals matching controller" via Visibility + on_event+- poll-trigger → controller: "Registers durable poll loop" via register_trigger signal+- cron-trigger → cron-action-workflow: "Fires scheduled action" via Temporal Schedule+- trigger-registration → controller: "Registers definitions and pause state" via Temporal Signal+- controller → child-graph-workflow: "Spawns admitted event or poll run" via Temporal child workflow+- cron-action-workflow → child-graph-workflow: "Launches snapshotted graph" via Temporal child workflow+- child-graph-workflow → execution-status: "Persists and broadcasts run state" via database + WebSocket+- cron-action-workflow → execution-status: "Reports scheduled run state" via Temporal + WebSocket+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Durable Deployment and Events", "Start · Pause · Resume · Reset", "WorkflowControlService", "Generation control row", "WorkflowControlWorkflow", "Local admission state", "Push trigger", "Poll trigger", "Cron trigger", "WorkflowEvent", "dispatch.emit", "Trigger registration", "Child graph workflow", "Cron action workflow", "Run status and events", "Requests lifecycle transition", "Allocates or CAS-updates", "Starts with immutable graph snapshot", "Updates pause/resume or signals reset", "Projects admission state", "Normalizes inbound event", "Emits envelope", "Signals matching controller", "Registers durable poll loop", "Fires scheduled action", "Registers definitions and pause state", "Spawns admitted event or poll run", "Launches snapshotted graph", "Persists and broadcasts run state", "Reports scheduled run state"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Show graph_snapshot as immutable per generation+- Show push events as CloudEvents dispatched through Visibility and on_event+- Keep cron as a Temporal Schedule path distinct from controller-owned push/poll paths+- Use dashed styling only for optional or legacy reporting/fallback semantics+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- one workflow per idle trigger+- mutable live canvas as the deployed graph source+- polling through a cron schedule+- unlabelled signals+- Kubernetes or queue infrastructure not present in source+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Durable Deployment and Events"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Durable Deployment and Events"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 05-plugin-agent-team-composition: Plugin → Agent → Team Composition++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a precise three-layer composition diagram that explains how self-registering plugins become chat-model and agent nodes, how an agent assembles context, skills, and tools before LLM dispatch, and how a team lead converts connected teammates into durable delegation state.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: BaseNode plugin contract (plugin contract); Chat-model plugins (model plugin); ChatUnifier (LLM facade); Agent plugins (agent plugin); Context (connected config); Skills (connected capability); Tools (connected capability); Prepared agent call (runtime payload); Orchestrator / AI Employee (team-lead agent); Connected teammate agents (agent set); Task Manager (intrinsic tool); Durable team state (execution data)+Composition/framing: Three framed columns from left to right: Plugin & Model Layer, Agent Composition, and Team Composition. Keep the BaseNode-to-model/agent branching explicit, arrange Context/Skills/Tools as a capability row feeding one prepared agent payload, and show team lead, teammates, intrinsic Task Manager, and durable team state as a clean vertical composition.+Directed relationships:+- base-node → model-plugins: "specializes as model plugin"+- base-node → agent-plugins: "specializes as agent plugin"+- model-plugins → chat-unifier: "dispatches chat" via provider + model+- agent-plugins → prepared-agent-call: "prepares execution payload"+- context-node → prepared-agent-call: "adds context descriptor"+- skill-nodes → prepared-agent-call: "injects enabled skill content"+- tool-nodes → prepared-agent-call: "builds tool surface"+- prepared-agent-call → chat-unifier: "routes selected provider and model"+- teammates → team-lead: "connect via input-teammates"+- team-lead → prepared-agent-call: "executes through shared agent runtime"+- team-lead → task-manager: "auto-binds intrinsic tool"+- teammates → durable-team: "registers execution members"+- task-manager → durable-team: "persists task lifecycle"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Plugin → Agent → Team Composition", "BaseNode plugin contract", "Chat-model plugins", "ChatUnifier", "Agent plugins", "Context", "Skills", "Tools", "Prepared agent call", "Orchestrator / AI Employee", "Connected teammate agents", "Task Manager", "Durable team state", "specializes as model plugin", "specializes as agent plugin", "dispatches chat", "prepares execution payload", "adds context descriptor", "injects enabled skill content", "builds tool surface", "routes selected provider and model", "connect via input-teammates", "executes through shared agent runtime", "auto-binds intrinsic tool", "registers execution members", "persists task lifecycle"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Do not draw standalone chat-model nodes as a required input to ordinary agents; agents select provider and model in their own Params+- Show every capability and teammate connection as a directed labelled edge+- Keep the shared ChatUnifier visible for both standalone model execution and agent execution+- Treat Task Manager as intrinsic to team leads, not a palette-connected tool+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- class-count claims not shown in source+- implying teammate-to-teammate communication is required for composition+- unlabelled containment lines+- bidirectional arrows+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Plugin → Agent → Team Composition"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Plugin → Agent → Team Composition"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 06-persistence-secret-plane: Persistence & Secret Plane++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a two-plane data architecture diagram that makes the separation between workflow.db operational persistence and the encrypted credentials.db secret plane unmistakable, including the real service boundaries and startup-derived encryption key path.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Runtime services (application callers); Database (persistence service); workflow.db (SQLite data store); Plugin credentials (secret consumers); AuthService (secret facade); Process caches (bounded secret cache); CredentialsDatabase (encrypted persistence); API_KEY_ENCRYPTION_KEY (server configuration); EncryptionService (cryptographic boundary); credentials.db (encrypted SQLite)+Composition/framing: Use two large side-by-side framed planes. The left plane is a short Runtime Services → Database → workflow.db flow with a blast-radius note. The right plane flows Plugin Credentials → AuthService → CredentialsDatabase → encrypted credentials.db, with a side cache, a server key feeding EncryptionService, and a refresh-token warning near the cache.+Directed relationships:+- runtime-services → database-service: "persists operational state"+- database-service → workflow-db: "reads and writes SQLModel rows" via sqlite+aiosqlite+- credential-callers → auth-service: "requests secret resolution"+- auth-service → credential-caches: "populates safe cache"+- auth-service → credentials-database: "save · retrieve · delete"+- encryption-password → encryption-service: "derives in-memory Fernet key"+- credentials-database → encryption-service: "calls encrypt / decrypt per field"+- credentials-database → credentials-db: "stores ciphertext rows and salt" via SQLite+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Persistence & Secret Plane", "Runtime services", "Database", "workflow.db", "Plugin credentials", "AuthService", "Process caches", "CredentialsDatabase", "API_KEY_ENCRYPTION_KEY", "EncryptionService", "credentials.db", "persists operational state", "reads and writes SQLModel rows", "requests secret resolution", "populates safe cache", "save · retrieve · delete", "derives in-memory Fernet key", "calls encrypt / decrypt per field", "stores ciphertext rows and salt"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Keep workflow.db and credentials.db visually separate+- Show AuthService as the single service-level credential access surface+- Show the API_KEY_ENCRYPTION_KEY and persisted salt as inputs to the encrypted-store design+- State that OAuth refresh tokens bypass the process cache+- Do not imply plaintext secrets are persisted+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- showing the unused credential backend factory as the active runtime path+- placing API keys in workflow.db+- plaintext secret labels inside credentials.db+- bidirectional arrows+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Persistence & Secret Plane"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Persistence & Secret Plane"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 07-workspace-anatomy: Workspace Anatomy++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a filesystem anatomy diagram showing how an immutable workflow ID resolves through workflow.db to a mutable slug-keyed workspace, what lives inside that workspace, and which HTTP, filesystem/media, and CLI-agent consumers access it through containment controls.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Workflow record (database identity); Workspace locator (path resolver); DATA_DIR / workspaces (filesystem root); workspaces/<workflow.slug>/ (workspace root); Workspace files (runtime artifacts); .claude/skills/<name>/ (materialized skills); <node_id>/wt_<task_id>/ (CLI worktree); Workspace HTTP routes (interface); Filesystem & media nodes (contained I/O); CLI agent session (agent consumer)+Composition/framing: Use three framed columns: Identity & Root Resolution, Per-Workflow Workspace, and Contained Consumers. Show the id→slug resolver as a vertical chain on the left; place the slug directory at the top of the middle frame with files, .claude skills, and per-task CLI worktrees below; stack HTTP routes, filesystem/media nodes, and the CLI agent on the right.+Directed relationships:+- workflow-record → workspace-locator: "lookup by immutable workflow id"+- workspace-locator → workspace-base: "selects mutable slug below root"+- workspace-base → workflow-workspace: "contains one slug directory"+- workflow-workspace → workspace-files: "contains runtime artifacts"+- workflow-workspace → workspace-skills: "contains isolated skill tree"+- workflow-workspace → cli-worktrees: "contains per-node task worktrees"+- workspace-routes → workflow-workspace: "resolves workflow id before file access" via workspace locator+- filesystem-media → workspace-files: "reads and writes contained paths"+- workspace-skills → cli-agent-session: "auto-discovers enabled skills" via --add-dir+- workflow-workspace → cli-agent-session: "passes workspace_dir"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Workspace Anatomy", "Workflow record", "Workspace locator", "DATA_DIR / workspaces", "workspaces/<workflow.slug>/", "Workspace files", ".claude/skills/<name>/", "<node_id>/wt_<task_id>/", "Workspace HTTP routes", "Filesystem & media nodes", "CLI agent session", "lookup by immutable workflow id", "selects mutable slug below root", "contains one slug directory", "contains runtime artifacts", "contains isolated skill tree", "contains per-node task worktrees", "resolves workflow id before file access", "reads and writes contained paths", "auto-discovers enabled skills", "passes workspace_dir"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Label the on-disk directory with workflow.slug, never workflow.id+- State that stable references and routes carry the immutable workflow id+- Show containment for relative paths and symlink/junction escapes+- Keep .claude/skills inside the per-workflow workspace+- Show CLI worktrees under the same workspace root+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- placing shipped example workflows under DATA_DIR+- using a workflow id as the workspace directory name+- showing unrestricted host filesystem access+- bidirectional arrows+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Workspace Anatomy"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Workspace Anatomy"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 08-node-configuration-anatomy: Node Configuration Anatomy++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create an annotated product-panel anatomy of the Node Configuration modal with its real header controls, three proportional columns, and the live client/server data flows that drive configuration, execution, and output.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Node identity (modal header); Save (header action); Run (header action); Cancel / Stop (header action); Close (X) (modal action); Input Data & Variables (left column · 0.7); Parameters (middle column · 1.6); Output (right column · 0.7); NodeSpec metadata (schema source); Parameter query + draft (client state); ExecutionService (per-node runtime); WebSocket + workflow.db (live data plane)+Composition/framing: Use one wide modal frame above a shallow live-data frame. In the modal header place Node identity, Save, Run, Cancel / Stop, and Close. Beneath it, preserve the visibly narrow-wide-narrow 0.7 / 1.6 / 0.7 Input Data & Variables, Parameters, and Output columns. Align NodeSpec, parameter draft/query, ExecutionService, and WebSocket + workflow.db cards below their consumers.+Directed relationships:+- node-spec → node-identity: "supplies icon and display name"+- node-spec → parameters-column: "renders fields and panel variants"+- input-column → parameters-column: "drag template variable"+- parameters-column → parameter-state: "onParameterChange updates local draft"+- save-action → parameter-state: "handleSave commits draft"+- run-action → execution-service: "save if dirty, then execute node"+- execution-service → output-column: "appends correlated ExecutionResult"+- websocket-database → output-column: "broadcasts node status and output" via execution_id+- cancel-action → websocket-database: "cancel wait or close draft"+- parameter-state → websocket-database: "save_node_parameters" via TanStack Query + WS+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Node Configuration Anatomy", "Node identity", "Save", "Run", "Cancel / Stop", "Close (X)", "Input Data & Variables", "Parameters", "Output", "NodeSpec metadata", "Parameter query + draft", "ExecutionService", "WebSocket + workflow.db", "supplies icon and display name", "renders fields and panel variants", "drag template variable", "onParameterChange updates local draft", "handleSave commits draft", "save if dirty, then execute node", "appends correlated ExecutionResult", "broadcasts node status and output", "cancel wait or close draft", "save_node_parameters"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Preserve the 0.7 / 1.6 / 0.7 column hierarchy+- Show Save, Run, Cancel / Stop, and Close as distinct controls+- Represent NodeSpec uiHints as the source of hidden sections and specialized middle panels+- Show the local edit buffer separately from persisted node_parameters+- Show output correlation by execution_id+- Keep all relationships directed and labelled+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- invented toolbar controls+- a generic settings form unrelated to the real panel+- equal-width content columns+- unlabelled arrows+- bidirectional arrows+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Node Configuration Anatomy"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Node Configuration Anatomy"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 09-credentials-architecture: Credentials Architecture++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Show the current OpenCompany credential architecture as a security-first flow from the Credentials Modal through WebSocket handlers and declarative credential registries to AuthService, encrypted SQLite, and client-invalidating status broadcasts.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Credentials Modal (UI); WebSocket + Query State (CLIENT); Credential WS Handlers (ROUTER); Credential Registries (REGISTRY); Status Broadcaster (EVENTS); AuthService (SECURITY SERVICE); Encryption Service (CRYPTO); credentials.db (ENCRYPTED SQLITE)+Composition/framing: Two clearly bounded lanes: a compact client control plane on the left and a larger server security plane on the right. Read primarily left-to-right, then down through AuthService to encrypted storage, with one dashed broadcast return path across the top. Keep the API-key versus OAuth-token split visible as a security callout.+Directed relationships:+- credentials-modal → client-state: "panel actions + cached status" via React Query+- client-state → ws-handlers: "catalogue + credential RPC" via WebSocket+- ws-handlers → credential-registries: "dispatch validation"+- ws-handlers → auth-service: "get · save · delete"+- credential-registries → auth-service: "store valid probe result"+- credential-registries → status-broadcaster: "publish validation status"+- auth-service → status-broadcaster: "catalogue version + mutation event"+- auth-service → credentials-db: "canonical encrypted CRUD"+- credentials-db → encryption-service: "encrypt / decrypt payloads" via Fernet+- status-broadcaster → client-state: "push status + invalidate catalogue" via WebSocket+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Credentials Architecture", "Credentials Modal", "WebSocket + Query State", "Credential WS Handlers", "Credential Registries", "Status Broadcaster", "AuthService", "Encryption Service", "credentials.db", "panel actions + cached status", "catalogue + credential RPC", "dispatch validation", "get · save · delete", "store valid probe result", "publish validation status", "catalogue version + mutation event", "canonical encrypted CRUD", "encrypt / decrypt payloads", "push status + invalidate catalogue"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- AuthService must be the only plaintext credential access boundary+- Show API keys and OAuth tokens as distinct non-interchangeable records+- Show CredentialsDatabase calling Fernet encryption with PBKDF2-SHA256-derived process key+- Show status broadcasts invalidating the client catalogue without exposing secret values+- Never render example API keys, access tokens, refresh tokens, or plaintext secrets+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- implying the browser stores plaintext secrets persistently+- merging API keys and OAuth tokens into one cache or record+- showing routers accessing CredentialsDatabase directly+- depicting refresh tokens inside the in-memory cache+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Credentials Architecture"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Credentials Architecture"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 10-team-operations: Team Operations++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Explain OpenCompany team operations as one integrated schematic: the team lead's intrinsic Task Manager and human panels feed an execution-scoped AgentTeamService, then a durable task state machine makes worker submission, lead acceptance, retries, reassignment, cancellation, and final team completion explicit.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Team Lead (AGENT); Task Manager (INTRINSIC TOOL); AgentTeamService (DURABLE SERVICE); Task Manager + Team Monitor (HUMAN UI); Blocked (TASK STATE); Queued (TASK STATE); Running (TASK STATE); Submitted (TASK STATE); Accepted (TASK STATE); Failed (TASK STATE); Cancelled (TASK STATE); Team Completed (EXECUTION STATE)+Composition/framing: A narrow top control band contains Team Lead, Task Manager, AgentTeamService, and the human Task Manager plus Team Monitor. A large lower band contains a left-to-right lifecycle from Blocked through Queued, Running, Submitted, and Accepted, with Failed and Cancelled recovery states below and Team Completed at the lower right. Route recovery arrows around the main path and keep every arrow label readable.+Directed relationships:+- team-lead → task-manager: "call public operations"+- task-manager → agent-team-service: "scoped durable mutation"+- human-views → agent-team-service: "inspect + permitted review actions" via WebSocket+- agent-team-service → human-views: "snapshots + lifecycle events"+- agent-team-service → queued: "assign_task persists ready work"+- blocked → queued: "dependencies accepted"+- queued → running: "worker claims task"+- running → submitted: "worker succeeds"+- submitted → accepted: "accept_task"+- running → failed: "worker errors"+- failed → queued: "retry_task / reassign_task"+- submitted → queued: "retry_task / reassign_task"+- cancelled → queued: "retry_task / reassign_task"+- accepted → team-completed: "finish_team when all resolved"+- cancelled → team-completed: "cancelled also counts resolved"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Team Operations", "Team Lead", "Task Manager", "AgentTeamService", "Task Manager + Team Monitor", "Blocked", "Queued", "Running", "Submitted", "Accepted", "Failed", "Cancelled", "Team Completed", "call public operations", "scoped durable mutation", "inspect + permitted review actions", "snapshots + lifecycle events", "assign_task persists ready work", "dependencies accepted", "worker claims task", "worker succeeds", "accept_task", "worker errors", "retry_task / reassign_task", "retry_task / reassign_task", "retry_task / reassign_task", "finish_team when all resolved", "cancelled also counts resolved"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Submitted must be visibly distinct from Accepted and must not be labelled Done+- Only accepted and cancelled tasks satisfy finish_team+- Show retry and reassign returning failed, submitted, or cancelled work to Queued+- Show optimistic revision-checked mutations at AgentTeamService+- Team Monitor must be described as read-only even though Task Manager UI can mutate+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- equating worker completion with lead acceptance+- showing arbitrary non-connected agents as valid assignees+- a single undifferentiated completed state+- implying one sibling failure cancels every sibling+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Team Operations"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Team Operations"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 11-agent-context-memory: Agent Context vs. Simple Memory++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Create a precise side-by-side comparison showing that Agent Context and Simple Memory are separate systems around the same Agent Runtime: Context automatically journals and replays exact execution state, while Simple Memory is an explicit tool for versioned durable facts chosen by the model or a human.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Context Node (POLICY); AgentContextStore (EXACT JOURNAL); Replay Checkpoint (CONTEXT STATE); Agent Runtime (SHARED CONSUMER); Simple Memory (LOCKED TOOL); MemoryToolStore (DURABLE DATA); Facts & Decisions (MEMORY ITEMS)+Composition/framing: Mirror two wide bounded lanes around one central Agent Runtime. The left Context lane flows from policy to exact journal to replay checkpoint and back into the runtime. The right Memory lane flows from the explicit tool to a scoped durable store to recalled facts and back into the runtime. Use symmetric geometry so the conceptual contrast is immediate.+Directed relationships:+- context-node → agent-runtime: "bind policy at input-context"+- agent-runtime → context-journal: "append exact observable events"+- context-journal → context-checkpoint: "compact at context pressure"+- context-checkpoint → agent-runtime: "replay checkpoint + exact tail"+- memory-node → agent-runtime: "register tool at input-tools"+- agent-runtime → memory-store: "remember / recall / update / forget"+- memory-store → memory-items: "persist isolated versioned items"+- memory-items → agent-runtime: "return selected recalled items"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Agent Context vs. Simple Memory", "Context Node", "AgentContextStore", "Replay Checkpoint", "Agent Runtime", "Simple Memory", "MemoryToolStore", "Facts & Decisions", "bind policy at input-context", "append exact observable events", "compact at context pressure", "replay checkpoint + exact tail", "register tool at input-tools", "remember / recall / update / forget", "persist isolated versioned items", "return selected recalled items"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Label Context connection as output-context to input-context and Memory connection as output-tool to input-tools+- Context must be automatic, exact, provider-bound, and system managed+- Simple Memory must expose remember, recall, list, get, update, and forget as explicit operations+- Memory items must never appear as automatically injected transcript replay+- Clearing either system must not imply clearing the other+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- calling Simple Memory conversation history+- showing Context as a model-invoked tool+- merging Context journal records with Memory items+- implying manual or generation-zero runs always create durable Context+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Agent Context vs. Simple Memory"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Agent Context vs. Simple Memory"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 12-master-skill-editor: Master Skill Editor++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Draw a source-backed product-panel schematic of the Master Skill Editor, showing its split skill catalogue and instructions editor, the built-in and user skill sources, the persisted skills_config, expansion into the connected Agent Skill runtime, and the safe runtime-status feedback loop.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Skill WebSocket handlers (service); Built-in SKILL.md (source); User skill store (database); TanStack skill caches (client state); Skills catalogue pane (interface); Instructions editor pane (interface); Catalogue projection (view model); Master Skill skills_config (node params); Master Skill expander (runtime); Agent Skill runtime (tool runtime); Exact-node status projection (observability)+Composition/framing: Use three clearly bounded vertical zones matching the supplied coordinates: source handlers on the left, the split editor and its view/config state in the center, and the connected agent runtime on the right. Keep the bottom status-feedback route outside the cards and reserve the final band for the invariant callout.+Directed relationships:+- skill-ws-handlers → builtin-skill-files: "scan and load metadata + instructions" via filesystem+- skill-ws-handlers → user-skill-store: "list and mutate custom skills" via database+- skill-ws-handlers → tanstack-skill-cache: "query results and lifecycle invalidation" via WebSocket+- tanstack-skill-cache → query-projection: "cached folder, user, and content records"+- query-projection → skill-catalogue-pane: "render and filter rows"+- skill-catalogue-pane → instructions-editor-pane: "select skill"+- skill-catalogue-pane → skills-config: "toggle enabled / keep required"+- instructions-editor-pane → skills-config: "write instructions + customized flag"+- instructions-editor-pane → skill-ws-handlers: "create / update / delete user skill" via WebSocket+- skills-config → master-skill-expander: "expand enabled entries"+- master-skill-expander → agent-skill-runtime: "descriptors + Skill tool catalogue"+- agent-skill-runtime → skill-status-projection: "loading / loaded / used / failed" via node status + CloudEvents+- skill-status-projection → skill-catalogue-pane: "project safe state onto matching row"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Master Skill Editor", "Skill WebSocket handlers", "Built-in SKILL.md", "User skill store", "TanStack skill caches", "Skills catalogue pane", "Instructions editor pane", "Catalogue projection", "Master Skill skills_config", "Master Skill expander", "Agent Skill runtime", "Exact-node status projection", "scan and load metadata + instructions", "list and mutate custom skills", "query results and lifecycle invalidation", "cached folder, user, and content records", "render and filter rows", "select skill", "toggle enabled / keep required", "write instructions + customized flag", "create / update / delete user skill", "expand enabled entries", "descriptors + Skill tool catalogue", "loading / loaded / used / failed", "project safe state onto matching row"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Show the Skills catalogue pane and Instructions editor pane as equal peers in one editor surface+- Keep built-in SKILL.md content distinct from database-backed user skills+- Show skills_config as the authoritative enabled/instructions configuration, not a runtime log+- Show the runtime feedback arrow returning to the matching catalogue row+- Use the exact handler/cache/config/runtime labels supplied in the spec+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- generic prompt-engineering imagery+- implying every skill body is eagerly injected into the system prompt+- showing runtime events that contain instruction text or secrets+- merging built-in files and user skills into one storage box+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Master Skill Editor"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Master Skill Editor"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 13-workspace-files: Workspace Files++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Draw a source-backed product-panel schematic of Workspace Files, showing the Gallery panel controls, the WebSocket listing/search path, the HTTP upload/content path, the contained workflow workspace, and the Gallery node’s downstream FileRef output.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Workspace Files header (interface); WorkspaceBrowser (interface); File actions (interface); Node params: path + selection (node params); list_workspace_files (WebSocket); Workspace HTTP routes (HTTP); Workspace listing service (service); Contained workflow workspace (filesystem); Gallery node execution (runtime); Downstream FileRef output (result)+Composition/framing: Use a large operator panel on the left, a two-by-two transport/storage block on the upper right, and a compact workflow execution lane on the lower right. Preserve the visible browser/action split and route listing versus content arrows separately.+Directed relationships:+- workspace-panel-header → workspace-file-actions: "Upload action"+- workspace-browser → workspace-file-actions: "activate, pin, or drag file"+- workspace-browser → list-workspace-files-handler: "browse path or send debounced search" via WebSocket+- list-workspace-files-handler → workspace-listing-service: "directory list or recursive search"+- workspace-listing-service → contained-workspace-root: "contained ls_info / glob_info" via async filesystem+- workspace-file-actions → workspace-http-routes: "upload, preview, or download" via HTTP+- workspace-http-routes → contained-workspace-root: "write upload or stream content"+- workspace-browser → gallery-node-parameters: "navigation writes path"+- workspace-file-actions → gallery-node-parameters: "pinning writes selection"+- gallery-node-parameters → gallery-node-runtime: "run with path / selection"+- gallery-node-runtime → workspace-listing-service: "reuse listing and FileRef conversion"+- gallery-node-runtime → gallery-file-ref-output: "emit selected or listed files"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Workspace Files", "Workspace Files header", "WorkspaceBrowser", "File actions", "Node params: path + selection", "list_workspace_files", "Workspace HTTP routes", "Workspace listing service", "Contained workflow workspace", "Gallery node execution", "Downstream FileRef output", "Upload action", "activate, pin, or drag file", "browse path or send debounced search", "directory list or recursive search", "contained ls_info / glob_info", "upload, preview, or download", "write upload or stream content", "navigation writes path", "pinning writes selection", "run with path / selection", "reuse listing and FileRef conversion", "emit selected or listed files"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Keep WebSocket listing/search separate from HTTP upload/content+- Show path and selection as controlled Gallery node parameters+- Show whole-workspace search, grid/list browsing, polling, preview, pinning, and FileRef drag behavior+- Show the Gallery execution precedence selection > pattern > directory+- Use workspace-relative paths and a single contained workflow workspace+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- generic cloud-drive branding+- implying directories are draggable FileRefs+- showing HTTP as the listing channel+- showing file delete, rename, or move controls that are not implemented+- uncontained host filesystem paths+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Workspace Files"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Workspace Files"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```++## 14-runtime-observability-dock: Runtime Observability Dock++### Dark generation prompt++```text+Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: Draw a source-backed runtime observability schematic of the collapsible Chat / Console dock, showing the three distinct streams—workflow chat, Console-node records, and Terminal server/process logs—from producers and retained state through WebSocketContext into the chat pane and Console/Terminal tabs.+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: Console node output (workflow); Server / process / CLI logs (runtime); chatTrigger consumers (trigger); StatusBroadcaster (event bus); Dock WebSocket handlers (service); Workflow history DB (database); Terminal ring buffer (memory); WebSocketContext state (client state); Chat pane (interface); Console tab (interface); Terminal tab (interface); Persisted dock preferences (local state)+Composition/framing: Use three vertical zones: runtime producers on the left, transport and retained state in the center, and the actual dock on the right. Inside the dock, show a tall Chat pane beside stacked Console and Terminal tab cards, plus a narrow persisted-preferences bar along the bottom.+Directed relationships:+- console-node-producer → status-broadcaster: "broadcast_console_log"+- terminal-log-producers → status-broadcaster: "broadcast_terminal_log"+- status-broadcaster → workflow-history-db: "persist Console records"+- status-broadcaster → terminal-ring-buffer: "retain latest Terminal records"+- dock-ws-handlers → workflow-history-db: "get / clear scoped history"+- dock-ws-handlers → terminal-ring-buffer: "get / clear terminal history"+- dock-ws-handlers → chat-trigger-consumers: "dispatch chat_message_received" via workflow-scoped CloudEvent+- status-broadcaster → websocket-context-state: "live console_log / terminal_log" via WebSocket broadcast+- dock-ws-handlers → websocket-context-state: "hydrate on connect or workflow switch"+- chat-pane → dock-ws-handlers: "send_chat_message / clear chat" via WebSocket request+- websocket-context-state → chat-pane: "chat messages"+- websocket-context-state → console-tab: "Console records"+- websocket-context-state → terminal-tab: "Terminal records"+- dock-preferences → chat-pane: "height + split width + font"+- dock-preferences → terminal-tab: "selected Console / Terminal tab"+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): ["Runtime Observability Dock", "Console node output", "Server / process / CLI logs", "chatTrigger consumers", "StatusBroadcaster", "Dock WebSocket handlers", "Workflow history DB", "Terminal ring buffer", "WebSocketContext state", "Chat pane", "Console tab", "Terminal tab", "Persisted dock preferences", "broadcast_console_log", "broadcast_terminal_log", "persist Console records", "retain latest Terminal records", "get / clear scoped history", "get / clear terminal history", "dispatch chat_message_received", "live console_log / terminal_log", "hydrate on connect or workflow switch", "send_chat_message / clear chat", "chat messages", "Console records", "Terminal records", "height + split width + font", "selected Console / Terminal tab"]+Constraints:+- Mixed product and technical audience; understandable without narration+- 16:9 landscape technical schematic with generous gutters and a clear legend+- Every connector is unidirectional, arrow-headed, and explicitly labelled+- Use only the listed components, relationships, and exact text+- Flat vector-like artwork; crisp rounded cards; no raster screenshots+- Geist-style headings with monospace machine labels+- Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text+- Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations+- Keep workflow Chat, Console-node output, and Terminal logs visibly separate+- Show chat and Console history as workflow-scoped and database-persisted+- Show Terminal history as a global in-memory latest-200 buffer+- Show live broadcasts and reconnect/workflow-switch hydration as separate labelled flows+- Show the actual chat target, Console-node filter, Terminal-level filter, clear controls, and resizable persisted preferences+Avoid:+- photorealism+- people or stock imagery+- 3D or isometric rendering+- glassmorphism or backdrop blur+- rainbow neon or excessive bloom+- full-strength accent backgrounds+- decorative emoji+- sci-fi HUD chrome+- tiny or illegible text+- crossing arrows+- spaghetti topology+- ambiguous bidirectional arrows+- extra boxes, labels, connectors, or logos+- watermarks+- merging Console and Terminal into one undifferentiated log stream+- implying Terminal history is workflow-scoped or database-persisted+- showing a generic monitoring dashboard with charts+- extra tabs beyond Chat, Console, and Terminal+- unlabelled bidirectional connectors+```++### Light-theme edit prompt++```text+Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "Runtime Observability Dock"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.+```++### Targeted repair prompt++```text+Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "Runtime Observability Dock"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.+```diff --git a/docs-internal/diagram-generation/scripts/generate_svgs.py b/docs-internal/diagram-generation/scripts/generate_svgs.pynew file mode 100644index 00000000..50bc125d--- /dev/null+++ b/docs-internal/diagram-generation/scripts/generate_svgs.py@@ -0,0 +1,417 @@+"""Generate the OpenCompany v2 SVG suite, prompt pack, and manifest."""++from __future__ import annotations++import hashlib+import html+import json+from pathlib import Path+from typing import Any+++ROOT = Path(__file__).resolve().parents[3]+WORK = ROOT / "docs-internal" / "diagram-generation"+SPECS = WORK / "specs"+OUT = ROOT / "docs" / "diagrams" / "v2"+SNAPSHOT_COMMIT = "5f7522250eae7b0d02ddfd8ee3740fdf5be4c25e"++THEMES = {+ "dark": {+ "bg": "#0d0f13", "panel": "#15171c", "card": "#1b1e25",+ "text": "#e8eaed", "muted": "#9aa1ac", "border": "#2b2f37",+ "line": "#e8eaed", "label_bg": "#15171c",+ },+ "light": {+ "bg": "#f5f7fa", "panel": "#fafbfc", "card": "#ffffff",+ "text": "#1a1d21", "muted": "#4b5563", "border": "#d1d5db",+ "line": "#374151", "label_bg": "#ffffff",+ },+}++ROLES = {+ "actor": "#f1fa8c", "system": "#bd93f9", "agent": "#bd93f9",+ "model": "#8be9fd", "interface": "#8be9fd", "tool": "#50fa7b",+ "result": "#50fa7b", "trigger": "#ff79c6", "event": "#ff79c6",+ "workflow": "#ffb86c", "runtime": "#ffb86c", "decision": "#ffb86c",+ "data": "#ff79c6", "security": "#f1fa8c", "neutral": "#9aa1ac",+}++COMMON_AVOID = [+ "photorealism", "people or stock imagery", "3D or isometric rendering",+ "glassmorphism or backdrop blur", "rainbow neon or excessive bloom",+ "full-strength accent backgrounds", "decorative emoji", "sci-fi HUD chrome",+ "tiny or illegible text", "crossing arrows", "spaghetti topology",+ "ambiguous bidirectional arrows", "extra boxes, labels, connectors, or logos",+ "watermarks",+]+++def esc(value: Any) -> str:+ return html.escape(str(value), quote=True)+++def load_specs() -> list[dict[str, Any]]:+ specs = [json.loads(path.read_text(encoding="utf-8")) for path in sorted(SPECS.glob("*.json"))]+ ids = [spec["id"] for spec in specs]+ if len(ids) != len(set(ids)):+ raise ValueError("duplicate diagram ids")+ return specs+++def endpoint(box: dict[str, Any], side: str) -> tuple[float, float]:+ x, y, w, h = box["x"], box["y"], box["w"], box["h"]+ return {+ "left": (x, y + h / 2), "right": (x + w, y + h / 2),+ "top": (x + w / 2, y), "bottom": (x + w / 2, y + h),+ }[side]+++def geometry_signature(spec: dict[str, Any]) -> str:+ payload = {key: spec[key] for key in ("groups", "nodes", "relationships", "callouts")}+ return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()[:16]+++def fit_text_attrs(text: str, max_width: float, font_size: float, ratio: float = 0.56) -> str:+ """Keep canonical one-line text inside its allotted box at >=16px."""+ if len(text) * font_size * ratio <= max_width:+ return ""+ return f' textLength="{max_width:.1f}" lengthAdjust="spacingAndGlyphs"'+++def relationship_label_size(rel: dict[str, Any]) -> tuple[float, float]:+ label = str(rel["label"])+ protocol = f'via {rel["protocol"]}' if rel.get("protocol") else ""+ longest_line = max(len(label), len(protocol))+ return min(360, max(120, longest_line * 7.6 + 24)), (48 if protocol else 30)+++def rect_overlap_area(a: tuple[float, float, float, float], b: tuple[float, float, float, float]) -> float:+ ax, ay, aw, ah = a+ bx, by, bw, bh = b+ return max(0.0, min(ax + aw, bx + bw) - max(ax, bx)) * max(0.0, min(ay + ah, by + bh) - max(ay, by))+++def place_relationship_labels(spec: dict[str, Any]) -> dict[str, dict[str, float]]:+ """Nudge label cards away from components and one another.++ Specs provide the semantic anchor. The renderer searches nearby free+ space and adds a subtle leader whenever the readable label card moves.+ """+ obstacles: list[tuple[float, float, float, float]] = [+ (node["x"] - 8, node["y"] - 8, node["w"] + 16, node["h"] + 16)+ for node in spec["nodes"]+ ]+ obstacles.extend(+ (item["x"] - 8, item["y"] - 8, item["w"] + 16, item["h"] + 16)+ for item in spec.get("callouts", [])+ )+ # Keep labels out of diagram and group headings, and above the legend.+ obstacles.append((0, 0, 1920, 116))+ obstacles.append((0, 998, 1920, 82))+ obstacles.extend(+ (+ g["x"] + 10,+ g["y"] + 8,+ min(g["w"] - 20, len(str(g["label"])) * 10 + 40),+ 36,+ )+ for g in spec.get("groups", [])+ )++ placed: list[tuple[float, float, float, float]] = []+ result: dict[str, dict[str, float]] = {}+ dxs = [0, -90, 90, -180, 180, -270, 270, -360, 360, -450, 450]+ dys = [0, -54, 54, -108, 108, -162, 162, -216, 216, -270, 270]+ offsets = sorted(((dx, dy) for dx in dxs for dy in dys), key=lambda p: abs(p[0]) + 1.2 * abs(p[1]))++ for rel in spec.get("relationships", []):+ width, height = relationship_label_size(rel)+ pref_x, pref_y = rel.get("labelAt", [960, 540])+ best: tuple[float, float, float] | None = None+ for dx, dy in offsets:+ cx = min(1908 - width / 2, max(12 + width / 2, pref_x + dx))+ cy = min(990 - height / 2, max(124 + height / 2, pref_y + dy))+ rect = (cx - width / 2, cy - height / 2, width, height)+ overlap = sum(rect_overlap_area(rect, obstacle) for obstacle in obstacles)+ overlap += 2 * sum(rect_overlap_area(rect, previous) for previous in placed)+ distance = abs(cx - pref_x) + 1.2 * abs(cy - pref_y)+ score = overlap * 1000 + distance+ if best is None or score < best[0]:+ best = (score, cx, cy)+ if overlap == 0:+ break+ assert best is not None+ _, cx, cy = best+ rect = (cx - width / 2, cy - height / 2, width, height)+ placed.append(rect)+ obstacles.append(rect)+ result[rel["id"]] = {+ "x": cx, "y": cy, "w": width, "h": height,+ "anchorX": float(pref_x), "anchorY": float(pref_y),+ }+ return result+++def render_group(group: dict[str, Any], theme: dict[str, str]) -> str:+ color = ROLES.get(group.get("role", "neutral"), ROLES["neutral"])+ dash = ' stroke-dasharray="8 7"' if group.get("dash") else ""+ return (+ f'<g data-group-id="{esc(group["id"])}">'+ f'<rect x="{group["x"]}" y="{group["y"]}" width="{group["w"]}" height="{group["h"]}" rx="18" '+ f'fill="{theme["panel"]}" stroke="{color}" stroke-width="2"{dash}/>'+ f'<text x="{group["x"] + 20}" y="{group["y"] + 32}" class="group-label">{esc(group["label"])}</text>'+ '</g>'+ )+++def render_node(node: dict[str, Any], theme: dict[str, str]) -> str:+ color = ROLES.get(node.get("role", "neutral"), ROLES["neutral"])+ x, y, w, h = node["x"], node["y"], node["w"], node["h"]+ labels = node.get("labelLines") or str(node["label"]).split("\n")+ detail = node.get("detail", [])+ parts = [+ f'<g data-component-id="{esc(node["id"])}">',+ f'<title>{esc(node["label"])}</title>',+ f'<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="12" fill="{theme["card"]}" stroke="{color}" stroke-width="2"/>',+ f'<rect x="{x}" y="{y}" width="{w}" height="7" rx="4" fill="{color}"/>',+ f'<text x="{x + 18}" y="{y + 26}" class="type-label"{fit_text_attrs(str(node["type"]).upper(), w - 36, 16, .61)}>{esc(node["type"].upper())}</text>',+ ]+ # The compact cards are intentionally information-dense. These baselines+ # keep one- and two-line labels plus 16px detail text inside 95–155px cards+ # without changing the shared geometry.+ cursor = y + 52+ for line in labels:+ parts.append(f'<text x="{x + 18}" y="{cursor}" class="node-label"{fit_text_attrs(str(line), w - 36, 20)}>{esc(line)}</text>')+ cursor += 22+ cursor += 4+ for line in detail:+ parts.append(f'<text x="{x + 18}" y="{cursor}" class="node-detail"{fit_text_attrs(str(line), w - 36, 16, .54)}>{esc(line)}</text>')+ cursor += 20+ parts.append('</g>')+ return "".join(parts)+++def render_relationship(+ rel: dict[str, Any], boxes: dict[str, dict[str, Any]], theme: dict[str, str],+ placement: dict[str, float],+) -> str:+ start = endpoint(boxes[rel["from"]], rel.get("fromSide", "right"))+ end = endpoint(boxes[rel["to"]], rel.get("toSide", "left"))+ points = [start, *[tuple(p) for p in rel.get("waypoints", [])], end]+ path = " ".join(("M" if idx == 0 else "L") + f" {p[0]} {p[1]}" for idx, p in enumerate(points))+ dash = ' stroke-dasharray="10 8"' if rel.get("style") == "dashed" else ""+ label = rel["label"]+ protocol = f'via {rel["protocol"]}' if rel.get("protocol") else ""+ accessible_label = label + (f' · {protocol}' if protocol else "")+ lx, ly, width, height = placement["x"], placement["y"], placement["w"], placement["h"]+ top = ly - height / 2+ label_fit = fit_text_attrs(label, width - 18, 16)+ protocol_fit = fit_text_attrs(protocol, width - 18, 16, .61)+ text = (+ f'<text x="{lx}" y="{ly - 3}" class="edge-label" text-anchor="middle"{label_fit}>{esc(label)}</text>'+ f'<text x="{lx}" y="{ly + 17}" class="edge-protocol" text-anchor="middle"{protocol_fit}>{esc(protocol)}</text>'+ if protocol else+ f'<text x="{lx}" y="{ly + 3}" class="edge-label" text-anchor="middle"{label_fit}>{esc(label)}</text>'+ )+ moved = abs(lx - placement["anchorX"]) + abs(ly - placement["anchorY"]) > 18+ leader = (+ f'<path d="M {placement["anchorX"]} {placement["anchorY"]} L {lx} {ly}" fill="none" '+ f'stroke="{theme["muted"]}" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/>'+ if moved else ""+ )+ return (+ f'<g data-relationship-id="{esc(rel["id"])}">'+ f'<title>{esc(accessible_label)}</title>'+ f'<path d="{path}" fill="none" stroke="{theme["line"]}" stroke-width="2"{dash} marker-end="url(#arrow)"/>'+ f'{leader}'+ f'<rect x="{lx - width / 2}" y="{top}" width="{width}" height="{height}" rx="7" fill="{theme["label_bg"]}" stroke="{theme["border"]}"/>'+ f'{text}'+ '</g>'+ )+++def render_callout(callout: dict[str, Any], theme: dict[str, str]) -> str:+ x, y, w, h = callout["x"], callout["y"], callout["w"], callout["h"]+ parts = [+ f'<g data-callout-id="{esc(callout["id"])}">',+ f'<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="10" fill="{theme["card"]}" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/>',+ f'<text x="{x + 16}" y="{y + 30}" class="callout-title">{esc(callout["title"])}</text>',+ ]+ cursor = y + 56+ for line in callout.get("lines", []):+ parts.append(f'<text x="{x + 16}" y="{cursor}" class="callout-text"{fit_text_attrs(str(line), w - 32, 16, .54)}>{esc(line)}</text>')+ cursor += 22+ parts.append('</g>')+ return "".join(parts)+++def render_svg(spec: dict[str, Any], theme_name: str) -> str:+ theme = THEMES[theme_name]+ boxes = {item["id"]: item for item in [*spec.get("groups", []), *spec["nodes"]]}+ signature = geometry_signature(spec)+ label_placements = place_relationship_labels(spec)+ body: list[str] = []+ body.extend(render_group(group, theme) for group in spec.get("groups", []))+ body.extend(render_relationship(rel, boxes, theme, label_placements[rel["id"]]) for rel in spec.get("relationships", []))+ body.extend(render_node(node, theme) for node in spec["nodes"])+ body.extend(render_callout(item, theme) for item in spec.get("callouts", []))+ role_labels = [+ ("agent", "Agents / system"), ("model", "Models / interfaces"),+ ("tool", "Tools / results"), ("trigger", "Triggers / events"),+ ("workflow", "Workflow / runtime"), ("security", "Security note"),+ ]+ legend_x = 72+ legend = []+ for role, label in role_labels:+ color = ROLES[role]+ legend.append(f'<circle cx="{legend_x}" cy="1038" r="7" fill="{color}"/><text x="{legend_x + 14}" y="1044" class="legend">{esc(label)}</text>')+ legend_x += 245+ desc = spec["description"] + " Sources: " + "; ".join(ref["path"] for ref in spec["sourceRefs"])+ return f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="{theme_name}" data-geometry-signature="{signature}">+<title id="title">{esc(spec["title"])} — {theme_name} theme</title>+<desc id="desc">{esc(desc)}</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="{theme["line"]}"/></marker>+ <style>+ .title {{ fill:{theme["text"]}; font:700 30px Geist,system-ui,sans-serif; }}+ .subtitle {{ fill:{theme["muted"]}; font:400 18px Geist,system-ui,sans-serif; }}+ .group-label {{ fill:{theme["muted"]}; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }}+ .type-label {{ fill:{theme["muted"]}; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }}+ .node-label {{ fill:{theme["text"]}; font:650 20px Geist,system-ui,sans-serif; }}+ .node-detail {{ fill:{theme["muted"]}; font:400 16px Geist,system-ui,sans-serif; }}+ .edge-label {{ fill:{theme["text"]}; font:500 16px Geist,system-ui,sans-serif; }}+ .edge-protocol {{ fill:{theme["muted"]}; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }}+ .callout-title {{ fill:{theme["text"]}; font:650 18px Geist,system-ui,sans-serif; }}+ .callout-text {{ fill:{theme["muted"]}; font:400 16px Geist,system-ui,sans-serif; }}+ .legend {{ fill:{theme["muted"]}; font:500 16px Geist,system-ui,sans-serif; }}+ </style>+</defs>+<rect width="1920" height="1080" fill="{theme["bg"]}"/>+<text x="72" y="58" class="title">{esc(spec["title"])}</text>+<text x="72" y="91" class="subtitle">{esc(spec["subtitle"])}</text>+{''.join(body)}+<g aria-label="Legend">{''.join(legend)}</g>+</svg>+'''+++def prompt_for(spec: dict[str, Any]) -> str:+ exact = [spec["title"], *[n["label"] for n in spec["nodes"]], *[r["label"] for r in spec["relationships"]]]+ components = "; ".join(f'{n["label"]} ({n["type"]})' for n in spec["nodes"])+ relationships = "\n".join(f'- {r["from"]} → {r["to"]}: "{r["label"]}"' + (f' via {r["protocol"]}' if r.get("protocol") else "") for r in spec["relationships"])+ constraints = [+ "Mixed product and technical audience; understandable without narration",+ "16:9 landscape technical schematic with generous gutters and a clear legend",+ "Every connector is unidirectional, arrow-headed, and explicitly labelled",+ "Use only the listed components, relationships, and exact text",+ "Flat vector-like artwork; crisp rounded cards; no raster screenshots",+ "Geist-style headings with monospace machine labels",+ "Dark OpenCompany palette: #0d0f13 background, #15171c panels, #1b1e25 cards, #e8eaed text",+ "Semantic accents only: purple agents, cyan models/interfaces, green tools/results, pink triggers/events, orange workflows/runtime, yellow annotations",+ *spec["prompt"].get("constraints", []),+ ]+ avoid = [*COMMON_AVOID, *spec["prompt"].get("avoid", [])]+ return f'''Use case: infographic-diagram+Asset type: OpenCompany technical documentation diagram; dark-theme structural draft for later SVG redraw+Audience: mixed product and technical readers+Primary request: {spec["prompt"]["primaryRequest"]}+Scene/backdrop: flat near-black technical canvas; no environment or decorative scene+Subject/components: {components}+Composition/framing: {spec["prompt"]["composition"]}+Directed relationships:+{relationships}+Style/medium: dark technical editorial schematic; flat vector-like infographic; quiet professional workspace wearing restrained neon accents+Text (verbatim): {json.dumps(exact, ensure_ascii=False)}+Constraints:+{chr(10).join(f'- {item}' for item in constraints)}+Avoid:+{chr(10).join(f'- {item}' for item in avoid)}'''+++def light_edit_prompt(spec: dict[str, Any]) -> str:+ return f'''Use case: precise-object-edit+Asset type: light-theme variant of the OpenCompany diagram "{spec["title"]}"+Input images: Image 1: edit target, the approved dark-theme structural draft+Primary request: Change only the theme from canonical OpenCompany dark to canonical OpenCompany light.+Color palette: #f5f7fa canvas, #fafbfc panels, #ffffff cards, #1a1d21 primary text, #4b5563 secondary text, #d1d5db neutral borders. Preserve the semantic accent assignments exactly.+Constraints: preserve every component, label, arrow, arrow direction, connector route, legend item, spacing, alignment, card size, and overall 16:9 composition; change only colors and contrast; no new or removed elements; no watermark.'''+++def repair_prompt(spec: dict[str, Any]) -> str:+ return f'''Use case: precise-object-edit+Asset type: structural repair for the OpenCompany diagram "{spec["title"]}"+Input images: Image 1: edit target, the latest generated draft+Primary request: Correct only the specifically identified missing, extra, or misconnected structural element from the review note.+Constraints: preserve all approved geometry, components, labels, colors, typography, spacing, and connector routes; do not redesign the diagram; do not add unrequested text; no watermark.'''+++def write_prompt_pack(specs: list[dict[str, Any]]) -> None:+ sections = [+ "# OpenCompany GPT Image prompt pack\n",+ "Generated from the source-backed diagram specifications. Use the built-in GPT Image path one asset at a time. Dark drafts are generations; light drafts are edits of their approved dark counterpart. Generated text is non-authoritative—the SVG redraw is canonical.\n",+ ]+ for spec in specs:+ sections.extend([+ f'## {spec["id"]}: {spec["title"]}\n',+ "### Dark generation prompt\n\n```text\n" + prompt_for(spec) + "\n```\n",+ "### Light-theme edit prompt\n\n```text\n" + light_edit_prompt(spec) + "\n```\n",+ "### Targeted repair prompt\n\n```text\n" + repair_prompt(spec) + "\n```\n",+ ])+ (WORK / "prompt-pack.md").write_text("\n".join(sections), encoding="utf-8")+++def write_index(specs: list[dict[str, Any]]) -> None:+ rows = ["# OpenCompany v2 diagrams", "", "Source-backed architecture and product-panel diagrams. Dark and light variants share identical geometry. AI-generated drafts and prompts are retained under `docs-internal/diagram-generation/`.", "", "| Diagram | Dark | Light |", "|---|---|---|"]+ for spec in specs:+ rows.append(f'| {spec["title"]} | [dark](dark/{spec["id"]}.svg) | [light](light/{spec["id"]}.svg) |')+ rows.extend(["", "The six existing public diagrams remain unchanged. These v2 assets are additive until separately approved for public-document replacement.", ""])+ (OUT / "README.md").write_text("\n".join(rows), encoding="utf-8")+++def main() -> None:+ specs = load_specs()+ if len(specs) != 14:+ raise SystemExit(f"expected 14 specs, found {len(specs)}")+ for theme_name in THEMES:+ (OUT / theme_name).mkdir(parents=True, exist_ok=True)+ for spec in specs:+ for theme_name in THEMES:+ (OUT / theme_name / f'{spec["id"]}.svg').write_text(render_svg(spec, theme_name), encoding="utf-8")+ write_prompt_pack(specs)+ write_index(specs)+ drafts = WORK / "drafts"+ manifest = {+ "schemaVersion": 1,+ "sourceSnapshot": {"commit": SNAPSHOT_COMMIT, "description": "See source-snapshot.md"},+ "diagramCount": len(specs),+ "themes": list(THEMES),+ "visualReview": {+ "status": "requires-review",+ "evidence": "docs-internal/diagram-generation/visual-review.md",+ "renderSizes": ["1920x1080", "960x540"],+ "themes": list(THEMES),+ },+ "diagrams": [+ {+ "id": spec["id"], "title": spec["title"], "diagramType": spec["diagramType"],+ "sourceReview": spec.get("sourceReview", "pending"),+ "components": [node["id"] for node in spec["nodes"]],+ "relationships": [rel["id"] for rel in spec["relationships"]],+ "sourceRefs": spec["sourceRefs"],+ "artifacts": {+ theme: {+ "draft": str((drafts / theme / f'{spec["id"]}.png').relative_to(ROOT)).replace("\\", "/"),+ "svg": str((OUT / theme / f'{spec["id"]}.svg').relative_to(ROOT)).replace("\\", "/"),+ "draftPresent": (drafts / theme / f'{spec["id"]}.png').exists(),+ "svgPresent": (OUT / theme / f'{spec["id"]}.svg').exists(),+ } for theme in THEMES+ },+ "validationStatus": "pending",+ } for spec in specs+ ],+ }+ (WORK / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")+++if __name__ == "__main__":+ main()diff --git a/docs-internal/diagram-generation/scripts/validate_svgs.py b/docs-internal/diagram-generation/scripts/validate_svgs.pynew file mode 100644index 00000000..8638dfba--- /dev/null+++ b/docs-internal/diagram-generation/scripts/validate_svgs.py@@ -0,0 +1,126 @@+"""Validate diagram specs, theme parity, SVG accessibility, and raster presence."""++from __future__ import annotations++import json+import struct+import xml.etree.ElementTree as ET+from pathlib import Path+++ROOT = Path(__file__).resolve().parents[3]+WORK = ROOT / "docs-internal" / "diagram-generation"+OUT = ROOT / "docs" / "diagrams" / "v2"+THEMES = ("dark", "light")+NS = {"svg": "http://www.w3.org/2000/svg"}+++def png_size(path: Path) -> tuple[int, int] | None:+ data = path.read_bytes()[:24]+ if len(data) == 24 and data[:8] == b"\x89PNG\r\n\x1a\n":+ return struct.unpack(">II", data[16:24])+ return None+++def validate_spec(spec: dict) -> list[str]:+ errors: list[str] = []+ node_ids = [n["id"] for n in spec["nodes"]]+ group_ids = [g["id"] for g in spec.get("groups", [])]+ if len(node_ids) != len(set(node_ids)):+ errors.append("duplicate component ids")+ known = set(node_ids + group_ids)+ for rel in spec["relationships"]:+ if rel["from"] not in known or rel["to"] not in known:+ errors.append(f'relationship {rel["id"]} references an unknown endpoint')+ if not rel.get("label"):+ errors.append(f'relationship {rel["id"]} has no label')+ if not spec.get("sourceRefs"):+ errors.append("missing source evidence")+ for ref in spec.get("sourceRefs", []):+ if not (ROOT / ref["path"]).exists():+ errors.append(f'missing source path {ref["path"]}')+ return errors+++def validate_svg(spec: dict, theme: str) -> tuple[list[str], str | None]:+ path = OUT / theme / f'{spec["id"]}.svg'+ errors: list[str] = []+ if not path.exists():+ return ["missing SVG"], None+ raw = path.read_text(encoding="utf-8")+ try:+ root = ET.fromstring(raw)+ except ET.ParseError as exc:+ return [f"invalid XML: {exc}"], None+ if root.attrib.get("viewBox") != "0 0 1920 1080":+ errors.append("wrong viewBox")+ if root.find("svg:title", NS) is None or root.find("svg:desc", NS) is None:+ errors.append("missing accessible title or description")+ if root.findall(".//svg:image", NS):+ errors.append("embedded raster image found")+ components = {node.attrib.get("data-component-id") for node in root.findall(".//*[@data-component-id]")}+ relationships = {node.attrib.get("data-relationship-id") for node in root.findall(".//*[@data-relationship-id]")}+ if components != {node["id"] for node in spec["nodes"]}:+ errors.append("component ids differ from spec")+ if relationships != {rel["id"] for rel in spec["relationships"]}:+ errors.append("relationship ids differ from spec")+ all_text = " ".join((node.text or "") for node in root.findall(".//svg:text", NS))+ for node in spec["nodes"]:+ for line in node.get("labelLines") or str(node["label"]).split("\n"):+ if line not in all_text:+ errors.append(f'missing label text: {line}')+ for rel in spec["relationships"]:+ if rel["label"] not in all_text:+ errors.append(f'missing relationship label: {rel["label"]}')+ if "font-size" in raw:+ errors.append("inline font-size found; sizes must stay in the audited style block")+ return errors, root.attrib.get("data-geometry-signature")+++def main() -> None:+ specs = [json.loads(path.read_text(encoding="utf-8")) for path in sorted((WORK / "specs").glob("*.json"))]+ report = {"ok": True, "expectedDiagramCount": 14, "actualDiagramCount": len(specs), "diagrams": []}+ if len(specs) != 14:+ report["ok"] = False+ manifest_path = WORK / "manifest.json"+ manifest = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.exists() else None+ manifest_by_id = {item["id"]: item for item in manifest.get("diagrams", [])} if manifest else {}+ for spec in specs:+ entry = {"id": spec["id"], "errors": validate_spec(spec), "themes": {}}+ signatures = []+ for theme in THEMES:+ svg_errors, signature = validate_svg(spec, theme)+ draft = WORK / "drafts" / theme / f'{spec["id"]}.png'+ draft_error = None+ dimensions = None+ if not draft.exists():+ draft_error = "missing PNG draft"+ else:+ dimensions = png_size(draft)+ if dimensions is None:+ draft_error = "draft is not a valid PNG"+ entry["themes"][theme] = {+ "svgErrors": svg_errors, "geometrySignature": signature,+ "draftError": draft_error, "draftDimensions": dimensions,+ }+ entry["errors"].extend(f"{theme}: {err}" for err in svg_errors)+ if draft_error:+ entry["errors"].append(f"{theme}: {draft_error}")+ signatures.append(signature)+ if len(set(signatures)) != 1:+ entry["errors"].append("dark/light geometry signatures differ")+ entry["ok"] = not entry["errors"]+ report["ok"] = report["ok"] and entry["ok"]+ report["diagrams"].append(entry)+ if spec["id"] in manifest_by_id:+ manifest_by_id[spec["id"]]["validationStatus"] = "validated" if entry["ok"] else "failed"+ (WORK / "validation-report.json").write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")+ if manifest:+ manifest["validationStatus"] = "validated" if report["ok"] else "failed"+ manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")+ if not report["ok"]:+ raise SystemExit("diagram validation failed; see validation-report.json")+++if __name__ == "__main__":+ main()diff --git a/docs-internal/diagram-generation/source-snapshot.md b/docs-internal/diagram-generation/source-snapshot.mdnew file mode 100644index 00000000..4b500590--- /dev/null+++ b/docs-internal/diagram-generation/source-snapshot.md@@ -0,0 +1,33 @@+# Diagram source snapshot++- Captured: `2026-08-04T16:46:54.1938992+05:30`+- Branch: `main` (`ahead 2` of `origin/main`)+- Commit: `5f7522250eae7b0d02ddfd8ee3740fdf5be4c25e`+- Latest relevant commits:+ - `5f752225` — `fix(workflows): stop destroying node config and descriptions on ordinary saves`+ - `9f2dff7c` — `fix(identity): one principal resolver, cron identity + routing, drop dead route`++## Existing working-tree changes++These files were already modified when diagram production began and are user-owned:++- `.opencompany/workflows/AI Employee_example_workflow-1779102911870-cbc76c82.json`+- `server/config/model_registry.json`++The diagrams describe this working tree. Diagram production must not modify, stage, or revert either file.++## Mid-production re-audit++The following user-owned tracked files changed after kickoff and were re-read before final validation:++- `client/src/components/parameterPanel/ContextPanel.tsx`+- `client/src/components/parameterPanel/MemoryToolPanel.tsx`+- `server/nodes/context/_descriptor.py`+- `server/nodes/context/_handlers.py`+- `server/services/temporal/agent_activities.py`+- `server/services/temporal/agent_workflow.py`+- `server/tests/temporal/test_agent_workflow.py`++The Context panel changes make unknown pressure, fidelity, and provider-binding states explicit; the Memory panel removes a duplicated reset-policy control and stops presenting an unknown indexing state as indexed. The Context descriptor now forwards only declared policy fields instead of unrelated legacy node data, and the Context handler scopes journal reads to the active epoch after Reset or Clear while preserving older epochs as archived history. The Temporal changes preserve generation/session scope while walking agent edges and add an idempotent per-iteration operation identifier. These changes reinforce the Context-versus-Memory and agent-runtime semantics already encoded in diagrams 5, 8, and 11; no component or relationship topology changed. They remain user-owned and are excluded from the diagram commit.++Git could not enumerate `.pytest_cache/`, `server/.pytest_cache/`, or `test-temp-v2/` because access was denied. None is a diagram source.diff --git a/docs-internal/diagram-generation/spec.schema.json b/docs-internal/diagram-generation/spec.schema.jsonnew file mode 100644index 00000000..8b91a7ec--- /dev/null+++ b/docs-internal/diagram-generation/spec.schema.json@@ -0,0 +1,91 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://opencompany.sh/schemas/diagram-spec-v1.json",+ "title": "OpenCompany diagram specification",+ "type": "object",+ "required": [+ "id", "title", "subtitle", "category", "diagramType", "description",+ "sourceRefs", "groups", "nodes", "relationships", "callouts", "prompt"+ ],+ "properties": {+ "id": {"type": "string", "pattern": "^[0-9]{2}-[a-z0-9-]+$"},+ "title": {"type": "string"},+ "subtitle": {"type": "string"},+ "category": {"enum": ["architecture", "product-panel"]},+ "diagramType": {"type": "string"},+ "description": {"type": "string"},+ "sourceReview": {"enum": ["reviewed", "pending"]},+ "sourceRefs": {+ "type": "array",+ "minItems": 1,+ "items": {+ "type": "object",+ "required": ["path", "reason"],+ "properties": {"path": {"type": "string"}, "reason": {"type": "string"}}+ }+ },+ "groups": {"type": "array", "items": {"$ref": "#/$defs/box"}},+ "nodes": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/node"}},+ "relationships": {"type": "array", "items": {"$ref": "#/$defs/relationship"}},+ "callouts": {"type": "array", "items": {"$ref": "#/$defs/callout"}},+ "prompt": {+ "type": "object",+ "required": ["primaryRequest", "composition", "constraints", "avoid"],+ "properties": {+ "primaryRequest": {"type": "string"},+ "composition": {"type": "string"},+ "constraints": {"type": "array", "items": {"type": "string"}},+ "avoid": {"type": "array", "items": {"type": "string"}}+ }+ }+ },+ "$defs": {+ "rect": {+ "type": "object",+ "required": ["id", "x", "y", "w", "h"],+ "properties": {+ "id": {"type": "string"}, "x": {"type": "number"}, "y": {"type": "number"},+ "w": {"type": "number"}, "h": {"type": "number"}+ }+ },+ "box": {+ "allOf": [+ {"$ref": "#/$defs/rect"},+ {"type": "object", "required": ["label", "role"], "properties": {+ "label": {"type": "string"}, "role": {"type": "string"}, "dash": {"type": "boolean"}+ }}+ ]+ },+ "node": {+ "allOf": [+ {"$ref": "#/$defs/rect"},+ {"type": "object", "required": ["label", "type", "role"], "properties": {+ "label": {"type": "string"}, "labelLines": {"type": "array", "items": {"type": "string"}},+ "type": {"type": "string"}, "role": {"type": "string"},+ "detail": {"type": "array", "items": {"type": "string"}}+ }}+ ]+ },+ "relationship": {+ "type": "object",+ "required": ["id", "from", "to", "label"],+ "properties": {+ "id": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"},+ "label": {"type": "string"}, "protocol": {"type": "string"},+ "style": {"enum": ["solid", "dashed"]},+ "fromSide": {"enum": ["left", "right", "top", "bottom"]},+ "toSide": {"enum": ["left", "right", "top", "bottom"]},+ "waypoints": {"type": "array", "items": {"type": "array", "prefixItems": [{"type": "number"}, {"type": "number"}], "minItems": 2, "maxItems": 2}},+ "labelAt": {"type": "array", "prefixItems": [{"type": "number"}, {"type": "number"}], "minItems": 2, "maxItems": 2}+ }+ },+ "callout": {+ "allOf": [+ {"$ref": "#/$defs/rect"},+ {"type": "object", "required": ["title", "lines"], "properties": {+ "title": {"type": "string"}, "lines": {"type": "array", "items": {"type": "string"}}+ }}+ ]+ }+ }+}diff --git a/docs-internal/diagram-generation/specs/01-system-context.json b/docs-internal/diagram-generation/specs/01-system-context.jsonnew file mode 100644index 00000000..d41c9ab9--- /dev/null+++ b/docs-internal/diagram-generation/specs/01-system-context.json@@ -0,0 +1,48 @@+{+ "id": "01-system-context",+ "title": "OpenCompany System Context",+ "subtitle": "Who uses the system and which external capabilities it orchestrates",+ "category": "architecture",+ "diagramType": "C4 system context",+ "description": "A C4-style system context view of OpenCompany as an automation workspace between human users and external model, productivity, messaging, device, developer, and retrieval services.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "README.md", "reason": "Product scope, workflow-builder positioning, supported integrations, and user-facing capabilities."},+ {"path": "server/nodes/groups.py", "reason": "Canonical node families that establish the external capability categories."},+ {"path": "server/config/credential_providers.json", "reason": "Configured provider catalogue for model, productivity, messaging, search, and developer integrations."},+ {"path": "server/main.py", "reason": "Authoritative application boundary and exposed HTTP, WebSocket, webhook, and MCP surfaces."}+ ],+ "groups": [+ {"id": "opencompany-boundary", "label": "OPENCOMPANY SYSTEM BOUNDARY", "role": "system", "x": 420, "y": 145, "w": 930, "h": 800}+ ],+ "nodes": [+ {"id": "workflow-authors", "label": "Workflow authors", "type": "person", "role": "actor", "x": 55, "y": 265, "w": 285, "h": 125, "detail": ["Build and test automations"]},+ {"id": "workflow-operators", "label": "Workflow operators", "type": "person", "role": "actor", "x": 55, "y": 640, "w": 285, "h": 125, "detail": ["Deploy and supervise runs"]},+ {"id": "opencompany", "label": "OpenCompany", "type": "software system", "role": "system", "x": 665, "y": 385, "w": 440, "h": 205, "detail": ["Visual workflow workspace", "Agents, tools, triggers and durable runs"]},+ {"id": "llm-providers", "label": "LLM providers", "type": "external system", "role": "model", "x": 1480, "y": 130, "w": 365, "h": 105, "detail": ["Hosted and local inference"]},+ {"id": "productivity-services", "label": "Productivity services", "type": "external system", "role": "tool", "x": 1480, "y": 275, "w": 365, "h": 105, "detail": ["Mail, calendar, docs and CRM"]},+ {"id": "messaging-channels", "label": "Messaging channels", "type": "external system", "role": "tool", "x": 1480, "y": 420, "w": 365, "h": 105, "detail": ["Chat and social platforms"]},+ {"id": "connected-devices", "label": "Connected devices", "type": "external system", "role": "tool", "x": 1480, "y": 565, "w": 365, "h": 105, "detail": ["Android and device services"]},+ {"id": "developer-services", "label": "Developer services", "type": "external system", "role": "interface", "x": 1480, "y": 710, "w": 365, "h": 105, "detail": ["Code, CLI and MCP tools"]},+ {"id": "search-vector-stores", "label": "Search and vector stores", "labelLines": ["Search and", "vector stores"], "type": "external system", "role": "data", "x": 1480, "y": 855, "w": 365, "h": 110, "detail": ["Retrieval and knowledge indexes"]}+ ],+ "relationships": [+ {"id": "r-authors-design", "from": "workflow-authors", "to": "opencompany", "label": "Design and run automations", "protocol": "Browser UI / CLI", "fromSide": "right", "toSide": "left", "waypoints": [[510, 327], [510, 445]], "labelAt": [500, 365]},+ {"id": "r-operators-control", "from": "workflow-operators", "to": "opencompany", "label": "Control deployed workflows", "protocol": "Browser UI / WebSocket", "fromSide": "right", "toSide": "left", "waypoints": [[535, 702], [535, 535]], "labelAt": [505, 665]},+ {"id": "r-opencompany-llm", "from": "opencompany", "to": "llm-providers", "label": "Requests inference", "protocol": "Provider SDK / HTTPS", "fromSide": "right", "toSide": "left", "waypoints": [[1210, 487], [1210, 182]], "labelAt": [1325, 182]},+ {"id": "r-opencompany-productivity", "from": "opencompany", "to": "productivity-services", "label": "Reads and updates work", "protocol": "OAuth / HTTPS", "fromSide": "right", "toSide": "left", "waypoints": [[1240, 487], [1240, 327]], "labelAt": [1350, 327]},+ {"id": "r-opencompany-messaging", "from": "opencompany", "to": "messaging-channels", "label": "Sends and receives messages", "protocol": "Webhooks / RPC", "fromSide": "right", "toSide": "left", "waypoints": [[1270, 487], [1270, 472]], "labelAt": [1365, 472]},+ {"id": "r-opencompany-devices", "from": "opencompany", "to": "connected-devices", "label": "Invokes device actions", "protocol": "RPC / platform APIs", "fromSide": "right", "toSide": "left", "waypoints": [[1270, 487], [1270, 617]], "labelAt": [1360, 617]},+ {"id": "r-opencompany-developer", "from": "opencompany", "to": "developer-services", "label": "Uses code and dev tools", "protocol": "MCP / CLI / HTTPS", "fromSide": "right", "toSide": "left", "waypoints": [[1240, 487], [1240, 762]], "labelAt": [1350, 762]},+ {"id": "r-opencompany-search", "from": "opencompany", "to": "search-vector-stores", "label": "Indexes and retrieves knowledge", "protocol": "HTTPS / vector API", "fromSide": "right", "toSide": "left", "waypoints": [[1210, 487], [1210, 910]], "labelAt": [1340, 910]}+ ],+ "callouts": [+ {"id": "system-purpose", "title": "System responsibility", "x": 615, "y": 700, "w": 540, "h": 135, "lines": ["Compose external capabilities as directed graphs.", "Keep execution, credentials and observability", "inside one user-scoped workspace."]}+ ],+ "prompt": {+ "primaryRequest": "Create a precise C4 system-context diagram with OpenCompany centered inside a clearly labelled system boundary, two human actor cards on the left, and six external-system cards stacked on the right.",+ "composition": "Left-to-right context map. Keep OpenCompany visually dominant in the middle. Route the two inbound human relationships into the left edge of OpenCompany and fan six labelled outbound relationships to a clean right-hand stack. Put the system-responsibility note beneath the central card.",+ "constraints": ["Treat OpenCompany as one software system at this abstraction level", "Show no internal containers or databases", "Keep all external systems outside the OpenCompany boundary"],+ "avoid": ["vendor logos", "unlisted integrations", "internal microservice detail", "bidirectional arrows"]+ }+}diff --git a/docs-internal/diagram-generation/specs/02-runtime-trust-topology.json b/docs-internal/diagram-generation/specs/02-runtime-trust-topology.jsonnew file mode 100644index 00000000..05cb26ee--- /dev/null+++ b/docs-internal/diagram-generation/specs/02-runtime-trust-topology.json@@ -0,0 +1,66 @@+{+ "id": "02-runtime-trust-topology",+ "title": "Runtime and Trust Topology",+ "subtitle": "Development and production paths, authenticated surfaces, durable orchestration and lazy helpers",+ "category": "architecture",+ "diagramType": "C4 container and deployment hybrid",+ "description": "A runtime topology that distinguishes the browser and CLI clients, Vite development proxy, FastAPI application, protected and restricted protocol surfaces, Temporal orchestration, and lazily started helper processes.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": ".env.template", "reason": "Canonical service port block: app 5678, development backend 5679, Temporal UI/gRPC 5680/5681, Node.js 5682, WhatsApp 5683."},+ {"path": "client/vite.config.js", "reason": "Same-origin development topology and proxy prefixes from Vite 5678 to Uvicorn 5679."},+ {"path": "server/main.py", "reason": "FastAPI lifespan, routers, webhook route, MCP mount, lazy service startup, and production SPA serving."},+ {"path": "server/middleware/auth.py", "reason": "Authentication exclusions and separate protection for public webhooks, internal WebSocket, and MCP."},+ {"path": "server/routers/websocket.py", "reason": "Canonical /ws/status and /ws/internal endpoints and authenticated status-socket identity."},+ {"path": "server/services/authz/ws_surface.py", "reason": "Restricted /ws/internal handler allowlist and internal-only payload identity rule."},+ {"path": "server/services/cli_agent/mcp_server.py", "reason": "Per-batch bearer authentication and MCP-over-HTTP server surface."},+ {"path": "server/services/temporal/lifecycle.py", "reason": "Temporal client and worker lifecycle wiring."},+ {"path": "server/nodes/code/_runtime.py", "reason": "Lazy Node.js executor runtime configuration."}+ ],+ "groups": [+ {"id": "client-zone", "label": "CLIENTS AND PUBLIC SENDERS", "role": "actor", "x": 40, "y": 135, "w": 350, "h": 830},+ {"id": "app-zone", "label": "OPENCOMPANY APPLICATION", "role": "system", "x": 425, "y": 135, "w": 1050, "h": 830},+ {"id": "runtime-zone", "label": "DURABLE AND LAZY RUNTIMES", "role": "runtime", "x": 1510, "y": 135, "w": 370, "h": 830}+ ],+ "nodes": [+ {"id": "browser-spa", "label": "Browser SPA", "type": "client", "role": "actor", "x": 70, "y": 215, "w": 290, "h": 115, "detail": ["React workflow workspace"]},+ {"id": "opencompany-cli", "label": "OpenCompany CLI", "type": "client", "role": "actor", "x": 70, "y": 470, "w": 290, "h": 115, "detail": ["Typer launcher and agent client"]},+ {"id": "webhook-senders", "label": "Webhook senders", "type": "external", "role": "trigger", "x": 70, "y": 735, "w": 290, "h": 115, "detail": ["Provider callbacks"]},+ {"id": "vite-dev", "label": "Vite development server", "labelLines": ["Vite development", "server"], "type": "container", "role": "interface", "x": 455, "y": 190, "w": 280, "h": 135, "detail": ["Port 5678 · development only"]},+ {"id": "fastapi-app", "label": "FastAPI application", "type": "container", "role": "system", "x": 820, "y": 190, "w": 300, "h": 135, "detail": ["5679 dev · 5678 production"]},+ {"id": "rest-surface", "label": "Protected REST API", "type": "interface", "role": "interface", "x": 455, "y": 400, "w": 280, "h": 120, "detail": ["Authenticated /api routes"]},+ {"id": "status-socket", "label": "/ws/status", "type": "websocket", "role": "interface", "x": 820, "y": 400, "w": 280, "h": 120, "detail": ["Cookie-derived user identity"]},+ {"id": "internal-socket", "label": "/ws/internal", "type": "websocket", "role": "security", "x": 1165, "y": 400, "w": 280, "h": 120, "detail": ["Local allowlist · payload identity"]},+ {"id": "mcp-surface", "label": "/mcp/ide/mcp", "type": "MCP endpoint", "role": "security", "x": 455, "y": 655, "w": 280, "h": 120, "detail": ["Per-batch bearer token"]},+ {"id": "webhook-ingress", "label": "/webhook/*", "type": "HTTP ingress", "role": "trigger", "x": 820, "y": 655, "w": 280, "h": 120, "detail": ["Public route · provider verification"]},+ {"id": "production-spa", "label": "Production SPA assets", "type": "static content", "role": "interface", "x": 1165, "y": 655, "w": 280, "h": 120, "detail": ["Served by FastAPI"]},+ {"id": "temporal-runtime", "label": "Temporal server and worker", "labelLines": ["Temporal server", "and worker"], "type": "durable runtime", "role": "workflow", "x": 1540, "y": 210, "w": 310, "h": 145, "detail": ["UI 5680 · gRPC 5681"]},+ {"id": "nodejs-sidecar", "label": "Node.js executor", "type": "lazy sidecar", "role": "runtime", "x": 1540, "y": 475, "w": 310, "h": 125, "detail": ["HTTP · port 5682"]},+ {"id": "whatsapp-sidecar", "label": "WhatsApp RPC", "type": "lazy sidecar", "role": "runtime", "x": 1540, "y": 735, "w": 310, "h": 125, "detail": ["RPC · port 5683"]}+ ],+ "relationships": [+ {"id": "r-browser-vite", "from": "browser-spa", "to": "vite-dev", "label": "Loads SPA in development", "protocol": "HTTP :5678", "fromSide": "right", "toSide": "left", "labelAt": [405, 238]},+ {"id": "r-vite-fastapi", "from": "vite-dev", "to": "fastapi-app", "label": "Proxies /api /ws /webhook /health /mcp", "protocol": "HTTP / WS :5679", "fromSide": "right", "toSide": "left", "labelAt": [780, 340]},+ {"id": "r-cli-fastapi", "from": "opencompany-cli", "to": "fastapi-app", "label": "Launches and administers", "protocol": "Typer / process", "fromSide": "right", "toSide": "left", "waypoints": [[405, 527], [405, 365], [790, 365], [790, 257]], "labelAt": [590, 365]},+ {"id": "r-browser-rest", "from": "browser-spa", "to": "rest-surface", "label": "Calls protected routes", "protocol": "HTTPS + JWT cookie", "fromSide": "right", "toSide": "left", "waypoints": [[405, 272], [405, 460]], "labelAt": [405, 395]},+ {"id": "r-browser-status", "from": "browser-spa", "to": "status-socket", "label": "Commands and receives status", "protocol": "WebSocket + cookie", "fromSide": "right", "toSide": "left", "waypoints": [[400, 272], [400, 580], [780, 580], [780, 460]], "labelAt": [585, 580]},+ {"id": "r-cli-mcp", "from": "opencompany-cli", "to": "mcp-surface", "label": "Invokes scoped tools", "protocol": "MCP over HTTP + Bearer", "fromSide": "right", "toSide": "left", "waypoints": [[405, 527], [405, 715]], "labelAt": [405, 635]},+ {"id": "r-webhook-ingress", "from": "webhook-senders", "to": "webhook-ingress", "label": "Delivers provider events", "protocol": "HTTPS webhook", "fromSide": "right", "toSide": "left", "labelAt": [585, 815]},+ {"id": "r-surfaces-app", "from": "rest-surface", "to": "fastapi-app", "label": "Dispatches request", "protocol": "ASGI", "fromSide": "top", "toSide": "bottom", "waypoints": [[595, 365], [970, 365]], "labelAt": [785, 365]},+ {"id": "r-status-app", "from": "status-socket", "to": "fastapi-app", "label": "Dispatches authenticated message", "protocol": "ASGI WebSocket", "fromSide": "top", "toSide": "bottom", "labelAt": [970, 365]},+ {"id": "r-temporal-internal", "from": "temporal-runtime", "to": "internal-socket", "label": "Calls legacy node handlers", "protocol": "WebSocket", "style": "dashed", "fromSide": "left", "toSide": "right", "waypoints": [[1500, 282], [1500, 460]], "labelAt": [1500, 390]},+ {"id": "r-fastapi-temporal", "from": "fastapi-app", "to": "temporal-runtime", "label": "Starts workflows and polls tasks", "protocol": "Temporal gRPC :5681", "fromSide": "right", "toSide": "left", "labelAt": [1325, 255]},+ {"id": "r-fastapi-nodejs", "from": "fastapi-app", "to": "nodejs-sidecar", "label": "Starts on demand and executes JavaScript", "protocol": "HTTP :5682", "fromSide": "right", "toSide": "left", "waypoints": [[1485, 257], [1485, 537]], "labelAt": [1390, 537]},+ {"id": "r-fastapi-whatsapp", "from": "fastapi-app", "to": "whatsapp-sidecar", "label": "Starts on demand and sends commands", "protocol": "RPC :5683", "fromSide": "right", "toSide": "left", "waypoints": [[1460, 257], [1460, 797]], "labelAt": [1395, 797]},+ {"id": "r-fastapi-spa", "from": "fastapi-app", "to": "production-spa", "label": "Serves production fallback", "protocol": "StaticFiles / HTML", "fromSide": "bottom", "toSide": "top", "waypoints": [[970, 605], [1305, 605]], "labelAt": [1140, 605]}+ ],+ "callouts": [+ {"id": "trust-rules", "title": "Trust rules", "x": 535, "y": 795, "w": 835, "h": 155, "lines": ["REST and /ws/status use authenticated server-owned identity.", "/ws/internal is local-only, unauthenticated, and restricted to", "execute_node, execute_ai_node, and ping.", "/mcp/ide/mcp uses a short-lived per-batch Bearer token;", "/webhook/* verifies provider signatures where configured."]}+ ],+ "prompt": {+ "primaryRequest": "Draw a deployment-aware runtime and trust topology for OpenCompany, showing clients on the left, the application and its security surfaces in the center, and Temporal plus lazy helper runtimes on the right.",+ "composition": "Use three vertical trust zones. Place Vite and FastAPI high in the application zone, API and WebSocket surfaces in the middle, MCP/webhook/static surfaces below, and the trust-rules note at the bottom. Clearly distinguish development proxying from production SPA serving.",+ "constraints": ["Show exact ports 5678, 5679, 5680, 5681, 5682 and 5683 only where specified", "Use a dashed line only for the legacy Temporal-to-/ws/internal path", "Make public, authenticated, bearer-scoped and internal-restricted boundaries visually distinct"],+ "avoid": ["Docker or Kubernetes assumptions", "microservices not present in the repository", "a public /ws/internal interpretation", "a removed /api/workflow/execute-node route"]+ }+}diff --git a/docs-internal/diagram-generation/specs/03-workflow-execution-routing.json b/docs-internal/diagram-generation/specs/03-workflow-execution-routing.jsonnew file mode 100644index 00000000..e44e9520--- /dev/null+++ b/docs-internal/diagram-generation/specs/03-workflow-execution-routing.json@@ -0,0 +1,62 @@+{+ "id": "03-workflow-execution-routing",+ "title": "Workflow Execution Routing",+ "subtitle": "Single-node requests and whole-graph runs converge on the same plugin execution pipeline",+ "category": "architecture",+ "diagramType": "C4 dynamic flow",+ "description": "A directed execution flow covering direct single-node execution, the WorkflowService routing decision, Temporal, Redis-backed parallel, and sequential orchestration paths, plus the canonical NodeExecutor pipeline and status persistence.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "server/services/workflow.py", "reason": "Authoritative single-node adapter and Temporal, Redis-parallel, sequential routing decision."},+ {"path": "server/services/node_executor.py", "reason": "Canonical parameter preparation, template resolution, plugin dispatch, and output storage pipeline."},+ {"path": "server/services/execution/executor.py", "reason": "In-process graph orchestration, dependency scheduling, retries, and node callback contract."},+ {"path": "server/services/temporal/executor.py", "reason": "Temporal graph execution adapter and durable workflow start path."},+ {"path": "server/services/temporal/workflow.py", "reason": "Durable graph workflow and activity routing."},+ {"path": "server/services/status_broadcaster.py", "reason": "Per-workflow execution and node status broadcasts."},+ {"path": "server/routers/workflow.py", "reason": "Internal Temporal node-execution endpoint still present in the current route surface."},+ {"path": "server/routers/websocket.py", "reason": "Interactive execute_node and execute_ai_node entry points."}+ ],+ "groups": [+ {"id": "entry-zone", "label": "ENTRY", "role": "interface", "x": 45, "y": 150, "w": 300, "h": 790},+ {"id": "routing-zone", "label": "GRAPH ORCHESTRATION", "role": "workflow", "x": 385, "y": 150, "w": 775, "h": 790},+ {"id": "node-pipeline-zone", "label": "NODEEXECUTOR PIPELINE", "role": "runtime", "x": 1200, "y": 150, "w": 675, "h": 790}+ ],+ "nodes": [+ {"id": "single-node-request", "label": "Single-node request", "type": "entry point", "role": "interface", "x": 75, "y": 250, "w": 240, "h": 125, "detail": ["WebSocket or internal REST"]},+ {"id": "whole-workflow-request", "label": "Whole-workflow run", "type": "entry point", "role": "interface", "x": 75, "y": 625, "w": 240, "h": 125, "detail": ["Interactive or deployed"]},+ {"id": "routing-decision", "label": "WorkflowService routing", "type": "decision", "role": "decision", "x": 455, "y": 250, "w": 300, "h": 145, "detail": ["Temporal → parallel → sequential"]},+ {"id": "temporal-branch", "label": "Temporal branch", "type": "durable orchestrator", "role": "workflow", "x": 820, "y": 205, "w": 285, "h": 125, "detail": ["Temporal executor is wired"]},+ {"id": "redis-parallel-branch", "label": "Redis-parallel branch", "labelLines": ["Redis-parallel", "branch"], "type": "graph orchestrator", "role": "workflow", "x": 820, "y": 420, "w": 285, "h": 145, "detail": ["WorkflowExecutor"]},+ {"id": "sequential-branch", "label": "Sequential fallback", "type": "graph orchestrator", "role": "workflow", "x": 820, "y": 680, "w": 285, "h": 125, "detail": ["Topological loop"]},+ {"id": "parameter-preparation", "label": "Prepare parameters", "type": "pipeline stage", "role": "runtime", "x": 1240, "y": 195, "w": 285, "h": 125, "detail": ["DB defaults + request overrides", "Pydantic Params + credentials"]},+ {"id": "template-resolution", "label": "Resolve templates", "type": "pipeline stage", "role": "runtime", "x": 1560, "y": 195, "w": 275, "h": 125, "detail": ["Graph and upstream outputs"]},+ {"id": "plugin-dispatch", "label": "Dispatch plugin operation", "labelLines": ["Dispatch plugin", "operation"], "type": "pipeline stage", "role": "tool", "x": 1240, "y": 455, "w": 285, "h": 145, "detail": ["Node registry handler"]},+ {"id": "validated-result", "label": "Validated execution result", "labelLines": ["Validated execution", "result"], "type": "pipeline stage", "role": "result", "x": 1560, "y": 455, "w": 275, "h": 145, "detail": ["Success or typed error"]},+ {"id": "output-store", "label": "Output store", "type": "persistence", "role": "data", "x": 1240, "y": 745, "w": 285, "h": 125, "detail": ["output_main / top / 0"]},+ {"id": "status-broadcast", "label": "Status broadcasts", "type": "observable result", "role": "result", "x": 1560, "y": 745, "w": 275, "h": 125, "detail": ["Per-workflow WebSocket stream"]}+ ],+ "relationships": [+ {"id": "r-single-pipeline", "from": "single-node-request", "to": "parameter-preparation", "label": "Executes directly", "protocol": "WorkflowService.execute_node", "fromSide": "right", "toSide": "left", "waypoints": [[360, 312], [360, 120], [1180, 120], [1180, 257]], "labelAt": [780, 120]},+ {"id": "r-whole-routing", "from": "whole-workflow-request", "to": "routing-decision", "label": "Submits nodes, edges and identity", "protocol": "WorkflowService.execute_workflow", "fromSide": "right", "toSide": "left", "waypoints": [[365, 687], [365, 322]], "labelAt": [365, 505]},+ {"id": "r-routing-temporal", "from": "routing-decision", "to": "temporal-branch", "label": "Chooses when requested and wired", "protocol": "Temporal", "fromSide": "right", "toSide": "left", "labelAt": [790, 235]},+ {"id": "r-routing-parallel", "from": "routing-decision", "to": "redis-parallel-branch", "label": "Else chooses when parallel and Redis enabled", "protocol": "in-process + Redis", "fromSide": "right", "toSide": "left", "waypoints": [[785, 322], [785, 492]], "labelAt": [790, 405]},+ {"id": "r-routing-sequential", "from": "routing-decision", "to": "sequential-branch", "label": "Otherwise falls back", "protocol": "in-process", "fromSide": "right", "toSide": "left", "waypoints": [[785, 322], [785, 742]], "labelAt": [790, 640]},+ {"id": "r-temporal-node", "from": "temporal-branch", "to": "parameter-preparation", "label": "Schedules node activities", "protocol": "Temporal task queue", "fromSide": "right", "toSide": "left", "labelAt": [1170, 225]},+ {"id": "r-parallel-node", "from": "redis-parallel-branch", "to": "parameter-preparation", "label": "Calls node adapter with retries", "protocol": "async callback", "fromSide": "right", "toSide": "left", "waypoints": [[1170, 492], [1170, 257]], "labelAt": [1170, 385]},+ {"id": "r-sequential-node", "from": "sequential-branch", "to": "parameter-preparation", "label": "Calls each ready node", "protocol": "await", "fromSide": "right", "toSide": "left", "waypoints": [[1170, 742], [1170, 257]], "labelAt": [1170, 650]},+ {"id": "r-prepare-resolve", "from": "parameter-preparation", "to": "template-resolution", "label": "Passes validated parameters", "protocol": "Python dict", "fromSide": "right", "toSide": "left", "labelAt": [1542, 347]},+ {"id": "r-resolve-dispatch", "from": "template-resolution", "to": "plugin-dispatch", "label": "Builds handler context", "protocol": "NodeContext", "fromSide": "bottom", "toSide": "top", "waypoints": [[1697, 380], [1382, 380]], "labelAt": [1540, 380]},+ {"id": "r-dispatch-result", "from": "plugin-dispatch", "to": "validated-result", "label": "Returns standardized result", "protocol": "ExecutionResult", "fromSide": "right", "toSide": "left", "labelAt": [1542, 665]},+ {"id": "r-result-store", "from": "validated-result", "to": "output-store", "label": "Persists successful outputs", "protocol": "database callback", "fromSide": "bottom", "toSide": "top", "waypoints": [[1697, 680], [1382, 680]], "labelAt": [1540, 680]},+ {"id": "r-store-broadcast", "from": "output-store", "to": "status-broadcast", "label": "Publishes execution state", "protocol": "WebSocket broadcast", "fromSide": "right", "toSide": "left", "labelAt": [1542, 925]}+ ],+ "callouts": [+ {"id": "routing-invariant", "title": "Routing invariant", "x": 455, "y": 830, "w": 650, "h": 110, "lines": ["Temporal requested but not wired logs an error, then falls through.", "The next eligible path is Redis-parallel or sequential.", "Every branch invokes WorkflowService.execute_node → NodeExecutor."]}+ ],+ "prompt": {+ "primaryRequest": "Create a source-accurate dynamic execution-routing diagram showing a direct single-node path, a whole-workflow routing decision with three ordered branches, and a shared six-stage NodeExecutor pipeline.",+ "composition": "Use three vertical bands: entries, graph orchestration, and NodeExecutor pipeline. Put the direct single-node connector above the graph router. Stack Temporal, Redis-parallel, and sequential branches in priority order. Arrange the pipeline as a compact two-column serpentine flow ending in output storage and status broadcasts.",+ "constraints": ["Preserve the routing precedence Temporal requested+wired, else parallel+Redis, else sequential", "Show that the single-node request bypasses graph routing", "Show all graph branches converging on the same NodeExecutor pipeline"],+ "avoid": ["claiming Redis is the executor itself", "claiming Temporal is always mandatory", "a removed public execute-node REST route", "parallel arrows without labels"]+ }+}diff --git a/docs-internal/diagram-generation/specs/04-durable-deployment-events.json b/docs-internal/diagram-generation/specs/04-durable-deployment-events.jsonnew file mode 100644index 00000000..10d85974--- /dev/null+++ b/docs-internal/diagram-generation/specs/04-durable-deployment-events.json@@ -0,0 +1,67 @@+{+ "id": "04-durable-deployment-events",+ "title": "Durable Deployment and Events",+ "subtitle": "Generation snapshots, trigger admission, controller signals and child workflow runs",+ "category": "architecture",+ "diagramType": "C4 dynamic and event flow",+ "description": "A deployment lifecycle and event-flow view showing Start/Pause/Resume/Reset controls, immutable per-generation graph snapshots, the long-lived WorkflowControlWorkflow, push/poll/cron trigger paths, CloudEvents dispatch, and child graph execution.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "server/services/deployment/handlers.py", "reason": "Start, pause, resume, reset handlers, controller start/rebuild, signals, schedules, trigger state, and cleanup."},+ {"path": "server/services/deployment/control.py", "reason": "Revision-guarded generation allocation and sanitized immutable graph_snapshot rows."},+ {"path": "server/services/deployment/triggers.py", "reason": "Trigger preparation and push/poll registration contracts."},+ {"path": "server/services/temporal/workflow_control_workflow.py", "reason": "Long-lived controller, pause/resume/reset, trigger registration, event queue, poll loops, child spawning, and continue-as-new."},+ {"path": "server/services/events/envelope.py", "reason": "CloudEvents v1.0 WorkflowEvent envelope."},+ {"path": "server/services/events/dispatch.py", "reason": "Event-to-controller dispatch using Temporal visibility and on_event signals."},+ {"path": "server/services/temporal/schedules.py", "reason": "Durable cron schedule creation, pause/unpause, ownership and cleanup."},+ {"path": "server/nodes/scheduler/cron_scheduler/_workflow.py", "reason": "Cron action workflow that launches the snapshotted graph run."},+ {"path": "server/services/workflow.py", "reason": "Local deployment admission and legacy fallback state."}+ ],+ "groups": [+ {"id": "control-plane", "label": "DEPLOYMENT CONTROL PLANE", "role": "security", "x": 45, "y": 145, "w": 610, "h": 815},+ {"id": "trigger-plane", "label": "TRIGGER AND EVENT PLANE", "role": "trigger", "x": 690, "y": 145, "w": 710, "h": 815},+ {"id": "execution-plane", "label": "DURABLE EXECUTION", "role": "workflow", "x": 1435, "y": 145, "w": 440, "h": 815}+ ],+ "nodes": [+ {"id": "lifecycle-controls", "label": "Start · Pause · Resume · Reset", "labelLines": ["Start · Pause", "Resume · Reset"], "type": "operator controls", "role": "actor", "x": 80, "y": 205, "w": 260, "h": 140, "detail": ["Revision-aware commands"]},+ {"id": "workflow-control-service", "label": "WorkflowControlService", "type": "control service", "role": "security", "x": 370, "y": 205, "w": 250, "h": 140, "detail": ["CAS lifecycle transitions"]},+ {"id": "generation-snapshot", "label": "Generation control row", "labelLines": ["Generation control", "row"], "type": "durable data", "role": "data", "x": 80, "y": 485, "w": 260, "h": 155, "detail": ["graph_snapshot + owner_id", "generation + revision"]},+ {"id": "controller", "label": "WorkflowControlWorkflow", "labelLines": ["WorkflowControl", "Workflow"], "type": "long-lived workflow", "role": "workflow", "x": 370, "y": 485, "w": 250, "h": 155, "detail": ["Signals, poll loops, event queue", "continue-as-new"]},+ {"id": "local-runtime-state", "label": "Local admission state", "type": "process projection", "role": "runtime", "x": 215, "y": 775, "w": 280, "h": 120, "detail": ["running / paused projection"]},+ {"id": "push-trigger", "label": "Push trigger", "type": "trigger definition", "role": "trigger", "x": 730, "y": 205, "w": 190, "h": 115, "detail": ["Webhook or platform event"]},+ {"id": "poll-trigger", "label": "Poll trigger", "type": "trigger definition", "role": "trigger", "x": 950, "y": 205, "w": 190, "h": 115, "detail": ["Controller timer + activity"]},+ {"id": "cron-trigger", "label": "Cron trigger", "type": "trigger definition", "role": "trigger", "x": 1170, "y": 205, "w": 190, "h": 115, "detail": ["Temporal Schedule"]},+ {"id": "cloudevent", "label": "WorkflowEvent", "type": "CloudEvents 1.0", "role": "event", "x": 730, "y": 455, "w": 250, "h": 130, "detail": ["id · source · type · subject"]},+ {"id": "event-dispatch", "label": "dispatch.emit", "type": "event router", "role": "event", "x": 1040, "y": 455, "w": 250, "h": 130, "detail": ["Visibility query + signal"]},+ {"id": "trigger-registration", "label": "Trigger registration", "type": "control signal", "role": "trigger", "x": 875, "y": 745, "w": 300, "h": 120, "detail": ["register_trigger + pause flags"]},+ {"id": "child-graph-workflow", "label": "Child graph workflow", "type": "Temporal workflow", "role": "workflow", "x": 1480, "y": 295, "w": 350, "h": 145, "detail": ["Snapshotted nodes and edges"]},+ {"id": "cron-action-workflow", "label": "Cron action workflow", "type": "Temporal workflow", "role": "workflow", "x": 1480, "y": 570, "w": 350, "h": 145, "detail": ["Schedule-owned graph launch"]},+ {"id": "execution-status", "label": "Run status and events", "type": "observable result", "role": "result", "x": 1515, "y": 810, "w": 280, "h": 115, "detail": ["Database + WebSocket"]}+ ],+ "relationships": [+ {"id": "r-controls-service", "from": "lifecycle-controls", "to": "workflow-control-service", "label": "Requests lifecycle transition", "protocol": "WebSocket command", "fromSide": "right", "toSide": "left", "labelAt": [350, 390]},+ {"id": "r-service-snapshot", "from": "workflow-control-service", "to": "generation-snapshot", "label": "Allocates or CAS-updates", "protocol": "workflow database", "fromSide": "bottom", "toSide": "top", "waypoints": [[495, 405], [210, 405]], "labelAt": [350, 405]},+ {"id": "r-snapshot-controller", "from": "generation-snapshot", "to": "controller", "label": "Starts with immutable graph snapshot", "protocol": "Temporal gRPC", "fromSide": "right", "toSide": "left", "labelAt": [350, 700]},+ {"id": "r-controls-controller", "from": "workflow-control-service", "to": "controller", "label": "Updates pause/resume or signals reset", "protocol": "Temporal Update / Signal", "fromSide": "bottom", "toSide": "top", "labelAt": [495, 405]},+ {"id": "r-service-local-state", "from": "workflow-control-service", "to": "local-runtime-state", "label": "Projects admission state", "protocol": "in-process", "fromSide": "bottom", "toSide": "top", "waypoints": [[640, 415], [640, 735], [355, 735]], "labelAt": [550, 735]},+ {"id": "r-push-event", "from": "push-trigger", "to": "cloudevent", "label": "Normalizes inbound event", "protocol": "CloudEvents 1.0", "fromSide": "bottom", "toSide": "top", "labelAt": [825, 385]},+ {"id": "r-event-dispatch", "from": "cloudevent", "to": "event-dispatch", "label": "Emits envelope", "protocol": "async dispatch", "fromSide": "right", "toSide": "left", "labelAt": [1010, 645]},+ {"id": "r-dispatch-controller", "from": "event-dispatch", "to": "controller", "label": "Signals matching controller", "protocol": "Visibility + on_event", "fromSide": "left", "toSide": "right", "waypoints": [[1010, 520], [675, 520]], "labelAt": [825, 520]},+ {"id": "r-poll-controller", "from": "poll-trigger", "to": "controller", "label": "Registers durable poll loop", "protocol": "register_trigger signal", "fromSide": "bottom", "toSide": "right", "waypoints": [[1045, 365], [675, 365], [675, 562]], "labelAt": [835, 365]},+ {"id": "r-cron-action", "from": "cron-trigger", "to": "cron-action-workflow", "label": "Fires scheduled action", "protocol": "Temporal Schedule", "fromSide": "right", "toSide": "left", "waypoints": [[1415, 262], [1415, 642]], "labelAt": [1415, 465]},+ {"id": "r-registration-controller", "from": "trigger-registration", "to": "controller", "label": "Registers definitions and pause state", "protocol": "Temporal Signal", "fromSide": "left", "toSide": "right", "waypoints": [[675, 805], [675, 562]], "labelAt": [675, 720]},+ {"id": "r-controller-child", "from": "controller", "to": "child-graph-workflow", "label": "Spawns admitted event or poll run", "protocol": "Temporal child workflow", "fromSide": "right", "toSide": "left", "waypoints": [[1410, 562], [1410, 367]], "labelAt": [1225, 367]},+ {"id": "r-cron-child", "from": "cron-action-workflow", "to": "child-graph-workflow", "label": "Launches snapshotted graph", "protocol": "Temporal child workflow", "fromSide": "top", "toSide": "bottom", "labelAt": [1655, 505]},+ {"id": "r-child-status", "from": "child-graph-workflow", "to": "execution-status", "label": "Persists and broadcasts run state", "protocol": "database + WebSocket", "fromSide": "bottom", "toSide": "top", "labelAt": [1655, 760]},+ {"id": "r-cron-status", "from": "cron-action-workflow", "to": "execution-status", "label": "Reports scheduled run state", "protocol": "Temporal + WebSocket", "fromSide": "bottom", "toSide": "top", "style": "dashed", "labelAt": [1775, 760]}+ ],+ "callouts": [+ {"id": "legacy-fallback", "title": "Optional legacy path", "x": 735, "y": 885, "w": 630, "h": 65, "lines": ["Local DeploymentManager / event-waiter remain optional fallbacks."]}+ ],+ "prompt": {+ "primaryRequest": "Build a deployment lifecycle and event-routing diagram that connects operator controls, revision-guarded generation snapshots, a long-lived Temporal controller, push/poll/cron trigger paths, and durable child graph runs.",+ "composition": "Use three vertical planes: control, trigger/event, and durable execution. Flow lifecycle commands and generation data down the left, push/poll/cron sources across the center, and child/cron workflows plus status on the right. Make the controller the visual hub without crossing connectors.",+ "constraints": ["Show graph_snapshot as immutable per generation", "Show push events as CloudEvents dispatched through Visibility and on_event", "Keep cron as a Temporal Schedule path distinct from controller-owned push/poll paths", "Use dashed styling only for optional or legacy reporting/fallback semantics"],+ "avoid": ["one workflow per idle trigger", "mutable live canvas as the deployed graph source", "polling through a cron schedule", "unlabelled signals", "Kubernetes or queue infrastructure not present in source"]+ }+}diff --git a/docs-internal/diagram-generation/specs/05-plugin-agent-team-composition.json b/docs-internal/diagram-generation/specs/05-plugin-agent-team-composition.jsonnew file mode 100644index 00000000..3cc255c6--- /dev/null+++ b/docs-internal/diagram-generation/specs/05-plugin-agent-team-composition.json@@ -0,0 +1,60 @@+{+ "id": "05-plugin-agent-team-composition",+ "title": "Plugin → Agent → Team Composition",+ "subtitle": "Self-registering node plugins compose provider-backed agents, edge-connected capabilities, and execution-scoped teams",+ "category": "architecture",+ "diagramType": "layered composition",+ "description": "A source-backed composition view showing how BaseNode plugins branch into standalone chat-model and agent plugins, how agents assemble context, skills, and tools before entering the shared LLM runtime, and how team leads turn teammate edges into durable delegation surfaces.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "server/services/plugin/base.py", "reason": "Authoritative BaseNode contract, subclass registration, component kinds, Params/Output schemas, handles, and uiHints."},+ {"path": "server/nodes/model/_base.py", "reason": "ChatModelBase contract and standalone output-model node behavior."},+ {"path": "server/nodes/agent/_specialized.py", "reason": "Agent Params select provider and model and specialized agents share the agent execution surface."},+ {"path": "server/nodes/agent/_handles.py", "reason": "Canonical agent and team-lead handle topology for context, skills, tools, tasks, and teammates."},+ {"path": "server/services/plugin/edge_walker.py", "reason": "Connection discovery, intrinsic Task Manager binding, teammate descriptors, and delegation-tool construction."},+ {"path": "server/services/llm/unifier.py", "reason": "Shared provider registry and native-SDK LLM facade used by model and agent execution."},+ {"path": "server/services/agent_team.py", "reason": "Execution-scoped durable team creation and task/member lifecycle service."},+ {"path": "server/models/database.py", "reason": "Persistent AgentTeam, TeamMember, TeamTask, TeamTaskAttempt, message, and concurrency records."}+ ],+ "groups": [+ {"id": "plugin-layer", "label": "PLUGIN & MODEL LAYER", "role": "system", "x": 50, "y": 125, "w": 500, "h": 830},+ {"id": "agent-layer", "label": "AGENT COMPOSITION", "role": "agent", "x": 590, "y": 125, "w": 700, "h": 830},+ {"id": "team-layer", "label": "TEAM COMPOSITION", "role": "workflow", "x": 1330, "y": 125, "w": 540, "h": 830}+ ],+ "nodes": [+ {"id": "base-node", "label": "BaseNode plugin contract", "type": "plugin contract", "role": "system", "x": 90, "y": 185, "w": 420, "h": 140, "detail": ["Params · Output · handles · uiHints", "Auto-registers subclasses on import"]},+ {"id": "model-plugins", "label": "Chat-model plugins", "type": "model plugin", "role": "model", "x": 90, "y": 400, "w": 420, "h": 150, "detail": ["ChatModelBase provider subclasses", "Standalone output-model nodes"]},+ {"id": "chat-unifier", "label": "ChatUnifier", "type": "LLM facade", "role": "model", "x": 90, "y": 730, "w": 420, "h": 160, "detail": ["Provider registry + native SDK adapters", "Shared model and agent dispatch path"]},+ {"id": "agent-plugins", "label": "Agent plugins", "type": "agent plugin", "role": "agent", "x": 640, "y": 185, "w": 600, "h": 160, "detail": ["provider · model · prompt · options", "Base, specialized, CLI, and team-lead variants"]},+ {"id": "context-node", "label": "Context", "type": "connected config", "role": "data", "x": 640, "y": 430, "w": 175, "h": 145, "detail": ["input-context", "policy + thread reference"]},+ {"id": "skill-nodes", "label": "Skills", "type": "connected capability", "role": "tool", "x": 850, "y": 430, "w": 175, "h": 145, "detail": ["input-skill", "direct or Master Skill"]},+ {"id": "tool-nodes", "label": "Tools", "type": "connected capability", "role": "tool", "x": 1060, "y": 430, "w": 180, "h": 145, "detail": ["input-tools", "plugin tool schemas"]},+ {"id": "prepared-agent-call", "label": "Prepared agent call", "type": "runtime payload", "role": "runtime", "x": 650, "y": 720, "w": 580, "h": 170, "detail": ["Edge walk + task/prompt assembly", "Provider-neutral tools and skill content"]},+ {"id": "team-lead", "label": "Orchestrator / AI Employee", "labelLines": ["Orchestrator /", "AI Employee"], "type": "team-lead agent", "role": "agent", "x": 1380, "y": 185, "w": 440, "h": 150, "detail": ["Same agent runtime", "Adds input-teammates handle"]},+ {"id": "teammates", "label": "Connected teammate agents", "labelLines": ["Connected teammate", "agents"], "type": "agent set", "role": "agent", "x": 1380, "y": 430, "w": 440, "h": 150, "detail": ["Specialized or custom aiAgent", "Stable delegate tool names"]},+ {"id": "task-manager", "label": "Task Manager", "type": "intrinsic tool", "role": "tool", "x": 1380, "y": 710, "w": 190, "h": 170, "detail": ["Auto-bound", "Lead-only control"]},+ {"id": "durable-team", "label": "Durable team state", "labelLines": ["Durable team", "state"], "type": "execution data", "role": "data", "x": 1610, "y": 710, "w": 210, "h": 170, "detail": ["Members · tasks", "Attempts · messages"]}+ ],+ "relationships": [+ {"id": "r-base-model", "from": "base-node", "to": "model-plugins", "label": "specializes as model plugin", "fromSide": "bottom", "toSide": "top", "labelAt": [300, 365]},+ {"id": "r-base-agent", "from": "base-node", "to": "agent-plugins", "label": "specializes as agent plugin", "fromSide": "bottom", "toSide": "left", "waypoints": [[300, 360], [610, 360], [610, 265]], "labelAt": [475, 360]},+ {"id": "r-model-unifier", "from": "model-plugins", "to": "chat-unifier", "label": "dispatches chat", "protocol": "provider + model", "fromSide": "bottom", "toSide": "top", "labelAt": [300, 640]},+ {"id": "r-agent-prepare", "from": "agent-plugins", "to": "prepared-agent-call", "label": "prepares execution payload", "fromSide": "bottom", "toSide": "top", "waypoints": [[940, 385], [940, 680]], "labelAt": [940, 650]},+ {"id": "r-context-prepare", "from": "context-node", "to": "prepared-agent-call", "label": "adds context descriptor", "fromSide": "bottom", "toSide": "left", "waypoints": [[727, 620], [620, 620], [620, 805]], "labelAt": [620, 665]},+ {"id": "r-skills-prepare", "from": "skill-nodes", "to": "prepared-agent-call", "label": "injects enabled skill content", "fromSide": "bottom", "toSide": "top", "waypoints": [[937, 630]], "labelAt": [937, 620]},+ {"id": "r-tools-prepare", "from": "tool-nodes", "to": "prepared-agent-call", "label": "builds tool surface", "fromSide": "bottom", "toSide": "right", "waypoints": [[1150, 620], [1260, 620], [1260, 805]], "labelAt": [1260, 665]},+ {"id": "r-prepare-unifier", "from": "prepared-agent-call", "to": "chat-unifier", "label": "routes selected provider and model", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[940, 920], [300, 920]], "labelAt": [620, 920]},+ {"id": "r-teammates-lead", "from": "teammates", "to": "team-lead", "label": "connect via input-teammates", "fromSide": "top", "toSide": "bottom", "labelAt": [1600, 382]},+ {"id": "r-lead-runtime", "from": "team-lead", "to": "prepared-agent-call", "label": "executes through shared agent runtime", "fromSide": "left", "toSide": "right", "waypoints": [[1320, 260], [1320, 650], [1260, 650], [1260, 805]], "labelAt": [1195, 650]},+ {"id": "r-lead-manager", "from": "team-lead", "to": "task-manager", "label": "auto-binds intrinsic tool", "fromSide": "bottom", "toSide": "top", "waypoints": [[1600, 650], [1475, 650]], "labelAt": [1515, 650]},+ {"id": "r-teammates-state", "from": "teammates", "to": "durable-team", "label": "registers execution members", "fromSide": "bottom", "toSide": "top", "waypoints": [[1600, 640], [1715, 640]], "labelAt": [1700, 640]},+ {"id": "r-manager-state", "from": "task-manager", "to": "durable-team", "label": "persists task lifecycle", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[1475, 920], [1715, 920]], "labelAt": [1595, 920]}+ ],+ "callouts": [],+ "prompt": {+ "primaryRequest": "Create a precise three-layer composition diagram that explains how self-registering plugins become chat-model and agent nodes, how an agent assembles context, skills, and tools before LLM dispatch, and how a team lead converts connected teammates into durable delegation state.",+ "composition": "Three framed columns from left to right: Plugin & Model Layer, Agent Composition, and Team Composition. Keep the BaseNode-to-model/agent branching explicit, arrange Context/Skills/Tools as a capability row feeding one prepared agent payload, and show team lead, teammates, intrinsic Task Manager, and durable team state as a clean vertical composition.",+ "constraints": ["Do not draw standalone chat-model nodes as a required input to ordinary agents; agents select provider and model in their own Params", "Show every capability and teammate connection as a directed labelled edge", "Keep the shared ChatUnifier visible for both standalone model execution and agent execution", "Treat Task Manager as intrinsic to team leads, not a palette-connected tool"],+ "avoid": ["class-count claims not shown in source", "implying teammate-to-teammate communication is required for composition", "unlabelled containment lines", "bidirectional arrows"]+ }+}diff --git a/docs-internal/diagram-generation/specs/06-persistence-secret-plane.json b/docs-internal/diagram-generation/specs/06-persistence-secret-plane.jsonnew file mode 100644index 00000000..3f7f2503--- /dev/null+++ b/docs-internal/diagram-generation/specs/06-persistence-secret-plane.json@@ -0,0 +1,56 @@+{+ "id": "06-persistence-secret-plane",+ "title": "Persistence & Secret Plane",+ "subtitle": "Operational state lives in workflow.db; API keys and OAuth tokens cross a separate encrypted credential boundary",+ "category": "architecture",+ "diagramType": "data and trust boundary",+ "description": "A two-plane architecture view separating ordinary workflow, execution, context, and team persistence from the credential path in which AuthService caches narrowly, CredentialsDatabase encrypts fields, and credentials.db stores only Fernet tokens plus derivation metadata.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "server/core/container.py", "reason": "Dependency wiring for Database, CredentialsDatabase, EncryptionService, CacheService, and AuthService."},+ {"path": "server/main.py", "reason": "Startup ordering: initialize credentials.db, load/create salt, then initialize encryption with the server-scoped key."},+ {"path": "server/core/database.py", "reason": "Authoritative async SQLModel service for workflow.db persistence."},+ {"path": "server/models/database.py", "reason": "Operational tables for workflows, node parameters/outputs, executions, context support, teams, tasks, and settings."},+ {"path": "server/services/auth.py", "reason": "Single credential access surface and the distinct API-key and OAuth display caches; refresh tokens bypass the process cache."},+ {"path": "server/core/credentials_database.py", "reason": "Separate encrypted SQLite schema with metadata, EncryptedAPIKey, and EncryptedOAuthToken tables."},+ {"path": "server/core/encryption.py", "reason": "Fernet field encryption and PBKDF2-SHA256 key derivation at 600,000 iterations."},+ {"path": "server/services/plugin/credential.py", "reason": "Plugin Credential.resolve path that obtains API keys or OAuth tokens through AuthService."},+ {"path": "server/core/config.py", "reason": "DATA_DIR-rooted workflow/credential database paths and API_KEY_ENCRYPTION_KEY configuration."}+ ],+ "groups": [+ {"id": "state-plane", "label": "APPLICATION PERSISTENCE · workflow.db", "role": "data", "x": 50, "y": 125, "w": 750, "h": 830},+ {"id": "secret-plane", "label": "SECRET PLANE · credentials.db", "role": "security", "x": 840, "y": 125, "w": 1030, "h": 830}+ ],+ "nodes": [+ {"id": "runtime-services", "label": "Runtime services", "type": "application callers", "role": "system", "x": 100, "y": 190, "w": 290, "h": 150, "detail": ["Workflows · nodes · deployments", "Context · teams · settings"]},+ {"id": "database-service", "label": "Database", "type": "persistence service", "role": "data", "x": 470, "y": 190, "w": 280, "h": 150, "detail": ["Async SQLModel / SQLite", "One operational access surface"]},+ {"id": "workflow-db", "label": "workflow.db", "type": "SQLite data store", "role": "data", "x": 280, "y": 540, "w": 330, "h": 200, "detail": ["Workflows · node params · outputs", "Executions · context · teams", "No encrypted credential tables"]},+ {"id": "credential-callers", "label": "Plugin credentials", "type": "secret consumers", "role": "system", "x": 870, "y": 190, "w": 250, "h": 150, "detail": ["Credential.resolve", "Connection / provider clients"]},+ {"id": "auth-service", "label": "AuthService", "type": "secret facade", "role": "security", "x": 1170, "y": 190, "w": 250, "h": 150, "detail": ["Only service-level credential route", "Store · resolve · remove"]},+ {"id": "credential-caches", "label": "Process caches", "type": "bounded secret cache", "role": "runtime", "x": 1570, "y": 190, "w": 250, "h": 150, "detail": ["API keys + model metadata", "OAuth access/display fields only"]},+ {"id": "credentials-database", "label": "CredentialsDatabase", "type": "encrypted persistence", "role": "security", "x": 1170, "y": 490, "w": 320, "h": 180, "detail": ["EncryptedAPIKey", "EncryptedOAuthToken", "credentials_metadata"]},+ {"id": "encryption-password", "label": "API_KEY_ENCRYPTION_KEY", "labelLines": ["API_KEY_", "ENCRYPTION_KEY"], "type": "server configuration", "role": "security", "x": 870, "y": 510, "w": 250, "h": 150, "detail": ["Minimum 32 characters", "Loaded at startup"]},+ {"id": "encryption-service", "label": "EncryptionService", "type": "cryptographic boundary", "role": "security", "x": 870, "y": 750, "w": 250, "h": 150, "detail": ["PBKDF2-SHA256 · 600,000", "Fernet encrypt / decrypt"]},+ {"id": "credentials-db", "label": "credentials.db", "type": "encrypted SQLite", "role": "data", "x": 1560, "y": 710, "w": 270, "h": 190, "detail": ["Ciphertext fields only", "32-byte salt in metadata", "Separate from workflow.db"]}+ ],+ "relationships": [+ {"id": "r-runtime-database", "from": "runtime-services", "to": "database-service", "label": "persists operational state", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[245, 400], [610, 400]], "labelAt": [425, 400]},+ {"id": "r-database-workflow", "from": "database-service", "to": "workflow-db", "label": "reads and writes SQLModel rows", "protocol": "sqlite+aiosqlite", "fromSide": "bottom", "toSide": "top", "waypoints": [[610, 450], [445, 450]], "labelAt": [525, 450]},+ {"id": "r-plugin-auth", "from": "credential-callers", "to": "auth-service", "label": "requests secret resolution", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[995, 400], [1295, 400]], "labelAt": [1145, 400]},+ {"id": "r-auth-cache", "from": "auth-service", "to": "credential-caches", "label": "populates safe cache", "fromSide": "right", "toSide": "left", "labelAt": [1495, 265]},+ {"id": "r-auth-credentials", "from": "auth-service", "to": "credentials-database", "label": "save · retrieve · delete", "fromSide": "bottom", "toSide": "top", "labelAt": [1335, 415]},+ {"id": "r-key-encryption", "from": "encryption-password", "to": "encryption-service", "label": "derives in-memory Fernet key", "fromSide": "bottom", "toSide": "top", "labelAt": [995, 710]},+ {"id": "r-credentials-encryption", "from": "credentials-database", "to": "encryption-service", "label": "calls encrypt / decrypt per field", "fromSide": "bottom", "toSide": "right", "waypoints": [[1330, 700], [1190, 700], [1190, 825]], "labelAt": [1280, 700]},+ {"id": "r-credentials-store", "from": "credentials-database", "to": "credentials-db", "label": "stores ciphertext rows and salt", "protocol": "SQLite", "fromSide": "bottom", "toSide": "top", "waypoints": [[1330, 690], [1695, 690]], "labelAt": [1515, 690]}+ ],+ "callouts": [+ {"id": "state-boundary-note", "title": "Blast-radius boundary", "x": 100, "y": 800, "w": 650, "h": 110, "lines": ["A workflow.db dump carries operational state,", "but never the encrypted API-key or OAuth tables."]},+ {"id": "refresh-token-note", "title": "Refresh-token rule", "x": 1525, "y": 395, "w": 305, "h": 115, "lines": ["Refresh tokens are never cached.", "AuthService reads them from", "credentials.db for every use."]}+ ],+ "prompt": {+ "primaryRequest": "Create a two-plane data architecture diagram that makes the separation between workflow.db operational persistence and the encrypted credentials.db secret plane unmistakable, including the real service boundaries and startup-derived encryption key path.",+ "composition": "Use two large side-by-side framed planes. The left plane is a short Runtime Services → Database → workflow.db flow with a blast-radius note. The right plane flows Plugin Credentials → AuthService → CredentialsDatabase → encrypted credentials.db, with a side cache, a server key feeding EncryptionService, and a refresh-token warning near the cache.",+ "constraints": ["Keep workflow.db and credentials.db visually separate", "Show AuthService as the single service-level credential access surface", "Show the API_KEY_ENCRYPTION_KEY and persisted salt as inputs to the encrypted-store design", "State that OAuth refresh tokens bypass the process cache", "Do not imply plaintext secrets are persisted"],+ "avoid": ["showing the unused credential backend factory as the active runtime path", "placing API keys in workflow.db", "plaintext secret labels inside credentials.db", "bidirectional arrows"]+ }+}diff --git a/docs-internal/diagram-generation/specs/07-workspace-anatomy.json b/docs-internal/diagram-generation/specs/07-workspace-anatomy.jsonnew file mode 100644index 00000000..212be452--- /dev/null+++ b/docs-internal/diagram-generation/specs/07-workspace-anatomy.json@@ -0,0 +1,56 @@+{+ "id": "07-workspace-anatomy",+ "title": "Workspace Anatomy",+ "subtitle": "Immutable workflow IDs resolve to mutable slug directories that isolate files, generated media, CLI worktrees, and materialized skills",+ "category": "architecture",+ "diagramType": "filesystem and consumer topology",+ "description": "A source-backed anatomy of per-workflow workspaces: the database-backed id-to-slug resolver selects a DATA_DIR-rooted directory, contained consumers read and write artifacts through traversal-safe helpers, and CLI agents receive the workspace for worktrees and per-workflow skill discovery.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "server/core/paths.py", "reason": "Canonical DATA_DIR, workspaces_dir, workspace_dir, and shipped example-workflow path rules."},+ {"path": "server/services/workspace_locator.py", "reason": "Single immutable workflow-id to mutable slug translation and safe default-workspace policy."},+ {"path": "server/services/workflow.py", "reason": "Workflow service creation and injection of the resolved workspace directory into execution context."},+ {"path": "server/services/workflow_storage/handlers.py", "reason": "Workflow rename path that moves a slug-keyed workspace directory."},+ {"path": "server/routers/workspace.py", "reason": "Workspace file-serving and bounded upload routes using immutable workflow IDs and contained relative paths."},+ {"path": "server/nodes/filesystem/_backend.py", "reason": "WorkspaceBackend and resolve_within path normalization, symlink/junction containment, and atomic write boundary."},+ {"path": "server/services/media/workspace.py", "reason": "Media references and reads/writes rooted in the executor-injected workspace."},+ {"path": "server/nodes/agent/claude_code_agent/_skills.py", "reason": "Per-workflow .claude/skills materialization with support-file preservation and diff updates."},+ {"path": "server/services/cli_agent/session.py", "reason": "Per-node CLI worktree placement and workspace --add-dir behavior."}+ ],+ "groups": [+ {"id": "workspace-resolution", "label": "IDENTITY & ROOT RESOLUTION", "role": "runtime", "x": 50, "y": 125, "w": 500, "h": 830},+ {"id": "workspace-boundary", "label": "PER-WORKFLOW WORKSPACE", "role": "data", "x": 590, "y": 125, "w": 710, "h": 830},+ {"id": "workspace-consumers", "label": "CONTAINED CONSUMERS", "role": "tool", "x": 1340, "y": 125, "w": 530, "h": 830}+ ],+ "nodes": [+ {"id": "workflow-record", "label": "Workflow record", "type": "database identity", "role": "data", "x": 90, "y": 190, "w": 420, "h": 150, "detail": ["Immutable id · mutable slug", "Stable references carry the id"]},+ {"id": "workspace-locator", "label": "Workspace locator", "type": "path resolver", "role": "runtime", "x": 90, "y": 430, "w": 420, "h": 170, "detail": ["Looks up id → slug in workflow.db", "Read-only misses may use default", "Mutations fail if id cannot resolve"]},+ {"id": "workspace-base", "label": "DATA_DIR / workspaces", "labelLines": ["DATA_DIR /", "workspaces"], "type": "filesystem root", "role": "data", "x": 90, "y": 720, "w": 420, "h": 150, "detail": ["~/.opencompany/workspaces by default", "WORKSPACE_BASE_DIR remains configurable"]},+ {"id": "workflow-workspace", "label": "workspaces/<workflow.slug>/", "type": "workspace root", "role": "data", "x": 640, "y": 190, "w": 610, "h": 160, "detail": ["Created for one workflow", "Directory moves when the slug changes"]},+ {"id": "workspace-files", "label": "Workspace files", "type": "runtime artifacts", "role": "data", "x": 640, "y": 470, "w": 280, "h": 170, "detail": ["Uploads · generated media", "Documents · code · nested files"]},+ {"id": "workspace-skills", "label": ".claude/skills/<name>/", "labelLines": [".claude/skills/", "<name>/"], "type": "materialized skills", "role": "tool", "x": 970, "y": 470, "w": 280, "h": 170, "detail": ["SKILL.md", "scripts/ + references/ preserved"]},+ {"id": "cli-worktrees", "label": "<node_id>/wt_<task_id>/", "labelLines": ["<node_id>/", "wt_<task_id>/"], "type": "CLI worktree", "role": "runtime", "x": 810, "y": 730, "w": 300, "h": 150, "detail": ["Per-task isolated branch", "Lives under the workflow workspace"]},+ {"id": "workspace-routes", "label": "Workspace HTTP routes", "labelLines": ["Workspace HTTP", "routes"], "type": "interface", "role": "interface", "x": 1380, "y": 190, "w": 440, "h": 150, "detail": ["Serve file by workflow id + path", "Accept bounded uploads"]},+ {"id": "filesystem-media", "label": "Filesystem & media nodes", "labelLines": ["Filesystem &", "media nodes"], "type": "contained I/O", "role": "tool", "x": 1380, "y": 460, "w": 440, "h": 170, "detail": ["resolve_within containment", "Traversal + symlink/junction defense", "Atomic workspace writes"]},+ {"id": "cli-agent-session", "label": "CLI agent session", "type": "agent consumer", "role": "agent", "x": 1380, "y": 730, "w": 440, "h": 150, "detail": ["Receives workspace_dir / --add-dir", "Discovers skills and owns worktrees"]}+ ],+ "relationships": [+ {"id": "r-workflow-locator", "from": "workflow-record", "to": "workspace-locator", "label": "lookup by immutable workflow id", "fromSide": "bottom", "toSide": "top", "labelAt": [300, 385]},+ {"id": "r-locator-base", "from": "workspace-locator", "to": "workspace-base", "label": "selects mutable slug below root", "fromSide": "bottom", "toSide": "top", "labelAt": [300, 665]},+ {"id": "r-base-workspace", "from": "workspace-base", "to": "workflow-workspace", "label": "contains one slug directory", "fromSide": "top", "toSide": "bottom", "waypoints": [[300, 680], [945, 680]], "labelAt": [675, 680]},+ {"id": "r-workspace-files", "from": "workflow-workspace", "to": "workspace-files", "label": "contains runtime artifacts", "fromSide": "bottom", "toSide": "top", "waypoints": [[945, 410], [780, 410]], "labelAt": [780, 410]},+ {"id": "r-workspace-skills", "from": "workflow-workspace", "to": "workspace-skills", "label": "contains isolated skill tree", "fromSide": "bottom", "toSide": "top", "waypoints": [[945, 410], [1110, 410]], "labelAt": [1110, 410]},+ {"id": "r-workspace-worktrees", "from": "workflow-workspace", "to": "cli-worktrees", "label": "contains per-node task worktrees", "fromSide": "bottom", "toSide": "top", "waypoints": [[945, 690]], "labelAt": [945, 690]},+ {"id": "r-routes-resolve", "from": "workspace-routes", "to": "workflow-workspace", "label": "resolves workflow id before file access", "protocol": "workspace locator", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[1600, 400], [945, 400]], "labelAt": [1320, 400]},+ {"id": "r-filesystem-files", "from": "filesystem-media", "to": "workspace-files", "label": "reads and writes contained paths", "fromSide": "left", "toSide": "right", "labelAt": [1150, 545]},+ {"id": "r-skills-cli", "from": "workspace-skills", "to": "cli-agent-session", "label": "auto-discovers enabled skills", "protocol": "--add-dir", "fromSide": "bottom", "toSide": "left", "waypoints": [[1110, 680], [1320, 680], [1320, 805]], "labelAt": [1215, 680]},+ {"id": "r-workspace-cli", "from": "workflow-workspace", "to": "cli-agent-session", "label": "passes workspace_dir", "fromSide": "bottom", "toSide": "top", "waypoints": [[1270, 350], [1270, 690], [1600, 690]], "labelAt": [1450, 690]}+ ],+ "callouts": [],+ "prompt": {+ "primaryRequest": "Create a filesystem anatomy diagram showing how an immutable workflow ID resolves through workflow.db to a mutable slug-keyed workspace, what lives inside that workspace, and which HTTP, filesystem/media, and CLI-agent consumers access it through containment controls.",+ "composition": "Use three framed columns: Identity & Root Resolution, Per-Workflow Workspace, and Contained Consumers. Show the id→slug resolver as a vertical chain on the left; place the slug directory at the top of the middle frame with files, .claude skills, and per-task CLI worktrees below; stack HTTP routes, filesystem/media nodes, and the CLI agent on the right.",+ "constraints": ["Label the on-disk directory with workflow.slug, never workflow.id", "State that stable references and routes carry the immutable workflow id", "Show containment for relative paths and symlink/junction escapes", "Keep .claude/skills inside the per-workflow workspace", "Show CLI worktrees under the same workspace root"],+ "avoid": ["placing shipped example workflows under DATA_DIR", "using a workflow id as the workspace directory name", "showing unrestricted host filesystem access", "bidirectional arrows"]+ }+}diff --git a/docs-internal/diagram-generation/specs/08-node-configuration-anatomy.json b/docs-internal/diagram-generation/specs/08-node-configuration-anatomy.jsonnew file mode 100644index 00000000..8320c687--- /dev/null+++ b/docs-internal/diagram-generation/specs/08-node-configuration-anatomy.json@@ -0,0 +1,58 @@+{+ "id": "08-node-configuration-anatomy",+ "title": "Node Configuration Anatomy",+ "subtitle": "A schema-driven modal combines draggable upstream data, a local parameter draft, per-node execution, and correlated live output",+ "category": "product-panel",+ "diagramType": "annotated panel flow",+ "description": "An anatomy of the Node Configuration modal showing the real header actions, the 0.7 / 1.6 / 0.7 Input–Parameters–Output layout, NodeSpec-driven variants, local edit-buffer persistence, save-before-run execution, and WebSocket-correlated output handling.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {"path": "client/src/ParameterPanel.tsx", "reason": "Modal shell, selected-node identity, Run/Save/Cancel-or-Stop actions, canvas-lock gating, and per-node execution reducer."},+ {"path": "client/src/components/parameterPanel/ParameterPanelLayout.tsx", "reason": "Authoritative three-column composition and 0.7 / 1.6 / 0.7 flex proportions."},+ {"path": "client/src/components/parameterPanel/InputSection.tsx", "reason": "Connected upstream output/schema discovery, inherited config-node inputs, recursive variable rendering, and drag source behavior."},+ {"path": "client/src/components/parameterPanel/MiddleSection.tsx", "reason": "Schema parameter rendering and uiHints-selected specialized panels, Connected Skills, Token Usage, and Console sections."},+ {"path": "client/src/components/parameterPanel/OutputSection.tsx", "reason": "Local execution plus WebSocket status/output merge and execution_id deduplication."},+ {"path": "client/src/hooks/useParameterPanel.ts", "reason": "Defaults + saved-parameters edit buffer, dirty comparison, save, cancel/revert, and selected NodeSpec resolution."},+ {"path": "client/src/hooks/useNodeParamsQuery.ts", "reason": "TanStack Query get/save node-parameter contract and optimistic versioned cache update."},+ {"path": "client/src/services/executionService.ts", "reason": "Save-aware WebSocket node execution and normalized ExecutionResult contract."},+ {"path": "server/routers/websocket.py", "reason": "get_node_parameters, save_node_parameters, output/status, and event-wait cancellation request handlers."},+ {"path": "server/core/database.py", "reason": "Persistent node_parameters and node_outputs backing the panel's live and saved data."}+ ],+ "groups": [+ {"id": "configuration-modal", "label": "NODE CONFIGURATION MODAL", "role": "interface", "x": 50, "y": 125, "w": 1820, "h": 620},+ {"id": "panel-data-plane", "label": "LIVE DATA & PERSISTENCE", "role": "runtime", "x": 50, "y": 775, "w": 1820, "h": 180}+ ],+ "nodes": [+ {"id": "node-identity", "label": "Node identity", "type": "modal header", "role": "interface", "x": 90, "y": 175, "w": 560, "h": 110, "detail": ["Icon · display name · dirty marker"]},+ {"id": "save-action", "label": "Save", "type": "header action", "role": "trigger", "x": 700, "y": 175, "w": 220, "h": 110, "detail": ["Disabled when clean or canvas locked"]},+ {"id": "run-action", "label": "Run", "type": "header action", "role": "trigger", "x": 960, "y": 175, "w": 220, "h": 110, "detail": ["Hidden by uiHints when passive"]},+ {"id": "cancel-action", "label": "Cancel / Stop", "type": "header action", "role": "trigger", "x": 1220, "y": 175, "w": 270, "h": 110, "detail": ["Revert draft or cancel active wait"]},+ {"id": "close-action", "label": "Close (X)", "type": "modal action", "role": "neutral", "x": 1530, "y": 175, "w": 300, "h": 110, "detail": ["Cancel draft and deselect node"]},+ {"id": "input-column", "label": "Input Data & Variables", "labelLines": ["Input Data &", "Variables"], "type": "left column · 0.7", "role": "interface", "x": 90, "y": 350, "w": 430, "h": 340, "detail": ["Upstream execution values or output schema", "Recursive object and array fields", "Drag template variables into parameters"]},+ {"id": "parameters-column", "label": "Parameters", "type": "middle column · 1.6", "role": "interface", "x": 560, "y": 350, "w": 760, "h": 340, "detail": ["Schema-rendered local edit buffer", "Specialized middle panels selected by uiHints", "Connected Skills · Token Usage · Console"]},+ {"id": "output-column", "label": "Output", "type": "right column · 0.7", "role": "result", "x": 1360, "y": 350, "w": 470, "h": 340, "detail": ["Local run results + WebSocket status", "Deduplicates matching execution_id", "Clear results without changing parameters"]},+ {"id": "node-spec", "label": "NodeSpec metadata", "type": "schema source", "role": "data", "x": 90, "y": 820, "w": 330, "h": 110, "detail": ["properties · handles · uiHints"]},+ {"id": "parameter-state", "label": "Parameter query + draft", "labelLines": ["Parameter query", "+ draft"], "type": "client state", "role": "runtime", "x": 500, "y": 820, "w": 380, "h": 125, "detail": ["defaults + saved params", "dirty edit buffer + query cache"]},+ {"id": "execution-service", "label": "ExecutionService", "type": "per-node runtime", "role": "runtime", "x": 940, "y": 820, "w": 360, "h": 110, "detail": ["save-before-run · executeNode", "per-node reducer"]},+ {"id": "websocket-database", "label": "WebSocket + workflow.db", "labelLines": ["WebSocket +", "workflow.db"], "type": "live data plane", "role": "data", "x": 1370, "y": 820, "w": 460, "h": 125, "detail": ["node_parameters · node_outputs", "node status + wait cancellation"]}+ ],+ "relationships": [+ {"id": "r-spec-identity", "from": "node-spec", "to": "node-identity", "label": "supplies icon and display name", "fromSide": "top", "toSide": "bottom", "waypoints": [[255, 760], [370, 760]], "labelAt": [370, 760]},+ {"id": "r-spec-parameters", "from": "node-spec", "to": "parameters-column", "label": "renders fields and panel variants", "fromSide": "top", "toSide": "bottom", "waypoints": [[255, 720], [940, 720]], "labelAt": [600, 720]},+ {"id": "r-input-parameters", "from": "input-column", "to": "parameters-column", "label": "drag template variable", "fromSide": "top", "toSide": "top", "waypoints": [[305, 320], [940, 320]], "labelAt": [620, 320]},+ {"id": "r-parameters-draft", "from": "parameters-column", "to": "parameter-state", "label": "onParameterChange updates local draft", "fromSide": "bottom", "toSide": "top", "waypoints": [[940, 750], [690, 750]], "labelAt": [815, 750]},+ {"id": "r-save-draft", "from": "save-action", "to": "parameter-state", "label": "handleSave commits draft", "fromSide": "bottom", "toSide": "top", "waypoints": [[810, 310], [460, 310], [460, 760], [690, 760]], "labelAt": [575, 760]},+ {"id": "r-run-execution", "from": "run-action", "to": "execution-service", "label": "save if dirty, then execute node", "fromSide": "bottom", "toSide": "top", "waypoints": [[1070, 310], [1120, 760]], "labelAt": [1120, 760]},+ {"id": "r-execution-output", "from": "execution-service", "to": "output-column", "label": "appends correlated ExecutionResult", "fromSide": "top", "toSide": "bottom", "waypoints": [[1120, 735], [1595, 735]], "labelAt": [1370, 735]},+ {"id": "r-websocket-output", "from": "websocket-database", "to": "output-column", "label": "broadcasts node status and output", "protocol": "execution_id", "fromSide": "top", "toSide": "bottom", "waypoints": [[1600, 780], [1760, 780], [1760, 720], [1595, 720]], "labelAt": [1705, 720]},+ {"id": "r-cancel-websocket", "from": "cancel-action", "to": "websocket-database", "label": "cancel wait or close draft", "fromSide": "bottom", "toSide": "top", "waypoints": [[1355, 310], [1850, 310], [1850, 760], [1600, 760]], "labelAt": [1720, 760]},+ {"id": "r-draft-database", "from": "parameter-state", "to": "websocket-database", "label": "save_node_parameters", "protocol": "TanStack Query + WS", "fromSide": "bottom", "toSide": "bottom", "waypoints": [[690, 970], [1600, 970]], "labelAt": [1145, 970]}+ ],+ "callouts": [],+ "prompt": {+ "primaryRequest": "Create an annotated product-panel anatomy of the Node Configuration modal with its real header controls, three proportional columns, and the live client/server data flows that drive configuration, execution, and output.",+ "composition": "Use one wide modal frame above a shallow live-data frame. In the modal header place Node identity, Save, Run, Cancel / Stop, and Close. Beneath it, preserve the visibly narrow-wide-narrow 0.7 / 1.6 / 0.7 Input Data & Variables, Parameters, and Output columns. Align NodeSpec, parameter draft/query, ExecutionService, and WebSocket + workflow.db cards below their consumers.",+ "constraints": ["Preserve the 0.7 / 1.6 / 0.7 column hierarchy", "Show Save, Run, Cancel / Stop, and Close as distinct controls", "Represent NodeSpec uiHints as the source of hidden sections and specialized middle panels", "Show the local edit buffer separately from persisted node_parameters", "Show output correlation by execution_id", "Keep all relationships directed and labelled"],+ "avoid": ["invented toolbar controls", "a generic settings form unrelated to the real panel", "equal-width content columns", "unlabelled arrows", "bidirectional arrows"]+ }+}diff --git a/docs-internal/diagram-generation/specs/09-credentials-architecture.json b/docs-internal/diagram-generation/specs/09-credentials-architecture.jsonnew file mode 100644index 00000000..e68ce9e1--- /dev/null+++ b/docs-internal/diagram-generation/specs/09-credentials-architecture.json@@ -0,0 +1,399 @@+{+ "id": "09-credentials-architecture",+ "title": "Credentials Architecture",+ "subtitle": "Server-owned catalogue, WebSocket orchestration, and encrypted storage",+ "category": "architecture",+ "diagramType": "layered-security-data-flow",+ "description": "Credential configuration flows from the server-owned provider catalogue through modular client panels and registered WebSocket handlers. AuthService is the only plaintext access boundary; CredentialsDatabase encrypts separate API-key and OAuth-token records with the process-held Fernet service, while status events invalidate every connected client's catalogue.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "client/src/components/credentials/CredentialsModal.tsx",+ "reason": "Defines the thin modal shell, server-owned catalogue consumption, searchable palette, and lazy panel dispatch."+ },+ {+ "path": "client/src/components/credentials/useCredentialPanel.ts",+ "reason": "Defines per-provider TanStack Query state and credential RPC actions without persisting plaintext in the UI store."+ },+ {+ "path": "server/services/credentials/handlers.py",+ "reason": "Implements registered validate, get, save, and delete WebSocket handlers and their mutation broadcasts."+ },+ {+ "path": "server/services/plugin/credential.py",+ "reason": "Defines declarative credential classes, provider-specific probes, runtime resolution, and validation dispatch."+ },+ {+ "path": "server/services/auth.py",+ "reason": "Defines the sole credential access service, separate API-key and OAuth caches, catalogue invalidation, and refresh-token non-caching rule."+ },+ {+ "path": "server/core/credentials_database.py",+ "reason": "Defines the canonical encrypted SQLite records, two-table storage split, and calls to EncryptionService."+ },+ {+ "path": "server/core/encryption.py",+ "reason": "Defines PBKDF2-SHA256 key derivation and the process-held Fernet encrypt/decrypt boundary."+ },+ {+ "path": "server/services/status_broadcaster.py",+ "reason": "Defines api_key_status and credential_catalogue_updated broadcasts consumed by connected clients."+ }+ ],+ "groups": [+ {+ "id": "client-plane",+ "x": 72,+ "y": 150,+ "w": 650,+ "h": 780,+ "label": "CLIENT CONTROL PLANE",+ "role": "interface"+ },+ {+ "id": "server-plane",+ "x": 760,+ "y": 150,+ "w": 1088,+ "h": 780,+ "label": "SERVER SECURITY PLANE",+ "role": "system"+ }+ ],+ "nodes": [+ {+ "id": "credentials-modal",+ "x": 110,+ "y": 230,+ "w": 270,+ "h": 170,+ "label": "Credentials Modal",+ "type": "UI",+ "role": "interface",+ "detail": [+ "server catalogue + IDB warm-start",+ "search palette + lazy panels"+ ]+ },+ {+ "id": "client-state",+ "x": 420,+ "y": 230,+ "w": 260,+ "h": 170,+ "label": "WebSocket + Query State",+ "labelLines": [+ "WebSocket +",+ "Query State"+ ],+ "type": "CLIENT",+ "role": "interface",+ "detail": [+ "request / response RPC",+ "catalogue invalidation"+ ]+ },+ {+ "id": "ws-handlers",+ "x": 800,+ "y": 230,+ "w": 270,+ "h": 170,+ "label": "Credential WS Handlers",+ "labelLines": [+ "Credential WS",+ "Handlers"+ ],+ "type": "ROUTER",+ "role": "runtime",+ "detail": [+ "validate · get · save · delete",+ "idempotent mutation envelope"+ ]+ },+ {+ "id": "credential-registries",+ "x": 1130,+ "y": 230,+ "w": 300,+ "h": 170,+ "label": "Credential Registries",+ "type": "REGISTRY",+ "role": "workflow",+ "detail": [+ "catalogue metadata + stored flags",+ "credential classes + probes"+ ]+ },+ {+ "id": "status-broadcaster",+ "x": 1500,+ "y": 230,+ "w": 300,+ "h": 170,+ "label": "Status Broadcaster",+ "type": "EVENTS",+ "role": "event",+ "detail": [+ "api_key_status",+ "credential_catalogue_updated"+ ]+ },+ {+ "id": "auth-service",+ "x": 1030,+ "y": 500,+ "w": 370,+ "h": 190,+ "label": "AuthService",+ "type": "SECURITY SERVICE",+ "role": "security",+ "detail": [+ "only credential access point",+ "separate API-key + OAuth caches",+ "refresh tokens never cached"+ ]+ },+ {+ "id": "encryption-service",+ "x": 1490,+ "y": 500,+ "w": 310,+ "h": 190,+ "label": "Encryption Service",+ "type": "CRYPTO",+ "role": "security",+ "detail": [+ "PBKDF2-SHA256 · 600k",+ "Fernet key held in process",+ "server key + install salt"+ ]+ },+ {+ "id": "credentials-db",+ "x": 1180,+ "y": 760,+ "w": 470,+ "h": 150,+ "label": "credentials.db",+ "type": "ENCRYPTED SQLITE",+ "role": "data",+ "detail": [+ "EncryptedAPIKey · EncryptedOAuthToken",+ "credentials_metadata encryption salt"+ ]+ }+ ],+ "relationships": [+ {+ "id": "modal-uses-client-state",+ "from": "credentials-modal",+ "to": "client-state",+ "label": "panel actions + cached status",+ "protocol": "React Query",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 400,+ 205+ ]+ },+ {+ "id": "client-calls-handlers",+ "from": "client-state",+ "to": "ws-handlers",+ "label": "catalogue + credential RPC",+ "protocol": "WebSocket",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 740,+ 315+ ]+ },+ {+ "id": "handlers-dispatch-registry",+ "from": "ws-handlers",+ "to": "credential-registries",+ "label": "dispatch validation",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 1100,+ 205+ ]+ },+ {+ "id": "handlers-use-auth-service",+ "from": "ws-handlers",+ "to": "auth-service",+ "label": "get · save · delete",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [+ [+ 935,+ 450+ ],+ [+ 1215,+ 450+ ]+ ],+ "labelAt": [+ 1075,+ 450+ ]+ },+ {+ "id": "registry-stores-valid-result",+ "from": "credential-registries",+ "to": "auth-service",+ "label": "store valid probe result",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [+ 1280,+ 480+ ]+ },+ {+ "id": "registry-publishes-status",+ "from": "credential-registries",+ "to": "status-broadcaster",+ "label": "publish validation status",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 1465,+ 205+ ]+ },+ {+ "id": "auth-publishes-mutation",+ "from": "auth-service",+ "to": "status-broadcaster",+ "label": "catalogue version + mutation event",+ "style": "solid",+ "fromSide": "right",+ "toSide": "bottom",+ "waypoints": [+ [+ 1450,+ 595+ ],+ [+ 1450,+ 440+ ],+ [+ 1650,+ 440+ ]+ ],+ "labelAt": [+ 1560,+ 440+ ]+ },+ {+ "id": "auth-canonical-crud",+ "from": "auth-service",+ "to": "credentials-db",+ "label": "canonical encrypted CRUD",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [+ 1260,+ 715+ ]+ },+ {+ "id": "db-uses-encryption",+ "from": "credentials-db",+ "to": "encryption-service",+ "label": "encrypt / decrypt payloads",+ "protocol": "Fernet",+ "style": "solid",+ "fromSide": "top",+ "toSide": "bottom",+ "waypoints": [+ [+ 1415,+ 720+ ],+ [+ 1645,+ 720+ ]+ ],+ "labelAt": [+ 1580,+ 720+ ]+ },+ {+ "id": "broadcast-invalidates-client",+ "from": "status-broadcaster",+ "to": "client-state",+ "label": "push status + invalidate catalogue",+ "protocol": "WebSocket",+ "style": "dashed",+ "fromSide": "top",+ "toSide": "top",+ "waypoints": [+ [+ 1650,+ 115+ ],+ [+ 550,+ 115+ ]+ ],+ "labelAt": [+ 1100,+ 115+ ]+ }+ ],+ "callouts": [+ {+ "id": "storage-split",+ "x": 800,+ "y": 735,+ "w": 330,+ "h": 175,+ "title": "Two non-interchangeable stores",+ "lines": [+ "API keys: session + provider",+ "OAuth tokens: provider + customer",+ "Access tokens may cache; refresh tokens do not"+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Show the current OpenCompany credential architecture as a security-first flow from the Credentials Modal through WebSocket handlers and declarative credential registries to AuthService, encrypted SQLite, and client-invalidating status broadcasts.",+ "composition": "Two clearly bounded lanes: a compact client control plane on the left and a larger server security plane on the right. Read primarily left-to-right, then down through AuthService to encrypted storage, with one dashed broadcast return path across the top. Keep the API-key versus OAuth-token split visible as a security callout.",+ "constraints": [+ "AuthService must be the only plaintext credential access boundary",+ "Show API keys and OAuth tokens as distinct non-interchangeable records",+ "Show CredentialsDatabase calling Fernet encryption with PBKDF2-SHA256-derived process key",+ "Show status broadcasts invalidating the client catalogue without exposing secret values",+ "Never render example API keys, access tokens, refresh tokens, or plaintext secrets"+ ],+ "avoid": [+ "implying the browser stores plaintext secrets persistently",+ "merging API keys and OAuth tokens into one cache or record",+ "showing routers accessing CredentialsDatabase directly",+ "depicting refresh tokens inside the in-memory cache"+ ]+ }+}diff --git a/docs-internal/diagram-generation/specs/10-team-operations.json b/docs-internal/diagram-generation/specs/10-team-operations.jsonnew file mode 100644index 00000000..e3c32fab--- /dev/null+++ b/docs-internal/diagram-generation/specs/10-team-operations.json@@ -0,0 +1,507 @@+{+ "id": "10-team-operations",+ "title": "Team Operations",+ "subtitle": "Execution-scoped durable tasks: assign, run, review, recover, and finish",+ "category": "architecture",+ "diagramType": "state-machine-and-control-surfaces",+ "description": "A team lead uses its intrinsic Task Manager to persist bounded work for graph-connected teammates. AgentTeamService enforces workflow, lead, execution, assignee, and optimistic-revision boundaries while tasks advance from blocked or queued through worker submission and explicit lead acceptance; Task Manager and Team Monitor expose mutable and read-only views of the same durable state.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "server/nodes/tool/task_manager/__init__.py",+ "reason": "Defines the intrinsic model-facing operations, connected-teammate resolution, and trusted execution scope."+ },+ {+ "path": "server/services/agent_team.py",+ "reason": "Defines durable assignment, authorized mutation transitions, submission versus acceptance semantics, and finish-team gating."+ },+ {+ "path": "server/services/agent_teams/handlers.py",+ "reason": "Defines human WebSocket reads and revision-checked task management operations."+ },+ {+ "path": "server/services/temporal/agent_workflow.py",+ "reason": "Implements detached delegated task execution, concurrency permits, child completion, and terminal cleanup."+ },+ {+ "path": "client/src/components/parameterPanel/TaskManagerPanel.tsx",+ "reason": "Defines the operational task UI, status-specific actions, revision checks, execution history, and Temporal trace inspection."+ },+ {+ "path": "client/src/components/parameterPanel/TeamMonitorPanel.tsx",+ "reason": "Defines the read-only teammate and task snapshot, lifecycle counts, execution selector, and event-driven refresh."+ }+ ],+ "groups": [+ {+ "id": "operation-surfaces",+ "x": 72,+ "y": 140,+ "w": 1776,+ "h": 235,+ "label": "OPERATION SURFACES",+ "role": "workflow"+ },+ {+ "id": "task-lifecycle",+ "x": 72,+ "y": 410,+ "w": 1776,+ "h": 535,+ "label": "DURABLE TASK LIFECYCLE",+ "role": "runtime"+ }+ ],+ "nodes": [+ {+ "id": "team-lead",+ "x": 110,+ "y": 205,+ "w": 300,+ "h": 140,+ "label": "Team Lead",+ "type": "AGENT",+ "role": "agent",+ "detail": [+ "Orchestrator or AI Employee",+ "connected teammates are authority"+ ]+ },+ {+ "id": "task-manager",+ "x": 500,+ "y": 205,+ "w": 330,+ "h": 140,+ "label": "Task Manager",+ "type": "INTRINSIC TOOL",+ "role": "tool",+ "detail": [+ "assign · inspect · review",+ "retry · reassign · cancel · finish"+ ]+ },+ {+ "id": "agent-team-service",+ "x": 920,+ "y": 205,+ "w": 360,+ "h": 140,+ "label": "AgentTeamService",+ "type": "DURABLE SERVICE",+ "role": "runtime",+ "detail": [+ "workflow + lead + execution scope",+ "optimistic revision transitions"+ ]+ },+ {+ "id": "human-views",+ "x": 1390,+ "y": 205,+ "w": 360,+ "h": 140,+ "label": "Task Manager + Team Monitor",+ "labelLines": [+ "Task Manager +",+ "Team Monitor"+ ],+ "type": "HUMAN UI",+ "role": "interface",+ "detail": [+ "authorized mutations + trace",+ "read-only lifecycle snapshot"+ ]+ },+ {+ "id": "blocked",+ "x": 110,+ "y": 520,+ "w": 250,+ "h": 140,+ "label": "Blocked",+ "type": "TASK STATE",+ "role": "neutral",+ "detail": [+ "dependencies unresolved"+ ]+ },+ {+ "id": "queued",+ "x": 440,+ "y": 520,+ "w": 250,+ "h": 140,+ "label": "Queued",+ "type": "TASK STATE",+ "role": "workflow",+ "detail": [+ "durably persisted",+ "awaiting admission"+ ]+ },+ {+ "id": "running",+ "x": 770,+ "y": 520,+ "w": 250,+ "h": 140,+ "label": "Running",+ "type": "TASK STATE",+ "role": "runtime",+ "detail": [+ "worker claimed task",+ "detached child execution"+ ]+ },+ {+ "id": "submitted",+ "x": 1100,+ "y": 520,+ "w": 250,+ "h": 140,+ "label": "Submitted",+ "type": "TASK STATE",+ "role": "event",+ "detail": [+ "worker result awaits review"+ ]+ },+ {+ "id": "accepted",+ "x": 1430,+ "y": 520,+ "w": 250,+ "h": 140,+ "label": "Accepted",+ "type": "TASK STATE",+ "role": "result",+ "detail": [+ "lead-approved Done state"+ ]+ },+ {+ "id": "failed",+ "x": 770,+ "y": 760,+ "w": 250,+ "h": 140,+ "label": "Failed",+ "type": "TASK STATE",+ "role": "event",+ "detail": [+ "error retained for recovery"+ ]+ },+ {+ "id": "cancelled",+ "x": 1100,+ "y": 760,+ "w": 250,+ "h": 140,+ "label": "Cancelled",+ "type": "TASK STATE",+ "role": "neutral",+ "detail": [+ "intentional terminal state"+ ]+ },+ {+ "id": "team-completed",+ "x": 1430,+ "y": 760,+ "w": 250,+ "h": 140,+ "label": "Team Completed",+ "type": "EXECUTION STATE",+ "role": "result",+ "detail": [+ "all tasks accepted or cancelled"+ ]+ }+ ],+ "relationships": [+ {+ "id": "lead-calls-task-manager",+ "from": "team-lead",+ "to": "task-manager",+ "label": "call public operations",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 455,+ 180+ ]+ },+ {+ "id": "task-manager-uses-service",+ "from": "task-manager",+ "to": "agent-team-service",+ "label": "scoped durable mutation",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 875,+ 180+ ]+ },+ {+ "id": "human-manages-service",+ "from": "human-views",+ "to": "agent-team-service",+ "label": "inspect + permitted review actions",+ "protocol": "WebSocket",+ "style": "solid",+ "fromSide": "left",+ "toSide": "right",+ "labelAt": [+ 1335,+ 245+ ]+ },+ {+ "id": "service-updates-human",+ "from": "agent-team-service",+ "to": "human-views",+ "label": "snapshots + lifecycle events",+ "style": "dashed",+ "fromSide": "bottom",+ "toSide": "bottom",+ "waypoints": [+ [+ 1100,+ 365+ ],+ [+ 1570,+ 365+ ]+ ],+ "labelAt": [+ 1335,+ 365+ ]+ },+ {+ "id": "service-assigns-ready",+ "from": "agent-team-service",+ "to": "queued",+ "label": "assign_task persists ready work",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [+ [+ 1100,+ 395+ ],+ [+ 565,+ 395+ ]+ ],+ "labelAt": [+ 830,+ 395+ ]+ },+ {+ "id": "dependencies-unblock",+ "from": "blocked",+ "to": "queued",+ "label": "dependencies accepted",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 400,+ 495+ ]+ },+ {+ "id": "worker-claims",+ "from": "queued",+ "to": "running",+ "label": "worker claims task",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 730,+ 495+ ]+ },+ {+ "id": "worker-submits",+ "from": "running",+ "to": "submitted",+ "label": "worker succeeds",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 1060,+ 495+ ]+ },+ {+ "id": "lead-accepts",+ "from": "submitted",+ "to": "accepted",+ "label": "accept_task",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 1390,+ 495+ ]+ },+ {+ "id": "worker-fails",+ "from": "running",+ "to": "failed",+ "label": "worker errors",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [+ 895,+ 710+ ]+ },+ {+ "id": "failed-requeues",+ "from": "failed",+ "to": "queued",+ "label": "retry_task / reassign_task",+ "style": "solid",+ "fromSide": "left",+ "toSide": "bottom",+ "waypoints": [+ [+ 720,+ 700+ ],+ [+ 565,+ 700+ ]+ ],+ "labelAt": [+ 640,+ 700+ ]+ },+ {+ "id": "submitted-requeues",+ "from": "submitted",+ "to": "queued",+ "label": "retry_task / reassign_task",+ "style": "dashed",+ "fromSide": "top",+ "toSide": "top",+ "waypoints": [+ [+ 1225,+ 455+ ],+ [+ 565,+ 455+ ]+ ],+ "labelAt": [+ 895,+ 455+ ]+ },+ {+ "id": "cancelled-requeues",+ "from": "cancelled",+ "to": "queued",+ "label": "retry_task / reassign_task",+ "style": "dashed",+ "fromSide": "bottom",+ "toSide": "bottom",+ "waypoints": [+ [+ 1225,+ 925+ ],+ [+ 700,+ 925+ ],+ [+ 700,+ 700+ ]+ ],+ "labelAt": [+ 895,+ 925+ ]+ },+ {+ "id": "accepted-finishes-team",+ "from": "accepted",+ "to": "team-completed",+ "label": "finish_team when all resolved",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [+ 1555,+ 690+ ]+ },+ {+ "id": "cancelled-is-resolved",+ "from": "cancelled",+ "to": "team-completed",+ "label": "cancelled also counts resolved",+ "style": "dashed",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [+ 1390,+ 735+ ]+ }+ ],+ "callouts": [+ {+ "id": "permitted-mutations",+ "x": 110,+ "y": 740,+ "w": 550,+ "h": 165,+ "title": "State-aware controls",+ "lines": [+ "modify_task: blocked or queued",+ "cancel_task: blocked, queued, or running",+ "list/get/inspect never mutate task state"+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Explain OpenCompany team operations as one integrated schematic: the team lead's intrinsic Task Manager and human panels feed an execution-scoped AgentTeamService, then a durable task state machine makes worker submission, lead acceptance, retries, reassignment, cancellation, and final team completion explicit.",+ "composition": "A narrow top control band contains Team Lead, Task Manager, AgentTeamService, and the human Task Manager plus Team Monitor. A large lower band contains a left-to-right lifecycle from Blocked through Queued, Running, Submitted, and Accepted, with Failed and Cancelled recovery states below and Team Completed at the lower right. Route recovery arrows around the main path and keep every arrow label readable.",+ "constraints": [+ "Submitted must be visibly distinct from Accepted and must not be labelled Done",+ "Only accepted and cancelled tasks satisfy finish_team",+ "Show retry and reassign returning failed, submitted, or cancelled work to Queued",+ "Show optimistic revision-checked mutations at AgentTeamService",+ "Team Monitor must be described as read-only even though Task Manager UI can mutate"+ ],+ "avoid": [+ "equating worker completion with lead acceptance",+ "showing arbitrary non-connected agents as valid assignees",+ "a single undifferentiated completed state",+ "implying one sibling failure cancels every sibling"+ ]+ }+}diff --git a/docs-internal/diagram-generation/specs/11-agent-context-memory.json b/docs-internal/diagram-generation/specs/11-agent-context-memory.jsonnew file mode 100644index 00000000..e499de80--- /dev/null+++ b/docs-internal/diagram-generation/specs/11-agent-context-memory.json@@ -0,0 +1,410 @@+{+ "id": "11-agent-context-memory",+ "title": "Agent Context vs. Simple Memory",+ "subtitle": "Automatic replay continuity and explicit durable knowledge are separate systems",+ "category": "architecture",+ "diagramType": "side-by-side-comparison",+ "description": "Agent Context is the system-managed exact journal, provider binding, replay checkpoint, and context-pressure policy connected through input-context. Simple Memory is a separate explicit tool connected through input-tools; the model or a human chooses when to remember, recall, update, or forget versioned facts in an isolated namespace, and those items are never injected as automatic transcript replay.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "server/nodes/context/__init__.py",+ "reason": "Defines the visible system-managed Context policy node, output-context handle, compaction policy, and metadata-only output."+ },+ {+ "path": "server/nodes/context/_descriptor.py",+ "reason": "Defines generation-scoped Context descriptors, thread selection, and delegated-task isolation."+ },+ {+ "path": "server/services/agent_context/store.py",+ "reason": "Defines transactional append-only Context threads, epochs, revisions, journal events, and checkpoints."+ },+ {+ "path": "server/services/agent_context/compaction.py",+ "reason": "Defines provider-native versus portable compaction and exact replay-tail behavior under context pressure."+ },+ {+ "path": "server/nodes/context/_handlers.py",+ "reason": "Defines active-epoch journal inspection so Reset and Clear expose the fresh live epoch while retaining prior events as archived history."+ },+ {+ "path": "server/nodes/tool/simple_memory/__init__.py",+ "reason": "Defines Simple Memory V2 as an explicit locked-schema tool with remember, recall, list, get, update, and forget operations."+ },+ {+ "path": "server/services/memory/tool_store.py",+ "reason": "Defines isolated owner/workflow/node namespaces, versioned durable items, idempotent mutations, and lexical or embedding retrieval."+ },+ {+ "path": "client/src/components/parameterPanel/ContextPanel.tsx",+ "reason": "Defines the authorized exact-journal and active-replay inspector, including pressure, checkpoints, fork, export, and epoch clear."+ },+ {+ "path": "client/src/components/parameterPanel/MemoryToolPanel.tsx",+ "reason": "Defines human-authored durable facts, search, update, forget, and isolated bulk-clear controls."+ }+ ],+ "groups": [+ {+ "id": "context-plane",+ "x": 72,+ "y": 140,+ "w": 720,+ "h": 800,+ "label": "AGENT CONTEXT · AUTOMATIC REPLAY",+ "role": "system"+ },+ {+ "id": "memory-plane",+ "x": 1128,+ "y": 140,+ "w": 720,+ "h": 800,+ "label": "SIMPLE MEMORY · EXPLICIT TOOL",+ "role": "tool"+ }+ ],+ "nodes": [+ {+ "id": "context-node",+ "x": 120,+ "y": 220,+ "w": 280,+ "h": 160,+ "label": "Context Node",+ "type": "POLICY",+ "role": "system",+ "detail": [+ "output-context → input-context",+ "compaction + tail policy"+ ]+ },+ {+ "id": "context-journal",+ "x": 120,+ "y": 510,+ "w": 300,+ "h": 185,+ "label": "AgentContextStore",+ "type": "EXACT JOURNAL",+ "role": "data",+ "detail": [+ "append-only observable events",+ "thread · epoch · revision",+ "provider-bound replay state"+ ]+ },+ {+ "id": "context-checkpoint",+ "x": 440,+ "y": 760,+ "w": 300,+ "h": 150,+ "label": "Replay Checkpoint",+ "type": "CONTEXT STATE",+ "role": "workflow",+ "detail": [+ "native or portable summary",+ "exact recent tail retained"+ ]+ },+ {+ "id": "agent-runtime",+ "x": 810,+ "y": 395,+ "w": 300,+ "h": 250,+ "label": "Agent Runtime",+ "type": "SHARED CONSUMER",+ "role": "agent",+ "detail": [+ "replays Context automatically",+ "invokes Memory explicitly",+ "keeps both namespaces separate"+ ]+ },+ {+ "id": "memory-node",+ "x": 1520,+ "y": 220,+ "w": 280,+ "h": 160,+ "label": "Simple Memory",+ "type": "LOCKED TOOL",+ "role": "tool",+ "detail": [+ "output-tool → input-tools",+ "remember · recall · list",+ "get · update · forget"+ ]+ },+ {+ "id": "memory-store",+ "x": 1500,+ "y": 510,+ "w": 300,+ "h": 185,+ "label": "MemoryToolStore",+ "type": "DURABLE DATA",+ "role": "data",+ "detail": [+ "owner / workflow / node scope",+ "versioned idempotent mutations",+ "lexical + optional embedding"+ ]+ },+ {+ "id": "memory-items",+ "x": 1180,+ "y": 760,+ "w": 300,+ "h": 150,+ "label": "Facts & Decisions",+ "type": "MEMORY ITEMS",+ "role": "result",+ "detail": [+ "returned only when recalled",+ "never automatic transcript"+ ]+ }+ ],+ "relationships": [+ {+ "id": "context-binds-runtime",+ "from": "context-node",+ "to": "agent-runtime",+ "label": "bind policy at input-context",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [+ [+ 430,+ 430+ ],+ [+ 790,+ 430+ ]+ ],+ "labelAt": [+ 600,+ 430+ ]+ },+ {+ "id": "runtime-appends-context",+ "from": "agent-runtime",+ "to": "context-journal",+ "label": "append exact observable events",+ "style": "solid",+ "fromSide": "left",+ "toSide": "right",+ "waypoints": [+ [+ 650,+ 520+ ],+ [+ 650,+ 603+ ]+ ],+ "labelAt": [+ 650,+ 520+ ]+ },+ {+ "id": "journal-compacts",+ "from": "context-journal",+ "to": "context-checkpoint",+ "label": "compact at context pressure",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [+ [+ 270,+ 725+ ],+ [+ 590,+ 725+ ]+ ],+ "labelAt": [+ 430,+ 725+ ]+ },+ {+ "id": "checkpoint-replays",+ "from": "context-checkpoint",+ "to": "agent-runtime",+ "label": "replay checkpoint + exact tail",+ "style": "solid",+ "fromSide": "right",+ "toSide": "bottom",+ "waypoints": [+ [+ 780,+ 835+ ],+ [+ 780,+ 700+ ],+ [+ 960,+ 700+ ]+ ],+ "labelAt": [+ 820,+ 720+ ]+ },+ {+ "id": "memory-registers-tool",+ "from": "memory-node",+ "to": "agent-runtime",+ "label": "register tool at input-tools",+ "style": "solid",+ "fromSide": "left",+ "toSide": "right",+ "waypoints": [+ [+ 1490,+ 430+ ],+ [+ 1130,+ 430+ ]+ ],+ "labelAt": [+ 1320,+ 430+ ]+ },+ {+ "id": "runtime-invokes-memory",+ "from": "agent-runtime",+ "to": "memory-store",+ "label": "remember / recall / update / forget",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [+ [+ 1290,+ 520+ ],+ [+ 1290,+ 603+ ]+ ],+ "labelAt": [+ 1290,+ 520+ ]+ },+ {+ "id": "memory-persists-items",+ "from": "memory-store",+ "to": "memory-items",+ "label": "persist isolated versioned items",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [+ [+ 1650,+ 725+ ],+ [+ 1330,+ 725+ ]+ ],+ "labelAt": [+ 1490,+ 725+ ]+ },+ {+ "id": "memory-returns-items",+ "from": "memory-items",+ "to": "agent-runtime",+ "label": "return selected recalled items",+ "style": "solid",+ "fromSide": "left",+ "toSide": "bottom",+ "waypoints": [+ [+ 1140,+ 835+ ],+ [+ 1140,+ 700+ ],+ [+ 960,+ 700+ ]+ ],+ "labelAt": [+ 1100,+ 680+ ]+ }+ ],+ "callouts": [+ {+ "id": "context-invariant",+ "x": 440,+ "y": 220,+ "w": 300,+ "h": 160,+ "title": "Automatic continuity",+ "lines": [+ "System managed; no model tool call",+ "Exact journal and replay policy",+ "Clear rotates the active epoch"+ ]+ },+ {+ "id": "memory-invariant",+ "x": 1180,+ "y": 220,+ "w": 300,+ "h": 160,+ "title": "Explicit knowledge",+ "lines": [+ "Model or human chooses mutations",+ "Stable facts and decisions only",+ "Clear never clears Agent Context"+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Create a precise side-by-side comparison showing that Agent Context and Simple Memory are separate systems around the same Agent Runtime: Context automatically journals and replays exact execution state, while Simple Memory is an explicit tool for versioned durable facts chosen by the model or a human.",+ "composition": "Mirror two wide bounded lanes around one central Agent Runtime. The left Context lane flows from policy to exact journal to replay checkpoint and back into the runtime. The right Memory lane flows from the explicit tool to a scoped durable store to recalled facts and back into the runtime. Use symmetric geometry so the conceptual contrast is immediate.",+ "constraints": [+ "Label Context connection as output-context to input-context and Memory connection as output-tool to input-tools",+ "Context must be automatic, exact, provider-bound, and system managed",+ "Simple Memory must expose remember, recall, list, get, update, and forget as explicit operations",+ "Memory items must never appear as automatically injected transcript replay",+ "Clearing either system must not imply clearing the other"+ ],+ "avoid": [+ "calling Simple Memory conversation history",+ "showing Context as a model-invoked tool",+ "merging Context journal records with Memory items",+ "implying manual or generation-zero runs always create durable Context"+ ]+ }+}diff --git a/docs-internal/diagram-generation/specs/12-master-skill-editor.json b/docs-internal/diagram-generation/specs/12-master-skill-editor.jsonnew file mode 100644index 00000000..4c77f37b--- /dev/null+++ b/docs-internal/diagram-generation/specs/12-master-skill-editor.json@@ -0,0 +1,381 @@+{+ "id": "12-master-skill-editor",+ "title": "Master Skill Editor",+ "subtitle": "One split panel joins the skill catalogue, authoritative instructions, node configuration, and live retrieval state.",+ "category": "product-panel",+ "diagramType": "product panel with configuration and runtime data flow",+ "description": "Source-backed anatomy of the Master Skill editor: built-in and user skill sources flow through WebSocket handlers and TanStack caches into the catalogue and instruction editor, while enabled skills persist in skills_config, expand for a connected agent, and report safe runtime badges back to the exact Master Skill row.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "client/src/components/parameterPanel/MasterSkillEditor.tsx",+ "reason": "Defines the split catalogue/editor surface, folder and user-skill queries, enable toggles, instruction editing, CRUD actions, skills_config writes, and runtime row badges."+ },+ {+ "path": "client/src/hooks/useFolderSkills.ts",+ "reason": "Defines the folderSkills TanStack query and scan_skill_folder metadata mapping used by the catalogue."+ },+ {+ "path": "server/services/skills/handlers.py",+ "reason": "Owns the list/scan/content handlers, user-skill CRUD, and lifecycle-producing mutation paths used by the editor."+ },+ {+ "path": "server/nodes/skill/master_skill/__init__.py",+ "reason": "Defines the passive Master Skill node, required assistant Skill entry, skills_config parameter shape, and editor UI hints."+ },+ {+ "path": "server/nodes/skill/_expander.py",+ "reason": "Expands enabled skills_config entries into per-skill descriptors for connected agents."+ },+ {+ "path": "server/services/skill_runtime.py",+ "reason": "Loads authoritative instructions progressively and publishes loading, loaded, used, or failed activity to the agent and exact Master Skill node."+ },+ {+ "path": "server/nodes/skill/master_skill/_events.py",+ "reason": "Defines the skill_lifecycle CloudEvent used to invalidate userSkills, folderSkills, and skillContent caches across clients."+ },+ {+ "path": "client/src/contexts/WebSocketContext.tsx",+ "reason": "Routes skill_lifecycle invalidation and live node-status data consumed by the editor."+ }+ ],+ "groups": [+ {+ "id": "skill-sources",+ "x": 70,+ "y": 130,+ "w": 500,+ "h": 700,+ "label": "SKILL SOURCES + WIRE HANDLERS",+ "role": "data"+ },+ {+ "id": "editor-surface",+ "x": 610,+ "y": 130,+ "w": 760,+ "h": 700,+ "label": "MASTER SKILL EDITOR",+ "role": "interface"+ },+ {+ "id": "agent-runtime",+ "x": 1410,+ "y": 130,+ "w": 440,+ "h": 700,+ "label": "CONNECTED AGENT RUNTIME",+ "role": "runtime"+ }+ ],+ "nodes": [+ {+ "id": "skill-ws-handlers",+ "x": 110,+ "y": 200,+ "w": 420,+ "h": 160,+ "label": "Skill WebSocket handlers",+ "labelLines": ["Skill WebSocket", "handlers"],+ "type": "service",+ "role": "system",+ "detail": ["list / scan / get content", "create / update / delete", "skill_lifecycle broadcasts"]+ },+ {+ "id": "builtin-skill-files",+ "x": 110,+ "y": 430,+ "w": 195,+ "h": 150,+ "label": "Built-in SKILL.md",+ "labelLines": ["Built-in", "SKILL.md"],+ "type": "source",+ "role": "data",+ "detail": ["server/skills/*", "metadata + instructions"]+ },+ {+ "id": "user-skill-store",+ "x": 335,+ "y": 430,+ "w": 195,+ "h": 150,+ "label": "User skill store",+ "labelLines": ["User skill", "store"],+ "type": "database",+ "role": "data",+ "detail": ["custom records", "display + instructions"]+ },+ {+ "id": "tanstack-skill-cache",+ "x": 110,+ "y": 650,+ "w": 420,+ "h": 130,+ "label": "TanStack skill caches",+ "labelLines": ["TanStack skill caches"],+ "type": "client state",+ "role": "data",+ "detail": ["userSkills · folderSkills", "skillContent by name"]+ },+ {+ "id": "skill-catalogue-pane",+ "x": 650,+ "y": 200,+ "w": 320,+ "h": 330,+ "label": "Skills catalogue pane",+ "labelLines": ["Skills catalogue", "pane"],+ "type": "interface",+ "role": "interface",+ "detail": ["folder selector + search", "enable / required / custom", "Loading · Loaded · Failed", "enabled count + create"]+ },+ {+ "id": "instructions-editor-pane",+ "x": 1010,+ "y": 200,+ "w": 320,+ "h": 330,+ "label": "Instructions editor pane",+ "labelLines": ["Instructions editor", "pane"],+ "type": "interface",+ "role": "interface",+ "detail": ["authoritative markdown", "create / edit / delete", "reset built-in default", "customized state"]+ },+ {+ "id": "query-projection",+ "x": 650,+ "y": 620,+ "w": 320,+ "h": 150,+ "label": "Catalogue projection",+ "labelLines": ["Catalogue projection"],+ "type": "view model",+ "role": "neutral",+ "detail": ["folder rows + user rows", "selected skill buffer"]+ },+ {+ "id": "skills-config",+ "x": 1010,+ "y": 620,+ "w": 320,+ "h": 150,+ "label": "Master Skill skills_config",+ "labelLines": ["Master Skill", "skills_config"],+ "type": "node params",+ "role": "security",+ "detail": ["enabled · instructions", "isCustomized · required"]+ },+ {+ "id": "master-skill-expander",+ "x": 1450,+ "y": 200,+ "w": 360,+ "h": 150,+ "label": "Master Skill expander",+ "labelLines": ["Master Skill", "expander"],+ "type": "runtime",+ "role": "runtime",+ "detail": ["enabled entries only", "per-skill descriptors"]+ },+ {+ "id": "agent-skill-runtime",+ "x": 1450,+ "y": 430,+ "w": 360,+ "h": 160,+ "label": "Agent Skill runtime",+ "labelLines": ["Agent Skill runtime"],+ "type": "tool runtime",+ "role": "agent",+ "detail": ["progressive load", "declared resources", "bounded safe events"]+ },+ {+ "id": "skill-status-projection",+ "x": 1450,+ "y": 660,+ "w": 360,+ "h": 120,+ "label": "Exact-node status projection",+ "labelLines": ["Exact-node status", "projection"],+ "type": "observability",+ "role": "event",+ "detail": ["active_skills / last_skills"]+ }+ ],+ "relationships": [+ {+ "id": "handlers-scan-builtins",+ "from": "skill-ws-handlers",+ "to": "builtin-skill-files",+ "label": "scan and load metadata + instructions",+ "protocol": "filesystem",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [[220, 390], [208, 390]],+ "labelAt": [205, 390]+ },+ {+ "id": "handlers-crud-user-skills",+ "from": "skill-ws-handlers",+ "to": "user-skill-store",+ "label": "list and mutate custom skills",+ "protocol": "database",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [[430, 390], [433, 390]],+ "labelAt": [430, 390]+ },+ {+ "id": "handlers-refresh-cache",+ "from": "skill-ws-handlers",+ "to": "tanstack-skill-cache",+ "label": "query results and lifecycle invalidation",+ "protocol": "WebSocket",+ "style": "solid",+ "fromSide": "left",+ "toSide": "left",+ "waypoints": [[90, 280], [90, 715]],+ "labelAt": [270, 615]+ },+ {+ "id": "cache-builds-projection",+ "from": "tanstack-skill-cache",+ "to": "query-projection",+ "label": "cached folder, user, and content records",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [590, 690]+ },+ {+ "id": "projection-populates-catalogue",+ "from": "query-projection",+ "to": "skill-catalogue-pane",+ "label": "render and filter rows",+ "style": "solid",+ "fromSide": "top",+ "toSide": "bottom",+ "labelAt": [810, 575]+ },+ {+ "id": "catalogue-selects-editor",+ "from": "skill-catalogue-pane",+ "to": "instructions-editor-pane",+ "label": "select skill",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [990, 350]+ },+ {+ "id": "catalogue-writes-toggle",+ "from": "skill-catalogue-pane",+ "to": "skills-config",+ "label": "toggle enabled / keep required",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "left",+ "waypoints": [[810, 570], [990, 570], [990, 695]],+ "labelAt": [900, 560]+ },+ {+ "id": "editor-writes-instructions",+ "from": "instructions-editor-pane",+ "to": "skills-config",+ "label": "write instructions + customized flag",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1170, 575]+ },+ {+ "id": "editor-user-skill-crud",+ "from": "instructions-editor-pane",+ "to": "skill-ws-handlers",+ "label": "create / update / delete user skill",+ "protocol": "WebSocket",+ "style": "dashed",+ "fromSide": "top",+ "toSide": "top",+ "waypoints": [[1170, 170], [320, 170]],+ "labelAt": [750, 165]+ },+ {+ "id": "config-expands",+ "from": "skills-config",+ "to": "master-skill-expander",+ "label": "expand enabled entries",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [[1385, 695], [1385, 275]],+ "labelAt": [1385, 485]+ },+ {+ "id": "expander-builds-runtime",+ "from": "master-skill-expander",+ "to": "agent-skill-runtime",+ "label": "descriptors + Skill tool catalogue",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1630, 390]+ },+ {+ "id": "runtime-publishes-status",+ "from": "agent-skill-runtime",+ "to": "skill-status-projection",+ "label": "loading / loaded / used / failed",+ "protocol": "node status + CloudEvents",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1630, 625]+ },+ {+ "id": "status-back-to-catalogue",+ "from": "skill-status-projection",+ "to": "skill-catalogue-pane",+ "label": "project safe state onto matching row",+ "style": "dashed",+ "fromSide": "bottom",+ "toSide": "left",+ "waypoints": [[1630, 840], [595, 840], [595, 365]],+ "labelAt": [1090, 835]+ }+ ],+ "callouts": [+ {+ "id": "master-skill-invariant",+ "x": 70,+ "y": 880,+ "w": 1780,+ "h": 90,+ "title": "Configuration is authoritative; observability is sanitized",+ "lines": [+ "skills_config keeps the enabled flag and instruction body used by the connected agent.",+ "Runtime events expose names and states only—never prompts, arguments, results, secrets, or raw exceptions."+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Draw a source-backed product-panel schematic of the Master Skill Editor, showing its split skill catalogue and instructions editor, the built-in and user skill sources, the persisted skills_config, expansion into the connected Agent Skill runtime, and the safe runtime-status feedback loop.",+ "composition": "Use three clearly bounded vertical zones matching the supplied coordinates: source handlers on the left, the split editor and its view/config state in the center, and the connected agent runtime on the right. Keep the bottom status-feedback route outside the cards and reserve the final band for the invariant callout.",+ "constraints": [+ "Show the Skills catalogue pane and Instructions editor pane as equal peers in one editor surface",+ "Keep built-in SKILL.md content distinct from database-backed user skills",+ "Show skills_config as the authoritative enabled/instructions configuration, not a runtime log",+ "Show the runtime feedback arrow returning to the matching catalogue row",+ "Use the exact handler/cache/config/runtime labels supplied in the spec"+ ],+ "avoid": [+ "generic prompt-engineering imagery",+ "implying every skill body is eagerly injected into the system prompt",+ "showing runtime events that contain instruction text or secrets",+ "merging built-in files and user skills into one storage box"+ ]+ }+}diff --git a/docs-internal/diagram-generation/specs/13-workspace-files.json b/docs-internal/diagram-generation/specs/13-workspace-files.jsonnew file mode 100644index 00000000..ff06e111--- /dev/null+++ b/docs-internal/diagram-generation/specs/13-workspace-files.json@@ -0,0 +1,357 @@+{+ "id": "13-workspace-files",+ "title": "Workspace Files",+ "subtitle": "Browse, search, upload, preview, pin, and emit files from the workflow’s contained workspace.",+ "category": "product-panel",+ "diagramType": "product panel with transport and execution paths",+ "description": "Source-backed anatomy of the Gallery node’s Workspace Files panel, separating WebSocket listing/search from HTTP content and upload routes while showing how controlled path and selection parameters drive the Gallery node’s FileRef output.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "client/src/components/parameterPanel/GalleryPanel.tsx",+ "reason": "Defines the Workspace Files header, upload action, preview, pinning, controlled path/selection parameters, and Gallery-panel integration."+ },+ {+ "path": "client/src/components/parameterPanel/gallery/WorkspaceBrowser.tsx",+ "reason": "Defines breadcrumbs, debounced workspace-wide search, grid/list views, refresh and polling, row activation, pinning, and drag payload behavior."+ },+ {+ "path": "server/nodes/filesystem/gallery/_handlers.py",+ "reason": "Defines list_workspace_files as the WebSocket listing/search channel and its workflow-root resolution."+ },+ {+ "path": "server/nodes/filesystem/gallery/_service.py",+ "reason": "Defines directory and recursive glob listing, caps, sorting, crumbs, self-sufficient FileRef rows, URLs, and preview verdicts."+ },+ {+ "path": "server/nodes/filesystem/gallery/__init__.py",+ "reason": "Defines Gallery node parameters and execution branches that emit workspace FileRef rows downstream."+ },+ {+ "path": "server/nodes/filesystem/_backend.py",+ "reason": "Provides the contained WorkspaceBackend used for ls/glob and safe workspace path handling."+ },+ {+ "path": "server/routers/workspace.py",+ "reason": "Defines the HTTP upload and file-content surface used for upload, preview, download, and Range reads."+ },+ {+ "path": "docs-internal/node-logic-flows/code_fs_process/gallery.md",+ "reason": "Documents the reviewed Gallery panel/execution contract and the separation between WebSocket listing and HTTP content."+ }+ ],+ "groups": [+ {+ "id": "workspace-panel",+ "x": 70,+ "y": 130,+ "w": 900,+ "h": 700,+ "label": "GALLERY NODE · WORKSPACE FILES PANEL",+ "role": "interface"+ },+ {+ "id": "workspace-transport",+ "x": 1010,+ "y": 130,+ "w": 840,+ "h": 420,+ "label": "WORKSPACE TRANSPORT + STORAGE",+ "role": "system"+ },+ {+ "id": "gallery-execution",+ "x": 1010,+ "y": 590,+ "w": 840,+ "h": 240,+ "label": "WORKFLOW EXECUTION PATH",+ "role": "runtime"+ }+ ],+ "nodes": [+ {+ "id": "workspace-panel-header",+ "x": 110,+ "y": 200,+ "w": 820,+ "h": 100,+ "label": "Workspace Files header",+ "labelLines": ["Workspace Files header"],+ "type": "interface",+ "role": "interface",+ "detail": ["workflow-produced files · Upload action"]+ },+ {+ "id": "workspace-browser",+ "x": 110,+ "y": 350,+ "w": 500,+ "h": 350,+ "label": "WorkspaceBrowser",+ "labelLines": ["WorkspaceBrowser"],+ "type": "interface",+ "role": "interface",+ "detail": ["breadcrumbs + directory navigation", "250 ms search · whole workspace", "grid / list · refresh · 5 s poll", "empty, missing, truncated states"]+ },+ {+ "id": "workspace-file-actions",+ "x": 650,+ "y": 350,+ "w": 280,+ "h": 350,+ "label": "File actions",+ "labelLines": ["File actions"],+ "type": "interface",+ "role": "tool",+ "detail": ["upload one or many", "preview / download", "pin for node output", "FileRef drag payload"]+ },+ {+ "id": "gallery-node-parameters",+ "x": 300,+ "y": 740,+ "w": 440,+ "h": 70,+ "label": "Node params: path + selection",+ "labelLines": ["Node params · path + selection"],+ "type": "node params",+ "role": "security",+ "detail": []+ },+ {+ "id": "list-workspace-files-handler",+ "x": 1050,+ "y": 200,+ "w": 340,+ "h": 130,+ "label": "list_workspace_files",+ "labelLines": ["list_workspace_files"],+ "type": "WebSocket",+ "role": "event",+ "detail": ["path or workspace-wide search", "limit 500 from panel"]+ },+ {+ "id": "workspace-http-routes",+ "x": 1450,+ "y": 200,+ "w": 360,+ "h": 130,+ "label": "Workspace HTTP routes",+ "labelLines": ["Workspace HTTP routes"],+ "type": "HTTP",+ "role": "interface",+ "detail": ["POST uploads", "GET content · Range"]+ },+ {+ "id": "workspace-listing-service",+ "x": 1050,+ "y": 390,+ "w": 340,+ "h": 130,+ "label": "Workspace listing service",+ "labelLines": ["Workspace listing", "service"],+ "type": "service",+ "role": "system",+ "detail": ["directory or recursive glob", "sort, cap, crumbs, preview"]+ },+ {+ "id": "contained-workspace-root",+ "x": 1450,+ "y": 390,+ "w": 360,+ "h": 130,+ "label": "Contained workflow workspace",+ "labelLines": ["Contained workflow", "workspace"],+ "type": "filesystem",+ "role": "data",+ "detail": ["WorkspaceBackend", "workspace-relative paths"]+ },+ {+ "id": "gallery-node-runtime",+ "x": 1050,+ "y": 650,+ "w": 340,+ "h": 120,+ "label": "Gallery node execution",+ "labelLines": ["Gallery node", "execution"],+ "type": "runtime",+ "role": "runtime",+ "detail": ["selection > pattern > directory"]+ },+ {+ "id": "gallery-file-ref-output",+ "x": 1450,+ "y": 650,+ "w": 360,+ "h": 120,+ "label": "Downstream FileRef output",+ "labelLines": ["Downstream FileRef", "output"],+ "type": "result",+ "role": "result",+ "detail": ["files · directories · missing[]"]+ }+ ],+ "relationships": [+ {+ "id": "header-opens-upload",+ "from": "workspace-panel-header",+ "to": "workspace-file-actions",+ "label": "Upload action",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "waypoints": [[790, 325]],+ "labelAt": [790, 325]+ },+ {+ "id": "browser-activates-file",+ "from": "workspace-browser",+ "to": "workspace-file-actions",+ "label": "activate, pin, or drag file",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [630, 505]+ },+ {+ "id": "browser-requests-listing",+ "from": "workspace-browser",+ "to": "list-workspace-files-handler",+ "label": "browse path or send debounced search",+ "protocol": "WebSocket",+ "style": "solid",+ "fromSide": "top",+ "toSide": "left",+ "waypoints": [[360, 325], [990, 325], [990, 265]],+ "labelAt": [780, 315]+ },+ {+ "id": "handler-selects-listing-mode",+ "from": "list-workspace-files-handler",+ "to": "workspace-listing-service",+ "label": "directory list or recursive search",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1220, 360]+ },+ {+ "id": "listing-reads-workspace",+ "from": "workspace-listing-service",+ "to": "contained-workspace-root",+ "label": "contained ls_info / glob_info",+ "protocol": "async filesystem",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [1420, 450]+ },+ {+ "id": "actions-use-http",+ "from": "workspace-file-actions",+ "to": "workspace-http-routes",+ "label": "upload, preview, or download",+ "protocol": "HTTP",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [[990, 525], [990, 265]],+ "labelAt": [990, 385]+ },+ {+ "id": "http-reads-writes-workspace",+ "from": "workspace-http-routes",+ "to": "contained-workspace-root",+ "label": "write upload or stream content",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1630, 360]+ },+ {+ "id": "browser-controls-path",+ "from": "workspace-browser",+ "to": "gallery-node-parameters",+ "label": "navigation writes path",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "left",+ "waypoints": [[360, 720], [280, 720], [280, 775]],+ "labelAt": [355, 715]+ },+ {+ "id": "actions-control-selection",+ "from": "workspace-file-actions",+ "to": "gallery-node-parameters",+ "label": "pinning writes selection",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "right",+ "waypoints": [[790, 720], [760, 720], [760, 775]],+ "labelAt": [760, 715]+ },+ {+ "id": "params-drive-gallery-run",+ "from": "gallery-node-parameters",+ "to": "gallery-node-runtime",+ "label": "run with path / selection",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [[980, 775], [980, 710]],+ "labelAt": [875, 765]+ },+ {+ "id": "gallery-reuses-listing-service",+ "from": "gallery-node-runtime",+ "to": "workspace-listing-service",+ "label": "reuse listing and FileRef conversion",+ "style": "dashed",+ "fromSide": "top",+ "toSide": "bottom",+ "labelAt": [1220, 585]+ },+ {+ "id": "gallery-emits-output",+ "from": "gallery-node-runtime",+ "to": "gallery-file-ref-output",+ "label": "emit selected or listed files",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [1420, 710]+ }+ ],+ "callouts": [+ {+ "id": "workspace-channel-contract",+ "x": 70,+ "y": 880,+ "w": 1780,+ "h": 90,+ "title": "Two channels, one contained workspace",+ "lines": [+ "WebSocket owns listing and search; HTTP owns upload and file bytes for preview, download, and Range requests.",+ "Rows arrive with a server-built FileRef and preview verdict, so the client does not duplicate path or security decisions."+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Draw a source-backed product-panel schematic of Workspace Files, showing the Gallery panel controls, the WebSocket listing/search path, the HTTP upload/content path, the contained workflow workspace, and the Gallery node’s downstream FileRef output.",+ "composition": "Use a large operator panel on the left, a two-by-two transport/storage block on the upper right, and a compact workflow execution lane on the lower right. Preserve the visible browser/action split and route listing versus content arrows separately.",+ "constraints": [+ "Keep WebSocket listing/search separate from HTTP upload/content",+ "Show path and selection as controlled Gallery node parameters",+ "Show whole-workspace search, grid/list browsing, polling, preview, pinning, and FileRef drag behavior",+ "Show the Gallery execution precedence selection > pattern > directory",+ "Use workspace-relative paths and a single contained workflow workspace"+ ],+ "avoid": [+ "generic cloud-drive branding",+ "implying directories are draggable FileRefs",+ "showing HTTP as the listing channel",+ "showing file delete, rename, or move controls that are not implemented",+ "uncontained host filesystem paths"+ ]+ }+}diff --git a/docs-internal/diagram-generation/specs/14-runtime-observability-dock.json b/docs-internal/diagram-generation/specs/14-runtime-observability-dock.jsonnew file mode 100644index 00000000..7851a224--- /dev/null+++ b/docs-internal/diagram-generation/specs/14-runtime-observability-dock.json@@ -0,0 +1,421 @@+{+ "id": "14-runtime-observability-dock",+ "title": "Runtime Observability Dock",+ "subtitle": "One resizable dock combines workflow chat, Console-node output, and live server/process logs without conflating their scopes.",+ "category": "product-panel",+ "diagramType": "runtime observability product panel and stream topology",+ "description": "Source-backed topology of the collapsible Chat / Console dock: chat messages, Console node records, and terminal logs use distinct producers and retention paths, converge in WebSocketContext state, and render in a resizable chat pane plus Console and Terminal tabs with targeted filters and clear actions.",+ "sourceReview": "reviewed",+ "sourceRefs": [+ {+ "path": "client/src/components/ui/ConsolePanel.tsx",+ "reason": "Defines the collapsible, resizable Chat / Console dock, chat target selector, Console and Terminal tabs, filters, clear controls, auto-scroll, pretty-print, and persisted preferences."+ },+ {+ "path": "client/src/contexts/WebSocketContext.tsx",+ "reason": "Owns live chat/console/terminal arrays, reconnect and workflow-switch hydration, clear commands, send_chat_message, and 100/200-entry client caps."+ },+ {+ "path": "server/nodes/utility/console/__init__.py",+ "reason": "Produces structured Console-node log records and broadcasts them while passing workflow data through."+ },+ {+ "path": "server/services/status_broadcaster.py",+ "reason": "Persists and broadcasts Console logs, retains the last 100 in memory, and retains/broadcasts the last 200 Terminal logs."+ },+ {+ "path": "server/routers/websocket.py",+ "reason": "Defines workflow-scoped chat send/history/clear, Console history/clear, and Terminal history/clear request handlers."+ },+ {+ "path": "server/nodes/trigger/chat_trigger/_events.py",+ "reason": "Dispatches workflow-scoped chat_message_received CloudEvents to waiting chatTrigger consumers and the frontend."+ },+ {+ "path": "server/services/process_service.py",+ "reason": "Streams managed-process output into the Terminal log channel."+ },+ {+ "path": "server/core/logging.py",+ "reason": "Streams server logger records into the Terminal log broadcaster."+ },+ {+ "path": "docs-internal/node-logic-flows/chat_utility/console.md",+ "reason": "Documents the reviewed Console node record shape and StatusBroadcaster side effect consumed by the dock."+ }+ ],+ "groups": [+ {+ "id": "runtime-producers",+ "x": 70,+ "y": 130,+ "w": 460,+ "h": 700,+ "label": "RUNTIME PRODUCERS + CONSUMERS",+ "role": "runtime"+ },+ {+ "id": "observability-transport",+ "x": 570,+ "y": 130,+ "w": 590,+ "h": 700,+ "label": "TRANSPORT + RETAINED STATE",+ "role": "system"+ },+ {+ "id": "observability-dock",+ "x": 1200,+ "y": 130,+ "w": 650,+ "h": 700,+ "label": "COLLAPSIBLE CHAT / CONSOLE DOCK",+ "role": "interface"+ }+ ],+ "nodes": [+ {+ "id": "console-node-producer",+ "x": 110,+ "y": 200,+ "w": 380,+ "h": 150,+ "label": "Console node output",+ "labelLines": ["Console node output"],+ "type": "workflow",+ "role": "workflow",+ "detail": ["label · format · formatted data", "workflow + source node IDs"]+ },+ {+ "id": "terminal-log-producers",+ "x": 110,+ "y": 430,+ "w": 380,+ "h": 150,+ "label": "Server / process / CLI logs",+ "labelLines": ["Server / process / CLI", "logs"],+ "type": "runtime",+ "role": "runtime",+ "detail": ["level · message · source", "optional details"]+ },+ {+ "id": "chat-trigger-consumers",+ "x": 110,+ "y": 660,+ "w": 380,+ "h": 120,+ "label": "chatTrigger consumers",+ "labelLines": ["chatTrigger consumers"],+ "type": "trigger",+ "role": "trigger",+ "detail": ["workflow-scoped CloudEvent"]+ },+ {+ "id": "status-broadcaster",+ "x": 610,+ "y": 200,+ "w": 240,+ "h": 160,+ "label": "StatusBroadcaster",+ "labelLines": ["StatusBroadcaster"],+ "type": "event bus",+ "role": "event",+ "detail": ["console_log", "terminal_log", "clear broadcasts"]+ },+ {+ "id": "dock-ws-handlers",+ "x": 890,+ "y": 200,+ "w": 230,+ "h": 160,+ "label": "Dock WebSocket handlers",+ "labelLines": ["Dock WebSocket", "handlers"],+ "type": "service",+ "role": "system",+ "detail": ["send / get / clear", "chat · console · terminal"]+ },+ {+ "id": "workflow-history-db",+ "x": 610,+ "y": 440,+ "w": 240,+ "h": 130,+ "label": "Workflow history DB",+ "labelLines": ["Workflow history DB"],+ "type": "database",+ "role": "data",+ "detail": ["chat_messages", "console_logs"]+ },+ {+ "id": "terminal-ring-buffer",+ "x": 890,+ "y": 440,+ "w": 230,+ "h": 130,+ "label": "Terminal ring buffer",+ "labelLines": ["Terminal ring", "buffer"],+ "type": "memory",+ "role": "data",+ "detail": ["latest 200 entries", "global in process"]+ },+ {+ "id": "websocket-context-state",+ "x": 760,+ "y": 660,+ "w": 260,+ "h": 120,+ "label": "WebSocketContext state",+ "labelLines": ["WebSocketContext", "state"],+ "type": "client state",+ "role": "system",+ "detail": ["chat · console · terminal arrays"]+ },+ {+ "id": "chat-pane",+ "x": 1240,+ "y": 200,+ "w": 260,+ "h": 500,+ "label": "Chat pane",+ "labelLines": ["Chat pane"],+ "type": "interface",+ "role": "interface",+ "detail": ["All Triggers or one target", "user + assistant messages", "Enter to send", "clear current workflow"]+ },+ {+ "id": "console-tab",+ "x": 1540,+ "y": 200,+ "w": 270,+ "h": 230,+ "label": "Console tab",+ "labelLines": ["Console tab"],+ "type": "interface",+ "role": "interface",+ "detail": ["filter by Console node", "search + pretty print", "workflow-scoped clear"]+ },+ {+ "id": "terminal-tab",+ "x": 1540,+ "y": 470,+ "w": 270,+ "h": 230,+ "label": "Terminal tab",+ "labelLines": ["Terminal tab"],+ "type": "interface",+ "role": "interface",+ "detail": ["level threshold", "message / source search", "global clear"]+ },+ {+ "id": "dock-preferences",+ "x": 1240,+ "y": 720,+ "w": 570,+ "h": 90,+ "label": "Persisted dock preferences",+ "labelLines": ["Persisted dock preferences"],+ "type": "local state",+ "role": "neutral",+ "detail": ["height · split width · font · autoscroll · pretty print · tab"]+ }+ ],+ "relationships": [+ {+ "id": "console-broadcasts-log",+ "from": "console-node-producer",+ "to": "status-broadcaster",+ "label": "broadcast_console_log",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "labelAt": [550, 265]+ },+ {+ "id": "runtime-broadcasts-terminal",+ "from": "terminal-log-producers",+ "to": "status-broadcaster",+ "label": "broadcast_terminal_log",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [[550, 505], [550, 315]],+ "labelAt": [550, 410]+ },+ {+ "id": "broadcaster-persists-console",+ "from": "status-broadcaster",+ "to": "workflow-history-db",+ "label": "persist Console records",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [730, 400]+ },+ {+ "id": "broadcaster-retains-terminal",+ "from": "status-broadcaster",+ "to": "terminal-ring-buffer",+ "label": "retain latest Terminal records",+ "style": "solid",+ "fromSide": "right",+ "toSide": "top",+ "waypoints": [[870, 280], [870, 405], [1005, 405]],+ "labelAt": [920, 395]+ },+ {+ "id": "handlers-query-db",+ "from": "dock-ws-handlers",+ "to": "workflow-history-db",+ "label": "get / clear scoped history",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "right",+ "waypoints": [[1005, 400], [870, 400], [870, 505]],+ "labelAt": [885, 390]+ },+ {+ "id": "handlers-query-terminal-cache",+ "from": "dock-ws-handlers",+ "to": "terminal-ring-buffer",+ "label": "get / clear terminal history",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "top",+ "labelAt": [1005, 400]+ },+ {+ "id": "handlers-dispatch-chat-trigger",+ "from": "dock-ws-handlers",+ "to": "chat-trigger-consumers",+ "label": "dispatch chat_message_received",+ "protocol": "workflow-scoped CloudEvent",+ "style": "solid",+ "fromSide": "left",+ "toSide": "right",+ "waypoints": [[560, 280], [560, 720]],+ "labelAt": [560, 600]+ },+ {+ "id": "live-events-update-context",+ "from": "status-broadcaster",+ "to": "websocket-context-state",+ "label": "live console_log / terminal_log",+ "protocol": "WebSocket broadcast",+ "style": "solid",+ "fromSide": "left",+ "toSide": "left",+ "waypoints": [[590, 280], [590, 720]],+ "labelAt": [675, 625]+ },+ {+ "id": "handlers-hydrate-context",+ "from": "dock-ws-handlers",+ "to": "websocket-context-state",+ "label": "hydrate on connect or workflow switch",+ "style": "dashed",+ "fromSide": "right",+ "toSide": "top",+ "waypoints": [[1140, 280], [1140, 630], [890, 630]],+ "labelAt": [1135, 520]+ },+ {+ "id": "chat-sends-handler-request",+ "from": "chat-pane",+ "to": "dock-ws-handlers",+ "label": "send_chat_message / clear chat",+ "protocol": "WebSocket request",+ "style": "solid",+ "fromSide": "top",+ "toSide": "top",+ "waypoints": [[1370, 165], [1005, 165]],+ "labelAt": [1190, 160]+ },+ {+ "id": "context-renders-chat",+ "from": "websocket-context-state",+ "to": "chat-pane",+ "label": "chat messages",+ "style": "solid",+ "fromSide": "right",+ "toSide": "left",+ "waypoints": [[1180, 720], [1180, 450]],+ "labelAt": [1180, 585]+ },+ {+ "id": "context-renders-console",+ "from": "websocket-context-state",+ "to": "console-tab",+ "label": "Console records",+ "style": "solid",+ "fromSide": "top",+ "toSide": "top",+ "waypoints": [[890, 610], [1175, 610], [1175, 145], [1675, 145]],+ "labelAt": [1510, 140]+ },+ {+ "id": "context-renders-terminal",+ "from": "websocket-context-state",+ "to": "terminal-tab",+ "label": "Terminal records",+ "style": "solid",+ "fromSide": "bottom",+ "toSide": "bottom",+ "waypoints": [[890, 845], [1675, 845]],+ "labelAt": [1480, 840]+ },+ {+ "id": "prefs-shape-chat-pane",+ "from": "dock-preferences",+ "to": "chat-pane",+ "label": "height + split width + font",+ "style": "dashed",+ "fromSide": "left",+ "toSide": "bottom",+ "waypoints": [[1220, 775], [1220, 720], [1370, 720]],+ "labelAt": [1300, 715]+ },+ {+ "id": "prefs-select-log-tab",+ "from": "dock-preferences",+ "to": "terminal-tab",+ "label": "selected Console / Terminal tab",+ "style": "dashed",+ "fromSide": "right",+ "toSide": "bottom",+ "waypoints": [[1830, 775], [1830, 720], [1675, 720]],+ "labelAt": [1725, 715]+ }+ ],+ "callouts": [+ {+ "id": "observability-scope-contract",+ "x": 70,+ "y": 880,+ "w": 1780,+ "h": 90,+ "title": "Scope and retention stay deliberately distinct",+ "lines": [+ "Chat and Console history are persisted and scoped to the current workflow; Terminal history is a process-wide in-memory buffer of the latest 200 entries.",+ "The dock persists only presentation preferences in localStorage—panel height, split width, font size, auto-scroll, pretty print, and selected log tab."+ ]+ }+ ],+ "prompt": {+ "primaryRequest": "Draw a source-backed runtime observability schematic of the collapsible Chat / Console dock, showing the three distinct streams—workflow chat, Console-node records, and Terminal server/process logs—from producers and retained state through WebSocketContext into the chat pane and Console/Terminal tabs.",+ "composition": "Use three vertical zones: runtime producers on the left, transport and retained state in the center, and the actual dock on the right. Inside the dock, show a tall Chat pane beside stacked Console and Terminal tab cards, plus a narrow persisted-preferences bar along the bottom.",+ "constraints": [+ "Keep workflow Chat, Console-node output, and Terminal logs visibly separate",+ "Show chat and Console history as workflow-scoped and database-persisted",+ "Show Terminal history as a global in-memory latest-200 buffer",+ "Show live broadcasts and reconnect/workflow-switch hydration as separate labelled flows",+ "Show the actual chat target, Console-node filter, Terminal-level filter, clear controls, and resizable persisted preferences"+ ],+ "avoid": [+ "merging Console and Terminal into one undifferentiated log stream",+ "implying Terminal history is workflow-scoped or database-persisted",+ "showing a generic monitoring dashboard with charts",+ "extra tabs beyond Chat, Console, and Terminal",+ "unlabelled bidirectional connectors"+ ]+ }+}diff --git a/docs-internal/diagram-generation/validation-report.json b/docs-internal/diagram-generation/validation-report.jsonnew file mode 100644index 00000000..93350791--- /dev/null+++ b/docs-internal/diagram-generation/validation-report.json@@ -0,0 +1,357 @@+{+ "ok": true,+ "expectedDiagramCount": 14,+ "actualDiagramCount": 14,+ "diagrams": [+ {+ "id": "01-system-context",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "7b0bff93951dc145",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "7b0bff93951dc145",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "02-runtime-trust-topology",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "ef4930f8db7feab0",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "ef4930f8db7feab0",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "03-workflow-execution-routing",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "a9db68cb272c047f",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "a9db68cb272c047f",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "04-durable-deployment-events",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "8df81da298fbe73d",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "8df81da298fbe73d",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "05-plugin-agent-team-composition",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "8152ad164c866305",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "8152ad164c866305",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "06-persistence-secret-plane",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "4dd0e49b0c18cbb7",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "4dd0e49b0c18cbb7",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "07-workspace-anatomy",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "d94e6e84070c5188",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "d94e6e84070c5188",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "08-node-configuration-anatomy",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "35179531c67b57ed",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "35179531c67b57ed",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "09-credentials-architecture",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "516cf648ab56c9c9",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "516cf648ab56c9c9",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "10-team-operations",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "9002f02d01716d7e",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "9002f02d01716d7e",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "11-agent-context-memory",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "c807035cec3f020d",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "c807035cec3f020d",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "12-master-skill-editor",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "37076efb9c516523",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "37076efb9c516523",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "13-workspace-files",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "c97fa2af80f57078",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "c97fa2af80f57078",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ },+ {+ "id": "14-runtime-observability-dock",+ "errors": [],+ "themes": {+ "dark": {+ "svgErrors": [],+ "geometrySignature": "66d4ac8c11b8cc0a",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ },+ "light": {+ "svgErrors": [],+ "geometrySignature": "66d4ac8c11b8cc0a",+ "draftError": null,+ "draftDimensions": [+ 1672,+ 941+ ]+ }+ },+ "ok": true+ }+ ]+}diff --git a/docs-internal/diagram-generation/visual-review.md b/docs-internal/diagram-generation/visual-review.mdnew file mode 100644index 00000000..d66c3893--- /dev/null+++ b/docs-internal/diagram-generation/visual-review.md@@ -0,0 +1,32 @@+# SVG visual review++- Reviewed: `2026-08-04`+- Frozen source commit: `5f7522250eae7b0d02ddfd8ee3740fdf5be4c25e`+- Render targets: `1920 × 1080` and `960 × 540`+- Themes: dark and light+- Authoritative artifacts: `docs/diagrams/v2/{dark,light}/*.svg`++Each final SVG was rendered in a Chromium-based browser at native resolution and at README width. The review checked clipping, text and card collisions, connector-label placement, arrow crossings, hierarchy, theme contrast, and dark/light topology parity.++| Diagram | Dark 1920 | Light 1920 | Dark 960 | Light 960 |+|---|---|---|---|---|+| 01 System context | Pass | Pass | Pass | Pass |+| 02 Runtime and trust topology | Pass | Pass | Pass | Pass |+| 03 Workflow execution routing | Pass | Pass | Pass | Pass |+| 04 Durable deployment and events | Pass | Pass | Pass | Pass |+| 05 Plugin, model, agent, and team composition | Pass | Pass | Pass | Pass |+| 06 Persistence and secret plane | Pass | Pass | Pass | Pass |+| 07 Workspace anatomy | Pass | Pass | Pass | Pass |+| 08 Node Configuration anatomy | Pass | Pass | Pass | Pass |+| 09 Credentials architecture | Pass | Pass | Pass | Pass |+| 10 Team operations | Pass | Pass | Pass | Pass |+| 11 Agent Context versus Memory | Pass | Pass | Pass | Pass |+| 12 Master Skill Editor | Pass | Pass | Pass | Pass |+| 13 Workspace files | Pass | Pass | Pass | Pass |+| 14 Runtime observability dock | Pass | Pass | Pass | Pass |++The final pass found no clipped content or unresolved component/label collisions. Dense architecture views intentionally use orthogonal routes, opaque relationship-label plates, and subtle dashed leaders to preserve direction and readability where routes cross.++AI-generated PNGs were inspected as non-authoritative composition drafts. Generation-specific text or connector defects may remain in those drafts; the matching SVGs are the validated source-backed documentation artifacts.++Temporary browser render outputs are excluded from version control.diff --git a/docs/diagrams/v2/README.md b/docs/diagrams/v2/README.mdnew file mode 100644index 00000000..c574f99f--- /dev/null+++ b/docs/diagrams/v2/README.md@@ -0,0 +1,22 @@+# OpenCompany v2 diagrams++Source-backed architecture and product-panel diagrams. Dark and light variants share identical geometry. AI-generated drafts and prompts are retained under `docs-internal/diagram-generation/`.++| Diagram | Dark | Light |+|---|---|---|+| OpenCompany System Context | [dark](dark/01-system-context.svg) | [light](light/01-system-context.svg) |+| Runtime and Trust Topology | [dark](dark/02-runtime-trust-topology.svg) | [light](light/02-runtime-trust-topology.svg) |+| Workflow Execution Routing | [dark](dark/03-workflow-execution-routing.svg) | [light](light/03-workflow-execution-routing.svg) |+| Durable Deployment and Events | [dark](dark/04-durable-deployment-events.svg) | [light](light/04-durable-deployment-events.svg) |+| Plugin → Agent → Team Composition | [dark](dark/05-plugin-agent-team-composition.svg) | [light](light/05-plugin-agent-team-composition.svg) |+| Persistence & Secret Plane | [dark](dark/06-persistence-secret-plane.svg) | [light](light/06-persistence-secret-plane.svg) |+| Workspace Anatomy | [dark](dark/07-workspace-anatomy.svg) | [light](light/07-workspace-anatomy.svg) |+| Node Configuration Anatomy | [dark](dark/08-node-configuration-anatomy.svg) | [light](light/08-node-configuration-anatomy.svg) |+| Credentials Architecture | [dark](dark/09-credentials-architecture.svg) | [light](light/09-credentials-architecture.svg) |+| Team Operations | [dark](dark/10-team-operations.svg) | [light](light/10-team-operations.svg) |+| Agent Context vs. Simple Memory | [dark](dark/11-agent-context-memory.svg) | [light](light/11-agent-context-memory.svg) |+| Master Skill Editor | [dark](dark/12-master-skill-editor.svg) | [light](light/12-master-skill-editor.svg) |+| Workspace Files | [dark](dark/13-workspace-files.svg) | [light](light/13-workspace-files.svg) |+| Runtime Observability Dock | [dark](dark/14-runtime-observability-dock.svg) | [light](light/14-runtime-observability-dock.svg) |++The six existing public diagrams remain unchanged. These v2 assets are additive until separately approved for public-document replacement.diff --git a/docs/diagrams/v2/dark/01-system-context.svg b/docs/diagrams/v2/dark/01-system-context.svgnew file mode 100644index 00000000..1eae9224--- /dev/null+++ b/docs/diagrams/v2/dark/01-system-context.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="7b0bff93951dc145">+<title id="title">OpenCompany System Context — dark theme</title>+<desc id="desc">A C4-style system context view of OpenCompany as an automation workspace between human users and external model, productivity, messaging, device, developer, and retrieval services. Sources: README.md; server/nodes/groups.py; server/config/credential_providers.json; server/main.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">OpenCompany System Context</text>+<text x="72" y="91" class="subtitle">Who uses the system and which external capabilities it orchestrates</text>+<g data-group-id="opencompany-boundary"><rect x="420" y="145" width="930" height="800" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="440" y="177" class="group-label">OPENCOMPANY SYSTEM BOUNDARY</text></g><g data-relationship-id="r-authors-design"><title>Design and run automations · via Browser UI / CLI</title><path d="M 340 327.5 L 510 327 L 510 445 L 665 487.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="389.2" y="341.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="500" y="362" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Design and run automations</text><text x="500" y="382" class="edge-protocol" text-anchor="middle">via Browser UI / CLI</text></g><g data-relationship-id="r-operators-control"><title>Control deployed workflows · via Browser UI / WebSocket</title><path d="M 340 702.5 L 535 702 L 535 535 L 665 487.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="394.2" y="641.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="505" y="662" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Control deployed workflows</text><text x="505" y="682" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via Browser UI / WebSocket</text></g><g data-relationship-id="r-opencompany-llm"><title>Requests inference · via Provider SDK / HTTPS</title><path d="M 1105 487.5 L 1210 487 L 1210 182 L 1480 182.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1221.8" y="158.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1325" y="179" class="edge-label" text-anchor="middle">Requests inference</text><text x="1325" y="199" class="edge-protocol" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">via Provider SDK / HTTPS</text></g><g data-relationship-id="r-opencompany-productivity"><title>Reads and updates work · via OAuth / HTTPS</title><path d="M 1105 487.5 L 1240 487 L 1240 327 L 1480 327.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1254.4" y="303.0" width="191.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1350" y="324" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Reads and updates work</text><text x="1350" y="344" class="edge-protocol" text-anchor="middle">via OAuth / HTTPS</text></g><g data-relationship-id="r-opencompany-messaging"><title>Sends and receives messages · via Webhooks / RPC</title><path d="M 1105 487.5 L 1270 487 L 1270 472 L 1480 472.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1365.0 472.0 L 1275 472" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1160.4" y="448.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1275" y="469" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Sends and receives messages</text><text x="1275" y="489" class="edge-protocol" text-anchor="middle">via Webhooks / RPC</text></g><g data-relationship-id="r-opencompany-devices"><title>Invokes device actions · via RPC / platform APIs</title><path d="M 1105 487.5 L 1270 487 L 1270 617 L 1480 617.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1260.6" y="593.0" width="198.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1360" y="614" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">Invokes device actions</text><text x="1360" y="634" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via RPC / platform APIs</text></g><g data-relationship-id="r-opencompany-developer"><title>Uses code and dev tools · via MCP / CLI / HTTPS</title><path d="M 1105 487.5 L 1240 487 L 1240 762 L 1480 762.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1250.6" y="738.0" width="198.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1350" y="759" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">Uses code and dev tools</text><text x="1350" y="779" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via MCP / CLI / HTTPS</text></g><g data-relationship-id="r-opencompany-search"><title>Indexes and retrieves knowledge · via HTTPS / vector API</title><path d="M 1105 487.5 L 1210 487 L 1210 910 L 1480 910.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1210.2" y="886.0" width="259.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1340" y="907" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">Indexes and retrieves knowledge</text><text x="1340" y="927" class="edge-protocol" text-anchor="middle">via HTTPS / vector API</text></g><g data-component-id="workflow-authors"><title>Workflow authors</title><rect x="55" y="265" width="285" height="125" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="55" y="265" width="285" height="7" rx="4" fill="#f1fa8c"/><text x="73" y="291" class="type-label">PERSON</text><text x="73" y="317" class="node-label">Workflow authors</text><text x="73" y="343" class="node-detail">Build and test automations</text></g><g data-component-id="workflow-operators"><title>Workflow operators</title><rect x="55" y="640" width="285" height="125" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="55" y="640" width="285" height="7" rx="4" fill="#f1fa8c"/><text x="73" y="666" class="type-label">PERSON</text><text x="73" y="692" class="node-label">Workflow operators</text><text x="73" y="718" class="node-detail">Deploy and supervise runs</text></g><g data-component-id="opencompany"><title>OpenCompany</title><rect x="665" y="385" width="440" height="205" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="665" y="385" width="440" height="7" rx="4" fill="#bd93f9"/><text x="683" y="411" class="type-label">SOFTWARE SYSTEM</text><text x="683" y="437" class="node-label">OpenCompany</text><text x="683" y="463" class="node-detail">Visual workflow workspace</text><text x="683" y="483" class="node-detail">Agents, tools, triggers and durable runs</text></g><g data-component-id="llm-providers"><title>LLM providers</title><rect x="1480" y="130" width="365" height="105" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1480" y="130" width="365" height="7" rx="4" fill="#8be9fd"/><text x="1498" y="156" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="182" class="node-label">LLM providers</text><text x="1498" y="208" class="node-detail">Hosted and local inference</text></g><g data-component-id="productivity-services"><title>Productivity services</title><rect x="1480" y="275" width="365" height="105" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="275" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="301" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="327" class="node-label">Productivity services</text><text x="1498" y="353" class="node-detail">Mail, calendar, docs and CRM</text></g><g data-component-id="messaging-channels"><title>Messaging channels</title><rect x="1480" y="420" width="365" height="105" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="420" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="446" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="472" class="node-label">Messaging channels</text><text x="1498" y="498" class="node-detail">Chat and social platforms</text></g><g data-component-id="connected-devices"><title>Connected devices</title><rect x="1480" y="565" width="365" height="105" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="565" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="591" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="617" class="node-label">Connected devices</text><text x="1498" y="643" class="node-detail">Android and device services</text></g><g data-component-id="developer-services"><title>Developer services</title><rect x="1480" y="710" width="365" height="105" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1480" y="710" width="365" height="7" rx="4" fill="#8be9fd"/><text x="1498" y="736" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="762" class="node-label">Developer services</text><text x="1498" y="788" class="node-detail">Code, CLI and MCP tools</text></g><g data-component-id="search-vector-stores"><title>Search and vector stores</title><rect x="1480" y="855" width="365" height="110" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1480" y="855" width="365" height="7" rx="4" fill="#ff79c6"/><text x="1498" y="881" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="907" class="node-label">Search and</text><text x="1498" y="929" class="node-label">vector stores</text><text x="1498" y="955" class="node-detail">Retrieval and knowledge indexes</text></g><g data-callout-id="system-purpose"><rect x="615" y="700" width="540" height="135" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="631" y="730" class="callout-title">System responsibility</text><text x="631" y="756" class="callout-text">Compose external capabilities as directed graphs.</text><text x="631" y="778" class="callout-text">Keep execution, credentials and observability</text><text x="631" y="800" class="callout-text">inside one user-scoped workspace.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/02-runtime-trust-topology.svg b/docs/diagrams/v2/dark/02-runtime-trust-topology.svgnew file mode 100644index 00000000..cc4c37e9--- /dev/null+++ b/docs/diagrams/v2/dark/02-runtime-trust-topology.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="ef4930f8db7feab0">+<title id="title">Runtime and Trust Topology — dark theme</title>+<desc id="desc">A runtime topology that distinguishes the browser and CLI clients, Vite development proxy, FastAPI application, protected and restricted protocol surfaces, Temporal orchestration, and lazily started helper processes. Sources: .env.template; client/vite.config.js; server/main.py; server/middleware/auth.py; server/routers/websocket.py; server/services/authz/ws_surface.py; server/services/cli_agent/mcp_server.py; server/services/temporal/lifecycle.py; server/nodes/code/_runtime.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Runtime and Trust Topology</text>+<text x="72" y="91" class="subtitle">Development and production paths, authenticated surfaces, durable orchestration and lazy helpers</text>+<g data-group-id="client-zone"><rect x="40" y="135" width="350" height="830" rx="18" fill="#15171c" stroke="#f1fa8c" stroke-width="2"/><text x="60" y="167" class="group-label">CLIENTS AND PUBLIC SENDERS</text></g><g data-group-id="app-zone"><rect x="425" y="135" width="1050" height="830" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="445" y="167" class="group-label">OPENCOMPANY APPLICATION</text></g><g data-group-id="runtime-zone"><rect x="1510" y="135" width="370" height="830" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1530" y="167" class="group-label">DURABLE AND LAZY RUNTIMES</text></g><g data-relationship-id="r-browser-vite"><title>Loads SPA in development · via HTTP :5678</title><path d="M 360 272.5 L 455 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 238.0 L 315 400" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="211.8" y="376.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="315" y="397" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Loads SPA in development</text><text x="315" y="417" class="edge-protocol" text-anchor="middle">via HTTP :5678</text></g><g data-relationship-id="r-vite-fastapi"><title>Proxies /api /ws /webhook /health /mcp · via HTTP / WS :5679</title><path d="M 735 257.5 L 820 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 340.0 L 780 556" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="623.6" y="532.0" width="312.8" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="780" y="553" class="edge-label" text-anchor="middle" textLength="294.8" lengthAdjust="spacingAndGlyphs">Proxies /api /ws /webhook /health /mcp</text><text x="780" y="573" class="edge-protocol" text-anchor="middle">via HTTP / WS :5679</text></g><g data-relationship-id="r-cli-fastapi"><title>Launches and administers · via Typer / process</title><path d="M 360 527.5 L 405 527 L 405 365 L 790 365 L 790 257 L 820 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="486.8" y="341.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="590" y="362" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Launches and administers</text><text x="590" y="382" class="edge-protocol" text-anchor="middle">via Typer / process</text></g><g data-relationship-id="r-browser-rest"><title>Calls protected routes · via HTTPS + JWT cookie</title><path d="M 360 272.5 L 405 272 L 405 460 L 455 460.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 395.0 L 495 557" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="399.4" y="533.0" width="191.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="495" y="554" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Calls protected routes</text><text x="495" y="574" class="edge-protocol" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">via HTTPS + JWT cookie</text></g><g data-relationship-id="r-browser-status"><title>Commands and receives status · via WebSocket + cookie</title><path d="M 360 272.5 L 400 272 L 400 580 L 780 580 L 780 460 L 820 460.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 585.0 580.0 L 315 634" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="196.60000000000002" y="610.0" width="236.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="315" y="631" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">Commands and receives status</text><text x="315" y="651" class="edge-protocol" text-anchor="middle">via WebSocket + cookie</text></g><g data-relationship-id="r-cli-mcp"><title>Invokes scoped tools · via MCP over HTTP + Bearer</title><path d="M 360 527.5 L 405 527 L 405 715 L 455 715.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 635.0 L 315 689" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="204.2" y="665.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="315" y="686" class="edge-label" text-anchor="middle">Invokes scoped tools</text><text x="315" y="706" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via MCP over HTTP + Bearer</text></g><g data-relationship-id="r-webhook-ingress"><title>Delivers provider events · via HTTPS webhook</title><path d="M 360 792.5 L 820 715.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 585.0 815.0 L 405 923" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="301.8" y="899.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="405" y="920" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Delivers provider events</text><text x="405" y="940" class="edge-protocol" text-anchor="middle">via HTTPS webhook</text></g><g data-relationship-id="r-surfaces-app"><title>Dispatches request · via ASGI</title><path d="M 595.0 400 L 595 365 L 970 365 L 970.0 325" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="704.6" y="341.0" width="160.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="785" y="362" class="edge-label" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">Dispatches request</text><text x="785" y="382" class="edge-protocol" text-anchor="middle">via ASGI</text></g><g data-relationship-id="r-status-app"><title>Dispatches authenticated message · via ASGI WebSocket</title><path d="M 960.0 400 L 970.0 325" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 970.0 365.0 L 1060 365" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="926.4" y="341.0" width="267.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1060" y="362" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Dispatches authenticated message</text><text x="1060" y="382" class="edge-protocol" text-anchor="middle">via ASGI WebSocket</text></g><g data-relationship-id="r-temporal-internal"><title>Calls legacy node handlers · via WebSocket</title><path d="M 1540 282.5 L 1500 282 L 1500 460 L 1445 460.0" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1500.0 390.0 L 1590 390" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1479.2" y="366.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1590" y="387" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Calls legacy node handlers</text><text x="1590" y="407" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="r-fastapi-temporal"><title>Starts workflows and polls tasks · via Temporal gRPC :5681</title><path d="M 1120 257.5 L 1540 282.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1191.4" y="231.0" width="267.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1325" y="252" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Starts workflows and polls tasks</text><text x="1325" y="272" class="edge-protocol" text-anchor="middle">via Temporal gRPC :5681</text></g><g data-relationship-id="r-fastapi-nodejs"><title>Starts on demand and executes JavaScript · via HTTP :5682</title><path d="M 1120 257.5 L 1485 257 L 1485 537 L 1540 537.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1390.0 537.0 L 1300 591" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1136.0" y="567.0" width="328.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1300" y="588" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">Starts on demand and executes JavaScript</text><text x="1300" y="608" class="edge-protocol" text-anchor="middle">via HTTP :5682</text></g><g data-relationship-id="r-fastapi-whatsapp"><title>Starts on demand and sends commands · via RPC :5683</title><path d="M 1120 257.5 L 1460 257 L 1460 797 L 1540 797.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1395.0 797.0 L 1575 905" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1430.0" y="881.0" width="290.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1575" y="902" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">Starts on demand and sends commands</text><text x="1575" y="922" class="edge-protocol" text-anchor="middle">via RPC :5683</text></g><g data-relationship-id="r-fastapi-spa"><title>Serves production fallback · via StaticFiles / HTML</title><path d="M 970.0 325 L 970 605 L 1305 605 L 1305.0 655" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1140.0 605.0 L 960 605" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="849.2" y="581.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="960" y="602" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Serves production fallback</text><text x="960" y="622" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via StaticFiles / HTML</text></g><g data-component-id="browser-spa"><title>Browser SPA</title><rect x="70" y="215" width="290" height="115" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="70" y="215" width="290" height="7" rx="4" fill="#f1fa8c"/><text x="88" y="241" class="type-label">CLIENT</text><text x="88" y="267" class="node-label">Browser SPA</text><text x="88" y="293" class="node-detail">React workflow workspace</text></g><g data-component-id="opencompany-cli"><title>OpenCompany CLI</title><rect x="70" y="470" width="290" height="115" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="70" y="470" width="290" height="7" rx="4" fill="#f1fa8c"/><text x="88" y="496" class="type-label">CLIENT</text><text x="88" y="522" class="node-label">OpenCompany CLI</text><text x="88" y="548" class="node-detail" textLength="254.0" lengthAdjust="spacingAndGlyphs">Typer launcher and agent client</text></g><g data-component-id="webhook-senders"><title>Webhook senders</title><rect x="70" y="735" width="290" height="115" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="70" y="735" width="290" height="7" rx="4" fill="#ff79c6"/><text x="88" y="761" class="type-label">EXTERNAL</text><text x="88" y="787" class="node-label">Webhook senders</text><text x="88" y="813" class="node-detail">Provider callbacks</text></g><g data-component-id="vite-dev"><title>Vite development server</title><rect x="455" y="190" width="280" height="135" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="455" y="190" width="280" height="7" rx="4" fill="#8be9fd"/><text x="473" y="216" class="type-label">CONTAINER</text><text x="473" y="242" class="node-label">Vite development</text><text x="473" y="264" class="node-label">server</text><text x="473" y="290" class="node-detail">Port 5678 · development only</text></g><g data-component-id="fastapi-app"><title>FastAPI application</title><rect x="820" y="190" width="300" height="135" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="820" y="190" width="300" height="7" rx="4" fill="#bd93f9"/><text x="838" y="216" class="type-label">CONTAINER</text><text x="838" y="242" class="node-label">FastAPI application</text><text x="838" y="268" class="node-detail">5679 dev · 5678 production</text></g><g data-component-id="rest-surface"><title>Protected REST API</title><rect x="455" y="400" width="280" height="120" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="455" y="400" width="280" height="7" rx="4" fill="#8be9fd"/><text x="473" y="426" class="type-label">INTERFACE</text><text x="473" y="452" class="node-label">Protected REST API</text><text x="473" y="478" class="node-detail">Authenticated /api routes</text></g><g data-component-id="status-socket"><title>/ws/status</title><rect x="820" y="400" width="280" height="120" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="820" y="400" width="280" height="7" rx="4" fill="#8be9fd"/><text x="838" y="426" class="type-label">WEBSOCKET</text><text x="838" y="452" class="node-label">/ws/status</text><text x="838" y="478" class="node-detail">Cookie-derived user identity</text></g><g data-component-id="internal-socket"><title>/ws/internal</title><rect x="1165" y="400" width="280" height="120" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1165" y="400" width="280" height="7" rx="4" fill="#f1fa8c"/><text x="1183" y="426" class="type-label">WEBSOCKET</text><text x="1183" y="452" class="node-label">/ws/internal</text><text x="1183" y="478" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Local allowlist · payload identity</text></g><g data-component-id="mcp-surface"><title>/mcp/ide/mcp</title><rect x="455" y="655" width="280" height="120" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="455" y="655" width="280" height="7" rx="4" fill="#f1fa8c"/><text x="473" y="681" class="type-label">MCP ENDPOINT</text><text x="473" y="707" class="node-label">/mcp/ide/mcp</text><text x="473" y="733" class="node-detail">Per-batch bearer token</text></g><g data-component-id="webhook-ingress"><title>/webhook/*</title><rect x="820" y="655" width="280" height="120" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="820" y="655" width="280" height="7" rx="4" fill="#ff79c6"/><text x="838" y="681" class="type-label">HTTP INGRESS</text><text x="838" y="707" class="node-label">/webhook/*</text><text x="838" y="733" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Public route · provider verification</text></g><g data-component-id="production-spa"><title>Production SPA assets</title><rect x="1165" y="655" width="280" height="120" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1165" y="655" width="280" height="7" rx="4" fill="#8be9fd"/><text x="1183" y="681" class="type-label">STATIC CONTENT</text><text x="1183" y="707" class="node-label">Production SPA assets</text><text x="1183" y="733" class="node-detail">Served by FastAPI</text></g><g data-component-id="temporal-runtime"><title>Temporal server and worker</title><rect x="1540" y="210" width="310" height="145" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="210" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="236" class="type-label">DURABLE RUNTIME</text><text x="1558" y="262" class="node-label">Temporal server</text><text x="1558" y="284" class="node-label">and worker</text><text x="1558" y="310" class="node-detail">UI 5680 · gRPC 5681</text></g><g data-component-id="nodejs-sidecar"><title>Node.js executor</title><rect x="1540" y="475" width="310" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="475" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="501" class="type-label">LAZY SIDECAR</text><text x="1558" y="527" class="node-label">Node.js executor</text><text x="1558" y="553" class="node-detail">HTTP · port 5682</text></g><g data-component-id="whatsapp-sidecar"><title>WhatsApp RPC</title><rect x="1540" y="735" width="310" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="735" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="761" class="type-label">LAZY SIDECAR</text><text x="1558" y="787" class="node-label">WhatsApp RPC</text><text x="1558" y="813" class="node-detail">RPC · port 5683</text></g><g data-callout-id="trust-rules"><rect x="535" y="795" width="835" height="155" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="551" y="825" class="callout-title">Trust rules</text><text x="551" y="851" class="callout-text">REST and /ws/status use authenticated server-owned identity.</text><text x="551" y="873" class="callout-text">/ws/internal is local-only, unauthenticated, and restricted to</text><text x="551" y="895" class="callout-text">execute_node, execute_ai_node, and ping.</text><text x="551" y="917" class="callout-text">/mcp/ide/mcp uses a short-lived per-batch Bearer token;</text><text x="551" y="939" class="callout-text">/webhook/* verifies provider signatures where configured.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/03-workflow-execution-routing.svg b/docs/diagrams/v2/dark/03-workflow-execution-routing.svgnew file mode 100644index 00000000..058a4f0d--- /dev/null+++ b/docs/diagrams/v2/dark/03-workflow-execution-routing.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="a9db68cb272c047f">+<title id="title">Workflow Execution Routing — dark theme</title>+<desc id="desc">A directed execution flow covering direct single-node execution, the WorkflowService routing decision, Temporal, Redis-backed parallel, and sequential orchestration paths, plus the canonical NodeExecutor pipeline and status persistence. Sources: server/services/workflow.py; server/services/node_executor.py; server/services/execution/executor.py; server/services/temporal/executor.py; server/services/temporal/workflow.py; server/services/status_broadcaster.py; server/routers/workflow.py; server/routers/websocket.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Workflow Execution Routing</text>+<text x="72" y="91" class="subtitle">Single-node requests and whole-graph runs converge on the same plugin execution pipeline</text>+<g data-group-id="entry-zone"><rect x="45" y="150" width="300" height="790" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="65" y="182" class="group-label">ENTRY</text></g><g data-group-id="routing-zone"><rect x="385" y="150" width="775" height="790" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="405" y="182" class="group-label">GRAPH ORCHESTRATION</text></g><g data-group-id="node-pipeline-zone"><rect x="1200" y="150" width="675" height="790" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1220" y="182" class="group-label">NODEEXECUTOR PIPELINE</text></g><g data-relationship-id="r-single-pipeline"><title>Executes directly · via WorkflowService.execute_node</title><path d="M 315 312.5 L 360 312 L 360 120 L 1180 120 L 1180 257 L 1240 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 120.0 L 780 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="646.4" y="124.0" width="267.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="780" y="145.0" class="edge-label" text-anchor="middle">Executes directly</text><text x="780" y="165.0" class="edge-protocol" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">via WorkflowService.execute_node</text></g><g data-relationship-id="r-whole-routing"><title>Submits nodes, edges and identity · via WorkflowService.execute_workflow</title><path d="M 315 687.5 L 365 687 L 365 322 L 455 322.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="216.20000000000002" y="481.0" width="297.59999999999997" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="365" y="502" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">Submits nodes, edges and identity</text><text x="365" y="522" class="edge-protocol" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">via WorkflowService.execute_workflow</text></g><g data-relationship-id="r-routing-temporal"><title>Chooses when requested and wired · via Temporal</title><path d="M 755 322.5 L 820 267.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 235.0 L 1060 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="926.4" y="124.0" width="267.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1060" y="145.0" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Chooses when requested and wired</text><text x="1060" y="165.0" class="edge-protocol" text-anchor="middle">via Temporal</text></g><g data-relationship-id="r-routing-parallel"><title>Else chooses when parallel and Redis enabled · via in-process + Redis</title><path d="M 755 322.5 L 785 322 L 785 492 L 820 492.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 405.0 L 790 621" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="610.8" y="597.0" width="358.4" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="790" y="618" class="edge-label" text-anchor="middle" textLength="340.4" lengthAdjust="spacingAndGlyphs">Else chooses when parallel and Redis enabled</text><text x="790" y="638" class="edge-protocol" text-anchor="middle">via in-process + Redis</text></g><g data-relationship-id="r-routing-sequential"><title>Otherwise falls back · via in-process</title><path d="M 755 322.5 L 785 322 L 785 742 L 820 742.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 640.0 L 700 694" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="612.0" y="670.0" width="176.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="700" y="691" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">Otherwise falls back</text><text x="700" y="711" class="edge-protocol" text-anchor="middle">via in-process</text></g><g data-relationship-id="r-temporal-node"><title>Schedules node activities · via Temporal task queue</title><path d="M 1105 267.5 L 1240 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 225.0 L 1170 387" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1063.0" y="363.0" width="214.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1170" y="384" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">Schedules node activities</text><text x="1170" y="404" class="edge-protocol" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">via Temporal task queue</text></g><g data-relationship-id="r-parallel-node"><title>Calls node adapter with retries · via async callback</title><path d="M 1105 492.5 L 1170 492 L 1170 257 L 1240 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 385.0 L 900 385" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="770.2" y="361.0" width="259.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="900" y="382" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">Calls node adapter with retries</text><text x="900" y="402" class="edge-protocol" text-anchor="middle">via async callback</text></g><g data-relationship-id="r-sequential-node"><title>Calls each ready node · via await</title><path d="M 1105 742.5 L 1170 742 L 1170 257 L 1240 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 650.0 L 1260 650" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1168.2" y="626.0" width="183.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1260" y="647" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">Calls each ready node</text><text x="1260" y="667" class="edge-protocol" text-anchor="middle">via await</text></g><g data-relationship-id="r-prepare-resolve"><title>Passes validated parameters · via Python dict</title><path d="M 1525 257.5 L 1560 257.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1542.0 347.0 L 1542 401" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1427.4" y="377.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1542" y="398" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Passes validated parameters</text><text x="1542" y="418" class="edge-protocol" text-anchor="middle">via Python dict</text></g><g data-relationship-id="r-resolve-dispatch"><title>Builds handler context · via NodeContext</title><path d="M 1697.5 320 L 1697 380 L 1382 380 L 1382.5 455" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1540.0 380.0 L 1810 380" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1714.4" y="356.0" width="191.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1810" y="377" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Builds handler context</text><text x="1810" y="397" class="edge-protocol" text-anchor="middle">via NodeContext</text></g><g data-relationship-id="r-dispatch-result"><title>Returns standardized result · via ExecutionResult</title><path d="M 1525 527.5 L 1560 527.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1427.4" y="641.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1542" y="662" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Returns standardized result</text><text x="1542" y="682" class="edge-protocol" text-anchor="middle">via ExecutionResult</text></g><g data-relationship-id="r-result-store"><title>Persists successful outputs · via database callback</title><path d="M 1697.5 600 L 1697 680 L 1382 680 L 1382.5 745" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1540.0 680.0 L 1793.4 680" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1678.8000000000002" y="656.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1793.4" y="677" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Persists successful outputs</text><text x="1793.4" y="697" class="edge-protocol" text-anchor="middle">via database callback</text></g><g data-relationship-id="r-store-broadcast"><title>Publishes execution state · via WebSocket broadcast</title><path d="M 1525 807.5 L 1560 807.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1435.0" y="901.0" width="214.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1542" y="922" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">Publishes execution state</text><text x="1542" y="942" class="edge-protocol" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">via WebSocket broadcast</text></g><g data-component-id="single-node-request"><title>Single-node request</title><rect x="75" y="250" width="240" height="125" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="75" y="250" width="240" height="7" rx="4" fill="#8be9fd"/><text x="93" y="276" class="type-label">ENTRY POINT</text><text x="93" y="302" class="node-label" textLength="204.0" lengthAdjust="spacingAndGlyphs">Single-node request</text><text x="93" y="328" class="node-detail" textLength="204.0" lengthAdjust="spacingAndGlyphs">WebSocket or internal REST</text></g><g data-component-id="whole-workflow-request"><title>Whole-workflow run</title><rect x="75" y="625" width="240" height="125" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="75" y="625" width="240" height="7" rx="4" fill="#8be9fd"/><text x="93" y="651" class="type-label">ENTRY POINT</text><text x="93" y="677" class="node-label">Whole-workflow run</text><text x="93" y="703" class="node-detail">Interactive or deployed</text></g><g data-component-id="routing-decision"><title>WorkflowService routing</title><rect x="455" y="250" width="300" height="145" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="455" y="250" width="300" height="7" rx="4" fill="#ffb86c"/><text x="473" y="276" class="type-label">DECISION</text><text x="473" y="302" class="node-label">WorkflowService routing</text><text x="473" y="328" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">Temporal → parallel → sequential</text></g><g data-component-id="temporal-branch"><title>Temporal branch</title><rect x="820" y="205" width="285" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="205" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="231" class="type-label">DURABLE ORCHESTRATOR</text><text x="838" y="257" class="node-label">Temporal branch</text><text x="838" y="283" class="node-detail">Temporal executor is wired</text></g><g data-component-id="redis-parallel-branch"><title>Redis-parallel branch</title><rect x="820" y="420" width="285" height="145" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="420" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="446" class="type-label">GRAPH ORCHESTRATOR</text><text x="838" y="472" class="node-label">Redis-parallel</text><text x="838" y="494" class="node-label">branch</text><text x="838" y="520" class="node-detail">WorkflowExecutor</text></g><g data-component-id="sequential-branch"><title>Sequential fallback</title><rect x="820" y="680" width="285" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="680" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="706" class="type-label">GRAPH ORCHESTRATOR</text><text x="838" y="732" class="node-label">Sequential fallback</text><text x="838" y="758" class="node-detail">Topological loop</text></g><g data-component-id="parameter-preparation"><title>Prepare parameters</title><rect x="1240" y="195" width="285" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1240" y="195" width="285" height="7" rx="4" fill="#ffb86c"/><text x="1258" y="221" class="type-label">PIPELINE STAGE</text><text x="1258" y="247" class="node-label">Prepare parameters</text><text x="1258" y="273" class="node-detail" textLength="249.0" lengthAdjust="spacingAndGlyphs">DB defaults + request overrides</text><text x="1258" y="293" class="node-detail" textLength="249.0" lengthAdjust="spacingAndGlyphs">Pydantic Params + credentials</text></g><g data-component-id="template-resolution"><title>Resolve templates</title><rect x="1560" y="195" width="275" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1560" y="195" width="275" height="7" rx="4" fill="#ffb86c"/><text x="1578" y="221" class="type-label">PIPELINE STAGE</text><text x="1578" y="247" class="node-label">Resolve templates</text><text x="1578" y="273" class="node-detail">Graph and upstream outputs</text></g><g data-component-id="plugin-dispatch"><title>Dispatch plugin operation</title><rect x="1240" y="455" width="285" height="145" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1240" y="455" width="285" height="7" rx="4" fill="#50fa7b"/><text x="1258" y="481" class="type-label">PIPELINE STAGE</text><text x="1258" y="507" class="node-label">Dispatch plugin</text><text x="1258" y="529" class="node-label">operation</text><text x="1258" y="555" class="node-detail">Node registry handler</text></g><g data-component-id="validated-result"><title>Validated execution result</title><rect x="1560" y="455" width="275" height="145" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1560" y="455" width="275" height="7" rx="4" fill="#50fa7b"/><text x="1578" y="481" class="type-label">PIPELINE STAGE</text><text x="1578" y="507" class="node-label">Validated execution</text><text x="1578" y="529" class="node-label">result</text><text x="1578" y="555" class="node-detail">Success or typed error</text></g><g data-component-id="output-store"><title>Output store</title><rect x="1240" y="745" width="285" height="125" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1240" y="745" width="285" height="7" rx="4" fill="#ff79c6"/><text x="1258" y="771" class="type-label">PERSISTENCE</text><text x="1258" y="797" class="node-label">Output store</text><text x="1258" y="823" class="node-detail">output_main / top / 0</text></g><g data-component-id="status-broadcast"><title>Status broadcasts</title><rect x="1560" y="745" width="275" height="125" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1560" y="745" width="275" height="7" rx="4" fill="#50fa7b"/><text x="1578" y="771" class="type-label">OBSERVABLE RESULT</text><text x="1578" y="797" class="node-label">Status broadcasts</text><text x="1578" y="823" class="node-detail" textLength="239.0" lengthAdjust="spacingAndGlyphs">Per-workflow WebSocket stream</text></g><g data-callout-id="routing-invariant"><rect x="455" y="830" width="650" height="110" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="471" y="860" class="callout-title">Routing invariant</text><text x="471" y="886" class="callout-text">Temporal requested but not wired logs an error, then falls through.</text><text x="471" y="908" class="callout-text">The next eligible path is Redis-parallel or sequential.</text><text x="471" y="930" class="callout-text">Every branch invokes WorkflowService.execute_node → NodeExecutor.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/04-durable-deployment-events.svg b/docs/diagrams/v2/dark/04-durable-deployment-events.svgnew file mode 100644index 00000000..41ccda50--- /dev/null+++ b/docs/diagrams/v2/dark/04-durable-deployment-events.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="8df81da298fbe73d">+<title id="title">Durable Deployment and Events — dark theme</title>+<desc id="desc">A deployment lifecycle and event-flow view showing Start/Pause/Resume/Reset controls, immutable per-generation graph snapshots, the long-lived WorkflowControlWorkflow, push/poll/cron trigger paths, CloudEvents dispatch, and child graph execution. Sources: server/services/deployment/handlers.py; server/services/deployment/control.py; server/services/deployment/triggers.py; server/services/temporal/workflow_control_workflow.py; server/services/events/envelope.py; server/services/events/dispatch.py; server/services/temporal/schedules.py; server/nodes/scheduler/cron_scheduler/_workflow.py; server/services/workflow.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Durable Deployment and Events</text>+<text x="72" y="91" class="subtitle">Generation snapshots, trigger admission, controller signals and child workflow runs</text>+<g data-group-id="control-plane"><rect x="45" y="145" width="610" height="815" rx="18" fill="#15171c" stroke="#f1fa8c" stroke-width="2"/><text x="65" y="177" class="group-label">DEPLOYMENT CONTROL PLANE</text></g><g data-group-id="trigger-plane"><rect x="690" y="145" width="710" height="815" rx="18" fill="#15171c" stroke="#ff79c6" stroke-width="2"/><text x="710" y="177" class="group-label">TRIGGER AND EVENT PLANE</text></g><g data-group-id="execution-plane"><rect x="1435" y="145" width="440" height="815" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1455" y="177" class="group-label">DURABLE EXECUTION</text></g><g data-relationship-id="r-controls-service"><title>Requests lifecycle transition · via WebSocket command</title><path d="M 340 275.0 L 370 275.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="227.8" y="366.0" width="244.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="350" y="387" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">Requests lifecycle transition</text><text x="350" y="407" class="edge-protocol" text-anchor="middle">via WebSocket command</text></g><g data-relationship-id="r-service-snapshot"><title>Allocates or CAS-updates · via workflow database</title><path d="M 495.0 345 L 495 405 L 210 405 L 210.0 485" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 350.0 405.0 L 115.19999999999999 405" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="12.0" y="381.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="115.19999999999999" y="402" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Allocates or CAS-updates</text><text x="115.19999999999999" y="422" class="edge-protocol" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">via workflow database</text></g><g data-relationship-id="r-snapshot-controller"><title>Starts with immutable graph snapshot · via Temporal gRPC</title><path d="M 340 562.5 L 370 562.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="201.20000000000002" y="676.0" width="297.59999999999997" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="350" y="697" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">Starts with immutable graph snapshot</text><text x="350" y="717" class="edge-protocol" text-anchor="middle">via Temporal gRPC</text></g><g data-relationship-id="r-controls-controller"><title>Updates pause/resume or signals reset · via Temporal Update / Signal</title><path d="M 495.0 345 L 495.0 485" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 495.0 405.0 L 675 405" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="522.4" y="381.0" width="305.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="675" y="402" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">Updates pause/resume or signals reset</text><text x="675" y="422" class="edge-protocol" text-anchor="middle">via Temporal Update / Signal</text></g><g data-relationship-id="r-service-local-state"><title>Projects admission state · via in-process</title><path d="M 495.0 345 L 640 415 L 640 735 L 355 735 L 355.0 775" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 735.0 L 640 735" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="536.8" y="711.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="640" y="732" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Projects admission state</text><text x="640" y="752" class="edge-protocol" text-anchor="middle">via in-process</text></g><g data-relationship-id="r-push-event"><title>Normalizes inbound event · via CloudEvents 1.0</title><path d="M 825.0 320 L 855.0 455" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 825.0 385.0 L 1005 385" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="901.8" y="361.0" width="206.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1005" y="382" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Normalizes inbound event</text><text x="1005" y="402" class="edge-protocol" text-anchor="middle">via CloudEvents 1.0</text></g><g data-relationship-id="r-event-dispatch"><title>Emits envelope · via async dispatch</title><path d="M 980 520.0 L 1040 520.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="929.6" y="621.0" width="160.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1010" y="642" class="edge-label" text-anchor="middle">Emits envelope</text><text x="1010" y="662" class="edge-protocol" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">via async dispatch</text></g><g data-relationship-id="r-dispatch-controller"><title>Signals matching controller · via Visibility + on_event</title><path d="M 1040 520.0 L 1010 520 L 675 520 L 620 562.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 825.0 520.0 L 735 682" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="620.4" y="658.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="735" y="679" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Signals matching controller</text><text x="735" y="699" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Visibility + on_event</text></g><g data-relationship-id="r-poll-controller"><title>Registers durable poll loop · via register_trigger signal</title><path d="M 1045.0 320 L 1045 365 L 675 365 L 675 562 L 620 562.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 835.0 365.0 L 1285 365" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1170.4" y="341.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1285" y="362" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Registers durable poll loop</text><text x="1285" y="382" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via register_trigger signal</text></g><g data-relationship-id="r-cron-action"><title>Fires scheduled action · via Temporal Schedule</title><path d="M 1360 262.5 L 1415 262 L 1415 642 L 1480 642.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1415.0 465.0 L 1415 519" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1319.4" y="495.0" width="191.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1415" y="516" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Fires scheduled action</text><text x="1415" y="536" class="edge-protocol" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">via Temporal Schedule</text></g><g data-relationship-id="r-registration-controller"><title>Registers definitions and pause state · via Temporal Signal</title><path d="M 875 805.0 L 675 805 L 675 562 L 620 562.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 675.0 720.0 L 675 828" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="522.4" y="804.0" width="305.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="675" y="825" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">Registers definitions and pause state</text><text x="675" y="845" class="edge-protocol" text-anchor="middle">via Temporal Signal</text></g><g data-relationship-id="r-controller-child"><title>Spawns admitted event or poll run · via Temporal child workflow</title><path d="M 620 562.5 L 1410 562 L 1410 367 L 1480 367.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1225.0 367.0 L 1315 421" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1177.6" y="397.0" width="274.79999999999995" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1315" y="418" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">Spawns admitted event or poll run</text><text x="1315" y="438" class="edge-protocol" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">via Temporal child workflow</text></g><g data-relationship-id="r-cron-child"><title>Launches snapshotted graph · via Temporal child workflow</title><path d="M 1655.0 570 L 1655.0 440" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1540.4" y="481.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1655" y="502" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Launches snapshotted graph</text><text x="1655" y="522" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Temporal child workflow</text></g><g data-relationship-id="r-child-status"><title>Persists and broadcasts run state · via database + WebSocket</title><path d="M 1655.0 440 L 1655.0 810" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1517.6" y="736.0" width="274.79999999999995" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1655" y="757" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">Persists and broadcasts run state</text><text x="1655" y="777" class="edge-protocol" text-anchor="middle">via database + WebSocket</text></g><g data-relationship-id="r-cron-status"><title>Reports scheduled run state · via Temporal + WebSocket</title><path d="M 1655.0 715 L 1655.0 810" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1775.0 760.0 L 1775 966.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1660.4" y="942.0" width="229.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1775" y="963.0" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Reports scheduled run state</text><text x="1775" y="983.0" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Temporal + WebSocket</text></g><g data-component-id="lifecycle-controls"><title>Start · Pause · Resume · Reset</title><rect x="80" y="205" width="260" height="140" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="80" y="205" width="260" height="7" rx="4" fill="#f1fa8c"/><text x="98" y="231" class="type-label">OPERATOR CONTROLS</text><text x="98" y="257" class="node-label">Start · Pause</text><text x="98" y="279" class="node-label">Resume · Reset</text><text x="98" y="305" class="node-detail">Revision-aware commands</text></g><g data-component-id="workflow-control-service"><title>WorkflowControlService</title><rect x="370" y="205" width="250" height="140" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="370" y="205" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="388" y="231" class="type-label">CONTROL SERVICE</text><text x="388" y="257" class="node-label" textLength="214.0" lengthAdjust="spacingAndGlyphs">WorkflowControlService</text><text x="388" y="283" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">CAS lifecycle transitions</text></g><g data-component-id="generation-snapshot"><title>Generation control row</title><rect x="80" y="485" width="260" height="155" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="80" y="485" width="260" height="7" rx="4" fill="#ff79c6"/><text x="98" y="511" class="type-label">DURABLE DATA</text><text x="98" y="537" class="node-label">Generation control</text><text x="98" y="559" class="node-label">row</text><text x="98" y="585" class="node-detail">graph_snapshot + owner_id</text><text x="98" y="605" class="node-detail">generation + revision</text></g><g data-component-id="controller"><title>WorkflowControlWorkflow</title><rect x="370" y="485" width="250" height="155" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="370" y="485" width="250" height="7" rx="4" fill="#ffb86c"/><text x="388" y="511" class="type-label">LONG-LIVED WORKFLOW</text><text x="388" y="537" class="node-label">WorkflowControl</text><text x="388" y="559" class="node-label">Workflow</text><text x="388" y="585" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Signals, poll loops, event queue</text><text x="388" y="605" class="node-detail">continue-as-new</text></g><g data-component-id="local-runtime-state"><title>Local admission state</title><rect x="215" y="775" width="280" height="120" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="215" y="775" width="280" height="7" rx="4" fill="#ffb86c"/><text x="233" y="801" class="type-label">PROCESS PROJECTION</text><text x="233" y="827" class="node-label">Local admission state</text><text x="233" y="853" class="node-detail">running / paused projection</text></g><g data-component-id="push-trigger"><title>Push trigger</title><rect x="730" y="205" width="190" height="115" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="730" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="748" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="748" y="257" class="node-label">Push trigger</text><text x="748" y="283" class="node-detail" textLength="154.0" lengthAdjust="spacingAndGlyphs">Webhook or platform event</text></g><g data-component-id="poll-trigger"><title>Poll trigger</title><rect x="950" y="205" width="190" height="115" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="950" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="968" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="968" y="257" class="node-label">Poll trigger</text><text x="968" y="283" class="node-detail" textLength="154.0" lengthAdjust="spacingAndGlyphs">Controller timer + activity</text></g><g data-component-id="cron-trigger"><title>Cron trigger</title><rect x="1170" y="205" width="190" height="115" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1170" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="1188" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="1188" y="257" class="node-label">Cron trigger</text><text x="1188" y="283" class="node-detail">Temporal Schedule</text></g><g data-component-id="cloudevent"><title>WorkflowEvent</title><rect x="730" y="455" width="250" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="730" y="455" width="250" height="7" rx="4" fill="#ff79c6"/><text x="748" y="481" class="type-label">CLOUDEVENTS 1.0</text><text x="748" y="507" class="node-label">WorkflowEvent</text><text x="748" y="533" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">id · source · type · subject</text></g><g data-component-id="event-dispatch"><title>dispatch.emit</title><rect x="1040" y="455" width="250" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1040" y="455" width="250" height="7" rx="4" fill="#ff79c6"/><text x="1058" y="481" class="type-label">EVENT ROUTER</text><text x="1058" y="507" class="node-label">dispatch.emit</text><text x="1058" y="533" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Visibility query + signal</text></g><g data-component-id="trigger-registration"><title>Trigger registration</title><rect x="875" y="745" width="300" height="120" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="875" y="745" width="300" height="7" rx="4" fill="#ff79c6"/><text x="893" y="771" class="type-label">CONTROL SIGNAL</text><text x="893" y="797" class="node-label">Trigger registration</text><text x="893" y="823" class="node-detail">register_trigger + pause flags</text></g><g data-component-id="child-graph-workflow"><title>Child graph workflow</title><rect x="1480" y="295" width="350" height="145" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1480" y="295" width="350" height="7" rx="4" fill="#ffb86c"/><text x="1498" y="321" class="type-label">TEMPORAL WORKFLOW</text><text x="1498" y="347" class="node-label">Child graph workflow</text><text x="1498" y="373" class="node-detail">Snapshotted nodes and edges</text></g><g data-component-id="cron-action-workflow"><title>Cron action workflow</title><rect x="1480" y="570" width="350" height="145" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1480" y="570" width="350" height="7" rx="4" fill="#ffb86c"/><text x="1498" y="596" class="type-label">TEMPORAL WORKFLOW</text><text x="1498" y="622" class="node-label">Cron action workflow</text><text x="1498" y="648" class="node-detail">Schedule-owned graph launch</text></g><g data-component-id="execution-status"><title>Run status and events</title><rect x="1515" y="810" width="280" height="115" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1515" y="810" width="280" height="7" rx="4" fill="#50fa7b"/><text x="1533" y="836" class="type-label">OBSERVABLE RESULT</text><text x="1533" y="862" class="node-label">Run status and events</text><text x="1533" y="888" class="node-detail">Database + WebSocket</text></g><g data-callout-id="legacy-fallback"><rect x="735" y="885" width="630" height="65" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="751" y="915" class="callout-title">Optional legacy path</text><text x="751" y="941" class="callout-text">Local DeploymentManager / event-waiter remain optional fallbacks.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/05-plugin-agent-team-composition.svg b/docs/diagrams/v2/dark/05-plugin-agent-team-composition.svgnew file mode 100644index 00000000..66e952c6--- /dev/null+++ b/docs/diagrams/v2/dark/05-plugin-agent-team-composition.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="8152ad164c866305">+<title id="title">Plugin → Agent → Team Composition — dark theme</title>+<desc id="desc">A source-backed composition view showing how BaseNode plugins branch into standalone chat-model and agent plugins, how agents assemble context, skills, and tools before entering the shared LLM runtime, and how team leads turn teammate edges into durable delegation surfaces. Sources: server/services/plugin/base.py; server/nodes/model/_base.py; server/nodes/agent/_specialized.py; server/nodes/agent/_handles.py; server/services/plugin/edge_walker.py; server/services/llm/unifier.py; server/services/agent_team.py; server/models/database.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Plugin → Agent → Team Composition</text>+<text x="72" y="91" class="subtitle">Self-registering node plugins compose provider-backed agents, edge-connected capabilities, and execution-scoped teams</text>+<g data-group-id="plugin-layer"><rect x="50" y="125" width="500" height="830" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="70" y="157" class="group-label">PLUGIN & MODEL LAYER</text></g><g data-group-id="agent-layer"><rect x="590" y="125" width="700" height="830" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="610" y="157" class="group-label">AGENT COMPOSITION</text></g><g data-group-id="team-layer"><rect x="1330" y="125" width="540" height="830" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1350" y="157" class="group-label">TEAM COMPOSITION</text></g><g data-relationship-id="r-base-model"><title>specializes as model plugin</title><path d="M 300.0 325 L 300.0 400" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="185.4" y="350.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="300" y="368" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">specializes as model plugin</text></g><g data-relationship-id="r-base-agent"><title>specializes as agent plugin</title><path d="M 300.0 325 L 300 360 L 610 360 L 610 265 L 640 265.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 475.0 360.0 L 475 144" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="360.4" y="129.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="475" y="147" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">specializes as agent plugin</text></g><g data-relationship-id="r-model-unifier"><title>dispatches chat · via provider + model</title><path d="M 300.0 550 L 300.0 730" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="212.0" y="616.0" width="176.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="300" y="637" class="edge-label" text-anchor="middle">dispatches chat</text><text x="300" y="657" class="edge-protocol" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">via provider + model</text></g><g data-relationship-id="r-agent-prepare"><title>prepares execution payload</title><path d="M 940.0 345 L 940 385 L 940 680 L 940.0 720" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="829.2" y="635.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="940" y="653" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">prepares execution payload</text></g><g data-relationship-id="r-context-prepare"><title>adds context descriptor</title><path d="M 727.5 575 L 727 620 L 620 620 L 620 805 L 650 805.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="520.6" y="650.0" width="198.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="620" y="668" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">adds context descriptor</text></g><g data-relationship-id="r-skills-prepare"><title>injects enabled skill content</title><path d="M 937.5 575 L 937 630 L 940.0 720" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="814.8" y="605.0" width="244.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="937" y="623" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">injects enabled skill content</text></g><g data-relationship-id="r-tools-prepare"><title>builds tool surface</title><path d="M 1150.0 575 L 1150 620 L 1260 620 L 1260 805 L 1230 805.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1175.8" y="650.0" width="168.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1260" y="668" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">builds tool surface</text></g><g data-relationship-id="r-prepare-unifier"><title>routes selected provider and model</title><path d="M 940.0 890 L 940 920 L 300 920 L 300.0 890" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="478.8" y="905.0" width="282.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="620" y="923" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">routes selected provider and model</text></g><g data-relationship-id="r-teammates-lead"><title>connect via input-teammates</title><path d="M 1600.0 430 L 1600.0 335" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1485.4" y="367.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1600" y="385" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">connect via input-teammates</text></g><g data-relationship-id="r-lead-runtime"><title>executes through shared agent runtime</title><path d="M 1380 260.0 L 1320 260 L 1320 650 L 1260 650 L 1260 805 L 1230 805.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1195.0 650.0 L 1195 380" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1042.4" y="365.0" width="305.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1195" y="383" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">executes through shared agent runtime</text></g><g data-relationship-id="r-lead-manager"><title>auto-binds intrinsic tool</title><path d="M 1600.0 335 L 1600 650 L 1475 650 L 1475.0 710" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1408.0" y="635.0" width="214.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1515" y="653" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">auto-binds intrinsic tool</text></g><g data-relationship-id="r-teammates-state"><title>registers execution members</title><path d="M 1600.0 580 L 1600 640 L 1715 640 L 1715.0 710" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1700.0 640.0 L 1790 640" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1675.4" y="625.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1790" y="643" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">registers execution members</text></g><g data-relationship-id="r-manager-state"><title>persists task lifecycle</title><path d="M 1475.0 880 L 1475 920 L 1715 920 L 1715.0 880" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1495.6" y="905.0" width="198.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1595" y="923" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">persists task lifecycle</text></g><g data-component-id="base-node"><title>BaseNode plugin contract</title><rect x="90" y="185" width="420" height="140" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="90" y="185" width="420" height="7" rx="4" fill="#bd93f9"/><text x="108" y="211" class="type-label">PLUGIN CONTRACT</text><text x="108" y="237" class="node-label">BaseNode plugin contract</text><text x="108" y="263" class="node-detail">Params · Output · handles · uiHints</text><text x="108" y="283" class="node-detail">Auto-registers subclasses on import</text></g><g data-component-id="model-plugins"><title>Chat-model plugins</title><rect x="90" y="400" width="420" height="150" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="400" width="420" height="7" rx="4" fill="#8be9fd"/><text x="108" y="426" class="type-label">MODEL PLUGIN</text><text x="108" y="452" class="node-label">Chat-model plugins</text><text x="108" y="478" class="node-detail">ChatModelBase provider subclasses</text><text x="108" y="498" class="node-detail">Standalone output-model nodes</text></g><g data-component-id="chat-unifier"><title>ChatUnifier</title><rect x="90" y="730" width="420" height="160" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="730" width="420" height="7" rx="4" fill="#8be9fd"/><text x="108" y="756" class="type-label">LLM FACADE</text><text x="108" y="782" class="node-label">ChatUnifier</text><text x="108" y="808" class="node-detail">Provider registry + native SDK adapters</text><text x="108" y="828" class="node-detail">Shared model and agent dispatch path</text></g><g data-component-id="agent-plugins"><title>Agent plugins</title><rect x="640" y="185" width="600" height="160" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="640" y="185" width="600" height="7" rx="4" fill="#bd93f9"/><text x="658" y="211" class="type-label">AGENT PLUGIN</text><text x="658" y="237" class="node-label">Agent plugins</text><text x="658" y="263" class="node-detail">provider · model · prompt · options</text><text x="658" y="283" class="node-detail">Base, specialized, CLI, and team-lead variants</text></g><g data-component-id="context-node"><title>Context</title><rect x="640" y="430" width="175" height="145" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="430" width="175" height="7" rx="4" fill="#ff79c6"/><text x="658" y="456" class="type-label" textLength="139.0" lengthAdjust="spacingAndGlyphs">CONNECTED CONFIG</text><text x="658" y="482" class="node-label">Context</text><text x="658" y="508" class="node-detail">input-context</text><text x="658" y="528" class="node-detail" textLength="139.0" lengthAdjust="spacingAndGlyphs">policy + thread reference</text></g><g data-component-id="skill-nodes"><title>Skills</title><rect x="850" y="430" width="175" height="145" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="850" y="430" width="175" height="7" rx="4" fill="#50fa7b"/><text x="868" y="456" class="type-label" textLength="139.0" lengthAdjust="spacingAndGlyphs">CONNECTED CAPABILITY</text><text x="868" y="482" class="node-label">Skills</text><text x="868" y="508" class="node-detail">input-skill</text><text x="868" y="528" class="node-detail" textLength="139.0" lengthAdjust="spacingAndGlyphs">direct or Master Skill</text></g><g data-component-id="tool-nodes"><title>Tools</title><rect x="1060" y="430" width="180" height="145" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1060" y="430" width="180" height="7" rx="4" fill="#50fa7b"/><text x="1078" y="456" class="type-label" textLength="144.0" lengthAdjust="spacingAndGlyphs">CONNECTED CAPABILITY</text><text x="1078" y="482" class="node-label">Tools</text><text x="1078" y="508" class="node-detail">input-tools</text><text x="1078" y="528" class="node-detail" textLength="144.0" lengthAdjust="spacingAndGlyphs">plugin tool schemas</text></g><g data-component-id="prepared-agent-call"><title>Prepared agent call</title><rect x="650" y="720" width="580" height="170" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="650" y="720" width="580" height="7" rx="4" fill="#ffb86c"/><text x="668" y="746" class="type-label">RUNTIME PAYLOAD</text><text x="668" y="772" class="node-label">Prepared agent call</text><text x="668" y="798" class="node-detail">Edge walk + task/prompt assembly</text><text x="668" y="818" class="node-detail">Provider-neutral tools and skill content</text></g><g data-component-id="team-lead"><title>Orchestrator / AI Employee</title><rect x="1380" y="185" width="440" height="150" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="185" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="211" class="type-label">TEAM-LEAD AGENT</text><text x="1398" y="237" class="node-label">Orchestrator /</text><text x="1398" y="259" class="node-label">AI Employee</text><text x="1398" y="285" class="node-detail">Same agent runtime</text><text x="1398" y="305" class="node-detail">Adds input-teammates handle</text></g><g data-component-id="teammates"><title>Connected teammate agents</title><rect x="1380" y="430" width="440" height="150" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="430" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="456" class="type-label">AGENT SET</text><text x="1398" y="482" class="node-label">Connected teammate</text><text x="1398" y="504" class="node-label">agents</text><text x="1398" y="530" class="node-detail">Specialized or custom aiAgent</text><text x="1398" y="550" class="node-detail">Stable delegate tool names</text></g><g data-component-id="task-manager"><title>Task Manager</title><rect x="1380" y="710" width="190" height="170" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1380" y="710" width="190" height="7" rx="4" fill="#50fa7b"/><text x="1398" y="736" class="type-label">INTRINSIC TOOL</text><text x="1398" y="762" class="node-label">Task Manager</text><text x="1398" y="788" class="node-detail">Auto-bound</text><text x="1398" y="808" class="node-detail">Lead-only control</text></g><g data-component-id="durable-team"><title>Durable team state</title><rect x="1610" y="710" width="210" height="170" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1610" y="710" width="210" height="7" rx="4" fill="#ff79c6"/><text x="1628" y="736" class="type-label">EXECUTION DATA</text><text x="1628" y="762" class="node-label">Durable team</text><text x="1628" y="784" class="node-label">state</text><text x="1628" y="810" class="node-detail">Members · tasks</text><text x="1628" y="830" class="node-detail">Attempts · messages</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/06-persistence-secret-plane.svg b/docs/diagrams/v2/dark/06-persistence-secret-plane.svgnew file mode 100644index 00000000..48be74f0--- /dev/null+++ b/docs/diagrams/v2/dark/06-persistence-secret-plane.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="4dd0e49b0c18cbb7">+<title id="title">Persistence & Secret Plane — dark theme</title>+<desc id="desc">A two-plane architecture view separating ordinary workflow, execution, context, and team persistence from the credential path in which AuthService caches narrowly, CredentialsDatabase encrypts fields, and credentials.db stores only Fernet tokens plus derivation metadata. Sources: server/core/container.py; server/main.py; server/core/database.py; server/models/database.py; server/services/auth.py; server/core/credentials_database.py; server/core/encryption.py; server/services/plugin/credential.py; server/core/config.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Persistence & Secret Plane</text>+<text x="72" y="91" class="subtitle">Operational state lives in workflow.db; API keys and OAuth tokens cross a separate encrypted credential boundary</text>+<g data-group-id="state-plane"><rect x="50" y="125" width="750" height="830" rx="18" fill="#15171c" stroke="#ff79c6" stroke-width="2"/><text x="70" y="157" class="group-label">APPLICATION PERSISTENCE · workflow.db</text></g><g data-group-id="secret-plane"><rect x="840" y="125" width="1030" height="830" rx="18" fill="#15171c" stroke="#f1fa8c" stroke-width="2"/><text x="860" y="157" class="group-label">SECRET PLANE · credentials.db</text></g><g data-relationship-id="r-runtime-database"><title>persists operational state</title><path d="M 245.0 340 L 245 400 L 610 400 L 610.0 340" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="314.2" y="385.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="425" y="403" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">persists operational state</text></g><g data-relationship-id="r-database-workflow"><title>reads and writes SQLModel rows · via sqlite+aiosqlite</title><path d="M 610.0 340 L 610 450 L 445 450 L 445.0 540" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="399.0" y="426.0" width="252.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="525" y="447" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">reads and writes SQLModel rows</text><text x="525" y="467" class="edge-protocol" text-anchor="middle">via sqlite+aiosqlite</text></g><g data-relationship-id="r-plugin-auth"><title>requests secret resolution</title><path d="M 995.0 340 L 995 400 L 1295 400 L 1295.0 340" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1034.2" y="385.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1145" y="403" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">requests secret resolution</text></g><g data-relationship-id="r-auth-cache"><title>populates safe cache</title><path d="M 1420 265.0 L 1570 265.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1495.0 265.0 L 1495 157" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1407.0" y="142.0" width="176.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1495" y="160" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">populates safe cache</text></g><g data-relationship-id="r-auth-credentials"><title>save · retrieve · delete</title><path d="M 1295.0 340 L 1330.0 490" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1335.0 415.0 L 975 469" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="871.8" y="454.0" width="206.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="975" y="472" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">save · retrieve · delete</text></g><g data-relationship-id="r-key-encryption"><title>derives in-memory Fernet key</title><path d="M 995.0 660 L 995.0 750" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="876.6" y="695.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="995" y="713" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">derives in-memory Fernet key</text></g><g data-relationship-id="r-credentials-encryption"><title>calls encrypt / decrypt per field</title><path d="M 1330.0 670 L 1330 700 L 1190 700 L 1190 825 L 1120 825.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1142.6" y="685.0" width="274.79999999999995" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1280" y="703" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">calls encrypt / decrypt per field</text></g><g data-relationship-id="r-credentials-store"><title>stores ciphertext rows and salt · via SQLite</title><path d="M 1330.0 670 L 1330 690 L 1695 690 L 1695.0 710" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1515.0 690.0 L 1335 744" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1205.2" y="720.0" width="259.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1335" y="741" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">stores ciphertext rows and salt</text><text x="1335" y="761" class="edge-protocol" text-anchor="middle">via SQLite</text></g><g data-component-id="runtime-services"><title>Runtime services</title><rect x="100" y="190" width="290" height="150" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="100" y="190" width="290" height="7" rx="4" fill="#bd93f9"/><text x="118" y="216" class="type-label">APPLICATION CALLERS</text><text x="118" y="242" class="node-label">Runtime services</text><text x="118" y="268" class="node-detail" textLength="254.0" lengthAdjust="spacingAndGlyphs">Workflows · nodes · deployments</text><text x="118" y="288" class="node-detail">Context · teams · settings</text></g><g data-component-id="database-service"><title>Database</title><rect x="470" y="190" width="280" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="470" y="190" width="280" height="7" rx="4" fill="#ff79c6"/><text x="488" y="216" class="type-label">PERSISTENCE SERVICE</text><text x="488" y="242" class="node-label">Database</text><text x="488" y="268" class="node-detail">Async SQLModel / SQLite</text><text x="488" y="288" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">One operational access surface</text></g><g data-component-id="workflow-db"><title>workflow.db</title><rect x="280" y="540" width="330" height="200" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="280" y="540" width="330" height="7" rx="4" fill="#ff79c6"/><text x="298" y="566" class="type-label">SQLITE DATA STORE</text><text x="298" y="592" class="node-label">workflow.db</text><text x="298" y="618" class="node-detail">Workflows · node params · outputs</text><text x="298" y="638" class="node-detail">Executions · context · teams</text><text x="298" y="658" class="node-detail">No encrypted credential tables</text></g><g data-component-id="credential-callers"><title>Plugin credentials</title><rect x="870" y="190" width="250" height="150" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="870" y="190" width="250" height="7" rx="4" fill="#bd93f9"/><text x="888" y="216" class="type-label">SECRET CONSUMERS</text><text x="888" y="242" class="node-label">Plugin credentials</text><text x="888" y="268" class="node-detail">Credential.resolve</text><text x="888" y="288" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Connection / provider clients</text></g><g data-component-id="auth-service"><title>AuthService</title><rect x="1170" y="190" width="250" height="150" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1170" y="190" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="1188" y="216" class="type-label">SECRET FACADE</text><text x="1188" y="242" class="node-label">AuthService</text><text x="1188" y="268" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Only service-level credential route</text><text x="1188" y="288" class="node-detail">Store · resolve · remove</text></g><g data-component-id="credential-caches"><title>Process caches</title><rect x="1570" y="190" width="250" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1570" y="190" width="250" height="7" rx="4" fill="#ffb86c"/><text x="1588" y="216" class="type-label">BOUNDED SECRET CACHE</text><text x="1588" y="242" class="node-label">Process caches</text><text x="1588" y="268" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">API keys + model metadata</text><text x="1588" y="288" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">OAuth access/display fields only</text></g><g data-component-id="credentials-database"><title>CredentialsDatabase</title><rect x="1170" y="490" width="320" height="180" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1170" y="490" width="320" height="7" rx="4" fill="#f1fa8c"/><text x="1188" y="516" class="type-label">ENCRYPTED PERSISTENCE</text><text x="1188" y="542" class="node-label">CredentialsDatabase</text><text x="1188" y="568" class="node-detail">EncryptedAPIKey</text><text x="1188" y="588" class="node-detail">EncryptedOAuthToken</text><text x="1188" y="608" class="node-detail">credentials_metadata</text></g><g data-component-id="encryption-password"><title>API_KEY_ENCRYPTION_KEY</title><rect x="870" y="510" width="250" height="150" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="870" y="510" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="888" y="536" class="type-label">SERVER CONFIGURATION</text><text x="888" y="562" class="node-label">API_KEY_</text><text x="888" y="584" class="node-label">ENCRYPTION_KEY</text><text x="888" y="610" class="node-detail">Minimum 32 characters</text><text x="888" y="630" class="node-detail">Loaded at startup</text></g><g data-component-id="encryption-service"><title>EncryptionService</title><rect x="870" y="750" width="250" height="150" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="870" y="750" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="888" y="776" class="type-label" textLength="214.0" lengthAdjust="spacingAndGlyphs">CRYPTOGRAPHIC BOUNDARY</text><text x="888" y="802" class="node-label">EncryptionService</text><text x="888" y="828" class="node-detail">PBKDF2-SHA256 · 600,000</text><text x="888" y="848" class="node-detail">Fernet encrypt / decrypt</text></g><g data-component-id="credentials-db"><title>credentials.db</title><rect x="1560" y="710" width="270" height="190" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1560" y="710" width="270" height="7" rx="4" fill="#ff79c6"/><text x="1578" y="736" class="type-label">ENCRYPTED SQLITE</text><text x="1578" y="762" class="node-label">credentials.db</text><text x="1578" y="788" class="node-detail">Ciphertext fields only</text><text x="1578" y="808" class="node-detail">32-byte salt in metadata</text><text x="1578" y="828" class="node-detail">Separate from workflow.db</text></g><g data-callout-id="state-boundary-note"><rect x="100" y="800" width="650" height="110" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="116" y="830" class="callout-title">Blast-radius boundary</text><text x="116" y="856" class="callout-text">A workflow.db dump carries operational state,</text><text x="116" y="878" class="callout-text">but never the encrypted API-key or OAuth tables.</text></g><g data-callout-id="refresh-token-note"><rect x="1525" y="395" width="305" height="115" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="1541" y="425" class="callout-title">Refresh-token rule</text><text x="1541" y="451" class="callout-text" textLength="273.0" lengthAdjust="spacingAndGlyphs">Refresh tokens are never cached.</text><text x="1541" y="473" class="callout-text">AuthService reads them from</text><text x="1541" y="495" class="callout-text">credentials.db for every use.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/07-workspace-anatomy.svg b/docs/diagrams/v2/dark/07-workspace-anatomy.svgnew file mode 100644index 00000000..c230dcad--- /dev/null+++ b/docs/diagrams/v2/dark/07-workspace-anatomy.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="d94e6e84070c5188">+<title id="title">Workspace Anatomy — dark theme</title>+<desc id="desc">A source-backed anatomy of per-workflow workspaces: the database-backed id-to-slug resolver selects a DATA_DIR-rooted directory, contained consumers read and write artifacts through traversal-safe helpers, and CLI agents receive the workspace for worktrees and per-workflow skill discovery. Sources: server/core/paths.py; server/services/workspace_locator.py; server/services/workflow.py; server/services/workflow_storage/handlers.py; server/routers/workspace.py; server/nodes/filesystem/_backend.py; server/services/media/workspace.py; server/nodes/agent/claude_code_agent/_skills.py; server/services/cli_agent/session.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Workspace Anatomy</text>+<text x="72" y="91" class="subtitle">Immutable workflow IDs resolve to mutable slug directories that isolate files, generated media, CLI worktrees, and materialized skills</text>+<g data-group-id="workspace-resolution"><rect x="50" y="125" width="500" height="830" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="70" y="157" class="group-label">IDENTITY & ROOT RESOLUTION</text></g><g data-group-id="workspace-boundary"><rect x="590" y="125" width="710" height="830" rx="18" fill="#15171c" stroke="#ff79c6" stroke-width="2"/><text x="610" y="157" class="group-label">PER-WORKFLOW WORKSPACE</text></g><g data-group-id="workspace-consumers"><rect x="1340" y="125" width="530" height="830" rx="18" fill="#15171c" stroke="#50fa7b" stroke-width="2"/><text x="1360" y="157" class="group-label">CONTAINED CONSUMERS</text></g><g data-relationship-id="r-workflow-locator"><title>lookup by immutable workflow id</title><path d="M 300.0 340 L 300.0 430" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="170.2" y="370.0" width="259.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="300" y="388" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">lookup by immutable workflow id</text></g><g data-relationship-id="r-locator-base"><title>selects mutable slug below root</title><path d="M 300.0 600 L 300.0 720" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="170.2" y="650.0" width="259.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="300" y="668" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">selects mutable slug below root</text></g><g data-relationship-id="r-base-workspace"><title>contains one slug directory</title><path d="M 300.0 720 L 300 680 L 945 680 L 945.0 350" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="560.4" y="665.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="675" y="683" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">contains one slug directory</text></g><g data-relationship-id="r-workspace-files"><title>contains runtime artifacts</title><path d="M 945.0 350 L 945 410 L 780 410 L 780.0 470" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="669.2" y="395.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="780" y="413" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">contains runtime artifacts</text></g><g data-relationship-id="r-workspace-skills"><title>contains isolated skill tree</title><path d="M 945.0 350 L 945 410 L 1110 410 L 1110.0 470" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="991.6" y="395.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1110" y="413" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">contains isolated skill tree</text></g><g data-relationship-id="r-workspace-worktrees"><title>contains per-node task worktrees</title><path d="M 945.0 350 L 945 690 L 960.0 730" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="811.4" y="675.0" width="267.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="945" y="693" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">contains per-node task worktrees</text></g><g data-relationship-id="r-routes-resolve"><title>resolves workflow id before file access · via workspace locator</title><path d="M 1600.0 340 L 1600 400 L 945 400 L 945.0 350" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1320.0 400.0 L 1410 400" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1249.8" y="376.0" width="320.4" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1410" y="397" class="edge-label" text-anchor="middle" textLength="302.4" lengthAdjust="spacingAndGlyphs">resolves workflow id before file access</text><text x="1410" y="417" class="edge-protocol" text-anchor="middle">via workspace locator</text></g><g data-relationship-id="r-filesystem-files"><title>reads and writes contained paths</title><path d="M 1380 545.0 L 920 555.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1150.0 545.0 L 1240 707" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1106.4" y="692.0" width="267.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1240" y="710" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">reads and writes contained paths</text></g><g data-relationship-id="r-skills-cli"><title>auto-discovers enabled skills · via --add-dir</title><path d="M 1110.0 640 L 1110 680 L 1320 680 L 1320 805 L 1380 805.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1215.0 680.0 L 1215 950" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1092.8" y="926.0" width="244.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1215" y="947" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">auto-discovers enabled skills</text><text x="1215" y="967" class="edge-protocol" text-anchor="middle">via --add-dir</text></g><g data-relationship-id="r-workspace-cli"><title>passes workspace_dir</title><path d="M 945.0 350 L 1270 350 L 1270 690 L 1600 690 L 1600.0 730" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1450.0 690.0 L 1540 690" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1452.0" y="675.0" width="176.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1540" y="693" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">passes workspace_dir</text></g><g data-component-id="workflow-record"><title>Workflow record</title><rect x="90" y="190" width="420" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="190" width="420" height="7" rx="4" fill="#ff79c6"/><text x="108" y="216" class="type-label">DATABASE IDENTITY</text><text x="108" y="242" class="node-label">Workflow record</text><text x="108" y="268" class="node-detail">Immutable id · mutable slug</text><text x="108" y="288" class="node-detail">Stable references carry the id</text></g><g data-component-id="workspace-locator"><title>Workspace locator</title><rect x="90" y="430" width="420" height="170" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="90" y="430" width="420" height="7" rx="4" fill="#ffb86c"/><text x="108" y="456" class="type-label">PATH RESOLVER</text><text x="108" y="482" class="node-label">Workspace locator</text><text x="108" y="508" class="node-detail">Looks up id → slug in workflow.db</text><text x="108" y="528" class="node-detail">Read-only misses may use default</text><text x="108" y="548" class="node-detail">Mutations fail if id cannot resolve</text></g><g data-component-id="workspace-base"><title>DATA_DIR / workspaces</title><rect x="90" y="720" width="420" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="720" width="420" height="7" rx="4" fill="#ff79c6"/><text x="108" y="746" class="type-label">FILESYSTEM ROOT</text><text x="108" y="772" class="node-label">DATA_DIR /</text><text x="108" y="794" class="node-label">workspaces</text><text x="108" y="820" class="node-detail">~/.opencompany/workspaces by default</text><text x="108" y="840" class="node-detail">WORKSPACE_BASE_DIR remains configurable</text></g><g data-component-id="workflow-workspace"><title>workspaces/<workflow.slug>/</title><rect x="640" y="190" width="610" height="160" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="190" width="610" height="7" rx="4" fill="#ff79c6"/><text x="658" y="216" class="type-label">WORKSPACE ROOT</text><text x="658" y="242" class="node-label">workspaces/<workflow.slug>/</text><text x="658" y="268" class="node-detail">Created for one workflow</text><text x="658" y="288" class="node-detail">Directory moves when the slug changes</text></g><g data-component-id="workspace-files"><title>Workspace files</title><rect x="640" y="470" width="280" height="170" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="470" width="280" height="7" rx="4" fill="#ff79c6"/><text x="658" y="496" class="type-label">RUNTIME ARTIFACTS</text><text x="658" y="522" class="node-label">Workspace files</text><text x="658" y="548" class="node-detail">Uploads · generated media</text><text x="658" y="568" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Documents · code · nested files</text></g><g data-component-id="workspace-skills"><title>.claude/skills/<name>/</title><rect x="970" y="470" width="280" height="170" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="970" y="470" width="280" height="7" rx="4" fill="#50fa7b"/><text x="988" y="496" class="type-label">MATERIALIZED SKILLS</text><text x="988" y="522" class="node-label">.claude/skills/</text><text x="988" y="544" class="node-label"><name>/</text><text x="988" y="570" class="node-detail">SKILL.md</text><text x="988" y="590" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">scripts/ + references/ preserved</text></g><g data-component-id="cli-worktrees"><title><node_id>/wt_<task_id>/</title><rect x="810" y="730" width="300" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="810" y="730" width="300" height="7" rx="4" fill="#ffb86c"/><text x="828" y="756" class="type-label">CLI WORKTREE</text><text x="828" y="782" class="node-label"><node_id>/</text><text x="828" y="804" class="node-label">wt_<task_id>/</text><text x="828" y="830" class="node-detail">Per-task isolated branch</text><text x="828" y="850" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">Lives under the workflow workspace</text></g><g data-component-id="workspace-routes"><title>Workspace HTTP routes</title><rect x="1380" y="190" width="440" height="150" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1380" y="190" width="440" height="7" rx="4" fill="#8be9fd"/><text x="1398" y="216" class="type-label">INTERFACE</text><text x="1398" y="242" class="node-label">Workspace HTTP</text><text x="1398" y="264" class="node-label">routes</text><text x="1398" y="290" class="node-detail">Serve file by workflow id + path</text><text x="1398" y="310" class="node-detail">Accept bounded uploads</text></g><g data-component-id="filesystem-media"><title>Filesystem & media nodes</title><rect x="1380" y="460" width="440" height="170" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1380" y="460" width="440" height="7" rx="4" fill="#50fa7b"/><text x="1398" y="486" class="type-label">CONTAINED I/O</text><text x="1398" y="512" class="node-label">Filesystem &</text><text x="1398" y="534" class="node-label">media nodes</text><text x="1398" y="560" class="node-detail">resolve_within containment</text><text x="1398" y="580" class="node-detail">Traversal + symlink/junction defense</text><text x="1398" y="600" class="node-detail">Atomic workspace writes</text></g><g data-component-id="cli-agent-session"><title>CLI agent session</title><rect x="1380" y="730" width="440" height="150" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="730" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="756" class="type-label">AGENT CONSUMER</text><text x="1398" y="782" class="node-label">CLI agent session</text><text x="1398" y="808" class="node-detail">Receives workspace_dir / --add-dir</text><text x="1398" y="828" class="node-detail">Discovers skills and owns worktrees</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/08-node-configuration-anatomy.svg b/docs/diagrams/v2/dark/08-node-configuration-anatomy.svgnew file mode 100644index 00000000..81ab5a8e--- /dev/null+++ b/docs/diagrams/v2/dark/08-node-configuration-anatomy.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="35179531c67b57ed">+<title id="title">Node Configuration Anatomy — dark theme</title>+<desc id="desc">An anatomy of the Node Configuration modal showing the real header actions, the 0.7 / 1.6 / 0.7 Input–Parameters–Output layout, NodeSpec-driven variants, local edit-buffer persistence, save-before-run execution, and WebSocket-correlated output handling. Sources: client/src/ParameterPanel.tsx; client/src/components/parameterPanel/ParameterPanelLayout.tsx; client/src/components/parameterPanel/InputSection.tsx; client/src/components/parameterPanel/MiddleSection.tsx; client/src/components/parameterPanel/OutputSection.tsx; client/src/hooks/useParameterPanel.ts; client/src/hooks/useNodeParamsQuery.ts; client/src/services/executionService.ts; server/routers/websocket.py; server/core/database.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Node Configuration Anatomy</text>+<text x="72" y="91" class="subtitle">A schema-driven modal combines draggable upstream data, a local parameter draft, per-node execution, and correlated live output</text>+<g data-group-id="configuration-modal"><rect x="50" y="125" width="1820" height="620" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="70" y="157" class="group-label">NODE CONFIGURATION MODAL</text></g><g data-group-id="panel-data-plane"><rect x="50" y="775" width="1820" height="180" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="70" y="807" class="group-label">LIVE DATA & PERSISTENCE</text></g><g data-relationship-id="r-spec-identity"><title>supplies icon and display name</title><path d="M 255.0 820 L 255 760 L 370 760 L 370.0 285" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="244.0" y="745.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="370" y="763" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">supplies icon and display name</text></g><g data-relationship-id="r-spec-parameters"><title>renders fields and panel variants</title><path d="M 255.0 820 L 255 720 L 940 720 L 940.0 690" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="462.6" y="705.0" width="274.79999999999995" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="600" y="723" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">renders fields and panel variants</text></g><g data-relationship-id="r-input-parameters"><title>drag template variable</title><path d="M 305.0 350 L 305 320 L 940 320 L 940.0 350" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="524.4" y="305.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="620" y="323" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">drag template variable</text></g><g data-relationship-id="r-parameters-draft"><title>onParameterChange updates local draft</title><path d="M 940.0 690 L 940 750 L 690 750 L 690.0 820" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="662.4" y="735.0" width="305.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="815" y="753" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">onParameterChange updates local draft</text></g><g data-relationship-id="r-save-draft"><title>handleSave commits draft</title><path d="M 810.0 285 L 810 310 L 460 310 L 460 760 L 690 760 L 690.0 820" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 575.0 760.0 L 575 975.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="471.8" y="960.0" width="206.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="575" y="978.0" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">handleSave commits draft</text></g><g data-relationship-id="r-run-execution"><title>save if dirty, then execute node</title><path d="M 1070.0 285 L 1070 310 L 1120 760 L 1120.0 820" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="986.4" y="745.0" width="267.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1120" y="763" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">save if dirty, then execute node</text></g><g data-relationship-id="r-execution-output"><title>appends correlated ExecutionResult</title><path d="M 1120.0 820 L 1120 735 L 1595 735 L 1595.0 690" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1370.0 735.0 L 1460 735" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1318.8" y="720.0" width="282.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1460" y="738" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">appends correlated ExecutionResult</text></g><g data-relationship-id="r-websocket-output"><title>broadcasts node status and output · via execution_id</title><path d="M 1600.0 820 L 1600 780 L 1760 780 L 1760 720 L 1595 720 L 1595.0 690" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1705.0 720.0 L 1705 774" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1567.6" y="750.0" width="274.79999999999995" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1705" y="771" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">broadcasts node status and output</text><text x="1705" y="791" class="edge-protocol" text-anchor="middle">via execution_id</text></g><g data-relationship-id="r-cancel-websocket"><title>cancel wait or close draft</title><path d="M 1355.0 285 L 1355 310 L 1850 310 L 1850 760 L 1600 760 L 1600.0 820" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1720.0 760.0 L 1720 975.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1609.2" y="960.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1720" y="978.0" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">cancel wait or close draft</text></g><g data-relationship-id="r-draft-database"><title>save_node_parameters · via TanStack Query + WS</title><path d="M 690.0 945 L 690 970 L 1600 970 L 1600.0 945" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1045.6" y="942.0" width="198.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1145" y="963.0" class="edge-label" text-anchor="middle">save_node_parameters</text><text x="1145" y="983.0" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via TanStack Query + WS</text></g><g data-component-id="node-identity"><title>Node identity</title><rect x="90" y="175" width="560" height="110" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="175" width="560" height="7" rx="4" fill="#8be9fd"/><text x="108" y="201" class="type-label">MODAL HEADER</text><text x="108" y="227" class="node-label">Node identity</text><text x="108" y="253" class="node-detail">Icon · display name · dirty marker</text></g><g data-component-id="save-action"><title>Save</title><rect x="700" y="175" width="220" height="110" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="700" y="175" width="220" height="7" rx="4" fill="#ff79c6"/><text x="718" y="201" class="type-label">HEADER ACTION</text><text x="718" y="227" class="node-label">Save</text><text x="718" y="253" class="node-detail" textLength="184.0" lengthAdjust="spacingAndGlyphs">Disabled when clean or canvas locked</text></g><g data-component-id="run-action"><title>Run</title><rect x="960" y="175" width="220" height="110" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="960" y="175" width="220" height="7" rx="4" fill="#ff79c6"/><text x="978" y="201" class="type-label">HEADER ACTION</text><text x="978" y="227" class="node-label">Run</text><text x="978" y="253" class="node-detail" textLength="184.0" lengthAdjust="spacingAndGlyphs">Hidden by uiHints when passive</text></g><g data-component-id="cancel-action"><title>Cancel / Stop</title><rect x="1220" y="175" width="270" height="110" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1220" y="175" width="270" height="7" rx="4" fill="#ff79c6"/><text x="1238" y="201" class="type-label">HEADER ACTION</text><text x="1238" y="227" class="node-label">Cancel / Stop</text><text x="1238" y="253" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">Revert draft or cancel active wait</text></g><g data-component-id="close-action"><title>Close (X)</title><rect x="1530" y="175" width="300" height="110" rx="12" fill="#1b1e25" stroke="#9aa1ac" stroke-width="2"/><rect x="1530" y="175" width="300" height="7" rx="4" fill="#9aa1ac"/><text x="1548" y="201" class="type-label">MODAL ACTION</text><text x="1548" y="227" class="node-label">Close (X)</text><text x="1548" y="253" class="node-detail">Cancel draft and deselect node</text></g><g data-component-id="input-column"><title>Input Data & Variables</title><rect x="90" y="350" width="430" height="340" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="350" width="430" height="7" rx="4" fill="#8be9fd"/><text x="108" y="376" class="type-label">LEFT COLUMN · 0.7</text><text x="108" y="402" class="node-label">Input Data &</text><text x="108" y="424" class="node-label">Variables</text><text x="108" y="450" class="node-detail">Upstream execution values or output schema</text><text x="108" y="470" class="node-detail">Recursive object and array fields</text><text x="108" y="490" class="node-detail">Drag template variables into parameters</text></g><g data-component-id="parameters-column"><title>Parameters</title><rect x="560" y="350" width="760" height="340" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="560" y="350" width="760" height="7" rx="4" fill="#8be9fd"/><text x="578" y="376" class="type-label">MIDDLE COLUMN · 1.6</text><text x="578" y="402" class="node-label">Parameters</text><text x="578" y="428" class="node-detail">Schema-rendered local edit buffer</text><text x="578" y="448" class="node-detail">Specialized middle panels selected by uiHints</text><text x="578" y="468" class="node-detail">Connected Skills · Token Usage · Console</text></g><g data-component-id="output-column"><title>Output</title><rect x="1360" y="350" width="470" height="340" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1360" y="350" width="470" height="7" rx="4" fill="#50fa7b"/><text x="1378" y="376" class="type-label">RIGHT COLUMN · 0.7</text><text x="1378" y="402" class="node-label">Output</text><text x="1378" y="428" class="node-detail">Local run results + WebSocket status</text><text x="1378" y="448" class="node-detail">Deduplicates matching execution_id</text><text x="1378" y="468" class="node-detail">Clear results without changing parameters</text></g><g data-component-id="node-spec"><title>NodeSpec metadata</title><rect x="90" y="820" width="330" height="110" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="820" width="330" height="7" rx="4" fill="#ff79c6"/><text x="108" y="846" class="type-label">SCHEMA SOURCE</text><text x="108" y="872" class="node-label">NodeSpec metadata</text><text x="108" y="898" class="node-detail">properties · handles · uiHints</text></g><g data-component-id="parameter-state"><title>Parameter query + draft</title><rect x="500" y="820" width="380" height="125" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="500" y="820" width="380" height="7" rx="4" fill="#ffb86c"/><text x="518" y="846" class="type-label">CLIENT STATE</text><text x="518" y="872" class="node-label">Parameter query</text><text x="518" y="894" class="node-label">+ draft</text><text x="518" y="920" class="node-detail">defaults + saved params</text><text x="518" y="940" class="node-detail">dirty edit buffer + query cache</text></g><g data-component-id="execution-service"><title>ExecutionService</title><rect x="940" y="820" width="360" height="110" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="940" y="820" width="360" height="7" rx="4" fill="#ffb86c"/><text x="958" y="846" class="type-label">PER-NODE RUNTIME</text><text x="958" y="872" class="node-label">ExecutionService</text><text x="958" y="898" class="node-detail">save-before-run · executeNode</text><text x="958" y="918" class="node-detail">per-node reducer</text></g><g data-component-id="websocket-database"><title>WebSocket + workflow.db</title><rect x="1370" y="820" width="460" height="125" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1370" y="820" width="460" height="7" rx="4" fill="#ff79c6"/><text x="1388" y="846" class="type-label">LIVE DATA PLANE</text><text x="1388" y="872" class="node-label">WebSocket +</text><text x="1388" y="894" class="node-label">workflow.db</text><text x="1388" y="920" class="node-detail">node_parameters · node_outputs</text><text x="1388" y="940" class="node-detail">node status + wait cancellation</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/09-credentials-architecture.svg b/docs/diagrams/v2/dark/09-credentials-architecture.svgnew file mode 100644index 00000000..746d2239--- /dev/null+++ b/docs/diagrams/v2/dark/09-credentials-architecture.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="516cf648ab56c9c9">+<title id="title">Credentials Architecture — dark theme</title>+<desc id="desc">Credential configuration flows from the server-owned provider catalogue through modular client panels and registered WebSocket handlers. AuthService is the only plaintext access boundary; CredentialsDatabase encrypts separate API-key and OAuth-token records with the process-held Fernet service, while status events invalidate every connected client's catalogue. Sources: client/src/components/credentials/CredentialsModal.tsx; client/src/components/credentials/useCredentialPanel.ts; server/services/credentials/handlers.py; server/services/plugin/credential.py; server/services/auth.py; server/core/credentials_database.py; server/core/encryption.py; server/services/status_broadcaster.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Credentials Architecture</text>+<text x="72" y="91" class="subtitle">Server-owned catalogue, WebSocket orchestration, and encrypted storage</text>+<g data-group-id="client-plane"><rect x="72" y="150" width="650" height="780" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="92" y="182" class="group-label">CLIENT CONTROL PLANE</text></g><g data-group-id="server-plane"><rect x="760" y="150" width="1088" height="780" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="780" y="182" class="group-label">SERVER SECURITY PLANE</text></g><g data-relationship-id="modal-uses-client-state"><title>panel actions + cached status · via React Query</title><path d="M 380 315.0 L 420 315.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 400.0 205.0 L 490 151" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="367.8" y="127.0" width="244.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="490" y="148" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">panel actions + cached status</text><text x="490" y="168" class="edge-protocol" text-anchor="middle">via React Query</text></g><g data-relationship-id="client-calls-handlers"><title>catalogue + credential RPC · via WebSocket</title><path d="M 680 315.0 L 800 315.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 740.0 315.0 L 740 477" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="629.2" y="453.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="740" y="474" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">catalogue + credential RPC</text><text x="740" y="494" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="handlers-dispatch-registry"><title>dispatch validation</title><path d="M 1070 315.0 L 1130 315.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1100.0 205.0 L 1190 205" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1105.8" y="190.0" width="168.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1190" y="208" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">dispatch validation</text></g><g data-relationship-id="handlers-use-auth-service"><title>get · save · delete</title><path d="M 935.0 400 L 935 450 L 1215 450 L 1215.0 500" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="990.8" y="435.0" width="168.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1075" y="453" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">get · save · delete</text></g><g data-relationship-id="registry-stores-valid-result"><title>store valid probe result</title><path d="M 1280.0 400 L 1215.0 500" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1280.0 480.0 L 1280 426" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1176.8" y="411.0" width="206.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1280" y="429" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">store valid probe result</text></g><g data-relationship-id="registry-publishes-status"><title>publish validation status</title><path d="M 1430 315.0 L 1500 315.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1358.0" y="190.0" width="214.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1465" y="208" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">publish validation status</text></g><g data-relationship-id="auth-publishes-mutation"><title>catalogue version + mutation event</title><path d="M 1400 595.0 L 1450 595 L 1450 440 L 1650 440 L 1650.0 400" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1418.8" y="425.0" width="282.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1560" y="443" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">catalogue version + mutation event</text></g><g data-relationship-id="auth-canonical-crud"><title>canonical encrypted CRUD</title><path d="M 1215.0 690 L 1415.0 760" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1156.8" y="700.0" width="206.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1260" y="718" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">canonical encrypted CRUD</text></g><g data-relationship-id="db-uses-encryption"><title>encrypt / decrypt payloads · via Fernet</title><path d="M 1415.0 760 L 1415 720 L 1645 720 L 1645.0 690" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1580.0 720.0 L 1580 966.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1469.2" y="942.0" width="221.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1580" y="963.0" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">encrypt / decrypt payloads</text><text x="1580" y="983.0" class="edge-protocol" text-anchor="middle">via Fernet</text></g><g data-relationship-id="broadcast-invalidates-client"><title>push status + invalidate catalogue · via WebSocket</title><path d="M 1650.0 230 L 1650 115 L 550 115 L 550.0 230" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1100.0 115.0 L 1190 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1048.8" y="124.0" width="282.4" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1190" y="145.0" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">push status + invalidate catalogue</text><text x="1190" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-component-id="credentials-modal"><title>Credentials Modal</title><rect x="110" y="230" width="270" height="170" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="230" width="270" height="7" rx="4" fill="#8be9fd"/><text x="128" y="256" class="type-label">UI</text><text x="128" y="282" class="node-label">Credentials Modal</text><text x="128" y="308" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">server catalogue + IDB warm-start</text><text x="128" y="328" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">search palette + lazy panels</text></g><g data-component-id="client-state"><title>WebSocket + Query State</title><rect x="420" y="230" width="260" height="170" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="420" y="230" width="260" height="7" rx="4" fill="#8be9fd"/><text x="438" y="256" class="type-label">CLIENT</text><text x="438" y="282" class="node-label">WebSocket +</text><text x="438" y="304" class="node-label">Query State</text><text x="438" y="330" class="node-detail">request / response RPC</text><text x="438" y="350" class="node-detail">catalogue invalidation</text></g><g data-component-id="ws-handlers"><title>Credential WS Handlers</title><rect x="800" y="230" width="270" height="170" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="800" y="230" width="270" height="7" rx="4" fill="#ffb86c"/><text x="818" y="256" class="type-label">ROUTER</text><text x="818" y="282" class="node-label">Credential WS</text><text x="818" y="304" class="node-label">Handlers</text><text x="818" y="330" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">validate · get · save · delete</text><text x="818" y="350" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">idempotent mutation envelope</text></g><g data-component-id="credential-registries"><title>Credential Registries</title><rect x="1130" y="230" width="300" height="170" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1130" y="230" width="300" height="7" rx="4" fill="#ffb86c"/><text x="1148" y="256" class="type-label">REGISTRY</text><text x="1148" y="282" class="node-label">Credential Registries</text><text x="1148" y="308" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">catalogue metadata + stored flags</text><text x="1148" y="328" class="node-detail">credential classes + probes</text></g><g data-component-id="status-broadcaster"><title>Status Broadcaster</title><rect x="1500" y="230" width="300" height="170" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1500" y="230" width="300" height="7" rx="4" fill="#ff79c6"/><text x="1518" y="256" class="type-label">EVENTS</text><text x="1518" y="282" class="node-label">Status Broadcaster</text><text x="1518" y="308" class="node-detail">api_key_status</text><text x="1518" y="328" class="node-detail">credential_catalogue_updated</text></g><g data-component-id="auth-service"><title>AuthService</title><rect x="1030" y="500" width="370" height="190" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1030" y="500" width="370" height="7" rx="4" fill="#f1fa8c"/><text x="1048" y="526" class="type-label">SECURITY SERVICE</text><text x="1048" y="552" class="node-label">AuthService</text><text x="1048" y="578" class="node-detail">only credential access point</text><text x="1048" y="598" class="node-detail">separate API-key + OAuth caches</text><text x="1048" y="618" class="node-detail">refresh tokens never cached</text></g><g data-component-id="encryption-service"><title>Encryption Service</title><rect x="1490" y="500" width="310" height="190" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1490" y="500" width="310" height="7" rx="4" fill="#f1fa8c"/><text x="1508" y="526" class="type-label">CRYPTO</text><text x="1508" y="552" class="node-label">Encryption Service</text><text x="1508" y="578" class="node-detail">PBKDF2-SHA256 · 600k</text><text x="1508" y="598" class="node-detail">Fernet key held in process</text><text x="1508" y="618" class="node-detail">server key + install salt</text></g><g data-component-id="credentials-db"><title>credentials.db</title><rect x="1180" y="760" width="470" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1180" y="760" width="470" height="7" rx="4" fill="#ff79c6"/><text x="1198" y="786" class="type-label">ENCRYPTED SQLITE</text><text x="1198" y="812" class="node-label">credentials.db</text><text x="1198" y="838" class="node-detail">EncryptedAPIKey · EncryptedOAuthToken</text><text x="1198" y="858" class="node-detail">credentials_metadata encryption salt</text></g><g data-callout-id="storage-split"><rect x="800" y="735" width="330" height="175" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="816" y="765" class="callout-title">Two non-interchangeable stores</text><text x="816" y="791" class="callout-text">API keys: session + provider</text><text x="816" y="813" class="callout-text">OAuth tokens: provider + customer</text><text x="816" y="835" class="callout-text" textLength="298.0" lengthAdjust="spacingAndGlyphs">Access tokens may cache; refresh tokens do not</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/10-team-operations.svg b/docs/diagrams/v2/dark/10-team-operations.svgnew file mode 100644index 00000000..846783da--- /dev/null+++ b/docs/diagrams/v2/dark/10-team-operations.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="9002f02d01716d7e">+<title id="title">Team Operations — dark theme</title>+<desc id="desc">A team lead uses its intrinsic Task Manager to persist bounded work for graph-connected teammates. AgentTeamService enforces workflow, lead, execution, assignee, and optimistic-revision boundaries while tasks advance from blocked or queued through worker submission and explicit lead acceptance; Task Manager and Team Monitor expose mutable and read-only views of the same durable state. Sources: server/nodes/tool/task_manager/__init__.py; server/services/agent_team.py; server/services/agent_teams/handlers.py; server/services/temporal/agent_workflow.py; client/src/components/parameterPanel/TaskManagerPanel.tsx; client/src/components/parameterPanel/TeamMonitorPanel.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Team Operations</text>+<text x="72" y="91" class="subtitle">Execution-scoped durable tasks: assign, run, review, recover, and finish</text>+<g data-group-id="operation-surfaces"><rect x="72" y="140" width="1776" height="235" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="92" y="172" class="group-label">OPERATION SURFACES</text></g><g data-group-id="task-lifecycle"><rect x="72" y="410" width="1776" height="535" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="92" y="442" class="group-label">DURABLE TASK LIFECYCLE</text></g><g data-relationship-id="lead-calls-task-manager"><title>call public operations</title><path d="M 410 275.0 L 500 275.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="359.4" y="165.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="455" y="183" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">call public operations</text></g><g data-relationship-id="task-manager-uses-service"><title>scoped durable mutation</title><path d="M 830 275.0 L 920 275.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="775.6" y="165.0" width="198.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="875" y="183" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">scoped durable mutation</text></g><g data-relationship-id="human-manages-service"><title>inspect + permitted review actions · via WebSocket</title><path d="M 1390 275.0 L 1280 275.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1335.0 245.0 L 1335 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1193.8" y="124.0" width="282.4" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1335" y="145.0" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">inspect + permitted review actions</text><text x="1335" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="service-updates-human"><title>snapshots + lifecycle events</title><path d="M 1100.0 345 L 1100 365 L 1570 365 L 1570.0 345" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1335.0 365.0 L 1335 419" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1216.6" y="404.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1335" y="422" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">snapshots + lifecycle events</text></g><g data-relationship-id="service-assigns-ready"><title>assign_task persists ready work</title><path d="M 1100.0 345 L 1100 395 L 565 395 L 565.0 520" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="700.2" y="380.0" width="259.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="830" y="398" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">assign_task persists ready work</text></g><g data-relationship-id="dependencies-unblock"><title>dependencies accepted</title><path d="M 360 590.0 L 440 590.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="308.2" y="480.0" width="183.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="400" y="498" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">dependencies accepted</text></g><g data-relationship-id="worker-claims"><title>worker claims task</title><path d="M 690 590.0 L 770 590.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="649.6" y="480.0" width="160.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="730" y="498" class="edge-label" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">worker claims task</text></g><g data-relationship-id="worker-submits"><title>worker succeeds</title><path d="M 1020 590.0 L 1100 590.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="991.0" y="480.0" width="138.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1060" y="498" class="edge-label" text-anchor="middle" textLength="120.0" lengthAdjust="spacingAndGlyphs">worker succeeds</text></g><g data-relationship-id="lead-accepts"><title>accept_task</title><path d="M 1350 590.0 L 1430 590.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1330.0" y="480.0" width="120" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1390" y="498" class="edge-label" text-anchor="middle">accept_task</text></g><g data-relationship-id="worker-fails"><title>worker errors</title><path d="M 895.0 660 L 895.0 760" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="833.6" y="695.0" width="122.8" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="895" y="713" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">worker errors</text></g><g data-relationship-id="failed-requeues"><title>retry_task / reassign_task</title><path d="M 770 830.0 L 720 700 L 565 700 L 565.0 660" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="529.2" y="685.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="640" y="703" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="submitted-requeues"><title>retry_task / reassign_task</title><path d="M 1225.0 520 L 1225 455 L 565 455 L 565.0 520" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="784.2" y="440.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="895" y="458" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="cancelled-requeues"><title>retry_task / reassign_task</title><path d="M 1225.0 900 L 1225 925 L 700 925 L 700 700 L 565.0 660" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="784.2" y="910.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="895" y="928" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="accepted-finishes-team"><title>finish_team when all resolved</title><path d="M 1555.0 660 L 1555.0 760" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1432.8" y="675.0" width="244.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1555" y="693" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">finish_team when all resolved</text></g><g data-relationship-id="cancelled-is-resolved"><title>cancelled also counts resolved</title><path d="M 1350 830.0 L 1430 830.0" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="1264.0" y="720.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1390" y="738" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">cancelled also counts resolved</text></g><g data-component-id="team-lead"><title>Team Lead</title><rect x="110" y="205" width="300" height="140" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="110" y="205" width="300" height="7" rx="4" fill="#bd93f9"/><text x="128" y="231" class="type-label">AGENT</text><text x="128" y="257" class="node-label">Team Lead</text><text x="128" y="283" class="node-detail">Orchestrator or AI Employee</text><text x="128" y="303" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">connected teammates are authority</text></g><g data-component-id="task-manager"><title>Task Manager</title><rect x="500" y="205" width="330" height="140" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="500" y="205" width="330" height="7" rx="4" fill="#50fa7b"/><text x="518" y="231" class="type-label">INTRINSIC TOOL</text><text x="518" y="257" class="node-label">Task Manager</text><text x="518" y="283" class="node-detail">assign · inspect · review</text><text x="518" y="303" class="node-detail">retry · reassign · cancel · finish</text></g><g data-component-id="agent-team-service"><title>AgentTeamService</title><rect x="920" y="205" width="360" height="140" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="920" y="205" width="360" height="7" rx="4" fill="#ffb86c"/><text x="938" y="231" class="type-label">DURABLE SERVICE</text><text x="938" y="257" class="node-label">AgentTeamService</text><text x="938" y="283" class="node-detail">workflow + lead + execution scope</text><text x="938" y="303" class="node-detail">optimistic revision transitions</text></g><g data-component-id="human-views"><title>Task Manager + Team Monitor</title><rect x="1390" y="205" width="360" height="140" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1390" y="205" width="360" height="7" rx="4" fill="#8be9fd"/><text x="1408" y="231" class="type-label">HUMAN UI</text><text x="1408" y="257" class="node-label">Task Manager +</text><text x="1408" y="279" class="node-label">Team Monitor</text><text x="1408" y="305" class="node-detail">authorized mutations + trace</text><text x="1408" y="325" class="node-detail">read-only lifecycle snapshot</text></g><g data-component-id="blocked"><title>Blocked</title><rect x="110" y="520" width="250" height="140" rx="12" fill="#1b1e25" stroke="#9aa1ac" stroke-width="2"/><rect x="110" y="520" width="250" height="7" rx="4" fill="#9aa1ac"/><text x="128" y="546" class="type-label">TASK STATE</text><text x="128" y="572" class="node-label">Blocked</text><text x="128" y="598" class="node-detail">dependencies unresolved</text></g><g data-component-id="queued"><title>Queued</title><rect x="440" y="520" width="250" height="140" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="440" y="520" width="250" height="7" rx="4" fill="#ffb86c"/><text x="458" y="546" class="type-label">TASK STATE</text><text x="458" y="572" class="node-label">Queued</text><text x="458" y="598" class="node-detail">durably persisted</text><text x="458" y="618" class="node-detail">awaiting admission</text></g><g data-component-id="running"><title>Running</title><rect x="770" y="520" width="250" height="140" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="770" y="520" width="250" height="7" rx="4" fill="#ffb86c"/><text x="788" y="546" class="type-label">TASK STATE</text><text x="788" y="572" class="node-label">Running</text><text x="788" y="598" class="node-detail">worker claimed task</text><text x="788" y="618" class="node-detail">detached child execution</text></g><g data-component-id="submitted"><title>Submitted</title><rect x="1100" y="520" width="250" height="140" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1100" y="520" width="250" height="7" rx="4" fill="#ff79c6"/><text x="1118" y="546" class="type-label">TASK STATE</text><text x="1118" y="572" class="node-label">Submitted</text><text x="1118" y="598" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">worker result awaits review</text></g><g data-component-id="accepted"><title>Accepted</title><rect x="1430" y="520" width="250" height="140" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1430" y="520" width="250" height="7" rx="4" fill="#50fa7b"/><text x="1448" y="546" class="type-label">TASK STATE</text><text x="1448" y="572" class="node-label">Accepted</text><text x="1448" y="598" class="node-detail">lead-approved Done state</text></g><g data-component-id="failed"><title>Failed</title><rect x="770" y="760" width="250" height="140" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="770" y="760" width="250" height="7" rx="4" fill="#ff79c6"/><text x="788" y="786" class="type-label">TASK STATE</text><text x="788" y="812" class="node-label">Failed</text><text x="788" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">error retained for recovery</text></g><g data-component-id="cancelled"><title>Cancelled</title><rect x="1100" y="760" width="250" height="140" rx="12" fill="#1b1e25" stroke="#9aa1ac" stroke-width="2"/><rect x="1100" y="760" width="250" height="7" rx="4" fill="#9aa1ac"/><text x="1118" y="786" class="type-label">TASK STATE</text><text x="1118" y="812" class="node-label">Cancelled</text><text x="1118" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">intentional terminal state</text></g><g data-component-id="team-completed"><title>Team Completed</title><rect x="1430" y="760" width="250" height="140" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1430" y="760" width="250" height="7" rx="4" fill="#50fa7b"/><text x="1448" y="786" class="type-label">EXECUTION STATE</text><text x="1448" y="812" class="node-label">Team Completed</text><text x="1448" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">all tasks accepted or cancelled</text></g><g data-callout-id="permitted-mutations"><rect x="110" y="740" width="550" height="165" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="126" y="770" class="callout-title">State-aware controls</text><text x="126" y="796" class="callout-text">modify_task: blocked or queued</text><text x="126" y="818" class="callout-text">cancel_task: blocked, queued, or running</text><text x="126" y="840" class="callout-text">list/get/inspect never mutate task state</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/11-agent-context-memory.svg b/docs/diagrams/v2/dark/11-agent-context-memory.svgnew file mode 100644index 00000000..306c3bd6--- /dev/null+++ b/docs/diagrams/v2/dark/11-agent-context-memory.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="c807035cec3f020d">+<title id="title">Agent Context vs. Simple Memory — dark theme</title>+<desc id="desc">Agent Context is the system-managed exact journal, provider binding, replay checkpoint, and context-pressure policy connected through input-context. Simple Memory is a separate explicit tool connected through input-tools; the model or a human chooses when to remember, recall, update, or forget versioned facts in an isolated namespace, and those items are never injected as automatic transcript replay. Sources: server/nodes/context/__init__.py; server/nodes/context/_descriptor.py; server/services/agent_context/store.py; server/services/agent_context/compaction.py; server/nodes/context/_handlers.py; server/nodes/tool/simple_memory/__init__.py; server/services/memory/tool_store.py; client/src/components/parameterPanel/ContextPanel.tsx; client/src/components/parameterPanel/MemoryToolPanel.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Agent Context vs. Simple Memory</text>+<text x="72" y="91" class="subtitle">Automatic replay continuity and explicit durable knowledge are separate systems</text>+<g data-group-id="context-plane"><rect x="72" y="140" width="720" height="800" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="92" y="172" class="group-label">AGENT CONTEXT · AUTOMATIC REPLAY</text></g><g data-group-id="memory-plane"><rect x="1128" y="140" width="720" height="800" rx="18" fill="#15171c" stroke="#50fa7b" stroke-width="2"/><text x="1148" y="172" class="group-label">SIMPLE MEMORY · EXPLICIT TOOL</text></g><g data-relationship-id="context-binds-runtime"><title>bind policy at input-context</title><path d="M 400 300.0 L 430 430 L 790 430 L 810 520.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="481.6" y="415.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="600" y="433" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">bind policy at input-context</text></g><g data-relationship-id="runtime-appends-context"><title>append exact observable events</title><path d="M 810 520.0 L 650 520 L 650 603 L 420 602.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="524.0" y="505.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="650" y="523" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">append exact observable events</text></g><g data-relationship-id="journal-compacts"><title>compact at context pressure</title><path d="M 270.0 695 L 270 725 L 590 725 L 590.0 760" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="315.4" y="710.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="430" y="728" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">compact at context pressure</text></g><g data-relationship-id="checkpoint-replays"><title>replay checkpoint + exact tail</title><path d="M 740 835.0 L 780 835 L 780 700 L 960 700 L 960.0 645" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="694.0" y="705.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="820" y="723" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">replay checkpoint + exact tail</text></g><g data-relationship-id="memory-registers-tool"><title>register tool at input-tools</title><path d="M 1520 300.0 L 1490 430 L 1130 430 L 1110 520.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1201.6" y="415.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1320" y="433" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">register tool at input-tools</text></g><g data-relationship-id="runtime-invokes-memory"><title>remember / recall / update / forget</title><path d="M 1110 520.0 L 1290 520 L 1290 603 L 1500 602.5" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1145.0" y="505.0" width="290.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1290" y="523" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">remember / recall / update / forget</text></g><g data-relationship-id="memory-persists-items"><title>persist isolated versioned items</title><path d="M 1650.0 695 L 1650 725 L 1330 725 L 1330.0 760" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1356.4" y="710.0" width="267.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1490" y="728" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">persist isolated versioned items</text></g><g data-relationship-id="memory-returns-items"><title>return selected recalled items</title><path d="M 1180 835.0 L 1140 835 L 1140 700 L 960 700 L 960.0 645" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="974.0" y="665.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1100" y="683" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">return selected recalled items</text></g><g data-component-id="context-node"><title>Context Node</title><rect x="120" y="220" width="280" height="160" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="120" y="220" width="280" height="7" rx="4" fill="#bd93f9"/><text x="138" y="246" class="type-label">POLICY</text><text x="138" y="272" class="node-label">Context Node</text><text x="138" y="298" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">output-context → input-context</text><text x="138" y="318" class="node-detail">compaction + tail policy</text></g><g data-component-id="context-journal"><title>AgentContextStore</title><rect x="120" y="510" width="300" height="185" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="120" y="510" width="300" height="7" rx="4" fill="#ff79c6"/><text x="138" y="536" class="type-label">EXACT JOURNAL</text><text x="138" y="562" class="node-label">AgentContextStore</text><text x="138" y="588" class="node-detail">append-only observable events</text><text x="138" y="608" class="node-detail">thread · epoch · revision</text><text x="138" y="628" class="node-detail">provider-bound replay state</text></g><g data-component-id="context-checkpoint"><title>Replay Checkpoint</title><rect x="440" y="760" width="300" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="440" y="760" width="300" height="7" rx="4" fill="#ffb86c"/><text x="458" y="786" class="type-label">CONTEXT STATE</text><text x="458" y="812" class="node-label">Replay Checkpoint</text><text x="458" y="838" class="node-detail">native or portable summary</text><text x="458" y="858" class="node-detail">exact recent tail retained</text></g><g data-component-id="agent-runtime"><title>Agent Runtime</title><rect x="810" y="395" width="300" height="250" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="810" y="395" width="300" height="7" rx="4" fill="#bd93f9"/><text x="828" y="421" class="type-label">SHARED CONSUMER</text><text x="828" y="447" class="node-label">Agent Runtime</text><text x="828" y="473" class="node-detail">replays Context automatically</text><text x="828" y="493" class="node-detail">invokes Memory explicitly</text><text x="828" y="513" class="node-detail">keeps both namespaces separate</text></g><g data-component-id="memory-node"><title>Simple Memory</title><rect x="1520" y="220" width="280" height="160" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1520" y="220" width="280" height="7" rx="4" fill="#50fa7b"/><text x="1538" y="246" class="type-label">LOCKED TOOL</text><text x="1538" y="272" class="node-label">Simple Memory</text><text x="1538" y="298" class="node-detail">output-tool → input-tools</text><text x="1538" y="318" class="node-detail">remember · recall · list</text><text x="1538" y="338" class="node-detail">get · update · forget</text></g><g data-component-id="memory-store"><title>MemoryToolStore</title><rect x="1500" y="510" width="300" height="185" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1500" y="510" width="300" height="7" rx="4" fill="#ff79c6"/><text x="1518" y="536" class="type-label">DURABLE DATA</text><text x="1518" y="562" class="node-label">MemoryToolStore</text><text x="1518" y="588" class="node-detail">owner / workflow / node scope</text><text x="1518" y="608" class="node-detail">versioned idempotent mutations</text><text x="1518" y="628" class="node-detail">lexical + optional embedding</text></g><g data-component-id="memory-items"><title>Facts & Decisions</title><rect x="1180" y="760" width="300" height="150" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1180" y="760" width="300" height="7" rx="4" fill="#50fa7b"/><text x="1198" y="786" class="type-label">MEMORY ITEMS</text><text x="1198" y="812" class="node-label">Facts & Decisions</text><text x="1198" y="838" class="node-detail">returned only when recalled</text><text x="1198" y="858" class="node-detail">never automatic transcript</text></g><g data-callout-id="context-invariant"><rect x="440" y="220" width="300" height="160" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="456" y="250" class="callout-title">Automatic continuity</text><text x="456" y="276" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">System managed; no model tool call</text><text x="456" y="298" class="callout-text">Exact journal and replay policy</text><text x="456" y="320" class="callout-text">Clear rotates the active epoch</text></g><g data-callout-id="memory-invariant"><rect x="1180" y="220" width="300" height="160" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="1196" y="250" class="callout-title">Explicit knowledge</text><text x="1196" y="276" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">Model or human chooses mutations</text><text x="1196" y="298" class="callout-text">Stable facts and decisions only</text><text x="1196" y="320" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">Clear never clears Agent Context</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/12-master-skill-editor.svg b/docs/diagrams/v2/dark/12-master-skill-editor.svgnew file mode 100644index 00000000..a5f97348--- /dev/null+++ b/docs/diagrams/v2/dark/12-master-skill-editor.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="37076efb9c516523">+<title id="title">Master Skill Editor — dark theme</title>+<desc id="desc">Source-backed anatomy of the Master Skill editor: built-in and user skill sources flow through WebSocket handlers and TanStack caches into the catalogue and instruction editor, while enabled skills persist in skills_config, expand for a connected agent, and report safe runtime badges back to the exact Master Skill row. Sources: client/src/components/parameterPanel/MasterSkillEditor.tsx; client/src/hooks/useFolderSkills.ts; server/services/skills/handlers.py; server/nodes/skill/master_skill/__init__.py; server/nodes/skill/_expander.py; server/services/skill_runtime.py; server/nodes/skill/master_skill/_events.py; client/src/contexts/WebSocketContext.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Master Skill Editor</text>+<text x="72" y="91" class="subtitle">One split panel joins the skill catalogue, authoritative instructions, node configuration, and live retrieval state.</text>+<g data-group-id="skill-sources"><rect x="70" y="130" width="500" height="700" rx="18" fill="#15171c" stroke="#ff79c6" stroke-width="2"/><text x="90" y="162" class="group-label">SKILL SOURCES + WIRE HANDLERS</text></g><g data-group-id="editor-surface"><rect x="610" y="130" width="760" height="700" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="630" y="162" class="group-label">MASTER SKILL EDITOR</text></g><g data-group-id="agent-runtime"><rect x="1410" y="130" width="440" height="700" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1430" y="162" class="group-label">CONNECTED AGENT RUNTIME</text></g><g data-relationship-id="handlers-scan-builtins"><title>scan and load metadata + instructions · via filesystem</title><path d="M 320.0 360 L 220 390 L 208 390 L 207.5 430" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 205.0 390.0 L 164.6 390" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="12.0" y="366.0" width="305.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="164.6" y="387" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">scan and load metadata + instructions</text><text x="164.6" y="407" class="edge-protocol" text-anchor="middle">via filesystem</text></g><g data-relationship-id="handlers-crud-user-skills"><title>list and mutate custom skills · via database</title><path d="M 320.0 360 L 430 390 L 433 390 L 432.5 430" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 430.0 390.0 L 520 390" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="397.8" y="366.0" width="244.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="520" y="387" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">list and mutate custom skills</text><text x="520" y="407" class="edge-protocol" text-anchor="middle">via database</text></g><g data-relationship-id="handlers-refresh-cache"><title>query results and lifecycle invalidation · via WebSocket</title><path d="M 110 280.0 L 90 280 L 90 715 L 110 715.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="106.0" y="591.0" width="328.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="270" y="612" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">query results and lifecycle invalidation</text><text x="270" y="632" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="cache-builds-projection"><title>cached folder, user, and content records</title><path d="M 530 715.0 L 650 695.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 590.0 690.0 L 590 852" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="426.0" y="837.0" width="328.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="590" y="855" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">cached folder, user, and content records</text></g><g data-relationship-id="projection-populates-catalogue"><title>render and filter rows</title><path d="M 810.0 620 L 810.0 530" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="714.4" y="560.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="810" y="578" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">render and filter rows</text></g><g data-relationship-id="catalogue-selects-editor"><title>select skill</title><path d="M 970 365.0 L 1010 365.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 990.0 350.0 L 990 139.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="930.0" y="124.0" width="120" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="990" y="142.0" class="edge-label" text-anchor="middle" textLength="102.0" lengthAdjust="spacingAndGlyphs">select skill</text></g><g data-relationship-id="catalogue-writes-toggle"><title>toggle enabled / keep required</title><path d="M 810.0 530 L 810 570 L 990 570 L 990 695 L 1010 695.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 900.0 560.0 L 1080 560" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="954.0" y="545.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1080" y="563" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">toggle enabled / keep required</text></g><g data-relationship-id="editor-writes-instructions"><title>write instructions + customized flag</title><path d="M 1170.0 530 L 1170.0 620" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 575.0 L 1170 845" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1021.2" y="830.0" width="297.59999999999997" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1170" y="848" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">write instructions + customized flag</text></g><g data-relationship-id="editor-user-skill-crud"><title>create / update / delete user skill · via WebSocket</title><path d="M 1170.0 200 L 1170 170 L 320 170 L 320.0 200" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 750.0 165.0 L 1200 165" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1055.0" y="141.0" width="290.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1200" y="162" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">create / update / delete user skill</text><text x="1200" y="182" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="config-expands"><title>expand enabled entries</title><path d="M 1330 695.0 L 1385 695 L 1385 275 L 1450 275.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1385.0 485.0 L 1295 593" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1199.4" y="578.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1295" y="596" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">expand enabled entries</text></g><g data-relationship-id="expander-builds-runtime"><title>descriptors + Skill tool catalogue</title><path d="M 1630.0 350 L 1630.0 430" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1488.8" y="375.0" width="282.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1630" y="393" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">descriptors + Skill tool catalogue</text></g><g data-relationship-id="runtime-publishes-status"><title>loading / loaded / used / failed · via node status + CloudEvents</title><path d="M 1630.0 590 L 1630.0 660" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1496.4" y="601.0" width="267.2" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1630" y="622" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">loading / loaded / used / failed</text><text x="1630" y="642" class="edge-protocol" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">via node status + CloudEvents</text></g><g data-relationship-id="status-back-to-catalogue"><title>project safe state onto matching row</title><path d="M 1630.0 780 L 1630 840 L 595 840 L 595 365 L 650 365.0" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1090.0 835.0 L 1540 835" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1391.2" y="820.0" width="297.59999999999997" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1540" y="838" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">project safe state onto matching row</text></g><g data-component-id="skill-ws-handlers"><title>Skill WebSocket handlers</title><rect x="110" y="200" width="420" height="160" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="110" y="200" width="420" height="7" rx="4" fill="#bd93f9"/><text x="128" y="226" class="type-label">SERVICE</text><text x="128" y="252" class="node-label">Skill WebSocket</text><text x="128" y="274" class="node-label">handlers</text><text x="128" y="300" class="node-detail">list / scan / get content</text><text x="128" y="320" class="node-detail">create / update / delete</text><text x="128" y="340" class="node-detail">skill_lifecycle broadcasts</text></g><g data-component-id="builtin-skill-files"><title>Built-in SKILL.md</title><rect x="110" y="430" width="195" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="430" width="195" height="7" rx="4" fill="#ff79c6"/><text x="128" y="456" class="type-label">SOURCE</text><text x="128" y="482" class="node-label">Built-in</text><text x="128" y="504" class="node-label">SKILL.md</text><text x="128" y="530" class="node-detail">server/skills/*</text><text x="128" y="550" class="node-detail" textLength="159.0" lengthAdjust="spacingAndGlyphs">metadata + instructions</text></g><g data-component-id="user-skill-store"><title>User skill store</title><rect x="335" y="430" width="195" height="150" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="335" y="430" width="195" height="7" rx="4" fill="#ff79c6"/><text x="353" y="456" class="type-label">DATABASE</text><text x="353" y="482" class="node-label">User skill</text><text x="353" y="504" class="node-label">store</text><text x="353" y="530" class="node-detail">custom records</text><text x="353" y="550" class="node-detail" textLength="159.0" lengthAdjust="spacingAndGlyphs">display + instructions</text></g><g data-component-id="tanstack-skill-cache"><title>TanStack skill caches</title><rect x="110" y="650" width="420" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="650" width="420" height="7" rx="4" fill="#ff79c6"/><text x="128" y="676" class="type-label">CLIENT STATE</text><text x="128" y="702" class="node-label">TanStack skill caches</text><text x="128" y="728" class="node-detail">userSkills · folderSkills</text><text x="128" y="748" class="node-detail">skillContent by name</text></g><g data-component-id="skill-catalogue-pane"><title>Skills catalogue pane</title><rect x="650" y="200" width="320" height="330" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="650" y="200" width="320" height="7" rx="4" fill="#8be9fd"/><text x="668" y="226" class="type-label">INTERFACE</text><text x="668" y="252" class="node-label">Skills catalogue</text><text x="668" y="274" class="node-label">pane</text><text x="668" y="300" class="node-detail">folder selector + search</text><text x="668" y="320" class="node-detail">enable / required / custom</text><text x="668" y="340" class="node-detail">Loading · Loaded · Failed</text><text x="668" y="360" class="node-detail">enabled count + create</text></g><g data-component-id="instructions-editor-pane"><title>Instructions editor pane</title><rect x="1010" y="200" width="320" height="330" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1010" y="200" width="320" height="7" rx="4" fill="#8be9fd"/><text x="1028" y="226" class="type-label">INTERFACE</text><text x="1028" y="252" class="node-label">Instructions editor</text><text x="1028" y="274" class="node-label">pane</text><text x="1028" y="300" class="node-detail">authoritative markdown</text><text x="1028" y="320" class="node-detail">create / edit / delete</text><text x="1028" y="340" class="node-detail">reset built-in default</text><text x="1028" y="360" class="node-detail">customized state</text></g><g data-component-id="query-projection"><title>Catalogue projection</title><rect x="650" y="620" width="320" height="150" rx="12" fill="#1b1e25" stroke="#9aa1ac" stroke-width="2"/><rect x="650" y="620" width="320" height="7" rx="4" fill="#9aa1ac"/><text x="668" y="646" class="type-label">VIEW MODEL</text><text x="668" y="672" class="node-label">Catalogue projection</text><text x="668" y="698" class="node-detail">folder rows + user rows</text><text x="668" y="718" class="node-detail">selected skill buffer</text></g><g data-component-id="skills-config"><title>Master Skill skills_config</title><rect x="1010" y="620" width="320" height="150" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="1010" y="620" width="320" height="7" rx="4" fill="#f1fa8c"/><text x="1028" y="646" class="type-label">NODE PARAMS</text><text x="1028" y="672" class="node-label">Master Skill</text><text x="1028" y="694" class="node-label">skills_config</text><text x="1028" y="720" class="node-detail">enabled · instructions</text><text x="1028" y="740" class="node-detail">isCustomized · required</text></g><g data-component-id="master-skill-expander"><title>Master Skill expander</title><rect x="1450" y="200" width="360" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1450" y="200" width="360" height="7" rx="4" fill="#ffb86c"/><text x="1468" y="226" class="type-label">RUNTIME</text><text x="1468" y="252" class="node-label">Master Skill</text><text x="1468" y="274" class="node-label">expander</text><text x="1468" y="300" class="node-detail">enabled entries only</text><text x="1468" y="320" class="node-detail">per-skill descriptors</text></g><g data-component-id="agent-skill-runtime"><title>Agent Skill runtime</title><rect x="1450" y="430" width="360" height="160" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="1450" y="430" width="360" height="7" rx="4" fill="#bd93f9"/><text x="1468" y="456" class="type-label">TOOL RUNTIME</text><text x="1468" y="482" class="node-label">Agent Skill runtime</text><text x="1468" y="508" class="node-detail">progressive load</text><text x="1468" y="528" class="node-detail">declared resources</text><text x="1468" y="548" class="node-detail">bounded safe events</text></g><g data-component-id="skill-status-projection"><title>Exact-node status projection</title><rect x="1450" y="660" width="360" height="120" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1450" y="660" width="360" height="7" rx="4" fill="#ff79c6"/><text x="1468" y="686" class="type-label">OBSERVABILITY</text><text x="1468" y="712" class="node-label">Exact-node status</text><text x="1468" y="734" class="node-label">projection</text><text x="1468" y="760" class="node-detail">active_skills / last_skills</text></g><g data-callout-id="master-skill-invariant"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Configuration is authoritative; observability is sanitized</text><text x="86" y="936" class="callout-text">skills_config keeps the enabled flag and instruction body used by the connected agent.</text><text x="86" y="958" class="callout-text">Runtime events expose names and states only—never prompts, arguments, results, secrets, or raw exceptions.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/13-workspace-files.svg b/docs/diagrams/v2/dark/13-workspace-files.svgnew file mode 100644index 00000000..0dcf71d9--- /dev/null+++ b/docs/diagrams/v2/dark/13-workspace-files.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="c97fa2af80f57078">+<title id="title">Workspace Files — dark theme</title>+<desc id="desc">Source-backed anatomy of the Gallery node’s Workspace Files panel, separating WebSocket listing/search from HTTP content and upload routes while showing how controlled path and selection parameters drive the Gallery node’s FileRef output. Sources: client/src/components/parameterPanel/GalleryPanel.tsx; client/src/components/parameterPanel/gallery/WorkspaceBrowser.tsx; server/nodes/filesystem/gallery/_handlers.py; server/nodes/filesystem/gallery/_service.py; server/nodes/filesystem/gallery/__init__.py; server/nodes/filesystem/_backend.py; server/routers/workspace.py; docs-internal/node-logic-flows/code_fs_process/gallery.md</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Workspace Files</text>+<text x="72" y="91" class="subtitle">Browse, search, upload, preview, pin, and emit files from the workflow’s contained workspace.</text>+<g data-group-id="workspace-panel"><rect x="70" y="130" width="900" height="700" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="90" y="162" class="group-label">GALLERY NODE · WORKSPACE FILES PANEL</text></g><g data-group-id="workspace-transport"><rect x="1010" y="130" width="840" height="420" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="1030" y="162" class="group-label">WORKSPACE TRANSPORT + STORAGE</text></g><g data-group-id="gallery-execution"><rect x="1010" y="590" width="840" height="240" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="1030" y="622" class="group-label">WORKFLOW EXECUTION PATH</text></g><g data-relationship-id="header-opens-upload"><title>Upload action</title><path d="M 520.0 300 L 790 325 L 790.0 350" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="728.6" y="310.0" width="122.8" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="790" y="328" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">Upload action</text></g><g data-relationship-id="browser-activates-file"><title>activate, pin, or drag file</title><path d="M 610 525.0 L 650 525.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 630.0 505.0 L 1080 559" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="965.4" y="544.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1080" y="562" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">activate, pin, or drag file</text></g><g data-relationship-id="browser-requests-listing"><title>browse path or send debounced search · via WebSocket</title><path d="M 360.0 350 L 360 325 L 990 325 L 990 265 L 1050 265.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 315.0 L 780 153" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="631.2" y="129.0" width="297.59999999999997" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="780" y="150" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">browse path or send debounced search</text><text x="780" y="170" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="handler-selects-listing-mode"><title>directory list or recursive search</title><path d="M 1220.0 330 L 1220.0 390" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1078.8" y="345.0" width="282.4" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1220" y="363" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">directory list or recursive search</text></g><g data-relationship-id="listing-reads-workspace"><title>contained ls_info / glob_info · via async filesystem</title><path d="M 1390 455.0 L 1450 455.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1420.0 450.0 L 1420 558" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1297.8" y="534.0" width="244.39999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1420" y="555" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">contained ls_info / glob_info</text><text x="1420" y="575" class="edge-protocol" text-anchor="middle">via async filesystem</text></g><g data-relationship-id="actions-use-http"><title>upload, preview, or download · via HTTP</title><path d="M 930 525.0 L 990 525 L 990 265 L 1450 265.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 990.0 385.0 L 1440 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1321.6" y="124.0" width="236.79999999999998" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1440" y="145.0" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">upload, preview, or download</text><text x="1440" y="165.0" class="edge-protocol" text-anchor="middle">via HTTP</text></g><g data-relationship-id="http-reads-writes-workspace"><title>write upload or stream content</title><path d="M 1630.0 330 L 1630.0 390" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1504.0" y="345.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1630" y="363" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">write upload or stream content</text></g><g data-relationship-id="browser-controls-path"><title>navigation writes path</title><path d="M 360.0 700 L 360 720 L 280 720 L 280 775 L 300 775.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 355.0 715.0 L 175 769" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="79.4" y="754.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="175" y="772" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">navigation writes path</text></g><g data-relationship-id="actions-control-selection"><title>pinning writes selection</title><path d="M 790.0 700 L 790 720 L 760 720 L 760 775 L 740 775.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 760.0 715.0 L 940 823" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="836.8" y="808.0" width="206.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="940" y="826" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">pinning writes selection</text></g><g data-relationship-id="params-drive-gallery-run"><title>run with path / selection</title><path d="M 740 775.0 L 980 775 L 980 710 L 1050 710.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="768.0" y="750.0" width="214.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="875" y="768" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">run with path / selection</text></g><g data-relationship-id="gallery-reuses-listing-service"><title>reuse listing and FileRef conversion</title><path d="M 1220.0 650 L 1220.0 520" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1220.0 585.0 L 1220 801" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1071.2" y="786.0" width="297.59999999999997" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1220" y="804" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">reuse listing and FileRef conversion</text></g><g data-relationship-id="gallery-emits-output"><title>emit selected or listed files</title><path d="M 1390 710.0 L 1450 710.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1420.0 710.0 L 1420 602" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1297.8" y="587.0" width="244.39999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1420" y="605" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">emit selected or listed files</text></g><g data-component-id="workspace-panel-header"><title>Workspace Files header</title><rect x="110" y="200" width="820" height="100" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="200" width="820" height="7" rx="4" fill="#8be9fd"/><text x="128" y="226" class="type-label">INTERFACE</text><text x="128" y="252" class="node-label">Workspace Files header</text><text x="128" y="278" class="node-detail">workflow-produced files · Upload action</text></g><g data-component-id="workspace-browser"><title>WorkspaceBrowser</title><rect x="110" y="350" width="500" height="350" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="350" width="500" height="7" rx="4" fill="#8be9fd"/><text x="128" y="376" class="type-label">INTERFACE</text><text x="128" y="402" class="node-label">WorkspaceBrowser</text><text x="128" y="428" class="node-detail">breadcrumbs + directory navigation</text><text x="128" y="448" class="node-detail">250 ms search · whole workspace</text><text x="128" y="468" class="node-detail">grid / list · refresh · 5 s poll</text><text x="128" y="488" class="node-detail">empty, missing, truncated states</text></g><g data-component-id="workspace-file-actions"><title>File actions</title><rect x="650" y="350" width="280" height="350" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="650" y="350" width="280" height="7" rx="4" fill="#50fa7b"/><text x="668" y="376" class="type-label">INTERFACE</text><text x="668" y="402" class="node-label">File actions</text><text x="668" y="428" class="node-detail">upload one or many</text><text x="668" y="448" class="node-detail">preview / download</text><text x="668" y="468" class="node-detail">pin for node output</text><text x="668" y="488" class="node-detail">FileRef drag payload</text></g><g data-component-id="gallery-node-parameters"><title>Node params: path + selection</title><rect x="300" y="740" width="440" height="70" rx="12" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2"/><rect x="300" y="740" width="440" height="7" rx="4" fill="#f1fa8c"/><text x="318" y="766" class="type-label">NODE PARAMS</text><text x="318" y="792" class="node-label">Node params · path + selection</text></g><g data-component-id="list-workspace-files-handler"><title>list_workspace_files</title><rect x="1050" y="200" width="340" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1050" y="200" width="340" height="7" rx="4" fill="#ff79c6"/><text x="1068" y="226" class="type-label">WEBSOCKET</text><text x="1068" y="252" class="node-label">list_workspace_files</text><text x="1068" y="278" class="node-detail">path or workspace-wide search</text><text x="1068" y="298" class="node-detail">limit 500 from panel</text></g><g data-component-id="workspace-http-routes"><title>Workspace HTTP routes</title><rect x="1450" y="200" width="360" height="130" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1450" y="200" width="360" height="7" rx="4" fill="#8be9fd"/><text x="1468" y="226" class="type-label">HTTP</text><text x="1468" y="252" class="node-label">Workspace HTTP routes</text><text x="1468" y="278" class="node-detail">POST uploads</text><text x="1468" y="298" class="node-detail">GET content · Range</text></g><g data-component-id="workspace-listing-service"><title>Workspace listing service</title><rect x="1050" y="390" width="340" height="130" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="1050" y="390" width="340" height="7" rx="4" fill="#bd93f9"/><text x="1068" y="416" class="type-label">SERVICE</text><text x="1068" y="442" class="node-label">Workspace listing</text><text x="1068" y="464" class="node-label">service</text><text x="1068" y="490" class="node-detail">directory or recursive glob</text><text x="1068" y="510" class="node-detail">sort, cap, crumbs, preview</text></g><g data-component-id="contained-workspace-root"><title>Contained workflow workspace</title><rect x="1450" y="390" width="360" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="1450" y="390" width="360" height="7" rx="4" fill="#ff79c6"/><text x="1468" y="416" class="type-label">FILESYSTEM</text><text x="1468" y="442" class="node-label">Contained workflow</text><text x="1468" y="464" class="node-label">workspace</text><text x="1468" y="490" class="node-detail">WorkspaceBackend</text><text x="1468" y="510" class="node-detail">workspace-relative paths</text></g><g data-component-id="gallery-node-runtime"><title>Gallery node execution</title><rect x="1050" y="650" width="340" height="120" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="1050" y="650" width="340" height="7" rx="4" fill="#ffb86c"/><text x="1068" y="676" class="type-label">RUNTIME</text><text x="1068" y="702" class="node-label">Gallery node</text><text x="1068" y="724" class="node-label">execution</text><text x="1068" y="750" class="node-detail">selection > pattern > directory</text></g><g data-component-id="gallery-file-ref-output"><title>Downstream FileRef output</title><rect x="1450" y="650" width="360" height="120" rx="12" fill="#1b1e25" stroke="#50fa7b" stroke-width="2"/><rect x="1450" y="650" width="360" height="7" rx="4" fill="#50fa7b"/><text x="1468" y="676" class="type-label">RESULT</text><text x="1468" y="702" class="node-label">Downstream FileRef</text><text x="1468" y="724" class="node-label">output</text><text x="1468" y="750" class="node-detail">files · directories · missing[]</text></g><g data-callout-id="workspace-channel-contract"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Two channels, one contained workspace</text><text x="86" y="936" class="callout-text">WebSocket owns listing and search; HTTP owns upload and file bytes for preview, download, and Range requests.</text><text x="86" y="958" class="callout-text">Rows arrive with a server-built FileRef and preview verdict, so the client does not duplicate path or security decisions.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/dark/14-runtime-observability-dock.svg b/docs/diagrams/v2/dark/14-runtime-observability-dock.svgnew file mode 100644index 00000000..aae18e9d--- /dev/null+++ b/docs/diagrams/v2/dark/14-runtime-observability-dock.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="dark" data-geometry-signature="66d4ac8c11b8cc0a">+<title id="title">Runtime Observability Dock — dark theme</title>+<desc id="desc">Source-backed topology of the collapsible Chat / Console dock: chat messages, Console node records, and terminal logs use distinct producers and retention paths, converge in WebSocketContext state, and render in a resizable chat pane plus Console and Terminal tabs with targeted filters and clear actions. Sources: client/src/components/ui/ConsolePanel.tsx; client/src/contexts/WebSocketContext.tsx; server/nodes/utility/console/__init__.py; server/services/status_broadcaster.py; server/routers/websocket.py; server/nodes/trigger/chat_trigger/_events.py; server/services/process_service.py; server/core/logging.py; docs-internal/node-logic-flows/chat_utility/console.md</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#e8eaed"/></marker>+ <style>+ .title { fill:#e8eaed; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#9aa1ac; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#9aa1ac; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#e8eaed; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#e8eaed; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#9aa1ac; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#e8eaed; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#9aa1ac; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#9aa1ac; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#0d0f13"/>+<text x="72" y="58" class="title">Runtime Observability Dock</text>+<text x="72" y="91" class="subtitle">One resizable dock combines workflow chat, Console-node output, and live server/process logs without conflating their scopes.</text>+<g data-group-id="runtime-producers"><rect x="70" y="130" width="460" height="700" rx="18" fill="#15171c" stroke="#ffb86c" stroke-width="2"/><text x="90" y="162" class="group-label">RUNTIME PRODUCERS + CONSUMERS</text></g><g data-group-id="observability-transport"><rect x="570" y="130" width="590" height="700" rx="18" fill="#15171c" stroke="#bd93f9" stroke-width="2"/><text x="590" y="162" class="group-label">TRANSPORT + RETAINED STATE</text></g><g data-group-id="observability-dock"><rect x="1200" y="130" width="650" height="700" rx="18" fill="#15171c" stroke="#8be9fd" stroke-width="2"/><text x="1220" y="162" class="group-label">COLLAPSIBLE CHAT / CONSOLE DOCK</text></g><g data-relationship-id="console-broadcasts-log"><title>broadcast_console_log</title><path d="M 490 275.0 L 610 280.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 265.0 L 460 373" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="368.2" y="358.0" width="183.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="460" y="376" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">broadcast_console_log</text></g><g data-relationship-id="runtime-broadcasts-terminal"><title>broadcast_terminal_log</title><path d="M 490 505.0 L 550 505 L 550 315 L 610 280.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 410.0 L 640 410" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="544.4" y="395.0" width="191.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="640" y="413" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">broadcast_terminal_log</text></g><g data-relationship-id="broadcaster-persists-console"><title>persist Console records</title><path d="M 730.0 360 L 730.0 440" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 730.0 400.0 L 910 400" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="810.6" y="385.0" width="198.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="910" y="403" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">persist Console records</text></g><g data-relationship-id="broadcaster-retains-terminal"><title>retain latest Terminal records</title><path d="M 850 280.0 L 870 280 L 870 405 L 1005 405 L 1005.0 440" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 920.0 395.0 L 920 611" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="794.0" y="596.0" width="252.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="920" y="614" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">retain latest Terminal records</text></g><g data-relationship-id="handlers-query-db"><title>get / clear scoped history</title><path d="M 1005.0 360 L 1005 400 L 870 400 L 870 505 L 850 505.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 885.0 390.0 L 1065 174" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="954.2" y="159.0" width="221.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1065" y="177" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">get / clear scoped history</text></g><g data-relationship-id="handlers-query-terminal-cache"><title>get / clear terminal history</title><path d="M 1005.0 360 L 1005.0 440" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1005.0 400.0 L 1005 139.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="886.6" y="124.0" width="236.79999999999998" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1005" y="142.0" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">get / clear terminal history</text></g><g data-relationship-id="handlers-dispatch-chat-trigger"><title>dispatch chat_message_received · via workflow-scoped CloudEvent</title><path d="M 890 280.0 L 560 280 L 560 720 L 490 720.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 560.0 600.0 L 560 816" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="434.0" y="792.0" width="252.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="560" y="813" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">dispatch chat_message_received</text><text x="560" y="833" class="edge-protocol" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">via workflow-scoped CloudEvent</text></g><g data-relationship-id="live-events-update-context"><title>live console_log / terminal_log · via WebSocket broadcast</title><path d="M 610 280.0 L 590 280 L 590 720 L 760 720.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 675.0 625.0 L 585 625" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="455.2" y="601.0" width="259.6" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="585" y="622" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">live console_log / terminal_log</text><text x="585" y="642" class="edge-protocol" text-anchor="middle">via WebSocket broadcast</text></g><g data-relationship-id="handlers-hydrate-context"><title>hydrate on connect or workflow switch</title><path d="M 1120 280.0 L 1140 280 L 1140 630 L 890 630 L 890.0 660" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1135.0 520.0 L 1045 790" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="892.4" y="775.0" width="305.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1045" y="793" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">hydrate on connect or workflow switch</text></g><g data-relationship-id="chat-sends-handler-request"><title>send_chat_message / clear chat · via WebSocket request</title><path d="M 1370.0 200 L 1370 165 L 1005 165 L 1005.0 200" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1190.0 160.0 L 1640 148.0" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1514.0" y="124.0" width="252.0" height="48" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1640" y="145.0" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">send_chat_message / clear chat</text><text x="1640" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket request</text></g><g data-relationship-id="context-renders-chat"><title>chat messages</title><path d="M 1020 720.0 L 1180 720 L 1180 450 L 1240 450.0" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1180.0 585.0 L 1090 693" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1028.6" y="678.0" width="122.8" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1090" y="696" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">chat messages</text></g><g data-relationship-id="context-renders-console"><title>Console records</title><path d="M 890.0 660 L 890 610 L 1175 610 L 1175 145 L 1675 145 L 1675.0 200" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1510.0 140.0 L 1839.0 140" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1770.0" y="125.0" width="138.0" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1839.0" y="143" class="edge-label" text-anchor="middle" textLength="120.0" lengthAdjust="spacingAndGlyphs">Console records</text></g><g data-relationship-id="context-renders-terminal"><title>Terminal records</title><path d="M 890.0 780 L 890 845 L 1675 845 L 1675.0 700" fill="none" stroke="#e8eaed" stroke-width="2" marker-end="url(#arrow)"/><rect x="1407.2" y="825.0" width="145.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1480" y="843" class="edge-label" text-anchor="middle" textLength="127.6" lengthAdjust="spacingAndGlyphs">Terminal records</text></g><g data-relationship-id="prefs-shape-chat-pane"><title>height + split width + font</title><path d="M 1240 765.0 L 1220 775 L 1220 720 L 1370 720 L 1370.0 700" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1300.0 715.0 L 1030 823" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="915.4" y="808.0" width="229.2" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1030" y="826" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">height + split width + font</text></g><g data-relationship-id="prefs-select-log-tab"><title>selected Console / Terminal tab</title><path d="M 1810 765.0 L 1830 775 L 1830 720 L 1675 720 L 1675.0 700" fill="none" stroke="#e8eaed" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1725.0 715.0 L 1778.2 445" fill="none" stroke="#9aa1ac" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1648.4" y="430.0" width="259.6" height="30" rx="7" fill="#15171c" stroke="#2b2f37"/><text x="1778.2" y="448" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">selected Console / Terminal tab</text></g><g data-component-id="console-node-producer"><title>Console node output</title><rect x="110" y="200" width="380" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="110" y="200" width="380" height="7" rx="4" fill="#ffb86c"/><text x="128" y="226" class="type-label">WORKFLOW</text><text x="128" y="252" class="node-label">Console node output</text><text x="128" y="278" class="node-detail">label · format · formatted data</text><text x="128" y="298" class="node-detail">workflow + source node IDs</text></g><g data-component-id="terminal-log-producers"><title>Server / process / CLI logs</title><rect x="110" y="430" width="380" height="150" rx="12" fill="#1b1e25" stroke="#ffb86c" stroke-width="2"/><rect x="110" y="430" width="380" height="7" rx="4" fill="#ffb86c"/><text x="128" y="456" class="type-label">RUNTIME</text><text x="128" y="482" class="node-label">Server / process / CLI</text><text x="128" y="504" class="node-label">logs</text><text x="128" y="530" class="node-detail">level · message · source</text><text x="128" y="550" class="node-detail">optional details</text></g><g data-component-id="chat-trigger-consumers"><title>chatTrigger consumers</title><rect x="110" y="660" width="380" height="120" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="660" width="380" height="7" rx="4" fill="#ff79c6"/><text x="128" y="686" class="type-label">TRIGGER</text><text x="128" y="712" class="node-label">chatTrigger consumers</text><text x="128" y="738" class="node-detail">workflow-scoped CloudEvent</text></g><g data-component-id="status-broadcaster"><title>StatusBroadcaster</title><rect x="610" y="200" width="240" height="160" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="610" y="200" width="240" height="7" rx="4" fill="#ff79c6"/><text x="628" y="226" class="type-label">EVENT BUS</text><text x="628" y="252" class="node-label">StatusBroadcaster</text><text x="628" y="278" class="node-detail">console_log</text><text x="628" y="298" class="node-detail">terminal_log</text><text x="628" y="318" class="node-detail">clear broadcasts</text></g><g data-component-id="dock-ws-handlers"><title>Dock WebSocket handlers</title><rect x="890" y="200" width="230" height="160" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="890" y="200" width="230" height="7" rx="4" fill="#bd93f9"/><text x="908" y="226" class="type-label">SERVICE</text><text x="908" y="252" class="node-label">Dock WebSocket</text><text x="908" y="274" class="node-label">handlers</text><text x="908" y="300" class="node-detail">send / get / clear</text><text x="908" y="320" class="node-detail" textLength="194.0" lengthAdjust="spacingAndGlyphs">chat · console · terminal</text></g><g data-component-id="workflow-history-db"><title>Workflow history DB</title><rect x="610" y="440" width="240" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="610" y="440" width="240" height="7" rx="4" fill="#ff79c6"/><text x="628" y="466" class="type-label">DATABASE</text><text x="628" y="492" class="node-label" textLength="204.0" lengthAdjust="spacingAndGlyphs">Workflow history DB</text><text x="628" y="518" class="node-detail">chat_messages</text><text x="628" y="538" class="node-detail">console_logs</text></g><g data-component-id="terminal-ring-buffer"><title>Terminal ring buffer</title><rect x="890" y="440" width="230" height="130" rx="12" fill="#1b1e25" stroke="#ff79c6" stroke-width="2"/><rect x="890" y="440" width="230" height="7" rx="4" fill="#ff79c6"/><text x="908" y="466" class="type-label">MEMORY</text><text x="908" y="492" class="node-label">Terminal ring</text><text x="908" y="514" class="node-label">buffer</text><text x="908" y="540" class="node-detail">latest 200 entries</text><text x="908" y="560" class="node-detail">global in process</text></g><g data-component-id="websocket-context-state"><title>WebSocketContext state</title><rect x="760" y="660" width="260" height="120" rx="12" fill="#1b1e25" stroke="#bd93f9" stroke-width="2"/><rect x="760" y="660" width="260" height="7" rx="4" fill="#bd93f9"/><text x="778" y="686" class="type-label">CLIENT STATE</text><text x="778" y="712" class="node-label">WebSocketContext</text><text x="778" y="734" class="node-label">state</text><text x="778" y="760" class="node-detail" textLength="224.0" lengthAdjust="spacingAndGlyphs">chat · console · terminal arrays</text></g><g data-component-id="chat-pane"><title>Chat pane</title><rect x="1240" y="200" width="260" height="500" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1240" y="200" width="260" height="7" rx="4" fill="#8be9fd"/><text x="1258" y="226" class="type-label">INTERFACE</text><text x="1258" y="252" class="node-label">Chat pane</text><text x="1258" y="278" class="node-detail" textLength="224.0" lengthAdjust="spacingAndGlyphs">All Triggers or one target</text><text x="1258" y="298" class="node-detail">user + assistant messages</text><text x="1258" y="318" class="node-detail">Enter to send</text><text x="1258" y="338" class="node-detail">clear current workflow</text></g><g data-component-id="console-tab"><title>Console tab</title><rect x="1540" y="200" width="270" height="230" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1540" y="200" width="270" height="7" rx="4" fill="#8be9fd"/><text x="1558" y="226" class="type-label">INTERFACE</text><text x="1558" y="252" class="node-label">Console tab</text><text x="1558" y="278" class="node-detail">filter by Console node</text><text x="1558" y="298" class="node-detail">search + pretty print</text><text x="1558" y="318" class="node-detail">workflow-scoped clear</text></g><g data-component-id="terminal-tab"><title>Terminal tab</title><rect x="1540" y="470" width="270" height="230" rx="12" fill="#1b1e25" stroke="#8be9fd" stroke-width="2"/><rect x="1540" y="470" width="270" height="7" rx="4" fill="#8be9fd"/><text x="1558" y="496" class="type-label">INTERFACE</text><text x="1558" y="522" class="node-label">Terminal tab</text><text x="1558" y="548" class="node-detail">level threshold</text><text x="1558" y="568" class="node-detail">message / source search</text><text x="1558" y="588" class="node-detail">global clear</text></g><g data-component-id="dock-preferences"><title>Persisted dock preferences</title><rect x="1240" y="720" width="570" height="90" rx="12" fill="#1b1e25" stroke="#9aa1ac" stroke-width="2"/><rect x="1240" y="720" width="570" height="7" rx="4" fill="#9aa1ac"/><text x="1258" y="746" class="type-label">LOCAL STATE</text><text x="1258" y="772" class="node-label">Persisted dock preferences</text><text x="1258" y="798" class="node-detail">height · split width · font · autoscroll · pretty print · tab</text></g><g data-callout-id="observability-scope-contract"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#1b1e25" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Scope and retention stay deliberately distinct</text><text x="86" y="936" class="callout-text">Chat and Console history are persisted and scoped to the current workflow; Terminal history is a process-wide in-memory buffer of the latest 200 entries.</text><text x="86" y="958" class="callout-text">The dock persists only presentation preferences in localStorage—panel height, split width, font size, auto-scroll, pretty print, and selected log tab.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/01-system-context.svg b/docs/diagrams/v2/light/01-system-context.svgnew file mode 100644index 00000000..61ff3549--- /dev/null+++ b/docs/diagrams/v2/light/01-system-context.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="7b0bff93951dc145">+<title id="title">OpenCompany System Context — light theme</title>+<desc id="desc">A C4-style system context view of OpenCompany as an automation workspace between human users and external model, productivity, messaging, device, developer, and retrieval services. Sources: README.md; server/nodes/groups.py; server/config/credential_providers.json; server/main.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">OpenCompany System Context</text>+<text x="72" y="91" class="subtitle">Who uses the system and which external capabilities it orchestrates</text>+<g data-group-id="opencompany-boundary"><rect x="420" y="145" width="930" height="800" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="440" y="177" class="group-label">OPENCOMPANY SYSTEM BOUNDARY</text></g><g data-relationship-id="r-authors-design"><title>Design and run automations · via Browser UI / CLI</title><path d="M 340 327.5 L 510 327 L 510 445 L 665 487.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="389.2" y="341.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="500" y="362" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Design and run automations</text><text x="500" y="382" class="edge-protocol" text-anchor="middle">via Browser UI / CLI</text></g><g data-relationship-id="r-operators-control"><title>Control deployed workflows · via Browser UI / WebSocket</title><path d="M 340 702.5 L 535 702 L 535 535 L 665 487.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="394.2" y="641.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="505" y="662" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Control deployed workflows</text><text x="505" y="682" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via Browser UI / WebSocket</text></g><g data-relationship-id="r-opencompany-llm"><title>Requests inference · via Provider SDK / HTTPS</title><path d="M 1105 487.5 L 1210 487 L 1210 182 L 1480 182.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1221.8" y="158.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1325" y="179" class="edge-label" text-anchor="middle">Requests inference</text><text x="1325" y="199" class="edge-protocol" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">via Provider SDK / HTTPS</text></g><g data-relationship-id="r-opencompany-productivity"><title>Reads and updates work · via OAuth / HTTPS</title><path d="M 1105 487.5 L 1240 487 L 1240 327 L 1480 327.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1254.4" y="303.0" width="191.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1350" y="324" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Reads and updates work</text><text x="1350" y="344" class="edge-protocol" text-anchor="middle">via OAuth / HTTPS</text></g><g data-relationship-id="r-opencompany-messaging"><title>Sends and receives messages · via Webhooks / RPC</title><path d="M 1105 487.5 L 1270 487 L 1270 472 L 1480 472.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1365.0 472.0 L 1275 472" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1160.4" y="448.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1275" y="469" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Sends and receives messages</text><text x="1275" y="489" class="edge-protocol" text-anchor="middle">via Webhooks / RPC</text></g><g data-relationship-id="r-opencompany-devices"><title>Invokes device actions · via RPC / platform APIs</title><path d="M 1105 487.5 L 1270 487 L 1270 617 L 1480 617.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1260.6" y="593.0" width="198.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1360" y="614" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">Invokes device actions</text><text x="1360" y="634" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via RPC / platform APIs</text></g><g data-relationship-id="r-opencompany-developer"><title>Uses code and dev tools · via MCP / CLI / HTTPS</title><path d="M 1105 487.5 L 1240 487 L 1240 762 L 1480 762.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1250.6" y="738.0" width="198.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1350" y="759" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">Uses code and dev tools</text><text x="1350" y="779" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via MCP / CLI / HTTPS</text></g><g data-relationship-id="r-opencompany-search"><title>Indexes and retrieves knowledge · via HTTPS / vector API</title><path d="M 1105 487.5 L 1210 487 L 1210 910 L 1480 910.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1210.2" y="886.0" width="259.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1340" y="907" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">Indexes and retrieves knowledge</text><text x="1340" y="927" class="edge-protocol" text-anchor="middle">via HTTPS / vector API</text></g><g data-component-id="workflow-authors"><title>Workflow authors</title><rect x="55" y="265" width="285" height="125" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="55" y="265" width="285" height="7" rx="4" fill="#f1fa8c"/><text x="73" y="291" class="type-label">PERSON</text><text x="73" y="317" class="node-label">Workflow authors</text><text x="73" y="343" class="node-detail">Build and test automations</text></g><g data-component-id="workflow-operators"><title>Workflow operators</title><rect x="55" y="640" width="285" height="125" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="55" y="640" width="285" height="7" rx="4" fill="#f1fa8c"/><text x="73" y="666" class="type-label">PERSON</text><text x="73" y="692" class="node-label">Workflow operators</text><text x="73" y="718" class="node-detail">Deploy and supervise runs</text></g><g data-component-id="opencompany"><title>OpenCompany</title><rect x="665" y="385" width="440" height="205" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="665" y="385" width="440" height="7" rx="4" fill="#bd93f9"/><text x="683" y="411" class="type-label">SOFTWARE SYSTEM</text><text x="683" y="437" class="node-label">OpenCompany</text><text x="683" y="463" class="node-detail">Visual workflow workspace</text><text x="683" y="483" class="node-detail">Agents, tools, triggers and durable runs</text></g><g data-component-id="llm-providers"><title>LLM providers</title><rect x="1480" y="130" width="365" height="105" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1480" y="130" width="365" height="7" rx="4" fill="#8be9fd"/><text x="1498" y="156" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="182" class="node-label">LLM providers</text><text x="1498" y="208" class="node-detail">Hosted and local inference</text></g><g data-component-id="productivity-services"><title>Productivity services</title><rect x="1480" y="275" width="365" height="105" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="275" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="301" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="327" class="node-label">Productivity services</text><text x="1498" y="353" class="node-detail">Mail, calendar, docs and CRM</text></g><g data-component-id="messaging-channels"><title>Messaging channels</title><rect x="1480" y="420" width="365" height="105" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="420" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="446" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="472" class="node-label">Messaging channels</text><text x="1498" y="498" class="node-detail">Chat and social platforms</text></g><g data-component-id="connected-devices"><title>Connected devices</title><rect x="1480" y="565" width="365" height="105" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1480" y="565" width="365" height="7" rx="4" fill="#50fa7b"/><text x="1498" y="591" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="617" class="node-label">Connected devices</text><text x="1498" y="643" class="node-detail">Android and device services</text></g><g data-component-id="developer-services"><title>Developer services</title><rect x="1480" y="710" width="365" height="105" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1480" y="710" width="365" height="7" rx="4" fill="#8be9fd"/><text x="1498" y="736" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="762" class="node-label">Developer services</text><text x="1498" y="788" class="node-detail">Code, CLI and MCP tools</text></g><g data-component-id="search-vector-stores"><title>Search and vector stores</title><rect x="1480" y="855" width="365" height="110" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1480" y="855" width="365" height="7" rx="4" fill="#ff79c6"/><text x="1498" y="881" class="type-label">EXTERNAL SYSTEM</text><text x="1498" y="907" class="node-label">Search and</text><text x="1498" y="929" class="node-label">vector stores</text><text x="1498" y="955" class="node-detail">Retrieval and knowledge indexes</text></g><g data-callout-id="system-purpose"><rect x="615" y="700" width="540" height="135" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="631" y="730" class="callout-title">System responsibility</text><text x="631" y="756" class="callout-text">Compose external capabilities as directed graphs.</text><text x="631" y="778" class="callout-text">Keep execution, credentials and observability</text><text x="631" y="800" class="callout-text">inside one user-scoped workspace.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/02-runtime-trust-topology.svg b/docs/diagrams/v2/light/02-runtime-trust-topology.svgnew file mode 100644index 00000000..ad41baad--- /dev/null+++ b/docs/diagrams/v2/light/02-runtime-trust-topology.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="ef4930f8db7feab0">+<title id="title">Runtime and Trust Topology — light theme</title>+<desc id="desc">A runtime topology that distinguishes the browser and CLI clients, Vite development proxy, FastAPI application, protected and restricted protocol surfaces, Temporal orchestration, and lazily started helper processes. Sources: .env.template; client/vite.config.js; server/main.py; server/middleware/auth.py; server/routers/websocket.py; server/services/authz/ws_surface.py; server/services/cli_agent/mcp_server.py; server/services/temporal/lifecycle.py; server/nodes/code/_runtime.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Runtime and Trust Topology</text>+<text x="72" y="91" class="subtitle">Development and production paths, authenticated surfaces, durable orchestration and lazy helpers</text>+<g data-group-id="client-zone"><rect x="40" y="135" width="350" height="830" rx="18" fill="#fafbfc" stroke="#f1fa8c" stroke-width="2"/><text x="60" y="167" class="group-label">CLIENTS AND PUBLIC SENDERS</text></g><g data-group-id="app-zone"><rect x="425" y="135" width="1050" height="830" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="445" y="167" class="group-label">OPENCOMPANY APPLICATION</text></g><g data-group-id="runtime-zone"><rect x="1510" y="135" width="370" height="830" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1530" y="167" class="group-label">DURABLE AND LAZY RUNTIMES</text></g><g data-relationship-id="r-browser-vite"><title>Loads SPA in development · via HTTP :5678</title><path d="M 360 272.5 L 455 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 238.0 L 315 400" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="211.8" y="376.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="315" y="397" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Loads SPA in development</text><text x="315" y="417" class="edge-protocol" text-anchor="middle">via HTTP :5678</text></g><g data-relationship-id="r-vite-fastapi"><title>Proxies /api /ws /webhook /health /mcp · via HTTP / WS :5679</title><path d="M 735 257.5 L 820 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 340.0 L 780 556" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="623.6" y="532.0" width="312.8" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="780" y="553" class="edge-label" text-anchor="middle" textLength="294.8" lengthAdjust="spacingAndGlyphs">Proxies /api /ws /webhook /health /mcp</text><text x="780" y="573" class="edge-protocol" text-anchor="middle">via HTTP / WS :5679</text></g><g data-relationship-id="r-cli-fastapi"><title>Launches and administers · via Typer / process</title><path d="M 360 527.5 L 405 527 L 405 365 L 790 365 L 790 257 L 820 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="486.8" y="341.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="590" y="362" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Launches and administers</text><text x="590" y="382" class="edge-protocol" text-anchor="middle">via Typer / process</text></g><g data-relationship-id="r-browser-rest"><title>Calls protected routes · via HTTPS + JWT cookie</title><path d="M 360 272.5 L 405 272 L 405 460 L 455 460.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 395.0 L 495 557" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="399.4" y="533.0" width="191.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="495" y="554" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Calls protected routes</text><text x="495" y="574" class="edge-protocol" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">via HTTPS + JWT cookie</text></g><g data-relationship-id="r-browser-status"><title>Commands and receives status · via WebSocket + cookie</title><path d="M 360 272.5 L 400 272 L 400 580 L 780 580 L 780 460 L 820 460.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 585.0 580.0 L 315 634" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="196.60000000000002" y="610.0" width="236.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="315" y="631" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">Commands and receives status</text><text x="315" y="651" class="edge-protocol" text-anchor="middle">via WebSocket + cookie</text></g><g data-relationship-id="r-cli-mcp"><title>Invokes scoped tools · via MCP over HTTP + Bearer</title><path d="M 360 527.5 L 405 527 L 405 715 L 455 715.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 405.0 635.0 L 315 689" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="204.2" y="665.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="315" y="686" class="edge-label" text-anchor="middle">Invokes scoped tools</text><text x="315" y="706" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via MCP over HTTP + Bearer</text></g><g data-relationship-id="r-webhook-ingress"><title>Delivers provider events · via HTTPS webhook</title><path d="M 360 792.5 L 820 715.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 585.0 815.0 L 405 923" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="301.8" y="899.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="405" y="920" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Delivers provider events</text><text x="405" y="940" class="edge-protocol" text-anchor="middle">via HTTPS webhook</text></g><g data-relationship-id="r-surfaces-app"><title>Dispatches request · via ASGI</title><path d="M 595.0 400 L 595 365 L 970 365 L 970.0 325" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="704.6" y="341.0" width="160.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="785" y="362" class="edge-label" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">Dispatches request</text><text x="785" y="382" class="edge-protocol" text-anchor="middle">via ASGI</text></g><g data-relationship-id="r-status-app"><title>Dispatches authenticated message · via ASGI WebSocket</title><path d="M 960.0 400 L 970.0 325" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 970.0 365.0 L 1060 365" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="926.4" y="341.0" width="267.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1060" y="362" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Dispatches authenticated message</text><text x="1060" y="382" class="edge-protocol" text-anchor="middle">via ASGI WebSocket</text></g><g data-relationship-id="r-temporal-internal"><title>Calls legacy node handlers · via WebSocket</title><path d="M 1540 282.5 L 1500 282 L 1500 460 L 1445 460.0" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1500.0 390.0 L 1590 390" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1479.2" y="366.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1590" y="387" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Calls legacy node handlers</text><text x="1590" y="407" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="r-fastapi-temporal"><title>Starts workflows and polls tasks · via Temporal gRPC :5681</title><path d="M 1120 257.5 L 1540 282.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1191.4" y="231.0" width="267.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1325" y="252" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Starts workflows and polls tasks</text><text x="1325" y="272" class="edge-protocol" text-anchor="middle">via Temporal gRPC :5681</text></g><g data-relationship-id="r-fastapi-nodejs"><title>Starts on demand and executes JavaScript · via HTTP :5682</title><path d="M 1120 257.5 L 1485 257 L 1485 537 L 1540 537.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1390.0 537.0 L 1300 591" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1136.0" y="567.0" width="328.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1300" y="588" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">Starts on demand and executes JavaScript</text><text x="1300" y="608" class="edge-protocol" text-anchor="middle">via HTTP :5682</text></g><g data-relationship-id="r-fastapi-whatsapp"><title>Starts on demand and sends commands · via RPC :5683</title><path d="M 1120 257.5 L 1460 257 L 1460 797 L 1540 797.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1395.0 797.0 L 1575 905" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1430.0" y="881.0" width="290.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1575" y="902" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">Starts on demand and sends commands</text><text x="1575" y="922" class="edge-protocol" text-anchor="middle">via RPC :5683</text></g><g data-relationship-id="r-fastapi-spa"><title>Serves production fallback · via StaticFiles / HTML</title><path d="M 970.0 325 L 970 605 L 1305 605 L 1305.0 655" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1140.0 605.0 L 960 605" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="849.2" y="581.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="960" y="602" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">Serves production fallback</text><text x="960" y="622" class="edge-protocol" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">via StaticFiles / HTML</text></g><g data-component-id="browser-spa"><title>Browser SPA</title><rect x="70" y="215" width="290" height="115" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="70" y="215" width="290" height="7" rx="4" fill="#f1fa8c"/><text x="88" y="241" class="type-label">CLIENT</text><text x="88" y="267" class="node-label">Browser SPA</text><text x="88" y="293" class="node-detail">React workflow workspace</text></g><g data-component-id="opencompany-cli"><title>OpenCompany CLI</title><rect x="70" y="470" width="290" height="115" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="70" y="470" width="290" height="7" rx="4" fill="#f1fa8c"/><text x="88" y="496" class="type-label">CLIENT</text><text x="88" y="522" class="node-label">OpenCompany CLI</text><text x="88" y="548" class="node-detail" textLength="254.0" lengthAdjust="spacingAndGlyphs">Typer launcher and agent client</text></g><g data-component-id="webhook-senders"><title>Webhook senders</title><rect x="70" y="735" width="290" height="115" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="70" y="735" width="290" height="7" rx="4" fill="#ff79c6"/><text x="88" y="761" class="type-label">EXTERNAL</text><text x="88" y="787" class="node-label">Webhook senders</text><text x="88" y="813" class="node-detail">Provider callbacks</text></g><g data-component-id="vite-dev"><title>Vite development server</title><rect x="455" y="190" width="280" height="135" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="455" y="190" width="280" height="7" rx="4" fill="#8be9fd"/><text x="473" y="216" class="type-label">CONTAINER</text><text x="473" y="242" class="node-label">Vite development</text><text x="473" y="264" class="node-label">server</text><text x="473" y="290" class="node-detail">Port 5678 · development only</text></g><g data-component-id="fastapi-app"><title>FastAPI application</title><rect x="820" y="190" width="300" height="135" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="820" y="190" width="300" height="7" rx="4" fill="#bd93f9"/><text x="838" y="216" class="type-label">CONTAINER</text><text x="838" y="242" class="node-label">FastAPI application</text><text x="838" y="268" class="node-detail">5679 dev · 5678 production</text></g><g data-component-id="rest-surface"><title>Protected REST API</title><rect x="455" y="400" width="280" height="120" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="455" y="400" width="280" height="7" rx="4" fill="#8be9fd"/><text x="473" y="426" class="type-label">INTERFACE</text><text x="473" y="452" class="node-label">Protected REST API</text><text x="473" y="478" class="node-detail">Authenticated /api routes</text></g><g data-component-id="status-socket"><title>/ws/status</title><rect x="820" y="400" width="280" height="120" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="820" y="400" width="280" height="7" rx="4" fill="#8be9fd"/><text x="838" y="426" class="type-label">WEBSOCKET</text><text x="838" y="452" class="node-label">/ws/status</text><text x="838" y="478" class="node-detail">Cookie-derived user identity</text></g><g data-component-id="internal-socket"><title>/ws/internal</title><rect x="1165" y="400" width="280" height="120" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1165" y="400" width="280" height="7" rx="4" fill="#f1fa8c"/><text x="1183" y="426" class="type-label">WEBSOCKET</text><text x="1183" y="452" class="node-label">/ws/internal</text><text x="1183" y="478" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Local allowlist · payload identity</text></g><g data-component-id="mcp-surface"><title>/mcp/ide/mcp</title><rect x="455" y="655" width="280" height="120" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="455" y="655" width="280" height="7" rx="4" fill="#f1fa8c"/><text x="473" y="681" class="type-label">MCP ENDPOINT</text><text x="473" y="707" class="node-label">/mcp/ide/mcp</text><text x="473" y="733" class="node-detail">Per-batch bearer token</text></g><g data-component-id="webhook-ingress"><title>/webhook/*</title><rect x="820" y="655" width="280" height="120" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="820" y="655" width="280" height="7" rx="4" fill="#ff79c6"/><text x="838" y="681" class="type-label">HTTP INGRESS</text><text x="838" y="707" class="node-label">/webhook/*</text><text x="838" y="733" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Public route · provider verification</text></g><g data-component-id="production-spa"><title>Production SPA assets</title><rect x="1165" y="655" width="280" height="120" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1165" y="655" width="280" height="7" rx="4" fill="#8be9fd"/><text x="1183" y="681" class="type-label">STATIC CONTENT</text><text x="1183" y="707" class="node-label">Production SPA assets</text><text x="1183" y="733" class="node-detail">Served by FastAPI</text></g><g data-component-id="temporal-runtime"><title>Temporal server and worker</title><rect x="1540" y="210" width="310" height="145" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="210" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="236" class="type-label">DURABLE RUNTIME</text><text x="1558" y="262" class="node-label">Temporal server</text><text x="1558" y="284" class="node-label">and worker</text><text x="1558" y="310" class="node-detail">UI 5680 · gRPC 5681</text></g><g data-component-id="nodejs-sidecar"><title>Node.js executor</title><rect x="1540" y="475" width="310" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="475" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="501" class="type-label">LAZY SIDECAR</text><text x="1558" y="527" class="node-label">Node.js executor</text><text x="1558" y="553" class="node-detail">HTTP · port 5682</text></g><g data-component-id="whatsapp-sidecar"><title>WhatsApp RPC</title><rect x="1540" y="735" width="310" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1540" y="735" width="310" height="7" rx="4" fill="#ffb86c"/><text x="1558" y="761" class="type-label">LAZY SIDECAR</text><text x="1558" y="787" class="node-label">WhatsApp RPC</text><text x="1558" y="813" class="node-detail">RPC · port 5683</text></g><g data-callout-id="trust-rules"><rect x="535" y="795" width="835" height="155" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="551" y="825" class="callout-title">Trust rules</text><text x="551" y="851" class="callout-text">REST and /ws/status use authenticated server-owned identity.</text><text x="551" y="873" class="callout-text">/ws/internal is local-only, unauthenticated, and restricted to</text><text x="551" y="895" class="callout-text">execute_node, execute_ai_node, and ping.</text><text x="551" y="917" class="callout-text">/mcp/ide/mcp uses a short-lived per-batch Bearer token;</text><text x="551" y="939" class="callout-text">/webhook/* verifies provider signatures where configured.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/03-workflow-execution-routing.svg b/docs/diagrams/v2/light/03-workflow-execution-routing.svgnew file mode 100644index 00000000..0dd079c2--- /dev/null+++ b/docs/diagrams/v2/light/03-workflow-execution-routing.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="a9db68cb272c047f">+<title id="title">Workflow Execution Routing — light theme</title>+<desc id="desc">A directed execution flow covering direct single-node execution, the WorkflowService routing decision, Temporal, Redis-backed parallel, and sequential orchestration paths, plus the canonical NodeExecutor pipeline and status persistence. Sources: server/services/workflow.py; server/services/node_executor.py; server/services/execution/executor.py; server/services/temporal/executor.py; server/services/temporal/workflow.py; server/services/status_broadcaster.py; server/routers/workflow.py; server/routers/websocket.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Workflow Execution Routing</text>+<text x="72" y="91" class="subtitle">Single-node requests and whole-graph runs converge on the same plugin execution pipeline</text>+<g data-group-id="entry-zone"><rect x="45" y="150" width="300" height="790" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="65" y="182" class="group-label">ENTRY</text></g><g data-group-id="routing-zone"><rect x="385" y="150" width="775" height="790" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="405" y="182" class="group-label">GRAPH ORCHESTRATION</text></g><g data-group-id="node-pipeline-zone"><rect x="1200" y="150" width="675" height="790" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1220" y="182" class="group-label">NODEEXECUTOR PIPELINE</text></g><g data-relationship-id="r-single-pipeline"><title>Executes directly · via WorkflowService.execute_node</title><path d="M 315 312.5 L 360 312 L 360 120 L 1180 120 L 1180 257 L 1240 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 120.0 L 780 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="646.4" y="124.0" width="267.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="780" y="145.0" class="edge-label" text-anchor="middle">Executes directly</text><text x="780" y="165.0" class="edge-protocol" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">via WorkflowService.execute_node</text></g><g data-relationship-id="r-whole-routing"><title>Submits nodes, edges and identity · via WorkflowService.execute_workflow</title><path d="M 315 687.5 L 365 687 L 365 322 L 455 322.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="216.20000000000002" y="481.0" width="297.59999999999997" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="365" y="502" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">Submits nodes, edges and identity</text><text x="365" y="522" class="edge-protocol" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">via WorkflowService.execute_workflow</text></g><g data-relationship-id="r-routing-temporal"><title>Chooses when requested and wired · via Temporal</title><path d="M 755 322.5 L 820 267.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 235.0 L 1060 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="926.4" y="124.0" width="267.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1060" y="145.0" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">Chooses when requested and wired</text><text x="1060" y="165.0" class="edge-protocol" text-anchor="middle">via Temporal</text></g><g data-relationship-id="r-routing-parallel"><title>Else chooses when parallel and Redis enabled · via in-process + Redis</title><path d="M 755 322.5 L 785 322 L 785 492 L 820 492.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 405.0 L 790 621" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="610.8" y="597.0" width="358.4" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="790" y="618" class="edge-label" text-anchor="middle" textLength="340.4" lengthAdjust="spacingAndGlyphs">Else chooses when parallel and Redis enabled</text><text x="790" y="638" class="edge-protocol" text-anchor="middle">via in-process + Redis</text></g><g data-relationship-id="r-routing-sequential"><title>Otherwise falls back · via in-process</title><path d="M 755 322.5 L 785 322 L 785 742 L 820 742.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 790.0 640.0 L 700 694" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="612.0" y="670.0" width="176.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="700" y="691" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">Otherwise falls back</text><text x="700" y="711" class="edge-protocol" text-anchor="middle">via in-process</text></g><g data-relationship-id="r-temporal-node"><title>Schedules node activities · via Temporal task queue</title><path d="M 1105 267.5 L 1240 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 225.0 L 1170 387" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1063.0" y="363.0" width="214.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1170" y="384" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">Schedules node activities</text><text x="1170" y="404" class="edge-protocol" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">via Temporal task queue</text></g><g data-relationship-id="r-parallel-node"><title>Calls node adapter with retries · via async callback</title><path d="M 1105 492.5 L 1170 492 L 1170 257 L 1240 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 385.0 L 900 385" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="770.2" y="361.0" width="259.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="900" y="382" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">Calls node adapter with retries</text><text x="900" y="402" class="edge-protocol" text-anchor="middle">via async callback</text></g><g data-relationship-id="r-sequential-node"><title>Calls each ready node · via await</title><path d="M 1105 742.5 L 1170 742 L 1170 257 L 1240 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 650.0 L 1260 650" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1168.2" y="626.0" width="183.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1260" y="647" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">Calls each ready node</text><text x="1260" y="667" class="edge-protocol" text-anchor="middle">via await</text></g><g data-relationship-id="r-prepare-resolve"><title>Passes validated parameters · via Python dict</title><path d="M 1525 257.5 L 1560 257.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1542.0 347.0 L 1542 401" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1427.4" y="377.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1542" y="398" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Passes validated parameters</text><text x="1542" y="418" class="edge-protocol" text-anchor="middle">via Python dict</text></g><g data-relationship-id="r-resolve-dispatch"><title>Builds handler context · via NodeContext</title><path d="M 1697.5 320 L 1697 380 L 1382 380 L 1382.5 455" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1540.0 380.0 L 1810 380" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1714.4" y="356.0" width="191.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1810" y="377" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Builds handler context</text><text x="1810" y="397" class="edge-protocol" text-anchor="middle">via NodeContext</text></g><g data-relationship-id="r-dispatch-result"><title>Returns standardized result · via ExecutionResult</title><path d="M 1525 527.5 L 1560 527.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1427.4" y="641.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1542" y="662" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Returns standardized result</text><text x="1542" y="682" class="edge-protocol" text-anchor="middle">via ExecutionResult</text></g><g data-relationship-id="r-result-store"><title>Persists successful outputs · via database callback</title><path d="M 1697.5 600 L 1697 680 L 1382 680 L 1382.5 745" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1540.0 680.0 L 1793.4 680" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1678.8000000000002" y="656.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1793.4" y="677" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Persists successful outputs</text><text x="1793.4" y="697" class="edge-protocol" text-anchor="middle">via database callback</text></g><g data-relationship-id="r-store-broadcast"><title>Publishes execution state · via WebSocket broadcast</title><path d="M 1525 807.5 L 1560 807.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1435.0" y="901.0" width="214.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1542" y="922" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">Publishes execution state</text><text x="1542" y="942" class="edge-protocol" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">via WebSocket broadcast</text></g><g data-component-id="single-node-request"><title>Single-node request</title><rect x="75" y="250" width="240" height="125" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="75" y="250" width="240" height="7" rx="4" fill="#8be9fd"/><text x="93" y="276" class="type-label">ENTRY POINT</text><text x="93" y="302" class="node-label" textLength="204.0" lengthAdjust="spacingAndGlyphs">Single-node request</text><text x="93" y="328" class="node-detail" textLength="204.0" lengthAdjust="spacingAndGlyphs">WebSocket or internal REST</text></g><g data-component-id="whole-workflow-request"><title>Whole-workflow run</title><rect x="75" y="625" width="240" height="125" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="75" y="625" width="240" height="7" rx="4" fill="#8be9fd"/><text x="93" y="651" class="type-label">ENTRY POINT</text><text x="93" y="677" class="node-label">Whole-workflow run</text><text x="93" y="703" class="node-detail">Interactive or deployed</text></g><g data-component-id="routing-decision"><title>WorkflowService routing</title><rect x="455" y="250" width="300" height="145" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="455" y="250" width="300" height="7" rx="4" fill="#ffb86c"/><text x="473" y="276" class="type-label">DECISION</text><text x="473" y="302" class="node-label">WorkflowService routing</text><text x="473" y="328" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">Temporal → parallel → sequential</text></g><g data-component-id="temporal-branch"><title>Temporal branch</title><rect x="820" y="205" width="285" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="205" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="231" class="type-label">DURABLE ORCHESTRATOR</text><text x="838" y="257" class="node-label">Temporal branch</text><text x="838" y="283" class="node-detail">Temporal executor is wired</text></g><g data-component-id="redis-parallel-branch"><title>Redis-parallel branch</title><rect x="820" y="420" width="285" height="145" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="420" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="446" class="type-label">GRAPH ORCHESTRATOR</text><text x="838" y="472" class="node-label">Redis-parallel</text><text x="838" y="494" class="node-label">branch</text><text x="838" y="520" class="node-detail">WorkflowExecutor</text></g><g data-component-id="sequential-branch"><title>Sequential fallback</title><rect x="820" y="680" width="285" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="820" y="680" width="285" height="7" rx="4" fill="#ffb86c"/><text x="838" y="706" class="type-label">GRAPH ORCHESTRATOR</text><text x="838" y="732" class="node-label">Sequential fallback</text><text x="838" y="758" class="node-detail">Topological loop</text></g><g data-component-id="parameter-preparation"><title>Prepare parameters</title><rect x="1240" y="195" width="285" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1240" y="195" width="285" height="7" rx="4" fill="#ffb86c"/><text x="1258" y="221" class="type-label">PIPELINE STAGE</text><text x="1258" y="247" class="node-label">Prepare parameters</text><text x="1258" y="273" class="node-detail" textLength="249.0" lengthAdjust="spacingAndGlyphs">DB defaults + request overrides</text><text x="1258" y="293" class="node-detail" textLength="249.0" lengthAdjust="spacingAndGlyphs">Pydantic Params + credentials</text></g><g data-component-id="template-resolution"><title>Resolve templates</title><rect x="1560" y="195" width="275" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1560" y="195" width="275" height="7" rx="4" fill="#ffb86c"/><text x="1578" y="221" class="type-label">PIPELINE STAGE</text><text x="1578" y="247" class="node-label">Resolve templates</text><text x="1578" y="273" class="node-detail">Graph and upstream outputs</text></g><g data-component-id="plugin-dispatch"><title>Dispatch plugin operation</title><rect x="1240" y="455" width="285" height="145" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1240" y="455" width="285" height="7" rx="4" fill="#50fa7b"/><text x="1258" y="481" class="type-label">PIPELINE STAGE</text><text x="1258" y="507" class="node-label">Dispatch plugin</text><text x="1258" y="529" class="node-label">operation</text><text x="1258" y="555" class="node-detail">Node registry handler</text></g><g data-component-id="validated-result"><title>Validated execution result</title><rect x="1560" y="455" width="275" height="145" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1560" y="455" width="275" height="7" rx="4" fill="#50fa7b"/><text x="1578" y="481" class="type-label">PIPELINE STAGE</text><text x="1578" y="507" class="node-label">Validated execution</text><text x="1578" y="529" class="node-label">result</text><text x="1578" y="555" class="node-detail">Success or typed error</text></g><g data-component-id="output-store"><title>Output store</title><rect x="1240" y="745" width="285" height="125" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1240" y="745" width="285" height="7" rx="4" fill="#ff79c6"/><text x="1258" y="771" class="type-label">PERSISTENCE</text><text x="1258" y="797" class="node-label">Output store</text><text x="1258" y="823" class="node-detail">output_main / top / 0</text></g><g data-component-id="status-broadcast"><title>Status broadcasts</title><rect x="1560" y="745" width="275" height="125" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1560" y="745" width="275" height="7" rx="4" fill="#50fa7b"/><text x="1578" y="771" class="type-label">OBSERVABLE RESULT</text><text x="1578" y="797" class="node-label">Status broadcasts</text><text x="1578" y="823" class="node-detail" textLength="239.0" lengthAdjust="spacingAndGlyphs">Per-workflow WebSocket stream</text></g><g data-callout-id="routing-invariant"><rect x="455" y="830" width="650" height="110" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="471" y="860" class="callout-title">Routing invariant</text><text x="471" y="886" class="callout-text">Temporal requested but not wired logs an error, then falls through.</text><text x="471" y="908" class="callout-text">The next eligible path is Redis-parallel or sequential.</text><text x="471" y="930" class="callout-text">Every branch invokes WorkflowService.execute_node → NodeExecutor.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/04-durable-deployment-events.svg b/docs/diagrams/v2/light/04-durable-deployment-events.svgnew file mode 100644index 00000000..8f192284--- /dev/null+++ b/docs/diagrams/v2/light/04-durable-deployment-events.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="8df81da298fbe73d">+<title id="title">Durable Deployment and Events — light theme</title>+<desc id="desc">A deployment lifecycle and event-flow view showing Start/Pause/Resume/Reset controls, immutable per-generation graph snapshots, the long-lived WorkflowControlWorkflow, push/poll/cron trigger paths, CloudEvents dispatch, and child graph execution. Sources: server/services/deployment/handlers.py; server/services/deployment/control.py; server/services/deployment/triggers.py; server/services/temporal/workflow_control_workflow.py; server/services/events/envelope.py; server/services/events/dispatch.py; server/services/temporal/schedules.py; server/nodes/scheduler/cron_scheduler/_workflow.py; server/services/workflow.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Durable Deployment and Events</text>+<text x="72" y="91" class="subtitle">Generation snapshots, trigger admission, controller signals and child workflow runs</text>+<g data-group-id="control-plane"><rect x="45" y="145" width="610" height="815" rx="18" fill="#fafbfc" stroke="#f1fa8c" stroke-width="2"/><text x="65" y="177" class="group-label">DEPLOYMENT CONTROL PLANE</text></g><g data-group-id="trigger-plane"><rect x="690" y="145" width="710" height="815" rx="18" fill="#fafbfc" stroke="#ff79c6" stroke-width="2"/><text x="710" y="177" class="group-label">TRIGGER AND EVENT PLANE</text></g><g data-group-id="execution-plane"><rect x="1435" y="145" width="440" height="815" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1455" y="177" class="group-label">DURABLE EXECUTION</text></g><g data-relationship-id="r-controls-service"><title>Requests lifecycle transition · via WebSocket command</title><path d="M 340 275.0 L 370 275.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="227.8" y="366.0" width="244.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="350" y="387" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">Requests lifecycle transition</text><text x="350" y="407" class="edge-protocol" text-anchor="middle">via WebSocket command</text></g><g data-relationship-id="r-service-snapshot"><title>Allocates or CAS-updates · via workflow database</title><path d="M 495.0 345 L 495 405 L 210 405 L 210.0 485" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 350.0 405.0 L 115.19999999999999 405" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="12.0" y="381.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="115.19999999999999" y="402" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Allocates or CAS-updates</text><text x="115.19999999999999" y="422" class="edge-protocol" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">via workflow database</text></g><g data-relationship-id="r-snapshot-controller"><title>Starts with immutable graph snapshot · via Temporal gRPC</title><path d="M 340 562.5 L 370 562.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="201.20000000000002" y="676.0" width="297.59999999999997" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="350" y="697" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">Starts with immutable graph snapshot</text><text x="350" y="717" class="edge-protocol" text-anchor="middle">via Temporal gRPC</text></g><g data-relationship-id="r-controls-controller"><title>Updates pause/resume or signals reset · via Temporal Update / Signal</title><path d="M 495.0 345 L 495.0 485" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 495.0 405.0 L 675 405" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="522.4" y="381.0" width="305.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="675" y="402" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">Updates pause/resume or signals reset</text><text x="675" y="422" class="edge-protocol" text-anchor="middle">via Temporal Update / Signal</text></g><g data-relationship-id="r-service-local-state"><title>Projects admission state · via in-process</title><path d="M 495.0 345 L 640 415 L 640 735 L 355 735 L 355.0 775" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 735.0 L 640 735" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="536.8" y="711.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="640" y="732" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Projects admission state</text><text x="640" y="752" class="edge-protocol" text-anchor="middle">via in-process</text></g><g data-relationship-id="r-push-event"><title>Normalizes inbound event · via CloudEvents 1.0</title><path d="M 825.0 320 L 855.0 455" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 825.0 385.0 L 1005 385" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="901.8" y="361.0" width="206.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1005" y="382" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">Normalizes inbound event</text><text x="1005" y="402" class="edge-protocol" text-anchor="middle">via CloudEvents 1.0</text></g><g data-relationship-id="r-event-dispatch"><title>Emits envelope · via async dispatch</title><path d="M 980 520.0 L 1040 520.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="929.6" y="621.0" width="160.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1010" y="642" class="edge-label" text-anchor="middle">Emits envelope</text><text x="1010" y="662" class="edge-protocol" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">via async dispatch</text></g><g data-relationship-id="r-dispatch-controller"><title>Signals matching controller · via Visibility + on_event</title><path d="M 1040 520.0 L 1010 520 L 675 520 L 620 562.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 825.0 520.0 L 735 682" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="620.4" y="658.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="735" y="679" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Signals matching controller</text><text x="735" y="699" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Visibility + on_event</text></g><g data-relationship-id="r-poll-controller"><title>Registers durable poll loop · via register_trigger signal</title><path d="M 1045.0 320 L 1045 365 L 675 365 L 675 562 L 620 562.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 835.0 365.0 L 1285 365" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1170.4" y="341.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1285" y="362" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Registers durable poll loop</text><text x="1285" y="382" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via register_trigger signal</text></g><g data-relationship-id="r-cron-action"><title>Fires scheduled action · via Temporal Schedule</title><path d="M 1360 262.5 L 1415 262 L 1415 642 L 1480 642.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1415.0 465.0 L 1415 519" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1319.4" y="495.0" width="191.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1415" y="516" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">Fires scheduled action</text><text x="1415" y="536" class="edge-protocol" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">via Temporal Schedule</text></g><g data-relationship-id="r-registration-controller"><title>Registers definitions and pause state · via Temporal Signal</title><path d="M 875 805.0 L 675 805 L 675 562 L 620 562.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 675.0 720.0 L 675 828" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="522.4" y="804.0" width="305.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="675" y="825" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">Registers definitions and pause state</text><text x="675" y="845" class="edge-protocol" text-anchor="middle">via Temporal Signal</text></g><g data-relationship-id="r-controller-child"><title>Spawns admitted event or poll run · via Temporal child workflow</title><path d="M 620 562.5 L 1410 562 L 1410 367 L 1480 367.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1225.0 367.0 L 1315 421" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1177.6" y="397.0" width="274.79999999999995" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1315" y="418" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">Spawns admitted event or poll run</text><text x="1315" y="438" class="edge-protocol" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">via Temporal child workflow</text></g><g data-relationship-id="r-cron-child"><title>Launches snapshotted graph · via Temporal child workflow</title><path d="M 1655.0 570 L 1655.0 440" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1540.4" y="481.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1655" y="502" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Launches snapshotted graph</text><text x="1655" y="522" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Temporal child workflow</text></g><g data-relationship-id="r-child-status"><title>Persists and broadcasts run state · via database + WebSocket</title><path d="M 1655.0 440 L 1655.0 810" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1517.6" y="736.0" width="274.79999999999995" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1655" y="757" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">Persists and broadcasts run state</text><text x="1655" y="777" class="edge-protocol" text-anchor="middle">via database + WebSocket</text></g><g data-relationship-id="r-cron-status"><title>Reports scheduled run state · via Temporal + WebSocket</title><path d="M 1655.0 715 L 1655.0 810" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1775.0 760.0 L 1775 966.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1660.4" y="942.0" width="229.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1775" y="963.0" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">Reports scheduled run state</text><text x="1775" y="983.0" class="edge-protocol" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">via Temporal + WebSocket</text></g><g data-component-id="lifecycle-controls"><title>Start · Pause · Resume · Reset</title><rect x="80" y="205" width="260" height="140" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="80" y="205" width="260" height="7" rx="4" fill="#f1fa8c"/><text x="98" y="231" class="type-label">OPERATOR CONTROLS</text><text x="98" y="257" class="node-label">Start · Pause</text><text x="98" y="279" class="node-label">Resume · Reset</text><text x="98" y="305" class="node-detail">Revision-aware commands</text></g><g data-component-id="workflow-control-service"><title>WorkflowControlService</title><rect x="370" y="205" width="250" height="140" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="370" y="205" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="388" y="231" class="type-label">CONTROL SERVICE</text><text x="388" y="257" class="node-label" textLength="214.0" lengthAdjust="spacingAndGlyphs">WorkflowControlService</text><text x="388" y="283" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">CAS lifecycle transitions</text></g><g data-component-id="generation-snapshot"><title>Generation control row</title><rect x="80" y="485" width="260" height="155" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="80" y="485" width="260" height="7" rx="4" fill="#ff79c6"/><text x="98" y="511" class="type-label">DURABLE DATA</text><text x="98" y="537" class="node-label">Generation control</text><text x="98" y="559" class="node-label">row</text><text x="98" y="585" class="node-detail">graph_snapshot + owner_id</text><text x="98" y="605" class="node-detail">generation + revision</text></g><g data-component-id="controller"><title>WorkflowControlWorkflow</title><rect x="370" y="485" width="250" height="155" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="370" y="485" width="250" height="7" rx="4" fill="#ffb86c"/><text x="388" y="511" class="type-label">LONG-LIVED WORKFLOW</text><text x="388" y="537" class="node-label">WorkflowControl</text><text x="388" y="559" class="node-label">Workflow</text><text x="388" y="585" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Signals, poll loops, event queue</text><text x="388" y="605" class="node-detail">continue-as-new</text></g><g data-component-id="local-runtime-state"><title>Local admission state</title><rect x="215" y="775" width="280" height="120" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="215" y="775" width="280" height="7" rx="4" fill="#ffb86c"/><text x="233" y="801" class="type-label">PROCESS PROJECTION</text><text x="233" y="827" class="node-label">Local admission state</text><text x="233" y="853" class="node-detail">running / paused projection</text></g><g data-component-id="push-trigger"><title>Push trigger</title><rect x="730" y="205" width="190" height="115" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="730" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="748" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="748" y="257" class="node-label">Push trigger</text><text x="748" y="283" class="node-detail" textLength="154.0" lengthAdjust="spacingAndGlyphs">Webhook or platform event</text></g><g data-component-id="poll-trigger"><title>Poll trigger</title><rect x="950" y="205" width="190" height="115" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="950" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="968" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="968" y="257" class="node-label">Poll trigger</text><text x="968" y="283" class="node-detail" textLength="154.0" lengthAdjust="spacingAndGlyphs">Controller timer + activity</text></g><g data-component-id="cron-trigger"><title>Cron trigger</title><rect x="1170" y="205" width="190" height="115" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1170" y="205" width="190" height="7" rx="4" fill="#ff79c6"/><text x="1188" y="231" class="type-label" textLength="154.0" lengthAdjust="spacingAndGlyphs">TRIGGER DEFINITION</text><text x="1188" y="257" class="node-label">Cron trigger</text><text x="1188" y="283" class="node-detail">Temporal Schedule</text></g><g data-component-id="cloudevent"><title>WorkflowEvent</title><rect x="730" y="455" width="250" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="730" y="455" width="250" height="7" rx="4" fill="#ff79c6"/><text x="748" y="481" class="type-label">CLOUDEVENTS 1.0</text><text x="748" y="507" class="node-label">WorkflowEvent</text><text x="748" y="533" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">id · source · type · subject</text></g><g data-component-id="event-dispatch"><title>dispatch.emit</title><rect x="1040" y="455" width="250" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1040" y="455" width="250" height="7" rx="4" fill="#ff79c6"/><text x="1058" y="481" class="type-label">EVENT ROUTER</text><text x="1058" y="507" class="node-label">dispatch.emit</text><text x="1058" y="533" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Visibility query + signal</text></g><g data-component-id="trigger-registration"><title>Trigger registration</title><rect x="875" y="745" width="300" height="120" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="875" y="745" width="300" height="7" rx="4" fill="#ff79c6"/><text x="893" y="771" class="type-label">CONTROL SIGNAL</text><text x="893" y="797" class="node-label">Trigger registration</text><text x="893" y="823" class="node-detail">register_trigger + pause flags</text></g><g data-component-id="child-graph-workflow"><title>Child graph workflow</title><rect x="1480" y="295" width="350" height="145" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1480" y="295" width="350" height="7" rx="4" fill="#ffb86c"/><text x="1498" y="321" class="type-label">TEMPORAL WORKFLOW</text><text x="1498" y="347" class="node-label">Child graph workflow</text><text x="1498" y="373" class="node-detail">Snapshotted nodes and edges</text></g><g data-component-id="cron-action-workflow"><title>Cron action workflow</title><rect x="1480" y="570" width="350" height="145" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1480" y="570" width="350" height="7" rx="4" fill="#ffb86c"/><text x="1498" y="596" class="type-label">TEMPORAL WORKFLOW</text><text x="1498" y="622" class="node-label">Cron action workflow</text><text x="1498" y="648" class="node-detail">Schedule-owned graph launch</text></g><g data-component-id="execution-status"><title>Run status and events</title><rect x="1515" y="810" width="280" height="115" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1515" y="810" width="280" height="7" rx="4" fill="#50fa7b"/><text x="1533" y="836" class="type-label">OBSERVABLE RESULT</text><text x="1533" y="862" class="node-label">Run status and events</text><text x="1533" y="888" class="node-detail">Database + WebSocket</text></g><g data-callout-id="legacy-fallback"><rect x="735" y="885" width="630" height="65" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="751" y="915" class="callout-title">Optional legacy path</text><text x="751" y="941" class="callout-text">Local DeploymentManager / event-waiter remain optional fallbacks.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/05-plugin-agent-team-composition.svg b/docs/diagrams/v2/light/05-plugin-agent-team-composition.svgnew file mode 100644index 00000000..56558322--- /dev/null+++ b/docs/diagrams/v2/light/05-plugin-agent-team-composition.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="8152ad164c866305">+<title id="title">Plugin → Agent → Team Composition — light theme</title>+<desc id="desc">A source-backed composition view showing how BaseNode plugins branch into standalone chat-model and agent plugins, how agents assemble context, skills, and tools before entering the shared LLM runtime, and how team leads turn teammate edges into durable delegation surfaces. Sources: server/services/plugin/base.py; server/nodes/model/_base.py; server/nodes/agent/_specialized.py; server/nodes/agent/_handles.py; server/services/plugin/edge_walker.py; server/services/llm/unifier.py; server/services/agent_team.py; server/models/database.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Plugin → Agent → Team Composition</text>+<text x="72" y="91" class="subtitle">Self-registering node plugins compose provider-backed agents, edge-connected capabilities, and execution-scoped teams</text>+<g data-group-id="plugin-layer"><rect x="50" y="125" width="500" height="830" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="70" y="157" class="group-label">PLUGIN & MODEL LAYER</text></g><g data-group-id="agent-layer"><rect x="590" y="125" width="700" height="830" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="610" y="157" class="group-label">AGENT COMPOSITION</text></g><g data-group-id="team-layer"><rect x="1330" y="125" width="540" height="830" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1350" y="157" class="group-label">TEAM COMPOSITION</text></g><g data-relationship-id="r-base-model"><title>specializes as model plugin</title><path d="M 300.0 325 L 300.0 400" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="185.4" y="350.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="300" y="368" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">specializes as model plugin</text></g><g data-relationship-id="r-base-agent"><title>specializes as agent plugin</title><path d="M 300.0 325 L 300 360 L 610 360 L 610 265 L 640 265.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 475.0 360.0 L 475 144" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="360.4" y="129.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="475" y="147" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">specializes as agent plugin</text></g><g data-relationship-id="r-model-unifier"><title>dispatches chat · via provider + model</title><path d="M 300.0 550 L 300.0 730" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="212.0" y="616.0" width="176.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="300" y="637" class="edge-label" text-anchor="middle">dispatches chat</text><text x="300" y="657" class="edge-protocol" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">via provider + model</text></g><g data-relationship-id="r-agent-prepare"><title>prepares execution payload</title><path d="M 940.0 345 L 940 385 L 940 680 L 940.0 720" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="829.2" y="635.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="940" y="653" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">prepares execution payload</text></g><g data-relationship-id="r-context-prepare"><title>adds context descriptor</title><path d="M 727.5 575 L 727 620 L 620 620 L 620 805 L 650 805.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="520.6" y="650.0" width="198.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="620" y="668" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">adds context descriptor</text></g><g data-relationship-id="r-skills-prepare"><title>injects enabled skill content</title><path d="M 937.5 575 L 937 630 L 940.0 720" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="814.8" y="605.0" width="244.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="937" y="623" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">injects enabled skill content</text></g><g data-relationship-id="r-tools-prepare"><title>builds tool surface</title><path d="M 1150.0 575 L 1150 620 L 1260 620 L 1260 805 L 1230 805.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1175.8" y="650.0" width="168.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1260" y="668" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">builds tool surface</text></g><g data-relationship-id="r-prepare-unifier"><title>routes selected provider and model</title><path d="M 940.0 890 L 940 920 L 300 920 L 300.0 890" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="478.8" y="905.0" width="282.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="620" y="923" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">routes selected provider and model</text></g><g data-relationship-id="r-teammates-lead"><title>connect via input-teammates</title><path d="M 1600.0 430 L 1600.0 335" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1485.4" y="367.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1600" y="385" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">connect via input-teammates</text></g><g data-relationship-id="r-lead-runtime"><title>executes through shared agent runtime</title><path d="M 1380 260.0 L 1320 260 L 1320 650 L 1260 650 L 1260 805 L 1230 805.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1195.0 650.0 L 1195 380" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1042.4" y="365.0" width="305.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1195" y="383" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">executes through shared agent runtime</text></g><g data-relationship-id="r-lead-manager"><title>auto-binds intrinsic tool</title><path d="M 1600.0 335 L 1600 650 L 1475 650 L 1475.0 710" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1408.0" y="635.0" width="214.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1515" y="653" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">auto-binds intrinsic tool</text></g><g data-relationship-id="r-teammates-state"><title>registers execution members</title><path d="M 1600.0 580 L 1600 640 L 1715 640 L 1715.0 710" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1700.0 640.0 L 1790 640" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1675.4" y="625.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1790" y="643" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">registers execution members</text></g><g data-relationship-id="r-manager-state"><title>persists task lifecycle</title><path d="M 1475.0 880 L 1475 920 L 1715 920 L 1715.0 880" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1495.6" y="905.0" width="198.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1595" y="923" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">persists task lifecycle</text></g><g data-component-id="base-node"><title>BaseNode plugin contract</title><rect x="90" y="185" width="420" height="140" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="90" y="185" width="420" height="7" rx="4" fill="#bd93f9"/><text x="108" y="211" class="type-label">PLUGIN CONTRACT</text><text x="108" y="237" class="node-label">BaseNode plugin contract</text><text x="108" y="263" class="node-detail">Params · Output · handles · uiHints</text><text x="108" y="283" class="node-detail">Auto-registers subclasses on import</text></g><g data-component-id="model-plugins"><title>Chat-model plugins</title><rect x="90" y="400" width="420" height="150" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="400" width="420" height="7" rx="4" fill="#8be9fd"/><text x="108" y="426" class="type-label">MODEL PLUGIN</text><text x="108" y="452" class="node-label">Chat-model plugins</text><text x="108" y="478" class="node-detail">ChatModelBase provider subclasses</text><text x="108" y="498" class="node-detail">Standalone output-model nodes</text></g><g data-component-id="chat-unifier"><title>ChatUnifier</title><rect x="90" y="730" width="420" height="160" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="730" width="420" height="7" rx="4" fill="#8be9fd"/><text x="108" y="756" class="type-label">LLM FACADE</text><text x="108" y="782" class="node-label">ChatUnifier</text><text x="108" y="808" class="node-detail">Provider registry + native SDK adapters</text><text x="108" y="828" class="node-detail">Shared model and agent dispatch path</text></g><g data-component-id="agent-plugins"><title>Agent plugins</title><rect x="640" y="185" width="600" height="160" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="640" y="185" width="600" height="7" rx="4" fill="#bd93f9"/><text x="658" y="211" class="type-label">AGENT PLUGIN</text><text x="658" y="237" class="node-label">Agent plugins</text><text x="658" y="263" class="node-detail">provider · model · prompt · options</text><text x="658" y="283" class="node-detail">Base, specialized, CLI, and team-lead variants</text></g><g data-component-id="context-node"><title>Context</title><rect x="640" y="430" width="175" height="145" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="430" width="175" height="7" rx="4" fill="#ff79c6"/><text x="658" y="456" class="type-label" textLength="139.0" lengthAdjust="spacingAndGlyphs">CONNECTED CONFIG</text><text x="658" y="482" class="node-label">Context</text><text x="658" y="508" class="node-detail">input-context</text><text x="658" y="528" class="node-detail" textLength="139.0" lengthAdjust="spacingAndGlyphs">policy + thread reference</text></g><g data-component-id="skill-nodes"><title>Skills</title><rect x="850" y="430" width="175" height="145" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="850" y="430" width="175" height="7" rx="4" fill="#50fa7b"/><text x="868" y="456" class="type-label" textLength="139.0" lengthAdjust="spacingAndGlyphs">CONNECTED CAPABILITY</text><text x="868" y="482" class="node-label">Skills</text><text x="868" y="508" class="node-detail">input-skill</text><text x="868" y="528" class="node-detail" textLength="139.0" lengthAdjust="spacingAndGlyphs">direct or Master Skill</text></g><g data-component-id="tool-nodes"><title>Tools</title><rect x="1060" y="430" width="180" height="145" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1060" y="430" width="180" height="7" rx="4" fill="#50fa7b"/><text x="1078" y="456" class="type-label" textLength="144.0" lengthAdjust="spacingAndGlyphs">CONNECTED CAPABILITY</text><text x="1078" y="482" class="node-label">Tools</text><text x="1078" y="508" class="node-detail">input-tools</text><text x="1078" y="528" class="node-detail" textLength="144.0" lengthAdjust="spacingAndGlyphs">plugin tool schemas</text></g><g data-component-id="prepared-agent-call"><title>Prepared agent call</title><rect x="650" y="720" width="580" height="170" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="650" y="720" width="580" height="7" rx="4" fill="#ffb86c"/><text x="668" y="746" class="type-label">RUNTIME PAYLOAD</text><text x="668" y="772" class="node-label">Prepared agent call</text><text x="668" y="798" class="node-detail">Edge walk + task/prompt assembly</text><text x="668" y="818" class="node-detail">Provider-neutral tools and skill content</text></g><g data-component-id="team-lead"><title>Orchestrator / AI Employee</title><rect x="1380" y="185" width="440" height="150" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="185" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="211" class="type-label">TEAM-LEAD AGENT</text><text x="1398" y="237" class="node-label">Orchestrator /</text><text x="1398" y="259" class="node-label">AI Employee</text><text x="1398" y="285" class="node-detail">Same agent runtime</text><text x="1398" y="305" class="node-detail">Adds input-teammates handle</text></g><g data-component-id="teammates"><title>Connected teammate agents</title><rect x="1380" y="430" width="440" height="150" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="430" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="456" class="type-label">AGENT SET</text><text x="1398" y="482" class="node-label">Connected teammate</text><text x="1398" y="504" class="node-label">agents</text><text x="1398" y="530" class="node-detail">Specialized or custom aiAgent</text><text x="1398" y="550" class="node-detail">Stable delegate tool names</text></g><g data-component-id="task-manager"><title>Task Manager</title><rect x="1380" y="710" width="190" height="170" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1380" y="710" width="190" height="7" rx="4" fill="#50fa7b"/><text x="1398" y="736" class="type-label">INTRINSIC TOOL</text><text x="1398" y="762" class="node-label">Task Manager</text><text x="1398" y="788" class="node-detail">Auto-bound</text><text x="1398" y="808" class="node-detail">Lead-only control</text></g><g data-component-id="durable-team"><title>Durable team state</title><rect x="1610" y="710" width="210" height="170" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1610" y="710" width="210" height="7" rx="4" fill="#ff79c6"/><text x="1628" y="736" class="type-label">EXECUTION DATA</text><text x="1628" y="762" class="node-label">Durable team</text><text x="1628" y="784" class="node-label">state</text><text x="1628" y="810" class="node-detail">Members · tasks</text><text x="1628" y="830" class="node-detail">Attempts · messages</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/06-persistence-secret-plane.svg b/docs/diagrams/v2/light/06-persistence-secret-plane.svgnew file mode 100644index 00000000..25f47c53--- /dev/null+++ b/docs/diagrams/v2/light/06-persistence-secret-plane.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="4dd0e49b0c18cbb7">+<title id="title">Persistence & Secret Plane — light theme</title>+<desc id="desc">A two-plane architecture view separating ordinary workflow, execution, context, and team persistence from the credential path in which AuthService caches narrowly, CredentialsDatabase encrypts fields, and credentials.db stores only Fernet tokens plus derivation metadata. Sources: server/core/container.py; server/main.py; server/core/database.py; server/models/database.py; server/services/auth.py; server/core/credentials_database.py; server/core/encryption.py; server/services/plugin/credential.py; server/core/config.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Persistence & Secret Plane</text>+<text x="72" y="91" class="subtitle">Operational state lives in workflow.db; API keys and OAuth tokens cross a separate encrypted credential boundary</text>+<g data-group-id="state-plane"><rect x="50" y="125" width="750" height="830" rx="18" fill="#fafbfc" stroke="#ff79c6" stroke-width="2"/><text x="70" y="157" class="group-label">APPLICATION PERSISTENCE · workflow.db</text></g><g data-group-id="secret-plane"><rect x="840" y="125" width="1030" height="830" rx="18" fill="#fafbfc" stroke="#f1fa8c" stroke-width="2"/><text x="860" y="157" class="group-label">SECRET PLANE · credentials.db</text></g><g data-relationship-id="r-runtime-database"><title>persists operational state</title><path d="M 245.0 340 L 245 400 L 610 400 L 610.0 340" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="314.2" y="385.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="425" y="403" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">persists operational state</text></g><g data-relationship-id="r-database-workflow"><title>reads and writes SQLModel rows · via sqlite+aiosqlite</title><path d="M 610.0 340 L 610 450 L 445 450 L 445.0 540" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="399.0" y="426.0" width="252.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="525" y="447" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">reads and writes SQLModel rows</text><text x="525" y="467" class="edge-protocol" text-anchor="middle">via sqlite+aiosqlite</text></g><g data-relationship-id="r-plugin-auth"><title>requests secret resolution</title><path d="M 995.0 340 L 995 400 L 1295 400 L 1295.0 340" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1034.2" y="385.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1145" y="403" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">requests secret resolution</text></g><g data-relationship-id="r-auth-cache"><title>populates safe cache</title><path d="M 1420 265.0 L 1570 265.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1495.0 265.0 L 1495 157" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1407.0" y="142.0" width="176.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1495" y="160" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">populates safe cache</text></g><g data-relationship-id="r-auth-credentials"><title>save · retrieve · delete</title><path d="M 1295.0 340 L 1330.0 490" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1335.0 415.0 L 975 469" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="871.8" y="454.0" width="206.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="975" y="472" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">save · retrieve · delete</text></g><g data-relationship-id="r-key-encryption"><title>derives in-memory Fernet key</title><path d="M 995.0 660 L 995.0 750" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="876.6" y="695.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="995" y="713" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">derives in-memory Fernet key</text></g><g data-relationship-id="r-credentials-encryption"><title>calls encrypt / decrypt per field</title><path d="M 1330.0 670 L 1330 700 L 1190 700 L 1190 825 L 1120 825.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1142.6" y="685.0" width="274.79999999999995" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1280" y="703" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">calls encrypt / decrypt per field</text></g><g data-relationship-id="r-credentials-store"><title>stores ciphertext rows and salt · via SQLite</title><path d="M 1330.0 670 L 1330 690 L 1695 690 L 1695.0 710" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1515.0 690.0 L 1335 744" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1205.2" y="720.0" width="259.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1335" y="741" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">stores ciphertext rows and salt</text><text x="1335" y="761" class="edge-protocol" text-anchor="middle">via SQLite</text></g><g data-component-id="runtime-services"><title>Runtime services</title><rect x="100" y="190" width="290" height="150" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="100" y="190" width="290" height="7" rx="4" fill="#bd93f9"/><text x="118" y="216" class="type-label">APPLICATION CALLERS</text><text x="118" y="242" class="node-label">Runtime services</text><text x="118" y="268" class="node-detail" textLength="254.0" lengthAdjust="spacingAndGlyphs">Workflows · nodes · deployments</text><text x="118" y="288" class="node-detail">Context · teams · settings</text></g><g data-component-id="database-service"><title>Database</title><rect x="470" y="190" width="280" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="470" y="190" width="280" height="7" rx="4" fill="#ff79c6"/><text x="488" y="216" class="type-label">PERSISTENCE SERVICE</text><text x="488" y="242" class="node-label">Database</text><text x="488" y="268" class="node-detail">Async SQLModel / SQLite</text><text x="488" y="288" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">One operational access surface</text></g><g data-component-id="workflow-db"><title>workflow.db</title><rect x="280" y="540" width="330" height="200" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="280" y="540" width="330" height="7" rx="4" fill="#ff79c6"/><text x="298" y="566" class="type-label">SQLITE DATA STORE</text><text x="298" y="592" class="node-label">workflow.db</text><text x="298" y="618" class="node-detail">Workflows · node params · outputs</text><text x="298" y="638" class="node-detail">Executions · context · teams</text><text x="298" y="658" class="node-detail">No encrypted credential tables</text></g><g data-component-id="credential-callers"><title>Plugin credentials</title><rect x="870" y="190" width="250" height="150" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="870" y="190" width="250" height="7" rx="4" fill="#bd93f9"/><text x="888" y="216" class="type-label">SECRET CONSUMERS</text><text x="888" y="242" class="node-label">Plugin credentials</text><text x="888" y="268" class="node-detail">Credential.resolve</text><text x="888" y="288" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Connection / provider clients</text></g><g data-component-id="auth-service"><title>AuthService</title><rect x="1170" y="190" width="250" height="150" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1170" y="190" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="1188" y="216" class="type-label">SECRET FACADE</text><text x="1188" y="242" class="node-label">AuthService</text><text x="1188" y="268" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">Only service-level credential route</text><text x="1188" y="288" class="node-detail">Store · resolve · remove</text></g><g data-component-id="credential-caches"><title>Process caches</title><rect x="1570" y="190" width="250" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1570" y="190" width="250" height="7" rx="4" fill="#ffb86c"/><text x="1588" y="216" class="type-label">BOUNDED SECRET CACHE</text><text x="1588" y="242" class="node-label">Process caches</text><text x="1588" y="268" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">API keys + model metadata</text><text x="1588" y="288" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">OAuth access/display fields only</text></g><g data-component-id="credentials-database"><title>CredentialsDatabase</title><rect x="1170" y="490" width="320" height="180" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1170" y="490" width="320" height="7" rx="4" fill="#f1fa8c"/><text x="1188" y="516" class="type-label">ENCRYPTED PERSISTENCE</text><text x="1188" y="542" class="node-label">CredentialsDatabase</text><text x="1188" y="568" class="node-detail">EncryptedAPIKey</text><text x="1188" y="588" class="node-detail">EncryptedOAuthToken</text><text x="1188" y="608" class="node-detail">credentials_metadata</text></g><g data-component-id="encryption-password"><title>API_KEY_ENCRYPTION_KEY</title><rect x="870" y="510" width="250" height="150" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="870" y="510" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="888" y="536" class="type-label">SERVER CONFIGURATION</text><text x="888" y="562" class="node-label">API_KEY_</text><text x="888" y="584" class="node-label">ENCRYPTION_KEY</text><text x="888" y="610" class="node-detail">Minimum 32 characters</text><text x="888" y="630" class="node-detail">Loaded at startup</text></g><g data-component-id="encryption-service"><title>EncryptionService</title><rect x="870" y="750" width="250" height="150" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="870" y="750" width="250" height="7" rx="4" fill="#f1fa8c"/><text x="888" y="776" class="type-label" textLength="214.0" lengthAdjust="spacingAndGlyphs">CRYPTOGRAPHIC BOUNDARY</text><text x="888" y="802" class="node-label">EncryptionService</text><text x="888" y="828" class="node-detail">PBKDF2-SHA256 · 600,000</text><text x="888" y="848" class="node-detail">Fernet encrypt / decrypt</text></g><g data-component-id="credentials-db"><title>credentials.db</title><rect x="1560" y="710" width="270" height="190" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1560" y="710" width="270" height="7" rx="4" fill="#ff79c6"/><text x="1578" y="736" class="type-label">ENCRYPTED SQLITE</text><text x="1578" y="762" class="node-label">credentials.db</text><text x="1578" y="788" class="node-detail">Ciphertext fields only</text><text x="1578" y="808" class="node-detail">32-byte salt in metadata</text><text x="1578" y="828" class="node-detail">Separate from workflow.db</text></g><g data-callout-id="state-boundary-note"><rect x="100" y="800" width="650" height="110" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="116" y="830" class="callout-title">Blast-radius boundary</text><text x="116" y="856" class="callout-text">A workflow.db dump carries operational state,</text><text x="116" y="878" class="callout-text">but never the encrypted API-key or OAuth tables.</text></g><g data-callout-id="refresh-token-note"><rect x="1525" y="395" width="305" height="115" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="1541" y="425" class="callout-title">Refresh-token rule</text><text x="1541" y="451" class="callout-text" textLength="273.0" lengthAdjust="spacingAndGlyphs">Refresh tokens are never cached.</text><text x="1541" y="473" class="callout-text">AuthService reads them from</text><text x="1541" y="495" class="callout-text">credentials.db for every use.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/07-workspace-anatomy.svg b/docs/diagrams/v2/light/07-workspace-anatomy.svgnew file mode 100644index 00000000..36e3bcb5--- /dev/null+++ b/docs/diagrams/v2/light/07-workspace-anatomy.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="d94e6e84070c5188">+<title id="title">Workspace Anatomy — light theme</title>+<desc id="desc">A source-backed anatomy of per-workflow workspaces: the database-backed id-to-slug resolver selects a DATA_DIR-rooted directory, contained consumers read and write artifacts through traversal-safe helpers, and CLI agents receive the workspace for worktrees and per-workflow skill discovery. Sources: server/core/paths.py; server/services/workspace_locator.py; server/services/workflow.py; server/services/workflow_storage/handlers.py; server/routers/workspace.py; server/nodes/filesystem/_backend.py; server/services/media/workspace.py; server/nodes/agent/claude_code_agent/_skills.py; server/services/cli_agent/session.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Workspace Anatomy</text>+<text x="72" y="91" class="subtitle">Immutable workflow IDs resolve to mutable slug directories that isolate files, generated media, CLI worktrees, and materialized skills</text>+<g data-group-id="workspace-resolution"><rect x="50" y="125" width="500" height="830" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="70" y="157" class="group-label">IDENTITY & ROOT RESOLUTION</text></g><g data-group-id="workspace-boundary"><rect x="590" y="125" width="710" height="830" rx="18" fill="#fafbfc" stroke="#ff79c6" stroke-width="2"/><text x="610" y="157" class="group-label">PER-WORKFLOW WORKSPACE</text></g><g data-group-id="workspace-consumers"><rect x="1340" y="125" width="530" height="830" rx="18" fill="#fafbfc" stroke="#50fa7b" stroke-width="2"/><text x="1360" y="157" class="group-label">CONTAINED CONSUMERS</text></g><g data-relationship-id="r-workflow-locator"><title>lookup by immutable workflow id</title><path d="M 300.0 340 L 300.0 430" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="170.2" y="370.0" width="259.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="300" y="388" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">lookup by immutable workflow id</text></g><g data-relationship-id="r-locator-base"><title>selects mutable slug below root</title><path d="M 300.0 600 L 300.0 720" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="170.2" y="650.0" width="259.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="300" y="668" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">selects mutable slug below root</text></g><g data-relationship-id="r-base-workspace"><title>contains one slug directory</title><path d="M 300.0 720 L 300 680 L 945 680 L 945.0 350" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="560.4" y="665.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="675" y="683" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">contains one slug directory</text></g><g data-relationship-id="r-workspace-files"><title>contains runtime artifacts</title><path d="M 945.0 350 L 945 410 L 780 410 L 780.0 470" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="669.2" y="395.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="780" y="413" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">contains runtime artifacts</text></g><g data-relationship-id="r-workspace-skills"><title>contains isolated skill tree</title><path d="M 945.0 350 L 945 410 L 1110 410 L 1110.0 470" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="991.6" y="395.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1110" y="413" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">contains isolated skill tree</text></g><g data-relationship-id="r-workspace-worktrees"><title>contains per-node task worktrees</title><path d="M 945.0 350 L 945 690 L 960.0 730" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="811.4" y="675.0" width="267.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="945" y="693" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">contains per-node task worktrees</text></g><g data-relationship-id="r-routes-resolve"><title>resolves workflow id before file access · via workspace locator</title><path d="M 1600.0 340 L 1600 400 L 945 400 L 945.0 350" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1320.0 400.0 L 1410 400" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1249.8" y="376.0" width="320.4" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1410" y="397" class="edge-label" text-anchor="middle" textLength="302.4" lengthAdjust="spacingAndGlyphs">resolves workflow id before file access</text><text x="1410" y="417" class="edge-protocol" text-anchor="middle">via workspace locator</text></g><g data-relationship-id="r-filesystem-files"><title>reads and writes contained paths</title><path d="M 1380 545.0 L 920 555.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1150.0 545.0 L 1240 707" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1106.4" y="692.0" width="267.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1240" y="710" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">reads and writes contained paths</text></g><g data-relationship-id="r-skills-cli"><title>auto-discovers enabled skills · via --add-dir</title><path d="M 1110.0 640 L 1110 680 L 1320 680 L 1320 805 L 1380 805.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1215.0 680.0 L 1215 950" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1092.8" y="926.0" width="244.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1215" y="947" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">auto-discovers enabled skills</text><text x="1215" y="967" class="edge-protocol" text-anchor="middle">via --add-dir</text></g><g data-relationship-id="r-workspace-cli"><title>passes workspace_dir</title><path d="M 945.0 350 L 1270 350 L 1270 690 L 1600 690 L 1600.0 730" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1450.0 690.0 L 1540 690" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1452.0" y="675.0" width="176.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1540" y="693" class="edge-label" text-anchor="middle" textLength="158.0" lengthAdjust="spacingAndGlyphs">passes workspace_dir</text></g><g data-component-id="workflow-record"><title>Workflow record</title><rect x="90" y="190" width="420" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="190" width="420" height="7" rx="4" fill="#ff79c6"/><text x="108" y="216" class="type-label">DATABASE IDENTITY</text><text x="108" y="242" class="node-label">Workflow record</text><text x="108" y="268" class="node-detail">Immutable id · mutable slug</text><text x="108" y="288" class="node-detail">Stable references carry the id</text></g><g data-component-id="workspace-locator"><title>Workspace locator</title><rect x="90" y="430" width="420" height="170" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="90" y="430" width="420" height="7" rx="4" fill="#ffb86c"/><text x="108" y="456" class="type-label">PATH RESOLVER</text><text x="108" y="482" class="node-label">Workspace locator</text><text x="108" y="508" class="node-detail">Looks up id → slug in workflow.db</text><text x="108" y="528" class="node-detail">Read-only misses may use default</text><text x="108" y="548" class="node-detail">Mutations fail if id cannot resolve</text></g><g data-component-id="workspace-base"><title>DATA_DIR / workspaces</title><rect x="90" y="720" width="420" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="720" width="420" height="7" rx="4" fill="#ff79c6"/><text x="108" y="746" class="type-label">FILESYSTEM ROOT</text><text x="108" y="772" class="node-label">DATA_DIR /</text><text x="108" y="794" class="node-label">workspaces</text><text x="108" y="820" class="node-detail">~/.opencompany/workspaces by default</text><text x="108" y="840" class="node-detail">WORKSPACE_BASE_DIR remains configurable</text></g><g data-component-id="workflow-workspace"><title>workspaces/<workflow.slug>/</title><rect x="640" y="190" width="610" height="160" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="190" width="610" height="7" rx="4" fill="#ff79c6"/><text x="658" y="216" class="type-label">WORKSPACE ROOT</text><text x="658" y="242" class="node-label">workspaces/<workflow.slug>/</text><text x="658" y="268" class="node-detail">Created for one workflow</text><text x="658" y="288" class="node-detail">Directory moves when the slug changes</text></g><g data-component-id="workspace-files"><title>Workspace files</title><rect x="640" y="470" width="280" height="170" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="640" y="470" width="280" height="7" rx="4" fill="#ff79c6"/><text x="658" y="496" class="type-label">RUNTIME ARTIFACTS</text><text x="658" y="522" class="node-label">Workspace files</text><text x="658" y="548" class="node-detail">Uploads · generated media</text><text x="658" y="568" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">Documents · code · nested files</text></g><g data-component-id="workspace-skills"><title>.claude/skills/<name>/</title><rect x="970" y="470" width="280" height="170" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="970" y="470" width="280" height="7" rx="4" fill="#50fa7b"/><text x="988" y="496" class="type-label">MATERIALIZED SKILLS</text><text x="988" y="522" class="node-label">.claude/skills/</text><text x="988" y="544" class="node-label"><name>/</text><text x="988" y="570" class="node-detail">SKILL.md</text><text x="988" y="590" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">scripts/ + references/ preserved</text></g><g data-component-id="cli-worktrees"><title><node_id>/wt_<task_id>/</title><rect x="810" y="730" width="300" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="810" y="730" width="300" height="7" rx="4" fill="#ffb86c"/><text x="828" y="756" class="type-label">CLI WORKTREE</text><text x="828" y="782" class="node-label"><node_id>/</text><text x="828" y="804" class="node-label">wt_<task_id>/</text><text x="828" y="830" class="node-detail">Per-task isolated branch</text><text x="828" y="850" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">Lives under the workflow workspace</text></g><g data-component-id="workspace-routes"><title>Workspace HTTP routes</title><rect x="1380" y="190" width="440" height="150" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1380" y="190" width="440" height="7" rx="4" fill="#8be9fd"/><text x="1398" y="216" class="type-label">INTERFACE</text><text x="1398" y="242" class="node-label">Workspace HTTP</text><text x="1398" y="264" class="node-label">routes</text><text x="1398" y="290" class="node-detail">Serve file by workflow id + path</text><text x="1398" y="310" class="node-detail">Accept bounded uploads</text></g><g data-component-id="filesystem-media"><title>Filesystem & media nodes</title><rect x="1380" y="460" width="440" height="170" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1380" y="460" width="440" height="7" rx="4" fill="#50fa7b"/><text x="1398" y="486" class="type-label">CONTAINED I/O</text><text x="1398" y="512" class="node-label">Filesystem &</text><text x="1398" y="534" class="node-label">media nodes</text><text x="1398" y="560" class="node-detail">resolve_within containment</text><text x="1398" y="580" class="node-detail">Traversal + symlink/junction defense</text><text x="1398" y="600" class="node-detail">Atomic workspace writes</text></g><g data-component-id="cli-agent-session"><title>CLI agent session</title><rect x="1380" y="730" width="440" height="150" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="1380" y="730" width="440" height="7" rx="4" fill="#bd93f9"/><text x="1398" y="756" class="type-label">AGENT CONSUMER</text><text x="1398" y="782" class="node-label">CLI agent session</text><text x="1398" y="808" class="node-detail">Receives workspace_dir / --add-dir</text><text x="1398" y="828" class="node-detail">Discovers skills and owns worktrees</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/08-node-configuration-anatomy.svg b/docs/diagrams/v2/light/08-node-configuration-anatomy.svgnew file mode 100644index 00000000..8712326d--- /dev/null+++ b/docs/diagrams/v2/light/08-node-configuration-anatomy.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="35179531c67b57ed">+<title id="title">Node Configuration Anatomy — light theme</title>+<desc id="desc">An anatomy of the Node Configuration modal showing the real header actions, the 0.7 / 1.6 / 0.7 Input–Parameters–Output layout, NodeSpec-driven variants, local edit-buffer persistence, save-before-run execution, and WebSocket-correlated output handling. Sources: client/src/ParameterPanel.tsx; client/src/components/parameterPanel/ParameterPanelLayout.tsx; client/src/components/parameterPanel/InputSection.tsx; client/src/components/parameterPanel/MiddleSection.tsx; client/src/components/parameterPanel/OutputSection.tsx; client/src/hooks/useParameterPanel.ts; client/src/hooks/useNodeParamsQuery.ts; client/src/services/executionService.ts; server/routers/websocket.py; server/core/database.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Node Configuration Anatomy</text>+<text x="72" y="91" class="subtitle">A schema-driven modal combines draggable upstream data, a local parameter draft, per-node execution, and correlated live output</text>+<g data-group-id="configuration-modal"><rect x="50" y="125" width="1820" height="620" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="70" y="157" class="group-label">NODE CONFIGURATION MODAL</text></g><g data-group-id="panel-data-plane"><rect x="50" y="775" width="1820" height="180" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="70" y="807" class="group-label">LIVE DATA & PERSISTENCE</text></g><g data-relationship-id="r-spec-identity"><title>supplies icon and display name</title><path d="M 255.0 820 L 255 760 L 370 760 L 370.0 285" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="244.0" y="745.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="370" y="763" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">supplies icon and display name</text></g><g data-relationship-id="r-spec-parameters"><title>renders fields and panel variants</title><path d="M 255.0 820 L 255 720 L 940 720 L 940.0 690" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="462.6" y="705.0" width="274.79999999999995" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="600" y="723" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">renders fields and panel variants</text></g><g data-relationship-id="r-input-parameters"><title>drag template variable</title><path d="M 305.0 350 L 305 320 L 940 320 L 940.0 350" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="524.4" y="305.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="620" y="323" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">drag template variable</text></g><g data-relationship-id="r-parameters-draft"><title>onParameterChange updates local draft</title><path d="M 940.0 690 L 940 750 L 690 750 L 690.0 820" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="662.4" y="735.0" width="305.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="815" y="753" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">onParameterChange updates local draft</text></g><g data-relationship-id="r-save-draft"><title>handleSave commits draft</title><path d="M 810.0 285 L 810 310 L 460 310 L 460 760 L 690 760 L 690.0 820" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 575.0 760.0 L 575 975.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="471.8" y="960.0" width="206.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="575" y="978.0" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">handleSave commits draft</text></g><g data-relationship-id="r-run-execution"><title>save if dirty, then execute node</title><path d="M 1070.0 285 L 1070 310 L 1120 760 L 1120.0 820" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="986.4" y="745.0" width="267.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1120" y="763" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">save if dirty, then execute node</text></g><g data-relationship-id="r-execution-output"><title>appends correlated ExecutionResult</title><path d="M 1120.0 820 L 1120 735 L 1595 735 L 1595.0 690" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1370.0 735.0 L 1460 735" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1318.8" y="720.0" width="282.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1460" y="738" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">appends correlated ExecutionResult</text></g><g data-relationship-id="r-websocket-output"><title>broadcasts node status and output · via execution_id</title><path d="M 1600.0 820 L 1600 780 L 1760 780 L 1760 720 L 1595 720 L 1595.0 690" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1705.0 720.0 L 1705 774" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1567.6" y="750.0" width="274.79999999999995" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1705" y="771" class="edge-label" text-anchor="middle" textLength="256.8" lengthAdjust="spacingAndGlyphs">broadcasts node status and output</text><text x="1705" y="791" class="edge-protocol" text-anchor="middle">via execution_id</text></g><g data-relationship-id="r-cancel-websocket"><title>cancel wait or close draft</title><path d="M 1355.0 285 L 1355 310 L 1850 310 L 1850 760 L 1600 760 L 1600.0 820" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1720.0 760.0 L 1720 975.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1609.2" y="960.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1720" y="978.0" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">cancel wait or close draft</text></g><g data-relationship-id="r-draft-database"><title>save_node_parameters · via TanStack Query + WS</title><path d="M 690.0 945 L 690 970 L 1600 970 L 1600.0 945" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1045.6" y="942.0" width="198.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1145" y="963.0" class="edge-label" text-anchor="middle">save_node_parameters</text><text x="1145" y="983.0" class="edge-protocol" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">via TanStack Query + WS</text></g><g data-component-id="node-identity"><title>Node identity</title><rect x="90" y="175" width="560" height="110" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="175" width="560" height="7" rx="4" fill="#8be9fd"/><text x="108" y="201" class="type-label">MODAL HEADER</text><text x="108" y="227" class="node-label">Node identity</text><text x="108" y="253" class="node-detail">Icon · display name · dirty marker</text></g><g data-component-id="save-action"><title>Save</title><rect x="700" y="175" width="220" height="110" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="700" y="175" width="220" height="7" rx="4" fill="#ff79c6"/><text x="718" y="201" class="type-label">HEADER ACTION</text><text x="718" y="227" class="node-label">Save</text><text x="718" y="253" class="node-detail" textLength="184.0" lengthAdjust="spacingAndGlyphs">Disabled when clean or canvas locked</text></g><g data-component-id="run-action"><title>Run</title><rect x="960" y="175" width="220" height="110" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="960" y="175" width="220" height="7" rx="4" fill="#ff79c6"/><text x="978" y="201" class="type-label">HEADER ACTION</text><text x="978" y="227" class="node-label">Run</text><text x="978" y="253" class="node-detail" textLength="184.0" lengthAdjust="spacingAndGlyphs">Hidden by uiHints when passive</text></g><g data-component-id="cancel-action"><title>Cancel / Stop</title><rect x="1220" y="175" width="270" height="110" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1220" y="175" width="270" height="7" rx="4" fill="#ff79c6"/><text x="1238" y="201" class="type-label">HEADER ACTION</text><text x="1238" y="227" class="node-label">Cancel / Stop</text><text x="1238" y="253" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">Revert draft or cancel active wait</text></g><g data-component-id="close-action"><title>Close (X)</title><rect x="1530" y="175" width="300" height="110" rx="12" fill="#ffffff" stroke="#9aa1ac" stroke-width="2"/><rect x="1530" y="175" width="300" height="7" rx="4" fill="#9aa1ac"/><text x="1548" y="201" class="type-label">MODAL ACTION</text><text x="1548" y="227" class="node-label">Close (X)</text><text x="1548" y="253" class="node-detail">Cancel draft and deselect node</text></g><g data-component-id="input-column"><title>Input Data & Variables</title><rect x="90" y="350" width="430" height="340" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="90" y="350" width="430" height="7" rx="4" fill="#8be9fd"/><text x="108" y="376" class="type-label">LEFT COLUMN · 0.7</text><text x="108" y="402" class="node-label">Input Data &</text><text x="108" y="424" class="node-label">Variables</text><text x="108" y="450" class="node-detail">Upstream execution values or output schema</text><text x="108" y="470" class="node-detail">Recursive object and array fields</text><text x="108" y="490" class="node-detail">Drag template variables into parameters</text></g><g data-component-id="parameters-column"><title>Parameters</title><rect x="560" y="350" width="760" height="340" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="560" y="350" width="760" height="7" rx="4" fill="#8be9fd"/><text x="578" y="376" class="type-label">MIDDLE COLUMN · 1.6</text><text x="578" y="402" class="node-label">Parameters</text><text x="578" y="428" class="node-detail">Schema-rendered local edit buffer</text><text x="578" y="448" class="node-detail">Specialized middle panels selected by uiHints</text><text x="578" y="468" class="node-detail">Connected Skills · Token Usage · Console</text></g><g data-component-id="output-column"><title>Output</title><rect x="1360" y="350" width="470" height="340" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1360" y="350" width="470" height="7" rx="4" fill="#50fa7b"/><text x="1378" y="376" class="type-label">RIGHT COLUMN · 0.7</text><text x="1378" y="402" class="node-label">Output</text><text x="1378" y="428" class="node-detail">Local run results + WebSocket status</text><text x="1378" y="448" class="node-detail">Deduplicates matching execution_id</text><text x="1378" y="468" class="node-detail">Clear results without changing parameters</text></g><g data-component-id="node-spec"><title>NodeSpec metadata</title><rect x="90" y="820" width="330" height="110" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="90" y="820" width="330" height="7" rx="4" fill="#ff79c6"/><text x="108" y="846" class="type-label">SCHEMA SOURCE</text><text x="108" y="872" class="node-label">NodeSpec metadata</text><text x="108" y="898" class="node-detail">properties · handles · uiHints</text></g><g data-component-id="parameter-state"><title>Parameter query + draft</title><rect x="500" y="820" width="380" height="125" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="500" y="820" width="380" height="7" rx="4" fill="#ffb86c"/><text x="518" y="846" class="type-label">CLIENT STATE</text><text x="518" y="872" class="node-label">Parameter query</text><text x="518" y="894" class="node-label">+ draft</text><text x="518" y="920" class="node-detail">defaults + saved params</text><text x="518" y="940" class="node-detail">dirty edit buffer + query cache</text></g><g data-component-id="execution-service"><title>ExecutionService</title><rect x="940" y="820" width="360" height="110" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="940" y="820" width="360" height="7" rx="4" fill="#ffb86c"/><text x="958" y="846" class="type-label">PER-NODE RUNTIME</text><text x="958" y="872" class="node-label">ExecutionService</text><text x="958" y="898" class="node-detail">save-before-run · executeNode</text><text x="958" y="918" class="node-detail">per-node reducer</text></g><g data-component-id="websocket-database"><title>WebSocket + workflow.db</title><rect x="1370" y="820" width="460" height="125" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1370" y="820" width="460" height="7" rx="4" fill="#ff79c6"/><text x="1388" y="846" class="type-label">LIVE DATA PLANE</text><text x="1388" y="872" class="node-label">WebSocket +</text><text x="1388" y="894" class="node-label">workflow.db</text><text x="1388" y="920" class="node-detail">node_parameters · node_outputs</text><text x="1388" y="940" class="node-detail">node status + wait cancellation</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/09-credentials-architecture.svg b/docs/diagrams/v2/light/09-credentials-architecture.svgnew file mode 100644index 00000000..0800346c--- /dev/null+++ b/docs/diagrams/v2/light/09-credentials-architecture.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="516cf648ab56c9c9">+<title id="title">Credentials Architecture — light theme</title>+<desc id="desc">Credential configuration flows from the server-owned provider catalogue through modular client panels and registered WebSocket handlers. AuthService is the only plaintext access boundary; CredentialsDatabase encrypts separate API-key and OAuth-token records with the process-held Fernet service, while status events invalidate every connected client's catalogue. Sources: client/src/components/credentials/CredentialsModal.tsx; client/src/components/credentials/useCredentialPanel.ts; server/services/credentials/handlers.py; server/services/plugin/credential.py; server/services/auth.py; server/core/credentials_database.py; server/core/encryption.py; server/services/status_broadcaster.py</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Credentials Architecture</text>+<text x="72" y="91" class="subtitle">Server-owned catalogue, WebSocket orchestration, and encrypted storage</text>+<g data-group-id="client-plane"><rect x="72" y="150" width="650" height="780" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="92" y="182" class="group-label">CLIENT CONTROL PLANE</text></g><g data-group-id="server-plane"><rect x="760" y="150" width="1088" height="780" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="780" y="182" class="group-label">SERVER SECURITY PLANE</text></g><g data-relationship-id="modal-uses-client-state"><title>panel actions + cached status · via React Query</title><path d="M 380 315.0 L 420 315.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 400.0 205.0 L 490 151" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="367.8" y="127.0" width="244.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="490" y="148" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">panel actions + cached status</text><text x="490" y="168" class="edge-protocol" text-anchor="middle">via React Query</text></g><g data-relationship-id="client-calls-handlers"><title>catalogue + credential RPC · via WebSocket</title><path d="M 680 315.0 L 800 315.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 740.0 315.0 L 740 477" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="629.2" y="453.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="740" y="474" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">catalogue + credential RPC</text><text x="740" y="494" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="handlers-dispatch-registry"><title>dispatch validation</title><path d="M 1070 315.0 L 1130 315.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1100.0 205.0 L 1190 205" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1105.8" y="190.0" width="168.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1190" y="208" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">dispatch validation</text></g><g data-relationship-id="handlers-use-auth-service"><title>get · save · delete</title><path d="M 935.0 400 L 935 450 L 1215 450 L 1215.0 500" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="990.8" y="435.0" width="168.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1075" y="453" class="edge-label" text-anchor="middle" textLength="150.4" lengthAdjust="spacingAndGlyphs">get · save · delete</text></g><g data-relationship-id="registry-stores-valid-result"><title>store valid probe result</title><path d="M 1280.0 400 L 1215.0 500" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1280.0 480.0 L 1280 426" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1176.8" y="411.0" width="206.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1280" y="429" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">store valid probe result</text></g><g data-relationship-id="registry-publishes-status"><title>publish validation status</title><path d="M 1430 315.0 L 1500 315.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1358.0" y="190.0" width="214.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1465" y="208" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">publish validation status</text></g><g data-relationship-id="auth-publishes-mutation"><title>catalogue version + mutation event</title><path d="M 1400 595.0 L 1450 595 L 1450 440 L 1650 440 L 1650.0 400" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1418.8" y="425.0" width="282.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1560" y="443" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">catalogue version + mutation event</text></g><g data-relationship-id="auth-canonical-crud"><title>canonical encrypted CRUD</title><path d="M 1215.0 690 L 1415.0 760" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1156.8" y="700.0" width="206.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1260" y="718" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">canonical encrypted CRUD</text></g><g data-relationship-id="db-uses-encryption"><title>encrypt / decrypt payloads · via Fernet</title><path d="M 1415.0 760 L 1415 720 L 1645 720 L 1645.0 690" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1580.0 720.0 L 1580 966.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1469.2" y="942.0" width="221.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1580" y="963.0" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">encrypt / decrypt payloads</text><text x="1580" y="983.0" class="edge-protocol" text-anchor="middle">via Fernet</text></g><g data-relationship-id="broadcast-invalidates-client"><title>push status + invalidate catalogue · via WebSocket</title><path d="M 1650.0 230 L 1650 115 L 550 115 L 550.0 230" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1100.0 115.0 L 1190 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1048.8" y="124.0" width="282.4" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1190" y="145.0" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">push status + invalidate catalogue</text><text x="1190" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-component-id="credentials-modal"><title>Credentials Modal</title><rect x="110" y="230" width="270" height="170" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="230" width="270" height="7" rx="4" fill="#8be9fd"/><text x="128" y="256" class="type-label">UI</text><text x="128" y="282" class="node-label">Credentials Modal</text><text x="128" y="308" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">server catalogue + IDB warm-start</text><text x="128" y="328" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">search palette + lazy panels</text></g><g data-component-id="client-state"><title>WebSocket + Query State</title><rect x="420" y="230" width="260" height="170" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="420" y="230" width="260" height="7" rx="4" fill="#8be9fd"/><text x="438" y="256" class="type-label">CLIENT</text><text x="438" y="282" class="node-label">WebSocket +</text><text x="438" y="304" class="node-label">Query State</text><text x="438" y="330" class="node-detail">request / response RPC</text><text x="438" y="350" class="node-detail">catalogue invalidation</text></g><g data-component-id="ws-handlers"><title>Credential WS Handlers</title><rect x="800" y="230" width="270" height="170" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="800" y="230" width="270" height="7" rx="4" fill="#ffb86c"/><text x="818" y="256" class="type-label">ROUTER</text><text x="818" y="282" class="node-label">Credential WS</text><text x="818" y="304" class="node-label">Handlers</text><text x="818" y="330" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">validate · get · save · delete</text><text x="818" y="350" class="node-detail" textLength="234.0" lengthAdjust="spacingAndGlyphs">idempotent mutation envelope</text></g><g data-component-id="credential-registries"><title>Credential Registries</title><rect x="1130" y="230" width="300" height="170" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1130" y="230" width="300" height="7" rx="4" fill="#ffb86c"/><text x="1148" y="256" class="type-label">REGISTRY</text><text x="1148" y="282" class="node-label">Credential Registries</text><text x="1148" y="308" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">catalogue metadata + stored flags</text><text x="1148" y="328" class="node-detail">credential classes + probes</text></g><g data-component-id="status-broadcaster"><title>Status Broadcaster</title><rect x="1500" y="230" width="300" height="170" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1500" y="230" width="300" height="7" rx="4" fill="#ff79c6"/><text x="1518" y="256" class="type-label">EVENTS</text><text x="1518" y="282" class="node-label">Status Broadcaster</text><text x="1518" y="308" class="node-detail">api_key_status</text><text x="1518" y="328" class="node-detail">credential_catalogue_updated</text></g><g data-component-id="auth-service"><title>AuthService</title><rect x="1030" y="500" width="370" height="190" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1030" y="500" width="370" height="7" rx="4" fill="#f1fa8c"/><text x="1048" y="526" class="type-label">SECURITY SERVICE</text><text x="1048" y="552" class="node-label">AuthService</text><text x="1048" y="578" class="node-detail">only credential access point</text><text x="1048" y="598" class="node-detail">separate API-key + OAuth caches</text><text x="1048" y="618" class="node-detail">refresh tokens never cached</text></g><g data-component-id="encryption-service"><title>Encryption Service</title><rect x="1490" y="500" width="310" height="190" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1490" y="500" width="310" height="7" rx="4" fill="#f1fa8c"/><text x="1508" y="526" class="type-label">CRYPTO</text><text x="1508" y="552" class="node-label">Encryption Service</text><text x="1508" y="578" class="node-detail">PBKDF2-SHA256 · 600k</text><text x="1508" y="598" class="node-detail">Fernet key held in process</text><text x="1508" y="618" class="node-detail">server key + install salt</text></g><g data-component-id="credentials-db"><title>credentials.db</title><rect x="1180" y="760" width="470" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1180" y="760" width="470" height="7" rx="4" fill="#ff79c6"/><text x="1198" y="786" class="type-label">ENCRYPTED SQLITE</text><text x="1198" y="812" class="node-label">credentials.db</text><text x="1198" y="838" class="node-detail">EncryptedAPIKey · EncryptedOAuthToken</text><text x="1198" y="858" class="node-detail">credentials_metadata encryption salt</text></g><g data-callout-id="storage-split"><rect x="800" y="735" width="330" height="175" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="816" y="765" class="callout-title">Two non-interchangeable stores</text><text x="816" y="791" class="callout-text">API keys: session + provider</text><text x="816" y="813" class="callout-text">OAuth tokens: provider + customer</text><text x="816" y="835" class="callout-text" textLength="298.0" lengthAdjust="spacingAndGlyphs">Access tokens may cache; refresh tokens do not</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/10-team-operations.svg b/docs/diagrams/v2/light/10-team-operations.svgnew file mode 100644index 00000000..736b9b4f--- /dev/null+++ b/docs/diagrams/v2/light/10-team-operations.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="9002f02d01716d7e">+<title id="title">Team Operations — light theme</title>+<desc id="desc">A team lead uses its intrinsic Task Manager to persist bounded work for graph-connected teammates. AgentTeamService enforces workflow, lead, execution, assignee, and optimistic-revision boundaries while tasks advance from blocked or queued through worker submission and explicit lead acceptance; Task Manager and Team Monitor expose mutable and read-only views of the same durable state. Sources: server/nodes/tool/task_manager/__init__.py; server/services/agent_team.py; server/services/agent_teams/handlers.py; server/services/temporal/agent_workflow.py; client/src/components/parameterPanel/TaskManagerPanel.tsx; client/src/components/parameterPanel/TeamMonitorPanel.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Team Operations</text>+<text x="72" y="91" class="subtitle">Execution-scoped durable tasks: assign, run, review, recover, and finish</text>+<g data-group-id="operation-surfaces"><rect x="72" y="140" width="1776" height="235" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="92" y="172" class="group-label">OPERATION SURFACES</text></g><g data-group-id="task-lifecycle"><rect x="72" y="410" width="1776" height="535" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="92" y="442" class="group-label">DURABLE TASK LIFECYCLE</text></g><g data-relationship-id="lead-calls-task-manager"><title>call public operations</title><path d="M 410 275.0 L 500 275.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="359.4" y="165.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="455" y="183" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">call public operations</text></g><g data-relationship-id="task-manager-uses-service"><title>scoped durable mutation</title><path d="M 830 275.0 L 920 275.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="775.6" y="165.0" width="198.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="875" y="183" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">scoped durable mutation</text></g><g data-relationship-id="human-manages-service"><title>inspect + permitted review actions · via WebSocket</title><path d="M 1390 275.0 L 1280 275.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1335.0 245.0 L 1335 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1193.8" y="124.0" width="282.4" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1335" y="145.0" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">inspect + permitted review actions</text><text x="1335" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="service-updates-human"><title>snapshots + lifecycle events</title><path d="M 1100.0 345 L 1100 365 L 1570 365 L 1570.0 345" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1335.0 365.0 L 1335 419" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1216.6" y="404.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1335" y="422" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">snapshots + lifecycle events</text></g><g data-relationship-id="service-assigns-ready"><title>assign_task persists ready work</title><path d="M 1100.0 345 L 1100 395 L 565 395 L 565.0 520" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="700.2" y="380.0" width="259.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="830" y="398" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">assign_task persists ready work</text></g><g data-relationship-id="dependencies-unblock"><title>dependencies accepted</title><path d="M 360 590.0 L 440 590.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="308.2" y="480.0" width="183.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="400" y="498" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">dependencies accepted</text></g><g data-relationship-id="worker-claims"><title>worker claims task</title><path d="M 690 590.0 L 770 590.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="649.6" y="480.0" width="160.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="730" y="498" class="edge-label" text-anchor="middle" textLength="142.8" lengthAdjust="spacingAndGlyphs">worker claims task</text></g><g data-relationship-id="worker-submits"><title>worker succeeds</title><path d="M 1020 590.0 L 1100 590.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="991.0" y="480.0" width="138.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1060" y="498" class="edge-label" text-anchor="middle" textLength="120.0" lengthAdjust="spacingAndGlyphs">worker succeeds</text></g><g data-relationship-id="lead-accepts"><title>accept_task</title><path d="M 1350 590.0 L 1430 590.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1330.0" y="480.0" width="120" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1390" y="498" class="edge-label" text-anchor="middle">accept_task</text></g><g data-relationship-id="worker-fails"><title>worker errors</title><path d="M 895.0 660 L 895.0 760" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="833.6" y="695.0" width="122.8" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="895" y="713" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">worker errors</text></g><g data-relationship-id="failed-requeues"><title>retry_task / reassign_task</title><path d="M 770 830.0 L 720 700 L 565 700 L 565.0 660" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="529.2" y="685.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="640" y="703" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="submitted-requeues"><title>retry_task / reassign_task</title><path d="M 1225.0 520 L 1225 455 L 565 455 L 565.0 520" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="784.2" y="440.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="895" y="458" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="cancelled-requeues"><title>retry_task / reassign_task</title><path d="M 1225.0 900 L 1225 925 L 700 925 L 700 700 L 565.0 660" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="784.2" y="910.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="895" y="928" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">retry_task / reassign_task</text></g><g data-relationship-id="accepted-finishes-team"><title>finish_team when all resolved</title><path d="M 1555.0 660 L 1555.0 760" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1432.8" y="675.0" width="244.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1555" y="693" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">finish_team when all resolved</text></g><g data-relationship-id="cancelled-is-resolved"><title>cancelled also counts resolved</title><path d="M 1350 830.0 L 1430 830.0" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><rect x="1264.0" y="720.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1390" y="738" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">cancelled also counts resolved</text></g><g data-component-id="team-lead"><title>Team Lead</title><rect x="110" y="205" width="300" height="140" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="110" y="205" width="300" height="7" rx="4" fill="#bd93f9"/><text x="128" y="231" class="type-label">AGENT</text><text x="128" y="257" class="node-label">Team Lead</text><text x="128" y="283" class="node-detail">Orchestrator or AI Employee</text><text x="128" y="303" class="node-detail" textLength="264.0" lengthAdjust="spacingAndGlyphs">connected teammates are authority</text></g><g data-component-id="task-manager"><title>Task Manager</title><rect x="500" y="205" width="330" height="140" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="500" y="205" width="330" height="7" rx="4" fill="#50fa7b"/><text x="518" y="231" class="type-label">INTRINSIC TOOL</text><text x="518" y="257" class="node-label">Task Manager</text><text x="518" y="283" class="node-detail">assign · inspect · review</text><text x="518" y="303" class="node-detail">retry · reassign · cancel · finish</text></g><g data-component-id="agent-team-service"><title>AgentTeamService</title><rect x="920" y="205" width="360" height="140" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="920" y="205" width="360" height="7" rx="4" fill="#ffb86c"/><text x="938" y="231" class="type-label">DURABLE SERVICE</text><text x="938" y="257" class="node-label">AgentTeamService</text><text x="938" y="283" class="node-detail">workflow + lead + execution scope</text><text x="938" y="303" class="node-detail">optimistic revision transitions</text></g><g data-component-id="human-views"><title>Task Manager + Team Monitor</title><rect x="1390" y="205" width="360" height="140" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1390" y="205" width="360" height="7" rx="4" fill="#8be9fd"/><text x="1408" y="231" class="type-label">HUMAN UI</text><text x="1408" y="257" class="node-label">Task Manager +</text><text x="1408" y="279" class="node-label">Team Monitor</text><text x="1408" y="305" class="node-detail">authorized mutations + trace</text><text x="1408" y="325" class="node-detail">read-only lifecycle snapshot</text></g><g data-component-id="blocked"><title>Blocked</title><rect x="110" y="520" width="250" height="140" rx="12" fill="#ffffff" stroke="#9aa1ac" stroke-width="2"/><rect x="110" y="520" width="250" height="7" rx="4" fill="#9aa1ac"/><text x="128" y="546" class="type-label">TASK STATE</text><text x="128" y="572" class="node-label">Blocked</text><text x="128" y="598" class="node-detail">dependencies unresolved</text></g><g data-component-id="queued"><title>Queued</title><rect x="440" y="520" width="250" height="140" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="440" y="520" width="250" height="7" rx="4" fill="#ffb86c"/><text x="458" y="546" class="type-label">TASK STATE</text><text x="458" y="572" class="node-label">Queued</text><text x="458" y="598" class="node-detail">durably persisted</text><text x="458" y="618" class="node-detail">awaiting admission</text></g><g data-component-id="running"><title>Running</title><rect x="770" y="520" width="250" height="140" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="770" y="520" width="250" height="7" rx="4" fill="#ffb86c"/><text x="788" y="546" class="type-label">TASK STATE</text><text x="788" y="572" class="node-label">Running</text><text x="788" y="598" class="node-detail">worker claimed task</text><text x="788" y="618" class="node-detail">detached child execution</text></g><g data-component-id="submitted"><title>Submitted</title><rect x="1100" y="520" width="250" height="140" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1100" y="520" width="250" height="7" rx="4" fill="#ff79c6"/><text x="1118" y="546" class="type-label">TASK STATE</text><text x="1118" y="572" class="node-label">Submitted</text><text x="1118" y="598" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">worker result awaits review</text></g><g data-component-id="accepted"><title>Accepted</title><rect x="1430" y="520" width="250" height="140" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1430" y="520" width="250" height="7" rx="4" fill="#50fa7b"/><text x="1448" y="546" class="type-label">TASK STATE</text><text x="1448" y="572" class="node-label">Accepted</text><text x="1448" y="598" class="node-detail">lead-approved Done state</text></g><g data-component-id="failed"><title>Failed</title><rect x="770" y="760" width="250" height="140" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="770" y="760" width="250" height="7" rx="4" fill="#ff79c6"/><text x="788" y="786" class="type-label">TASK STATE</text><text x="788" y="812" class="node-label">Failed</text><text x="788" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">error retained for recovery</text></g><g data-component-id="cancelled"><title>Cancelled</title><rect x="1100" y="760" width="250" height="140" rx="12" fill="#ffffff" stroke="#9aa1ac" stroke-width="2"/><rect x="1100" y="760" width="250" height="7" rx="4" fill="#9aa1ac"/><text x="1118" y="786" class="type-label">TASK STATE</text><text x="1118" y="812" class="node-label">Cancelled</text><text x="1118" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">intentional terminal state</text></g><g data-component-id="team-completed"><title>Team Completed</title><rect x="1430" y="760" width="250" height="140" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1430" y="760" width="250" height="7" rx="4" fill="#50fa7b"/><text x="1448" y="786" class="type-label">EXECUTION STATE</text><text x="1448" y="812" class="node-label">Team Completed</text><text x="1448" y="838" class="node-detail" textLength="214.0" lengthAdjust="spacingAndGlyphs">all tasks accepted or cancelled</text></g><g data-callout-id="permitted-mutations"><rect x="110" y="740" width="550" height="165" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="126" y="770" class="callout-title">State-aware controls</text><text x="126" y="796" class="callout-text">modify_task: blocked or queued</text><text x="126" y="818" class="callout-text">cancel_task: blocked, queued, or running</text><text x="126" y="840" class="callout-text">list/get/inspect never mutate task state</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/11-agent-context-memory.svg b/docs/diagrams/v2/light/11-agent-context-memory.svgnew file mode 100644index 00000000..b5f84774--- /dev/null+++ b/docs/diagrams/v2/light/11-agent-context-memory.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="c807035cec3f020d">+<title id="title">Agent Context vs. Simple Memory — light theme</title>+<desc id="desc">Agent Context is the system-managed exact journal, provider binding, replay checkpoint, and context-pressure policy connected through input-context. Simple Memory is a separate explicit tool connected through input-tools; the model or a human chooses when to remember, recall, update, or forget versioned facts in an isolated namespace, and those items are never injected as automatic transcript replay. Sources: server/nodes/context/__init__.py; server/nodes/context/_descriptor.py; server/services/agent_context/store.py; server/services/agent_context/compaction.py; server/nodes/context/_handlers.py; server/nodes/tool/simple_memory/__init__.py; server/services/memory/tool_store.py; client/src/components/parameterPanel/ContextPanel.tsx; client/src/components/parameterPanel/MemoryToolPanel.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Agent Context vs. Simple Memory</text>+<text x="72" y="91" class="subtitle">Automatic replay continuity and explicit durable knowledge are separate systems</text>+<g data-group-id="context-plane"><rect x="72" y="140" width="720" height="800" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="92" y="172" class="group-label">AGENT CONTEXT · AUTOMATIC REPLAY</text></g><g data-group-id="memory-plane"><rect x="1128" y="140" width="720" height="800" rx="18" fill="#fafbfc" stroke="#50fa7b" stroke-width="2"/><text x="1148" y="172" class="group-label">SIMPLE MEMORY · EXPLICIT TOOL</text></g><g data-relationship-id="context-binds-runtime"><title>bind policy at input-context</title><path d="M 400 300.0 L 430 430 L 790 430 L 810 520.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="481.6" y="415.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="600" y="433" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">bind policy at input-context</text></g><g data-relationship-id="runtime-appends-context"><title>append exact observable events</title><path d="M 810 520.0 L 650 520 L 650 603 L 420 602.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="524.0" y="505.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="650" y="523" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">append exact observable events</text></g><g data-relationship-id="journal-compacts"><title>compact at context pressure</title><path d="M 270.0 695 L 270 725 L 590 725 L 590.0 760" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="315.4" y="710.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="430" y="728" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">compact at context pressure</text></g><g data-relationship-id="checkpoint-replays"><title>replay checkpoint + exact tail</title><path d="M 740 835.0 L 780 835 L 780 700 L 960 700 L 960.0 645" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="694.0" y="705.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="820" y="723" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">replay checkpoint + exact tail</text></g><g data-relationship-id="memory-registers-tool"><title>register tool at input-tools</title><path d="M 1520 300.0 L 1490 430 L 1130 430 L 1110 520.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1201.6" y="415.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1320" y="433" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">register tool at input-tools</text></g><g data-relationship-id="runtime-invokes-memory"><title>remember / recall / update / forget</title><path d="M 1110 520.0 L 1290 520 L 1290 603 L 1500 602.5" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1145.0" y="505.0" width="290.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1290" y="523" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">remember / recall / update / forget</text></g><g data-relationship-id="memory-persists-items"><title>persist isolated versioned items</title><path d="M 1650.0 695 L 1650 725 L 1330 725 L 1330.0 760" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1356.4" y="710.0" width="267.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1490" y="728" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">persist isolated versioned items</text></g><g data-relationship-id="memory-returns-items"><title>return selected recalled items</title><path d="M 1180 835.0 L 1140 835 L 1140 700 L 960 700 L 960.0 645" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="974.0" y="665.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1100" y="683" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">return selected recalled items</text></g><g data-component-id="context-node"><title>Context Node</title><rect x="120" y="220" width="280" height="160" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="120" y="220" width="280" height="7" rx="4" fill="#bd93f9"/><text x="138" y="246" class="type-label">POLICY</text><text x="138" y="272" class="node-label">Context Node</text><text x="138" y="298" class="node-detail" textLength="244.0" lengthAdjust="spacingAndGlyphs">output-context → input-context</text><text x="138" y="318" class="node-detail">compaction + tail policy</text></g><g data-component-id="context-journal"><title>AgentContextStore</title><rect x="120" y="510" width="300" height="185" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="120" y="510" width="300" height="7" rx="4" fill="#ff79c6"/><text x="138" y="536" class="type-label">EXACT JOURNAL</text><text x="138" y="562" class="node-label">AgentContextStore</text><text x="138" y="588" class="node-detail">append-only observable events</text><text x="138" y="608" class="node-detail">thread · epoch · revision</text><text x="138" y="628" class="node-detail">provider-bound replay state</text></g><g data-component-id="context-checkpoint"><title>Replay Checkpoint</title><rect x="440" y="760" width="300" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="440" y="760" width="300" height="7" rx="4" fill="#ffb86c"/><text x="458" y="786" class="type-label">CONTEXT STATE</text><text x="458" y="812" class="node-label">Replay Checkpoint</text><text x="458" y="838" class="node-detail">native or portable summary</text><text x="458" y="858" class="node-detail">exact recent tail retained</text></g><g data-component-id="agent-runtime"><title>Agent Runtime</title><rect x="810" y="395" width="300" height="250" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="810" y="395" width="300" height="7" rx="4" fill="#bd93f9"/><text x="828" y="421" class="type-label">SHARED CONSUMER</text><text x="828" y="447" class="node-label">Agent Runtime</text><text x="828" y="473" class="node-detail">replays Context automatically</text><text x="828" y="493" class="node-detail">invokes Memory explicitly</text><text x="828" y="513" class="node-detail">keeps both namespaces separate</text></g><g data-component-id="memory-node"><title>Simple Memory</title><rect x="1520" y="220" width="280" height="160" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1520" y="220" width="280" height="7" rx="4" fill="#50fa7b"/><text x="1538" y="246" class="type-label">LOCKED TOOL</text><text x="1538" y="272" class="node-label">Simple Memory</text><text x="1538" y="298" class="node-detail">output-tool → input-tools</text><text x="1538" y="318" class="node-detail">remember · recall · list</text><text x="1538" y="338" class="node-detail">get · update · forget</text></g><g data-component-id="memory-store"><title>MemoryToolStore</title><rect x="1500" y="510" width="300" height="185" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1500" y="510" width="300" height="7" rx="4" fill="#ff79c6"/><text x="1518" y="536" class="type-label">DURABLE DATA</text><text x="1518" y="562" class="node-label">MemoryToolStore</text><text x="1518" y="588" class="node-detail">owner / workflow / node scope</text><text x="1518" y="608" class="node-detail">versioned idempotent mutations</text><text x="1518" y="628" class="node-detail">lexical + optional embedding</text></g><g data-component-id="memory-items"><title>Facts & Decisions</title><rect x="1180" y="760" width="300" height="150" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1180" y="760" width="300" height="7" rx="4" fill="#50fa7b"/><text x="1198" y="786" class="type-label">MEMORY ITEMS</text><text x="1198" y="812" class="node-label">Facts & Decisions</text><text x="1198" y="838" class="node-detail">returned only when recalled</text><text x="1198" y="858" class="node-detail">never automatic transcript</text></g><g data-callout-id="context-invariant"><rect x="440" y="220" width="300" height="160" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="456" y="250" class="callout-title">Automatic continuity</text><text x="456" y="276" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">System managed; no model tool call</text><text x="456" y="298" class="callout-text">Exact journal and replay policy</text><text x="456" y="320" class="callout-text">Clear rotates the active epoch</text></g><g data-callout-id="memory-invariant"><rect x="1180" y="220" width="300" height="160" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="1196" y="250" class="callout-title">Explicit knowledge</text><text x="1196" y="276" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">Model or human chooses mutations</text><text x="1196" y="298" class="callout-text">Stable facts and decisions only</text><text x="1196" y="320" class="callout-text" textLength="268.0" lengthAdjust="spacingAndGlyphs">Clear never clears Agent Context</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/12-master-skill-editor.svg b/docs/diagrams/v2/light/12-master-skill-editor.svgnew file mode 100644index 00000000..4d0d4356--- /dev/null+++ b/docs/diagrams/v2/light/12-master-skill-editor.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="37076efb9c516523">+<title id="title">Master Skill Editor — light theme</title>+<desc id="desc">Source-backed anatomy of the Master Skill editor: built-in and user skill sources flow through WebSocket handlers and TanStack caches into the catalogue and instruction editor, while enabled skills persist in skills_config, expand for a connected agent, and report safe runtime badges back to the exact Master Skill row. Sources: client/src/components/parameterPanel/MasterSkillEditor.tsx; client/src/hooks/useFolderSkills.ts; server/services/skills/handlers.py; server/nodes/skill/master_skill/__init__.py; server/nodes/skill/_expander.py; server/services/skill_runtime.py; server/nodes/skill/master_skill/_events.py; client/src/contexts/WebSocketContext.tsx</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Master Skill Editor</text>+<text x="72" y="91" class="subtitle">One split panel joins the skill catalogue, authoritative instructions, node configuration, and live retrieval state.</text>+<g data-group-id="skill-sources"><rect x="70" y="130" width="500" height="700" rx="18" fill="#fafbfc" stroke="#ff79c6" stroke-width="2"/><text x="90" y="162" class="group-label">SKILL SOURCES + WIRE HANDLERS</text></g><g data-group-id="editor-surface"><rect x="610" y="130" width="760" height="700" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="630" y="162" class="group-label">MASTER SKILL EDITOR</text></g><g data-group-id="agent-runtime"><rect x="1410" y="130" width="440" height="700" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1430" y="162" class="group-label">CONNECTED AGENT RUNTIME</text></g><g data-relationship-id="handlers-scan-builtins"><title>scan and load metadata + instructions · via filesystem</title><path d="M 320.0 360 L 220 390 L 208 390 L 207.5 430" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 205.0 390.0 L 164.6 390" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="12.0" y="366.0" width="305.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="164.6" y="387" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">scan and load metadata + instructions</text><text x="164.6" y="407" class="edge-protocol" text-anchor="middle">via filesystem</text></g><g data-relationship-id="handlers-crud-user-skills"><title>list and mutate custom skills · via database</title><path d="M 320.0 360 L 430 390 L 433 390 L 432.5 430" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 430.0 390.0 L 520 390" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="397.8" y="366.0" width="244.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="520" y="387" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">list and mutate custom skills</text><text x="520" y="407" class="edge-protocol" text-anchor="middle">via database</text></g><g data-relationship-id="handlers-refresh-cache"><title>query results and lifecycle invalidation · via WebSocket</title><path d="M 110 280.0 L 90 280 L 90 715 L 110 715.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="106.0" y="591.0" width="328.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="270" y="612" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">query results and lifecycle invalidation</text><text x="270" y="632" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="cache-builds-projection"><title>cached folder, user, and content records</title><path d="M 530 715.0 L 650 695.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 590.0 690.0 L 590 852" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="426.0" y="837.0" width="328.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="590" y="855" class="edge-label" text-anchor="middle" textLength="310.0" lengthAdjust="spacingAndGlyphs">cached folder, user, and content records</text></g><g data-relationship-id="projection-populates-catalogue"><title>render and filter rows</title><path d="M 810.0 620 L 810.0 530" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="714.4" y="560.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="810" y="578" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">render and filter rows</text></g><g data-relationship-id="catalogue-selects-editor"><title>select skill</title><path d="M 970 365.0 L 1010 365.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 990.0 350.0 L 990 139.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="930.0" y="124.0" width="120" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="990" y="142.0" class="edge-label" text-anchor="middle" textLength="102.0" lengthAdjust="spacingAndGlyphs">select skill</text></g><g data-relationship-id="catalogue-writes-toggle"><title>toggle enabled / keep required</title><path d="M 810.0 530 L 810 570 L 990 570 L 990 695 L 1010 695.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 900.0 560.0 L 1080 560" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="954.0" y="545.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1080" y="563" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">toggle enabled / keep required</text></g><g data-relationship-id="editor-writes-instructions"><title>write instructions + customized flag</title><path d="M 1170.0 530 L 1170.0 620" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1170.0 575.0 L 1170 845" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1021.2" y="830.0" width="297.59999999999997" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1170" y="848" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">write instructions + customized flag</text></g><g data-relationship-id="editor-user-skill-crud"><title>create / update / delete user skill · via WebSocket</title><path d="M 1170.0 200 L 1170 170 L 320 170 L 320.0 200" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 750.0 165.0 L 1200 165" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1055.0" y="141.0" width="290.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1200" y="162" class="edge-label" text-anchor="middle" textLength="272.0" lengthAdjust="spacingAndGlyphs">create / update / delete user skill</text><text x="1200" y="182" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="config-expands"><title>expand enabled entries</title><path d="M 1330 695.0 L 1385 695 L 1385 275 L 1450 275.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1385.0 485.0 L 1295 593" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1199.4" y="578.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1295" y="596" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">expand enabled entries</text></g><g data-relationship-id="expander-builds-runtime"><title>descriptors + Skill tool catalogue</title><path d="M 1630.0 350 L 1630.0 430" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1488.8" y="375.0" width="282.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1630" y="393" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">descriptors + Skill tool catalogue</text></g><g data-relationship-id="runtime-publishes-status"><title>loading / loaded / used / failed · via node status + CloudEvents</title><path d="M 1630.0 590 L 1630.0 660" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1496.4" y="601.0" width="267.2" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1630" y="622" class="edge-label" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">loading / loaded / used / failed</text><text x="1630" y="642" class="edge-protocol" text-anchor="middle" textLength="249.2" lengthAdjust="spacingAndGlyphs">via node status + CloudEvents</text></g><g data-relationship-id="status-back-to-catalogue"><title>project safe state onto matching row</title><path d="M 1630.0 780 L 1630 840 L 595 840 L 595 365 L 650 365.0" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1090.0 835.0 L 1540 835" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1391.2" y="820.0" width="297.59999999999997" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1540" y="838" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">project safe state onto matching row</text></g><g data-component-id="skill-ws-handlers"><title>Skill WebSocket handlers</title><rect x="110" y="200" width="420" height="160" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="110" y="200" width="420" height="7" rx="4" fill="#bd93f9"/><text x="128" y="226" class="type-label">SERVICE</text><text x="128" y="252" class="node-label">Skill WebSocket</text><text x="128" y="274" class="node-label">handlers</text><text x="128" y="300" class="node-detail">list / scan / get content</text><text x="128" y="320" class="node-detail">create / update / delete</text><text x="128" y="340" class="node-detail">skill_lifecycle broadcasts</text></g><g data-component-id="builtin-skill-files"><title>Built-in SKILL.md</title><rect x="110" y="430" width="195" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="430" width="195" height="7" rx="4" fill="#ff79c6"/><text x="128" y="456" class="type-label">SOURCE</text><text x="128" y="482" class="node-label">Built-in</text><text x="128" y="504" class="node-label">SKILL.md</text><text x="128" y="530" class="node-detail">server/skills/*</text><text x="128" y="550" class="node-detail" textLength="159.0" lengthAdjust="spacingAndGlyphs">metadata + instructions</text></g><g data-component-id="user-skill-store"><title>User skill store</title><rect x="335" y="430" width="195" height="150" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="335" y="430" width="195" height="7" rx="4" fill="#ff79c6"/><text x="353" y="456" class="type-label">DATABASE</text><text x="353" y="482" class="node-label">User skill</text><text x="353" y="504" class="node-label">store</text><text x="353" y="530" class="node-detail">custom records</text><text x="353" y="550" class="node-detail" textLength="159.0" lengthAdjust="spacingAndGlyphs">display + instructions</text></g><g data-component-id="tanstack-skill-cache"><title>TanStack skill caches</title><rect x="110" y="650" width="420" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="650" width="420" height="7" rx="4" fill="#ff79c6"/><text x="128" y="676" class="type-label">CLIENT STATE</text><text x="128" y="702" class="node-label">TanStack skill caches</text><text x="128" y="728" class="node-detail">userSkills · folderSkills</text><text x="128" y="748" class="node-detail">skillContent by name</text></g><g data-component-id="skill-catalogue-pane"><title>Skills catalogue pane</title><rect x="650" y="200" width="320" height="330" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="650" y="200" width="320" height="7" rx="4" fill="#8be9fd"/><text x="668" y="226" class="type-label">INTERFACE</text><text x="668" y="252" class="node-label">Skills catalogue</text><text x="668" y="274" class="node-label">pane</text><text x="668" y="300" class="node-detail">folder selector + search</text><text x="668" y="320" class="node-detail">enable / required / custom</text><text x="668" y="340" class="node-detail">Loading · Loaded · Failed</text><text x="668" y="360" class="node-detail">enabled count + create</text></g><g data-component-id="instructions-editor-pane"><title>Instructions editor pane</title><rect x="1010" y="200" width="320" height="330" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1010" y="200" width="320" height="7" rx="4" fill="#8be9fd"/><text x="1028" y="226" class="type-label">INTERFACE</text><text x="1028" y="252" class="node-label">Instructions editor</text><text x="1028" y="274" class="node-label">pane</text><text x="1028" y="300" class="node-detail">authoritative markdown</text><text x="1028" y="320" class="node-detail">create / edit / delete</text><text x="1028" y="340" class="node-detail">reset built-in default</text><text x="1028" y="360" class="node-detail">customized state</text></g><g data-component-id="query-projection"><title>Catalogue projection</title><rect x="650" y="620" width="320" height="150" rx="12" fill="#ffffff" stroke="#9aa1ac" stroke-width="2"/><rect x="650" y="620" width="320" height="7" rx="4" fill="#9aa1ac"/><text x="668" y="646" class="type-label">VIEW MODEL</text><text x="668" y="672" class="node-label">Catalogue projection</text><text x="668" y="698" class="node-detail">folder rows + user rows</text><text x="668" y="718" class="node-detail">selected skill buffer</text></g><g data-component-id="skills-config"><title>Master Skill skills_config</title><rect x="1010" y="620" width="320" height="150" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="1010" y="620" width="320" height="7" rx="4" fill="#f1fa8c"/><text x="1028" y="646" class="type-label">NODE PARAMS</text><text x="1028" y="672" class="node-label">Master Skill</text><text x="1028" y="694" class="node-label">skills_config</text><text x="1028" y="720" class="node-detail">enabled · instructions</text><text x="1028" y="740" class="node-detail">isCustomized · required</text></g><g data-component-id="master-skill-expander"><title>Master Skill expander</title><rect x="1450" y="200" width="360" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1450" y="200" width="360" height="7" rx="4" fill="#ffb86c"/><text x="1468" y="226" class="type-label">RUNTIME</text><text x="1468" y="252" class="node-label">Master Skill</text><text x="1468" y="274" class="node-label">expander</text><text x="1468" y="300" class="node-detail">enabled entries only</text><text x="1468" y="320" class="node-detail">per-skill descriptors</text></g><g data-component-id="agent-skill-runtime"><title>Agent Skill runtime</title><rect x="1450" y="430" width="360" height="160" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="1450" y="430" width="360" height="7" rx="4" fill="#bd93f9"/><text x="1468" y="456" class="type-label">TOOL RUNTIME</text><text x="1468" y="482" class="node-label">Agent Skill runtime</text><text x="1468" y="508" class="node-detail">progressive load</text><text x="1468" y="528" class="node-detail">declared resources</text><text x="1468" y="548" class="node-detail">bounded safe events</text></g><g data-component-id="skill-status-projection"><title>Exact-node status projection</title><rect x="1450" y="660" width="360" height="120" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1450" y="660" width="360" height="7" rx="4" fill="#ff79c6"/><text x="1468" y="686" class="type-label">OBSERVABILITY</text><text x="1468" y="712" class="node-label">Exact-node status</text><text x="1468" y="734" class="node-label">projection</text><text x="1468" y="760" class="node-detail">active_skills / last_skills</text></g><g data-callout-id="master-skill-invariant"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Configuration is authoritative; observability is sanitized</text><text x="86" y="936" class="callout-text">skills_config keeps the enabled flag and instruction body used by the connected agent.</text><text x="86" y="958" class="callout-text">Runtime events expose names and states only—never prompts, arguments, results, secrets, or raw exceptions.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/13-workspace-files.svg b/docs/diagrams/v2/light/13-workspace-files.svgnew file mode 100644index 00000000..3ae28c97--- /dev/null+++ b/docs/diagrams/v2/light/13-workspace-files.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="c97fa2af80f57078">+<title id="title">Workspace Files — light theme</title>+<desc id="desc">Source-backed anatomy of the Gallery node’s Workspace Files panel, separating WebSocket listing/search from HTTP content and upload routes while showing how controlled path and selection parameters drive the Gallery node’s FileRef output. Sources: client/src/components/parameterPanel/GalleryPanel.tsx; client/src/components/parameterPanel/gallery/WorkspaceBrowser.tsx; server/nodes/filesystem/gallery/_handlers.py; server/nodes/filesystem/gallery/_service.py; server/nodes/filesystem/gallery/__init__.py; server/nodes/filesystem/_backend.py; server/routers/workspace.py; docs-internal/node-logic-flows/code_fs_process/gallery.md</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Workspace Files</text>+<text x="72" y="91" class="subtitle">Browse, search, upload, preview, pin, and emit files from the workflow’s contained workspace.</text>+<g data-group-id="workspace-panel"><rect x="70" y="130" width="900" height="700" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="90" y="162" class="group-label">GALLERY NODE · WORKSPACE FILES PANEL</text></g><g data-group-id="workspace-transport"><rect x="1010" y="130" width="840" height="420" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="1030" y="162" class="group-label">WORKSPACE TRANSPORT + STORAGE</text></g><g data-group-id="gallery-execution"><rect x="1010" y="590" width="840" height="240" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="1030" y="622" class="group-label">WORKFLOW EXECUTION PATH</text></g><g data-relationship-id="header-opens-upload"><title>Upload action</title><path d="M 520.0 300 L 790 325 L 790.0 350" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="728.6" y="310.0" width="122.8" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="790" y="328" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">Upload action</text></g><g data-relationship-id="browser-activates-file"><title>activate, pin, or drag file</title><path d="M 610 525.0 L 650 525.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 630.0 505.0 L 1080 559" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="965.4" y="544.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1080" y="562" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">activate, pin, or drag file</text></g><g data-relationship-id="browser-requests-listing"><title>browse path or send debounced search · via WebSocket</title><path d="M 360.0 350 L 360 325 L 990 325 L 990 265 L 1050 265.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 780.0 315.0 L 780 153" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="631.2" y="129.0" width="297.59999999999997" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="780" y="150" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">browse path or send debounced search</text><text x="780" y="170" class="edge-protocol" text-anchor="middle">via WebSocket</text></g><g data-relationship-id="handler-selects-listing-mode"><title>directory list or recursive search</title><path d="M 1220.0 330 L 1220.0 390" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1078.8" y="345.0" width="282.4" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1220" y="363" class="edge-label" text-anchor="middle" textLength="264.4" lengthAdjust="spacingAndGlyphs">directory list or recursive search</text></g><g data-relationship-id="listing-reads-workspace"><title>contained ls_info / glob_info · via async filesystem</title><path d="M 1390 455.0 L 1450 455.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1420.0 450.0 L 1420 558" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1297.8" y="534.0" width="244.39999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1420" y="555" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">contained ls_info / glob_info</text><text x="1420" y="575" class="edge-protocol" text-anchor="middle">via async filesystem</text></g><g data-relationship-id="actions-use-http"><title>upload, preview, or download · via HTTP</title><path d="M 930 525.0 L 990 525 L 990 265 L 1450 265.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 990.0 385.0 L 1440 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1321.6" y="124.0" width="236.79999999999998" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1440" y="145.0" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">upload, preview, or download</text><text x="1440" y="165.0" class="edge-protocol" text-anchor="middle">via HTTP</text></g><g data-relationship-id="http-reads-writes-workspace"><title>write upload or stream content</title><path d="M 1630.0 330 L 1630.0 390" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1504.0" y="345.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1630" y="363" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">write upload or stream content</text></g><g data-relationship-id="browser-controls-path"><title>navigation writes path</title><path d="M 360.0 700 L 360 720 L 280 720 L 280 775 L 300 775.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 355.0 715.0 L 175 769" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="79.4" y="754.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="175" y="772" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">navigation writes path</text></g><g data-relationship-id="actions-control-selection"><title>pinning writes selection</title><path d="M 790.0 700 L 790 720 L 760 720 L 760 775 L 740 775.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 760.0 715.0 L 940 823" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="836.8" y="808.0" width="206.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="940" y="826" class="edge-label" text-anchor="middle" textLength="188.4" lengthAdjust="spacingAndGlyphs">pinning writes selection</text></g><g data-relationship-id="params-drive-gallery-run"><title>run with path / selection</title><path d="M 740 775.0 L 980 775 L 980 710 L 1050 710.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="768.0" y="750.0" width="214.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="875" y="768" class="edge-label" text-anchor="middle" textLength="196.0" lengthAdjust="spacingAndGlyphs">run with path / selection</text></g><g data-relationship-id="gallery-reuses-listing-service"><title>reuse listing and FileRef conversion</title><path d="M 1220.0 650 L 1220.0 520" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1220.0 585.0 L 1220 801" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1071.2" y="786.0" width="297.59999999999997" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1220" y="804" class="edge-label" text-anchor="middle" textLength="279.6" lengthAdjust="spacingAndGlyphs">reuse listing and FileRef conversion</text></g><g data-relationship-id="gallery-emits-output"><title>emit selected or listed files</title><path d="M 1390 710.0 L 1450 710.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1420.0 710.0 L 1420 602" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1297.8" y="587.0" width="244.39999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1420" y="605" class="edge-label" text-anchor="middle" textLength="226.4" lengthAdjust="spacingAndGlyphs">emit selected or listed files</text></g><g data-component-id="workspace-panel-header"><title>Workspace Files header</title><rect x="110" y="200" width="820" height="100" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="200" width="820" height="7" rx="4" fill="#8be9fd"/><text x="128" y="226" class="type-label">INTERFACE</text><text x="128" y="252" class="node-label">Workspace Files header</text><text x="128" y="278" class="node-detail">workflow-produced files · Upload action</text></g><g data-component-id="workspace-browser"><title>WorkspaceBrowser</title><rect x="110" y="350" width="500" height="350" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="110" y="350" width="500" height="7" rx="4" fill="#8be9fd"/><text x="128" y="376" class="type-label">INTERFACE</text><text x="128" y="402" class="node-label">WorkspaceBrowser</text><text x="128" y="428" class="node-detail">breadcrumbs + directory navigation</text><text x="128" y="448" class="node-detail">250 ms search · whole workspace</text><text x="128" y="468" class="node-detail">grid / list · refresh · 5 s poll</text><text x="128" y="488" class="node-detail">empty, missing, truncated states</text></g><g data-component-id="workspace-file-actions"><title>File actions</title><rect x="650" y="350" width="280" height="350" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="650" y="350" width="280" height="7" rx="4" fill="#50fa7b"/><text x="668" y="376" class="type-label">INTERFACE</text><text x="668" y="402" class="node-label">File actions</text><text x="668" y="428" class="node-detail">upload one or many</text><text x="668" y="448" class="node-detail">preview / download</text><text x="668" y="468" class="node-detail">pin for node output</text><text x="668" y="488" class="node-detail">FileRef drag payload</text></g><g data-component-id="gallery-node-parameters"><title>Node params: path + selection</title><rect x="300" y="740" width="440" height="70" rx="12" fill="#ffffff" stroke="#f1fa8c" stroke-width="2"/><rect x="300" y="740" width="440" height="7" rx="4" fill="#f1fa8c"/><text x="318" y="766" class="type-label">NODE PARAMS</text><text x="318" y="792" class="node-label">Node params · path + selection</text></g><g data-component-id="list-workspace-files-handler"><title>list_workspace_files</title><rect x="1050" y="200" width="340" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1050" y="200" width="340" height="7" rx="4" fill="#ff79c6"/><text x="1068" y="226" class="type-label">WEBSOCKET</text><text x="1068" y="252" class="node-label">list_workspace_files</text><text x="1068" y="278" class="node-detail">path or workspace-wide search</text><text x="1068" y="298" class="node-detail">limit 500 from panel</text></g><g data-component-id="workspace-http-routes"><title>Workspace HTTP routes</title><rect x="1450" y="200" width="360" height="130" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1450" y="200" width="360" height="7" rx="4" fill="#8be9fd"/><text x="1468" y="226" class="type-label">HTTP</text><text x="1468" y="252" class="node-label">Workspace HTTP routes</text><text x="1468" y="278" class="node-detail">POST uploads</text><text x="1468" y="298" class="node-detail">GET content · Range</text></g><g data-component-id="workspace-listing-service"><title>Workspace listing service</title><rect x="1050" y="390" width="340" height="130" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="1050" y="390" width="340" height="7" rx="4" fill="#bd93f9"/><text x="1068" y="416" class="type-label">SERVICE</text><text x="1068" y="442" class="node-label">Workspace listing</text><text x="1068" y="464" class="node-label">service</text><text x="1068" y="490" class="node-detail">directory or recursive glob</text><text x="1068" y="510" class="node-detail">sort, cap, crumbs, preview</text></g><g data-component-id="contained-workspace-root"><title>Contained workflow workspace</title><rect x="1450" y="390" width="360" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="1450" y="390" width="360" height="7" rx="4" fill="#ff79c6"/><text x="1468" y="416" class="type-label">FILESYSTEM</text><text x="1468" y="442" class="node-label">Contained workflow</text><text x="1468" y="464" class="node-label">workspace</text><text x="1468" y="490" class="node-detail">WorkspaceBackend</text><text x="1468" y="510" class="node-detail">workspace-relative paths</text></g><g data-component-id="gallery-node-runtime"><title>Gallery node execution</title><rect x="1050" y="650" width="340" height="120" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="1050" y="650" width="340" height="7" rx="4" fill="#ffb86c"/><text x="1068" y="676" class="type-label">RUNTIME</text><text x="1068" y="702" class="node-label">Gallery node</text><text x="1068" y="724" class="node-label">execution</text><text x="1068" y="750" class="node-detail">selection > pattern > directory</text></g><g data-component-id="gallery-file-ref-output"><title>Downstream FileRef output</title><rect x="1450" y="650" width="360" height="120" rx="12" fill="#ffffff" stroke="#50fa7b" stroke-width="2"/><rect x="1450" y="650" width="360" height="7" rx="4" fill="#50fa7b"/><text x="1468" y="676" class="type-label">RESULT</text><text x="1468" y="702" class="node-label">Downstream FileRef</text><text x="1468" y="724" class="node-label">output</text><text x="1468" y="750" class="node-detail">files · directories · missing[]</text></g><g data-callout-id="workspace-channel-contract"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Two channels, one contained workspace</text><text x="86" y="936" class="callout-text">WebSocket owns listing and search; HTTP owns upload and file bytes for preview, download, and Range requests.</text><text x="86" y="958" class="callout-text">Rows arrive with a server-built FileRef and preview verdict, so the client does not duplicate path or security decisions.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>diff --git a/docs/diagrams/v2/light/14-runtime-observability-dock.svg b/docs/diagrams/v2/light/14-runtime-observability-dock.svgnew file mode 100644index 00000000..5eb79fe9--- /dev/null+++ b/docs/diagrams/v2/light/14-runtime-observability-dock.svg@@ -0,0 +1,25 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="100%" role="img" aria-labelledby="title desc" data-theme="light" data-geometry-signature="66d4ac8c11b8cc0a">+<title id="title">Runtime Observability Dock — light theme</title>+<desc id="desc">Source-backed topology of the collapsible Chat / Console dock: chat messages, Console node records, and terminal logs use distinct producers and retention paths, converge in WebSocketContext state, and render in a resizable chat pane plus Console and Terminal tabs with targeted filters and clear actions. Sources: client/src/components/ui/ConsolePanel.tsx; client/src/contexts/WebSocketContext.tsx; server/nodes/utility/console/__init__.py; server/services/status_broadcaster.py; server/routers/websocket.py; server/nodes/trigger/chat_trigger/_events.py; server/services/process_service.py; server/core/logging.py; docs-internal/node-logic-flows/chat_utility/console.md</desc>+<defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#374151"/></marker>+ <style>+ .title { fill:#1a1d21; font:700 30px Geist,system-ui,sans-serif; }+ .subtitle { fill:#4b5563; font:400 18px Geist,system-ui,sans-serif; }+ .group-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:1.2px; }+ .type-label { fill:#4b5563; font:600 16px 'JetBrains Mono',ui-monospace,monospace; letter-spacing:.8px; }+ .node-label { fill:#1a1d21; font:650 20px Geist,system-ui,sans-serif; }+ .node-detail { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .edge-label { fill:#1a1d21; font:500 16px Geist,system-ui,sans-serif; }+ .edge-protocol { fill:#4b5563; font:500 16px 'JetBrains Mono',ui-monospace,monospace; }+ .callout-title { fill:#1a1d21; font:650 18px Geist,system-ui,sans-serif; }+ .callout-text { fill:#4b5563; font:400 16px Geist,system-ui,sans-serif; }+ .legend { fill:#4b5563; font:500 16px Geist,system-ui,sans-serif; }+ </style>+</defs>+<rect width="1920" height="1080" fill="#f5f7fa"/>+<text x="72" y="58" class="title">Runtime Observability Dock</text>+<text x="72" y="91" class="subtitle">One resizable dock combines workflow chat, Console-node output, and live server/process logs without conflating their scopes.</text>+<g data-group-id="runtime-producers"><rect x="70" y="130" width="460" height="700" rx="18" fill="#fafbfc" stroke="#ffb86c" stroke-width="2"/><text x="90" y="162" class="group-label">RUNTIME PRODUCERS + CONSUMERS</text></g><g data-group-id="observability-transport"><rect x="570" y="130" width="590" height="700" rx="18" fill="#fafbfc" stroke="#bd93f9" stroke-width="2"/><text x="590" y="162" class="group-label">TRANSPORT + RETAINED STATE</text></g><g data-group-id="observability-dock"><rect x="1200" y="130" width="650" height="700" rx="18" fill="#fafbfc" stroke="#8be9fd" stroke-width="2"/><text x="1220" y="162" class="group-label">COLLAPSIBLE CHAT / CONSOLE DOCK</text></g><g data-relationship-id="console-broadcasts-log"><title>broadcast_console_log</title><path d="M 490 275.0 L 610 280.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 265.0 L 460 373" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="368.2" y="358.0" width="183.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="460" y="376" class="edge-label" text-anchor="middle" textLength="165.6" lengthAdjust="spacingAndGlyphs">broadcast_console_log</text></g><g data-relationship-id="runtime-broadcasts-terminal"><title>broadcast_terminal_log</title><path d="M 490 505.0 L 550 505 L 550 315 L 610 280.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 550.0 410.0 L 640 410" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="544.4" y="395.0" width="191.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="640" y="413" class="edge-label" text-anchor="middle" textLength="173.2" lengthAdjust="spacingAndGlyphs">broadcast_terminal_log</text></g><g data-relationship-id="broadcaster-persists-console"><title>persist Console records</title><path d="M 730.0 360 L 730.0 440" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 730.0 400.0 L 910 400" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="810.6" y="385.0" width="198.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="910" y="403" class="edge-label" text-anchor="middle" textLength="180.8" lengthAdjust="spacingAndGlyphs">persist Console records</text></g><g data-relationship-id="broadcaster-retains-terminal"><title>retain latest Terminal records</title><path d="M 850 280.0 L 870 280 L 870 405 L 1005 405 L 1005.0 440" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 920.0 395.0 L 920 611" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="794.0" y="596.0" width="252.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="920" y="614" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">retain latest Terminal records</text></g><g data-relationship-id="handlers-query-db"><title>get / clear scoped history</title><path d="M 1005.0 360 L 1005 400 L 870 400 L 870 505 L 850 505.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 885.0 390.0 L 1065 174" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="954.2" y="159.0" width="221.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1065" y="177" class="edge-label" text-anchor="middle" textLength="203.6" lengthAdjust="spacingAndGlyphs">get / clear scoped history</text></g><g data-relationship-id="handlers-query-terminal-cache"><title>get / clear terminal history</title><path d="M 1005.0 360 L 1005.0 440" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1005.0 400.0 L 1005 139.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="886.6" y="124.0" width="236.79999999999998" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1005" y="142.0" class="edge-label" text-anchor="middle" textLength="218.8" lengthAdjust="spacingAndGlyphs">get / clear terminal history</text></g><g data-relationship-id="handlers-dispatch-chat-trigger"><title>dispatch chat_message_received · via workflow-scoped CloudEvent</title><path d="M 890 280.0 L 560 280 L 560 720 L 490 720.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 560.0 600.0 L 560 816" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="434.0" y="792.0" width="252.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="560" y="813" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">dispatch chat_message_received</text><text x="560" y="833" class="edge-protocol" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">via workflow-scoped CloudEvent</text></g><g data-relationship-id="live-events-update-context"><title>live console_log / terminal_log · via WebSocket broadcast</title><path d="M 610 280.0 L 590 280 L 590 720 L 760 720.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 675.0 625.0 L 585 625" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="455.2" y="601.0" width="259.6" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="585" y="622" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">live console_log / terminal_log</text><text x="585" y="642" class="edge-protocol" text-anchor="middle">via WebSocket broadcast</text></g><g data-relationship-id="handlers-hydrate-context"><title>hydrate on connect or workflow switch</title><path d="M 1120 280.0 L 1140 280 L 1140 630 L 890 630 L 890.0 660" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1135.0 520.0 L 1045 790" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="892.4" y="775.0" width="305.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1045" y="793" class="edge-label" text-anchor="middle" textLength="287.2" lengthAdjust="spacingAndGlyphs">hydrate on connect or workflow switch</text></g><g data-relationship-id="chat-sends-handler-request"><title>send_chat_message / clear chat · via WebSocket request</title><path d="M 1370.0 200 L 1370 165 L 1005 165 L 1005.0 200" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1190.0 160.0 L 1640 148.0" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1514.0" y="124.0" width="252.0" height="48" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1640" y="145.0" class="edge-label" text-anchor="middle" textLength="234.0" lengthAdjust="spacingAndGlyphs">send_chat_message / clear chat</text><text x="1640" y="165.0" class="edge-protocol" text-anchor="middle">via WebSocket request</text></g><g data-relationship-id="context-renders-chat"><title>chat messages</title><path d="M 1020 720.0 L 1180 720 L 1180 450 L 1240 450.0" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1180.0 585.0 L 1090 693" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1028.6" y="678.0" width="122.8" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1090" y="696" class="edge-label" text-anchor="middle" textLength="104.8" lengthAdjust="spacingAndGlyphs">chat messages</text></g><g data-relationship-id="context-renders-console"><title>Console records</title><path d="M 890.0 660 L 890 610 L 1175 610 L 1175 145 L 1675 145 L 1675.0 200" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><path d="M 1510.0 140.0 L 1839.0 140" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1770.0" y="125.0" width="138.0" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1839.0" y="143" class="edge-label" text-anchor="middle" textLength="120.0" lengthAdjust="spacingAndGlyphs">Console records</text></g><g data-relationship-id="context-renders-terminal"><title>Terminal records</title><path d="M 890.0 780 L 890 845 L 1675 845 L 1675.0 700" fill="none" stroke="#374151" stroke-width="2" marker-end="url(#arrow)"/><rect x="1407.2" y="825.0" width="145.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1480" y="843" class="edge-label" text-anchor="middle" textLength="127.6" lengthAdjust="spacingAndGlyphs">Terminal records</text></g><g data-relationship-id="prefs-shape-chat-pane"><title>height + split width + font</title><path d="M 1240 765.0 L 1220 775 L 1220 720 L 1370 720 L 1370.0 700" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1300.0 715.0 L 1030 823" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="915.4" y="808.0" width="229.2" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1030" y="826" class="edge-label" text-anchor="middle" textLength="211.2" lengthAdjust="spacingAndGlyphs">height + split width + font</text></g><g data-relationship-id="prefs-select-log-tab"><title>selected Console / Terminal tab</title><path d="M 1810 765.0 L 1830 775 L 1830 720 L 1675 720 L 1675.0 700" fill="none" stroke="#374151" stroke-width="2" stroke-dasharray="10 8" marker-end="url(#arrow)"/><path d="M 1725.0 715.0 L 1778.2 445" fill="none" stroke="#4b5563" stroke-width="1" stroke-dasharray="3 4" opacity=".7"/><rect x="1648.4" y="430.0" width="259.6" height="30" rx="7" fill="#ffffff" stroke="#d1d5db"/><text x="1778.2" y="448" class="edge-label" text-anchor="middle" textLength="241.6" lengthAdjust="spacingAndGlyphs">selected Console / Terminal tab</text></g><g data-component-id="console-node-producer"><title>Console node output</title><rect x="110" y="200" width="380" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="110" y="200" width="380" height="7" rx="4" fill="#ffb86c"/><text x="128" y="226" class="type-label">WORKFLOW</text><text x="128" y="252" class="node-label">Console node output</text><text x="128" y="278" class="node-detail">label · format · formatted data</text><text x="128" y="298" class="node-detail">workflow + source node IDs</text></g><g data-component-id="terminal-log-producers"><title>Server / process / CLI logs</title><rect x="110" y="430" width="380" height="150" rx="12" fill="#ffffff" stroke="#ffb86c" stroke-width="2"/><rect x="110" y="430" width="380" height="7" rx="4" fill="#ffb86c"/><text x="128" y="456" class="type-label">RUNTIME</text><text x="128" y="482" class="node-label">Server / process / CLI</text><text x="128" y="504" class="node-label">logs</text><text x="128" y="530" class="node-detail">level · message · source</text><text x="128" y="550" class="node-detail">optional details</text></g><g data-component-id="chat-trigger-consumers"><title>chatTrigger consumers</title><rect x="110" y="660" width="380" height="120" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="110" y="660" width="380" height="7" rx="4" fill="#ff79c6"/><text x="128" y="686" class="type-label">TRIGGER</text><text x="128" y="712" class="node-label">chatTrigger consumers</text><text x="128" y="738" class="node-detail">workflow-scoped CloudEvent</text></g><g data-component-id="status-broadcaster"><title>StatusBroadcaster</title><rect x="610" y="200" width="240" height="160" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="610" y="200" width="240" height="7" rx="4" fill="#ff79c6"/><text x="628" y="226" class="type-label">EVENT BUS</text><text x="628" y="252" class="node-label">StatusBroadcaster</text><text x="628" y="278" class="node-detail">console_log</text><text x="628" y="298" class="node-detail">terminal_log</text><text x="628" y="318" class="node-detail">clear broadcasts</text></g><g data-component-id="dock-ws-handlers"><title>Dock WebSocket handlers</title><rect x="890" y="200" width="230" height="160" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="890" y="200" width="230" height="7" rx="4" fill="#bd93f9"/><text x="908" y="226" class="type-label">SERVICE</text><text x="908" y="252" class="node-label">Dock WebSocket</text><text x="908" y="274" class="node-label">handlers</text><text x="908" y="300" class="node-detail">send / get / clear</text><text x="908" y="320" class="node-detail" textLength="194.0" lengthAdjust="spacingAndGlyphs">chat · console · terminal</text></g><g data-component-id="workflow-history-db"><title>Workflow history DB</title><rect x="610" y="440" width="240" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="610" y="440" width="240" height="7" rx="4" fill="#ff79c6"/><text x="628" y="466" class="type-label">DATABASE</text><text x="628" y="492" class="node-label" textLength="204.0" lengthAdjust="spacingAndGlyphs">Workflow history DB</text><text x="628" y="518" class="node-detail">chat_messages</text><text x="628" y="538" class="node-detail">console_logs</text></g><g data-component-id="terminal-ring-buffer"><title>Terminal ring buffer</title><rect x="890" y="440" width="230" height="130" rx="12" fill="#ffffff" stroke="#ff79c6" stroke-width="2"/><rect x="890" y="440" width="230" height="7" rx="4" fill="#ff79c6"/><text x="908" y="466" class="type-label">MEMORY</text><text x="908" y="492" class="node-label">Terminal ring</text><text x="908" y="514" class="node-label">buffer</text><text x="908" y="540" class="node-detail">latest 200 entries</text><text x="908" y="560" class="node-detail">global in process</text></g><g data-component-id="websocket-context-state"><title>WebSocketContext state</title><rect x="760" y="660" width="260" height="120" rx="12" fill="#ffffff" stroke="#bd93f9" stroke-width="2"/><rect x="760" y="660" width="260" height="7" rx="4" fill="#bd93f9"/><text x="778" y="686" class="type-label">CLIENT STATE</text><text x="778" y="712" class="node-label">WebSocketContext</text><text x="778" y="734" class="node-label">state</text><text x="778" y="760" class="node-detail" textLength="224.0" lengthAdjust="spacingAndGlyphs">chat · console · terminal arrays</text></g><g data-component-id="chat-pane"><title>Chat pane</title><rect x="1240" y="200" width="260" height="500" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1240" y="200" width="260" height="7" rx="4" fill="#8be9fd"/><text x="1258" y="226" class="type-label">INTERFACE</text><text x="1258" y="252" class="node-label">Chat pane</text><text x="1258" y="278" class="node-detail" textLength="224.0" lengthAdjust="spacingAndGlyphs">All Triggers or one target</text><text x="1258" y="298" class="node-detail">user + assistant messages</text><text x="1258" y="318" class="node-detail">Enter to send</text><text x="1258" y="338" class="node-detail">clear current workflow</text></g><g data-component-id="console-tab"><title>Console tab</title><rect x="1540" y="200" width="270" height="230" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1540" y="200" width="270" height="7" rx="4" fill="#8be9fd"/><text x="1558" y="226" class="type-label">INTERFACE</text><text x="1558" y="252" class="node-label">Console tab</text><text x="1558" y="278" class="node-detail">filter by Console node</text><text x="1558" y="298" class="node-detail">search + pretty print</text><text x="1558" y="318" class="node-detail">workflow-scoped clear</text></g><g data-component-id="terminal-tab"><title>Terminal tab</title><rect x="1540" y="470" width="270" height="230" rx="12" fill="#ffffff" stroke="#8be9fd" stroke-width="2"/><rect x="1540" y="470" width="270" height="7" rx="4" fill="#8be9fd"/><text x="1558" y="496" class="type-label">INTERFACE</text><text x="1558" y="522" class="node-label">Terminal tab</text><text x="1558" y="548" class="node-detail">level threshold</text><text x="1558" y="568" class="node-detail">message / source search</text><text x="1558" y="588" class="node-detail">global clear</text></g><g data-component-id="dock-preferences"><title>Persisted dock preferences</title><rect x="1240" y="720" width="570" height="90" rx="12" fill="#ffffff" stroke="#9aa1ac" stroke-width="2"/><rect x="1240" y="720" width="570" height="7" rx="4" fill="#9aa1ac"/><text x="1258" y="746" class="type-label">LOCAL STATE</text><text x="1258" y="772" class="node-label">Persisted dock preferences</text><text x="1258" y="798" class="node-detail">height · split width · font · autoscroll · pretty print · tab</text></g><g data-callout-id="observability-scope-contract"><rect x="70" y="880" width="1780" height="90" rx="10" fill="#ffffff" stroke="#f1fa8c" stroke-width="2" stroke-dasharray="7 6"/><text x="86" y="910" class="callout-title">Scope and retention stay deliberately distinct</text><text x="86" y="936" class="callout-text">Chat and Console history are persisted and scoped to the current workflow; Terminal history is a process-wide in-memory buffer of the latest 200 entries.</text><text x="86" y="958" class="callout-text">The dock persists only presentation preferences in localStorage—panel height, split width, font size, auto-scroll, pretty print, and selected log tab.</text></g>+<g aria-label="Legend"><circle cx="72" cy="1038" r="7" fill="#bd93f9"/><text x="86" y="1044" class="legend">Agents / system</text><circle cx="317" cy="1038" r="7" fill="#8be9fd"/><text x="331" y="1044" class="legend">Models / interfaces</text><circle cx="562" cy="1038" r="7" fill="#50fa7b"/><text x="576" y="1044" class="legend">Tools / results</text><circle cx="807" cy="1038" r="7" fill="#ff79c6"/><text x="821" y="1044" class="legend">Triggers / events</text><circle cx="1052" cy="1038" r="7" fill="#ffb86c"/><text x="1066" y="1044" class="legend">Workflow / runtime</text><circle cx="1297" cy="1038" r="7" fill="#f1fa8c"/><text x="1311" y="1044" class="legend">Security note</text></g>+</svg>