Norml Wp Manager

Norml WordPress Copilot

Installed skill: norml-wp-manager

Requires onboarding. Before this skill can do anything, the site must be connected once. If no */.wpm/config.json is found (Console: walking up from the working directory; Desktop: in the mapped project folder), hard-stop and route to onboarding — Console → onboarding-console.md, Desktop → onboarding-desktop.md — never improvise the connection by asking for the Application Password in chat.

REST API only. This skill talks to WordPress exclusively over its built-in REST API at /wp-json/. It does not use SSH, does not use WP-CLI, does not touch the server filesystem. That makes it safe to hand to a site owner who has WordPress admin access but no developer tooling. The trade-off: anything the REST API can't do, this skill can't do — bulk DB operations, plugin/theme install on most managed hosts, wp eval PHP, search-replace. Those belong to a developer using WP-CLI directly.

One mental model

Everything Claude knows about a site lives in one folder the user names (e.g. acme-marketing/). Three human-readable files sit at the top (capabilities.md, project-notes.md, changelog.md); a hidden .wpm/ subfolder holds the machinery (connection config, the credential when applicable, the auto-generated site scan). Delete the folder and the skill forgets the site — nothing else on the machine is touched.

acme-marketing/                    ← THE unit. User-named, visible, one per site. Portable, zip-safe, update-safe.
├── README.md                      ← 4 plain lines: what this is / move / delete / "don't hand-edit .wpm/"
├── capabilities.md                ← generated contract: what this account can do here. Rewritten on capability rescan.
├── project-notes.md               ← durable human/AI knowledge. Hand-editable. Survives rescans.
├── changelog.md                   ← append-only op + decision + [SCAN] log. Human-readable audit trail.
└── .wpm/                          ← the machinery (dotted = hidden, brand-neutral).
    ├── config.json                ← connection config, schema_version 4. NO secret. chmod 600.
    ├── credential                 ← AP, RAW string. born chmod 600. gitignored. FLOOR TIER ONLY (absent on OS-keychain).
    ├── .gitignore                 ← lives HERE, beside the secret. One line: credential
    └── docs/                      ← auto-generated scan layer. Read-before-operate. Do-not-hand-edit.
        ├── README.md              ← doc index + rescan map + read-order contract
        ├── 00-connection.md       ← env, network-gate result, auth, user+roles, secret pointer, last_scan_at
        ├── 01-site.md             ← WP version (best-effort), settings, REST namespaces, multisite hint
        ├── 02-content-model.md    ← post types (per-type show_in_rest), taxonomies, content counts
        ├── 03-plugins-theme.md    ← active theme, plugin inventory, detected key plugins, 3rd-party agents
        └── 04-rest-capabilities.md← writability matrix + known blockers + "What REST cannot see"

Hard invariants (non-negotiable):

1. One user-named folder per site. No ~/.config/ anywhere, ever — not written, read, probed, or created as a side effect.
2. Per-site state never lands inside the skill folder (~/.claude/skills/… or the desktop skill mount) — skill updates wipe it.
3. Network reachability is proven before any credential is created or handed off (Desktop).
4. The credential never enters argv or the AI transcript, and is born private on disk. The v2.3.0 -u "$user:$pass" pattern is a vulnerability, not a mitigation.
5. No security claim the platform doesn't deliver — no false "owner-read only" where the filesystem ignores POSIX perms.

Config is resolved at runtime by walking for */.wpm/config.json — NEVER a literal folder name, NEVER ~/.config. The site folder is always derived from the .wpm/ parent, so config.json stores zero paths that escape the folder.

Where this skill runs — two environments

The skill detects its environment once per session and acts accordingly.

• Console = Claude Code (terminal). A real local shell: the OS secret store is reachable, an OS dialog can pop, and outbound network is unrestricted.
• Desktop = the Claude desktop app + Cowork. A cloud sandbox: no OS secret store, no OS dialog, and a default-deny egress allowlist. The bundled local connect.html writes a short-lived handoff directly into the selected site folder, outside the AI conversation. This is the PRIMARY distribution target.

env values (four cells)

