What the agent does
The agent reads how the docs are built and deployed before it decides how to version them. In a monorepo like vuejs/pinia, the docs are a workspace package, packages/docs, with vitepress 1.6.4, vitepress-plugin-llms and typedoc-vitepress-theme as dependencies and scripts docs, docs:build and docs:api, the last running run-typedoc.mjs to generate the API pages from the library's types. .vitepress/config/index.ts spreads a shared.ts config and defines locales: root and zh built from this repository, and es, ko, pt, uk and ru as links to sites other people deploy. netlify.toml builds with pnpm run docs:build, publishes packages/docs/.vitepress/dist, pins NODE_VERSION = "24" and skips builds through scripts/docs-check.sh, which exits zero unless packages/docs/, the vitepress entry in pnpm-lock.yaml, netlify.toml or a docs-prefixed commit message changed. .github/workflows/ci.yml lists packages/docs/** in its paths but runs only lint, type checks and tests, never a docs build.
The repository already versions by branch, and the docs lag that. packages/pinia/package.json is 4.1.0 on the default branch, v4, with v3, v2 and v1 branches beside it; the v3 branch's packages/pinia/package.json is 3.0.4 and its netlify.toml is identical to the current one. Yet en.ts and zh.ts on v4 still show a nav item text: 'v3.x' whose only entry is v2.x linking to https://v2.pinia.vuejs.org, and their changelog link points at blob/v3/packages/pinia/CHANGELOG.md. On the v2 branch the same menu reads v2.x with an item v3.x pointing at https://pinia.vuejs.org, which is the pattern the project uses for an archived major: the menu names the version you are reading and links the others. So the work is to carry that pattern to the new major, give v3 an archive site, and make the archive say it is one.
On v4 the agent edits en.ts and zh.ts so the menu reads v4.x with items v3.x at https://v3.pinia.vuejs.org and v2.x at the existing v2 address, and points both changelog links at blob/v4. To stop the menu drifting again, it reads the version from packages/pinia/package.json in shared.ts and derives the vX.x label from its major, so the next major changes the label by itself. On the v3 branch it opens a second pull request with the mirror image, v3.x current and v4.x at https://pinia.vuejs.org, and adds an archive banner through the theme: .vitepress/theme/index.ts already wraps DefaultTheme.Layout with slots for the hero image, the aside and doc-before, and carries a commented-out layout-top slot, so the agent adds a small VersionBanner.vue in that slot that renders only when a VITE_DOCS_ARCHIVED build variable is set, saying which version these docs are for and linking to the current site. The banner's strings go in both locales, since zh is built from the same branch.
Then it builds both. It runs pnpm install --frozen-lockfile and pnpm run docs:build on each branch, which runs the typedoc step first, opens the output with vitepress preview in its browser, and checks the menu on the home page and on a zh page, the banner on the v3 build and its absence on v4, and that sitemap.xml under dist still names pinia.vuejs.org on the current branch, because shared.ts hard-codes the sitemap hostname and the archive needs its own. It leaves netlify.toml alone on both branches, since the archive is a second Netlify site built from the v3 branch with the same command, and the person who owns the Netlify account creates it; the pull request on v3 lists the three settings that site needs, the branch, the VITE_DOCS_ARCHIVED variable and the v3 subdomain, and the v4 pull request says its v3.x link resolves only once that site exists.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Set up versioned docs for this VitePress site. Read the docs package, every file under .vitepress/config and .vitepress/theme, netlify.toml, the deploy-skip script and the CI workflow first, and read the library's package.json on the default branch and on each older major branch to learn which versions exist and how their docs differ. On the current branch make the version menu name the current major, derived from the library's package.json so it cannot drift, with one item per older major linking to that major's own site, and fix any changelog link that points at an older branch. On the most recent older branch open a second pull request that flips the menu to name that version and link the current site, and adds a banner in the theme's layout-top slot, shown only when an archive build variable is set, in every locale the branch builds. Run the docs build on both branches, open the output in the browser and check the menu, the banner and the sitemap hostname. Do not change the deploy config; list instead the settings a second deploy of the older branch needs. Open both pull requests with the build output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
Two pull requests. The one on the current branch changes en.ts, zh.ts and shared.ts: the version menu, the derived label and the changelog links. The one on the older major's branch changes the same menu the other way, adds VersionBanner.vue and the layout-top slot in theme/index.ts, and adds the banner strings per locale. Each description has the docs:build output, screenshots of the menu and of the banner from the browser, and the three settings the archive deploy needs; the full build logs and every page the agent opened are in the run's record.
A reviewer checks the links in the menu against the sites that exist today, since the v3.x entry on the current branch points at a site that goes live only when someone creates it, and checks that the banner is gated on the build variable so a preview deploy of the older branch does not show it by accident. The build output answers whether the typedoc step and both locales still render.
Run it on every terminal hand-off
A maintainer who has just tagged a new major starts this from the terminal with this body and the repository in resources, and returns to the release notes. The run reads the real branches and the real config, so the menu follows the versioning the repository already practises rather than a scheme imported from another tool.
Send a request_id, a UUID, with the body so a retried start returns the run it already began. When the turn ends, the answer GET /o/{org}/sessions/{id} carries links both pull requests, and a follow-up to the same session can ask it to add a robots rule or a noindex meta tag to the archive build once the second site exists.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Versioned docs are a pair of edits that have to agree across two branches and two locales, and the mistake is always the same: a menu that still names last year's major, or a link to a site nobody created. The agent reads every branch, builds both, opens the output in its own browser and attaches the pictures, so the reviewer sees the menu and the banner as a reader will rather than as a diff of config.
The same run fits any VitePress site that keeps a branch per major, whether it deploys to Netlify, Vercel or Pages: the agent changes the config and the theme, not the host, and lists what the host needs. Each repository gets a menu derived from its own package version, and every run keeps the full record of the builds that prove it.
Frequently asked questions
Does it deploy the archived version?
No. The archive is a second site built from the older branch by the same docs:build command, and creating that site needs the hosting account. The pull request on the older branch lists the branch, the build variable and the hostname it needs, and the current branch's link resolves once it exists.
What about the translations hosted elsewhere?
Locales that are links to other people's sites, like the Spanish or Korean docs, stay as links; the agent cannot version a site it does not build. The locales built from the repository, here English and Chinese, get the menu and the banner strings.
Will the version label need editing at the next major?
No. The label is derived from the library's package.json major in shared.ts, so it changes when the version does. The items for older majors are a list in the same file; adding the next archive is one line.
Why a banner instead of a different theme colour on the archive?
A banner in the layout-top slot is text a reader and a search engine can read, says which version it is and links to the current one. It is gated on a build variable so previews and local builds of the older branch look normal unless that variable is set.