reshoot 0.3.0__py3-none-any.whl

reshoot/__init__.py

@@ -0,0 +1 @@
+"""Demo videos of software, made from scripts so you can shoot them again when the app changes."""

reshoot/artifacts.py

@@ -0,0 +1,55 @@
+"""Small file-based run helpers; captured JPEG bytes stay on disk."""
+import hashlib
+import json
+import tempfile
+from pathlib import Path
+
+
+class Frames:
+    def __init__(self):
+        self.temp = tempfile.TemporaryDirectory(prefix='reshoot-capture-')
+        self.records = []
+
+    def append(self, frame):
+        at, data = frame
+        path = None
+        if data is not None:
+            path = Path(self.temp.name) / f'{len(self.records):08}.jpg'
+            path.write_bytes(data)
+        self.records.append((at, path))
+
+    def __len__(self):
+        return len(self.records)
+
+    def __getitem__(self, key):
+        if isinstance(key, slice):
+            return (self[i] for i in range(*key.indices(len(self))))
+        at, path = self.records[key]
+        return at, path.read_bytes() if path else None
+
+    def __iter__(self):
+        return (self[i] for i in range(len(self)))
+
+    def without_end(self):
+        view = object.__new__(Frames)
+        view.temp = self.temp
+        view.records = [(at, path) for at, path in self.records if path is not None]
+        return view
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.temp.cleanup()
+
+
+def images(frames):
+    return frames.without_end() if isinstance(frames, Frames) else [f for f in frames if f[1] is not None]
+
+
+def digest(path):
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b''):
+            h.update(chunk)
+    return h.hexdigest()

reshoot/browser.py

