Coding agents

Beignet's conventions are enforced by tooling — beignet lint checks dependency direction, beignet doctor reports registration and structure drift, and generators produce canonical output. That makes a Beignet app unusually legible to coding agents: an agent can generate an artifact, check its own work, and fix drift without guessing at project conventions. Three integration points connect agents to that tooling.

Package-shipped skills

Beignet packages ship TanStack Intent skills with the npm package version that contains the code they describe. Generated apps trust the relevant Beignet packages through package.json#intent.skills, so an agent can load the guidance that matches the installed Beignet version instead of relying on a copied file that drifts.

Start with Intent from the app root:

bash

bunx @tanstack/intent@latest install
bunx @tanstack/intent@latest list
bunx @tanstack/intent@latest load @beignet/core#app-architecture

Use the matching runner for the app's package manager, such as npx, pnpm dlx, or yarn dlx.

Load the narrow skill for the task:

Skill	Use it for
`@beignet/core#app-architecture`	Schemas, contracts, use cases, errors, ports, policies, workflows, seeds, tests, and core imports
`@beignet/next#routes-server`	Route groups, central registration, server context, Next route handlers, OpenAPI, devtools, uploads, storage, webhooks, schedules, and outbox drains
`@beignet/react-query#client`	Typed clients, query/mutation/infinite options, feature client helpers, hooks, cache keys, invalidation, and client/server boundary fixes
`@beignet/react-hook-form#forms`	Contract-backed forms, Standard Schema resolvers, root form errors, React Query mutations, transforming body schemas, and form boundaries
`@beignet/react-uploads#uploads-client`	Typed upload clients, React upload hooks, progress, abort/reset behavior, upload callbacks, invalidation, and upload client boundaries
`@beignet/provider-db-drizzle#database-provider`	Drizzle provider setup, schema placement, config, `DbPort` typing, repositories, Unit of Work, audit, idempotency, outbox, migrations, and doctor drift
`@beignet/provider-auth-better-auth#auth-provider`	Better Auth setup, auth routes, `AuthPort` typing, deferred port registration, server context, auth hooks, policies, tests, and doctor drift
`@beignet/cli#app-structure`	Generators, full-slice recipes, db schema sync, `beignet.config.*`, route inspection, lint, doctor, MCP tools, and generated app structure

The scaffolded guide files

beignet create writes AGENTS.md and CLAUDE.md at the app root. Agents that follow the AGENTS.md convention read AGENTS.md automatically, and Claude reads CLAUDE.md; both files contain the same conventions and also apply to humans.

It carries the conventions an agent cannot discover by reading code:

Registration is explicit. Generators create or update the central server/ entrypoints for route groups, schedules, tasks, and outbox registries. Hand-written files still need to be wired there before they run, and beignet doctor --fix --dry-run previews exact guarded repairs before beignet doctor --fix --plan <plan-id> applies them.
Prefer generators. beignet make output lands in the right place, wires registries, and passes lint and doctor; hand-written files often miss a wiring step.
The capability index. A need-to-API table for the machinery agents most often reimplement by accident: query-cache invalidation, service contexts for non-HTTP entrypoints, reaching ports outside a request, raw routes, metadata-driven rate limits and idempotency, route-level test harnesses, and env validation.
The validation loop. Run beignet check after each change — it runs the app's Biome lint, beignet lint, beignet doctor --strict, tests, and typecheck in one pass — and treat findings as the next task.
Placement rules and the naming grammar. Where feature artifacts live, and how defineX, createX, and createXProvider divide the API.

The guide deliberately excludes anything discoverable from the code or covered elsewhere: package skills own framework-specific agent guidance, the README.md owns setup and run instructions, and AGENTS.md and CLAUDE.md own app-local conventions. Keeping them short keeps agents reading them.

The MCP server

beignet mcp runs a Model Context Protocol server over stdio, exposing the CLI's inspection and generation commands as tools:

Tool	What it does
`app_map`	Project the source-backed app graph by optional feature or node kinds. Read-only.
`explain`	Explain any mapped concept or diagnostic with `{ kind, target }`; returns source evidence, relationships, conventions, findings, suggested files, and follow-up commands. Read-only.
`check`	Run the complete validation loop and return versioned step results, bounded failure output, durations, and overall `ok`. Accepts `{ preflight?: boolean, timeoutMs?: number }` and cancels the active script with the request. It does not apply Beignet fixes, but app scripts retain their normal side effects, so this is an execution tool.
`db`	Run `generate`, `migrate`, `seed`, or `reset` with `{ command, dryRun?, timeoutMs? }`. Returns the matching versioned CLI/library report with bounded output, request cancellation, and a command timeout. Database scripts retain their app-owned side effects; `dryRun` reports the script without simulating its SQL or data changes.
`db_schema_sync`	Idempotently sync app-owned Beignet provider-table schema re-exports with `{ dialect?, tables?, output?, dryRun? }`. It writes source unless `dryRun` is true and never generates or applies SQL migrations.
`routes`	List the app's routes and contracts. Read-only.
`doctor`	Report framework drift as JSON diagnostics. Accepts `{ strict?: boolean }`, default `true`. Read-only.
`doctor_fix_plan`	Plan low-risk repairs with stable operation IDs, hashes, exact patches, and current doctor diagnostics. Read-only.
`doctor_fix`	Apply low-risk repairs. Pass `{ planId, fixIds? }` from `doctor_fix_plan` for guarded application; omitting both preserves apply-all. Its JSON matches guarded CLI apply, including `planId` and `operationIds`.
`lint`	Report architecture and dependency-direction diagnostics. Read-only.
`make`	Run a generator with `{ artifact, name, ...options }` — the same artifact kinds as `beignet make`.
`provider_add`	Add a provider setup preset with `{ preset, dryRun? }`; presets match `beignet provider add`.

Tool outputs are exactly the JSON the CLI's --json flags produce, so anything written against beignet map --json, beignet explain ... --json, beignet check --json, beignet db ... --json, beignet doctor --json, or beignet lint --json reads MCP results unchanged. For persistent generated work, the intended coding loop is app_map to orient, explain to focus one concept, make or an edit to change it, db_schema_sync when provider tables changed, db with generate then migrate, and check to verify the whole app.

Generated apps ship a .mcp.json that registers the server through the app-local @beignet/cli bin, so Claude Code picks it up with zero configuration. Other clients, such as Cursor and VS Code, take the same command in their own config files (.cursor/mcp.json or .vscode/mcp.json):

json

{
  "mcpServers": {
    "beignet": {
      "command": "./node_modules/.bin/beignet",
      "args": ["mcp"]
    }
  }
}

Run the MCP client from the app root so the relative bin path resolves to the installed app version. For one-off usage outside an installed app, use the scoped package name with a registry runner, such as bunx @beignet/cli mcp or npx @beignet/cli mcp; never use the unscoped beignet npm name.

llms.txt

The docs site publishes two plain-text views of itself, rebuilt on every docs build:

https://beignetjs.com/llms.txt — an llms.txt-style index mirroring the docs navigation: every page with its title, URL, and description.
https://beignetjs.com/llms-full.txt — the full text of every docs page in one file.

Use the index when an agent should navigate to the right page and fetch it; use the full file when an agent retrieves grep-style over the whole corpus.

See the CLI reference for the beignet mcp command and App architecture for the structure the conventions in AGENTS.md and CLAUDE.md describe.