Work on API and dashboard

Start an API workspace in Orca and select Run on shipyard. Setup runs automatically and Orca waits for readiness before starting the agent. The recorded base is shipyard-ready, which contains merged API worktree changes plus the still-open nodemon fix. See Orca configuration before changing it.

API only

Use the API task normally. Setup invokes the repository’s reviewed lifecycle scripts, starts npm run dev, and checks health. No dashboard checkout or process is created until requested. Do not launch a second API process.

On Shipyard, set TASK_ROOT to the absolute path of the selected API worktree:

TASK_ROOT=/absolute/path/to/api-worktree
python3 ~/dev-environment/scripts/orca-task.py status --root "$TASK_ROOT"

Status reads .worktree/orca-task.json. Inspect apiPort and apiSession; do not reuse ports from an old report. Status process presence alone is not an application health check.

Add dashboard in the same agent session

Coordinate with anyone using the current preview, then run:

python3 ~/dev-environment/scripts/orca-task.py dashboard --root "$TASK_ROOT"

This creates or restores .worktree/dashboard, a separate dashboard Git worktree with its own dependencies. Its preview uses port 3003 and proxies to this API. Switching stops the previously managed preview, preserving files and edits; it does not kill unrelated processes occupying the port.

Use git -C "$TASK_ROOT/.worktree/dashboard" status and separate commits/PRs. Orca’s API source panel does not combine both repositories. Read the dashboard’s repository instructions as well.

Restart and stop

setup --root "$TASK_ROOT" restarts the managed API through the normal lifecycle while preserving data. archive --root "$TASK_ROOT" stops task services and retains volumes. It moves the companion dashboard outside the API directory so deleting the API checkout does not erase companion edits.

Do not repeatedly pass --seed or reset first-attempt markers to fix startup. First-time failures require the setup runbook. Repository seeding uses the primary local seed, not a staging connection. Authorization reconciliation generates local revision tokens; streaming CDC covers subsequent changes rather than historical analytics backfill.

Verify

Read the current port, request /health directly on Shipyard and through http://127.0.0.1:3003/health, then use the Linux browser for the relevant authenticated behavior. A successful health endpoint does not prove camera images, external services or every application workflow.