@wickedevolutions/abilities-mcp 1.5.4 → 1.6.1

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.6.1] - 2026-05-08
+
+Documentation update — README rewrite for OAuth-from-`.mcpb` recommended path + post-v1.5.0/v1.6.0 surface coverage. Code unchanged from v1.6.0.
+
+### Documentation
+
+- README rewritten to lead operators into the alpha-recommended OAuth path (Path 1: `.mcpb` install + `npm install -g @wickedevolutions/abilities-mcp` + `upgrade-auth` + `add-site` + `reauth --add-scope=`). OAuth was invisible in the v1.6.0 README despite being available since v1.5.0.
+- New CLI Reference section covering all subcommands: `add-site`, `reauth` (with the `--add-scope=` / `--remove-scope=` / `--scope=` triad), `revoke`, `list-sites`, `test`, `upgrade-auth`, `force-downgrade`, `self-check`. Plus global flags + exit-code table.
+- Multisite `wp-sites.json` example rewritten: dropped the stale `main` slug (which v1.6.0's [#70](https://github.com/Wicked-Evolutions/abilities-mcp/issues/70) explicitly removed from `add-site` generation), replaced with the dot-suffix routing model documentation.
+- macOS keychain note rewritten: `/usr/bin/security` is now the default backend on darwin under the `auto` setting per v1.6.0's [#61](https://github.com/Wicked-Evolutions/abilities-mcp/issues/61). Removed instruction to opt into `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli` (no longer needed).
+- New Notes section (replaces Known Limitations) covering: four-layer permissions model with the runtime-error-as-teacher pattern, paired ability classes architecture (`content-list-structure` ↔ `content-list`; `content-get-text` ↔ `content-get`), multisite OAuth subsite execution path, and session lock contention as the only remaining concrete product constraint.
+- Welcome section at top with verbatim *"Welcome, Wordpressnaut"* spaceship paragraph + 3 URL pointers (knowledge.wickedevolutions.com, wickedevolutions.com, abilitiesforai.io). Disclaimer block from J at the very top.
+- Pointer to [PRINCIPLES.md](PRINCIPLES.md) as the *Official WordPress Compatibility Contract* binding all four suite repos.
+- Architecture section updated to reflect both OAuth 2.1 + Application Password as transport options (was Application Password only).
+- Existing bottom *Disclaimer* section retired (replaced by J's disclaimer at the top).
+
+Closes [#74](https://github.com/Wicked-Evolutions/abilities-mcp/issues/74).
+
+## [1.6.0] - 2026-05-07
+
+### Fixed
+
+- **macOS keychain backend defaults to security-CLI for cross-runtime ACL identity (Issue [#61](https://github.com/Wicked-Evolutions/abilities-mcp/issues/61), Alpha Release Gate Phase B.2).** v1.5.5's [#58](https://github.com/Wicked-Evolutions/abilities-mcp/issues/58) shipped `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli` as an opt-in alignment, but the default `auto` backend still picked keytar in terminal / Claude Code contexts and security-CLI only in Claude Desktop's `.mcpb` runtime. Multi-client operator setups (Claude Desktop + Claude Code + Codex on the same workstation — the standard alpha install reality) saw a fresh macOS Keychain ACL prompt on every cross-runtime read, because each runtime's keychain syscall caller binary was a different ACL identity (system `node`, Codex's bundled `node`, `/usr/bin/security`). On darwin under the default `auto` backend, `KeychainSecretStore` now engages `/usr/bin/security` directly without attempting to load keytar. Every bridge spawn — Claude Desktop, Claude Code, Codex, terminal CLI — issues `SecKeychainItem*` calls through the same caller binary, so macOS's per-binary ACL trusted-application list contains exactly one entry. After the operator's first "Always Allow" the entry is silently readable from every runtime. The fix preserves least-privilege ACL semantics: no `-A` all-apps flag, no `-T` consumer-path additions, no broadening of the trusted-application set; the trusted set is *narrower* than today (one binary instead of N). Linux / win32 behavior unchanged (keytar via libsecret / Credential Manager — no analogous identity-split bug on those platforms).
+  - **Security CLI existence probe.** `_load()` now probes `/usr/bin/security` on first use and surfaces a typed `SecretStoreError` (`code: 'security_cli_unavailable'`) if absent, so corporate-locked or non-standard macOS hosts get a clear early diagnostic instead of an opaque execFile spawn failure on the first ability call.
+  - **`findAll()` darwin behavior:** `findAll()` is unavailable on the Darwin security-cli backend; current bridge flows do not rely on it. Linux / Windows (keytar) continue to enumerate normally.
+  - **Operator opt-out:** operators who need keytar on darwin (uncommon — debugging, custom build) can opt back in with `ABILITIES_MCP_KEYCHAIN_BACKEND=keytar`. Behavior matches v1.5.5: keytar is attempted, throws `SecretStoreError` (`code: 'keytar_unavailable'`) if it can't load.
+
+### Known limitations
+
+- **Existing macOS keychain entries written under v1.5.5 keytar may prompt once on first read under the new default (Issue [#61](https://github.com/Wicked-Evolutions/abilities-mcp/issues/61)).** v1.5.5 wrote OAuth and App Password entries via keytar in terminal / Claude Code contexts, so the entry's macOS Keychain ACL trusted-application list contains the system `node` binary, not `/usr/bin/security`. After upgrading, the first read by `/usr/bin/security` against an existing entry triggers a one-time ACL prompt — operators have **two recovery paths** (same shape as the v1.5.5 [#58](https://github.com/Wicked-Evolutions/abilities-mcp/issues/58) opt-in note): (1) click **Always Allow** at the prompt — the ACL is updated to add `/usr/bin/security` and no further prompts appear from any runtime, OR (2) re-run `abilities-mcp add-site --force <site>` / `abilities-mcp reauth <site>` to write a fresh entry under the new default backend. New entries written from this release forward never carry the legacy ACL state. The remaining one-time prompt is UX, not security: existing keychain ACLs continue to protect secrets correctly throughout.
+
+- **Multisite OAuth dot-notation routing is discovery-only in alpha (carried forward from v1.5.5; tracked on [#60](https://github.com/Wicked-Evolutions/abilities-mcp/issues/60)).** **Multisite discovery is available in alpha.** For OAuth subsite execution, add each subsite as a separate site entry using `add-site --site-id=<subsite-id>`. Use the explicit subsite IDs in your MCP client. Dot-notation subsite routing from a single network-root OAuth token is a known alpha limitation; a first-class fix is post-alpha design work tracked on [#60](https://github.com/Wicked-Evolutions/abilities-mcp/issues/60).
+
+- **Default OAuth grants are intentionally baseline-scoped.** `add-site` / `upgrade-auth` request a baseline scope set (`abilities:read`, `abilities:write`, `abilities:multisite:read`, `abilities:multisite:write`) that expands to common read/write categories. Operators who need delete-tier scopes, sensitive WordPress core scopes (`users`, `settings`, `filesystem`, `plugins`, `cron`, `themes`, `rewrite`), suite scopes (`astra`, `spectra`, `surecart`, `surecart-ecommerce`, `presto-player`), or Fluent suite scopes must request them explicitly with `add-site --scope="<list>"` at registration time or `reauth <site> --add-scope="<list>"` after OAuth. Scope expansion through `reauth --add-scope` is supported; an effective-permissions diagnostic feed is post-alpha.
+
+- **Full OAuth grant does not imply full execution. Abilities for AI module permissions remain an independent per-blog gate.** A granted OAuth scope is necessary but not sufficient to execute an ability. Abilities for AI's module permission settings (per-blog on multisite, configured at *Abilities for AI → Permissions* in wp-admin) gate execution independently — if a module's read/write/delete tier is disabled there, the OAuth-scope-bearing token will receive `[ability_disabled]` 403 errors with explicit operator remediation guidance, regardless of the granted scope set. The two gates apply together by design (Principle 5 — Permissions Stay Layered) to prevent AI sessions from escalating their own permissions via the OAuth surface.
+
+- **Pre-1.6.0 add-site runs may have written stale `main` aliases into multisite blocks of `wp-sites.json` (Issue [#70](https://github.com/Wicked-Evolutions/abilities-mcp/issues/70)).** v1.6.0 includes the fix that no longer generates `main` slugs, but existing `wp-sites.json` files written by earlier versions retain those keys and would silently route `<site>.main` to the source subsite instead of the network root. Operators upgrading from earlier versions: either re-run `add-site` against any affected subsite to regenerate its multisite block fresh under v1.6.0+ logic, or manually edit `~/.abilities-mcp/wp-sites.json` to remove the `"main": ...` entry from each affected `multisite` block. The `<site>.<network-root-domain-label>` slug (e.g., `wicked-community.wickedevolutions`) continues to route to the network root and remains the supported alias.
+
+
+## [1.5.5] - 2026-05-05
+
+### Fixed
+
+- **OAuth subsite routing actually targets the subsite host (Issue [#48](https://github.com/Wicked-Evolutions/abilities-mcp/issues/48), Public Alpha Hardening Phase A.1).** v1.5.4 wrote the `multisite` block on add-site but the OAuth dispatch path ignored the resolved subsite endpoint — every `<network-id>.<subsite-slug>` ability call was POSTed to the network root, so WordPress booted blog 1 regardless of which subsite was named. Three connected fixes:
+  - `lib/config.js:resolveSiteKey` now derives `resolvedEndpoint` for OAuth subsites (was HTTP/App-Password only). OAuth sites carry their endpoint on `mcp_resource`, not `http.endpoint`, so the substitution branch never fired for the OAuth case.
+  - `lib/connection-pool.js:_createTransport` passes `{ resolvedEndpoint, subsiteUrl: finalSubsiteUrl }` through to the OAuth branch, mirroring the HTTP branch's pattern. `_createOAuthHttpTransport` uses `resolvedEndpoint || siteConfig.mcp_resource` and forwards `subsiteUrl` to the transport.
+  - `lib/connection-pool.js:_findExistingHttpTransport` dedupes OAuth subsites by `resolvedEndpoint || mcp_resource` (was always `mcp_resource`). Without this, the cached network-root transport was returned for every subsite key, making the endpoint fix functionally inert behind the cache lookup.
+  - `lib/transports/oauth-http-transport.js` accepts `subsiteUrl` and forwards it on every POST as `X-Abilities-MCP-Subsite-URL`. Subdomain-style multisite (the alpha-locked scope) routes by host in the endpoint URL and does not need the header; it's forward-looking infrastructure for path-style multisite (Phase B) so the adapter can `switch_to_blog()` per request without re-parsing the request URL.
+- **Multisite probe pages through `multisite-list-sites` (Issue [#49](https://github.com/Wicked-Evolutions/abilities-mcp/issues/49), Public Alpha Hardening Phase A.2).** v1.5.4's `add-site` probe issued a single `multisite-list-sites` call with `per_page=100`, so networks with more than 100 sites silently got a truncated `multisite` block while `add-site` reported success. `lib/cli/multisite-probe.js` now loops `page=1..N` accumulating items across pages, terminating on the first of: empty page, partial page (length < `PROBE_PER_PAGE`), body-level `total` / `total_pages` reached, or the 50-page cap (`PROBE_PAGE_CAP × PROBE_PER_PAGE = 5,000` sites). When the cap is reached with a still-full final page, the probe throws a typed `Error` with `code === 'probe_cap_exceeded'` and `data: { count, cap }` so an operator hitting it gets a clean diagnostic rather than a silently-truncated block. The cap is a hard constant — no env shim — because >5,000-site networks are an exceptional case that should engage maintainers. Body-level `total` / `total_pages` (when the adapter exposes them) take precedence over the partial-page fallback to avoid one redundant page request when the last page is exactly full.
+- **Multisite auto-populate via `add-site` is now functional end-to-end on multisite-network OAuth setups (Issue [#54](https://github.com/Wicked-Evolutions/abilities-mcp/issues/54)).** Two bugs in `BearerJsonRpcClient` (the one-shot probe client distinct from the long-running MCP runtime transports) blocked auto-populate since v1.5.4: (a) the client did not echo the adapter's `Mcp-Session-Token` HMAC on requests after `initialize`, so the adapter's `HttpSessionValidator::validate_session()` correctly rejected the probe call as session-fixation defense; and (b) the probe sent the tool name `multisite/list-sites` (slash-case) but the adapter registers it as `multisite-list-sites` (kebab-case) — the session-token rejection masked the name mismatch until (a) was fixed. Both fixes required to deliver the v1.5.4 multisite-UX promise; the v1.5.4 auto-populate flow has shipped non-functional in production until this release. `BearerJsonRpcClient` now mirrors the long-running runtime transports' established session-token capture/echo pattern (see `lib/transports/http-transport.js:42-46, 442-447, 470-477`); the kebab-case tool name is verified against `tools/list` from the live adapter.
+- **`upgrade-auth` no longer corrupts config when the legacy keychain copy fails (Issue [#56](https://github.com/Wicked-Evolutions/abilities-mcp/issues/56)).** The App Password → OAuth migration's dual-write step swallowed keychain read/write errors but still rewrote the fallback `password_ref` to `<siteId>/apppassword-legacy`. If the keychain read was denied, hung, or failed (common during macOS cross-process ACL prompts), config could end up pointing at a legacy fallback secret that was never created. `lib/cli/commands/upgrade-auth.js` now only switches the fallback ref to `apppassword-legacy` after the legacy keychain copy actually succeeds; otherwise it preserves the original `password_ref` as the fallback and surfaces a stderr advisory naming what happened. Operators see a clean diagnostic rather than silent config corruption.
+- **macOS `security` CLI fallback has a 30s timeout (Issue [#57](https://github.com/Wicked-Evolutions/abilities-mcp/issues/57)).** The darwin-only fallback (introduced in v1.5.3 to bypass the hardened-runtime keytar barrier inside Claude Desktop's `.mcpb` host) shelled out to `security find-generic-password -w` with no timeout. Stuck macOS ACL prompts (common when multiple bridge consumer processes — Claude Desktop, Claude Code, terminal CLI — race for the same keychain entry) caused `upgrade-auth` and other CLI flows to hang indefinitely while additional bridge processes piled up more prompts. `lib/auth/keychain-secret-store.js` now wraps every `security` shell-out (`find`, `add`, `delete`) with a 30-second default timeout (configurable via constructor option). On timeout, surfaces a typed `SecretStoreError` with `code: 'security_cli_timeout'` and a message naming the situation, kills the child process, and lets the caller decide how to recover. CLI flows fail clean instead of hanging silently.
+- **macOS operators can opt into security-CLI keychain backend alignment (Issue [#58](https://github.com/Wicked-Evolutions/abilities-mcp/issues/58)).** Terminal `add-site` / `reauth` normally uses keytar when it loads successfully, while Claude Desktop's `.mcpb` runtime falls back to `/usr/bin/security` after macOS hardened-runtime rejects the native keytar module. That split can make Terminal write OAuth token entries through one macOS Keychain app identity and Claude Desktop read them through another, producing repeated cross-process ACL prompts. `KeychainSecretStore` now accepts `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli` (or constructor `backend: 'security-cli'`) on darwin so terminal setup can write tokens through the same backend Claude Desktop reads through. The setting is opt-in, macOS-only, and does **not** use the insecure `security -A` all-apps trust flag. Defaults remain unchanged (`auto` prefers keytar and falls back to security-CLI only when keytar fails on darwin).
+
+### Changed
+
+- **`reauth` scope-mutation flag triad replaces the bare `--scope` footgun (Issue [#50](https://github.com/Wicked-Evolutions/abilities-mcp/issues/50), Public Alpha Hardening Phase A.3).** The previous `reauth --scope=<list>` behavior *replaced* the persisted scope array — an operator (or AI assistant) adding new scopes via `--scope='<new only>'` would silently drop every existing scope. The locked design adds two new flags and keeps `--scope` as the explicit-replace escape hatch:
+  - `reauth <site> --add-scope=<scopes>` — merge into the existing scope set, deduped (preserves order: existing first, additions appended). The recommended way to add scopes.
+  - `reauth <site> --remove-scope=<scopes>` — drop scopes by exact match. Removals that aren't in the existing set are reported on stderr as no-op warnings, not errors.
+  - `reauth <site> --scope=<scopes>` — replace the entire scope set. Emits a stderr warning when the supplied set is a strict subset of the existing scopes (i.e., the replace would drop scopes), naming the count and recommending `--add-scope` instead.
+  - All three flags are **mutually exclusive** — passing more than one is a typed `EXIT_USAGE` error before the OAuth flow runs at all. Mirrors `git remote add` / `git remote remove` conventions; each flag has one job.
+  - Scope lists accept comma- or whitespace-separated tokens.
+  - Bare `reauth <site>` (no flag) continues to use the persisted scope set unchanged — no behavior change for the common refresh case.
+  - New pure module `lib/cli/scope-mutation.js` houses the parse / merge / remove / subset-detect logic so the reauth command stays a thin wrapper. CLI help output (`abilities-mcp --help`) documents all three flags + the mutual-exclusion rule.
+
+### Known limitations
+
+- **Existing macOS keychain entries may still carry old ACL state (Issue [#58](https://github.com/Wicked-Evolutions/abilities-mcp/issues/58)).** The new `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli` escape hatch aligns future Terminal OAuth writes with Claude Desktop's `.mcpb` reader backend, but it does not rewrite ACLs on entries that already exist in the operator's Keychain. If macOS is already showing a prompt, operators may still need to click **Always Allow**, kill a stale `SecurityAgent`, or rerun `add-site --force` / `reauth` with the env var so fresh token entries are written through the aligned backend. A fuller long-term design (explicit `-T` consumer-path list at write time, or canonical helper identity) remains a post-alpha improvement. The remaining cross-process gap is UX, not security: existing keychain ACLs continue to protect secrets correctly.
+- **Multisite OAuth dot-notation routing is discovery-only in alpha (Issue [#60](https://github.com/Wicked-Evolutions/abilities-mcp/issues/60)).** `add-site` against a Multisite Network root probes `multisite-list-sites` and writes the `multisite` slug→URL block to `wp-sites.json` (the v1.5.4 promise, end-to-end functional after the v1.5.5 fixes for [#48](https://github.com/Wicked-Evolutions/abilities-mcp/issues/48), [#49](https://github.com/Wicked-Evolutions/abilities-mcp/issues/49), [#54](https://github.com/Wicked-Evolutions/abilities-mcp/issues/54)). However, dot-notation execution against a subsite (e.g., `<network-id>.<subsite-slug>.<ability>`) routed by a single network-root OAuth token is rejected by the adapter at token validation: the adapter's `mcp_resource` check binds tokens to a specific blog URL, so a token minted against the network root cannot satisfy a subsite resource match even when the bridge has correctly switched the request endpoint and forwarded `X-Abilities-MCP-Subsite-URL`. Subsite execution **does** work today by adding each subsite as a separate site entry: `abilities-mcp add-site <subsite-id> https://<subsite-host>` (or, for path-style, `--site-id=<subsite-id>` against the subsite URL) provisions an OAuth token bound to that subsite's resource, and AI clients can then call abilities by the explicit subsite site_id. **Operator guidance:** Multisite discovery is available in alpha. For OAuth subsite execution, add each subsite that you want to operate on as a separate site entry using `--site-id`. Use the explicit subsite IDs in your MCP client. Dot-notation subsite routing from a single network-root OAuth token is a known alpha limitation. A first-class fix (network-root token + adapter-side per-blog `switch_to_blog()` validation, or first-class per-subsite token discovery) is tracked as a post-alpha design item on [#60](https://github.com/Wicked-Evolutions/abilities-mcp/issues/60).
+
+
 ## [1.5.4] - 2026-05-04
 
 This release lands the bridge-side foundations for the multisite UX promised in [#43](https://github.com/Wicked-Evolutions/abilities-mcp/issues/43). `add-site` now requests multisite OAuth scopes during DCR (so super-admin operators consent through the standard consent flow), runs a one-shot `multisite/list-sites` probe after OAuth completes, and on success writes a slug→subsite-URL `multisite` block to `wp-sites.json` so the bridge's existing dot-notation routing serves multi-site OAuth in any AI client without operator JSON editing. End-to-end dot-notation routing validated on darwin-arm64 against a 4-subsite multisite by manually populating the block from the verified `multisite/list-sites` response.

package/README.md

@@ -1,18 +1,33 @@
 # Abilities MCP
 
-> One MCP to Rule Your WordPress World.
+> **A word from J, the director of this creation.**
+>
+> Everything you see here is built by a single human who does not read or write code and is written by AI. Everything is in constant motion and by observing that movement we create the illusion of being still. Change happens at any given moment. It is simply a law of evolution. Stillness is an act of conscious awareness, not a reality of life.
 
-Open-source MCP bridge that connects any AI client to your WordPress sites through the [WordPress Abilities API](https://developer.wordpress.org/reference/functions/wp_register_ability/). Single STDIO server, multi-site routing, zero dependencies.
+## Welcome, Wordpressnaut
+
+Here is the spaceship, now you'll have to learn how to fly and please do remember, humans make mistakes, humans created AI so AI makes mistakes. Learning to fly is your job and to do that you'll need structure, systems, checklists, principles and understanding you stand before a magical leap of a steep and wonderful learning curve. Be patient and do backup things.
+
+→ Knowledge layer (deeper traversal): [https://knowledge.wickedevolutions.com](https://knowledge.wickedevolutions.com)
+→ [https://wickedevolutions.com](https://wickedevolutions.com)
+→ [https://abilitiesforai.io](https://abilitiesforai.io)
+
+Our development aim is the *Official WordPress Compatibility Contract* — see [PRINCIPLES.md](PRINCIPLES.md) for the full binding principles across the four-repo suite.
+
+---
+
+Open-source MCP bridge that connects any AI client to your WordPress sites through the [WordPress Abilities API](https://developer.wordpress.org/reference/functions/wp_register_ability/). Single STDIO server, multi-site routing, OAuth 2.1 or Application Password authentication, zero npm dependencies.
 
 ## Features
 
 - **Multi-site routing** — Single MCP server serves all your WordPress sites
+- **OAuth 2.1** — Dynamic Client Registration, PKCE, browser-loopback consent, keychain-backed tokens, automatic refresh, scope expansion
+- **Application Password** — Application Passwords with MCP session management (the legacy alpha-supported path; OAuth is recommended)
 - **Site parameter injection** — LLM sees a `site` enum on every tool, defaults to your primary site
 - **Lazy connections** — Sites connect on first use, not at startup
-- **HTTP transport** — Application Passwords with MCP session management
-- **WordPress multisite** — Subdomain/subdirectory multisites via dot notation (`site.blog`)
+- **WordPress multisite** — Subdomain-style multisite with cross-site routing through the dot-suffix model
 - **Auto-reconnect** — Exponential backoff, healthcheck pings, session recovery
-- **Zero dependencies** — Node.js built-in modules only
+- **Zero npm dependencies** — Node.js built-in modules only
 
 ## What You Can Do
 
@@ -23,17 +38,17 @@ The abilities available to your AI agent depend on which ability plugins you ins
 **Infrastructure** — filesystem, meta, REST discovery, knowledge layer
 **Third-party integrations** — auto-detected modules for supported plugins (Astra, Spectra, SureCart, Presto Player, and more)
 
-**[Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins)** is our continuously-enhanced third-party translator — bringing AI control to FluentCRM, FluentCommunity, FluentForms, FluentBooking, FluentSupport, FluentBoards, FluentSMTP, FluentAuth, FluentSnippets, FluentMessaging, FluentCart, and FluentAffiliate. We build and maintain it because we use Fluent's plugins ourselves and wanted them AI-native.
+**[Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins)** is our continuously-enhanced first-party translator — bringing AI control to FluentCRM, FluentCommunity, FluentForms, FluentBooking, FluentSupport, FluentBoards, FluentSMTP, FluentAuth, FluentSnippets, FluentMessaging, FluentCart, and FluentAffiliate. We build and maintain it because we use Fluent's plugins ourselves and wanted them AI-native.
 
 Beyond Fluent, the bridge is plugin-agnostic by design. Any plugin that registers abilities through the WordPress Abilities API becomes available automatically — no configuration in this bridge required. We urge every WordPress plugin developer to prioritize native Abilities API support over anything else.
 
-Every ability enforces `current_user_can()` at execution time — your WordPress role is the security boundary.
+Every ability enforces `current_user_can()` at execution time — your WordPress role is the security boundary, with OAuth scopes and the [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) per-module permission gate as additional layers above it (see [Notes — Four-layer permissions model](#four-layer-permissions-model)).
 
 > **Sign up for the Abilities for AI alpha release:** https://community.wickedevolutions.com/item/abilities-for-ai/
 
 ## Install
 
-There are three install paths. Pick the one that matches how you use AI clients.
+There are three install paths. Pick the one that matches how you use AI clients. **Path 1 (`.mcpb` for Claude Desktop, with the OAuth upgrade) is the recommended operator entry for the alpha.**
 
 ### Set up WordPress (required for all paths)
 
@@ -55,34 +70,75 @@ Go to **Users → Edit (your mcp-agent user) → Application Passwords**, enter
 | Role | Access | Use case |
 |------|--------|----------|
 | **Administrator** | All modules — content, plugins, themes, settings, users, cache, cron, filesystem, and more | Full site management |
-| **Editor** | Content, Blocks, Taxonomies, Patterns, Meta, Media | Content publishing workflows — safe for teams where AI should write but not configure |
+| **Editor** | Content, Blocks, Taxonomies, Patterns, Meta, Media | Content publishing workflows — safe for teams where AI writes but does not configure |
 
-> **Tip:** Start with Editor. Upgrade to Administrator when you need infrastructure abilities like plugin management, theme switching, or settings changes.
+> **Tip:** Start with Editor. Move to Administrator when you need infrastructure abilities like plugin management, theme switching, or settings changes.
 
 #### Required plugins
 
 Install both on your WordPress site:
 
 1. **[Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
-2. **[Abilities MCP Adapter](https://community.wickedevolutions.com/item/abilities-mcp-adapter/)** — exposes abilities as MCP tools via REST API
+2. **[Abilities MCP Adapter](https://community.wickedevolutions.com/item/abilities-mcp-adapter/)** — exposes abilities as MCP tools via REST API and runs the OAuth 2.1 resource server + authorization server
 
 Both are available as free downloads from our store, or install from GitHub: [abilities-for-ai](https://github.com/Wicked-Evolutions/abilities-for-ai) and [abilities-mcp-adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter).
 
 ---
 
-### Path 1 — `.mcpb` bundle for Claude Desktop (recommended)
+### Path 1 — `.mcpb` bundle for Claude Desktop with OAuth upgrade (recommended)
+
+The full alpha-recommended operator path: install the `.mcpb` for single-click Claude Desktop integration, then upgrade in place to OAuth so tokens live in your OS keychain (macOS Keychain / Windows Credential Manager) and refresh automatically.
 
-Single-click install for Claude Desktop on macOS and Windows. The Application Password is stored encrypted in your OS keychain (macOS Keychain / Windows Credential Manager).
+#### Step 1 — install the `.mcpb` (Application Password baseline)
 
 1. Download `abilities-mcp.mcpb` from the [latest GitHub Release](https://github.com/Wicked-Evolutions/abilities-mcp/releases/latest).
 2. Double-click the file. Claude Desktop opens an "Install Extension" dialog.
 3. Type three things:
    - **WordPress Site URL** — `https://example.com`
    - **WordPress Username** — `mcp-agent`
-   - **Application Password** — paste the password from the previous step
-4. Click **Install**. The connection is live.
+   - **Application Password** — paste the password from the WordPress setup step
+4. Click **Install**. The connection is live with an Application Password.
+
+The bundle covers the single-site case. To unlock OAuth, multi-site, and the `add-site` / `reauth` / `revoke` / `list-sites` / `test` operator flows, continue to Step 2.
+
+#### Step 2 — install the CLI globally for OAuth and multi-site flows
 
-The bundle covers the single-site case. For multi-site (one bridge connected to several WordPress sites at once), use Path 3.
+```bash
+npm install -g @wickedevolutions/abilities-mcp
+```
+
+This puts the `abilities-mcp` command on your PATH so you can run the OAuth subcommands from a terminal.
+
+#### Step 3 — upgrade your Claude Desktop site to OAuth in place
+
+```bash
+abilities-mcp upgrade-auth <site>
+```
+
+This runs the OAuth 2.1 authorization-code flow with PKCE in your default browser, mints fresh tokens, writes them to your OS keychain, and updates `~/.abilities-mcp/wp-sites.json` so the existing Claude Desktop "Abilities MCP" entry now uses OAuth. The Application Password fallback stays in place until you confirm with `--confirm` in a follow-up `upgrade-auth` run.
+
+#### Step 4 — add additional sites (OAuth by default)
+
+```bash
+abilities-mcp add-site https://second-site.com
+abilities-mcp add-site https://third-site.com --label="My Staging Site"
+```
+
+Each added site provisions OAuth via Dynamic Client Registration, runs the consent flow in your browser, and persists tokens to the keychain. New sites surface through the same Claude Desktop "Abilities MCP" entry — no Claude Desktop config edit needed.
+
+For App Password sites instead of OAuth (legacy path), pass `--apppassword --username=<user> --password=<pw>`.
+
+#### Step 5 — expand scopes when broader powers are needed
+
+Default OAuth grants are baseline-scoped — they cover the common read/write categories (`abilities:read`, `abilities:write`, `abilities:multisite:read`, `abilities:multisite:write`). For delete-tier operations, sensitive WordPress core categories (`users`, `settings`, `filesystem`, `plugins`, `cron`, `themes`, `rewrite`), suite scopes (`astra`, `spectra`, `surecart`, `surecart-ecommerce`, `presto-player`), or Fluent suite scopes, extend explicitly:
+
+```bash
+abilities-mcp reauth <site> --add-scope="abilities:users:delete abilities:settings:write"
+```
+
+The `--add-scope=` flag merges the new scopes into the existing set (deduped, order-preserved). Use `--remove-scope=` to drop scopes by exact match, or `--scope=` to replace the entire set (warns if dropping any). The three flags are mutually exclusive.
+
+**macOS keychain note (since v1.6.0).** On macOS, the bridge uses `/usr/bin/security` as its keychain backend by default under the `auto` backend setting. Every bridge spawn — Claude Desktop, Claude Code, Codex, terminal CLI — issues keychain syscalls through the same caller binary, so macOS's per-binary ACL trusted-application list contains exactly one entry. After your first "Always Allow" the entry reads silently from every runtime. If you upgraded from v1.5.x and Claude Desktop repeatedly asks for keychain access, click **Always Allow** once at the prompt OR run `abilities-mcp add-site --force <site>` / `abilities-mcp reauth <site>` to write a fresh entry under the unified backend.
 
 ---
 
@@ -111,7 +167,7 @@ In your client's MCP config:
 }
 ```
 
-The endpoint is auto-derived as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Single-site only — for multi-site, use Path 3.
+The endpoint is auto-derived as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Single-site, Application Password only — for OAuth or multi-site, use Path 1 or Path 3.
 
 For `claude mcp add` users:
 
@@ -127,7 +183,7 @@ claude mcp add wordpress \
 
 ### Path 3 — `wp-sites.json` (multi-site, power users)
 
-Use this when you connect one bridge to multiple WordPress sites, when you want passwords sourced from a keychain or shell command, or when you're targeting WordPress multisite networks via dot-notation routing.
+Use this when you want passwords sourced from a keychain or shell command without going through the OAuth provisioning flow, when you're connecting one bridge to multiple WordPress sites with hand-curated config, or when you're targeting WordPress multisite networks with explicit per-subsite entries.
 
 ```bash
 cp wp-sites.example.json wp-sites.json
@@ -161,6 +217,37 @@ For Claude Desktop, you can also auto-register:
 node abilities-mcp.js --register
 ```
 
+## CLI Reference
+
+Once `@wickedevolutions/abilities-mcp` is installed globally (or you run `node abilities-mcp.js <subcommand>` from a clone), the following subcommands are available:
+
+| Subcommand | What it does | Common flags |
+|------------|--------------|--------------|
+| `add-site <url>` | Register a new site (OAuth by default) | `--apppassword` `--username=` `--password=` `--scope=` `--site-id=` `--label=` `--force` |
+| `reauth <site_id>` | Re-run the OAuth flow for an existing site | `--add-scope=` (recommended) · `--remove-scope=` · `--scope=` (mutually exclusive) |
+| `revoke <site_id>` | Revoke OAuth tokens (local + remote) | — |
+| `list-sites` | Show configured sites + auth status | — |
+| `test <site_id>` | Ping the adapter and report scopes | — |
+| `upgrade-auth <site_id>` | Migrate an existing Application Password site to OAuth in place | `--confirm` (Step 4: drop the App Password fallback after OAuth is verified) |
+| `force-downgrade <site_id>` | Override OAuth pinning (escape hatch for capability-pin failure) | `--i-understand-the-risk` (required) · `--reason="<text>"` |
+| `self-check <site_id>` | Probe Authorization-header survival end-to-end | — |
+
+Bare `abilities-mcp` (no subcommand) starts the MCP STDIO server — the mode every MCP client config invokes.
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--config=<path>` | Path to `wp-sites.json` |
+| `--debug` | Include cause stack on errors; debug logging to `/tmp/abilities-mcp.log` |
+| `--allow-insecure` | Allow plain HTTP (localhost dev only) |
+| `--register` | Register in Claude Desktop config |
+| `--name=<name>` | Server name for `--register` (default: `wordpress`) |
+
+### Exit codes
+
+`0` success · `1` unexpected error · `2` usage error · `3` config error · `4` auth failure · `5` capability-pinning violation
+
 ## Configuration
 
 ### `wp-sites.json`
@@ -183,6 +270,8 @@ node abilities-mcp.js --register
 }
 ```
 
+OAuth-managed sites added through `abilities-mcp add-site` are written to `~/.abilities-mcp/wp-sites.json` automatically — they carry an `auth.method: "oauth"` block with keychain references rather than inline secrets.
+
 ### Config search order
 
 1. `--config=/path/to/wp-sites.json` (explicit)
@@ -195,7 +284,9 @@ The first one found wins. If a `wp-sites.json` exists, env vars are ignored.
 
 ### WordPress Multisite
 
-For WordPress multisites, add a `multisite` object mapping subsite keys to their URLs:
+For WordPress multisite networks, OAuth multi-site is provisioned through `abilities-mcp add-site --site-id=<subsite-id> https://<subsite-host>` for each subsite you want to operate on. Each subsite provisions its own OAuth token bound to that subsite's resource. Use the explicit subsite IDs in your MCP client.
+
+For App Password multisite (Path 3 hand-curated config), add a `multisite` object mapping subsite slugs to their URLs:
 
 ```json
 {
@@ -208,15 +299,15 @@ For WordPress multisites, add a `multisite` object mapping subsite keys to their
       "passwordCommand": "security find-generic-password -a mcp-agent -s example.com -w"
     },
     "multisite": {
-      "main": "https://example.com/",
       "blog": "https://blog.example.com/",
-      "shop": "https://shop.example.com/"
+      "shop": "https://shop.example.com/",
+      "example": "https://example.com/"
     }
   }
 }
 ```
 
-Use dot notation to target subsites: `"site": "network.blog"`
+Use the dot-suffix routing pattern to target subsites: `"site": "network.blog"`. The bare bridge name (`"site": "network"`) routes to the bridge's own root; the dot suffix routes cross-site through the same adapter. The recommended cross-site context naming uses the network root's domain label (e.g., `wickedevolutions` for `wickedevolutions.com`) — `abilities-mcp add-site` against a Multisite Network root populates this automatically per the dot-suffix model.
 
 ### Secure password storage
 
@@ -286,7 +377,7 @@ export WP_MCP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"
 WP_MCP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
 ```
 
-The bridge reads `process.env.WP_MCP_PASSWORD` at connection time. If the variable is not set, it throws an error immediately.
+The bridge reads `process.env.WP_MCP_PASSWORD` at connection time. If the variable is not set, it surfaces an error immediately.
 
 #### `password` (not recommended)
 
@@ -330,25 +421,15 @@ When multiple sites are configured, every tool gets an optional `site` parameter
 }
 ```
 
-Omit `site` to use the default site.
-
-## CLI Options
-
-| Flag | Description |
-|------|-------------|
-| `--config=<path>` | Path to wp-sites.json |
-| `--server=<name>` | MCP adapter server name |
-| `--debug` | Enable debug logging to `/tmp/abilities-mcp.log` |
-| `--register` | Register in Claude Desktop config |
-| `--name=<name>` | Server name for `--register` (default: `wordpress`) |
+Omit `site` to use the default site. For multisite networks, the `site` enum surfaces both the bare bridge name and the dot-suffix cross-site contexts (e.g., `network`, `network.blog`, `network.shop`).
 
 ## Architecture
 
 ```mermaid
 graph TD
     Client[AI Client<br/>Claude Code · Gemini CLI · Cursor · any MCP client] -->|STDIO| Bridge[Abilities MCP]
-    Bridge -->|HTTP POST| SiteA[Site A]
-    Bridge -->|HTTP POST| SiteB[Site B]
+    Bridge -->|OAuth 2.1 / HTTP POST| SiteA[Site A]
+    Bridge -->|App Password / HTTP POST| SiteB[Site B]
     Bridge -->|SSH + WP-CLI| SiteC[Site C]
 
     subgraph "Each WordPress Site"
@@ -358,35 +439,56 @@ graph TD
 ```
 
 - One STDIO process handles all sites through a unified connection pool
-- **HTTP transport** — Application Passwords with MCP session management, batch coalescing, auto-reconnect
+- **OAuth 2.1 transport** — Bearer tokens with automatic refresh, keychain-backed persistence, scope expansion via `reauth --add-scope=`
+- **Application Password transport** — HTTP Basic with MCP session management, batch coalescing, auto-reconnect
 - **SSH transport** — WP-CLI over SSH tunnel, healthcheck pings, handshake replay
 - Lazy connections — non-default sites connect on first tool call
 - Tool list comes from the default site with `site` enum injected
 - Permission metadata (`permission`, `enabled`) flows through annotations to the LLM
 - Error responses include `input_schema` for AI self-correction
 
-See [docs/architecture.md](docs/architecture.md) for the full technical deep dive — transport comparison tables, session management, multi-site routing internals, and security model.
+See [docs/architecture.md](docs/architecture.md) for the full technical deep dive — transport comparison tables, session management, multi-site routing internals, OAuth state machine, and security model.
+
+## Notes
+
+### Four-layer permissions model
+
+When an ability is denied, the rejection comes from one of four independent layers. The runtime error names the layer:
+
+1. **Abilities for AI module permission** — per-blog read/write/delete toggle in *WP Admin → Abilities for AI → Permissions*. The runtime returns `[ability_disabled]` with the module name and where to fix it. (Fix in *Abilities for AI → Permissions*.)
+2. **WordPress capability** — the WordPress user the bridge authenticates as lacks the relevant capability. WordPress core REST returns `rest_forbidden` / `rest_cannot_*` codes. (Fix by granting the cap to the user, or use a higher-privilege user.)
+3. **OAuth scope** — the bridge's OAuth token does not include the scope the ability requires. The adapter returns an `insufficient_scope` rejection. (Fix with `abilities-mcp reauth <site> --add-scope="<scope>"`.)
+4. **Unclear** — generic 500, timeout, or malformed response. Check server logs.
+
+The four gates apply together by design (see [PRINCIPLES.md](PRINCIPLES.md), Principle 5 — *Permissions Stay Layered*). The runtime error tells you which gate fired so you can act at the right layer.
+
+### Paired ability classes
 
-## Known Limitations
+The product ships compact-vs-full pairs across the API by design. Pick the pair member that matches the traversal you intend:
 
-- **Session lock contention** ([#4](https://github.com/Wicked-Evolutions/abilities-mcp/issues/4)) — Concurrent bridge instances targeting the same site can cause session loss. Use a single bridge process per site.
+- `content-list-structure` (id/title/slug/status/date/link, ~0.5KB/post) ↔ `content-list` (full block markup, ~50–200KB/post). Use `content-list-structure` for bulk discovery; use `content-list` for targeted full inspection.
+- `content-get-text` (plain text stripped, ~2–20KB) ↔ `content-get` (full block markup, ~50–200KB). Use `content-get-text` when you want the readable content; use `content-get` when you need the block structure.
+
+Each ability description names its payload tradeoff. The pattern recurs across other categories — read the description before reaching for the heavy member when a compact member is available.
+
+### Multisite OAuth subsite execution
+
+For WordPress multisite networks under OAuth, add each subsite you want to operate on as a separate site entry: `abilities-mcp add-site --site-id=<subsite-id> https://<subsite-host>`. Each subsite provisions its own OAuth token bound to that subsite's resource by the adapter's `mcp_resource` check. Use the explicit subsite IDs in your MCP client. Tracked on [#60](https://github.com/Wicked-Evolutions/abilities-mcp/issues/60) for further iteration.
+
+### Session lock contention ([#4](https://github.com/Wicked-Evolutions/abilities-mcp/issues/4))
+
+Concurrent bridge instances targeting the same site can cause session loss. Use a single bridge process per site.
 
 ## Requirements
 
 - Node.js >= 18
 - WordPress 6.9+ with [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
-- Application Passwords enabled (default in WordPress 5.6+)
+- Application Passwords enabled (default in WordPress 5.6+) for the App Password path; OAuth path needs no additional setup beyond the adapter
 
 ## Evolving Knowledge
 
 We continuously add knowledge docs, skills, and agent patterns to [knowledge.wickedevolutions.com](https://knowledge.wickedevolutions.com).
 
-## Disclaimer
-
-Humans make mistakes — as we know from the present day and history. Humans trained AI. AI acts accordingly. AI predicts probability based on the context window it holds. It is trained to sound certain, as if everything is truth, and to "fix" everything so the human becomes satisfied.
-
-Learn how to communicate with AI. You are fully responsible for using AI in your life, business, and projects. Using these products is your personal responsibility to learn and own.
-
 ## License
 
 GPL-2.0-or-later