Add flow runtime and Codex release flows

docs/flows.md

@@ -0,0 +1,164 @@
+# Flows
+
+Flows are packaged automation units. They are discovered from `.codex/flows/*`
+first and then `flows/*`, with the installed `.codex` copy taking precedence.
+
+Each flow has:
+
+```text
+flow.toml
+schemas/*.schema.json
+exec/*
+```
+
+`flow.toml` is the manifest. Use `flow` naming consistently:
+
+```toml
+name = "example-flow"
+version = 1
+description = "Short operational purpose."
+
+[config]
+commit = true
+
+[[steps]]
+name = "do-work"
+runner = "bun"
+script = "exec/do-work.ts"
+timeout_ms = 300000
+
+[steps.trigger]
+type = "upstream.release"
+schema = "schemas/upstream-release.schema.json"
+```
+
+The runtime passes a generic event to every step:
+
+```ts
+type FlowEvent<T = unknown> = {
+  id: string;
+  type: string;
+  source?: string;
+  occurredAt?: string;
+  receivedAt: string;
+  payload: T;
+};
+```
+
+Domain payload types live in each flow package as JSON Schema files and are
+referenced by `steps.trigger.schema`.
+
+## Runners
+
+`runner = "bun"` executes the script directly with Bun. The step receives JSON
+on stdin:
+
+```json
+{
+  "flow": {
+    "name": "example-flow",
+    "version": 1,
+    "root": "/repo/flows/example-flow",
+    "step": "do-work",
+    "config": {},
+    "event": {}
+  }
+}
+```
+
+The script must print a final line beginning with `FLOW_RESULT ` followed by
+JSON.
+
+`runner = "code-mode"` starts a Codex app-server and calls the fork-only
+`thread/codeMode/execute` method through a raw JSON-RPC request. Code Mode code
+is present on `main`, but execution is disabled unless:
+
+```bash
+CODEX_FLOWS_ENABLE_CODE_MODE=1
+```
+
+Set `CODEX_APP_SERVER_CODEX_COMMAND` when Code Mode should run against the
+Peezy fork instead of the default `codex` binary.
+
+## Commands
+
+List flows:
+
+```bash
+bun run flow list
+```
+
+Fire all matching steps for an event:
+
+```bash
+bun run flow fire --event event.json
+```
+
+Run one step:
+
+```bash
+bun run flow run openai-codex-bindings regenerate-bindings --event event.json
+```
+
+## Systemd-Local Backend
+
+`codex-flow-systemd-local` is the first execution backend. Patchbay posts
+generic `FlowEvent` JSON to this service; the service persists events and runs
+to SQLite, discovers matching flow steps, and starts each step locally.
+
+Run it directly:
+
+```bash
+bun run flow:backend serve --cwd /home/peezy/codex-flows-public
+```
+
+Useful environment:
+
+```bash
+CODEX_FLOW_BACKEND_HOST=127.0.0.1
+CODEX_FLOW_BACKEND_PORT=7345
+CODEX_FLOW_BACKEND_DATA_DIR=/var/lib/codex-flow-systemd-local
+CODEX_FLOW_BACKEND_SECRET=shared-hmac-secret
+CODEX_FLOW_BACKEND_EXECUTOR=direct
+```
+
+`CODEX_FLOW_BACKEND_EXECUTOR=systemd-run` wraps each step in a transient
+`systemd-run --user --wait --collect` unit. The default `direct` executor is
+still suitable when the backend service itself is managed by systemd.
+
+Endpoints:
+
+- `POST /events` or `POST /flow-events`: accept one `FlowEvent`
+- `GET /runs?eventId=<id>`: inspect recorded runs for an event
+- `GET /healthz`: health check
+
+## Convex Backend Direction
+
+Convex should be a durable orchestration backend, not the place where long
+running Codex or shell work executes. A future Convex backend should:
+
+- accept the same generic `FlowEvent` shape
+- persist event, run, step, retry, and result records durably
+- choose matching flow steps from a stored or installed flow manifest
+- lease work to an external worker or remote app-server
+- receive heartbeats and final `FLOW_RESULT` records from that worker
+- expose programmatic fire/retry/cancel APIs
+
+This keeps Patchbay dispatch-only, keeps Convex durable, and keeps process-heavy
+work on infrastructure that can run Codex, Bun, Git, Cargo, and system tools.
+
+## Codex Release Flows
+
+The upstream `openai/codex` release event fans out to two flow packages:
+
+- `openai-codex-bindings`: Bun runner. Uses canonical `@openai/codex@version`,
+  regenerates `@peezy.tech/codex-flows` app-server bindings, runs checks,
+  commits when changed, and can push/trigger trusted publishing when configured.
+- `peezy-codex-fork`: Code Mode runner. Rebases the Peezy fork patch stack onto
+  the upstream release tag, optionally squashes the patch stack, verifies the
+  fork, and can push/tag to trigger the fork release workflow when configured.
+
+Publishing is controlled by flow config and environment. The packaged defaults
+commit local changes when appropriate but do not push or publish until
+`push = true`, `publish = true`, or matching `CODEX_FLOW_PUSH=1` /
+`CODEX_FLOW_PUBLISH=1` deployment configuration is set.