iris: screenshots for agents — manifest, cargo-building sidecar, session wrapper, affordance and skill

Designed 2026-08-20 in conversation; PLUGIN.md is the decision record. Nothing here has
run yet: no live install, no build, no capture. The wrapper's two launch branches and the
cookie-seeding are written against documented behaviour, not observed behaviour.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

skills/iris-screenshots/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Iris screenshots
+description: Use when capturing website screenshots with the iris CLI — flags, authenticated captures, viewports, element capture, batching, and what to do when a capture comes out wrong.
+version: 1
+---
+
+`iris` (github.com/brijr/iris) renders a URL in a real Chrome-family browser over the DevTools protocol
+and writes an image. It waits for fonts, images and animations before capturing, so the output is what a
+person would see, not a half-loaded page.
+
+## The basic loop
+
+```
+iris https://example.com -o /tmp/shot.png
+```
+
+Then **Read the file** — that is the whole point. Write captures somewhere disposable (`/tmp`) unless the
+user asks to keep them.
+
+## Authenticated captures
+
+```
+iris https://site.example/private -o /tmp/private.png --chrome ~/.local/bin/iris-browser
+```
+
+`iris-browser` picks whichever Chrome-family browser is installed (Brave first, then Chromium, then
+Chrome) and seeds the capture with a copy of the cookies from `~/.config/officer/browser-profile` — the
+profile the desktop plugin's browser signs into. The copy is read-only with respect to that profile:
+captures cannot corrupt or lock it.
+
+Three rules:
+
+- **Never ask the user for credentials.** If a capture shows a login page, ask them to sign in to that
+  site once through the desktop app, then capture again.
+- **Whose sessions ride along is decided by `$HOME`** — each Linux user has their own profile, so you can
+  only ever capture with the sessions of the account you run as.
+- **Officer's own UI is behind its login too**, so capturing it needs the same wrapper and a signed-in
+  desktop session, exactly like any other site.
+
+## Flags that matter
+
+| Flag | What it does |
+| --- | --- |
+| `-o, --out <path>` | output file (or directory for batches) |
+| `-s, --size <preset>` | `desktop`, `iphone`, `ipad`, or `WxH` |
+| `--full` | full page height, not just the viewport |
+| `--selector <css>` | capture the first matching element only |
+| `--padding <px>` | breathing room around a selected element |
+| `--dark` | emulate `prefers-color-scheme: dark` |
+| `--format <fmt>` | `png`, `jpg`, `webp` |
+| `--wait <ms>` | extra settle time before capture |
+| `--wait-for <css>` | wait until a selector exists |
+| `--scale <n>` | device pixel ratio |
+| `--timeout <secs>` | per-page limit |
+| `--jobs <n>` | concurrency for multiple URLs |
+| `--chrome <path>` | which browser binary — for sessions, always `~/.local/bin/iris-browser` |
+| `--json` | structured result on stdout |
+
+Verify a UI change in both themes by capturing twice, once with `--dark`. Verify responsive work with
+`-s iphone` beside the desktop shot.
+
+## When it goes wrong
+
+- **`iris: command not found`** — the sidecar builds it on first start; `pm2 logs officer-iris` shows
+  progress or says exactly what is missing (usually Rust older than 1.88, with the fix printed).
+- **Capture shows a login page** — the site has no session in the profile. Ask the user to sign in via
+  the desktop app; do not work around it.
+- **`iris-browser: no Chrome-family browser found`** — the machine has no browser; the desktop plugin
+  provides one.
+- **Blank or half-rendered output** — add `--wait-for` on a selector that only exists when the page is
+  really ready, or raise `--wait`.