twentythree-skills 1.0.0

package/skills/workflows/upload-and-publish.md

@@ -0,0 +1,146 @@
+---
+name: upload-and-publish
+description: Upload a video file, set metadata, and publish it on TwentyThree.
+---
+
+# Workflow: Upload and Publish a Video
+
+> Complete sequence for uploading a video file, setting metadata, and making it publicly visible.
+> All commands use `--json` — capture IDs from the `data.photo_id` field of upload responses and `data.id` for other responses.
+
+> See [`reference/video.md`](../reference/video.md) for exhaustive flag details and [`reference/category.md`](../reference/category.md) for category selection.
+
+## Prerequisites
+
+- Auth scope required: **write**
+- Run `twentythree auth credentials` if not already configured.
+- Confirm auth: `twentythree auth status --json`
+- Chunked upload is automatic — `twentythree video upload` handles chunking internally (see `reference/video.md` §video upload).
+
+## Steps
+
+### 1. (Optional) List categories to find a target category ID
+
+```bash
+twentythree category list --json
+```
+
+Expected output shape: `{ data: [ { id, title, description, hidden }, ... ] }`
+Capture: `data[n].id` of the desired row as `category_id`
+On failure:
+- `401 Unauthorized` → run `twentythree auth status --json` to confirm credentials
+- Empty list → confirm workspace has categories; create one with `twentythree category create --title "…" --json`
+
+---
+
+### 2. Upload the video
+
+```bash
+twentythree video upload ./video.mp4 --title "Product Demo" --category-id <category_id> --json
+```
+
+Expected output shape: `{ ok: true, data: { photo_id, tree_id, token } }`
+Capture:
+- `data.photo_id` as `video_id`
+- Construct admin URL as: `https://<domain>/manage/video/<data.photo_id>`
+  (surface this to the user — the CLI prints it on stdout but it is not in the JSON data object)
+
+On failure:
+- Network error or `401` → run `twentythree auth status` and `twentythree doctor`
+- Upload stalls → retry; chunked upload resumes automatically (see `reference/video.md` for `--chunk-size` / `--concurrency` tuning)
+- `413 Payload Too Large` → the file exceeds workspace quota; check `twentythree site get --include-quota --json`
+
+---
+
+### 3. (Optional) Set additional metadata
+
+```bash
+twentythree video update <video_id> --description "Launch video for Q2 release" --tags "product q2 launch" --json
+```
+
+Expected output shape: `{ ok: true, data: { photo_id, title, description, ... } }`
+Capture: none (fire-and-forget update — verify with `twentythree video get <video_id> --json` if needed)
+On failure:
+- `403 Forbidden` → confirm auth scope is `write`, not `read`
+- `404 Not Found` → confirm `video_id` is correct and video exists (`twentythree video get <video_id> --json`)
+
+---
+
+### 4. (Optional) Set a custom thumbnail frame
+
+```bash
+twentythree video frame <video_id> --time 10 --json
+```
+
+Expected output shape: `{ data: { id, thumbnail_url } }`
+Capture: none
+On failure:
+- `400 Invalid Time` → ensure `--time` is less than video duration (check via `twentythree video get <video_id> --json`)
+
+---
+
+### 5. (Optional) Wait for transcoding to complete
+
+```bash
+twentythree video transcoding-progress <video_id> --json
+```
+
+Expected output shape: `{ data: { status, progress } }`
+Capture: `data.status` — must be `complete` before publishing
+On failure:
+- Status stuck at `processing` for >10 minutes → contact support; do NOT publish
+- Status `failed` → check the video file; re-upload if corrupt
+
+Polling pattern:
+
+```bash
+while true; do
+  STATUS=$(twentythree video transcoding-progress <video_id> --json | jq -r '.data.status')
+  if [ "$STATUS" = "complete" ]; then break; fi
+  sleep 30
+done
+```
+
+---
+
+### 6. Publish
+
+```bash
+twentythree video update <video_id> --publish --json
+```
+
+Expected output shape: `{ data: { id, published: true } }`
+Capture: confirm `data.published` is `true`
+On failure:
+- `403 Forbidden` → confirm auth scope is `write`
+- Publish fails silently → run `twentythree video get <video_id> --json` and check `published` field
+
+---
+
+## Error Handling
+
+| Step | Failure | What to check |
+|------|---------|---------------|
+| 1 | Empty category list | `twentythree category create --title "…" --json` to create one |
+| 1 | `401 Unauthorized` | `twentythree auth status --json` to confirm credentials |
+| 2 | Upload auth/network error | `twentythree auth status --json`, `twentythree doctor` |
+| 2 | Quota exceeded | `twentythree site get --include-quota --json` |
+| 3 | 403 Forbidden | Confirm auth scope is `write` |
+| 3 | 404 Not Found | `twentythree video get <video_id> --json` to confirm video exists |
+| 4 | Invalid time | `--time` must be less than duration from `video get` |
+| 5 | Transcoding stuck | Poll `transcoding-progress` after 30s; contact support after 10 min |
+| 5 | Status `failed` | Check video file integrity; re-upload if corrupt |
+| 6 | 403 Forbidden | Confirm auth scope is `write` |
+| 6 | Publish fails silently | `twentythree video get <video_id> --json` to check `published` field |
+
+## Notes
+
+- All 6 steps can be scripted in sequence; only Steps 2 and 6 are strictly required (1, 3, 4, 5 are optional).
+- For a minimal end-to-end sequence: pass `--publish` directly to the upload command:
+  ```bash
+  twentythree video upload ./video.mp4 --title "Demo" --publish --json
+  ```
+  This is valid but skips the optional metadata, frame, and transcoding-check steps.
+- The admin URL from Step 2 opens the video's admin edit page — surface this to the user so they can review or make manual edits. Construct it as `https://<domain>/manage/video/<data.photo_id>` (it is printed on stdout by the CLI but is not included in the JSON data object).
+- `--category-id` accepts a comma-separated list of IDs to assign to multiple categories simultaneously.
+- After a successful publish, use `twentythree video get <video_id> --json` to confirm the `published` field is `true` before reporting success to the user.