console-macos | console-windows | console-linux | desktop. Set once at setup, written to config.json, held for the session. Governs secret lookup, the network gate, and 403 disambiguation.

Detection by probe (first decisive signal wins)

• PROBE-P (platform): uname -s → Darwin / Linux / MINGW*|MSYS*|CYGWIN* (Windows = PowerShell).
• PROBE-E (egress — THE decisive tell):

  curl -sS -o /dev/null -w "%{http_code}" --max-time 8 https://example.com
  

  200/30x = outbound OPEN (Console-like); blocked / 000 / curl exit 6/7/35/56 = a default-deny allowlist is present = DESKTOP. Probe a NEUTRAL host (example.com), not anthropic.com — package / GitHub / Anthropic hosts are allowlisted and would pass even inside a sandbox, defeating the test.
• PROBE-K (OS secret store — only if PROBE-E is OPEN): macOS command -v security; Windows lib/credman.ps1 resolves; Linux command -v secret-tool AND a store→lookup→delete round-trip succeeds → libsecret, else FLOOR. (The binary can exist while the D-Bus secret service isn't running — headless/WSL/SSH — so the round-trip is mandatory; any failure silently degrades to FLOOR, never blocks setup.)
• PROBE-D (OS dialog — confirms the Console capture path): macOS osascript / Windows PromptForCredential succeeds.

Router decision

IF PROBE-E BLOCKED                          → env = DESKTOP  (storage = FLOOR; run NETWORK GATE before any credential)
ELIF PROBE-E OPEN and a secret store passes → env = CONSOLE  (storage = that OS store)
ELIF PROBE-E OPEN but no secret store       → env = CONSOLE  (storage = FLOOR; e.g. Linux server / WSL, no keyring)
ELSE / no writable folder & no shell        → UNSUPPORTED (claude.ai web/mobile) — say so, point at Console or Desktop

Anti-false-positive rules:

• Never conclude Desktop from uname=Linux alone — WSL and Linux servers are Console (network open, no keyring → FLOOR, no gate).
• Never conclude Console from "Keychain present" without running PROBE-E first.
• A timeout where even anthropic.com is unreachable = a dead network ("your machine has no internet right now"), not Desktop.

This replaces v2.3.0's "is ~/.config/ writable?" check, which mis-routed sandboxes with a writable $HOME and never gated on network. The egress probe is the single signal that separates "Linux Console, no keyring → file, network open, NO gate" from "Desktop sandbox → file, network BLOCKED, gate REQUIRED."

First-run setup is environment-specific

Don't improvise it here. Console → onboarding-console.md (no gate). Desktop → run the NETWORK GATE first, then onboarding-desktop.md. See the Pre-flight router below for the exact branch.

When to use

Any request to read, change, or audit content on the user's WordPress site — posts, pages, custom post types, ACF field values, SEO metadata, media, users, categories, settings.

Typical asks:

• "List my plugins" / "What's my theme?"
• "Show me my last 10 posts."
• "Update the title of post 42 to 'Spring launch.'"
• "Publish the draft called 'New pricing page.'"
• "What ACF fields does the homepage use? What are their current values?"
• "Set the featured image on post 42 to {filename}."
• "Update the SEO title and description on the /about page."
• "Add a category called 'Insurance Tech.'"
• "Who are the admin users on this site?"
• "Scan my site again — I activated a new plugin."

Skip if

• The user needs to install, activate, or update a plugin or theme. Most managed hosts disable POST /wp/v2/plugins. Tell the user to use wp-admin (Plugins → Add New) or have their developer do it via SSH/WP-CLI.
• The user needs to edit theme code, plugin code, functions.php, or any PHP file. That's developer territory — this skill never touches files.
• The user needs bulk database operations (search-replace, mass schema updates, wp_options rows that aren't REST-exposed). REST is too slow and the surface is too narrow. Escalate to a developer.
• The user wants to migrate a whole site between environments. Different workflow entirely.
• The user is doing a code-level architecture audit of the WordPress install. This skill operates inside wp-admin's surface, not under it.

Pre-flight (run every session, before the first WP operation)

Step 1 — Detect the environment

Run the probes above (PROBE-E first, then PROBE-K / PROBE-D as needed). Decide env via the router decision table. Hold env for the whole session — it changes how the credential is looked up, whether a network gate is required, and how a 403 is diagnosed.

Step 2 — Resolve the site folder + resume-or-onboard

• Console: walk up from the current working directory for */.wpm/config.json. There is no ~/.config branch — drop it entirely.
• Desktop: look in the mapped project folder for .wpm/config.json.
• Found + config.env matches the detected env → RESUME (go to Step 3).
• Found but env mismatches (e.g. a Console keychain config opened in Desktop) → tell the user this site was set up for the other environment, offer a fresh setup, and never silently reuse a keychain pointer that can't resolve in a sandbox.
• Absent → FIRST-RUN. Branch on env and follow EXACTLY ONE runbook — Console = no gate (onboarding-console.md); Desktop = NETWORK GATE FIRST (onboarding-desktop.md). Do not interleave the two.
• Templates are READ from the skill folder but NEVER written back there. If the skill isn't at ~/.claude/skills/ (Cowork mounts it elsewhere), write minimal inline versions of the curated files so setup still completes.
• A v3 config (found at the old ~/.config/norml-wp-manager/config.json or {project}/norml-wp-manager/config.json) → offer one-time migration, never silently dual-home. See wordpress-guides/safety-rules.md and the changelog migration note; carry project-notes.md + changelog.md over verbatim, reuse (or cleanly re-key) the keychain entry, and rotate a floor secret rather than byte-copying it.

Step 3 — Load the doc set before any WP op, in this exact order

1. .wpm/docs/00-connection.md — env, who you're connected as + roles, secret pointer, last scan time.
2. capabilities.md — what can I actually do here. This is the visible, generated operating contract. Consult BEFORE any write.
3. .wpm/docs/02-content-model.md — does the target post type have show_in_rest?
4. project-notes.md (site-folder top level) — surface gotchas; if the user is editing the homepage and notes say "uses Elementor," lead with that.
5. The last ~20 lines of changelog.md (site-folder top level) — so you don't blindly conflict with, repeat, or undo a recent deliberate change.

If 00–04 are missing → run the scan (all stages) inline first (Stage 0 gates everything; see "Scaffold + scrape"). If last_scan_at is >7 days old, mention it once and proceed unless the user declines.

Step 4 — Operate-phase gate (NEW hard rule)

Before any write, check 04/02. If the target surface is not REST-exposed or not writable at the connected role, do NOT fire a doomed request. Tell the user: "this CPT/field isn't reachable over REST; edit it in wp-admin, or have a developer flip show_in_rest," and append a [LEARNED] line to changelog.md.

Never ask the user for the Application Password in chat in any environment. Console captures it through a native OS dialog. Desktop / Cowork captures it in the bundled local connect.html handoff, which writes a short-lived, git-ignored file that the importer deletes immediately after authentication.

How operations work

Every WordPress operation is an HTTPS call to {production_url}/wp-json/..., authenticated with HTTP Basic Auth using the WordPress login slug plus the Application Password retrieved at runtime. There is exactly one sanctioned auth call form and exactly one sanctioned secret reader.

The only sanctioned secret reader

get_password() is the single reader. It never echoes the value — it pipes it straight into the auth call.

get_password() {   # resolves the AP for the active tier; prints to stdout for piping only
  case "$SECRET_KIND" in
    macos-keychain)             security find-generic-password -s "$SECRET_REF" -w ;;
    linux-libsecret)            secret-tool lookup service "$SECRET_REF" ;;
    windows-credential-manager) : ;;   # Windows uses the PSCredential path below, never this
    portable-file)              cat "$SITE_FOLDER/.wpm/$SECRET_REF" ;;   # floor: raw string file
  esac
}

