Skip to content

Self-improving AI Employees for everyone

docs: correct internal docs to match shipped reality

trohitgc6188b6d0355
diff --git a/CLAUDE.md b/CLAUDE.md
index a212e0d8..69e59aa8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -534,14 +534,14 @@ The frontend uses a layered cache + slice-subscription model so cold refreshes a
### React.memo every canvas node component ([client/src/components/nodeMemoEquality.ts](./client/src/components/nodeMemoEquality.ts))
- React Flow's documented requirement. Use the shared `nodePropsEqual` comparator -- it skips drag-state props (`xPos` / `yPos` / `dragging`) so the memo isn't defeated during drag.
-- Applies to `SquareNode`, `AIAgentNode`, `TriggerNode`, `GenericNode`, `ToolkitNode`, `StartNode`, `TeamMonitorNode`. Add new node components the same way.
+- Applies to `SquareNode`, `AIAgentNode`, `TriggerNode`, `ToolkitNode`, `StartNode`, `TeamMonitorNode`. Add new node components the same way.
- Reference: https://reactflow.dev/learn/advanced-use/performance
### Icon + color — per-plugin folder + visuals.json fallback
Plugin icons and colors live co-located in the plugin folder; `visuals.json` is the fallback registry for emoji / library icons and the skill reverse-map. Full resolution chain (per-node-type → shared → fallback) is documented in [server/nodes/README.md → Icon + color](./server/nodes/README.md) and [docs-internal/plugin_system.md](./docs-internal/plugin_system.md).
-Backend endpoints serve SVGs at `GET /api/schemas/nodes/<type>/icon` (plugin icons) and `GET /api/schemas/credentials/<provider>/icon` (credential brand icons). Frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts) dispatches `lib:brand` / URL passthrough / emoji / dead-code `asset:<key>`.
+Backend endpoints serve SVGs at `GET /api/schemas/nodes/<type>/icon` (plugin icons) and `GET /api/schemas/credentials/<provider>/icon` (credential brand icons). Frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts) dispatches `lib:brand` / URL passthrough / emoji / `asset:<key>`. The `asset:` branch is currently inert at runtime (the frontend `ICON_REGISTRY` glob finds no SVGs so it resolves to null) but it is NOT dead code — the backend still emits `asset:google` / `asset:stripe` for palette groups (`server/nodes/groups.py`) and the format is invariant-tested on both sides (`test_node_spec.py` Wave 10.B, `icons/index.test.ts`).
**Do not** declare `icon` / `color` as class attributes on a node (the override path was removed in F1). Drop `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders like whatsapp) and `meta.json` into the plugin folder. SKILL.md icon/color resolves from the first node in `allowed-tools` — only orphan skills keep inline `metadata.icon` / `metadata.color`.
@@ -583,7 +583,7 @@ AI model nodes route through `SquareNode` via `Dashboard.tsx`'s `COMPONENT_BY_KI
### Specialized UI
- `src/components/ui/MapSelector.tsx` - Interactive location picker
-- `src/components/ui/OutputDisplayPanel.tsx` - Execution result display
+- `src/components/output/OutputPanel.tsx` - Execution result display (the active renderer; the legacy `ui/OutputDisplayPanel.tsx` was deleted)
- `src/components/ui/ComponentPalette.tsx` - Searchable component library with emoji icons and dracula-themed category colors. Categories: Workflow, Triggers, AI Agents, AI Models, AI Skills, AI Abilities, AI Tools, Google Maps, Social Media Platforms (merged WhatsApp + Social), Android, Chat, Code Executors
- `src/components/ui/ComponentItem.tsx` - Draggable node items with hover effects and icon rendering
- `src/components/ui/CodeEditor.tsx` - Syntax-highlighted code editor (react-simple-code-editor + prismjs). Token colours come from the per-theme `--code-*` tokens (see [Theme System](./docs-internal/theme_system.md) tier 6) — the code editor, console/output JSON viewers, and chat code blocks all paint in the active theme's syntax palette, not a global dracula scheme. (Retired the old `--prism-*` block + dead `getPrismTokenCSS()`.)
@@ -791,10 +791,9 @@ Three methods for renaming nodes, following n8n UX patterns:
Global State (useAppStore) Node Components
├── renamingNodeId: string | null ├── SquareNode.tsx
├── setRenamingNodeId() ├── TriggerNode.tsx
- ↓ ├── GenericNode.tsx
- Coordinates which node └── StartNode.tsx
- is currently being renamed ↓
- Local State:
+ ↓ └── StartNode.tsx
+ Coordinates which node ↓
+ is currently being renamed Local State:
├── isRenaming: boolean
├── editLabel: string
└── inputRef: HTMLInputElement
@@ -806,7 +805,6 @@ Global State (useAppStore) Node Components
- **`client/src/Dashboard.tsx`** - Context menu handler, F2 keyboard handler
- **`client/src/components/SquareNode.tsx`** - Inline rename for square nodes (Android, WhatsApp)
- **`client/src/components/TriggerNode.tsx`** - Inline rename for trigger nodes
-- **`client/src/components/GenericNode.tsx`** - Inline rename for generic colored nodes
- **`client/src/components/StartNode.tsx`** - Inline rename with label support (was hardcoded "Start")
#### Key Pattern (shared by all node components)
@@ -1144,18 +1142,8 @@ npx tsc --noEmit
# Build verification
npm run build
-
-# Test WebSocket connection for remote Android devices
-python test_websocket.py
```
-### WebSocket Testing (`test_websocket.py`)
-- Tests health endpoint configured via `WEBSOCKET_URL` environment variable
-- Tests stats endpoint
-- Tests WebSocket connection
-- Validates connection establishment and ping/pong messaging
-- Comprehensive test results with pass/fail status
-
## Production Deployment
### Self-Deploy CLI (`company deploy`) — current path
@@ -2739,12 +2727,12 @@ This function:
- QR codes generated as base64 PNG in memory (no file I/O, no `data/qr` directory)
- Source: https://github.com/trohitg/whatsapp-rpc
- **Node Data Architecture**: `node.data` only stores `label` (display name). All parameters are stored in the database via `save_node_parameters` WebSocket handler. This prevents parameter bloat in workflow JSON exports and keeps React Flow state lightweight. `useDragAndDrop.ts` saves default parameters to DB on drop, not to `node.data`.
-- **Workflow Export/Import with Parameters**: Exported workflow JSON includes a `nodeParameters` field containing all node configuration (provider, model, prompt, skillsConfig, etc.) fetched from the database at export time. On import, embedded `nodeParameters` are saved back to the database. `sanitizeNodes()` in `workflowExport.ts` still strips `node.data` to UI-only fields (`label`, `disabled`, `condition`). A `parameterSanitizer.ts` utility exists for credential stripping but is currently disabled (pass-through). Old exports without `nodeParameters` import cleanly (backward compatible). Key files: `client/src/utils/workflowExport.ts`, `client/src/utils/parameterSanitizer.ts`, `client/src/Dashboard.tsx` (export/import handlers), `server/services/example_loader.py`.
+- **Workflow Export/Import with Parameters**: Exported workflow JSON includes a `nodeParameters` field containing all node configuration (provider, model, prompt, skillsConfig, etc.) fetched from the database at export time. On import, embedded `nodeParameters` are saved back to the database. `sanitizeNodes()` in `workflowExport.ts` still strips `node.data` to UI-only fields (`label`, `disabled`, `condition`). The `parameterSanitizer.ts` utility strips credential-bearing keys (SENSITIVE key sets + substring matching + runtime-key stripping) and is ACTIVE in the export path (`buildExportParameters` in `workflowExport.ts` calls `sanitizeParameters`). Old exports without `nodeParameters` import cleanly (backward compatible). Key files: `client/src/utils/workflowExport.ts`, `client/src/utils/parameterSanitizer.ts`, `client/src/Dashboard.tsx` (export/import handlers), `server/services/example_loader.py`.
- **Skill System Architecture**: Skills organized in `server/skills/<folder>/` subfolders. Each folder appears in Master Skill dropdown. DB is source of truth for skill instructions (seeded from SKILL.md on first load). Icon resolution mirrors `BaseNode._metadata_dict`: per-plugin `<plugin>/icon.svg` (served as `/api/schemas/nodes/<type>/icon`) → `visuals.json` (emoji / `lobehub:<brand>`); color: per-plugin `<plugin>/meta.json` → `visuals.json`. Lives in [`skill_loader.py::_parse_skill_metadata`](./server/services/skill_loader.py). Native DOM keydown handler prevents React Flow from intercepting Ctrl shortcuts in skill editor. **Mutation broadcasts use the CloudEvents-typed `skill_lifecycle` wire key** with stages `created` / `updated` / `deleted` / `content_saved` — see "Plugin-folder location for plugin-specific CloudEvents factories" below.
- **Example Workflows**: Auto-load example workflow seeds from `<repo>/.opencompany/workflows/` on first use (git-tracked; the only non-ignored content under `<repo>/.opencompany/`). Path resolved by `core.paths.example_workflows_dir()` — fixed, NOT under `DATA_DIR`, preserved by `company clean` via `_OPENCOMPANY_KEEP`. Uses `UserSettings.examples_loaded` flag; supports anonymous users (`user_id="default"`); embedded `nodeParameters` saved to DB on import.
- **Onboarding Service**: 5-step welcome wizard (Welcome, Concepts, API Keys, Canvas Tour, Get Started) using shadcn primitives + lucide icons. Database-backed via `UserSettings.onboarding_completed` + `onboarding_step`. Existing users auto-skip (migration marks `examples_loaded=1` as completed). Replayable from Settings "Help" section. No new WebSocket handlers needed. See [Onboarding Service](./docs-internal/onboarding.md) for details.
- **Node.js Code Executor**: Persistent Node.js server (Express + tsx) at port 3020 for JavaScript/TypeScript execution, replacing subprocess spawning per execution. The code executor plugins under `server/nodes/code/` call `NodeJSClient` which makes HTTP requests to the Node.js server. All config via environment variables (`NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_PORT`, etc.).
-- **writeTodos Tool Node**: Dedicated AI tool for task planning connecting to any agent's `input-tools` handle. `TodoService` singleton (`server/services/todo_service.py`) stores JSON-based per-session todo state keyed by workflow_id. Handler broadcasts `phase: "todo_update"` via WebSocket on each update for real-time UI; `formatTodoOutput()` in `OutputDisplayPanel.tsx` renders the result as a checklist with `[ ]` / `[~]` / `[x]` icons. Schema uses `TodoItem`/`TodoStatus` Pydantic enum. Skill at `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop.
+- **writeTodos Tool Node**: Dedicated AI tool for task planning connecting to any agent's `input-tools` handle. `TodoService` singleton (`server/services/todo_service.py`) stores JSON-based per-session todo state keyed by workflow_id. Handler broadcasts `phase: "todo_update"` via WebSocket on each update for real-time UI. (The former checklist rendering — `formatTodoOutput()` — lived only in the legacy `ui/OutputDisplayPanel.tsx`, which was deleted as dead code; the active `components/output/OutputPanel.tsx` shows todo results as regular JSON.) Schema uses `TodoItem`/`TodoStatus` Pydantic enum. Skill at `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop.
- **Temporal Activity Heartbeats**: Activities send `activity.heartbeat()` on every non-matching WebSocket broadcast inside the read loop in `services/temporal/activities.py`. This keeps long-running browser and claude_code_agent operations alive past the 2-minute `heartbeat_timeout`. Start/end heartbeats alone were causing `TIMEOUT_TYPE_HEARTBEAT` failures on ops taking 5-10 minutes. Connection config: `heartbeat=30`, `receive_timeout=540` (fits within 10-min `start_to_close_timeout`).
- **WebSocket `_safe_send` Guard**: `server/routers/websocket.py` checks `websocket.client_state.name != "CONNECTED"` before sending and logs at `debug` level (not `error`) on failure. Prevents "ASGI message after websocket.close" errors when broadcasts race with disconnects.
- **Claude Code CLI Flag**: the Claude Code agent (`nodes/agent/claude_code_agent/`) uses `--max-budget-usd <amount>` (previously incorrectly `--max-cost`, which caused "unknown option" errors on every run).
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index 68cc206f..c3341c86 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -9,203 +9,100 @@ company start
Open http://localhost:3000
-## CLI Commands
+## CLI Commands (`company`, Python Typer app under `cli/`)
-### Available Commands
+The CLI is the single orchestration surface — every `npm run <verb>` at
+the root is a thin wrapper over `python -m cli <verb>`. The old
+`scripts/{start,stop,build,clean,docker}.js` orchestrators were retired
+(each `cli/commands/<verb>.py` docstring records what it replaced).
+`machina` remains as a deprecated alias of `company` (prints a
+deprecation warning; kept for upgrade compatibility).
| Command | Description |
|---------|-------------|
-| `company start` | Start the development server (checks dependencies first) |
-| `company stop` | Stop all running services |
-| `company build` | Build the project for production (checks dependencies first) |
-| `company clean` | Clean build artifacts and node_modules |
-| `company docker:up` | Start with Docker Compose (detached) |
-| `company docker:down` | Stop Docker Compose services |
-| `company docker:build` | Build Docker images |
-| `company docker:logs` | View Docker logs (follows) |
-| `company help` | Show help message |
-
-### Dependency Checks
-
-The `start` and `build` commands verify these dependencies before running:
-- Node.js 22+
-- Python 3.12+
-- uv (Python package manager)
+| `company start` | Start all services in production mode (static client + uvicorn + temporal) |
+| `company dev` | Start in dev mode (Vite HMR + uvicorn + temporal). `--force` re-bundles Vite deps (recovers "Outdated Optimize Dep"); `--daemon` binds backend to 0.0.0.0 |
+| `company serve` | Single-port production runtime (uvicorn serves API + WS + built SPA + Node sidecar) — the systemd `ExecStart` on deployed VMs |
+| `company stop` | Stop all services and free configured ports |
+| `company build` | Full production build (pnpm install → client → sidecar → uv sync → bytecode → temporal binary) |
+| `company clean` | Stop services, then remove build artifacts, node_modules, `.venv`, repo-local state (preserves `.opencompany/{workflows,deploy,packages}`) |
+| `company deploy up/status/destroy` | Self-deploy a login-gated VM (gcloud preflight + Terraform; see `cli/commands/deploy/`) |
+| `company daemon start/stop/status/restart` | Detached backend management (PID file under user data dir) |
+| `company version sync` | Propagate the root package.json version |
+| `company docs nodes [--check]` | Regenerate (or verify) the `docs-internal/node-logic-flows/` index |
+| `company help` | Show help |
+
+### Dependency checks
+
+`start` and `build` verify Node.js 22+, Python 3.12+, and uv before
+running.
---
## npm Scripts
-Run with `npm run <script>` from the project root.
+Run with `npm run <script>` from the project root (`package.json` is
+the source of truth).
-### Core Scripts
+### CLI wrappers
-| Script | Command | Description |
-|--------|---------|-------------|
-| `start` | `node scripts/start.js` | Start all services concurrently |
-| `start:temporal` | `cross-env TEMPORAL_ENABLED=true node scripts/start.js` | Start with Temporal enabled |
-| `stop` | `node scripts/stop.js` | Stop all running services |
-| `build` | `node scripts/build.js` | Build entire project |
-| `clean` | `node scripts/clean.js` | Remove build artifacts |
+| Script | Command |
+|--------|---------|
+| `start` / `dev` / `serve` / `build` / `clean` / `stop` / `deploy` | `python -m cli <verb>` |
+| `start:temporal` | `cross-env TEMPORAL_ENABLED=true python -m cli start` |
+| `daemon:start` / `daemon:stop` / `daemon:status` / `daemon:restart` | `python -m cli daemon <verb>` |
+| `version:sync` | `python -m cli version sync` |
+| `docs:nodes` / `docs:nodes:check` | `python -m cli docs nodes [--check]` |
-### Service Scripts
+### Service scripts
| Script | Command | Description |
|--------|---------|-------------|
-| `client:start` | `cd client && npm run start` | Start React frontend (Vite) |
-| `python:start` | `cd server && uv run uvicorn main:app ...` | Start Python backend |
-| `temporal:worker` | `cd server && uv run python -m services.temporal.worker` | Start standalone Temporal worker |
+| `client:start` | `cd client && npm run start` | React frontend (Vite dev server) |
+| `python:start` | `cd server && uv run uvicorn main:app --host 127.0.0.1 --port 3010 ...` | Backend only |
+| `python:daemon` | same, bound to `0.0.0.0` | Backend only, LAN-reachable |
+| `temporal:worker` | `cd server && uv run python -m services.temporal.worker` | Standalone Temporal worker |
Temporal server lifecycle is managed by `company start` / `company dev` / `company stop` directly (see [Temporal Architecture](./TEMPORAL_ARCHITECTURE.md)). The official `temporal` CLI is downloaded by `pooch` to `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default) during `company build` and spawned as a supervised subprocess.
-### Docker Scripts (Development)
-
-| Script | Command | Description |
-|--------|---------|-------------|
-| `docker:up` | `node scripts/docker.js up` | Start dev stack (detached) |
-| `docker:down` | `node scripts/docker.js down` | Stop dev stack |
-| `docker:build` | `node scripts/docker.js build` | Build dev images |
-| `docker:logs` | `node scripts/docker.js logs` | View logs (follows) |
-| `docker:restart` | `node scripts/docker.js restart` | Restart dev stack |
-
-### Docker Scripts (Production)
-
-| Script | Command | Description |
-|--------|---------|-------------|
-| `docker:prod:up` | `docker-compose -f docker-compose.prod.yml up -d` | Start production stack |
-| `docker:prod:down` | `docker-compose -f docker-compose.prod.yml down` | Stop production stack |
-| `docker:prod:build` | `docker-compose -f docker-compose.prod.yml build` | Build production images |
-| `docker:prod:logs` | `docker-compose -f docker-compose.prod.yml logs -f` | View production logs |
-
-### Deployment Scripts
-
-| Script | Command | Description |
-|--------|---------|-------------|
-| `deploy` | `python -m cli deploy` | Self-deploy to a cloud VM (`company deploy up/status/destroy` — gcloud preflight + Terraform; see `cli/commands/deploy/`) |
-
-The legacy `deploy.sh` (SCP + docker-compose to a GCE box) was removed; `company deploy`
-provisions a login-gated VM natively via the operator's cloud CLI + Terraform.
-
----
-
-## Script Details
-
-### start.js
-
-**Location:** `scripts/start.js`
-
-Cross-platform start script that runs all services concurrently.
-
-**What it does** (mirrored by the canonical `company start` / `company dev` CLI commands):
-1. Validates build artifacts exist
-2. Creates `.env` from `.env.template` if missing
-3. Frees configured app ports (client, backend, WhatsApp, Node.js executor, Temporal gRPC, Temporal UI)
-4. Spawns each service in its own process group (Windows: `CREATE_NEW_PROCESS_GROUP` for graceful `CTRL_BREAK_EVENT` shutdown):
- - Static client server (`serve-client.js`)
- - Python backend (uvicorn) -- supervises the edgymeow Go binary lazily via [server/nodes/whatsapp/_runtime.py](../server/nodes/whatsapp/_runtime.py)
- - Temporal dev server -- the supervised-runtime shim ([server/services/temporal/_supervised_runtime.py](../server/services/temporal/_supervised_runtime.py)) spawning `temporal server start-dev`
-
-**Temporal handling:** The supervisor's TCP readiness probe on 7233 short-circuits if Temporal is already running, so launching `company start` against a pre-existing Temporal works without conflict.
-
-**Ports (configurable in .env):**
-- `VITE_CLIENT_PORT` - Frontend (default: 3000)
-- `PYTHON_BACKEND_PORT` - Backend (default: 3010)
-- `WHATSAPP_RPC_PORT` - WhatsApp (default: 9400)
-
-**Platform support:** Windows, macOS, Linux, WSL, Git Bash
-
----
-
-### build.js
-
-**Location:** `scripts/build.js`
+### Tests
-Production build script that compiles all components.
+| Script | Command |
+|--------|---------|
+| `test` | backend + frontend suites |
+| `test:backend` | `cd server && uv run pytest tests/ -v` |
+| `test:frontend` | `cd client && npm run test` (vitest) |
+| `test:nodes` | node-plugin tests with handler coverage |
-**Build steps:**
-1. `[0/6]` Create `.env` from template if missing
-2. `[1/6]` Install root dependencies (`npm ci` or `npm install`)
-3. `[2/6]` Install client dependencies
-4. `[3/6]` Build client (`vite build`)
-5. `[4/6]` Install Python dependencies (`uv venv && uv sync`)
-6. `[5/6]` Install WhatsApp dependencies
-7. `[6/6]` Build WhatsApp Go binary
+### Lifecycle hooks
-**Dependencies checked:**
-- Node.js, npm, Python, uv, Go
+| Script | File | Purpose |
+|--------|------|---------|
+| `preinstall` / `preuninstall` | `scripts/preinstall.js` | Removes the legacy `machinaos` global package / stale temp dirs before (un)install |
+| `postinstall` | `scripts/postinstall.js` | End-user install pipeline for the npm tarball (delegates to `scripts/install.js`) |
---
-### stop.js
+## Files actually in `scripts/`
-**Location:** `scripts/stop.js`
+| File | Purpose |
+|------|---------|
+| `install.js` | npm-tarball install pipeline (pnpm/uv install, client + sidecar build, bytecode compile, temporal binary fetch) — mirrors `company build`; the compileall command shape is locked in sync by `cli/tests/test_release_pipeline_config.py` |
+| `preinstall.js` | Legacy-package/temp cleanup (also runs on uninstall) |
+| `postinstall.js` | npm lifecycle entry that guards recursion and invokes install.js |
+| `serve-client.js` | Static client server used by `company start` (production mode, no Vite) |
+| `migrate_icons.py`, `migrate_skill_icons.py` | One-off icon-migration utilities (historical) |
-Cross-platform stop script that kills all OpenCompany processes.
-
-**What it does:**
-1. Reads port configuration from `.env`
-2. Finds processes on each port
-3. Kills processes including child processes
-4. Verifies processes are stopped
-5. Retries stubborn processes with force kill
-6. Kills Temporal processes via `killByPattern('temporal')`
-
-**Platform-specific commands:**
-| Platform | Find processes | Kill process |
-|----------|----------------|--------------|
-| Unix/Mac | `lsof -ti:PORT` | `kill -15`, then `kill -9` |
-| Linux | `ss -tlnp` (fallback) | `kill -15`, then `kill -9` |
-| Windows | `netstat -ano \| findstr` | `taskkill /PID` |
-
----
-
-### clean.js
-
-**Location:** `scripts/clean.js`
-
-Removes build artifacts and dependencies.
-
-**Directories removed:**
-- `node_modules/` - Root dependencies
-- `client/node_modules/` - Frontend dependencies
-- `client/dist/` - Built frontend
-- `client/.vite/` - Vite cache
-- `server/.venv/` - Python virtual environment
-- `.opencompany/` - Repo-local DATA_DIR opt-out (only present when `DATA_DIR=.opencompany`; the default `~/.opencompany/` lives in your home dir and is never touched)
-
----
-
-### docker.js
-
-**Location:** `scripts/docker.js`
-
-Docker Compose wrapper with automatic Redis profile detection.
-
-**Usage:**
-```bash
-node scripts/docker.js <command> [args...]
-```
-
-**Commands:** `up`, `down`, `build`, `logs`, `restart`
-
-**Features:**
-- Creates `.env` from template if missing
-- Reads `REDIS_ENABLED` from `.env`
-- Adds `--profile redis` flag when Redis is enabled
-- `up` runs detached (`-d`) by default
-- `logs` follows (`-f`) by default
-
-**Example output:**
-```
-[Docker] Redis profile enabled (REDIS_ENABLED=true in .env)
-[Docker] Running: docker-compose --profile redis up -d
-```
+There is no Docker tooling: Docker Compose support was removed
+(historical topology preserved in
+[deployment_legacy.md](./deployment_legacy.md)); deployment is
+`company deploy` (Terraform → GCP VM → systemd).
---
## Environment Variables
-Key variables in `.env` (see `.env.template` for full list):
+Key variables in `.env` (see `.env.template` for the full list):
### Ports
| Variable | Default | Description |
@@ -213,38 +110,25 @@ Key variables in `.env` (see `.env.template` for full list):
| `VITE_CLIENT_PORT` | 3000 | Frontend port |
| `PYTHON_BACKEND_PORT` | 3010 | Backend port |
| `WHATSAPP_RPC_PORT` | 9400 | WhatsApp API port |
+| `NODEJS_EXECUTOR_PORT` | 3020 | Node.js code-executor sidecar |
+| — | 7233 / 8080 | Temporal gRPC / Temporal Web UI |
### Features
| Variable | Default | Description |
|----------|---------|-------------|
-| `TEMPORAL_ENABLED` | false | Enable Temporal worker |
-| `REDIS_ENABLED` | false | Enable Redis cache (uses SQLite if false) |
-
-### Redis (when enabled)
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `REDIS_URL` | redis://redis:6379 | Redis connection URL |
-| `REDIS_PORT` | 6379 | Redis port |
+| `TEMPORAL_ENABLED` | (see `.env.template`) | Temporal execution engine |
+| `REDIS_ENABLED` | false | Redis cache (SQLite fallback when false) |
---
## Required Dependencies
-### For `start` and `build` commands
-
| Dependency | Version | Install |
|------------|---------|---------|
-| Node.js | 18+ | https://nodejs.org/ |
-| Python | 3.11+ | https://python.org/ |
+| Node.js | 22+ | https://nodejs.org/ |
+| Python | 3.12+ (CLI); server venv accepts 3.11–3.12 | https://python.org/ |
| uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
-| Go | latest | https://go.dev/dl/ (for WhatsApp binary) |
-
-### For Docker commands
-
-| Dependency | Install |
-|------------|---------|
-| Docker | https://docs.docker.com/get-docker/ |
-| Docker Compose | Included with Docker Desktop |
+| pnpm | 9.x | `corepack enable` (root `packageManager` pin) |
---
@@ -252,21 +136,17 @@ Key variables in `.env` (see `.env.template` for full list):
```bash
# Development
-company start # Start all services
+company dev # Vite HMR + backend + temporal
+company dev --force # ...forcing a Vite dependency re-bundle
+company start # Production mode (static client)
company stop # Stop all services
-# Build
-company build # Build for production
-company clean # Clean everything
-
-# Docker (development)
-company docker:up # Start containers
-company docker:down # Stop containers
-company docker:logs # View logs
-company docker:build # Rebuild images
+# Build / clean
+company build # Full production build
+company clean # Clean everything (keeps workflows/deploy/packages state)
-# Docker (production)
-npm run docker:prod:up # Start production
-npm run docker:prod:down # Stop production
-npm run deploy # Deploy to server
+# Deploy
+company deploy up --provider gcp --owner-email [email protected]
+company deploy status
+company deploy destroy
```
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index acad7c5c..05f33aae 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -25,12 +25,13 @@ The repo currently ships **exactly 4 workflows** plus one composite action. A nu
| +---------------------+
+-- publish-npm
+-- publish-github-packages
-
- push to main under +------------------+
- docs-OpenCompany/ ------> | docs.yml | Mintlify documentation deploy
- +------------------+
```
+> Documentation is NOT deployed from this repo: the Mintlify docs live in
+> the separate [zeenie-ai/docs-OpenCompany](https://github.com/zeenie-ai/docs-OpenCompany)
+> repo and auto-deploy to docs.zeenie.xyz via the Mintlify GitHub app
+> (that repo's own workflow only runs `mintlify validate` + broken-links).
+
### Workflow summary
| Workflow | File | Triggers | Purpose |
@@ -38,7 +39,6 @@ The repo currently ships **exactly 4 workflows** plus one composite action. A nu
| CI | `.github/workflows/ci.yml` | push/PR → main | Delegates to predeploy.yml |
| Predeploy | `.github/workflows/predeploy.yml` | `workflow_call` | build/lint + backend tests + CLI tests + cross-OS build/start smoke |
| Release | `.github/workflows/release.yml` | `v*.*.*` tag, `workflow_dispatch` | predeploy gate → publish (npm + GitHub Packages) |
-| Docs | `.github/workflows/docs.yml` | push to `docs-OpenCompany/**` on main + manual | Mintlify deploy |
| Setup | `.github/actions/setup/action.yml` | (composite) | pnpm 9 + Node 22 + Python 3.12 + uv v8 + editable CLI install |
### Toolchain pin
@@ -51,7 +51,6 @@ The repo currently ships **exactly 4 workflows** plus one composite action. A nu
|--------|---------|-------------|
| `NPM_TOKEN` | release.yml | npmjs publish access to the public `@zeenie` scope (`publish-npm`) |
| `GITHUB_TOKEN` | release.yml | GitHub Packages publish (auto-provided) |
-| `MINTLIFY_TOKEN` | docs.yml | Mintlify documentation deployment |
---
@@ -134,11 +133,15 @@ There is currently no audit gate, no PyPI publish, no SLSA `attest-build-provena
---
-## Docs workflow
-
-**File:** [.github/workflows/docs.yml](../.github/workflows/docs.yml)
+## Documentation deployment (separate repo)
-Triggers on push to `main` touching `docs-OpenCompany/**` + manual dispatch. Single `deploy` job: `actions/checkout` → `actions/setup-node@v4` (Node 22) → `npm install -g mintlify` → `mintlify deploy` from `docs-OpenCompany/` with `MINTLIFY_TOKEN`. No predeploy gate — docs are static, independent of the application build.
+The public Mintlify docs (docs.zeenie.xyz) live in the separate
+[zeenie-ai/docs-OpenCompany](https://github.com/zeenie-ai/docs-OpenCompany)
+repo. Deployment happens automatically via the Mintlify GitHub app on
+pushes to that repo's `main`; its own workflow only validates
+(`mintlify validate` + broken-links). This repo previously carried a
+`docs.yml` deploy workflow targeting an in-repo `docs-OpenCompany/`
+folder — both the folder and the workflow are gone.
---
@@ -149,7 +152,6 @@ Triggers on push to `main` touching `docs-OpenCompany/**` + manual dispatch. Sin
| `.github/workflows/ci.yml` | CI entry point (delegates to predeploy.yml) |
| `.github/workflows/predeploy.yml` | Reusable validation (build/lint + backend tests + CLI tests + OS matrix build/start) |
| `.github/workflows/release.yml` | Tag / manual release: predeploy gate → publish npm + GitHub Packages |
-| `.github/workflows/docs.yml` | Mintlify documentation deploy |
| `.github/actions/setup/action.yml` | Composite: pnpm + Node + Python + uv + editable CLI install |
| `.python-version` | Toolchain pin (`3.12`) — single source of truth |