@wickedevolutions/abilities-mcp 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.6.2] - 2026-05-10
+
+Schema validity polish + boot fragility MVP + multisite topology gate. Four Bridge fixes ship together as a bundled release closing the operator-side schema-400 + the silent-bridge-death-on-expired-refresh-token (both connect-time and request-time refresh boundaries) + the misplaced-multisite-block-cross-product issues.
+
+### Fixed
+
+- **Sanitizer defensively normalizes broken `inputSchema` (Issue [#78](https://github.com/Wicked-Evolutions/abilities-mcp/issues/78)).** `sanitizeToolsList` in `lib/sanitizer.js` now coerces non-object `inputSchema` values (`[]` / `null` / `undefined` / primitives) to `{ type: 'object' }` before forwarding `tools/list` responses. The previous behavior detected non-object schemas via a warn-only log path but forwarded the broken schema unchanged, allowing the Anthropic API to reject the entire request with `400 tools.N.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12`. Companion source-of-truth fix in [abilities-for-fluent-plugins#41](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins/issues/41) (v1.1.3); shipping both as defense-in-depth — either fix alone closes the operator-side 400, the bridge-side normalization absorbs any future upstream registry bug regardless of source plugin. Valid object `inputSchema` values pass through byte-identical (regression-guarded with reference-equality assertion in `test/sanitizer.test.js`).
+
+- **Per-site auth-init isolation prevents silent bridge death on expired refresh token — connect-time AND request-time boundaries (Issue [#76](https://github.com/Wicked-Evolutions/abilities-mcp/issues/76), Schema Validity Polish Sprint Phase B Wave 2 + Wave 2.5).** Pre-1.6.2, the bridge's `pool.connectDefault()` exited the entire process via `process.exit(1)` when the default site's refresh token was expired (or any other auth-init failure on the default site). MCP clients saw EOF on bridge stdout, the JSON-RPC SDK reported the `initialize` response missing required fields (`protocolVersion` / `capabilities` / `serverInfo`), and the runtime became unreachable with no actionable error message — operators had to recover manually via `abilities-mcp reauth <site>` or direct `wp-sites.json` edit. v1.6.2 fixes this at TWO refresh boundaries:
+  - **Connect-time boundary (Wave 2 / PR #81):** per-site try/catch isolation now lives at the auth-init boundary in `lib/connection-pool.js`; one site's expired refresh token (or any per-site connect failure) no longer propagates to bridge-wide exit. Healthy sites' tools remain fully usable. Degraded sites are surfaced through three channels: (i) `tools/list` annotations on the bridge-only `wp_bridge_health` tool, (ii) per-call errors when an operator attempts a tool against a degraded site, (iii) the dedicated `wp_bridge_health` tools/call shape for explicit per-site health querying. The `process.exit(1)` paths in `abilities-mcp.js` bootstrap now fire only on bridge-level bugs (e.g., schema migration failure), never on per-site auth state.
+  - **Request-time boundary (Wave 2.5 / PR #82):** when `transport.connect()` succeeds (transport object created without validating tokens) but the cached `initialize` request gets forwarded and triggers a lazy `refresh()` on first use that fails, the OAuth error was previously wrapped in `CallToolResult` shape (`content[]` + `isError: true`) per the OAuth-error-handling convention — invalid response shape for an `initialize` request, SDK rejects, bridge appears unreachable. `lib/router.js` `handleTransportMessage` now intercepts error responses whose `id` matches the cached `initialize` request, synthesizes a valid `InitializeResult` with all three required fields, and enters degraded mode (reusing the same `enterDegradedMode` plumbing introduced by Wave 2). Live-verified against the operator's actual reproduction shape; pre-fix control output is byte-equivalent to the operator's captured failure. Both connect-time AND request-time refresh failures now produce valid `InitializeResult` responses.
+  - Healthy-site-only boot path is byte-equivalent to pre-fix (regression-guarded with explicit "all-healthy still boots correctly" tests). Together these two fixes close the silent-bridge-death failure mode for the most common operator state — multi-site setup with one site's refresh token aged out, regardless of which OAuth-refresh boundary the failure surfaces at.
+
+- **Multisite probe gates `add-site` block writes on detected-network-root (Issue [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77), Schema Validity Polish Sprint Phase B Wave 2 — gate side).** Pre-1.6.2, `add-site` against a subsite URL ran an unconditional post-OAuth `multisite/list-sites` probe and wrote a multisite block on the subsite's wp-sites.json entry (regardless of whether the URL was a network root or a subsite). For multi-subsite operators who ran `add-site` on each of N subsites independently, this produced N misplaced multisite blocks generating N×N dot-notation cross-products at the MCP tool surface (e.g., a 4-blog network seen via 4 subsite-rooted blocks produces 16 dot-notation site aliases instead of the correct 4 routes from the network root). `lib/cli/multisite-probe.js` now gates `buildMultisiteBlock()` write on detected-network-root verification; subsite URLs skip the block write and emit an operator message redirecting to the network-root URL. Future `add-site` invocations on subsite URLs no longer re-introduce the cross-product noise.
+
+- **Boot-time auto-migration cleans existing misplaced multisite blocks (Issue [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77) — migrate side).** Operators upgrading from pre-1.6.2 with existing wrong wp-sites.json state get auto-recovery on next bridge boot — no manual `abilities-mcp reauth` or wp-sites.json edit required. `migrateMisplacedMultisiteBlocks` in `lib/config.js` runs as part of `loadConfig` on every bridge startup (idempotent — second boot finds nothing to migrate). The migration scans persisted multisite blocks and drops subsite-entry blocks **only** when the network root for that domain is also configured; if the network root is absent, the subsite-entry block is left intact (operators may need it for dot-notation routing until they add the network-root URL via `add-site`). Operators who had been seeing N×N dot-notation cross-products (e.g. 15 sites for a 4-subsite multisite + 2 standalone sites) see clean enumeration after upgrade (e.g. 6 sites total — 4 distinct subsites + 2 standalone). Tests cover three migration paths: subsite-skip-on-add, migration-with-network-root-present (drops the misplaced block), migration-with-network-root-absent (no-op preserves block). Live-verified against operator wp-sites.json on first invocation of v1.6.2 npm-linked bridge: three subsite-rooted multisite blocks dropped (wicked-community, wicked-test1, wicked-knowledge); operator-visible diagnostic output emitted; site enumeration dropped from 15 to 6.
+
+### Compatibility & operator notes
+
+- **All four Bridge fixes ship together** as a single coordinated release per the Schema Validity Polish Sprint v2.2 marketing-launch coupling. Marketing-launch authorization (per the sprint plan) is gated on three smoke checks against an operator-approved test target: (i) Fluent-scoped reconnect produces no 400, (ii) bridge boots and serves valid InitializeResult when ≥1 configured site has expired refresh token (BOTH connect-time AND request-time refresh boundaries verified), (iii) multi-subsite multisite operator sees clean enumeration after upgrade.
+- **No protocol semantics change** for any of the four fixes. Healthy operators on single-site or correctly-configured network-root multisite see no behavioral difference. The fixes activate only on the failure modes they close.
+- **No operator action required** — schema-validity defense (#78), boot-fragility recovery at both refresh boundaries (#76), and multisite-block migration (#77) are all passive on next bridge restart.
+
+### Out of scope (deferred)
+
+- Bridge Boot Fragility research draft surfaces other than #76 + #77 — auth lifecycle redesign (Surface 1 beyond per-site try/catch isolation + request-time refresh-error interception), multi-client coordination races (Surface 3), broader multisite probe architecture (Surface 4 fix-shape-#4), test coverage gap remediation (Surface 5), broader operator-state migrations (Surface 6 beyond multisite-block migration), README troubleshooting section (Surface 7) — deferred to a future sprint.
+
+Closes [#76](https://github.com/Wicked-Evolutions/abilities-mcp/issues/76). Closes [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77). Closes [#78](https://github.com/Wicked-Evolutions/abilities-mcp/issues/78).
+
+## [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

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,42 +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)
 
-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).
+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.
+
+#### 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
+
+```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
 
-The bundle covers the single-site case. For multi-site (one bridge connected to several WordPress sites at once), use Path 3.
+```bash
+abilities-mcp upgrade-auth <site>
+```
 
-**macOS + Claude Desktop keychain note.** Claude Desktop's `.mcpb` runtime may use Apple's `/usr/bin/security` keychain path when macOS rejects native keytar loading. If you set up OAuth from Terminal and then Claude Desktop repeatedly asks for Keychain access, rerun the terminal setup with the same backend Claude Desktop uses:
+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_KEYCHAIN_BACKEND=security-cli abilities-mcp add-site --force https://example.com
+abilities-mcp add-site https://second-site.com
+abilities-mcp add-site https://third-site.com --label="My Staging Site"
 ```
 
-This is macOS-only and opt-in. It does not loosen Keychain permissions; it just writes tokens through the same Keychain doorway Claude Desktop reads through.
+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.
 
 ---
 
@@ -119,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:
 
@@ -135,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
@@ -169,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`
@@ -191,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)
@@ -203,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
 {
@@ -216,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
 
@@ -294,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)
 
@@ -338,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"
@@ -366,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
+
+The product ships compact-vs-full pairs across the API by design. Pick the pair member that matches the traversal you intend:
 
-## Known Limitations
+- `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.
 
-- **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.
+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

package/abilities-mcp.js

@@ -212,15 +212,42 @@ if (!isSubcommandInvocation) {
     // Startup — connect to default site
     // -----------------------------------------------------------------------
 
+    // Issue #76: per-site auth-init isolation. `pool.connectDefault` tries the
+    // configured default first and falls back to other configured sites on a
+    // per-site failure (typically RefreshError when refresh tokens expire).
+    // Returns the connected transport, or null when ALL sites failed — in
+    // that case the bridge enters degraded mode (router synthesizes a valid
+    // InitializeResult locally, returns bridge tools only on tools/list, and
+    // surfaces per-call errors on non-bridge tools/call) instead of dying
+    // with the malformed-InitializeResult / EOF symptom that motivated #76.
     try {
       const transport = await pool.connectDefault((parsedMsg, rawLine) => {
         router.handleTransportMessage(parsedMsg, rawLine);
       });
-      router.setDefaultTransport(transport);
-      log(`Default transport connected: ${config.defaultSite}`);
+      if (transport) {
+        router.setDefaultTransport(transport);
+        log(`Default transport connected: ${config.defaultSite}`);
+      } else {
+        const degradedSites = Object.entries(config.sites).map(([siteId, site]) => ({
+          siteId,
+          reason: (site && site._degraded_reason) || 'connect failed',
+        }));
+        process.stderr.write(
+          `abilities-mcp: all configured sites failed to connect at boot — ` +
+          `entering degraded mode. Operators can call wp_bridge_health to see ` +
+          `per-site status; reauth a site to recover.\n`
+        );
+        for (const ds of degradedSites) {
+          process.stderr.write(`  - ${ds.siteId}: ${ds.reason}\n`);
+        }
+        router.enterDegradedMode(degradedSites);
+      }
       router.drainEarlyQueue();
     } catch (err) {
-      process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
+      // Reached only on non-per-site errors (bug in connectDefault itself,
+      // or a thrown synchronous error during bootstrap). Per-site failures
+      // are handled inside connectDefault and never surface here.
+      process.stderr.write(`abilities-mcp: bootstrap failed unexpectedly: ${err.message}\n`);
       process.exit(1);
     }
 

package/lib/cli/commands/add-site.js

@@ -222,6 +222,23 @@ async function run(args, ctx) {
         config.sites[siteId].multisite = probeResult.block;
         const slugs = Object.keys(probeResult.block).join(', ');
         out.push(`  Multisite: discovered ${Object.keys(probeResult.block).length} subsite(s) → ${slugs}`);
+      } else if (probeResult && probeResult.reason === 'subsite-not-root') {
+        // Issue #77: the operator's URL is a subsite of a multisite network,
+        // not the network root. Writing a multisite block from the subsite's
+        // perspective produces parallel cross-product blocks at the MCP tool
+        // surface — so we skip the block write and redirect the operator to
+        // the network-root URL where dot-notation routing belongs.
+        const rootUrl = probeResult.networkRootUrl;
+        const redirect = rootUrl
+          ? `Run: abilities-mcp add-site ${rootUrl}`
+          : 'Re-run add-site with the network-root URL.';
+        errLines.push(
+          `Multisite block not written for "${siteId}": this URL is a subsite, not the ` +
+          `network root${rootUrl ? ` (${rootUrl})` : ''}. Dot-notation routing belongs on ` +
+          `the network-root entry; subsite-rooted blocks describe the network from one ` +
+          `subsite's perspective and surface N×(N-1) cross-products at the MCP tool ` +
+          `surface. Site entry written without multisite block. ${redirect}`
+        );
       }
     } catch (probeErr) {
       _appendProbeAdvisory(probeErr, siteId, errLines);

package/lib/cli/multisite-probe.js

@@ -34,9 +34,14 @@ const PROBE_PAGE_CAP = 50;
 /**
  * @typedef {object} ProbeResult
  * @property {object|null} block      Multisite block, or null when no block
- *                                    should be written (single-site / empty).
+ *                                    should be written (single-site / empty /
+ *                                    subsite-not-root).
  * @property {string} reason          One of: 'multisite-root', 'single-site',
- *                                    'tool-not-registered', 'empty-list'.
+ *                                    'tool-not-registered', 'empty-list',
+ *                                    'subsite-not-root'.
+ * @property {string} [networkRootUrl] Set when reason === 'subsite-not-root'
+ *                                    so callers can emit an operator message
+ *                                    redirecting to the network-root URL.
  */
 
 /**
@@ -144,6 +149,21 @@ async function probeMultisite(opts) {
     return { block: null, reason: 'single-site' };
   }
 
+  // Issue #77: gate block write on detected-network-root.
+  // Without this gate, OAuth super-admin invocations from a subsite URL get
+  // the full network's site list back from multisite/list-sites and write a
+  // subsite-rooted block that describes the network from the subsite's
+  // perspective — surfacing N×(N-1) dot-notation cross-products at the MCP
+  // tool surface (one parallel block per subsite entry).
+  const rootCheck = detectNetworkRoot(siteUrl, items);
+  if (!rootCheck.isRoot) {
+    return {
+      block: null,
+      reason: 'subsite-not-root',
+      networkRootUrl: rootCheck.networkRootUrl,
+    };
+  }
+
   const block = buildMultisiteBlock(siteUrl, items);
   if (!block || Object.keys(block).length === 0) {
     return { block: null, reason: 'empty-list' };
@@ -151,6 +171,55 @@ async function probeMultisite(opts) {
   return { block, reason: 'multisite-root' };
 }
 
+/**
+ * Detect whether `parentSiteUrl` points at the network root of the multisite
+ * list returned by `multisite/list-sites`. Pure function — no I/O.
+ *
+ * Primary signal: the canonical WordPress network-root marker `blog_id === 1`.
+ * When that item exists, parent IS the root iff its URL origin matches.
+ *
+ * Fallback (no blog_id metadata): parent IS the root iff any item's URL
+ * origin matches `parentSiteUrl`. This is conservative — it accepts the
+ * pre-#77 behavior whenever we can't positively identify a non-root
+ * invocation, so an exotic adapter that omits `blog_id` doesn't lose probe
+ * functionality. The new gate fires only when we have positive evidence
+ * (blog_id===1 present and pointing elsewhere, or no URL match at all).
+ *
+ * @param {string} parentSiteUrl
+ * @param {Array<object>} items
+ * @returns {{ isRoot: boolean, networkRootUrl: string|null }}
+ */
+function detectNetworkRoot(parentSiteUrl, items) {
+  let parentOrigin;
+  try { parentOrigin = new URL(parentSiteUrl).origin.toLowerCase(); }
+  catch { return { isRoot: false, networkRootUrl: null }; }
+
+  const rootItem = (items || []).find((it) => it && it.blog_id === 1);
+  if (rootItem && typeof rootItem.url === 'string' && rootItem.url.length > 0) {
+    let rootOrigin;
+    try { rootOrigin = new URL(rootItem.url).origin.toLowerCase(); }
+    catch { return { isRoot: false, networkRootUrl: rootItem.url }; }
+    return {
+      isRoot: rootOrigin === parentOrigin,
+      networkRootUrl: rootItem.url,
+    };
+  }
+
+  // No blog_id metadata — fall back to URL match. Accept the parent as root
+  // when any item's URL origin matches; otherwise this is a subsite invocation
+  // whose root is unknown to us (return isRoot: false, networkRootUrl: null).
+  for (const it of (items || [])) {
+    if (!it || typeof it.url !== 'string' || it.url.length === 0) continue;
+    let itOrigin;
+    try { itOrigin = new URL(it.url).origin.toLowerCase(); }
+    catch { continue; }
+    if (itOrigin === parentOrigin) {
+      return { isRoot: true, networkRootUrl: it.url };
+    }
+  }
+  return { isRoot: false, networkRootUrl: null };
+}
+
 /**
  * Build the multisite block (slug → subsite URL) from a `multisite/list-sites`
  * response. Pure function — no I/O, no logging. Exported so `add-site.js`
@@ -485,6 +554,7 @@ class InjectedClient {
 module.exports = {
   probeMultisite,
   buildMultisiteBlock,
+  detectNetworkRoot,
   deriveSubsiteSlug,
   parseToolResponse,
   // Exported for direct testing of the per-session HMAC echo contract

package/lib/config.js

@@ -228,6 +228,16 @@ async function loadConfigFile(filePath, source = 'explicit-config') {
     await validateSiteConfig(key, site);
   }
 
+  // Issue #77: bridge-boot migration — drop subsite-rooted multisite blocks
+  // when the network-root URL is also configured. Operator-visible advisory
+  // is emitted to stderr so the change is auditable; the file on disk is left
+  // alone so operators can choose to remove or re-add the network-root entry
+  // without losing the original subsite block. See migrateMisplacedMultisiteBlocks.
+  const migrationMessages = migrateMisplacedMultisiteBlocks(config);
+  for (const msg of migrationMessages) {
+    process.stderr.write(`abilities-mcp: ${msg}\n`);
+  }
+
   config._isMultiSite = Object.keys(config.sites).length > 1 ||
     Object.values(config.sites).some(s => s.multisite);
   config._configPath = filePath;
@@ -237,6 +247,88 @@ async function loadConfigFile(filePath, source = 'explicit-config') {
   return config;
 }
 
+/**
+ * Issue #77 migration. Scan persisted multisite blocks; drop those that were
+ * written from a subsite's perspective when the network-root URL is also a
+ * configured site. Pure function — mutates `config.sites[*].multisite` in
+ * place and returns a list of operator-visible advisory messages. The on-disk
+ * file is NOT rewritten; the migration runs every boot (idempotent — second
+ * boot finds nothing to drop) so operators who later remove the network-root
+ * entry get the original subsite-rooted block back as fallback routing.
+ *
+ * Detection: a multisite block is "subsite-rooted" iff it contains an entry
+ * whose hostname is a parent of the owning site's hostname (e.g. site URL
+ * `https://community.example.com` with a block entry pointing at
+ * `https://example.com`). This matches the failure shape pinned in #77 —
+ * `buildMultisiteBlock` called from a subsite invocation maps the network's
+ * other sites (including the network root) into the block.
+ *
+ * Drop condition: any OTHER configured site has `url` whose origin matches
+ * the candidate network-root entry. Without that, the operator still needs
+ * the misplaced block for dot-notation routing until they add the
+ * network-root URL — leaving it intact preserves utility on the upgrade path.
+ *
+ * @param {object} config  Parsed wp-sites.json — must have `config.sites`.
+ * @returns {string[]}     Advisory messages, one per dropped block.
+ */
+function migrateMisplacedMultisiteBlocks(config) {
+  const messages = [];
+  if (!config || !config.sites || typeof config.sites !== 'object') return messages;
+
+  const siteOrigins = new Map();
+  for (const [key, site] of Object.entries(config.sites)) {
+    if (!site || typeof site.url !== 'string') continue;
+    let origin;
+    try { origin = new URL(site.url).origin.toLowerCase(); }
+    catch { continue; }
+    siteOrigins.set(origin, key);
+  }
+
+  for (const [siteKey, site] of Object.entries(config.sites)) {
+    if (!site || !site.multisite || typeof site.multisite !== 'object') continue;
+    if (typeof site.url !== 'string') continue;
+
+    let siteHost;
+    try { siteHost = new URL(site.url).hostname.toLowerCase().replace(/^www\./, ''); }
+    catch { continue; }
+
+    // Find a block entry whose hostname is a parent domain of this site's
+    // hostname AND maps to a different origin from the site itself. That's
+    // the network-root candidate.
+    let networkRootUrl = null;
+    let networkRootOrigin = null;
+    for (const subsiteUrl of Object.values(site.multisite)) {
+      if (typeof subsiteUrl !== 'string' || subsiteUrl.length === 0) continue;
+      let entryHost, entryOrigin;
+      try {
+        const u = new URL(subsiteUrl);
+        entryHost = u.hostname.toLowerCase().replace(/^www\./, '');
+        entryOrigin = u.origin.toLowerCase();
+      } catch { continue; }
+      if (entryHost === siteHost) continue;
+      if (siteHost.endsWith('.' + entryHost)) {
+        networkRootUrl = subsiteUrl;
+        networkRootOrigin = entryOrigin;
+        break;
+      }
+    }
+    if (!networkRootUrl) continue;
+
+    const rootSiteKey = siteOrigins.get(networkRootOrigin);
+    if (!rootSiteKey || rootSiteKey === siteKey) continue;
+
+    delete site.multisite;
+    messages.push(
+      `Migration (#77): dropped subsite-rooted multisite block from "${siteKey}" ` +
+      `(${site.url}); the network-root entry "${rootSiteKey}" (${networkRootUrl}) ` +
+      `is also configured, so dot-notation routing belongs there. Subsite-rooted ` +
+      `blocks describe the network from one subsite's perspective and surface ` +
+      `parallel cross-product enumerations at the MCP tool surface.`
+    );
+  }
+  return messages;
+}
+
 async function validateSiteConfig(key, site) {
   // v2 OAuth sites carry no transport block (Appendix F.5 + add-site flow).
   // The runtime treats them as HTTP — endpoint comes from auth.mcp_resource
@@ -477,4 +569,5 @@ module.exports = {
   buildSiteKeyEnum,
   buildEnvConfig,
   validateSiteConfig,
+  migrateMisplacedMultisiteBlocks,
 };

package/lib/connection-pool.js

@@ -2,6 +2,7 @@
 
 const { SshTransport } = require('./transports/ssh-transport');
 const { resolveSiteKey, resolveSitePassword } = require('./config');
+const { AUTH_STATUS } = require('./auth/events');
 
 // Incrementing counter for synthetic handshake IDs.
 // Avoids integer overflow from Date.now() (13-digit ms timestamps exceed
@@ -138,14 +139,69 @@ class ConnectionPool {
   /**
    * Create and connect transport for the default site (no handshake replay).
    * Called once at startup — the client handles the handshake directly.
+   *
+   * Issue #76: per-site auth-init isolation. The configured `defaultSite` is
+   * tried first; if its `_createTransport` / `transport.connect()` throws
+   * (typically a `RefreshError` when the refresh token is expired — confirmed
+   * via static trace from `lib/auth/token-manager.js:147-152`), the failure
+   * is captured against the site's in-memory `auth_status` and the next
+   * configured site is tried in `Object.keys(config.sites)` order. The first
+   * site that connects becomes the runtime default (`config.defaultSite` is
+   * reassigned in-memory only — wp-sites.json on disk is untouched).
+   *
+   * Returns `null` when ALL configured sites fail. The bootstrap caller pairs
+   * a `null` return with `router.enterDegradedMode(...)` so the bridge still
+   * answers `initialize` with a valid `InitializeResult` — the failure mode
+   * the gate explicitly forbids (init-time bridge death) cannot recur.
+   *
+   * @param {function} onMessage  Per-site message router callback.
+   * @returns {Promise<Transport|null>}
    */
   async connectDefault(onMessage) {
-    const key = this.config.defaultSite;
-    const transport = await this._createTransport(key, null);
-    transport.onMessage = onMessage;
-    await transport.connect();
-    this.transports.set(key, transport);
-    return transport;
+    const configuredDefault = this.config.defaultSite;
+    const otherKeys = Object.keys(this.config.sites).filter((k) => k !== configuredDefault);
+    const tryOrder = [configuredDefault, ...otherKeys];
+
+    for (const key of tryOrder) {
+      try {
+        const transport = await this._createTransport(key, null);
+        transport.onMessage = onMessage;
+        await transport.connect();
+        this.transports.set(key, transport);
+
+        if (key !== configuredDefault) {
+          this.log(
+            `Configured default "${configuredDefault}" failed to connect; ` +
+            `runtime default fell back to "${key}". The configured default ` +
+            `is marked degraded in-memory; reauth it to restore.`
+          );
+          this.config.defaultSite = key;
+        }
+        return transport;
+      } catch (err) {
+        this.log(`Site "${key}" failed to connect at boot: ${err.message}`);
+        this._markSiteDegraded(key, err);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Mark a site degraded in the in-memory config so other lookups (tools/list,
+   * resources/read wp-abilities://sites, per-call routing) can surface it
+   * without re-attempting the failed connection. The on-disk wp-sites.json is
+   * NOT rewritten here — degraded state is recoverable (operator runs reauth)
+   * and the next bridge boot will re-attempt the connection from the existing
+   * persisted state.
+   *
+   * @private
+   */
+  _markSiteDegraded(siteId, err) {
+    const site = this.config.sites && this.config.sites[siteId];
+    if (!site) return;
+    site.auth_status = AUTH_STATUS.EXPIRED;
+    site._degraded_reason = (err && err.message) || 'connect failed';
   }
 
   /**

package/lib/router.js

@@ -54,6 +54,15 @@ class McpRouter {
     // Early queue for messages before transport is ready
     this.MAX_EARLY_QUEUE = 50;
     this.earlyQueue = [];
+
+    // Issue #76: degraded mode — entered when ALL configured sites fail to
+    // connect at boot. The bridge still answers `initialize` with a locally
+    // synthesized InitializeResult (so the MCP runtime stays connectable and
+    // the operator can call wp_bridge_health to see which sites are degraded);
+    // tools/list returns the bridge's three local tools only; non-bridge
+    // tools/call surfaces a per-call error naming the degraded sites.
+    this.degraded = false;
+    this.degradedSites = [];  // [{ siteId, reason }]
   }
 
   /**
@@ -63,6 +72,22 @@ class McpRouter {
     this.defaultTransport = transport;
   }
 
+  /**
+   * Issue #76: enter degraded mode when no configured site connected at boot.
+   * The router will synthesize an InitializeResult on the next `initialize`
+   * request and refuse non-bridge tool calls with a descriptive error.
+   *
+   * @param {Array<{siteId:string, reason:string}>} degradedSites
+   */
+  enterDegradedMode(degradedSites) {
+    this.degraded = true;
+    this.degradedSites = Array.isArray(degradedSites) ? degradedSites.slice() : [];
+    this.log(
+      `Router entering degraded mode: ${this.degradedSites.length} site(s) failed to ` +
+      `connect at boot — ` + this.degradedSites.map((s) => `${s.siteId} (${s.reason})`).join('; ')
+    );
+  }
+
   /**
    * Drain messages queued before the default transport was ready.
    */
@@ -90,6 +115,14 @@ class McpRouter {
       if (msg.params && msg.params.protocolVersion) {
         this.clientProtocolVersion = msg.params.protocolVersion;
       }
+      // Issue #76: in degraded mode (no site transport at boot), synthesize
+      // a locally-valid InitializeResult so the MCP runtime stays connectable
+      // and the client can still issue wp_bridge_health / etc. against the
+      // bridge's local tools.
+      if (this.degraded) {
+        this._sendSynthesizedInitializeResult(msg);
+        return;
+      }
       this._forwardToDefault(line);
       return;
     }
@@ -99,12 +132,22 @@ class McpRouter {
       this.cachedInitNotification = msg;
       this.initHandshakeComplete = true;
       this.pool.setHandshakeCache(this.cachedInitRequest, this.cachedInitNotification, this.clientProtocolVersion);
+      // In degraded mode there is no transport to forward to; the notification
+      // is purely informational once the synthesized InitializeResult has been
+      // sent.
+      if (this.degraded) return;
       this._forwardToDefault(line);
       return;
     }
 
     // tools/list — route to default, then inject site param
     if (msg.method === 'tools/list') {
+      // Issue #76: in degraded mode, return only the bridge's local tools so
+      // operators can call wp_bridge_health and see which sites are degraded.
+      if (this.degraded) {
+        this._sendSynthesizedToolsListResult(msg);
+        return;
+      }
       this._forwardToDefault(line);
       return;
     }
@@ -115,6 +158,13 @@ class McpRouter {
         this._handleBridgeToolCall(msg);
         return;
       }
+      // Issue #76: in degraded mode there is no backing site transport; surface
+      // a per-call error naming the degraded sites so the client sees a clear
+      // diagnostic, not a hang.
+      if (this.degraded) {
+        this._sendDegradedToolsCallError(msg);
+        return;
+      }
       this._handleToolsCall(msg);
       return;
     }
@@ -153,6 +203,37 @@ class McpRouter {
       return;
     }
 
+    // Issue #76 follow-up — request-time boundary.
+    //
+    // OAuthHttpTransport.connect() does NOT pre-validate tokens (lib/transports/
+    // oauth-http-transport.js:139-143 — sets ready=true, returns). When the
+    // configured default site has an expired refresh token, _createTransport
+    // and connect() both succeed; the bridge does NOT enter the connect-time
+    // degraded path covered by #81. Instead, drainEarlyQueue() forwards the
+    // cached `initialize` request through the transport, _processMessage
+    // calls _postWithRetry → getAccessToken → refresh → throws RefreshError
+    // synchronously when authStatus===EXPIRED (lib/auth/token-manager.js:147).
+    // _processMessage catches the throw at lib/transports/oauth-http-transport.js:
+    // 379-388 and emits onMessage with `{jsonrpc, id, error}` — the cached
+    // initialize id paired with `OAuth HTTP bridge error: …`. Without this
+    // intercept, the error→CallToolResult conversion below blanket-converts
+    // it to `{result:{content:[],isError:true}}` and the MCP runtime rejects
+    // the response shape. Pin the gate-violating shape here: when the failed
+    // response carries the cached initialize id, synthesize a valid
+    // InitializeResult locally and enter degraded mode for the failed site.
+    if (parsedMsg.error && parsedMsg.id !== undefined &&
+        this.cachedInitRequest && parsedMsg.id === this.cachedInitRequest.id) {
+      const failedSite = this.config && this.config.defaultSite;
+      const reason = (parsedMsg.error && parsedMsg.error.message) || 'unknown';
+      this.log(
+        `Initialize forward failed for "${failedSite || '(unknown)'}": ${reason} — ` +
+        `synthesizing degraded-mode InitializeResult to satisfy MCP runtime`
+      );
+      this._sendSynthesizedInitializeResult(this.cachedInitRequest);
+      this.enterDegradedMode([{ siteId: failedSite || '(unknown)', reason }]);
+      return;
+    }
+
     // Sanitize tools/list responses
     if (isToolsListResponse(parsedMsg)) {
       sanitizeToolsList(parsedMsg, this.log);
@@ -234,22 +315,112 @@ class McpRouter {
   _forwardToDefault(line) {
     if (this.defaultTransport) {
       this.defaultTransport.send(line);
-    } else {
-      if (this.earlyQueue.length >= this.MAX_EARLY_QUEUE) {
-        this.log('Early queue full — rejecting message');
-        try {
-          const msg = JSON.parse(line);
-          if (msg.id !== undefined) {
-            this.sendToClient(JSON.stringify({
-              jsonrpc: '2.0', id: msg.id,
-              error: { code: -32603, message: 'Server not ready — queue full' }
-            }));
-          }
-        } catch (e) { /* non-JSON, drop */ }
-        return;
-      }
-      this.earlyQueue.push(line);
+      return;
     }
+    // Issue #76: in degraded mode any message that reached this point (i.e.
+    // not handled by a degraded-aware branch above) gets a per-call error
+    // rather than being queued forever waiting for a transport that will
+    // never arrive.
+    if (this.degraded) {
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined) {
+          this.sendToClient(JSON.stringify({
+            jsonrpc: '2.0', id: msg.id,
+            error: {
+              code: -32603,
+              message: `Bridge running in degraded mode — no site transport available. ` +
+                this._degradedSummary(),
+            },
+          }));
+        }
+      } catch (e) { /* non-JSON, drop */ }
+      return;
+    }
+    if (this.earlyQueue.length >= this.MAX_EARLY_QUEUE) {
+      this.log('Early queue full — rejecting message');
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined) {
+          this.sendToClient(JSON.stringify({
+            jsonrpc: '2.0', id: msg.id,
+            error: { code: -32603, message: 'Server not ready — queue full' }
+          }));
+        }
+      } catch (e) { /* non-JSON, drop */ }
+      return;
+    }
+    this.earlyQueue.push(line);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal — degraded mode (Issue #76)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Synthesize a valid MCP InitializeResult so the client's MCP validator
+   * receives `protocolVersion`, `capabilities`, and `serverInfo` instead of
+   * EOF (the failure mode pinned in #76 — bridge died before any response).
+   *
+   * Echoes the client's `protocolVersion` when present (per MCP spec — the
+   * server returns the negotiated version, defaulting to its own when no
+   * client-side version was provided).
+   */
+  _sendSynthesizedInitializeResult(msg) {
+    const clientProtocol = msg.params && msg.params.protocolVersion;
+    const result = {
+      jsonrpc: '2.0',
+      id: msg.id,
+      result: {
+        protocolVersion: clientProtocol || '2025-06-18',
+        capabilities: { tools: {}, resources: {} },
+        serverInfo: {
+          name: 'abilities-mcp (degraded)',
+          version: this._bridgeVersion(),
+        },
+      },
+    };
+    this.sendToClient(JSON.stringify(result));
+  }
+
+  /**
+   * Synthesize a tools/list response with only the bridge's local tools.
+   * In degraded mode there is no WordPress adapter to answer the real list,
+   * so wp_bridge_health / wp_browse_tools / wp_load_tools are still callable
+   * for diagnostics.
+   */
+  _sendSynthesizedToolsListResult(msg) {
+    const result = { jsonrpc: '2.0', id: msg.id, result: { tools: [] } };
+    injectBridgeTools(result);
+    this.sendToClient(JSON.stringify(result));
+  }
+
+  _sendDegradedToolsCallError(msg) {
+    this.sendToClient(JSON.stringify({
+      jsonrpc: '2.0', id: msg.id,
+      error: {
+        code: -32603,
+        message: `Tool call cannot be served — bridge is running in degraded mode. ` +
+          this._degradedSummary() +
+          ` Run: abilities-mcp reauth <site> to recover, or use the bridge tools ` +
+          `(wp_bridge_health, wp_browse_tools, wp_load_tools) for diagnostics.`,
+      },
+    }));
+  }
+
+  _degradedSummary() {
+    if (!this.degradedSites || this.degradedSites.length === 0) {
+      return 'No degraded-site details available.';
+    }
+    const parts = this.degradedSites.map((s) => `${s.siteId}: ${s.reason}`);
+    return `Degraded sites — ${parts.join('; ')}.`;
+  }
+
+  _bridgeVersion() {
+    try {
+      const pkg = require('../package.json');
+      return (pkg && pkg.version) || 'unknown';
+    } catch { return 'unknown'; }
   }
 
   // ---------------------------------------------------------------------------

package/lib/sanitizer.js

@@ -65,8 +65,14 @@ function sanitizeToolsList(msg, log) {
     delete tool.type;
     delete tool.outputSchema;
 
-    // Validate schema and log warnings
-    if (tool.inputSchema) {
+    // Normalize broken or non-object inputSchema (defensive — broken upstream
+    // schemas would otherwise 400 the API and break the entire tool list).
+    if (!tool.inputSchema || typeof tool.inputSchema !== 'object' || Array.isArray(tool.inputSchema)) {
+      if (tool.inputSchema !== undefined) {
+        _log(`SCHEMA NORMALIZE [${tool.name || '(unnamed)'}]: inputSchema not a valid object — defaulted to {type:'object'}`);
+      }
+      tool.inputSchema = { type: 'object' };
+    } else {
       validateToolSchema(tool.name || '(unnamed)', tool.inputSchema, _log);
     }
 

package/package.json

@@ -1,13 +1,29 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {
     "abilities-mcp": "./abilities-mcp.js"
   },
-  "files": ["abilities-mcp.js", "lib/", "wp-sites.example.json", "LICENSE", "README.md", "CHANGELOG.md"],
-  "keywords": ["mcp", "wordpress", "bridge", "abilities", "ai", "open-source", "multi-site", "model-context-protocol"],
+  "files": [
+    "abilities-mcp.js",
+    "lib/",
+    "wp-sites.example.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "wordpress",
+    "bridge",
+    "abilities",
+    "ai",
+    "open-source",
+    "multi-site",
+    "model-context-protocol"
+  ],
   "license": "GPL-2.0-or-later",
   "author": "Wicked Evolutions",
   "repository": {