@oobe-protocol-labs/sap-mcp-server 0.9.15 → 0.9.20

package/docs/07_ENDPOINTS_AND_CLIENTS.md

@@ -10,6 +10,9 @@
 | `GET` | `/server.json` | Machine-readable public server metadata. | Public. |
 | `GET` | `/pricing.json` | Machine-readable x402/pay.sh pricing catalog generated from the hosted pricing registry. | Public. |
 | `GET` | `/openapi.json` | OpenAPI 3.1 discovery document for the hosted MCP endpoint, x402 metadata, and pay.sh catalog link. | Public. |
+| `GET` | `/premium/catalog.json` | Secret-free premium plugin contracts, schemas, pricing models, and provider readiness. | Public. |
+| `GET` | `/premium/streams.json` | Secret-free premium stream contracts for future x402/pay.sh real-time delivery rails. | Public. |
+| `GET` | `/premium/webhooks.json` | Secret-free premium webhook contracts with signed delivery expectations. | Public. |
 | `GET` | `/.well-known/x402` | x402 discovery document for paid hosted MCP resources. | Public. |
 | `GET` | `/pay/provider.yml` | Secret-free pay.sh provider YAML for the hosted SAP MCP catalog/proxy workflow. | Public. |
 | `GET` | `/favicon.png` | SAP MCP favicon/social preview asset. | Public. |
@@ -132,7 +135,7 @@ Codex supports Streamable HTTP MCP servers with URL-based TOML entries. Use loca
 ```toml
 [mcp_servers.sap]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.15", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.20", "sap-mcp-server"]
 
 [mcp_servers.sap.env]
 SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"

package/docs/09_TOOLS_SKILLS_AND_AGENT_GUIDE.md

@@ -26,13 +26,21 @@ Agents should:
 8. Answer in the user's language unless the user asks otherwise.
 9. Avoid showing internal thinking, keypair bytes, raw request secrets, or private config.
 10. Ask for approval before signing or value-moving operations when required by policy.
-11. For paid hosted agent discovery, use targeted `sap_discover_agents` filters
+11. Use free exact/base SAP reads before paid discovery when possible:
+    `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+    `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and compact
+    `sap_list_agents` pages with `limit <= 20`, `view: "compact"`, and
+    `includeProtocolIndexes: false`.
+12. For paid hosted agent discovery, use targeted `sap_discover_agents` filters
     before broad scans: `query`, `wallet`, `agentPda`, `protocol`,
     `capability`, `capabilities`, `hasX402Endpoint`, small `limit`, then
     `pagination.nextCursor`.
-12. If a capability lookup returns zero agents, retry with `query` or `wallet`
+13. If a capability lookup returns zero agents, retry with `query` or `wallet`
     before saying the agent is absent; AgentAccount rows are canonical and
     indexes can lag.
+14. Call `sap_agent_next_action` before retrying after `payment_required`,
+    `hosted_local_signer_required`, transient RPC errors, missing local bridge
+    tools, or submitted signatures that did not confirm.
 
 The intended user command is short:
 
@@ -54,9 +62,12 @@ unless the user explicitly asks what tools are available.
 SAP MCP exposes a free startup path:
 
 1. `sap_agent_start` returns the machine-readable agent playbook.
-2. `sap-agent-start` is the matching MCP prompt for runtimes that prefer prompts.
-3. `sap_skills_bundle` returns the bundled SAP MCP skills so the agent can load tool routing, x402, SNS, registry, chat, and Solana protocol guidance.
-4. `sap_payments_readiness` checks the local non-custodial payment bridge before paid/write hosted calls.
+2. `sap_agent_runtime_status` returns the hosted/accountless/local-bridge routing table.
+3. `sap_agent_context` returns free compact SAP agent context before paid discovery.
+4. `sap_agent_next_action` classifies SAP MCP errors and tells the agent whether a retry is safe.
+5. `sap-agent-start` is the matching MCP prompt for runtimes that prefer prompts.
+6. `sap_skills_bundle` returns the bundled SAP MCP skills so the agent can load tool routing, x402, SNS, registry, chat, and Solana protocol guidance.
+7. `sap_payments_readiness` checks the local non-custodial payment bridge before paid/write hosted calls.
 
 These calls are free. Paid tools should only start after the agent has loaded
 skills and, when needed, verified the local `sap_payments` bridge.

package/docs/14_DESKTOP_WIZARD_RELEASE.md

@@ -66,7 +66,7 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 ```toml
 [mcp_servers.sap_payments]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.15", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.20", "sap-mcp-server"]
 startup_timeout_sec = 300
 tool_timeout_sec = 300
 
