aurival 0.7.0 → 0.9.0

package/README.md

@@ -75,8 +75,8 @@ bot.command('say', async (ctx) => {
   ctx.command; // "say"
   ctx.arguments; // the raw rest of the line, unparsed, possibly ""
   ctx.chat; // { id, type, name, member_count }
-  ctx.sender; // { id, handle, name } — always set
-  ctx.message.text; // "/say hi" — the invoking message, verbatim
+  ctx.sender; // { id, handle, name }, always set
+  ctx.message.text; // "/say hi", the invoking message, verbatim
   await ctx.reply('…');
 });
 ```
@@ -184,7 +184,8 @@ bot.command('fix', async (ctx) => {
 });
 
 bot.command('oops', async (ctx) => {
-  await ctx.delete(ctx.message);
+  const sent = await ctx.reply('ignore that');
+  await ctx.delete(sent);
 });
 
 bot.command('upvote', async (ctx) => {
@@ -224,6 +225,10 @@ straight back to `edit()`, `delete()` and `react()` — no id juggling. The `sen
 those, when it is set at all, is known by id alone — `handle` and `name` are empty strings,
 because the REST entity names the sender with a bare `usr_…`.
 
+`edit()` and `delete()` take only the bot's own messages; anyone else's answers
+`message_not_yours`, which is why `oops` above deletes the reply it just sent rather than the
+message that invoked it. `react()` and `unreact()` work on any message in a chat the bot is in.
+
 The typing indicator is automatic: a command handler still running 300 ms after it started
 shows the chat "is thinking", and the indicator clears when the handler returns, including on a
 throw. A handler that replies inside those 300 ms sends nothing, so a fast bot never flickers.
@@ -245,6 +250,11 @@ bot.on('member.joined', async (ctx) => {
 });
 ```
 
+Every entry in `mentions` needs its `@handle` token actually present in `text`, outside any
+code block or inline code, or the server rejects the request — write the handle into the
+message yourself, in plain text; the SDK will not edit `text` for you, and a mention inside
+code, or with no token at all, renders as nothing.
+
 ## Embeds and buttons
 
 `Embed` is a builder — every `setAuthor`/`setThumbnail`/`addField`/`setFooter` call returns the
@@ -258,20 +268,20 @@ already uses:
 ```ts
 import { Embed, Button } from 'aurival';
 
-const embed = new Embed({ title: 'Trivia round 4', description: 'Which ocean is the deepest?', color: '#3E6E8E' })
-  .setAuthor('Quizbot', 'https://cdn.aurival.com/q.png')
-  .setThumbnail('https://cdn.aurival.com/t.png')
-  .addField('Players', '6', true)
-  .addField('Round', '4 of 10', true)
-  .setFooter('Answer within 30s');
+const embed = new Embed({ title: 'Title', description: 'Description. Plain text or markdown, under the title.' })
+  .setAuthor('Author line')
+  .addField('Field name', 'Field value', true)
+  .addField('Second field', 'Second value', true)
+  .setImage('https://bots.aurival.com/docs-assets/aurival-welcome-cover.jpg')
+  .setFooter('Footer text', 'https://bots.aurival.com/docs-assets/aurival-mascot-hero.png');
 
 const buttons = [
-  new Button({ label: 'Pacific', id: 'pacific', style: 'primary' }),
-  new Button({ label: 'Atlantic', id: 'atlantic', style: 'secondary' }),
-  new Button({ label: 'Indian', id: 'indian', style: 'secondary' }),
+  new Button({ label: 'Primary action', id: 'primary', style: 'primary' }),
+  new Button({ label: 'Secondary action', id: 'secondary', style: 'secondary' }),
+  new Button({ label: 'Danger action', id: 'danger', style: 'danger' }),
 ];
 