($SECRET_KIND / $SECRET_REF come from config.json secret_store.kind / secret_store.ref. $SITE_FOLDER is derived from where config.json was found.)

The only sanctioned auth call

restcall() {   # $1 = endpoint path (e.g. /wp/v2/users/me), $2.. = extra curl args
  local ep="$1"; shift
  curl -sS --proto '=https' --max-redirs 0 \
    --config <(printf 'user = "%s:%s"\n' "$WP_USER" "$(get_password)") \
    -H "Accept: application/json" "$@" "${PROD_URL}${ep}"
}

Mandate and forbid, explicitly:

• --config <(...) (process-substitution FD) is mandatory: curl's argv shows only --config /dev/fd/NN; the user = "..." line travels over a pipe — never on disk, never in argv, and set -x renders the FD path, not the bytes.
• FORBIDDEN: a real curl config file (-K /tmp/wpm-curl.cfg) — it trades an argv leak for a world-readable-/tmp leak. Recorded as a rejected alternative so no contributor "hardens" the FD form into it.
• Every authenticated call carries --proto '=https' --max-redirs 0 so a compromised site can't bounce the Basic-auth header to another origin.
• Windows / PowerShell: build a PSCredential and call Invoke-RestMethod -Authentication Basic -Credential $cred (the secret stays a SecureString). Do NOT shell out to curl.exe -u.