@@ -279,8 +279,8 @@ npm pack --dry-run --cache ./.npm-cache
 The current local macOS arm64 build produces:
 
 ```txt
-SAP-MCP-Wizard-0.9.15-arm64.dmg
-SAP-MCP-Wizard-0.9.15-arm64.zip
+SAP-MCP-Wizard-0.9.20-arm64.dmg
+SAP-MCP-Wizard-0.9.20-arm64.zip
 ```
 
 Windows EXE and Linux artifacts are produced by the GitHub Actions matrix.

package/docs/16_SAP_AGENT_IDENTITY_PIPELINE.md

@@ -235,6 +235,12 @@ Then call:
   confirms the agent account and reports a non-failing `protocolFee` audit.
 - Do not call profile/image update complete until `sap_payments_update_agent`
   confirms and a fresh `sap_get_agent_profile` read shows the intended fields.
+- If an update returns Anchor 3012, `AccountNotInitialized`, or a
+  `pricing_menu` error, do not classify it as missing `sap_payments` and do not
+  ask the user to repair/restart the runtime. The local signer route worked; the
+  SAP registry account lifecycle is missing a required on-chain PDA. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then use the current
+  SDK/server initializer path before retrying the update.
 - Do not create temporary signing scripts.
 - Do not read keypair JSON.
 - Do not pay x402 for writes that the hosted server says require local signer.

package/docs/18_PREMIUM_PLUGIN_RUNTIME.md

