@buildaureon/sdk 0.1.2 → 0.1.8

package/docs/architecture.md

@@ -127,7 +127,7 @@ sequenceDiagram
 
 - **Capital Book** — gateway portfolio used for weight math (`syncPortfolio`).
 - **Vault balances** — on-chain capital Automatic restores trade against.
-- Empty vault ⇒ Automatic restores cannot meaningfully settle on-chain even if policy exists.
+- Empty vault ⇒ Automatic restore returns 409. It does not stage a fake success or edit the capital book.
 
 ---
 
@@ -184,16 +184,18 @@ flowchart TD
 
 ---
 
-## 8. Network (early access testnet)
+## 8. Network
 
-| Item | Value |
-| --- | --- |
-| Chain | Robinhood Chain testnet |
-| Chain ID | `46630` |
-| API | `https://api.aureonlabs.network` |
-| Explorer | Configure via product / env (`AUREON_EXPLORER_BASE`) |
+Default omitted SDK/MCP options are the **isolated mainnet stack** (4663 + local 8788). Public `api.aureonlabs.network` is still **testnet 46630**.
+
+| Item | Mainnet (default) | Testnet (opt-in) |
+| --- | --- | --- |
+| Chain | Robinhood Chain mainnet | Robinhood Chain testnet |
+| Chain ID | `4663` | `46630` |
+| API | `http://127.0.0.1:8788` | `https://api.aureonlabs.network` |
+| Explorer | `https://robinhoodchain.blockscout.com` | `https://explorer.testnet.chain.robinhood.com` |
 
-Confirm live addresses and allowlisted symbols from the operator utility and API responses — do not hardcode stale addresses in agents.
+Production does **not** already sync 4663. Confirm live addresses from the API you actually call.
 
 ---
 

package/docs/auth.md

@@ -40,8 +40,9 @@ Control-plane calls (sync, objectives, health, restore, vault reads, prepare-*)
 import { createAureonClient } from "@buildaureon/sdk";
 
 const aureon = createAureonClient({
-  baseUrl: "https://api.aureonlabs.network",
   apiKey: process.env.AUREON_API_KEY!, // issued key from Developers
+  // omit network → mainnet 4663 / http://127.0.0.1:8788
+  // network: "testnet" → public host (still 46630)
 });
 
 const me = await aureon.me();
@@ -88,7 +89,7 @@ import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk
 
 const session = createSessionTokenProvider(null);
 const aureon = createAureonClient({
-  baseUrl: "https://api.aureonlabs.network",
+  network: "testnet", // public host, still chain 46630
   apiKey: process.env.AUREON_API_KEY,
   getAccessToken: session.getAccessToken,
 });
@@ -143,7 +144,8 @@ session.clear();
 | Variable | Required | Description |
 | --- | --- | --- |
 | `AUREON_API_KEY` | Recommended | Issued developer key |
-| `AUREON_API_URL` | No | Defaults to `https://api.aureonlabs.network` |
+| `AUREON_NETWORK` | No | Omit for mainnet 4663 / `http://127.0.0.1:8788`. Set `testnet` for the public host (still 46630). |
+| `AUREON_API_URL` | No | Optional override. Must match `AUREON_NETWORK` if both are set. |
 | `AUREON_TOKEN` | No | Optional Bearer for CLI / scripts |
 
 CLI example:

package/docs/client-api.md

