# Building a product, for agents

The brief an agent follows when it builds a new Buun Group product, or adds Buun Identity to one, without reading the Buun Group repositories. Each step is something to do, then something to check.

## Before writing code

- Read [llms-full.txt](https://developers.buungroup.com/llms-full.txt) once: it is every page here in one file.
- The product runs on Cloudflare Workers. Its MCP server is a Worker of its own, on `mcp.<product domain>`, with its MCP endpoint at `/mcp-oauth`.
- Pick the product id: lower case letters, one word, such as `plotwork`. It must be added to `PRODUCTS` in `@buun-group/core` by a change to `buun-group/buungroup-app`, and the package published, before anything else names it.

## The rules that are easy to get wrong

| Rule | Check |
|---|---|
| Accept a token only when `aud` is exactly your own address | A token for the gateway or another product is refused, with a test |
| Insist on `typ: at+jwt` and `alg: ES256` | An ID token sent as an access token is refused, with a test |
| Take the issuer and your own address from `wrangler.jsonc` vars, per environment | No address is read from a token or a request |
| Link an existing user by address only when it is verified on both sides | An unverified address makes a new user, with a test |
| Answer 401 with `WWW-Authenticate: Bearer error="invalid_token"` for any token that fails | The gateway trades again on a 401 and on nothing else |
| Never log a token, and never forward one | Search the code for the header name before shipping |
| Never keep a plan in a token or a long cache | Ask `/oauth/plans` each time it matters |
| Keep your own sign-in working beside Buun Identity's | Pick the check by the token's `iss`, then verify everything |

## The steps

1. **Sign-in on the website.** Ask staff for a Buun Group product client with your redirect addresses. Build [the sign-in flow](https://developers.buungroup.com/sign-in/flow): PKCE S256, `state`, `iss` checked on return, tokens checked as on [Tokens and keys](https://developers.buungroup.com/sign-in/tokens). Test: a wrong `state` is refused; a wrong `iss` is refused.
2. **Plans.** Read [`/oauth/plans`](https://developers.buungroup.com/sign-in/plans) where the product decides what a person may do. Test: a cancelled plan stops access at the next request.
3. **The MCP server.** Make it accept Buun Identity tokens as on [Accepting Buun Identity tokens](https://developers.buungroup.com/mcp/accepting-tokens). Test every refusal in the table there.
4. **Tools.** Give each tool a stable name, an honest description, `readOnlyHint` or `destructiveHint`, and an input schema under 32 KB. Staff approve each version before an agent sees it: [Tool review](https://developers.buungroup.com/mcp/tool-review).
5. **The gateway.** Ask for, or make as a reviewed change to `buun-group/buungroup-gateway`, a catalogue entry for each environment with `acceptsIdentityTokens: true`, and a resource server in the staff console for each MCP address: [How the gateway works](https://developers.buungroup.com/mcp/how-it-works).
6. **Test on one machine** as on [Local development](https://developers.buungroup.com/local-development): `pnpm dev:exchange`, a plan for yourself, `claude mcp add --transport http buun-local http://localhost:28502/mcp`, approve the tools, call one.

## Asking the person

Stop and ask before anything outward-facing: deploying, setting a secret, applying a remote migration, publishing a package, or registering a client or resource server in a deployed environment. Everything on a developer's machine is safe to do.

## Where things are

| Thing | Where |
|---|---|
| Product ids, scopes, the client schema | `@buun-group/core` on GitHub Packages, `buun-group/buungroup-app` `packages/core` |
| The design system | `@buun-group/ui`, the same repository, `packages/ui` |
| The issuer and the portal | `buun-group/buungroup-app`, `apps/identity` and `apps/account` |
| The gateway | `buun-group/buungroup-gateway` |
| The staff console | `buun-group/buungroup-staff` |
| These pages, as Markdown | `buun-group/buungroup-app`, `apps/developers/content`, and on this site at `/<page>.md` |

Source: https://developers.buungroup.com/agents/building-a-product
