@buildaureon/mcp 0.1.2 → 0.1.8

package/docs/auth.md

@@ -1,6 +1,6 @@
 # Authentication Guide
 
-How **`@buildaureon/mcp`** `v0.1.1` authenticates to the live AUREON API — aligned with `@buildaureon/sdk`, safe for humans and for agents that call the **34** stdio tools.
+How **`@buildaureon/mcp`** `v0.1.1` authenticates to the live AUREON API — aligned with `@buildaureon/sdk`, safe for humans and for agents that call the **43** stdio tools.
 
 Related docs: [Setup](./setup.md) · [Tools](./tools.md) · [Agent guide](./agent-guide.md) · [Architecture](./architecture.md) · [Security](./security.md) · [Package README](../README.md)
 
@@ -19,7 +19,7 @@ If you have not configured the host yet, start with [./setup.md](./setup.md), th
 
 ## Goals of MCP auth
 
-1. Reach `https://api.aureonlabs.network` with credentials the gateway accepts.
+1. Reach the resolved API (default local mainnet `http://127.0.0.1:8788` / 4663). Opt in to the public host with `AUREON_NETWORK=testnet` (still 46630).
 2. Bind control-plane actions to a wallet identity (issued key or Bearer session).
 3. Keep signing and broadcasting of on-chain vault steps **outside** MCP.
 4. Prefer a long-lived issued key for always-on agents over interactive wallet handshakes.
@@ -49,9 +49,10 @@ Plain language:
 
 | Variable | Role |
 | --- | --- |