-await ctx.reply('Ready when you are.', { embeds: [embed], buttons });
+await ctx.reply({ embeds: [embed], buttons });
 ```
 
 A card earns its place when there is something to put on it: buttons, fields, an image. A reply
@@ -288,19 +298,20 @@ url throws, because a link button with nowhere to go is a dead pill:
 import { Button } from 'aurival';
 
 const buttons = [
-  Button.link({ label: 'Full lineup', url: 'https://aurival.com/spaces/deepcuts/lineup' }),
-  Button.link({ label: 'Set notes', url: 'https://example.com/notes' }),
-  new Button({ label: 'Remind me', id: 'remind', style: 'primary' }),
+  Button.link({ label: 'Opens aurival.com', url: 'https://aurival.com' }),
+  Button.link({ label: 'Opens the docs', url: 'https://bots.aurival.com' }),
+  new Button({ label: 'Primary action', id: 'primary', style: 'primary' }),
 ];
 
-await ctx.reply('Doors at 21:00.', { buttons });
+await ctx.reply('Two link buttons and a regular one, sharing one row.', { buttons });
 ```
 
 A link button never comes back to you: no `button.pressed` event, ever, and it never flips the
 row to used. It also stays tappable after a sibling is pressed, and while a sibling is still
 waiting on your `ack()` — the row greys out around it, the link does not. `id` still has to be
 there and still has to be unique in the message, and the SDK still slugs it from the label when
-you leave it out, so that `Set notes` pill gets `id: 'set-notes'` like any other button. Link
+you leave it out, so that `Opens the docs` pill gets `id: 'opens-the-docs'` like any other
+button. Link
 buttons count toward the five-button cap, and a message made only of link buttons is fine.
 
 A url is `https://` and at most 2048 characters, everywhere a url is a link target. A non-link
@@ -315,11 +326,11 @@ you cannot see is worse than an error you can.
 import { Button } from 'aurival';
 
 const buttons = [
-  new Button({ label: 'Maybe', id: 'maybe', style: 'secondary', emoji: '🤔' }),
-  new Button({ label: 'Remind me', id: 'remind', style: 'primary', emoji: '⏰' }),
+  new Button({ label: 'Secondary action', id: 'secondary', style: 'secondary', emoji: '🤔' }),
+  new Button({ label: 'Primary action', id: 'primary', style: 'primary', emoji: '⏰' }),
 ];
 
-await ctx.reply('Set starts in an hour.', { buttons });
+await ctx.reply('Two buttons, each with one emoji in front of the label.', { buttons });
 ```
 
 Exactly one unicode emoji, no custom emoji, no `:shortcode:`, no image url. The emoji does not
@@ -337,16 +348,15 @@ title tappable, and the third argument to `setAuthor` does the same for the auth
 import { Embed } from 'aurival';
 
 const embed = new Embed({
-  title: "Tonight's set",
-  description: 'Deep cuts only, and nothing after midnight.',
-  color: '#3E6E8E',
-  url: 'https://aurival.com/spaces/deepcuts',
+  title: 'A linked title',
+  description: 'The title and the author line below both open a url when tapped.',
+  url: 'https://aurival.com',
 })
-  .setAuthor('Deep Cuts', 'https://cdn.aurival.com/dc.png', 'https://aurival.com/u/deepcuts')
-  .setThumbnail('https://cdn.aurival.com/cover.jpg')
-  .setFooter('set by deepcuts', 'https://cdn.aurival.com/dc-small.png');
+  .setAuthor('Author line', 'https://bots.aurival.com/docs-assets/aurival-mascot-hero.png', 'https://aurival.com')
+  .setThumbnail('https://bots.aurival.com/docs-assets/aurival-mascot-hero.png')
+  .setFooter('Footer text', 'https://bots.aurival.com/docs-assets/aurival-mascot-hero.png');
 
-await ctx.reply("Tonight's lineup.", { embeds: [embed] });
+await ctx.reply({ embeds: [embed] });
 ```
 
 Each of the three needs the thing it attaches to: a footer icon needs footer text, an embed url
