[mmkal]

Docs builds, tests, publishes and deploys from iterate/docs, with nothing from iterate's monorepo but published packages. Main already holds Docs' history (56 commits, see "History" below). This PR is the one commit that makes that tree stand alone, as iterate/kit#1 did for Kit.

Its other half removes Docs from iterate/private (linked once open). The cutover order is at the end.

What changes for people

Nothing, once both halves land: the same Workers (docs at docs.iterate.workers.dev, which the iterate project's docs slug and docs.iterate.com route to, and docs at docs.iterate-dev-preview.workers.dev), the same ITERATE_APP, the same package name. What moves:

before: https://pkg.pr.new/iterate/private/@iterate-com/docs@<sha>
after:  https://pkg.pr.new/iterate/docs/@iterate-com/docs@<sha>
        npm: @iterate-com/docs@<version>-main.<date>-<sha>, published from here (needs the npm step below)

before: https://raw.githubusercontent.com/iterate/packages/main/packages/docs/AGENTS.md   (what installDocs writes into a project's AGENTS.md)
after:  https://raw.githubusercontent.com/iterate/docs/main/packages/docs/AGENTS.md

Change / Purpose

Change	Purpose
package.json, pnpm-workspace.yaml, pnpm-lock.yaml, patches/zod@4.6.5.patch, tsconfig.{base,app}.json, .nvmrc	A two-package pnpm workspace. The catalog is iterate/private's versions for what Docs uses, so catalog: in the packages' manifests stays as it was. iterate is npm's 0.4.1-main.20261105T063432Z-a81a857 (iterate/private's main today), let past the one-day release age like the Cloudflare toolchain. zod's patch (a ZodError's message across Durable Object RPC) comes along, as Kit's did.
packages/docs-app/src/components/**, src/hooks/use-mobile.ts, src/lib/plain-left-click.ts, src/styles/{globals,iterate,tokens}.css, components.json	The UI that came from @iterate-com/ui in the workspace. Its npm build bundles React for no-build pages, so a Start app can't use it; the app takes the components from the shadcn registry instead, like Kit: shadcn's base-nova ones and iterate/packages' project-app-shell, stream-link, posthog, first-project-redirect, environment-head-content, route-defaults and their dependencies, each file byte-identical to iterate's packages/ui.
packages/docs-app/src/app/*	The six packages/ui/src/apps files (base path, document, head, providers, router, server) and two packages/shared ones (ITERATE_APP's schema, the PostHog proxy) the app imported, copied with a header naming where from.
packages/docs-app/src/** imports	@iterate-com/ui/… and @iterate-com/shared/… become #/components/… and #/app/…. No other change to what the app does.
envs.ts, packages/docs-app/vite.config.ts, packages/docs-app/scripts/app.ts	The Worker config iterate's startAppWorkerConfig wrote for Docs, cut down the way Kit's was: same name, account, bindings, compatibility date, observability, run_worker_first and ITERATE_APP (every link, denyZones copied from iterate's ownZones()). deploy --env <name> builds, wrangler deploys with _shared's Cloudflare token, and smokes /healthz; generate-route-tree as before.
packages/docs-app/src/routes/_auth/projects.$slug.$repo.$.tsx	"Install Docs" on a per-commit deployment installs pkg.pr.new/iterate/docs/…@<commit>; iterate/package-builds buildVersion names iterate/private's builds. Production still installs npm's main.
packages/docs/src/install.ts (+ test)	docsAgentGuide names iterate/docs. iterate/private's half keeps the old URL answering with a pointer here.
packages/docs/src/processor.test.ts	Casts where the test passes an engine or checkpoint table between iterate/stream/processor and iterate/stream/test-support. iterate's npm build declares those classes twice (core/lib/tsdown.config.ts builds test-support in its node build), so TypeScript sees two #private fields. One class at runtime; a fix in core/lib would drop the casts.
packages/docs/src/processor.ts, the $.tsx route	Two oxlint-disable comments for iterate's own lint plugin, which isn't here, become plain comments.
.depot/workflows/ci.yml, .depot/actions/setup, scripts/ci/toolchain.sh (+ test)	Depot CI: typecheck, lint, format, both Vitest suites and the app's build on every PR and main push. The setup and toolchain are iterate's and Kit's.
.depot/workflows/deploy.yml, scripts/ci/page.ts	Main deploys preview, then prd; a red run pages #error-pulse (Kit's pager, with _shared/prd's bot token).
.github/workflows/pkg-pr-new.yml	@iterate-com/docs on pkg.pr.new for every main commit and every PR head (iterate/private published a PR only when a package's inputs changed; here nearly every PR touches the package or the app that installs it).
.github/workflows/npm-publish.yml, scripts/ci/npm-publish.ts (+ test)	iterate/private's npm publish, unchanged but for where it finds the package list and the repo it names in setup commands.
README.md, AGENTS.md, doppler.yaml, LICENSE, .oxlintrc.json, .oxfmtrc.json, .gitignore, package READMEs	The repo's map, rules and history; Apache-2.0, as both packages were. Lint config is Kit's (iterate's less its own plugin).

History

Main starts with Docs' own commits, the tip's tree byte-identical to iterate/private@a541c9d's packages/docs and packages/docs-app:

• 36 from the iterate/iterate archive (2026-07-29 to 2026-10-02): packages/docs, and apps/docs written as packages/docs-app. Each title's (#N) reads (iterate/iterate#N), and each ends in Original-Commit: iterate/iterate@<sha>.
• 20 from iterate/packages, the public copies of iterate/private's commits since, whose messages copybara already cut to what is public. Each ends in Original-Commit: iterate/packages@<sha> beside copybara's GitOrigin-RevId.

Done outside the diff

• Repo: iterate/docs, public (projects install its package; agents read its AGENTS.md), with iterate/kit's merge settings (squash with the PR's title and body). No rulesets yet.
• pkg.pr.new's and Depot's GitHub Apps are on every iterate repo, so neither needed setting up.

Still to do

• npm: @iterate-com/docs's trusted publisher names iterate/private's npm-publish.yml. Until a maintainer adds iterate/docs (npx npm@latest trust github @iterate-com/docs --repo iterate/docs --file npm-publish.yml --allow-publish, then tick "Allow npm dist-tag" at https://www.npmjs.com/package/@iterate-com/docs/access), npm / check stays red here and main's npm run fails. Its job summary prints the commands.
• Browser specs: iterate/private's test/playwright/docs move here in a follow-up PR, run against the dev platform.

Risk map

• The copied UI is the riskiest part: the app's look and its base-path handling under a project's routes now run on copies (src/app/*, src/components/**), not the workspace's packages/ui. They are byte-identical to iterate/private@a541c9d, so the risk is drift later, not a difference now.
• Two writers until the cutover: while iterate/private still has deploy-docs.yml and preview-parents.yml, a main push there redeploys the same Workers from its copy. The code is the same today, so stale, not broken; the cutover order below avoids it.
• npm: main's npm job is red here until the trusted publisher moves (above), and iterate/private keeps publishing @iterate-com/docs until its half lands.
• Review order: packages/docs-app/vite.config.ts and envs.ts (what deploys where), .depot/workflows/deploy.yml, the two .github/workflows, packages/docs-app/src/routes/_auth/projects.$slug.$repo.$.tsx, packages/docs/src/install.ts; the copied files (src/app, src/components) only for their headers.

Cutover

1. Merge iterate/private's half. Its deploy-docs.yml, Docs' per-PR previews and preview-parents.yml's Docs redeploy go with it, and the Workers keep their last deploy.
2. Merge this. Main deploys preview and prd.
3. The npm step above, then re-run npm's failed job here.

Evidence

• CI on Depot (typecheck, lint, format, both Vitest suites, the app's build) green on this PR with no setup beyond the push; pkg.pr.new published @iterate-com/docs for its head (pkg.pr.new/iterate/docs/@iterate-com/docs@2cf1c08… answers 200).
• npm / check red, as expected: "@iterate-com/docs does not trust this workflow to publish it (npm answered 404 …)", with the setup commands in its summary.
• iterate's Docs specs against this build: built with CLOUDFLARE_ENV=preview, deployed to a throwaway Worker on the dev account (docs-standalone-check), and iterate/private's own --project docs specs run from its main against it, served through fixture projects on main on dev: 8 passed (53.8s). Then the same specs from Docs' browser specs run here: on each pull request's own Worker, and on preview before prd #2, installing this PR's pkg.pr.new build: 10 passed (50.2s) with the phone runs.
• CLOUDFLARE_ENV=preview vite build writes the Worker config iterate/private's startAppWorkerConfig writes for Docs: name, account, compatibility date and flags, bindings, observability, run_worker_first and ITERATE_APP (every link and deny zone) equal.
• Not exercised yet: deploy.yml (main only), scripts/ci/page.ts (a red main run only), npm's publish job (main only, and needs the trusted publisher).

Claude Code session: local_cdd673f8-107f-4d2f-8087-ac4278554ee1 ("iterate/docs repo")

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@iterate-com/docs@1

commit: 2cf1c08

[cursor]

PR Summary

Medium Risk
Touches production deploy, npm publishing, and Cloudflare Worker configuration paths while vendoring large UI copies; misconfiguration could break deployments or package installs even though behavior is intended to match the monorepo.

Overview
Bootstrap a standalone iterate/docs repo
This PR turns the former monorepo slice into its own pnpm workspace with root tooling (Node 24 via .nvmrc, package.json, oxlint/oxfmt configs, .gitignore, Apache-2.0 LICENSE) plus documentation (README.md, AGENTS.md, doppler.yaml).

CI, publishing and deploy automation
New Depot workflows wire up composite .depot/actions/setup (toolchain + pnpm install) and .depot/workflows/ci.yml to run typecheck, lint, format, tests and pnpm --dir packages/docs-app build on every PR/main push, while .depot/workflows/deploy.yml chains preview then prd Cloudflare deploys with Doppler-backed secrets and an #error-pulse paging job on failure. GitHub Actions add pkg-pr-new and trusted npm publishing/check flows, mirroring iterate’s prior automation but pointed at this repo.

Docs app de-monolithing and UI copies
packages/docs-app drops workspace deps on @iterate-com/ui/@iterate-com/shared, adds #/* import aliases, pulls iterate from npm, and vendors the shadcn/Base UI stack (components.json, large src/components/ui tree, hooks, logos, posthog, stream-link, project-app-shell, etc.). Core iterate app plumbing (src/app/* server/router/document/base-path helpers, start-app-config, PostHog proxy) is copied in-tree with provenance headers, and routes switch imports accordingly. scripts/app.ts is rewritten to a dedicated trpc-cli tool that deploys via Doppler + wrangler with retry/smoke checks and regenerates routeTree.gen.ts using @tanstack/router-generator.

Behavioral tweaks tied to the split
Root envs.ts centralizes Cloudflare/Doppler targets, and projects.$slug.$repo.$.tsx now pins @iterate-com/docs installs to pkg.pr.new/iterate/docs/... for non-main refs while production still tracks npm main. README/docs-app README explain the new dev tunnel flows, shadcn sourcing, and automation layout. Overall this is primarily an extraction + wiring change: functionality is intended to match the old monorepo build, but all packaging, deploy, and UI maintenance now live in this repository.

^{Reviewed by Cursor Bugbot for commit 2cf1c08. Bugbot is set up for automated code reviews on this repo. Configure here.}