docs(ego-browser): note window-state cause of screenshot timeouts

[jsiu93]

Summary

page.screenshot() times out whenever the ego lite window is minimized or hidden on macOS, because the system stops issuing drawing signals for those window states. #183 localized this and the workaround established there is to keep the window visible; it may be fully covered by other windows. That conclusion currently lives only in the issue thread, so every agent rediscovers it the hard way.

The symptom is actively misleading: the screenshot times out while page.info(), page.evaluate(), navigation and input helpers all keep working normally, which reads as a broken runtime rather than a window state. In our session it cost roughly six rounds of diagnosis across new tabs, new routes and three fresh task spaces before an unrelated app restart happened to make the window visible again, after which the first capture returned in about 1 second and the next in 63 ms.

One Caveats bullet turns that into zero rounds.

Related issue

Relates to #183. Not a fix for it: the underlying behavior is a Chromium display-backend concern that the maintainer has said may not be worth fixing. This only records the symptom, the cause, and the recovery so agents stop misdiagnosing it.

Changes

• Add one bullet to ## Caveats in skills/ego-browser/SKILL.md, placed directly after the existing page.info() bullet since that one already covers when to stop screenshot and coordinate work.

Verification

Commands run from package/ego-browser:

npm test                      311 pass, 0 fail
npm run validate:site-skills  site skills ok
npm run typecheck             clean

Behavior reproduction, on ego lite 0.4.6.12 (chromium 150.0.7871.101, macOS Darwin 25.6.0), with a page loaded and settled:

1. Minimize (Cmd+M) or hide (Cmd+H) the ego lite window, then take a screenshot. It times out after about 15 seconds with CDP request timed out: Page.captureScreenshot, while a page-info call in the same command returns a normal viewport.
2. Restore the window and leave it unfocused and fully covered by another window, then repeat. The capture succeeds in well under a second.

Impact

• Public helper API or behavior
• Agent skill or instructions
• Site learning
• Installation or update flow
• Build, CI, or release process
• Documentation only
• No externally visible impact

No public surface changes, so there is nothing to migrate or roll out.

Checklist

• The PR targets the correct base branch (dev for normal changes; only dev may target main).
• The change is focused and does not include unrelated cleanup.
• Tests were added or updated for behavior changes, or the reason they are unnecessary is explained above. Documentation only, no behavior change.
• Relevant tests and validation commands pass locally.
• Public helper JSDoc and agent-facing documentation are updated when the helper surface changes. The helper surface is unchanged; this updates the agent-facing document itself.
• No credentials, tokens, cookies, personal data, or other secrets are included.
• A release-note label is selected (feat, fix, docs, chore, ci, or refactor). Outside contributors cannot set labels; please apply docs.