spearkit 0.3.0 → 0.3.1

package/.claude/skills/spearkit/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: spearkit
+description: >-
+  Write and edit Discord bots built with the spearkit package ("discord.js++"):
+  type-safe slash commands, options, subcommands, autocomplete, buttons / select
+  menus / modals with custom-id routing, events, cooldowns, scheduled tasks,
+  prefix commands, guards, context menus, pagination / confirm, preset embeds,
+  structured logging, usage tracking and dotenv. Use whenever a file imports from
+  "spearkit", or when asked to build or modify a Discord bot, slash command,
+  button, select menu, modal, autocomplete, or interaction handler in a spearkit
+  project.
+---
+
+# spearkit
+
+spearkit is a developer-experience-first layer over [discord.js](https://discord.js.org).
+It **re-exports the entire discord.js surface** (so it is a drop-in replacement)
+and adds a fully type-safe API: handlers never see `any`/`unknown`. Install with
+`npm install spearkit discord.js`.
+
+When a task needs more than this file, load
+[`reference/cheatsheet.md`](reference/cheatsheet.md) (every exported symbol + ready
+recipes). The package also ships `llms-full.txt` (all docs in one file) and a
+`docs/` folder; in a consumer project they sit under `node_modules/spearkit/`.
+
+## Non-negotiable rules
+
+1. **Import only from `"spearkit"`** — spearkit's helpers *and* every discord.js
+   symbol (`Client`, `EmbedBuilder`, `GatewayIntentBits`, `REST`, `Routes`,
+   `PermissionFlagsBits`, …). Never add a separate `import … from "discord.js"`.
+2. **Use `SpearClient`** (extends discord.js `Client`; routes interactions).
+   `intents` is optional → defaults to `Intents.default` (`[Guilds]`).
+3. **Co-locate** definition + handler in one object; `client.register(...)` it.
+   **Never** write an `interactionCreate` switch or parse custom ids by hand —
+   spearkit routes commands by name and components by custom-id namespace.
+4. **Lifecycle order:** `register(...)` → `await client.start(token)` →
+   `await client.deployCommands({ guildId })`. Deploy **after** `start()`; deploy
+   only when command *definitions* change (not every restart).
+5. **The ready event is `clientReady`**, not `ready` (discord.js v14.16 rename).
+6. **Trust inference.** Required options are non-nullable, optional ones are
+   `T | undefined`, `choices` narrow to a literal union, custom-id `{param}`s and
+   modal field keys are typed. Do not cast; do not annotate handler args.
+7. **Hidden replies:** `ctx.replyEphemeral(...)` or `ctx.reply({ content, ephemeral: true })`
+   (spearkit normalizes `ephemeral`). Do not hand-set message flags.
+
+## Minimal 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", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // ctx.options.who: User
+});
+
+client.register(greet, event("clientReady", (c) => console.log(c.user.tag)));
+await client.start(process.env.DISCORD_TOKEN);              // falls back to DISCORD_TOKEN
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId → global (slow)
+```
+
+## Recipes
+
+### Slash command with typed options
+
+```ts
+const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),     // string
+    times: option.integer({ description: "Count", minValue: 1, maxValue: 5 }),// number | undefined
+    mode: option.string({
+      description: "Visibility",
+      choices: [{ name: "Everyone", value: "public" }, { name: "Just me", value: "private" }],
+    }),                                                                       // "public" | "private" | undefined
+  },
+  run: (ctx) =>
+    ctx.reply({
+      content: ctx.options.text.repeat(ctx.options.times ?? 1),
+      ephemeral: ctx.options.mode === "private",
+    }),
+});
+```
+
+Option builders: `option.string|integer|number|boolean|user|channel|role|mentionable|attachment`.
+Co-located autocomplete: `option.string({ autocomplete: (ctx) => choices.filter(c => c.startsWith(ctx.value)).map(c => ({ name: c, value: c })) })`.
+
+### Subcommands
+
+```ts
+import { commandGroup, subcommand, subcommandGroup, option } from "spearkit";
+
+commandGroup({
+  name: "admin", description: "Admin tools", guildOnly: true,
+  subcommands: {
+    say: subcommand({
+      description: "Speak",
+      options: { message: option.string({ description: "Text", required: true }) },
+      run: (ctx) => ctx.reply(ctx.options.message),
+    }),
+  },
+  groups: {
+    users: subcommandGroup({
+      description: "Manage users",
+      subcommands: {
+        ban: subcommand({
+          description: "Ban", options: { target: option.user({ description: "Who", required: true }) },
+          run: (ctx) => ctx.reply(`Banned ${ctx.options.target.tag}`),
+        }),
+      },
+    }),
+  },
+});
+```
+
+### Components (button / select / modal)
+
+```ts
+import { button, stringSelect, modal, textInput, row } from "spearkit";
+
+const vote = button({
+  id: "vote:{choice}",                 // {choice} → typed param
+  label: "Yes", style: "Success",      // "Primary" | "Secondary" | "Success" | "Danger"
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // ctx.params.choice: string
+});
+
+const colour = stringSelect({
+  id: "colour",
+  options: [{ label: "Red", value: "red" }, { label: "Blue", value: "blue" }],
+  run: (ctx) => ctx.replyEphemeral(ctx.values.join(", ")),     // ctx.values: string[]
+});
+
+const feedback = modal({
+  id: "feedback:{ticket}",
+  title: "Feedback",
+  fields: {
+    summary: textInput({ label: "Summary", required: true }),
+    detail: textInput({ label: "Details", style: "Paragraph" }),
+  },
+  run: (ctx) => ctx.reply(`#${ctx.params.ticket}: ${ctx.fields.summary}`), // params + fields typed
+});
+
+client.register(vote, colour, feedback);
+
+// build() requires exactly the {param}s the id declares (ids cap at 100 chars):
+await channel.send({ content: "Choose:", components: [row(vote.build({ choice: "yes" })), row(colour.build())] });
+```
+
+Component builders: `button`, `linkButton`, `stringSelect`, `userSelect`,
+`roleSelect`, `channelSelect`, `mentionableSelect`, `modal` (+ `textInput`), `row`.
+Component context: `ctx.params`, `ctx.update`, `ctx.deferUpdate`, `ctx.showModal`,
+`ctx.message`; selects add `ctx.values` (+ `ctx.users/roles/channels/members`);
+modals add `ctx.fields`.
+
+### Guards, cooldown, context menus, pagination/confirm
+
+```ts
+import { command, requireAnyRole, guildOnly, userCommand, paginate, confirm } from "spearkit";
+
+const purge = command({
+  name: "purge", description: "Delete messages",
+  guards: [guildOnly(), requireAnyRole(["MOD_ROLE_ID"])],
+  cooldown: { duration: 10_000, scope: "user" },
+  run: (ctx) => ctx.replySuccess("Done"),
+});
+
+const report = userCommand({ name: "Report", run: (ctx) => ctx.replyEphemeral(`Reported ${ctx.targetUser.tag}`) });
+
+await paginate(ctx.interaction, items, {
+  pageSize: 10,
+  render: (slice, { page, pages }) =>
+    new EmbedBuilder().setTitle(`Page ${page + 1}/${pages}`).setDescription(slice.join("\n")),
+});
+
+const { confirmed } = await confirm(ctx.interaction, {
+  body: "Reset everything?", confirm: { label: "Reset", style: "Danger" },
+});
+if (!confirmed) return ctx.error("Cancelled.");
+```
+
+Guards usable on `command`/`prefixCommand`/`button`/`userCommand`/`messageCommand`
+configs, or client-wide via `new SpearClient({ guards: [...] })`.
+
+## Context (every handler)
+
+`reply` · `replyEphemeral` · `defer({ ephemeral? })` · `editReply` · `followUp` ·
+`send` (state-aware) · `error(msg)` · preset embeds `success/info/warn/error`
+(+ `replySuccess/Info/Warn/Error`) · accessors `client/user/member/guild/guildId/
+channel/channelId/locale` · state `deferred/replied`. Commands add `ctx.options`,
+`ctx.commandName`, `ctx.subcommand`, `ctx.showModal`.
+
+## Subsystems (configured on `SpearClient` options)
+
+- **Cooldowns** — `command({ cooldown: number | CooldownConfig })` or
+  `new SpearClient({ cooldown })`; scopes `user|guild|channel|global`, plus
+  `exempt`/`overrides`.
+- **Scheduled tasks** — `task({ name, cron?, interval?, runOnStart?, run })`,
+  `client.schedule(...)`, `client.scheduler.delay/followUp/reconcile`, `cron(expr)`.
+- **Prefix commands** — `prefixCommand({ name, aliases?, cooldown?, guards?, args?, run })`
+  + `new SpearClient({ prefix: "!" })`. Typed args:
+  `args: (a) => a.snowflake("target").duration("d").rest("reason")` → `ctx.options`.
+  Reading **other users'** content needs the privileged `MessageContent` intent —
+  use `Intents.messages` and enable it in the Developer Portal.
+- **Context menus** — `userCommand`/`messageCommand`; deploy with slash commands
+  via `client.deployAllCommands({ guildId, strategy: "diff", dryRun? })`.
+- **Logging** — `client.logger`; `new SpearClient({ logger: { level, transports: [consoleSink, jsonlSink(path), webhookSink({ url })] } })`.
+- **Usage tracking** — `new SpearClient({ usage: { store?, channel?, format? } })`;
+  `MemoryUsageStore`, `JsonFileUsageStore`.
+- **Env** — `.env` auto-loads on `start()`; read with `env.string/number/boolean/require`.
+- **Plugins** — `definePlugin({ name, setup(client) })`, then `await client.use(plugin)`.
+- **File-based loading** — `await client.load(dir)`. Imports **compiled JS**
+  (default extensions `.js/.mjs/.cjs`); build before running compiled output.
+- **Primitives** — `KeyedLock`, `safeFetch.{member,channel,message,user,guild,role,try}`,
+  `formatDuration`/`parseDuration`/`discordTimestamp`/`relativeTimestamp`,
+  `MemoryCache`, `loadConfig`.
+
+## Mistakes to avoid
+
+- Importing from `"discord.js"` (use `"spearkit"`).
+- Listening on `"ready"` instead of `"clientReady"`.
+- `deployCommands()` before `start()`, or deploying on every restart.
+- Hand-rolling an `interactionCreate` switch or splitting custom ids manually.
+- Passing wrong/missing params to `component.build(...)` (typed; pass exactly the
+  declared `{param}`s).
+- Forgetting the `MessageContent` intent when prefix commands must read other
+  users' messages.
+
+## Verify your work
+
+In a spearkit repo, run `npm run typecheck` (and `npm test`) — option values,
+custom-id params and modal fields are statically checked, so a type error usually
+means the definition and handler disagree.

package/.claude/skills/spearkit/reference/cheatsheet.md

@@ -0,0 +1,218 @@
+# spearkit cheatsheet
+
+Condensed map of every spearkit export. All importable from `"spearkit"` alongside
+the full discord.js surface. For prose and edge cases, read the package's
+`llms-full.txt` or `docs/`.
+
+## Client
+
+```ts
+new SpearClient(options?: Partial<ClientOptions>) // intents optional → Intents.default
+client.commands   // CommandRegistry
+client.events     // EventRegistry
+client.components // ComponentRegistry
+client.register(...items)            // route SlashCommand | EventDef | ComponentDef | PrefixCommand | ContextMenu | ScheduledTask
+client.use(...plugins): Promise<this>
+client.load(dir, options?): Promise<number>            // imports compiled JS (.js/.mjs/.cjs)
+client.start(token?): Promise<this>                    // login; falls back to DISCORD_TOKEN
+client.deployCommands({ guildId? }): Promise<DeployResult>      // after start()
+client.deployAllCommands({ guildId?, applicationId?, strategy?: "diff", dryRun? }) // slash + context menus
+client.schedule(taskConfig); client.scheduler          // TaskScheduler
+client.cooldowns; client.prefix; client.usage; client.logger; client.embeds
+
+const Intents = { none: [], default: [Guilds], guilds: [Guilds, GuildMembers],
+                  messages: [Guilds, GuildMessages, MessageContent], all: /* every intent */ }
+```
+
+## Commands & options
+
+```ts
+command({ name, description, options?, defaultMemberPermissions?, nsfw?, guildOnly?,
+          nameLocalizations?, descriptionLocalizations?, guards?, cooldown?, run })
+commandGroup({ name, description, subcommands?, groups?, defaultMemberPermissions?, nsfw?, guildOnly?, ... })
+subcommand({ description, options?, run, ... })
+subcommandGroup({ description, subcommands, ... })
+
+option.string({ description, required?, choices?, minLength?, maxLength?, autocomplete? })   // string
+option.integer({ description, required?, choices?, minValue?, maxValue?, autocomplete? })    // number
+option.number(...)   // number
+option.boolean(...)  // boolean
+option.user(...)     // User
+option.channel({ ..., channelTypes? }) // channel union
+option.role(...)     // Role | APIRole
+option.mentionable(...) // user/role/member
+option.attachment(...)  // Attachment
+
+// choices: { name, value, nameLocalizations? }[]   (value narrows the resolved type to a literal union)
+// autocomplete: (ctx: AutocompleteContext) => Awaitable<OptionChoice[]>   ctx.value / ctx.respond(...)
+```
+
+`CommandContext`: `options`, `commandName`, `subcommand`, `showModal(modal)` + BaseContext.
+
+## Components
+
+```ts
+button({ id, label?, style?, emoji?, disabled?, guards?, run })   // style: "Primary"|"Secondary"|"Success"|"Danger"|ButtonStyle.*
+linkButton({ url, label?, emoji?, disabled? })                    // returns ButtonBuilder (no handler)
+stringSelect({ id, options, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+userSelect / roleSelect / mentionableSelect ({ id, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+channelSelect({ id, channelTypes?, placeholder?, minValues?, maxValues?, disabled?, guards?, run })
+modal({ id, title, fields, run })   // fields: Record<string, TextInputDef>
+textInput({ label, style?, placeholder?, required?, minLength?, maxLength?, value? }) // style: "Short"|"Paragraph"
+row(...components): ActionRowBuilder
+
+component.build(params?)  // requires exactly the {param}s in id; no args when none
+
+// id pattern: "name" or "name:{a}:{b}"   →  ctx.params.a, ctx.params.b (string)
+// MAX_CUSTOM_ID_LENGTH = 100
+```
+
+Contexts: `ButtonContext` (params); `StringSelectContext` (values, value);
+`UserSelectContext`/`MentionableSelectContext` (values, users, members[, roles]);
+`RoleSelectContext` (values, roles); `ChannelSelectContext` (values, channels);
+`ModalContext` (params, fields). All component contexts: `update`, `deferUpdate`,
+`showModal`, `message`, `customId`.
+
+## Events
+
+```ts
+event("clientReady", (c) => ...)              // name from discord.js ClientEvents (args inferred)
+event({ name, once?, run })
+// errors + rejections route to the client's "error" event
+```
+
+## Contexts (BaseContext — every handler)
+
+```ts
+reply(input) · replyEphemeral(input) · defer({ ephemeral? }) · editReply(input) ·
+followUp(input) · send(input) · error(message)
+success(input) · info(input) · warn(input) · error(input)                 // preset embeds, state-aware
+replySuccess/replyInfo/replyWarn/replyError(input)
+client · user · member · guild · guildId · channel · channelId · locale · deferred · replied
+// ReplyInput = string | (InteractionReplyOptions & { ephemeral?: boolean })
+```
+
+## Guards
+
+```ts
+guildOnly(reason?) · dmOnly(reason?) · requireAnyRole(ids, reason?) · requireAllRoles(ids, reason?)
+requireOwner(ownerIds, reason?) · requireUserPermissions(perm, reason?) · requireBotPermissions(perm, reason?)
+guard(predicate) · denied(reason?)
+// per-handler: { guards: [...] } on command/prefixCommand/button/userCommand/messageCommand
+// client-wide:  new SpearClient({ guards: [...] })
+```
+
+## Cooldowns
+
+```ts
+command({ cooldown: number | CooldownConfig })
+new SpearClient({ cooldown: CooldownConfig })
+CooldownConfig = { duration, scope?: "user"|"guild"|"channel"|"global",
+                   exempt?: { users?, roles? }, overrides?: { users?, roles? },
+                   message?: string | ((remainingMs) => string) }
+```
+
+## Scheduler
+
+```ts
+task({ name, cron?, interval?, runOnStart?, run: (client) => ... })   // register() it
+client.schedule(config)
+cron(expr).next(from?: Date): Date
+client.scheduler.delay(name, ms, fn) -> { cancel() }
+client.scheduler.followUp(name, [10_000, 30_000], (i) => ...) -> { cancel() }
+client.scheduler.reconcile(name, async (client) => ...)   // once on ready
+```
+
+## Prefix commands
+
+```ts
+new SpearClient({ prefix: "!" | string[] | { prefix, mention?, ignoreBots?, caseInsensitive? } })
+prefixCommand({ name, aliases?, description?, cooldown?, guards?, args?, run })
+// PrefixContext: message, commandName, args: string[], rest: string, reply, send, options (when args used)
+prefixArgs() builder: .string(n) .integer(n) .number(n) .boolean(n) .snowflake(n) .duration(n) .rest(n)
+prefixCommand({ args: (a) => a.snowflake("target").duration("d").rest("reason"), run: (ctx) => ctx.options })
+// reading other users' content requires the privileged MessageContent intent (Intents.messages)
+```
+
+## Context menus
+
+```ts
+userCommand({ name, guards?, cooldown?, run: (ctx) => ctx.targetUser / ctx.targetMember })
+messageCommand({ name, guards?, cooldown?, run: (ctx) => ctx.targetMessage })
+// deploy with slash commands via client.deployAllCommands(...)
+```
+
+## Pagination & confirm
+
+```ts
+paginate(interaction, items, { render, pageSize?, user?, timeoutMs?, controls?: "prev-next"|"first-prev-next-last", ephemeral?, labels?, namespace? })
+buildPaginatorPage(items, page, options) -> { payload, pages }
+confirm(interaction, { body, title?, confirm?, cancel?, user?, timeoutMs?, ephemeral?, namespace? })
+  -> { confirmed: boolean, reason: "confirm"|"cancel"|"timeout", interaction? }
+```
+
+## Embeds
+
+```ts
+client.embeds.{ error|success|info|warn|build(level, input) }
+createEmbeds(opts?)  // alias for new Embeds(opts)
+new SpearClient({ embeds: { /* colors/icons per level */ } })
+// BaseContext exposes ctx.success/info/warn/error + replySuccess/Info/Warn/Error
+```
+
+## Logging
+
+```ts
+new Logger({ level, transports: [consoleSink, jsonlSink("./logs/bot.jsonl"), webhookSink({ url, minLevel: "error" })] })
+logger.debug/info/warn/error(message, { error?, data? }); logger.child(scope); logger.setLevel(level); logger.enabled(level)
+logger.addTransport(sink); logger.setTransports([sinks])
+new SpearClient({ logger: { level: "debug" } })   // client.logger
+```
+
+## Usage tracking
+
+```ts
+new SpearClient({ usage: { store?, channel?, format? } })   // client.usage
+MemoryUsageStore  // record, all, size, byUser(id), clear
+JsonFileUsageStore(path)
+// UsageEvent { type: "command"|"prefix"|"component"|"event", name, userId?, userTag?, guildId?, channelId?,
+//              detail?, outcome?: "success"|"error", durationMs?, errorMessage?, options?, timestamp }
+```
+
+## Env
+
+```ts
+loadEnv({ path?, override? }); parseEnv(content)
+env.string(k, fallback?) · env.number(k, fallback?) · env.boolean(k, fallback?) · env.require(k)
+// SpearClient auto-loads .env on start(); configure/disable via the `dotenv` option
+```
+
+## Plugins & loading
+
+```ts
+definePlugin({ name, setup(client) }); await client.use(plugin)
+collectModules(dir, options?); loadInto(client, dir, options?)
+client.load(dir, { extensions?: readonly string[], recursive? })  // defaults [.js,.mjs,.cjs], true
+```
+
+## Primitives
+
+```ts
+new KeyedLock(); lock.tryAcquire(key, ttl?); lock.run(key, fn, { onBusy?, ttl? }); lock.isHeld(key); lock.forget(key); lock.dispose()
+safeFetch.{ member, channel, message, user, guild, role, try }  // each returns T | null
+withSafeTimeout(promise, ms)  // T | null
+formatDuration(ms, { locale?: "en"|"tr"|UnitLabels, largest?, units? })
+parseDuration(input): number | null
+discordTimestamp(date, style?: "t"|"T"|"d"|"D"|"f"|"F"|"R"); relativeTimestamp(date)
+new MemoryCache()  // CacheStore: get/set/delete/has/increment/rateLimit/clear (TTL + counters + fixed-window rate limit)
+loadConfig({ file, parser?, schema?, encoding? }); loadConfigAsync(opts)   // JSON/JSON5/YAML
+lookup(table, resourceName?) -> (key) => value
+```
+
+## Error handling
+
+```ts
+client.commands.onError((error, interaction) => interaction.reply({ content: "Oops.", flags: 64 }))
+client.components.onError((error, interaction) => console.error(error))
+// handler errors never crash the process; uncaught ones flow through client.logger
+```

package/AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md — writing code with spearkit
+
+Authoritative rules for AI agents (and humans) writing Discord bots with
+**spearkit**. Read this first; it is short on purpose. For depth, load
+[`llms-full.txt`](./llms-full.txt) (every guide + the full API reference in one
+file) or browse [`docs/`](./docs) and [`examples/`](./examples).
+
+spearkit is **discord.js++**: it re-exports the entire discord.js surface (so it
+is a drop-in replacement) and adds a fully type-safe layer for slash commands,
+options, components, events, cooldowns, scheduled tasks, prefix commands,
+logging, usage tracking and dotenv. Install: `npm install spearkit discord.js`.
+
+## Golden rules
+
+1. **Import everything from `"spearkit"`.** Both spearkit's helpers and every
+   discord.js symbol (`Client`, `EmbedBuilder`, `GatewayIntentBits`, `REST`,
+   `Routes`, …) come from `"spearkit"`. Do **not** add a separate
+   `import … from "discord.js"`.
+2. **Use `SpearClient`, not `Client`.** It extends discord.js `Client` and wires
+   up command/event/component routing. `intents` may be omitted (defaults to
+   `Intents.default`).
+3. **Co-locate definition + handler.** A command's options and `run`, a button's
+   look and click logic, a modal's fields and submit — each in one object.
+4. **Never write an `interactionCreate` switch.** Define commands/components and
+   `client.register(...)` them; spearkit routes by command name and custom-id
+   namespace and decodes typed params for you.
+5. **Lifecycle order:** `client.register(...)` → `await client.start(token)` →
+   `await client.deployCommands({ guildId })`. Deploy **after** `start()` (it
+   uses the client's authenticated REST and the ready application id).
+6. **The ready event is `clientReady`**, not `ready` (discord.js v14.16 rename).
+7. **Trust inference.** Required options are non-nullable, optional ones are
+   `T | undefined`, `choices` narrow to a literal union, custom-id `{param}`s and
+   modal field keys are typed. Don't cast; don't annotate handler args.
+
+## Canonical patterns
+
+### Client + lifecycle
+
+```ts
+import { SpearClient, Intents, command, option, event } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default }); // Intents: none|default|guilds|messages|all
+
+const ready = event("clientReady", (c) => console.log(`Online as ${c.user.tag}`));
+
+client.register(/* commands, events, components */ ready);
+await client.start(process.env.DISCORD_TOKEN);          // falls back to DISCORD_TOKEN
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // omit guildId for global (slow)
+```
+
+### Slash commands + typed options
+
+```ts
+const echo = command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }), // string
+    times: option.integer({ description: "Count", minValue: 1, maxValue: 5 }), // number | undefined
+    who: option.user({ description: "Mention", required: true }),          // User
+  },
+  run: (ctx) =>
+    ctx.reply(ctx.options.text.repeat(ctx.options.times ?? 1)),
+});
+```
+
+Builders: `option.string|integer|number|boolean|user|channel|role|mentionable|attachment`.
+Autocomplete is co-located: `option.string({ autocomplete: (ctx) => [{ name, value }] })`.
+Subcommands: `commandGroup({ name, description, subcommands, groups })` with
+`subcommand(...)` and `subcommandGroup(...)`.
+
+### Interactive components
+
+```ts
+import { button, stringSelect, modal, textInput, row } from "spearkit";
+
+const vote = button({
+  id: "vote:{choice}",                       // {choice} → typed param
+  label: "Yes", style: "Success",            // "Primary"|"Secondary"|"Success"|"Danger"
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // ctx.params.choice: string
+});
+
+const colour = stringSelect({
+  id: "colour",
+  options: [{ label: "Red", value: "red" }, { label: "Blue", value: "blue" }],
+  run: (ctx) => ctx.replyEphemeral(ctx.values.join(", ")),     // ctx.values: string[]
+});
+
+const feedback = modal({
+  id: "feedback:{ticket}",
+  title: "Feedback",
+  fields: { summary: textInput({ label: "Summary", required: true }) },
+  run: (ctx) => ctx.reply(`#${ctx.params.ticket}: ${ctx.fields.summary}`), // typed params + fields
+});
+
+client.register(vote, colour, feedback);
+
+// Put them in a message — build() requires exactly the params the id declares:
+await channel.send({ content: "Choose:", components: [row(vote.build({ choice: "yes" })), row(colour.build())] });
+```
+
+Builders: `button`, `linkButton`, `stringSelect`, `userSelect`, `roleSelect`,
+`channelSelect`, `mentionableSelect`, `modal` (+ `textInput`), `row`.
+Component context: `ctx.params`, `ctx.update(...)`, `ctx.deferUpdate()`,
+`ctx.showModal(modal)`; selects add `ctx.values` (+ `ctx.users/roles/channels/members`);
+modals add `ctx.fields`.
+
+### Context (every handler)
+
+`ctx.reply` · `ctx.replyEphemeral` · `ctx.defer({ ephemeral? })` · `ctx.editReply`
+· `ctx.followUp` · `ctx.send` (state-aware) · `ctx.error(msg)` · preset embeds
+`ctx.success/info/warn/error` (+ `ctx.replySuccess/Info/Warn/Error`) · accessors
+`ctx.client/user/member/guild/guildId/channel/channelId/locale` · state
+`ctx.deferred/replied`. For hidden replies prefer `ctx.replyEphemeral(...)` or
+`ctx.reply({ content, ephemeral: true })` — spearkit normalizes it.
+
+## Subsystems (each has a guide in docs/)
+
+- **Guards** — `guards: [...]` on `command`/`prefixCommand`/`button`/`userCommand`/
+  `messageCommand`, or client-wide `new SpearClient({ guards })`. Helpers:
+  `guildOnly`, `dmOnly`, `requireAnyRole`, `requireAllRoles`, `requireOwner`,
+  `requireUserPermissions`, `requireBotPermissions`, `guard`, `denied`.
+- **Cooldowns** — `command({ cooldown: number | CooldownConfig })` or
+  `new SpearClient({ cooldown })`; scopes `user|guild|channel|global`, `exempt`,
+  `overrides`.
+- **Scheduled tasks** — `task({ name, cron?, interval?, runOnStart?, run })`,
+  `client.schedule(...)`, `client.scheduler.delay/followUp/reconcile`, `cron(expr)`.
+- **Prefix commands** — `prefixCommand({ name, aliases?, cooldown?, guards?, args?, run })`
+  + `new SpearClient({ prefix: "!" })`. Typed args:
+  `args: (a) => a.snowflake("target").duration("d").rest("reason")` → `ctx.options`.
+  Reading **other users'** message content needs the privileged `MessageContent`
+  intent — use `Intents.messages` and enable it in the Developer Portal.
+- **Context menus** — `userCommand({ name, run: (ctx) => ctx.targetUser })`,
+  `messageCommand({ name, run: (ctx) => ctx.targetMessage })`. Deploy slash +
+  menus together with `client.deployAllCommands({ guildId, strategy: "diff", dryRun? })`.
+- **Pagination / confirm** — `paginate(interaction, items, { pageSize, render, user?, timeoutMs?, controls?, ephemeral? })`;
+  `const { confirmed } = await confirm(interaction, { body, confirm?, cancel?, user?, timeoutMs?, ephemeral? })`.
+- **Logging** — `client.logger`; configure via `new SpearClient({ logger: { level, transports: [consoleSink, jsonlSink(path), webhookSink({ url })] } })`.
+- **Usage tracking** — `new SpearClient({ usage: { store?, channel?, format? } })`;
+  `MemoryUsageStore`, `JsonFileUsageStore`.
+- **Env** — `.env` auto-loads on `start()`; read with `env.string/number/boolean/require`.
+- **Plugins** — `definePlugin({ name, setup(client) })`, then `await client.use(plugin)`.
+- **File-based loading** — `await client.load(dir)`. Imports **compiled JS**
+  (default extensions `.js/.mjs/.cjs`), so build before running compiled output.
+- **Primitives** — `KeyedLock`, `safeFetch.{member,channel,message,user,guild,role,try}`,
+  `formatDuration`/`parseDuration`/`discordTimestamp`/`relativeTimestamp`,
+  `MemoryCache`, `loadConfig`.
+
+## Common mistakes to avoid
+
+- Importing from `"discord.js"` in a spearkit project (use `"spearkit"`).
+- Listening on `"ready"` instead of `"clientReady"`.
+- Calling `deployCommands()` before `start()`.
+- Hand-rolling an `interactionCreate` switch or parsing custom ids by hand.
+- Passing the wrong/missing params to `component.build(...)` (it is typed — pass
+  exactly the `{param}`s in the id; custom ids cap at 100 chars).
+- Deploying on every restart — only deploy when command *definitions* change.
+
+## For maintainers
+
+`docs/*.md` is the single source of truth. `llms.txt`, `llms-full.txt` and the
+`website/public/` copies are generated — run `npm run docs:llms` after editing
+docs. A ready-to-use agent skill lives at
+[`.claude/skills/spearkit/`](./.claude/skills/spearkit).

package/README.md

@@ -38,6 +38,19 @@ npm install spearkit discord.js
 - **Guides & API reference** ([`docs/`](./docs)) — the Markdown the site is built from.
 - **Examples** ([`examples/`](./examples)) — one folder per topic (commands, options, components, events, loading, …).
 
+## For AI agents
+
+spearkit ships machine-readable guidance so coding agents write correct code with it:
+
+- **[`AGENTS.md`](./AGENTS.md)** — the golden rules and canonical patterns, auto-read by most coding agents.
+- **[`llms.txt`](./llms.txt)** — an [llmstxt.org](https://llmstxt.org) index of the docs; **[`llms-full.txt`](./llms-full.txt)** is every guide and the full API reference in one file.
+- **Agent skill** ([`.claude/skills/spearkit/`](./.claude/skills/spearkit)) — a drop-in [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) with recipes and a symbol cheatsheet.
+
+`AGENTS.md`, `llms.txt`, `llms-full.txt`, `docs/` and the agent skill ship in the
+npm package as plain files (no install hook), so an installed copy lives under
+`node_modules/spearkit/` — e.g. `node_modules/spearkit/.claude/skills/spearkit/SKILL.md`.
+The `llms` files are generated from `docs/`; run `npm run docs:llms` after editing docs.
+
 ## Quick start
 
 ```ts