docs(polls): add polls feature documentation

content/features/_index.md

@@ -18,3 +18,4 @@ This section covers the features and improvements that have been added to Sable
 - [UI Improvements](ui-improvements) — A collection of quality-of-life improvements across the whole app.
 - [Presence](presence) — Control whether your online/away status is shared with others.
 - [Developer Tools](developer-tools) — Internal debug log viewer and in-app bug report command.
+- [Polls](polls) — Create and vote on polls directly in a room using the MSC3381 standard.

content/features/polls.md

@@ -0,0 +1,48 @@
++++
+title = "Polls"
+weight = 9
++++
+
+Sable supports Matrix polls ([MSC3381](https://github.com/matrix-org/matrix-spec-proposals/pull/3381)), letting you ask questions and collect votes directly inside a room.
+
+![A poll in the Sable timeline showing answer options with vote counts and an End Poll button](/img/polls-example.png)
+
+> **Note:** Polls are currently disabled by default. They can be enabled by setting `"features": { "polls": true }` in your server's `config.json`.
+
+# Creating a Poll
+
+Type `/poll` in any room's message box and press Enter (or select the suggestion from the command list). The **Create Poll** dialog will open.
+
+Fill in:
+
+- **Question** — what you want to ask (up to 340 characters)
+- **Options** — at least 2 and at most 20 answer choices (each up to 340 characters); blank options are ignored when sent
+- **Max selections** — how many options each voter may choose (default: 1; cannot exceed the number of options)
+- **Results visibility** — *Show live results* (disclosed, results visible while voting) or *Hide until closed* (undisclosed, results hidden until the poll ends)
+- **Voter visibility** — choose whether voter names are shown next to each answer in the results
+- **Poll duration** — optionally set an expiry time (1 hour, 12 hours, 24 hours, 48 hours, 1 week, or a custom date and time); the poll automatically closes when the time is reached
+
+Click **Create Poll** to post it to the room.
+
+# Voting
+
+Click an answer button to cast your vote. In a *disclosed* poll, vote counts and percentages update immediately.
+
+For **single-choice** polls, clicking a different option moves your vote; clicking your current selection removes it.
+
+For **multi-selection** polls, you can pick up to the stated maximum. Click a selected option again to deselect it. Once you've reached the maximum, you must deselect an option before you can choose another.
+
+# Ending a Poll
+
+If you created the poll or have moderator permissions in the room, an **End Poll** button appears at the bottom of the poll. Ending the poll locks voting and shows final results to everyone, including in *undisclosed* polls.
+
+# Results
+
+Once a poll is ended (or for disclosed polls, at any time) each answer shows:
+
+- A fill bar indicating the share of votes
+- The percentage and raw vote count
+- A tick mark next to the option(s) you voted for
+- An expandable voter list (if the poll creator enabled voter visibility)
+
+The footer shows the total number of unique voters plus the poll status ("Poll ended", "Poll expired", or "Results hidden until closed"), and the time remaining if a duration was set.

content/general/commands.md

@@ -5,6 +5,16 @@ weight = 1
 
 ## General Commands
 
+### /poll
+
+Create a poll in the current room
+
+Usage: `/poll`
+
+Opens the **Create Poll** dialog where you can enter a question, answer options, visibility settings, and an optional expiry time.
+
+> Polls must be enabled in `config.json` (`"features": { "polls": true }`).
+
 ### /me
 
 Describing what you're doing