@@ -0,0 +1,108 @@
+# SAP MCP Premium Plugin Runtime
+
+SAP MCP includes a typed premium plugin contract for paid streams, webhooks, and enterprise capabilities. The goal is to let agents discover paid real-time capabilities, validate schemas before spending, and bind future x402/pay.sh receipts to a clear session id without exposing private provider code or user key material.
+
+This layer is deliberately strict:
+
+- no fake stream data
+- no implicit provider claims
+- no execution of plugin code from user input
+- no keypair bytes or provider secrets in public metadata
+- no x402 charge for invalid catalog/session planning requests
+
+## What Ships In The Open Server
+
+The public MCP server exposes free discovery and planning tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `sap_premium_plugin_catalog` | Lists premium plugin manifests, schemas, pricing contracts, provider readiness, and private plugin loader guidance. |
+| `sap_stream_catalog` | Lists stream capability contracts such as quote deltas, price ticks, registry events, and x402 ledger events. |
+| `sap_webhook_catalog` | Lists webhook delivery contracts and signed callback event types. |
+| `sap_premium_validate_plugin_manifest` | Validates a manifest before publication or enterprise loading. |
+| `sap_premium_plugin_template` | Builds a strict data-only manifest template for custom stream, webhook, or premium tool contracts. |
+| `sap_premium_session_start` | Creates an unpaid, bounded session plan for a premium capability. |
+| `sap_premium_session_status` | Reads in-memory premium session planning status. |
+
+Planning is free because it prevents wasted x402 attempts. Live premium delivery should be charged by the delivery rail once the provider is configured and the session is activation-ready.
+
+## Public HTTP Discovery
+
+The hosted server also exposes the same premium contracts as public, machine-readable JSON:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/premium/catalog.json` | Full premium plugin catalog with provider readiness, pricing contracts, stream/webhook/tool capability ids, and private loader guidance. |
+| `/premium/streams.json` | Stream-only discovery for price ticks, quote deltas, registry events, and x402 ledger streams. |
+| `/premium/webhooks.json` | Webhook-only discovery for signed callback subscriptions and event delivery contracts. |
+
+These endpoints are discovery-only. They do not activate paid streams, execute private plugins, expose provider secrets, or return live provider data while readiness is false.
+
+## Provider Readiness
+
+Capabilities that depend on external streaming or webhook infrastructure include explicit provider env vars. If a required env var is missing, the capability returns:
+
+```txt
+status: requires-provider
+```
+
+Agents must not attempt paid activation when provider readiness is false. They should tell the user that the capability is contract-ready but not live on this deployment.
+
+## Built-In Premium Contracts
+
+The open catalog currently defines contract-level manifests for:
+
+| Plugin | Capability Examples |
+| --- | --- |
+| `sap-premium-market-data` | Jupiter quote deltas, Pyth price ticks, price threshold webhooks. |
+| `sap-premium-trading-streams` | Cross-DEX arbitrage scanning, volatility breakout detection, MEV-protected route optimization. |
+| `sap-premium-meme-radar` | New listing alerts, social sentiment, rugpull risk, DEX volume anomalies. |
+| `sap-premium-tech-fundamentals` | GitHub activity spikes, TVL changes, tokenomics analysis. |
+
+These are not mock feeds. They are typed contracts that become live only when the corresponding provider env is configured.
+
+## Private Enterprise Plugins
+
+Enterprise/private plugin code should live outside the public repository. The public server exposes the contract and validation path only.
+
+Supported loader env contract:
+
+```txt
+SAP_MCP_ENABLE_PREMIUM_PLUGINS=true
+SAP_MCP_PLUGIN_DIR=/secure/path/to/private/plugins
+SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=false
+```
+
+Private plugins must provide manifests that pass:
+
+```txt
+sap_premium_validate_plugin_manifest
+```
+
+The runtime loads private manifests as data only from the configured directory.
+It does not execute plugin code supplied through MCP tool input. Private and
+enterprise manifests are not exposed in public catalog responses unless
+`SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=true` is set deliberately, which
+should be reserved for authenticated or explicitly shared deployments.
+
+Use `sap_premium_plugin_template` to generate a starter manifest, then store the
+reviewed JSON in the private plugin subrepo under `manifests/`. Plugging and
+unplugging a private capability is a file/deploy operation: add or remove the
+manifest, validate it, and restart the hosted server with the intended env.
+
+## Agent Flow
+
+Recommended agent behavior:
+
+1. Call `sap_premium_plugin_catalog` with `includeSchemas:true`.
+2. Use `sap_stream_catalog` or `sap_webhook_catalog` to pick an exact capability id.
+3. Check `providerStatus` and the capability-level `providerReady` boolean.
+4. Call `sap_premium_session_start` to get a bounded session plan and estimated price.
+5. Activate only through the future paid delivery rail when provider readiness is true.
+6. Bind x402/pay.sh receipt, session id, plugin id, capability id, and event ids in the audit output.
+
+If the provider is not ready, stop cleanly and do not request payment.
+
+## Why This Matters
+
+Agent commerce needs more than one-shot tools. Trading agents, research agents, protocol monitors, and marketplace agents need fast event access with clear payment boundaries. SAP MCP premium plugins create the contract layer for that: typed schemas, bounded sessions, x402/pay.sh pricing, signed delivery, and enterprise provider isolation.

package/docs/README.md

@@ -65,6 +65,7 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
 - [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
 - [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+- [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## What The Hosted Server Provides
 
@@ -118,6 +119,7 @@ Read these first:
 6. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
 7. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
 8. [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+9. [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## Public Endpoints
 
@@ -127,6 +129,16 @@ Read these first:
 | `GET /docs` | This documentation site. |
 | `POST /mcp` | Streamable HTTP MCP endpoint for agents. |
 | `GET /server.json` | Public, secret-free machine-readable server metadata. |
+| `GET /premium/catalog.json` | Public premium plugin contracts, pricing models, schemas, and provider readiness. |
+| `GET /premium/streams.json` | Public premium stream contracts for future x402/pay.sh real-time delivery rails. |
+| `GET /premium/webhooks.json` | Public premium webhook contracts with signed delivery expectations. |
+
+Premium plugin authors can use `sap_premium_plugin_template` and
+`sap_premium_validate_plugin_manifest` to build strict data-only contracts,
+then deploy reviewed manifests from a private plugin directory. The public
+server never executes plugin code supplied through MCP input and does not expose
+private/enterprise manifests unless the operator explicitly enables private
+discovery.
 | `GET /smithery.config.schema.json` | Optional Smithery setup schema for free discovery, native x402 clients, and local `sap_payments` bridge users. |
 | `GET /.well-known/agent-card.json` | A2A-style agent card. |
 | `GET /.well-known/sap-mcp-wizard.json` | Wizard install descriptor for agents that cannot see local config. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.15",
+  "version": "0.9.20",
   "mcpName": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "description": "Official MCP gateway for OOBE Protocol SAP — AI agents can interact with SAP identity, registry, reputation, tools, memory, payments, settlement, and proof-of-execution on Solana",
   "type": "module",
@@ -145,13 +145,15 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@11.7.0",
   "overrides": {
-    "bigint-buffer": "file:vendor/bigint-buffer",
-    "esbuild": "^0.28.1",
+    "@hono/node-server": "2.0.10",
+    "body-parser": "1.20.6",
+    "fast-uri": "3.1.4",
+    "hono": "4.12.27",
     "langsmith": "^0.6.0",
+    "postcss": "8.5.18",
     "uuid": "^11.1.1",
-    "vite": "8.1.0",
     "ws": "^8.21.0"
-  }
+  },
+  "packageManager": "pnpm@11.7.0"
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "title": "SAP MCP Server | OOBE Protocol",
   "description": "Solana-native MCP gateway for SAP tools, DeFi, SNS identity, x402/pay.sh, and agent operations.",
-  "version": "0.9.15",
+  "version": "0.9.20",
   "websiteUrl": "https://mcp.sap.oobeprotocol.ai/",
   "repository": {
     "url": "https://github.com/OOBE-PROTOCOL/sap-mcp",
@@ -29,7 +29,7 @@
     {
       "registryType": "npm",
       "identifier": "@oobe-protocol-labs/sap-mcp-server",
-      "version": "0.9.15",
+      "version": "0.9.20",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.15"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.20"
         },
         {
           "type": "positional",

package/skills/README.md

@@ -55,12 +55,20 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 ## Agent Behavior
 
 - Answer in the same natural language as the user's latest request.
+- Use free exact/base SAP reads before paid discovery when possible:
+  `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+  compact `sap_list_agents` pages with `limit <= 20`.
 - Use `sap_discover_agents` for targeted hosted agent search by query, wallet,
   PDA, protocol, capability, capability list, or x402 endpoint presence.
