# WP Browser

Use this skill for WordPress tasks that require a real browser instead of WP-CLI or file inspection. Prefer `references/wp-project.md` first when you need to resolve a project slug, local URL, production URL, repo, or paths.

## Safety and scope

- Treat local sites as safe to inspect and operate, but still avoid destructive admin actions unless explicitly requested.
- Ask before changing production content, settings, users, plugins, themes, orders, forms, menus, options, or publishing state.
- Prefer read-only checks on remote/production sites: navigate, inspect, screenshot, verify text/layout, check console/network symptoms.
- Do not submit public forms, checkout flows, newsletter signups, contact forms, or anything that sends email/external effects unless explicitly requested.
- If login is required, use existing browser session/cookies when available. Ask for credentials only if no usable session exists.

## Choosing the URL

Resolve the target URL from the request:

- If the user gives a full URL, use it directly.
- If the user gives a project slug, use `references/wp-project.md` conventions to derive the local site URL: `${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}`.
- If the user says production/remote, prefer `WP_SITE_URL` from Gitea repository Actions variables via `references/websimple-gitea.md` conventions/tools when available.
- If the request is ambiguous between local and production, default to local and state that assumption briefly.

## Browser environment prerequisite

Websimple local dev sites may resolve to private network IPs, for example a `*.${WEBSIMPLE_STACK_DOMAIN}` hostname resolving to an IPv6 ULA address like `fd00::/8`. Some browser/MCP harnesses are SSRF-guarded and block private-network targets by default.

If browser navigation to a local Websimple site fails with a policy-related error (e.g. "navigation blocked by policy"), the browser harness likely needs an allowlist entry for the local Websimple domain plus private-network opt-in. The shape of that configuration depends on the harness in use (Playwright MCP, OpenClaw, etc.), but conceptually:

- Allow `*.${WEBSIMPLE_STACK_DOMAIN}` (and `${WEBSIMPLE_STACK_DOMAIN}` itself) on the hostname allowlist.
- Permit private-network destinations.

Resolve `${WEBSIMPLE_STACK_DOMAIN}` from the environment; do not hard-code a specific local domain. Prefer an allowlisted form over globally allowing private-network access. Restart/reload the browser harness after changing its SSRF policy.

## Browser workflow

1. Open or reuse a browser tab for the target site.
2. Take a snapshot before interacting; use semantic/ARIA refs where possible.
3. Navigate like a user: click links/buttons, fill inputs, use menus, and wait for reliable UI state instead of arbitrary delays.
4. Check the page result with at least one concrete signal: visible text, URL, status page, screenshot, console messages, or DOM state.
5. Report concise evidence: URL checked, action performed, result, and any blockers.

For multi-step browser flows, login checks, stale refs, or tab recovery, follow the general `browser-automation` skill’s browser-control practices.

## WordPress admin

Common admin URLs:

- Dashboard: `/wp-admin/`
- Login: `/wp-login.php`
- Plugins: `/wp-admin/plugins.php`
- Themes: `/wp-admin/themes.php`
- Customizer: `/wp-admin/customize.php`
- Menus: `/wp-admin/nav-menus.php`
- Pages: `/wp-admin/edit.php?post_type=page`
- Posts: `/wp-admin/edit.php`
- Site Health: `/wp-admin/site-health.php`

When checking admin screens:

- Confirm whether the session is authenticated by looking for the admin bar, dashboard, or login form.
- Avoid saving forms unless requested.
- For settings screens, inspect current values and controls before editing.
- For editor screens, avoid autosave-risky content edits unless explicitly requested.
- If normal browser `fill` does not populate the WordPress login fields, use a narrow DOM fallback to set `#user_login` and `#user_pass`, dispatch `input` events, then submit. Do not echo credentials back to the user.

## Frontend checks

For frontend verification:

- Check desktop first unless the user asks for mobile/responsive.
- Capture a screenshot when visual appearance matters.
- Inspect console errors when behavior looks broken or JavaScript-heavy.
- Verify canonical symptoms with user-visible evidence, not assumptions from source code alone.

## Cookies and debugging hooks

- For Xdebug-specific browser requests, use `references/wp-xdebug.md`.
- If needed manually, set or include the `XDEBUG_SESSION=vscode` cookie only for local debugging flows and mention that it may route PHP through `wp-php-xdebug`.