{"owner":"AmanVarshney01","repo":"create-better-t-stack","hasSkills":true,"totalSkillsCount":15,"totalTokensCount":10620,"categories":["marketplace","root-instruction","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".agents/plugins/marketplace.json",".claude-plugin/marketplace.json","AGENTS.md","packages/backend/convex/README.md","packages/create-bts/README.md","packages/template-generator/templates/backend/convex/packages/backend/convex/README.md","plugin/.claude-plugin/plugin.json","plugin/.codex-plugin/plugin.json","plugin/skills/add-to-project/SKILL.md","plugin/skills/scaffold-project/SKILL.md","plugin/skills/scaffold-project/references/cli.md","plugin/skills/scaffold-project/references/options.md","skills/better-t-stack/SKILL.md","skills/better-t-stack/references/cli.md","skills/better-t-stack/references/options.md"],"skills":{".agents/plugins/marketplace.json":"{\n  \"name\": \"better-t-stack\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": {\n        \"source\": \"local\",\n        \"path\": \"./plugin\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Coding\"\n    }\n  ]\n}\n",".claude-plugin/marketplace.json":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"better-t-stack\",\n  \"description\": \"Better-T-Stack plugin marketplace — scaffold end-to-end type-safe TypeScript projects with AI\",\n  \"owner\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": \"./plugin\",\n      \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n      \"author\": {\n        \"name\": \"Aman Varshney\",\n        \"url\": \"https://github.com/AmanVarshney01\"\n      },\n      \"homepage\": \"https://better-t-stack.dev\",\n      \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n      \"license\": \"MIT\",\n      \"category\": \"development\",\n      \"keywords\": [\n        \"better-t-stack\",\n        \"create-better-t-stack\",\n        \"scaffold\",\n        \"starter\",\n        \"boilerplate\",\n        \"typescript\",\n        \"fullstack\",\n        \"monorepo\",\n        \"turborepo\",\n        \"nx\",\n        \"nextjs\",\n        \"react\",\n        \"hono\",\n        \"trpc\",\n        \"better-auth\",\n        \"drizzle\",\n        \"tanstack\",\n        \"ai-agent\",\n        \"mcp\"\n      ]\n    }\n  ]\n}\n","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nThis repo is a Bun + Turborepo monorepo.\n\n- `apps/cli`: published CLI (`create-better-t-stack`), with source in `apps/cli/src` and tests in `apps/cli/test`.\n- `apps/web`: Next.js docs/site (`apps/web/src`, `apps/web/content/docs`, `apps/web/public`).\n- `packages/template-generator`: template generation engine used by the CLI.\n- `packages/types`: shared schemas/types.\n- `packages/backend`: Convex backend used by web features.\n- `plugin/`: installable agent plugin (Claude Code + Codex) — skills, commands, and MCP wiring; published via the root marketplaces (`.claude-plugin/`, `.agents/plugins/`).\n\n## Build, Test, and Development Commands\n\n- `bun install`: install workspace dependencies.\n- `bun dev:cli`: watch-build CLI package.\n- `bun dev:web`: run web app locally (`next dev --port 3333`).\n- `bun build`: build all packages/apps through Turbo.\n- `bun build:cli`: build only the CLI target.\n- `bun run check`: format + lint (`oxfmt . && oxlint .`).\n- `cd apps/cli && bun run test`: run CLI integration tests.\n\n## Coding Style & Naming Conventions\n\n- Language: TypeScript (strict mode enabled across projects).\n- Modules: ESM-first (`\"type\": \"module\"` where applicable).\n- Formatting/linting: `oxfmt` and `oxlint`; run `bun run check` before committing.\n- File naming: prefer kebab-case files (for example `database-setup.ts`).\n- Symbols: `camelCase` for functions/variables, `PascalCase` for types/components.\n- Keep feature logic near domain folders (`helpers`, `utils`, `template-handlers`).\n\n## Error Handling Conventions\n\n- In CLI code, prefer `better-result` over ad-hoc `try/catch` for recoverable flows.\n- Return typed `Result<T, E>` and use `Result.ok`, `Result.err`, `Result.try`, and `Result.tryPromise`.\n- Reuse domain errors from `apps/cli/src/utils/errors.ts` (`CLIError`, `ProjectCreationError`, `UserCancelledError`) and convert thrown prompt errors at boundaries.\n\n## Template Authoring (Handlebars)\n\n- Templates live in `packages/template-generator/templates` and use helpers from `packages/template-generator/src/core/template-processor.ts` (`eq`, `ne`, `and`, `or`, `includes`).\n- For conditional ORM-specific output, use helper form with quoted values:\n  - `{{#if (eq orm \"prisma\")}}`\n  - `{{else if (eq orm \"drizzle\")}}`\n  - `{{/if}}`\n  - Example: `packages/template-generator/templates/packages/infra/alchemy.run.ts.hbs`.\n- When files must contain literal `{{ ... }}` (Vue/JSX/template syntax), escape opening braces as `\\{{` in `.hbs` files so Handlebars does not evaluate them.\n  - Example: `packages/template-generator/templates/frontend/nuxt/app/pages/index.vue.hbs`.\n\n## Testing Guidelines\n\nA test earns its place when it can fail while a user would get hurt. Tests live in three tiers, each with one job:\n\n| Tier             | Where                                      | Runs                     | Proves                                                                                                 |\n| ---------------- | ------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Contract         | `apps/cli/test/*.test.ts`, `apps/web/test` | Every PR                 | The CLI, MCP and oRPC interfaces reject bad input, write the right files and keep existing ones        |\n| Generated builds | `apps/cli/test/generated-builds.test.ts`   | Every PR and daily       | Generated projects install the latest dependencies, typecheck, build and, where a sample opts in, boot |\n| Live             | `apps/cli/live-tests`                      | Locally, before releases | Generated apps work in a browser against real databases and deployments                                |\n\n- Use `bun:test`. Reuse `apps/cli/test/setup.ts` for disposable project directories.\n- Never assert that generated output contains text copied from a template. The generated-builds tier already proves templates compile and run.\n- Do not add isolated unit tests or mocked helper tests.\n- To cover a new stack, add a sample to `apps/cli/test/generated-builds/samples.ts`. If it needs a runtime check, name it in the sample's `checks` and implement it in `probes.ts`.\n- When an upstream release breaks a generated build, fix the template so it works on the latest version. Never pin an older dependency.\n- Keep live tests out of CI. Record their results in the pull request, not in the repository.\n\n## Commit & Pull Request Guidelines\n\n- Use Conventional Commits with scope, matching history:\n  - `feat(cli): ...`, `fix(web): ...`, `docs(cli): ...`\n- Open an issue/discussion before major feature work.\n- PRs should include:\n  - clear summary,\n  - linked issue (if applicable),\n  - verification steps run (`bun run check`, relevant tests),\n  - screenshots/GIFs for web UI changes.\n\n## Agent skills\n\n### Issue tracker\n\nIssues are tracked in GitHub Issues for `AmanVarshney01/create-better-t-stack` using the `gh` CLI.\n\n### Triage labels\n\nThe canonical triage roles map directly to same-named GitHub labels.\n","packages/backend/convex/README.md":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","packages/create-bts/README.md":"# create-bts\n\nThis is an alias package for [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack).\n\n## Usage\n\n```bash\nnpx create-bts@latest\n```\n\nor\n\n```bash\nbun create bts\n```\n\nFor full documentation, please visit [better-t-stack.dev](https://better-t-stack.dev/).\n\n## About\n\n`create-bts` is a shorter alias for the full `create-better-t-stack` command. Both packages provide the same functionality - a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects.\n\nAll functionality is provided by the main [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack) package.\n","packages/template-generator/templates/backend/convex/packages/backend/convex/README.md":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","plugin/.claude-plugin/plugin.json":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ]\n}\n","plugin/.codex-plugin/plugin.json":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ],\n  \"skills\": \"./skills/\",\n  \"mcpServers\": \"./.mcp.json\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\",\n    \"shortDescription\": \"Scaffold end-to-end type-safe TypeScript projects\",\n    \"longDescription\": \"Bring Better-T-Stack into Codex with skills that plan a valid stack and generate it through the official create-better-t-stack MCP server, plus an add-addons workflow for existing projects. Covers frontends (Next, TanStack, Nuxt, Svelte, Solid, Astro, React Native), backends (Hono, Express, Fastify, Elysia, Convex), databases and ORMs, auth, payments, deployment, and DB provisioning (Neon, Prisma Postgres, Supabase, Turso, PlanetScale, MongoDB Atlas, Cloudflare D1, Docker).\",\n    \"developerName\": \"Aman Varshney\",\n    \"category\": \"Coding\",\n    \"capabilities\": [\"Interactive\", \"Write\", \"MCP\"],\n    \"websiteURL\": \"https://better-t-stack.dev\",\n    \"brandColor\": \"#8839EF\",\n    \"composerIcon\": \"./assets/icon.svg\",\n    \"logo\": \"./assets/icon.svg\",\n    \"defaultPrompt\": [\n      \"Create a fullstack app with Next, Hono, Postgres + Drizzle, and Better Auth\",\n      \"Scaffold a TanStack Start project with a Neon database\",\n      \"Add PWA, Biome, and Turborepo to my Better-T-Stack project\"\n    ]\n  }\n}\n","plugin/skills/add-to-project/SKILL.md":"---\nname: add-to-project\ndescription: Add addons, tooling or a workspace package to an existing Better-T-Stack project, such as PWA, Tauri, Starlight or Fumadocs docs, Biome, Oxlint, Ultracite, Husky, Lefthook, Turborepo, Nx, the MCP or Skills addon, or a shared `packages/<name>`. Use when the project has a `bts.jsonc` file and the user wants to extend it or add tooling.\nmetadata:\n  priority: 7\n  docs:\n    - \"https://better-t-stack.dev/docs\"\n  pathPatterns:\n    - \"bts.jsonc\"\n---\n\n# Add to an existing Better-T-Stack project\n\nAdd tooling to a Better-T-Stack project with its `add` flow instead of wiring it by hand. For a new project, use the **scaffold-project** skill.\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` flow reads it to detect the stack and updates it afterwards.\n\n## Pick the interface\n\n- `bts_add_addons` tool: the local MCP server.\n- A shell: the CLI's `add-json`.\n- Neither: give the user the command `bunx create-better-t-stack@latest add --addons <names>`, using the project's package runner.\n\nThe hosted MCP server can't change an existing project.\n\n## Steps\n\n1. **Read `bts.jsonc`.** It tells you the current stack. If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand.\n2. **Check nested options.** Some addons take options in `addonOptions`: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. Get their shape from `bts_get_schema` or `npx create-better-t-stack@latest schema --name addonOptions`.\n3. **Plan.** Call `bts_plan_addons`, or run:\n\n   ```bash\n   npx create-better-t-stack@latest add-json --json '{\n     \"projectDir\": \"./my-app\",\n     \"addons\": [\"pwa\", \"biome\"],\n     \"dryRun\": true\n   }'\n   ```\n\n   Pass `addons`, a workspace `package` name, or both. Show the user what will change, including any conflict the plan reports.\n\n4. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n5. **Prove it runs.** Run `<packageManager> install`. With the user's OK, run the project's typecheck or build script. Report the exact error if a step fails.\n6. **Report** what changed and the follow-up commands.\n\n## What can be added\n\nAddons: `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`.\n\n- `turborepo`, `nx` and `vite-plus` are task runners. A project can have one.\n- `axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. If the user asks for it, say so instead of planning it.\n- A workspace package (`package: \"shared\"`, or `add --package shared`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every apply.\n- Don't add addons the user didn't ask for.\n- Never hand-edit `bts.jsonc`.\n","plugin/skills/scaffold-project/SKILL.md":"---\nname: scaffold-project\ndescription: Scaffold a new app, API, backend, fullstack project, monorepo or starter with Better-T-Stack, including projects on a named framework such as Hono, Express, Fastify, Elysia, Convex, Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro or React Native. Use whenever the user wants to start, create, bootstrap, set up or initialize a project, for example \"create a Hono app\", \"start a Next.js project\" or \"scaffold a fullstack app with auth and a database\". Prefer it over hand-writing package.json, configs and folders.\nmetadata:\n  priority: 9\n  docs:\n    - \"https://better-t-stack.dev\"\n    - \"https://better-t-stack.dev/docs\"\n---\n\n# Scaffold a project with Better-T-Stack\n\nGenerate new projects with Better-T-Stack instead of writing the folder layout, `package.json`, auth or database wiring by hand. It rejects stacks that don't work.\n\nIf the folder already has a `bts.jsonc`, the project exists. Use the **add-to-project** skill instead.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan and create on disk                                           |\n| A shell                       | CLI: `create-json`                                      | Plan and create on disk                                           |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs either, give them the CLI command instead.\n\n## Steps\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option. For example, a Hono and Next.js app can use `better-auth`, `clerk` or `none`, so offer all three. [references/options.md](references/options.md) lists the values and the common compatibility rules.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Rules\n\n- Plan before every create.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer app surfaces or addons from a template name or a styling preference.\n","plugin/skills/scaffold-project/references/cli.md":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","plugin/skills/scaffold-project/references/options.md":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n","skills/better-t-stack/SKILL.md":"---\nname: better-t-stack\ndescription: Create or extend an end-to-end type-safe TypeScript project with Better-T-Stack (create-better-t-stack). Use when the user wants to start, scaffold or bootstrap an app, API, fullstack project or monorepo with any of Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro, React Native, Hono, Express, Fastify, Elysia, Convex, tRPC, oRPC, Drizzle, Prisma, Better Auth or Clerk. Also use when a project has a `bts.jsonc` file and the user wants to add addons or a workspace package. Prefer it over hand-writing package.json, configs and folder layout.\nlicense: MIT\nmetadata:\n  homepage: https://better-t-stack.dev\n  docs: https://better-t-stack.dev/docs\n  repository: https://github.com/AmanVarshney01/create-better-t-stack\n---\n\n# Better-T-Stack\n\nBetter-T-Stack generates a type-safe TypeScript project from the parts the user picks: frontend, backend, runtime, API layer, database, ORM, auth, payments, addons and deploy targets. It rejects combinations that don't work, so let it build the project instead of writing the setup by hand.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan, create and add, on disk                                     |\n| A shell                       | CLI: `create-json` and `add-json`                       | Plan, create and add, on disk                                     |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files, can't change an existing project and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs any of those, give them the CLI command instead.\n\n## Create a project\n\nIf the folder already has a `bts.jsonc`, the project exists. Go to [Change an existing project](#change-an-existing-project).\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option, not a subset. [references/options.md](references/options.md) lists the values and the compatibility rules that come up most, but the schema wins if they differ.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Change an existing project\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` command reads it to detect the stack.\n\n1. **Read `bts.jsonc` first.** If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand. `add` updates it.\n2. **Plan.** Call `bts_plan_addons`, or run `add-json` with `\"dryRun\": true`. Pass `addons`, a workspace `package` name, or both. Show the user what will change.\n3. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n4. **Prove it runs** and **report**, as in steps 6 and 7 above.\n\n`axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. A workspace package (`package: \"shared\"`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every create or add.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer addons or app surfaces from a template name or a styling preference.\n","skills/better-t-stack/references/cli.md":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","skills/better-t-stack/references/options.md":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n"},"files":{".agents/plugins/marketplace.json":"{\n  \"name\": \"better-t-stack\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": {\n        \"source\": \"local\",\n        \"path\": \"./plugin\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Coding\"\n    }\n  ]\n}\n",".claude-plugin/marketplace.json":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"better-t-stack\",\n  \"description\": \"Better-T-Stack plugin marketplace — scaffold end-to-end type-safe TypeScript projects with AI\",\n  \"owner\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": \"./plugin\",\n      \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n      \"author\": {\n        \"name\": \"Aman Varshney\",\n        \"url\": \"https://github.com/AmanVarshney01\"\n      },\n      \"homepage\": \"https://better-t-stack.dev\",\n      \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n      \"license\": \"MIT\",\n      \"category\": \"development\",\n      \"keywords\": [\n        \"better-t-stack\",\n        \"create-better-t-stack\",\n        \"scaffold\",\n        \"starter\",\n        \"boilerplate\",\n        \"typescript\",\n        \"fullstack\",\n        \"monorepo\",\n        \"turborepo\",\n        \"nx\",\n        \"nextjs\",\n        \"react\",\n        \"hono\",\n        \"trpc\",\n        \"better-auth\",\n        \"drizzle\",\n        \"tanstack\",\n        \"ai-agent\",\n        \"mcp\"\n      ]\n    }\n  ]\n}\n","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nThis repo is a Bun + Turborepo monorepo.\n\n- `apps/cli`: published CLI (`create-better-t-stack`), with source in `apps/cli/src` and tests in `apps/cli/test`.\n- `apps/web`: Next.js docs/site (`apps/web/src`, `apps/web/content/docs`, `apps/web/public`).\n- `packages/template-generator`: template generation engine used by the CLI.\n- `packages/types`: shared schemas/types.\n- `packages/backend`: Convex backend used by web features.\n- `plugin/`: installable agent plugin (Claude Code + Codex) — skills, commands, and MCP wiring; published via the root marketplaces (`.claude-plugin/`, `.agents/plugins/`).\n\n## Build, Test, and Development Commands\n\n- `bun install`: install workspace dependencies.\n- `bun dev:cli`: watch-build CLI package.\n- `bun dev:web`: run web app locally (`next dev --port 3333`).\n- `bun build`: build all packages/apps through Turbo.\n- `bun build:cli`: build only the CLI target.\n- `bun run check`: format + lint (`oxfmt . && oxlint .`).\n- `cd apps/cli && bun run test`: run CLI integration tests.\n\n## Coding Style & Naming Conventions\n\n- Language: TypeScript (strict mode enabled across projects).\n- Modules: ESM-first (`\"type\": \"module\"` where applicable).\n- Formatting/linting: `oxfmt` and `oxlint`; run `bun run check` before committing.\n- File naming: prefer kebab-case files (for example `database-setup.ts`).\n- Symbols: `camelCase` for functions/variables, `PascalCase` for types/components.\n- Keep feature logic near domain folders (`helpers`, `utils`, `template-handlers`).\n\n## Error Handling Conventions\n\n- In CLI code, prefer `better-result` over ad-hoc `try/catch` for recoverable flows.\n- Return typed `Result<T, E>` and use `Result.ok`, `Result.err`, `Result.try`, and `Result.tryPromise`.\n- Reuse domain errors from `apps/cli/src/utils/errors.ts` (`CLIError`, `ProjectCreationError`, `UserCancelledError`) and convert thrown prompt errors at boundaries.\n\n## Template Authoring (Handlebars)\n\n- Templates live in `packages/template-generator/templates` and use helpers from `packages/template-generator/src/core/template-processor.ts` (`eq`, `ne`, `and`, `or`, `includes`).\n- For conditional ORM-specific output, use helper form with quoted values:\n  - `{{#if (eq orm \"prisma\")}}`\n  - `{{else if (eq orm \"drizzle\")}}`\n  - `{{/if}}`\n  - Example: `packages/template-generator/templates/packages/infra/alchemy.run.ts.hbs`.\n- When files must contain literal `{{ ... }}` (Vue/JSX/template syntax), escape opening braces as `\\{{` in `.hbs` files so Handlebars does not evaluate them.\n  - Example: `packages/template-generator/templates/frontend/nuxt/app/pages/index.vue.hbs`.\n\n## Testing Guidelines\n\nA test earns its place when it can fail while a user would get hurt. Tests live in three tiers, each with one job:\n\n| Tier             | Where                                      | Runs                     | Proves                                                                                                 |\n| ---------------- | ------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Contract         | `apps/cli/test/*.test.ts`, `apps/web/test` | Every PR                 | The CLI, MCP and oRPC interfaces reject bad input, write the right files and keep existing ones        |\n| Generated builds | `apps/cli/test/generated-builds.test.ts`   | Every PR and daily       | Generated projects install the latest dependencies, typecheck, build and, where a sample opts in, boot |\n| Live             | `apps/cli/live-tests`                      | Locally, before releases | Generated apps work in a browser against real databases and deployments                                |\n\n- Use `bun:test`. Reuse `apps/cli/test/setup.ts` for disposable project directories.\n- Never assert that generated output contains text copied from a template. The generated-builds tier already proves templates compile and run.\n- Do not add isolated unit tests or mocked helper tests.\n- To cover a new stack, add a sample to `apps/cli/test/generated-builds/samples.ts`. If it needs a runtime check, name it in the sample's `checks` and implement it in `probes.ts`.\n- When an upstream release breaks a generated build, fix the template so it works on the latest version. Never pin an older dependency.\n- Keep live tests out of CI. Record their results in the pull request, not in the repository.\n\n## Commit & Pull Request Guidelines\n\n- Use Conventional Commits with scope, matching history:\n  - `feat(cli): ...`, `fix(web): ...`, `docs(cli): ...`\n- Open an issue/discussion before major feature work.\n- PRs should include:\n  - clear summary,\n  - linked issue (if applicable),\n  - verification steps run (`bun run check`, relevant tests),\n  - screenshots/GIFs for web UI changes.\n\n## Agent skills\n\n### Issue tracker\n\nIssues are tracked in GitHub Issues for `AmanVarshney01/create-better-t-stack` using the `gh` CLI.\n\n### Triage labels\n\nThe canonical triage roles map directly to same-named GitHub labels.\n","packages/backend/convex/README.md":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","packages/create-bts/README.md":"# create-bts\n\nThis is an alias package for [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack).\n\n## Usage\n\n```bash\nnpx create-bts@latest\n```\n\nor\n\n```bash\nbun create bts\n```\n\nFor full documentation, please visit [better-t-stack.dev](https://better-t-stack.dev/).\n\n## About\n\n`create-bts` is a shorter alias for the full `create-better-t-stack` command. Both packages provide the same functionality - a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects.\n\nAll functionality is provided by the main [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack) package.\n","packages/template-generator/templates/backend/convex/packages/backend/convex/README.md":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","plugin/.claude-plugin/plugin.json":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ]\n}\n","plugin/.codex-plugin/plugin.json":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ],\n  \"skills\": \"./skills/\",\n  \"mcpServers\": \"./.mcp.json\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\",\n    \"shortDescription\": \"Scaffold end-to-end type-safe TypeScript projects\",\n    \"longDescription\": \"Bring Better-T-Stack into Codex with skills that plan a valid stack and generate it through the official create-better-t-stack MCP server, plus an add-addons workflow for existing projects. Covers frontends (Next, TanStack, Nuxt, Svelte, Solid, Astro, React Native), backends (Hono, Express, Fastify, Elysia, Convex), databases and ORMs, auth, payments, deployment, and DB provisioning (Neon, Prisma Postgres, Supabase, Turso, PlanetScale, MongoDB Atlas, Cloudflare D1, Docker).\",\n    \"developerName\": \"Aman Varshney\",\n    \"category\": \"Coding\",\n    \"capabilities\": [\"Interactive\", \"Write\", \"MCP\"],\n    \"websiteURL\": \"https://better-t-stack.dev\",\n    \"brandColor\": \"#8839EF\",\n    \"composerIcon\": \"./assets/icon.svg\",\n    \"logo\": \"./assets/icon.svg\",\n    \"defaultPrompt\": [\n      \"Create a fullstack app with Next, Hono, Postgres + Drizzle, and Better Auth\",\n      \"Scaffold a TanStack Start project with a Neon database\",\n      \"Add PWA, Biome, and Turborepo to my Better-T-Stack project\"\n    ]\n  }\n}\n","plugin/skills/add-to-project/SKILL.md":"---\nname: add-to-project\ndescription: Add addons, tooling or a workspace package to an existing Better-T-Stack project, such as PWA, Tauri, Starlight or Fumadocs docs, Biome, Oxlint, Ultracite, Husky, Lefthook, Turborepo, Nx, the MCP or Skills addon, or a shared `packages/<name>`. Use when the project has a `bts.jsonc` file and the user wants to extend it or add tooling.\nmetadata:\n  priority: 7\n  docs:\n    - \"https://better-t-stack.dev/docs\"\n  pathPatterns:\n    - \"bts.jsonc\"\n---\n\n# Add to an existing Better-T-Stack project\n\nAdd tooling to a Better-T-Stack project with its `add` flow instead of wiring it by hand. For a new project, use the **scaffold-project** skill.\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` flow reads it to detect the stack and updates it afterwards.\n\n## Pick the interface\n\n- `bts_add_addons` tool: the local MCP server.\n- A shell: the CLI's `add-json`.\n- Neither: give the user the command `bunx create-better-t-stack@latest add --addons <names>`, using the project's package runner.\n\nThe hosted MCP server can't change an existing project.\n\n## Steps\n\n1. **Read `bts.jsonc`.** It tells you the current stack. If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand.\n2. **Check nested options.** Some addons take options in `addonOptions`: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. Get their shape from `bts_get_schema` or `npx create-better-t-stack@latest schema --name addonOptions`.\n3. **Plan.** Call `bts_plan_addons`, or run:\n\n   ```bash\n   npx create-better-t-stack@latest add-json --json '{\n     \"projectDir\": \"./my-app\",\n     \"addons\": [\"pwa\", \"biome\"],\n     \"dryRun\": true\n   }'\n   ```\n\n   Pass `addons`, a workspace `package` name, or both. Show the user what will change, including any conflict the plan reports.\n\n4. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n5. **Prove it runs.** Run `<packageManager> install`. With the user's OK, run the project's typecheck or build script. Report the exact error if a step fails.\n6. **Report** what changed and the follow-up commands.\n\n## What can be added\n\nAddons: `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`.\n\n- `turborepo`, `nx` and `vite-plus` are task runners. A project can have one.\n- `axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. If the user asks for it, say so instead of planning it.\n- A workspace package (`package: \"shared\"`, or `add --package shared`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every apply.\n- Don't add addons the user didn't ask for.\n- Never hand-edit `bts.jsonc`.\n","plugin/skills/scaffold-project/SKILL.md":"---\nname: scaffold-project\ndescription: Scaffold a new app, API, backend, fullstack project, monorepo or starter with Better-T-Stack, including projects on a named framework such as Hono, Express, Fastify, Elysia, Convex, Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro or React Native. Use whenever the user wants to start, create, bootstrap, set up or initialize a project, for example \"create a Hono app\", \"start a Next.js project\" or \"scaffold a fullstack app with auth and a database\". Prefer it over hand-writing package.json, configs and folders.\nmetadata:\n  priority: 9\n  docs:\n    - \"https://better-t-stack.dev\"\n    - \"https://better-t-stack.dev/docs\"\n---\n\n# Scaffold a project with Better-T-Stack\n\nGenerate new projects with Better-T-Stack instead of writing the folder layout, `package.json`, auth or database wiring by hand. It rejects stacks that don't work.\n\nIf the folder already has a `bts.jsonc`, the project exists. Use the **add-to-project** skill instead.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan and create on disk                                           |\n| A shell                       | CLI: `create-json`                                      | Plan and create on disk                                           |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs either, give them the CLI command instead.\n\n## Steps\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option. For example, a Hono and Next.js app can use `better-auth`, `clerk` or `none`, so offer all three. [references/options.md](references/options.md) lists the values and the common compatibility rules.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Rules\n\n- Plan before every create.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer app surfaces or addons from a template name or a styling preference.\n","plugin/skills/scaffold-project/references/cli.md":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","plugin/skills/scaffold-project/references/options.md":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n","skills/better-t-stack/SKILL.md":"---\nname: better-t-stack\ndescription: Create or extend an end-to-end type-safe TypeScript project with Better-T-Stack (create-better-t-stack). Use when the user wants to start, scaffold or bootstrap an app, API, fullstack project or monorepo with any of Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro, React Native, Hono, Express, Fastify, Elysia, Convex, tRPC, oRPC, Drizzle, Prisma, Better Auth or Clerk. Also use when a project has a `bts.jsonc` file and the user wants to add addons or a workspace package. Prefer it over hand-writing package.json, configs and folder layout.\nlicense: MIT\nmetadata:\n  homepage: https://better-t-stack.dev\n  docs: https://better-t-stack.dev/docs\n  repository: https://github.com/AmanVarshney01/create-better-t-stack\n---\n\n# Better-T-Stack\n\nBetter-T-Stack generates a type-safe TypeScript project from the parts the user picks: frontend, backend, runtime, API layer, database, ORM, auth, payments, addons and deploy targets. It rejects combinations that don't work, so let it build the project instead of writing the setup by hand.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan, create and add, on disk                                     |\n| A shell                       | CLI: `create-json` and `add-json`                       | Plan, create and add, on disk                                     |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files, can't change an existing project and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs any of those, give them the CLI command instead.\n\n## Create a project\n\nIf the folder already has a `bts.jsonc`, the project exists. Go to [Change an existing project](#change-an-existing-project).\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option, not a subset. [references/options.md](references/options.md) lists the values and the compatibility rules that come up most, but the schema wins if they differ.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Change an existing project\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` command reads it to detect the stack.\n\n1. **Read `bts.jsonc` first.** If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand. `add` updates it.\n2. **Plan.** Call `bts_plan_addons`, or run `add-json` with `\"dryRun\": true`. Pass `addons`, a workspace `package` name, or both. Show the user what will change.\n3. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n4. **Prove it runs** and **report**, as in steps 6 and 7 above.\n\n`axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. A workspace package (`package: \"shared\"`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every create or add.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer addons or app surfaces from a template name or a styling preference.\n","skills/better-t-stack/references/cli.md":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","skills/better-t-stack/references/options.md":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\n\nThis repo is a Bun + Turborepo monorepo.\n\n- `apps/cli`: published CLI (`create-better-t-stack`), with source in `apps/cli/src` and tests in `apps/cli/test`.\n- `apps/web`: Next.js docs/site (`apps/web/src`, `apps/web/content/docs`, `apps/web/public`).\n- `packages/template-generator`: template generation engine used by the CLI.\n- `packages/types`: shared schemas/types.\n- `packages/backend`: Convex backend used by web features.\n- `plugin/`: installable agent plugin (Claude Code + Codex) — skills, commands, and MCP wiring; published via the root marketplaces (`.claude-plugin/`, `.agents/plugins/`).\n\n## Build, Test, and Development Commands\n\n- `bun install`: install workspace dependencies.\n- `bun dev:cli`: watch-build CLI package.\n- `bun dev:web`: run web app locally (`next dev --port 3333`).\n- `bun build`: build all packages/apps through Turbo.\n- `bun build:cli`: build only the CLI target.\n- `bun run check`: format + lint (`oxfmt . && oxlint .`).\n- `cd apps/cli && bun run test`: run CLI integration tests.\n\n## Coding Style & Naming Conventions\n\n- Language: TypeScript (strict mode enabled across projects).\n- Modules: ESM-first (`\"type\": \"module\"` where applicable).\n- Formatting/linting: `oxfmt` and `oxlint`; run `bun run check` before committing.\n- File naming: prefer kebab-case files (for example `database-setup.ts`).\n- Symbols: `camelCase` for functions/variables, `PascalCase` for types/components.\n- Keep feature logic near domain folders (`helpers`, `utils`, `template-handlers`).\n\n## Error Handling Conventions\n\n- In CLI code, prefer `better-result` over ad-hoc `try/catch` for recoverable flows.\n- Return typed `Result<T, E>` and use `Result.ok`, `Result.err`, `Result.try`, and `Result.tryPromise`.\n- Reuse domain errors from `apps/cli/src/utils/errors.ts` (`CLIError`, `ProjectCreationError`, `UserCancelledError`) and convert thrown prompt errors at boundaries.\n\n## Template Authoring (Handlebars)\n\n- Templates live in `packages/template-generator/templates` and use helpers from `packages/template-generator/src/core/template-processor.ts` (`eq`, `ne`, `and`, `or`, `includes`).\n- For conditional ORM-specific output, use helper form with quoted values:\n  - `{{#if (eq orm \"prisma\")}}`\n  - `{{else if (eq orm \"drizzle\")}}`\n  - `{{/if}}`\n  - Example: `packages/template-generator/templates/packages/infra/alchemy.run.ts.hbs`.\n- When files must contain literal `{{ ... }}` (Vue/JSX/template syntax), escape opening braces as `\\{{` in `.hbs` files so Handlebars does not evaluate them.\n  - Example: `packages/template-generator/templates/frontend/nuxt/app/pages/index.vue.hbs`.\n\n## Testing Guidelines\n\nA test earns its place when it can fail while a user would get hurt. Tests live in three tiers, each with one job:\n\n| Tier             | Where                                      | Runs                     | Proves                                                                                                 |\n| ---------------- | ------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Contract         | `apps/cli/test/*.test.ts`, `apps/web/test` | Every PR                 | The CLI, MCP and oRPC interfaces reject bad input, write the right files and keep existing ones        |\n| Generated builds | `apps/cli/test/generated-builds.test.ts`   | Every PR and daily       | Generated projects install the latest dependencies, typecheck, build and, where a sample opts in, boot |\n| Live             | `apps/cli/live-tests`                      | Locally, before releases | Generated apps work in a browser against real databases and deployments                                |\n\n- Use `bun:test`. Reuse `apps/cli/test/setup.ts` for disposable project directories.\n- Never assert that generated output contains text copied from a template. The generated-builds tier already proves templates compile and run.\n- Do not add isolated unit tests or mocked helper tests.\n- To cover a new stack, add a sample to `apps/cli/test/generated-builds/samples.ts`. If it needs a runtime check, name it in the sample's `checks` and implement it in `probes.ts`.\n- When an upstream release breaks a generated build, fix the template so it works on the latest version. Never pin an older dependency.\n- Keep live tests out of CI. Record their results in the pull request, not in the repository.\n\n## Commit & Pull Request Guidelines\n\n- Use Conventional Commits with scope, matching history:\n  - `feat(cli): ...`, `fix(web): ...`, `docs(cli): ...`\n- Open an issue/discussion before major feature work.\n- PRs should include:\n  - clear summary,\n  - linked issue (if applicable),\n  - verification steps run (`bun run check`, relevant tests),\n  - screenshots/GIFs for web UI changes.\n\n## Agent skills\n\n### Issue tracker\n\nIssues are tracked in GitHub Issues for `AmanVarshney01/create-better-t-stack` using the `gh` CLI.\n\n### Triage labels\n\nThe canonical triage roles map directly to same-named GitHub labels.\n","isInternal":false,"tokens":1148,"sizeBytes":5107},{"name":"SKILL.md","path":"plugin/skills/add-to-project/SKILL.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/skills/add-to-project/SKILL.md","title":"add-to-project","category":"anthropic-skill","format":"markdown","content":"---\nname: add-to-project\ndescription: Add addons, tooling or a workspace package to an existing Better-T-Stack project, such as PWA, Tauri, Starlight or Fumadocs docs, Biome, Oxlint, Ultracite, Husky, Lefthook, Turborepo, Nx, the MCP or Skills addon, or a shared `packages/<name>`. Use when the project has a `bts.jsonc` file and the user wants to extend it or add tooling.\nmetadata:\n  priority: 7\n  docs:\n    - \"https://better-t-stack.dev/docs\"\n  pathPatterns:\n    - \"bts.jsonc\"\n---\n\n# Add to an existing Better-T-Stack project\n\nAdd tooling to a Better-T-Stack project with its `add` flow instead of wiring it by hand. For a new project, use the **scaffold-project** skill.\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` flow reads it to detect the stack and updates it afterwards.\n\n## Pick the interface\n\n- `bts_add_addons` tool: the local MCP server.\n- A shell: the CLI's `add-json`.\n- Neither: give the user the command `bunx create-better-t-stack@latest add --addons <names>`, using the project's package runner.\n\nThe hosted MCP server can't change an existing project.\n\n## Steps\n\n1. **Read `bts.jsonc`.** It tells you the current stack. If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand.\n2. **Check nested options.** Some addons take options in `addonOptions`: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. Get their shape from `bts_get_schema` or `npx create-better-t-stack@latest schema --name addonOptions`.\n3. **Plan.** Call `bts_plan_addons`, or run:\n\n   ```bash\n   npx create-better-t-stack@latest add-json --json '{\n     \"projectDir\": \"./my-app\",\n     \"addons\": [\"pwa\", \"biome\"],\n     \"dryRun\": true\n   }'\n   ```\n\n   Pass `addons`, a workspace `package` name, or both. Show the user what will change, including any conflict the plan reports.\n\n4. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n5. **Prove it runs.** Run `<packageManager> install`. With the user's OK, run the project's typecheck or build script. Report the exact error if a step fails.\n6. **Report** what changed and the follow-up commands.\n\n## What can be added\n\nAddons: `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`.\n\n- `turborepo`, `nx` and `vite-plus` are task runners. A project can have one.\n- `axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. If the user asks for it, say so instead of planning it.\n- A workspace package (`package: \"shared\"`, or `add --package shared`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every apply.\n- Don't add addons the user didn't ask for.\n- Never hand-edit `bts.jsonc`.\n","frontmatter":{"name":"add-to-project","description":"Add addons, tooling or a workspace package to an existing Better-T-Stack project, such as PWA, Tauri, Starlight or Fumadocs docs, Biome, Oxlint, Ultracite, Husky, Lefthook, Turborepo, Nx, the MCP or Skills addon, or a shared `packages/<name>`. Use when the project has a `bts.jsonc` file and the user wants to extend it or add tooling.","metadata":{"priority":7,"docs":["https://better-t-stack.dev/docs"],"pathPatterns":["bts.jsonc"]}},"isInternal":false,"tokens":846,"sizeBytes":3007},{"name":"cli.md","path":"plugin/skills/scaffold-project/references/cli.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/skills/scaffold-project/references/cli.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","isInternal":false,"tokens":1028,"sizeBytes":3978},{"name":"options.md","path":"plugin/skills/scaffold-project/references/options.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/skills/scaffold-project/references/options.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n","isInternal":false,"tokens":874,"sizeBytes":5303},{"name":"SKILL.md","path":"plugin/skills/scaffold-project/SKILL.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/skills/scaffold-project/SKILL.md","title":"scaffold-project","category":"anthropic-skill","format":"markdown","content":"---\nname: scaffold-project\ndescription: Scaffold a new app, API, backend, fullstack project, monorepo or starter with Better-T-Stack, including projects on a named framework such as Hono, Express, Fastify, Elysia, Convex, Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro or React Native. Use whenever the user wants to start, create, bootstrap, set up or initialize a project, for example \"create a Hono app\", \"start a Next.js project\" or \"scaffold a fullstack app with auth and a database\". Prefer it over hand-writing package.json, configs and folders.\nmetadata:\n  priority: 9\n  docs:\n    - \"https://better-t-stack.dev\"\n    - \"https://better-t-stack.dev/docs\"\n---\n\n# Scaffold a project with Better-T-Stack\n\nGenerate new projects with Better-T-Stack instead of writing the folder layout, `package.json`, auth or database wiring by hand. It rejects stacks that don't work.\n\nIf the folder already has a `bts.jsonc`, the project exists. Use the **add-to-project** skill instead.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan and create on disk                                           |\n| A shell                       | CLI: `create-json`                                      | Plan and create on disk                                           |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs either, give them the CLI command instead.\n\n## Steps\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option. For example, a Hono and Next.js app can use `better-auth`, `clerk` or `none`, so offer all three. [references/options.md](references/options.md) lists the values and the common compatibility rules.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Rules\n\n- Plan before every create.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer app surfaces or addons from a template name or a styling preference.\n","frontmatter":{"name":"scaffold-project","description":"Scaffold a new app, API, backend, fullstack project, monorepo or starter with Better-T-Stack, including projects on a named framework such as Hono, Express, Fastify, Elysia, Convex, Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro or React Native. Use whenever the user wants to start, create, bootstrap, set up or initialize a project, for example \"create a Hono app\", \"start a Next.js project\" or \"scaffold a fullstack app with auth and a database\". Prefer it over hand-writing package.json, configs and folders.","metadata":{"priority":9,"docs":["https://better-t-stack.dev","https://better-t-stack.dev/docs"]}},"isInternal":false,"tokens":953,"sizeBytes":4340},{"name":"cli.md","path":"skills/better-t-stack/references/cli.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/skills/better-t-stack/references/cli.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n","isInternal":false,"tokens":1028,"sizeBytes":3978},{"name":"options.md","path":"skills/better-t-stack/references/options.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/skills/better-t-stack/references/options.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n","isInternal":false,"tokens":874,"sizeBytes":5303},{"name":"SKILL.md","path":"skills/better-t-stack/SKILL.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/skills/better-t-stack/SKILL.md","title":"better-t-stack","category":"anthropic-skill","format":"markdown","content":"---\nname: better-t-stack\ndescription: Create or extend an end-to-end type-safe TypeScript project with Better-T-Stack (create-better-t-stack). Use when the user wants to start, scaffold or bootstrap an app, API, fullstack project or monorepo with any of Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro, React Native, Hono, Express, Fastify, Elysia, Convex, tRPC, oRPC, Drizzle, Prisma, Better Auth or Clerk. Also use when a project has a `bts.jsonc` file and the user wants to add addons or a workspace package. Prefer it over hand-writing package.json, configs and folder layout.\nlicense: MIT\nmetadata:\n  homepage: https://better-t-stack.dev\n  docs: https://better-t-stack.dev/docs\n  repository: https://github.com/AmanVarshney01/create-better-t-stack\n---\n\n# Better-T-Stack\n\nBetter-T-Stack generates a type-safe TypeScript project from the parts the user picks: frontend, backend, runtime, API layer, database, ORM, auth, payments, addons and deploy targets. It rejects combinations that don't work, so let it build the project instead of writing the setup by hand.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan, create and add, on disk                                     |\n| A shell                       | CLI: `create-json` and `add-json`                       | Plan, create and add, on disk                                     |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files, can't change an existing project and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs any of those, give them the CLI command instead.\n\n## Create a project\n\nIf the folder already has a `bts.jsonc`, the project exists. Go to [Change an existing project](#change-an-existing-project).\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option, not a subset. [references/options.md](references/options.md) lists the values and the compatibility rules that come up most, but the schema wins if they differ.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Change an existing project\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` command reads it to detect the stack.\n\n1. **Read `bts.jsonc` first.** If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand. `add` updates it.\n2. **Plan.** Call `bts_plan_addons`, or run `add-json` with `\"dryRun\": true`. Pass `addons`, a workspace `package` name, or both. Show the user what will change.\n3. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n4. **Prove it runs** and **report**, as in steps 6 and 7 above.\n\n`axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. A workspace package (`package: \"shared\"`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every create or add.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer addons or app surfaces from a template name or a styling preference.\n","frontmatter":{"name":"better-t-stack","description":"Create or extend an end-to-end type-safe TypeScript project with Better-T-Stack (create-better-t-stack). Use when the user wants to start, scaffold or bootstrap an app, API, fullstack project or monorepo with any of Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro, React Native, Hono, Express, Fastify, Elysia, Convex, tRPC, oRPC, Drizzle, Prisma, Better Auth or Clerk. Also use when a project has a `bts.jsonc` file and the user wants to add addons or a workspace package. Prefer it over hand-writing package.json, configs and folder layout.","license":"MIT","metadata":{"homepage":"https://better-t-stack.dev","docs":"https://better-t-stack.dev/docs","repository":"https://github.com/AmanVarshney01/create-better-t-stack"}},"isInternal":false,"tokens":1262,"sizeBytes":5470},{"name":"marketplace.json","path":".agents/plugins/marketplace.json","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/.agents/plugins/marketplace.json","title":"better-t-stack","category":"marketplace","format":"json","content":"{\n  \"name\": \"better-t-stack\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": {\n        \"source\": \"local\",\n        \"path\": \"./plugin\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Coding\"\n    }\n  ]\n}\n","frontmatter":{"name":"better-t-stack","interface":{"displayName":"Better-T-Stack"},"plugins":[{"name":"better-t-stack","source":{"source":"local","path":"./plugin"},"policy":{"installation":"AVAILABLE","authentication":"ON_INSTALL"},"category":"Coding"}]},"isInternal":false,"tokens":98,"sizeBytes":364},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/.claude-plugin/marketplace.json","title":"better-t-stack","category":"marketplace","format":"json","content":"{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"better-t-stack\",\n  \"description\": \"Better-T-Stack plugin marketplace — scaffold end-to-end type-safe TypeScript projects with AI\",\n  \"owner\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": \"./plugin\",\n      \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n      \"author\": {\n        \"name\": \"Aman Varshney\",\n        \"url\": \"https://github.com/AmanVarshney01\"\n      },\n      \"homepage\": \"https://better-t-stack.dev\",\n      \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n      \"license\": \"MIT\",\n      \"category\": \"development\",\n      \"keywords\": [\n        \"better-t-stack\",\n        \"create-better-t-stack\",\n        \"scaffold\",\n        \"starter\",\n        \"boilerplate\",\n        \"typescript\",\n        \"fullstack\",\n        \"monorepo\",\n        \"turborepo\",\n        \"nx\",\n        \"nextjs\",\n        \"react\",\n        \"hono\",\n        \"trpc\",\n        \"better-auth\",\n        \"drizzle\",\n        \"tanstack\",\n        \"ai-agent\",\n        \"mcp\"\n      ]\n    }\n  ]\n}\n","frontmatter":{"$schema":"https://anthropic.com/claude-code/marketplace.schema.json","name":"better-t-stack","description":"Better-T-Stack plugin marketplace — scaffold end-to-end type-safe TypeScript projects with AI","owner":{"name":"Aman Varshney","url":"https://github.com/AmanVarshney01"},"plugins":[{"name":"better-t-stack","source":"./plugin","description":"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.","author":{"name":"Aman Varshney","url":"https://github.com/AmanVarshney01"},"homepage":"https://better-t-stack.dev","repository":"https://github.com/AmanVarshney01/create-better-t-stack","license":"MIT","category":"development","keywords":["better-t-stack","create-better-t-stack","scaffold","starter","boilerplate","typescript","fullstack","monorepo","turborepo","nx","nextjs","react","hono","trpc","better-auth","drizzle","tanstack","ai-agent","mcp"]}]},"isInternal":false,"tokens":356,"sizeBytes":1370},{"name":"README.md","path":"packages/backend/convex/README.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/packages/backend/convex/README.md","title":"convex Documentation","category":"plugin-manifest","format":"markdown","content":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","isInternal":false,"tokens":584,"sizeBytes":2530},{"name":"README.md","path":"packages/create-bts/README.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/packages/create-bts/README.md","title":"create-bts Documentation","category":"plugin-manifest","format":"markdown","content":"# create-bts\n\nThis is an alias package for [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack).\n\n## Usage\n\n```bash\nnpx create-bts@latest\n```\n\nor\n\n```bash\nbun create bts\n```\n\nFor full documentation, please visit [better-t-stack.dev](https://better-t-stack.dev/).\n\n## About\n\n`create-bts` is a shorter alias for the full `create-better-t-stack` command. Both packages provide the same functionality - a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects.\n\nAll functionality is provided by the main [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack) package.\n","isInternal":false,"tokens":157,"sizeBytes":632},{"name":"README.md","path":"packages/template-generator/templates/backend/convex/packages/backend/convex/README.md","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/packages/template-generator/templates/backend/convex/packages/backend/convex/README.md","title":"convex Documentation","category":"plugin-manifest","format":"markdown","content":"# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n","isInternal":false,"tokens":584,"sizeBytes":2530},{"name":"plugin.json","path":"plugin/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/.claude-plugin/plugin.json","title":"better-t-stack","category":"plugin-manifest","format":"json","content":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ]\n}\n","frontmatter":{"name":"better-t-stack","version":"3.48.0","description":"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.","author":{"name":"Aman Varshney","url":"https://github.com/AmanVarshney01"},"homepage":"https://better-t-stack.dev","repository":"https://github.com/AmanVarshney01/create-better-t-stack","license":"MIT","keywords":["better-t-stack","create-better-t-stack","scaffold","starter","boilerplate","typescript","fullstack","monorepo","turborepo","nx","nextjs","react","hono","trpc","better-auth","drizzle","tanstack","ai-agent","mcp"]},"isInternal":false,"tokens":256,"sizeBytes":869},{"name":"plugin.json","path":"plugin/.codex-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/AmanVarshney01/create-better-t-stack/HEAD/plugin/.codex-plugin/plugin.json","title":"better-t-stack","category":"plugin-manifest","format":"json","content":"{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ],\n  \"skills\": \"./skills/\",\n  \"mcpServers\": \"./.mcp.json\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\",\n    \"shortDescription\": \"Scaffold end-to-end type-safe TypeScript projects\",\n    \"longDescription\": \"Bring Better-T-Stack into Codex with skills that plan a valid stack and generate it through the official create-better-t-stack MCP server, plus an add-addons workflow for existing projects. Covers frontends (Next, TanStack, Nuxt, Svelte, Solid, Astro, React Native), backends (Hono, Express, Fastify, Elysia, Convex), databases and ORMs, auth, payments, deployment, and DB provisioning (Neon, Prisma Postgres, Supabase, Turso, PlanetScale, MongoDB Atlas, Cloudflare D1, Docker).\",\n    \"developerName\": \"Aman Varshney\",\n    \"category\": \"Coding\",\n    \"capabilities\": [\"Interactive\", \"Write\", \"MCP\"],\n    \"websiteURL\": \"https://better-t-stack.dev\",\n    \"brandColor\": \"#8839EF\",\n    \"composerIcon\": \"./assets/icon.svg\",\n    \"logo\": \"./assets/icon.svg\",\n    \"defaultPrompt\": [\n      \"Create a fullstack app with Next, Hono, Postgres + Drizzle, and Better Auth\",\n      \"Scaffold a TanStack Start project with a Neon database\",\n      \"Add PWA, Biome, and Turborepo to my Better-T-Stack project\"\n    ]\n  }\n}\n","frontmatter":{"name":"better-t-stack","version":"3.48.0","description":"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.","author":{"name":"Aman Varshney","url":"https://github.com/AmanVarshney01"},"homepage":"https://better-t-stack.dev","repository":"https://github.com/AmanVarshney01/create-better-t-stack","license":"MIT","keywords":["better-t-stack","create-better-t-stack","scaffold","starter","boilerplate","typescript","fullstack","monorepo","turborepo","nx","nextjs","react","hono","trpc","better-auth","drizzle","tanstack","ai-agent","mcp"],"skills":"./skills/","mcpServers":"./.mcp.json","interface":{"displayName":"Better-T-Stack","shortDescription":"Scaffold end-to-end type-safe TypeScript projects","longDescription":"Bring Better-T-Stack into Codex with skills that plan a valid stack and generate it through the official create-better-t-stack MCP server, plus an add-addons workflow for existing projects. Covers frontends (Next, TanStack, Nuxt, Svelte, Solid, Astro, React Native), backends (Hono, Express, Fastify, Elysia, Convex), databases and ORMs, auth, payments, deployment, and DB provisioning (Neon, Prisma Postgres, Supabase, Turso, PlanetScale, MongoDB Atlas, Cloudflare D1, Docker).","developerName":"Aman Varshney","category":"Coding","capabilities":["Interactive","Write","MCP"],"websiteURL":"https://better-t-stack.dev","brandColor":"#8839EF","composerIcon":"./assets/icon.svg","logo":"./assets/icon.svg","defaultPrompt":["Create a fullstack app with Next, Hono, Postgres + Drizzle, and Better Auth","Scaffold a TanStack Start project with a Neon database","Add PWA, Biome, and Turborepo to my Better-T-Stack project"]}},"isInternal":false,"tokens":572,"sizeBytes":2055}],"systemPromptSnippet":"<yakaai_skills repo=\"AmanVarshney01/create-better-t-stack\">\n<!-- File: AGENTS.md (Tokens: ~1148 | Category: root-instruction) -->\n# Repository Guidelines\n\n## Project Structure & Module Organization\n\nThis repo is a Bun + Turborepo monorepo.\n\n- `apps/cli`: published CLI (`create-better-t-stack`), with source in `apps/cli/src` and tests in `apps/cli/test`.\n- `apps/web`: Next.js docs/site (`apps/web/src`, `apps/web/content/docs`, `apps/web/public`).\n- `packages/template-generator`: template generation engine used by the CLI.\n- `packages/types`: shared schemas/types.\n- `packages/backend`: Convex backend used by web features.\n- `plugin/`: installable agent plugin (Claude Code + Codex) — skills, commands, and MCP wiring; published via the root marketplaces (`.claude-plugin/`, `.agents/plugins/`).\n\n## Build, Test, and Development Commands\n\n- `bun install`: install workspace dependencies.\n- `bun dev:cli`: watch-build CLI package.\n- `bun dev:web`: run web app locally (`next dev --port 3333`).\n- `bun build`: build all packages/apps through Turbo.\n- `bun build:cli`: build only the CLI target.\n- `bun run check`: format + lint (`oxfmt . && oxlint .`).\n- `cd apps/cli && bun run test`: run CLI integration tests.\n\n## Coding Style & Naming Conventions\n\n- Language: TypeScript (strict mode enabled across projects).\n- Modules: ESM-first (`\"type\": \"module\"` where applicable).\n- Formatting/linting: `oxfmt` and `oxlint`; run `bun run check` before committing.\n- File naming: prefer kebab-case files (for example `database-setup.ts`).\n- Symbols: `camelCase` for functions/variables, `PascalCase` for types/components.\n- Keep feature logic near domain folders (`helpers`, `utils`, `template-handlers`).\n\n## Error Handling Conventions\n\n- In CLI code, prefer `better-result` over ad-hoc `try/catch` for recoverable flows.\n- Return typed `Result<T, E>` and use `Result.ok`, `Result.err`, `Result.try`, and `Result.tryPromise`.\n- Reuse domain errors from `apps/cli/src/utils/errors.ts` (`CLIError`, `ProjectCreationError`, `UserCancelledError`) and convert thrown prompt errors at boundaries.\n\n## Template Authoring (Handlebars)\n\n- Templates live in `packages/template-generator/templates` and use helpers from `packages/template-generator/src/core/template-processor.ts` (`eq`, `ne`, `and`, `or`, `includes`).\n- For conditional ORM-specific output, use helper form with quoted values:\n  - `{{#if (eq orm \"prisma\")}}`\n  - `{{else if (eq orm \"drizzle\")}}`\n  - `{{/if}}`\n  - Example: `packages/template-generator/templates/packages/infra/alchemy.run.ts.hbs`.\n- When files must contain literal `{{ ... }}` (Vue/JSX/template syntax), escape opening braces as `\\{{` in `.hbs` files so Handlebars does not evaluate them.\n  - Example: `packages/template-generator/templates/frontend/nuxt/app/pages/index.vue.hbs`.\n\n## Testing Guidelines\n\nA test earns its place when it can fail while a user would get hurt. Tests live in three tiers, each with one job:\n\n| Tier             | Where                                      | Runs                     | Proves                                                                                                 |\n| ---------------- | ------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Contract         | `apps/cli/test/*.test.ts`, `apps/web/test` | Every PR                 | The CLI, MCP and oRPC interfaces reject bad input, write the right files and keep existing ones        |\n| Generated builds | `apps/cli/test/generated-builds.test.ts`   | Every PR and daily       | Generated projects install the latest dependencies, typecheck, build and, where a sample opts in, boot |\n| Live             | `apps/cli/live-tests`                      | Locally, before releases | Generated apps work in a browser against real databases and deployments                                |\n\n- Use `bun:test`. Reuse `apps/cli/test/setup.ts` for disposable project directories.\n- Never assert that generated output contains text copied from a template. The generated-builds tier already proves templates compile and run.\n- Do not add isolated unit tests or mocked helper tests.\n- To cover a new stack, add a sample to `apps/cli/test/generated-builds/samples.ts`. If it needs a runtime check, name it in the sample's `checks` and implement it in `probes.ts`.\n- When an upstream release breaks a generated build, fix the template so it works on the latest version. Never pin an older dependency.\n- Keep live tests out of CI. Record their results in the pull request, not in the repository.\n\n## Commit & Pull Request Guidelines\n\n- Use Conventional Commits with scope, matching history:\n  - `feat(cli): ...`, `fix(web): ...`, `docs(cli): ...`\n- Open an issue/discussion before major feature work.\n- PRs should include:\n  - clear summary,\n  - linked issue (if applicable),\n  - verification steps run (`bun run check`, relevant tests),\n  - screenshots/GIFs for web UI changes.\n\n## Agent skills\n\n### Issue tracker\n\nIssues are tracked in GitHub Issues for `AmanVarshney01/create-better-t-stack` using the `gh` CLI.\n\n### Triage labels\n\nThe canonical triage roles map directly to same-named GitHub labels.\n\n<!-- File: plugin/skills/add-to-project/SKILL.md (Tokens: ~846 | Category: anthropic-skill) -->\n---\nname: add-to-project\ndescription: Add addons, tooling or a workspace package to an existing Better-T-Stack project, such as PWA, Tauri, Starlight or Fumadocs docs, Biome, Oxlint, Ultracite, Husky, Lefthook, Turborepo, Nx, the MCP or Skills addon, or a shared `packages/<name>`. Use when the project has a `bts.jsonc` file and the user wants to extend it or add tooling.\nmetadata:\n  priority: 7\n  docs:\n    - \"https://better-t-stack.dev/docs\"\n  pathPatterns:\n    - \"bts.jsonc\"\n---\n\n# Add to an existing Better-T-Stack project\n\nAdd tooling to a Better-T-Stack project with its `add` flow instead of wiring it by hand. For a new project, use the **scaffold-project** skill.\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` flow reads it to detect the stack and updates it afterwards.\n\n## Pick the interface\n\n- `bts_add_addons` tool: the local MCP server.\n- A shell: the CLI's `add-json`.\n- Neither: give the user the command `bunx create-better-t-stack@latest add --addons <names>`, using the project's package runner.\n\nThe hosted MCP server can't change an existing project.\n\n## Steps\n\n1. **Read `bts.jsonc`.** It tells you the current stack. If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand.\n2. **Check nested options.** Some addons take options in `addonOptions`: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. Get their shape from `bts_get_schema` or `npx create-better-t-stack@latest schema --name addonOptions`.\n3. **Plan.** Call `bts_plan_addons`, or run:\n\n   ```bash\n   npx create-better-t-stack@latest add-json --json '{\n     \"projectDir\": \"./my-app\",\n     \"addons\": [\"pwa\", \"biome\"],\n     \"dryRun\": true\n   }'\n   ```\n\n   Pass `addons`, a workspace `package` name, or both. Show the user what will change, including any conflict the plan reports.\n\n4. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n5. **Prove it runs.** Run `<packageManager> install`. With the user's OK, run the project's typecheck or build script. Report the exact error if a step fails.\n6. **Report** what changed and the follow-up commands.\n\n## What can be added\n\nAddons: `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`.\n\n- `turborepo`, `nx` and `vite-plus` are task runners. A project can have one.\n- `axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. If the user asks for it, say so instead of planning it.\n- A workspace package (`package: \"shared\"`, or `add --package shared`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every apply.\n- Don't add addons the user didn't ask for.\n- Never hand-edit `bts.jsonc`.\n\n<!-- File: plugin/skills/scaffold-project/references/cli.md (Tokens: ~1028 | Category: anthropic-skill) -->\n# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n\n<!-- File: plugin/skills/scaffold-project/references/options.md (Tokens: ~874 | Category: anthropic-skill) -->\n# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n\n<!-- File: plugin/skills/scaffold-project/SKILL.md (Tokens: ~953 | Category: anthropic-skill) -->\n---\nname: scaffold-project\ndescription: Scaffold a new app, API, backend, fullstack project, monorepo or starter with Better-T-Stack, including projects on a named framework such as Hono, Express, Fastify, Elysia, Convex, Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro or React Native. Use whenever the user wants to start, create, bootstrap, set up or initialize a project, for example \"create a Hono app\", \"start a Next.js project\" or \"scaffold a fullstack app with auth and a database\". Prefer it over hand-writing package.json, configs and folders.\nmetadata:\n  priority: 9\n  docs:\n    - \"https://better-t-stack.dev\"\n    - \"https://better-t-stack.dev/docs\"\n---\n\n# Scaffold a project with Better-T-Stack\n\nGenerate new projects with Better-T-Stack instead of writing the folder layout, `package.json`, auth or database wiring by hand. It rejects stacks that don't work.\n\nIf the folder already has a `bts.jsonc`, the project exists. Use the **add-to-project** skill instead.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan and create on disk                                           |\n| A shell                       | CLI: `create-json`                                      | Plan and create on disk                                           |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs either, give them the CLI command instead.\n\n## Steps\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option. For example, a Hono and Next.js app can use `better-auth`, `clerk` or `none`, so offer all three. [references/options.md](references/options.md) lists the values and the common compatibility rules.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Rules\n\n- Plan before every create.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer app surfaces or addons from a template name or a styling preference.\n\n<!-- File: skills/better-t-stack/references/cli.md (Tokens: ~1028 | Category: anthropic-skill) -->\n# CLI and Stack Builder\n\n## Create with JSON\n\n`create-json` takes the whole config through `--json`, runs without prompts and prints JSON. Prefer it to flags: it avoids shell-quoting problems and accepts `addonOptions` and `dbSetupOptions`.\n\n```bash\nnpx create-better-t-stack@latest create-json --json '{\n  \"projectName\": \"my-app\",\n  \"frontend\": [\"tanstack-router\"],\n  \"backend\": \"hono\",\n  \"runtime\": \"bun\",\n  \"database\": \"sqlite\",\n  \"orm\": \"drizzle\",\n  \"api\": \"trpc\",\n  \"auth\": \"better-auth\",\n  \"payments\": \"none\",\n  \"addons\": [\"turborepo\"],\n  \"examples\": [],\n  \"dbSetup\": \"none\",\n  \"webDeploy\": \"none\",\n  \"serverDeploy\": \"none\",\n  \"packageManager\": \"bun\",\n  \"git\": true,\n  \"install\": false,\n  \"dryRun\": true\n}'\n```\n\nWith `\"dryRun\": true` it validates and writes nothing. Remove `dryRun` to create the project.\n\n## Add with JSON\n\n```bash\nnpx create-better-t-stack@latest add-json --json '{\n  \"projectDir\": \"./my-app\",\n  \"addons\": [\"pwa\", \"biome\"],\n  \"dryRun\": true\n}'\n```\n\nPass `\"package\": \"shared\"` to scaffold a workspace package as well as, or instead of, addons.\n\n## Flags, for a command the user pastes\n\n```bash\nbun create better-t-stack@latest my-app \\\n  --frontend next --backend self --runtime none \\\n  --database postgres --orm drizzle --api orpc --auth better-auth \\\n  --payments none --addons turborepo biome --examples none \\\n  --db-setup none --web-deploy none --server-deploy none \\\n  --package-manager bun --no-install\n```\n\n- Turn a boolean off with `--no-git` or `--no-install`.\n- `--dry-run` validates without writing files.\n- `--yes` accepts every default.\n- `--template mern`, `pern`, `t3` or `uniwind` starts from a preset.\n- `--directory-conflict` sets what happens when the folder exists: `merge`, `overwrite`, `increment` or `error`.\n- `pnpm create better-t-stack@latest` and `npx create-better-t-stack@latest` work the same way.\n\nTo add to an existing project: `bunx create-better-t-stack@latest add --addons pwa biome`, or `add --package shared`.\n\n## Other commands\n\n| Command                       | What it does                                                                                                            |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `schema --name <name>`        | Prints a schema as JSON. Names: `all`, `cli`, `createInput`, `addInput`, `addonOptions`, `dbSetupOptions`               |\n| `mcp`                         | Runs the local MCP server over stdio. Install it with `npx -y add-mcp@latest \"npx -y create-better-t-stack@latest mcp\"` |\n| `history`                     | Lists past projects. Takes `--limit <n>`, `--json` and `--clear`                                                        |\n| `builder`, `docs`, `sponsors` | Opens the Stack Builder, the docs or the sponsors page                                                                  |\n\n## Stack Builder link\n\nWhen nothing can run, send the user to `https://www.better-t-stack.dev/new` with the stack in the query string. The builder shows the file tree and gives them the command.\n\n| Key    | Field           | Key   | Field           |\n| ------ | --------------- | ----- | --------------- |\n| `name` | project name    | `au`  | auth            |\n| `fe-w` | web frontend    | `pay` | payments        |\n| `fe-n` | native frontend | `pm`  | package manager |\n| `rt`   | runtime         | `add` | addons          |\n| `be`   | backend         | `ex`  | examples        |\n| `api`  | API layer       | `wd`  | web deploy      |\n| `db`   | database        | `sd`  | server deploy   |\n| `orm`  | ORM             | `dbs` | database setup  |\n\nJoin several values with commas in one key: `add=turborepo,biome`. For `backend: self`, write the frontend into the value: `be=self-next`. A full link:\n\n```\nhttps://www.better-t-stack.dev/new?name=my-app&fe-w=next&be=hono&rt=bun&db=postgres&orm=drizzle&api=trpc&au=better-auth&add=turborepo,biome\n```\n\n<!-- File: skills/better-t-stack/references/options.md (Tokens: ~874 | Category: anthropic-skill) -->\n# Options and compatibility\n\nThe schema is the source of truth: `bts_get_schema`, or `npx create-better-t-stack@latest schema --name createInput`. This page lists the values at the time of writing.\n\n## Values\n\n| Field                       | Values                                                                                                                                                                                          |\n| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `frontend` (array)          | `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`, `astro`, `native-bare`, `native-uniwind`, `native-unistyles`, `none`                                    |\n| `backend`                   | `hono`, `express`, `fastify`, `elysia`, `convex`, `self`, `none`                                                                                                                                |\n| `runtime`                   | `bun`, `node`, `workers`, `none`                                                                                                                                                                |\n| `api`                       | `trpc`, `orpc`, `none`                                                                                                                                                                          |\n| `database`                  | `sqlite`, `postgres`, `mysql`, `mongodb`, `none`                                                                                                                                                |\n| `orm`                       | `drizzle`, `prisma`, `mongoose`, `none`                                                                                                                                                         |\n| `auth`                      | `better-auth`, `clerk`, `none`                                                                                                                                                                  |\n| `payments`                  | `polar`, `none`                                                                                                                                                                                 |\n| `addons` (array)            | `pwa`, `tauri`, `electrobun`, `starlight`, `fumadocs`, `biome`, `oxlint`, `ultracite`, `husky`, `lefthook`, `turborepo`, `nx`, `vite-plus`, `mcp`, `skills`, `opentui`, `wxt`, `evlog`, `axiom` |\n| `examples` (array)          | `todo`, `ai`                                                                                                                                                                                    |\n| `dbSetup`                   | `turso`, `neon`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`                                                                                          |\n| `webDeploy`, `serverDeploy` | `cloudflare`, `vercel`, `prisma`, `docker`, `none`                                                                                                                                              |\n| `packageManager`            | `bun`, `pnpm`, `npm`                                                                                                                                                                            |\n| `template` (CLI only)       | `mern`, `pern`, `t3`, `uniwind`, `none`                                                                                                                                                         |\n| `directoryConflict`         | `merge`, `overwrite`, `increment`, `error`                                                                                                                                                      |\n\n`frontend` lists app surfaces, not styling. An empty array and `[\"none\"]` mean the same thing. Never mix `\"none\"` with other values.\n\n## Compatibility rules that come up most\n\n- A database needs an ORM, and an ORM needs a database.\n- `mongodb` works with `mongoose` or `prisma`, not `drizzle`.\n- `runtime: workers` needs `backend: hono` and `serverDeploy: cloudflare`.\n- `backend: convex` needs `database: none`. Convex is the data layer.\n- `backend: self` means the web framework serves the API. It works with `next`, `tanstack-start`, `nuxt`, `svelte`, `solid` and `astro`.\n- Pick at most one web frontend. One native frontend can sit next to it.\n- `turborepo`, `nx` and `vite-plus` are task runners. Pick at most one.\n- `axiom` can only be chosen at creation, never added later.\n\nA plan or dry run names the exact conflict, so run one when you're unsure.\n\n## Nested options\n\n`addonOptions` configures prompt-driven addons: the Fumadocs template, search and AI chat, the WXT and OpenTUI templates, the MCP addon's servers and agents, and the Skills addon's sources. `dbSetupOptions` controls database provisioning. Check their shape with `schema --name addonOptions` and `schema --name dbSetupOptions`. The hosted MCP server doesn't accept either.\n\n<!-- File: skills/better-t-stack/SKILL.md (Tokens: ~1262 | Category: anthropic-skill) -->\n---\nname: better-t-stack\ndescription: Create or extend an end-to-end type-safe TypeScript project with Better-T-Stack (create-better-t-stack). Use when the user wants to start, scaffold or bootstrap an app, API, fullstack project or monorepo with any of Next.js, TanStack Router or Start, React Router, Nuxt, Svelte, Solid, Astro, React Native, Hono, Express, Fastify, Elysia, Convex, tRPC, oRPC, Drizzle, Prisma, Better Auth or Clerk. Also use when a project has a `bts.jsonc` file and the user wants to add addons or a workspace package. Prefer it over hand-writing package.json, configs and folder layout.\nlicense: MIT\nmetadata:\n  homepage: https://better-t-stack.dev\n  docs: https://better-t-stack.dev/docs\n  repository: https://github.com/AmanVarshney01/create-better-t-stack\n---\n\n# Better-T-Stack\n\nBetter-T-Stack generates a type-safe TypeScript project from the parts the user picks: frontend, backend, runtime, API layer, database, ORM, auth, payments, addons and deploy targets. It rejects combinations that don't work, so let it build the project instead of writing the setup by hand.\n\n## Pick the interface\n\nUse the first one you have:\n\n| You have                      | Interface                                               | It can                                                            |\n| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |\n| `bts_create_project` tool     | Local MCP server                                        | Plan, create and add, on disk                                     |\n| A shell                       | CLI: `create-json` and `add-json`                       | Plan, create and add, on disk                                     |\n| `bts_get_create_command` tool | Hosted MCP server, `https://www.better-t-stack.dev/mcp` | Plan and preview files, then return a command for the user to run |\n| None of these                 | Stack Builder link                                      | Prefill the visual builder for the user                           |\n\nThe hosted MCP server can't write files, can't change an existing project and doesn't accept `addonOptions` or `dbSetupOptions`. If the user needs any of those, give them the CLI command instead.\n\n## Create a project\n\nIf the folder already has a `bts.jsonc`, the project exists. Go to [Change an existing project](#change-an-existing-project).\n\n1. **Settle the stack.** If the user left out a major choice (frontend, backend or database), ask one short question or propose defaults and confirm them. Don't add app surfaces, addons, examples or database provisioning the user didn't ask for.\n2. **Get valid values from the tool, not from memory.** Call `bts_get_schema`, or run `npx create-better-t-stack@latest schema --name createInput`. When the user has to choose, offer every valid option, not a subset. [references/options.md](references/options.md) lists the values and the compatibility rules that come up most, but the schema wins if they differ.\n3. **Build a full explicit config.** Set every field. Use `\"none\"`, `[]`, `true` or `false` instead of leaving a field out.\n4. **Plan before you write.** Call `bts_plan_project`, or run `create-json` with `\"dryRun\": true`. If the plan fails, its error names the conflict. Fix the config and plan again. Show the user the planned stack and get a yes.\n5. **Create.**\n   - Local MCP server: `bts_create_project` with `install: false`.\n   - CLI: the same `create-json` payload without `dryRun`, with `install: false`.\n   - Hosted MCP server: `bts_get_create_command`. Give the user the command to run in a terminal and stop here.\n\n   Installs can outlast tool timeouts, so create with `install: false` and install as a separate step.\n\n6. **Prove it runs.** Run `<packageManager> install` in the new folder. With the user's OK, run the project's typecheck or build script from its `package.json`. If a step fails, report the exact error.\n7. **Report.** Give the stack and the next commands (`dev`, database setup such as `db:push`), taken from the generated `README.md` and `package.json`, not from memory.\n\n[references/cli.md](references/cli.md) has the full `create-json` payload, the flag form for a command the user pastes, and the Stack Builder URL keys.\n\n## Change an existing project\n\n`bts.jsonc` at the project root records the stack chosen at creation and a `reproducibleCommand` that recreates it. The `add` command reads it to detect the stack.\n\n1. **Read `bts.jsonc` first.** If it's missing, `add` can't run. Tell the user instead of recreating the file. Never edit it by hand. `add` updates it.\n2. **Plan.** Call `bts_plan_addons`, or run `add-json` with `\"dryRun\": true`. Pass `addons`, a workspace `package` name, or both. Show the user what will change.\n3. **Apply** after the user agrees: `bts_add_addons`, or `add-json` without `dryRun`.\n4. **Prove it runs** and **report**, as in steps 6 and 7 above.\n\n`axiom` can't be added later. It sets up deployment infrastructure, so it must be chosen at creation. A workspace package (`package: \"shared\"`) scaffolds `packages/shared` with a manifest, the shared tsconfig and `src/index.ts`.\n\n## Rules\n\n- Plan before every create or add.\n- Send full explicit configs to MCP tools. Never send a partial payload.\n- Never pass `--yolo`. It skips the compatibility checks.\n- Don't infer addons or app surfaces from a template name or a styling preference.\n\n<!-- File: .agents/plugins/marketplace.json (Tokens: ~98 | Category: marketplace) -->\n{\n  \"name\": \"better-t-stack\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": {\n        \"source\": \"local\",\n        \"path\": \"./plugin\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Coding\"\n    }\n  ]\n}\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~356 | Category: marketplace) -->\n{\n  \"$schema\": \"https://anthropic.com/claude-code/marketplace.schema.json\",\n  \"name\": \"better-t-stack\",\n  \"description\": \"Better-T-Stack plugin marketplace — scaffold end-to-end type-safe TypeScript projects with AI\",\n  \"owner\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"better-t-stack\",\n      \"source\": \"./plugin\",\n      \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n      \"author\": {\n        \"name\": \"Aman Varshney\",\n        \"url\": \"https://github.com/AmanVarshney01\"\n      },\n      \"homepage\": \"https://better-t-stack.dev\",\n      \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n      \"license\": \"MIT\",\n      \"category\": \"development\",\n      \"keywords\": [\n        \"better-t-stack\",\n        \"create-better-t-stack\",\n        \"scaffold\",\n        \"starter\",\n        \"boilerplate\",\n        \"typescript\",\n        \"fullstack\",\n        \"monorepo\",\n        \"turborepo\",\n        \"nx\",\n        \"nextjs\",\n        \"react\",\n        \"hono\",\n        \"trpc\",\n        \"better-auth\",\n        \"drizzle\",\n        \"tanstack\",\n        \"ai-agent\",\n        \"mcp\"\n      ]\n    }\n  ]\n}\n\n<!-- File: packages/backend/convex/README.md (Tokens: ~584 | Category: plugin-manifest) -->\n# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n\n<!-- File: packages/create-bts/README.md (Tokens: ~157 | Category: plugin-manifest) -->\n# create-bts\n\nThis is an alias package for [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack).\n\n## Usage\n\n```bash\nnpx create-bts@latest\n```\n\nor\n\n```bash\nbun create bts\n```\n\nFor full documentation, please visit [better-t-stack.dev](https://better-t-stack.dev/).\n\n## About\n\n`create-bts` is a shorter alias for the full `create-better-t-stack` command. Both packages provide the same functionality - a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects.\n\nAll functionality is provided by the main [`create-better-t-stack`](https://www.npmjs.com/package/create-better-t-stack) package.\n\n<!-- File: packages/template-generator/templates/backend/convex/packages/backend/convex/README.md (Tokens: ~584 | Category: plugin-manifest) -->\n# Welcome to your Convex functions directory!\n\nWrite your Convex functions here.\nSee https://docs.convex.dev/functions for more.\n\nA query function that takes two arguments looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { query } from \"./_generated/server\";\n\nexport const myQueryFunction = query({\n  // Validators for arguments.\n  args: {\n    first: v.number(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Read the database as many times as you need here.\n    // See https://docs.convex.dev/database/reading-data.\n    const documents = await ctx.db.query(\"tablename\").collect();\n\n    // Arguments passed from the client are properties of the args object.\n    console.log(args.first, args.second);\n\n    // Write arbitrary JavaScript here: filter, aggregate, build derived data,\n    // remove non-public properties, or create new objects.\n    return documents;\n  },\n});\n```\n\nUsing this query function in a React component looks like:\n\n```ts\nconst data = useQuery(api.myFunctions.myQueryFunction, {\n  first: 10,\n  second: \"hello\",\n});\n```\n\nA mutation function looks like:\n\n```ts\nimport { v } from \"convex/values\";\n\n// convex/myFunctions.ts\nimport { mutation } from \"./_generated/server\";\n\nexport const myMutationFunction = mutation({\n  // Validators for arguments.\n  args: {\n    first: v.string(),\n    second: v.string(),\n  },\n\n  // Function implementation.\n  handler: async (ctx, args) => {\n    // Insert or modify documents in the database here.\n    // Mutations can also read from the database like queries.\n    // See https://docs.convex.dev/database/writing-data.\n    const message = { body: args.first, author: args.second };\n    const id = await ctx.db.insert(\"messages\", message);\n\n    // Optionally, return a value from your mutation.\n    return await ctx.db.get(\"messages\", id);\n  },\n});\n```\n\nUsing this mutation function in a React component looks like:\n\n```ts\nconst mutation = useMutation(api.myFunctions.myMutationFunction);\nfunction handleButtonPress() {\n  // fire and forget, the most common way to use mutations\n  mutation({ first: \"Hello!\", second: \"me\" });\n  // OR\n  // use the result once the mutation has completed\n  mutation({ first: \"Hello!\", second: \"me\" }).then((result) => console.log(result));\n}\n```\n\nUse the Convex CLI to push your functions to a deployment. See everything\nthe Convex CLI can do by running `npx convex -h` in your project root\ndirectory. To learn more, launch the docs with `npx convex docs`.\n\n<!-- File: plugin/.claude-plugin/plugin.json (Tokens: ~256 | Category: plugin-manifest) -->\n{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills, commands, and an agent so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ]\n}\n\n<!-- File: plugin/.codex-plugin/plugin.json (Tokens: ~572 | Category: plugin-manifest) -->\n{\n  \"name\": \"better-t-stack\",\n  \"version\": \"3.48.0\",\n  \"description\": \"Let your AI scaffold and extend projects with Better-T-Stack. Bundles the create-better-t-stack MCP server plus skills so the assistant plans a valid stack and generates it instead of hand-rolling boilerplate.\",\n  \"author\": {\n    \"name\": \"Aman Varshney\",\n    \"url\": \"https://github.com/AmanVarshney01\"\n  },\n  \"homepage\": \"https://better-t-stack.dev\",\n  \"repository\": \"https://github.com/AmanVarshney01/create-better-t-stack\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"better-t-stack\",\n    \"create-better-t-stack\",\n    \"scaffold\",\n    \"starter\",\n    \"boilerplate\",\n    \"typescript\",\n    \"fullstack\",\n    \"monorepo\",\n    \"turborepo\",\n    \"nx\",\n    \"nextjs\",\n    \"react\",\n    \"hono\",\n    \"trpc\",\n    \"better-auth\",\n    \"drizzle\",\n    \"tanstack\",\n    \"ai-agent\",\n    \"mcp\"\n  ],\n  \"skills\": \"./skills/\",\n  \"mcpServers\": \"./.mcp.json\",\n  \"interface\": {\n    \"displayName\": \"Better-T-Stack\",\n    \"shortDescription\": \"Scaffold end-to-end type-safe TypeScript projects\",\n    \"longDescription\": \"Bring Better-T-Stack into Codex with skills that plan a valid stack and generate it through the official create-better-t-stack MCP server, plus an add-addons workflow for existing projects. Covers frontends (Next, TanStack, Nuxt, Svelte, Solid, Astro, React Native), backends (Hono, Express, Fastify, Elysia, Convex), databases and ORMs, auth, payments, deployment, and DB provisioning (Neon, Prisma Postgres, Supabase, Turso, PlanetScale, MongoDB Atlas, Cloudflare D1, Docker).\",\n    \"developerName\": \"Aman Varshney\",\n    \"category\": \"Coding\",\n    \"capabilities\": [\"Interactive\", \"Write\", \"MCP\"],\n    \"websiteURL\": \"https://better-t-stack.dev\",\n    \"brandColor\": \"#8839EF\",\n    \"composerIcon\": \"./assets/icon.svg\",\n    \"logo\": \"./assets/icon.svg\",\n    \"defaultPrompt\": [\n      \"Create a fullstack app with Next, Hono, Postgres + Drizzle, and Better Auth\",\n      \"Scaffold a TanStack Start project with a Neon database\",\n      \"Add PWA, Biome, and Turborepo to my Better-T-Stack project\"\n    ]\n  }\n}\n</yakaai_skills>"}