Vulnerability reclassification. The v2.3.0 -u "$user:$pass" pattern is a vulnerability, not a mitigation. It leaks the credential into ps, /proc/<pid>/cmdline, and auditd, and — under set -x — into the Bash-tool transcript. It is removed from every script and every command template in this document. Do not reintroduce it.

Two genuinely-correct rules carried over from v2.3.0 (keep them):

• Always send Content-Type: application/json on writes, otherwise WordPress treats the body as form-encoded and silently drops nested objects (the acf key, the meta key).
• Use ?context=edit when reading data you intend to write back — without it, context=view strips the raw + meta payloads and the round-trip becomes impossible.

Secret-storage ladder

Two rungs. There is no Rung 3. No crypto theater.

No Rung 3 (stated plainly, protect it). There is no zero-infra way to encrypt the floor file meaningfully — any key the skill could auto-decrypt with must sit on the same disk as the file it protects. A per-session passphrase is unacceptable UX for a non-technical owner. The floor is honest plaintext, protected by filesystem perms + git-exclusion. No contributor may add a fake "encrypted credential store."

The real mitigations carry the weight crypto can't:

• Least-privilege editor-role AP by default — admin only when the task needs plugin/theme/settings endpoints. A leaked editor AP can't install plugins, edit users, or escalate.
• AP ≠ login password — independently revocable; always say so.
• Monthly rotation for any standing floor secret.
• End-of-Desktop-session rotation as the DEFAULT close-out (not "consider it"). The skill proactively offers to walk the revoke when a Desktop session that handled the AP ends.
• No argv / no trace / no echo — the --config <(...) form, set +x, and never cat/echo the credential to stdout.
• Assertive gitignore gate (BLOCKING) — after writing credential, if git is present run git check-ignore; if it does NOT return the path, STOP and back the credential out, don't merely assert the line exists.
• HTTPS only — production_url must be https:// for any AP-bearing call; warn-and-allow only for explicit localhost.

Honest caveat (no false claims). On a Windows-host Desktop session where the floor file can't be ACL-locked from the sandbox, the skill MUST NOT report "owner-read only." It says plainly: "On this setup the file's OS permissions can't be locked to you — treat the folder as readable by anyone with an account on this PC; rotate weekly and use an editor AP."

Safety classification (apply to every request)

Cross-reference against wordpress-guides/safety-rules.md. Three buckets:

• Safe — read-only or low-risk single-item edits. Run immediately, then report. Examples: GET /wp/v2/posts, GET /wp/v2/users/me, updating one named post's title, attaching a featured image to one post, updating one ACF field value on one post.

• Confirm — anything that mutates multiple items, changes site-wide settings, creates/deletes users, or trashes published content. Show the exact endpoint + body you intend to send, the affected target, and ask for an explicit "yes" in the same session before executing. Examples: POST /wp/v2/settings for site title / posts_per_page, POST /wp/v2/users (especially with admin role), bulk content edits affecting >5 items, DELETE /wp/v2/posts/{id}?force=true, any change to siteurl or home.

