Documentation sweep over apps/os. Every statement written into a doc was verified against the code on this branch.

Changes

apps/os/README.md (= AGENTS.md)

• Important Files: src/app.ts / src/entry.workerd.ts do not exist — replaced with src/worker.ts (Worker entrypoint) and src/config.ts (AppConfig schema). All other listed files verified to exist.
• Real-worker tests: the documented vitest configs (src/capnweb/e2e/vitest.config.ts, src/domains/capability-prototype/e2e.vitest.config.ts) are gone — replaced with the real lanes pnpm e2e (e2e/vitest.config.ts) and pnpm e2e:itx (src/itx/e2e/vitest.config.ts), verified against apps/os/package.json.
• pnpm cf:deploy # production deploy was wrong and dangerous: cf:deploy deploys to whatever Doppler/Alchemy stage is ambient. Now documents both cf:deploy (ambient stage) and pnpm deploy (the doppler --config prd wrapper).
• Removed the nonexistent /org/:organizationSlug route; remaining routes verified against src/routes/; added /new-project.

apps/os/CONTEXT.md — fixed the example-dialogue claim that organization UI lives under /org/:organizationSlug (no such route; orgs live in the auth worker).

apps/os/docs/architecture-and-operations.md — rewritten. The old doc described the pre-migration world: Clerk auth (whole ## Clerk section, sync-clerk-apps.ts, APP_CONFIG_CLERK__*), /orgs/:organizationSlug route maps, inbound MCP via ProjectMcpServerEntrypoint (now a hardcoded 410 tombstone), wrong redirect claims, and an unprefixed /durable-objects/stream debug route. The new doc describes current reality: src/worker.ts dispatch pipeline, Iterate Auth middleware, real route map and root-redirect behavior (/ → /projects/$projectSlug or /projects; project root renders ProjectHomePage), canonical MCP endpoint from APP_CONFIG_MCP__BASE_URL with Iterate Auth protected-resource metadata, /__durable-objects/<kind>/<name>/<path> debug proxy (kinds verified), itx endpoints, scripts/sync-auth-clients.ts, current codemode default/example providers, and current smoke-test env vars (verified in the e2e test files).

apps/os/docs/headless-local-debugging.md — /projects/new → the real route /new-project.

apps/os/docs/iterate-context.md, iterate-context-learnings.md — both pointed at the deleted src/capnweb/ tree as "the current design"; now short tombstones pointing at the successor (src/itx/ README + DECISIONS, docs/itx-spec.md).

apps/os/docs/capability-system-research-and-design-notes.md, rpc-target-constructor-shape-research.md — added status headers marking them historical research notes superseded by itx; bodies untouched.

apps/os/src/itx/README.md + src/itx/handle.ts — the "Typed caps" ProjectCaps declaration-merging pattern does not exist in code (no ProjectCaps interface anywhere). Rewrote the README section to the thing that actually works: casting itx.cap("name") through the exported Stubify<T> type. Also fixed the same false claim in the Stubify doc comment in handle.ts (comment-only change).

apps/os/docs/itx-spec.md — status header said "IMPLEMENTED on the itx-implementation branch"; PR #1407 is merged to main (verified in git history). Marked the one known divergence honestly: the §6.3 client reconnect loop was never built — connectItx (src/itx/client.ts) is one-shot, and there is no itx.cap.disconnected event. Corrected §6.3 and the related §4 caveat.

apps/os/tasks/

• Deleted simplify-context-cloudflare-native.md (state: todo, but shipped — src/worker.ts imports env from cloudflare:workers directly, RequestContext is the narrow request-scoped shape the task specified, auth lives in Start request middleware, the manifest/src/app.ts is gone).
• Deleted project-egress-secrets-mvp.md (state: todo, but shipped — ProjectEgress entrypoint, ProjectDurableObject.egressFetch with substituteProjectEgressSecretHeaders, D1-backed SecretsCapability.getSecret, and the /api/itx/egress-echo echo proof covered by src/itx/e2e/itx-egress.e2e.test.ts).
• Grooming rules (docs/tasks-grooming.md) say "Delete when done", so deletion rather than state edits.
• Added brief status notes (no rewrite) to codemode-session-vertical-slice.md (checked-off "tiny worker" box diverged: CodemodeSession lives in the main OS worker) and codemode-session-night-plan.md (plan superseded by itx).

Skipped

• Nothing skipped; all nine items verified and addressed.

Flags for reviewers

• src/itx/handle.ts got a comment-only edit (the Stubify doc comment made the same false declaration-merging claim as the README). No runtime change; typecheck/lint/tests pass.
• The two deleted task files: please sanity-check the "shipped" verdicts above if you have more context on intended remaining scope.
• Carve-outs respected: no changes to the streams type systems or to how the os-streams worker is deployed.

Checks

• pnpm install, pnpm format (oxfmt), pnpm typecheck, pnpm lint, pnpm test — all pass.

Task-file audit

A follow-up commit deletes 22 task files whose work was verified as shipped, obsolete, or purely historical. (Two more from the audit — apps/os/tasks/project-egress-secrets-mvp.md and apps/os/tasks/simplify-context-cloudflare-native.md — were already deleted by earlier commits on this branch, see above.)

Deleted: completed

• tasks/cf-prd-orphaned-resources-cleanup.md — live Cloudflare API check of the prd account (2026-06-10) shows 14 worker scripts (was 1026 at the task's 2026-05-18 sweep) and 6 D1 databases; cleanup is done.
• tasks/complete/2026-05-22-os-captun-worker-test-tunnel.md — shipped via merged PR codemode++ e2e++ #1361 ("codemode++ e2e++"); all described artifacts exist on main and survived the golden-path rebuild (Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework #1411).
• tasks/dead-code-and-docs-cleanup-audit.md — high-confidence items all shipped; pnpm-workspace.yaml no longer lists the dead packages and now uses apps/*/packages/* globs.
• tasks/os-auth-spurious-logout-refresh.md — commit ad6da76 "Fix 5-min logout, deploy-time JWKS, and stream append skeleton flash (Fix 5-min logout, deploy-time JWKS, and stream append skeleton flash #1410)" (merged 2026-06-10) shipped exactly this work.
• tasks/os-codemode-router.md — task file was added in the very PR that implemented it (commit 98ee148, Add codemode system: kernel, oRPC endpoints, and MCP run_code tool #1294).
• tasks/os-domain-capability-orpc-refactor-design.md — every major pillar of the design (domains layout, capabilities, oRPC structure) exists on main.
• tasks/os-domain-capability-orpc-refactor-prd.md — shipped in PR Make codemode function calls event-driven #1305 "Make codemode function calls event-driven" (squash commit 284193e, merged 2026-05-08).
• tasks/semaphore-lease-renewal.md — the described lease-renewal feature exists on main as resources.renew (named "renew" rather than the proposed "extend") in apps/semaphore.
• tasks/signup-slug-uniqueness.md — shipped with the auth worker (PR auth worker #1273); packages/shared/src/slug.ts implements resolveUniqueSlug/slugifyWithSuffix.
• apps/os/tasks/codemode-session-night-plan.md — planned outcomes verifiably shipped on main, in evolved form (codemode session browser UI and follow-ons).
• apps/os/tasks/codemode-session-vertical-slice.md — all 11 ticked checklist items shipped via PRs Add codemode system: kernel, oRPC endpoints, and MCP run_code tool #1294/Make codemode function calls event-driven #1305 and follow-ups.
• apps/os/tasks/refactor-lifecycle-init-params-as-structured-name.md — every acceptance criterion implemented in the with-lifecycle-hooks.ts mixin on main.
• apps/os/tasks/repos-vertical-slice.md — frontmatter already says state: done and the described slice verifiably exists on main.
• apps/os/tasks/slack-processor-unwind.md — all target-shape items exist on main (/integrations/slack stream path; no /integrations/slack/webhooks references).

Deleted: obsolete / nonsense

• tasks/github-oauth-use-repo-id.md — all referenced code is gone: linkExternalIdToGroups / repoId / repository.id return zero hits repo-wide.
• tasks/ignoreme-email-security.md — every code path the task targets was deleted with the legacy OS1 stack (commit 545854d, Remove legacy OS1 stack (apps/os, daemon, sandbox) #1341).
• tasks/os-stream-runtime-big-refactors.md — os2-era brainstorm list largely superseded or done differently; item 2 shipped via PR [codex] remove events app and legacy shared streams #1394.
• tasks/realtime-pusher-efficiency.md — targets the legacy OS1 realtime pusher, which no longer exists.
• tasks/stream-processor-ergonomics.md — targets the legacy hook-style processor API, replaced by the class-based StreamProcessor model.

Deleted: historical logs

• apps/os/tasks/slack-google-auth-poc-implementation.md — explicitly an "Implementation Log" (state: done), not actionable work; shipped in merged PR Add OS2 integrations and Slack stream-agent routing #1317.
• apps/os/tasks/stream-processor-class-design-notes.md — design notes written alongside the class-based StreamProcessor migration, not a task.
• apps/os/tasks/workspace-codemode-implementation-log.md — state: done, all 9 checkpoints ticked; the described work verifiably shipped on main.

Kept but flagged for maintainer judgment

• tasks/cf-prd-orphaned-resources-cleanup.md: Explicit not-in-scope follow-ups (preview account 376ef7ed cleanup, Doppler os-legacy-backup pruning) were never broken out into their own tasks; spin them out only if still wanted.
• tasks/codemode-capability-policy.md: Still-unshipped, still-wanted design work, but duplicates apps/os/tasks/codemode-capability-access-policy.md and overlaps the active itx capability-system design notes — maintainer should consolidate into a single task.
• tasks/complete/2026-05-22-os-captun-worker-test-tunnel.md: apps/os still depends on the unpublished pkg.pr.new/captun@14 build (the task's stated stopgap); a published captun/worker release would be a separate follow-up, not a reason to keep this file.
• tasks/dead-code-and-docs-cleanup-audit.md: Residual from this audit: packages/iterate is still excluded from root build/typecheck/test (--filter '!iterate'); if that CI gap matters, open a fresh small task rather than keeping this stale inventory.
• tasks/doppler-shared-and-os-secrets-audit.md: Audit still unrun and wanted, but needs a rewrite first: replace Clerk-key expectations with iterateAuth, point AppConfig refs at apps/os/src/config.ts (app.ts and packages/shared/src/apps/config.ts were deleted in PR Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework #1411), and refresh the 2026-05-18 baseline.
• tasks/ignoreme-email-security.md: If outbound email via Resend is ever reintroduced in the rebuilt apps/os, recipient allowlisting should be designed fresh against the itx/egress-secret-substitution layer, not this OS1-era plan.
• tasks/iterate-cli-distribution.md: Live but ~90% of the file is OpenCode architecture research notes, not actionable steps; npm distribution already exists, so the remaining work (bun binary, brew, install script) should be restated as concrete tasks or the research trimmed.
• tasks/os-auth-spurious-logout-refresh.md: PR Fix 5-min logout, deploy-time JWKS, and stream append skeleton flash #1410 left one open thread: a manual end-to-end "wait 5 minutes in prod" verification was never done, and the claims-staleness force-refresh was consciously skipped (≤30m propagation accepted) — file a new narrow task only if either still matters.
• tasks/os-deploy-time-jwks-fetch.md: Code shipped in PR Fix 5-min logout, deploy-time JWKS, and stream append skeleton flash #1410; only remaining action is deleting ITERATE_AUTH_JWKS from Doppler os prd/preview (still present and shadowing the deploy-time fetch) — after that, delete this task.
• tasks/os-domain-capability-orpc-refactor-prd.md: Sibling task os-domain-capability-orpc-refactor-design.md (its dependsOn target) is likely also completed and should be audited/deleted together.
• tasks/os-project-do-projection-reconciliation.md: Scope item "rename IterateMcpServer to ProjectMcpServerConnection" is already done and could be ticked off; the rest is unshipped and still relevant.
• tasks/os-project-hostname-base-singular.md: Scope file paths are stale post-PR Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework #1411 (app.ts→src/config.ts, sync-clerk-apps.ts→sync-auth-clients.ts, entry.workerd.ts deleted, routing files moved to src/ingress/); task itself is still valid.
• tasks/os-project-route-authorization.md: Still-wanted design work (referenced by live project-ingress-architecture task), but needs rewrite: Clerk OAuth and ProjectMcpServerEntrypoint references are dead — MCP moved off project ingress (410 stub) and auth is now apps/auth Principal-based.
• tasks/os-stream-runtime-big-refactors.md: Only surviving idea: cosmetic no-compat rename of events.iterate.com/... event-type names (events app is deleted); re-file as a small standalone task if still wanted.
• apps/os/tasks/codemode-capability-access-policy.md: Live work, but near-duplicates root-level tasks/codemode-capability-policy.md (same PR Add codemode system: kernel, oRPC endpoints, and MCP run_code tool #1294); keep this copy and consolidate/delete the root one.
• apps/os/tasks/codemode-session-night-plan.md: Open capability-scope questions from this plan live on in codemode-capability-access-policy.md; checkboxes are unticked but the work shipped via PRs Add codemode system: kernel, oRPC endpoints, and MCP run_code tool #1294/Make codemode function calls event-driven #1305/Class-model stream processors across apps/os: DO-hosted, callable subscriptions, legacy model deleted #1402.
• apps/os/tasks/codemode-session-vertical-slice.md: Last unchecked box (generalize self-callable bindings) shipped as the loopback-binding pattern used repo-wide; follow-on work lives in codemode-session-night-plan.md.
• apps/os/tasks/project-egress-and-secrets-architecture.md: Design doc whose first vertical slice shipped (egress + secret substitution MVP); remaining secret-DO/policy/approval/OAuth design is still live but needs grooming: drop completed PoC sections, update Clerk-scope terminology, and reconcile with itx DECISIONS.md as the newer design-of-record for egress wiring.
• apps/os/tasks/project-egress-intercept-tunnel-latency.md: Still-relevant latency work, but file refs are stale (entry.workerd.ts → src/worker.ts; vendored apps/os/src/lib/captun removed for the published captun package in codemode++ e2e++ #1361) and the benchmark numbers predate the Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework #1411 worker rebuild — re-benchmark before picking an option.
• apps/os/tasks/project-ingress-architecture.md: Live, actively-maintained ingress reference (edited today in [codex] Stop provisioning project DNS records #1416), but needs a refresh: Clerk auth sections, Project.checkAccess, and the streams-upstream proxy model are superseded (auth worker, principal claims, bundled project worker), and the 2026-05-05 status checklist is partly outdated.
• apps/os/tasks/stream-processor-class-migration-log.md: Migration log (merged today via Class-model stream processors across apps/os: DO-hosted, callable subscriptions, legacy model deleted #1402, which links to it as the canonical rationale) — not an actionable task; contains unique I6-I8 forensics not in the PR body, consider moving to docs/ alongside tasks/migration-notes/ rather than deleting.
• apps/os/tasks/stream-subscriber-delivery-refactor.md: Core design shipped differently via the class-model cutover (Class-based stream processors: crisp batch model, honest contracts, regression tests #1401/Class-model stream processors across apps/os: DO-hosted, callable subscriptions, legacy model deleted #1402/[codex] remove events app and legacy shared streams #1394); only live remainder is migrating codemode.streamEvents, StreamsCapability.stream(), and project-mcp-server-connection off the OS-internal NDJSON shim in new-stream-runtime.ts — consider replacing this large draft with a small task for that.
• apps/os/tasks/workspace-codemode-implementation-log.md: Done implementation log; only marginally unique note is the rationale that plain method objects (not class instances) cross DO RPC, which is now embodied in the shipped workspace DO code.
• apps/os/tasks/migration-notes/: Historical migration logs (not tasks) committed with and cited by merged PR Class-model stream processors across apps/os: DO-hosted, callable subscriptions, legacy model deleted #1402 one day ago; contain unique per-domain decisions plus the legacy-subscriber gap behind the 2026-06-10 prd Slack outage — maintainer should relocate to docs/ or delete deliberately.

🤖 Generated with Claude Code

Environment Config Lease

No active environment config lease.

OS

Status: released
Commit: a4f093f
Preview: https://os.iterate-preview-5.com
Summary: Preview app released.
Workflow run
Updated: 2026-06-10T12:37:37.303Z