twentythree-skills 1.0.0

package/skills/reference/poll.md

@@ -0,0 +1,174 @@
+---
+name: poll
+description: Create and manage in-webinar polls (questions with answer options shown to live viewers).
+---
+
+# TwentyThree Poll Commands
+
+> Create, configure, and manage interactive polls shown to live webinar viewers.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: anonymous (list, answer), write (add, update, remove, set-options).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> Polls are attached to webinars (live objects) via `--object-id`. Always pass the webinar ID as `--object-id`.
+> For any flag not listed here, run `twentythree poll <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### poll list
+
+**Auth scope:** anonymous  **Side effects:** none  **Output:** table (ID, Question, Open, Results Visible)
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID (webinar or live object) |
+| `--object-token` | no | Object token (auto-looked up if omitted) |
+
+```bash
+# List all polls for a webinar
+twentythree poll list --object-id <webinar-id> --json
+
+# List polls using a specific object token
+twentythree poll list --object-id <webinar-id> --object-token <token> --json
+```
+
+### poll add
+
+**Auth scope:** write  **Side effects:** creates  **Output:** none
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | yes | Object ID (webinar or live object) |
+| `--question` | no | Poll question text |
+
+```bash
+# Create a new poll for a webinar
+twentythree poll add --object-id <webinar-id> --question "What is your role?" --json
+
+# Create a poll without a question (set it later with update)
+twentythree poll add --object-id <webinar-id> --json
+```
+
+### poll update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Takes `<poll-id>` as positional argument.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--question` | no | Updated poll question text |
+| `--open` | no | Open or close the poll (boolean) |
+| `--display-results` | no | Show or hide results to viewers (boolean) |
+
+```bash
+# Open a poll for voting
+twentythree poll update <poll-id> --open --json
+
+# Close the poll and display results to viewers
+twentythree poll update <poll-id> --no-open --display-results --json
+```
+
+### poll remove
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** none
+
+Takes `<poll-id>` as positional argument. No additional flags.
+
+```bash
+# Delete a poll from a webinar
+twentythree poll remove <poll-id> --json
+
+# Remove a poll that is no longer needed
+twentythree poll remove <poll-id> --json
+```
+
+### poll answer
+
+**Auth scope:** anonymous  **Side effects:** creates  **Output:** none
+
+Takes `<poll-id>` as positional argument. Submits a viewer's answer to a poll.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | no | Object ID (webinar or live object) |
+| `--object-token` | no | Object token (auto-looked up if omitted) |
+| `--option-id` | no | Poll option ID to vote for |
+
+```bash
+# Submit a poll answer by option ID
+twentythree poll answer <poll-id> --object-id <webinar-id> --option-id <option-id> --json
+
+# Answer with an object token
+twentythree poll answer <poll-id> --object-id <webinar-id> --object-token <token> --option-id <option-id> --json
+```
+
+### poll set-options
+
+**Auth scope:** write  **Side effects:** updates  **Output:** none
+
+Takes `<poll-id>` as positional argument. Use `--option` repeatedly to set multiple options.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--option` | no | Poll option text (repeat flag for multiple options) |
+
+```bash
+# Set two options on a poll
+twentythree poll set-options <poll-id> --option "Yes" --option "No" --json
+
+# Set multiple options
+twentythree poll set-options <poll-id> --option "Option A" --option "Option B" --option "Option C" --json
+```
+
+## Common Patterns
+
+### Create a poll with options and open it for voting
+
+```bash
+# Step 1: Create the poll for a webinar
+twentythree poll add --object-id <webinar-id> --question "Which feature matters most?" --json
+
+# Step 2: Set the answer options using the poll ID from step 1
+twentythree poll set-options <poll-id> --option "Performance" --option "Ease of Use" --option "Integrations" --json
+
+# Step 3: Open the poll so viewers can vote
+twentythree poll update <poll-id> --open --json
+
+# Step 4: Close the poll and display results at the end
+twentythree poll update <poll-id> --no-open --display-results --json
+```
+
+### Review existing polls on a webinar
+
+```bash
+# List all polls and their current state
+twentythree poll list --object-id <webinar-id> --json
+
+# Open a previously closed poll again
+twentythree poll update <poll-id> --open --json
+```
+
+### Update a poll question before opening
+
+```bash
+# Change the question text before opening to viewers
+twentythree poll update <poll-id> --question "Updated: Which feature is most important?" --json
+
+# Then open for voting
+twentythree poll update <poll-id> --open --json
+```

package/skills/reference/presentation.md

@@ -0,0 +1,99 @@
+---
+name: presentation
+description: Workspace-level presentation and embed settings (link locations and setting CRUD).
+---
+
+# TwentyThree Presentation Commands
+
+> Manage workspace-level presentation and embed configuration.
+> There is no CRUD for presentation objects — these commands manage workspace-level settings only.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (page link-locations, setting list), write (setting update).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree presentation <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### presentation page link-locations
+
+**Auth scope:** read  **Side effects:** none  **Output:** table (Link Location, Label)
+
+Lists valid link location identifiers for presentation pages. No flags required.
+Use this to discover accepted values before authoring presentation content.
+
+```bash
+# Discover all available link locations
+twentythree presentation page link-locations --json
+
+# Use in a script to inspect available values
+twentythree presentation page link-locations --json
+```
+
+### presentation setting list
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Lists all current workspace presentation settings as key-value pairs. No flags required.
+Use this to review current configuration before making updates.
+
+```bash
+# List all current presentation settings
+twentythree presentation setting list --json
+
+# Inspect settings before planning updates
+twentythree presentation setting list --json
+```
+
+### presentation setting update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Updates one or more workspace presentation settings. The `--set` flag is repeatable — pass it
+multiple times to update several settings in a single call.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--set` | no | Setting key=value pair (repeatable) |
+
+```bash
+# Update the site name
+twentythree presentation setting update --set site_name="My Brand" --json
+
+# Update multiple settings atomically
+twentythree presentation setting update \
+  --set site_name="My Brand" \
+  --set logo_url="https://example.com/logo.png" \
+  --json
+```
+
+## Common Patterns
+
+### Discover link locations before authoring content
+
+```bash
+# Step 1: List available link locations to know accepted values
+twentythree presentation page link-locations --json
+
+# Step 2: Review current presentation settings
+twentythree presentation setting list --json
+
+# Step 3: Update relevant settings
+twentythree presentation setting update --set site_name="Updated Brand" --json
+```
+
+### Update multiple presentation settings atomically
+
+```bash
+# Apply several settings in one command call
+twentythree presentation setting update \
+  --set site_name="Q2 Campaign" \
+  --set logo_url="https://assets.example.com/logo-q2.png" \
+  --json
+```