-- Use `sap_list_all_agents` for current global SAP ecosystem agent lists and
-  continue with `pagination.nextCursor` when more pages are needed.
+- Use `sap_list_all_agents` for current global SAP ecosystem agent lists only
+  when the user needs more than the free compact orientation page, and continue
+  with `pagination.nextCursor` when more pages are needed.
 - Treat `mcp_sap_<tool>` as a client display prefix; the callable MCP tool name
   inside this server is the suffix, for example `jupiter_getQuote`.
+- Call `sap_agent_next_action` before retrying after `payment_required`,
+  `hosted_local_signer_required`, transient Solana RPC errors, a missing local
+  bridge, or a submitted signature that has not confirmed.
 - Use `skills/sap-mcp/TOOL_REFERENCE.md` and `USER_DOCS/05_SKILLS_AND_TOOLS.md`
   as the bundled routing maps when deciding which SAP MCP tool or skill domain
   applies to a user request.

package/skills/sap-agent-registry/SKILL.md

@@ -12,10 +12,16 @@ state, global directory listing, and agent profile inspection.
    full identity setup, call `sap_agent_identity_plan` before any write. It is
    free and returns normalized fields, local-signer routing, metadata contract,
    forbidden actions, and verification checklist.
-4. Call `sap_get_network_overview` for ecosystem counters when needed.
-5. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
-   `capability` for targeted paid hosted directory reads.
-6. Use `sap_list_all_agents` for global current agent lists and follow
+4. Use free exact/base reads before paid discovery: `sap_agent_context`,
+   `sap_get_agent`,
+   `sap_get_agent_profile`, `sap_get_agent_stats`, `sap_is_agent_active`,
+   `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
+   `view: "compact"`, and `includeProtocolIndexes: false`.
+5. Call `sap_get_network_overview` for ecosystem counters when needed.
+6. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
+   `capability` for targeted paid hosted directory reads when free exact/base
+   reads are not enough.
+7. Use `sap_list_all_agents` for global current agent lists and follow
    `pagination.nextCursor` for additional pages.
 
 ## Tools
@@ -23,6 +29,8 @@ state, global directory listing, and agent profile inspection.
 - `sap_register_agent`
 - `sap_protocol_invariants`
 - `sap_agent_identity_plan`
+- `sap_agent_context`
+- `sap_agent_next_action`
 - `sap_update_agent`
 - `sap_deactivate_agent`
 - `sap_reactivate_agent`
@@ -32,6 +40,7 @@ state, global directory listing, and agent profile inspection.
 - `sap_get_agent_stats`
 - `sap_get_global_state`
 - `sap_get_network_overview`
+- `sap_list_agents`
 - `sap_list_all_agents`
 - `sap_is_agent_active`
 - `sap_report_calls`
@@ -50,6 +59,10 @@ state, global directory listing, and agent profile inspection.
   `confirm: true`. For other registry writes, run the write on the local SAP
   MCP profile or use a production unsigned builder/finalizer flow when
   available.
+- Before any retry after `payment_required`, `hosted_local_signer_required`,
+  `BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted
+  signature that did not confirm, call `sap_agent_next_action`. Follow its
+  `safeToRetryNow`, `nextTool`, and `forbiddenActions` fields.
 - Agent pictures must be public metadata, not desktop file paths. Upload the
   image or metadata JSON to IPFS, Arweave, Kommodo, or HTTPS, then set
   `agentUri`/`metadataUri` with `sap_payments_update_agent`.
