twentythree-skills 1.1.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twentythree-skills",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "description": "AI agent skills for the TwentyThree CLI",
   "license": "MIT",
   "author": "TwentyThree",

package/skills/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Full TwentyThree video platform CLI. Use when the user asks to upload or manage
   videos, run webinars, query analytics, manage audiences, configure players,
   create categories, manage tags, spots, thumbnails, webhooks, collectors, polls,
-  presentations, or any TwentyThree platform operation. Covers 235+ API commands
+  presentations, or any TwentyThree platform operation. Covers 238+ API commands
   across 22 resource groups plus meta commands (auth, workspace, autocomplete, doctor).
   Every command supports --json for machine-readable output and --agent for
   self-describing metadata (api_endpoint, auth_scope, output_shape, side_effects).
@@ -17,6 +17,9 @@ triggers:
   - twentythree
   - video platform
   - TwentyThree CLI
+  - personal video
+  - record video
+  - video recording
 invocable: true
 argument-hint: "<topic> <verb> [flags]"
 allowed-tools: Bash(twentythree *)
@@ -25,7 +28,7 @@ compatibility: Requires twentythree-cli installed globally (npm install -g twent
 
 # TwentyThree CLI
 
-> Terminal access to the full TwentyThree video platform API — videos, webinars, analytics, audiences, and every related resource. 235+ commands across 22 resource groups.
+> Terminal access to the full TwentyThree video platform API — videos, webinars, analytics, audiences, and every related resource. 238+ commands across 22 resource groups.
 >
 > Always use `--json` in agentic contexts for structured output. Always run `twentythree <command> --agent` before calling an unfamiliar command to discover its flags, API endpoint, auth scope, and side effects.
 
@@ -138,6 +141,7 @@ All 22 resource groups. Every topic supports `--agent`, `--json`, and `--workspa
 | Topic | Representative verbs | Use for |
 |-------|---------------------|---------|
 | `video` | `upload`, `list`, `get`, `update`, `delete`, `replace`, `frame`, `transcoding-progress` | Video file management, upload, metadata, thumbnails |
+| `personal` | workspace switch, list, tasks, flows, templates, email | Personal video recording — browser-based recording, mischung videos, tasks, flows |
 | `webinar` | `create`, `list`, `get`, `update`, `delete`, `repeat`, `highlights`, `clips`, `metrics`, `log` + attachment/mail/queued-video/recording/room/section/series/speaker/transcription subtopics | Live events, scheduling, recordings, attendee comms |
 | `analytics` | `conversions`, `live`, `usage`, `video` subtopics (many verbs each) | Reporting, viewer data, playback metrics, conversion tracking |
 | `audience` | `list`, `create`, `get`, `update`, `delete` + segment ops | Audience segmentation and targeting |
@@ -145,11 +149,11 @@ All 22 resource groups. Every topic supports `--agent`, `--json`, and `--workspa
 | `action` | `list`, `create`, `get`, `update`, `delete` + subtypes | Interactive overlays, CTAs inside videos |
 | `collector` | `list`, `create`, `delete` | Lead capture forms |
 | `comment` | `list`, `create`, `get`, `update`, `delete` | Video comments moderation |
-| `player` | `list`, `create`, `get`, `update`, `delete` | Player configuration and theming |
+| `player` | `list`, `create`, `get`, `update`, `delete`, `set-thumbnail`, `remove-thumbnail` | Player configuration, theming, and custom thumbnails |
 | `poll` | `list`, `create`, `get`, `update`, `delete` | In-video polls |
 | `spot` | `list`, `create`, `get`, `update`, `delete` | Hotspot annotations on videos |
 | `tag` | `list`, `create` | Content tagging |
-| `thumbnail` | `list`, `create`, `get`, `update`, `delete` | Video thumbnail management |
+| `thumbnail` | `list`, `create`, `get`, `update`, `delete`, `preview-scss` | Video thumbnail and template management |
 | `webhook` | `list`, `create`, `get`, `update`, `delete` | Event webhooks |
 | `app` | `list`, `thumbnail`, `create`, `get`, `update`, `delete` | App/integration management |
 | `presentation` | `list` + page/setting subtopics | Presentation content |

package/skills/guide.md

@@ -36,6 +36,31 @@ twentythree webinar list --search "Q2 Town Hall" --json
 
 ---
 
+### Personal Video Requires Dedicated Workspace
+
+Personal is always on its own workspace. Before any Personal or video recording operation, confirm the CLI is pointed at the Personal workspace.
+
+1. Check current workspace: `twentythree auth status --json` — inspect `data.domain`
+2. Personal workspace domains follow `*.personalvideo.co` or a custom domain configured for Personal
+3. If not on the Personal workspace, list options: `twentythree workspace list --json`
+4. Confirm intent with the user before switching, showing both current and target domains
+5. Switch: `twentythree workspace use <personal-domain>`
+
+Never silently switch workspaces. Always show the user what workspace they're on and what they're switching to.
+
+```bash
+# Check current workspace
+twentythree auth status --json
+
+# List all configured workspaces
+twentythree workspace list --json
+
+# Switch to Personal workspace (confirm with user first)
+twentythree workspace use company.personalvideo.co
+```
+
+---
+
 ### Webinar Creation Defaults
 
 Verify publication and draft flags when creating webinars — the defaults may not match your intent. Pass `--publish` to make the webinar immediately visible or `--draft` to hold it unpublished. Run `twentythree webinar create --agent` to confirm all available access flags before creating.

package/skills/reference/personal.md

@@ -0,0 +1,229 @@
+---
+name: personal
+description: Personal video recording — browser-based screen/webcam recording, mischung videos, templates, flows, tasks, folders, activities, email sharing, and use case catalog. Always operates on a dedicated Personal workspace.
+---
+
+# TwentyThree Personal Video
+
+> Personal is a browser-based screen/webcam recording tool in the TwentyThree suite.
+> All Personal operations use standard TwentyThree API calls, but against a **dedicated Personal workspace** — not the user's main video or webinar workspace.
+> **Before any Personal operation, confirm the active workspace is the Personal workspace.**
+
+## Terminology
+
+| Personal product term | API / CLI term |
+|-----------------------|----------------|
+| Personal video | mischung video (`mischung_p=1`) |
+| Template | mischung template (`mischung_template_p=1`) |
+| Flow | user group (`usergroup`) |
+| Folder | album (CLI: `category`) |
+| Recording part / track | mischung part/track |
+| Task | mischung task (`/photo/mischung/task/*`) |
+
+---
+
+## § Workspace Context
+
+> **CRITICAL: Personal always lives in its own workspace. Never operate on Personal data from the wrong workspace.**
+
+### Check current workspace
+
+```bash
+twentythree auth status --json
+# Inspect data.domain — Personal workspaces typically use *.personalvideo.co
+# or a custom domain configured for Personal.
+```
+
+### If not on the Personal workspace
+
+1. List all configured workspaces:
+
+```bash
+twentythree workspace list --json
+```
+
+2. Identify the Personal workspace domain in the output.
+3. **Show the user both the current domain and the target domain. Confirm intent before switching.**
+4. Switch:
+
+```bash
+twentythree workspace use company.personalvideo.co
+```
+
+**Never silently switch workspaces.** Always show the user what workspace they are on and what they are switching to before running `workspace use`.
+
+---
+
+## § Video Listing (Personal)
+
+Always filter with `--mischung` (maps to `mischung_p=1`) when listing Personal recordings. Check flag availability with `twentythree video list --agent` before use — flags may not yet be implemented; if unavailable, use raw API calls.
+
+| View | CLI flags | Description |
+|------|-----------|-------------|
+| My videos | `video list --mischung --user-id me --include-unpublished --json` | User's own recordings |
+| Team videos | `video list --mischung --include-unpublished --require-posts --orderby posted --json` | All team recordings |
+| Templates | `video list --mischung-template --include-unpublished --json` | Recording templates |
+| Folder contents | `video list --category-id <album_id> --mischung --json` | Videos in a specific folder |
+
+---
+
+## § Mischung Video Operations
+
+### CLI commands (standard video topic)
+
+| Operation | Command |
+|-----------|---------|
+| Get specific recording | `twentythree video list --photo-id <id> --mischung --include-unpublished --json` |
+| Update metadata | `twentythree video update <id> --title "…" --json` |
+| Delete | `twentythree video delete <id> --json` |
+| Transcoding progress | `twentythree video transcoding-progress <id> --json` |
+
+For transcoding-progress, check `.data.progress.all` in the response — `1.0` means ready.
+
+### Operations without CLI commands (raw API)
+
+| Operation | Notes |
+|-----------|-------|
+| Upload (new mischung) | Multi-step asset flow — see Raw API Operations section |
+| Replace (edit existing) | Raw API — see Raw API Operations section |
+| Duplicate / create from template | `POST /photo/mischung/duplicate?photo_id=<id>` |
+
+---
+
+## § Templates
+
+Templates are mischung videos with `mischung_template_p=1`.
+
+| Operation | Method |
+|-----------|--------|
+| List templates | `twentythree video list --mischung-template --include-unpublished --json` (verify flag with `--agent`) |
+| Save video as template | `twentythree video update <id> --mischung-template-p 1 --json` (verify flag) or raw `POST /photo/update?photo_id=<id>&mischung_template_p=1` |
+| Create from template | raw `POST /photo/mischung/duplicate?photo_id=<template_id>` |
+| Set template icon | raw `POST /photo/update?photo_id=<id>&mischung_template_icon=<icon>` |
+| List available icons | raw `GET /internal/design/icons` |
+
+---
+
+## § Tasks
+
+Tasks assign recording work to users. All task operations use raw API calls. Get `api_base_url` from `twentythree auth status --json` → `data.api_base_url`.
+
+| Operation | Endpoint |
+|-----------|----------|
+| List my tasks | `POST /photo/mischung/task/list?assignee_user_id=me` |
+| List tasks I created | `POST /photo/mischung/task/list?user_id=me` |
+| Completed tasks | `POST /photo/mischung/task/list?associated_user_id=me&completed_p=1` |
+| Uncompleted count | `POST /photo/mischung/task/list?assignee_user_id=me&size=1&completed_p=0` → read `total_count` |
+| Create new video task | `POST /photo/mischung/task/add?assignee_users=<uid>&task_title=…[&template_photo_id=…]` |
+| Assign part recording | `POST /photo/mischung/task/add?assignee_user_id=<uid>&task_photo_id=<id>&task_part_uuid=<uuid>&task_title=…` |
+| Task redirect URL | `GET /photo/mischung/task/redirect?task_id=<id>` |
+| Complete task | `POST /photo/mischung/task/complete?task_id=<id>` |
+| Delete task | `POST /photo/mischung/task/delete?task_id=<id>` |
+
+**Task fields:** `task_title` (required), `task_description`, `task_notes` (script for the recording), `recipient_email`, `deadline_date`.
+
+---
+
+## § Flows (User Groups)
+
+Flows group users and videos. No dedicated CLI topic — use raw API calls.
+
+| Operation | Endpoint |
+|-----------|----------|
+| Create flow | `POST /usergroup/create?name=…&join_policy=open\|closed` |
+| Update flow | `POST /usergroup/update?user_group_id=<id>&name=…` |
+| Delete flow | `POST /usergroup/delete?user_group_id=<id>` |
+| List flows | `GET /usergroup/list[?user_id=…&photo_id=…&search=…]` |
+| Add user to flow | `POST /usergroup/join?user_group_id=<id>&user_id=<id>` |
+| Remove user from flow | `POST /usergroup/leave?user_group_id=<id>&user_id=<id>` |
+| Videos in flow | `twentythree video list --user-group-id <id> --mischung --json` (verify flag with `--agent`) |
+| Templates in flow | raw `GET /photo/list?user_group_id=<id>&mischung_p=1&mischung_template_p=1` |
+| Users in flow | `twentythree user list --user-group-id <id> --json` (verify flag with `--agent`) |
+
+---
+
+## § Folders (Albums = Categories in CLI)
+
+Folders use the album/category API. CLI topic: `twentythree category *`.
+
+| Operation | Command |
+|-----------|---------|
+| Create folder | `twentythree category create --title "My folder" --json` |
+| List folders | `twentythree category list --json` |
+| Delete folder | `twentythree category delete <album_id> --json` |
+| Place video in folder | `twentythree video update <video_id> --category-id <album_id> --json` |
+| Remove video from folder | raw `POST /photo/update?photo_id=<id>&album_id=` (empty string clears) |
+
+---
+
+## § Activities
+
+Raw `GET /user/activity?context=personal` — returns up to 100 recent items sorted by recency.
+
+Activity types: `video-watched`, `user-added`, `video-created`.
+
+Each item has: `message` (HTML), `timestamp` (UTC epoch), optional `user_avatar_url`, `user_name`, `video_thumbnail_url`.
+
+---
+
+## § Email Sharing
+
+| Operation | Endpoint |
+|-----------|----------|
+| Preview email HTML | `GET /mail/get-attachments-html?selection=photo:<id>&gif_p=0` |
+| Send video email | `POST /mail/send?selection=photo:<id>&to=…&subject=…&body=…&gif_p=0` |
+| Get embed/share links | `twentythree player embed-versions <id> --object-type photo --json` |
+
+Direct share link: in `player embed-versions` response, find the entry where `type=="link" && key=="secret"`.
+
+---
+
+## § Use Case Catalog
+
+Pre-built video templates managed by TwentyThree admins.
+
+| Operation | Endpoint |
+|-----------|----------|
+| List use cases | `GET /photo/mischung/usecase/list[?category=…&search=…&orderby=…]` |
+| List categories | `GET /photo/mischung/usecase/categories` |
+| Use a use case | `POST /photo/mischung/usecase/use?use_case_id=<id>` → returns `photo_id` |
+
+---
+
+## § User Management (Personal)
+
+Standard user commands apply. Key Personal-specific patterns:
+
+| Operation | Command |
+|-----------|---------|
+| Get current user | `twentythree user get --json` |
+| Invite user | `twentythree user create --email … --json` |
+| Resend invite | `twentythree user send-invitation --user-id <id> --json` |
+| List users | `twentythree user list --json` |
+
+Domain-gated signup: permitted domains are listed in `twentythree setting get --json` → `user_approval_auto_domains`.
+
+---
+
+## § Raw API Operations — Mischung Upload Flow
+
+When no CLI command exists, use this pattern. Get `api_base_url` from `twentythree auth status --json` → `data.api_base_url`. All paths below are relative to that base URL.
+
+**New mischung upload:**
+
+1. Get asset upload token: `POST /asset/get-upload-token?valid_minutes=360&max_uploads=50`
+2. Upload component video files, poster PNG, and `.misch` file to `/asset/redeem-upload-token` using the token
+3. Save new video: `POST /photo/mischung/upload?asset_uri=twentythree://asset/<token>/<uuid>.misch&title=…`
+
+**Save edit to existing mischung:**
+
+`POST /photo/mischung/replace?asset_uri=twentythree://asset/<token>/<uuid>.misch&photo_id=<id>`
+
+---
+
+## Terminology Notes
+
+- CLI `video` = API `photo`
+- CLI `category` = API `album`
+- Mischung = the internal term for a Personal video recording session and its component parts
+- Personal workspace = a distinct TwentyThree workspace dedicated to the Personal product; domain typically `*.personalvideo.co`

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

@@ -39,11 +39,10 @@ On failure:
 twentythree video upload ./video.mp4 --title "Product Demo" --category-id <category_id> --json
 ```
 
-Expected output shape: `{ ok: true, data: { photo_id, tree_id, token } }`
+Expected output shape: `{ ok: true, data: { photo_id, tree_id, token, admin_url } }`
 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)
+- `data.admin_url` — the admin URL for the uploaded video (surface this to the user)
 
 On failure:
 - Network error or `401` → run `twentythree auth status` and `twentythree doctor`
@@ -141,6 +140,6 @@ On failure:
   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).
+- 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. It is available as `data.admin_url` in the JSON response and also printed on stdout.
 - `--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.