@wolfstar/create-http-framework 2.7.0 → 2.8.0-next-20261004142621

package/README.md

@@ -48,26 +48,27 @@ The CLI will guide you through the following prompts:
 
 ## Options
 
-| Flag                                 | Alias | Description                                                                |
-| ------------------------------------ | ----- | -------------------------------------------------------------------------- |
-| `--overwrite`                        |       | Overwrite the target directory if it already exists                        |
-| `--no-interactive`                   |       | Skip all prompts and use defaults / flags                                  |
-| `--interactive`                      | `-i`  | Force interactive prompts even when an AI agent is detected                |
-| `--package-manager <pm>`             |       | Choose npm, yarn, pnpm, or bun                                             |
-| `--language <lang>`                  |       | Choose TypeScript (`ts`) or JavaScript (`js`)                              |
-| `--build <tool>`                     |       | Choose `tsc6`, `tsc7`, `tsdown`, `vite`, or `vite-nitro` for TypeScript    |
-| `--lint <linter>`                    |       | Choose `none`, `eslint`, or `oxlint`                                       |
-| `--format <formatter>`               |       | Choose `none`, `prettier`, or `oxfmt`                                      |
-| `--port <number>`                    |       | Set the HTTP port (default: `3000`)                                        |
-| `--i18n` / `--no-i18n`               |       | Enable or disable `@wolfstar/plugin-i18next` scaffolding                   |
-| `--subcommands` / `--no-subcommands` |       | Enable or disable the example subcommand command                           |
-| `--testing` / `--no-testing`         |       | Enable or disable the Vitest + `@wolfstar/http-framework-test-utils` setup |
-| `--gateway` / `--no-gateway`         |       | Enable or disable `@wolfstar/plugin-gateway` scaffolding                   |
-| `--cache` / `--no-cache`             |       | Enable or disable `@wolfstar/plugin-cache` (turns `--gateway` on)          |
-| `--redis` / `--no-redis`             |       | Cache in Redis instead of memory (turns `--cache` on)                      |
-| `--sharder` / `--no-sharder`         |       | Enable or disable `@wolfstar/plugin-sharder` (turns `--gateway` on)        |
-| `--install` / `--no-install`         |       | Enable or disable dependency installation                                  |
-| `--help`                             | `-h`  | Print usage and exit                                                       |
+| Flag                                 | Alias | Description                                                                 |
+| ------------------------------------ | ----- | --------------------------------------------------------------------------- |
+| `--overwrite`                        |       | Overwrite the target directory if it already exists                         |
+| `--no-interactive`                   |       | Skip all prompts and use defaults / flags                                   |
+| `--interactive`                      | `-i`  | Force interactive prompts even when an AI agent is detected                 |
+| `--package-manager <pm>`             |       | Choose npm, yarn, pnpm, or bun                                              |
+| `--language <lang>`                  |       | Choose TypeScript (`ts`) or JavaScript (`js`)                               |
+| `--build <tool>`                     |       | Choose `tsc6`, `tsc7`, `tsdown`, `vite`, or `vite-nitro` for TypeScript     |
+| `--lint <linter>`                    |       | Choose `none`, `eslint`, or `oxlint`                                        |
+| `--format <formatter>`               |       | Choose `none`, `prettier`, or `oxfmt`                                       |
+| `--port <number>`                    |       | Set the HTTP port (default: `3000`)                                         |
+| `--i18n` / `--no-i18n`               |       | Enable or disable `@wolfstar/plugin-i18next` scaffolding                    |
+| `--subcommands` / `--no-subcommands` |       | Enable or disable the example subcommand command                            |
+| `--testing` / `--no-testing`         |       | Enable or disable the Vitest + `@wolfstar/http-framework-test-utils` setup  |
+| `--gateway` / `--no-gateway`         |       | Enable or disable `@wolfstar/plugin-gateway` scaffolding                    |
+| `--cache` / `--no-cache`             |       | Enable or disable `@wolfstar/plugin-cache` (turns `--gateway` on)           |
+| `--redis` / `--no-redis`             |       | Cache in Redis instead of memory (turns `--cache` on)                       |
+| `--sharder` / `--no-sharder`         |       | Enable or disable `@wolfstar/plugin-sharder` (turns `--gateway` on)         |
+| `--tunnel` / `--no-tunnel`           |       | Open a cloudflared quick tunnel in `stars dev` (`dev.tunnel` in the config) |
+| `--install` / `--no-install`         |       | Enable or disable dependency installation                                   |
+| `--help`                             | `-h`  | Print usage and exit                                                        |
 
 ## Non-interactive / AI agent mode
 