@@ -63,6 +76,12 @@ state, global directory listing, and agent profile inspection.
 - After `sap_payments_update_agent`, fetch the agent profile again and verify
   the changed fields. For image/profile updates, `agentUri` or `metadataUri`
   must resolve to public metadata containing the image URL.
+- If `sap_payments_update_agent` returns Anchor 3012, `AccountNotInitialized`,
+  or mentions `pricing_menu`, do not run runtime repair and do not retry the
+  same write. This means the write reached the SAP on-chain program but a
+  required registry lifecycle PDA is missing or stale. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then upgrade the
+  SDK/server or use the initializer path before retrying.
 - For full agent identity setup, follow
   `docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`: SAP registration first, optional
   Metaplex/MPL Core identity, optional SNS domain and records, then a final SAP
@@ -71,8 +90,10 @@ state, global directory listing, and agent profile inspection.
   `query`.
 - "Find x402 agents" means `sap_discover_agents` with
   `hasX402Endpoint: true`.
-- "List all agents" means `sap_list_all_agents` with a small `limit`, then
-  `pagination.nextCursor` if the user wants more.
+- "List all agents" means first call free `sap_list_agents` with
+  `limit <= 20`, `view: "compact"`, and `includeProtocolIndexes: false`; then
+  use paid `sap_list_all_agents` with `pagination.nextCursor` if the user wants
+  more, full rows, or ecosystem-scale enumeration.
 - "Agent by wallet" means `sap_get_agent` or `sap_get_agent_profile`.
 - "Is this agent live?" means `sap_is_agent_active`.
 - "Network totals" means `sap_get_network_overview`.

package/skills/sap-discovery-indexing/SKILL.md

@@ -18,12 +18,21 @@ indexes, and filtered agent discovery.
 
 ## Rules
 
+- Start with free orientation when possible:
+  - `sap_agent_context` for a one-shot compact context read and routing hints.
+  - `sap_get_agent` or `sap_get_agent_profile` for a known owner wallet.
+  - `sap_is_agent_active` for a known owner wallet status check.
+  - `sap_get_global_state` for compact registry state.
+  - `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+    `includeProtocolIndexes: false` for a small current directory page.
 - Use `sap_discover_agents` for paid hosted agent directory search. It supports
   `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
   `capabilityMode`, `hasX402Endpoint`, `limit`, `cursor`, and `view`.
 - Use `sap_list_all_agents` for global directory requests or when the user asks
   for the whole SAP ecosystem. Keep the first page small and follow
   `pagination.nextCursor` only when the previous page is useful.
+- Use paid discovery only when the user needs search, enrichment, full rows,
+  large pages, analytics, or global enumeration beyond the free compact page.
 - Prefer exact filters before broad scans: `wallet` when a wallet is known,
   `query` for an agent name such as `XONA`, and `capability` for one exact
   capability such as `creative:imageGeneration`.
@@ -34,6 +43,8 @@ indexes, and filtered agent discovery.
   the canonical AgentAccount directory.
 - Do not guess that global enumeration is impossible; try `sap_list_all_agents`
   first and report the exact failure if it fails.
+- If discovery hits `payment_required`, a transient RPC error, or a missing
+  local bridge, call `sap_agent_next_action` before retrying or changing route.
 
 ## Common Inputs
 

package/skills/sap-mcp/SKILL.md

