Skip to content

Self-improving AI Employees for everyone

docs: bring the docs in line with the Home design update

trohitg51f160452a82
diff --git a/CLAUDE.md b/CLAUDE.md
index 57d4fc54..496e10f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +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. |
+| **[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` plus the owner's skill library and a Canvas node, 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; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; the Browser and Android tabs are placeholders), 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). |
diff --git a/README.md b/README.md
index fb522f39..2bcd135b 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ Download the app for your computer and install it (these links always point at t
- **macOS, Intel**: [OpenCompany-macos-x64.dmg](https://github.com/zeenie-ai/OpenCompany/releases/latest/download/OpenCompany-macos-x64.dmg)
- **Linux**: [OpenCompany-linux-x86_64.AppImage](https://github.com/zeenie-ai/OpenCompany/releases/latest/download/OpenCompany-linux-x86_64.AppImage), or [OpenCompany-linux-amd64.deb](https://github.com/zeenie-ai/OpenCompany/releases/latest/download/OpenCompany-linux-amd64.deb) on Debian and Ubuntu
-Nothing else to install. On first launch the app sets itself up (a one-time download, a minute or two) and opens the canvas. Click the key icon in the toolbar to connect your first AI provider. Three example employees are already on the canvas; open one to see how it is put together.
+Nothing else to install. On first launch the app sets itself up (a one-time download, a minute or two) and opens Home. Describe a job to hire your first employee; if no AI provider is connected yet, Home asks you to connect one, or you can add it yourself in Settings > Connectors. Switch to Dev mode for the workflow editor, where three example employees are already on the canvas; open one to see how it is put together.
The builds are not code-signed yet, so macOS asks you to allow the app under System Settings > Privacy & Security, and Windows SmartScreen needs "More info > Run anyway".
@@ -88,10 +88,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.** 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.
+1. **Hire.** Describe the job in plain words on the Home screen, or start from a ready-made bundle in Settings > Plugins. 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.
+4. **Review.** Watch it work from its card on Home or on the canvas, open its Workspace to see the things it has made, 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)
@@ -123,7 +123,7 @@ Runs payment operations through Stripe and reacts the moment a payment event hap
- **They pick up where they left off.** Every new message, task, or scheduled run continues the same conversation instead of starting from zero. When the conversation gets long, the employee writes itself a summary and carries on from it.
- **They add tools when they need them.** Mid-task, an employee can look at its own team, add a tool, attach a skill, or bring in another specialist, and the change stays.
- **They check their own work.** The lead reviews every result from the team and sends it back if it is not right, before it ever reaches you.
-- **You coach them.** Skills are short plain-text playbooks. Edit one and the employee follows it on its next turn.
+- **You coach them.** Skills are short plain-text playbooks. Edit one and the employee follows it on its next turn. Settings > Skills keeps your library of them, and every new hire starts with the ones you have switched on.
Nothing here is a black box. What an employee learns lives in its memory, its notes, its skills, and the pieces on its canvas, and you can read or change all of it. OpenCompany never retrains a model.
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index ef3338e6..9e75b902 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -65,8 +65,9 @@ client/src/
│ └── 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
+│ ├── HomeShell.tsx # Sidebar + header + current view + Workspace dock + Settings + orb stage
│ ├── sidebar/ header/ hire/ employee/ settings/ approvals/ data/ state/ ui/
+│ ├── workspace/ # The Workspace dock; its Canvas tab loads in its own chunk
│ ├── genui/ # Setup-screen pipeline; only its index.ts is importable (ESLint)
│ └── orb/ # orb.ts (state + lifecycle), orbEngine.ts (three.js, own chunk)
│
@@ -162,6 +163,8 @@ client/src/
│ ├── useOnboarding.ts # Reads via useUserSettingsQuery; writes via mutation
│ ├── useParameterPanel.ts # Thin orchestrator over useNodeParamsQuery + save mutation
│ ├── useWhatsApp.ts # WS-based WhatsApp ops (Android ops go via useWebSocket directly)
+│ ├── useUserSkills.ts / useFolderSkills.ts # Skill library + skill-folder queries (Home Skills, Master Skill editor)
+│ ├── useCanvasBoard.ts # One Canvas board's query + remove / clear (every Canvas host)
│ └── useCopyPaste.ts / useRename.ts
│
├── store/
diff --git a/docs-internal/node-logic-flows/ai_agents/masterSkill.md b/docs-internal/node-logic-flows/ai_agents/masterSkill.md
index b80c0aa8..2951b1ba 100644
--- a/docs-internal/node-logic-flows/ai_agents/masterSkill.md
+++ b/docs-internal/node-logic-flows/ai_agents/masterSkill.md
@@ -101,6 +101,7 @@ flowchart TD
- **Duplicate names**: `validate_connected_skills` raises `SkillRuntimeError("DUPLICATE_CONNECTED_SKILL_NAME")` when the same `skill_name` reaches an agent from more than one Master Skill node.
- **Missing expander**: `get_master_skill_expander()` is `None` only when `nodes.skill` was never imported; the walker logs a warning and the agent runs without the node's skills. Re-registering a *different* callable raises `ValueError`.
- **Auto-skill** (`services/auto_skill.evaluate`, driven by the `auto_add_skill_for_tools` user setting): connecting a tool that has a paired skill to an agent returns a workflow-ops batch that either toggles the skill in the agent's existing Master Skill (`set_node_parameters(master_skill_id, {skills_config})`, preserving customised `instructions` / `isCustomized`) or adds a new `masterSkill` node with that config plus an edge to `input-skill`.
+- **Hire** (`services/employees/builder.py`): a new employee gets one `masterSkill` node built from the owner's skill library, the user skills that are on. It holds the `skill` entry plus one entry per library skill with its `instructions` and `description` copied in, so a later library edit never changes an employee already hired. Names that would take over the Skill tool or the system message (`skill`, `*-personality`) are left out. The editor keeps those extra keys when it toggles, edits or resets an entry, and does not send `is_active: true` on save, which would switch a library skill back on for new hires.
- **Error paths**: `noop` cannot fail; `load_skill` failures for personality skills are logged (`warning`) and the entry proceeds with empty instructions.
## Side Effects
@@ -114,7 +115,7 @@ flowchart TD
- **Credentials**: none.
- **Services**: `services.plugin.edge_walker` (`register_master_skill_expander` / `get_master_skill_expander`), `services.skill_loader`, `services.skill_prompt`, `services.skill_runtime`, `services.auto_skill`, `services.workflow_ops`, `services.events.envelope.WorkflowEvent`.
-- **Frontend**: [`client/src/components/parameterPanel/MasterSkillEditor.tsx`](../../../client/src/components/parameterPanel/MasterSkillEditor.tsx) (dispatched by `MiddleSection` on `uiHints.isMasterSkillEditor`), `Dashboard.tsx` component dispatch to `ToolkitNode`, [`client/src/hooks/useAutoSkillEdges.ts`](../../../client/src/hooks/useAutoSkillEdges.ts).
+- **Frontend**: [`client/src/components/parameterPanel/MasterSkillEditor.tsx`](../../../client/src/components/parameterPanel/MasterSkillEditor.tsx) (dispatched by `MiddleSection` on `uiHints.isMasterSkillEditor`), `Dashboard.tsx` component dispatch to `ToolkitNode`, [`client/src/hooks/useAutoSkillEdges.ts`](../../../client/src/hooks/useAutoSkillEdges.ts), and the skill queries it shares with Home's Settings > Skills ([`useUserSkills.ts`](../../../client/src/hooks/useUserSkills.ts), [`useFolderSkills.ts`](../../../client/src/hooks/useFolderSkills.ts)).
- **Task queue**: `TaskQueue.DEFAULT` (never dispatched in practice). Annotations: `readonly`.
## Edge cases & known limits
diff --git a/docs-internal/node-logic-flows/ai_tools/canvas.md b/docs-internal/node-logic-flows/ai_tools/canvas.md
index d351cb1f..227430e2 100644
--- a/docs-internal/node-logic-flows/ai_tools/canvas.md
+++ b/docs-internal/node-logic-flows/ai_tools/canvas.md
@@ -15,9 +15,12 @@ A display board workflows and agents push content onto — the platform's
Claude/ChatGPT-Canvas-style viewing surface. Agents call the `canvas` tool
after producing something the user should see (a screenshot, a chart, a
report, a URL); workflow edges push upstream file outputs automatically. The
-board renders in two hosts sharing one component: the node's full-height
-parameter panel (`uiHints.isCanvasPanel`) and the docked right-side canvas
-sidebar (auto-opens on push, resizable, ephemeral click-to-preview mode).
+board renders in three hosts sharing one component: the node's full-height
+parameter panel (`uiHints.isCanvasPanel`), the docked right-side canvas
+sidebar (auto-opens on push, resizable, ephemeral click-to-preview mode),
+and the Canvas tab of Home's Workspace dock, which shows one employee's
+board. Hire gives every new employee a Canvas node, and its instructions ask
+it to put finished work there.
Items are *references* (serialized `FileRef`s, URLs) and small markdown
notes — never file bytes (media-transport contract).
@@ -91,7 +94,7 @@ flowchart TD
- **Credentials**: none.
- **Services**: `services.media` (`resolve_media`, `workspace_file_url`), `services.plugin.deps.get_database`.
-- **Frontend**: `client/src/components/parameterPanel/CanvasPanel.tsx` (panel host), `client/src/components/ui/CanvasDock.tsx` (docked sidebar + ephemeral preview), shared `parameterPanel/canvas/CanvasContent.tsx` (carousel, follow-latest image poll, markdown/code/JSON/text via capped client fetch, sandboxed iframes for external URLs + workspace HTML, inline PDF).
+- **Frontend**: `client/src/components/parameterPanel/CanvasPanel.tsx` (panel host), `client/src/components/ui/CanvasDock.tsx` (docked sidebar + ephemeral preview), `client/src/features/home/workspace/WorkspaceCanvas.tsx` (Home's Workspace dock, loaded lazily), shared `parameterPanel/canvas/CanvasContent.tsx` (carousel, follow-latest image poll, markdown/code/JSON/text via capped client fetch, sandboxed iframes for external URLs + workspace HTML, inline PDF).
## Edge cases & known limits
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index 1cf4c889..8d7d9a86 100644
--- a/docs-internal/node_allowlist.md
+++ b/docs-internal/node_allowlist.md
@@ -40,9 +40,12 @@ governs what Normal mode's Hire may assemble into an employee instead:
type is not blocked (exact type, or any of its groups, the same matching
the palette uses) and either `enabled_nodes` is empty or lists it. The graph
builder checks every node it emits, and node types never come from the hire
-payload. The node types the v1 app registry (`server/config/employee_apps.json`)
-can emit are locked in by `server/tests/test_node_allowlist_hire.py`, so a
-missing entry fails CI rather than a hire.
+payload. The node types Hire can emit, its fixed building blocks (the agent,
+the triggers, Context and Memory, the always-on tools, the approval gate,
+Canvas, and a Skills node when the owner's library has skills on) and every
+node the v1 app registry (`server/config/employee_apps.json`) names, are
+locked in by `server/tests/test_node_allowlist_hire.py`, so a missing entry
+fails CI rather than a hire.
## Frontend hook API
diff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.md
index 1ec8ab2f..19ea9022 100644
--- a/docs-internal/normal_mode.md
+++ b/docs-internal/normal_mode.md
@@ -18,9 +18,13 @@ up in Home too, with details derived from their graph.
| 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) |
+| Built-in skills offered to new hires (Settings > Skills > Discover) | [server/skills/employee/](../server/skills/employee/) |
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.
+out of git; the 2026-09-25 export). Where its token values differ from the
+repo's, the repo wins. Its README's Settings section predates the Settings
+redesign, so for Settings the prototype (`reference/OpenCompany Home.dc.html`)
+is the reference.
## Switching screens
@@ -59,7 +63,7 @@ out of git). Where its token values differ from the repo's, the repo wins.
|---|---|
| `HomeShell.tsx` | Sidebar, header, the current view (hire or one employee), the Workspace dock, Settings, the connect dialog, the orb's stage |
| `sidebar/`, `header/` | The team list, New employee, the profile row; the view title, the Workspace pill, mode toggle and theme button |
-| `hire/` | The hero, the composer, starter jobs |
+| `hire/` | The hero, the composer, and the starter bundles (`starters.json`), which the template chips and Settings > Plugins both read |
| `genui/` | The setup draft under the composer (below) |
| `employee/` | One employee's card: status, the current task, apps, "done today", Start / Pause / Resume, Watch live, the drafts waiting for the owner |
| `workspace/` | The Workspace dock (below), its header pill, and its Canvas tab, which loads in its own chunk |
@@ -337,6 +341,8 @@ Server: `tests/services/employees/`, `tests/services/approvals/`,
`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/test_home_catalog_contract.py` (the starter bundles and the Discover
+folder against each other and the app registry),
`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`.