Rename Zero v2 to First by batuhan · Pull Request #112 · spacefast/docs

batuhan · 2026-11-09T02:53:36Z

Zero v2 is now First. Zero 0.8 keeps the name Zero. It's retired: existing Spaces keep serving and publishing, and Zero 0.9 is its last release apart from security fixes, for moving apps to First.

This is stacked on #107, which introduced the Zero v2 pages. It merges into #107's branch, which ships with the v2 release.

How

scripts/rename-to-first.mjs does the rename, and running it again changes nothing. I checked that two ways: a second run on the result reports moved 0 file(s), rewrote 0 file(s), and on a fresh checkout of #107 it produced the same tree apart from the hand edits listed below. A branch picks up the rename by merging and running the script again.

The script:

moves content/(dynamic)/zero.mdx to first.mdx, content/cli/zero.mdx to cli/first.mdx, then content/(dynamic)/zero-migrate.mdx to zero.mdx, each only while its target is free;
in authored content (content/, evals.yaml, redirects.ts), rewrites v2 names: the product name, first.config.ts, from "first", sf first …, --runtime first, /wp-json/first/v1, first-identity, first-signature, .first/, first/client/, first/_generated/migrations/, first.gen.ts, SPACEFAST_FIRST_BIN, and the /first and /cli/first links;
skips build overlays (content/cli/reference.md, content/(reference)/errors, changelog, setup, _pricing) and generated/. Those come from the exporter, so they change when it re-runs against the renamed CLI and API.

Hand edits after the script:

The Zero 0.8 page (/zero) is now titled "Zero 0.8". It says Zero is retired and First replaces it, that existing Spaces keep working, and that 0.9 is the last release.
The glossary defines First, and keeps a Zero entry for the retired runtime.
Links that said "an older Zero app" now say Zero 0.8.
First's intro carries the one "(formerly Zero v2)".
The script protects all of this, so a re-run leaves it alone.

Routes

No First (Zero v2) app exists in production, so nothing that documents First is published today. The live site still serves the Zero 0.8 docs: /docs/zero 301s to /docs/zero-runtime/ ("Dynamic sites with Zero", capsule() in server/index.ts), and /docs/cli/zero/ lists the 0.8 sf zero abilities|call|types|ls|import commands. /docs/first and /docs/zero-migrate 404 today. So this adds no redirects. redirects.ts and scripts/redirect-rules.mjs match the base branch.

/first: First, the page Teach Zero v2 and move Zero 0.8 to one migration page #107 had at /zero.
/cli/first: the sf first commands.
/zero: Zero 0.8. The page Teach Zero v2 and move Zero 0.8 to one migration page #107 had at /zero-migrate (never published) moves here, titled "Zero 0.8". It says Zero is retired, existing Spaces keep working, and Zero 0.9 moves apps to First. The existing /runtimes, /runtimes/zero, /apps/zero and /zero-runtime redirects already land on /zero, which keeps the published Zero URLs on Zero.

Names kept

Zero 0.8 names, or names production already ships:

"runtime": { "kind": "zero" }, @spacefast/zero, @spacefast/zero/client, --from zero-0.8;
API operations createSpaceZeroToken, listSpaceZeroAbilities and /v1/spaces/{id}/zero/token;
Abilities zero/storage-* and the zero-storage category;
the sfz_ table prefix, the refused ZERO_ env prefix, and version.zero.migration.status;
error codes zero_mixed_generation and zero_migration_required, whose reference pages are generated;
ordinary English such as "zero or more" and "nonzero".

The pricing fixture's "PHP and Zero" labels mirror the API's pricing document, so they change with the API. Usage and billing prose now says "PHP, First and SQL"; Zero 0.8 apps run as PHP.

Hold: check against the shipped names

Don't merge until the zero rename's "Shipped names" table lands. The zero thread confirmed every name below as expected from the rename mapping and checked it against the prod control plane and engine (none of the v2 names ships in prod). The zero rename-to-first branch has no commits yet. When its table lands I diff it against this list, change the script's table where they differ, and re-run the script. The zero thread also expects the zero/storage-*, createSpaceZeroToken, sfz_, @spacefast/zero/client, runtime.kind: "zero" and ZERO_ names to stay.

These names have to match what the monorepo and zero renames ship. I've asked both:

sf first … for every v2 command, and --runtime first;
first.config.ts;
SPACEFAST_FIRST_BIN;
the REST namespace /wp-json/first/v1;
the first import module;
the first-identity plugin and first-signature header;
.first/ and first/_generated/migrations/;
whether FIRST_ joins the refused env prefixes.

If either ships a different name, the script's table changes and a re-run updates the docs.

Checks

Run locally:

bun run check: 0 errors.
bun run validate: passes.
bun run build: passes. The routing rules are the base branch's.
bun run test:docs: 37 pass. "Database gives the First prerequisite" and the glossary test now cover First, and the glossary test also requires a Zero entry.
bun run audit: passes.
bun run verify:routes: passes.
bun run verify:public-safety: passes.

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

Zero v2 is now First. Zero 0.8 keeps the name Zero: it is retired, existing Spaces keep serving and publishing it, and Zero 0.9 is its last release apart from security fixes, for moving apps to First. scripts/rename-to-first.mjs applies the rename and is idempotent, so a branch picks it up by merging and running it again. It moves the First page to /first and the CLI page to /cli/first, renames v2 names in authored content, and keeps every Zero 0.8 name and every name production already ships. /zero redirects to /first. Hand edits on top: the Zero 0.8 page says Zero is retired, the glossary defines both, and links that said "an older Zero app" now say Zero 0.8.

batuhan · 2026-11-09T02:53:42Z

@indent please review.

indent · 2026-11-09T02:53:42Z

Issues

3 potential issues found:

content/cli/zero.mdx is a public page on main. This PR moves it to cli/first.mdx and adds a redirect only for /zero, so /docs/cli/zero will 404 once the stack ships. Add a /cli/zero to /cli/first 301 and a matching check in verify-routes.mjs, freeing room in the 1880 redirect budget or raising the limit.
_{Found by Indent Review Agent}
The last sentence of "Publishing a hand-ported app" says "edit and publish the current Zero app as usual", but after migration the app is a First app. The script protects "Zero app" on this page, so it stayed. Change it to "the First app" and protect that phrase.
_{Found by Indent Review Agent}
With the Zero 0.8 page now at /zero, /runtimes redirects to /zero. That is the generic runtimes overview, and on the base branch it went to the current runtime's page. Point /runtimes at /first; /runtimes/zero, /apps/zero and /zero-runtime can stay on /zero.
_{Found by Indent Review Agent}

↑ Select any checkbox above to have Indent auto-fix the issue

CI Checks

All CI checks passed on f5e90b7.

Review agents

Select any unchecked box below to run or rerun that agent.

Found issues (1)

Indent Review Agent · /cli/zero 404s; /runtimes lands on retired Zero

Full results

Indent Review Agent

Summary: /cli/zero 404s; /runtimes lands on retired Zero
Last ran on commit: f5e90b77

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 483b94c4-452e-4127-878b-a8fa2335d85e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

Trigger review

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

chatgpt-codex-connector · 2026-11-09T02:53:44Z

Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	❌ Failed 2026-11-09T02:53:40.573354Z We couldn’t complete this review. Comment `@codex review` to try again.	`8316f41`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector · 2026-11-09T02:53:46Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

indent · 2026-11-09T02:55:41Z

-  { from: "/runtimes/zero", to: "/zero", status: 301 },
+  { from: "/runtimes/zero", to: "/first", status: 301 },
  { from: "/sdk", to: "/api/sdk", status: 301 },
+  { from: "/zero", to: "/first", status: 301 },


🟡 Bug · Live /cli/zero URL 404s after the rename, with no redirect

/docs/cli/zero is live on main and this PR moves the page to cli/first.mdx, but only /zero gets a redirect. Old bookmarks, search results and docs-corpus links to /docs/cli/zero/ will 404. Add a /cli/zero to /cli/first 301 (making room in the redirect budget) and a matching verify-routes check.

_{Found by Indent Review Agent}

indent · 2026-11-09T02:55:44Z


 ## Publishing a hand-ported app

-Publish the 0.8 project, not a hand-edited candidate. A Space's data moves with the app: publishing a `zero.config.ts` app to a Space that still runs Zero 0.8 is refused with `zero_migration_required`, because it would leave the posts, users, and sessions behind. Once a publish has migrated the Space, edit and publish the current Zero app as usual.
+Publish the 0.8 project, not a hand-edited candidate. A Space's data moves with the app: publishing a `first.config.ts` app to a Space that still runs Zero 0.8 is refused with `zero_migration_required`, because it would leave the posts, users, and sessions behind. Once a publish has migrated the Space, edit and publish the current Zero app as usual.


