@nectar-js/nectar 0.1.0 → 0.3.0

package/dist/{cli-Ce-ZUj6M.js → cli-Cv0mpiRy.js}

@@ -1,6 +1,6 @@
-import { T as version, _ as parseSegment, a as MANIFEST_FILE, b as loadModule, c as writeManifest, d as checkDeclaredRoute, f as compileComponents, g as formatSegment, i as pluginGraph, o as stableStringify, r as applyPlugins, s as toManifest, t as PluginError, v as enableModuleReloading, x as Diagnostics, y as invalidateModuleGraph } from "./plugins-CGvM19v9.js";
-import { a as checkIntents, c as configFor, i as scopeKey, n as syncCommands, r as RegistrationError, s as ConfigError, t as UnsafeSyncError, u as validateConfig } from "./registration-CaE0QBT6.js";
-import { i as createLogger, l as createSignals, n as createRuntime, r as manifestFiles, s as HandlerLoadError, t as LoginError, u as loadManifest } from "./runtime-CZJeZvSL.js";
+import { C as typeOf, D as version, S as docsUrl, _ as parseSegment, a as MANIFEST_FILE, b as loadModule, c as writeManifest, d as checkHandler, f as compileComponents, g as formatSegment, i as pluginGraph, o as stableStringify, r as applyPlugins, s as toManifest, t as PluginError, v as enableModuleReloading, x as Diagnostics, y as invalidateModuleGraph } from "./plugins-C2uwN3-D.js";
+import { a as checkIntents, c as configFor, i as scopeKey, n as syncCommands, r as RegistrationError, s as ConfigError, t as UnsafeSyncError, u as validateConfig } from "./registration-mUZJidnF.js";
+import { d as loadManifest, i as createLogger, l as createSignals, n as createRuntime, r as manifestFiles, s as HandlerLoadError, t as LoginError, u as optionsAt } from "./runtime-B7mCDO5Q.js";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, rmSync, watch, writeFileSync } from "node:fs";
@@ -27,17 +27,6 @@ const COMMAND_TYPE$1 = {
 	[ApplicationCommandType.User]: "user",
 	[ApplicationCommandType.Message]: "message"
 };
