Editing ObsidianIRC polls spec (section)

== ObsidianIRC Polls Specification ==

=== Overview ===
This document specifies the vendored capabilities, message formats, and implementation guidelines for integrated polling within ObsidianIRC, utilizing the IRCv3 standard, extended with client message-tags and metadata. The core capabilitiy introduced is through the IRCv3 capabilities mechanism, specifically with the 'obsidian/polls' cap.

=== 1. Extension Capabilities ===

==== 1.1 obsidian/polls Cap ====
This capability, when enabled by the server, indicates support for in-channel and private polls. Clients can negotiate this capability during the CAP LS exchange.

==== 1.2 Negotiation ====
Clients and servers negotiate the obsidian/polls capability via the CAP negotiation mechanism. If supported by both, the client will activate poll-related message formats and metadata, which enable rich polling interactions.

=== 2. Message Formats ===

==== 2.1 Initiating a Poll ====
Clients initiate a poll using a PRIVMSG with specific message-tags and metadata. Example:

TAGs:
* event=poll''start
* id=<poll''id>
* question=<UTF-8 string>
* options=<list of options>
* anonymous=<true/false (optional)>

Message format:

@event=poll''start;id=1234;question=What is your favorite color?;options=Red,Blue,Green;anonymous=false :<target> !poll

==== 2.2 Voting ====
Users submit votes similarly, with message-tags indicating vote event:

TAGs:
* event=poll''vote
* id=<poll''id>
* option=<option''value>

Message format:

@event=poll''vote;id=1234;option=Blue :<target> !vote

==== 2.3 Ending or Closing a Poll ====
Polls can be ended either by the poll creator or by server policy:

TAGs:
* event=poll''end
* id=<poll''id>

Message format:

@event=poll''end;id=1234 :<target> !endpoll

=== 3. Metadata and Message-Tags Usage ===

* All poll-related messages include message-tags such as 'event', 'id', 'question', 'options', etc.
* These tags ensure rich, machine-readable, and extensible message content.
* Optional tags like 'anonymous' can influence client UI and result privacy.

=== 4. Implementation Guidelines ===

* Clients should parse message-tags to correctly identify poll events.
* Servers must support CAP obsidian/polls and associate message-tags accordingly.
* All poll actions should be logged server-side for audit and analytics purposes.
* Clients should verify the presence of the obsidian/polls cap before attempting to parse or send poll messages.

=== 5. Security Considerations ===

* Vote validation must ensure that duplicate votes are prevented if not anonymous.
* Poll creator identity should remain confidential if anonymity is enabled.
* Unauthorized starting or ending of polls should be blocked.
* All message data should be sanitized to prevent injection or parsing errors.

=== 6. Summary ===

The obsidian/polls capability, coupled with message-tags, offers a flexible, extendable, and secure polling framework within IRC channels. Clients and servers are encouraged to implement these standards to facilitate interactive and engaging conversations.