# Rolz agents

This file helps agents, bots, and integration clients discover Rolz documentation and public integration surfaces.

## Primary agent references

- Dice and user-facing feature reference: https://rolz.org/llms.txt
- Complete dice reference in one file: https://rolz.org/llms-full.txt
- Dice syntax details: https://rolz.org/llms/dice.txt
- Macros and variables: https://rolz.org/llms/variables.txt
- Character sheets: https://rolz.org/llms/character-sheets.txt
- Lookup lists: https://rolz.org/llms/lookups.txt
- Generators: https://rolz.org/llms/generators.txt
- Examples: https://rolz.org/llms/examples.txt

Use these files when a user asks how to write Rolz dice codes, character-sheet buttons, macros, lookup lists, or generator commands.

## Public API references

- API help page: https://rolz.org/help/api
- Unauthenticated dice roll API: https://rolz.org/api/?6d6.json
- Other result formats: https://rolz.org/api/?6d6.txt, https://rolz.org/api/?6d6.simple, https://rolz.org/api/?6d6.xml
- Room log feed example: https://rolz.org/api/roomlog?room=lobby
- Room posting endpoint format: https://rolz.org/api/post?room=ROOM_ID&text=TEXT&from=APP

Room posting requires the room owner to enable API posting with `/room api=on`. Use `/room info` in that room to get the room ID.

## Authenticated API surfaces

Rolz account API keys use this header:

```text
Authorization: Bearer YOUR_API_KEY
```

Authenticated endpoint examples:

- Roll dice for an account: `GET https://rolz.org/api/roll.php?dice=d20&comment=attack`
- List the account's rooms: `GET https://rolz.org/api/rooms.php?limit=50&offset=0`
- Create a room: `POST https://rolz.org/api/create-room.php`

Create and manage API keys from the Rolz account API key page while signed in. Do not put API keys in public prompts, public repos, or browser-visible client code.

## Discord integration

Rolz has a Discord bot for server slash-command rolling.

- Discord account and bot setup page: https://rolz.org/account/discord
- Bot invite redirect: https://rolz.org/api/discord/invite

Discord server use requires server authorization from a Rolz account that is allowed to authorize the bot. Use the bot's slash roll command in Discord to start the linking flow if the server is not authorized.

Agents should help users write dice codes for Discord the same way they help with Rolz chat dice codes. Use the `llms.txt` references above for dice syntax.

## Browser and room integration

Rolz dice rooms expose client-side hooks for user scripts:

- `document.onMessage = function(msg) { ... }` receives room messages.
- `document.onMessageRender = function(html, msg) { return html; }` can modify rendered message HTML.
- `document.isActive` tells whether the Rolz tab is active.

These hooks are for user-controlled browser customization. Do not use them to bypass room permissions.

## Integration rules for agents

- Prefer documented public URLs and account API keys.
- Do not scrape private room content.
- Do not suggest bypassing room access controls, Discord authorization, Patreon/server authorization, or hidden wiki page controls.
- Do not invent dice syntax. Check `llms-full.txt` or the focused `llms/*.txt` files.
- For named character values, prefer `!DEX` or `var("DEX")`.
- Use `var("DEX", 4)` only when the user wants to set a value. If `DEX` is a writable wiki field, Rolz writes it back.