Record Browser GIF

Produce a short, truthful Orbit UI demonstration as a local GIF. Use the browser-control skill for interaction and the bundled encoder for repeatable timing, dimensions, and size. This skill is the canonical project workflow; do not copy a second full version into a host-specific directory.

Recording integrity

• Record from the real Orbit server and the real UI path that the GIF claims to demonstrate. Do not substitute fixture requests, mock transports, synthetic event injection, or test-only hooks unless the user explicitly requests a fixture recording.
• Use a benign demonstration prompt. Never expose API keys, login state, personal data, unrelated tabs, or private workspace paths in a frame.
• Keep one storyboard in one isolated run. Do not splice frames from different servers, browser profiles, workspaces, or model rounds.
• If the recording supports a pull request claim, record the exact commit with git rev-parse HEAD and state that commit beside the embedded GIF.
• If credentials, a supported runtime, or the server are unavailable, report the limitation instead of presenting a fixture as a real run.

Stage Orbit

1. Read the root AGENTS.md and the relevant product docs. For the current collaboration demo, read docs/ARCHITECTURE.md and docs/TERMINOLOGY_AND_ROUTING.md.
2. For a pull-request recording, require a clean worktree and record the exact commit before building. For a README or documentation recording, record the current branch and note that provenance in the handoff.

3. Build the UI from that tree:

   npm run build

   The build requires Bun because it compiles the standalone executable. The source server itself runs with Node and the repository's npm scripts.

4. Start Orbit with npm run dev and use http://localhost:4317, or set ORBIT_PORT to an available port. Keep one server for the whole storyboard.
5. Use a fresh browser context or clear only the demo origin's storage before navigation. Orbit stores product data under ~/.orbit; do not delete or overwrite a user's existing data to create a clean recording. Use a dedicated demo workspace and remove only artifacts created for the recording when cleanup is explicitly safe.
6. Stop the exact server process after capture. Do not use a broad process-kill pattern that could terminate the shell or another Orbit instance.

Record the story

1. Invoke the available browser-control skill. If it is unavailable, use the repository's existing Playwright dependency in an isolated browser; do not install another driver or launch the user's browser unless requested.
2. Before recording, identify the origin, built/development mode, runtime, transport, and whether the run is real or fixture-backed. State exceptions in the final provenance.
3. Choose three to six semantic states that tell one story. A useful Orbit README storyboard is: workspace and team visible, assignment typed, employee running, handoff or verification visible, and final settled result.
4. Keep one viewport and crop for every frame. Write frames under the ignored .playwright-mcp/gif-frames-<label>/ directory and name them lexically: 00-initial.png, 01-assigned.png, 02-running.png, and so on.
5. Before each screenshot, wait for a concrete UI condition such as a unique label, an enabled control, a changed heading, a visible run state, or an exact final reply. Do not use a fixed delay as proof that the UI reached a state.
6. When checking completion, match an exact-text element rather than a broad body.textContent.includes(...) check, which can match the echoed prompt.
7. When the claim involves approval, tool activity, handoff, failure, or recovery, include a frame that visibly proves that state. A final chat reply alone does not prove the preceding path.
8. Capture transient states by driving a real foreground operation and polling a concrete DOM marker in the same browser-script call that takes the screenshot. Stop unnecessarily long real-model runs once the demonstrated state is visible.

Use the browser's screenshot API and save the returned image bytes directly.

Encode the GIF

Require python3 or python, ffmpeg, and ffprobe. If a required media binary is missing, report it instead of installing software without approval.

On PowerShell:

$gifSkillDir = (Resolve-Path ".agents/skills/record-browser-gif").Path
python "$gifSkillDir/scripts/encode_gif.py" `
  "$(Resolve-Path '.playwright-mcp/gif-frames-<label>')" `
  "$(Resolve-Path '.playwright-mcp')/orbit-demo.gif" `
  --durations 1.5,1.5,1.5,3.5 `
  --fps 10 `
  --max-width 1200 `
  --colors 128

On a POSIX shell, export the skill directory before invoking Python:

export GIF_SKILL_DIR="$PWD/.agents/skills/record-browser-gif"
python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
  "$PWD/.playwright-mcp/gif-frames-<label>" \
  "$PWD/.playwright-mcp/orbit-demo.gif" \
  --durations 1.5,1.5,1.5,3.5 \
  --fps 10 \
  --max-width 1200 \
  --colors 128

Provide one positive duration per frame, holding the final state longest. The encoder rejects fewer than two frames, mismatched dimensions or durations, invalid limits, accidental overwrite, unexpected duration, and oversized output. Reduce --max-width first when text is still readable; then reduce colors or FPS. Use --force only after checking the exact output path.

Verify the artifact

1. Read the encoder's JSON summary. Confirm output path, source and encoded frame counts, dimensions, duration, and byte size.
2. Inspect the encoded GIF itself, not only the source screenshots. Confirm that transitions are legible, the final state is held long enough, and no private data appears. Decode representative frames with ffmpeg if the viewer only exposes the first frame.
3. Run git status --short and confirm frames and the GIF are under ignored paths unless the user explicitly requested publication.
4. Return the absolute GIF path and state whether it used a real ACP/model run, a fixture, or another transport. Render the local GIF when the client supports local media.

Publish for README or pull-request use

Only publish when the user explicitly asks for a GitHub-visible README or pull-request asset. Prefer a dedicated assets branch such as orbit-assets so the product branch does not accumulate binary history. Verify that the branch contains media only and that the remote checksum matches the verified local GIF.

Embed a published GIF with a raw blob URL:

![Orbit multi-agent collaboration demo](https://github.com/<owner>/<repo>/blob/orbit-assets/orbit-demo.gif?raw=true)

For a pull request, record the demonstrated commit SHA, server origin, runtime, browser-state exception if any, and whether a real model round ran next to the GIF. Re-read the live pull-request head before and after editing its body; if it moved, re-record. Never force-push or rewrite an assets branch.