@@ -106,6 +107,9 @@ my-discord-bot/
 ├── vitest.setup.ts               # Vitest setup file (--testing)
 ├── compose.yaml                  # Local Redis server (--redis)
 ├── README.md                     # Generated project README
+├── AGENTS.md                     # The project's commands, layout and rules, for AI coding agents
+├── llms.txt                      # The upstream documentation by topic, for AI coding agents
+├── stars.config.ts               # The `stars` CLI configuration (build, dev, tunnel)
 ├── .env                          # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
 ├── .gitignore
 ├── package.json
@@ -117,6 +121,9 @@ my-discord-bot/
 - `src/commands/math.ts` is only generated when **Subcommands** is enabled.
 - `src/lib/cache.ts` is only generated with **Cache**, `src/shard.ts` with **Sharder**, and `compose.yaml` with **Redis**.
 - `tests/ping.test.ts`, `vitest.config.ts`, and `vitest.setup.ts` are only generated when **Testing** is enabled.
+- `AGENTS.md` and `llms.txt` are always generated and only describe the features the project was created with. When one already exists and is not this generator's own unedited output (you wrote it, or edited it), a rerun leaves it as it is and says so.
+- With a linter, the generated configuration (`.oxlintrc.json` or `eslint.config.mjs`) enables the rules of [`@wolfstar/eslint-plugin-http-framework`](../eslint-plugin-http-framework): decorator order, raw Discord fetches, dynamic translation keys and the other mistakes TypeScript cannot catch.
+- `--tunnel` (or the **Dev tunnel** feature in the prompt) writes `dev: { tunnel: true }` to `stars.config`, so `stars dev` opens a cloudflared quick tunnel and Discord reaches the bot on your machine. Without it, press `t` in `stars dev` to open one on demand.
 
 ### Vite and Nitro
 

package/dist/index.js

@@ -145,6 +145,7 @@ async function fetchDependencyVersions(selections) {
 		names.add(selections.language === "ts" ? "typescript-eslint" : "@eslint/js");
 	}
 	if (selections.linter === "oxlint") names.add("oxlint");
+	if (selections.linter !== "none") names.add("@wolfstar/eslint-plugin-http-framework");
 	if (selections.formatter === "prettier") names.add("prettier");
 	if (selections.formatter === "oxfmt") names.add("oxfmt");
 	const list = [...names];