package/skills/workflows/webinar-lifecycle.md

@@ -0,0 +1,209 @@
+---
+name: webinar-lifecycle
+description: Create, configure, run, record, and archive a live webinar end-to-end.
+---
+
+# Workflow: Webinar Lifecycle
+
+> Complete sequence from creating a webinar through archiving it after the session ends.
+> All commands use `--json` — capture IDs from the `data.id` field of each response.
+> CLI `webinar` maps to API `live` — see `reference/webinar.md` §Terminology Notes.
+
+> See [`reference/webinar.md`](../reference/webinar.md) for exhaustive flag details on every command referenced below.
+
+## Prerequisites
+
+- Auth scope required: **write** (create, update, upload-image, recording, publishing)
+  - Some read-only steps (room connect, clips) accept `read` scope
+- Run `twentythree auth credentials` if not already configured.
+- Confirm auth: `twentythree auth status --json`
+- NOTE: There is no `webinar get` command — to retrieve webinar details, use `webinar list --search "<title>" --json` (see `reference/webinar.md`).
+
+## Steps
+
+### 1. Create the webinar
+
+```bash
+twentythree webinar create --title "Q2 Town Hall" --live-date "2026-05-15T16:00:00Z" --description "Quarterly update" --json
+```
+
+Expected output shape: `{ data: { id, admin_url } }`
+Capture:
+- `data.id` as `webinar_id`
+- `data.admin_url` as `admin_url` (surface to the user — always print ID + admin URL after create)
+
+On failure:
+- `400 Invalid date` → `--live-date` must be ISO 8601 (e.g. `2026-05-15T16:00:00Z`)
+- `401 Unauthorized` → run `twentythree auth status --json`
+
+---
+
+### 2. (Optional) Add agenda sections
+
+```bash
+twentythree webinar section add <webinar_id> --title "Intro" --start-time 0 --json
+twentythree webinar section add <webinar_id> --title "Q&A" --start-time 1800 --json
+```
+
+Expected output shape: `{ data: { id, title, start_time } }`
+Capture: `data.id` as `section_id` if you intend to update or remove this section later; otherwise none
+On failure:
+- `404 Not Found` → confirm `webinar_id` exists (`twentythree webinar list --search "<title>" --json`)
+- Validation error → confirm `--start-time` is in seconds, not mm:ss format
+
+---
+
+### 3. (Optional) Add speakers
+
+```bash
+twentythree webinar speaker add <webinar_id> --name "Jane Doe" --email jane@example.com --title "CTO" --json
+```
+
+Expected output shape: `{ data: { id, name, role } }`
+Capture: `data.id` as `speaker_id` if you need to update or remove this speaker later
+On failure:
+- Missing required flag → run `twentythree webinar speaker add --agent` to see the complete flag list
+- `404 Not Found` → confirm `webinar_id` exists
+
+---
+
+### 4. (Optional) Upload a thumbnail image
+
+```bash
+twentythree webinar upload-image <webinar_id> ./thumb.jpg --type thumbnail --json
+```
+
+Expected output shape: none (upload-image returns no JSON body — success is confirmed by exit code 0)
+Capture: none (image is attached to the webinar automatically)
+On failure:
+- `413 Payload Too Large` → resize image; chunked upload is automatic but workspace size limits still apply
+- `401 Unauthorized` → run `twentythree auth status --json`
+
+---
+
+### 5. Publish the webinar (make visible to registrants)
+
+```bash
+twentythree webinar update <webinar_id> --publish --json
+```
+
+Expected output shape: `{ data: { id, published: true } }`
+Capture: confirm `data.published` is `true`
+On failure:
+- `403 Forbidden` → auth scope `write` required
+- Publish fails silently → run `twentythree webinar list --search "<title>" --json` and check the `published` field
+
+---
+
+### 6. Get room connection info (when going live)
+
+```bash
+twentythree webinar room connect <webinar_id> --json
+```
+
+Expected output shape: `{ data: { stream_key, room_url } }`
+Capture:
+- `data.stream_key` as `stream_key` — pass to your broadcasting software (OBS, Zoom, etc.)
+- `data.room_url` as `room_url` — pass to moderators who join the room
+
+On failure:
+- Webinar status is `previous` → room connection unavailable for archived webinars; run `twentythree webinar update <webinar_id> --status upcoming --json` to re-open
+- `404 Not Found` → confirm `webinar_id` is correct
+
+---
+
+### 7. (Optional) Start recording once the live session is active
+
+```bash
+twentythree webinar recording start <webinar_id> --json
+```
+
+Expected output shape: `{ data: {} }` (recording start returns minimal output; confirm via `recording status`)
+Capture: none (recording is attached to the webinar; monitor via `webinar recording status`)
+On failure:
+- `409 Conflict` → recording already in progress; run `twentythree webinar recording status <webinar_id> --json` to check
+- `403 Forbidden` → auth scope `write` required
+
+---
+
+### 8. Stop recording (after session ends)
+
+```bash
+twentythree webinar recording stop <webinar_id> --json
+```
+
+Expected output shape: `{ data: {} }` (recording stop returns minimal output; clip processing begins asynchronously)
+Capture: none
+On failure:
+- `409 Conflict` → no recording in progress; confirm with `twentythree webinar recording status <webinar_id> --json`
+
+---
+
+### 9. Check recording status and wait for clips
+
+```bash
+twentythree webinar recording status <webinar_id> --json
+twentythree webinar clips <webinar_id> --json
+```
+
+Expected output shape:
+- `recording status`: `{ data: { status, ... } }` — check `data.status` for `processing` or `complete`
+- `webinar clips`: `{ data: [ { id, title, duration, ... } ] }` — array of clip objects; empty while still processing
+
+Capture:
+- `recording status` `data.status` — must be `complete` before clips are fully available
+- `webinar clips` array — each element is a clip with an `id` you can use with `twentythree video` commands
+
+On failure:
+- Clips array empty immediately after `stop` → normal; recording processing takes several minutes
+- Clips still empty after 10+ minutes → contact support
+
+Polling pattern (wait for at least one clip to be available):
+
+```bash
+while true; do
+  CLIPS=$(twentythree webinar clips <webinar_id> --json | jq '.data | length')
+  if [ "$CLIPS" -gt 0 ]; then break; fi
+  sleep 60
+done
+```
+
+---
+
+### 10. (Optional) Archive — mark as previous
+
+```bash
+twentythree webinar update <webinar_id> --status previous --json
+```
+
+Expected output shape: `{ data: { id, status: "previous" } }`
+Capture: none
+On failure:
+- `400 Bad Request` → check current status; `recording stop` must be called before archiving a live session
+- Some status transitions may be blocked: confirm `recording status` is not `recording` before archiving
+
+---
+
+## Error Handling
+
+| Step | Failure | What to check |
+|------|---------|---------------|
+| 1 | Invalid date | `--live-date` must be ISO 8601 (e.g. `2026-05-15T16:00:00Z`) |
+| 1 | `401 Unauthorized` | `twentythree auth status --json` to confirm credentials |
+| 2-3 | Missing required flags | Run `twentythree webinar <subtopic> <cmd> --agent` to enumerate all flags |
+| 2-3 | `404 Not Found` | `webinar_id` invalid; `twentythree webinar list --search "<title>" --json` to find it |
+| 5 | Publish 403 | Confirm auth scope is `write` |
+| 6 | Room connection blocked | Webinar status must be `upcoming` or `live`, not `previous` |
+| 7 | Recording 409 Conflict | Already recording; `twentythree webinar recording status <webinar_id> --json` first |
+| 8 | Stop 409 Conflict | No recording in progress; verify with `recording status` |
+| 9 | Clips empty | Processing can take 10+ minutes after `recording stop`; poll every 60s |
+| 10 | Status transition blocked | Confirm `recording stop` was called; check `recording status` is not `recording` |
+
+## Notes
+
+- Steps 2-4 (sections, speakers, thumbnail) are optional but improve viewer experience.
+- Step 6 (`room connect`) returns credentials for a third-party broadcaster. Agents should NOT attempt to stream content themselves — pass the `stream_key` and `room_url` to the user.
+- Steps 7-8 (recording start/stop) are optional. If you skip them, no clips will be generated after the session.
+- Step 9's polling loop can be replaced by subscribing to the `recording.completed` webhook event (see `reference/webhook.md`).
+- Use `twentythree webinar list --search "<title>" --json` as the canonical way to retrieve webinar details — there is no `webinar get` command.
+- Clips generated from recording are standard video assets. After they appear in `webinar clips`, you can manage them with the full `video` command set (e.g. `twentythree video update <clip_id> --publish --json`).