-| `AUREON_API_KEY` | Preferred. Issued developer key from [app.aureonlabs.network](https://app.aureonlabs.network) **Developers**. |
+| `AUREON_API_KEY` | Preferred. Issued developer key. |
 | `AUREON_AUTH_TOKEN` | Optional Bearer. Use when you intentionally want a session without (or in addition to) a key — see conflict rules below. |
-| `AUREON_API_URL` | Defaults to `https://api.aureonlabs.network`. Leave default for public use. |
+| `AUREON_NETWORK` | Optional. Omit for mainnet (4663 / 8788). Set `testnet` for the public host (still 46630). |
+| `AUREON_API_URL` | Optional override. Must match `AUREON_NETWORK` if both are set. |
 
 Startup rule: at least one of `AUREON_API_KEY` or `AUREON_AUTH_TOKEN` must be set or the MCP process exits with a clear error.
 
@@ -65,18 +66,18 @@ This is the default for Cursor, Claude, and other always-on agents.
 
 ### Steps
 
-1. Open [https://app.aureonlabs.network](https://app.aureonlabs.network).
+1. Issue a key on the **same** API you will call. Local mainnet: Developers on `http://127.0.0.1:5174`. Public testnet: [app.aureonlabs.network](https://app.aureonlabs.network) (still 46630).
 2. Connect the wallet that should own objectives and Capital Book state.
 3. Open **Developers** and create a key (name it after the host, e.g. `cursor-mcp`).
 4. Copy the secret once into the host MCP `env` as `AUREON_API_KEY`.
 5. Do **not** set `AUREON_AUTH_TOKEN` unless you have a specific reason.
 6. Restart the host and call `aureon_ping` then `aureon_me`.
 
-Minimal env:
+Minimal env (local mainnet 8788 / 4663):
 
 ```bash
-AUREON_API_URL=https://api.aureonlabs.network
 AUREON_API_KEY=aureon_....
+# AUREON_NETWORK=testnet   # only for the public host (still 46630)
 ```
 
 With only the issued key, agents can sync portfolio, create objectives, fetch restore plans, restore, refresh watchdog, and manage developer keys — without an interactive signature each session.
@@ -218,9 +219,9 @@ Never paste a private key into MCP tool arguments or host env “for convenience
 | `401` Unauthorized | Key revoked/paused, Bearer expired, or typo | Rotate key or re-verify wallet |
 | Wrong wallet on `aureon_me` | Bearer winning over key | `aureon_logout`; remove env Bearer; restart |
 | `aureon_verify_wallet` fails | Bad signature, stale nonce, or missing invite | New nonce; re-sign; supply `inviteCode` if required |
-| `aureon_dev_login` fails on live API | Expected | Use issued key on `https://api.aureonlabs.network` |
+| `aureon_dev_login` fails on live API | Expected | Use an issued key. Public host is still 46630. |
 | Prepare tools succeed but funds do not move | Unsigned steps not broadcast | Sign outside MCP with a real wallet |
-| Agent invents a local API URL | Misconfigured override | Reset `AUREON_API_URL` to the live default |
+| Agent invents a local API URL | Misconfigured override | Omit `AUREON_API_URL` for 8788, or set `AUREON_NETWORK=testnet` |
 
 Map structured SDK errors in tool output to the same categories; do not retry blindly on `401` without rotating credentials.
 
@@ -247,13 +248,14 @@ Map structured SDK errors in tool output to the same categories; do not retry bl
 MCP host (Cursor / Claude)
     │  stdio
     ▼
-@buildaureon/mcp  (34 tools, no private key)
+@buildaureon/mcp  (54 tools, no private key)
     │
     ▼
 @buildaureon/sdk  (HTTP, retries, types)
-    │  HTTPS + API key and/or Bearer
+    │  HTTP(S) + API key and/or Bearer
     ▼
-https://api.aureonlabs.network
+default http://127.0.0.1:8788 (4663)
+opt-in  https://api.aureonlabs.network (still 46630)
     │
     ├── control plane (objectives, portfolio, restore, …)
     └── prepare vault steps → human/agent signs elsewhere
@@ -318,7 +320,7 @@ Do not reuse the compromised secret “temporarily.” Treat rotation as mandato
 
 - Issued key → API key header / client option
 - Bearer → access token via the session provider
-- Base URL → `https://api.aureonlabs.network` by default
+- Base URL → `http://127.0.0.1:8788` by default (4663). Public host is `AUREON_NETWORK=testnet` (still 46630).
 
 If a typed SDK script works with your issued key but MCP fails, compare env names (`AUREON_API_KEY` vs hard-coded client options) and confirm the host actually injects env into the stdio child process.
 

package/docs/security.md

@@ -15,12 +15,12 @@ This document is for operators configuring agent hosts and for AI agents that mu
 | Private key | Never enters MCP env or process | Full fund theft if combined with broadcast capability |
 | Host LLM / agent | Can call any enabled tool | Prompt injection or confused deputy may trigger writes |
 | Operator utility | Separate wallet-Bearer UI | Unrelated to MCP, but same API identity if same wallet |
-| HTTPS to API | TLS to `https://api.aureonlabs.network` | MITM only if TLS broken or base URL pointed at attacker |
+| HTTP(S) to API | Default local 8788 (4663). Public host TLS is `https://api.aureonlabs.network` (still 46630) | MITM if URL pointed at attacker |
 
 ```mermaid
 flowchart LR
   Host[MCP_host_and_LLM] -->|tool_calls_stdio| MCP[local_MCP_adapter]
-  MCP -->|API_key_and_optional_Bearer| API[api.aureonlabs.network]
+  MCP -->|API_key_and_optional_Bearer| API[8788_or_public_testnet_host]
   MCP -.->|never_holds| PK[private_keys]
   Human[Human_operator] -->|reviews_and_signs| Chain[Robinhood_Chain]
   API --> Vault[Smart_Vault]
@@ -171,7 +171,7 @@ MCP hosts typically store command + env in a JSON (or UI) config. Hygiene rules:
 1. **Secrets only in env fields** managed by the host — not in chat history, not in repo files checked into git.
 2. **Do not commit** MCP config files that contain live keys. Prefer redacted examples in docs (see package `examples/`).
 3. **Restrict workspace access** — anyone who can edit MCP config can point the agent at their own key or change the API base URL.
-4. **Watch `AUREON_API_URL` overrides** — only use non-default bases when you intentionally target a documented non-production environment. A malicious override is a credential phishing vector.
+4. **Watch `AUREON_API_URL` overrides** — only use a non-default base when you intentionally target a documented other host (local 8788 is the omitted default; public `api.aureonlabs.network` is still testnet 46630). A malicious override is a credential phishing vector.
 5. **Browser vs agent hosting** — browser-based agent products may persist configs in cloud profiles; treat those as higher risk than a local desktop host you control. Prefer short-lived keys and aggressive revoke there.
 6. **Disable MCP** when not needed — reduce accidental write tool invocation.
 7. **Never ask the model to echo env** — including “debug by printing AUREON_API_KEY.”
@@ -207,7 +207,7 @@ Use this before enabling `@buildaureon/mcp` on a machine that can affect real ca
 - [ ] Issued API key created specifically for this host
 - [ ] Key stored only in host secret/env config (not in git)
 - [ ] Private keys absent from MCP env and agent-accessible storage
-- [ ] Default API URL is `https://api.aureonlabs.network` unless override is intentional
+- [ ] Default API is local 8788 / 4663 unless `AUREON_NETWORK=testnet` (public host still 46630)
 - [ ] Host is local stdio — not published as an open network service
 - [ ] Write tools understood by operators (`create`, `restore`, `prepare`, key CRUD)
 - [ ] Prepare → human sign → broadcast workflow documented for the team
@@ -332,4 +332,4 @@ Follow AUREON’s published support / security channels on the product site; inc
 
 ## 15. Summary
 
-Treat `@buildaureon/mcp` as a **local, non-custodial stdio adapter** over `@buildaureon/sdk` to `https://api.aureonlabs.network`. Protect issued keys like passwords, keep private keys out of the MCP process, require human (or hardened external) signing for deposit/withdraw broadcast, rotate and revoke quickly, and assume the LLM is not a security boundary — configuration hygiene and least privilege are.
+Treat `@buildaureon/mcp` as a **local, non-custodial stdio adapter** over `@buildaureon/sdk`. Default API is `http://127.0.0.1:8788` (4663); the public host is still testnet 46630. Protect issued keys like passwords, keep private keys out of the MCP process, require human (or hardened external) signing for deposit/withdraw broadcast, rotate and revoke quickly, and assume the LLM is not a security boundary — configuration hygiene and least privilege are.

package/docs/setup.md

@@ -2,7 +2,7 @@
 
 Complete installation and host configuration for **`@buildaureon/mcp`** `v0.1.1` against the live AUREON API.
 
-This package is a **stdio** [Model Context Protocol](https://modelcontextprotocol.io) server. It wraps [`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk) and exposes **34 tools** so Cursor, Claude Desktop, and other MCP hosts can call the Financial Compass control plane.
+This package is a **stdio** [Model Context Protocol](https://modelcontextprotocol.io) server. It wraps [`@buildaureon/sdk`](https://github.com/buildaureon/aureon-sdk) and exposes **54 tools** so Cursor, Claude Desktop, and other MCP hosts can call the Financial Compass control plane.
 
 Related docs: [Authentication](./auth.md) · [Tools](./tools.md) · [Agent guide](./agent-guide.md) · [Architecture](./architecture.md) · [Security](./security.md) · [Package README](../README.md)
 
@@ -28,8 +28,8 @@ If you only want auth semantics (key vs Bearer vs private key), skip ahead to [.
 | Requirement | Notes |
 | --- | --- |
 | **Node.js 20+** | ESM runtime. Check with `node -v`. |
-| **Issued developer API key** | Create at [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers**. Plaintext is shown once. |
-| **Network access** | HTTPS to `https://api.aureonlabs.network` (Robinhood Chain early access). |
+| **Issued developer API key** | Issue the key on the **same** API you will call. Local mainnet: Developers on `http://127.0.0.1:5174`. Public testnet: [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers** (still chain 46630). Plaintext is shown once. |
+| **Network access** | Default is local mainnet `http://127.0.0.1:8788` (chain 4663). Optional `AUREON_NETWORK=testnet` uses `https://api.aureonlabs.network` (still 46630). |
 | **MCP host** | Cursor, Claude Desktop, or any client that can launch a stdio MCP server. |
 
 You do **not** need a wallet Bearer token for day-to-day control-plane tools when you use an issued key.
@@ -48,8 +48,8 @@ The MCP server never custodies funds and never signs chain transactions.
 | Version | `0.1.1` |
 | Depends on | `@buildaureon/sdk` |
 | Transport | stdio MCP (JSON-RPC over stdin/stdout) |
-| Tool count | 34 |
-| Live API | `https://api.aureonlabs.network` |
+| Tool count | 47 |
+| Default API | `http://127.0.0.1:8788` (4663). Public host is opt-in testnet 46630. |
 | Console | [app.aureonlabs.network](https://app.aureonlabs.network) |
 
 Primary launch command (recommended for hosts):
@@ -68,11 +68,12 @@ The process reads these at startup. Put them in your MCP host `env` block (Curso
 | --- | --- | --- | --- |
 | `AUREON_API_KEY` | **Preferred** | — | Issued developer key (`aureon_…`). Product access **and** wallet identity for control-plane tools. |
 | `AUREON_AUTH_TOKEN` | Optional | — | Wallet Bearer session. Wins over key identity when both are present on a request. |
-| `AUREON_API_URL` | Optional | `https://api.aureonlabs.network` | API base URL. Leave unset unless you intentionally override. |
+| `AUREON_NETWORK` | Optional | `mainnet` | Omit for local mainnet 4663 / 8788. Set `testnet` for the public host (still 46630). |
+| `AUREON_API_URL` | Optional | mainnet `http://127.0.0.1:8788` | Override URL. Must match `AUREON_NETWORK` if both are set. |
 
 At least one of `AUREON_API_KEY` or `AUREON_AUTH_TOKEN` must be set or the server refuses to start.
 
-**Recommendation:** set only `AUREON_API_KEY` (and optionally leave `AUREON_API_URL` at the default). That is the agent-friendly path documented in [./auth.md](./auth.md).
+**Recommendation:** set only `AUREON_API_KEY` for local mainnet. Add `AUREON_NETWORK=testnet` only if you want the public host (still 46630).
 
 Never put a wallet private key in MCP env. Prepare tools return unsigned calldata; the host wallet signs elsewhere.
 
@@ -105,7 +106,6 @@ Create or edit `.cursor/mcp.json` in the project, or merge into your user MCP co
       "command": "npx",
       "args": ["-y", "@buildaureon/mcp"],
       "env": {
-        "AUREON_API_URL": "https://api.aureonlabs.network",
         "AUREON_API_KEY": "aureon_...."
       }
     }
@@ -117,6 +117,8 @@ Restart Cursor (or reload MCP servers). Confirm **aureon** appears under MCP / t
 
 Ask a smoke prompt such as: *“Use aureon_ping, then aureon_me.”*
 
+Issue the key on the same network this process will call. A public-console key does not authenticate the local 8788 mainnet API. To hit the public host (still 46630), add `"AUREON_NETWORK": "testnet"`.
+
 ### Option B — from a local build
 
 Use this only when you are iterating on a clone of the package. Replace the working directory with your own clone path.
@@ -129,7 +131,6 @@ Use this only when you are iterating on a clone of the package. Replace the work
       "args": ["dist/index.js"],
       "cwd": "/path/to/your/clone/mcp",
       "env": {
-        "AUREON_API_URL": "https://api.aureonlabs.network",
         "AUREON_API_KEY": "aureon_...."
       }
     }
@@ -154,7 +155,6 @@ Merge the same shape into Claude Desktop’s MCP config file (location depends o
       "command": "npx",
       "args": ["-y", "@buildaureon/mcp"],
       "env": {
-        "AUREON_API_URL": "https://api.aureonlabs.network",
         "AUREON_API_KEY": "aureon_...."
       }
     }
@@ -176,8 +176,8 @@ From a terminal, with the key in the environment:
 
 ```bash
 export AUREON_API_KEY=aureon_....
-# optional — live API is already the default
-export AUREON_API_URL=https://api.aureonlabs.network
+# omit AUREON_API_URL for local mainnet 8788 / 4663
+# export AUREON_NETWORK=testnet   # public host, still 46630
 
 npx -y @buildaureon/mcp
 ```
@@ -186,7 +186,8 @@ On Windows PowerShell:
 
 ```powershell
 $env:AUREON_API_KEY = "aureon_...."
-$env:AUREON_API_URL = "https://api.aureonlabs.network"
+# omit AUREON_API_URL for local mainnet 8788 / 4663
+# $env:AUREON_NETWORK = "testnet"   # public host, still 46630
 npx -y @buildaureon/mcp
 ```
 
@@ -258,7 +259,7 @@ For write workflows (create objective, restore, prepare vault), see [./agent-gui
 
 ## Verify the tool surface
 
-A healthy install exposes auth, read, objective, portfolio, execution, market, vault prepare, and developer key tools — **34** in total.
+A healthy install exposes auth, read, objective, portfolio, execution, market, vault prepare, and developer key tools — **47** in total.
 
 You do not need every tool on day one. Start with:
 
@@ -280,7 +281,7 @@ Vault **prepare** tools return unsigned steps only. Signing and broadcasting sta
 | Startup error about missing credentials | Neither key nor Bearer set | Set `AUREON_API_KEY` in the host `env` block |
 | `401` / unauthorized on tools | Bad, paused, or revoked key | Create a new issued key; update config |
 | `npx` hangs or fails | Network / registry issue | Retry; ensure Node 20+; try `npm view @buildaureon/mcp version` |
-| Tools listed but every call fails | Wrong `AUREON_API_URL` | Remove override or set `https://api.aureonlabs.network` |
+| Tools listed but every call fails | Wrong URL / mixed network | Omit `AUREON_API_URL` for 8788, or set `AUREON_NETWORK=testnet` for the public host (still 46630) |
 | `aureon_me` shows unexpected wallet | Bearer also set and winning | Clear `AUREON_AUTH_TOKEN` / logout; prefer key-only — see [./auth.md](./auth.md) |
 | Local `node dist/index.js` fails | Missing build | Run `pnpm build` so `dist/index.js` exists |
 | Deposit / withdraw “not signed” | Expected | MCP returns unsigned steps; sign outside MCP |
@@ -306,7 +307,7 @@ No. Keep private keys out of MCP. Use them only in a separate signing host when
 
 ### Does MCP talk to a local backend?
 
-Public setup uses `https://api.aureonlabs.network` only. Point hosts at that URL (or omit `AUREON_API_URL` to use the default).
+Default (omit `AUREON_API_URL`) is local mainnet `http://127.0.0.1:8788` (chain 4663). Set `AUREON_NETWORK=testnet` only for the public host (still 46630). Do not map mainnet to `api.aureonlabs.network`.
 
 ### How is this different from `@buildaureon/sdk`?
 
@@ -328,7 +329,7 @@ Node.js **20 or newer**. Older runtimes are unsupported.
 - [ ] Issued key created on the Developers page
 - [ ] Host config uses `npx -y @buildaureon/mcp` (or local `node dist/index.js` with a placeholder cwd)
 - [ ] `AUREON_API_KEY` set in host `env` (no private key)
-- [ ] `AUREON_API_URL` omitted or set to `https://api.aureonlabs.network`
+- [ ] `AUREON_API_URL` omitted (mainnet 8788). Optional `AUREON_NETWORK=testnet` for the public host (still 46630)
 - [ ] Host restarted; aureon server shows connected
 - [ ] `aureon_ping` succeeds
 - [ ] `aureon_me` returns the expected wallet

package/docs/tools.md

@@ -6,9 +6,9 @@ Each tool maps to one public method on the `@buildaureon/sdk` client. Handlers v
 
 For request/response shapes, error codes, and HTTP contracts, see the **@buildaureon/sdk documentation**.
 
-**Tool count:** 34.
+**Tool count:** 52.
 
-**API:** `https://api.aureonlabs.network` (Robinhood Chain L2, early access).
+**API:** default local mainnet `http://127.0.0.1:8788` (chain 4663). Optional `AUREON_NETWORK=testnet` uses `https://api.aureonlabs.network` (still 46630).
 
 ---
 
@@ -20,19 +20,19 @@ These conventions apply to every tool below.
 | --- | --- |
 | Issued API key | Set `AUREON_API_KEY` to an issued Developers key. That key is product access **and** wallet identity for control-plane calls. |
 | Optional Bearer | You may also supply a wallet Bearer (`AUREON_AUTH_TOKEN` or `aureon_verify_wallet`). If both key and Bearer are present, Bearer wins. |
-| Live API only | Tools talk to the live AUREON gateway. There is no local-backend mode for agents. |
+| Default network | Local mainnet 8788 / 4663. Optional `AUREON_NETWORK=testnet` for the public host (still 46630). |
 | Private key outside MCP | Deposit and withdraw **prepare** tools return unsigned steps. Signing and broadcast happen in the host wallet — never inside the MCP process. |
 | Default automation | `aureon_create_objective` defaults `automationMode` to `"auto"`. |
 | Locked at create | `targetSymbol` and `automationMode` are immutable after create. Recreate the objective to change them. |
 | Unsigned prepare | `aureon_prepare_vault_deposit` and `aureon_prepare_vault_withdraw` never broadcast. |
 | Settlement honesty | Restore / execution receipts may show `settlement: "vault"` (on-chain) or `"staged"` (ledger-local). Label them honestly. |
 
-The catalog includes `aureon_dev_login` for preview APIs only. On the live production API it fails by design — agents should use an issued key (or optional Bearer) instead.
+The catalog includes `aureon_dev_login` for preview APIs only. On hosted APIs it fails by design — agents should use an issued key (or optional Bearer) instead. The public host is still testnet 46630, not 4663.
 
 ### Auth bootstrap (agents)
 
 1. Create an issued key in the operator utility **Developers** console.
-2. Configure the MCP host with `AUREON_API_URL=https://api.aureonlabs.network` and `AUREON_API_KEY`.
+2. Configure the MCP host with `AUREON_API_KEY`. Omit `AUREON_API_URL` for local mainnet 8788. Set `AUREON_NETWORK=testnet` only for the public host (still 46630).
 3. Call tools. Day-to-day agent work does **not** require a wallet handshake.
 
 Optional wallet path: `aureon_get_auth_nonce` → host signs → `aureon_verify_wallet`. Prefer issued keys for always-on agents.
@@ -47,8 +47,8 @@ Successful calls return structured JSON (formatted for agents). Failures return
 | --- | --- |
 | Health | `aureon_ping` |
 | Auth & identity | `aureon_get_auth_nonce`, `aureon_verify_wallet`, `aureon_dev_login`, `aureon_logout`, `aureon_me` |
-| Dashboard & read | `aureon_get_overview`, `aureon_get_portfolio`, `aureon_list_objectives`, `aureon_get_objective`, `aureon_get_health`, `aureon_list_timeline`, `aureon_list_market_presets`, `aureon_get_restore_plan`, `aureon_list_executions`, `aureon_get_vault`, `aureon_get_vault_status` |
-| Objectives | `aureon_create_objective`, `aureon_update_objective`, `aureon_pause_objective`, `aureon_resume_objective` |
+| Dashboard & read | `aureon_get_overview`, `aureon_get_allocation_vs_target`, `aureon_get_objective_portfolio_flow`, `aureon_get_drift_restore_flow`, `aureon_get_receipt_verification_flow`, `aureon_get_portfolio_watch_flow`, `aureon_get_full_aureon_loop_flow`, `aureon_get_portfolio`, `aureon_list_objectives`, `aureon_get_objective`, `aureon_get_health`, `aureon_list_timeline`, `aureon_list_market_presets`, `aureon_get_restore_plan`, `aureon_list_executions`, `aureon_get_vault`, `aureon_get_vault_status` |
+| Objectives | `aureon_create_objective`, `aureon_apply_financial_intent`, `aureon_run_drift_restore_demo`, `aureon_run_receipt_verification_demo`, `aureon_run_portfolio_watch_demo`, `aureon_run_full_aureon_loop_demo`, `aureon_update_objective`, `aureon_pause_objective`, `aureon_resume_objective` |
 | Portfolio write | `aureon_set_portfolio`, `aureon_clear_portfolio`, `aureon_sync_portfolio` |
 | Execution | `aureon_run_execution`, `aureon_restore_objective` |
 | Market | `aureon_apply_market_event`, `aureon_refresh_watchdog` |
@@ -148,6 +148,154 @@ Successful calls return structured JSON (formatted for agents). Failures return
 
 **Caveats:** Overview is a summary. Drill into `aureon_get_health` / `aureon_get_objective` for policy decisions.
 
+### `aureon_get_allocation_vs_target`
+
+**Purpose:** Objective vs actual portfolio — current weight vs policy target per active objective, plus a green-book/off-plan paradox flag.
+
+**Typical args:** none.
+
+**When to use:** demos; explain when the book is up but objectives are in warning/violation; avoid stitching overview + health manually.
+
+**Returns:** `{ rows, paradox, overview }` — see `@buildaureon/sdk` `getAllocationVsTarget()`.
+
+**Caveats:** Paradox detection uses 24h book change when available. Pair with `aureon_apply_market_event` (`autoRestore: false`) for rehearsal demos.
+
+### `aureon_get_objective_portfolio_flow`
+
+**Purpose:** Read AI → objective → portfolio flow for active objectives (intent summary, objective, health, portfolio snapshot).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Filter to one objective; omit for all active |
+
+**When to use:** — confirm intent is linked to live portfolio after `aureon_apply_financial_intent`; read-only refresh without creating a new objective.
+
+**Returns:** Array of flow objects — see `@buildaureon/sdk` `getObjectivePortfolioFlow()`.
+
+**Caveats:** Only active objectives are included. Pair with `aureon_get_allocation_vs_target` for ongoing objective vs actual tracking.
+
+### `aureon_run_drift_restore_demo`
+
+**Purpose:** Run drift → detection → restore demo in one call (seed book, create stable objective, NVDA rally with `autoRestore: false`, manual restore).
+
+**Typical args:** none.
+
+**When to use:** Content Arc Day 4; teach the full loop without stitching portfolio, market, plan, and restore tools.
+
+**Returns:** `DriftRestoreFlow` — see `@buildaureon/sdk` `runDriftRestoreDemo()`.
+
+**Caveats:** Mutates portfolio and creates a new objective. Settlement may be `vault` or `staged`. Controlled rehearsal — not discretionary trading.
+
+### `aureon_get_drift_restore_flow`
+
+**Purpose:** Read drift → detection → restore flow for active objectives (health, allocation row, restore plan when off-plan, latest receipt).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Filter to one objective; omit for all active |
+
+**When to use:** Confirm three-beat arc after manual steps in workflow J; read-only monitoring.
+
+**Returns:** Array of `DriftRestoreFlow` — see `@buildaureon/sdk` `getDriftRestoreFlow()`.
+
+**Caveats:** Inferred phases when historical aligned/drift snapshots are not stored; pair with `aureon_list_timeline` for audit trail.
+
+### `aureon_run_receipt_verification_demo`
+
+**Purpose:** Run receipt → verification demo (drift-restore + validate receipt + settlement lookup + timeline).
+
+**Typical args:** none.
+
+**When to use:** Content Arc Day 5; teach claim vs validation vs chain proof without stitching restore, validate, and settlement tools.
+
+**Returns:** `ReceiptVerificationFlow` — see `@buildaureon/sdk` `runReceiptVerificationDemo()`.
+
+**Caveats:** Mutates portfolio via embedded drift-restore. Validator is local — does not re-query chain. Staged receipts validate but are not chain-verified.
+
+### `aureon_get_receipt_verification_flow`
+
+**Purpose:** Read receipt → verification flow for execution receipts (claim, validation result, settlement lookup, timeline).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `executionId` | no | Filter to one execution; omit for five most recent |
+
+**When to use:** Confirm verification tier after manual steps in workflow K.
+
+**Returns:** Array of `ReceiptVerificationFlow` — see `@buildaureon/sdk` `getReceiptVerificationFlow()`.
+
+**Caveats:** Pair with `aureon_validate_receipt` for local checks; use `aureon_get_execution_settlement` for vault chain proof.
+
+### `aureon_run_portfolio_watch_demo`
+
+**Purpose:** Run portfolio watch demo (brief → Automatic objective → while-away market event with auto restore → return briefing).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `brief` | no | User wording; default watch-while-away brief |
+| `host` | no | `cursor` \| `claude` \| `mcp` for briefing labels |
+
+**When to use:** Content Arc Day 6; Claude/Cursor + AUREON agent-in-host teaching.
+
+**Returns:** `PortfolioWatchFlow` — see `@buildaureon/sdk` `runPortfolioWatchDemo()`.
+
+**Caveats:** Mutates portfolio and objectives. Uses `autoRestore: true`. Not unsupervised trading — registered Automatic policy only.
+
+### `aureon_get_portfolio_watch_flow`
+
+**Purpose:** Read portfolio watch briefing for Automatic objectives.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Filter to one objective |
+| `brief` | no | User brief for summary lines |
+| `host` | no | Agent host label |
+
+**When to use:** Confirm briefing after manual steps in workflow L.
+
+**Returns:** Array of `PortfolioWatchFlow` — see `@buildaureon/sdk` `getPortfolioWatchFlow()`.
+
+### `aureon_run_full_aureon_loop_demo`
+
+**Purpose:** Run Content Arc full AUREON loop (intent → plan check with autoRestore false → restore → receipt verification).
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `brief` | no | User wording; default full-loop brief |
+
+**When to use:** Content Arc Day 7; positioning demo — not a portfolio tracker.
+
+**Returns:** `FullAureonLoopFlow` — see `@buildaureon/sdk` `runFullAureonLoopDemo()`.
+
+**Caveats:** Mutates portfolio. Uses `autoRestore: false` then manual restore. Staged receipts validate but are not chain-verified.
+
+### `aureon_get_full_aureon_loop_flow`
+
+**Purpose:** Read full AUREON loop for active objectives that already have an execution receipt.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `objectiveId` | no | Filter to one objective |
+| `brief` | no | User brief for teaching shape |
+
+**When to use:** Confirm closed loop after manual steps in workflow M.
+
+**Returns:** Array of `FullAureonLoopFlow` — see `@buildaureon/sdk` `getFullAureonLoopFlow()`.
+
 ### `aureon_get_portfolio`
 
 **Purpose:** Current Capital Book snapshot — positions, marks, and weights.
@@ -333,6 +481,28 @@ Successful calls return structured JSON (formatted for agents). Failures return
 
 **Caveats:** Agents should use **Automatic** (`auto`) unless the human explicitly wants Manual Approve. To change symbol or mode later, create a new objective (pause or leave the old one).
 
+### `aureon_apply_financial_intent`
+
+**Purpose:** Register user/agent intent as an Automatic objective and return the full AI → objective → portfolio flow in one call.
+
+**Typical args:**
+
+| Arg | Required | Notes |
+| --- | --- | --- |
+| `brief` | yes | What the user wants their money to do — agent-extracted wording |
+| `kind` | yes | `stable_allocation` \| `balanced_portfolio` \| `risk_ceiling` \| `reward_reinvestment` |
+| `targetWeight` | yes | 0–1 |
+| `tolerance` | yes | Drift band 0–1 |
+| `targetSymbol` | no | Asset symbol for `balanced_portfolio` |
+| `name` | no | Display name override |
+| `priority` | no | `low` \| `medium` \| `high` \| `critical` |
+
+**When to use:** turn structured agent intent into persistent policy without stitching create + health + portfolio calls.
+
+**Returns:** `{ intent, objective, health, portfolio, message }` — see `@buildaureon/sdk` `applyFinancialIntent()`.
+
+**Caveats:** Agent must supply structured fields; `brief` is for audit/teaching, not autonomous NLU. Creates a new objective each call.
+
 ### `aureon_update_objective`
 
 **Purpose:** Partial update of mutable fields (name, weight, tolerance, priority, optional risk/reinvest fields).
@@ -389,13 +559,44 @@ Successful calls return structured JSON (formatted for agents). Failures return
 
 ### `aureon_restore_objective`
 
-**Purpose:** Run vault-backed restorative execution for an objective outside policy (primary agent restore path).
+**Purpose:** Run restorative execution for an objective outside policy. Not always vault-backed.
 
 **Typical args:** `objectiveId` (required).
 
-**When to use:** After a clear breach and a reviewed restore plan; Automatic objectives with a funded vault.
+**When to use:** After a clear breach and a reviewed restore plan.
+
+**Caveats:** Automatic + configured vault that cannot execute returns 409 — it does not stage a fake restore. Manual may stage. Empty vault blocks Automatic on-chain restore. Confirm with `aureon_list_timeline` / `aureon_list_executions`. Read `settlement`, `verifiedOnChain`, `explorerUrl`, and `registryRef` on every receipt.
+
+### How to read a receipt (agents)
+
+1. Call `aureon_list_executions` or use the receipt from restore/run.
+2. Check **`settlement`**: `vault` vs `staged` — never claim on-chain for `staged`.
+3. If **`explorerUrl`** is present, the vault tx can be verified on the explorer.
+4. If **`registryRef`** is present, the objective was registered on ObjectiveRegistry.
+5. Match **`aureon_list_timeline`** events via `payload.executionId === receipt.id`.
+6. For vault receipts, check **`verifiedOnChain`**. When true, cite **`settlementRecord`** or call **`aureon_get_execution_settlement`**. Never invent chain proof when `verifiedOnChain` is false.
+
+### `aureon_get_execution_settlement`
 
-**Caveats:** Empty vault or Manual-only product constraints can block or stage settlement. Confirm with `aureon_list_timeline` / `aureon_list_executions`.
+**Purpose:** Returns the durable on-chain settlement record for a vault execution when the API listener observed a `Rebalanced` event.
+
+**When to use:** After a vault restore when you need independent chain proof (tx hash, block, token pair, amounts).
+
+**Caveats:** Staged executions return `verifiedOnChain: false` with no settlement. Vault without listener confirmation is **not** chain-verified — say “vault submitted, not yet observed on-chain.”
+
+### `aureon_list_settlements`
+
+**Purpose:** Lists settlement records for the wallet (optional `objectiveId` filter). May include orphans — observed vault events not yet bound to an execution.
+
+**When to use:** Audit trail review; cross-check multiple restores. Read `status` and `executionId` before claiming proof.
+
+### `aureon_validate_receipt`
+
+**Purpose:** Validates an execution receipt locally (no API call). Returns `{ valid, issues }`.
+
+**When to use:** After `aureon_restore_objective` or `aureon_list_executions` — confirm the receipt is honest before reporting to the operator.
+
+**Caveats:** Validation is schema + policy only; it does not re-fetch chain state. If `valid: false`, quote `issues` and do not claim on-chain settlement.
 
 ---
 
@@ -511,6 +712,16 @@ Successful calls return structured JSON (formatted for agents). Failures return
 
 **Caveats:** Toggled-off keys fail subsequent control-plane calls until re-enabled.
 
+### `aureon_get_audit_trail`
+
+**Purpose:** Export one objective’s financial audit trail — registry, receipts, settlements, timeline — in a single object.
+
+**Typical args:** `objectiveId` (required).
+
+**When to use:** “Did this restore actually happen?” / follow intent → receipt → settlement without stitching four tools.
+
+**Caveats:** Missing proof is labeled as a gap. Staged receipts are never on-chain. Do not invent explorer links or `verifiedOnChain`. Testnet only.
+
 ---
 
 ## Prompt → tool mapping
@@ -525,6 +736,7 @@ Successful calls return structured JSON (formatted for agents). Failures return
 | “Why is health red?” | `aureon_get_health`, `aureon_list_timeline` |
 | “Show the restore plan” | `aureon_get_restore_plan` |
 | “Execute restore” | `aureon_restore_objective` |
+| “Export the audit trail” | `aureon_get_audit_trail` |
 | “Simulate −10% TSLA” | `aureon_apply_market_event` |
 | “Prepare 0.1 ETH deposit” | `aureon_prepare_vault_deposit` then host signs |
 | “Rotate my agent key” | `aureon_create_api_key` (+ secure store), optional `aureon_revoke_api_key` |
@@ -550,4 +762,4 @@ Successful calls return structured JSON (formatted for agents). Failures return
 - Prepare tools are safe to call with an API key; broadcasting is a separate host step.
 - When summarizing restores, always include settlement type when the receipt provides it.
 
-This reference is the canonical MCP tool surface for live agents: **34 tools**, live API, issued key (optional Bearer), and private key only outside MCP for broadcast.
+This reference is the canonical MCP tool surface for live agents: **54 tools**, live API, issued key (optional Bearer), and private key only outside MCP for broadcast.

package/examples/claude-desktop.json

@@ -4,7 +4,6 @@
       "command": "npx",
       "args": ["-y", "@buildaureon/mcp"],
       "env": {
-        "AUREON_API_URL": "https://api.aureonlabs.network",
         "AUREON_API_KEY": "<issued-developer-api-key>"
       }
     }

package/examples/cursor.mcp.json

@@ -4,7 +4,6 @@
       "command": "npx",
       "args": ["-y", "@buildaureon/mcp"],
       "env": {
-        "AUREON_API_URL": "https://api.aureonlabs.network",
         "AUREON_API_KEY": "<issued-developer-api-key>"
       }
     }