# PhotoLM Agent Guide

Preferred automation route:
Open PhotoLM with a task URL such as `/?photolmAgentTask=agent-tasks/agent-smoke.json`, then poll `#photolm-agent-state` until its JSON status is `done` or `error`.
Use browser navigation or the address bar for URL autorun. If the launch command times out while PhotoLM is busy, keep polling hidden state before failing.
For visible design builds, keep humanoid layer pacing enabled. Layer-like steps pause briefly before adding or moving layers by default; use `layerDelayMs` / `photolmAgentLayerDelay` to tune it, or set it to `0` only when speed matters more than human-feeling progress.

Canonical files:
- `agent-manifest.json` - machine-readable entrypoints, selectors, helpers, and sample tasks.
- `site-skill.md` - full operating guide for agents and humans.
- `photolm-agent-api.js` - browser-console API loaded by the app.

Direct page-world route:
When your automation context can reach page globals, use `await PhotoLM.ready()` and then call `PhotoLM.agent.runTask(...)`, `PhotoLM.agent.runFromUrl(...)`, or lower-level `PhotoLM.run(...)` helpers.

Recovery rules:
- If Chrome blocks raw docs with `ERR_BLOCKED_BY_CLIENT`, fetch them with a terminal/http client.
- After interruptions or browser session changes, reacquire a fresh tab before probing PhotoLM.
- If `window.PhotoLM` is not visible, use URL autorun and poll hidden DOM state.
- Fail only when `state.status === "error"` or polling exceeds the timeout. Read `state.polling` and `state.automationRecovery` when present.

Verification:
After export, inspect `#photolm-agent-export-preview` and parse `#photolm-agent-export-preview.dataset.meta`. Export success is not visual approval.