• Stop — destructive or unsupported via REST. Refuse and explain. The REST API physically can't do most truly destructive operations (no wp db reset, no rm), but a few are still dangerous: changing siteurl/home (often locks the user out), demoting the last administrator, bulk-deleting users with content. If the user insists, point them at a backup first and have them confirm the risk explicitly.

When in doubt, treat as Confirm, not Safe.

Project knowledge layer — the site folder

The site folder is the canonical knowledge store for everything norml-wp-manager knows about this WordPress site. It is the main point of context for every future session. It is designed to compound knowledge over time — every session leaves the folder richer than it found it. There are two trust layers.

Two-layer trust split

(a) Generated layer — .wpm/docs/00–04 (do-not-hand-edit). Auto-written by the scan, overwritten by rescan. Each file opens with a frozen header:

<!-- GENERATED by norml-wp-manager scan — DO NOT EDIT BY HAND. Rescan rewrites this file. -->
_Scanned: {ISO-8601} · Connected as: {user} ({roles}) · Tier: {secret_store.kind} · env: {env}_

…and ends with a What REST cannot see here fenced block (the honesty ceiling). Anything that should survive a rescan does not go here — it goes in project-notes.md.

(b) Visible operating layer — top-level capabilities.md. Generated from the Stage 4 REST checks and overwritten on a capability rescan. It is the short human/AI contract for what this connected account can read, create, update, and delete here.

(c) Curated layer — top-level project-notes.md + changelog.md. Hand/AI-editable, never touched by a rescan. (Templates KEPT verbatim from v2.3.0; only the write location moved to the site-folder top level.)

project-notes.md — how this site works

Durable knowledge that doesn't change with a rescan. Claude appends to it when it learns something non-obvious. The user can edit freely. Four sections:

# {Site Name} — WP management notes

> Durable knowledge about managing this site. Claude appends to this file
> when it learns something non-obvious. Humans can edit freely. Survives
> capability rescans.

## Workflows specific to this site

