spearkit 0.3.0 → 0.4.0

package/llms-full.txt

@@ -0,0 +1,4619 @@
+# spearkit v0.4.0 — full documentation for LLMs
+
+> discord.js++ — a developer-experience-first Discord library. Drop-in compatible with discord.js, with ergonomic events, slash commands, and interactive components.
+
+This file concatenates every spearkit guide and the complete API reference. It is generated from docs/*.md (the single source of truth). Install: `npm install spearkit discord.js`. Import every symbol — spearkit additions and the entire re-exported discord.js surface — from `spearkit`.
+
+---
+
+## Use cases — reach for
+
+**Bot setup & lifecycle**
+
+| Want to… | Reach for |
+| --- | --- |
+| Start a bot and connect | `new SpearClient({ intents })` + `await client.start(token)` |
+| Choose gateway intents | `Intents.none / default / guilds / messages / all` |
+| Wire up handlers | `client.register(...)`; one file per handler → `client.load(dir)` |
+| Push commands to Discord | `client.deployCommands({ guildId })`; slash + context menus, safe CI → `client.deployAllCommands({ strategy: "diff", dryRun })` |
+| Package a reusable feature | `definePlugin(...)` + `client.use(...)` |
+| Migrate an existing discord.js bot | import from `"spearkit"`, swap `Client` → `SpearClient` |
+
+**Commands & input**
+
+| Want to… | Reach for |
+| --- | --- |
+| A slash command | `command({ name, description, run })` |
+| Typed inputs to a command | `options: { x: option.string/integer/number/boolean/user/channel/role/mentionable/attachment(...) }` |
+| Group many commands under one name | `commandGroup` + `subcommand` / `subcommandGroup` |
+| Suggest values while the user types | `option.string({ autocomplete })` |
+| A right-click "Apps" action on a user/message | `userCommand` / `messageCommand` |
+| A classic `!text` command | `prefixCommand(...)` + `new SpearClient({ prefix })` |
+| Parse `!cmd` arguments into typed values | `args: (a) => a.snowflake().duration().rest()` → `ctx.options` |
+| Avoid `Unknown interaction` (10062) on slow work | `command({ autoDefer: true })` / `new SpearClient({ autoDefer: true })` |
+
+**Interactivity (components)**
+
+| Want to… | Reach for |
+| --- | --- |
+| A clickable button | `button({ id, run })` → `row(btn.build(...))` |
+| A URL button (no handler) | `linkButton` |
+| A dropdown of fixed options | `stringSelect` |
+| Pick users / roles / channels / mentionables | `userSelect` / `roleSelect` / `channelSelect` / `mentionableSelect` |
+| A form with text fields | `modal` + `textInput` |
+| Carry data through a component | custom-id params `id: "x:{id}"` → `ctx.params.id` |
+| A paged list with next/prev | `paginate(...)` |
+| An "Are you sure?" yes/no gate | `confirm(...)` |
+
+**Replies & UX**
+
+| Want to… | Reach for |
+| --- | --- |
+| Reply, public or hidden | `ctx.reply(...)` / `ctx.replyEphemeral(...)` |
+| Work that takes >3s | `ctx.defer()` then `ctx.editReply(...)` |
+| A styled success/error/info/warn embed | `ctx.success/error/info/warn(...)` |
+| "Reply, edit, or follow-up — whichever fits" | `ctx.send(...)` |
+
+**Cross-cutting concerns**
+
+| Want to… | Reach for |
+| --- | --- |
+| React to gateway events | `event(name, run)`; once on startup → `event("clientReady", ...)` |
+| Rate-limit a command/handler | `cooldown` (per-command or client-wide) |
+| Restrict by role / permission / owner / guild | guards: `requireAnyRole` / `requireUserPermissions` / `requireOwner` / `guildOnly` |
+| Run jobs on cron or interval | `task({ cron \| interval })` / `client.schedule(...)` |
+| Delay once / staged follow-ups / recover on restart | `client.scheduler.delay` / `followUp` / `reconcile` |
+| Structured logs to file/webhook | `client.logger` + `consoleSink` / `jsonlSink` / `webhookSink` |
+| Track who used what | `new SpearClient({ usage })` + `MemoryUsageStore` / `JsonFileUsageStore` |
+| Read typed env / load `.env` | `env.string/number/boolean/require` (auto-loaded on `start()`) |
+| Shut down cleanly on SIGINT/SIGTERM | `client.enableGracefulShutdown({ onShutdown })` |
+| Permission / role-hierarchy preflight | `moderationCheck(...)`, `missingPermissions(...)`, `canActOn(...)`, `ctx.botMissing(...)` |
+| Wait for a reply / click / modal submission | `ctx.awaitMessageFrom(...)` / `ctx.awaitModal(...)` / `awaitComponent(...)` |
+| Branch on a Discord API error | `isDiscordError(err, DiscordErrorCode.X)` / `explainDiscordError(err)` |
+| Per-guild prefix from a store | `prefix: { dynamic: (message) => ... }` |
+
+**Utilities (primitives)**
+
+| Want to… | Reach for |
+| --- | --- |
+| Stop concurrent runs per key (e.g. per user) | `KeyedLock` |
+| Fetch that returns `null` instead of throwing | `safeFetch.{member,channel,message,user,guild,role}` |
+| Format/parse `"1h30m"` durations | `formatDuration` / `parseDuration` |
+| Render `<t:…>` Discord timestamps | `discordTimestamp` / `relativeTimestamp` |
+| In-memory cache / counters / rate-limit window | `MemoryCache` |
+| Load JSON/JSON5/YAML config | `loadConfig` |
+| Persist key-value data / per-guild settings | `MemoryStore` / `JsonStore` + `createSettings({ store, defaults })` |
+| Split text to Discord's 2000-char limit | `chunkMessage(text)` / `truncate(text, max)` |
+
+---
+
+# spearkit documentation
+
+**discord.js++** — a developer-experience-first layer over discord.js. spearkit
+re-exports all of discord.js (so it's a drop-in replacement) and adds an
+ergonomic, fully type-safe API for events, slash commands and interactive
+components.
+
+## Contents
+
+1. [Getting started](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/getting-started.md) — install, first bot, project layout.
+2. [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — `SpearClient`, intents, `register`, `start`, deployment.
+3. [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — slash commands, subcommands, permissions, deployment.
+4. [Options](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/options.md) — typed option builders, choices, autocomplete.
+5. [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — buttons, selects, modals, custom-id routing.
+6. [Context menus](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context-menus.md) — user and message "Apps" commands.
+7. [Events](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/events.md) — the `event()` helper and the event registry.
+8. [Contexts](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md) — reply helpers shared by every handler.
+9. [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md) — role/permission/owner/guild preconditions.
+10. [Auto-defer](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/auto-defer.md) — beat the 3-second `Unknown interaction` error.
+11. [Permissions & hierarchy](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/permissions.md) — moderation preflight checks.
+12. [Discord API errors](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/errors.md) — recognise and recover from `DiscordAPIError`.
+13. [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) — per-user/role/guild rate limiting.
+14. [Scheduled tasks](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/scheduler.md) — cron and interval jobs.
+15. [Prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md) — classic `!text` commands.
+16. [Collectors](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/collectors.md) — await messages, modals and component clicks.
+17. [Key-value store & settings](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/store.md) — persist per-guild config + dynamic prefix.
+18. [Messages & limits](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/messages.md) — split long output, truncate text.
+19. [Logging](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md) — structured, leveled, scoped logging.
+20. [Usage tracking](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/usage.md) — record who used what (store + Discord channel).
+21. [Environment & dotenv](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/env.md) — load `.env` and read typed env vars.
+22. [Graceful shutdown](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/shutdown.md) — close cleanly on `SIGINT`/`SIGTERM`.
+23. [Plugins](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/plugins.md) — bundling features into reusable units.
+24. [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md) — one file per command/event/component.
+25. [Migrating from discord.js](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/migration.md) — the drop-in path.
+26. [API reference](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md) — every exported symbol.
+
+## Why spearkit
+
+- **Drop-in.** `import { Client, EmbedBuilder } from "spearkit"` — every discord.js
+  export is available, so you can migrate one file at a time.
+- **Fully type-safe.** No `any` or `unknown` leaks into your handlers. Option
+  values, custom-id params and modal fields are all inferred from your
+  definitions.
+- **Co-located.** A command's options and handler, a button's appearance and
+  click logic, a modal's fields and submit logic — each lives in one place.
+- **No boilerplate.** No `interactionCreate` switch statements; spearkit routes
+  commands, autocomplete, buttons, selects and modals for you.
+
+## Thirty-second tour
+
+```ts
+import { SpearClient, Intents, command, option, button, row, event } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const ping = button({
+  id: "ping:{n}",
+  label: "Ping",
+  run: (ctx) => ctx.update(`pong #${ctx.params.n}`), // n: string
+});
+
+client.register(greet, ping, event("clientReady", (c) => console.log(c.user.tag)));
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+---
+
+# Getting started
+
+spearkit is **discord.js++**: it re-exports the entire discord.js surface and adds a
+fully type-safe layer for events, slash commands and interactive components. This
+page takes you from an empty folder to a running bot that responds to a slash
+command.
+
+## Install
+
+spearkit sits alongside discord.js, so install both:
+
+```bash
+npm install spearkit discord.js
+```
+
+Everything in your code imports from `"spearkit"` — including the plain discord.js
+symbols, which spearkit re-exports unchanged.
+
+## Credentials you need
+
+Create an application in the [Discord Developer Portal](https://discord.com/developers/applications)
+and collect three values:
+
+| Value | Where to find it | Used for |
+| ----- | ---------------- | -------- |
+| Bot token | Application → **Bot** → *Reset Token* | `client.start(token)` |
+| Application id | Application → **General Information** → *Application ID* | command deployment (spearkit reads it from the client once ready) |
+| Test guild id | Right-click your server in Discord (with Developer Mode on) → *Copy Server ID* | guild-scoped deploy |
+
+Keep the token secret. The examples below read these from the environment
+(`DISCORD_TOKEN`, `GUILD_ID`).
+
+## Your first bot
+
+```ts
+import { SpearClient, Intents, command, option, event } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: {
+    who: option.user({ description: "Who to greet", required: true }),
+  },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // ctx.options.who: User
+});
+
+const ready = event("clientReady", (c) => console.log(`Online as ${c.user.tag}`));
+
+client.register(greet, ready);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+What each step does:
+
+1. **`new SpearClient({ intents })`** — a discord.js `Client` with command, event
+   and component routing wired up. `Intents.default` is `[Guilds]`, enough for
+   slash commands and interactions.
+2. **`command({ ... })`** — defines a leaf slash command. Required options resolve
+   to their value type (`who` is a `User`); optional options would resolve to
+   `value | undefined`.
+3. **`client.register(...)`** — routes each item to the matching registry
+   (commands, events, components) by its kind.
+4. **`client.start(token)`** — logs in. With no argument it falls back to the
+   `DISCORD_TOKEN` environment variable.
+5. **`client.deployCommands({ guildId })`** — pushes your command definitions to
+   Discord over the client's own authenticated REST connection. Must run after the
+   client is ready (i.e. after `start`).
+
+### Guild vs global deploy
+
+`deployCommands` takes an optional `guildId`:
+
+- **Guild deploy** (`{ guildId }`) registers commands in a single server. Changes
+  appear **instantly** — ideal while developing.
+- **Global deploy** (omit `guildId`) registers commands across every server the
+  bot is in. Propagation can take up to an hour.
+
+```ts
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // instant, one guild
+await client.deployCommands();                                  // global, slow to propagate
+```
+
+You only need to deploy when your command *definitions* change (names,
+descriptions, options) — not on every restart.
+
+## Suggested project layout
+
+As a bot grows, give each command, event and component its own file:
+
+```
+my-bot/
+  src/
+    index.ts          # construct the client, register/load, start, deploy
+    commands/
+      greet.ts
+      ping.ts
+    events/
+      ready.ts
+    components/
+      vote.ts
+  package.json
+  tsconfig.json
+```
+
+A module exports a command, event or component as a default or named export:
+
+```ts
+// src/commands/ping.ts
+import { command } from "spearkit";
+
+export default command({
+  name: "ping",
+  description: "Check that the bot is alive",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+You can wire the pieces up explicitly with `register`, or let spearkit discover them
+with `client.load` (see [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md)).
+
+## Running it
+
+**With tsx** (run TypeScript directly, great for development):
+
+```bash
+npx tsx src/index.ts
+```
+
+**Compiled JavaScript** (for production):
+
+```bash
+npx tsc            # emit JS into dist/ per your tsconfig
+node dist/index.js
+```
+
+Note that `client.load` imports **compiled JavaScript**, so if you use file-based
+loading you must build before running the compiled output. Explicit `register`
+calls work the same under `tsx` or `node`.
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — `SpearClient`, intents, `register`, `start`, deployment.
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — slash commands, subcommands, options, deployment.
+
+---
+
+# Migrating from discord.js
+
+spearkit re-exports the entire discord.js surface, so adopting it is not a rewrite —
+it is a one-line import change followed by *optional*, incremental cleanup. You can
+move to spearkit today and start using its ergonomic helpers whenever you like.
+
+## The drop-in story
+
+Change `from "discord.js"` to `from "spearkit"`. Nothing else has to change: every
+discord.js export is available under the same name with the same types.
+
+```ts
+// before
+import { Client, EmbedBuilder, GatewayIntentBits } from "discord.js";
+
+// after — identical behaviour
+import { Client, EmbedBuilder, GatewayIntentBits } from "spearkit";
+```
+
+The full classic surface is there — builders, enums, the REST client, route
+helpers, the `Events` map, and so on:
+
+```ts
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  Client,
+  EmbedBuilder,
+  Events,
+  GatewayIntentBits,
+  REST,
+  Routes,
+  SlashCommandBuilder,
+} from "spearkit";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+const pingCommand = new SlashCommandBuilder()
+  .setName("ping")
+  .setDescription("Replies with an embed and a button");
+
+client.once(Events.ClientReady, (c) => {
+  console.log(`Ready as ${c.user.tag}`);
+});
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (!interaction.isChatInputCommand()) return;
+  if (interaction.commandName !== "ping") return;
+
+  const embed = new EmbedBuilder().setTitle("Pong!").setDescription(`Latency: ${client.ws.ping}ms`);
+  const buttons = new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder().setCustomId("again").setLabel("Again").setStyle(ButtonStyle.Primary),
+  );
+  await interaction.reply({ embeds: [embed], components: [buttons] });
+});
+
+async function deploy(token: string, appId: string): Promise<void> {
+  const rest = new REST().setToken(token);
+  await rest.put(Routes.applicationCommands(appId), { body: [pingCommand.toJSON()] });
+}
+```
+
+This file is 100% classic discord.js — only the import source changed. It keeps
+working exactly as before.
+
+## Incremental adoption
+
+Once your imports point at spearkit, you can convert pieces one at a time. There is no
+big-bang migration; old and new styles coexist.
+
+1. **Swap the client.** Replace `new Client(...)` with `new SpearClient(...)`. It
+   *is* a discord.js `Client` (it extends it), so your existing `client.on`,
+   `client.once`, `client.ws`, `client.rest` code is unchanged — but now it also
+   routes interactions to spearkit's registries.
+
+   ```ts
+   import { SpearClient, Intents } from "spearkit";
+
+   const client = new SpearClient({ intents: Intents.default });
+   ```
+
+2. **Move commands to `command()`.** Replace a hand-written `SlashCommandBuilder`
+   plus its branch of the `interactionCreate` switch with a single co-located
+   definition. Option values become fully typed.
+3. **Move events to `event()`.** Replace `client.on(Events.X, ...)` listeners with
+   `event("x", ...)` definitions and register them.
+4. **Move components to spearkit builders.** Replace manual `ButtonBuilder` +
+   custom-id parsing with `button()`, `stringSelect()`, `modal()`, etc. — spearkit
+   routes them by custom-id namespace and decodes `{param}`s for you.
+
+Convert at whatever pace suits you; un-migrated handlers keep running through your
+existing `interactionCreate` listener.
+
+## Before and after
+
+The classic approach hand-routes every interaction through one big switch and
+parses custom ids by hand:
+
+```ts
+// discord.js: one listener routes everything by hand
+import { Client, Events, GatewayIntentBits } from "discord.js";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (interaction.isChatInputCommand()) {
+    if (interaction.commandName === "greet") {
+      const who = interaction.options.getUser("who", true);
+      await interaction.reply(`Hello ${who}!`);
+    }
+  } else if (interaction.isButton()) {
+    const [name, choice] = interaction.customId.split(":"); // manual parsing
+    if (name === "vote") {
+      await interaction.update({ content: `You chose ${choice}` });
+    }
+  }
+});
+```
+
+spearkit co-locates each command and component with its handler, and routes
+interactions for you — no switch, no manual id parsing:
+
+```ts
+// spearkit: each handler owns its definition; routing is automatic
+import { SpearClient, Intents, command, option, button, row } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who to greet", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const vote = button({
+  id: "vote:{choice}",                              // {choice} is a typed param
+  label: "Yes",
+  style: "Success",
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // choice: string
+});
+
+client.register(greet, vote);
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+
+// build() requires exactly the params the id pattern declares:
+await channel.send({ content: "Vote:", components: [row(vote.build({ choice: "yes" }))] });
+```
+
+The option value (`who`) and the custom-id param (`choice`) are inferred from the
+definitions — no casts, no `getUser`/`split` boilerplate, and no `interactionCreate`
+switch to maintain.
+
+## See also
+
+- [Getting started](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/getting-started.md) — install spearkit and build a first bot.
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — define slash commands with typed options.
+- [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — buttons, selects, modals and custom-id routing.
+
+---
+
+# Client
+
+`SpearClient` is a discord.js `Client` with command, event and component
+registries — plus interaction routing — wired up for you. You construct it the
+same way you construct a discord.js client, register your handlers, log in, and
+(optionally) push your slash commands to Discord.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+```
+
+## Constructing a client
+
+`new SpearClient(options?)` takes the same options as discord.js'
+`ClientOptions`, except `intents` may be omitted: it defaults to
+`Intents.default` (just the `Guilds` intent, enough for slash commands and
+interactions).
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+// Explicit preset.
+const a = new SpearClient({ intents: Intents.messages });
+
+// Omitted — falls back to Intents.default.
+const b = new SpearClient();
+```
+
+The options type is exported as `SpearClientOptions` — `Partial<ClientOptions> &
+SpearOptions`. Every discord.js option (`partials`, `presence`, `sweepers`, …) is
+available, plus spearkit's own: `logger`, `dotenv`, `cooldown`, `prefix`, `usage`,
+`embeds`, `guards` and `autoDefer` (each covered in its own guide).
+
+### Intents presets
+
+`Intents` is a set of ready-made arrays of `GatewayIntentBits`. Pass one as
+`intents`, or compose your own array of `GatewayIntentBits` if you need
+something in between.
+
+| Preset | Contents |
+| ------ | -------- |
+| `Intents.none` | `[]` |
+| `Intents.default` | `[Guilds]` |
+| `Intents.guilds` | `[Guilds, GuildMembers]` |
+| `Intents.messages` | `[Guilds, GuildMessages, MessageContent]` |
+| `Intents.all` | Every intent, including privileged ones. |
+
+`Intents.messages` includes `MessageContent`, and `Intents.guilds` includes
+`GuildMembers` — both are **privileged intents**. You must enable them in the
+Discord developer portal for your application, otherwise the gateway will reject
+the connection. `Intents.all` includes every privileged intent for the same
+reason.
+
+```ts
+import { SpearClient, GatewayIntentBits } from "spearkit";
+
+// A custom intent set, mixing a preset idea with explicit bits.
+const client = new SpearClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+});
+```
+
+## Registries and subsystems
+
+Every client owns a set of registries and subsystems, each populated by
+`register` (or `load`) or configured by an option:
+
+| Member | Type | Holds / does |
+| ------ | ---- | ------------ |
+| `client.commands` | `CommandRegistry` | Slash commands; dispatches chat-input and autocomplete interactions. |
+| `client.events` | `EventRegistry` | Event listeners; attached to the client automatically. |
+| `client.components` | `ComponentRegistry` | Buttons, selects and modals; routed by custom-id namespace. |
+| `client.contextMenus` | `ContextMenuRegistry` | User / message context-menu ("Apps") commands. |
+| `client.prefix` | `PrefixRegistry` | Prefix (text) commands, dispatched from `messageCreate`. |
+| `client.scheduler` | `TaskScheduler` | Cron / interval tasks; started on ready, stopped on `destroy`. |
+| `client.cooldowns` | `CooldownManager` | Shared rate-limit state across commands and prefix commands. |
+| `client.usage` | `UsageTracker` | Records who used what to a store and/or channel. |
+| `client.logger` | `Logger` | Structured, scoped logger used across spearkit. |
+| `client.embeds` | `Embeds` | Preset embed factory behind `ctx.success/error/...`. |
+
+You rarely touch the registries directly — `register` routes items into the right
+one — but they are public for inspection and advanced control (e.g.
+`client.commands.size`, `client.commands.toJSON()`). Each subsystem has its own
+guide: [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md), [Scheduled tasks](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/scheduler.md),
+[Prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md), [Context menus](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context-menus.md),
+[Logging](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md), [Usage tracking](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/usage.md), [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md).
+
+## Registering handlers
+
+`client.register(...items)` accepts commands, events, components, context-menu
+commands, prefix commands and scheduled tasks in a single call and routes each to
+its registry by kind. The accepted union is exported as `Registerable`
+(`SlashCommand | EventDef | ComponentDef | ScheduledTask | PrefixCommand |
+ContextMenuCommand`). It returns the client for chaining.
+
+```ts
+import { SpearClient, command, event, button, option } from "spearkit";
+
+const client = new SpearClient();
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const ready = event("clientReady", (c) => {
+  console.log(`Logged in as ${c.user.tag}`); // c: Client<true>
+});
+
+const ping = button({
+  id: "ping:{n}",
+  label: "Ping",
+  run: (ctx) => ctx.reply(`pong #${ctx.params.n}`), // n: string
+});
+
+// Commands, events and components in one call.
+client.register(greet, ready, ping);
+```
+
+## Plugins
+
+`client.use(...plugins)` installs one or more plugins, awaiting each plugin's
+`setup`. It is async and returns the client.
+
+```ts
+import { SpearClient } from "spearkit";
+import { statsPlugin } from "./plugins/stats.js";
+
+const client = new SpearClient();
+await client.use(statsPlugin);
+```
+
+See [Plugins](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/plugins.md) for authoring `SpearPlugin`s.
+
+## File-based loading
+
+`client.load(dir, options?)` recursively imports a directory and registers every
+spearkit-registrable export it finds — commands, events, components, scheduled
+tasks and prefix commands. It returns the number of items registered.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+const count = await client.load("./src/commands");
+console.log(`Loaded ${count} handlers`);
+```
+
+See [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md) for the layout and `LoadOptions`.
+
+## Starting and deploying
+
+`client.start(token?)` logs in. If you omit the token it falls back to the
+`DISCORD_TOKEN` environment variable, and throws if neither is present.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+// Pass a token explicitly…
+await client.start("your-token");
+
+// …or set DISCORD_TOKEN and call start() with no argument.
+await client.start();
+```
+
+`client.deployCommands({ guildId })` pushes the registered slash commands to
+Discord using the client's own authenticated REST connection — there is no
+separate token or application id to supply. Because it reads the application id
+from the logged-in client, it **must run after the client is ready**. Pass a
+`guildId` to deploy instantly to a single guild (ideal for development); omit it
+to deploy globally.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+// …register commands…
+
+await client.start(); // uses DISCORD_TOKEN
+
+// Deploy once the client is ready.
+client.once("clientReady", async () => {
+  await client.deployCommands({ guildId: process.env.GUILD_ID });
+});
+```
+
+## Reliability: auto-defer and graceful shutdown
+
+A slow handler that doesn't respond within Discord's 3-second window dies with
+`Unknown interaction` (10062). Set `autoDefer` to have spearkit `deferReply()`
+automatically just before that window closes — per handler (`command({ autoDefer:
+true })`, `userCommand`/`messageCommand`) or for every slash + context-menu
+handler at once:
+
+```ts
+const client = new SpearClient({ autoDefer: true });
+// or { ephemeral: true, delayMs: 1500 } for a hidden defer / earlier fire.
+```
+
+With auto-defer on, respond via `ctx.send(...)` or `ctx.editReply(...)` — the
+initial reply slot may already be taken by the safety defer.
+
+`client.enableGracefulShutdown(options?)` closes the bot cleanly on `SIGINT` /
+`SIGTERM`: it runs an optional `onShutdown` hook, calls `destroy()` (stopping the
+scheduler and gateway), and exits, with a hard timeout so a wedged shutdown can't
+hang. It returns a disposer that removes the signal handlers.
+
+```ts
+client.enableGracefulShutdown({ onShutdown: () => db.close() });
+```
+
+## Everything discord.js still works
+
+`SpearClient` extends discord.js `Client`, so the full client surface is
+available unchanged. spearkit adds registries on top — it never hides what is
+underneath:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+client.on("guildCreate", (guild) => console.log(`Joined ${guild.name}`));
+client.ws.on("VOICE_SERVER_UPDATE", () => {});
+
+await client.start();
+
+console.log(client.application?.id); // application
+console.log(client.user?.tag); // user
+console.log(client.rest); // REST manager (used by deployCommands)
+
+await client.destroy(); // graceful shutdown
+```
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — defining slash commands you register here.
+- [Plugins](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/plugins.md) — bundling features for `client.use`.
+- [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md) — populating the client from a directory.
+
+---
+
+# Commands
+
+Slash commands in spearkit are defined as a single object: the metadata, the typed
+options, and the handler all live together. spearkit serialises them for discord
+and routes incoming interactions to the right handler for you.
+
+## A first command
+
+```ts
+import { command } from "spearkit";
+
+export const ping = command({
+  name: "ping",
+  description: "Check latency",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+Register it on a client (`client.register(ping)`) and deploy it (see
+[Deployment](#deployment)). That's the whole loop.
+
+## The command context
+
+The handler receives a `CommandContext`. It wraps the discord.js
+`ChatInputCommandInteraction` and adds ergonomic accessors and reply helpers.
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.options` | Resolved, fully-typed option values (see [Options](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/options.md)). |
+| `ctx.commandName` | The invoked command name. |
+| `ctx.subcommand` | The invoked subcommand name, or `null`. |
+| `ctx.showModal(modal)` | Present a modal in response. |
+| `ctx.user` / `ctx.member` / `ctx.guild` / `ctx.guildId` / `ctx.channel` / `ctx.channelId` / `ctx.locale` | Actor and location accessors. |
+| `ctx.reply` / `ctx.replyEphemeral` / `ctx.defer` / `ctx.editReply` / `ctx.followUp` / `ctx.send` / `ctx.error` | Reply helpers (see [Contexts](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md)). |
+| `ctx.interaction` | The raw discord.js interaction, for anything not wrapped. |
+
+```ts
+import { command, option } from "spearkit";
+
+export const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    times: option.integer({ description: "Repeat count", minValue: 1, maxValue: 5 }),
+  },
+  run: (ctx) => {
+    ctx.options.text;  // string
+    ctx.options.times; // number | undefined
+    return ctx.reply({
+      content: ctx.options.text.repeat(ctx.options.times ?? 1),
+      ephemeral: true,
+    });
+  },
+});
+```
+
+Options are covered in depth in [Options](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/options.md).
+
+## Command metadata
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export const purge = command({
+  name: "purge",
+  description: "Delete recent messages",
+  guildOnly: true,                                  // only usable in guilds
+  nsfw: false,                                      // age-restricted command
+  defaultMemberPermissions: PermissionFlagsBits.ManageMessages, // who sees it by default
+  nameLocalizations: { tr: "temizle" },             // localized name
+  descriptionLocalizations: { tr: "Mesajları sil" },
+  run: (ctx) => ctx.reply("…"),
+});
+```
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `guildOnly` | `boolean` | Restricts the command to guild contexts. |
+| `nsfw` | `boolean` | Marks the command age-restricted. |
+| `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate (members without it don't see the command). |
+| `nameLocalizations` / `descriptionLocalizations` | `LocalizationMap` | Per-locale name/description. |
+| `cooldown` | `number \| CooldownConfig` | Rate-limit the command (a number is milliseconds). See [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. See [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md). |
+| `autoDefer` | `boolean \| { ephemeral?, delayMs? }` | Auto-`deferReply()` if the handler is slow (>~2s), preventing `Unknown interaction`. Respond via `ctx.send`/`ctx.editReply`. |
+
+## Subcommands and groups
+
+For commands with subcommands, use `commandGroup` together with `subcommand`
+and (optionally) `subcommandGroup`. Each subcommand has its own typed options
+and handler; spearkit routes to the right one automatically.
+
+```ts
+import { commandGroup, subcommand, subcommandGroup, option } from "spearkit";
+
+export const admin = commandGroup({
+  name: "admin",
+  description: "Administration",
+  guildOnly: true,
+  // Direct subcommands: /admin say
+  subcommands: {
+    say: subcommand({
+      description: "Make the bot say something",
+      options: { message: option.string({ description: "Message", required: true }) },
+      run: (ctx) => ctx.reply(ctx.options.message),
+    }),
+  },
+  // Grouped subcommands: /admin users ban
+  groups: {
+    users: subcommandGroup({
+      description: "Manage users",
+      subcommands: {
+        ban: subcommand({
+          description: "Ban a member",
+          options: {
+            target: option.user({ description: "Member", required: true }),
+            reason: option.string({ description: "Reason" }),
+          },
+          run: (ctx) =>
+            ctx.reply(`Banned ${ctx.options.target.tag}: ${ctx.options.reason ?? "no reason"}`),
+        }),
+      },
+    }),
+  },
+});
+```
+
+Inside a subcommand handler, `ctx.options` is typed from *that subcommand's*
+options. There is no `switch (subcommand)` to write — spearkit dispatches by the
+invoked subcommand group/name.
+
+## The command registry
+
+`client.commands` is a `CommandRegistry`. You usually feed it through
+`client.register(...)`, but you can use it directly:
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry();
+registry.add(ping, echo, admin);
+
+registry.get("ping");   // SlashCommand | undefined
+registry.names;         // string[]
+registry.size;          // number
+registry.remove("ping"); // boolean
+registry.toJSON();      // REST payloads for all commands
+```
+
+`SpearClient` calls `registry.handle(interaction)` and
+`registry.handleAutocomplete(interaction)` for you on every interaction.
+
+### Error handling
+
+If a handler throws, spearkit catches it. By default it emits the client's `error`
+event and replies with an ephemeral "something went wrong" message. Override
+that:
+
+```ts
+client.commands.onError((error, interaction) => {
+  console.error(`/${interaction.commandName} failed`, error);
+  if (!interaction.replied && !interaction.deferred) {
+    return interaction.reply({ content: "Command failed.", ephemeral: true });
+  }
+});
+```
+
+## Deployment
+
+Commands must be registered with discord before they appear. spearkit gives you two
+ways.
+
+**From the client** (uses the client's authenticated REST; call after ready):
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId for global
+```
+
+**Standalone** (a separate deploy script, no running client needed):
+
+```ts
+import { CommandRegistry } from "spearkit";
+
+const registry = new CommandRegistry().add(ping, echo, admin);
+await registry.deploy({
+  token: process.env.DISCORD_TOKEN,
+  applicationId: process.env.DISCORD_APP_ID,
+  guildId: process.env.GUILD_ID, // optional
+});
+```
+
+Guild deploys apply **instantly** and are ideal during development. Global
+deploys (no `guildId`) can take up to an hour to propagate.
+
+## See also
+
+- [Options](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/options.md) — typed option builders, choices, autocomplete.
+- [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — buttons, selects, modals.
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — registering and deploying from the client.
+- [Contexts](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md) — the reply helpers every handler shares.
+- [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) — rate-limit a command with `cooldown`.
+- [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md) — gate a command with `guards`.
+
+---
+
+# Options
+
+Slash command options are declared as a map of name → builder. spearkit infers the
+exact value type each option resolves to, so your handler's `ctx.options` is
+fully typed — no casts, no `any`, no manual `getString` calls.
+
+```ts
+import { command, option } from "spearkit";
+
+command({
+  name: "profile",
+  description: "Show a profile",
+  options: {
+    user: option.user({ description: "Whose profile", required: true }),
+    detailed: option.boolean({ description: "Show extra detail" }),
+  },
+  run: (ctx) => {
+    ctx.options.user;     // User
+    ctx.options.detailed; // boolean | undefined
+  },
+});
+```
+
+## Builders and resolved types
+
+| Builder | Resolved type | Type-specific config |
+| ------- | ------------- | -------------------- |
+| `option.string(config)` | `string` | `choices`, `minLength`, `maxLength`, `autocomplete` |
+| `option.integer(config)` | `number` | `choices`, `minValue`, `maxValue`, `autocomplete` |
+| `option.number(config)` | `number` | `choices`, `minValue`, `maxValue`, `autocomplete` |
+| `option.boolean(config)` | `boolean` | — |
+| `option.user(config)` | `User` | — |
+| `option.channel(config)` | channel union | `channelTypes` |
+| `option.role(config)` | `Role \| APIRole` | — |
+| `option.mentionable(config)` | user / role / member | — |
+| `option.attachment(config)` | `Attachment` | — |
+
+Every builder accepts the common config:
+
+```ts
+{
+  description: string;                        // required
+  required?: boolean;                         // default: false
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+```
+
+## Inference rules
+
+spearkit narrows the resolved type from your declaration:
+
+```ts
+options: {
+  // required → the value type, never undefined
+  name: option.string({ description: "Name", required: true }),     // string
+
+  // optional (default) → value | undefined
+  age: option.integer({ description: "Age" }),                      // number | undefined
+
+  // choices → a literal union of the choice values
+  size: option.string({
+    description: "Size",
+    choices: [
+      { name: "Small", value: "sm" },
+      { name: "Large", value: "lg" },
+    ],
+  }),                                                               // "sm" | "lg" | undefined
+}
+```
+
+- **Required** options resolve to the value type.
+- **Optional** options resolve to `value | undefined` (spearkit converts discord's
+  absent value to `undefined`, never `null`).
+- **`choices`** narrow string/integer/number options to a literal union of the
+  declared `value`s.
+
+```ts
+run: (ctx) => {
+  const name: string = ctx.options.name;
+  const age: number | undefined = ctx.options.age;
+  const size: "sm" | "lg" | undefined = ctx.options.size;
+};
+```
+
+## Numeric and length constraints
+
+```ts
+options: {
+  count: option.integer({ description: "How many", minValue: 1, maxValue: 100 }),
+  code: option.string({ description: "Code", minLength: 4, maxLength: 8 }),
+}
+```
+
+## Channel options
+
+Restrict the selectable channel types with `channelTypes` (from discord.js
+`ChannelType`):
+
+```ts
+import { option, ChannelType } from "spearkit";
+
+options: {
+  target: option.channel({
+    description: "A text or announcement channel",
+    channelTypes: [ChannelType.GuildText, ChannelType.GuildAnnouncement],
+  }),
+}
+```
+
+## Choices
+
+`choices` are `{ name, value }` pairs. `name` is shown to the user; `value` is
+what your handler receives (and what spearkit narrows the type to).
+
+```ts
+option.integer({
+  description: "Priority",
+  choices: [
+    { name: "Low", value: 1 },
+    { name: "High", value: 2 },
+  ],
+  // optional per-choice localization:
+  // choices: [{ name: "Low", value: 1, nameLocalizations: { tr: "Düşük" } }],
+}); // 1 | 2 | undefined
+```
+
+## Autocomplete
+
+Provide an `autocomplete` handler instead of fixed `choices` to suggest values
+as the user types. spearkit marks the option as autocompletable, routes the
+autocomplete interaction, and (for subcommands) finds the right option.
+
+```ts
+const fruits = ["apple", "apricot", "banana", "cherry"];
+
+option.string({
+  description: "Fruit",
+  required: true,
+  autocomplete: (ctx) =>
+    fruits
+      .filter((f) => f.startsWith(ctx.value))
+      .map((f) => ({ name: f, value: f })),
+});
+```
+
+The autocomplete handler receives an `AutocompleteContext`:
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.value` | The current partial value typed by the user. |
+| `ctx.focusedName` | The name of the option being completed. |
+| `ctx.commandName` | The command being completed. |
+| `ctx.client` / `ctx.user` / `ctx.guild` / `ctx.guildId` | Accessors. |
+| `ctx.respond(choices)` | Send suggestions (capped at discord's 25). |
+
+Returning the choices array (as above) is enough — spearkit calls `respond` for
+you. Returning `[]` shows no suggestions.
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — using options inside commands and subcommands.
+- [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — buttons, selects and modals.
+
+---
+
+# Components
+
+Buttons, select menus and modals in spearkit follow one pattern: define the
+appearance, the **custom-id pattern**, and the handler in one place; register
+it; then `build()` the discord.js component to put in a message. spearkit decodes
+incoming interactions and routes them to your handler — no `interactionCreate`
+switch statements, no manual custom-id parsing.
+
+```ts
+import { button, row } from "spearkit";
+
+const vote = button({
+  id: "vote:{choice}",
+  label: "Yes",
+  style: "Success",
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // ctx.params.choice: string
+});
+
+client.register(vote); // or client.components.add(vote)
+
+await channel.send({
+  content: "Cast your vote:",
+  components: [row(vote.build({ choice: "yes" }))], // build() requires { choice }
+});
+```
+
+## Custom-id patterns
+
+The `id` is a pattern with the grammar `name` or `name:{param}` or
+`name:{a}:{b}`. The leading `name` is the routing **namespace**; each `{param}`
+becomes a positional value carried in the custom-id.
+
+- In the handler, params are available as a typed object: `ctx.params.choice`.
+- `build(params)` requires **exactly** those params and encodes them into the
+  custom-id.
+
+```ts
+const page = button({
+  id: "page:{id}:{dir}",
+  label: "Next",
+  run: (ctx) => ctx.update(`item ${ctx.params.id}, going ${ctx.params.dir}`),
+});
+
+page.build({ id: "42", dir: "next" }); // custom-id "page:42:next"
+```
+
+spearkit percent-escapes param values, so they may safely contain `:`. Custom-ids
+are limited to 100 characters (`MAX_CUSTOM_ID_LENGTH`); `build()` throws if you
+exceed it.
+
+For advanced use, the codec is exported directly: `compilePattern`,
+`buildCustomId`, `parseCustomId`, and `paramsFromValues`.
+
+## Buttons
+
+```ts
+import { button, linkButton, ButtonStyle } from "spearkit";
+
+const confirm = button({
+  id: "confirm:{action}",
+  label: "Confirm",
+  style: ButtonStyle.Danger,     // or the string "Danger"
+  emoji: "⚠️",
+  disabled: false,
+  run: (ctx) => ctx.update(`Confirmed: ${ctx.params.action}`),
+});
+
+// Link buttons have no handler and no custom-id:
+const docs = linkButton({ url: "https://example.com", label: "Docs" });
+```
+
+`style` accepts the string names `"Primary"`, `"Secondary"`, `"Success"`,
+`"Danger"`, or the `ButtonStyle` enum. It defaults to `"Secondary"`.
+
+All component builders (`button`, the five selects, and `modal`) also accept
+`guards?: readonly Guard[]` — preconditions evaluated before the handler runs.
+See [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md).
+
+The `ButtonContext` adds, on top of the shared [reply helpers](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md):
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.params` | Decoded custom-id params. |
+| `ctx.update(input)` | Edit the message the button is on. |
+| `ctx.deferUpdate()` | Acknowledge without editing yet. |
+| `ctx.showModal(modal)` | Open a modal in response. |
+| `ctx.message` | The message the button belongs to. |
+| `ctx.customId` | The raw custom-id. |
+
+## Select menus
+
+There are five select builders. All share `placeholder`, `minValues`,
+`maxValues`, and `disabled`; the string select additionally takes `options`,
+and the channel select takes `channelTypes`.
+
+```ts
+import { stringSelect, channelSelect, ChannelType } from "spearkit";
+
+const colour = stringSelect({
+  id: "colour",
+  placeholder: "Pick a colour",
+  minValues: 1,
+  maxValues: 1,
+  options: [
+    { label: "Red", value: "red" },
+    { label: "Green", value: "green", description: "the calm one" },
+    { label: "Blue", value: "blue", default: true },
+  ],
+  run: (ctx) => ctx.reply({ content: `You picked ${ctx.values.join(", ")}`, ephemeral: true }),
+});
+
+const pickChannel = channelSelect({
+  id: "pick-channel",
+  channelTypes: [ChannelType.GuildText],
+  run: (ctx) => ctx.reply({ content: `${ctx.values.length} channel(s)`, ephemeral: true }),
+});
+```
+
+Each select context exposes the relevant resolved data:
+
+| Builder | Context | Extra accessors |
+| ------- | ------- | --------------- |
+| `stringSelect` | `StringSelectContext` | `values: string[]`, `value: string \| undefined` |
+| `userSelect` | `UserSelectContext` | `values`, `users`, `members` |
+| `roleSelect` | `RoleSelectContext` | `values`, `roles` |
+| `channelSelect` | `ChannelSelectContext` | `values`, `channels` |
+| `mentionableSelect` | `MentionableSelectContext` | `values`, `users`, `roles`, `members` |
+
+Select contexts also have `ctx.params`, `ctx.update`, `ctx.deferUpdate`,
+`ctx.showModal`, and the shared reply helpers.
+
+## Modals
+
+A modal declares its `fields` as a map of name → `textInput`. The submit handler
+receives the submitted values in `ctx.fields`, keyed (and typed) by those names,
+plus any custom-id params in `ctx.params`.
+
+```ts
+import { modal, textInput } from "spearkit";
+
+const feedback = modal({
+  id: "feedback:{ticket}",
+  title: "Feedback",
+  fields: {
+    summary: textInput({ label: "Summary", required: true }),
+    detail: textInput({ label: "Details", style: "Paragraph", maxLength: 2000 }),
+  },
+  run: (ctx) =>
+    ctx.reply({
+      // ctx.params.ticket: string, ctx.fields.summary / ctx.fields.detail: string
+      content: `#${ctx.params.ticket}: ${ctx.fields.summary}`,
+      ephemeral: true,
+    }),
+});
+```
+
+`textInput` config: `label` (required), `style` (`"Short"` default, or
+`"Paragraph"`, or a `TextInputStyle`), `placeholder`, `required`, `minLength`,
+`maxLength`, `value`.
+
+Open a modal from a command or a component handler with `showModal` — modals
+cannot be the *response* to another modal, but they can follow a command or a
+button/select:
+
+```ts
+import { command } from "spearkit";
+
+const ask = command({
+  name: "ask",
+  description: "Open the feedback form",
+  run: (ctx) => ctx.showModal(feedback.build({ ticket: "1234" })),
+});
+```
+
+## Action rows
+
+`row(...components)` wraps builders in an `ActionRowBuilder`. A row holds up to
+five buttons, or exactly one select menu.
+
+```ts
+import { row } from "spearkit";
+
+const components = [
+  row(confirm.build({ action: "delete" }), docs),
+  row(colour.build()),
+];
+await channel.send({ content: "Choose:", components });
+```
+
+## Registering and routing
+
+Register components like anything else:
+
+```ts
+client.register(vote, colour, feedback);
+// equivalently:
+client.components.add(vote, colour, feedback);
+```
+
+`SpearClient` routes every button, select and modal interaction to the matching
+namespace automatically. The `ComponentRegistry` API:
+
+| Member | Description |
+| ------ | ----------- |
+| `add(...defs)` | Register components (override by namespace). |
+| `size` | Number registered. |
+| `onError(handler)` | Set the error handler. |
+| `handle(interaction)` | Route an interaction; returns `true` if matched. |
+| `setDefaultGuards(guards)` | Guards run before each component's own guards. |
+
+`setLogger` and `setUsageHook` also exist; the client wires all three for you.
+
+### Error handling
+
+By default a throwing handler emits the client `error` event and replies with an
+ephemeral message. Customise it:
+
+```ts
+client.components.onError((error, interaction) => {
+  console.error("component failed", error);
+});
+```
+
+## End-to-end example
+
+```ts
+import {
+  SpearClient,
+  Intents,
+  command,
+  button,
+  stringSelect,
+  modal,
+  textInput,
+  row,
+} from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const open = button({
+  id: "open-form:{topic}",
+  label: "Open form",
+  style: "Primary",
+  run: (ctx) => ctx.showModal(form.build({ topic: ctx.params.topic })),
+});
+
+const rating = stringSelect({
+  id: "rating",
+  placeholder: "Rate us",
+  options: [
+    { label: "Good", value: "good" },
+    { label: "Bad", value: "bad" },
+  ],
+  run: (ctx) => ctx.reply({ content: `Thanks: ${ctx.value}`, ephemeral: true }),
+});
+
+const form = modal({
+  id: "form:{topic}",
+  title: "Tell us more",
+  fields: { body: textInput({ label: "Message", style: "Paragraph", required: true }) },
+  run: (ctx) => ctx.reply({ content: `[${ctx.params.topic}] ${ctx.fields.body}`, ephemeral: true }),
+});
+
+const panel = command({
+  name: "panel",
+  description: "Show the panel",
+  run: (ctx) =>
+    ctx.reply({
+      content: "How was it?",
+      components: [row(open.build({ topic: "support" })), row(rating.build())],
+    }),
+});
+
+client.register(panel, open, rating, form);
+```
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — opening components from commands.
+- [Contexts](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md) — the reply/update helpers contexts share.
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — registration and routing.
+
+---
+
+# Context-menu commands
+
+Context-menu commands are the right-click **"Apps"** actions Discord shows on a
+user or a message. spearkit makes them first-class: define one with `userCommand`
+or `messageCommand`, register it like anything else, and deploy it alongside your
+slash commands. The handler gets a typed `targetUser` or `targetMessage`.
+
+```ts
+import { userCommand } from "spearkit";
+
+export const whois = userCommand({
+  name: "Who is this?",
+  run: (ctx) => ctx.replyEphemeral(`That's ${ctx.targetUser.tag}.`),
+});
+```
+
+`name` is the label shown in the Apps menu (no description — Discord does not show
+one for context-menu commands).
+
+## User vs message commands
+
+| Builder | Appears on | Target context |
+| ------- | ---------- | -------------- |
+| `userCommand` | a user (right-click → Apps) | `ctx.targetUser`, `ctx.targetMember` |
+| `messageCommand` | a message (right-click → Apps) | `ctx.targetMessage` |
+
+```ts
+import { messageCommand } from "spearkit";
+
+export const report = messageCommand({
+  name: "Report message",
+  run: (ctx) =>
+    ctx.replyEphemeral(`Reported message ${ctx.targetMessage.id}.`),
+});
+```
+
+Both handler contexts extend the shared [`BaseContext`](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md), so
+`ctx.reply`, `ctx.replyEphemeral`, `ctx.defer`, `ctx.success/error/...` and the
+usual accessors are all available.
+
+## Metadata, cooldowns and guards
+
+Both builders accept the same metadata, plus a `cooldown` and `guards`:
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `name` | `string` | The Apps-menu label. |
+| `defaultMemberPermissions` | `PermissionResolvable \| null` | Default permission gate. |
+| `nsfw` | `boolean` | Marks the command age-restricted. |
+| `guildOnly` | `boolean` | Restricts it to guild contexts. |
+| `nameLocalizations` | `LocalizationMap` | Per-locale label. |
+| `cooldown` | `number \| CooldownConfig` | Rate limit (shares `client.cooldowns`). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. |
+| `autoDefer` | `boolean \| { ephemeral?, delayMs? }` | Auto-`deferReply()` if the handler is slow, preventing `Unknown interaction`. |
+
+```ts
+import { userCommand, guildOnly, requireUserPermissions, PermissionFlagsBits } from "spearkit";
+
+export const warn = userCommand({
+  name: "Warn user",
+  guildOnly: true,
+  cooldown: 5_000,
+  guards: [requireUserPermissions(PermissionFlagsBits.ModerateMembers)],
+  run: (ctx) => ctx.replyEphemeral(`Warned ${ctx.targetUser.tag}.`),
+});
+```
+
+See [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) and [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md) for the shared options.
+
+## Registering and deploying
+
+Register context-menu commands like everything else with `client.register(...)`.
+They route automatically — spearkit dispatches user- and message-context-menu
+interactions to the matching command.
+
+```ts
+client.register(whois, report, warn);
+```
+
+Because context menus and slash commands deploy to the same Discord endpoint,
+push them together with `deployAllCommands` once you mix the two — it sends both
+in a single request. (`deployCommands` is slash-only.)
+
+```ts
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployAllCommands({ guildId: process.env.GUILD_ID }); // slash + menus
+```
+
+`deployAllCommands` also supports a `dryRun` flag and a `strategy: "diff"` that
+skips the PUT when the remote set already matches — handy in CI:
+
+```ts
+// Preview without touching Discord:
+const result = await client.deployAllCommands({ guildId, dryRun: true });
+// → { skipped: true, reason: "dry-run", body: [...] }
+
+// Only deploy when something changed:
+await client.deployAllCommands({ guildId, strategy: "diff" });
+```
+
+## The registry
+
+`client.contextMenus` is a `ContextMenuRegistry`. The client wires it to the
+logger and cooldown manager and routes interactions for you, so you rarely touch
+it directly:
+
+```ts
+client.contextMenus.size;   // number registered
+client.contextMenus.all();  // ContextMenuCommand[]
+client.contextMenus.toJSON(); // REST payloads (also included by deployAllCommands)
+```
+
+Note: context-menu commands are **not** picked up by `client.load(...)`
+directory loading — register them explicitly with `client.register(...)`.
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — slash commands.
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — `deployAllCommands` and registration.
+- [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md) / [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) — the shared preconditions.
+- [Contexts](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context.md) — the reply helpers every handler shares.
+
+---
+
+# Events
+
+`event()` defines a reusable, loadable discord.js event listener with a
+fully-typed handler. The handler's arguments are inferred from discord.js'
+`ClientEvents`, so you never annotate them by hand. Register an event with the
+client and spearkit attaches the listener for you.
+
+```ts
+import { event } from "spearkit";
+
+export default event("messageCreate", (message) => {
+  if (message.author.bot) return;
+  // message is fully typed as Message
+});
+```
+
+## Defining an event
+
+`event` has two forms. The positional form takes the event name and handler:
+
+```ts
+import { event } from "spearkit";
+
+const onMessage = event("messageCreate", (message) => {
+  // message: Message
+  console.log(message.content);
+});
+
+const onReady = event("clientReady", (client) => {
+  // client: Client<true> — the ready client
+  console.log(`Logged in as ${client.user.tag}`);
+});
+```
+
+The object form (`EventConfig`) additionally accepts `once`, which runs the
+handler at most once and then auto-detaches:
+
+```ts
+import { event } from "spearkit";
+
+const onceReady = event({
+  name: "clientReady",
+  once: true,
+  run: (client) => {
+    // client: Client<true>
+    console.log(`Ready as ${client.user.tag}`);
+  },
+});
+```
+
+Both forms return an `EventDef` — a type-erased, ready-to-attach listener
+(`{ name, once, attach, detach }`). Register it like anything else:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+client.register(onMessage, onReady);
+```
+
+### Handlers are fully typed from `ClientEvents`
+
+The event name drives the parameter types. There is nothing to import or
+annotate — picking `"messageCreate"` types the argument as `Message`, picking
+`"guildMemberAdd"` types it as `GuildMember`, and so on. The handler type is
+exported as `EventHandler<E>` (`(...args: ClientEvents[E]) => Awaitable<void>`).
+
+```ts
+import { event } from "spearkit";
+
+const onJoin = event("guildMemberAdd", (member) => {
+  // member: GuildMember
+  void member.roles.add("123456789012345678");
+});
+
+const onReaction = event("messageReactionAdd", (reaction, user) => {
+  // reaction: MessageReaction | PartialMessageReaction
+  // user: User | PartialUser
+  console.log(`${user.id} reacted with ${reaction.emoji.name}`);
+});
+```
+
+### Intents are required
+
+An event only fires if the client connected with the matching gateway intents.
+For example, `messageCreate` with message content needs `Intents.messages` (or
+at least the `GuildMessages` / `MessageContent` bits); `guildMemberAdd` needs
+`GuildMembers`. See [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) for the intent presets.
+
+## Errors are routed, not fatal
+
+If a handler throws synchronously or rejects a returned promise, spearkit catches
+it and emits it on the client's `error` event instead of crashing the process.
+Listen for `error` to log or report failures centrally:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+client.on("error", (err) => {
+  console.error("A handler failed:", err);
+});
+```
+
+## Inline listeners still work
+
+Because spearkit re-exports discord.js, the plain `client.on(...)` / `client.once(...)`
+listeners work exactly as before — they are the same methods. Reach for them for
+quick, inline, client-local listeners:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+client.on("guildCreate", (guild) => console.log(`Joined ${guild.name}`));
+```
+
+Use `event()` when you want a listener that is **reusable and loadable** — a
+self-contained module you can export, register from anywhere, or pick up via
+`client.load(...)`. Note that inline `client.on` listeners do **not** get the
+automatic error-routing that `event()` handlers do.
+
+## The `EventRegistry`
+
+`client.events` is an `EventRegistry`. The client attaches it automatically at
+construction and again when you `register` an event, so you usually never call
+its methods directly. They are available for advanced control:
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `add(...defs)` | `this` | Register one or more `EventDef`s (and attach them to already-attached clients). |
+| `size` | `number` | Number of registered listeners. |
+| `attachAll(client)` | `void` | Attach every registered listener to a client. |
+| `detachAll(client)` | `void` | Detach every registered listener from a client. |
+
+```ts
+import { SpearClient, event } from "spearkit";
+
+const client = new SpearClient();
+client.events.add(event("warn", (info) => console.warn(info)));
+
+console.log(client.events.size); // 1
+
+// Detach all spearkit-managed listeners (e.g. before a hot reload).
+client.events.detachAll(client);
+```
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — registering events and the required intents.
+- [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md) — one event per file, auto-registered.
+
+---
+
+# Contexts
+
+Every spearkit handler — command, button, select, modal — receives a context
+object. They all share `BaseContext`, which smooths over discord.js'
+reply/defer/edit/follow-up state machine and exposes the common
+actor/location accessors. Learn it once and it applies everywhere.
+
+```ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "hello",
+  description: "Say hello",
+  options: { name: option.string({ description: "Name", required: true }) },
+  run: (ctx) => ctx.reply(`Hi, ${ctx.options.name}!`),
+});
+```
+
+`CommandContext`, `ButtonContext`, `StringSelectContext`, modal contexts and the
+rest extend `BaseContext`, adding their own specifics (e.g. `ctx.options`,
+`ctx.params`, `ctx.fields`) on top of everything below.
+
+## Reply helpers
+
+| Method | Returns | Behaviour |
+| ------ | ------- | --------- |
+| `reply(input)` | `Promise<InteractionResponse>` | Send the initial response. |
+| `replyEphemeral(input)` | `Promise<InteractionResponse>` | Reply, hidden to everyone but the invoking user. |
+| `defer({ ephemeral })` | `Promise<InteractionResponse>` | Acknowledge now, respond later via `editReply`. |
+| `editReply(input)` | `Promise<Message>` | Edit the original (or deferred) response. |
+| `followUp(input)` | `Promise<Message>` | Add a message after the initial response. |
+| `send(input)` | `Promise<void>` | State-aware: replies, edits, or follows up automatically. |
+| `error(input, options?)` | `Promise<void>` | State-aware preset error embed; ephemeral by default. |
+| `success` / `info` / `warn` `(input, options?)` | `Promise<void>` | State-aware preset embeds. |
+| `replyError` / `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `Promise<InteractionResponse>` | Initial-reply preset embeds. |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "demo",
+  description: "Reply helpers",
+  run: async (ctx) => {
+    await ctx.reply("Working on it…");
+    await ctx.followUp("…almost done.");
+  },
+});
+```
+
+### `send` is the one most handlers need
+
+`send` inspects the interaction state and does the right thing:
+
+- not yet answered → `reply`
+- already deferred → `editReply`
+- already replied → `followUp`
+
+This means you can call `send` without tracking whether you deferred, which is
+ideal for shared helpers that may run before or after a `defer`.
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "report",
+  description: "Generate a report",
+  run: async (ctx) => {
+    await ctx.defer(); // acknowledge while we do slow work
+    const data = await buildReport();
+    await ctx.send(data); // sees the deferred state → edits the reply
+  },
+});
+```
+
+### `error` for ephemeral failures
+
+`error(input, options?)` sends a state-aware preset **error embed** — ephemeral
+by default (pass `{ ephemeral: false }` to make it public) — perfect for
+validation failures that only the invoking user should see.
+
+```ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "kick",
+  description: "Kick a member",
+  options: { who: option.user({ description: "Member", required: true }) },
+  run: async (ctx) => {
+    if (!ctx.guild) return ctx.error("This command only works in a server.");
+    await ctx.reply(`Kicked ${ctx.options.who}.`);
+  },
+});
+```
+
+## Preset embeds
+
+`BaseContext` builds consistent, colored embeds from `client.embeds` (or a shared
+default). Each takes an `EmbedPresetInput` — a plain string, or a structured body
+(`{ title?, description?, fields?, footer?, ... }`) — and an optional
+`{ ephemeral? }`.
+
+| Method | Sends via | Default visibility |
+| ------ | --------- | ------------------ |
+| `success(input, options?)` | `send` (state-aware) | public |
+| `info(input, options?)` | `send` (state-aware) | public |
+| `warn(input, options?)` | `send` (state-aware) | public |
+| `error(input, options?)` | `send` (state-aware) | **ephemeral** |
+| `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `reply` (initial only) | public |
+| `replyError(input, options?)` | `reply` (initial only) | **ephemeral** |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "save",
+  description: "Save settings",
+  run: async (ctx) => {
+    await ctx.success("Settings saved.");            // green embed, public
+    await ctx.warn({ title: "Heads up", description: "Quota is almost full." });
+    // error defaults to ephemeral; make it public with { ephemeral: false }:
+    // await ctx.error("Failed to save.", { ephemeral: false });
+  },
+});
+```
+
+Configure the colors/icons with the client `embeds` option; see the
+[API reference](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md#embeds--preset-replies).
+
+## The `{ ephemeral: true }` shortcut
+
+discord.js represents an ephemeral reply with `flags: MessageFlags.Ephemeral`.
+spearkit lets you write the more obvious `{ ephemeral: true }` on any reply payload
+and maps it to that flag for you. The input type is `ReplyInput`
+(`string | ReplyData`), where `ReplyData` is discord.js'
+`InteractionReplyOptions` plus the optional `ephemeral` boolean.
+
+```ts
+import { command, EmbedBuilder } from "spearkit";
+
+export default command({
+  name: "secret",
+  description: "Only you can see this",
+  run: (ctx) =>
+    ctx.reply({
+      embeds: [new EmbedBuilder().setTitle("Just for you")],
+      ephemeral: true, // mapped to MessageFlags.Ephemeral
+    }),
+});
+```
+
+`replyEphemeral(input)` is sugar for the same thing, accepting either a string
+or a payload:
+
+```ts
+await ctx.replyEphemeral("Saved.");
+await ctx.replyEphemeral({ embeds: [embed] });
+```
+
+If you set `flags` yourself, spearkit preserves them and adds the ephemeral flag
+rather than overwriting it.
+
+### Exported helpers
+
+spearkit exports the two functions it uses internally, so you can normalise reply
+input yourself (e.g. in a plugin or shared utility):
+
+- `normalizeReply(input: ReplyInput): InteractionReplyOptions` — converts a
+  string or `ReplyData` into a discord.js reply payload, applying the ephemeral
+  flag mapping.
+- `asEphemeral(input: ReplyInput): ReplyData` — marks any input ephemeral,
+  regardless of how it was passed.
+
+```ts
+import { normalizeReply, asEphemeral } from "spearkit";
+
+normalizeReply("hi");
+// → { content: "hi" }
+
+normalizeReply({ content: "hi", ephemeral: true });
+// → { content: "hi", flags: MessageFlags.Ephemeral }
+
+asEphemeral("hidden");
+// → { content: "hidden", ephemeral: true }
+```
+
+## Accessors
+
+`BaseContext` forwards the common interaction fields so you do not reach through
+`ctx.interaction` for everyday data:
+
+| Accessor | Description |
+| -------- | ----------- |
+| `interaction` | The raw discord.js interaction. |
+| `client` | The `SpearClient` (typed as the interaction's client). |
+| `user` | The invoking `User`. |
+| `member` | The invoking guild member (or `null` outside a guild). |
+| `guild` | The `Guild`, or `null` in DMs. |
+| `guildId` | The guild id, or `null`. |
+| `channel` | The channel the interaction came from. |
+| `channelId` | The channel id. |
+| `locale` | The user's locale. |
+| `deferred` | Whether the interaction is already deferred. |
+| `replied` | Whether the interaction already received an initial response. |
+| `botPermissions` | The bot's resolved permissions in the channel (`PermissionsBitField`, zero-fetch). |
+
+```ts
+import { command } from "spearkit";
+
+export default command({
+  name: "whereami",
+  description: "Report context",
+  run: (ctx) =>
+    ctx.reply(
+      ctx.guild
+        ? `In ${ctx.guild.name} (#${ctx.channelId}), locale ${ctx.locale}.`
+        : "We're in a DM.",
+    ),
+});
+```
+
+`deferred` and `replied` let you branch when you are not using `send`:
+
+```ts
+import { button } from "spearkit";
+
+export default button({
+  id: "refresh",
+  label: "Refresh",
+  run: async (ctx) => {
+    if (ctx.replied || ctx.deferred) await ctx.followUp("Refreshed.");
+    else await ctx.reply("Refreshed.");
+  },
+});
+```
+
+## Permission preflights
+
+`BaseContext` reads the permissions Discord already attached to the interaction —
+no extra fetches — so you can check before attempting a privileged action:
+
+```ts
+import { command, PermissionFlagsBits } from "spearkit";
+
+export default command({
+  name: "slowmode",
+  description: "Set slowmode",
+  run: async (ctx) => {
+    const missing = ctx.botMissing(PermissionFlagsBits.ManageChannels);
+    if (missing.length > 0) return ctx.error(`I'm missing: ${missing.join(", ")}`);
+    // …apply slowmode…
+  },
+});
+```
+
+- `ctx.botPermissions` — the bot's `PermissionsBitField` in the current channel.
+- `ctx.botMissing(required)` — permission names the bot lacks here (`[]` if none).
+- `ctx.userMissing(required)` — permission names the invoking user lacks here.
+
+For role-hierarchy and moderation preflights (acting on self/owner, comparing top
+roles) see `moderationCheck` and the permission helpers in the
+[API reference](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md#permissions--moderation).
+
+## Awaiting input
+
+When a flow needs a follow-up message or a modal, the context wraps discord.js
+collectors so you skip the boilerplate. Both resolve to `null` on timeout.
+
+```ts
+import { command, modal, textInput } from "spearkit";
+
+const nameModal = modal({ id: "name", title: "Your name", fields: { name: textInput({ label: "Name" }) }, run: () => {} });
+
+export default command({
+  name: "setup",
+  description: "Interactive setup",
+  run: async (ctx) => {
+    // Wait for the user to type an answer in this channel:
+    const reply = await ctx.awaitMessageFrom(ctx.user.id, { time: 30_000 });
+    if (reply === null) return ctx.error("Timed out.");
+    // Or show a modal and await its submission:
+    const submission = await ctx.awaitModal(nameModal);
+    if (submission !== null) await submission.reply(`Hi, ${submission.fields.getTextInputValue("name")}!`);
+  },
+});
+```
+
+The standalone `awaitMessage`, `awaitComponent` and `showAndAwaitModal` helpers
+are also exported; see the [API reference](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md#collectors).
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — `CommandContext`, options and `showModal`.
+- [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — button, select and modal contexts.
+
+---
+
+# Guards
+
+Guards are declarative **preconditions** that run before a handler. They work
+uniformly across slash commands, components (buttons, selects, modals), prefix
+commands and context-menu commands — and can also be applied client-wide. A
+guard returns `true` to allow the handler, or a denial (with an optional reason)
+to block it; spearkit replies with the reason and the handler never runs.
+
+```ts
+import { command, requireUserPermissions, PermissionFlagsBits } from "spearkit";
+
+export const purge = command({
+  name: "purge",
+  description: "Bulk-delete messages",
+  guards: [requireUserPermissions(PermissionFlagsBits.ManageMessages)],
+  run: (ctx) => ctx.reply("Purged."),
+});
+```
+
+## Where guards attach
+
+Pass `guards: [...]` to any handler definition, or set client-wide defaults that
+run before every handler's own guards.
+
+```ts
+import {
+  SpearClient,
+  command,
+  button,
+  prefixCommand,
+  userCommand,
+  guildOnly,
+} from "spearkit";
+
+// Per-handler — on commands, components, prefix and context-menu commands.
+command({ name: "kick", description: "…", guards: [guildOnly()], run: () => {} });
+button({ id: "del:{id}", guards: [guildOnly()], run: () => {} });
+prefixCommand({ name: "ban", guards: [guildOnly()], run: () => {} });
+userCommand({ name: "Report", guards: [guildOnly()], run: () => {} });
+
+// Client-wide — applied before each handler's own guards.
+const client = new SpearClient({ guards: [guildOnly()] });
+```
+
+Client-wide guards run first; if they pass, the handler's own guards run next.
+The first denial short-circuits the rest.
+
+## Built-in guards
+
+Each built-in returns a `Guard` and accepts an optional custom `reason`. When
+omitted, a sensible default message is used (shown below).
+
+| Guard | Denies unless… | Default reason |
+| ----- | -------------- | -------------- |
+| `guildOnly(reason?)` | used inside a guild | `"This can only be used in a server."` |
+| `dmOnly(reason?)` | used in a DM | `"This can only be used in DMs."` |
+| `requireAnyRole(roleIds, reason?)` | the member holds **any** of `roleIds` | `"You don't have permission to use this."` |
+| `requireAllRoles(roleIds, reason?)` | the member holds **every** id in `roleIds` | `"You're missing one of the required roles."` |
+| `requireOwner(ownerIds, reason?)` | the user id is in `ownerIds` | `"This is owner-only."` |
+| `requireUserPermissions(permission, reason?)` | the member has the Discord `permission` | `"You don't have permission to use this."` |
+| `requireBotPermissions(permission, reason?)` | the bot's member has the Discord `permission` | `"I don't have permission to do that here."` |
+
+```ts
+import {
+  command,
+  requireAnyRole,
+  requireBotPermissions,
+  PermissionFlagsBits,
+} from "spearkit";
+
+export const announce = command({
+  name: "announce",
+  description: "Post an announcement",
+  guards: [
+    requireAnyRole(["111111111111111111"], "Staff only."),
+    requireBotPermissions(PermissionFlagsBits.SendMessages),
+  ],
+  run: (ctx) => ctx.reply("Announced."),
+});
+```
+
+## Custom guards
+
+`guard(predicate)` wraps an inline predicate so a one-off check still types as a
+`Guard`. The predicate receives a `GuardContext` and returns a `GuardResult`;
+use `denied(reason?)` to build a denial.
+
+```ts
+import { command, guard, denied } from "spearkit";
+
+const cooldownOver = guard((ctx) =>
+  isReady(ctx.user.id) ? true : denied("Still warming up — try again soon."),
+);
+
+export const cast = command({
+  name: "cast",
+  description: "Cast a spell",
+  guards: [cooldownOver],
+  run: (ctx) => ctx.reply("✨"),
+});
+```
+
+`GuardContext` exposes the actor/location fields every handler shares, so the
+same guard works on commands, components, prefix and context-menu handlers:
+
+```ts
+interface GuardContext {
+  client: Client;
+  user: User;
+  member: GuildMember | APIInteractionGuildMember | null;
+  guild: Guild | null;
+  guildId: string | null;
+  channelId: string | null;
+}
+
+type GuardResult = boolean | { allowed: false; reason?: string };
+type Guard<TCtx extends GuardContext = GuardContext> = (ctx: TCtx) => Awaitable<GuardResult>;
+```
+
+## Running guards manually
+
+`runGuards(ctx, guards)` evaluates a list in order and short-circuits on the
+first denial — useful if you build your own dispatch on top of spearkit.
+
+```ts
+import { runGuards, guildOnly } from "spearkit";
+
+const result = await runGuards(ctx, [guildOnly()]);
+if (!result.allowed) {
+  // result.reason is the denial message (or undefined)
+}
+```
+
+`runGuards` resolves to `RunGuardsResult`:
+
+```ts
+type RunGuardsResult = { allowed: true } | { allowed: false; reason: string | undefined };
+```
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — `guards` on slash commands.
+- [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — `guards` on buttons, selects and modals.
+- [Prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md) — `guards` on text commands.
+- [Context menus](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context-menus.md) — `guards` on "Apps" actions.
+- [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) — the other built-in precondition.
+
+---
+
+# Permissions & hierarchy
+
+Moderation commands fail in two predictable ways: the bot lacks a permission in
+the channel (`Missing Permissions`, 50013), or the target sits above the bot (or
+the moderator) in the role list. Both are checkable *before* you act, so you can
+bail out with a clear message instead of a half-finished action and an exception.
+
+## Did the bot/user get the permissions? (zero-fetch)
+
+Every interaction carries the bot's and the invoker's resolved permissions for
+the current channel. `ctx.botMissing(...)` / `ctx.userMissing(...)` read them
+with no API calls and return the **missing** flag names:
+
+```ts
+import { PermissionFlagsBits, command, formatPermissions } from "spearkit";
+
+export const slowmode = command({
+  name: "slowmode",
+  description: "Set channel slowmode",
+  run: async (ctx) => {
+    const missing = ctx.botMissing(PermissionFlagsBits.ManageChannels);
+    if (missing.length > 0) return ctx.error(`I need: ${formatPermissions(missing)}`);
+    // …
+  },
+});
+```
+
+`formatPermissions(...)` renders flag names as a friendly list
+(`"Manage Channels, Ban Members"`).
+
+## Permissions in another channel
+
+For a channel other than the current one, use the standalone helpers:
+
+```ts
+import { botMissingPermissions, hasPermissions, missingPermissions } from "spearkit";
+
+const missing = botMissingPermissions(targetChannel, [PermissionFlagsBits.SendMessages]);
+if (missing.length > 0) return ctx.error("I can't post there.");
+
+// or for a specific member/role:
+hasPermissions(targetChannel, member, PermissionFlagsBits.ViewChannel); // boolean
+missingPermissions(targetChannel, role, [PermissionFlagsBits.Connect]); // PermissionsString[]
+```
+
+## Role hierarchy
+
+`moderationCheck(...)` validates both the moderator and the bot against a target,
+returning a ready-to-show reason on the first failing rule (self, server owner,
+moderator hierarchy, bot hierarchy):
+
+```ts
+import { moderationCheck } from "spearkit";
+
+const moderator = await ctx.guild!.members.fetch(ctx.user.id);
+const check = moderationCheck({ moderator, target, action: "ban" });
+if (!check.ok) return ctx.error(check.reason);
+await target.ban();
+```
+
+The `me` (bot) member defaults to `target.guild.members.me`; pass `me: null` to
+skip the bot check. `action` is the verb used in messages (default `"moderate"`).
+
+Lower-level primitives are exported too:
+
+- `canActOn(actor, target)` — boolean: not self, target isn't the owner, actor is
+  the owner or outranks the target.
+- `compareRoles(a, b)` — highest-role position comparison (`>0`, `<0`, `0`).
+
+---
+
+# Auto-defer
+
+The single most common discord.js error is
+`DiscordAPIError[10062]: Unknown interaction`. An interaction token is valid for
+only **3 seconds** before your first response; any handler that awaits a database
+query or an HTTP call risks blowing past that window, after which the interaction
+is dead and every reply throws.
+
+Auto-defer removes the footgun: spearkit arms a timer when your handler starts
+and, if you haven't responded in time, calls `deferReply()` for you. The timer is
+cancelled the instant your handler replies or defers itself.
+
+## Per command
+
+```ts
+import { command, option } from "spearkit";
+
+export const weather = command({
+  name: "weather",
+  description: "Look up the weather",
+  autoDefer: true, // defers automatically if the handler takes too long
+  options: { city: option.string({ description: "City", required: true }) },
+  run: async (ctx) => {
+    const report = await fetchWeather(ctx.options.city); // slow
+    await ctx.send(`Weather in ${ctx.options.city}: ${report}`);
+  },
+});
+```
+
+> With auto-defer on, respond via `ctx.send(...)` or `ctx.editReply(...)`, not
+> `ctx.reply(...)` — the initial reply slot may already be taken by the
+> auto-defer. `ctx.send` is state-aware and always does the right thing.
+
+## Options
+
+`autoDefer` accepts `true` (defaults) or an object:
+
+```ts
+command({
+  name: "report",
+  description: "Generate a report",
+  autoDefer: { ephemeral: true, delayMs: 1500 },
+  run: async (ctx) => ctx.send("…"),
+});
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `ephemeral` | `false` | Defer as a hidden ("thinking…") response. |
+| `delayMs` | `2000` | How long to wait before the safety defer fires. Kept under the 3s cutoff. |
+
+## Client-wide default
+
+Apply auto-defer to **every** slash command and context menu; each handler can
+still override with its own `autoDefer`.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ autoDefer: true });
+```
+
+## Scope
+
+Auto-defer covers slash commands and context menus (answered with `deferReply`).
+Component handlers (buttons/selects) usually respond instantly with `update`, so
+they're not auto-deferred — call `ctx.deferUpdate()` yourself if a component
+handler does slow work.
+
+## Lower-level helpers
+
+`normalizeAutoDefer(input)` resolves `true`/object/`undefined` into an
+`AutoDeferConfig`; `armAutoDefer(interaction, config)` arms the timer and returns
+a cancel function. Both are exported for custom dispatch.
+
+---
+
+# Cooldowns
+
+Rate-limit commands per user, per guild, per channel, or globally — with per-role
+and per-user exemptions and overrides.
+Cooldowns are enforced automatically by command dispatch: when an actor is
+still on cooldown, spearkit replies (ephemerally) with a message and the
+handler does not run.
+
+## Per-command
+
+Pass a number (milliseconds) or a full config to any command:
+
+```ts
+import { command } from "spearkit";
+
+export const daily = command({
+  name: "daily",
+  description: "Claim your daily reward",
+  cooldown: 86_400_000, // once per day, per user
+  run: (ctx) => ctx.reply("Reward claimed!"),
+});
+```
+
+## Client-wide default
+
+A default applies to every command; a command's own `cooldown` overrides it.
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ cooldown: { duration: 3000 } });
+```
+
+## Scope
+
+`scope` controls what the cooldown is keyed on. Default `"user"`.
+
+```ts
+command({
+  name: "announce",
+  description: "Post an announcement",
+  cooldown: { duration: 60_000, scope: "guild" }, // one per guild per minute
+  run: (ctx) => ctx.reply("Announced."),
+});
+```
+
+| Scope | Keyed on |
+| --- | --- |
+| `user` | the invoking user (default) |
+| `guild` | the guild |
+| `channel` | the channel |
+| `global` | everyone shares one bucket |
+
+## Exemptions — who waits and who doesn't
+
+`exempt` lists users and roles that bypass the cooldown entirely.
+
+```ts
+command({
+  name: "purge",
+  description: "Bulk delete",
+  cooldown: {
+    duration: 10_000,
+    exempt: { roles: ["111111111111111111"], users: ["222222222222222222"] },
+  },
+  run: (ctx) => ctx.reply("Purged."),
+});
+```
+
+## Per-role / per-user overrides
+
+`overrides` gives specific roles or users a different duration (milliseconds).
+A user override beats role overrides; among matching roles the most lenient
+(shortest) duration wins. Use `0` to effectively disable the wait for them.
+
+```ts
+command({
+  name: "search",
+  description: "Search the archive",
+  cooldown: {
+    duration: 10_000, // everyone else
+    overrides: {
+      roles: { "333333333333333333": 2_000 }, // VIP role: 2s
+      users: { "444444444444444444": 0 }, // this user: no wait
+    },
+  },
+  run: (ctx) => ctx.reply("Searching…"),
+});
+```
+
+## The message
+
+`message` customises what blocked users see — a string, or a function of the
+remaining milliseconds.
+
+```ts
+command({
+  name: "spin",
+  description: "Spin the wheel",
+  cooldown: {
+    duration: 5_000,
+    message: (ms) => `Hold on — ${Math.ceil(ms / 1000)}s to go.`,
+  },
+  run: (ctx) => ctx.reply("🎡"),
+});
+```
+
+## The manager
+
+`client.cooldowns` is the shared `CooldownManager` (also used by
+[prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md)). Use it directly for custom flows:
+
+```ts
+const result = client.cooldowns.consume("vote", 5_000, {
+  userId: "1",
+  roleIds: [],
+  guildId: null,
+  channelId: null,
+});
+if (!result.allowed) console.log(`wait ${result.remaining}ms`);
+```
+
+`consume` records the use and returns `{ allowed: true }` or
+`{ allowed: false, remaining }`. `peek` checks without recording; `reset` and
+`clear` drop tracked cooldowns.
+
+---
+
+# Scheduled tasks
+
+Run work on a cron schedule or a fixed interval. The client starts the
+scheduler when it becomes ready and stops it on `destroy()`, so timers never
+outlive your bot.
+
+## Define a task
+
+Provide exactly one of `cron` or `interval` (if both are set, the interval is used):
+
+```ts
+import { task } from "spearkit";
+
+export const heartbeat = task({
+  name: "heartbeat",
+  interval: 60_000, // every minute
+  runOnStart: true, // also run once on startup
+  run: (client) => client.logger.info("still alive"),
+});
+```
+
+Register it like anything else:
+
+```ts
+client.register(heartbeat);
+```
+
+Or define and register in one call:
+
+```ts
+client.schedule({
+  name: "cleanup",
+  cron: "0 3 * * *", // 03:00 local time, every day
+  run: async (client) => {
+    // …purge expired records…
+  },
+});
+```
+
+## Cron syntax
+
+Standard 5-field expressions, evaluated in the host's **local** time:
+
+```
+┌─ minute (0-59)
+│ ┌─ hour (0-23)
+│ │ ┌─ day of month (1-31)
+│ │ │ ┌─ month (1-12)
+│ │ │ │ ┌─ day of week (0-6, Sunday = 0)
+│ │ │ │ │
+* * * * *
+```
+
+Each field supports `*`, ranges (`1-5`), lists (`1,3,5`) and steps (`*/15`).
+When both day-of-month and day-of-week are restricted, a date matches if
+**either** does (standard cron behaviour).
+
+Aliases: `@yearly`/`@annually`, `@monthly`, `@weekly`, `@daily`/`@midnight`, `@hourly`.
+
+```ts
+task({ name: "report", cron: "@daily", run: () => {} });
+task({ name: "poll", cron: "*/5 * * * *", run: () => {} }); // every 5 minutes
+task({ name: "mondays", cron: "0 9 * * 1", run: () => {} }); // Mon 09:00
+```
+
+Compute the next run yourself with `cron`:
+
+```ts
+import { cron } from "spearkit";
+
+const next = cron("*/15 * * * *").next(new Date());
+```
+
+## One-shot jobs, follow-ups and on-ready recovery
+
+Beyond recurring tasks, the scheduler runs one-shot timers (they `unref()`
+themselves, so they never keep the process alive) and a once-on-ready reconciler.
+
+```ts
+// Run once after a delay; returns a cancel handle.
+const handle = client.scheduler.delay("remind", 10 * 60_000, async () => {
+  // …remind the moderator if nothing happened…
+});
+handle.cancel(); // true if it was still pending
+
+// A series of fires measured from "now"; the callback gets the fire index.
+client.scheduler.followUp("escalate", [10_000, 30_000, 60_000], (i) => {
+  // i = 0, then 1, then 2
+});
+
+// Run once the first time the scheduler starts (typically on clientReady) and
+// never again — ideal for restart recovery.
+client.scheduler.reconcile("voice-sessions", async (client) => {
+  // …close orphaned voice sessions, reapply cached state…
+});
+```
+
+## The scheduler
+
+`client.scheduler` is the `TaskScheduler`:
+
+```ts
+client.scheduler.size; // number of tasks
+client.scheduler.active; // started?
+client.scheduler.list(); // every task
+client.scheduler.remove("heartbeat"); // cancel + forget
+client.scheduler.stop(); // cancel all timers
+```
+
+Task errors are caught and logged through `client.logger` (scope `scheduler`),
+so a throwing task never crashes the process or stops future runs.
+
+---
+
+# Prefix commands
+
+Alongside slash commands, spearkit can dispatch classic text/prefix commands like
+`!ping`. You define them with `prefixCommand`, enable them with the client's
+`prefix` option, and spearkit parses each `messageCreate` for you — matching the
+prefix, splitting arguments, and routing to the right handler.
+
+## Enabling prefix commands
+
+Prefix commands are off until you set the `prefix` option on the client. It
+accepts a string, an array of strings, or a `PrefixOptions` object:
+
+```ts
+import { Intents, SpearClient } from "spearkit";
+
+// A single prefix.
+new SpearClient({ intents: Intents.messages, prefix: "!" });
+
+// Several prefixes.
+new SpearClient({ intents: Intents.messages, prefix: ["!", "?"] });
+
+// Full control.
+new SpearClient({
+  intents: Intents.messages,
+  prefix: {
+    prefix: "!",
+    mention: true,         // also trigger on a leading @bot mention (default true)
+    ignoreBots: true,      // skip messages authored by bots (default true)
+    caseInsensitive: true, // match command names ignoring case (default true)
+  },
+});
+```
+
+### Dynamic (per-guild) prefixes
+
+Pass `dynamic` to resolve extra prefix(es) per message — for example a custom
+per-guild prefix from a database or [`createSettings`](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md#persistent-storage).
+Dynamic prefixes are tried in addition to any static `prefix`; return
+`null`/`undefined` for none. It runs on every candidate message, so keep it fast
+(and cached).
+
+```ts
+new SpearClient({
+  intents: Intents.messages,
+  prefix: {
+    prefix: "!", // static fallback
+    dynamic: async (message) =>
+      message.guildId ? await settings.get(message.guildId).then((s) => s.prefix) : null,
+  },
+});
+```
+
+## You need the MessageContent intent
+
+Reading the text of other users' messages is a **privileged** gateway intent.
+Without `MessageContent` your bot still receives `messageCreate`, but
+`message.content` arrives empty for messages it was not mentioned in or did not
+author — so no prefix command will ever match.
+
+Use the `Intents.messages` preset, which includes `Guilds`, `GuildMessages`, and
+the privileged `MessageContent` bit:
+
+```ts
+import { Intents, SpearClient } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.messages, prefix: "!" });
+```
+
+You must also toggle **Message Content Intent** on for your application in the
+Discord Developer Portal, or the gateway will reject the connection.
+
+## Defining a command
+
+`prefixCommand` takes the command name, the handler, and a few optional fields:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const ping = prefixCommand({
+  name: "ping",
+  description: "Check that the bot is alive",
+  run: (ctx) => ctx.reply("Pong!"),
+});
+```
+
+Register it like anything else, with `client.register(...)`:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ prefix: "!" });
+client.register(ping);
+```
+
+| Field | Type | Effect |
+| ----- | ---- | ------ |
+| `name` | `string` | The word after the prefix that triggers the command. |
+| `aliases` | `string[]` | Extra names that also trigger it. |
+| `description` | `string` | Human description, for your own help command. |
+| `cooldown` | `number \| CooldownConfig` | Per-user rate limit (a number is milliseconds). |
+| `guards` | `readonly Guard[]` | Preconditions run before the handler. See [Guards](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md). |
+| `args` | `(a) => PrefixArgsBuilder` | Typed argument schema; shapes `ctx.options`. See [Typed arguments](#typed-arguments). |
+| `run` | `(ctx: PrefixContext) => void \| Promise<void>` | The handler. |
+
+## The prefix context
+
+The handler receives a `PrefixContext`. It wraps the triggering `Message` and
+adds the parsed arguments plus reply helpers.
+
+| Member | Description |
+| ------ | ----------- |
+| `ctx.message` | The triggering discord.js `Message`. |
+| `ctx.commandName` | The matched name as the user typed it (an alias if they used one). |
+| `ctx.args` | Whitespace-split arguments after the command name (`string[]`). |
+| `ctx.rest` | The raw text after the command name (unsplit). |
+| `ctx.options` | Typed parsed arguments from the `args` schema (`{}` when none). |
+| `ctx.author` / `ctx.member` / `ctx.guild` / `ctx.guildId` / `ctx.channel` / `ctx.channelId` | Actor and location accessors. |
+| `ctx.reply(content)` | Reply to the triggering message. |
+| `ctx.send(content)` | Send a message to the same channel without a reply reference. |
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const echo = prefixCommand({
+  name: "echo",
+  description: "Repeat what you said",
+  run: (ctx) => {
+    if (ctx.args.length === 0) return ctx.reply("Give me something to echo.");
+    // `args` is split on whitespace; `rest` is the untouched remainder.
+    return ctx.reply(ctx.rest);
+  },
+});
+```
+
+`ctx.args` and `ctx.rest` are two views of the same input: `!say hello   world`
+gives `args === ["hello", "world"]` and `rest === "hello   world"`.
+
+## Typed arguments
+
+Pass an `args` schema to parse positional arguments into typed values. Chain
+builder methods — first token → first arg, second → second, and so on — and read
+the result from `ctx.options`. Each method requires a name and takes optional
+settings (`required`, `default`, and per-type bounds).
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const mute = prefixCommand({
+  name: "mute",
+  description: "Mute a member",
+  args: (a) =>
+    a
+      .snowflake("target", { required: true })       // raw id or <@mention> → string
+      .duration("duration", { required: true })      // "1h30m" → number (ms)
+      .rest("reason", { default: "No reason given" }), // remaining text → string
+  run: (ctx) => {
+    ctx.options.target;   // string
+    ctx.options.duration; // number
+    ctx.options.reason;   // string
+    return ctx.reply(`Muted <@${ctx.options.target}> for ${ctx.options.duration}ms.`);
+  },
+});
+```
+
+Builder methods: `.string`, `.integer`, `.number`, `.boolean`, `.snowflake`,
+`.duration`, `.rest`. A missing required argument — or a value that fails to
+parse — makes spearkit reply with an error and skip the handler. Without an `args`
+schema, `ctx.options` is `{}`; use `ctx.args` / `ctx.rest` for raw access.
+
+## Aliases
+
+List alternative names in `aliases`; any of them triggers the command, and
+`ctx.commandName` reports whichever the user typed:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const help = prefixCommand({
+  name: "help",
+  aliases: ["h", "commands"],
+  run: (ctx) => ctx.reply(`You used "${ctx.commandName}".`),
+});
+```
+
+## Cooldowns
+
+Prefix commands share the client's cooldown manager (`client.cooldowns`) with
+slash commands, so the API is identical. Pass `cooldown` as a number of
+milliseconds or a full `CooldownConfig`:
+
+```ts
+import { prefixCommand } from "spearkit";
+
+export const daily = prefixCommand({
+  name: "daily",
+  description: "Claim your daily reward",
+  cooldown: 5_000, // one use per user per 5s
+  run: (ctx) => ctx.reply("Reward claimed! Come back soon."),
+});
+```
+
+When a user is on cooldown, spearkit replies with the remaining time and does not
+run the handler. A per-command `cooldown` overrides the client-wide `cooldown`
+default. See [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) for scopes and configuration.
+
+## The prefix registry
+
+`client.prefix` is a `PrefixRegistry`. The client wires it to `messageCreate`,
+the logger, and the cooldown manager for you, so you rarely call it directly. It
+is available for introspection and advanced control:
+
+```ts
+client.prefix.get("ping");  // PrefixCommand | undefined (also resolves aliases)
+client.prefix.list();       // PrefixCommand[] (excludes aliases)
+client.prefix.size;         // number of commands
+```
+
+### Error handling
+
+If a handler throws, spearkit catches it, logs it, and calls your error hook if you
+set one — the process never crashes:
+
+```ts
+client.prefix.onError((error, message) => {
+  console.error(`prefix command failed in #${message.channelId}`, error);
+});
+```
+
+## See also
+
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) — slash commands.
+- [Cooldowns](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md) — the shared rate limiter.
+- [Usage tracking](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/usage.md) — record who runs which prefix commands.
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — the `prefix` option and intent presets.
+
+---
+
+# Logging
+
+spearkit ships a small, dependency-free structured logger. Every client owns one
+at `client.logger`, and spearkit routes its own command, component, event, and
+gateway errors through it. You can use the same logger for your code, or build a
+standalone one.
+
+## A first logger
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // level "info", logs to the console
+log.info("bot starting");
+log.error("connection lost", { error: new Error("ECONNRESET") });
+```
+
+A logger is constructed from `LoggerOptions`:
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({
+  level: "debug",   // minimum severity to emit; default "info"
+  scope: "worker",  // a prefix attached to every entry
+  // sink: consoleSink (the default)
+});
+```
+
+## Levels
+
+There are four levels, lowest to highest: `debug`, `info`, `warn`, `error`. The
+logger emits an entry only if its level is at or above the configured threshold.
+The default threshold is **`info`**, so `debug` entries are suppressed until you
+lower it. A fifth threshold, `"silent"`, suppresses everything.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // threshold "info"
+log.debug("only visible at debug"); // suppressed by default
+log.info("visible");
+
+log.setLevel("debug");        // now debug entries are emitted too
+log.enabled("debug");         // true
+log.setLevel("silent");       // suppress everything
+```
+
+| Method | Level | Use for |
+| ------ | ----- | ------- |
+| `log.debug(msg, opts?)` | `debug` | Verbose diagnostics, off by default. |
+| `log.info(msg, opts?)` | `info` | Normal operational messages. |
+| `log.warn(msg, opts?)` | `warn` | Recoverable problems worth attention. |
+| `log.error(msg, opts?)` | `error` | Failures; attach the cause via `{ error }`. |
+
+`log.level` reads the current threshold, `log.setLevel(level)` changes it, and
+`log.enabled(level)` reports whether an entry of that level would be emitted —
+handy to guard expensive message construction.
+
+## Scopes and child loggers
+
+`log.child("scope")` returns a child logger whose entries carry an extra scope
+segment. A child **shares its parent's threshold and sink**, so changing the
+level on any logger in the tree affects them all.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({ scope: "app" });
+const db = log.child("db");      // scope "app:db"
+const cache = db.child("cache"); // scope "app:db:cache"
+
+db.info("connected");
+log.setLevel("debug");           // affects log, db, and cache
+cache.debug("warm");             // now emitted
+```
+
+spearkit uses this internally: the client creates `commands`, `components`,
+`events`, `scheduler`, `prefix`, and `usage` children off `client.logger`, so
+every subsystem's output is scoped and a single `setLevel` controls them all.
+
+## Structured `data` and `error`
+
+Both arguments live in the optional second parameter (`LogOptions`):
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger();
+
+log.info("command finished", {
+  data: { command: "ping", ms: 12, cached: true },
+});
+
+try {
+  throw new Error("kaboom");
+} catch (cause) {
+  log.error("handler failed", {
+    error: cause instanceof Error ? cause : new Error(String(cause)),
+    data: { command: "purge", guildId: "123" },
+  });
+}
+```
+
+`data` is a flat record of primitives (`string | number | boolean | bigint |
+null | undefined`). `error` is an `Error`; the default sink renders its stack.
+
+### Coercing unknown throws
+
+A `catch` binding is `unknown`. `toError(value)` turns any thrown value into an
+`Error` so it fits `{ error }`:
+
+```ts
+import { Logger, toError } from "spearkit";
+
+const log = new Logger();
+try {
+  JSON.parse("{");
+} catch (cause) {
+  log.error("parse failed", { error: toError(cause) });
+}
+```
+
+## Custom sinks
+
+A sink is `(entry: LogEntry) => void`. The default is `consoleSink`, which writes
+human-readable lines to the console (stderr for `warn`/`error`). Pass your own to
+route entries anywhere — JSON lines, a file, an aggregator:
+
+```ts
+import { Logger, type LogEntry } from "spearkit";
+
+const log = new Logger({
+  level: "debug",
+  sink: (entry: LogEntry) => {
+    process.stdout.write(
+      JSON.stringify({
+        level: entry.level,
+        message: entry.message,
+        scope: entry.scope,
+        at: entry.timestamp.toISOString(),
+        data: entry.data,
+        error: entry.error?.message,
+      }) + "\n",
+    );
+  },
+});
+
+log.child("commands").info("dispatched", { data: { name: "ping" } });
+```
+
+A `LogEntry` is the fully-resolved record handed to the sink:
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `level` | `LogLevel` | One of `debug`/`info`/`warn`/`error`. |
+| `message` | `string` | The log message. |
+| `scope` | `string \| undefined` | The accumulated scope, if any. |
+| `timestamp` | `Date` | When the entry was created. |
+| `error` | `Error \| undefined` | The attached error, if any. |
+| `data` | `Record<string, LogValue> \| undefined` | The structured metadata, if any. |
+
+## Configuring via the client
+
+Pass `logger` to `SpearClient`. Give it `LoggerOptions` to build one, or a
+`Logger` instance you already have:
+
+```ts
+import { SpearClient, Logger } from "spearkit";
+
+// Build from options:
+const a = new SpearClient({ logger: { level: "debug" } });
+
+// Or reuse an instance (e.g. one shared with non-Discord code):
+const shared = new Logger({ level: "info", scope: "svc" });
+const b = new SpearClient({ logger: shared });
+
+a.logger.info("ready");
+```
+
+The client logs all command, component, and event handler errors plus gateway
+errors through `client.logger`. Set `level: "debug"` to see dispatch traces from
+every subsystem:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ logger: { level: "debug" } });
+// client.logger.child("commands"), ".child('events')", etc. all log at debug now
+```
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — the `logger` and other construction options.
+- [Environment & dotenv](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/env.md) — load configuration before you start.
+
+---
+
+# Discord API errors
+
+discord.js reports REST failures as `DiscordAPIError` with a numeric `code`
+(`10008` "Unknown Message", `50013` "Missing Permissions", `50007` "Cannot send
+DMs to this user", …). Catching *everything* turns recoverable failures — a
+deleted message, a closed DM — into crashes or scary stack traces. spearkit gives
+you named codes, a type-narrowing predicate, and a friendly explanation.
+
+## Recognise and recover
+
+`isDiscordError(err, code?)` narrows the throw and optionally matches a code
+(or a list). Perfect for "ignore this one, re-throw the rest":
+
+```ts
+import { DiscordErrorCode, isDiscordError } from "spearkit";
+
+try {
+  await message.delete();
+} catch (err) {
+  if (isDiscordError(err, DiscordErrorCode.UnknownMessage)) return; // already gone
+  throw err;
+}
+```
+
+```ts
+// match any of several codes
+if (isDiscordError(err, [DiscordErrorCode.UnknownChannel, DiscordErrorCode.MissingAccess])) {
+  return;
+}
+```
+
+## Friendly messages
+
+`explainDiscordError(err)` returns an end-user-appropriate sentence for a
+recognised failure, or `null` otherwise (fall back to a generic message + log):
+
+```ts
+import { explainDiscordError } from "spearkit";
+
+catch (err) {
+  await ctx.error(explainDiscordError(err) ?? "Something went wrong.");
+}
+```
+
+spearkit already routes its own command/context-menu errors through
+`explainDiscordError`, so a handler that throws `Missing Permissions` shows the
+user *"I'm missing the permissions needed to do that."* instead of a generic
+error.
+
+## Named codes
+
+`DiscordErrorCode` is a curated map of the codes bots actually hit:
+
+| Name | Code | When |
+| --- | --- | --- |
+| `UnknownChannel` | 10003 | Channel gone/invisible |
+| `UnknownMessage` | 10008 | Message deleted |
+| `UnknownMember` | 10007 | Member left |
+| `UnknownInteraction` | 10062 | Token expired (the 3s window) |
+| `MissingAccess` | 50001 | No access to the resource |
+| `CannotSendMessagesToThisUser` | 50007 | DMs closed / blocked |
+| `MissingPermissions` | 50013 | Missing a permission |
+| `InteractionHasAlreadyBeenAcknowledged` | 40060 | Double-acked |
+
+(See the type for the full set — it mirrors discord.js' `RESTJSONErrorCodes`.)
+
+## Transport & rate-limit errors
+
+- `isHTTPError(err)` — a transport-level `HTTPError` (timeout, 5xx, aborted): an
+  HTTP status with no Discord JSON code.
+- `isRateLimitError(err)` — a `DiscordAPIError` with HTTP status `429`.
+  `explainDiscordError` handles this case first, returning a "try again in a
+  moment" message.
+
+---
+
+# Usage tracking
+
+Usage tracking records **who used what**: every command, component, context-menu
+and prefix-command invocation — successful or errored — becomes a `UsageEvent`
+that spearkit can persist to a
+store and/or mirror into a Discord channel. Turn it on with the client's `usage`
+option.
+
+## Usage tracking vs the logger
+
+These look similar but answer different questions, and they are completely
+independent sinks:
+
+| | Logger | Usage tracking |
+| --- | --- | --- |
+| Question | *What is the bot doing?* (diagnostics) | *Who used which feature?* (audit) |
+| Content | Free-form messages, levels, errors, internals | Structured `UsageEvent`s for every completed use (with its `outcome`) |
+| Sinks | Console / your log pipeline | A database store and/or a Discord channel |
+| Configured by | the `logger` option | the `usage` option |
+
+Both successes and handler errors are recorded as usage events — an error carries
+`outcome: "error"` and an `errorMessage` — so usage is a complete audit trail.
+The [logger](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md) is for debugging; usage tracking is for analytics,
+audit trails, and "top commands" dashboards.
+
+## Enabling it
+
+Set the `usage` option. Provide a `store` (a database), a `channel` (a Discord
+channel id to mirror events into), or both:
+
+```ts
+import { MemoryUsageStore, SpearClient } from "spearkit";
+
+const client = new SpearClient({
+  usage: {
+    store: new MemoryUsageStore(),
+    channel: "123456789012345678", // optional: also post each event here
+  },
+});
+```
+
+Once enabled, spearkit auto-tracks every command, component, context-menu and
+prefix-command invocation — successes and errors alike — with no tracking code in
+your handlers.
+
+## The usage event
+
+Each tracked use is a `UsageEvent`:
+
+```ts
+interface UsageEvent {
+  type: UsageType;         // "command" | "prefix" | "component" | "event"
+  name: string;            // command / component / event name
+  userId?: string;
+  userTag?: string;
+  guildId?: string | null;
+  channelId?: string | null;
+  detail?: string;         // free-form extra detail
+  outcome?: UsageOutcome;  // "success" | "error"
+  durationMs?: number;     // handler wall-clock time
+  options?: Readonly<Record<string, UsageMetaValue>>; // snapshot of typed options
+  errorMessage?: string;   // set when outcome === "error"
+  timestamp: Date;
+}
+type UsageType = "command" | "prefix" | "component" | "event";
+type UsageOutcome = "success" | "error";
+type UsageMetaValue = string | number | boolean | null;
+```
+
+## Stores (the database)
+
+A store is any object implementing `UsageStore`:
+
+```ts
+interface UsageStore {
+  record(event: UsageEvent): void | Promise<void>;
+  all(): UsageEvent[] | Promise<readonly UsageEvent[]>;
+}
+```
+
+spearkit ships two.
+
+### MemoryUsageStore
+
+In-memory and synchronous — ideal for tests, prototypes, and live dashboards.
+Pass an optional cap to keep only the most recent N events:
+
+```ts
+import { MemoryUsageStore } from "spearkit";
+
+const store = new MemoryUsageStore(1_000); // keep the last 1,000 events
+
+store.all();             // readonly UsageEvent[]
+store.size;              // number of events held
+store.byUser("123...");  // UsageEvent[] for one user id
+store.clear();           // forget everything
+```
+
+### JsonFileUsageStore
+
+Durable and dependency-free: appends one event per line as newline-delimited
+JSON (`.jsonl`). `all()` reads the file back and parses it, so it behaves like a
+small file-backed database:
+
+```ts
+import { JsonFileUsageStore } from "spearkit";
+
+const store = new JsonFileUsageStore("./usage.jsonl");
+
+await store.record({ type: "command", name: "ping", timestamp: new Date() });
+const events = await store.all(); // readonly UsageEvent[]
+```
+
+The directory is created on demand. Because `all()` is async here (it reads from
+disk), always `await` it.
+
+## Querying the store
+
+`client.usage.store` is the store you configured — query it directly. Note that
+`all()` may be synchronous (`MemoryUsageStore`) or asynchronous
+(`JsonFileUsageStore`); awaiting works for both:
+
+```ts
+const store = client.usage.store;
+if (store !== undefined) {
+  const events = await store.all();
+  const topCommand = events.filter((e) => e.type === "command").length;
+  console.log(`${topCommand} command uses recorded`);
+}
+```
+
+## The Discord channel reporter
+
+Besides (or instead of) a store, you can mirror each event into a Discord
+channel. Pass `channel` (a channel id) in the `usage` option; spearkit posts one
+line per event using `formatUsage`:
+
+```ts
+import { SpearClient } from "spearkit";
+
+new SpearClient({ usage: { channel: "123456789012345678" } });
+```
+
+`formatUsage(event)` is the default renderer (e.g. `` `command` **ping** by
+user#0001 in <#…> ``). Override it with `format` to control the line:
+
+```ts
+import { SpearClient, type UsageEvent } from "spearkit";
+
+new SpearClient({
+  usage: {
+    channel: "123456789012345678",
+    format: (event: UsageEvent) => `${event.userTag ?? "someone"} used ${event.name}`,
+  },
+});
+```
+
+## The usage tracker
+
+`client.usage` is a `UsageTracker`. The client configures it from the `usage`
+option, but you can drive it directly:
+
+| Member | Description |
+| ------ | ----------- |
+| `setStore(store)` | Set (or swap) the persistence store. |
+| `reportTo(channelId, format?)` | Mirror events into a channel, optionally with a custom formatter. |
+| `track(event)` | Record a use. Returns immediately; storing/reporting run in the background. |
+| `store` | The configured store, for querying. |
+| `enabled` | `true` if a store or channel is configured. |
+
+```ts
+import { JsonFileUsageStore } from "spearkit";
+
+client.usage.setStore(new JsonFileUsageStore("./usage.jsonl"));
+client.usage.reportTo("123456789012345678");
+
+// Record a custom event yourself (e.g. a non-command action).
+client.usage.track({ type: "event", name: "signup", timestamp: new Date() });
+```
+
+Tracking is fire-and-forget: a slow store or channel never blocks command
+handling, and any failure is logged rather than thrown.
+
+## See also
+
+- [Logging](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md) — diagnostics, the other sink.
+- [Commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/commands.md) / [Prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md) / [Components](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/components.md) — what gets tracked.
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — the `usage` option.
+
+---
+
+# Environment & dotenv
+
+spearkit includes a tiny, dependency-free `.env` loader and a typed reader over
+`process.env`, so a bot needs no extra dotenv dependency. The client auto-loads
+`.env` on `start()`, and the same helpers are exported for your own use.
+
+## Loading a `.env` file
+
+`loadEnv(options?)` reads a `.env` file and merges it into `process.env`. By
+default it reads `.env` from the current working directory. Variables already
+present in `process.env` win unless you pass `override: true`. A missing file is
+ignored — it simply returns `{}` — so it is safe to call unconditionally.
+
+```ts
+import { loadEnv } from "spearkit";
+
+const parsed = loadEnv();                       // reads ./.env
+loadEnv({ path: ".env.local" });                // a different file
+loadEnv({ override: true });                    // let the file win over existing vars
+```
+
+`loadEnv` returns the parsed key/value pairs it read from the file:
+
+```ts
+import { loadEnv } from "spearkit";
+
+const parsed = loadEnv(); // ParsedEnv = Record<string, string>
+console.log(Object.keys(parsed));
+```
+
+## Parsing without touching `process.env`
+
+`parseEnv(text)` parses `.env`-formatted text into a flat object and never
+mutates `process.env`. It understands single/double quotes, a leading `export `,
+`#` comments, and `\n`/`\r`/`\t` escapes inside double quotes.
+
+```ts
+import { parseEnv } from "spearkit";
+
+const vars = parseEnv(`
+# a comment
+export TOKEN="abc#notacomment"
+GREETING="line one\nline two"
+RAW='no $escapes here'
+`);
+
+vars.TOKEN;    // "abc#notacomment"
+vars.GREETING; // "line one\nline two" (real newline)
+vars.RAW;      // "no $escapes here"
+```
+
+## The typed `env` reader
+
+`env` reads from `process.env` with coercion and optional fallbacks. Empty
+strings count as missing.
+
+```ts
+import { env } from "spearkit";
+
+env.string("REGION");            // string | undefined
+env.string("REGION", "eu");      // string (fallback when missing)
+
+env.number("PORT");              // number | undefined
+env.number("PORT", 3000);        // number (fallback when missing or non-numeric)
+
+env.boolean("DEBUG");            // boolean | undefined
+env.boolean("DEBUG", false);     // boolean
+
+env.require("DISCORD_TOKEN");    // string, throws if missing or empty
+```
+
+`env.boolean` treats `true`/`1`/`yes`/`on` as `true` and `false`/`0`/`no`/`off`
+as `false` (case-insensitive); anything else yields the fallback. `env.require`
+throws a descriptive error when the variable is missing or empty — use it for
+values your bot cannot run without.
+
+```ts
+import { loadEnv, env } from "spearkit";
+
+loadEnv();
+const token = env.require("DISCORD_TOKEN"); // guaranteed string
+const port = env.number("PORT", 8080);      // number
+const verbose = env.boolean("VERBOSE", false);
+```
+
+## Auto-loading on the client
+
+`SpearClient` calls `loadEnv()` for you inside `client.start()`, so `.env` is
+picked up before login. That means `await client.start()` finds
+`DISCORD_TOKEN` from `.env` without any extra wiring:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient();
+
+async function main(): Promise<void> {
+  await client.start(); // loads .env, then reads DISCORD_TOKEN
+}
+
+void main();
+```
+
+### The `dotenv` option
+
+Control the auto-load with the `dotenv` construction option:
+
+```ts
+import { SpearClient } from "spearkit";
+
+// Default: load ./.env on start.
+new SpearClient({ dotenv: true });
+
+// Disable auto-loading entirely (e.g. env is provided by the platform).
+new SpearClient({ dotenv: false });
+
+// Customize: same shape as loadEnv's options.
+new SpearClient({ dotenv: { path: ".env.production", override: true } });
+```
+
+| `dotenv` value | Effect |
+| -------------- | ------ |
+| `true` / omitted | Load `.env` from the cwd on `start()`. |
+| `false` | Skip auto-loading; `process.env` is used as-is. |
+| `{ path?, override? }` | Load with those `loadEnv` options. |
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — the `dotenv` and other construction options.
+- [Logging](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md) — structured logging that pairs with `env`-driven config.
+
+---
+
+# Plugins
+
+A plugin is a named, reusable bundle of commands, events and components. It lets
+you package a feature once and install it into any `SpearClient` with a single
+call — useful for sharing functionality across bots or splitting a large bot into
+self-contained features.
+
+## Defining a plugin
+
+`definePlugin` is an identity helper: it returns the object you pass it, but gives
+it the `SpearPlugin` type and editor hints.
+
+```ts
+interface SpearPlugin {
+  name: string;
+  setup(client: SpearClient): Awaitable<void>;
+}
+```
+
+A plugin has a `name` and a `setup` function. `setup` receives the client and
+registers whatever the feature needs — commands, events, components — typically
+via `client.register`.
+
+```ts
+import { definePlugin, button, command, event, option, row } from "spearkit";
+
+export const moderation = definePlugin({
+  name: "moderation",
+  setup(client) {
+    const confirmKick = button({
+      id: "kick:{userId}",
+      label: "Confirm kick",
+      style: "Danger",
+      run: (ctx) => ctx.update(`Kicked <@${ctx.params.userId}> (demo).`), // userId: string
+    });
+
+    const warn = command({
+      name: "warn",
+      description: "Warn a member",
+      options: {
+        member: option.user({ description: "Member", required: true }),
+        reason: option.string({ description: "Reason" }),
+      },
+      run: (ctx) =>
+        ctx.reply({
+          // member: User, reason: string | undefined
+          content: `Warning ${ctx.options.member.tag}: ${ctx.options.reason ?? "no reason given"}`,
+          components: [row(confirmKick.build({ userId: ctx.options.member.id }))],
+          ephemeral: true,
+        }),
+    });
+
+    const ready = event("clientReady", (c) => console.log(`[moderation] ready on ${c.user.tag}`));
+
+    client.register(warn, confirmKick, ready);
+  },
+});
+```
+
+Everything declared inside `setup` is local to the plugin; only what you pass to
+`client.register` becomes active on the client.
+
+## Installing a plugin
+
+Install one or more plugins with `client.use`. It runs each plugin's `setup` in
+order and resolves to the client, so you can chain it with the rest of startup.
+
+```ts
+import { SpearClient, Intents } from "spearkit";
+import { moderation } from "./plugins/moderation.js";
+
+const client = new SpearClient({ intents: Intents.default });
+
+await client.use(moderation);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+`use` accepts several plugins at once:
+
+```ts
+await client.use(moderation, welcome, tickets);
+```
+
+## Asynchronous setup
+
+`setup` may be async — `client.use` awaits each one before moving to the next. Use
+this to load data, connect to a database, or fetch remote config before
+registering handlers.
+
+```ts
+export const tags = definePlugin({
+  name: "tags",
+  async setup(client) {
+    const store = await openTagStore(); // await anything you need first
+
+    client.register(
+      command({
+        name: "tag",
+        description: "Show a saved tag",
+        options: { name: option.string({ description: "Tag name", required: true }) },
+        run: (ctx) => ctx.reply(store.get(ctx.options.name) ?? "No such tag."),
+      }),
+    );
+  },
+});
+```
+
+Because `use` awaits `setup`, every plugin is fully installed before
+`client.start` runs.
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — `register`, `use`, `start`, and the registries plugins write to.
+- [File-based loading](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/loading.md) — discover commands, events and components from a directory instead of bundling them by hand.
+
+---
+
+# Collectors
+
+discord.js collectors are powerful but fiddly: you wire an event emitter, set a
+`time`, write a `filter`, remember that dismissed modals need their own timeout,
+and translate the "timed out" rejection into something you can branch on.
+spearkit collapses the common cases to a single `await` that resolves to the
+result — or `null` on timeout.
+
+Beyond these, see the [pagination and confirm helpers](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md#pagination--confirmation)
+for ready-made paged lists and yes/no gates.
+
+## Wait for a message ("type your answer")
+
+`ctx.awaitMessageFrom(userId?, options?)` waits for the next message in the
+current channel from a user (defaults to the invoking user):
+
+```ts
+await ctx.reply("What's your favourite colour?");
+const answer = await ctx.awaitMessageFrom(ctx.user.id, { time: 30_000 });
+if (answer === null) return ctx.followUp("Timed out.");
+await ctx.followUp(`Nice — ${answer.content}!`);
+```
+
+The standalone `awaitMessage(channel, options)` does the same for any text
+channel; `options` takes `{ filter, time }` (default `time` 60s).
+
+## Wait for a modal submission
+
+`ctx.awaitModal(modal, options?)` (on command and component contexts) shows a
+modal and waits for the submission — scoped to the same user and that modal's
+custom-id, always bounded — sidestepping the "Unknown interaction after a
+cancelled modal" trap:
+
+```ts
+import { modal, textInput } from "spearkit";
+
+const form = modal({
+  id: "feedback",
+  title: "Feedback",
+  fields: { text: textInput({ label: "Your feedback", required: true }) },
+  run: (ctx) => ctx.replyEphemeral("thanks"), // routed fallback
+});
+
+const submitted = await ctx.awaitModal(form.build(), { time: 120_000 });
+if (submitted === null) return; // dismissed or timed out
+await submitted.reply({ content: submitted.fields.getTextInputValue("text"), ephemeral: true });
+```
+
+This is the inline alternative to registering a separate modal handler and
+threading state through its custom-id.
+
+## Wait for a component click
+
+`awaitComponent(message, options)` waits for the next button/select interaction
+on a message. `options` takes `{ filter, time, componentType }`. You must still
+acknowledge the returned interaction (`update`/`deferUpdate`/`reply`):
+
+```ts
+import { awaitComponent } from "spearkit";
+
+const sent = await ctx.channel!.send({ content: "Pick one", components: [row] });
+const click = await awaitComponent(sent, { time: 15_000 });
+if (click === null) return;
+await click.update("Got it!");
+```
+
+---
+
+# Key-value store & settings
+
+Almost every community bot needs to remember *something* per guild — a custom
+prefix, a mod-log channel, a welcome message — and reaches for a database on day
+one. spearkit ships a dependency-free `KeyValueStore` interface with two
+backends, plus a typed per-guild settings helper. Swap in Redis/SQL later by
+implementing the same interface.
+
+## Stores
+
+```ts
+import { JsonStore, MemoryStore } from "spearkit";
+
+const dev = new MemoryStore();             // in-memory, great for tests
+const prod = new JsonStore("data/db.json"); // durable JSON file
+```
+
+Both implement `KeyValueStore`:
+
+```ts
+await store.set("key", { any: "json" });
+await store.get<{ any: string }>("key"); // typed read, or undefined
+await store.has("key");
+await store.delete("key");                // → boolean (existed?)
+await store.keys();                       // → string[]
+await store.clear();
+```
+
+`MemoryStore` deep-clones on read and write, so callers can't mutate stored
+state. `JsonStore` serves reads from an in-memory cache and commits writes
+atomically (temp file + rename) through a queue — a crash mid-write can't corrupt
+the file, and concurrent writes don't interleave.
+
+## Typed per-guild settings
+
+`createSettings` wraps a store with defaults. `get` always returns a complete
+object; `set` persists *only* the overrides, so widening `defaults` later is
+safe.
+
+```ts
+import { JsonStore, createSettings } from "spearkit";
+
+const settings = createSettings({
+  store: new JsonStore("data/guilds.json"),
+  defaults: { prefix: "!", modLogChannelId: null as string | null },
+});
+
+const cfg = await settings.get(guildId);          // { prefix, modLogChannelId }
+await settings.set(guildId, { prefix: "?" });     // shallow-merged + persisted
+await settings.reset(guildId);                    // back to defaults
+```
+
+Pass `namespace` to keep several settings groups in one store:
+
+```ts
+const guilds = createSettings({ store, defaults: { prefix: "!" }, namespace: "guild" });
+const users = createSettings({ store, defaults: { xp: 0 }, namespace: "user" });
+```
+
+## Dynamic per-guild prefix
+
+A stored prefix is only useful if prefix commands respect it. `prefix.dynamic`
+resolves extra prefix(es) per message — combine it with `createSettings` for true
+per-guild prefixes:
+
+```ts
+const client = new SpearClient({
+  prefix: {
+    dynamic: async (message) =>
+      message.guildId ? (await settings.get(message.guildId)).prefix : null,
+  },
+});
+```
+
+The resolver runs on every candidate message, so keep it fast (cache or use the
+in-memory `JsonStore` cache). Returned prefixes are tried *in addition* to any
+static `prefix`. See [Prefix commands](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md) for the rest of the prefix
+system.
+
+## Namespacing a raw store
+
+`namespaced(store, prefix)` returns a `KeyValueStore` whose keys are
+transparently prefixed — handy for sharing one file across features:
+
+```ts
+import { namespaced } from "spearkit";
+
+const tags = namespaced(store, "tags");
+await tags.set("hello", "world"); // stored under "tags:hello"
+```
+
+---
+
+# Messages & limits
+
+Discord caps a message's `content` at **2000 characters**. Long output — a log
+dump, a list, an AI response — silently fails or throws unless you split it.
+spearkit ships two helpers (in addition to the duration/timestamp formatters; see
+the [API reference](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/api-reference.md)).
+
+## Split long output
+
+`chunkMessage(text, options?)` breaks text into chunks that each fit the limit,
+preferring line boundaries (and word boundaries for an over-long single line) so
+you never lose the tail:
+
+```ts
+import { chunkMessage } from "spearkit";
+
+const parts = chunkMessage(hugeLog); // default max = 2000
+await ctx.reply(parts[0] ?? "(empty)");
+for (const part of parts.slice(1)) await ctx.followUp(part);
+```
+
+Pass `{ max }` to target a smaller budget (e.g. inside a code block or embed
+description). `MESSAGE_CHARACTER_LIMIT` (2000) is exported as the default.
+
+## Truncate
+
+`truncate(text, max, suffix?)` cuts text to `max` characters, appending the
+suffix (default `…`) — the result, suffix included, never exceeds `max`:
+
+```ts
+import { truncate } from "spearkit";
+
+embed.setFooter({ text: truncate(reason, 100) });
+truncate("a very long reason", 10); // → "a very lo…"
+```
+
+---
+
+# Graceful shutdown
+
+A `Ctrl-C` or a container stop sends your process a signal. If you don't handle
+it, the process dies mid-flight — the gateway connection, scheduler timers, and
+any open database handles are reaped abruptly. Graceful shutdown runs an optional
+cleanup hook, calls `client.destroy()` (which also stops spearkit's scheduler),
+then exits — with a hard timeout so a wedged shutdown can't hang forever.
+
+## On a SpearClient
+
+```ts
+client.enableGracefulShutdown({
+  onShutdown: () => db.close(), // flush state before we exit
+});
+await client.start();
+```
+
+Progress is logged through `client.logger`. The method returns a disposer that
+removes the signal handlers (useful for tests / hot-reload).
+
+## Standalone
+
+`gracefulShutdown(client, options)` works with any object that has a `destroy()`
+method:
+
+```ts
+import { gracefulShutdown } from "spearkit";
+
+gracefulShutdown(client, { onShutdown: () => db.close() });
+```
+
+## Options
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `signals` | `["SIGINT", "SIGTERM"]` | Signals to listen for. |
+| `timeoutMs` | `10000` | Force-exit if shutdown exceeds this. |
+| `onShutdown` | — | Runs before `destroy()`; receives the signal. |
+| `exit` | `true` | Call `process.exit()` when done (set `false` in tests). |
+| `logger` | — | `{ info?, error? }` progress logger. |
+
+Shutdown runs **once** — repeated signals during teardown are ignored.
+
+---
+
+# File-based loading
+
+Instead of importing and registering every handler by hand, you can keep one
+handler per file and let spearkit discover them. The loader imports a directory,
+inspects each module's exports, and registers everything that is a command,
+event, component, scheduled task or prefix command.
+
+## `client.load`
+
+```ts
+load(dir: string, options?: LoadOptions): Promise<number>
+```
+
+`client.load` imports `dir` and registers every spearkit-registrable export it finds,
+resolving to the number of items registered.
+
+```ts
+import { fileURLToPath } from "node:url";
+import { SpearClient, Intents } from "spearkit";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+
+const client = new SpearClient({ intents: Intents.default });
+
+const loaded =
+  (await client.load(`${here}commands`)) +
+  (await client.load(`${here}events`)) +
+  (await client.load(`${here}components`));
+console.log(`Loaded ${loaded} modules.`);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+### What gets registered
+
+For every imported file, spearkit walks **all** of its exports — default *and*
+named — and registers each value that is a command (`command`, `commandGroup`),
+an event (`event`), a component (`button`, `stringSelect`, `modal`, …), a
+scheduled task (`task`) or a prefix command (`prefixCommand`). Other exports
+(helpers, constants, types) are ignored, and context-menu commands are **not**
+auto-detected — register those explicitly. So both of these are picked up:
+
+```ts
+// default export
+export default command({ name: "ping", description: "…", run: (ctx) => ctx.reply("pong") });
+```
+
+```ts
+// named export
+export const vote = button({ id: "vote:{choice}", label: "Vote", run: (ctx) => ctx.update(ctx.params.choice) });
+```
+
+### Options
+
+```ts
+interface LoadOptions {
+  extensions?: readonly string[]; // default: [".js", ".mjs", ".cjs"]
+  recursive?: boolean;            // default: true
+}
+```
+
+- **`extensions`** — which file extensions to import. By default the loader reads
+  `.js`, `.mjs` and `.cjs` — i.e. **compiled JavaScript**, not `.ts` source.
+- **`recursive`** — by default the loader descends into subdirectories. Pass
+  `recursive: false` to load only the top level.
+
+```ts
+await client.load(`${here}features`, { recursive: false });
+```
+
+> The loader imports compiled JavaScript. **Build your TypeScript first**, then run
+> (and load) the emitted output — `npx tsc && node dist/index.js`. Loading a
+> directory of `.ts` source files will not match the default extensions.
+
+## Standalone helpers
+
+`client.load` is the method form of `loadInto`. Both helpers are exported if you
+want to collect or register modules separately.
+
+```ts
+collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>
+loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>
+```
+
+- **`collectModules`** imports a directory and returns the registrable exports it
+  found, without touching any client. Use it to inspect, filter, or combine
+  modules before registering.
+- **`loadInto`** calls `collectModules` and then `client.register(...)` for you,
+  returning the count.
+
+```ts
+import { collectModules, loadInto } from "spearkit";
+
+// Inspect before registering:
+const items = await collectModules(`${here}commands`);
+console.log(`Found ${items.length} modules`);
+client.register(...items);
+
+// Or do both in one step:
+const count = await loadInto(client, `${here}events`);
+```
+
+## Example layout
+
+The `examples/file-based-loading` project keeps each handler in its own file:
+
+```
+file-based-loading/
+  index.ts            # construct client, load each folder, start, deploy
+  commands/
+    ping.ts           # export default command({ ... })
+    echo.ts           # export default command({ ... })
+  events/
+    ready.ts          # export default event("clientReady", ...)
+  components/
+    vote.ts           # export const vote = button({ ... })
+```
+
+A command file looks like this:
+
+```ts
+// commands/echo.ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    loud: option.boolean({ description: "Shout it" }),
+  },
+  // text: string, loud: boolean | undefined
+  run: (ctx) => ctx.reply(ctx.options.loud ? ctx.options.text.toUpperCase() : ctx.options.text),
+});
+```
+
+Build the project, then run the compiled `index.js`; `client.load` will import the
+emitted `.js` files and register `ping`, `echo`, `ready` and `vote` for you.
+
+## See also
+
+- [Client](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/client.md) — `load`, `register`, and the registries the loader writes to.
+- [Events](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/events.md) — the `event()` helper that event modules export.
+
+---
+
+# API reference
+
+Every symbol spearkit exports, in addition to the entire re-exported discord.js
+surface. Import any of these from `"spearkit"`.
+
+```ts
+import { SpearClient, command, option, event, button, modal, row /* … */ } from "spearkit";
+```
+
+---
+
+## Client
+
+### `class SpearClient extends Client`
+
+A discord.js `Client` with registries and interaction routing wired up.
+
+```ts
+new SpearClient(options?: SpearClientOptions)
+```
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `commands` | `CommandRegistry` | Slash command registry + dispatcher. |
+| `events` | `EventRegistry` | Event listener registry. |
+| `components` | `ComponentRegistry` | Button/select/modal router. |
+| `logger` | `Logger` | Structured logger (`client.logger.child(scope)` for sub-scopes). |
+| `cooldowns` | `CooldownManager` | Shared cooldown manager (also used by prefix commands). |
+| `scheduler` | `TaskScheduler` | Cron / interval task scheduler. |
+| `prefix` | `PrefixRegistry` | Prefix (text) command registry. |
+| `usage` | `UsageTracker` | Usage tracker — records who used what. |
+| `embeds` | `Embeds` | Preset embed factory behind `ctx.success/error/...`. |
+| `contextMenus` | `ContextMenuRegistry` | User / message context-menu registry. |
+| `register(...items: Registerable[])` | `this` | Route each item to the matching registry. |
+| `use(...plugins: SpearPlugin[])` | `Promise<this>` | Run each plugin's `setup`. |
+| `load(dir: string, options?: LoadOptions)` | `Promise<number>` | Import a directory and register its exports. Returns count. |
+| `start(token?: string)` | `Promise<this>` | Log in (falls back to `DISCORD_TOKEN`). |
+| `deployCommands(options?: { guildId?: string })` | `Promise<DeployResult>` | Push commands using the client's REST. Call after ready. |
+| `deployAllCommands(options?)` | `Promise<DeployResult \| { skipped: true; reason; body }>` | Deploy slash + context menus together; supports `dryRun` and `strategy: "diff"`. |
+| `schedule(config: TaskConfig)` | `ScheduledTask` | Define and register a scheduled task in one call. |
+| `enableGracefulShutdown(options?: GracefulShutdownOptions)` | `() => void` | Tear down cleanly on `SIGINT`/`SIGTERM`; returns a disposer. |
+
+Inherits everything from discord.js `Client` (`on`, `once`, `login`, `ws`, `rest`, `application`, `user`, …).
+
+### `type SpearClientOptions = Partial<ClientOptions> & SpearOptions`
+
+discord.js `ClientOptions` (with `intents` optional — it defaults to
+`Intents.default`) intersected with spearkit's own options (`SpearOptions`):
+
+| Option | Type | Configures |
+| ------ | ---- | ---------- |
+| `logger` | `Logger \| LoggerOptions` | The `client.logger`. |
+| `dotenv` | `boolean \| LoadEnvOptions` | Auto-load `.env` on `start()` (default `true`). |
+| `cooldown` | `CooldownInput` | Default cooldown applied to every command. |
+| `prefix` | `string \| readonly string[] \| PrefixOptions` | Enable prefix commands. |
+| `usage` | `UsageOptions` | Usage-tracking store and/or channel. |
+| `embeds` | `Embeds \| EmbedsOptions` | Preset embed factory. |
+| `guards` | `readonly Guard[]` | Default guards run before every handler. |
+| `autoDefer` | `AutoDeferInput` | Default auto-defer for slash + context-menu handlers. |
+
+### `const Intents`
+
+Ready-made intent presets (arrays of `GatewayIntentBits`).
+
+| Key | Contents |
+| --- | -------- |
+| `Intents.none` | `[]` |
+| `Intents.default` | `[Guilds]` |
+| `Intents.guilds` | `[Guilds, GuildMembers]` |
+| `Intents.messages` | `[Guilds, GuildMessages, MessageContent]` |
+| `Intents.all` | Every intent (includes privileged). |
+
+### `type Registerable = SlashCommand | EventDef | ComponentDef | ScheduledTask | PrefixCommand | ContextMenuCommand`
+
+The union accepted by `SpearClient.register`.
+
+---
+
+## Commands
+
+### `function command<O, R>(config): SlashCommand`
+
+Define a leaf slash command.
+
+```ts
+interface CommandConfig<O extends OptionMap, R> {
+  name: string;
+  description: string;
+  options?: O;
+  defaultMemberPermissions?: PermissionResolvable | null;
+  nsfw?: boolean;
+  guildOnly?: boolean;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+  cooldown?: CooldownInput;
+  guards?: readonly Guard[];
+  autoDefer?: AutoDeferInput;
+  run: (ctx: CommandContext<O>) => Awaitable<R>;
+}
+```
+
+### `function commandGroup(config: CommandGroupConfig): SlashCommand`
+
+Define a command that routes to subcommands and/or subcommand groups.
+
+```ts
+interface CommandGroupConfig {
+  name: string;
+  description: string;
+  subcommands?: Record<string, Subcommand>;
+  groups?: Record<string, SubcommandGroup>;
+  defaultMemberPermissions?: PermissionResolvable | null;
+  nsfw?: boolean;
+  guildOnly?: boolean;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+  cooldown?: CooldownInput;
+  guards?: readonly Guard[];
+  autoDefer?: AutoDeferInput;
+}
+```
+
+### `function subcommand<O, R>(config): Subcommand`
+
+```ts
+interface SubcommandConfig<O extends OptionMap, R> {
+  description: string;
+  options?: O;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+  run: (ctx: CommandContext<O>) => Awaitable<R>;
+}
+```
+
+### `function subcommandGroup(config: SubcommandGroupConfig): SubcommandGroup`
+
+```ts
+interface SubcommandGroupConfig {
+  description: string;
+  subcommands: Record<string, Subcommand>;
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+```
+
+### `class SlashCommand`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `name` | `string` | Top-level command name. |
+| `hasAutocomplete` | `boolean` | True if any option declares autocomplete. |
+| `toJSON()` | `RESTPostAPIChatInputApplicationCommandsJSONBody` | REST payload. |
+| `execute(interaction)` | `Promise<void>` | Run for a chat-input interaction. |
+| `autocomplete(interaction)` | `Promise<void>` | Run autocomplete for the focused option. |
+| `cooldown` | `CooldownConfig \| undefined` | Resolved cooldown, when set. |
+| `guards` | `readonly Guard[] \| undefined` | Guards run before `execute`. |
+| `autoDefer` | `AutoDeferConfig \| undefined` | Resolved auto-defer config, when set. |
+
+### `class CommandContext<O> extends BaseContext<ChatInputCommandInteraction>`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `options` | `ResolvedOptions<O>` | Resolved, fully-typed option values. |
+| `commandName` | `string` | Invoked command name. |
+| `subcommand` | `string \| null` | Invoked subcommand, if any. |
+| `showModal(modal)` | `Promise<void>` | Present a modal. |
+| `awaitModal(modal, options?)` | `Promise<ModalSubmitInteraction \| null>` | Show a modal and await its submission (scoped to this user). |
+
+Plus all `BaseContext` members.
+
+### `class CommandRegistry`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `add(...commands: SlashCommand[])` | `this` | Register commands (override by name). |
+| `remove(name: string)` | `boolean` | Remove a command. |
+| `get(name: string)` | `SlashCommand \| undefined` | Look up a command. |
+| `all()` | `SlashCommand[]` | All commands. |
+| `names` | `string[]` | All command names. |
+| `size` | `number` | Count. |
+| `onError(handler: CommandErrorHandler)` | `this` | Set the error handler. |
+| `toJSON()` | `RESTPostAPIApplicationCommandsJSONBody[]` | Serialise all commands. |
+| `handle(interaction)` | `Promise<void>` | Dispatch a chat-input interaction. |
+| `handleAutocomplete(interaction)` | `Promise<void>` | Dispatch an autocomplete interaction. |
+| `deploy(options: DeployOptions)` | `Promise<DeployResult>` | Push commands to discord. |
+| `setLogger(logger: Logger)` | `this` | Attach a debug logger for dispatch tracing. |
+| `setCooldowns(manager: CooldownManager, default?: CooldownConfig)` | `this` | Wire a shared cooldown manager and optional default. |
+| `setDefaultGuards(guards: readonly Guard[])` | `this` | Guards run before each command's own guards. |
+| `setUsageHook(hook: (event: UsageEvent) => void)` | `this` | Called after each dispatch (success or error). |
+
+```ts
+type CommandErrorHandler = (error: Error, interaction: ChatInputCommandInteraction) => Awaitable<void>;
+interface DeployOptions { token?: string; applicationId: string; guildId?: string; rest?: REST; }
+type DeployResult = RESTPutAPIApplicationCommandsResult | RESTPutAPIApplicationGuildCommandsResult;
+```
+
+---
+
+## Options
+
+### `const option`
+
+Type-safe option builders. Each returns an `OptionDef` whose resolved value type
+is inferred (required → value, optional → `value | undefined`, `choices` →
+literal union).
+
+| Builder | Resolved type | Extra config |
+| ------- | ------------- | ------------ |
+| `option.string(config)` | `string` | `choices?`, `minLength?`, `maxLength?`, `autocomplete?` |
+| `option.integer(config)` | `number` | `choices?`, `minValue?`, `maxValue?`, `autocomplete?` |
+| `option.number(config)` | `number` | `choices?`, `minValue?`, `maxValue?`, `autocomplete?` |
+| `option.boolean(config)` | `boolean` | — |
+| `option.user(config)` | `User` | — |
+| `option.channel(config)` | channel union | `channelTypes?` |
+| `option.role(config)` | `Role \| APIRole` | — |
+| `option.mentionable(config)` | user/role/member | — |
+| `option.attachment(config)` | `Attachment` | — |
+
+Common config (`BaseConfig`):
+
+```ts
+{
+  description: string;
+  required?: boolean;            // default false
+  nameLocalizations?: LocalizationMap;
+  descriptionLocalizations?: LocalizationMap;
+}
+```
+
+`choices` items are `OptionChoice<V>`:
+
+```ts
+interface OptionChoice<V extends string | number = string | number> {
+  name: string;
+  value: V;
+  nameLocalizations?: LocalizationMap;
+}
+```
+
+`autocomplete`:
+
+```ts
+type AutocompleteHandler<V extends string | number> =
+  (ctx: AutocompleteContext) => Awaitable<OptionChoice<V>[]>;
+```
+
+### Option types
+
+| Symbol | Description |
+| ------ | ----------- |
+| `interface OptionDef<TValue, TRequired>` | A described option (phantom-typed for inference). |
+| `type AnyOptionDef` | `OptionDef<OptionValue, boolean>`. |
+| `type OptionMap` | `Record<string, AnyOptionDef>`. |
+| `type ResolvedOption<O>` | The handler value for one option. |
+| `type ResolvedOptions<O>` | The handler's `options` object. |
+| `type OptionValue` | Union of all possible resolved values. |
+| `type AllowedChannelType` | Channel types valid for a channel option. |
+| `function toAPIOption(name, def)` | Serialise one option to REST. |
+| `function readOption(resolver, name, def)` | Read a resolved value (null → undefined). |
+| `function optionsHaveAutocomplete(options)` | True if any option has autocomplete. |
+
+### `class AutocompleteContext`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `interaction` | `AutocompleteInteraction` | Raw interaction. |
+| `client` / `user` / `guild` / `guildId` | — | Convenience accessors. |
+| `commandName` | `string` | Command being completed. |
+| `focusedName` | `string` | Name of the focused option. |
+| `value` | `string` | Current partial value typed by the user. |
+| `respond(choices: OptionChoice[])` | `Promise<void>` | Send up to 25 suggestions. |
+
+---
+
+## Events
+
+### `function event(name, run): EventDef` / `function event(config): EventDef`
+
+```ts
+type EventHandler<E extends keyof ClientEvents> = (...args: ClientEvents[E]) => Awaitable<void>;
+interface EventConfig<E extends keyof ClientEvents> { name: E; once?: boolean; run: EventHandler<E>; }
+interface EventDef { name: keyof ClientEvents; once: boolean; attach(client: Client): void; detach(client: Client): void; }
+```
+
+Thrown errors and rejected promises are routed to the client's `error` event.
+
+### `class EventRegistry`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `add(...defs: EventDef[])` | `this` | Register listeners. |
+| `size` | `number` | Count. |
+| `attachAll(client: Client)` | `void` | Attach every listener. |
+| `detachAll(client: Client)` | `void` | Detach every listener. |
+
+---
+
+## Components
+
+### Builders
+
+| Function | Returns | Notes |
+| -------- | ------- | ----- |
+| `button(config)` | `Button<P>` | Interactive button. |
+| `linkButton(config)` | `ButtonBuilder` | URL button, no handler. |
+| `stringSelect(config)` | `StringSelect<P>` | String select; takes `options`. |
+| `userSelect(config)` | `UserSelect<P>` | User select. |
+| `roleSelect(config)` | `RoleSelect<P>` | Role select. |
+| `channelSelect(config)` | `ChannelSelect<P>` | Channel select; takes `channelTypes?`. |
+| `mentionableSelect(config)` | `MentionableSelect<P>` | User + role select. |
+| `modal(config)` | `Modal<P>` | Modal with `fields`. |
+| `textInput(config)` | `TextInputDef` | A modal text-input field. |
+| `row(...components)` | `ActionRowBuilder<C>` | Wrap components in a row. |
+
+Each registrable component (`Button`, `StringSelect`, …, `Modal`) extends its
+routing interface and adds `build(...args: BuildArgs<P>)`, which returns the
+discord.js builder. `build` requires exactly the params declared in the id
+pattern.
+
+```ts
+interface ButtonConfig<P extends string, R> {
+  id: P;                       // pattern: "name" or "name:{param}"
+  label?: string;
+  style?: ButtonStyleInput;    // "Primary" | "Secondary" | "Success" | "Danger" | ButtonStyle.*
+  emoji?: ComponentEmojiResolvable;
+  disabled?: boolean;
+  guards?: readonly Guard[];
+  run: (ctx: ButtonContext<Params<P>>) => Awaitable<R>;
+}
+
+interface LinkButtonConfig { url: string; label?: string; emoji?: ComponentEmojiResolvable; disabled?: boolean; }
+
+interface StringSelectConfig<P extends string, R> {
+  id: P;
+  options: readonly SelectMenuComponentOptionData[];
+  placeholder?: string; minValues?: number; maxValues?: number; disabled?: boolean;
+  guards?: readonly Guard[];
+  run: (ctx: StringSelectContext<Params<P>>) => Awaitable<R>;
+}
+
+interface EntitySelectConfig<P extends string> {
+  id: P; placeholder?: string; minValues?: number; maxValues?: number; disabled?: boolean;
+  guards?: readonly Guard[];
+}
+// user/role/mentionable selects take EntitySelectConfig & { run };
+// channelSelect additionally takes { channelTypes?: readonly ChannelType[] }.
+
+function textInput(config: {
+  label: string;
+  style?: TextInputStyleInput;     // "Short" | "Paragraph" | TextInputStyle
+  placeholder?: string; required?: boolean; minLength?: number; maxLength?: number; value?: string;
+}): TextInputDef;
+
+interface ModalConfig<P extends string, F extends Record<string, TextInputDef>, R> {
+  id: P;
+  title: string;
+  fields: F;
+  guards?: readonly Guard[];
+  run: (ctx: ModalContext<Params<P>, keyof F & string>) => Awaitable<R>;
+}
+```
+
+### Component contexts
+
+| Class | Extra members |
+| ----- | ------------- |
+| `MessageComponentContext<P, I>` | `params`, `customId`, `message`, `update(input)`, `deferUpdate()`, `showModal(modal)`, `awaitModal(modal, options?)` (+ BaseContext) |
+| `ButtonContext<P>` | — |
+| `StringSelectContext<P>` | `values: string[]`, `value: string \| undefined` |
+| `UserSelectContext<P>` | `values`, `users`, `members` |
+| `RoleSelectContext<P>` | `values`, `roles` |
+| `ChannelSelectContext<P>` | `values`, `channels` |
+| `MentionableSelectContext<P>` | `values`, `users`, `roles`, `members` |
+| `ModalContext<P, F>` | `params`, `fields: Record<F, string>`, `customId` (+ BaseContext) |
+
+### `class ComponentRegistry`
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `add(...defs: ComponentDef[])` | `this` | Register components (override by namespace). |
+| `onError(handler: ComponentErrorHandler)` | `this` | Set the error handler. |
+| `size` | `number` | Count. |
+| `handle(interaction: Interaction)` | `Promise<boolean>` | Route an interaction; `true` if matched. |
+| `setLogger(logger: Logger)` | `this` | Debug logger for dispatch tracing. |
+| `setUsageHook(hook: (event: UsageEvent) => void)` | `this` | Called after each component run (success or error). |
+| `setDefaultGuards(guards: readonly Guard[])` | `this` | Guards run before each component's own guards. |
+
+```ts
+type ComponentErrorHandler = (error: Error, interaction: RepliableInteraction) => Awaitable<void>;
+type ComponentDef = ButtonRoute | StringSelectRoute | UserSelectRoute | RoleSelectRoute
+  | ChannelSelectRoute | MentionableSelectRoute | ModalRoute;
+```
+
+### Custom-id codec
+
+| Symbol | Description |
+| ------ | ----------- |
+| `type ParamNames<S>` | Union of `{param}` names in a pattern. |
+| `type Params<S>` | The params object a pattern resolves to. |
+| `type BuildArgs<S>` | `build()` args (none when no params). |
+| `const MAX_CUSTOM_ID_LENGTH` | `100`. |
+| `function compilePattern(pattern)` | → `CompiledPattern { pattern, namespace, paramNames }`. |
+| `function buildCustomId(compiled, params)` | Encode a concrete id. |
+| `function parseCustomId(customId)` | → `ParsedCustomId { namespace, values }`. |
+| `function paramsFromValues(paramNames, values)` | Map values onto names. |
+
+---
+
+## Contexts (shared)
+
+### `abstract class BaseContext<I>`
+
+The base for every interaction context.
+
+| Member | Type | Description |
+| ------ | ---- | ----------- |
+| `interaction` | `I` | Raw discord.js interaction. |
+| `client` / `user` / `member` / `guild` / `guildId` / `channel` / `channelId` / `locale` | — | Accessors. |
+| `deferred` / `replied` | `boolean` | Interaction state. |
+| `reply(input)` | `Promise<InteractionResponse>` | Initial response. |
+| `replyEphemeral(input)` | `Promise<InteractionResponse>` | Hidden reply. |
+| `defer({ ephemeral? })` | `Promise<InteractionResponse>` | Acknowledge, respond later. |
+| `editReply(input)` | `Promise<Message>` | Edit the response. |
+| `followUp(input)` | `Promise<Message>` | Additional message. |
+| `send(input)` | `Promise<void>` | State-aware reply/edit/followUp. |
+| `error(input, options?)` | `Promise<void>` | State-aware preset error embed; defaults to ephemeral (pass `{ ephemeral: false }` to override). |
+| `success` / `info` / `warn` `(input, options?)` | `Promise<void>` | State-aware preset embeds (green / blue / yellow). |
+| `replyError(input, options?)` | `Promise<InteractionResponse>` | Initial-reply error embed; defaults to ephemeral. |
+| `replySuccess` / `replyInfo` / `replyWarn` `(input, options?)` | `Promise<InteractionResponse>` | Initial-reply preset embeds. |
+| `botPermissions` | `Readonly<PermissionsBitField>` | The bot's resolved permissions in the channel (zero-fetch). |
+| `botMissing(required)` | `PermissionsString[]` | Permission names the bot is missing here. |
+| `userMissing(required)` | `PermissionsString[]` | Permission names the invoking user is missing here. |
+| `awaitMessageFrom(userId?, options?)` | `Promise<Message \| null>` | Wait for the next message from a user in this channel. |
+
+```ts
+type ReplyData = InteractionReplyOptions & { ephemeral?: boolean };
+type ReplyInput = string | ReplyData;
+function normalizeReply(input: ReplyInput): InteractionReplyOptions;
+function asEphemeral(input: ReplyInput): ReplyData;
+```
+
+---
+
+## Plugins
+
+```ts
+interface SpearPlugin { name: string; setup(client: SpearClient): Awaitable<void>; }
+function definePlugin(plugin: SpearPlugin): SpearPlugin;
+```
+
+---
+
+## Loading
+
+```ts
+interface LoadOptions { extensions?: readonly string[]; recursive?: boolean; } // defaults: [.js,.mjs,.cjs], true
+function collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>;
+function loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>;
+```
+
+`SpearClient.load(dir, options?)` is the method form of `loadInto`.
+
+---
+
+## Added in 0.2
+
+New subsystems, each with a dedicated guide. The `SpearClient` options
+`{ logger?, dotenv?, cooldown?, prefix?, usage?, embeds?, guards? }` configure them.
+
+### Logging — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/logging.md)
+
+```ts
+class Logger { log(level, message, options?): void; debug/info/warn/error(message: string, options?: { error?: Error; data?: Record<string, LogValue> }): void; child(scope: string): Logger; setLevel(level: LogThreshold): this; enabled(level: LogLevel): boolean; addTransport(sink): this; setTransports(sinks): this; }
+type LogLevel = "debug" | "info" | "warn" | "error";
+type LogThreshold = LogLevel | "silent";
+function consoleSink(entry: LogEntry): void;
+function toError(value: unknown): Error;
+// client.logger is a Logger; new SpearClient({ logger: { level: "debug" } })
+```
+
+### Environment — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/env.md)
+
+```ts
+function parseEnv(content: string): Record<string, string>;
+function loadEnv(options?: { path?: string; override?: boolean }): Record<string, string>;
+const env: { string(k, fallback?); number(k, fallback?); boolean(k, fallback?); require(k): string };
+// client auto-loads .env on start(); disable/configure via the dotenv option
+```
+
+### Cooldowns — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/cooldown.md)
+
+```ts
+interface CooldownConfig { duration: number; scope?: "user" | "guild" | "channel" | "global"; exempt?: { users?: string[]; roles?: string[] }; overrides?: { users?: Record<string, number>; roles?: Record<string, number> }; message?: string | ((remainingMs: number) => string); }
+class CooldownManager { consume(bucket, input, actor, now?); peek(...); reset(...); clear(); }
+type CooldownInput = number | CooldownConfig;       // a bare ms duration, or a full config
+type CooldownScope = "user" | "guild" | "channel" | "global";
+type CooldownResult = { allowed: true } | { allowed: false; remaining: number };
+interface CooldownActor { userId; roleIds; guildId; channelId; }   // also: CooldownExemptions, CooldownOverrides
+function normalizeCooldown(input: CooldownInput): CooldownConfig;
+function effectiveDuration(config: CooldownConfig, actor: CooldownActor): number | null; // null = exempt
+function formatCooldownMessage(config: CooldownConfig, remainingMs: number): string;
+// command({ cooldown: number | CooldownConfig }); new SpearClient({ cooldown }); client.cooldowns
+```
+
+### Scheduled tasks — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/scheduler.md)
+
+```ts
+function task(config: { name: string; cron?: string; interval?: number; runOnStart?: boolean; run: (client: SpearClient) => Awaitable<void> }): ScheduledTask;
+function cron(expression: string): CronExpression; // .next(from?: Date): Date
+class TaskScheduler { add/remove/list/size/active/start/stop/setLogger; delay/followUp/reconcile (see "Scheduler — one-shot + reconcile") }
+// client.register(task(...)); client.schedule(config); client.scheduler
+```
+
+### Prefix commands — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/prefix.md)
+
+```ts
+function prefixCommand<TArgs, R>(config: { name: string; aliases?: readonly string[]; description?: string; cooldown?: CooldownInput; guards?: readonly Guard[]; args?: (a: PrefixArgsBuilder<{}>) => PrefixArgsBuilder<TArgs>; run: (ctx: PrefixContext<TArgs>) => Awaitable<R> }): PrefixCommand;
+class PrefixContext<TArgs> { message; commandName; args: string[]; rest: string; options: TArgs; client; author; member; guild; guildId; channel; channelId; reply(content); send(content); }
+// new SpearClient({ prefix: "!" | string[] | { prefix, mention?, ignoreBots?, caseInsensitive? } }); client.prefix
+// reading others' content needs the privileged MessageContent intent (Intents.messages)
+```
+
+### Usage tracking — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/usage.md)
+
+```ts
+interface UsageEvent { type: UsageType; name: string; userId?; userTag?; guildId?; channelId?; detail?; outcome?: UsageOutcome; durationMs?: number; options?: Readonly<Record<string, UsageMetaValue>>; errorMessage?: string; timestamp: Date; }
+type UsageType = "command" | "prefix" | "component" | "event";
+type UsageOutcome = "success" | "error";
+type UsageMetaValue = string | number | boolean | null;
+function formatUsage(event: UsageEvent): string; // default channel-line renderer
+interface UsageStore { record(event): Awaitable<void>; all(): Awaitable<readonly UsageEvent[]>; }
+class MemoryUsageStore { record; all; size; byUser(id); clear; }
+class JsonFileUsageStore { constructor(path: string); record; all; }
+class UsageTracker { setStore(store); reportTo(channelId, format?); track(event); store; enabled; }
+// new SpearClient({ usage: { store?, channel?, format? } }); client.usage
+```
+
+---
+
+## Added in 0.3
+
+Driven by patterns repeated across long-running production bots: the role/
+permission checks, `.catch(() => null)` fetches, embed factories, pagination
+/confirm flows, mention/duration parsing, locks, config loaders and pluggable
+log/usage transports a real Discord bot ends up writing.
+
+### Embeds — preset replies
+
+```ts
+class Embeds { constructor(options?: EmbedsOptions); error(input); success(input); info(input); warn(input); build(level, input); readonly colors: EmbedColors; readonly icons: EmbedIcons; }
+const defaultEmbeds: Embeds;                 // shared default used when `client.embeds` is unset
+const DEFAULT_EMBED_COLORS: EmbedColors;     // red / green / blue / yellow
+const DEFAULT_EMBED_ICONS: EmbedIcons;       // ⛔ ✅ ℹ️ ⚠️
+// SpearClient owns one as `client.embeds`; configure via the `embeds` option.
+// BaseContext gains ctx.success/info/warn/error (state-aware send) + replySuccess/replyInfo/replyWarn/replyError.
+```
+
+### Guards — declarative preconditions — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/guards.md)
+
+```ts
+type Guard<TCtx extends GuardContext = GuardContext> = (ctx: TCtx) => Awaitable<GuardResult>;
+interface GuardContext { client; user; member; guild; guildId; channelId; }
+type GuardResult = boolean | { allowed: false; reason?: string };
+type RunGuardsResult = { allowed: true } | { allowed: false; reason: string | undefined };
+function runGuards<TCtx extends GuardContext>(ctx: TCtx, guards?: readonly Guard<TCtx>[]): Promise<RunGuardsResult>;
+function denied(reason?: string): GuardResult;
+function guildOnly(reason?: string): Guard;
+function dmOnly(reason?: string): Guard;
+function requireAnyRole(roleIds: readonly string[], reason?: string): Guard;
+function requireAllRoles(roleIds: readonly string[], reason?: string): Guard;
+function requireOwner(ownerIds: readonly string[], reason?: string): Guard;
+function requireUserPermissions(permission: PermissionResolvable, reason?: string): Guard;
+function requireBotPermissions(permission: PermissionResolvable, reason?: string): Guard;
+function guard<TCtx>(predicate: Guard<TCtx>): Guard<TCtx>;
+// every built-in guard takes an optional custom `reason`; each has a sensible default message.
+// per-handler: command({ guards: [...] }), prefixCommand({ guards }), button({ guards }), userCommand({ guards }), ...
+// client-wide: new SpearClient({ guards: [...] })
+```
+
+### Context-menu commands — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/context-menus.md)
+
+```ts
+interface ContextMenuMeta { defaultMemberPermissions?: PermissionResolvable | null; nsfw?: boolean; guildOnly?: boolean; nameLocalizations?: LocalizationMap; cooldown?: CooldownInput; guards?: readonly Guard[]; autoDefer?: AutoDeferInput; }
+function userCommand<R>(config: ContextMenuMeta & { name: string; run: (ctx: UserContextMenuContext) => Awaitable<R> }): UserContextMenu;
+function messageCommand<R>(config: ContextMenuMeta & { name: string; run: (ctx: MessageContextMenuContext) => Awaitable<R> }): MessageContextMenu;
+// UserContextMenuContext adds ctx.targetUser, ctx.targetMember; MessageContextMenuContext adds ctx.targetMessage (+ BaseContext).
+// ContextMenuCommand = UserContextMenu | MessageContextMenu; client.contextMenus is a ContextMenuRegistry.
+// Deploy slash commands + menus together with client.deployAllCommands({ guildId }).
+```
+
+### Prefix typed arguments
+
+```ts
+function prefixArgs(): PrefixArgsBuilder<{}>;
+// builder methods — each requires a `name` and takes an optional options object:
+//   .string(name, { required?, minLength?, maxLength?, default? })   -> string
+//   .integer(name, { required?, minValue?, maxValue?, default? })    -> number
+//   .number(name,  { required?, minValue?, maxValue?, default? })    -> number
+//   .boolean(name, { required?, default? })                          -> boolean
+//   .snowflake(name, { required?, default? })   -> string (accepts raw ids and <@u>/<#c>/<@&r> mentions)
+//   .duration(name, { required?, default? })    -> number ("1h30m" parsed to ms)
+//   .rest(name, { required?, default? })        -> string (remaining text)
+// prefixCommand({ args: (a) => a.snowflake("target", { required: true }).duration("dur").rest("reason", { default: "No reason" }), run: (ctx) => ctx.options });
+```
+
+### Pagination + Confirmation
+
+```ts
+function paginate<T>(interaction, items, { render, pageSize?, user?, timeoutMs?, controls?: "prev-next" | "first-prev-next-last", ephemeral?, namespace?, labels?: { first?; prev?; next?; last? } }): Promise<void>;
+function buildPaginatorPage<T>(items, page, options): Promise<{ payload; pages }>;
+function confirm(interaction, { body, title?, confirm?: { label?; style? }, cancel?: { label?; style? }, user?, timeoutMs?, ephemeral?, namespace? }): Promise<{ confirmed: boolean; reason: "confirm" | "cancel" | "timeout"; interaction? }>; // style: "Primary" | "Secondary" | "Success" | "Danger"
+```
+
+### Primitives
+
+```ts
+class KeyedLock { constructor(options?: { ttl?: number; sweep?: number }); tryAcquire(key, ttl?); run(key, fn, { onBusy?, ttl? }); isHeld(key); forget(key); dispose(); readonly size: number; }
+const safeFetch = { member, channel, message, user, guild, role, try }; // each returns T | null; also exported standalone as fetchMember/fetchChannel/fetchMessage/fetchUser/fetchGuild/fetchRole/safeTry
+function withSafeTimeout<T>(p: Promise<T>, ms): Promise<T | null>;
+function formatDuration(ms, opts?: { locale?: string | UnitLabels; largest?: number; units?: readonly DurationUnit[] }): string; // locale: "en"|"en-US"|"en-GB"|"tr"|"tr-TR" or a custom label set; unknown locales fall back to en
+function parseDuration(input: string): number | null;
+function discordTimestamp(date, style?: "t"|"T"|"d"|"D"|"f"|"F"|"R"): string;
+function relativeTimestamp(date): string;
+interface CacheStore { get; set; delete; has; increment; rateLimit; clear; }
+class MemoryCache implements CacheStore { /* TTL, counter, fixed-window rate limit */ }
+function createCache(): CacheStore; // default in-memory cache
+function loadConfig<T>({ file, parser?, schema?, encoding? }): T;
+function loadConfigAsync<T>(opts): Promise<T>;
+function lookup<K, V>(table, resourceName?): (key: K) => V;
+function lookupOptional<K, V>(table): (key: K) => V | undefined; // non-throwing variant of lookup
+```
+
+### Logger transports
+
+```ts
+new Logger({ level, transports: [consoleSink, jsonlSink("./logs/bot.jsonl"), webhookSink({ url, minLevel: "error" })] });
+function jsonlSink(path: string, { minLevel? }?): LogSink;
+function webhookSink({ url, minLevel?, username? }): LogSink;
+function consoleSink(entry: LogEntry): void; // default human-readable console transport
+// Logger.addTransport(sink), setTransports([sinks])
+```
+
+### Scheduler — one-shot + reconcile
+
+```ts
+client.scheduler.delay(name, ms, fn) -> { cancel(): boolean };
+client.scheduler.followUp(name, [10_000, 30_000, 60_000], (i) => ...) -> { cancel(): boolean };
+client.scheduler.reconcile("voice-sessions", async (client) => { /* once on ready */ });
+```
+
+### Deploy diff + dry run
+
+```ts
+client.deployAllCommands({ guildId, dryRun: true });            // returns { skipped, body, reason: "dry-run" }
+client.deployAllCommands({ guildId, strategy: "diff" });        // skips PUT when remote matches
+client.deployAllCommands({ applicationId: "...", strategy: "diff" }); // explicit app id, no ready required
+```
+---
+
+## Added in 0.4
+
+Reliability and moderation helpers distilled from production bots: never lose an
+interaction to the 3-second window, shut down cleanly, run permission/hierarchy
+preflights, persist per-guild settings, and await replies without hand-rolled
+collectors.
+
+### Auto-defer — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/auto-defer.md)
+
+```ts
+type AutoDeferInput = boolean | { ephemeral?: boolean; delayMs?: number };
+interface AutoDeferConfig { ephemeral: boolean; delayMs: number; }
+const DEFAULT_AUTO_DEFER_DELAY_MS = 2000;
+function normalizeAutoDefer(input?: AutoDeferInput): AutoDeferConfig | undefined;
+function armAutoDefer(interaction, config: AutoDeferConfig): () => void; // returns a cancel fn
+type AutoDeferrableInteraction = ChatInputCommandInteraction | UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction;
+// Enable per handler: command({ autoDefer: true }), userCommand({ autoDefer }), messageCommand({ autoDefer })
+// Or globally: new SpearClient({ autoDefer: true }). With it on, respond via ctx.send / ctx.editReply.
+// Arms a timer when the handler starts; defers if it hasn't responded by ~2s, preventing "Unknown interaction" (10062).
+```
+
+### Graceful shutdown
+
+```ts
+interface GracefulShutdownOptions {
+  signals?: readonly NodeJS.Signals[];   // default ["SIGINT", "SIGTERM"]
+  timeoutMs?: number;                     // force-exit after this; default 10000
+  exit?: boolean;                         // call process.exit when done; default true
+  onShutdown?: (signal: NodeJS.Signals) => Awaitable<void>; // runs before client.destroy()
+  logger?: { info?(msg): void; error?(msg, meta?): void };
+}
+interface Destroyable { destroy(): Awaitable<void>; } // a discord.js Client qualifies
+interface ShutdownLogger { info?(message: string): void; error?(message: string, meta?: unknown): void; }
+function gracefulShutdown(client: Destroyable, options?: GracefulShutdownOptions): () => void;
+// SpearClient.enableGracefulShutdown(options?) wires it with client.logger and returns a disposer.
+```
+
+### Permissions & moderation — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/permissions.md)
+
+```ts
+type PermissionHolder = GuildMember | Role;
+function missingPermissions(channel: GuildBasedChannel, who: PermissionHolder, required: PermissionResolvable): PermissionsString[];
+function botMissingPermissions(channel: GuildBasedChannel, required: PermissionResolvable): PermissionsString[];
+function hasPermissions(channel: GuildBasedChannel, who: PermissionHolder, required: PermissionResolvable): boolean;
+function compareRoles(a: GuildMember, b: GuildMember): number;     // by highest-role position
+function canActOn(actor: GuildMember, target: GuildMember): boolean;
+function formatPermissions(permissions: PermissionResolvable): string; // human, comma-separated
+
+type ModerationCheckResult = { ok: true } | { ok: false; reason: string };
+interface ModerationCheckOptions { moderator: GuildMember; target: GuildMember; me?: GuildMember | null; action?: string; }
+function moderationCheck(options: ModerationCheckOptions): ModerationCheckResult; // self / owner / role-hierarchy preflight
+```
+
+### Persistent storage
+
+```ts
+interface KeyValueStore {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  has(key: string): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  keys(): Promise<string[]>;
+  clear(): Promise<void>;
+}
+class MemoryStore implements KeyValueStore { /* deep-cloned in-memory */ }
+class JsonStore implements KeyValueStore { constructor(path: string); /* atomic JSON file */ }
+function namespaced(store: KeyValueStore, prefix: string): KeyValueStore;
+
+interface SettingsManager<T> { readonly defaults: T; readonly store: KeyValueStore; get(id): Promise<T>; set(id, patch: Partial<T>): Promise<T>; reset(id): Promise<void>; }
+interface CreateSettingsOptions<T> { store: KeyValueStore; defaults: T; namespace?: string; } // namespace default "settings"
+function createSettings<T extends Record<string, unknown>>(options: CreateSettingsOptions<T>): SettingsManager<T>;
+```
+
+### Collectors
+
+```ts
+interface AwaitMessageOptions { filter?: (m: Message) => boolean; time?: number; }   // time default 60000
+function awaitMessage(channel: CollectableChannel, options?: AwaitMessageOptions): Promise<Message | null>;
+interface AwaitComponentOptions { filter?; time?; componentType?: ComponentType; }   // time default 60000
+function awaitComponent(message: Message, options?: AwaitComponentOptions): Promise<MessageComponentInteraction | null>;
+interface AwaitModalOptions { time?: number; filter?: (i: ModalSubmitInteraction) => boolean; } // time default 120000
+function showAndAwaitModal(interaction: ModalShowingInteraction, modal: ModalLike, options?: AwaitModalOptions): Promise<ModalSubmitInteraction | null>;
+// Context sugar: ctx.awaitMessageFrom(userId?, options?) and ctx.awaitModal(modal, options?) (command + component contexts).
+```
+
+### Discord errors — [guide](https://raw.githubusercontent.com/byigitt/spearkit/main/docs/errors.md)
+
+```ts
+const DiscordErrorCode = { UnknownChannel, UnknownGuild, UnknownMember, UnknownMessage, UnknownUser,
+  UnknownInteraction, MissingAccess, CannotExecuteActionOnDMChannel, CannotSendMessagesToThisUser,
+  MissingPermissions, InvalidFormBodyOrContentType, InteractionHasAlreadyBeenAcknowledged,
+  MaximumNumberOfGuildsReached, MaximumNumberOfReactionsReached } as const; // named RESTJSONErrorCodes
+type DiscordErrorCodeValue = (typeof DiscordErrorCode)[keyof typeof DiscordErrorCode];
+function isDiscordError(error: unknown, code?: number | string | readonly (number | string)[]): error is DiscordAPIError;
+function isHTTPError(error: unknown): error is HTTPError;
+function isRateLimitError(error: unknown): boolean;        // HTTP 429
+function explainDiscordError(error: unknown): string | null; // end-user-friendly sentence, or null
+// The default command/component error reply uses explainDiscordError(...) when it can.
+```
+
+### Message formatting
+
+```ts
+const MESSAGE_CHARACTER_LIMIT = 2000;
+function truncate(text: string, max: number, suffix?: string): string;       // suffix default "…"
+interface ChunkOptions { max?: number; }                                      // default MESSAGE_CHARACTER_LIMIT
+function chunkMessage(text: string, options?: ChunkOptions): string[];        // splits on line/word boundaries
+```
+
+### Dynamic prefixes
+
+```ts
+// PrefixOptions gains a per-message resolver (e.g. a per-guild prefix from a store):
+interface PrefixOptions { /* …prefix, mention, ignoreBots, caseInsensitive… */
+  dynamic?: (message: Message) => Awaitable<string | readonly string[] | null | undefined>;
+}
+// Dynamic prefixes are tried in addition to any static prefix. Keep the resolver fast (cache it).
+```
+
+---