@@ -32,7 +32,8 @@ import {
 } from "@buildaureon/sdk";
 
 const aureon = createAureonClient({
-  // baseUrl defaults to https://api.aureonlabs.network
+  // network defaults to mainnet (4663 / http://127.0.0.1:8788)
+  // network: "testnet" → public host (still chain 46630)
   apiKey: process.env.AUREON_API_KEY,
   getAccessToken: () => sessionToken,
   timeoutMs: 30_000,
@@ -44,7 +45,8 @@ const aureon = createAureonClient({
 
 | Option | Required | Default | Description |
 |--------|----------|---------|-------------|
-| `baseUrl` | no | `https://api.aureonlabs.network` | Absolute `http://` or `https://` URL. |
+| `network` | no | `mainnet` | `mainnet` = 4663 / `http://127.0.0.1:8788`. `testnet` = public host (still 46630). |
+| `baseUrl` | no | mainnet local API | Absolute `http://` or `https://` URL. Wins when set; mismatch with `network` throws. |
 | `apiKey` | SDK / CLI | N/A | Sent as `X-Aureon-Api-Key`. Issued developer keys also identify the bound wallet (no Bearer required). Env bootstrap keys are product-gate only. Utility uses wallet Bearer only. |
 | `getAccessToken` | no | N/A | Optional Bearer getter. Wins over API-key identity when present. |
 | `authToken` | no | N/A | Static Bearer string when `getAccessToken` is omitted. |
@@ -59,8 +61,12 @@ const aureon = createAureonClient({
 
 | Rule | Behavior |
 |------|----------|
-| Omitted `baseUrl` | Uses production default |
+| Omitted `network` and `baseUrl` | Local mainnet `http://127.0.0.1:8788`, chain 4663 |
+| `network: "testnet"` | Public `https://api.aureonlabs.network` (still 46630) |
+| Explicit `baseUrl` | Wins; infer network from known hosts |
+| `network` + disagreeing `baseUrl` | Throws |
 | Invalid `baseUrl` scheme | Throws via `assertBaseUrl` |
+| `aureon.network` / `aureon.chainId` | Resolved bundle |
 | Both `authToken` and `getAccessToken` | Transport uses `getAccessToken` only |
 | `aureon.baseUrl` getter | Returns resolved base (no trailing slash) |
 
@@ -365,6 +371,172 @@ async getOverview(): Promise<DashboardOverview>
 | HTTP | `GET /overview` |
 | Contains | Health counts, global score, 24h portfolio change (daily snapshots), evaluation schedule, recent executions + events |
 
+### `getAllocationVsTarget()`
+
+```ts
+async getAllocationVsTarget(): Promise<{
+  rows: AllocationComparisonRow[];
+  paradox: PlanParadoxResult;
+  overview: DashboardOverview;
+}>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — parallel `GET /overview`, `GET /objectives`, `GET /health` |
+| Returns | Per-objective current vs target weights plus a green-book/off-plan paradox flag |
+| Use | demo — objective vs actual portfolio without stitching JSON yourself |
+
+Helpers `buildAllocationComparison()` and `detectPlanParadox()` are exported for custom integrators. See `pnpm example:green-vs-plan`.
+
+### `applyFinancialIntent(intent)`
+
+```ts
+async applyFinancialIntent(intent: FinancialIntent): Promise<ObjectivePortfolioFlow>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — `POST /objectives` + watchdog refresh + `GET /health` + `GET /portfolio` |
+| Returns | Intent summary, created objective, health, portfolio snapshot, teaching message |
+| Use | AI → objective → portfolio in one call |
+
+### `getObjectivePortfolioFlow(objectiveId?)`
+
+```ts
+async getObjectivePortfolioFlow(objectiveId?: string): Promise<ObjectivePortfolioFlow[]>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — objectives + health + portfolio |
+| Returns | Flow snapshots for active objectives (or one id) |
+
+Helpers `parseFinancialIntent()`, `resolveObjectiveFromIntent()`, and `buildObjectivePortfolioFlow()` are exported. See `pnpm example:ai-to-objective-to-portfolio`.
+
+### `runDriftRestoreDemo()`
+
+```ts
+async runDriftRestoreDemo(): Promise<DriftRestoreFlow>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — portfolio seed, objective create, market event (`autoRestore: false`), restore plan, manual restore |
+| Returns | Three-beat `DriftRestoreFlow` — aligned → drift → restored |
+| Use | drift → detection → restore teaching demo |
+
+### `getDriftRestoreFlow(objectiveId?)`
+
+```ts
+async getDriftRestoreFlow(objectiveId?: string): Promise<DriftRestoreFlow[]>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — objectives + health + allocation + executions (+ restore plan when off-plan) |
+| Returns | Inferred drift-restore flows for active objectives |
+
+Helpers `buildDriftRestoreFlow()`, `buildDriftRestoreFlowFromSnapshot()`, and `inferDriftPhase()` are exported. See `pnpm example:drift-detect-restore`.
+
+### `runReceiptVerificationDemo()`
+
+```ts
+async runReceiptVerificationDemo(): Promise<ReceiptVerificationFlow>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — `runDriftRestoreDemo()` + local validation + settlement lookup + timeline |
+| Returns | Three-beat `ReceiptVerificationFlow` — claim → validate → verify |
+| Use | receipt → verification teaching demo |
+
+### `getReceiptVerificationFlow(executionId?)`
+
+```ts
+async getReceiptVerificationFlow(executionId?: string): Promise<ReceiptVerificationFlow[]>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — executions + validation + settlement + timeline |
+| Returns | Verification flows for recent or specified execution(s) |
+
+Helpers `buildReceiptVerificationFlow()`, `inferProofTier()`, and `validateExecutionReceipt()` are exported. See `pnpm example:receipt-verification`.
+
+### `runPortfolioWatchDemo(input?)`
+
+```ts
+async runPortfolioWatchDemo(input?: {
+  brief?: string;
+  host?: "cursor" | "claude" | "mcp";
+}): Promise<PortfolioWatchFlow>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — `applyFinancialIntent` + market event (`autoRestore: true`) + timeline |
+| Returns | Portfolio watch flow — register → while away → return briefing |
+| Use | agent-in-host demo |
+
+### `getPortfolioWatchFlow(input?)`
+
+```ts
+async getPortfolioWatchFlow(input?: {
+  objectiveId?: string;
+  brief?: string;
+  host?: "cursor" | "claude" | "mcp";
+}): Promise<PortfolioWatchFlow[]>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — Automatic objectives + health + allocation + timeline |
+| Returns | Read-only briefing for active Automatic objectives |
+
+Helpers `buildPortfolioWatchFlow()`, `DEFAULT_PORTFOLIO_WATCH_BRIEF`, and `inferPortfolioWatchPhase()` are exported. See `pnpm example:portfolio-watch`.
+
+### `runFullAureonLoopDemo(input?)`
+
+```ts
+async runFullAureonLoopDemo(input?: {
+  brief?: string;
+}): Promise<FullAureonLoopFlow>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — intent + allocation paradox + restore (`autoRestore: false`) + receipt verification |
+| Returns | Full loop — intent → plan check → restore → verify |
+| Use | Content Arc — full AUREON loop positioning demo |
+
+### `getFullAureonLoopFlow(input?)`
+
+```ts
+async getFullAureonLoopFlow(input?: {
+  objectiveId?: string;
+  brief?: string;
+}): Promise<FullAureonLoopFlow[]>
+```
+
+| | |
+|--|--|
+| Auth | Required |
+| HTTP | Composite — objectives + allocation + latest receipt + validation |
+| Returns | Read-only full-loop flows for active objectives with receipts |
+
+Helpers `buildFullAureonLoopFlow()`, `DEFAULT_FULL_LOOP_BRIEF`, and `inferFullAureonLoopPhase()` are exported. See `pnpm example:full-aureon-loop`.
+
 ---
 
 ## 6. Vault
@@ -478,7 +650,7 @@ async applyMarketEvent(input: ApplyMarketEventInput): Promise<{
 |--|--|
 | Auth | Required |
 | HTTP | `POST /market/events` |
-| Normalization | Uppercases symbol; `autoRestore` defaults **true** |
+| Normalization | Uppercases symbol; `autoRestore` defaults **false** (must opt in to restore) |
 | Validation | Symbol required; finite `priceChangeRatio`; rejects extreme ≤ -0.95 |
 
 ### `getRestorePlan(objectiveId)`
@@ -578,6 +750,17 @@ session.clear();
 | `syncPortfolio` | POST | `/portfolio/sync` | **yes** |
 | `refreshWatchdog` | POST | `/watchdog/refresh` | **yes** |
 | `getOverview` | GET | `/overview` | **yes** |
+| `getAllocationVsTarget` | composite | overview + objectives + health | **yes** |
+| `applyFinancialIntent` | composite | create objective + health + portfolio | **yes** |
+| `getObjectivePortfolioFlow` | composite | objectives + health + portfolio | **yes** |
+| `runDriftRestoreDemo` | composite | seed + drift + manual restore | **yes** |
+| `getDriftRestoreFlow` | composite | objectives + health + allocation + executions | **yes** |
+| `runReceiptVerificationDemo` | composite | drift-restore + validate + settlement | **yes** |
+| `getReceiptVerificationFlow` | composite | executions + validation + settlement | **yes** |
+| `runPortfolioWatchDemo` | composite | intent + auto-restore market event + briefing | **yes** |
+| `getPortfolioWatchFlow` | composite | Automatic objectives + health + timeline | **yes** |
+| `runFullAureonLoopDemo` | composite | intent + plan paradox + restore + verify | **yes** |
+| `getFullAureonLoopFlow` | composite | objectives + allocation + receipt validation | **yes** |
 | `listMarketPresets` | GET | `/market/presets` | **yes** |
 | `applyMarketEvent` | POST | `/market/events` | **yes** |
 | `getRestorePlan` | GET | `/objectives/:id/restore-plan` | **yes** |

package/docs/data-contracts.md

@@ -402,14 +402,84 @@ export interface ExecutionReceipt {
   result: string;
   createdAt: string;
   confirmedAt: string | null;
-  /** 
-   * vault represents keeper rebalances on the Robinhood Chain.
-   * staged represents simulated/book-only ledger updates.
-   */
-  settlement?: "staged" | "vault";
+  /** Required. vault = on-chain keeper path; staged = capital-book update only. */
+  settlement: "staged" | "vault";
+  /** Block explorer link when vault tx is confirmed (`0x…`); null for staged. */
+  explorerUrl?: string | null;
+  /** Present when the objective is registered on ObjectiveRegistry. */
+  registryRef?: RegistryRef;
+  /** True when a settlement record exists for this execution (vault only). */
+  verifiedOnChain?: boolean;
+  /** Populated when `verifiedOnChain` is true. */
+  settlementRecord?: SettlementRecord;
 }
 ```
 
+### SettlementRecord (Day 8)
+
+Independent on-chain proof from AureonVault `Rebalanced` events:
+
+```ts
+export interface SettlementRecord {
+  id: string;
+  executionId: string | null;
+  objectiveId: string | null;
+  walletAddress: string;
+  settlement: "vault";
+  transactionHash: string;
+  blockNumber: number;
+  logIndex: number;
+  vaultAddress: string;
+  tokenSell: string;
+  tokenBuy: string;
+  amountIn: string;
+  amountOut: string;
+  explorerUrl: string;
+  verifiedAt: string;
+  status: "confirmed" | "orphan";
+  registryRef?: RegistryRef;
+}
+```
+
+Client methods: `getExecutionSettlement`, `listSettlements`, `confirmExecutionSettlement`.
+
+---
+
+## 6.1 Receipt validation (Day 9)
+
+Validate receipts locally before trusting them in automation:
+
+```ts
+import {
+  validateExecutionReceipt,
+  assertValidExecutionReceipt,
+} from "@buildaureon/sdk";
+
+const result = validateExecutionReceipt(receipt);
+if (!result.valid) {
+  console.error(result.issues);
+}
+
+assertValidExecutionReceipt(receipt); // throws AureonValidationError
+```
+
+`ReceiptValidationResult`:
+
+```ts
+export type ReceiptValidationIssue = {
+  code: string;
+  message: string;
+  path?: string;
+};
+
+export type ReceiptValidationResult = {
+  valid: boolean;
+  issues: ReceiptValidationIssue[];
+};
+```
+
+Enforces required fields, `vault` vs `staged` honesty, explorer rules, and `verifiedOnChain` / `settlementRecord` consistency. See [receipt-validation.md](./receipt-validation.md).
+
 #### JSON Representation Example
 ```json
 {
@@ -422,7 +492,12 @@ export interface ExecutionReceipt {
   "result": "Exchanged stock tokens for 3750.0 USDG on Robinhood Chain",
   "createdAt": "2026-07-15T22:46:00.000Z",
   "confirmedAt": "2026-07-15T22:46:05.000Z",
-  "settlement": "vault"
+  "settlement": "vault",
+  "explorerUrl": "https://explorer.testnet.chain.robinhood.com/tx/0xe295c2763f0d4681a8b54dfd38a0f8bfd21051515fcd9185a494ff3c8a99478f",
+  "registryRef": {
+    "objectiveKey": "0xabc…",
+    "contractAddress": "0x76d8f088d2abba3c73ff93f92308f8b59b250ea5"
+  }
 }
 ```
 

package/docs/error-model.md

@@ -134,7 +134,7 @@ flowchart TD
 | --- | --- |
 | Invalid / paused key | Stop loop; operator rotates Developers key |
 | Bootstrap key alone | Switch to issued key |
-| Vault empty on restore | Prepare deposit → broadcast → sync → retry |
+| Vault empty on restore | Expected first use. Call `prepareVaultDeposit`, return unsigned steps, wait for the **user/host** to broadcast. Agents do not fund the vault. |
 | Locked field on update | Recreate objective |
 | Conflict mid-restore | Back off; read timeline / executions |
 | Staged settlement returned | Do not treat as on-chain success |
@@ -186,7 +186,7 @@ import {
 
 test("empty objective name fails validation", async () => {
   const client = createAureonClient({
-    baseUrl: "https://api.aureonlabs.network",
+    network: "testnet",
     apiKey: "test",
   });
 

package/docs/integration-guide.md

@@ -11,8 +11,11 @@ Integrate `@buildaureon/sdk` into server-side agents and automated rebalancing l
 ```mermaid
 flowchart TD
   Init[1_issued_API_key_client] --> Sync[2_sync_Capital_Book]
-  Sync --> Fund[3_fund_vault_if_empty]
-  Fund --> Obj[4_create_Auto_objective]
+  Sync --> Empty{vault empty?}
+  Empty -->|yes| FourOhNine[restore 409]
+  FourOhNine --> Prep[prepareVaultDeposit unsigned]
+  Prep --> User[user/host signs when they use it]
+  Empty -->|no| Obj[create Auto objective]
   Obj --> Loop[5_watchdog_heartbeat]
   Loop -->|breach| Plan[6_restore_plan]
   Plan --> Restore[7_restoreObjective]
@@ -22,10 +25,12 @@ flowchart TD
 ### Step 1 — Client
 
 ```ts
-import { createAureonClient } from "@buildaureon/sdk";
+import { createAureonClient, resolveAureonNetworkFromEnv } from "@buildaureon/sdk";
 
+const resolved = resolveAureonNetworkFromEnv();
 export const aureon = createAureonClient({
-  baseUrl: process.env.AUREON_API_URL || "https://api.aureonlabs.network",
+  network: resolved.network,
+  baseUrl: resolved.baseUrl,
   apiKey: process.env.AUREON_API_KEY!, // issued Developers key
   timeoutMs: 30_000,
   maxRetries: 2,
@@ -39,11 +44,17 @@ console.log("operating as", me.walletAddress);
 Optional Bearer (usually unnecessary with an issued key):
 
 ```ts
-import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
+import {
+  createAureonClient,
+  createSessionTokenProvider,
+  resolveAureonNetworkFromEnv,
+} from "@buildaureon/sdk";
 
+const resolved = resolveAureonNetworkFromEnv();
 const session = createSessionTokenProvider(process.env.AUREON_TOKEN ?? null);
 export const aureon = createAureonClient({
-  baseUrl: process.env.AUREON_API_URL || "https://api.aureonlabs.network",
+  network: resolved.network,
+  baseUrl: resolved.baseUrl,
   apiKey: process.env.AUREON_API_KEY ?? null,
   getAccessToken: session.getAccessToken,
 });
@@ -62,28 +73,19 @@ console.log({
 
 Prefer `syncPortfolio()` over hand-seeded books in production. Use `setPortfolio` only for controlled rehearsals.
 
-### Step 3 — Fund vault when needed
+### Step 3 — Empty vault is first use (do not fund for the user)
 
-Automatic restores require vault capital. Prepare returns **unsigned** steps — your host signs and broadcasts.
+Automatic restore on an empty vault must **409**. That is the same path as testnet. The SDK/MCP process does **not** broadcast a deposit. When the user actually uses the product, their host wallet signs `prepareVaultDeposit` steps.
 
 ```ts
 import type { VaultPrepareResult } from "@buildaureon/sdk";
 
-async function ensureVaultFunded(
-  symbol: string,
-  amount: string,
-  broadcast: (step: VaultPrepareResult["steps"][number]) => Promise<string>
-) {
-  const status = await aureon.getVaultStatus();
-  if (!status.empty && status.canRestore) return status;
-
-  const prep = await aureon.prepareVaultDeposit({ symbol, amount });
-  for (const step of prep.steps) {
-    const hash = await broadcast(step);
-    console.log(step.label, hash);
-  }
-
-  return aureon.getVaultStatus();
+const status = await aureon.getVaultStatus();
+if (status.empty) {
+  // restoreObjective must 409 here — do not treat that as a bug
+  const prep = await aureon.prepareVaultDeposit({ symbol: "USDG", amount: "0.05" });
+  // prep.steps are UNSIGNED. Return them. The user broadcasts when they fund.
+  return prep;
 }
 ```
 
@@ -163,7 +165,147 @@ Start with one Automatic `balanced_portfolio` objective and a funded vault befor
 
 ---
 
-## 3. Daemon runners
+## 2b. Green vs plan paradox demo (Update 2)
+
+Most dashboards celebrate green PnL. AUREON separates book performance from plan adherence:
+
+```ts
+// Baseline
+const before = await aureon.getAllocationVsTarget();
+console.log(before.rows); // current vs target per objective
+
+// Controlled shock — keep violation visible
+await aureon.applyMarketEvent({
+  symbol: "NVDA",
+  priceChangeRatio: 0.45,
+  autoRestore: false,
+});
+
+const after = await aureon.getAllocationVsTarget();
+console.log(after.paradox.message);
+// "Book is up (5.0%), but 1 objective is off-plan."
+```
+
+Run the full script: `pnpm example:green-vs-plan` (requires `AUREON_API_KEY`).
+
+---
+
+## 2c. AI → objective → portfolio (Update 3)
+
+Most AI agents can transact but forget what the user wanted. AUREON registers intent as a persistent objective, then reads the portfolio through that policy:
+
+```ts
+const flow = await aureon.applyFinancialIntent({
+  brief: "Keep about 20% of the portfolio in stable assets",
+  kind: "stable_allocation",
+  targetWeight: 0.2,
+  tolerance: 0.02,
+});
+
+console.log(flow.intent.policySummary);
+console.log(flow.objective.id);
+console.log(flow.health?.state);
+console.log(flow.message);
+```
+
+For demos, `parseFinancialIntent(brief)` converts a user sentence into structured fields (rule-based, not production NLU).
+
+Run the full script: `pnpm example:ai-to-objective-to-portfolio`.
+
+Then use `getAllocationVsTarget()` (Update 2) to compare objective vs actual over time.
+
+---
+
+## 2d. Drift → detection → restore (Update 4)
+
+Update 2 stops at the paradox — book up, plan off-target, no restore. Update 4 closes the loop:
+
+```ts
+const flow = await aureon.runDriftRestoreDemo();
+
+console.log(flow.rule.summary);
+console.log(flow.phases.aligned.health.state);
+console.log(flow.phases.drift.health.state);
+console.log(flow.phases.restored?.receipt?.settlement);
+console.log(flow.message);
+```
+
+For read-only monitoring without mutating the book, use `getDriftRestoreFlow()` — it joins objectives, health, allocation rows, restore plans (when off-plan), and the latest execution receipt.
+
+Run the full script: `pnpm example:drift-detect-restore`.
+
+---
+
+## 2e. Receipt → verification (Update 5)
+
+Update 4 returns a receipt after restore. Update 5 teaches that **"transaction successful" is a claim**, not proof:
+
+```ts
+const flow = await aureon.runReceiptVerificationDemo();
+
+console.log(flow.phases.claimed.result);
+console.log(flow.phases.validation.valid);
+console.log(flow.proofTier);
+console.log(flow.phases.settlement?.verifiedOnChain);
+console.log(flow.message);
+```
+
+Proof tiers: **claim_only** (validation failed) → **schema_valid** (honest receipt shape) → **chain_verified** (independent settlement record for vault).
+
+For read-only checks on existing executions, use `getReceiptVerificationFlow(executionId?)`.
+
+Run the full script: `pnpm example:receipt-verification`.
+
+Forward link: Update 6 — Claude/Cursor + AUREON agent-in-host demo.
+
+---
+
+## 2f. Portfolio watch while away (Update 6)
+
+Consumer hook: *“Imagine telling your AI: watch my portfolio while I'm away.”*
+
+```ts
+const flow = await aureon.runPortfolioWatchDemo({ host: "cursor" });
+
+console.log(flow.userBrief);
+console.log(flow.phases.register.automationMode);
+console.log(flow.phases.whileAway?.autoRestored);
+for (const line of flow.phases.briefing.summaryLines) {
+  console.log(line);
+}
+```
+
+Update 4 uses `autoRestore: false` (manual restore demo). Update 6 uses **`autoRestore: true`** — Automatic mode acts while the operator is away.
+
+For read-only briefing on existing Automatic objectives: `getPortfolioWatchFlow()`.
+
+Run the full script: `pnpm example:portfolio-watch`.
+
+Forward link: Update 7 — full AUREON loop.
+
+---
+
+## 2g. Full AUREON loop (Update 7)
+
+Positioning hook: *"We're not building another portfolio tracker."*
+
+```ts
+const flow = await aureon.runFullAureonLoopDemo();
+
+console.log(flow.phases.intent.policySummary);
+console.log(flow.phases.planCheck.afterShock.paradox.detected);
+console.log(flow.phases.driftRestore.settlement);
+console.log(flow.phases.verification.proofTier);
+console.log(flow.message);
+```
+
+One composite closes the content arc: **intent → plan check → restore → receipt verification**. A tracker stops at marks; AUREON registers policy, exposes green-vs-plan failure (`autoRestore: false`), restores, then validates the receipt.
+
+For read-only joins on existing objectives with receipts: `getFullAureonLoopFlow()`.
+
+Run the full script: `pnpm example:full-aureon-loop`.
+
+---
 
 ### PM2
 
@@ -177,7 +319,8 @@ module.exports = {
       autorestart: true,
       env: {
         NODE_ENV: "production",
-        AUREON_API_URL: "https://api.aureonlabs.network",
+        // omit AUREON_API_URL for local mainnet 8788 / 4663
+        // AUREON_NETWORK: "testnet"  // public host, still 46630
         // AUREON_API_KEY from secret store / PM2 ecosystem secrets
       },
     },
@@ -240,7 +383,7 @@ Never log API keys, Bearer tokens, or private keys.
 | --- | --- | --- |
 | 401 invalid key | Wrong / paused / revoked key | Rotate in Developers |
 | 401 need issued key | Env bootstrap key alone | Use an issued Developers key |
-| Vault empty / cannot restore | No vault capital | `prepareVaultDeposit` → broadcast → sync |
+| Vault empty / cannot restore | First use — no user deposit yet | `prepareVaultDeposit` (unsigned). User/host broadcasts when they fund. Agents do not. |
 | Update rejects symbol/mode | Locked at create | Recreate objective |
 | Restore receipt `staged` | Ledger-local path | Do not claim on-chain |
 | Health still violated after restore | Prices / sizing / liquidity | Re-read plan, vault balances, timeline |