@maccesar/aiskills 1.21.1 → 1.23.0

package/skills/technical-demo-videos/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: technical-demo-videos
+description: Plan and produce reproducible macOS screen-recorded technical demonstrations from a project path and a conversational goal. Use when the user wants a coding, CLI, build, simulator, emulator, or app workflow recorded in VS Code, including reviewable scripts, timed narration, captions, retakes, or final video assembly. Present the recording plan for approval before controlling the UI or starting a capture.
+---
+
+# Technical Demo Videos
+
+Turn a natural-language request into a reviewable production plan and, after approval, a reproducible recording package. Treat domain-specific projects such as Titanium, Flutter, native mobile, web, or a CLI as inputs; do not encode one repository, framework, command, or directory layout in this skill.
+
+Act as the project's technical screenwriter, director, producer, screen operator, voice-script writer, and editor. Translate the user's informal explanation into a concise visual story that is technically accurate, pleasant to watch, and practical to reproduce. These roles are responsibilities, not permission to override the user's creative brief, change the product, publish media, spend money, or begin recording without approval.
+
+## Required workflow
+
+Read only the references needed for the current phase, but read each applicable reference before drafting advice or acting:
+
+| Task | Required reference |
+|---|---|
+| Storyboard, narration intent, or take review | [references/story-direction.md](references/story-direction.md) |
+| Production package or artifact cleanup | [references/package-contract.md](references/package-contract.md) |
+| macOS or VS Code automation | [references/recording-workflow.md](references/recording-workflow.md) and [references/vscode-default-profile.md](references/vscode-default-profile.md) |
+| Audio alignment or final duration | [references/audio-timing.md](references/audio-timing.md) |
+| Upload-ready horizontal master | [references/youtube-master.md](references/youtube-master.md) |
+| Vertical or social derivative | [references/vertical-social-video.md](references/vertical-social-video.md) |
+| Publishing copy and settings | [references/publishing-metadata.md](references/publishing-metadata.md) |
+| Automated YouTube publication | [references/youtube-publishing.md](references/youtube-publishing.md) |
+
+In proposals, review notes, and handoff documents, cite each concrete production recommendation from this skill as `[source: references/<file>.md]`. Cite technical claims using the applicable domain skill or official primary documentation. If a claim cannot be verified from the inspected project or a consulted source, prefix it with `FROM_MEMORY (unverified):` instead of presenting it as fact.
+
+## Establish the request
+
+Resolve these facts from the user's message and the inspected project:
+
+- source project path;
+- demonstration goal and intended audience;
+- exact command or UI operation;
+- target platform, device, simulator, or emulator;
+- files, terminal output, and runtime result that prove success;
+- spoken language, caption language, and desired voice workflow;
+- artifact destination and naming convention.
+
+Preserve meaningful series conventions. When a project slug combines an order and the demonstrated command, such as `02-images`, keep that slug across the plan, recorder, recipe, takes, event logs, narration, captions, and final render. Do not invent a marketing title that breaks traceability unless the user requests one.
+
+Infer safe details from the project and existing conventions. Ask only when a missing choice would materially change the demonstration. Use the applicable domain skill or official documentation to validate commands and expected results. Do not execute the showcased command during planning unless a harmless preflight is necessary and the user authorized implementation rather than review only.
+
+## Route technical knowledge
+
+This skill owns production and recording decisions; it is not the technical authority for every stack. Detect the project's languages, framework, build system, requested feature, and teaching angle before drafting the proposal. Assemble the smallest useful panel of installed skills, which may combine:
+
+- **platform and framework expertise:** mobile and web frameworks, application platforms, databases, build systems, CLIs, or release tooling;
+- **software judgment:** architecture, senior engineering, refactoring, security, performance, testing, maintainability, or framework-specific best practices;
+- **presentation quality:** UI/UX, visual hierarchy, accessibility, responsive design, technical writing, diagrams, or documentation;
+- **deliverable expertise:** voice, captions, image work, presentations, or publishing when the brief actually needs them.
+
+This routing is a hard gate: do not draft the recording plan, visible sequence, narration intent, recipe, or recorder until every applicable domain skill has been loaded and its required task-specific references have been read. If a requested command, option, API, or behavior belongs to another installed skill, treat that skill and its cited sources as the technical authority. Verify the exact behavior in the inspected project or implementation when the documentation leaves any uncertainty. Never fill a technical gap with a plausible-looking command, option, output path, or product claim.
+
+Use those skills to establish:
+
+- the exact valid command and required working directory;
+- prerequisites, configuration, credentials, devices, and expected duration;
+- success and failure signals;
+- files or runtime behavior that prove the claim;
+- framework-specific actions that should or should not appear on screen.
+
+Apply specialists only when their perspective materially affects this video. A command-only demo may need the framework skill and engineering judgment but no UI redesign. A UI walkthrough may need UI/UX and accessibility guidance in addition to the framework skill. An architecture explanation may need diagrams and software-architecture analysis without changing the application.
+
+Then apply this skill to turn those verified facts into the visual sequence, narration intent, automation, and edit. If no suitable domain skill is installed, inspect the project and consult official primary documentation when current or uncertain facts matter. Never invent a command or expected result merely to complete a script.
+
+Reconcile advice in this order: the user's explicit brief and scope, factual platform constraints, observable project behavior, safety and correctness, then stylistic recommendations. Clearly label an optional best practice as a recommendation; do not present it as a prerequisite. Mention the specialist skills used in the written proposal so the user can review the basis of the technical and creative decisions.
+
+## Phase 1: propose before recording
+
+Inspect the source project without changing it. Draft a production package and present the plan to the user before any UI automation or screen recording. The proposal must include:
+
+1. the exact initial frame and preparation that will remain outside the video;
+2. every visible action in order, including commands exactly as typed;
+3. the proof shown after each meaningful action;
+4. estimated visual timing and narration beats;
+5. files that will be generated and files that will remain untouched;
+6. cleanup behavior and any external cost, login, device, or permission dependency.
+
+Shape the proposal as a short story: establish what exists before the command, show the action without wasted motion, prove the promised result, and finish on the strongest useful frame. Every spoken claim must have matching visual evidence. Remove dead time, redundant file browsing, terminal noise, and actions that do not advance the demonstration. Narration explains meaning while the image supplies evidence; it should not mechanically read filenames already visible.
+
+Use a beat table with these columns unless the user requests another format: `Beat`, `Estimated time`, `On screen`, `Operator action`, `Narration intent`, and `Proof/exit condition`. Follow it with the proposed exact command text, initial-frame checklist, expected generated artifacts, and open questions or risks.
+
+Write the draft `recording-plan.md` and recipe/recorder files when the user asked to create the production package, but mark them as draft. Then stop and request review. Approval of the concept is not approval to begin recording.
+
+Read [references/story-direction.md](references/story-direction.md) when drafting or revising the proposal. Read [references/package-contract.md](references/package-contract.md) when creating the package. Read [references/recording-workflow.md](references/recording-workflow.md) before generating or running macOS/VS Code automation. Also read [references/vscode-default-profile.md](references/vscode-default-profile.md), load an approved workstation profile when one exists, and preserve its calibrated layout across takes. When none exists, calibrate once outside capture and save the resulting values with the production package.
+
+## Phase 2: generate the reproducible package
+
+After the plan is approved, generate one permanent recorder and its data under the episode's `production/` subfolder. Build the recorder from reusable primitives in `scripts/recording_runtime.py`, but copy that runtime into the production package so recreation does not depend on this installed skill or its future version. Reserve the episode root for the final upload-ready MP4, external SRT, and one publishing-metadata document.
+
+The recorder must:
+
+- accept or derive the source project path without embedding a random temporary path;
+- create a fresh disposable copy for every take unless the workflow genuinely requires the original; select a short, dedicated copies directory from the recipe, `TECHNICAL_DEMO_COPIES_ROOT`, or the runtime default, append a random slug, and keep helpers in a separate system-temp directory so printed absolute paths remain readable;
+- verify preconditions before opening applications;
+- prepare the initial frame before capture begins;
+- identify and assert the exact target window before every UI action block;
+- record real event timestamps from the same clock as capture;
+- refuse to overwrite existing recordings or user-provided audio;
+- let validation-only checks inspect draft, approved, and finalized packages, while allowing a real capture only when the recipe is explicitly approved and its timing is ready;
+- stop capture before closing the project window;
+- close only the window it opened and remove all temporary copies and helpers in `finally` cleanup.
+
+For VS Code captures, make the accepted workstation-profile preparation part of every generated recorder. Project-specific recipes begin after that common preparation and contain only the actions that tell the episode's story. Store display selection, logical geometry, shortcuts, terminal-divider coordinates, and panel behavior as profile data rather than scattering machine-specific values through the recorder.
+
+Retakes modify the same permanent recorder or declarative recipe. Names such as `take-02` identify output media, never different throwaway automation scripts.
+
+## Phase 3: announce and capture
+
+Immediately before a real capture, send a commentary message beginning with `🎬` that says recording is about to start and asks the user not to move the mouse or keyboard. Allow a short visible lead time before starting. Never begin a capture in the same tool call that first announces it.
+
+Do all setup outside the recording: open the isolated project window, arrange panels, open the terminal, choose the correct device or simulator state, and remove Welcome or unrelated tabs. Capture only the approved sequence. Do not introduce extra pauses merely to fit provisional narration.
+
+When a simulator or emulator is needed only for a later proof beat, boot it, wait for readiness, warm the build, and terminate any previously running copy of the demonstrated app without activating the simulator window. Bring that app to the foreground only at the scheduled recorded action. This keeps preparation invisible and avoids leaving an old runtime state on screen.
+
+After capture, perform only inexpensive structural checks: confirm that capture exited, the video and event log exist, and the disposable copy was removed. Then ask the user how the take looked before extracting frames, building contact sheets, transcribing, or performing detailed visual analysis. The user watched the live sequence and is the primary first reviewer.
+
+Inspect frames only when the user requests it, reports a specific problem that needs diagnosis, or could not watch the take. Correct confirmed automation defects by editing the same recorder and creating a new take. Do not generate final narration for a rejected take.
+
+## Phase 4: narration and delivery
+
+Choose the timing authority explicitly. The default is capture-first: write narration after an accepted visual sequence, derive cue boundaries from its event log, then create narration text, cue JSON, and external SRT. When the user wants an externally generated voice track to determine the video duration, use audio-first instead: approve final narration before capture, preserve ordinary paragraph breaks, measure the returned audio, and only then lock and execute the visual recipe. Keep an audio-first recipe in draft until those measurements exist.
+
+For voice-generator input, use fluent prose and normal paragraph breaks by default. Do not inject pause-control tags such as `[short pause]`, `[pause]`, `[long pause]`, or SSML `<break>` unless the user explicitly requests provider-specific pause markup. Do not burn subtitles into the image unless explicitly requested.
+
+If the user generates voice audio in an external service, preserve the original file. Align speech blocks to cues without stretching the voice, and report a paragraph/block mismatch rather than guessing. Creating paid audio or using an external account requires the user's authorization.
+
+Measure the first and last audible speech in the returned audio instead of relying only on the container duration. Unless the brief specifies otherwise, allow roughly 0.35 seconds before the first spoken word and 1.5 seconds after the last spoken word, with a normal acceptable post-roll range of 1–2 seconds. Count silence already present in the audio toward those margins, avoid doubling it, and never use `-shortest` when it would remove the clean final frame. Read [references/audio-timing.md](references/audio-timing.md) before timing or assembling narration.
+
+Do not settle for placing the complete narration track under the capture when the spoken paragraphs and visible actions drift apart. After the take is accepted, compare every narration paragraph with its intended event and perform block-level editorial alignment whenever needed: preserve every spoken sample unchanged, trim only surplus silence at known paragraph boundaries, and place each paragraph against the action or proof it explains. Adjust visual holds or cuts when that produces the more natural result; never create one conspicuous pause to absorb a distributed timing mismatch. Record the source and final ranges in the cue sheet or recording plan so the edit is reproducible. If paragraph boundaries cannot be identified confidently, stop and report the mismatch instead of cutting through speech.
+
+Verify the final video visually and audibly. Review the beginning, every paragraph transition, every command/result beat, and the ending rather than checking duration alone. Keep a clean final frame after the last spoken line. Preserve the complete reproducible package and remove only intermediates identified by the package contract.
+
+Before naming any render `<slug>-final.mp4`, read [references/youtube-master.md](references/youtube-master.md), verify its time-sensitive defaults against current official YouTube upload guidance, and pass its delivery-master quality gate. A stream-copied mux is a review preview, not a final upload file. Validate resolution, constant frame rate, bitrate, H.264 profile, pixel format, BT.709 metadata, AAC sample rate, and fast-start layout; never infer quality from the `.mp4` extension or 4K dimensions alone.
+
+Use `scripts/events_to_cues.py` to normalize a completed event log. The generated SRT must reflect final audio alignment rather than estimated plan timings.
+
+When the user requests a vertical or social-media derivative, read [references/vertical-social-video.md](references/vertical-social-video.md). Keep it opt-in: do not reframe a horizontal master or burn dynamic captions merely because social delivery might be useful later.
+
+When the user requests titles, descriptions, keywords, hashtags, upload settings, or a complete social publishing handoff, read [references/publishing-metadata.md](references/publishing-metadata.md). Browse current official platform documentation because these recommendations and limits change, then create one clearly grouped metadata document for each episode.
+
+When the user requests automated YouTube upload, playlist placement, captions, scheduling, or metadata publication, read [references/youtube-publishing.md](references/youtube-publishing.md). Before generating the upload manifest or dry run, present a publishing-target table containing the expected channel ID/name, either an exact playlist ID/name or an explicit `none`, privacy/schedule, captions, and thumbnail. Do not infer “no playlist” from silence. If the user does not know the IDs, request authorization to run `scripts/youtube_publish.py --inspect-account` and present the authenticated channel and available playlists without uploading. Wait for the user to approve these choices.
+
+Then generate the production manifest and run a dry run with `scripts/youtube_publish.py`. Present its exact target, operations, hashes, and confirmation token. A real API upload is a separate external mutation: wait for explicit authorization that refers to the reviewed dry run, then pass its token through `--confirm-plan`. The script must verify that OAuth exposes `expectedChannelId` before performing `videos.insert`. Default new uploads to private, never invent a playlist ID, and preserve an upload receipt so retries do not create duplicate videos.