(How to do common things on THIS site. Add as the team develops
site-specific patterns. E.g. "Blog posts use category 'Updates' by
default, featured image must be 1200×630, RankMath title format is
'{Post title} — {Site name}'.")

## Discovered facts

(Claude appends one-liners with dates when it learns something
non-obvious during a session.)

## Known gotchas

(Things that don't work, things to avoid, workarounds in use.)

## Open questions

(Unverified assumptions, things to test next session.)

changelog.md — what was done and decided

Append-only, chronological, at the site-folder top level. Every write operation lands here. Significant decisions and discoveries also land here. The reader (Claude or human) can scroll backward to answer "what's been done on this site, when, and why?"

Format: newest entry on top. Per-day section. One line per logical change. Tags at the start of each line:

• [WRITE] — content / postmeta change (post update, page update, ACF value, featured image)
• [OPTION] — wp_options or settings change (site title, posts_per_page)
• [USER] — user create / role change / delete / password reset
• [MEDIA] — upload / attach / update metadata / delete
• [DECISION] — policy / convention agreed with the user (e.g. "use category X for all blog posts going forward")
• [LEARNED] — non-obvious fact discovered during a session (e.g. "the case_study CPT isn't REST-exposed; ask the developer to flip show_in_rest: true")
• [SCAN] — architecture scan ran; what notable changed since the last one (or [SCAN] … ABORTED at gate: {egress-blocked|unreachable|auth-failed})
• [ROLLBACK] — explicit undo of a previous write

Example:

## 2026-05-20 — Spring sale launch + RankMath fixes

- 14:35 — [WRITE] Updated post 42 ("Spring sale") — title + body + set
  featured image (media #318). Was draft, now published.
- 14:32 — [DECISION] All blog posts use category "Updates" by default;
  confirmed with the user.
- 14:20 — [LEARNED] rank_math_focus_keyword isn't REST-writable on this
  site — the theme doesn't `register_post_meta(...,'show_in_rest'=>true)`.
  Wrote the value via wp-admin instead. Logged in project-notes.md →
  Known gotchas.
- 14:00 — [SCAN] First-time site architecture scan completed.
  RankMath SEO + ACF Pro active. 11 plugins. Active theme: child of
  "blocksy" (v2.0.30).

Scaffold + scrape (init)

On first connect — and on demand thereafter — the skill scrapes the site over REST into the five numbered docs in .wpm/docs/. The scan is REST-only and infra-free.

Five read-only REST stages. Stage 0 gates everything. "Degrade" = on a 403/empty response at a higher-role endpoint, write "not visible at this role" into that doc's blockers, never crash.

"What REST cannot see" (in every doc, mastered in 04): exact WP core version; PHP/MySQL/server stack/DB size/table prefix/custom tables; wp-config.php constants; cron events; theme file tree / functions.php / template hierarchy / enqueued assets; ACF field-group definitions (per-post values may be visible via ?context=edit, the schema is not); page-builder data shape (_elementor_data opaque blob); plugin settings in wp_options; CPTs/taxonomies with show_in_rest: false are invisible to REST entirely — with an explicit warning that the site may have more types than REST sees.

Role-requirement honesty. An editor AP fully populates 00, 02, and most of 04; 01 settings + 03 plugins/themes need admin → without admin those carry "not visible at this role" and 04 notes the gap. Non-fatal.

Rescan map

scan-site.sh --site-folder {path} --stage {0|1|2|3|4|all} — Stage 0 always re-runs first as a cheap reachability re-check.

Rescan rules: overwrite ONLY the targeted docs; never touch project-notes.md / changelog.md; diff-before-overwrite and print a per-doc delta ("post types: +1 portfolio; plugins: +Yoast, −WP Rocket"); append one [SCAN] line to changelog.md (or [SCAN] … ABORTED at gate: {egress-blocked | unreachable | auth-failed} on a Stage-0 failure — the scan must stop swallowing 403 silently); write config.json.last_scan_at. Staleness: pre-flight reads last_scan_at; if >7 days, mention once, proceed unless declined.

Write-back rules — how the skill compounds knowledge

The whole point of the site folder is that every session leaves it richer than it found it. Three triggers for writing back; treat them as defaults, not exceptions.

When to append to changelog.md

Append an entry before closing any response that mutated the site. This is the audit trail the user relies on to answer "what did Claude touch, when, and why?"

Triggers:

• [WRITE] — any operation that wrote to a post, page, postmeta, or ACF field value
• [OPTION] — any change to wp_options or settings
• [USER] — any user create / role change / delete / password reset
• [MEDIA] — any upload / attach / update / delete
• [DECISION] — any policy or convention the user agreed to ("from now on we use X")
• [LEARNED] — any non-obvious fact discovered (silently-no-op'd REST endpoint, hidden constraint, version mismatch); also write to project-notes.md for the durable copy
• [SCAN] — when the scan runs
• [ROLLBACK] — any explicit undo

Multi-step operations collapse into one compound entry capturing the full flow — not one entry per HTTP call. The reader cares about the change, not the request count.

Do not log: pure reads (list / get / query). If a read revealed something durable, that goes in project-notes.md → ## Discovered facts, not the changelog.

How to write:

1. Read {site_folder}/changelog.md (site-folder top level).
2. If today's date section exists at the top, append entries to it. Otherwise insert a new ## YYYY-MM-DD — {short theme} section above the previous section.
3. Use Edit with a unique old_string. Newest entry on top of the day's section. Time format HH:MM (local time, 24-hour).
4. One line per logical change. Tag at the start. Include the target and a one-line cause.

When to append to project-notes.md

Write to project-notes.md → ## Discovered facts (or ## Known gotchas when it's a "watch out for X" lesson) when ANY of these hold:

• A first attempt at an operation failed and a second attempt succeeded — the thing that made it work is the durable fact.
• A counterintuitive constraint surfaced (ACF field key doesn't match its label; CPT slug differs from public name; a plugin hooks something unexpectedly).
• A workaround used to bypass a "Known blockers" item from 04-rest-capabilities.md.
• The user explicitly says "remember this," "add this to the notes," "going forward do X."

Do not write routine successes ("posted a blog post"), anything obvious from the generated docs, or personally-identifying details about specific posts/users (use patterns, not contents).

Date the line YYYY-MM-DD so the file stays sortable. Newest first within the section.

When to update the generated docs (00–04)

Only via a rescan. Never hand-edit. If a fact should survive across rescans, it belongs in project-notes.md.

Knowledge baseline

Use these reference files to answer "how does WordPress work" questions without an API call:

• wordpress-guides/wordpress-architecture.md — file layout, DB tables, hook lifecycle, what each WP component does.
• wordpress-guides/rest-api-cookbook.md — canonical REST API calls organized by intent (content, ACF, SEO meta, media, users, settings, taxonomies).
• wordpress-guides/safety-rules.md — Safe / Confirm / Stop categories with examples, plus credential rotation.
• wordpress-guides/acf-guide.md — how ACF stores fields and how to read/write them via the REST API (acf payload key, ACF Pro defaults, fallback for un-REST-exposed groups).
• wordpress-guides/plugin-catalog.md — common WordPress plugins, what each stores, and how to talk to it over REST (which endpoints exist, which ones are commonly disabled).

For site-specific facts (active theme, installed plugins, registered CPTs, ACF groups, REST-exposed surfaces, workflows, gotchas, what's been done), read the docs in the site folder — the generated .wpm/docs/00–04 plus the curated project-notes.md + changelog.md at the top level.

Credentials — hard rules

• Never ask the user to paste the Application Password, an API token, or any secret into chat in any environment. Desktop / Cowork uses the bundled local connector handoff; Console uses a native OS dialog.
• Never read or echo the contents of any OS secret-store entry or the floor credential file. The only thing you ever do with the AP is pipe it through get_password() into the restcall auth FD (or the PSCredential on Windows).
• Never write secrets into config.json, any .wpm/docs/ file, or any file you control besides the dedicated born-private credential.
• Never run a secret-bearing script with bash -x, and never add set -x to one. Every such script runs set +x immediately after set -euo pipefail.
• The setup scripts (scripts/setup-*) and prompt-secret-* are the only places secrets are entered. On Console they go straight into the OS secret store via a native dialog (macOS writes over stdin, not -w); the password never passes through chat or any Claude-visible variable. On the floor tier the AP is written born-private (umask 077) and immediately git-checked.
• If a secret is leaked (printed, written, or pasted somewhere it shouldn't be), tell the user to rotate it — revoke in wp-admin, generate a new AP, re-store. The flow is in wordpress-guides/safety-rules.md → "Rotation."

Onboarding

First-run setup is environment-specific and follows EXACTLY ONE runbook. The connector, no-chat secret boundary, and ordering contracts below are immutable.

The connector

WordPress supplies the built-in authorize-application deep link:

{production_url}/wp-admin/authorize-application.php?app_name=norml-wp-manager-{site_name}

User clicks → logs into WP if needed → "Authorize norml-wp-manager-{site}?" → clicks Yes → copies the 24-character AP shown once. Console: the OS dialog captures it. Desktop / Cowork: the bundled local connect.html page captures it outside chat and writes a one-time credential.handoff; the importer locks the real credential, verifies authentication, runs the site scan, and deletes the handoff. Keep manual {url}/wp-admin/profile.php as a one-line fallback. No hosted success_url relay.

Explicitly REJECTED (recorded so no contributor re-adds):

• ✗ Hosted relay (e.g. connect.norml.studio catching success_url) — breaks 100%-self-contained on day one and routes a stranger's live WP credential through a third-party server. If Norml ever wants it, it's a separate, clearly-branded, opt-in product — never a dependency of this MIT skill.
• ✗ localhost auto-capture listener — unnecessary. The Desktop connector is a static local file with no network access of its own; WordPress authorization opens separately in the user's browser.

Console first-run (no gate) → onboarding-console.md

pick folder (+ collision / cloud-sync guard)
  → collect basics (site name / production URL / WP login slug)
  → CONNECTOR: one-click authorize deep link
  → OS DIALOG captures the AP (never chat)
  → assertive gitignore gate ONLY if floor tier
  → test connection (authenticated GET /wp/v2/users/me)
  → scan (00→04) ; scaffold README + project-notes + changelog
  → report what was created + SECURITY FLAGS

Desktop first-run (gate first) → onboarding-desktop.md

The immutable ordering contract — no Application Password is requested, generated, or written until the gate returns reachable:

NETWORK GATE (anon GET {site}/wp-json → allowlist fix → re-probe until 200)
  → collect site name / WP username / folder (+ collision / cloud-sync guard)
  → CONNECTOR: one-click authorize deep link
  → open bundled connect.html locally; paste the AP into that local-only form
  → choose the site folder; browser writes .wpm/credential.handoff + config + .gitignore without network access
  → import-desktop-handoff rewrites .wpm/credential born-private, verifies auth, and deletes the handoff
  → ASSERTIVE GITIGNORE GATE: if git present, `git check-ignore credential` MUST return it, else BACK OUT the secret + warn
  → authenticated GET /wp/v2/users/me  (now guaranteed to reach WP)
  → scan (00→04) ; generate capabilities.md ; scaffold README + project-notes + changelog
  → report what was created + SECURITY FLAGS
  → offer end-of-session AP revoke as the DEFAULT close-out

No half-written debris: credential is created only AFTER the gate returns 200 AND the auth check succeeds. If setup aborts mid-way, remove the empty .wpm/ scaffold — no stray folders or half-written password left behind.

Desktop secret handoff — no chat paste

Open the bundled connect.html in Chrome or Edge. It is a self-contained local file with network access disabled. The user pastes the Application Password into that local page and chooses the site folder; the page writes a short-lived .wpm/credential.handoff. The skill then runs scripts/import-desktop-handoff.sh or .ps1, validates the credential without echoing it, rewrites it with the platform's private-file controls, deletes the handoff, and runs the scan. If the runtime cannot use the local connector, hard-stop and route to a Console install; never downgrade to asking for the secret in chat.

Required post-setup SECURITY FLAGS (both environments)

State these as a deliverable at the end of both onboarding contracts:

1. (floor tiers only) plaintext-AP-on-disk reminder + rotation cadence.
2. admin-count > threshold ("N administrators is a lot for one site — consider trimming") — data from 04's HEAD …/users?roles=administrator.
3. any detected 3rd-party admin-level agent plugin (ManageWP-Worker, Jetpack, iThemes Sync, etc.) — cross-referenced from 03-plugins-theme.md.

Error handling

Fail loudly and stop. Do not improvise destructive recovery.

A 403/000 is TWO different failures — disambiguated by env + where the response came from. Never conflate them. Read against .wpm/docs/00-connection.md.

• Egress / allowlist (Desktop only). Signature: env=desktop AND any of — the response came from the sandbox proxy, not WordPress (no WP JSON body / proxy error / "blocked by your network egress settings"); OR an anon GET {site}/wp-json itself fails / 000 / curl exit 6/7/35/56; OR the gate was never cleared this session. → Fix = Settings → Capabilities → Domain allowlist. Never mention WP roles. Quick confirm: re-run the anon probe — if it ALSO fails → egress; if it returns 200 but the authenticated call 403s → capability.
• WordPress capability. Signature: network known-reachable (anon /wp-json returned 200) AND the 403 carries a real WP JSON body with a rest_* code (rest_cannot_edit, rest_forbidden). → Fix = use an editor/admin account for that endpoint. This is the ONLY place v2.3.0's "your WP user lacks the capability" message is correct.
• In Console an egress 403 is effectively impossible (open network) → a 403 there is always the capability kind.
• 401 Unauthorized → the Application Password is wrong, revoked, or belongs to a different user; the username must be the login slug (check {url}/wp-admin/profile.php). Don't retry — re-run the onboarding password step.
• 404 Not Found / rest_no_route on a known endpoint → the feature isn't exposed to REST (a CPT registered without show_in_rest, an ACF group without show_in_rest, or a plugin endpoint disabled by the host). Stop and explain; the scan should already have flagged it and the operate-phase gate should have caught the write before it fired.
• 5xx → host-side issue, often rate limiting. Don't retry blindly; suggest the user check their host's status page

…(truncated)