Documentation is out of date and worker onboarding path is wrong #28

New Issue

2026-09-08T20:57:31-04:00

jared commented

2026-09-08 20:57:31 -04:00

Overview

README issues that trip up anyone setting PULSE up or trying to use workflows:

"Workflow Creation (Future Feature)" – workflows, prompts, routes, params, dry-run and the Scheduler all exist but are undocumented.
Database schema section lists executions.worker_id/command/output/created_at and workers.last_seen – none exist; real columns are logs, started_at, last_heartbeat, plus the scheduled_commands table which is not mentioned.
Worker setup says to clone the repo to /opt/pulse-worker and run node worker.js, but worker.js lives in worker/, and the repo contains no worker/package.json (the deployed worker on CT153 has its own with axios, node-fetch, ws, dotenv). npm install at repo root will not install axios.
package.json: "main": "index.js", no start script, licence ISC vs README MIT (no LICENSE file).
Env vars HOST, GANDALF_API_KEY, EXECUTION_MAX_MINUTES, NODE_ENV are used but undocumented; no .env.example for server or worker.
Troubleshooting "Commands Stuck in Running – this was fixed" is not accurate (see the stuck-execution issue).

Suggested fix

Commit worker/package.json and .env.example files, add a Workflow Reference section (all step types + fields + a worked example), correct the schema tables, add npm start.

## Overview README issues that trip up anyone setting PULSE up or trying to use workflows: - "Workflow Creation (Future Feature)" – workflows, prompts, routes, params, dry-run and the Scheduler all exist but are undocumented. - Database schema section lists `executions.worker_id/command/output/created_at` and `workers.last_seen` – none exist; real columns are `logs`, `started_at`, `last_heartbeat`, plus the `scheduled_commands` table which is not mentioned. - Worker setup says to clone the repo to `/opt/pulse-worker` and run `node worker.js`, but `worker.js` lives in `worker/`, and the repo contains no `worker/package.json` (the deployed worker on CT153 has its own with `axios`, `node-fetch`, `ws`, `dotenv`). `npm install` at repo root will not install `axios`. - `package.json`: `"main": "index.js"`, no `start` script, licence `ISC` vs README `MIT` (no LICENSE file). - Env vars `HOST`, `GANDALF_API_KEY`, `EXECUTION_MAX_MINUTES`, `NODE_ENV` are used but undocumented; no `.env.example` for server or worker. - Troubleshooting "Commands Stuck in Running – this was fixed" is not accurate (see the stuck-execution issue). ## Suggested fix Commit `worker/package.json` and `.env.example` files, add a Workflow Reference section (all step types + fields + a worked example), correct the schema tables, add `npm start`.

jared added the ux documentation worker priority/medium labels 2026-09-08 20:57:31 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: LotusGuild/pulse#28