package/skills/technical-demo-videos/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Technical Demo Videos"
+  short_description: "Plan and produce reproducible technical screen demos"
+  default_prompt: "Use $technical-demo-videos to create a reviewable recording plan and reproducible production package for this technical demo. Do not record until I approve the plan."

package/skills/technical-demo-videos/evals/evals.json

@@ -0,0 +1,62 @@
+{
+  "skill_name": "technical-demo-videos",
+  "note": "Cross-domain planning evals written when a project-specific production workflow was generalized. These prompts are review fixtures, not claims of completed recordings or measured results.",
+  "evals": [
+    {
+      "id": 0,
+      "name": "node-cli-capture-plan",
+      "prompt": "Take /workspace/json-pretty-cli and make a short VS Code video showing npm test, then formatting fixtures/input.json with node bin/pretty.js. Show the output file and give me the recording plan before touching the UI.",
+      "fixture_spec": "A small Node.js CLI repository with package.json, bin/pretty.js, test/pretty.test.js and fixtures/input.json. It has no video conventions or workstation-specific paths.",
+      "expected_output": "Inspects the project and applicable Node documentation, proposes the exact initial frame, command sequence, visible proof, narration beats, disposable-copy location and cleanup, then waits for approval without recording.",
+      "assertions": [
+        "Does not start UI automation or recording before approval",
+        "Uses the exact project path and verified commands instead of framework assumptions",
+        "Shows both test success and the formatted output as separate proof beats",
+        "Keeps workstation geometry and disposable-copy root configurable",
+        "Names the production artifacts and cleanup behavior"
+      ]
+    },
+    {
+      "id": 1,
+      "name": "web-app-runtime-proof",
+      "prompt": "Plan a tutorial from /workspace/inventory-web that starts its dev server, changes the stock filter in VS Code, and proves the result in the browser. I want English narration and selectable captions.",
+      "fixture_spec": "A Vite web application with a documented npm run dev command, a StockFilter component and local fixture data. The browser can be opened without authentication or network access.",
+      "expected_output": "Loads appropriate web/UI expertise, proposes a deterministic server-readiness check and browser proof, keeps setup outside capture, and separates narration source from SRT spelling.",
+      "assertions": [
+        "Routes technical claims through applicable domain skills or primary project documentation",
+        "Waits for observable server readiness instead of a long arbitrary sleep",
+        "Defines the browser state that proves the filter works",
+        "Keeps English voice text and selectable captions as separate artifacts",
+        "Does not publish or create paid voice audio without authorization"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "retake-audio-alignment",
+      "prompt": "The take is good, but paragraph three says the build completed before the terminal reaches Finished. Fix the same recorder, keep my original voice file, and make take 2.",
+      "fixture_spec": "An approved technical-video package with recording plan, permanent recorder, take-01 MOV, event log, paragraph-based narration, original external voice MP3 and cue sheet.",
+      "expected_output": "Edits the permanent recipe rather than creating a throwaway script, preserves the supplied audio, records take 2 after a clapperboard warning, asks for the live review, and performs block-level alignment only after acceptance.",
+      "assertions": [
+        "Modifies the permanent recorder or recipe instead of creating a take-specific automation script",
+        "Never overwrites take 1 or the supplied audio",
+        "Announces the real capture with a clapperboard in a separate update",
+        "Uses actual event timing for the Finished beat",
+        "Keeps a clean post-roll and does not use one unrelated long pause to absorb drift"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "youtube-channel-playlist-targeting",
+      "prompt": "Upload the approved final video to my YouTube tutorials playlist. I have several channels and do not know the channel or playlist IDs yet.",
+      "fixture_spec": "An approved production package with final MP4, SRT, publishing metadata, OAuth client file, and token path. No channel or playlist ID has been selected.",
+      "expected_output": "Requests authorization for read-only account inspection, presents the authenticated channels and playlists, obtains an explicit channel/playlist/privacy/captions/thumbnail decision, runs a dry run, and waits for separate approval before executing with its confirmation token.",
+      "assertions": [
+        "Does not infer a channel or playlist from its visible name",
+        "Does not treat silence as approval to leave the video out of playlists",
+        "Inspects the OAuth account without uploading when IDs are unknown",
+        "Verifies expectedChannelId before videos.insert",
+        "Requires approval of the exact dry-run token before upload"
+      ]
+    }
+  ]
+}

package/skills/technical-demo-videos/references/audio-timing.md

@@ -0,0 +1,40 @@
+# Narration entrance, exit, and visual timing
+
+Read this before aligning returned narration audio or deciding the final video duration.
+
+## Measure audible speech
+
+Inspect three different values:
+
+1. the audio container duration;
+2. the first audible spoken sample;
+3. the last audible spoken sample.
+
+Use silence detection as a measurement aid, then associate speech blocks with the known narration paragraphs. Do not assume every detected pause is a paragraph boundary; voices may pause naturally around punctuation or spelled product names.
+
+## Default margins
+
+- Aim for about `0.35 s` of visual lead-in before the first spoken word. A practical range is `0.25–0.50 s` for a short technical video.
+- Aim for `1.5 s` of clean visual post-roll after the last spoken word. A range of `1–2 s` is normally appropriate.
+- Count existing leading or trailing silence in the returned audio toward those margins. Do not add the same cushion twice.
+- Base the final video duration on the last audible speech plus post-roll, not simply on the audio container duration.
+
+Distribute additional visual time across the matching narration beats. Do not hide a duration mismatch by adding one unrelated pause before the command or by holding a source preview longer than its spoken explanation.
+
+Preserve the original narration file. Do not time-stretch it unless the user explicitly requests that treatment. When muxing, do not use `-shortest` if it would cut the final visual margin.
+
+## Align paragraphs as editable blocks
+
+Treat the narration paragraphs and their matching event-log beats as the units of the final edit. A single unedited audio track is acceptable only when those blocks already align naturally.
+
+When they do not:
+
+1. map each approved paragraph to its audible source range and intended visual event;
+2. preserve the original audio file and every spoken sample;
+3. remove only unnecessary silence between confidently identified paragraph boundaries;
+4. position each speech block so its explanation begins with, or slightly anticipates, the corresponding visible action;
+5. extend or trim neutral visual holds where appropriate, distributing corrections across the relevant beats;
+6. retain natural conversational pauses and the configured lead-in and post-roll;
+7. write the source-audio range, final-video range, and matching visual cue into the cue sheet or recording plan.
+
+Never cut based only on generic silence detection. Confirm boundaries against the approved paragraph text, and do not split a spoken sentence or word. If the returned voice merges paragraphs or inserts ambiguous pauses, report the mismatch instead of guessing.

package/skills/technical-demo-videos/references/package-contract.md

@@ -0,0 +1,33 @@
+# Production package contract
+
+Prefer an existing project convention. Otherwise propose `demo-videos/<slug>/` beneath the project root, or an external destination when the source repository should remain untouched. Treat the episode root as the upload handoff: it contains only `<slug>-final.mp4`, `<slug>-subtitles-<language>.srt`, `<slug>-publishing-metadata.md`, and the `production/` subfolder.
+
+## Draft and source files
+
+- `production/recording-plan.md`: human-readable approved story, initial frame, visible actions, proof, timing intent, narration beats, risks, and cleanup.
+- `production/<slug>-recording.json`: machine-readable values and ordered actions when the recorder is data-driven.
+- `production/record-<slug>.py`: permanent entry point for rehearsals, retakes, and recreation.
+- `production/recording_runtime.py`: copied reusable automation primitives, pinned with the package.
+
+The recorder and recipe are source artifacts. A take number never appears in their filenames. Choose the next take number after the highest take already present in `production/`; do not reuse gaps left by rejected or archived takes.
+
+## Capture and delivery files
+
+- `production/<slug>-take-01.mov`: raw capture; increment for a retake and never overwrite.
+- `production/<slug>-take-01-events.json`: actual monotonic timestamps for the matching capture.
+- `production/<slug>-cues.json`: normalized visual and narration intervals for the accepted take.
+- `production/<slug>-narration-<language>.txt`: text sent to the voice generator.
+- `production/` keeps the original returned audio, with its provider filename preserved when useful.
+- `<slug>-subtitles-<language>.srt`: selectable upload-ready captions in the episode root.
+- `<slug>-final.mp4`: synchronized delivery master that passed the YouTube master quality gate; a stream-copied review preview does not qualify.
+- `<slug>-publishing-metadata.md`: copy-ready YouTube, TikTok and Instagram metadata plus upload settings in the episode root.
+
+Use names appropriate to the project when it already has a convention. The essential rule is that each media file can be traced to the recorder version, recipe, and event log that produced it.
+
+## Temporary material
+
+Disposable project copies, compiled click helpers, diagnostic screenshots, extracted frames, split audio blocks, proxy files, and rejected render intermediates are temporary. Create them in a uniquely named temporary directory and remove that exact directory after verification or failure.
+
+Remove caches and Finder metadata such as `__pycache__/` and `.DS_Store` from the episode root before handoff. They are neither publication files nor production sources.
+
+Never delete source projects, accepted takes, user-provided audio, or an existing artifact merely to reuse its filename.

package/skills/technical-demo-videos/references/publishing-metadata.md

@@ -0,0 +1,36 @@
+# Publishing metadata handoff
+
+Read this after a final technical-demo video and external caption file exist, or when the user asks for social-platform metadata.
+
+## Deliverable
+
+Create one upload-ready `<slug>-publishing-metadata.md` in the episode root. The root then contains exactly three regular files:
+
+- `<slug>-final.mp4`
+- `<slug>-subtitles-<language>.srt`
+- `<slug>-publishing-metadata.md`
+
+Keep research notes and intermediate metadata drafts in `production/`, not in the episode root.
+
+## Required document sections
+
+1. **Shared identity:** final filenames, content/original-language setting, primary search phrase, supporting phrases, one-sentence summary, canonical project link, and cover/thumbnail text.
+2. **YouTube:** copy-ready title, description, hashtags, Studio tags, thumbnail copy, pinned comment, playlist/category/language/audience/caption settings, and whether chapters are useful.
+3. **TikTok:** copy-ready organic caption, focused hashtags, cover text, searchable phrases, accessibility setting, and a format warning when the supplied master is not 9:16.
+4. **Instagram Reels:** copy-ready caption, focused hashtags, cover text, searchable phrases, accessibility setting, and the same format warning when relevant.
+5. **Publishing checklist:** verify spelling, links, caption timing, public visibility, cover crop, safe zones, and platform preview before posting.
+
+## Writing rules
+
+- Match the video's language unless the user requests localized variants.
+- Preserve the project's subtitle typography convention independently from pronunciation text. Define a small lexicon in the production plan when product names, acronyms, commands, paths, or URLs need different written and spoken forms. Captions retain canonical spelling; voice-generator input uses only the pronunciation form approved for that provider.
+- Put the primary phrase naturally in the first title/description lines. Do not stuff keywords or paste ordinary tags into prose.
+- Keep hashtags directly relevant. For YouTube, use a small focused set; more than 60 hashtags are ignored. Studio tags mainly help with misspellings, so include product spelling variants there rather than bloating the description.
+- Treat platform-specific copy as separate even when the central message is shared. TikTok and Instagram organic posts use a caption rather than YouTube's separate title and long description.
+- Do not invent social handles, sponsorships, partnerships, locations, playlist IDs, or trending hashtags. Recommend checking current trends immediately before publishing.
+- Do not automatically crop or reframe a horizontal master. State that TikTok and Reels favor vertical 9:16 creative and offer a separate derivative when requested.
+- For short videos whose useful sections cannot meet YouTube chapter requirements, explicitly omit chapters rather than creating misleading timestamps.
+
+## Freshness and sources
+
+Platform behavior and limits are unstable. Browse current official platform documentation whenever generating or materially revising the metadata file. Prefer YouTube Help, TikTok Business/Creative Center, and Meta/Instagram Help or Meta for Business. Link the exact official pages used in a short Sources section inside the metadata document.

package/skills/technical-demo-videos/references/recording-workflow.md

@@ -0,0 +1,40 @@
+# macOS and VS Code recording workflow
+
+Use this reference only when the accepted plan will control VS Code or other Mac applications.
+
+## Preparation
+
+Keep preparation out of the capture unless it is part of the story. Open a uniquely identifiable project window, stabilize its size and position, arrange Explorer/editor/terminal panels, close unrelated tabs, and prepare simulators or devices before starting `screencapture`.
+
+Use [vscode-default-profile.md](vscode-default-profile.md) to define a baseline for the current workstation. Reuse an approved profile across projects instead of experimenting with panel commands or coordinates in each episode. Recalibrate only after a display, VS Code layout, keybinding, or global editor-association change.
+
+On VS Code, use full project-relative paths with Quick Open. Keep terminal commands readable and execute them from the project root without exposing temporary absolute paths. Prefer stable commands and accessibility selectors. When coordinates are unavoidable, store them as configurable logical-display values and validate display/window geometry first.
+
+Choose a dedicated, short copies directory before generating the recorder. Record that choice in the recipe or set `TECHNICAL_DEMO_COPIES_ROOT`; the reusable runtime otherwise uses `~/TechnicalDemos`. Place each disposable project directly beneath it with a short runtime slug such as `build-assets.a1b2c3`. Keep helpers and diagnostic screenshots in a separate system-temp directory. This makes printed absolute paths legible, keeps the Desktop clean, and lets `finally` remove only the current run's resources.
+
+A fresh disposable folder prevents stale project tabs and generated files, but it does not guarantee a fresh panel height: VS Code can inherit non-maximized panel geometry across windows. Detect and verify the actual divider position as described in [vscode-default-profile.md](vscode-default-profile.md); do not treat a hard-coded starting `y` coordinate as part of the profile.
+
+## Safe targeting
+
+Before every AppleScript or UI action block:
+
+1. find the window by the current run's unique slug;
+2. raise that exact window;
+3. make its owning process frontmost;
+4. re-read the front window title;
+5. abort unless it still contains the slug;
+6. only then send the intended action.
+
+Never assume activating an application preserves the correct window. Never paste a generated temporary slug into permanent source; create it at runtime.
+
+## Capture and events
+
+Use macOS `screencapture` for actual video, not a sequence of screenshots. Record `recording_started`, each visual transition, command submission/completion, relevant output, and `recording_stopped` with monotonic timestamps. Wait for observable completion such as a process exit, file creation, simulator state, or expected UI rather than an arbitrary long sleep.
+
+Stop capture cleanly before closing the demonstration window. Close the full project window afterward so the user can see that interaction is finished. Cleanup must target only resources created by the current run.
+
+Afterward, verify only that the expected media/log files exist and the temporary project is gone. Ask the user how the live take looked before spending time or tokens on screenshots, contact sheets, frame-by-frame review, transcription, or narration. Use deeper inspection only to investigate feedback or when the user asks for it.
+
+## User coordination
+
+Before capture, announce with `🎬` in a separate commentary update and ask the user not to touch input devices. Do not surface permission dialogs during the recording; preflight permissions before the announcement. If a permission or login prompt appears unexpectedly, reject the take, stop safely, and explain what must be prepared.

package/skills/technical-demo-videos/references/story-direction.md

@@ -0,0 +1,37 @@
+# Story and direction criteria
+
+Read this when turning a conversational brief into the written proposal or revising a take.
+
+## Build the visual argument
+
+A technical demonstration normally has four movements:
+
+1. **Context:** show the smallest amount of source material needed to understand the task.
+2. **Action:** type and execute the exact approved command or UI operation at a readable pace.
+3. **Proof:** show terminal completion and representative output that substantiates every promise.
+4. **Finish:** hold the clearest result long enough for comprehension and a clean edit.
+
+This is a decision framework, not a forced duration or marketing formula. Omit any movement the user's goal does not need.
+
+## Direct the screen
+
+- Start from a deliberately composed frame, not application-launch clutter.
+- Keep the pointer parked when it is not communicating something.
+- Make text, previews, terminal height, and simulator/device content legible at delivery resolution.
+- Prefer one decisive action over exploratory menu movement.
+- Show representative results rather than every file when repetition adds no proof. Show every platform or output family that narration explicitly claims.
+- Use an observable exit condition for builds and long-running commands. Avoid dramatic pauses or arbitrary sleeps.
+
+## Write for voice
+
+- Give the viewer information they cannot get merely by reading the screen.
+- Keep each line short enough for its measured visual interval.
+- Pronounce command names and symbols naturally for the selected voice service.
+- Preserve the user's approved spelling and pronunciation lexicon across every episode. Do not split an acronym into space-separated letters unless the user explicitly approved that rendering for the selected voice.
+- Do not synchronize final narration against estimated timing. In capture-first mode, exact wording follows the accepted capture and event log. In audio-first mode, approve the exact wording first, measure the returned audio, and use those measurements to lock the visual timing before capture.
+- Use normal punctuation and paragraph breaks for a conversational voice. Do not add synthetic pause tags unless the user explicitly asks for them.
+- Leave captions selectable unless the user asks for burned-in text.
+
+## Edit and review
+
+Reject a take when focus lands in the wrong control, text enters a source file, the command is obscured, proof is missing, a permission dialog appears, or dead time materially harms pacing. Correct the permanent recorder and create a new numbered take. Do not conceal a broken workflow with edits that misrepresent what happened.

package/skills/technical-demo-videos/references/vertical-social-video.md

@@ -0,0 +1,24 @@
+# Vertical and social-media derivatives
+
+Read this only when the user asks for a TikTok, YouTube Shorts, Instagram Reels, or other vertical/social deliverable.
+
+## Preserve a clean master
+
+Keep the approved horizontal capture and clean audio as source masters. Produce vertical framing, split-screen layouts, dynamic captions, and platform-specific safe areas as separate derivatives so one social format never damages the reusable master.
+
+## Choose the composition deliberately
+
+Prefer these approaches in order:
+
+1. record a native `9:16` composition when the workflow can be staged legibly in that space;
+2. build a deterministic split-screen composition for programming demos, such as code/terminal on one half and simulator, game, animation, narrator, or result on the other;
+3. reframe a horizontal master with explicit timed points of interest;
+4. use automatic subject tracking only when the visual target genuinely moves unpredictably.
+
+AI is useful but not inherently required. Deterministic crops can follow recorder events, cursor coordinates, editor focus, simulator bounds, or authored keyframes. AI becomes useful for face/object tracking, automatic highlight selection, transcription, word-level caption timing, speaker detection, and semantic layout decisions.
+
+## Captions and safe areas
+
+Dynamic word- or phrase-level captions are often burned into social derivatives because viewers may watch muted and platforms overlay their own controls. They must remain optional deliverables: keep the clean master and external SRT, then create a separately named captioned vertical version only when requested.
+
+Use the target platform's current resolution, duration, and safe-area rules at production time; verify those rules from official platform documentation because they can change.

package/skills/technical-demo-videos/references/vscode-default-profile.md

@@ -0,0 +1,49 @@
+# VS Code recording profile
+
+Use this reference to calibrate a workstation once, save the accepted values with the production package, and reuse them across projects and retakes. The numbers below are an example profile for a 4K display, not universal defaults.
+
+## Values the profile owns
+
+- capture display number and physical resolution;
+- logical display size and minimum VS Code window size;
+- whether an auxiliary panel must be hidden and the shortcut that does it;
+- whether Explorer remains visible and on which side;
+- whether Welcome is disabled before recording;
+- terminal divider detection range, drag coordinate, target height, and tolerance;
+- terminal focus shortcut after an editor takes focus;
+- file-preview associations needed by the demonstration.
+
+Keep these values in the declarative recipe or pass an equivalent profile to `prepare_default_vscode()`. Do not spread coordinates and shortcuts across project-specific action code.
+
+## Example 4K profile
+
+- Physical capture: 3840 × 2160.
+- Logical display: 1920 × 1080.
+- VS Code minimum: 1850 × 1000 logical points.
+- Terminal divider drag: logical `x=645` to `y=720`, verified within 8 points.
+- Terminal open delay: about 1.5 seconds before divider detection.
+- Main Explorer remains visible; unrelated auxiliary panels and Welcome are removed before capture.
+
+Recalibrate those values for a different display, scaling mode, VS Code layout, keybinding, or panel placement.
+
+## Integrated terminal preparation
+
+1. Open a uniquely identifiable disposable project in a new VS Code window.
+2. Apply the profile's panel state and close unrelated tabs before capture.
+3. Use `Terminal` → `New Terminal` after targeting that exact window.
+4. Wait for the panel to finish opening.
+5. Capture a temporary screenshot and detect the real horizontal divider across several columns. A fresh folder does not guarantee a fresh panel height.
+6. Drag the detected separator to the profile's target height.
+7. Capture the layout again and verify the divider is within the configured tolerance. Abort before recording if detection fails; never guess the starting coordinate.
+8. Store diagnostics under the run's temporary helper directory so cleanup removes them.
+9. Leave the terminal open when preparation finishes.
+
+Do not resize with repeated Command Palette steps: they are slower, visible, and dependent on unknown starting height. Do not send the terminal-focus shortcut immediately after creating the terminal because a toggle-style binding may close it. Use it later, after an editor or preview has taken focus and immediately before typing the command.
+
+## Preview behavior
+
+If a source format needs a visual preview, configure and preflight the VS Code association before capture. Open the file directly into that preview during the take. Do not expose the editor-selection menu or change a user setting inside the demonstrated project merely for recording.
+
+## Recording boundary
+
+All profile preparation happens before capture. The first recorded action belongs to the approved story. Save a newly accepted profile instead of rediscovering the same coordinates during every episode.

package/skills/technical-demo-videos/references/youtube-master.md

@@ -0,0 +1,42 @@
+# YouTube master quality gate
+
+Read this before promoting an approved edit to `<slug>-final.mp4` or creating
+its YouTube upload manifest.
+
+An MP4 can report 3840×2160 and still be a poor delivery master. Do not treat
+resolution or successful muxing as sufficient. A stream-copied synchronization
+preview remains a preview.
+
+For horizontal 4K screen demonstrations using an approved capture profile, create
+the final upload master with:
+
+- MP4, H.264 High Profile, progressive, yuv420p;
+- 3840×2160 with no baked-in letterboxing;
+- constant 30 FPS unless the approved content genuinely needs its native 60 FPS;
+- BT.709 primaries, transfer, and matrix metadata;
+- AAC stereo audio at 48 kHz and 384 kbps;
+- the moov atom at the front (`faststart`);
+- a deliberate variable bitrate. The bundled helper uses the lower edge of
+  YouTube's current SDR upload ranges: 35 Mbps for 4K at 24–30 FPS and 53 Mbps
+  for 4K at 48–60 FPS. It also selects the documented standard/high-frame-rate
+  defaults for 1440p, 1080p, and 720p.
+
+These bitrate and codec recommendations can change. Before creating a delivery
+master, verify them against YouTube's current official
+[recommended upload encoding settings](https://support.google.com/youtube/answer/1722171).
+If the published range changed, pass its lower bound with `--video-bitrate` and
+record the source and chosen value in the production plan.
+
+Run:
+
+```bash
+python3 scripts/normalize_youtube_master.py APPROVED_EDIT.mp4 FINAL.mp4
+```
+
+The tool refuses to overwrite the output and verifies resolution, CFR, codec,
+profile, pixel format, BT.709, audio, container, and bitrate before completing.
+Do not create an upload manifest when this gate fails.
+
+After upload, keep the video private until the intended high-resolution
+representations are actually available. YouTube chooses the playback codecs;
+the upload API cannot request AVC, VP9, or AV1 and offers no reprocess action.