@@ -12,20 +12,28 @@ available, then call `sap_agent_runtime_status` with the closest intent and
 `sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
 skill contents into context before selecting advanced tools.
 
+If the MCP runtime exposes prompts, use `sap-agent-intent-router` as the compact
+decision prompt before paid calls, registry writes, escrow flows, identity
+updates, or after SAP/x402/MCP errors. It routes the user intent to hosted
+reads, `sap_payments_*`, unsigned builders, transaction finalization, or repair
+without requiring a long pasted prompt from the user.
+
 Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
 2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
-3. `sap_skills_bundle` with `includeContents: true`
-4. `sap_pricing_catalog` before estimating hosted paid call tiers
-5. `sap_skills_upgrade_plan` when local skills are missing or stale
-6. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
-7. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
-8. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
-9. `sap_profile_current`
-10. `sap_profile_list`
-11. `sap_profile_public_key`
-12. `sap_network_stats`
+3. `sap_agent_context` for free compact agent/directory orientation before paid discovery
+4. `sap_skills_bundle` with `includeContents: true`
+5. `sap_pricing_catalog` before estimating hosted paid call tiers
+6. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
+7. `sap_skills_upgrade_plan` when local skills are missing or stale
+8. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
+9. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
+10. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
+11. `sap_profile_current`
+12. `sap_profile_list`
+13. `sap_profile_public_key`
+14. `sap_network_stats`
 
 For simple "are you connected?" checks, do not dump tool counts or inspect
 local files. Use `sap_agent_runtime_status` first and answer with the hosted
@@ -45,6 +53,15 @@ and error strings unchanged.
 
 ## Discovery Rules
 
+- Treat SAP registry, balances, SNS ownership, quotes, settlement status, and
+  agent profile reads as fresh data. Do not rely on old chat memory when the
+  user asks for current state; use exact lightweight reads first, then paid
+  discovery only when enrichment or broad search is needed.
+- Use free exact/base reads first when the wallet, PDA, or a small orientation
+  page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+  `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+  `includeProtocolIndexes: false`.
 - Use `sap_get_network_overview` for live ecosystem counters.
 - Use `sap_discover_agents` for targeted paid hosted discovery. Prefer
   `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
@@ -52,7 +69,9 @@ and error strings unchanged.
 - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
   agents. It performs global on-chain `AgentAccount` enumeration and returns
   `pagination.nextCursor` when more pages are available.
-- Use `sap_list_agents` as a compatibility alias for `sap_discover_agents`.
+- Use `sap_list_agents` for a free compact orientation page first. Larger
+  pages, `view: "full"`, hydration, protocol index summaries, and global scans
+  are paid read-premium.
 - Use `sap_fetch_protocol_index` when a specific protocol ID is known.
 - If a capability lookup returns zero results, retry with `query` or `wallet`
   before saying an agent is absent. AgentAccount rows are canonical; indexes can
@@ -80,7 +99,8 @@ Use the bundled routing map for local MCP tool selection:
 - `USER_DOCS/05_SKILLS_AND_TOOLS.md`
 
 SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
-`sap_agent_start`, `sap_agent_runtime_status`, `sap_pricing_catalog`,
+`sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+`sap_agent_next_action`, `sap_pricing_catalog`,
 `sap_skills_list`, `sap_skills_bundle`, `sap_skills_upgrade_plan`,
 `sap_runtime_repair_plan`, and local `sap_skills_install` directly. Do not
 route startup, runtime status, pricing catalog, skill listing, bundling,
@@ -165,10 +185,19 @@ Use `sap_payments.sap_payments_profile_current` only as a narrower compatibility
 profile check.
 
 Basic wallet reads are free on hosted SAP MCP. Call `sol_get_balance`,
