Skip to content

Self-improving AI Employees for everyone

docs: describe Normal mode and the approval gate

trohitga30bc4aeafd5
diff --git a/CLAUDE.md b/CLAUDE.md
index 0f2de582..7afccd4f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[UI Migration Plan](./docs-internal/ARCHIVE/ui_migration_plan.md)** | *Archived.* antd → shadcn/ui migration completion log (Waves 1–10). Current state lives in [Frontend Architecture](./docs-internal/frontend_architecture.md) and [Theme System](./docs-internal/theme_system.md). |
| **[Temporal Cleanup & Resilience Plan (Waves 15-18)](./docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md)** | *Archived — all four waves shipped.* 15 dead-code retirement (Redis-Streams branch in event_waiter, APScheduler cron stack, orphaned `connection_status` factory), 16 per-queue task routing (`TemporalWorkerPool`), 17 resilience hardening (cron `catchup_window`, SDK interceptors, `DEPLOYMENT_MODE`, periodic heartbeats; the one-shot LLM-step retry it records was later reverted to unlimited-with-backoff), 18 worker performance tuning. Current settings live in [Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md). |
| **[Node Allowlist](./docs-internal/node_allowlist.md)** | Single-config UI visibility — `server/config/node_allowlist.json` controls which nodes / credential categories / skill folders show in the UI. Five lists with two enforcement tiers (mode-gated allowlist + absolute blocklist). `useNodeAllowlist` hook exposes `isVisible` / `isBlocked` / `isAllowed` / `isCredentialCategoryDisabled` / `isSkillFolderDisabled`. Adding a new disabled domain = single JSON edit, no code change. |
+| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee card, the `approvalGate` "ask me before sending" step, run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields, consumer Connectors), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` broadcasts. |
| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (toggled by Dashboard's `visibilitychange` listener; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 inline SVG glyph strings across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), 12-theme docs (`guidelines/THEMES.md`), **the merged handoff brief (`HANDOFF.md` — glow-ladder traps, step-edge contract, toolbar layout traps, canvas-layer asymmetries, plus the recorded product amendments)**, and **the panel×theme fidelity target (`reference-mockup/Panel Theme Matrix.dc.html` — 17 panels × 12 themes, open in a browser)**. `reference/themes/` no longer vendors CSS snapshots — it points at the authoritative [client/src/themes/](./client/src/themes/). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |
| **[Schema Source of Truth RFC](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)** | *Archived — shipped.* Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons; `VITE_NODESPEC_BACKEND` defaults on and the frontend node definitions are gone. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Current reference: [Plugin System](./docs-internal/plugin_system.md). |
@@ -740,7 +741,7 @@ Workflows execute via Temporal for durability and horizontal scaling, gated by `
Execution routing falls back Temporal → sequential; the Temporal dev server + embedded worker are managed in-process under `server/services/temporal/` (pooch-downloaded CLI, single `temporal server start-dev` process, gRPC `TEMPORAL_FRONTEND_GRPC_PORT` + Web UI `TEMPORAL_UI_PORT`, SQLite at `~/.opencompany/temporal.db`). Full architecture, dispatch matrix, per-node + agent-loop lifecycle, the F4.B `agent.*` activities (unsuffixed since the AgentWorkflow fold; read the live set from `collect_agent_activities()` rather than a hardcoded count), heartbeat semantics, delegation input contract, the worker tuning recipe, and all `.env` tunables live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).
-**Months-long durability contract (July 2026).** Running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Load-bearing invariants: (1) `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` stays `false` (debug-only sweep; even enabled, any control row in the shared `WORKFLOW_CONTROL_ACTIVE_STATES` — including `resetting` — vetoes it). (2) New child workflow starts carry **no** `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so lifetime caps silently terminated paused runs; liveness comes from activity heartbeats (30s beat / 2min timeout), never from workflow lifetime caps. Removing/adding start options or retry policies on recorded commands requires a `workflow.patched(...)` guard (the only two live markers are `machina-conditional-edges-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py`). (3) Every long-lived workflow loop must continue-as-new under history pressure (`is_continue_as_new_suggested()` + a soft cap) — Temporal hard-terminates around ~51,200 history events; `WorkflowControlWorkflow` carries triggers/queued events/seen-ids/control state across rollovers, so controller handles are addressed **by workflow id only, never run_id-pinned**. (4) `dispatch.emit` skips controllers whose `ControlEventTypes` Search Attribute doesn't match the event (absent attribute = legacy match-all). (5) The Temporal lifecycle is owned by [services/temporal/lifecycle.py](./server/services/temporal/lifecycle.py) (`main.py` only schedules it): dev-server supervision + resident watchdog (`TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS`), worker crash-restarts that REBUILD the single-use SDK `Worker` per attempt (manager + every pool queue worker), and the boot-time `reconcile_active_controls_on_boot` pass (converges crash-stranded `starting` rows, re-arms running/paused generations from the persisted graph snapshot). (6) **Recovery policies** (env-driven, defaults in `.env.template`; full semantics in [temporal-workflow-control.md → Recovery policies](./docs-internal/temporal-workflow-control.md)): `WORKFLOW_CONTROL_CRASH_RECOVERY=pause` — after a kill/crash (dirty-bit marker cleared only by graceful teardown) boot recovers running generations as **paused** so the user consciously resumes; `WORKFLOW_CONTROL_MISSING_CONTROLLER=pause` — a killed/vanished controller converges the generation to paused and **Resume rebuilds the controller** (`WorkflowIdConflictPolicy.USE_EXISTING`, re-arm from snapshot) instead of forcing a state-archiving Reset; `WORKFLOW_CONTROL_PAUSE_ON_FAILURE=true` — repeatedly-failing trigger-spawned runs pause their deployment via the `workflow_control.pause_on_failure` activity (circuit breaker; trips only after `WORKFLOW_CONTROL_PAUSE_ON_FAILURE_THRESHOLD` (default 3) failures inside a rolling `_WINDOW_SECONDS` (default 600) so one node hiccup never pauses anything; Resume resets the streak; manual canvas runs never qualify). Temporal's native Pause/Unpause (server 1.28+) is deliberately NOT used — no Python SDK surface, and it halts workflow-task dispatch so a natively-paused controller couldn't process the resume Update. (7) **Workflow-scoped event delivery**: an envelope whose `workflow_id` is set by its producer's call site reaches only that workflow's consumers (`dispatch.emit` narrows both Visibility clauses by `EventWorkflowId`); chat is the first scoped producer — the decision lives in `routers/websocket.py`, the narrowing in core dispatch, and plugin `_events.py` factories only plumb the field (see [event_framework.md](./docs-internal/event_framework.md)). (8) **Canvas editability is the server-owned `can_edit` capability** emitted by `serialize_control` (paused = editable; starting/running/transitional = locked); the FE renders it via `lib/canvasLock.ts` + Dashboard's `guardCanvasEdit` and never re-derives the rule from state strings (see [temporal-workflow-control.md → Canvas editability](./docs-internal/temporal-workflow-control.md)). Locked by `tests/temporal/test_durability_hardening.py` + `test_worker_restart.py`.
+**Months-long durability contract (July 2026).** Running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Load-bearing invariants: (1) `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` stays `false` (debug-only sweep; even enabled, any control row in the shared `WORKFLOW_CONTROL_ACTIVE_STATES` — including `resetting` — vetoes it). (2) New child workflow starts carry **no** `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so lifetime caps silently terminated paused runs; liveness comes from activity heartbeats (30s beat / 2min timeout), never from workflow lifetime caps. Removing/adding start options or retry policies on recorded commands requires a `workflow.patched(...)` guard (the live markers are `machina-conditional-edges-v1` and `machina-run-record-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py`; verify with `grep -rn "workflow.patched(" server/services/temporal`). (3) Every long-lived workflow loop must continue-as-new under history pressure (`is_continue_as_new_suggested()` + a soft cap) — Temporal hard-terminates around ~51,200 history events; `WorkflowControlWorkflow` carries triggers/queued events/seen-ids/control state across rollovers, so controller handles are addressed **by workflow id only, never run_id-pinned**. (4) `dispatch.emit` skips controllers whose `ControlEventTypes` Search Attribute doesn't match the event (absent attribute = legacy match-all). (5) The Temporal lifecycle is owned by [services/temporal/lifecycle.py](./server/services/temporal/lifecycle.py) (`main.py` only schedules it): dev-server supervision + resident watchdog (`TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS`), worker crash-restarts that REBUILD the single-use SDK `Worker` per attempt (manager + every pool queue worker), and the boot-time `reconcile_active_controls_on_boot` pass (converges crash-stranded `starting` rows, re-arms running/paused generations from the persisted graph snapshot). (6) **Recovery policies** (env-driven, defaults in `.env.template`; full semantics in [temporal-workflow-control.md → Recovery policies](./docs-internal/temporal-workflow-control.md)): `WORKFLOW_CONTROL_CRASH_RECOVERY=pause` — after a kill/crash (dirty-bit marker cleared only by graceful teardown) boot recovers running generations as **paused** so the user consciously resumes; `WORKFLOW_CONTROL_MISSING_CONTROLLER=pause` — a killed/vanished controller converges the generation to paused and **Resume rebuilds the controller** (`WorkflowIdConflictPolicy.USE_EXISTING`, re-arm from snapshot) instead of forcing a state-archiving Reset; `WORKFLOW_CONTROL_PAUSE_ON_FAILURE=true` — repeatedly-failing trigger-spawned runs pause their deployment via the `workflow_control.pause_on_failure` activity (circuit breaker; trips only after `WORKFLOW_CONTROL_PAUSE_ON_FAILURE_THRESHOLD` (default 3) failures inside a rolling `_WINDOW_SECONDS` (default 600) so one node hiccup never pauses anything; Resume resets the streak; manual canvas runs never qualify). Temporal's native Pause/Unpause (server 1.28+) is deliberately NOT used — no Python SDK surface, and it halts workflow-task dispatch so a natively-paused controller couldn't process the resume Update. (7) **Workflow-scoped event delivery**: an envelope whose `workflow_id` is set by its producer's call site reaches only that workflow's consumers (`dispatch.emit` narrows both Visibility clauses by `EventWorkflowId`); chat is the first scoped producer — the decision lives in `routers/websocket.py`, the narrowing in core dispatch, and plugin `_events.py` factories only plumb the field (see [event_framework.md](./docs-internal/event_framework.md)). (8) **Canvas editability is the server-owned `can_edit` capability** emitted by `serialize_control` (paused = editable; starting/running/transitional = locked); the FE renders it via `lib/canvasLock.ts` + Dashboard's `guardCanvasEdit` and never re-derives the rule from state strings (see [temporal-workflow-control.md → Canvas editability](./docs-internal/temporal-workflow-control.md)). Locked by `tests/temporal/test_durability_hardening.py` + `test_worker_restart.py`.
**Temporal tracing ownership is strict.** Register the SDK `TracingInterceptor` exactly once on the shared `Client.connect(...)`; the Python SDK automatically prepends compatible client interceptors to every worker. Never repeat `TracingInterceptor` in `Worker(..., interceptors=...)`. Worker lists contain the distinct `ObservabilityWorkerInterceptor` and plugin-specific worker interceptors only. Exact paired `StartActivity` / `RunActivity` / `CompleteWorkflow` console spans with identical Temporal identities indicate duplicate instrumentation, not duplicate execution; use Temporal Event History and the `node.<type>.execute` application span to verify actual attempts. See the tracing and debugging sections in [TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md) and [errors.md](./docs-internal/errors.md).
@@ -1355,7 +1356,7 @@ if "examples_loaded" not in columns:
## Onboarding Service
-Multi-step welcome wizard shown on first launch — database-backed (`UserSettings.onboarding_completed` + `onboarding_step`), skippable, resumable, replayable from Settings, and auto-skipped for existing users (migration sets `onboarding_completed=1` where `examples_loaded=1`). Built with shadcn primitives (no antd). Full step list, key files, replay flow, and how to add a step are in **[Onboarding Service](./docs-internal/onboarding.md)**.
+Multi-step welcome wizard shown on first launch of the workflow editor (it lives in `Dashboard.tsx`, so with Normal mode on it first appears when Dev mode opens) — database-backed (`UserSettings.onboarding_completed` + `onboarding_step`), skippable, resumable, replayable from Settings, and auto-skipped for existing users (migration sets `onboarding_completed=1` where `examples_loaded=1`). Built with shadcn primitives (no antd). Full step list, key files, replay flow, and how to add a step are in **[Onboarding Service](./docs-internal/onboarding.md)**.
## AI Chat Model Development Guide
@@ -2491,6 +2492,8 @@ Updated `client_left` and presence handlers use `has_real_android_devices()` ins
| **Usage/Compaction** | `get_api_usage_summary`, `get_compaction_stats`, `configure_compaction`, `get_provider_usage_summary` |
| **Agent Teams** | `create_team`, `get_team`, `get_team_status`, `dissolve_team`, `add_team_task`, `claim_team_task`, `complete_team_task`, `get_team_tasks`, `send_team_message`, `get_team_messages` |
| **Model Registry** | `get_model_constraints`, `refresh_model_registry` |
+| **Employees (Normal mode)** | `list_employees`, `get_employee`, `generate_employee_setup`, `cancel_employee_setup`, `hire_employee`, `start_employee` (see [normal_mode.md](./docs-internal/normal_mode.md)) |
+| **Approvals** | `list_approvals`, `decide_approval` (the `approvalGate` node's drafts) |
#### Broadcast Messages (Server -> All Clients)
| Message Type | Description |
@@ -2500,6 +2503,9 @@ Updated `client_left` and presence handlers use `has_real_android_devices()` ins
| `node_output` | Node execution output data |
| `agent_progress` | CloudEvents v1.0 envelope (type=`com.opencompany.agent.progress`) — per-step agent-loop iteration count, drives the live "N / max" badge on AI Agent canvas nodes |
| `agent_capability` | CloudEvents v1.0 envelope (`com.opencompany.agent.(skill|tool).*`) — exact-agent capability lifecycle with deterministic Temporal IDs, `(source,id)` deduplication, sanitized data, and an optional exact target node |
+| `employee_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.employee.{hired,updated,removed}`, subject = workflow id) — Home's team list; `updated` is coalesced to one per second per employee, control changes go out at once |
+| `approval_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.approval.{requested,decided,expired,cancelled}`) — identity only, never the draft or the recipient; the card refetches via `list_approvals` |
+| `workflow_lifecycle` | CloudEvents v1.0 envelope for workflow stages (`deployment.*`, `lock.*`, `execution.*`, `imported`, `renamed`, `created`, `deleted`) — other tabs invalidate their workflow lists |
| `deployment_snapshot` | CloudEvents v1.0 envelope (type=`workflow.deployment.snapshot`) — pushed once per WS connect from `broadcaster._send_deployment_snapshot`; lets the FE reconcile stale `deploymentStatus.isRunning=true` after a backend restart wiped `DeploymentManager._deployments`. Empty list is meaningful (forces reset). |
| `variable_update` | Single variable value change |
| `workflow_status` | Workflow execution progress |
diff --git a/README.md b/README.md
index 01619193..ceadb90b 100644
--- a/README.md
+++ b/README.md
@@ -75,10 +75,10 @@ https://github.com/user-attachments/assets/3d25e9a3-f7b9-4760-8b9a-6de1e5a19cad
[![How OpenCompany Works](docs/diagrams/how-it-works.svg)](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/how-it-works.svg)
-1. **Hire.** Drop an AI Employee onto the canvas. That is the lead.
-2. **Build the team.** Connect a few specialist agents to it and give each one the tools for its part of the job: email, browser, code, messaging, payments, and so on.
-3. **Start.** The team runs in the background and wakes up when something happens: a new email, a customer message, a scheduled time.
-4. **Review.** Watch it work on the canvas, read what it remembers, and change how it does things by editing its skills in plain text.
+1. **Hire.** Describe the job in plain words on the Home screen. OpenCompany drafts the new employee's setup (the apps it uses, when it works, what it checks with you first); adjust it and press Hire. Or switch to Dev mode and drop an AI Employee onto the canvas.
+2. **Build the team.** In Dev mode, connect a few specialist agents to it and give each one the tools for its part of the job: email, browser, code, messaging, payments, and so on.
+3. **Start.** The team runs in the background and wakes up when something happens: a new email, a customer message, a scheduled time. If you ask it to, it shows you each reply to approve before it goes out.
+4. **Review.** Watch it work from its card on Home or on the canvas, read what it remembers, and change how it does things by editing its skills in plain text.
[![Default workflows that ship with OpenCompany](docs/diagrams/default-workflows.svg)](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/default-workflows.svg)
@@ -120,7 +120,7 @@ Nothing here is a black box. What an employee learns lives in its memory, its no
- **Models** from OpenAI, Anthropic, Google, xAI, DeepSeek, Kimi, Mistral, Groq, Cerebras, Sarvam, and OpenRouter, or run local models with Ollama and LM Studio for free.
- **Speech and translation**, so employees can listen, talk, and work in other languages.
- **78 skills** that ship ready to use, and a place to drop your own.
-- **Built to keep running.** Employees survive restarts, pause and resume from the canvas, and catch up on missed schedules. Your API keys are stored encrypted on your machine. Add a login for shared or cloud use; one command deploys to Google Cloud.
+- **Built to keep running.** Employees survive restarts, pause and resume from Home or the canvas, and catch up on missed schedules. Your API keys are stored encrypted on your machine. Add a login for shared or cloud use; one command deploys to Google Cloud.
- **A canvas you will want to look at**, with 12 visual themes.
## For Developers
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index ac655fde..a1195acd 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -654,7 +654,7 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa
**Months-long durability contract**: running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Mechanisms, each replay-patch-guarded where it changes recorded commands:
-- **No lifetime caps on new child runs.** Trigger/cron-spawned `MachinaWorkflow` runs, agent children, and delegated-task runners previously carried 1-2h `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so any pause longer than the cap silently terminated the run (and a timed-out delegated runner skipped its compensation: leaked permit + stuck task row). New executions start children unbounded (no patch marker was retained for this change; the only live `workflow.patched` markers in the tree are `machina-conditional-edges-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py` — verify with `grep -rn "workflow.patched(" server/services/temporal`). Liveness is the activity layer's job: node activities heartbeat every 30s against a 2-minute `heartbeat_timeout`; their `start_to_close` is a generous 24h ceiling, not 10 minutes. The subagent-permit wait uses `PERMIT_WAIT_RETRY` (unlimited attempts) so a queued delegation waits as long as admission takes instead of failing after ~3h.
+- **No lifetime caps on new child runs.** Trigger/cron-spawned `MachinaWorkflow` runs, agent children, and delegated-task runners previously carried 1-2h `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so any pause longer than the cap silently terminated the run (and a timed-out delegated runner skipped its compensation: leaked permit + stuck task row). New executions start children unbounded (no patch marker was retained for this change; the live `workflow.patched` markers in the tree are `machina-conditional-edges-v1` and `machina-run-record-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py` — verify with `grep -rn "workflow.patched(" server/services/temporal`. `machina-run-record-v1` gates the `workflow_runs.record_completion` activity that trigger-spawned runs schedule when they finish, for Normal mode's "done today"; see [normal_mode.md](./normal_mode.md#done-today)). Liveness is the activity layer's job: node activities heartbeat every 30s against a 2-minute `heartbeat_timeout`; their `start_to_close` is a generous 24h ceiling, not 10 minutes. The subagent-permit wait uses `PERMIT_WAIT_RETRY` (unlimited attempts) so a queued delegation waits as long as admission takes instead of failing after ~3h.
- **History-pressure continue-as-new everywhere.** Temporal terminates any workflow around ~51,200 history events. `WorkflowControlWorkflow` (which multiplexes all of a deployment's triggers into one history) now rolls over on `is_continue_as_new_suggested()` / a 10K-event soft cap, carrying trigger specs, per-trigger provider `seen_ids` (written back into the spec after every poll cycle), queued push events, the bounded dedup baseline, and the control state — a rollover works mid-pause too, since a paused controller still accretes signal history. `TriggerListenerWorkflow`/`PollingTriggerWorkflow` gained the same pressure check (the old `_processed_count >= 16_000` gate was unreachable: real spawns cost ~15-25 events each, and polling counted only emitted events while a quiet mailbox burned ~11 events/cycle — dead in ~3 days at the 60s default). Poll intervals are clamped to a 30s floor on the patched path. Because run ids change on rollover, **controller handles are addressed by workflow id only, never run_id-pinned** (`_controller_handle`, manager `register_trigger`).
- **dispatch.emit controller narrowing.** Controllers advertise their push event types via the `ControlEventTypes` keyword-list Search Attribute (upserted as triggers register); `dispatch.emit` skips controllers with no matching trigger instead of signalling every running controller with every platform event (each unmatched signal was ~4 immutable history events — one busy deployment burned every other controller's rollover budget). Controllers without the attribute (pre-upgrade histories) keep match-all behaviour.
- **Boot-time reconcile** (`reconcile_active_controls_on_boot`, called from the lifecycle module after workers start): runs the lazy `_reconcile_control` over every active control row, converges `starting` rows a crash left behind (controller alive with triggers registered → `running`; alive-but-empty for a graph that declares triggers → `failed` + controller closed; vanished → `failed`), and re-arms the process-local half of running/paused generations from the persisted graph snapshot — DeploymentManager state, in-process collectors for non-canary trigger types, cron pause posture. Idempotent by construction (controller `register_trigger` keyed by listener id, legacy starts use `USE_EXISTING`, cron creation preserves server-owned pause state).
diff --git a/docs-internal/design-system/components/canvas/ModeToggle.prompt.md b/docs-internal/design-system/components/canvas/ModeToggle.prompt.md
index 6f2aa1b6..22651287 100644
--- a/docs-internal/design-system/components/canvas/ModeToggle.prompt.md
+++ b/docs-internal/design-system/components/canvas/ModeToggle.prompt.md
@@ -1,4 +1,4 @@
-Normal/Dev segmented toggle from the toolbar (Normal = AI components only; Dev = everything).
+Normal/Dev segmented toggle from the toolbar and the Home header: switches between Normal mode (Home) and Dev mode (the workflow editor). With Normal mode turned off (`VITE_NORMAL_MODE=false`) it filters the palette instead (Normal = AI components only; Dev = everything). The app's version is `client/src/components/shell/ModeToggle.tsx`.
```jsx
const [mode, setMode] = React.useState('normal');
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index aef2dd2f..f6ebee27 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -242,7 +242,11 @@ query is guaranteed to match nothing — once per save/mutation. They call
`get_status_broadcaster().broadcast({...})` directly instead, which is the same
pattern `nodes/telegram/_events.py` uses for status. The CloudEvents envelope,
`source`, `type`, `subject` and `data` are identical either way, so the wire
-contract the frontend sees does not change.
+contract the frontend sees does not change. Normal mode's two events follow
+the same rule: `employee_lifecycle` (`com.opencompany.employee.*`, in
+`services/employees/events.py`) and `approval_lifecycle`
+(`com.opencompany.approval.*`, in `nodes/workflow/approval_gate/_events.py`,
+identity only). See [normal_mode.md](./normal_mode.md#wire-contract).
Rule of thumb: **if no `register_canary_trigger_type` call names your event
type, broadcast it directly.** Reach for `emit` only when a Temporal workflow
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 99f9b403..ef3338e6 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -11,7 +11,8 @@ Post-migration (2026-04-14). Single source of truth for the current frontend.
- **shadcn/ui** via the canonical CLI (`bun x shadcn@latest add` — bun's `npx` equivalent; npm is not part of the toolchain). All primitives live under [client/src/components/ui/](../client/src/components/ui/) as first-class repo files we can edit.
- **Radix UI** is the primitive engine shadcn uses (Dialog, Accordion, Select, Switch, Tabs, Tooltip, Popover, Dropdown, AlertDialog, Collapsible, Progress, Slider, Label, Checkbox).
- **Forms**: react-hook-form + zod via shadcn's `Form` composition. Per-form schemas live colocated with the form (e.g. `credentials/panels/schemas/email.ts`); tiny forms use inline zod.
-- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`.
+- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`. Normal mode has a second toaster, one bottom-centre pill at a time (`pillToast()` in [features/home/ui/pillToast.tsx](../client/src/features/home/ui/pillToast.tsx)).
+- **Two screens**: Normal mode (Home, [features/home/](../client/src/features/home/)) and Dev mode (the workflow editor, `Dashboard.tsx`), both lazy chunks switched by the app shell in [app/](../client/src/app/). See [Normal Mode](./normal_mode.md).
- **State**: TanStack Query for server state, Zustand for UI-only state, plain `useState`/`useReducer` for local. No global redux store.
- **WebSocket realtime** via `WebSocketContext`; chat/node/workflow events are push-based, never polled.
- **antd is gone.** `styled-components` is gone. `@ant-design/icons` is gone. Icons come from `lucide-react`.
@@ -50,11 +51,25 @@ Not present (intentionally): antd, `@ant-design/icons`, styled-components, emoti
```
client/src/
-├── App.tsx # Root: syncs ThemeContext -> <html data-theme>/class, mounts Toaster
-├── main.tsx # Providers (QueryClient, Theme, Auth, WebSocket) + renders <App/>
-├── Dashboard.tsx # Canvas workspace (React Flow + top-level panels)
+├── App.tsx # Root: SVG filter defs, ProtectedRoute -> AppShell, both Toasters
+├── main.tsx # Providers (QueryClient, ShellThemeProvider, Auth, WebSocket) + renders <App/>
+├── Dashboard.tsx # Dev mode: canvas workspace (React Flow + top-level panels), a lazy chunk
├── ParameterPanel.tsx # Per-node inspector (Phase 6 will schema-drive this)
│
+├── app/ # The shell around both screens
+│ ├── AppShell.tsx # .app-frame, boot effects, Settings / Credentials dialogs
+│ ├── ShellModeSwitch.tsx # Lazy Home / editor screens + preloadHome / preloadEditor
+│ ├── ShellThemeProvider.tsx # ThemeProvider with baseOnly while Home shows
+│ ├── useShellActions.ts # enterNormal / enterDev (the only way to switch)
+│ ├── shellTransition.ts # The fade-out / swap choreography
+│ └── useModeShortcut.ts / useCurrentWorkflowSync.ts / usePageActivitySync.ts / useUIDefaultsOnce.ts
+│
+├── features/home/ # Normal mode (see docs-internal/normal_mode.md)
+│ ├── HomeShell.tsx # Sidebar + header + current view + Settings + orb stage
+│ ├── sidebar/ header/ hire/ employee/ settings/ approvals/ data/ state/ ui/
+│ ├── genui/ # Setup-screen pipeline; only its index.ts is importable (ESLint)
+│ └── orb/ # orb.ts (state + lifecycle), orbEngine.ts (three.js, own chunk)
+│
├── index.css # Tailwind v4 @import + @theme inline tokens + RF/scrollbar chrome
│
├── components/
@@ -123,13 +138,15 @@ client/src/
│ │ └── steps/ # WelcomeStep / HowItWorksStep / ConnectAIStep / TryItStep
│ │
│ ├── icons/ # AI provider icons (SVG data URIs)
+│ ├── brand/Logo.tsx # OcMark / OcWordmark / OcLogo (inline SVG, --lg-* palette, intro + pulse)
+│ ├── shell/ModeToggle.tsx # The Normal / Dev switch (editor toolbar + Home header)
│ ├── auth/ # Login page + protected route
│ ├── SquareNode.tsx, StartNode.tsx, TriggerNode.tsx, AIAgentNode.tsx, ToolkitNode.tsx, TeamMonitorNode.tsx
│ │ # React Flow nodes with lucide icons
│ └── APIKeyValidator.tsx # Shadcn Input + Button + Tooltip composition
│
├── contexts/
-│ ├── ThemeContext.tsx # isDarkMode + toggleTheme
+│ ├── ThemeContext.tsx # theme (on the page) / chosenTheme, setTheme with the circular reveal, baseOnly
│ ├── AuthContext.tsx # JWT user state
│ └── WebSocketContext.tsx # Single source of truth for WS state + handlers
│
@@ -148,7 +165,7 @@ client/src/
│ └── useCopyPaste.ts / useRename.ts
│
├── store/
-│ ├── useAppStore.ts # UI state (sidebar, palette, pro mode, persisted)
+│ ├── useAppStore.ts # UI state (sidebar, palette, shellMode, pro mode, persisted)
│ └── useCredentialRegistry.ts # UI-only: selectedId + paletteOpen + query
│
├── styles/
@@ -181,11 +198,18 @@ client/src/
│ ├── workflowOps.ts # applyOperations for backend workflow-ops batches
│ ├── canvasLock.ts # Server-owned can_edit capability -> canvas lock
│ ├── sound.ts # WebAudio sound engine (10 packs)
+│ ├── motion.ts # The one place Web Animations start: --dur-* / --ease-* tokens,
+│ │ # 1 ms under reduced motion or a hidden page, no loops then
+│ ├── pageActivity.ts / useReducedMotion.ts # Whether anyone can see the page; the motion preference
+│ ├── debouncedInvalidate.ts # Trailing-edge query invalidation (broadcast bursts)
│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)
├── schemas/workflowSchema.ts # Structural pre-flight for workflow export (backend is the schema authority)
├── stores/
│ ├── nodeStatusStore.ts # Per-workflow node statuses (slice-subscribed Zustand)
-│ └── canvasDockStore.ts # Docked Canvas sidebar state
+│ ├── canvasDockStore.ts # Docked Canvas sidebar state
+│ ├── workflowControlStore.ts # Mirror of workflow control statuses for Home (written from WebSocketContext)
+│ ├── shellDialogsStore.ts # Settings / Credentials dialog flags (lifted out of Dashboard)
+│ └── workflowSettingsStore.ts # Editor settings (auto-save etc.) read by the shell
├── test/ # Vitest setup.ts, builders.ts, providers.tsx, README.md
├── themes/ # base.css + animations.css + 12 per-theme CSS files
├── types/ # INodeProperties, NodeTypes, etc.
@@ -475,7 +499,7 @@ This is the rule that keeps the data layer schema-driven instead of imperatively
| Owns | What goes here | Examples |
|---|---|---|
| **TanStack Query** | Anything the server has authoritative state for. List / single-record / settings reads. Mutations that change server state. | `useWorkflowsQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`, `useCatalogueQuery`, `useSaveWorkflowMutation`, `useSaveNodeParamsMutation`, `useSaveUserSettingsMutation` |
-| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId` |
+| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `shellMode`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId`, Home's `useHomeStore` |
| **`useState` / `useReducer`** | Per-component transient state. Form-field drafts. Hover/focus. | text-input drafts, dropdown-open, inline-edit toggles |
| **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (workflow progress, android/whatsapp/twitter status, console/terminal logs). The provider value is `useMemo`'d so unrelated state changes do not re-render every consumer. Exposes `isConnected` (socket open) and `isReady` (open + pending-send queue drained); gate catalogue/spec queries on `isReady`. `drainPendingSends(ws)` runs synchronously, then `setIsReady(true)` fires immediately; terminal/chat/console history restore is fire-and-forget in the background (Wave 32 removed the init-burst gate and the hardcoded `probeApiKey` loop). Catalogue invalidation routes through `invalidateCatalogue(queryClient)` ([`hooks/useCatalogueQuery.ts`](../client/src/hooks/useCatalogueQuery.ts)) which debounces the refetch on a 300 ms trailing edge, so an oauth burst or multi-service reconnect collapses to one refetch instead of N. | `androidStatus`, `consoleLogs`, broadcast streams |
| **`stores/nodeStatusStore.ts`** (Zustand) | Per-workflow node-execution statuses -- moved out of WebSocketContext so a status tick does not cascade through the React tree. `useNodeStatus(id)` is a slice selector; only the affected node's consumers re-render. Mirror this pattern for any new high-frequency push state. | `allStatuses[workflowId][nodeId]`, `currentWorkflowId` |
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index 24e5a7db..c008d78d 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -242,6 +242,7 @@ match its doc here, and each doc must still describe what the code does.
### workflow_triggers
+- [Approval (`approvalGate`)](./workflow_triggers/approvalGate.md)
- [Chat Trigger (`chatTrigger`)](./workflow_triggers/chatTrigger.md)
- [Cron Scheduler (`cronScheduler`)](./workflow_triggers/cronScheduler.md)
- [Start (`start`)](./workflow_triggers/start.md)
diff --git a/docs-internal/node-logic-flows/workflow_triggers/approvalGate.md b/docs-internal/node-logic-flows/workflow_triggers/approvalGate.md
new file mode 100644
index 00000000..5f022860
--- /dev/null
+++ b/docs-internal/node-logic-flows/workflow_triggers/approvalGate.md
@@ -0,0 +1,158 @@
+# Approval (`approvalGate`)
+
+| Field | Value |
+|------|-------|
+| **Category** | workflow |
+| **Backend handler** | [`server/nodes/workflow/approval_gate/__init__.py`](../../../server/nodes/workflow/approval_gate/__init__.py) - `ApprovalGateNode`; dispatched via `BaseNode.execute()` + the `@Operation("request")` method |
+| **Tests** | [`server/tests/services/approvals/test_approval_gate.py`](../../../server/tests/services/approvals/test_approval_gate.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | no - `usable_as_tool = False`, so no agent can approve its own draft |
+
+## Purpose
+
+Holds a draft until the owner sends or discards it. A Normal-mode employee
+with "Ask me before sending anything" on answers through
+`agent -> approvalGate -> reply`: the gate records the agent's draft (who it
+goes to, what it says), shows it on the employee's card in Home, and waits.
+Send lets the draft, or the owner's edit of it, through to the reply node;
+Discard, expiry or a Reset lets nothing through. Hire builds this wiring
+(`services/employees/builder.py`); the node is also usable by hand in the
+editor. Feature overview: [Normal mode](../../normal_mode.md).
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | yes | The agent's reply (drives the `draft` template) and the trigger's data (the recipient) |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `channel` | string | `""` | no | - | The app the reply goes out through (shown on the card) |
+| `recipient` | string | `""` | no | - | Who the reply goes to, from the trigger (ints such as Telegram chat ids are coerced) |
+| `recipient_label` | string | `""` | no | - | How the card names the recipient |
+| `subject` | string | `""` | no | - | Subject line, for email |
+| `draft` | string | `""` | no | - | The message waiting for approval (capped at 20,000 characters) |
+| `context_excerpt` | string | `""` | no | - | The message being answered, shown above the draft (capped at 2,000) |
+| `max_length` | int | `20000` | no | - | Longest edit the channel accepts (1-20,000) |
+| `timeout_hours` | int | `168` | no | - | Hours before the draft expires (1-720) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | The decision (see below); fails closed |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ approved: boolean;
+ status: 'approved' | 'discarded' | 'expired' | 'cancelled' | 'skipped';
+ skipped: boolean;
+ text: string; // the sent text (the edit if there was one); "" unless approved
+ subject: string; // "" unless approved
+ recipient: string; // "" unless approved
+ recipient_label: string; // "" unless approved
+ approval_id: string | null;
+ edited: boolean;
+}
+```
+
+The reply node reads `{{<gate label>.text}}` and `{{<gate label>.recipient}}`,
+and its incoming edge carries `{"field": "result.approved", "operator": "is_true"}`
+(`services/approvals/contract.py::approved_edge_condition`), so nothing is sent
+unless the owner approved. The recipient always comes from the run's trigger,
+never from the agent's text.
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{draft empty or NO_REPLY?}
+ B -- yes --> S[Return skipped, no row]
+ B -- no --> C[Idempotency key: activity identity on Temporal, execution + node + inputs fingerprint in-process]
+ C --> D[get_or_create approval_requests row]
+ D -- created --> E[Broadcast approval_lifecycle requested]
+ D --> F{row pending?}
+ E --> F
+ F -- no --> O[Return the outcome]
+ F -- yes --> G[Show node status waiting]
+ G --> H{expired?}
+ H -- yes --> X[Settle expired, broadcast] --> O
+ H -- no --> I{worker shutting down?}
+ I -- yes --> W[Raise NodeWaitInterrupted: Temporal retries the attempt]
+ I -- no --> J[Wait for a notification or POLL_SECONDS, re-read the row] --> F
+```
+
+## Decision Logic
+
+- **Validation**: parameters are coerced and capped by the Params validators;
+ `extra="ignore"`.
+- **Branches**: an empty draft, or exactly `NO_REPLY`, returns
+ `status: "skipped"` and creates no row. The agent answers `NO_REPLY` when
+ nothing should go out; the gate's own incoming edge also carries
+ `result.response != NO_REPLY`.
+- **Identity**: `t:{workflow_id}:{run_id}:{activity_id}` inside a Temporal
+ activity, so a retry after a restart re-attaches to the same draft;
+ `p:{execution}:{node}:{sha256(outputs)[:16]}` in-process, where one
+ execution id can span several runs of a deployment.
+- **Waiting**: a process-local waiter (`services/approvals/waiter.py`) wakes
+ the gate the moment `decide_approval` settles the row; it also re-reads
+ the row every `POLL_SECONDS` (10) to see decisions made in another process
+ and expiry.
+- **Error paths**: a worker shutting down mid-wait raises `NodeWaitInterrupted`,
+ which `BaseNode.as_activity` turns into a retryable `ApplicationError`. On
+ the in-process path there is no retry, and the run fails as for any error.
+
+## Side Effects
+
+- **Database writes**: one `approval_requests` row per draft
+ ([`server/models/approvals.py`](../../../server/models/approvals.py)): the
+ recipient, draft, final text, status, revision and expiry. Decisions are
+ compare-and-swap on `revision`.
+- **Broadcasts**: `approval_lifecycle` (CloudEvents type
+ `com.opencompany.approval.{requested|decided|expired|cancelled}`, subject =
+ approval id). Identity only, never the message body or the recipient; the
+ card refetches through `list_approvals`. Node status `waiting` while it waits.
+- **External API calls**: none.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: the approvals package
+ ([`server/services/approvals/`](../../../server/services/approvals/)):
+ store, waiter, listeners, reconcile, queries, contract.
+- **Python packages**: `temporalio` (activity identity and worker shutdown).
+- **Environment variables**: none.
+
+## Edge cases & known limits
+
+- Runs on `TaskQueue.TRIGGERS_EVENT` with a 24-hour `start_to_close` and
+ unlimited retries (`maximum_attempts=0`); expiry, not the retry policy,
+ ends a wait. Each waiting draft holds one slot on that queue's worker.
+- A Reset cancels the workflow's pending drafts (`reset_execution_state`), and
+ deleting the workflow removes its rows (workflow-deleted hook).
+- Rows left pending by a crashed process are cancelled by
+ `reconcile_once`, which `list_approvals` runs: local rows created before
+ this process started, and Temporal rows whose generation is no longer live.
+- Deciding while the employee is paused is allowed; the response carries
+ `will_send_on_resume: true` and the card says so.
+
+## Related
+
+- **WebSocket handlers**
+ ([`_handlers.py`](../../../server/nodes/workflow/approval_gate/_handlers.py)):
+ `list_approvals {workflow_id?, status?, limit <= 100}` returns the owner's
+ drafts, per-workflow pending counts and `server_time`;
+ `decide_approval {approval_id, decision: "send" | "discard", text?, subject?, decision_key}`
+ is idempotent per `decision_key` and validates edits against `max_length`.
+ Errors: `already_decided`, `expired`, `cancelled`, `not_found`, `invalid_request`.
+- **Other nodes that consume this output**: the reply node of the app that
+ received the message (`whatsappSend`, `telegramSend`, `discordSend`,
+ `googleGmail`, `msMail`, `whatsappBusinessSend`).
+- **Architecture docs**: [Normal mode](../../normal_mode.md),
+ [Plugin System](../../plugin_system.md).
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index ece31687..1cf4c889 100644
--- a/docs-internal/node_allowlist.md
+++ b/docs-internal/node_allowlist.md
@@ -101,7 +101,8 @@ Read via `services.node_allowlist.get_node_allowlist_service().get_config()` —
| File | Filter |
|---|---|
-| `client/src/components/ui/ComponentPalette.tsx` | `if (isBlocked(name, groups)) return false; if (!proMode && !isAllowed(name)) return false;` |
+| `client/src/components/ui/ComponentPalette.tsx` | `if (isBlocked(name, groups)) return false; if (!showAll && !isAllowed(name)) return false;` where `showAll = featureFlags.normalMode \|\| proMode` |
+| `server/services/employees/builder.py` | every node Hire builds must pass `is_hire_allowed(node_type)` |
| `client/src/components/credentials/CredentialsModal.tsx` | `providers.filter(p => !isCredentialCategoryDisabled(p.category))` + same for `categories` |
| `client/src/components/parameterPanel/MasterSkillEditor.tsx` | `(foldersQuery.data ?? []).filter(f => !isSkillFolderDisabled(f.name))` |
diff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.md
new file mode 100644
index 00000000..6d4b060b
--- /dev/null
+++ b/docs-internal/normal_mode.md
@@ -0,0 +1,259 @@
+# Normal mode ("Home")
+
+Normal mode is the landing screen for owners who are not technical. They
+describe a job in plain words, an LLM on the server drafts a setup screen for
+a new AI employee, they adjust it and press **Hire**, and the server builds,
+saves and starts a workflow that does the job. Each employee appears in a
+sidebar with a live status card. The workflow editor is **Dev mode**, one
+switch away.
+
+**One employee is one workflow.** The workflow id is the employee id and the
+workflow's name is the employee's name. Workflows created in the editor show
+up in Home too, with details derived from their graph.
+
+| Layer | Where |
+|---|---|
+| Shell (screen switch, mode toggle, theme rule) | [client/src/app/](../client/src/app/), [components/shell/ModeToggle.tsx](../client/src/components/shell/ModeToggle.tsx) |
+| Home UI | [client/src/features/home/](../client/src/features/home/) |
+| Setup-screen pipeline (parse, normalise, render) | [client/src/features/home/genui/](../client/src/features/home/genui/) |
+| Employees service (list, setup, hire, start, run records) | [server/services/employees/](../server/services/employees/) |
+| Approvals (the "ask me first" step) | [server/services/approvals/](../server/services/approvals/), node [approvalGate](./node-logic-flows/workflow_triggers/approvalGate.md) |
+
+The design reference is the `design_handoff_opencompany_home/` bundle (kept
+out of git). Where its token values differ from the repo's, the repo wins.
+
+## Switching screens
+
+- **Flag**: `featureFlags.normalMode` ([lib/featureFlags.ts](../client/src/lib/featureFlags.ts))
+ is on by default; `VITE_NORMAL_MODE=false` turns Home off. The app then
+ opens straight into the editor, and the toolbar's Normal/Dev switch goes back
+ to filtering the component palette.
+- **State**: `useAppStore.shellMode` (`'normal' | 'dev'`), persisted as
+ `ui_shell_mode`. While that key is unset it comes from the old palette
+ choice: `ui_pro_mode === 'true'` starts in Dev.
+- **Switching** goes through `enterNormal` / `enterDev` in
+ [app/useShellActions.ts](../client/src/app/useShellActions.ts), never
+ `setShellMode` directly. `enterDev({workflowId})` settles unsaved editor work
+ first (saves it when auto-save is on, asks otherwise), opens the workflow and
+ preloads the editor chunk; `enterNormal` preloads Home. Then
+ [app/shellTransition.ts](../client/src/app/shellTransition.ts) fades the
+ current screen out and swaps. Requests during a switch coalesce. The toggle
+ lives in the editor toolbar and the Home header; Ctrl/Cmd+Shift+D toggles too.
+- **Screens are lazy chunks** ([app/ShellModeSwitch.tsx](../client/src/app/ShellModeSwitch.tsx)),
+ so ReactFlow stays out of a Normal-mode session and Home out of a Dev one.
+- **App-level concerns** live in [app/AppShell.tsx](../client/src/app/AppShell.tsx)
+ rather than in `Dashboard`: the `.app-frame`, boot effects (current workflow,
+ sound sync, page activity, UI defaults, the shortcut), and the Settings and
+ Credentials dialogs.
+- **Themes**: Home shows only light and dark.
+ [app/ShellThemeProvider.tsx](../client/src/app/ShellThemeProvider.tsx) passes
+ `baseOnly` to `ThemeProvider` while Home is showing, so a stylized theme
+ chosen in the editor appears as its family's base (Atomic as light, Cyber as
+ dark) and applies again in Dev mode. See [Theme System](./theme_system.md).
+
+## The Home screen
+
+[features/home/](../client/src/features/home/):
+
+| Folder | Contents |
+|---|---|
+| `HomeShell.tsx` | Sidebar, header, the current view (hire or one employee), Settings, the connect dialog, the orb's stage |
+| `sidebar/`, `header/` | The team list, New employee, the profile row; the view title, mode toggle and theme button |
+| `hire/` | The hero, the composer, starter jobs |
+| `genui/` | The setup draft under the composer (below) |
+| `employee/` | One employee's card: status, the current task, apps, "done today", Start / Pause / Resume, the drafts waiting for the owner |
+| `settings/` | Profile and Connectors, and `ConnectDialog` (the editor's credential panel for one provider, in its compact variant) |
+| `approvals/` | The drafts query, the decide mutation (optimistic), the approval broadcast listener |
+| `data/` | zod-parsed queries for employees, connectors and the profile; `presentation.ts` maps server state to pills and actions without deriving new rules |
+| `orb/` | The 3D orb (below) |
+| `ui/` | Small shared pieces (avatar, status dot and pill, app mark) and the pill toast |
+| `state/homeStore.ts` | UI state only: the view, the sidebar, Settings, one-shot glow and pulse signals |
+
+Status comes from the server: an employee summary is `working`, `ready`,
+`paused` or `attention` (an automatic pause, see below), and a pending draft
+shows as "Needs you". Motion goes through [lib/motion.ts](../client/src/lib/motion.ts),
+which reads the `--dur-*` / `--ease-*` tokens, runs at 1 ms under reduced
+motion and while the page is hidden ([lib/pageActivity.ts](../client/src/lib/pageActivity.ts)),
+and never starts loops then. Toasts are a second sonner toaster
+(`ui/pillToast.tsx`): one bottom-centre pill at a time.
+
+### The orb
+
+A 3D version of the logo drawn behind Home's content
+([orb/orbEngine.ts](../client/src/features/home/orb/orbEngine.ts), a port of
+the design prototype's scene on current three.js; loaded in its own chunk the
+first time it runs). [orb/orb.ts](../client/src/features/home/orb/orb.ts) holds
+what the engine reads each frame (the slot to fill, an energy target, a spike)
+and its lifecycle: leaving Home keeps the renderer, the app shell disposes it.
+`OrbStage` is the canvas host below the header; each view's `OrbSlot` reserves
+the square the orb glides into. The composer sets the energy target (focused,
+holding text, a setup being written); a hire, a theme or mode switch, a connect
+and a task change spike it. Without WebGL, under reduced motion, or after a
+lost WebGL context, the slot shows the static mark.
+
+## Hiring
+
+### 1. The setup screen
+
+`generate_employee_setup {job, refine?, history?, draft_token}`
+([services/employees/setup.py](../server/services/employees/setup.py)):
+
+- **The server builds every message** ([setup_prompt.py](../server/services/employees/setup_prompt.py)):
+ a preamble, the component catalogue, and a context block
+ ([context.py](../server/services/employees/context.py)) with the connected
+ and connectable apps, the team's names, the owner profile, the local time and
+ whether an AI model is set up. A change request carries the latest reply
+ plus at most two earlier turns, within a character budget.
+- **Model choice** ([llm.py](../server/services/employees/llm.py)): a local
+ provider when the owner prefers local AI, else the global default provider
+ when it has a key, else the first usable provider, else the first saved
+ endpoint. Calls go through `ChatUnifier` with a deadline (longer for local
+ models). One retry when the reply was cut off or cannot be salvaged. Usage is
+ recorded for every call.
+- **One request in flight per owner**: a newer `draft_token` cancels the older
+ call, and `cancel_employee_setup` cancels explicitly. The payload field is
+ `draft_token` because `request_id` is the WebSocket correlation id.
+- **Privacy**: neither the job nor the reply is ever logged.
+- **Errors**: `no_ai_provider` (the composer opens Connectors on AI),
+ `timeout`, `provider_error`, `unparseable`, `cancelled`, `busy`,
+ `invalid_request`.
+
+The reply is a flat JSON UI spec. The client parses, repairs and normalises it
+and renders it from a fixed component catalogue
+([genui/](../client/src/features/home/genui/): `catalog.ts`, `parse.ts`,
+`normalize.ts`, `expressions.ts`, `render.tsx`). The normaliser keeps the
+root a vertical stack, enforces a tree, guarantees one Hire button, one
+change button and the "Ask me before sending anything" toggle (on by default),
+and caps sizes. The server mirrors the catalogue in
+[config/genui_catalog.json](../server/config/genui_catalog.json);
+`server/tests/test_genui_catalog_sync.py` keeps the two in step, and a shared
+corpus of bad model replies (`genui/__fixtures__/replies.json`) is parsed the
+same way on both sides. Only what `genui/index.ts` exports (`HireDraftPanel`,
+`useHireComposer`, `DraftMessagePreview`) leaves the folder: ESLint refuses
+imports of its internal modules.
+
+### 2. Hire
+
+`hire_employee` ([hire.py](../server/services/employees/hire.py)) takes a
+`HireEmployeeRequest` ([hire_request.py](../server/services/employees/hire_request.py);
+the client's `HIRE_PAYLOAD_KEYS` must match, locked by
+`test_hire_payload_contract.py`) and:
+
+1. checks size and shape, then the idempotency key: the same key with the same
+ payload returns the employee already hired, a different payload `conflict`;
+2. resolves the apps it names through the app registry
+ ([config/employee_apps.json](../server/config/employee_apps.json),
+ [apps.py](../server/services/employees/apps.py)): each app's provider,
+ its trigger / reply / notify-owner / tool nodes with parameter templates,
+ and a `side_effects` class. Apps the registry does not know are recorded as
+ unsupported, named in the instructions, and never block a start;
+3. builds the graph ([builder.py](../server/services/employees/builder.py),
+ pure): one trigger (an app event, a schedule on `cronScheduler`, or manual
+ chat), one `aiAgent` whose system message comes from
+ [prompt.py](../server/services/employees/prompt.py), always-on tools (web
+ search, todos, clock, plus memory when the owner allows it) and the apps'
+ tools, delivery, and an "Activity log" console node. With "Ask me before
+ sending anything" on, a reply goes through `approvalGate`, and tools that
+ send or spend money are left off. Every node type must pass
+ `node_allowlist.is_hire_allowed` ([Node Allowlist](./node_allowlist.md));
+ node types never come from the payload;
+4. validates it with `validate_workflow` and saves it with
+ [persist_new_workflow](../server/services/workflow_storage/persist.py)
+ (shared with workflow import);
+5. answers `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}`
+ and, when every app is connected and an AI model exists, starts the
+ employee in the background.
+
+### 3. Start, pause, resume
+
+`start_employee {workflow_id, expected_revision, idempotency_key}`
+([start.py](../server/services/employees/start.py)) refuses with
+`missing_apps` or `needs_ai`, moves the agent onto a usable model, and calls
+`start_saved_workflow`, the same start path the editor uses. Pause and Resume
+are the editor's `pause_workflow` / `resume_workflow`.
+
+Automatic pauses now record why: `WorkflowControlExecution.pause_reason`
+(`failures` from the circuit breaker, `recovery` after a crash,
+`controller_missing`) and `pause_detail`, emitted by `serialize_control` and
+cleared on resume. Home shows such an employee as "Needs attention". See
+[Temporal Workflow Control](./temporal-workflow-control.md#recovery-policies).
+
+## Asking before sending
+
+With the rule on, a reply waits in an `approvalGate` until the owner decides
+on the employee's card. The gate stores the draft in `approval_requests`,
+wakes the moment it is decided, survives restarts (its idempotency key finds
+the same row on every attempt), expires after `timeout_hours`, and fails
+closed: nothing is sent unless it was approved, and the recipient always comes
+from the run's trigger. Full contract:
+[approvalGate](./node-logic-flows/workflow_triggers/approvalGate.md).
+
+## "Done today"
+
+Every trigger-spawned run that finishes writes a `workflow_run_records` row
+([runs.py](../server/services/employees/runs.py)): on Temporal from the
+`workflow_runs.record_completion` activity, scheduled at the end of
+`MachinaWorkflow.run` behind the `machina-run-record-v1` patch; in-process
+from `DeploymentManager`. The count starts at local midnight in the owner's
+timezone, and rows are pruned after 35 days.
+
+## Settings
+
+- **Profile**: `profile_full_name`, `profile_call_name`, `profile_role`,
+ `profile_preferences`, `profile_timezone` (written from `Intl` on save),
+ `memory_across_chats` and `prefer_local_ai` on `UserSettings`, normalised on
+ save by [services/settings/profile.py](../server/services/settings/profile.py).
+ Every hire reads them into its instructions.
+- **Connectors**: the providers in `config/credential_providers.json` that
+ declare a `consumer_category` (`messages`, `organize`, `business`, `ai`) and a
+ short `description`. The catalogue adds `connected`, which differs from
+ `stored` for providers with a `connected_check` (WhatsApp's live pairing, the
+ IMAP/SMTP account's keys).
+
+## Wire contract
+
+WebSocket requests (snake_case; failures come back as `success: false` with an
+`error` code):
+
+| Type | Payload | Response |
+|---|---|---|
+| `list_employees` | `{}` | `{employees}` |
+| `get_employee` | `{workflow_id}` | the summary plus `description`, `job`, `plan`, `rules`, `choices`, `trigger_text`, `last_run`, `latest_report` |
+| `generate_employee_setup` | `{job, refine?, history?, draft_token}` | `{draft_token, reply, provider, model, usage, retried, finish_reason, apps}` |
+| `cancel_employee_setup` | `{draft_token}` | `{cancelled}` |
+| `hire_employee` | `HireEmployeeRequest` | `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}` |
+| `start_employee` | `{workflow_id, expected_revision, idempotency_key}` | as `start_workflow` |
+| `list_approvals` | `{workflow_id?, status?, limit <= 100}` | `{approvals, counts, server_time}` |
+| `decide_approval` | `{approval_id, decision, text?, subject?, decision_key}` | `{approval, will_send_on_resume}` |
+
+Broadcasts, all CloudEvents envelopes broadcast directly (no Temporal
+consumer; see [Event Framework](./event_framework.md#ui-only-lifecycle-events-broadcast-directly-never-through-emit)):
+
+| Wire key | Type | Notes |
+|---|---|---|
+| `employee_lifecycle` | `com.opencompany.employee.{hired,updated,removed}` | Subject is the workflow id; `updated` is coalesced to one per second per employee, except control changes, which go out at once |
+| `approval_lifecycle` | `com.opencompany.approval.{requested,decided,expired,cancelled}` | Identity only, never the message or the recipient |
+| `workflow_lifecycle` | gains `created` and `deleted` stages | So open editors refresh their workflow lists |
+
+## Tests
+
+Server: `tests/services/employees/`, `tests/services/approvals/`,
+`tests/test_edge_condition_parity.py`, `tests/test_genui_catalog_sync.py`,
+`tests/test_hire_payload_contract.py`, `tests/test_node_allowlist_hire.py`,
+`tests/test_user_settings_profile_fields.py`,
+`tests/test_credential_catalogue_consumer_fields.py`,
+`tests/temporal/test_machina_run_record.py` (including replay of a pre-patch
+history). Client: `features/home/**/__tests__`, `app/__tests__`,
+`contexts/__tests__/themePrePaint.test.ts`.
+
+## Known gaps
+
+- An employee's latest report is not captured yet (`latest_report` is always
+ empty).
+- `list_employees` is not filtered per owner (multi-user mode shares one
+ store anyway; see [Authentication](./authentication.md)).
+- OAuth sign-in is not opened ahead of the request, so a browser may block
+ the popup.
+- Each waiting draft holds one `triggers-event` worker slot.
+- A manual-chat employee cannot be given work from Home yet; the setup prompt
+ steers towards app and schedule triggers.
diff --git a/docs-internal/onboarding.md b/docs-internal/onboarding.md
index 80faf799..fbfbdec3 100644
--- a/docs-internal/onboarding.md
+++ b/docs-internal/onboarding.md
@@ -2,7 +2,7 @@
## Overview
-The onboarding service provides a four-step welcome wizard that appears after a user's first launch: what OpenCompany is, how the canvas works, connecting an AI provider, and trying the shipped AI Assistant example. It is database-backed, skippable, resumable, and replayable from Settings. A separate, dismissable **Get Started checklist** (`GetStartedChecklist.tsx`) sits in the corner of the canvas after the wizard and tracks five first-session milestones.
+The onboarding service provides a four-step welcome wizard that appears after a user's first launch: what OpenCompany is, how the canvas works, connecting an AI provider, and trying the shipped AI Assistant example. It is database-backed, skippable, resumable, and replayable from Settings. The wizard is part of the workflow editor (`Dashboard.tsx`), so with Normal mode on it first appears when Dev mode opens; Normal mode's first screen is Home itself ([normal_mode.md](./normal_mode.md)). A separate, dismissable **Get Started checklist** (`GetStartedChecklist.tsx`) sits in the corner of the canvas after the wizard and tracks five first-session milestones.
The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client/src/`. The wizard composes the project's `Modal` primitive, shadcn `Button` / `ActionButton` / `Card` / `Badge` / `Alert` / `Skeleton`, and `lucide-react` icons. The step progress indicator is a hand-rolled `<ol>` driven by node-role tokens (no antd `Steps`).
diff --git a/docs-internal/temporal-workflow-control.md b/docs-internal/temporal-workflow-control.md
index 14cafa8c..4619eed8 100644
--- a/docs-internal/temporal-workflow-control.md
+++ b/docs-internal/temporal-workflow-control.md
@@ -213,6 +213,14 @@ that Resume relies on.
every knob is evaluated on the activity side so flipping config never
touches recorded workflow commands.
+**Why an automatic pause happened.** Each of the three records it on the
+control row: `pause_reason` is `failures` (the circuit breaker),
+`recovery` (crash recovery) or `controller_missing`, with a readable
+`pause_detail`. `serialize_control` emits both; a transition back to
+`running` (Resume, reconcile, restore) clears them. Only server-side calls
+can set a reason; a `pause_workflow` from a socket cannot. Normal mode shows
+such an employee as "Needs attention" ([normal_mode.md](./normal_mode.md)).
+
## Canvas editability (`can_edit` capability)
Whether a workflow's canvas may be edited is a **server-owned capability**,
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 71c9e2c9..dacdc44e 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -126,6 +126,38 @@ Six tokens for canvas identity: `agent / model / skill / tool / trigger / workfl
Consumed as `var(--code-*)` in [index.css](../client/src/index.css) (`.code-editor-container`, `.console-json-output`, the `.chat-markdown` dark overrides) and exposed as Tailwind utilities (`text-code-tag`, `bg-code-bg`, …) via the `@theme inline` bridge; the `OutputPanel` `@uiw/react-json-view` viewer reads the same vars. This **replaced the old global dracula-hardcoded `--prism-*` block and the dead `getPrismTokenCSS()` helper** — code/JSON now paints in each theme's palette instead of one dracula scheme everywhere. (`prismjs` is still the tokenizer; only the colours moved to `--code-*`.)
+### Home (Normal mode) tokens
+
+Normal mode ([normal_mode.md](./normal_mode.md)) adds its own steps, all in
+[base.css](../client/src/themes/base.css) unless noted, and bridged in
+`index.css` like the rest:
+
+- **Motion**: `--ease-spring | overshoot | reveal` and the choreography
+ durations (`--dur-intro`, `--dur-view-swap`, `--dur-panel-in/-out`,
+ `--dur-toast-in/-hold/-out`, `--dur-mode-in/-out`, `--dur-theme-reveal`,
+ `--dur-glow`, `--dur-pip-loop`, …). Read only through
+ [lib/motion.ts](../client/src/lib/motion.ts), whose fallbacks mirror
+ base.css.
+- **Radii**: `--radius-row | card | panel | draft | composer`, multiples of each
+ theme's `--radius-lg`, so square themes stay square.
+- **Type and layout**: `--text-meta | row | lead | title | hero` (with
+ `--tracking-hero`, `--leading-hero`), and the Home layout constants
+ (`--w-home-sidebar`, `--h-home-header`, `--w-composer`, the orb slot sizes,
+ the Settings dialog size).
+- **Status**: `--status-{working,ready,paused,attention,waiting}-{dot,fill,border,ink}`
+ for the employee pills and dots. The dot is the raw role colour; light.css
+ keeps the paused dot at the design's mid grey.
+- **Per family** (light.css / dark.css): `--shadow-float | popover | dialog`,
+ the logo palette `--lg-*`, and the node-role `-fill / -edge / -hover / -ink`
+ variants.
+
+Home shows only the two base themes: `ThemeProvider`'s `baseOnly` (set by
+`app/ShellThemeProvider.tsx` while Home is showing) renders a chosen stylized
+theme as its family's base, and the pre-paint script in `index.html` applies
+the same rule to the first frame. `setTheme(next, { reveal: true, origin })`
+grows the new theme as a circle from `origin` (View Transitions), falls back
+to a short colour fade, and is instant under reduced motion.
+
## Migration recipe
The single most important rule from the design handoff: