docs: refresh dor agent skill

[nedtwigg]

Summary

• document dor await in the agent skill and surface-handle guidance
• simplify opening agent-browser panes from terminal surface refs
• remove the dedicated dor iframe section from the agent skill

Checks

• pnpm lint:specs
• pnpm lint:public-docs
• git diff --check

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	cf16df1
Status:	✅  Deploy successful!
Preview URL:	https://ad9f32c4.mouseterm.pages.dev
Branch Preview URL:	https://await-fixup.mouseterm.pages.dev

View logs

[dormouse-bot]

Two things worth a look, plus one note on text outside the diff.

The rewritten dev-server recipe races. dor ensure responds as soon as waitForTerminalState(..., isPaneOscDriven, INTEGRATION_DETECT_TIMEOUT_MS) reports shell integration — before typeCommandWhenPromptReady has even run the command, let alone before the server binds a port (the ensure handler in lib/src/components/wall/use-dor-control.ts). surface.resolveOpen then does a single getPlatform().getOpenPorts(target.id) scan with no retry, so the zero-candidate arm fires and the agent gets surface:3 is not serving any port. For any dev server with real startup cost that's the deterministic outcome, not an edge case. This PR ships the fix in the same file — dor await surface:3 --until quiet parks on the quiesce settle rather than the grace window (ensure leaves commandExitWatch set, so the idle path can't short-circuit it), which lands after the banner and after the bind.

The same un-awaited shape sits in docs/specs/dor-cli.md -> "Agent Workflows", in the Share a dev server row (dor ensure -- npm dev ... dor ab open surface:N / dor iframe surface:N then resolves that terminal's port in one step). If the recipe here grows an await, that row wants the same edit.

Dropping the dor iframe section left two dangling references. The skill still names iframe as a surface-creating command in "Targeting" (Commands that create surfaces (split, ensure, iframe) print the new ref) and again in "Rules and pitfalls" (Capture the ref that split/ensure/iframe print). An agent reading top-to-bottom now meets a command the skill never introduces. Since rule 2 already routes every page through dor ab, dropping iframe from both lists reads cleaner than reinstating the section — happy to push that if you want it.

[nedtwigg]

remove the dangling iframe references, I think I disagree on the rest

[dormouse-bot]

Done — cf16df13 drops iframe from both lists in dor/skill.md: the surface-creating commands in "Targeting" and the split/ensure/iframe triple in "Rules and pitfalls". Dropping the rest.

One iframe mention stayed on purpose: the dor ab --surface failure modes still say it fails "on an iframe-rendered surface (nothing to drive — open it with dor ab instead)". That names a render mode an agent can hit on a browser the user opened, not the removed command section, so it isn't dangling — say the word if you want it gone too.

node scripts/spec-lint.mjs and node scripts/public-docs-lint.mjs both pass; git diff --check clean.