hive-intelligence 1.1.3 → 1.3.0

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Hive Intelligence. All rights reserved.
+
+This software, including its source code and compiled artifacts, is the
+proprietary and confidential property of Hive Intelligence. It is published
+solely to enable authorized installation and use of the Hive command-line
+interface and Hive MCP server.
+
+No license or right is granted to any person to copy, modify, merge, publish,
+redistribute, sublicense, sell, reverse engineer, decompile, or create
+derivative works of this software, in whole or in part, in source or compiled
+form, except as expressly authorized in writing by Hive Intelligence.
+
+Bundled third-party components retain their own licenses. The Hive agent skills
+distributed under agent-skills/ are licensed separately under the MIT License
+(see agent-skills/LICENSE).
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,66 +1,143 @@
 # Hive Intelligence
 
-Crypto intelligence for AI agents, shipped as an MCP server and CLI.
+[![npm version](https://img.shields.io/npm/v/hive-intelligence.svg)](https://www.npmjs.com/package/hive-intelligence)
+[![Node.js 22.12+](https://img.shields.io/badge/node-%3E%3D22.12-339933.svg)](https://nodejs.org/)
+[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](./LICENSE)
+[![MCP compatible](https://img.shields.io/badge/MCP-compatible-111827.svg)](https://modelcontextprotocol.io/)
 
-`hive-intelligence` gives Claude Code, Cursor, VS Code, ChatGPT Desktop,
-Gemini CLI, Codex, and custom agents one way to discover and call live crypto
-data. Agents get a compact MCP surface, schema lookup, bounded execution,
-provider provenance, and runtime status instead of a wall of raw endpoints.
+One connection for evidence-backed crypto due diligence. Every Hive-backed
+answer carries sources, freshness, and a runtime receipt.
+
+Hive gives Claude Code, Cursor, VS Code, OpenAI Responses API, Gemini CLI,
+Codex, and supported custom agents one compact way to discover and call live
+crypto data. Agents route through task toolsets, inspect schemas before
+execution, keep calls bounded, and return provider provenance plus runtime
+status instead of browsing a wall of raw endpoints. Hive is shipped as a
+hosted MCP server, local `stdio` runtime, CLI, and REST API.
 
 ```bash
-npx -y -p hive-intelligence@latest hive init --all --browser
+npx -y -p hive-intelligence@latest hive init --all
 ```
 
-Use the hosted MCP when you want Hive to run the server, auth, rate limits, and
-provider infrastructure. Use local `stdio` when you want a desktop/self-hosted
-MCP process or provider-key experiments.
+Use the hosted MCP when you want Hive to run auth, rate limits, provider
+infrastructure, and runtime status. Use local `stdio` when you want desktop
+client setup, self-hosting, or provider-key experiments.
 
 ## What You Get
 
-- 351 provider tools across market data, wallets, DeFi, DEX, NFTs, token and
-  contract data, security risk, network infrastructure, search, Solana, and
-  prediction markets.
-- A compact root MCP endpoint with 13 discovery and execution tools, so agents
-  can route before they call.
+- Evidence-backed workflows for token diligence, wallet investigation,
+  security checks, market research, DeFi, DEX pools, NFTs, Solana, prediction
+  markets, and durable monitoring.
+- A compact eight-tool root MCP workflow surface — three direct hero tools
+  (`get_token_price`, `check_token_safety`, `get_wallet_portfolio`) plus the
+  five-tool discovery loop, so agents can route before they call.
 - Task toolsets for market research, token diligence, wallet investigation,
   security checks, DEX pool analysis, DeFi research, NFT research, Solana
-  analysis, network infrastructure, and prediction markets.
-- A CLI for auth, client setup, tool discovery, schema inspection, direct tool
-  calls, diagnostics, aliases, and polling.
+  analysis, network infrastructure, prediction markets, and stateful monitoring.
+- CLI commands for auth, client setup, tool discovery, schema inspection,
+  direct execution, diagnostics, aliases, polling, and config generation.
 - Runtime resources for providers, categories, full tool catalog, task
   toolsets, canaries, skills, and status metadata.
-- Shipped agent skills that teach assistants how to use Hive through discovery,
-  schema lookup, bounded execution, and provenance-aware reporting.
+- Bundled agent skills that teach assistants the right Hive workflow:
+  discovery -> schema lookup -> bounded execution -> evidence receipt.
+- A broad provider catalog remains available behind discovery for agents that
+  need a long-tail endpoint. The current catalog contains 615 tools, but that
+  coverage is not the primary product contract.
 
-## Install Fast
+## Quickstart
 
 Requirements:
 
-- Node.js 20+
+- Node.js 22.12+ (Node.js 24 LTS recommended)
 - npm
-- A Hive API key for the hosted MCP or hosted REST API
+- Browser authorization for interactive hosted MCP after OAuth activation, or
+  a Hive API key for direct CLI, REST, and headless agents
 
-Create a key in the Hive dashboard:
+For the fastest proof before setup, run the fixed, read-only public demo. It
+requires no account and returns the same source/freshness/runtime-receipt shape
+used by authenticated calls:
+
+```text
+https://www.hiveintelligence.xyz/playground
+```
+
+For direct CLI or headless REST access, create a key:
 
 ```text
 https://www.hiveintelligence.xyz/login?next=/dashboard/keys
 ```
 
-Then configure your client:
+After hosted OAuth activation, configure OAuth-capable AI clients without
+putting a secret in their config:
+
+```bash
+npx -y -p hive-intelligence@latest hive init --all
+```
+
+For automation, exit code `0` means every detected programmable client,
+requested skill install, and enabled readiness check completed; partial setup
+returns non-zero and is detailed in `--json` output.
+
+For direct CLI or headless REST use, sign in separately:
 
 ```bash
 npx -y -p hive-intelligence@latest hive auth login
-npx -y -p hive-intelligence@latest hive config claude-code
 ```
 
-For one-command setup across detected local clients:
+Make a first successful call:
 
 ```bash
-npx -y -p hive-intelligence@latest hive init --all --browser
+npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json
 ```
 
+Expected output shape:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "bitcoin": {
+      "usd": 0
+    }
+  },
+  "meta": {
+    "provider": "CoinGecko",
+    "runtime_status": "ok",
+    "fetched_at": "2026-07-11T12:00:00.000Z",
+    "observed_at": "2026-07-11T11:59:59.900Z",
+    "cache_age_ms": 100,
+    "source": "live",
+    "receipt_id": "00000000-0000-4000-8000-000000000000",
+    "receipt_version": "1.0",
+    "server_version": "1.3.0",
+    "build_sha": null,
+    "digest_algorithm": "sha256",
+    "input_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "result_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "duration_ms": 0
+  }
+}
+```
+
+Use `--json` for scripts and agents. Use `--pretty` for human-readable output.
+
 ## Connect Hosted MCP
 
+After hosted OAuth activation, use secret-free config prefill for OAuth-capable
+clients. Review the public URL in the client, approve it, and complete Hive
+authorization in the browser. These links never contain an API key:
+
+Use these native OAuth paths only after the hosted protected-resource metadata
+reports OAuth enabled. Until that deployment gate is open, use the API-key
+fallback from a trusted client/backend; do not paste a key into an install URL.
+
+[![Cursor setup](https://img.shields.io/badge/Cursor-Setup-000000.svg?logo=cursor)](https://www.hiveintelligence.xyz/install/cursor)
+[![VS Code setup](https://img.shields.io/badge/VS_Code-Setup-0098FF?logo=visualstudiocode&logoColor=white)](https://www.hiveintelligence.xyz/install/vs-code)
+
+The setup pages check the live OAuth and release contract before exposing a
+native install action, so a stale deployment cannot masquerade as a successful
+one-click install.
+
 Hosted MCP URL:
 
 ```text
@@ -70,28 +147,59 @@ https://mcp.hiveintelligence.xyz/mcp
 Claude Code:
 
 ```bash
-claude mcp add --transport http --header "Authorization: Bearer YOUR_HIVE_API_KEY" hive https://mcp.hiveintelligence.xyz/mcp
+claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp
+```
+
+OpenAI Codex:
+
+```bash
+codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp
+codex mcp login hive
 ```
 
-Generic MCP JSON for clients that support remote HTTP and custom headers:
+Generic OAuth-capable Streamable HTTP config:
 
 ```json
 {
   "mcpServers": {
     "hive": {
-      "url": "https://mcp.hiveintelligence.xyz/mcp",
-      "headers": {
-        "Authorization": "Bearer YOUR_HIVE_API_KEY"
-      }
+      "url": "https://mcp.hiveintelligence.xyz/mcp"
     }
   }
 }
 ```
 
-Header-based API key auth works for MCP clients that support custom headers,
-including Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex, and
-ChatGPT Desktop. Claude.ai custom connectors and directory submissions require
-OAuth-compatible auth; Hive does not implement OAuth/CIMD yet.
+For headless automation that cannot open a browser, add
+`Authorization: Bearer $HIVE_API_KEY` from secret storage instead.
+
+## Client Compatibility
+
+| Client                                | Hosted HTTP MCP  | Hosted auth                         | Local stdio | Recommended setup                                                            |
+| ------------------------------------- | ---------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------- |
+| Claude Code                           | Yes              | OAuth or API-key fallback           | Yes         | `claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp`  |
+| Cursor                                | Yes              | OAuth or API-key fallback           | Yes         | Secret-free config prefill above                                             |
+| VS Code                               | Yes              | OAuth or API-key fallback           | Yes         | Secret-free config prefill above                                             |
+| Windsurf / Devin Desktop              | Yes              | OAuth or API-key fallback           | Yes         | Add the hosted URL in MCP settings                                           |
+| Gemini CLI                            | Yes              | OAuth or API-key fallback           | Yes         | `gemini mcp add hive https://mcp.hiveintelligence.xyz/mcp --transport http --scope user`  |
+| Codex                                 | Yes              | OAuth or API-key fallback           | Yes         | `codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp`, then `codex mcp login hive` |
+| OpenAI Responses API                  | Yes              | API-key authorization token         | No          | Use a server-side remote MCP `tools` entry                                   |
+| ChatGPT custom apps                   | Deployment-gated | OAuth 2.1                           | No          | Direct after hosted OAuth + consent activation; use Responses API until then |
+| Claude custom connectors/directory    | Deployment-gated | OAuth 2.1                           | No          | Direct after hosted OAuth + consent activation                               |
+| Grok custom connectors                | Deployment-gated | OAuth 2.1                           | No          | Add the hosted URL at `grok.com/connectors`                                  |
+
+Header-based API key auth works today for clients or API surfaces that support
+custom headers or authorization tokens. The server also includes a fail-closed
+OAuth 2.1 foundation with PKCE, protected-resource discovery, CIMD/DCR, rotating
+refresh tokens, and revocation. It is disabled until the hosted deployment and
+the Hive consent page are configured. See [MCP OAuth 2.1 operations](docs/OAUTH.md).
+
+Codex versions that do not show `--url` in `codex mcp add --help` must be
+updated before the remote-MCP command will work. Run `codex update` when the
+installed release supports self-update; otherwise update it through the
+installer or package manager you originally used. Public OpenAI/Codex and Cursor
+plugin artifacts are staged in the public SDK, but marketplace installs are not
+advertised as live until external approval and clean-profile verification. See
+[the distribution runbook](docs/DISTRIBUTION.md).
 
 ## Run Local stdio MCP
 
@@ -118,6 +226,24 @@ or your own upstream provider keys.
 Running `hive` with no subcommand starts the `stdio` MCP server. `hive-mcp`
 remains available as a backward-compatible binary alias.
 
+## Staying Current
+
+The hosted MCP (`https://mcp.hiveintelligence.xyz/mcp`) is managed by Hive.
+Local `stdio` installs are pinned to whatever your client last fetched, so:
+
+- Keep `hive-intelligence@latest` in your client config (as shown above) so each
+  host restart re-resolves the newest version.
+- Run `hive upgrade` to update a global install and clear the npx cache, then
+  restart your MCP client to load it:
+
+```bash
+npx -y -p hive-intelligence@latest hive upgrade
+```
+
+`hive` checks npm for newer versions once a day and surfaces the result through
+`hive doctor` and the MCP server instructions, so your agent can prompt you when
+an update is available. Set `HIVE_NO_UPDATE_CHECK=1` to disable the check.
+
 ## Use The CLI
 
 Search the catalog:
@@ -145,28 +271,60 @@ npx -y -p hive-intelligence@latest hive doctor
 npx -y -p hive-intelligence@latest hive status
 ```
 
-Useful setup commands:
+Generate client config:
 
 ```bash
-npx -y -p hive-intelligence@latest hive config claude-desktop
+npx -y -p hive-intelligence@latest hive config claude-code
+npx -y -p hive-intelligence@latest hive config codex
 npx -y -p hive-intelligence@latest hive config cursor
 npx -y -p hive-intelligence@latest hive config vscode
+npx -y -p hive-intelligence@latest hive config grok
 ```
 
-Use `--json` for scripts and agents. Use `--pretty` for human-readable output.
-
 ## How Agents Should Use Hive
 
 Hive is designed for retrieval-led agent work:
 
-1. Discover the task surface with `search_tools`, `hive://toolsets`, or
-   `hive tools search`.
-2. Inspect exact parameters with `get_api_endpoint_schema` or
-   `hive tools info`.
-3. Execute through `invoke_api_endpoint`, category tools, REST, or the CLI.
-4. Preserve provider, freshness, cache, `_hive`, `meta`, and runtime status in
-   the final answer.
-5. Keep reads bounded with `limit`, `page`, `per_page`, or `offset`.
+1. Call `search_tools` or read the compact `hive://toolsets` index. Search
+   returns at most three compact workflow matches by default; use its cursors
+   instead of loading the entire catalog.
+2. Load one exact workflow with `hive://toolsets/{id}` or select the compact
+   matching `routes[]` entry returned by `search_tools`. Choose the route whose
+   trigger/question matches the user's decision, preserve its `route_id`, and
+   follow its ordered primary calls, per-call fallback conditions, four-call
+   budget, and stop condition. The broad `coverageCatalog` is capability
+   coverage, not an execution plan.
+3. Inspect exact parameters and the endpoint's `operation` for every selected
+   route step with `get_api_endpoint_schema` or `hive tools info`.
+4. Execute reads through `invoke_api_endpoint`. For a Hive-native state change,
+   obtain explicit user approval and use `invoke_stateful_endpoint`; clients
+   must not auto-approve that conservatively destructive router.
+5. Copy each material call's server-returned `_hive` block into the workflow
+   receipt, map each material `claims[]` entry to exact receipt IDs, account
+   for each canonical `coverage[]` phase, include the selected `route_id`, then
+   call `validate_task_result` before presenting a structured result.
+   Validation checks route membership and order, conditional fallback use,
+   call budget, structure, and consistency; it does not make an invented
+   receipt authentic.
+6. Stop when the decision is answerable, a material gap cannot be resolved, or
+   the workflow budget is reached. Report partial evidence instead of silently
+   expanding scope.
+
+`search_tools`, `get_api_endpoint_schema`, `validate_task_result`, MCP
+`tools/list`, and resource reads cost zero Hive credits.
+Material endpoint executions cost one credit each.
+
+Freshness has two layers. `_hive.observed_at` is when Hive first observed the
+response, or the original cache-population time on a cache hit;
+`cache_age_ms: 0` means newly retrieved by Hive, not necessarily that the
+upstream datum is current. Use a provider timestamp, block, slot, transaction,
+or candle close for source recency. If the provider supplies none, report
+upstream recency as unknown.
+
+The runtime receipt also includes server/build version plus SHA-256
+`input_digest` and `result_digest` self-checks. The result check covers the
+canonical normalized returned payload with the top-level `_hive` block
+removed. They are not signatures and do not imply a retained receipt lookup.
 
 This flow lets an agent answer questions like:
 
@@ -175,6 +333,7 @@ This flow lets an agent answer questions like:
 - "Compare Aave and Curve by TVL, fees, chains, and risk."
 - "Find active prediction markets for the next Fed decision."
 - "Show the best pools for this token and explain liquidity risk."
+- "Remember this wallet monitor and report when important activity changes."
 
 ## MCP Contract
 
@@ -193,9 +352,72 @@ http://localhost:8080/mcp
 Root MCP tools:
 
 - `search_tools`
-- 10 category listing tools, one per crypto domain
 - `get_api_endpoint_schema`
-- `invoke_api_endpoint`
+- `invoke_api_endpoint` for read-only endpoints
+- `invoke_stateful_endpoint` for explicitly approved Hive state changes
+- `validate_task_result` for structural workflow-output validation
+
+## Stateful Monitoring And B2B State
+
+Hive's stateful monitor tools let authenticated agents store durable crypto
+intelligence intent in Hive instead of relying on chat memory. Direct users get
+one default state subject per Hive account. B2B partners can use one Hive API
+key from a trusted backend adapter while isolating downstream customers by
+signed tenant/end-user subject headers.
+
+The stateful surface includes monitor CRUD, stored run reads, observations,
+alerts, latest snapshots, memory facts, generated reports, and B2B subject admin
+tools. The scheduled worker runs wallet, token, protocol, market,
+prediction-market, watchlist digest, token discovery risk, and risk watch
+workflows. Inspect the exact endpoint schema first. Reads use
+`invoke_api_endpoint`; creates, updates, archives, remembers, forgets, and alert
+status changes require explicit user approval and use
+`invoke_stateful_endpoint`. See
+[`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md#stateful-monitoring) for the
+full monitor, subject-signing, worker, table, and smoke-test contract.
+The same 10-minute worker also persists current-build provider, MCP protocol,
+task, and workflow canary evidence in Redis for `/api/health` and `/status`;
+missing or stale evidence remains `unknown`.
+For partner products, use
+[`docs/B2B_PARTNER_ADOPTION.md`](docs/B2B_PARTNER_ADOPTION.md) as the
+implementation checklist.
+
+TypeScript B2B adapters should use `hive-mcp-client/b2b` instead
+of hand-building subject headers or raw monitor calls. If npm returns 404,
+publish the client package with
+[`docs/MCP_CLIENT_RELEASE.md`](docs/MCP_CLIENT_RELEASE.md) before partners
+depend on it:
+
+```ts
+import { createHiveB2BAdapter } from "hive-mcp-client/b2b";
+
+const hive = await createHiveB2BAdapter({
+  apiKey: process.env.HIVE_API_KEY!,
+  subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET!,
+});
+
+await hive.createWatchlistDigestMonitor(
+  { tenantId: workspaceId, endUserId: userId },
+  {
+    name: "Daily portfolio brief",
+    target: { wallets, tokens },
+    cadence: "daily",
+  },
+);
+```
+
+Verify a B2B key and signed-subject isolation with:
+
+```bash
+curl https://mcp.hiveintelligence.xyz/api/v1/b2b/readiness \
+  -H "Authorization: Bearer $HIVE_API_KEY"
+```
+
+```bash
+HIVE_API_KEY="hive_live_..." \
+HIVE_SUBJECT_SIGNING_SECRET="hive_subject_..." \
+npm run smoke:b2b-partner
+```
 
 Discovery resources:
 
@@ -203,8 +425,10 @@ Discovery resources:
 - `hive://categories`
 - `hive://tools`
 - `hive://toolsets`
+- `hive://toolsets/{id}` for one exact workflow, output schema, and execution policy
 - `hive://task-canaries`
 - `hive://skills`
+- `hive://skills/{name}` for one complete procedural skill
 - `hive://status`
 
 Reusable prompts:
@@ -229,17 +453,20 @@ tool lists:
 
 ## Providers
 
-| Provider | Coverage | Env var |
-| --- | --- | --- |
-| Alchemy | EVM wallet, token, NFT, transfer, simulation, gas, and RPC data | `ALCHEMY_API_KEY` |
-| CoinGecko | Prices, OHLC, trending, news | `COINGECKO_PRO_API_KEY` |
-| DeFiLlama | TVL, yields, fees, bridges | Free |
-| CCXT | CEX data, funding rates, perpetuals | Free |
-| GoPlus | Token, wallet, and dApp security | `GOPLUS_APP_KEY` + `GOPLUS_APP_SECRET` |
-| Codex | DEX analytics and Polymarket prediction markets | `CODEX_API_KEY` |
-| Helius | Solana RPC, DAS, priority fees, wallet history | `HELIUS_API_KEY` |
-| Moralis | Wallet, token, NFT, PnL, DeFi positions | `MORALIS_API_KEY` |
-| Tenderly | EVM simulation, tracing, gas estimation | `TENDERLY_API_KEY` |
+| Provider        | Coverage                                                                           | Env var                                                                                                                                         |
+| --------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Alchemy         | EVM wallet, token, NFT, transfer, simulation, gas, Solana DAS/Photon, and RPC data | `ALCHEMY_API_KEY`                                                                                                                               |
+| CoinGecko       | Prices, OHLC, trending, news                                                       | Optional `COINGECKO_PRO_API_KEY` or `COINGECKO_DEMO_API_KEY`                                                                                    |
+| DeFiLlama       | TVL, yields, fees, bridges                                                         | Free                                                                                                                                            |
+| CCXT            | CEX data, funding rates, perpetuals                                                | Free                                                                                                                                            |
+| GoPlus          | Token, wallet, NFT, approval, phishing, and dApp security                          | `GOPLUS_APP_KEY` or `GOPLUS_API_KEY`, plus `GOPLUS_APP_SECRET`                                                                                  |
+| Codex           | DEX analytics and Polymarket prediction markets                                    | `CODEX_API_KEY`                                                                                                                                 |
+| Helius          | Solana RPC, DAS, priority fees, wallet history                                     | `HELIUS_API_KEY`                                                                                                                                |
+| Moralis         | Wallet, token, NFT, PnL, DeFi positions                                            | `MORALIS_API_KEY`                                                                                                                               |
+| Tenderly        | EVM simulation, tracing, gas estimation, and read-only Node RPC                    | REST: `TENDERLY_API_KEY` + `TENDERLY_ACCOUNT_SLUG` + `TENDERLY_PROJECT_SLUG`; Node: `TENDERLY_NODE_ACCESS_KEY` or `TENDERLY_GATEWAY_ACCESS_KEY` |
+| Hyperliquid     | Full /info surface: perp/spot markets, order books, user state, vaults, staking, borrow/lend, HIP-4 outcome markets | Free                                                                                                                                            |
+| Open Data Fetch | Allowlisted, size-capped access to long-tail public crypto APIs                    | Free                                                                                                                                            |
+| FRED            | US macro indicators (CPI, fed funds, Treasury curve, GDP, unemployment) — government-sourced series allowlist only | `FRED_API_KEY` (free from the St. Louis Fed)                                                                                                    |
 
 Providers without configured keys remain discoverable and return classified
 runtime status such as `missing_key`, `plan_required`, `rate_limited`,
@@ -271,6 +498,17 @@ curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
   }'
 ```
 
+## Troubleshooting
+
+| Symptom                                                     | What to check                                                                                                                          |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `API key required`                                          | Run `hive auth login`, pass `--api-key`, or set the hosted MCP `Authorization: Bearer ...` header.                                     |
+| `Unsupported engine` or install failure                     | Use Node.js 22.12 or newer; Node.js 24 LTS is recommended.                                                                             |
+| Hosted MCP works in one client but not another              | Confirm whether the client uses custom API-key headers or native OAuth. Native connectors require the hosted OAuth deployment and consent page to be enabled. |
+| A provider tool returns `missing_key`                       | The tool is discoverable, but that provider needs an env var such as `ALCHEMY_API_KEY`, `HELIUS_API_KEY`, or `MORALIS_API_KEY`.        |
+| A provider returns `rate_limited`, `degraded`, or `failing` | Check `hive status`, `hive doctor`, or `hive://status` for runtime status and retry guidance.                                          |
+| `npx` install/cache errors                                  | Retry with a clean cache: `NPM_CONFIG_CACHE=$(mktemp -d) npx -y -p hive-intelligence@latest hive --help`.                              |
+
 ## Develop Locally
 
 Install:
@@ -303,10 +541,6 @@ npm run verify:agent-skills
 npm run env:render:check
 ```
 
-Use focused checks while iterating. Run `npm run check` before releases and
-after changes to shared MCP behavior, auth, middleware, provider routing, task
-toolsets, generated metadata, or CLI setup paths.
-
 ## Package Contents
 
 The `hive-intelligence` npm package includes:
@@ -316,31 +550,27 @@ The `hive-intelligence` npm package includes:
 - Bundled Hive agent skills in `agent-skills/`.
 - Local `stdio` MCP runtime for desktop clients and self-hosting.
 
-## Architecture Map
+## Contributor Context
+
+Core implementation areas:
 
-- `src/mcpServer.ts` builds root/category MCP servers, tools, resources,
-  prompts, and runtime instructions.
-- `src/server.ts` runs Express, Streamable HTTP MCP, REST routes, auth, rate
-  limits, CORS, security headers, discovery descriptors, and shutdown.
-- `src/toolRegistry.ts` defines the 10 category surfaces.
-- `src/wrapper/allEndpoints.ts` maps provider tools into the public Hive tool
-  catalog.
+- `src/mcpServer.ts` builds the MCP servers, tools, resources, prompts, and
+  runtime instructions.
+- `src/server.ts` runs Express, Streamable HTTP MCP, REST routes, auth,
+  middleware, discovery descriptors, and shutdown.
 - `src/taskToolsets.ts` defines the workflow surface agents should prefer over
-  raw endpoint browsing.
-- `src/agentSkills.ts` and `agent-skills/` ship agent-installable Hive skills.
+  raw endpoint browsing. See the [workflow design contract](docs/WORKFLOW_DESIGN.md)
+  for composition and receipt requirements.
 - `src/cli.ts` and `src/cli/` expose auth, setup, discovery, execution,
   diagnostics, config generation, aliases, and watch mode.
-- `packages/mcp-client/` contains the typed client adapter.
-- `tests/` covers unit, integration, E2E, MCP compliance, live, security, and
-  Docker readiness paths.
+- `agent-skills/` ships agent-installable Hive skills.
 
 ## Links
 
 - Website: https://www.hiveintelligence.xyz
 - Hosted MCP: https://mcp.hiveintelligence.xyz/mcp
-- Docs overview: https://github.com/sharpe-labs/hive-mcp2/blob/master/docs/DOCUMENTATION.md
-- Tool reference: https://github.com/sharpe-labs/hive-mcp2/blob/master/docs/TOOLS_REFERENCE.md
-- Agent instructions: https://github.com/sharpe-labs/hive-mcp2/blob/master/AGENTS.md
-- Contributing: https://github.com/sharpe-labs/hive-mcp2/blob/master/CONTRIBUTING.md
-- Security: https://github.com/sharpe-labs/hive-mcp2/blob/master/SECURITY.md
-- Changelog: https://github.com/sharpe-labs/hive-mcp2/blob/master/CHANGELOG.md
+- Public SDK and issues: https://github.com/hive-intel/hive-sdk
+- Authenticated REST tool catalog: https://mcp.hiveintelligence.xyz/api/v1/tools
+- Public live catalog overview: https://www.hiveintelligence.xyz/tools/live-catalog
+- Install guides: https://www.hiveintelligence.xyz/install
+- Quick start: https://www.hiveintelligence.xyz/quick-start

package/agent-skills/.claude-plugin/plugin.json

@@ -1,15 +1,16 @@
 {
   "name": "hive-agent-skills",
-  "version": "1.0.0",
-  "description": "Hive Intelligence skills for Claude Code, Cursor, Codex, and other agents. Covers Hive MCP setup, tool discovery, crypto workflows, CLI flows, and PKCE-based authentication. Install via `npx -y -p hive-intelligence@latest hive init --all --browser` or copy the packs into the target agent skills directory.",
+  "version": "0.2.0",
+  "description": "Hive Intelligence skills for Claude Code, Cursor, Codex, and other agents. Covers OAuth-first Hive MCP setup, tool discovery, evidence-backed crypto workflows, CLI flows, and runtime receipts. Install via `npx -y -p hive-intelligence@latest hive init --all` or copy the packs into the target agent skills directory.",
   "author": {
     "name": "Hive Intelligence",
     "url": "https://www.hiveintelligence.xyz",
     "email": "support@hiveintelligence.xyz"
   },
   "homepage": "https://www.hiveintelligence.xyz",
-  "repository": "https://github.com/sharpe-labs/hive-mcp2",
+  "repository": "https://github.com/hive-intel/hive-skills",
   "license": "MIT",
+  "mcpServers": "./.mcp.json",
   "skills": [
     {
       "name": "hive-cli",
@@ -24,7 +25,7 @@
     {
       "name": "hive-build-onboarding",
       "path": "../packs/hive-build-onboarding/SKILL.md",
-      "description": "Walk the user through PKCE-based browser auth. Use when the user has no API key or cannot find theirs."
+      "description": "Walk the user through browser-based sign-in. Use when the user has no API key or cannot find theirs."
     },
     {
       "name": "hive-build",
@@ -90,6 +91,11 @@
       "name": "hive-prediction-markets",
       "path": "../packs/hive-prediction-markets/SKILL.md",
       "description": "Research prediction markets, events, outcomes, market stats, traders, holders, and trades."
+    },
+    {
+      "name": "hive-stateful-monitoring",
+      "path": "../packs/hive-stateful-monitoring/SKILL.md",
+      "description": "Create, list, update, and archive durable crypto monitors, alerts, scheduled reports, and agent memory."
     }
   ],
   "tags": [

package/agent-skills/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hive": {
+      "type": "http",
+      "url": "https://mcp.hiveintelligence.xyz/mcp"
+    }
+  }
+}