package/skills/reference/protection.md

@@ -0,0 +1,131 @@
+---
+name: protection
+description: Apply and verify access protection (password/SSO/token) on videos and webinars.
+---
+
+# TwentyThree Protection Commands
+
+> Apply, remove, and verify access protection on videos and webinars.
+> Supported protection methods: `password`, `sso`, `token`.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: write (protect, unprotect), read (verify).
+Valid `--protection-method` values: `password`, `sso`, `token`.
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree protection <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### protection protect
+
+**Auth scope:** write  **Side effects:** creates  **Output:** key-value
+
+Applies protection to a video or webinar. Specify the method with `--protection-method`.
+The optional `--grace-minutes` flag delays protection activation to allow existing sessions to continue.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--protection-method` | yes | Protection method: `password`, `sso`, or `token` |
+| `--object-id` | no | ID of the video or webinar to protect |
+| `--grace-minutes` | no | Grace period in minutes before protection activates |
+
+```bash
+# Protect a video with password, allowing a 10-minute grace period
+twentythree protection protect --protection-method password \
+  --object-id <video-id> --grace-minutes 10 --json
+
+# Apply SSO protection to a webinar
+twentythree protection protect --protection-method sso \
+  --object-id <webinar-id> --json
+```
+
+### protection unprotect
+
+**Auth scope:** write  **Side effects:** destructive  **Output:** key-value
+
+Removes protection from a video or webinar.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--object-id` | no | ID of the video or webinar to unprotect |
+
+```bash
+# Remove protection from a specific video
+twentythree protection unprotect --object-id <video-id> --json
+
+# Remove protection from a webinar
+twentythree protection unprotect --object-id <webinar-id> --json
+```
+
+### protection verify
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Checks whether a viewer has valid credentials for protected content. Useful for server-side
+access checks before serving an embed or issuing a session token.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--protection-method` | yes | Protection method to verify against: `password`, `sso`, or `token` |
+| `--video-id` | no | Video ID to verify access for (maps to photo_id in API) |
+| `--webinar-id` | no | Webinar ID to verify access for (maps to live_id in API) |
+| `--object-id` | no | Object ID to verify access for |
+| `--verification-data` | no | Verification data (e.g. password value, token) |
+
+```bash
+# Verify password access to a video
+twentythree protection verify --protection-method password \
+  --video-id <video-id> --verification-data "secretpass" --json
+
+# Verify token access to a webinar
+twentythree protection verify --protection-method token \
+  --webinar-id <webinar-id> --verification-data <viewer-token> --json
+```
+
+## Common Patterns
+
+### Protect a webinar with a password and a grace period
+
+```bash
+# Apply password protection with a 30-minute grace period for current viewers
+twentythree protection protect \
+  --protection-method password \
+  --object-id <webinar-id> \
+  --grace-minutes 30 \
+  --json
+```
+
+### Verify a viewer's access before serving content
+
+```bash
+# Server-side check: verify the viewer has a valid token before embedding
+twentythree protection verify \
+  --protection-method token \
+  --video-id <video-id> \
+  --verification-data <viewer-token> \
+  --json
+# => Returns access status in the response
+```
+
+### Full lifecycle: protect, verify, then unprotect
+
+```bash
+# Step 1: Apply SSO protection to a video
+twentythree protection protect --protection-method sso --object-id <video-id> --json
+
+# Step 2: Verify a viewer has SSO access
+twentythree protection verify --protection-method sso --video-id <video-id> --json
+
+# Step 3: Remove protection when the access period ends
+twentythree protection unprotect --object-id <video-id> --json
+```

package/skills/reference/session.md

@@ -0,0 +1,98 @@
+---
+name: session
+description: Generate and redeem short-lived viewer session tokens for SSO-style access.
+---
+
+# TwentyThree Session Commands
+
+> Generate and redeem short-lived viewer session tokens for SSO-style access to TwentyThree content.
+> Session tokens are for viewer SSO. They are distinct from CLI auth (`twentythree auth credentials`).
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: read (both commands).
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree session <cmd> --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### session get-token
+
+**Auth scope:** read  **Side effects:** none  **Output:** key-value
+
+Generates a short-lived session token for a viewer. The token can be passed to the viewer who
+then redeems it via `session redeem-token` to gain authenticated access to TwentyThree content.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--return-url` | no | Return URL after the viewer authenticates via the session token |
+| `--email` | no | Viewer's email address (used to identify the viewer in the session) |
+| `--full-name` | no | Viewer's full name (used to identify the viewer in the session) |
+
+```bash
+# Generate a basic session token
+twentythree session get-token --json
+
+# Generate a session token for a named viewer with a return URL
+twentythree session get-token \
+  --email viewer@example.com \
+  --full-name "Jane Doe" \
+  --return-url "https://example.com/videos" \
+  --json
+```
+
+### session redeem-token
+
+**Auth scope:** read  **Side effects:** updates  **Output:** key-value
+
+Redeems a session token to authenticate a viewer. The token is typically passed from the
+server-side `session get-token` response to the viewer's browser, which then exchanges it
+for a session.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--session-token` | yes | Session token to redeem |
+
+```bash
+# Redeem a session token
+twentythree session redeem-token --session-token <token> --json
+
+# Redeem in a scripted viewer-access flow
+twentythree session redeem-token --session-token <session-token> --json
+```
+
+## Common Patterns
+
+### Full SSO viewer access flow
+
+```bash
+# Step 1: Server-side — generate a session token for the viewer
+twentythree session get-token \
+  --email viewer@example.com \
+  --full-name "Jane Doe" \
+  --return-url "https://platform.example.com/dashboard" \
+  --json
+# => Returns { session_token: "<token>", ... }
+# Capture: session_token
+
+# Step 2: Pass the token to the viewer (via redirect, page param, or API response)
+
+# Step 3: Viewer redeems the token to establish their session
+twentythree session redeem-token --session-token <token> --json
+```
+
+### Generate a session token for anonymous viewer access
+
+```bash
+# Token without email/name — creates an anonymous viewer session
+twentythree session get-token \
+  --return-url "https://example.com/content" \
+  --json
+```

package/skills/reference/setting.md

@@ -0,0 +1,115 @@
+---
+name: setting
+description: Update workspace settings via key=value pairs with optional dry-run validation.
+---
+
+# TwentyThree Setting Commands
+
+> Update workspace configuration settings as key=value pairs.
+> Setting keys are workspace-specific. Check the workspace admin UI for the list of valid keys.
+> Always use `--json` in agentic contexts for structured output.
+
+## Prerequisites
+
+Auth scope required: write.
+Run `twentythree auth credentials` if not already configured.
+Verify: `twentythree auth status --json`
+
+> For any flag not listed here, run `twentythree setting update --agent` to get the complete flag list, types, and defaults.
+
+## Commands
+
+### setting update
+
+**Auth scope:** write  **Side effects:** updates  **Output:** key-value
+
+Updates one or more workspace settings as key=value pairs. The `--set` flag is repeatable —
+pass it multiple times to update several settings in a single call.
+
+Use `--validate-only` to perform a dry-run and verify that the key=value pairs are accepted
+before actually applying them. This is especially useful when updating multiple settings.
+
+Flags:
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--set` | no | Setting key=value pair (repeatable) |
+| `--validate-only` | no | Dry-run: validate settings without applying changes |
+
+```bash
+# Update a single setting
+twentythree setting update --set site_name="My Workspace" --json
+
+# Update multiple settings in one call
+twentythree setting update --set theme=dark --set language=en --json
+
+# Dry-run: validate before applying
+twentythree setting update --set site_name="Test" --validate-only --json
+```
+
+## Common Patterns
+
+### Dry-run a setting change before applying
+
+```bash
+# Step 1: Validate the change (no write to the workspace)
+twentythree setting update --set branding_color="#ff0000" --validate-only --json
+
+# Step 2: If validation passes, apply the change for real
+twentythree setting update --set branding_color="#ff0000" --json
+```
+
+### Apply multiple settings atomically
+
+```bash
+# All settings applied in a single API call
+twentythree setting update \
+  --set site_name="Brand Workspace" \
+  --set language=en \
+  --set timezone=UTC \
+  --json
+```
+
+### Validate a multi-key update before committing
+
+```bash
+# Step 1: Validate all keys together
+twentythree setting update \
+  --set key1=val1 \
+  --set key2=val2 \
+  --set key3=val3 \
+  --validate-only \
+  --json
+
+# Step 2: Review validation response, then apply if OK
+twentythree setting update \
+  --set key1=val1 \
+  --set key2=val2 \
+  --set key3=val3 \
+  --json
+```
+
+### Timezone and locale configuration
+
+```bash
+# Set workspace timezone
+twentythree setting update --set timezone=Europe/Copenhagen --json
+
+# Set workspace language
+twentythree setting update --set language=da --json
+
+# Set both together with a dry-run check first
+twentythree setting update --set timezone=Europe/Copenhagen --set language=da --validate-only --json
+twentythree setting update --set timezone=Europe/Copenhagen --set language=da --json
+```
+
+### Branding and appearance settings
+
+```bash
+# Update the workspace site name shown in the embed player
+twentythree setting update --set site_name="Company Video Hub" --json
+
+# Validate a logo URL before applying
+twentythree setting update --set logo_url="https://cdn.example.com/logo.png" --validate-only --json
+twentythree setting update --set logo_url="https://cdn.example.com/logo.png" --json
+```