@@ -219,6 +220,17 @@ function runCommand(command, args, dir) {
 //#endregion
 //#region src/tools/projectFiles.ts
 const caret = (version) => `^${version}`;
+const FRAMEWORK_LINT_PLUGIN = "@wolfstar/eslint-plugin-http-framework";
+/** The rules of {@link FRAMEWORK_LINT_PLUGIN}, listed for oxlint, whose JSON configuration cannot import them. */
+const FRAMEWORK_LINT_RULES = [
+	"wolfstar/apply-options-decorator-order",
+	"wolfstar/require-subcommand-parent",
+	"wolfstar/no-raw-discord-fetch",
+	"wolfstar/no-dynamic-translation-key",
+	"wolfstar/prefer-apply-localized-builder",
+	"wolfstar/no-hoisted-plugin-register-import",
+	"wolfstar/no-deprecated-i18n-package"
+];
 function sortKeys(record) {
 	return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
 }
@@ -300,6 +312,7 @@ function buildDevDependencies(ctx) {
 		if (ctx.language === "ts") dev["typescript-eslint"] = caret(v["typescript-eslint"]);
 		else dev["@eslint/js"] = caret(v["@eslint/js"]);
 	} else if (ctx.linter === "oxlint") dev["oxlint"] = caret(v["oxlint"]);
+	if (ctx.linter !== "none") dev[FRAMEWORK_LINT_PLUGIN] = caret(v[FRAMEWORK_LINT_PLUGIN]);
 	if (ctx.formatter === "prettier") dev["prettier"] = caret(v["prettier"]);
 	else if (ctx.formatter === "oxfmt") dev["oxfmt"] = caret(v["oxfmt"]);
 	if (ctx.i18n) dev["@wolfstar/i18next-type-generator"] = caret(v["@wolfstar/i18next-type-generator"]);
@@ -389,12 +402,16 @@ function writeTsconfig(targetDir, ctx) {
 */
 function writeStarsConfig(targetDir, ctx) {
 	const isJs = ctx.language === "js";
-	let options = !isJs && (ctx.buildTool === "tsc6" || ctx.buildTool === "tsc7") ? "{ build: { tool: 'tsc' }, env: false }" : isJs ? "{ env: false }" : "{}";
-	if (!isJs && isViteBuild(ctx.buildTool)) options = `{ build: { tool: 'vite' }, experimental: { enableVite: true${isNitroBuild(ctx.buildTool) ? ", enableNitro: true, nitro: { preset: 'node-server' }" : ""} } }`;
+	const parts = !isJs && (ctx.buildTool === "tsc6" || ctx.buildTool === "tsc7") ? ["build: { tool: 'tsc' }", "env: false"] : isJs ? ["env: false"] : [];
+	if (!isJs && isViteBuild(ctx.buildTool)) {
+		const nitro = isNitroBuild(ctx.buildTool) ? ", enableNitro: true, nitro: { preset: 'node-server' }" : "";
+		parts.push("build: { tool: 'vite' }", `experimental: { enableVite: true${nitro} }`);
+	}
+	if (ctx.tunnel) parts.push("dev: { tunnel: true }");
 	const content = [
 		"import { defineConfig } from '@wolfstar/http-framework/config';",
 		"",
-		`export default defineConfig(${options});`,
+		`export default defineConfig(${parts.length > 0 ? `{ ${parts.join(", ")} }` : "{}"});`,
 		""
 	].join("\n");
 	writeFile(join(targetDir, isJs ? "stars.config.js" : "stars.config.ts"), content);
@@ -403,27 +420,33 @@ function writeLinterConfig(targetDir, ctx) {
 	if (ctx.linter === "oxlint") writeFile(join(targetDir, ".oxlintrc.json"), json({
 		$schema: "./node_modules/oxlint/configuration_schema.json",
 		...ctx.language === "ts" ? { plugins: ["typescript"] } : {},
+		jsPlugins: [FRAMEWORK_LINT_PLUGIN],
 		categories: {
 			correctness: "error",
 			suspicious: "warn"
 		},
+		rules: Object.fromEntries(FRAMEWORK_LINT_RULES.map((rule) => [rule, "error"])),
 		ignorePatterns: ["dist/**", "node_modules/**"]
 	}));
 	else if (ctx.linter === "eslint") {
 		const content = ctx.language === "ts" ? [
+			`import wolfstar, { recommendedRules } from '${FRAMEWORK_LINT_PLUGIN}';`,
 			"import tseslint from 'typescript-eslint';",
 			"",
 			"export default tseslint.config(",
 			"	{ ignores: ['dist/**'] },",
-			"	...tseslint.configs.recommended",
+			"	...tseslint.configs.recommended,",
+			"	{ plugins: { wolfstar }, rules: recommendedRules }",
 			");",
 			""
 		].join("\n") : [
 			"import js from '@eslint/js';",
+			`import wolfstar, { recommendedRules } from '${FRAMEWORK_LINT_PLUGIN}';`,
 			"",
 			"export default [",
 			"	{ ignores: ['dist/**'] },",
-			"	js.configs.recommended",
+			"	js.configs.recommended,",
+			"	{ plugins: { wolfstar }, rules: recommendedRules }",
 			"];",
 			""
 		].join("\n");
@@ -497,6 +520,12 @@ function removeI18nDeclaration(outputDir) {
 	if (existsSync(typesDir) && readdirSync(typesDir).length === 0) rmSync(typesDir, { recursive: true });
 }
 /**
+* The files that describe a project to coding agents. A project often has its own already, and unlike the sources
+* they are prose a rerun cannot merge: an existing one is only replaced when this generator wrote it and nobody
+* edited it since.
+*/
+const AGENT_DOCS = /* @__PURE__ */ new Set(["AGENTS.md", "llms.txt"]);
+/**
 * What the Handlebars sources see: the persisted {@link TemplateContext} plus values derived from it. Deriving at render
 * time keeps the manifest small and lets manifests written before these fields existed still render.
 */
@@ -516,8 +545,10 @@ function toRenderContext(context) {
 	});
 	return {
 		...context,
+		typescript,
 		vite: typescript && isViteBuild(context.buildTool),
 		nitro: typescript && isNitroBuild(context.buildTool),
+		autoImports: typescript && context.buildTool === "tsdown",
 		registersEnv: Boolean(context.autoEnv) && typescript && (context.buildTool === "tsdown" || context.buildTool === "vite"),
 		commands
 	};
@@ -694,7 +725,7 @@ function removeStaleGeneratedFiles(outputDir, context) {
 * - Non-`.hbs` files (e.g. static locale JSON under a feature's `src/locales/**`) are copied verbatim —
 *   no extension stripped, no Handlebars compilation.
 */
-function processDir(root, outputDir, context) {
+function processDir(root, outputDir, context, keep) {
 	for (const absoluteSource of walkDir(root)) {
 		const outputRelative = toOutputRelative(root, absoluteSource, context.language);
 		if (outputRelative === null) continue;
@@ -702,6 +733,7 @@ function processDir(root, outputDir, context) {
 		const isHandlebars = absoluteSource.endsWith(".hbs");
 		const outputPath = join(outputDir, outputRelative);
 		const content = isHandlebars ? Handlebars.compile(rawContent)(toRenderContext(context)) : rawContent;
+		if (keep?.(outputRelative, content)) continue;
 		writeFile(outputPath, content);
 	}
 }
@@ -710,13 +742,25 @@ function processDir(root, outputDir, context) {
 * {@link resolveFeatureDirs} on top, in order — feature files overwrite base files at the same
 * output-relative path (e.g. `features/i18n/src/main.ts.hbs` overwrites `base/src/main.ts.hbs`).
 *
+* @param onKept Called with each of `AGENTS.md`/`llms.txt` that was left as it is, because it exists and is not this
+* generator's own unedited output.
 * @returns Output-relative paths that looked stale (belong to a disabled feature or the other
 * language) but were left in place because they'd been hand-edited since the last run.
 */
-async function processTemplate(outputDir, context) {
+async function processTemplate(outputDir, context, onKept) {
+	const manifestContext = readManifest(outputDir);
 	const preserved = removeStaleGeneratedFiles(outputDir, context);
 	if (!context.i18n) removeI18nDeclaration(outputDir);
-	processDir(baseDir, outputDir, context);
+	processDir(baseDir, outputDir, context, (outputRelative, content) => {
+		if (!AGENT_DOCS.has(outputRelative)) return false;
+		const target = join(outputDir, outputRelative);
+		if (!existsSync(target)) return false;
+		const actual = readFileSync(target, "utf-8");
+		const source = join(baseDir, `${outputRelative}.hbs`);
+		const pristine = actual === content || manifestContext !== void 0 && renderSource(source, manifestContext) === actual;
+		if (!pristine) onKept?.(outputRelative);
+		return !pristine;
+	});
 	for (const feature of resolveFeatureDirs(context)) processDir(join(featuresDir, feature), outputDir, context);
 	writeManifest(outputDir, context);
 	return preserved;
@@ -752,6 +796,7 @@ Options:
   --cache / --no-cache         Toggle @wolfstar/plugin-cache, the gateway entity cache (default: off; enables --gateway)
   --redis / --no-redis         Store the cache in Redis instead of memory (default: off; enables --cache)
   --sharder / --no-sharder     Toggle @wolfstar/plugin-sharder, gateway shards across cluster workers (default: off; enables --gateway)
+  --tunnel / --no-tunnel       Open a cloudflared quick tunnel in \`stars dev\`, so Discord reaches the bot (default: off)
   --install / --no-install     Toggle dependency installation (default: on)
   --ignore                     Write into an existing, non-empty directory without clearing it
   --help, -h                   Print this message and exit
@@ -810,6 +855,7 @@ async function main() {
 	const cliCache = argv["cache"];
 	const cliRedis = argv["redis"];
 	const cliSharder = argv["sharder"];
+	const cliTunnel = argv["tunnel"];
 	const cliInstall = argv["install"];
 	const { isAgent, agent } = await determineAgent();
 	const agentMode = isAgent && flagInteractive !== true;
@@ -1037,6 +1083,7 @@ async function main() {
 	let wantsCache;
 	let wantsRedis;
 	let wantsSharder;
+	let wantsTunnel;
 	const nitro = language === "ts" && isNitroBuild(buildTool);
 	if (nonInteractive) {
 		wantsI18n = cliI18n ?? false;
@@ -1047,6 +1094,7 @@ async function main() {
 		wantsCache = cliCache ?? false;
 		wantsRedis = cliRedis ?? false;
 		wantsSharder = cliSharder ?? false;
+		wantsTunnel = cliTunnel ?? false;
 	} else {
 		const featuresResult = await multiselect({
 			message: "Which optional features would you like to add?",
@@ -1078,9 +1126,13 @@ async function main() {
 				...nitro ? [] : [{
 					value: "sharder",
 					label: "Gateway sharding across cluster workers (@wolfstar/plugin-sharder)"
-				}]
+				}],
+				{
+					value: "tunnel",
+					label: "Dev tunnel (a cloudflared quick tunnel, so Discord reaches the bot while developing)"
+				}
 			],
-			initialValues: [],
+			initialValues: cliTunnel ? ["tunnel"] : [],
 			required: false
 		});
 		if (isCancel(featuresResult)) {
@@ -1095,6 +1147,7 @@ async function main() {
 		wantsGateway = features.has("gateway");
 		wantsCache = features.has("cache");
 		wantsSharder = features.has("sharder");
+		wantsTunnel = features.has("tunnel");
 		wantsRedis = cliRedis ?? false;
 		if (wantsCache && cliRedis === void 0) {
 			const redisResult = await confirm({
@@ -1155,6 +1208,7 @@ async function main() {
 	});
 	s.stop("Versions fetched.");
 	s.start("Generating project files...");
+	const keptDocs = [];
 	const preservedFiles = await processTemplate(targetDir, {
 		name: projectName,
 		port,
@@ -1168,8 +1222,9 @@ async function main() {
 		redis: wantsRedis,
 		sharder: wantsSharder,
 		buildTool,
+		tunnel: wantsTunnel,
 		autoEnv: true
-	});
+	}, (path) => keptDocs.push(path));
 	writeProjectFiles(targetDir, {
 		name: projectName,
 		port,
@@ -1181,6 +1236,7 @@ async function main() {
 		cache: wantsCache,
 		redis: wantsRedis,
 		sharder: wantsSharder,
+		tunnel: wantsTunnel,
 		packageManager,
 		language,
 		buildTool,
@@ -1189,6 +1245,7 @@ async function main() {
 		versions
 	});
 	s.stop("Project files generated.");
+	for (const file of keptDocs) log.warn(`Kept your existing "${file}" as it is — delete it and run again to get the generated one.`);
 	for (const file of preservedFiles) log.warn(`Kept hand-edited "${file}" even though its feature is now disabled — remove it manually if it's no longer needed.`);
 	if (wantsI18n) try {
 		s.start("Generating i18n types...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolfstar/create-http-framework",
-  "version": "2.7.0",
+  "version": "2.8.0-next-20261004142621",
   "description": "Create a new WolfStar HTTP Framework bot project",
   "keywords": [
     "cli",

package/template/base/AGENTS.md.hbs

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in `{{name}}`, a Discord bot built with
+[`@wolfstar/http-framework`](https://www.npmjs.com/package/@wolfstar/http-framework). It receives interactions over
+HTTP{{#if gateway}} and gateway events over a WebSocket (`@wolfstar/plugin-gateway`){{/if}}.
+
+## Commands
+
+- `npm run dev` — build, run and restart the bot on changes (`stars dev`). Add `-- --no-tui` for plain line output,
+  which is what a non-interactive shell gets anyway.
+{{#if typescript}}
+- `npm run build` — build once (`stars build`).
+{{/if}}
+- `npm start` — run the built bot.
+- `npx stars doctor` — check the runtime, the credentials and the generated files. Run it first when something is off.
+- `npx stars info --json` — the resolved configuration.
+- `npx stars commands diff` — what a deploy would change on Discord. `npx stars commands deploy --yes` deploys.
+{{#if i18n}}
+- `npm run generate:i18n` — regenerate the i18next types after editing `src/locales/`.
+{{/if}}
+{{#if testing}}
+- `npm test` — run the tests (vitest).
+{{/if}}
+
+## Layout
+
+- `src/main.*` — the entry: creates the client, loads the pieces, starts listening.
+- `src/commands/` — one file per application command. A command registers its own builder
+  (`@RegisterCommand(...)` or `registerApplicationCommands`) and answers in `chatInputRun`.
+- `src/interaction-handlers/` — buttons, select menus and modals, matched by custom id.
+- `src/listeners/` — client event listeners.
+- `src/lib/` — shared code{{#if autoImports}}, auto-imported by `stars` (see `.stars/imports.d.ts`){{else}}; import what you use, nothing is auto-imported{{/if}}.
+{{#if i18n}}
+- `src/locales/<locale>/` — translations. Keys are typed: never build a key from a variable.
+{{/if}}
+- `stars.config.*` — the only build and dev configuration. There is no separate bundler config.
+- `.stars/` — generated by `stars prepare`. Never edit it, and do not commit it.
+
+{{#if vite}}
+The project is bundled into one file, so there is no `commands` directory at runtime: import every new piece in
+`src/main.*` and load it with `container.stores.loadPiece`.
+
+{{/if}}
+## Rules
+
+- Secrets live in `.env` (`DISCORD_TOKEN`, `DISCORD_PUBLIC_KEY`, `DISCORD_CLIENT_ID`). Never print or commit them.
+- Call Discord through `container.rest`, not `fetch`: it handles rate limits and authentication.
+- An interaction must be answered within 3 seconds: `reply()`, or `defer()` first and `edit()` later. `edit()` before
+  either one fails.
+{{#if tunnel}}
+- `stars dev` opens a public cloudflared tunnel to the bot (`dev.tunnel` in `stars.config`). Its URL changes on every
+  run; it is the application's interactions endpoint only while the session lasts.
+{{/if}}
+- Changing a command's builder (name, description, options) changes what Discord has to be told. `stars dev` asks
+  before it redeploys; outside it, use `stars commands deploy`.
+- Do not start a long-running `npm run dev` to check a change: build{{#if testing}} and run the tests{{/if}} instead.
+
+## Reference
+
+- Framework and CLI documentation: <https://github.com/wolfstar-project/stars-components>
+- `llms.txt` in this directory lists the documentation by topic.

package/template/base/README.md.hbs

@@ -2,6 +2,8 @@
 
 A Discord bot built with [`@wolfstar/http-framework`](https://www.npmjs.com/package/@wolfstar/http-framework), an HTTP-interactions framework for Discord bots.
 
+`AGENTS.md` and `llms.txt` describe the project to AI coding agents: its commands, its layout and the rules that are easy to get wrong.
+
 ## Setup
 
 1. Install dependencies (skip this if the generator already installed them for you).
@@ -40,14 +42,22 @@ The project is bundled with [Vite](https://vite.dev) into a single file, so the
 
 The `dev` and `build` scripts are powered by the [`stars`](https://www.npmjs.com/package/@wolfstar/cli) CLI and read the `stars.config` file at the project root.
 
-- `npm run dev` — build, run and restart the bot on changes, with an interactive terminal UI (`npm run dev -- --no-tui` for plain logs).
+- `npm run dev` — build, run and restart the bot on changes, with an interactive terminal dashboard: status, log channels and levels you can filter, and a prompt before changed commands are redeployed (`npm run dev -- --no-tui` for plain logs).
 - `npm run build` — {{#if nitro}}build the deployable `.output/` directory{{else}}compile the project{{/if}} (TypeScript projects only).
 - `npm start` — run the bot.
 - `npx stars info` — print the resolved configuration.
+- `npx stars doctor` — check the runtime, the credentials, the interactions endpoint and the generated files.
+- `npx stars commands diff` / `npx stars commands deploy` — compare the commands the bot defines with the ones Discord has, and deploy them.
 {{#if testing}}
 - `npm test` — run the test suite with vitest.
 {{/if}}
 
+{{#if tunnel}}
+## Tunnel
+
+`stars dev` opens a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel (`dev.tunnel` in `stars.config`), so Discord can reach the bot on your machine. Its URL changes on every run: paste it as the **Interactions Endpoint URL** of the application, or set `dev: { tunnel: { updateEndpoint: true } }` to let `stars dev` do it. Press `t` in the dev UI to close or reopen it.
+
+{{/if}}
 ## Commands
 
 - `/ping` — replies with `Pong!`.

package/template/base/llms.txt.hbs

@@ -0,0 +1,39 @@
+# {{name}}
+
+> A Discord bot built with @wolfstar/http-framework: HTTP interactions{{#if gateway}} and gateway events{{/if}}, built and run with the `stars` CLI.
+
+Start with `AGENTS.md` for this project's commands, layout and rules. The links below are the upstream documentation.
+
+## Framework
+
+- [@wolfstar/http-framework](https://github.com/wolfstar-project/stars-components/tree/main/packages/http-framework#readme): the client, commands, interaction handlers, listeners, plugins
+- [@wolfstar/decorators](https://github.com/wolfstar-project/stars-components/tree/main/packages/decorators#readme): `ApplyOptions`, permission and context preconditions
+- [@wolfstar/env-utilities](https://github.com/wolfstar-project/stars-components/tree/main/packages/env-utilities#readme): typed environment variables
+
+## CLI
+
+- [@wolfstar/cli](https://github.com/wolfstar-project/stars-components/tree/main/packages/cli#readme): `stars dev`, `build`, `prepare`, `info`, `doctor`, `commands`, `codegen`, `completions`, and every `stars.config` option
+{{#if i18n}}
+
+## Internationalisation
+
+- [@wolfstar/plugin-i18next](https://www.npmjs.com/package/@wolfstar/plugin-i18next): the i18next plugin
+- [@wolfstar/i18next-type-generator](https://github.com/wolfstar-project/stars-components/tree/main/packages/i18next-type-generator#readme): typed translation keys
+{{/if}}
+{{#if gateway}}
+
+## Gateway
+
+- [@wolfstar/plugin-gateway](https://www.npmjs.com/package/@wolfstar/plugin-gateway): gateway events next to HTTP interactions
+{{#if cache}}
+- [@wolfstar/plugin-cache](https://www.npmjs.com/package/@wolfstar/plugin-cache): the gateway entity cache
+{{/if}}
+{{#if sharder}}
+- [@wolfstar/plugin-sharder](https://www.npmjs.com/package/@wolfstar/plugin-sharder): shards across cluster workers
+{{/if}}
+{{/if}}
+
+## Discord
+
+- [Receiving and responding to interactions](https://discord.com/developers/docs/interactions/receiving-and-responding)
+- [Application commands](https://discord.com/developers/docs/interactions/application-commands)