# Operations Runbook

## Local Runtime

Canonical local verification URL:

```text
http://127.0.0.1:4217/demo-website
```

Start from the `development` checkout after merging task work:

```bash
npm run dev -- --port 4217 --host 127.0.0.1
```

If port `4217` is occupied by a stale Zonegaze Flow process, stop the stale process and restart from the merged `development` checkout.

Direct app users should not need this contributor command. See [Direct Mac application](../platforms/direct-mac-application.md) and [Direct Android application](../platforms/android-application.md).

## Validation

Run the narrowest proving check first, then broader checks:

```bash
node scripts/generate-docs-inventory.mjs
npx typedoc
node scripts/check-docs.mjs
npm run check:boundaries
npm run typecheck
npm run check       # build + all JS/TS tests; mirrors the CI build-check-test job
npm run android:test # Android JVM unit tests (JDK + SDK required)
```

The CI `Test` workflow runs three jobs: `build-check-test` (matches `npm run check`), `e2e-smoke` (Playwright against a booted runtime), and `android-unit-tests`. See the [QA checklist](qa-checklist.md) for the manual pre-release pass across web, Mac, and Android.

## Screenshot Capture

Use `project-testing/project-test-zonegaze-flow-###` for raw captures and notes. Promote only durable screenshots into `docs/assets/screenshots/`.

Required views:

- board
- task create dialog
- task detail/diff review
- Cline/ZoneGaze chat
- settings/Cline setup
- git history
- project browser
- mobile viewport

## Common Incidents

- Runtime disconnected: restart runtime and verify websocket route.
- Agent start failure: check binary detection, provider config, and task worktree.
- Git lock or conflict: stop automation, preserve worktree, inspect lock/stash state.
- Cline provider issue: inspect SDK-backed provider state and avoid writing secrets into runtime config.
- Remote/headless folder picker unavailable: use manual path entry.

## Release Closeout

1. Validate locally.
2. Commit task branch.
3. Pull `development`.
4. Merge task branch into `development`.
5. Re-run required validation from joined branch.
6. Push `origin/development`.
7. Restart the app from `development`.

## Direct App Release Notes

- Mac packaging is documented in [Direct Mac application](../platforms/direct-mac-application.md) and sourced from `platforms/desktop/electron-builder.yml`.
- Android packaging is documented in [Direct Android application](../platforms/android-application.md) and sourced from `platforms/android/app/build.gradle.kts` plus the Zone Terminal setup flow.
