docs: xvfb claims match CI evidence — run headless in CI

AGENTS.md

@@ -49,9 +49,9 @@ test/            → unit tests for the pure/safe modules (no browser)
   strips the extension subsystem; never switch to it. Under the full channel,
   headless **works** (`HEADED=0`; verified 2026-06-10 on macOS + Linux CI,
   recordVideo included); the local default stays headed for debuggability.
-  Headed-under-xvfb needs a 24-bit screen
-  (`xvfb-run -a --server-args="-screen 0 1920x1080x24"` — the 8-bit default
-  breaks `Page.captureScreenshot`).
+  Headed-under-xvfb is unsupported on CI runners (the 8-bit default breaks
+  `Page.captureScreenshot`; a 24-bit screen still failed silently) — run
+  headless in CI.
 - **Caption band stacks UNDER the shot** (scene captured at `height - bandHeight`,
   band appended) so the final image is the exact preset size and no UI is hidden.
 - **`promo.js` innerHTML** is trusted, build-time content only (the repo's own

README.ko.md

@@ -38,7 +38,7 @@ npx playwright install chromium    # 최초 1회: shotkit이 구동할 브라우
 npx @starter-series/shotkit
 ```
 
-> shotkit은 **풀 Chromium**(`channel: 'chromium'`)을 구동합니다 — 확장 서브시스템이 없는 headless-shell이 아닙니다. **headless 동작 검증 완료**(`HEADED=0`; macOS·Linux CI, 영상 포함)이며 starter capture 워크플로의 기본값입니다. 로컬 기본은 디버깅 편의상 headed. CI에서 headed가 필요하면 xvfb에 24비트 화면을 주십시오(`--server-args="-screen 0 1920x1080x24"` — 8비트 기본값은 스크린샷 캡처가 깨집니다).
+> shotkit은 **풀 Chromium**(`channel: 'chromium'`)을 구동합니다 — 확장 서브시스템이 없는 headless-shell이 아닙니다. **headless 동작 검증 완료**(`HEADED=0`; macOS·Linux CI, 영상 포함)이며 starter capture 워크플로의 기본값입니다. 로컬 기본은 디버깅 편의상 headed. CI 러너에서 headed-under-xvfb는 신뢰할 수 없었습니다(8비트 기본값은 스크린샷 캡처가 깨지고, 24비트로도 무성 실패) — CI에서는 headless를 쓰십시오.
 
 ## 사용
 

README.md

@@ -41,7 +41,7 @@ Zero-install in any repo that has a config:
 npx @starter-series/shotkit
 ```
 
-> shotkit launches the **full Chromium** (`channel: 'chromium'`) — never the default headless-shell, which strips the extension subsystem. **Headless works** (`HEADED=0`; verified on macOS and Linux CI, video included) and is the CI default in the starter's capture workflow; the local default stays headed for easy debugging. If you need headed-under-xvfb in CI, give xvfb a 24-bit screen (`xvfb-run -a --server-args="-screen 0 1920x1080x24"`) — the 8-bit default breaks Chromium's screenshot capture.
+> shotkit launches the **full Chromium** (`channel: 'chromium'`) — never the default headless-shell, which strips the extension subsystem. **Headless works** (`HEADED=0`; verified on macOS and Linux CI, video included) and is the CI default in the starter's capture workflow; the local default stays headed for easy debugging. Headed-under-xvfb proved unreliable on CI runners (the 8-bit default breaks Chromium's screenshot capture, and a 24-bit screen still failed silently) — run headless in CI.
 
 ## Usage
 
@@ -121,7 +121,7 @@ module.exports = {
 | Claude Code skill ([`skills/capture/`](skills/capture/SKILL.md)) | ✅ now | Claude Code (portable to Codex/Cursor/Gemini via the Agent Skills format) |
 | `AGENTS.md` run-block | ✅ now | every agent that reads AGENTS.md |
 | npm package (`@starter-series/shotkit`) | ✅ now | `npx` zero-install |
-| Capture-in-CI GitHub Action | ✅ now — ships in [`browser-extension-starter`](https://github.com/starter-series/browser-extension-starter)'s `capture.yml` (headless default, 24-bit-xvfb fallback) | zero-local-browser runs + CI smoke test |
+| Capture-in-CI GitHub Action | ✅ now — ships in [`browser-extension-starter`](https://github.com/starter-series/browser-extension-starter)'s `capture.yml` (headless) | zero-local-browser runs + CI smoke test |
 | `starter-series` marketplace entry | planned | discovery |
 | Video editing (`webm→mp4`, trim, captions) | planned | SNS clips |
 

skills/capture/SKILL.md

@@ -35,8 +35,7 @@ rendered from the shipped code.
 ## Notes
 
 - Runs the full-Chromium channel; headless works (`HEADED=0 npx …` — verified,
-  video included) and is the right mode for CI. If headed-in-CI is required,
-  use `xvfb-run -a --server-args="-screen 0 1920x1080x24"` (the 8-bit xvfb
-  default breaks Chromium screenshots).
+  video included) and is the mode to use in CI. Headed-under-xvfb is
+  unreliable on CI runners — don't use it.
 - Scenes are the repo's own config — to change *what* is captured, edit
   `shotkit.config.js`, not shotkit.

src/launch.js

@@ -10,8 +10,8 @@
  *     (no service worker, MV3 onInstalled never fires) — the full Chromium
  *     channel is required. Under it, headless ALSO works (HEADED=0; verified
  *     2026-06-10 on macOS + Linux CI, recordVideo included). The local
- *     default stays headed for easy debugging. Headed-under-xvfb needs a
- *     24-bit screen (--server-args="-screen 0 1920x1080x24").
+ *     default stays headed for easy debugging. Headed-under-xvfb proved
+ *     unreliable on CI runners — prefer headless there.
  *
  *   --disable-features=DisableLoadExtensionCommandLineSwitch
  *     Chromium 121+ guards --load-extension behind this flag by default.