What the agent does
The agent clones the repository into its own cloud sandbox and reads how the package is built and what it exports before it adds a docs tool. In a library like sindresorhus/ky, package.json says "type": "module", engines.node is >=22, exports points types at ./distribution/index.d.ts, and files publishes only distribution. The build script is del-cli distribution && tsc --project tsconfig.dist.json; that tsconfig extends ./tsconfig (itself extending @sindresorhus/tsconfig with exactOptionalPropertyTypes), sets rootDir to ./source and outDir to ./distribution. The test script chains xo, the build, a tsc --project tsconfig.test.json type check and ava. The agent reads .gitignore too: distribution/ and package-lock.json are ignored, so the docs output must be ignored the same way and the workflow cannot rely on a lockfile.
Then it reads source/index.ts to learn the public surface TypeDoc will document. The default export is the ky instance made by createInstance. After it come the type exports: KyInstance; Input, Options, NormalizedOptions, RetryOptions, ShouldRetryState, SearchParamsOption and Progress from types/options.js; eleven hook types from types/hooks.js; ResponsePromise, the three StandardSchemaV1 types, KyRequest and KyResponse. The value exports are seven error classes (KyError, HTTPError, SchemaValidationError, NetworkError, TimeoutError, ResponseSizeError, ForceRetryError), six is* type guards from utils/type-guards.js and replaceOption. A comment says NonError is deliberately not exported. The agent notes that source/types/options.ts already carries JSDoc on its options, which is what TypeDoc renders, and that readme.md has a long hand-written ## API section (### ky(input, options?), ##### retry, ###### hooks.beforeRequest, ...) that stays the narrative reference while the generated site becomes the exhaustive one.
The agent adds typedoc as a dev dependency and writes typedoc.json: entryPoints ["source/index.ts"], tsconfig tsconfig.dist.json so the same compiler settings apply, out docs, readme readme.md so the landing page is the existing readme, excludeInternal on, and validation.notExported on so a type that appears in a signature but is not exported from index.ts fails the build instead of rendering as a dead link. It adds a docs script (typedoc) and a docs:check script (typedoc --emit none --treatWarningsAsErrors) that validates without writing files and fails on any warning, appends docs/ to .gitignore, and runs both in the sandbox with npm install. The output is checked by hand: the Options page should list every option the readme documents, each error class should show its name and the HTTPError page its response and request properties.
Finally it adds .github/workflows/docs.yml: on push to main, a job with permissions: pages: write and id-token: write runs actions/checkout, actions/setup-node with Node 22, npm install, npm run docs, then actions/upload-pages-artifact with path: docs and actions/deploy-pages. The existing main.yml CI gets one step, npm run docs:check, in its browser job, which the file's own comment reserves for checks that do not depend on the Node version. The agent changes nothing in source/ and nothing in the readme beyond one line under ## API linking to the published site.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add TypeDoc to this TypeScript library. Read package.json, the tsconfig files and the entry point first, and document exactly what the entry point exports, nothing more. Configure TypeDoc to use the distribution tsconfig, use the existing readme as the landing page, and fail on types that are referenced but not exported. Add a docs script that builds the site and a check script that validates without writing files, ignore the output directory, and add a GitHub Actions workflow that builds the site on pushes to main and deploys it to GitHub Pages. Add the check script to the existing CI workflow. Do not change any source file or the public API. Open a pull request that lists every exported symbol the site documents.",
"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
What comes back is a pull request on its own branch that adds typedoc.json and .github/workflows/docs.yml, changes package.json (the typedoc dev dependency, the docs and docs:check scripts), .gitignore (docs/), .github/workflows/main.yml (one step) and readme.md (one link). Its description lists the entry point's exports as TypeDoc grouped them: the default export, the type aliases and interfaces, the classes, the type guards and replaceOption, and quotes the docs:check output from the sandbox, warnings included.
The run's record keeps every command with its output, including the npm install that fetched TypeDoc and the validation pass, so a reviewer can see which version was installed and that the build produced no warnings before the workflow ever runs on GitHub.
Before merging, a reviewer enables GitHub Pages with GitHub Actions as the source in the repository settings, since the workflow cannot do that, checks that the readme landing page renders the readme's relative image path for media/logo.svg (TypeDoc copies the readme but not sibling files unless told to), and decides whether validation.notExported should block CI or only warn while the first undocumented types are sorted out.
Run it on every terminal hand-off
This is a one-time setup, so the natural start is from a terminal: one POST /o/{org}/sessions with this body and the repository in resources, then walk away. The run keeps going in its sandbox, and when the turn ends the sandbox parks with its disk and memory, so a follow-up (POST /o/{org}/sessions/{id}/messages) can ask for a different theme or output path without starting over.
A webhook on the API key reports run.completed with the session_url to read the pull request link, or the key's creator watches the live event stream at GET /o/{org}/sessions/{id}/events.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Documentation tooling is the kind of change that is easy to half-finish: a config that documents internal helpers, a workflow that fails on the first push because Pages permissions are missing, a readme landing page with broken relative links. The agent reads the entry point and the build configuration first, so the site documents the package the way exports presents it, and it runs the validation in its own sandbox so unresolved references are found before the pull request opens.
The sandbox is a real computer with Node and npm, so npm install and typedoc run for real and their output is kept in the run's record. Several libraries can get the same treatment at once, each in its own sandbox, and each pull request arrives with the validation output as proof.
Frequently asked questions
Will TypeDoc document my internal modules?
No. With source/index.ts as the only entry point, TypeDoc documents what that file exports and the types those exports reference. Internal helpers such as utils/merge.ts appear only where an exported signature uses them, and excludeInternal hides anything tagged @internal.
What if a type is used in a public signature but not exported?
validation.notExported turns that into a warning, and typedoc --emit none --treatWarningsAsErrors fails the check. The pull request lists each such type so you can decide whether to export it from the entry point or mark it @internal.
Does it need a lockfile?
No. This library ignores package-lock.json, so the workflow runs npm install rather than npm ci. If your repository commits a lockfile, the agent uses npm ci and enables the setup-node cache instead.
Why not generate Markdown into the readme instead?
The readme already has a curated API section with examples and prose that a generator would not produce. The site complements it with every signature, overload and property, and the readme gains one link to it. If you prefer Markdown output, a follow-up can switch to the TypeDoc Markdown plugin.
More TypeScript library jobs
More jobs like this: Hand off a long task
- Add a Typing Indicator to a Socket.IO Chat (Socket.IO)
- Add a Typo Check to a Docusaurus Site in CI (Docusaurus)
- Add a Typo Check to an Eleventy Blog in CI (Eleventy)