1# Quality Gate & Recovery
2 
3Headless Chrome can silently return low-quality content — layout shells, login walls, or framework payloads — without the CLI returning a non-zero exit code. Read this after every headless run so you can catch and recover from those cases.
4 
5## Checks the Agent Must Run
6 
71. Confirm the markdown title matches the target page, not a generic site shell
82. Confirm the body contains the expected article/page content, not just navigation, footer, or a generic error
93. Watch for obvious failure signs:
10   - `Application error`
11   - `This page could not be found`
12   - Login, signup, subscribe, or verification shells
13   - Extremely short markdown for a page that should be long-form
14   - Raw framework payloads or mostly boilerplate content
154. Do NOT accept a run as successful just because the CLI exited `0`
16 
17**Tip**: run with `--format json` to get structured signals including `status`, `login.state`, and `interaction`. `"status": "needs_interaction"` means the page requires manual interaction.
18 
19## Recovery Workflow
20 
211. Start headless (default) unless there is already a clear reason to use interaction mode
222. Review markdown quality immediately after the run
233. If the content is low quality or indicates login/CAPTCHA:
24   - `--wait-for interaction` for auto-detected gates (login, CAPTCHA, Cloudflare)
25   - `--wait-for force` when the page needs manual browsing, scroll loading, or complex interaction
264. If `--wait-for` is used, tell the user exactly what to do:
27   - Login required → sign in in the browser
28   - CAPTCHA visible → solve it
29   - Slow loading → wait until content is visible
30   - `--wait-for force` → press Enter when ready
315. If JSON output shows `"status": "needs_interaction"`, switch to `--wait-for interaction` automatically
32 
33## Capture Modes
34 
35| Mode | Behavior | Use When |
36|------|----------|----------|
37| Default | Headless Chrome, auto-extract on network idle | Public pages, static content |
38| `--headless` | Explicit headless (same as default) | Clarify intent |
39| `--wait-for interaction` | Opens visible Chrome, auto-detects login/CAPTCHA gates, waits for them to clear, then continues | Login-required, CAPTCHA-protected |
40| `--wait-for force` | Opens visible Chrome, auto-detects OR accepts Enter keypress to continue | Complex flows, lazy loading, paywalls |
41 
42**Interaction gate auto-detection**: Cloudflare Turnstile / "just a moment" pages, Google reCAPTCHA, hCaptcha, custom challenge / verification screens.
43