monorepo wit docs

docs/pages/tutorials/dispatch-codex-release-flow.md

@@ -0,0 +1,44 @@
+---
+title: Dispatch a Codex release flow
+description: Connect the OpenAI Codex release feed to codex-flow automation.
+---
+
+# Dispatch a Codex release flow
+
+Patch was built to let upstream release activity trigger generic codex-flow
+automation without putting Codex-specific completion logic into Patch itself.
+
+## 1. Use the release source
+
+The bundled `apps/patch/feed-sources.json` includes
+`github-openai-codex-releases`. Its target emits `upstream.release` events with
+the upstream repository and release tag in the payload.
+
+## 2. Point Patch at a backend
+
+```bash
+PATCH_FLOW_DISPATCH_URL=http://127.0.0.1:7345/events \
+PATCH_FLOW_DISPATCH_SECRET=dev-secret \
+DATA_DIR=./data \
+FEED_SOURCES_PATH=./feed-sources.json \
+bun run --filter @peezy.tech/patch start
+```
+
+`PATCH_FLOW_DISPATCH_URL` can point at the `/events` endpoint or at the backend
+base URL. Patch normalizes either form before it creates the shared flow client.
+
+## 3. Inspect the stored event
+
+```bash
+curl http://127.0.0.1:3000/flow-events
+```
+
+When `PATCH_ADMIN_TOKEN` is set, include either `Authorization: Bearer <token>`
+or `X-Patch-Admin-Token: <token>`.
+
+## 4. Keep completion app-owned
+
+Patch dispatches the generic event. The installed Codex release flow owns the
+work that happens next: matching `flow.toml`, running steps, checking gates, and
+emitting `FLOW_RESULT`. Product-specific completion stays in that flow package
+or its backend worker.

docs/pages/tutorials/watch-upstream-release.md

@@ -0,0 +1,65 @@
+---
+title: Watch an upstream release
+description: Configure a release feed and store the first Patch flow event.
+---
+
+# Watch an upstream release
+
+This tutorial creates the smallest useful release watcher: one upstream release
+feed that becomes a stored `upstream.release` flow event.
+
+## 1. Add a feed source
+
+Create or edit `apps/patch/feed-sources.json`:
+
+```json
+{
+  "sources": [
+    {
+      "id": "github-openai-codex-releases",
+      "provider": "github",
+      "url": "https://github.com/openai/codex/releases.atom",
+      "event": "release",
+      "repo": {
+        "owner": "openai",
+        "name": "codex",
+        "fullName": "openai/codex",
+        "webUrl": "https://github.com/openai/codex",
+        "defaultBranch": "main"
+      },
+      "target": {
+        "mode": "flow_dispatch",
+        "eventType": "upstream.release",
+        "dispatchUrlEnv": "PATCH_FLOW_DISPATCH_URL",
+        "dispatchSecretEnv": "PATCH_FLOW_DISPATCH_SECRET",
+        "payload": {
+          "provider": "github",
+          "repo": "openai/codex"
+        }
+      }
+    }
+  ]
+}
+```
+
+## 2. Start Patch
+
+```bash
+DATA_DIR=./data \
+FEED_SOURCES_PATH=./feed-sources.json \
+bun run --filter @peezy.tech/patch dev
+```
+
+The first poll primes `data/feed-state.json`. By default, old feed entries are
+not emitted on that first pass.
+
+## 3. Dispatch new releases
+
+When the feed later contains an unseen release entry, Patch appends:
+
+- `data/feed-events.jsonl` for the normalized signal.
+- `data/flow-events.jsonl` for the generic flow event.
+- `data/flow-dispatches.jsonl` for the dispatch outcome.
+
+If `PATCH_FLOW_DISPATCH_URL` is not set, Patch uses local flow execution from
+the working directory. If it is set, Patch sends the event to the HTTP backend.