⚪️ Nit · Zero 0.8 page still calls the migrated app "the current Zero app"

After migration the app is a First app, so "the current Zero app" is wrong here. Change to "the First app" and protect the phrase in the script.

_{Found by Indent Review Agent}

indent · 2026-11-09T02:58:38Z

Review of 8316f41 is done, with two findings in the banner:

Bug: /docs/cli/zero is live on main. This PR moves it to cli/first.mdx but only redirects /zero, so the old CLI URL will 404. The fix is a /cli/zero to /cli/first 301 plus a verify-routes.mjs check. That needs room in the redirect budget, which your description says is full.
Nit: zero-migrate.mdx still says "edit and publish the current Zero app as usual" after migration. It should say "the First app", and the script needs to protect that phrase so a re-run leaves it alone.

I didn't run the script or the build; CI covers that. I didn't find any other problems in the script or the route changes.

No First app exists in production, so nothing documents First at a published URL today. /docs/zero now documents Zero 0.8 (the page moves from /zero-migrate, which was never published), First is at /first, and the redirect rules are unchanged from the base branch.

batuhan · 2026-11-09T03:49:39Z

@indent please review f5e90b7: /zero now documents Zero 0.8, First is at /first, and no redirects are added.

indent · 2026-11-09T03:49:52Z

Reviewing f5e90b7 now. I'm checking that /zero now documents Zero 0.8 and First is at /first, and re-checking both earlier findings. I'll update the banner when the review finishes.

indent · 2026-11-09T03:49:55Z

The review of f5e90b7 is still running. I'll post any new findings in the banner and resolve the two earlier ones if they no longer apply. That covers the /cli/zero 404 and the "current Zero app" wording.

indent · 2026-11-09T03:50:35Z

Review of f5e90b7 is done. Two earlier findings are still open and I found one new nit.

Bug, still open: /docs/cli/zero is live on main. This branch moves it to cli/first.mdx and adds no /cli/zero redirect, so the old URL will 404. This matches your "no redirects" choice, so it's your call.
Nit, still open: The Zero 0.8 page (content/(dynamic)/zero.mdx, line 134) still says "edit and publish the current Zero app as usual". After migration it's a First app.
Nit, new: /runtimes now redirects to /zero, the retired Zero 0.8 page. It should go to /first. /runtimes/zero, /apps/zero and /zero-runtime can stay on /zero.

batuhan · 2026-11-09T03:56:53Z

Closing. First's docs are now a separate site, so spacefast.com/docs gets no First section and no rename. #113 marks Zero retired instead.

spacefast Bot temporarily deployed to preview/rename-to-first November 9, 2026 02:53 Inactive

indent Bot reviewed Nov 9, 2026

View reviewed changes

spacefast Bot temporarily deployed to preview/rename-to-first November 9, 2026 03:49 Inactive

batuhan mentioned this pull request Nov 9, 2026

Mark Zero retired and point new apps to First #113

Closed

batuhan closed this Nov 9, 2026

Conversation

batuhan commented Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How

Routes

Names kept

Hold: check against the shipped names

Checks

Uh oh!

batuhan commented Nov 9, 2026

Uh oh!

indent Bot commented Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

chatgpt-codex-connector Bot commented Nov 9, 2026

Uh oh!

chatgpt-codex-connector Bot commented Nov 9, 2026

Uh oh!

indent Bot Nov 9, 2026

Choose a reason for hiding this comment

Uh oh!

indent Bot Nov 9, 2026

Choose a reason for hiding this comment

Uh oh!

indent Bot commented Nov 9, 2026

Uh oh!

batuhan commented Nov 9, 2026

Uh oh!

indent Bot commented Nov 9, 2026

Uh oh!

indent Bot commented Nov 9, 2026

Uh oh!

indent Bot commented Nov 9, 2026

Uh oh!

batuhan commented Nov 9, 2026

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

batuhan commented Nov 9, 2026 •

edited

Loading

indent Bot commented Nov 9, 2026 •

edited

Loading

coderabbitai Bot commented Nov 9, 2026 •

edited

Loading