claude-websimple-devops/references/wp-browser.md

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.