-const OPTION_TYPE$1 = {
-	[ApplicationCommandOptionType.String]: "string",
-	[ApplicationCommandOptionType.Integer]: "integer",
-	[ApplicationCommandOptionType.Number]: "number",
-	[ApplicationCommandOptionType.Boolean]: "boolean",
-	[ApplicationCommandOptionType.User]: "user",
-	[ApplicationCommandOptionType.Channel]: "channel",
-	[ApplicationCommandOptionType.Role]: "role",
-	[ApplicationCommandOptionType.Mentionable]: "mentionable",
-	[ApplicationCommandOptionType.Attachment]: "attachment"
-};
 /**
 * Renders `types.d.ts`: a module augmentation of `@nectar-js/nectar` that lists every route with
 * its parameters, options, and the context its middleware chain adds. Handler and middleware
@@ -61,7 +50,7 @@ function toTypes(graph, outDir, plugins = []) {
 	};
 	const commands = [];
 	for (const command of [...graph.commands].sort((a, b) => a.name.localeCompare(b.name))) for (const [key, route] of Object.entries(command.handlers)) {
-		const options = Object.entries(optionsAt(command.payload, key)).map(([name, type]) => `${quote(name)}: ${quote(type)}`).join("; ");
+		const options = optionsAt(command.payload, key).map((o) => `${quote(o.name)}: { type: ${quote(o.type)}; required: ${o.required} }`).join("; ");
 		commands.push(`    ${quote(route.path)}: { type: ${quote(COMMAND_TYPE$1[command.type] ?? "chatInput")}; options: {${options === "" ? "" : ` ${options} `}}; context: ${contextOf(route)} };`);
 	}
 	commands.sort();
@@ -122,17 +111,6 @@ function writeTypes(graph, outDir, plugins = []) {
 	writeFileSync(file, toTypes(graph, outDir, plugins));
 	return file;
 }
-/** Option name to option type name for one handler position of a command payload. */
-function optionsAt(payload, key) {
-	let options = payload.options;
-	for (const part of key === "" ? [] : key.split("/")) options = options?.find((o) => o.name === part)?.options;
-	const out = {};
-	for (const option of options ?? []) {
-		const type = option.type === void 0 ? void 0 : OPTION_TYPE$1[option.type];
-		if (option.name !== void 0 && type !== void 0) out[option.name] = type;
-	}
-	return out;
-}
 /** `../app/middleware.ts` becomes `../app/middleware.js`, which NodeNext resolves back to the source. */
 function importPath(fromDir, file) {
 	const mapped = path.relative(fromDir, file).split(path.sep).join("/").replace(/\.mts$/, ".mjs").replace(/\.ts$/, ".js");
@@ -162,7 +140,8 @@ async function compileAutocomplete(table, commands) {
 	const results = await Promise.all(routes.map(async (route) => {
 		const target = targets.get(route.id);
 		if (target === void 0) {
-			diagnostics.error("autocomplete-without-command", `autocomplete.ts needs a command.ts in the same directory. None was found for "${route.path}".`, {
+			if (table.routes.some((r) => r.id === route.id && r.kind === "command")) return null;
+			diagnostics.error("autocomplete-without-command", "There's no command.ts next to this autocomplete.ts. Autocomplete answers the options of the command in the same directory, so move it next to that command.ts.", {
 				file: route.file,
 				route: route.id
 			});
@@ -172,7 +151,7 @@ async function compileAutocomplete(table, commands) {
 		try {
 			module = await loadModule(route.file);
 		} catch (error) {
-			diagnostics.error("module-load-failed", `Could not import this file: ${error instanceof Error ? error.message : String(error)}`, {
+			diagnostics.error("module-load-failed", `The compiler imports every route file to read its exports, and this one threw: ${error instanceof Error ? error.message : String(error)}`, {
 				file: route.file,
 				route: route.id
 			});
@@ -182,7 +161,7 @@ async function compileAutocomplete(table, commands) {
 		let ok = true;
 		for (const name of exported) {
 			if (typeof module[name] !== "function") {
-				diagnostics.error("autocomplete-export-not-function", `Export "${name}" must be a function that answers autocomplete for the "${name}" option.`, {
+				diagnostics.error("autocomplete-export-not-function", `Export "${name}" isn't a function. Each export of autocomplete.ts is a function that answers the option with the same name.`, {
 					file: route.file,
 					route: route.id
 				});
@@ -190,7 +169,7 @@ async function compileAutocomplete(table, commands) {
 				continue;
 			}
 			if (!target.options.has(name)) {
-				diagnostics.error("autocomplete-unknown-option", `Export "${name}" does not match an option with \`autocomplete: true\` in ${relative$2(target.command.file)}. ${expected(target.options)}`, {
+				diagnostics.error("autocomplete-unknown-option", `Export "${name}" doesn't match an option with autocomplete: true in ${relative$3(target.command.file)}. ${expected(target.options)} Rename the export, or set autocomplete: true on the option.`, {
 					file: route.file,
 					route: route.id
 				});
@@ -199,7 +178,7 @@ async function compileAutocomplete(table, commands) {
 		}
 		for (const name of [...target.options].sort()) {
 			if (exported.includes(name)) continue;
-			diagnostics.error("autocomplete-missing-handler", `Option "${name}" has \`autocomplete: true\` but ${relative$2(route.file)} does not export a "${name}" function.`, {
+			diagnostics.error("autocomplete-missing-handler", `Option "${name}" has autocomplete: true, but this file doesn't export a function named "${name}" to answer it.`, {
 				file: route.file,
 				route: route.id
 			});
@@ -213,7 +192,8 @@ async function compileAutocomplete(table, commands) {
 	}));
 	for (const [id, target] of targets) {
 		if (target.options.size === 0 || routes.some((r) => r.id === id)) continue;
-		diagnostics.error("autocomplete-missing-file", `${[...target.options].map((o) => `"${o}"`).join(", ")} ${target.options.size === 1 ? "has" : "have"} \`autocomplete: true\` but there is no autocomplete.ts next to this command.`, {
+		const names = [...target.options].map((o) => `"${o}"`);
+		diagnostics.error("autocomplete-missing-file", names.length === 1 ? `Option ${names[0]} has autocomplete: true, but there's no autocomplete.ts next to this command. Add one that exports a function named ${names[0]}.` : `Options ${new Intl.ListFormat("en").format(names)} have autocomplete: true, but there's no autocomplete.ts next to this command. Add one that exports a function named after each of them.`, {
 			file: target.command.file,
 			route: id
 		});
@@ -230,9 +210,11 @@ function autocompleteOptions(command, key) {
 	return new Set((options ?? []).filter((o) => o.autocomplete === true).map((o) => o.name));
 }
 function expected(options) {
-	return options.size === 0 ? "The command declares no autocomplete options." : `Expected one of: ${[...options].sort().join(", ")}.`;
+	const names = [...options].sort().map((o) => `"${o}"`);
+	if (names.length === 0) return "That command has no autocomplete options.";
+	return names.length === 1 ? `Its autocomplete option is ${names[0]}.` : `Its autocomplete options are ${new Intl.ListFormat("en").format(names)}.`;
 }
-function relative$2(file) {
+function relative$3(file) {
 	return path.relative(process.cwd(), file).split(path.sep).join("/");
 }
 //#endregion
@@ -270,27 +252,28 @@ function validateCommandMeta(value, file, diagnostics) {
 		file
 	};
 	if (value === void 0) {
-		diagnostics.error("missing-meta", "command.ts must export a `meta` object with at least a description.", { file });
+		diagnostics.error("missing-meta", "This command.ts doesn't export meta. Discord needs a description for every slash command, so add export const meta = { description: \"...\" }. A context menu command sets type instead, like { type: \"user\" }.", { file });
 		return null;
 	}
 	if (!isRecord(value)) {
-		fail$1(ctx, "invalid-meta", "`meta` must be an object.");
+		fail$1(ctx, "invalid-meta", `meta is ${typeOf(value)}. Export an object, like { description: "..." }.`);
 		return null;
 	}
 	let ok = true;
 	const type = value.type ?? "chatInput";
-	if (typeof type !== "string" || !COMMAND_TYPES.has(type)) ok = fail$1(ctx, "invalid-meta", "`meta.type` must be \"chatInput\", \"user\", or \"message\".");
+	if (typeof type !== "string" || !COMMAND_TYPES.has(type)) ok = fail$1(ctx, "invalid-meta", `meta.type is ${JSON.stringify(type)}. Use "chatInput" for a slash command, or "user" or "message" for a context menu command.`);
 	if (value.name !== void 0) ok = checkName(ctx, value.name, "meta.name", type === "chatInput") && ok;
 	if (type === "chatInput") {
 		ok = checkDescription(ctx, value.description, "meta.description") && ok;
 		if (value.options !== void 0) ok = checkOptions(ctx, value.options) && ok;
 	} else {
-		if (value.description !== void 0 && value.description !== "") ok = fail$1(ctx, "invalid-meta", "Context menu commands cannot have a description. Remove `meta.description`.");
-		if (value.options !== void 0) ok = fail$1(ctx, "invalid-meta", "Context menu commands cannot have options.");
+		if (value.description !== void 0 && value.description !== "") ok = fail$1(ctx, "invalid-meta", "Discord doesn't allow a description on context menu commands. Remove meta.description.");
+		if (value.options !== void 0) ok = fail$1(ctx, "invalid-meta", "Discord doesn't allow options on context menu commands. Remove meta.options.");
 	}
 	ok = checkLocalizations(ctx, value.nameLocalizations, "meta.nameLocalizations") && ok;
 	ok = checkLocalizations(ctx, value.descriptionLocalizations, "meta.descriptionLocalizations") && ok;
 	ok = checkTopLevel(ctx, value) && ok;
+	if (value.defer !== void 0 && typeof value.defer !== "boolean" && value.defer !== "ephemeral") ok = fail$1(ctx, "invalid-meta", `meta.defer is ${JSON.stringify(value.defer)}. Use true to defer the reply before the handler runs, or "ephemeral" to defer it as an ephemeral reply.`);
 	return ok ? value : null;
 }
 /** Validates the `meta` export of a `route.ts` under `commands/`. */
@@ -300,11 +283,11 @@ function validateCommandRouteMeta(value, file, diagnostics) {
 		file
 	};
 	if (value === void 0) {
-		diagnostics.error("missing-meta", "route.ts must export a `meta` object with a description.", { file });
+		diagnostics.error("missing-meta", "This route.ts doesn't export meta. It holds the description Discord shows for the command or subcommand group, so add export const meta = { description: \"...\" }.", { file });
 		return null;
 	}
 	if (!isRecord(value)) {
-		fail$1(ctx, "invalid-meta", "`meta` must be an object.");
+		fail$1(ctx, "invalid-meta", `meta is ${typeOf(value)}. Export an object, like { description: "..." }.`);
 		return null;
 	}
 	let ok = checkDescription(ctx, value.description, "meta.description");
@@ -322,91 +305,105 @@ function fail$1(ctx, code, message) {
 	ctx.diagnostics.error(code, message, { file: ctx.file });
 	return false;
 }
+/** What a text field holds, for length errors: `empty`, `140 characters`, or its type. */
+function sizeOf(value) {
+	if (typeof value !== "string") return typeOf(value);
+	return value === "" ? "empty" : `${value.length} characters`;
+}
 function checkName(ctx, name, label, chatInput) {
-	if (typeof name !== "string" || name.length === 0 || name.length > 32) return fail$1(ctx, "invalid-name", `${label} must be a string of 1 to 32 characters.`);
+	if (typeof name !== "string" || name.length === 0 || name.length > 32) return fail$1(ctx, "invalid-name", `${label} is ${sizeOf(name)}. Discord needs a name of 1 to 32 characters.`);
 	if (chatInput) {
-		if (!COMMAND_NAME.test(name) || name !== name.toLowerCase()) return fail$1(ctx, "invalid-name", `${label} "${name}" is not a valid chat input command name. Discord requires lowercase letters, digits, hyphens, and underscores.`);
+		if (!COMMAND_NAME.test(name) || name !== name.toLowerCase()) return fail$1(ctx, "invalid-name", `${label} is "${name}". Discord only allows lowercase letters, digits, hyphens, and underscores in slash command and option names.`);
 	}
 	return true;
 }
 function checkDescription(ctx, description, label) {
-	if (typeof description !== "string" || description.length === 0 || description.length > 100) return fail$1(ctx, "invalid-description", `${label} must be a string of 1 to 100 characters.`);
+	if (typeof description !== "string" || description.length === 0 || description.length > 100) return fail$1(ctx, "invalid-description", `${label} is ${sizeOf(description)}. Discord needs a description of 1 to 100 characters.`);
 	return true;
 }
 function checkLocalizations(ctx, value, label) {
 	if (value === void 0) return true;
-	if (!isRecord(value)) return fail$1(ctx, "invalid-meta", `${label} must be an object of locale to string.`);
-	for (const [locale, text] of Object.entries(value)) if (typeof text !== "string") return fail$1(ctx, "invalid-meta", `${label}.${locale} must be a string.`);
+	if (!isRecord(value)) return fail$1(ctx, "invalid-meta", `${label} is ${typeOf(value)}. Use an object of locale to text, like { fr: "..." }.`);
+	for (const [locale, text] of Object.entries(value)) if (typeof text !== "string") return fail$1(ctx, "invalid-meta", `${label}.${locale} is ${typeOf(text)}, not a string.`);
 	return true;
 }
 function checkTopLevel(ctx, value) {
 	let ok = true;
 	const perms = value.defaultMemberPermissions;
-	if (perms !== void 0 && perms !== null && typeof perms !== "bigint" && typeof perms !== "string" && typeof perms !== "number") ok = fail$1(ctx, "invalid-meta", "`meta.defaultMemberPermissions` must be a permission bitfield (bigint, string, or number) or null.");
-	if (value.nsfw !== void 0 && typeof value.nsfw !== "boolean") ok = fail$1(ctx, "invalid-meta", "`meta.nsfw` must be a boolean.");
-	ok = checkEnumArray(ctx, value.contexts, "meta.contexts", [
+	if (perms !== void 0 && perms !== null && typeof perms !== "bigint" && typeof perms !== "string" && typeof perms !== "number") ok = fail$1(ctx, "invalid-meta", `meta.defaultMemberPermissions is ${typeOf(perms)}. Use a permission bitfield, like PermissionFlagsBits.BanMembers from discord.js, or null.`);
+	if (value.nsfw !== void 0 && typeof value.nsfw !== "boolean") ok = fail$1(ctx, "invalid-meta", `meta.nsfw is ${typeOf(value.nsfw)}. Use true or false.`);
+	ok = checkEnumArray(ctx, value.contexts, "meta.contexts", "InteractionContextType", [
 		0,
 		1,
 		2
 	]) && ok;
-	ok = checkEnumArray(ctx, value.integrationTypes, "meta.integrationTypes", [0, 1]) && ok;
+	ok = checkEnumArray(ctx, value.integrationTypes, "meta.integrationTypes", "ApplicationIntegrationType", [0, 1]) && ok;
 	return ok;
 }
-function checkEnumArray(ctx, value, label, allowed) {
+function checkEnumArray(ctx, value, label, enumName, allowed) {
 	if (value === void 0) return true;
-	if (!Array.isArray(value) || value.some((v) => !allowed.includes(v))) return fail$1(ctx, "invalid-meta", `${label} must be an array of ${allowed.join(", ")}. Use the discord.js enum values.`);
+	if (!Array.isArray(value) || value.some((v) => !allowed.includes(v))) return fail$1(ctx, "invalid-meta", `${label} has to be an array of ${enumName} values from discord.js.`);
 	return true;
 }
 function checkOptions(ctx, options) {
-	if (!Array.isArray(options)) return fail$1(ctx, "invalid-option", "`meta.options` must be an array.");
-	if (options.length > 25) return fail$1(ctx, "invalid-option", "A command can have at most 25 options.");
+	if (!Array.isArray(options)) return fail$1(ctx, "invalid-option", `meta.options is ${typeOf(options)}, not an array.`);
+	if (options.length > 25) return fail$1(ctx, "invalid-option", `meta.options has ${options.length} options. Discord allows 25 per command.`);
 	let ok = true;
 	const names = /* @__PURE__ */ new Set();
 	let seenOptional = false;
 	for (const [index, option] of options.entries()) {
 		const label = `meta.options[${index}]`;
 		if (!isRecord(option)) {
-			ok = fail$1(ctx, "invalid-option", `${label} must be an object.`);
+			ok = fail$1(ctx, "invalid-option", `${label} is ${typeOf(option)}, not an object.`);
 			continue;
 		}
 		const typedOk = checkOption(ctx, option, label);
 		ok = typedOk && ok;
 		if (!typedOk) continue;
 		const typed = option;
-		if (names.has(typed.name)) ok = fail$1(ctx, "invalid-option", `${label}: option name "${typed.name}" is used twice.`);
+		if (names.has(typed.name)) ok = fail$1(ctx, "invalid-option", `${label} reuses the name "${typed.name}". Discord needs option names to be unique within a command.`);
 		names.add(typed.name);
 		if (typed.required) {
-			if (seenOptional) ok = fail$1(ctx, "invalid-option", `${label}: required option "${typed.name}" comes after an optional one. Discord requires all required options first.`);
+			if (seenOptional) ok = fail$1(ctx, "invalid-option", `${label}, "${typed.name}", is required but comes after an optional option. Discord needs required options first, so move it up.`);
 		} else seenOptional = true;
 	}
 	return ok;
 }
+/** The option types each type-specific field works on. */
+const FIELD_TYPES = {
+	choices: [
+		"string",
+		"integer",
+		"number"
+	],
+	autocomplete: [
+		"string",
+		"integer",
+		"number"
+	],
+	minLength: ["string"],
+	maxLength: ["string"],
+	minValue: ["integer", "number"],
+	maxValue: ["integer", "number"],
+	channelTypes: ["channel"]
+};
+const quoted = (items, type) => new Intl.ListFormat("en", { type }).format([...items].map((item) => `"${item}"`));
 function checkOption(ctx, option, label) {
 	let ok = true;
-	if (typeof option.type !== "string" || !OPTION_TYPES.has(option.type)) return fail$1(ctx, "invalid-option", `${label}.type must be one of ${[...OPTION_TYPES].map((t) => `"${t}"`).join(", ")}.`);
+	if (typeof option.type !== "string" || !OPTION_TYPES.has(option.type)) return fail$1(ctx, "invalid-option", `${label}.type is ${option.type === void 0 ? "missing" : JSON.stringify(option.type)}. Use ${quoted(OPTION_TYPES, "disjunction")}.`);
 	ok = checkName(ctx, option.name, `${label}.name`, true) && ok;
 	ok = checkDescription(ctx, option.description, `${label}.description`) && ok;
-	if (option.required !== void 0 && typeof option.required !== "boolean") ok = fail$1(ctx, "invalid-option", `${label}.required must be a boolean.`);
+	if (option.required !== void 0 && typeof option.required !== "boolean") ok = fail$1(ctx, "invalid-option", `${label}.required is ${typeOf(option.required)}. Use true or false.`);
 	ok = checkLocalizations(ctx, option.nameLocalizations, `${label}.nameLocalizations`) && ok;
 	ok = checkLocalizations(ctx, option.descriptionLocalizations, `${label}.descriptionLocalizations`) && ok;
 	const type = option.type;
-	const numeric = type === "integer" || type === "number";
-	const choosable = type === "string" || numeric;
-	for (const key of [
-		"choices",
-		"autocomplete",
-		"minLength",
-		"maxLength",
-		"minValue",
-		"maxValue",
-		"channelTypes"
-	]) {
-		if (option[key] === void 0) continue;
-		if (!((key === "choices" || key === "autocomplete") && choosable ? true : (key === "minLength" || key === "maxLength") && type === "string" ? true : (key === "minValue" || key === "maxValue") && numeric ? true : key === "channelTypes" && type === "channel")) ok = fail$1(ctx, "invalid-option", `${label}.${key} is not valid for a "${type}" option.`);
+	for (const [key, types] of Object.entries(FIELD_TYPES)) {
+		if (option[key] === void 0 || types.includes(type)) continue;
+		ok = fail$1(ctx, "invalid-option", `${label}.${key} only works on ${quoted(types, "conjunction")} options, and this one is "${type}".`);
 	}
-	if (option.autocomplete !== void 0 && typeof option.autocomplete !== "boolean") ok = fail$1(ctx, "invalid-option", `${label}.autocomplete must be a boolean.`);
+	if (option.autocomplete !== void 0 && typeof option.autocomplete !== "boolean") ok = fail$1(ctx, "invalid-option", `${label}.autocomplete is ${typeOf(option.autocomplete)}. Use true or false.`);
 	if (option.choices !== void 0) {
-		if (option.autocomplete === true) ok = fail$1(ctx, "invalid-option", `${label} cannot have both choices and autocomplete.`);
+		if (option.autocomplete === true) ok = fail$1(ctx, "invalid-option", `${label} has both choices and autocomplete. Discord allows one or the other.`);
 		ok = checkChoices(ctx, option.choices, `${label}.choices`, type === "string") && ok;
 	}
 	for (const key of [
@@ -416,30 +413,30 @@ function checkOption(ctx, option, label) {
 		"maxValue"
 	]) {
 		const v = option[key];
-		if (v !== void 0 && typeof v !== "number") ok = fail$1(ctx, "invalid-option", `${label}.${key} must be a number.`);
+		if (v !== void 0 && typeof v !== "number") ok = fail$1(ctx, "invalid-option", `${label}.${key} is ${typeOf(v)}, not a number.`);
 	}
-	if (typeof option.minLength === "number" && (option.minLength < 0 || option.minLength > 6e3)) ok = fail$1(ctx, "invalid-option", `${label}.minLength must be between 0 and 6000.`);
-	if (typeof option.maxLength === "number" && (option.maxLength < 1 || option.maxLength > 6e3)) ok = fail$1(ctx, "invalid-option", `${label}.maxLength must be between 1 and 6000.`);
+	if (typeof option.minLength === "number" && (option.minLength < 0 || option.minLength > 6e3)) ok = fail$1(ctx, "invalid-option", `${label}.minLength is ${option.minLength}. Discord allows 0 to 6000.`);
+	if (typeof option.maxLength === "number" && (option.maxLength < 1 || option.maxLength > 6e3)) ok = fail$1(ctx, "invalid-option", `${label}.maxLength is ${option.maxLength}. Discord allows 1 to 6000.`);
 	if (option.channelTypes !== void 0) {
-		if (!Array.isArray(option.channelTypes) || option.channelTypes.some((c) => typeof c !== "number")) ok = fail$1(ctx, "invalid-option", `${label}.channelTypes must be an array of ChannelType values.`);
+		if (!Array.isArray(option.channelTypes) || option.channelTypes.some((c) => typeof c !== "number")) ok = fail$1(ctx, "invalid-option", `${label}.channelTypes has to be an array of ChannelType values from discord.js.`);
 	}
 	return ok;
 }
 function checkChoices(ctx, choices, label, isString) {
-	if (!Array.isArray(choices)) return fail$1(ctx, "invalid-option", `${label} must be an array.`);
-	if (choices.length > 25) return fail$1(ctx, "invalid-option", `${label} can have at most 25 entries.`);
+	if (!Array.isArray(choices)) return fail$1(ctx, "invalid-option", `${label} is ${typeOf(choices)}, not an array.`);
+	if (choices.length > 25) return fail$1(ctx, "invalid-option", `${label} has ${choices.length} entries. Discord allows 25 per option.`);
 	let ok = true;
 	for (const [index, choice] of choices.entries()) {
 		const at = `${label}[${index}]`;
 		if (!isRecord(choice)) {
-			ok = fail$1(ctx, "invalid-option", `${at} must be an object with name and value.`);
+			ok = fail$1(ctx, "invalid-option", `${at} is ${typeOf(choice)}. Each choice is an object like { name: "Red", value: "red" }.`);
 			continue;
 		}
 		const typed = choice;
-		if (typeof typed.name !== "string" || typed.name.length === 0 || typed.name.length > 100) ok = fail$1(ctx, "invalid-option", `${at}.name must be a string of 1 to 100 characters.`);
+		if (typeof typed.name !== "string" || typed.name.length === 0 || typed.name.length > 100) ok = fail$1(ctx, "invalid-option", `${at}.name is ${sizeOf(typed.name)}. Discord needs a name of 1 to 100 characters.`);
 		if (isString) {
-			if (typeof typed.value !== "string" || typed.value.length === 0 || typed.value.length > 100) ok = fail$1(ctx, "invalid-option", `${at}.value must be a string of 1 to 100 characters.`);
-		} else if (typeof typed.value !== "number") ok = fail$1(ctx, "invalid-option", `${at}.value must be a number.`);
+			if (typeof typed.value !== "string" || typed.value.length === 0 || typed.value.length > 100) ok = fail$1(ctx, "invalid-option", `${at}.value is ${sizeOf(typed.value)}. A string option's choices need a value of 1 to 100 characters.`);
+		} else if (typeof typed.value !== "number") ok = fail$1(ctx, "invalid-option", `${at}.value is ${typeOf(typed.value)}. A numeric option's choices need a number value.`);
 		ok = checkLocalizations(ctx, typed.nameLocalizations, `${at}.nameLocalizations`) && ok;
 	}
 	return ok;
@@ -462,6 +459,17 @@ const COMMAND_TYPE = {
 	user: ApplicationCommandType.User,
 	message: ApplicationCommandType.Message
 };
+const TYPE_LABEL = {
+	[ApplicationCommandType.ChatInput]: "slash command",
+	[ApplicationCommandType.User]: "user context menu command",
+	[ApplicationCommandType.Message]: "message context menu command"
+};
+/** How many commands of each type Discord takes, globally and in each server. */
+const COMMAND_LIMITS = {
+	[ApplicationCommandType.ChatInput]: 100,
+	[ApplicationCommandType.User]: 15,
+	[ApplicationCommandType.Message]: 15
+};
 /** Compiles the command routes of a route table into Discord command definitions. */
 async function compileCommands(table) {
 	const diagnostics = new Diagnostics();
@@ -476,20 +484,37 @@ async function compileCommands(table) {
 		const command = compileTopLevel(top, entries, routeMetas, diagnostics);
 		if (command !== null) commands.push(command);
 	}
-	for (const entry of routeMetas.values()) if (!entry.used) diagnostics.warn("unused-route-meta", "This route.ts does not describe a command with subcommands and has no effect.", { file: entry.boundary.file });
+	for (const entry of routeMetas.values()) if (!entry.used) diagnostics.warn("unused-route-meta", "This route.ts has no effect because there are no subcommands below it. A plain command's meta goes in its command.ts.", { file: entry.boundary.file });
 	detectDuplicateNames(commands, diagnostics);
+	checkLimits(commands, diagnostics);
 	commands.sort((a, b) => a.type - b.type || a.name.localeCompare(b.name));
 	return {
 		commands,
 		diagnostics
 	};
 }
+function checkLimits(commands, diagnostics) {
+	for (const [type, limit] of Object.entries(COMMAND_LIMITS)) {
+		const ofType = commands.filter((c) => c.type === Number(type));
+		const first = ofType[0];
+		if (first === void 0 || ofType.length <= limit) continue;
+		const slash = Number(type) === ApplicationCommandType.ChatInput;
+		diagnostics.error("too-many-commands", `The app has ${ofType.length} ${TYPE_LABEL[Number(type)]}s, and Discord allows ${limit}, globally and in each server. ${slash ? "Subcommands don't count toward it, so group related commands under one." : "Remove some."}`, { file: commandsDir(first) });
+	}
+}
+/** The `commands/` directory, found by walking up from one of the command's handlers. */
+function commandsDir(command) {
+	const route = Object.values(command.handlers)[0];
+	let dir = path.dirname(route.file);
+	for (let i = 0; i < route.segments.length; i++) dir = path.dirname(dir);
+	return dir;
+}
 async function loadRoutes(routes, diagnostics) {
 	const commandRoutes = routes.filter((r) => r.kind === "command");
 	return (await Promise.all(commandRoutes.map(async (route) => {
 		const module = await importOrReport(route.file, diagnostics);
 		if (module === null) return null;
-		if (!checkDeclaredRoute(module, route, diagnostics)) return null;
+		if (!checkHandler(module, route, diagnostics)) return null;
 		const meta = validateCommandMeta(module.meta, route.file, diagnostics);
 		if (meta === null) return null;
 		return {
@@ -505,7 +530,7 @@ async function loadRouteMetas(boundaries, diagnostics) {
 	await Promise.all(relevant.map(async (boundary) => {
 		const key = boundary.segments.filter((s) => s.type !== "group").map(formatSegment).join("/");
 		if (key === "") {
-			diagnostics.error("route-meta-without-path", "route.ts must live inside a command directory. At the commands root it describes nothing.", { file: boundary.file });
+			diagnostics.error("route-meta-without-path", "This route.ts isn't inside a command's directory, so it doesn't describe a command. Move it into the command's directory, like commands/moderation/route.ts.", { file: boundary.file });
 			return;
 		}
 		const module = await importOrReport(boundary.file, diagnostics);
@@ -524,15 +549,16 @@ async function importOrReport(file, diagnostics) {
 	try {
 		return await loadModule(file);
 	} catch (error) {
-		diagnostics.error("module-load-failed", `Could not import this file: ${error instanceof Error ? error.message : String(error)}`, { file });
+		diagnostics.error("module-load-failed", `The compiler imports every route file to read its exports, and this one threw: ${error instanceof Error ? error.message : String(error)}`, { file });
 		return null;
 	}
 }
 function compileTopLevel(top, entries, routeMetas, diagnostics) {
 	const direct = entries.filter((e) => e.parts.length === 1);
 	const nested = entries.filter((e) => e.parts.length > 1);
+	if (direct.length > 1) return null;
 	if (direct.length > 0 && nested.length > 0) {
-		for (const entry of nested) diagnostics.error("mixed-command-and-subcommands", `"${top}" has its own command.ts and also subcommands. Discord does not allow both. Either remove ${relative$1(direct[0]?.route.file)} or move this handler out of ${top}/.`, {
+		for (const entry of nested) diagnostics.error("mixed-command-and-subcommands", `"${top}" has a command.ts and also subcommands, like this one. Discord doesn't let a command with subcommands run by itself. Replace ${relative$2(direct[0]?.route.file)} with a route.ts, or move this file out of ${top}/.`, {
 			file: entry.route.file,
 			route: entry.route.id
 		});
@@ -540,7 +566,7 @@ function compileTopLevel(top, entries, routeMetas, diagnostics) {
 	}
 	const tooDeep = nested.filter((e) => e.parts.length > 3);
 	if (tooDeep.length > 0) {
-		for (const entry of tooDeep) diagnostics.error("command-too-deep", `Commands can nest at most three levels (command / group / subcommand). "${entry.route.path}" has ${entry.parts.length}.`, {
+		for (const entry of tooDeep) diagnostics.error("command-too-deep", `"${entry.route.path}" is ${entry.parts.length} levels deep. Discord commands go three levels at most: command, subcommand group, and subcommand. Remove a level of directories.`, {
 			file: entry.route.file,
 			route: entry.route.id
 		});
@@ -567,14 +593,20 @@ function compilePlainCommand(entry, diagnostics) {
 		payload.description = meta.description;
 		if (meta.options !== void 0) payload.options = meta.options.map(optionPayload);
 	}
+	const mode = deferMode(meta);
 	return {
 		name,
 		type,
 		handlers: { "": route },
+		defer: mode === null ? {} : { "": mode },
 		payload: compact(payload),
 		files: [route.file]
 	};
 }
+function deferMode(meta) {
+	if (meta.defer === "ephemeral") return "ephemeral";
+	return meta.defer === true ? "reply" : null;
+}
 function compileParentCommand(top, nested, routeMetas, diagnostics) {
 	const parent = requireRouteMeta(top, nested[0], routeMetas, diagnostics);
 	if (parent === null) return null;
@@ -584,23 +616,30 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 		return null;
 	}
 	const handlers = {};
+	const defer = {};
 	const files = [parent.boundary.file];
 	const options = [];
 	let ok = true;
+	const place = (key, entry) => {
+		handlers[key] = entry.route;
+		files.push(entry.route.file);
+		const mode = deferMode(entry.meta);
+		if (mode !== null) defer[key] = mode;
+	};
 	const bySecond = /* @__PURE__ */ new Map();
 	for (const entry of nested) {
 		const second = entry.parts[1];
 		bySecond.set(second, [...bySecond.get(second) ?? [], entry]);
 	}
 	if (bySecond.size > 25) {
-		diagnostics.error("too-many-subcommands", `"${top}" has ${bySecond.size} subcommands and groups. Discord allows at most 25.`, { file: parent.boundary.file });
+		diagnostics.error("too-many-subcommands", `"${top}" has ${bySecond.size} subcommands and groups. Discord allows 25 per command. Move some into a subcommand group or another command.`, { file: parent.boundary.file });
 		ok = false;
 	}
 	for (const [second, entries] of [...bySecond].sort(([a], [b]) => a.localeCompare(b))) {
 		const subs = entries.filter((e) => e.parts.length === 2);
 		const grouped = entries.filter((e) => e.parts.length === 3);
 		if (subs.length > 0 && grouped.length > 0) {
-			for (const entry of grouped) diagnostics.error("mixed-subcommand-and-group", `"${top}/${second}" is both a subcommand (${relative$1(subs[0]?.route.file)}) and a subcommand group. Discord does not allow both.`, {
+			for (const entry of grouped) diagnostics.error("mixed-subcommand-and-group", `${relative$2(subs[0]?.route.file)} makes "${top} ${second}" a subcommand, and this file makes it a subcommand group. Discord doesn't allow both. Move that command.ts into its own directory under ${second}/, or move this file out.`, {
 				file: entry.route.file,
 				route: entry.route.id
 			});
@@ -613,8 +652,7 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 				ok = false;
 				continue;
 			}
-			handlers[sub.name] = sub.route;
-			files.push(sub.route.file);
+			place(sub.name, subs[0]);
 			options.push(sub.payload);
 			continue;
 		}
@@ -632,12 +670,12 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 		}
 		const extra = topLevelKeysUsed(group.meta);
 		if (extra.length > 0) {
-			diagnostics.error("top-level-field-on-group", `${extra.map((k) => `meta.${k}`).join(", ")} only applies to top-level commands. Move it to ${relative$1(parent.boundary.file)}.`, { file: group.boundary.file });
+			diagnostics.error("top-level-field-on-group", `${fieldList(extra)} can't be set on a subcommand group. Discord applies ${extra.length === 1 ? "it" : "them"} to the whole command, so move ${extra.length === 1 ? "it" : "them"} to ${relative$2(parent.boundary.file)}.`, { file: group.boundary.file });
 			ok = false;
 			continue;
 		}
 		if (grouped.length > 25) {
-			diagnostics.error("too-many-subcommands", `Group "${groupKey}" has ${grouped.length} subcommands. Discord allows at most 25.`, { file: group.boundary.file });
+			diagnostics.error("too-many-subcommands", `The "${groupKey}" group has ${grouped.length} subcommands. Discord allows 25 per group. Move some into another group.`, { file: group.boundary.file });
 			ok = false;
 			continue;
 		}
@@ -649,8 +687,7 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 				ok = false;
 				continue;
 			}
-			handlers[`${groupName}/${sub.name}`] = sub.route;
-			files.push(sub.route.file);
+			place(`${groupName}/${sub.name}`, entry);
 			groupOptions.push(sub.payload);
 		}
 		options.push(compact({
@@ -674,6 +711,7 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 		name,
 		type: ApplicationCommandType.ChatInput,
 		handlers,
+		defer,
 		payload,
 		files
 	};
@@ -681,7 +719,7 @@ function compileParentCommand(top, nested, routeMetas, diagnostics) {
 function compileSubcommand(entry, diagnostics) {
 	const { route, meta } = entry;
 	if (meta.type !== void 0 && meta.type !== "chatInput") {
-		diagnostics.error("context-menu-nested", `Context menu commands cannot be subcommands. Move ${relative$1(route.file)} to the top of commands/.`, {
+		diagnostics.error("context-menu-nested", `This is a context menu command, but it's nested under ${entry.parts[0]}/ as a subcommand. Discord doesn't allow context menu subcommands. Move it to its own directory directly under commands/, like commands/${entry.parts.at(-1)}/command.ts.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -689,7 +727,7 @@ function compileSubcommand(entry, diagnostics) {
 	}
 	const extra = topLevelKeysUsed(meta);
 	if (extra.length > 0) {
-		diagnostics.error("top-level-field-on-subcommand", `${extra.map((k) => `meta.${k}`).join(", ")} only applies to top-level commands. Move it to the route.ts of "${entry.parts[0]}".`, {
+		diagnostics.error("top-level-field-on-subcommand", `${fieldList(extra)} can't be set on a subcommand. Discord applies ${extra.length === 1 ? "it" : "them"} to the whole command, so move ${extra.length === 1 ? "it" : "them"} to the route.ts in ${entry.parts[0]}/.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -719,7 +757,7 @@ function requireRouteMeta(key, child, routeMetas, diagnostics) {
 		return entry;
 	}
 	const dir = directoryForPath(child.route, key.split("/").length);
-	diagnostics.error("missing-route-meta", `"${key}" has subcommands but no route.ts. Discord needs a description for it. Add ${path.join(dir, "route.ts")} exporting \`meta\` with a description.`, {
+	diagnostics.error("missing-route-meta", `"${key}" has subcommands but no route.ts. Discord needs a description for it, and without a command.ts that goes in route.ts. Add ${relative$2(path.join(dir, "route.ts"))} with export const meta = { description: "..." }.`, {
 		file: child.route.file,
 		route: child.route.id
 	});
@@ -746,11 +784,15 @@ function isValidChatInputName(name) {
 	return /^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$/u.test(name) && name === name.toLowerCase();
 }
 function reportDirectoryName(route, name, diagnostics, file) {
-	diagnostics.error("invalid-name", `"${name}" is not a valid chat input command name. Discord requires lowercase letters, digits, hyphens, and underscores, 1 to 32 characters. Rename the directory or set \`meta.name\`.`, {
+	diagnostics.error("invalid-name", `"${name}" isn't a valid slash command name. Discord only allows lowercase letters, digits, hyphens, and underscores, up to 32 characters. Rename the directory, or set meta.name.`, {
 		file: file ?? route.file,
 		route: route.id
 	});
 }
+/** `meta.nsfw and meta.contexts` */
+function fieldList(keys) {
+	return new Intl.ListFormat("en").format(keys.map((key) => `meta.${key}`));
+}
 function detectDuplicateNames(commands, diagnostics) {
 	const seen = /* @__PURE__ */ new Map();
 	for (const command of commands) {
@@ -760,7 +802,7 @@ function detectDuplicateNames(commands, diagnostics) {
 			seen.set(key, command);
 			continue;
 		}
-		diagnostics.error("duplicate-command-name", `Two commands register as "${command.name}": ${relative$1(existing.files[0])} and ${relative$1(command.files[0])}. Check \`meta.name\` overrides.`, { file: command.files[0] });
+		diagnostics.error("duplicate-command-name", `${relative$2(existing.files[0])} and ${relative$2(command.files[0])} both register a ${TYPE_LABEL[command.type]} named "${command.name}". Discord needs the names to be unique, so change meta.name or the directory of one of them.`, { file: command.files[0] });
 	}
 }
 function optionPayload(option) {
@@ -816,7 +858,7 @@ function compact(object) {
 	for (const [key, value] of Object.entries(object)) if (value !== void 0) out[key] = value;
 	return out;
 }
-function relative$1(file) {
+function relative$2(file) {
 	return file === void 0 ? "?" : path.relative(process.cwd(), file).split(path.sep).join("/");
 }
 //#endregion
@@ -840,7 +882,7 @@ async function compileEvents(table) {
 		if (modes.size > 1) {
 			for (const handler of handlers) {
 				if (handler.mode === void 0) continue;
-				diagnostics.error("event-mode-conflict", `Handlers of "${name}" disagree on \`meta.mode\`: ${[...modes].map((m) => `"${m}"`).join(" and ")}. All handlers of one event share a mode; set it on one file or make them agree.`, {
+				diagnostics.error("event-mode-conflict", `Handlers of "${name}" set meta.mode to both "concurrent" and "sequential". The mode applies to all of an event's handlers, so set it in one file, or make them match.`, {
 					file: handler.route.file,
 					route: handler.route.id
 				});
@@ -870,13 +912,13 @@ async function loadHandler(route, diagnostics) {
 	try {
 		module = await loadModule(route.file);
 	} catch (error) {
-		diagnostics.error("module-load-failed", `Could not import this file: ${error instanceof Error ? error.message : String(error)}`, {
+		diagnostics.error("module-load-failed", `The compiler imports every route file to read its exports, and this one threw: ${error instanceof Error ? error.message : String(error)}`, {
 			file: route.file,
 			route: route.id
 		});
 		return null;
 	}
-	if (!checkDeclaredRoute(module, route, diagnostics, name)) return null;
+	if (!checkHandler(module, route, diagnostics, name)) return null;
 	const meta = validateEventMeta(module.meta, route, diagnostics);
 	if (meta === null) return null;
 	return {
@@ -892,7 +934,7 @@ function eventName(route, diagnostics) {
 	const first = statics[0];
 	if (first === void 0 || first.type !== "static") return null;
 	if (statics.length > 1) {
-		diagnostics.error("event-nested-path", `Event handlers live directly under events/<eventName>/. "${route.path}" adds ${statics.slice(1).map(formatSegment).join("/")} below the event name. Use a route group like (${statics[1]?.name}) to keep several handlers apart.`, {
+		diagnostics.error("event-nested-path", `"${route.path}" has ${statics.slice(1).map(formatSegment).join("/")}/ below the event name, and event handlers go directly in events/<eventName>/. To split an event across files, use route groups, like events/${first.name}/(${statics[1]?.name})/event.ts.`, {
 			file: route.file,
 			route: route.id
 		});
@@ -901,8 +943,8 @@ function eventName(route, diagnostics) {
 	const name = first.name;
 	if (EVENT_NAMES.has(name)) return name;
 	const renamed = RENAMED[name];
-	const hint = renamed !== void 0 ? `discord.js renamed it to "${renamed}".` : closest(name) ? `Did you mean "${closest(name)}"?` : "Event names are the lowerCamelCase values of discord.js's `Events` enum.";
-	diagnostics.error("unknown-event", `"${name}" is not a discord.js event. ${hint} Rename the directory.`, {
+	const hint = renamed !== void 0 ? `discord.js renamed it to "${renamed}".` : closest(name) ? `Did you mean "${closest(name)}"?` : "Event directories are named after a value of discord.js's Events enum, like messageCreate.";
+	diagnostics.error("unknown-event", `"${name}" isn't a discord.js event. ${hint} Rename the directory.`, {
 		file: route.file,
 		route: route.id
 	});
@@ -917,11 +959,11 @@ function validateEventMeta(value, route, diagnostics) {
 		});
 		return null;
 	};
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return fail("`meta` must be an object.");
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return fail("meta has to be an object, like { order: 1 }.");
 	const meta = value;
-	if (meta.once !== void 0 && typeof meta.once !== "boolean") return fail("`meta.once` must be a boolean.");
-	if (meta.order !== void 0 && (typeof meta.order !== "number" || !Number.isFinite(meta.order))) return fail("`meta.order` must be a finite number.");
-	if (meta.mode !== void 0 && meta.mode !== "sequential" && meta.mode !== "concurrent") return fail("`meta.mode` must be \"sequential\" or \"concurrent\".");
+	if (meta.once !== void 0 && typeof meta.once !== "boolean") return fail("meta.once has to be true or false.");
+	if (meta.order !== void 0 && (typeof meta.order !== "number" || !Number.isFinite(meta.order))) return fail(`meta.order is ${String(meta.order)}. Use a finite number.`);
+	if (meta.mode !== void 0 && meta.mode !== "sequential" && meta.mode !== "concurrent") return fail(`meta.mode is ${JSON.stringify(meta.mode)}. Use "sequential" or "concurrent".`);
 	return meta;
 }
 /** Case-insensitive match against known events, to catch `GuildMemberAdd` or `guildmemberadd`. */
@@ -1040,6 +1082,12 @@ const BOUNDARY_KINDS = /* @__PURE__ */ new Set([
 	"error",
 	"route"
 ]);
+/** A directory name for the examples in messages. */
+const EXAMPLE_DIR = {
+	command: "ping",
+	component: "confirm",
+	event: "messageCreate"
+};
 /** Discovers the app directory and builds the route table. */
 function buildRouteTable(appDir) {
 	return buildRouteTableFromFiles(discover(appDir));
@@ -1057,12 +1105,13 @@ function buildRouteTableFromFiles(files) {
 				segments: [],
 				file: source.file
 			});
-			else diagnostics.error("file-outside-category", `${path.basename(source.file)} must live under commands/, components/, or events/. Only middleware and error files may sit at the app root.`, { file: source.file });
+			else diagnostics.error("file-outside-category", `${path.basename(source.file)} is directly in the app directory, where only middleware and error files go. Move it under commands/, components/, or events/.`, { file: source.file });
 			continue;
 		}
 		const category = CATEGORY_DIRS[categoryDir];
 		if (category === void 0) {
-			diagnostics.error("unknown-category", `"${categoryDir}/" is not a route area. Reserved files must live under commands/, components/, or events/.`, { file: source.file });
+			const name = path.basename(source.file);
+			diagnostics.error("unknown-category", `${name} is in ${categoryDir}/, which isn't a route directory. Nectar treats every file named ${name} as a route file, so move it under commands/, components/, or events/, or rename it.`, { file: source.file });
 			continue;
 		}
 		const segments = parseSegments(rest, source, diagnostics);
@@ -1077,7 +1126,8 @@ function buildRouteTableFromFiles(files) {
 			continue;
 		}
 		if (!HANDLER_KINDS[category].has(source.kind)) {
-			diagnostics.error("file-in-wrong-category", `${path.basename(source.file)} does not belong under ${categoryDir}/. Expected one of: ${[...HANDLER_KINDS[category]].map((k) => `${k}.ts`).join(", ")}.`, { file: source.file });
+			const home = Object.entries(CATEGORY_DIRS).find(([, c]) => HANDLER_KINDS[c].has(source.kind));
+			diagnostics.error("file-in-wrong-category", `${path.basename(source.file)} belongs under ${home?.[0]}/, not ${categoryDir}/.`, { file: source.file });
 			continue;
 		}
 		const route = makeRoute(category, source.kind, segments, source.file, diagnostics);
@@ -1103,31 +1153,35 @@ function parseSegments(dirs, source, diagnostics) {
 	return segments;
 }
 function makeRoute(category, kind, segments, file, diagnostics) {
+	const name = path.basename(file);
+	const dir = `${category}s`;
 	if (segments.length === 0) {
-		diagnostics.error("route-without-path", `${path.basename(file)} needs a named directory. Files directly inside ${category}s/ have no route path.`, { file });
+		diagnostics.error("route-without-path", `${name} is directly in ${dir}/, so it has no route path. Put it in a named directory, like ${dir}/${EXAMPLE_DIR[category]}/${name}.`, { file });
+		return null;
+	}
+	if (segments.every((segment) => segment.type === "group")) {
+		const groups = segments.map(formatSegment).join("/");
+		const example = category === "event" ? `${dir}/${EXAMPLE_DIR[category]}/${groups}/${name}` : `${dir}/${groups}/${EXAMPLE_DIR[category]}/${name}`;
+		diagnostics.error("route-without-path", `${name} is only inside route groups, and groups aren't part of the route path. Put it in a named directory, like ${example}.`, { file });
 		return null;
 	}
 	const params = [];
 	for (const [index, segment] of segments.entries()) if (segment.type === "dynamic" || segment.type === "catchAll") {
 		if (category !== "component") {
-			diagnostics.error("dynamic-segment-not-allowed", `${formatSegment(segment)} is a dynamic segment, but ${category} routes cannot carry parameters. Only component routes can.`, { file });
+			diagnostics.error("dynamic-segment-not-allowed", `${formatSegment(segment)} is a parameter, and only component routes can have parameters. ${category === "command" ? "Discord registers commands under fixed names, so take input with meta.options instead." : "The directory has to be named after a discord.js event, like events/messageCreate/."}`, { file });
 			return null;
 		}
 		if (params.includes(segment.name)) {
-			diagnostics.error("duplicate-param", `Parameter "${segment.name}" appears twice in the same route.`, { file });
+			diagnostics.error("duplicate-param", `The parameter "${segment.name}" appears twice in this route. Each parameter becomes a key of ctx.params, so the names have to differ. Rename one of the directories.`, { file });
 			return null;
 		}
 		if (segment.type === "catchAll" && index !== segments.length - 1) {
-			diagnostics.error("catch-all-not-last", `${formatSegment(segment)} must be the last segment of the route.`, { file });
+			diagnostics.error("catch-all-not-last", `${formatSegment(segment)} has more directories after it. A catch-all takes all the remaining values, so it has to be the last segment. Use [${segment.name}] if it only needs one value.`, { file });
 			return null;
 		}
 		params.push(segment.name);
 	}
 	const routePath = segments.filter((segment) => segment.type !== "group" || category === "event").map(formatSegment).join("/");
-	if (routePath === "") {
-		diagnostics.error("route-without-path", `${path.basename(file)} sits only inside route groups. Groups do not contribute to the route, so this route has no path.`, { file });
-		return null;
-	}
 	const id = `${category}:${routePath}`;
 	return {
 		id,
@@ -1153,12 +1207,16 @@ function detectDuplicates(routes, diagnostics) {
 			seen.set(key, route);
 			continue;
 		}
-		diagnostics.error("duplicate-route", existing.kind === route.kind ? `Route ${route.id} is defined twice: ${existing.file} and ${route.file}. Route groups do not make paths distinct.` : `Route ${route.id} has two handlers: ${existing.file} and ${route.file}. A component route takes one button.ts, select.ts, or modal.ts. Move one into its own directory.`, {
+		const other = relative$1(existing.file);
+		diagnostics.error("duplicate-route", existing.kind !== route.kind ? `${other} handles the same route, ${route.id}. customId() and the generated types identify a component by its path alone, so each path takes one button.ts, select.ts, or modal.ts. Move one of them into its own directory.` : path.dirname(existing.file) === path.dirname(route.file) ? `${other} is in the same directory and handles the same route, ${route.id}. Keep one of them.` : `${other} is the same route, ${route.id}. Route groups aren't part of the path, so they don't tell the two apart. Rename one of the directories.`, {
 			file: route.file,
 			route: route.id
 		});
 	}
 }
+function relative$1(file) {
+	return path.relative(process.cwd(), file).split(path.sep).join("/");
+}
 //#endregion
 //#region src/compiler/graph.ts
 /** Runs the whole compiler pipeline on an app directory. */
@@ -1272,15 +1330,17 @@ async function compileProject(project, io) {
 	return graph;
 }
 /**
-* One diagnostic as a headline and an indented message:
+* One diagnostic as a headline, an indented message, and the code's reference entry:
 *
-*     ✖ error  invalid-name  app/commands/Bad Name/command.ts
-*       Command names must be lowercase ...
+*     ✖ error  invalid-name  app/commands/Ping/command.ts
+*       "Ping" isn't a valid slash command name. ...
+*       https://nectar-js.github.io/nectar/reference/diagnostics#invalid-name
 */
 function formatDiagnostic(diagnostic, root) {
 	const mark = diagnostic.severity === "error" ? fail(c.red("error")) : warn(c.yellow("warning"));
 	const where = diagnostic.file === void 0 ? "" : `  ${relative(root, diagnostic.file)}`;
-	return [`${mark}  ${c.dim(diagnostic.code)}${where}`, ...indent([diagnostic.message])].join("\n");
+	const docs = docsUrl(diagnostic.code);
+	return [`${mark}  ${c.dim(diagnostic.code)}${where}`, ...indent([diagnostic.message, ...docs === void 0 ? [] : [link(docs)]])].join("\n");
 }
 function relative(root, file) {
 	return path.relative(root, file).split(path.sep).join("/");
@@ -2222,4 +2282,4 @@ function commandHelp(command) {
 //#endregion
 export { main as t };
 
-//# sourceMappingURL=cli-Ce-ZUj6M.js.map
+//# sourceMappingURL=cli-Cv0mpiRy.js.map