# Voxgig SDK generation for agents

> This page is the entry point for an agent asked to ship an SDK. The Voxgig generator is deliberately agent-friendly: output is deterministic (same spec, same SDK, so diffs stay reviewable), the work is declarative (edit the model, not N codebases), regeneration is safe (decisions are declared in the model and generation diff-merges), drift is machine-checkable (`voxgig-sdkgen doctor` exits non-zero), and verification is offline (generated test suites plus a mock transport and network simulation). Every generated SDK also ships its own AGENTS.md.

The authoritative end-to-end guide is AGENTS.md in the create-sdkgen
repository: https://github.com/voxgig/create-sdkgen/blob/main/AGENTS.md. Read
it before a first build. The summary runbook:

## The runbook

1. Scaffold a project from the user's OpenAPI 3 description: `npm create @voxgig/sdkgen -- my-api -d ./openapi.yaml -o ./my-api-sdk`
2. Add language targets, plus the offline test feature: `cd my-api-sdk/.sdk && npx voxgig-sdkgen target add ts py go && npx voxgig-sdkgen feature add test`
3. Generate every SDK from the model: `npm run generate`
4. Verify a target the way its ecosystem would: `cd ../ts && npm install && npm run build && npm test`

Iterate by editing the model in `.sdk/model/` (entities, operations, fields,
project decisions), then regenerating. Run `npx voxgig-sdkgen doctor` before
committing.

## Rules

- Never hand-edit generated output (`ts/`, `py/`, `go/`, ...) to fix a bug: regeneration overwrites or merges it. Fix the model, a template or a component instead, then regenerate.
- `.sdk/model/project.aon` is the project's own file, created once and never overwritten. The model files beside it are toolchain-derived and refreshed, so edits there are lost by design.
- Prove behaviour with the generated offline tests; they need no server and no credentials.
- Treat a non-zero `doctor` exit as a finding to act on, not as noise.

## Where the deeper guides are

- [create-sdkgen AGENTS.md](https://github.com/voxgig/create-sdkgen/blob/main/AGENTS.md): the complete build guide, spec to publish.
- [sdkgen AGENTS.md](https://github.com/voxgig/sdkgen/blob/main/AGENTS.md): modifying the generator itself, templates, components and targets.
- [apidef AGENTS.md](https://github.com/voxgig/apidef/blob/main/AGENTS.md): how the OpenAPI description becomes the model.
- [Customization](https://voxgig.com/sdk/custom): the six levers, up to entirely custom language targets.
- [SDK features](https://voxgig.com/sdk/features): the eighteen generated features.
- [The site's own machine surface](https://voxgig.com/developers): MCP server, llms.txt, catalog API.