iterate

Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.

We do not accept unexplained, unbounded, or silently tolerated system behaviour. An error is either an explicitly modelled and correctly classified expected outcome, or it is a product defect. The same rule applies to retry storms, stuck work, silent data loss, unexplained latency, state drift, and resource leaks.

• Never normalize an error counter merely because it is noisy or longstanding. Classify every contributing outcome, remove expected outcomes from error telemetry, and fix the rest.
• Never swallow, endlessly retry, or hide failures behind fallbacks or compatibility shims. Recovery must be bounded, observable, and preserve a durable explanation of what happened.
• A healthy request is not enough if it leaves corrupt, stalled, or divergent state behind. Verify the resulting state and the relevant production-shaped telemetry.
• Green tests are necessary but not sufficient. For operational changes, the acceptance proof includes a preview deployment and evidence that its traces, logs, metrics, and state transitions are coherent, correctly classified, and free of new unexplained errors.

Treat any unexplained error volume as a release blocker until evidence proves that each outcome is expected and correctly represented outside the error signal. "Unavoidable error spam" is not a category.

• The root envs.ts is the typed map of every deployed environment (hostnames, worker names, accounts, resource IDs); Doppler supplies only secrets, one config per env (prd, preview_N; dev/dev_<you> are fully local and never deploy).
• Each app deploys with its own small scripts: pnpm run deploy --env <name> (build → wrangler deploy with atomic secrets → smoke), ensure-resources, erase-data. Workers are never deleted.
• Details: DevOps: Cloudflare And Doppler.

Run these from apps/os. Plain pnpm cli ... uses your local Doppler setup for apps/os. Wrap in doppler run --config <config> -- ... to target a specific environment; the config supplies URLs and secrets. More on this script pattern: Doppler-backed scripts.

OS exposes project capability handles through /api/itx. The app CLI authenticates with the config's admin API secret and can run scripts against a project's itx surface:

# your local Doppler setup, normally shared dev
pnpm cli itx --help

# production
doppler run --config prd -- pnpm cli itx --help

# preview slot 3
doppler run --config preview_3 -- pnpm cli itx --help

# local dev server (while pnpm dev is running)
doppler run --config dev -- pnpm cli itx --help

Use pnpm cli itx run --help to run a script against a project.

Open Claude Code against the OS MCP server for a deployment:

doppler run --config prd -- pnpm cli claude-mcp

The Doppler config picks the environment (prod, preview, or local dev). APP_CONFIG_PROJECT_HOSTNAME_BASES in the config sets the deployed project hostname base (e.g. iterate.app, iterate-preview-3.app); local dev project hosts use <slug>.localhost:<port>. Override with --base-host if needed.

More: apps/os README.

pnpm install
doppler setup --config dev --no-interactive   # once per worktree; doppler.yaml scopes every app dir
pnpm dev                                      # attached local OS dev server (http://localhost:<port>)

Use pnpm dev <action> [flags] for dev server lifecycle controls (status, start --detach, attach, restart, kill). The shared dev config and personal dev_<you> configs are fully local and safe for parallel worktrees; use captun, preview, or production for public callbacks. Details: Dev environments.

Before PRs:

pnpm install && pnpm typecheck && pnpm lint && pnpm format && pnpm test

How to open a PR (branch hygiene, body shape, screenshots that actually render, previews) — and after open: wait for Iterate Review / review bots, address every CI/review comment (fix or reply + resolve), never leave threads standing, never merge on red CI unless the human explicitly said so: Pull requests.

Browser testing: use Playwriter with an isolated headless session by default (or an authorized real-Chrome session when explicitly requested). Give every concurrent agent a unique Playwriter session id. See Browser testing. Keep the Playwriter CLI and skill current.

Start here: apps/os/

Other Cloudflare apps (semaphore, …) are supporting services — see docs/architecture.md.

doppler setup --config dev --no-interactive   # once per worktree (or --config dev_<you> for personal secrets)
pnpm dev                      # attached local OS dev server at http://localhost:<port> (see docs/dev-environments.md)
pnpm auth:mint                # mint a session as any user/admin (repo root; dev/preview; wrap in doppler run)
pnpm --dir apps/auth dev      # auth app only (when working on auth itself)
pnpm test && pnpm typecheck && pnpm lint && pnpm format

Canonical code-review rules live in rules/**/*.md. Before changing or reviewing code, read the rules whose frontmatter files globs match the files in scope and honor their exclusions. The hosted GitHub linter reads these same files; keep shared review policy here, not in the config repo.

How do I…? — Dev environments answers: run local dev (fully local, random port, localhost plus project <slug>.localhost hosts), be any user or an admin (minting), point an isolated visible browser at local dev or a preview, create a preview environment from your machine, and when you need a public callback URL. Doppler/Cloudflare/deploy details: docs/devops-cloudflare-doppler.md.

• Architecture
• DevOps: Cloudflare And Doppler
• Brand & tone

• Pull requests — opening PRs, absolute screenshot URLs, previews, body hygiene; after open: wait for Iterate Review, address every thread, no merge on red CI
• Browser testing — isolated Playwriter sessions, and reusable test logins
• Dev environments — local dev, minting identities, opening project-scoped or platform-wide operator sessions, browsers for agents, preview-from-local
• Tunnels — public HTTPS URLs for local dev, webhooks, OAuth callbacks, and CI/e2e fixtures
• Coding style
• Depot CI — workflow editing, Depot CLI commands, monitoring/wait loops, logs, dispatch, metrics, secrets, and gotchas
• CLI scripts — how to write normal TypeScript scripts and expose them as CLIs
• Preview CI performance — how the preview deploy+e2e check stays ~2-3 min, the budget guardrail, and how to keep it fast without raising cost
• CI and test telemetry — one PostHog model and health-checked dashboards for Vitest/Playwright/Node tests, failures, retries, phases, GitHub Actions, Depot, and review bots
• TypeScript conventions
• Frontend development — the apps/os programming model: one capnweb capability tree over one WebSocket, the thin itx hooks (useIterateSession/useItx, useItxQuery/useIterateSessionQuery, useLiveState), and LiveView-style live state from Durable Objects
• Design system & React
• Slack testing — real Slack flows; SLACK_CI_BOT_TOKEN trigger actor; channel membership (#slack-agent-e2e-test); preview setup; duplicate-bot caveats
• GitHub production smoke testing — post-recreation config sync, authenticated requests, and webhook routing
• Slack preview OAuth clients — API-first creation and secret handoff for preview Slack apps
• Slack bot token migration — per-app bot token fallback links and Doppler shape
• Testing — test lanes, how to run them against any environment, the canonical env vars, and the retry/timeout policy (one retry layer, fail-fast watchdogs, retry telemetry)
• Vitest patterns
• Domain objects & stream processors
• Writing & testing stream processors — side-effect guarantees, the obligation/reconciler pattern, eviction recovery, staleness policy, and the node test harness
• Playwright specs - instructions for agents writing playwright tests

• Task system
• Task grooming
• Writing agent docs
• Cloudflare trace queries — MCP dataset selection, correlation, and span-tree audits
• Debugging the OS worker — ITX, agents, scheduler alarms, dynamic workers, and error lookup

• OS app
• Kit device installer
• Auth app — public OIDC/oRPC plus OS-only Workers RPC for the org/project directory
• itx — the /api/itx surface and its public contract (types.ts)
• OS worker topology
• OS architecture & operations
• Debugging deployed OS workers
• Doppler-backed scripts
• Project seeds — capture and semantically restore selected projects across deliberate production erases