Refresh dashboard screenshots + first use-case guide (death counter)

astro.config.mjs

@@ -191,6 +191,16 @@ export default defineConfig({
               items: [
                 { label: 'Overview', slug: 'chatbot' },
                 { label: 'Getting Started', slug: 'chatbot/getting-started' },
+                {
+                  label: 'Guides',
+                  items: [
+                    { label: 'Overview', slug: 'chatbot/guides' },
+                    { label: 'Death Counter', slug: 'chatbot/guides/death-counter' },
+                    { label: 'Lurk Command', slug: 'chatbot/guides/lurk-command' },
+                    { label: 'Countdown Command', slug: 'chatbot/guides/countdown-command' },
+                    { label: 'Viewer Input', slug: 'chatbot/guides/viewer-input' },
+                  ],
+                },
                 {
                   label: 'Commands',
                   items: [

src/content/docs/chatbot/commands/default/level.mdx

@@ -81,6 +81,10 @@ StreamElements uses the following numeric values for permission levels:
 
 These six values are the only ones the bot accepts — commands like `!level` and `!command options -level` reject anything else.
 
+:::note
+The dashboard's custom-command **User level** dropdown additionally offers **Broadcaster**, a level above Super Moderator. It can only be assigned from the dashboard, not from chat.
+:::
+
 :::note
 Manually setting a level (e.g., setting a non-sub to `250`) grants them the permissions of that level within StreamElements (e.g., access to sub-only commands) but does *not* grant them platform-specific benefits like sub badges or emotes.
 :::

src/content/docs/chatbot/getting-started.mdx

@@ -27,36 +27,38 @@ Commands are the main way users will interact with the bot in your chat. They ca
 
 <Steps>
 
-1. From the [bot command dashboard](https://streamelements.com/dashboard/bot/commands), navigate to the "Custom Commands" tab.
+1. From the [bot command dashboard](https://streamelements.com/dashboard/bot/commands), navigate to the "Custom commands" tab.
 
-2. Click the "Add New Command" button to open the command creation tool.
+2. Click the "Add new command" button to open the command creation tool.
 
-   ![Step 1](img/step_1.png "Step 1")
+   ![The Chat commands page with the Custom commands tab and Add new command button highlighted](img/step_1.png "Add new command")
 
-3. Enter the desired name for your new command. For this example we will name the command "lastseen".
+3. Enter the desired name for your new command in the "Command name" field. For this example we will name the command "lastseen".
 
-4. Optional: In the "Response Type" dropdown, select the method you would like the bot to use to send the response.
+4. Optional: In the "Response type" dropdown, select the method you would like the bot to use to send the response.
    - "Say" will send the response as a chat message as it is entered in the basic settings.
    - "Mention" will send the response as a chat message, but will prefix the message with [`@$(user),`](/chatbot/variables/sender).
    - "Reply" will send the response as a native reply to the user who triggered the command.
      - NOTE: If the platform does not support native replies, the response will be sent as a "Mention" instead.
    - "Whisper" will send the response as a whisper to the user who triggered the command.
 
-5. Add the response. For our example, enter:
+5. Add the response in the "Reply" field. For our example, enter:
 
    ```streamelements
    $(user) was last seen $(user.lastseen) ago
    ```
 
    [`$(user)`](/chatbot/variables/user) and its sub-variables target the name typed after the command — or the person who used the command, when no name is given. For a list of all available variables, see the [variables documentation](/chatbot/variables).
 
-   ![Step 2](img/step_2.png "Step 2")
+   ![The command settings filled in with a name, response type, and reply](img/step_2.png "Command settings")
 
-6. Optional: Add one or more command aliases to allow users to trigger the same command using alternate names.
+6. Optional: Switch to the "Advanced settings" tab to add command aliases (alternate trigger words), cooldowns, a loyalty-point cost, or conditions such as only running while the stream is live.
 
-7. Click the "Activate Command" button to save your new command.
+   ![The Advanced settings tab with the Command aliases field highlighted](img/command-advanced.png "Advanced settings")
 
-   ![Step 3](img/step_3.png "Step 3")
+7. Click the "Activate command" button to save your new command.
+
+   ![The Activate command button](img/step_3.png "Activate command")
 
 </Steps>
 

src/content/docs/chatbot/guides/countdown-command.mdx

@@ -0,0 +1,85 @@
+---
+title: Create a Countdown Command
+sidebar:
+  label: Countdown Command
+description: "Create a StreamElements countdown command for a daily stream time or a one-time event, with UTC and RFC 3339 examples."
+keywords:
+  - StreamElements countdown command
+  - Twitch countdown command
+  - next stream command
+  - event countdown
+  - time until command
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import ChatExample from '@components/ChatExample.astro';
+
+A countdown command tells viewers how long remains until your next stream, tournament, community night, or other event. StreamElements provides two countdown formats: a recurring time of day and a fixed date and time.
+
+## Choose a countdown type
+
+| Countdown | Use it for | Target format |
+| --- | --- | --- |
+| Daily | A stream or event that starts at the same time every day | A 24-hour UTC time, such as `19:00` |
+| One-time | An event on a specific date | A complete RFC 3339 timestamp, such as `2027-09-20T19:00:00-03:00` |
+
+:::caution[Check the timezone]
+A bare time is always interpreted as UTC, not your local timezone. For a one-time event, include its UTC offset in the timestamp. For example, `+02:00` means two hours ahead of UTC and `-03:00` means three hours behind UTC.
+:::
+
+## Create a daily countdown
+
+This example counts down to the next occurrence of 19:00 UTC. If 19:00 has already passed today, the countdown automatically targets 19:00 tomorrow.
+
+<Steps>
+
+1. Open the [bot command dashboard](https://streamelements.com/dashboard/bot/commands), select **Custom commands**, and click **Add new command**.
+
+2. Name the command `nextstream` and enter this reply:
+
+   ```streamelements
+   The next stream starts in $(time.until 19:00)
+   ```
+
+3. Replace `19:00` with your start time converted to UTC.
+
+4. Click **Activate command**.
+
+</Steps>
+
+<ChatExample messages={[
+  { persona: 'user', message: '!nextstream' },
+  { persona: 'bot', message: 'The next stream starts in 2 hours 30 mins' }
+]} />
+
+## Create a one-time event countdown
+
+For an event on a particular date, use a complete RFC 3339 timestamp:
+
+```streamelements
+The community tournament starts in $(time.until 2027-09-20T19:00:00-03:00)
+```
+
+The timestamp has four parts:
+
+```text
+2027-09-20 T 19:00:00 -03:00
+date         time       UTC offset
+```
+
+Replace the example with the event's actual date, local start time, and UTC offset. After the fixed time passes, the output ends in `ago`; update or disable the command when the event is over.
+
+## Troubleshooting
+
+- **The time is several hours wrong:** a daily `HH:MM` target uses UTC. Convert the intended start time to UTC.
+- **The bot prints a parsing error:** use either a bare `HH:MM` time or a complete RFC 3339 timestamp. Formats such as `September 20 at 7 PM` are not accepted.
+- **The response says the event was "ago":** the fixed timestamp is in the past. Update the target or disable the command.
+- **The variable appears as text:** check the spelling and keep the target inside `$(time.until ...)`.
+
+See the [`$(time)` reference](/chatbot/variables/time#timeuntil) for the precise input and output rules.
+
+## Related
+
+- [`$(time)`](/chatbot/variables/time): Current-time and countdown syntax.
+- [Custom Commands](/chatbot/commands/custom): Manage the command from the dashboard or chat.
+- [Timers](/chatbot/timers): Post messages automatically instead of waiting for a viewer command.

src/content/docs/chatbot/guides/death-counter.mdx

@@ -0,0 +1,79 @@
+---
+title: Set Up a Death Counter
+sidebar:
+  label: Death Counter
+description: "Build a Twitch death counter with StreamElements: a !death command that counts up, a !deaths command to check the score, and a reset — step by step."
+keywords:
+  - death counter
+  - StreamElements death counter
+  - Twitch death counter
+  - death count command
+  - counter command
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import ChatExample from '@components/ChatExample.astro';
+
+A death counter is three small commands: one that counts a death, one that shows the score without changing it, and one that resets it for the next game. It's built on the chatbot's [counters](/chatbot/counters), so the count survives stream restarts.
+
+## The counting command
+
+<Steps>
+
+1. From the [bot command dashboard](https://streamelements.com/dashboard/bot/commands), open the "Custom commands" tab and click "Add new command".
+
+2. Name the command `death`, set the "User level" to **Moderator** so random chatters can't inflate your death count, and enter this reply:
+
+   ```streamelements
+   Deaths: $(count deaths)
+   ```
+
+   ![The command settings with the death command name, Moderator user level, and reply highlighted](../img/death-counter-command.png "The !death command")
+
+3. Click "Activate command".
+
+</Steps>
+
+Every use of [`$(count deaths)`](/chatbot/variables/count) adds 1 to the counter and prints the new total — so each `!death` in chat is one more death:
+
+<ChatExample messages={[
+  { persona: 'moderator', message: '!death' },
+  { persona: 'bot', message: 'Deaths: 4' }
+]} />
+
+## Checking the score without counting
+
+For a command everyone can use, read the counter with [`$(getcount)`](/chatbot/variables/getcount) — it outputs the value without adding to it. Create a second command named `deaths` (User level: Everyone) with the reply:
+
+```streamelements
+We have died $(getcount deaths) times so far
+```
+
+<ChatExample messages={[
+  { persona: 'user', message: '!deaths' },
+  { persona: 'bot', message: 'We have died 4 times so far' }
+]} />
+
+## Corrections and resets
+
+The counter takes modifiers: `+n` adds, `-n` subtracts, and a bare number sets it. A moderator-level reset command with the reply below puts the counter back to zero between games:
+
+```streamelements
+Death counter reset ($(count deaths 0))
+```
+
+You can also fix miscounts on the fly — `$(count deaths -1)` in any moderator command takes one back.
+
+:::caution
+Modifiers only work in the space-separated form: `$(count deaths +5)`. In the dot form, `$(count.deaths +5)` treats `+5` itself as the counter name — see the [`$(count)` reference](/chatbot/variables/count).
+:::
+
+## Managing counters
+
+Counters are created automatically the first time they're used and persist until you change them. You can view and edit every counter — including `deaths` — in the dashboard under **Chatbot → Counters**, and moderators can use the [`!editcounter`](/chatbot/commands/default/editcounter) default command from chat.
+
+## Related
+
+- [Counters](/chatbot/counters): How counters work, with the full syntax.
+- [`$(count)`](/chatbot/variables/count) and [`$(getcount)`](/chatbot/variables/getcount): The two variables this guide is built on.
+- [Custom Commands](/chatbot/commands/custom): Everything else you can do with custom commands.

src/content/docs/chatbot/guides/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Chatbot Guides
+sidebar:
+  label: Overview
+description: "Step-by-step StreamElements Chatbot guides for building useful custom commands with counters, countdowns, viewer input, and more."
+keywords:
+  - StreamElements chatbot guides
+  - chatbot command tutorials
+  - Twitch custom commands
+  - StreamElements command examples
+---
+
+import { CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+These guides combine chatbot commands, variables, and settings into complete features you can use in your channel. For individual syntax and configuration options, use the [Commands](/chatbot/commands) and [Variables](/chatbot/variables) reference sections.
+
+<CardGrid>
+  <LinkCard
+    title="Death Counter"
+    href="/chatbot/guides/death-counter"
+    description="Count deaths, show the current score, correct mistakes, and reset between games."
+  />
+  <LinkCard
+    title="Lurk Command"
+    href="/chatbot/guides/lurk-command"
+    description="Give viewers a friendly way to say they are watching while away from chat."
+  />
+  <LinkCard
+    title="Countdown Command"
+    href="/chatbot/guides/countdown-command"
+    description="Count down to a daily stream time or a one-time event."
+  />
+  <LinkCard
+    title="Commands with Viewer Input"
+    href="/chatbot/guides/viewer-input"
+    description="Capture words from chat, add fallbacks and validation, and encode input for URLs."
+  />
+</CardGrid>

src/content/docs/chatbot/guides/lurk-command.mdx

@@ -0,0 +1,68 @@
+---
+title: Set Up a Lurk Command
+sidebar:
+  label: Lurk Command
+description: "Create a !lurk command with the StreamElements Chatbot, personalize its reply, add a cooldown, and test it in Twitch chat."
+platforms: [twitch]
+keywords:
+  - StreamElements lurk command
+  - Twitch lurk command
+  - create lurk command
+  - custom chatbot command
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import ChatExample from '@components/ChatExample.astro';
+
+A lurk command gives viewers a quick way to say they are still watching even when they are stepping away from chat. It posts a friendly reply; it does not change the viewer's Twitch status or how their view is counted.
+
+## Create the command
+
+<Steps>
+
+1. Open the [bot command dashboard](https://streamelements.com/dashboard/bot/commands), select the **Custom commands** tab, and click **Add new command**.
+
+2. Enter `lurk` in the **Command name** field and leave **User level** set to **Everyone**.
+
+3. Enter this in the **Reply** field:
+
+   ```streamelements
+   $(sender) is lurking. Thanks for keeping the stream company! $(random.emote)
+   ```
+
+   [`$(sender)`](/chatbot/variables/sender) is always the viewer who used the command. [`$(random.emote)`](/chatbot/variables/random#randomemote) adds a random emote available in the channel and can be removed if you want a consistent reply.
+
+4. Open **Advanced settings** and set a **User cooldown**. This limits how often the same viewer can trigger the reply without preventing other viewers from using it.
+
+5. Optional: add `brb` or `afk` under **Command aliases** if you want those triggers to use the same response.
+
+6. Click **Activate command**.
+
+</Steps>
+
+## Test it
+
+Use the command from a viewer account or ask someone in chat to try it:
+
+<ChatExample messages={[
+  { persona: 'user', message: '!lurk' },
+  { persona: 'bot', message: 'ViewerName is lurking. Thanks for keeping the stream company! Kappa' }
+]} />
+
+If the bot does not reply, check that it has joined the channel, the command is enabled, and the command is not on cooldown. See [Chatbot troubleshooting](/chatbot/troubleshooting) for the full checklist.
+
+## Customize the reply
+
+You can change all of the text around the variables without changing how the command works. For example:
+
+```streamelements
+Thanks for lurking, $(sender)! Enjoy the stream and come back whenever you're ready. $(random.emote)
+```
+
+Keep `$(sender)` if you want the reply to name the person who used the command. The bot replaces it with their display name each time.
+
+## Related
+
+- [Custom Commands](/chatbot/commands/custom): Manage command replies, permissions, aliases, and cooldowns.
+- [`$(sender)`](/chatbot/variables/sender): Information about the viewer who triggered a command.
+- [`$(random)`](/chatbot/variables/random): Random emotes, numbers, chatters, and list choices.