@@ -364,13 +374,13 @@ as four asterisks and two words:
 import { Embed } from 'aurival';
 
 const embed = new Embed({
-  title: 'House rules',
+  title: 'Markdown in the description',
   description:
-    '**Deep cuts** only. No *requests* after the ~~third~~ second hour.\n' +
-    'Type `!queue` to see what is next.',
-}).addField('Set length', '3 hours', true);
+    '**Bold**, *italic*, ~~strikethrough~~ and `inline code` all render.\n' +
+    'Headings render as bold body text, not larger type.',
+}).addField('Field name', 'Field value', true);
 
-await ctx.reply('Welcome in.', { embeds: [embed] });
+await ctx.reply({ embeds: [embed] });
 ```
 
 Supported: bold, italic, bold-italic, strikethrough and inline code. Headings render as bold
@@ -422,8 +432,8 @@ A press comes back as a `button.pressed` event, handled the same way any other e
 ```ts
 bot.on('button.pressed', async (ctx) => {
   await ctx.ack();
-  if (ctx.button === 'pacific') {
-    await ctx.reply('Correct! The Pacific is deepest.');
+  if (ctx.button === 'primary') {
+    await ctx.reply('You pressed the primary button.');
   }
 });
 ```
@@ -432,9 +442,64 @@ The `ctx` there is a `ButtonContext`: `.chat`, `.user`, `.message`, `.button` (t
 when building it) and `.interaction`. Call `await ctx.ack()` exactly once per press — a button
 is single-use, and acking one a second time doesn't throw locally, the server 409s the request.
 
-The full set of showcase examples (trivia, giveaways, DJ bots, moderation reports…) is in the
+The showcase bot runs every one of these cards live. The full set is in the
 [cookbook](https://bots.aurival.com/docs/cookbook).
 
+## Buttons only the caller can press
+
+By default nobody is locked: any member in the chat can press a card's buttons, exactly as
+before this existed. Pass `forUser` to `reply`, `send`, `edit` or `ack` to lock the press to one
+member.
+
+```ts
+await ctx.reply('Locked to the caller', { buttons, forUser: ctx.sender });
+```
+
+`forUser` takes a `User` (`ctx.sender` is one) or a bare `usr_…` id string. Either one
+serializes to the same id on the wire.
+
+Everyone still sees the card and its text. Only the press is gated: a non-caller's buttons
+render at `.56` opacity with no checkmark and are not tappable. Nothing is drawn under the
+row: the card never says who it is for, so write that into the embed footer yourself if you
+want it on the plate. A link button on a locked card stays pressable by anyone. It never
+round-trips to the server, so there is nothing for the lock to gate.
+
+A non-caller who presses anyway is refused by the server with a `403`, before anything is
+spent. `used` stays unset and the card is unchanged. That refusal never reaches your bot: a bot
+never presses a button, so there is no SDK exception for it.
+
+Omitting `forUser` on a `reply`/`edit`/`ack` that replaces a card **keeps the existing lock**.
+Passing `forUser: null` **clears** it, and the card opens to everyone. Passing a new id **moves**
+the lock to that member. This matters most on `ack`, where a quiz redraws its own card between
+questions and must not silently unlock itself by leaving `forUser` out.
+
+A caller-only quiz, start to finish:
+
+```ts
+import { Button, Embed } from 'aurival';
+
+bot.command('locked', async (ctx) => {
+  const embed = new Embed({
+    title: 'Locked to the caller',
+    description: 'Everyone sees this card. Only the person who ran the command can press.',
+  });
+  await ctx.reply({
+    embeds: [embed],
+    buttons: [new Button({ label: 'Only the caller presses', id: 'only', style: 'primary' })],
+    forUser: ctx.sender,
+  });
+});
+
+bot.on('button.pressed', async (ctx) => {
+  await ctx.ack({ text: 'Pressed.', buttons: [] });
+});
+```
+
+`ButtonContext` carries no `forUser` field. The presser is always the locked user by
+construction: the server refuses everyone else before your handler ever runs, so there is
+nothing on the press for it to expose. If you need the lock on a card you are acking, you
+already have it: you set it on the send.
+
 ## Cooldowns
 
 A cooldown paces a command or a button. You attach it, the SDK keeps the bucket, and the wire
@@ -503,7 +568,7 @@ Override it where it belongs, and precedence is button, then card, then the bot
 ```ts
 const bot = new Bot({ buttonCooldown: { rate: 1, per: 5 } }); // this bot's buttons
 await ctx.reply({ buttons, buttonCooldown: null });           // this card's buttons, off
-new Button({ label: 'Paint', cooldown: null });               // this one button, off
+new Button({ label: 'Primary action', cooldown: null });      // this one button, off
 ```
 
 A per-card or per-button cooldown gets its own buckets, keyed on the message, the button id and
@@ -517,6 +582,23 @@ legitimate once an hour.
 Link buttons are outside all of this — a link opens on the device and never round-trips, so it
 cannot carry a cooldown and `Button.link` has no `cooldown` field.
 
+### Keep one Cooldown per button
+
+A `Cooldown` owns its own bucket of remaining presses. Build a fresh one inside the ack handler —
+or anywhere a press can re-run it — and it forgets every prior press, so the cooldown never
+actually triggers. Define the `Cooldown` and the `Button` once, at module scope, and reuse those
+same objects on the send and on every ack that follows it:
+
+```ts
+// Once, at module scope — not inside the handler.
+const cooldown = new Cooldown(1, 10);
+const button = new Button({ label: '+1', id: 'inc', style: 'primary', cooldown });
+
+bot.on('button.pressed', async (ctx) => {
+  await ctx.ack({ buttons: [button] });   // the same button, never rebuilt here
+});
+```
+
 ### The caveat, said plainly
 
 **Buckets are process memory.** They reset on restart, and they are not shared between
@@ -607,31 +689,30 @@ Three states, one rule, on both doors:
 with all three left out throws `an edit needs text, embeds or buttons` before anything is sent,
 and the server answers the same sentence as `NothingToEdit`.
 
-A trivia round is the whole feature in one pair of handlers. Both cards earn their plate: the
-question card carries buttons, the result card carries a field.
+Pressing a button is the whole feature in one pair of handlers. Both cards earn their plate: the
+first card carries buttons, the replacement carries the result.
 
 ```ts
 import { Button, Embed } from 'aurival';
 
-bot.command('trivia', async (ctx) => {
-  await ctx.reply({
-    embeds: [new Embed({ title: 'Which planet is largest?' })],
-    buttons: [
-      new Button({ label: 'Mars', style: 'secondary' }),
-      new Button({ label: 'Jupiter', style: 'secondary' }),
-    ],
-  });
+bot.command('update', async (ctx) => {
+  const embed = new Embed({ title: 'Press a button', description: 'The card is replaced in place when you press one.' });
+  const buttons = [
+    new Button({ label: 'Press me, card updates', id: 'u1', style: 'primary' }),
+    new Button({ label: 'Or press me', id: 'u2', style: 'secondary' }),
+  ];
+  await ctx.reply({ embeds: [embed], buttons });
 });
 
 bot.on('button.pressed', async (ctx) => {
-  const correct = ctx.button === 'jupiter';
+  const which = ctx.button === 'u1' ? 'first' : 'second';
   const result = new Embed({
-    title: correct ? 'Jupiter' : 'Not quite',
-    description: 'Jupiter is about eleven Earths across.',
-  }).addField('Answered by', ctx.user.handle, true);
+    title: `You pressed the ${which} button`,
+    description: 'ack() replaced the card in place. Nothing else in the chat moved.',
+  });
   await ctx.ack({
     embeds: [result],
-    buttons: [new Button({ id: 'again', label: 'Play again' })],
+    buttons: [new Button({ label: 'Press again', id: 'again', style: 'primary' })],
   });
 });
 ```
@@ -646,7 +727,7 @@ on the id.
 outside a press:
 
 ```ts
-await ctx.edit(sent, { embeds: [new Embed({ title: 'Starting in 3…' })] });
+await ctx.edit(sent, { embeds: [new Embed({ title: 'Title' })] });
 await ctx.edit(sent, { buttons: [] });   // the row is gone, the plate stays
 ```
 
@@ -671,6 +752,44 @@ Two new error classes ship with it, `CooldownWithBody` and `CooldownRetryAfterIn
 `InvalidRequestError`. You will not normally see either: the SDK builds the cooldown ack itself
 and refuses an out-of-range button cooldown where you write it.
 
+### Upgrading from 0.8.x
+
+0.9.0 adds new per-field and per-embed caps, and **one of them can break a card that worked on
+0.8.x**: none of these fields were length-limited before, so a card built past one of the new
+limits used to send successfully and now throws. `Embed.addField`, `setAuthor` and `setFooter`
+check length locally as of this version, before any round trip:
+
+- an embed field name is at most 256 characters
+- an embed field value is at most 1024 characters
+- an embed author name is at most 256 characters
+- an embed footer's text is at most 2048 characters
+- `setImage` and `setThumbnail` urls are at most 2048 characters (author and footer icons
+  stay uncapped)
+- the embeds on one message carry at most 6000 characters in total, summed across every
+  title, description, field name and value, author name and footer text — checked when the
+  message is sent, since it spans every embed, not one
+
+A card that never approaches these sizes is unaffected. One built past a limit now throws
+locally, with the same sentence the server used to send back as a 400 — the SDK catches it
+before the round trip instead of after. The server enforces the identical caps independently
+of SDK version, so a bot on an older SDK sees the 400 from the wire the moment this ships, not
+only on upgrade. Six matching error classes ship for the wire-error path, all
+`InvalidRequestError`: `EmbedFieldNameTooLong`, `EmbedFieldValueTooLong`,
+`EmbedAuthorNameTooLong`, `EmbedFooterTextTooLong`, `ImageURLTooLong` and `EmbedsTooLong`.
+
+`mentions` got stricter too, and this is also a server-side change that applies regardless of
+SDK version: a `@handle` token that appears only inside a code block or inline code no longer
+satisfies the mention, and the server answers `mention_token_missing` the same way it always
+has for a missing token — write the handle into `text` yourself, in plain text, outside any
+fence or backtick.
+
+Two fixes land alongside the caps: `ctx.edit(sent, { forUser: null })` with no other part
+named is now a real edit that reaches the wire as `{ "for_user": null }`, rather than being
+refused locally before the round trip — naming only the lock is a real change to the card.
+And a successful button-cooldown ack now logs one `info` line naming the message, the button,
+the presser and the window, so a cooldown firing and a press silently vanishing no longer look
+identical from the outside.
+
 ## Shadowed commands
 
 A bot can declare up to 50 commands, the SDK refuses to connect past that.
@@ -686,6 +805,42 @@ aurival warn: /ping is shadowed by another bot in chat_01j…, so it will not re
 Rename the command, or get the other bot out of that chat. Nothing else in the SDK reacts
 to it — a shadowed command in one chat is still live in every other.
 
+## Command aliases
+
+`aliases` on `bot.command(...)` gives one command several spellings, all handled by the same
+function. `/roll` and `/r` fire the same handler, share the same cooldown bucket, and are one
+command everywhere the server or the app talks about it.
+
+```ts
+bot.command('roll', { description: 'Roll dice', aliases: ['r'] }, async (ctx) => {
+  await ctx.reply(`/${ctx.invokedAs} ran ${ctx.command}, dice rolled`);
+});
+```
+
+`ctx.command` is always the canonical name, `'roll'`, whichever spelling fired the handler.
+`ctx.invokedAs` is the token the human actually typed, lowercased: `'roll'` or `'r'`. They are
+equal on a canonical call. Code that checks `ctx.command === 'roll'` keeps working no matter
+which spelling reached it.
+
+The options object also takes `cooldown`, same as any other command. It is one bucket, keyed on
+the canonical name, shared across every spelling:
+
+```ts
+bot.command('roll', { description: 'Roll dice', aliases: ['r'], cooldown: { rate: 1, per: 5 } }, handler);
+```
+
+At most three aliases per command. A fourth throws locally, before anything is synced. It is the
+same validation path as a bad command name: lowercase letters, digits, hyphens and underscores
+only, and none of the reserved names (`help`, `report`, `block`, `mute`, `kick`, `ban`, `admin`,
+`staff`, `support`, `aurival`).
+
+The cooldown notice echoes the typed token: hit the limit through `/r` and you get `Slow down.
+Try /r again in 3 s.`, never `/roll`.
+
+In the app, the command picker lists a command's aliases as a muted secondary line under its
+row: `also /r`. Picking a row that matched by alias fills that alias, not the canonical
+spelling: typing `/r` and picking the row inserts `/r `, not `/roll `.
+
 ## Environment
 
 | variable           | what it does                                                                                                                                              |

package/dist/bot.d.ts

@@ -78,6 +78,19 @@ export interface CommandOptions {
     description?: string | undefined;
     cooldown?: CooldownLike | undefined;
     onCooldown?: OnCooldownHook | undefined;
+    /**
+     * AMENDMENT-09 §2.1: alternate spellings that fire this same handler —
+     * `/r` and `/dice` for a command registered as `roll`, say. At most
+     * {@link MAX_ALIASES_PER_COMMAND}, checked locally at registration; every
+     * other rule an alias obeys (the name pattern, the reserved list,
+     * uniqueness) is the server's alone (§2.1) — this SDK reuses
+     * `invalid_command_name` for those exactly as the server does, by simply
+     * not re-validating them here and letting the sync refusal surface.
+     * Dispatch, the cooldown bucket and `onCooldown` all stay keyed on the
+     * canonical name; an alias only ever changes which typed token reaches
+     * that same handler (`ctx.invokedAs`, `Context`).
+     */
+    aliases?: readonly string[] | undefined;
 }
 /**
  * How long a command handler runs before the chat is told the bot is thinking
@@ -97,6 +110,17 @@ export declare function ensurePaired(http: HttpClient, keyFile: KeyFile, host: s
     machine: Machine;
     paired: boolean;
 }>;
+/**
+ * One `PUT /v1/bots/{bot}/commands` row. `aliases` is optional and, when
+ * present, always non-empty — the caller omits the key entirely for a
+ * command with no aliases (AMENDMENT-09 §2.1: absent and `[]` mean the same
+ * thing, so there is no reason to send the empty spelling).
+ */
+export interface SyncPayloadEntry {
+    name: string;
+    description: string;
+    aliases?: string[];
+}
 /**
  * The one door to command sync, so the lane that syncs is always the lane that
  * reports. Both `Bot` call sites go through here.
@@ -104,10 +128,7 @@ export declare function ensurePaired(http: HttpClient, keyFile: KeyFile, host: s
  * Exported for the tests, not from `index.ts` — the package's export list
  * mirrors Python's `__all__` (SDK-7) and this is not on it.
  */
-export declare function syncCommandsAndReport(http: HttpClient, bot: string, payload: Array<{
-    name: string;
-    description: string;
-}>, log: Logger): Promise<void>;
+export declare function syncCommandsAndReport(http: HttpClient, bot: string, payload: SyncPayloadEntry[], log: Logger): Promise<void>;
 /**
  * One warning line per shadowed chat (S11). Silently dropping `conflicts` is
  * the silence the field exists to end: the developer whose command never fires.

package/dist/bot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/bot.js

@@ -3,7 +3,7 @@ import { Auth, KeyFile, machineLabel, pair, resolveHost } from './auth.js';
 import { AurivalError, BotSuspended, ButtonAlreadyUsed, NotFound, RateLimitError, SessionSuperseded } from './errors.js';
 import { Context, Event, contextFor } from './events.js';
 import { DEFAULT_HOST, HttpClient, defaultLogger } from './http.js';
-import { commandCooldownNotice } from './caps.js';
+import { CAP_TOO_MANY_ALIASES, MAX_ALIASES_PER_COMMAND, commandCooldownNotice } from './caps.js';
 import { Cooldown, buttonBucketKey, normalizeCooldownOption, resolveButtonCooldown, retryAfterMs, roundSeconds, subjectKey, } from './cooldown.js';
 import { EVENT_BACKLOG_OVERFLOWED, EVENT_COMMAND_INVOKED, Socket } from './socket.js';
 import * as status from './status.js';
@@ -139,6 +139,7 @@ export class Bot {
         let handler;
         let cooldownLike;
         let onCooldownHook;
+        let aliasesLike;
         if (typeof second === 'string') {
             description = second;
             handler = third;
@@ -150,14 +151,21 @@ export class Bot {
             description = second.description ?? '';
             cooldownLike = second.cooldown;
             onCooldownHook = second.onCooldown;
+            aliasesLike = second.aliases;
             handler = third;
         }
         if (handler === undefined)
             throw new AurivalError(`command(${name}) needs a handler`);
+        // AMENDMENT-09 §2.1: `[]` in every state but never `undefined` — a
+        // `Command` this SDK constructs always carries the list, even empty.
+        const aliases = aliasesLike !== undefined ? [...aliasesLike] : [];
+        if (aliases.length > MAX_ALIASES_PER_COMMAND) {
+            throw new AurivalError(CAP_TOO_MANY_ALIASES);
+        }
         const key = lookupKey(name);
         if (this.#registered.has(key))
             status.duplicateCommand(name, this.#quiet);
-        const registered = { command: { name, description }, handler };
+        const registered = { command: { name, description, aliases }, handler };
         if (cooldownLike !== undefined)
             registered.cooldown = Cooldown.from(cooldownLike);
         if (onCooldownHook !== undefined)
@@ -285,10 +293,16 @@ export class Bot {
      * and land the sync in the background.
      */
     async #syncCommands(http, bot, signal) {
-        const payload = [...this.#registered.values()].map((r) => ({
-            name: r.command.name,
-            description: r.command.description,
-        }));
+        const payload = [...this.#registered.values()].map((r) => {
+            const entry = { name: r.command.name, description: r.command.description };
+            // AMENDMENT-09 §2.1: the key is present only when the list is
+            // non-empty — absent and `[]` mean the same thing on this wire, so
+            // there is nothing to gain from sending the empty spelling.
+            if (r.command.aliases !== undefined && r.command.aliases.length > 0) {
+                entry.aliases = [...r.command.aliases];
+            }
+            return entry;
+        });
         try {
             await syncCommandsAndReport(http, bot, payload, this.#log);
             return null;
@@ -424,7 +438,11 @@ export class Bot {
         }
         const n = roundSeconds(refusedAfterSeconds);
         try {
-            await ctx.reply(commandCooldownNotice(ctx.command, n));
+            // AMENDMENT-09 §13.1: names the token the human actually typed, not
+            // the canonical spelling — the bucket is still the canonical
+            // command's (one bucket, all spellings); only the rendered sentence
+            // changes.
+            await ctx.reply(commandCooldownNotice(ctx.invokedAs, n));
         }
         catch (exc) {
             this.#log.error(`cooldown notice for ${JSON.stringify(ctx.command)} failed: ${exc instanceof Error ? (exc.stack ?? exc.message) : String(exc)}`);
@@ -468,6 +486,14 @@ export class Bot {
             return;
         try {
             await this.#http.ackCooldown(ctx.interaction, ms);
+            // The ack landed. Without this line a button cooldown is invisible to
+            // the bot author: the SDK answers the press itself, the handler never
+            // runs, and nothing is written anywhere — so a cooldown firing and a
+            // press vanishing look identical from the outside. `info`, not
+            // `debug`, because the swallowed-refusal lines below are the ones a
+            // reader can ignore; this one is the cooldown working. Byte-mirrors
+            // `sdk/python/aurival/bot.py`'s sentence (SDK-7).
+            this.#log.info(`cooldown: acked press on ${ctx.message.id}/${ctx.button} for ${ctx.user.id}, retry_after_ms=${ms}`);
         }
         catch (exc) {
             if (exc instanceof ButtonAlreadyUsed || exc instanceof NotFound) {