chore(_example): add in-memory executor scripts and improve onboarding docs

packages/_example/README.md

@@ -55,51 +55,76 @@ yarn start
 
 `start:with-executor` launches both the agent and the workflow executor side-by-side using `concurrently`. The executor waits for the agent to be ready before starting.
 
-### 1. Start the executor's Postgres database
+### Quick start (in-memory, no database required)
 
-```bash
-yarn db:executor:up
+#### 1. Add executor variables to `.env`
+
+```dotenv
+# Workflow executor
+EXECUTOR_AGENT_URL=http://localhost:3351  # must match the port your agent listens on
+OPENAI_API_KEY=sk-...                     # or ANTHROPIC_API_KEY
 ```
 
-Starts a dedicated Postgres container on `localhost:5452` (separate from the agent databases).
+`FOREST_ENV_SECRET` and `FOREST_AUTH_SECRET` are already required by the agent and are reused by the executor automatically.
+
+#### 2. Install `tsx` (if not already available)
 
-### 2. Add executor variables to `.env`
+```bash
+npm install -g tsx
+```
 
-The script sources the `_example` `.env` file and maps two variables to the executor's expected names. Add these to your `.env`:
+#### 3. Start both processes
 
-```dotenv
-# Workflow executor
-EXECUTOR_AGENT_URL=http://localhost:3310   # must match the port your agent listens on
-EXECUTOR_DATABASE_URL=postgres://executor:password@localhost:5452/workflow_executor
+```bash
+yarn start:with-executor:with-openai:in-memory
+# or
+yarn start:with-executor:with-anthropic:in-memory
 ```
 
-`FOREST_ENV_SECRET` and `FOREST_AUTH_SECRET` are already required by the agent and are reused by the executor automatically.
+Run state is kept in memory and lost on restart. Use this for local development and testing.
+
+---
 
-### 3. Install `tsx` (if not already available)
+### Persistent mode (Postgres)
 
-The executor CLI uses `tsx` for fast TypeScript execution without a build step:
+Use the database-backed scripts when you need run history to survive restarts.
+
+#### 1. Start the executor's Postgres database
 
 ```bash
-npm install -g tsx
+yarn db:executor:up
+```
+
+Starts a dedicated Postgres container on `localhost:5459` (separate from the agent databases).
+
+#### 2. Add executor variables to `.env`
+
+```dotenv
+# Workflow executor
+EXECUTOR_AGENT_URL=http://localhost:3351
+EXECUTOR_DATABASE_URL=postgres://executor:password@localhost:5459/workflow_executor
+OPENAI_API_KEY=sk-...                     # or ANTHROPIC_API_KEY
 ```
 
-### 4. Start both processes
+#### 3. Start both processes
 
 ```bash
-yarn start:with-executor
+yarn start:with-executor:with-openai
+# or
+yarn start:with-executor:with-anthropic
 ```
 
-Expected output (two prefixed streams):
+Expected output:
 
 ```
-[agent]    Forest Admin agent listening on port 3310
+[agent]    Forest Admin agent listening on port 3351
 [executor] [forest-workflow-executor] Starting (database mode)
 [executor] [forest-workflow-executor] Ready on http://localhost:3400
 [executor] {"message":"Poll cycle completed","fetched":0,"dispatching":0}
 ```
 
-### Teardown
+#### Teardown
 
 ```bash
-yarn db:executor:down   # stop the executor DB container
+yarn db:executor:down
 ```

packages/_example/package.json

@@ -46,7 +46,9 @@
     "db:seed": "ts-node scripts/db-seed.ts",
     "start:with-executor": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && DATABASE_URL=\\$EXECUTOR_DATABASE_URL && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty'\"",
     "start:with-executor:with-openai": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && DATABASE_URL=\\$EXECUTOR_DATABASE_URL && AI_PROVIDER=openai && AI_MODEL=gpt-4o && AI_API_KEY=\\$OPENAI_API_KEY && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty'\"",
+    "start:with-executor:with-openai:in-memory": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && AI_PROVIDER=openai && AI_MODEL=gpt-4o && AI_API_KEY=\\$OPENAI_API_KEY && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty --in-memory'\"",
     "start:with-executor:with-anthropic": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && DATABASE_URL=\\$EXECUTOR_DATABASE_URL && AI_PROVIDER=anthropic && AI_MODEL=claude-sonnet-4-6 && AI_API_KEY=\\$ANTHROPIC_API_KEY && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty'\"",
+    "start:with-executor:with-anthropic:in-memory": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && AI_PROVIDER=anthropic && AI_MODEL=claude-sonnet-4-6 && AI_API_KEY=\\$ANTHROPIC_API_KEY && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty --in-memory'\"",
     "start:with-executor:ai-error": "concurrently --kill-others --names 'agent,executor' \"yarn start\" \"bash -c 'set -a && source .env && AGENT_URL=\\$EXECUTOR_AGENT_URL && DATABASE_URL=\\$EXECUTOR_DATABASE_URL && FORCE_AI_ERROR=true && until curl -s \\$EXECUTOR_AGENT_URL >/dev/null 2>&1; do sleep 1; done && tsx watch ../workflow-executor/src/cli.ts --pretty'\"",
     "db:executor:up": "cd ../workflow-executor/example && docker compose up -d",
     "db:executor:down": "cd ../workflow-executor/example && docker compose down",

packages/workflow-executor/.env.example

@@ -0,0 +1,3 @@
+AGENT_URL=http://localhost:3351
+FOREST_ENV_SECRET=your_env_secret_here
+FOREST_AUTH_SECRET=your_auth_secret_here

packages/workflow-executor/package.json

@@ -23,7 +23,9 @@
     "build:watch": "tsc --watch",
     "clean": "rm -rf coverage dist",
     "lint": "eslint src test",
-    "test": "jest"
+    "test": "jest",
+    "start": "tsx --env-file=.env src/cli.ts --pretty",
+    "start:in-memory": "tsx --env-file=.env src/cli.ts --pretty --in-memory"
   },
   "dependencies": {
     "@forestadmin/agent-client": "1.5.10",