@@ -0,0 +1,280 @@
+"""Native-input Chromium driver for TOML storyboards. The overlay only draws."""
+import asyncio
+import base64
+import json
+import os
+import time
+from pathlib import Path
+from reshoot import story, web, zoom
+from reshoot.artifacts import Frames, digest
+from reshoot.safety import redact
+
+
+def locator(page, spec):
+    scope = page.frame_locator(spec['frame']) if 'frame' in spec else page
+    if 'test_id' in spec:
+        return scope.get_by_test_id(spec['test_id'])
+    if 'role' in spec:
+        return scope.get_by_role(spec['role'], **({'name': spec['name'], 'exact': True} if 'name' in spec else {}))
+    item = scope.locator(spec['css'])
+    if 'text' in spec:
+        import re
+        item = item.filter(has_text=re.compile('^' + re.escape(spec['text']) + '$'))
+    return item
+
+
+async def action(page, entry, events, root):
+    kind = entry['type']
+    timeout = entry.get('timeout', 10000)
+    if kind == 'navigate':
+        await page.goto(entry['url'], timeout=timeout)
+        return
+    if kind == 'scroll':
+        await page.mouse.wheel(0, entry.get('dy', 300))
+        await page.wait_for_timeout(400)
+        return
+    item = locator(page, entry['target'])
+    if kind == 'wait':
+        await item.wait_for(state='visible', timeout=timeout)
+        return
+    if await item.count() != 1:
+        raise ValueError('action target must match exactly one element')
+    await item.scroll_into_view_if_needed(timeout=timeout)
+    box = await item.bounding_box()
+    rect = [box[k] for k in ('x', 'y', 'width', 'height')] if box else None
+    events.append((time.monotonic(), {'kind': 'act', 'phase': 'start', 'rect': rect}))
+    if box:
+        await page.evaluate('p => __demo.moveTo(p[0], p[1], 350)', [box['x'] + box['width']/2, box['y'] + box['height']/2])
+    if kind == 'click':
+        await item.click(timeout=timeout)
+    elif kind == 'type':
+        await item.click(timeout=timeout)
+        if entry.get('clear', True):
+            await item.fill('', timeout=timeout)
+        await item.press_sequentially(entry['text'], delay=65, timeout=timeout)
+    elif kind == 'key':
+        await item.press(entry['key'], timeout=timeout)
+    elif kind == 'upload':
+        await item.set_input_files(str((root / entry['file']).resolve()), timeout=timeout)
+    events.append((time.monotonic(), {'kind': 'act', 'phase': 'end', 'rect': rect}))
+
+
+async def assertion(page, entry):
+    from playwright.async_api import expect
+    kind = entry['type']
+    timeout = entry.get('timeout', 10000)
+    if kind == 'url':
+        import re
+        await expect(page).to_have_url(re.compile(re.escape(entry['contains'])), timeout=timeout)
+        return page.url
+    item = locator(page, entry['target'])
+    if kind == 'count':
+        await expect(item).to_have_count(entry['count'], timeout=timeout)
+        return await item.count()
+    await expect(item).to_be_visible(timeout=timeout)
+    if kind == 'text':
+        await expect(item).to_contain_text(entry['contains'], timeout=timeout)
+        return await item.inner_text()
+    if kind == 'value':
+        await expect(item).to_have_value(entry['value'], timeout=timeout)
+        return await item.input_value()
+    if kind == 'checked':
+        await expect(item).to_be_checked(checked=entry.get('checked', True), timeout=timeout)
+        return await item.is_checked()
+    return True
+
+
+async def capture(board, a, frames, out, metadata, spoken):
+    from playwright.async_api import async_playwright
+    w, h, dpr = web.parse_size(a.size or board.get('size', '1280x720@1'))
+    if os.environ.get('RESHOOT_PREVIEW') == '1':
+        dpr = min(dpr, 720 / max(w, h))
+    z = zoom.settings(a.zoom if a.zoom is not None else board.get('zoom'))
+    if board.get('caption'):
+        z = z or {**zoom.DEFAULTS, 'scale': 1, 'watch': False}
+        style = dict(board['caption'])
+        if style.get('font'):
+            style['font'] = str(Path(a.storyboard).resolve().parent / style['font'])
+        z['caption_style'] = style
+    cap_dpr = min(dpr * min(z['scale'], 2), 4) if z else dpr
+    first = getattr(a, 'from_beat', None) or os.environ.get('RESHOOT_FROM_BEAT')
+    ids = [b['id'] for b in board['beat']]
+    metadata['mode'] = 'partial' if first else 'preview' if os.environ.get('RESHOOT_PREVIEW') else 'final'
+    if first and first not in ids:
+        raise ValueError('unknown starting beat')
+    split = ids.index(first) if first else 0
+    events, beats, pending, assets, resources = [], {}, [], [], []
+    clock = None
+    root = Path(a.storyboard).resolve().parent
+    async with async_playwright() as pw:
+        browser = await pw.chromium.launch(executable_path=web.find_chrome(), headless=True, args=web.chrome_flags())
+        context = await browser.new_context(viewport={'width': w, 'height': h}, device_scale_factor=cap_dpr,
+                                            color_scheme=a.theme or board.get('theme', 'dark'), locale='en-US', timezone_id='UTC',
+                                            is_mobile=bool(a.mobile or board.get('mobile')), has_touch=bool(a.mobile or board.get('mobile')))
+        page = await context.new_page()
+        metadata['browser'] = browser.version
+        errors = []
+        page.on('pageerror', lambda e: errors.append(redact(str(e))))
+        await page.expose_binding('__reshoot', lambda source, payload: events.append((time.monotonic(), json.loads(payload))))
+        await page.add_init_script('window.__reshootPostCaptions = ' + json.dumps(bool(z)) + '; window.__reshootBlur = ' + json.dumps(board.get('blur', [])) + '; window.__reshootSeed = ' + str(board.get('seed', 1)) + ';')
+        await page.add_init_script((web.HERE / 'overlay.js').read_text())
+        asset_folder = out.with_suffix('.resources')
+        asset_folder.mkdir(exist_ok=True)
+        async def save_resource(response):
+            if response.request.resource_type not in ('image', 'media'):
+                return
+            from reshoot.safety import describe
+            record = {'source': describe(response.url), 'status': 'unavailable'}
+            try:
+                data = await response.body()
+                import hashlib
+                name = hashlib.sha256(data).hexdigest()
+                target = asset_folder / name
+                target.write_bytes(data)
+                record.update(status='saved', file=str(target.relative_to(out.parent)), sha256=name, content_type=response.headers.get('content-type', ''))
+                if response.request.resource_type == 'image':
+                    from reshoot.check import open_image
+                    if open_image(data) is not None:
+                        assets.append(str(target))
+                    else:
+                        record['status'] = 'unsupported'
+            except Exception:
+                pass
+            resources.append(record)
+        resource_handler = lambda response: pending.append(asyncio.create_task(save_resource(response)))
+        page.on('response', resource_handler)
+        cdp = await context.new_cdp_session(page)
+        # Playwright's virtual viewport can exceed Chrome's visible capture surface.
+        # CDP screencasting needs both sizes, rather than stretching a clipped frame.
+        await cdp.send('Emulation.setDeviceMetricsOverride', {'width': w, 'height': h, 'deviceScaleFactor': cap_dpr,
+                       'mobile': bool(a.mobile or board.get('mobile')), 'screenWidth': w, 'screenHeight': h,
+                       'dontSetVisibleSize': False})
+        async def frame(event):
+            nonlocal clock
+            timestamp = event['metadata']['timestamp']
+            if clock is None:
+                clock = time.monotonic() - timestamp
+            frames.append((timestamp + clock, base64.b64decode(event['data'])))
+            await cdp.send('Page.screencastFrameAck', {'sessionId': event['sessionId']})
+        frame_tasks = []
+        frame_handler = lambda event: frame_tasks.append(asyncio.create_task(frame(event)))
+        cdp.on('Page.screencastFrame', frame_handler)
+        current = None
+        try:
+            await page.goto(a.url or board.get('url', 'http://localhost:8000/'), wait_until='load', timeout=30000)
+            await page.evaluate('document.fonts.ready')
+            for entry in board.get('setup', []):
+                await action(page, entry, events, root)
+            for previous in board['beat'][:split]:
+                for entry in previous.get('action', []):
+                    await action(page, entry, events, root)
+                for entry in previous.get('expect', []):
+                    await assertion(page, entry)
+            metadata['replayed_before'] = ids[:split]
+            events.clear()
+            await cdp.send('Page.startScreencast', {'format': 'jpeg', 'quality': 92, 'maxWidth': int(w*cap_dpr), 'maxHeight': int(h*cap_dpr)})
+            for beat in board['beat'][split:]:
+                current = beat['id']
+                start = beats[current] = time.monotonic()
+                result = {'id': current, 'purpose': beat.get('purpose'), 'caption': beat.get('caption'),
+                          'definition_sha256': __import__('hashlib').sha256(json.dumps(beat, sort_keys=True).encode()).hexdigest(),
+                          'status': 'running', 'expectations': []}
+                metadata['beats'].append(result)
+                await page.evaluate('p => __demo.caption(p[0], p[1])', [beat.get('caption'), beat.get('sub')])
+                for entry in beat.get('action', []):
+                    await action(page, entry, events, root)
+                for entry in beat.get('expect', []):
+                    try:
+                        actual = await assertion(page, entry)
+                    except Exception as error:
+                        result['expectations'].append({'type': entry['type'], 'status': 'failed', 'error': redact(str(error))})
+                        raise
+                    result['expectations'].append({'type': entry['type'], 'status': 'passed', 'actual': redact(str(actual)), 'at': time.monotonic()})
+                if errors:
+                    raise RuntimeError('page error: ' + '; '.join(errors))
+                result.update(verified_at=time.monotonic(), trim_wait=bool(beat.get('trim_wait')), min_reading=max(beat.get('min_reading', 0), board.get('caption', {}).get('min_seconds', 0)))
+                shot = out.parent / (out.stem + '.evidence') / (current + '.png')
+                shot.parent.mkdir(exist_ok=True)
+                await page.screenshot(path=str(shot))
+                result.update(status='passed' if beat.get('expect') else 'unverified', screenshot=str(shot.relative_to(out.parent)), start=start)
+                await asyncio.sleep(max(beat.get('hold', 1), beat.get('min_reading', 0), board.get('caption', {}).get('min_seconds', 0) if beat.get('caption') else 0, spoken.get(current, ('', 0))[1] + .3 - (time.monotonic() - start)))
+                result['end'] = time.monotonic()
+            stop = time.monotonic()
+            await cdp.send('Page.stopScreencast')
+            cdp.remove_listener('Page.screencastFrame', frame_handler)
+            page.remove_listener('response', resource_handler)
+            if frame_tasks:
+                await asyncio.gather(*frame_tasks)
+            frames.append((stop, None))
+            if pending:
+                await asyncio.gather(*pending)
+            if errors:
+                raise RuntimeError('page error: ' + '; '.join(errors))
+            metadata['status'] = 'completed'
+        except Exception as e:
+            if metadata['beats']:
+                metadata['beats'][-1]['status'] = 'failed'
+            failure = out.with_suffix('.failure.png')
+            try:
+                await page.screenshot(path=str(failure))
+                metadata['failure_screenshot'] = str(failure.relative_to(out.parent))
+            except Exception:
+                pass
+            raise RuntimeError(f'beat {current!r} failed: {redact(str(e))}') from None
+        finally:
+            cdp.remove_listener('Page.screencastFrame', frame_handler)
+            page.remove_listener('response', resource_handler)
+            if frame_tasks:
+                await asyncio.gather(*frame_tasks, return_exceptions=True)
+            if pending:
+                await asyncio.gather(*pending, return_exceptions=True)
+            await context.close()
+            await browser.close()
+            metadata['resources'] = resources
+    if not len(frames):
+        raise ValueError('no frames captured')
+    t0 = frames[0][0]
+    for result in metadata['beats']:
+        for key in ('start', 'end', 'verified_at'):
+            if key in result:
+                result[key] = max(0, result[key] - t0)
+        for check in result['expectations']:
+            check['at'] = max(0, check['at'] - t0)
+    times = [t for t, _ in frames]
+    metadata['capture'] = {'css_width': w, 'css_height': h, 'pixel_ratio': cap_dpr,
+                           'frames': len(frames)-1, 'max_gap_seconds': max((b-a for a,b in zip(times,times[1:])), default=0), 'seed': board.get('seed', 1), 'locale': 'en-US', 'timezone': 'UTC',
+                           'theme': a.theme or board.get('theme', 'dark'), 'mobile': bool(a.mobile or board.get('mobile'))}
+    metadata['events'] = [{'t': max(0, t-t0), **event} for t, event in events]
+    out.with_suffix('.beats.json').write_text(json.dumps({name: max(0, at-t0) for name, at in beats.items()}, indent=2))
+    out.with_suffix('.events.json').write_text(json.dumps(metadata['events'], indent=2))
+    out.with_suffix('.assets.json').write_text(json.dumps(sorted(set(assets)), indent=2))
+    out.with_suffix('.voice.json').unlink(missing_ok=True)
+    if spoken:
+        spoken = {name: line for name, line in spoken.items() if name in beats}
+        out.with_suffix('.voice.json').write_text(json.dumps([{'beat': name, 't': max(0, beats[name]-t0), 'file': f, 'seconds': seconds, 'text': board['voice'][name]} for name, (f, seconds) in spoken.items()], indent=2))
+    temp = out.with_name(out.stem + '.partial.mp4')
+    if z:
+        zoom.render(frames, events, temp, w, h, int(w*dpr)//2*2, int(h*dpr)//2*2, z)
+    else:
+        web.encode(frames, temp, size=f'{int(w*dpr)//2*2}:{int(h*dpr)//2*2}')
+    temp.replace(out)
+    metadata['sha256'] = digest(out)
+
+
+def main(a):
+    board = story.load(a.storyboard)
+    web.parse_size(a.size or board.get('size', '1280x720@1'))
+    out = Path(a.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    metadata = {'schema_version': 1, 'video': out.name, 'status': 'failed', 'story_id': board.get('id', Path(a.storyboard).stem), 'story_sha256': digest(a.storyboard), 'beats': []}
+    from reshoot.voice import prepare
+    spoken = prepare(board['voice'], os.environ.get('RESHOOT_VOICE_CACHE', out.with_suffix('.voice')), board.get('voice_engine')) if board.get('voice') else {}
+    try:
+        with Frames() as frames:
+            asyncio.run(asyncio.wait_for(capture(board, a, frames, out, metadata, spoken), board.get('timeout', 600)))
+    except (Exception, KeyboardInterrupt) as e:
+        metadata['error'] = redact(str(e)) or type(e).__name__
+        raise ValueError(metadata['error']) from None
+    finally:
+        out.with_suffix('.take.json').write_text(json.dumps(metadata, indent=2))
+    print('wrote', out)

reshoot/bundled_skills/README.md

@@ -0,0 +1,98 @@
+# Skills for repeatable demo videos
+
+Give a coding agent the workflow for making a demo, updating it when the app
+changes, and checking the result before sharing. Reshoot's skills guide the
+agent through the work; the reshoot CLI records and edits the media.
+
+For a first video, use the [agent quickstart](../guide/agent-quickstart.md).
+Paste its prompt into Codex or Claude Code in your app repository or a demo work
+folder and let the agent handle setup. Supply source code, a running URL or an
+installed macOS app with a demo window. Source code is optional.
+
+## Start with three skills
+
+| Skill | Use it to | Supply |
+|---|---|---|
+| [reshoot-demo](reshoot-demo/SKILL.md) | Choose the capture route, make a first clip, inspect a test take and prepare final exports | App source, a web URL or a native macOS app; the task to show |
+| [reshoot-refresh](reshoot-refresh/SKILL.md) | Record an existing task again after an app change and compare the result | Configuration and exact previous run, or native recipe and previous media |
+| [reshoot-review](reshoot-review/SKILL.md) | Inspect exports, expected results, readability, scan coverage and comparisons | Current and optional previous run, or standalone media and check reports |
+
+Invoke the skill with the task in the same message. For example, in Codex:
+
+```text
+$reshoot-demo
+Show adding an issue and finding it by its label. Use synthetic demo data.
+Create a short captioned MP4 and a README GIF for this app.
+```
+
+In Claude Code, use `/reshoot-demo`. For the plugin, use
+`/reshoot:reshoot-demo`. Apply the same prefix convention to refresh and review.
+
+## Install the package
+
+Install the [CLI and platform dependencies](../guide/install.md), then choose
+one route:
+
+| Route | Installation | Included skills |
+|---|---|---|
+| Codex, project-local | Run `reshoot skills codex --directory .` in the app or demo folder | Three primary skills in `.agents/skills/` |
+| Claude Code, project-local | Run `reshoot skills claude --directory .` in the app or demo folder | Three primary skills in `.claude/skills/` |
+| Claude Code plugin | Run the two commands below inside Claude Code | All ten skills |
+
+```text
+/plugin marketplace add mumit/reshoot
+/plugin install reshoot@reshoot
+```
+
+Follow Claude Code's installation and reload prompts. The plugin uses namespaced
+invocations such as `/reshoot:reshoot-demo`. The skills need the CLI and recording
+tools for every route. See [setup and discovery](../guide/agent-quickstart.md#install-the-skills-yourself).
+
+The CLI bundles the same primary skill source used by the plugin. It refuses
+to overwrite existing project skills. Upgrading the CLI does not update those
+copies; preserve local edits and compare a new bundle before replacing them.
+
+## Use the supporting skills
+
+The plugin also includes focused workflows for individual parts of a shoot:
+
+| Skill | Purpose |
+|---|---|
+| [plan-demo](plan-demo/SKILL.md) | Choose the story, result, captions and recording format |
+| [record-web](record-web/SKILL.md) | Record a browser page from a storyboard |
+| [record-terminal](record-terminal/SKILL.md) | Record a CLI or agent with VHS |
+| [record-window](record-window/SKILL.md) | Record one macOS app window |
+| [check-privacy](check-privacy/SKILL.md) | Generate and inspect scan sheets and findings |
+| [cut-video](cut-video/SKILL.md) | Edit takes and produce finished exports |
+| [keep-current](keep-current/SKILL.md) | Run a shoot from configuration or prepare CI recording |
+
+Use the primary skills for a complete first demo or update. Use a supporting
+skill when working on that part separately. The three-skill CLI installer does
+not install these seven supporting skills.
+
+The three primary skills cover all three starting points without requiring the
+supporting bundle. Browser stories support captions and explicit result checks.
+Native takes require app-specific automation or manual interaction, standalone
+editing and manual comparison; browser overlays and assertions do not apply.
+
+After the first clip, [explore features](../guide/features.md),
+[customize the source](../guide/customize.md), [build a fuller tutorial](../guide/make-demo.md)
+or [maintain and publish](../guide/publish.md).
+
+## Keep the review with the recording
+
+The agent can prepare a story, run commands, inspect outputs and explain
+findings. The owner watches the final exports and decides whether the recording
+and scan sheets are acceptable. A successful command or clean scan does not
+make that decision.
+
+Use synthetic demo data and page, terminal or single-window capture. Retain
+the previous run for a refresh. Keep publication and repository changes within
+the owner's authorization.
+
+## Extend a workflow
+
+Keep shared skill source in this directory. The wheel packages it and the CLI
+copies the primary skills into each harness's project location. Follow the
+[contribution guide](../CONTRIBUTING.md#add-a-skill) when adding a skill or fixing
+a recording pitfall.

reshoot/bundled_skills/check-privacy/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: check-privacy
+description: Check everything a demo video's takes can show (images the page loaded, frames of each take, anything picked at random) by eye on numbered contact sheets with `reshoot check`, before anything is cut or shared. Use after recording and before cutting or posting.
+---
+
+# Check a take for private things
+
+Every image a take can show is looked at by a person, at full size, before the video is cut. This is the step that
+keeps a face, a name or a house number out of a public video.
+
+## Steps
+
+1. Make sheets of everything not checked yet:
+
+   ```bash
+   reshoot check takes/web.assets.json takes/web.mp4 takes/cli.mp4 --review takes/review
+   ```
+
+   Add `--watch-for "Acme,Jane Roe"` (or `--watch-for @words.txt`) with anything of the person's that mustn't
+   show: their name, company, street, customers. Sources can be `.assets.json` lists, videos (a frame every
+   `--every` seconds, default 3), image files, folders and URLs. The app must still be running, since the assets list holds its URLs. Add anything the app could pick at
+   random during a take (suggestions, featured items, a shuffled gallery): the whole set, not only what this take
+   showed.
+2. Start with what the scan flagged. It reads the text in supplied images and sampled frames, and flags emails, phone numbers,
+   keys and tokens, file paths with a user name, street addresses and the watch-for words. On macOS it also finds
+   faces and people. Flagged images come first, with a red label and a red box round each find, and are listed
+   with what was found masked (`jane•••`), so nothing private lands in a log.
+3. Look at every sheet (`takes/review/01.jpg` and on) at full size, flagged or not. The scan misses things: text in
+   pictures, small or odd fonts, and anything it has no rule for. You may look too, but the person decides. Show
+   them the sheets.
+4. For any that fail: `reshoot check --review takes/review --fail 3-2 7-1`. It lists where each came from. Take those
+   out of the demo data, then record the take again, since the take still shows them.
+5. When the rest pass: `reshoot check --review takes/review --ok`. Passed images are remembered by a hash of their
+   bytes, so the next round shows only what's new.
+6. Repeat until `reshoot check` says everything has been checked.
+
+## What fails an image
+
+- A person: faces, heads at the edge of the frame, tiny figures far away, reflections in glass, people behind
+  windows.
+- Personal details: names, emails, phone numbers, addresses, number plates, house numbers, documents.
+- Secrets: keys, tokens, passwords, URLs with tokens in them.
+- Work details: customers, colleagues, internal tools, unreleased features, private repo names.
+- The computer itself: user names, file paths, other apps, browser tabs, bookmarks, notifications.
+
+When in doubt, it fails. In a photo app's demo, a first check missed a straw hat at the edge of a frame, a
+silhouette in a mesh railing and a blurred head in the background.
+
+## Pitfalls
+
+- **Random picks.** A view that picks at random shows different things in each take. Check its whole pool, or check
+  every take.
+- **Deleting doesn't fix the take.** After removing a failed image from the demo data, record again.
+- **Thumbnails hide things.** A small head at the edge only shows at full size. The sheets use up to 1000 px.
+- **Text in the app.** The assets list covers images. Frames from the video cover everything else, so include the
+  takes themselves.
+- **A clean scan isn't a pass.** Only `--ok` marks images as checked, and only after a person has looked.
+- **Something private that has to stay in the app:** blur it during the take with `BLUR` or `__demo.blur(sel)`
+  (record-web), rather than taking it out of the demo data.
+- **No scan here.** On Linux, text needs Tesseract (`apt install tesseract-ocr`), and faces and people need macOS.
+  `reshoot check` says when part of the scan is off. Look extra closely then.
+
+## Check status
+
+`check` exits 0 when the supplied review items are accepted, 1 when human review is pending, and 2 on a check error. Read `report.json` in the review folder. A missing input or unavailable required text detector is an error, never a pass. Video frames are sampled every three seconds by default; unsampled frames are not covered. `--no-scan` explicitly skips automatic detection and still requires human review.
+
+Use `--full` to inspect every decoded video or GIF frame, including brief content. This is slower than the default sampled mode. Original frames are saved in `REVIEW_DIR/originals/`. Scan completion describes coverage, not a guarantee of finding every private detail. Changing scan settings or watch words requires a fresh scan.
+
+`--ocr tesseract` or `[check] ocr = "tesseract"` selects text-only OCR explicitly when Vision cannot run. `RESHOOT_OCR` sets the default. Backend failures do not silently fall back; read the reported detector coverage, including unavailable face detection.
+
+`check --text-file FINAL.srt` scans exact caption text. Runs also check generated
+subtitle and narration sidecars. Inspect text findings at their recorded cue times.

reshoot/bundled_skills/cut-video/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: cut-video
+description: "Cut checked takes into a finished demo video with ffmpeg and the `reshoot.cut` helpers: trims at beat names, title and end cards, sped-up parts, a 9:16 version for phones, and one GIF per section. Use after the takes are recorded and checked."
+---
+
+# Cut the video
+
+Each project has a short edit script, since the order of takes and the words on screen differ. Start from
+`../../examples/notes/edit.py` (from this skill's folder) and copy it into the project. It joins a web take, a
+terminal take on a labeled card, and an end card. Run it with `reshoot edit tools/demo/edit.py
+takes/web.mp4`, which makes `reshoot.cut` importable even when reshoot is installed as a tool.
+
+## The helpers
+
+```python
+from reshoot import cut
+
+b = cut.beats("takes/web.mp4")                         # {beat name: seconds}
+cut.trim(src, start, end, out, fade_in=0, fade_out=0.4)
+cut.speed(src, start, end, 8, out)                     # 8x as fast
+cut.still(png, 3, out)                                 # an image held 3 s, faded in
+cut.place(bg_png, src, x, y, out, width=None)          # a video placed on a background
+cut.vertical(src, bg_png, out)                         # 9:16, the video across the middle
+cut.concat([a, b, c], out)                             # joined without encoding again
+cut.gif(src, start, end, out, fps=15, width=800)
+cut.last_change(take)                                  # when a terminal take finished
+cut.window_clip(mov, bg_png, x, y, out, width=None)    # a window recording, cropped, corners rounded, on a card
+cut.window_box(mov)                                    # (w, h, x, y) of a window in its shadow
+cut.Card(1920, 1080, bg).text(None, 400, "Title", 112, 700).badge(None, 600, "8x speed").save(png)
+
+said = cut.lines(take, start, end, offset)             # a take's voiceover lines in [start, end), moved to offset
+cut.voice_track(said, wav, total)                      # those lines laid out on a track `total` seconds long
+cut.add_audio(video, out, voice=wav, music=None, music_volume=0.25)   # music loops, fades, ducks under the voice
+cut.write_srt(cut.cues(take, start, end, offset), srt) # subtitles: the voiceover, or else the captions
+```
+
+`cut.ff(...)` runs any other ffmpeg command. Every clip made by these is 60 fps H.264 in yuv420p with no sound.
+
+## Steps
+
+1. Keep all the words on screen at the top of the edit script, so they're easy to change.
+2. Cut each web part at its beats: the take's own end beat is usually replaced by a proper end card.
+3. Cut a terminal take at `cut.last_change`. Speed up the waiting part and label it ("8x speed").
+4. Join the parts with `cut.concat`. They must all be the same size: a web take at 1280x720@1.5 is 1920x1080, a VHS
+   take is its tape's `Width` and `Height`. Place smaller takes on a full-size card with `cut.place`.
+5. Make the 9:16 version: the landscape video on a 1080x1920 card, with the name above and the link below.
+6. Make one GIF per section, from beat to beat.
+7. Add sound last, to the finished video: `cut.add_audio` with the voice track (if the storyboard had `VOICE`)
+   and any music. Give each part's lines its place in the finished video with `offset`: a part that starts 12 s
+   in uses `cut.lines(take, a, b, offset=12)`. Write subtitles the same way.
+8. Watch the whole thing, with sound if it has any. Check the end card's spelling and link. Then give the person the files and say where they
+   are. Don't post them.
+
+## Pitfalls
+
+- **Joining clips of different sizes** fails or looks wrong. `cut.concat` refuses them; make every part the same size.
+- **Colors change when joined.** A clip in full color range (a camera clip, or one made outside these helpers)
+  makes the clips after it look washed out. `cut.concat` refuses a mix; run such a clip through `cut.trim` first.
+- **Odd sizes.** H.264 in yuv420p needs even widths and heights. Scale to `-2` (as the helpers do).
+- **GIF colours.** The default palette bands badly. `cut.gif` makes a palette for each GIF.
+- **Joined GIF sections.** `cut.gif` normalizes frames before building a palette from the full clip, preserving card/browser joins and static scene changes. Inspect the opening, ending and duration so an omitted or frozen section cannot pass on MP4 playback alone.
+- **Fonts.** Cards use SF on macOS, and DejaVu Sans on Linux if installed.
+- **Faststart.** Joined videos are written with `+faststart`, so they play in a browser before they finish loading.
+- **Joining clips with sound.** `cut.concat` joins video only. Join the silent parts first, then add the sound.
+- **Subtitles and burned-in captions.** Captions on screen can't be read by a screen reader or searched, so the
+  `.srt` carries them too. With a voiceover, it carries what's said instead. Upload it with the video where the site
+  allows.
+- **Music you can use.** Only use music you have the right to post. Keep it quiet (`music_volume` 0.15 to 0.3).
+- **Limits for posting.** Sites limit size and length, and change them. Check before uploading.
+
+## Declarative edits
+
+`reshoot edit EDIT.toml TAKE...` accepts schema-version-1 edit files with ordered `[[part]]` entries and output profiles. The packaged project provides an example. Cut helpers write `.timeline.json` mappings; trims, speed changes, placement, and concatenation retain source times. Speed changes need a visible label and cannot shorten narration. Explicit local copies use `reshoot export RUN --directory DIR --file PATH`; hashes must match the report, and existing destinations are not overwritten.
+
+Declarative edits can use `trim_waits = true` for beats explicitly marked
+`trim_wait = true` with a passed expectation. Keep `min_reading` long enough to
+read the result. Reshoot preserves speech and labels shortened waits.

reshoot/bundled_skills/keep-current/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: keep-current
+description: Set up a reshoot.toml so one command (`reshoot run`) records a project's whole demo video again, and a GitHub Actions workflow that reshoots it on each release and opens a pull request. Use when someone wants their demo video or README GIF to stay up to date, or asks for demo videos in CI.
+---
+
+# Keep a demo video current
+
+## Rules
+
+- CI never publishes anything. The workflow opens a pull request; a person checks the review sheets and merges it.
+- Demo data used in CI is in the repo, so it's as public as the repo. Only put in what anyone may see.
+- Create workflow files locally when authorized. Push or publish only with the owner's permission.
+
+## Steps
+
+1. **Write `reshoot.toml`** at the project root, from the takes the project already has. `reshoot run --help`
+   lists every setting; `../../examples/notes/reshoot.toml` (from this skill's folder) is a full example.
+   - `[app]`: the command that starts the app on demo data, and the URL to wait for.
+   - `[[take]]`: one per take, `web` (with `out`), `tape`, or `run` for any other command.
+   - `[edit]`, `[check]`: the edit script and what to check.
+   - `[keep]`: where the finished files go in the repo, such as `docs/demo/`.
+2. **Run it locally:** `reshoot run`. Fix whatever fails. It stops at the first failed step and names it.
+3. **Add the workflow:** copy `../../examples/github/reshoot.yml` to `.github/workflows/reshoot.yml`. Add the steps
+   the app needs before it starts (installing packages, making demo data), and change the marked lines. The repo
+   must let workflows open pull requests (Settings, Actions, General, "Allow GitHub Actions to create and approve
+   pull requests"); it's off by default. Changing it is the person's call.
+4. **Tell the person** what the workflow does, and that they review each pull request's sheets (the
+   `reshoot-review` artifact) before merging. Push only with their yes.
+
+## Pitfalls
+
+- **Fonts differ on Linux,** so text may wrap differently from the local takes. Look at the first CI video closely.
+- **Agent takes** (Claude Code) need an account and key in CI, and vary between runs. Record them locally and keep
+  the file instead.
+- **Checks wait on the pull request.** Workflows don't run on a pull request opened by `github-actions[bot]` until
+  someone approves them ("action_required"). Tell the person, or use a GitHub App or personal token.
+- **A server already running** on the app's port stops the shoot, so a take can't show the wrong server.
+
+The run report and Action outputs distinguish `scan_status` and `review_status`. `ok=true` means execution completed, not approval to publish. A required check error stops the run, and the app remains available until its URL-based checks finish.
+
+Versioned runs keep separate candidate files. Compare two explicit runs with `reshoot compare OLD NEW --out FILE`, then generate `reshoot review NEW --previous OLD`. Matching beat IDs do not imply matching results. No new run promotes itself to the baseline.