-`spl-token_getBalance`, and `spl-token_getTokenAccounts` directly on the hosted
-server. Do not send these balance checks through `sap_payments_call_paid_tool`,
-and do not summarize a balance read as a facilitator `BlockhashNotFound`
-problem unless a paid tool actually returned that error.
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, and `magicblock_balance`
+directly on the hosted server. Do not send these balance checks through
+`sap_payments_call_paid_tool`, and do not summarize a balance read as a
+facilitator `BlockhashNotFound` problem unless a paid tool actually returned
+that error. Use `jupiter_getHoldings` only when the user needs enriched paid
+portfolio context.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact pricing tier, estimated USD cost, and recommended `maxPriceUsd`.
+This prevents silent cap aborts and failed x402 attempts on local-signer-only
+tools. For local-signer-only tools (e.g. `sap_register_agent`), the estimate
+will say `tier: "local-signer-only"` and tell you to use the local
+`sap_payments_*` equivalent instead of `sap_payments_call_paid_tool`.
 
 If a hosted paid tool returns `BlockhashNotFound`,
 `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
@@ -210,6 +239,10 @@ and protocol fee invariant were verified. If `success` is false while
 protocol registration lifecycle is not complete. After
 `sap_payments_update_agent`, fetch the agent again and confirm the changed
 fields before saying an image, metadata, pricing, or capability update is done.
+If an update returns Anchor 3012, `AccountNotInitialized`, or `pricing_menu`, do
+not call runtime repair or retry the same write. Route it through
+`sap_agent_next_action` and `sap_protocol_invariants`; it is an SAP on-chain
+registry lifecycle issue, not a missing local bridge.
 
 Before any write-like operation, use this routing order:
 

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -49,12 +49,22 @@ SAP registry and discovery:
 `sap_deactivate_tool`, `sap_reactivate_tool`,
 `sap_report_tool_invocations`, `sap_report_calls`.
 
-Use `sap_discover_agents` for targeted paid hosted agent search by `query`,
-`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
-`hasX402Endpoint`. Use `sap_list_all_agents` for user requests such as "give me
-a list of all agents in the SAP ecosystem rn"; start with a small `limit` and
-continue with `pagination.nextCursor`. If a capability lookup returns zero,
-retry with `query` or `wallet` before reporting that the agent is absent.
+Use free exact/base reads before paid discovery when possible:
+`sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+`sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+`sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+`includeProtocolIndexes: false`.
+Use `sap_discover_agents` for targeted paid hosted search by `query`, `wallet`,
+`agentPda`, `protocol`, `capability`, `capabilities`, or `hasX402Endpoint`.
+Use paid `sap_list_all_agents` for user requests such as "give me a list of all
+agents in the SAP ecosystem rn"; start with a small `limit` and continue with
+`pagination.nextCursor`. If a capability lookup returns zero, retry with
+`query` or `wallet` before reporting that the agent is absent.
+
+Use `sap_agent_next_action` before retrying any SAP MCP error or partial write
+result. It normalizes `payment_required`, `hosted_local_signer_required`,
+transient Solana RPC failures, missing local bridge tools, and unconfirmed
+submitted signatures into the next safe tool route.
 
 Use `sap_protocol_invariants` before registry writes when the program id,
 protocol treasury, source-level 0.1 SOL registration fee invariant, hosted
@@ -191,7 +201,10 @@ Protocol routing shortcuts:
 
 | User intent | Most specific tools |
 | --- | --- |
-| SOL or SPL balance | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts` |
+| SOL or SPL balance (free) | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance` |
+| Enriched holdings (paid read-premium) | `jupiter_getHoldings` |
+| Pre-call cost estimate (free) | `sap_estimate_tool_cost` |
+| Pricing catalog (free) | `sap_pricing_catalog` |
 | SOL or SPL transfer | `spl-token_transferSol`, `spl-token_transfer` |
 | Token launch/mint/burn | `spl-token_deployToken`, `spl-token_mintTo`, `spl-token_burn` |
 | Jupiter quote/swap | `jupiter_getQuote`, `jupiter_smartSwap`, `jupiter_swap`, `jupiter_swapInstructions` |

package/skills/sap-operations/SKILL.md

@@ -36,6 +36,12 @@ Use `sap_discover_agents` for targeted hosted directory reads by `query`,
 `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
 `hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
 requests, keep pages small, and continue with `pagination.nextCursor`.
+For first-pass orientation, prefer free reads: `sap_agent_context`,
+`sap_get_agent`, `sap_get_agent_profile`, `sap_get_agent_stats`,
+`sap_is_agent_active`, `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
+`view: "compact"`, and `includeProtocolIndexes: false`. Use paid discovery
+only when the user needs search, enrichment, full rows, large pages, analytics,
+or global enumeration beyond the compact page.
 
 Before registering or updating an agent profile, call free
 `sap_protocol_invariants` when treasury, registration fee, hosted write route,
@@ -52,6 +58,11 @@ Hosted accountless SAP MCP cannot sign wallet-owned registry writes. If hosted
 `confirmationStatus`, and `protocolFee.status`; after update, fetch the agent
 profile again and compare the changed fields.
 
+If any SAP operation returns `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted signature
+that did not confirm, call `sap_agent_next_action` before retrying. Follow its
+`safeToRetryNow` and `nextTool` fields.
+
 ## Memory
 
 Use: