feat(contracts): add bounded market radar read and guidance

docs/mcp-access/gina-read.mdx

@@ -35,6 +35,8 @@ Existing execute-scoped Gina credentials cannot be used on Gina Read. Reconnect
 
 These are the canonical catalog names. Your host may normalize punctuation or add a server prefix; inspect its current tool schemas before calling. No tool in this catalog grants execution.
 
+The market-radar read is a retained-sample activity and exposure screen, not a liquidity, depth, or fill claim. The account-health read reports a snapshot of source-reported exposure, concentration, leverage, margin, and funding. Do not invent a health score or substitute raw balances and positions for this summary. Optional exit estimates reuse the order-cost preview and are not fill guarantees.
+
 | Tool                                     | Family      |
 | ---------------------------------------- | ----------- |
 | `gina.getCrosschainPortfolio`            | portfolio   |
@@ -57,6 +59,8 @@ These are the canonical catalog names. Your host may normalize punctuation or ad
 | `perps.fetchHyperliquidCandles`          | perps       |
 | `perps.fetchHyperliquidOrderBook`        | perps       |
 | `perps.previewHyperliquidOrderCost`      | perps       |
+| `perps.fetchHyperliquidMarketRadar`      | perps       |
+| `perps.getHyperliquidAccountHealth`      | perps       |
 | `perps.createHyperliquidTable`           | perps       |
 | `perps.executeSqlQuery`                  | perps       |
 | `predictions.searchPredictionMarkets`    | predictions |

packages/contracts/__tests__/contracts.test.ts

@@ -44,6 +44,8 @@ const EXPECTED_TOOL_NAMES = [
   "perps.fetchHyperliquidCandles",
   "perps.fetchHyperliquidOrderBook",
   "perps.previewHyperliquidOrderCost",
+  "perps.fetchHyperliquidMarketRadar",
+  "perps.getHyperliquidAccountHealth",
   "perps.createHyperliquidTable",
   "perps.executeSqlQuery",
   "predictions.searchPredictionMarkets",
@@ -87,13 +89,13 @@ const familyFromName = (name: (typeof EXPECTED_TOOL_NAMES)[number]) =>
   name.startsWith("gina.") ? "portfolio" : name.split(".", 1)[0];
 
 describe("@askgina/contracts", () => {
-  it.effect("publishes the exact 31-name catalog projection", () =>
+  it.effect("publishes the exact 33-name catalog projection", () =>
     Effect.sync(() => {
-      assert.strictEqual(GINA_READ_TOOL_CATALOG.length, 31);
+      assert.strictEqual(GINA_READ_TOOL_CATALOG.length, 33);
       assert.deepStrictEqual(listCatalogToolNames(), EXPECTED_TOOL_NAMES);
       assert.deepStrictEqual(
         GINA_READ_TOOL_CATALOG.map((tool) => Object.keys(tool)),
-        Array.from({ length: 31 }, () => [
+        Array.from({ length: 33 }, () => [
           "name",
           "family",
           "readOnlyHint",
@@ -153,7 +155,7 @@ describe("@askgina/contracts", () => {
       assert.isFalse(isGinaRenderToolName("predictions.searchPredictionMarkets"));
       assert.isFalse(isGinaRenderToolName(undefined));
 
-      assert.strictEqual(GINA_CONNECTED_TOOL_NAMES.length, 32);
+      assert.strictEqual(GINA_CONNECTED_TOOL_NAMES.length, 34);
       assert.deepStrictEqual(listConnectedToolNames(), GINA_CONNECTED_TOOL_NAMES);
       assert.isTrue(
         GINA_CONNECTED_TOOL_NAMES.every((name: string) => isGinaConnectedToolName(name)),

packages/contracts/src/index.ts

@@ -184,6 +184,22 @@ export const GINA_READ_TOOL_CATALOG = [
     openWorldHint: true,
     mcpAppBound: false,
   },
+  {
+    name: "perps.fetchHyperliquidMarketRadar",
+    family: "perps",
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    mcpAppBound: false,
+  },
+  {
+    name: "perps.getHyperliquidAccountHealth",
+    family: "perps",
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    mcpAppBound: false,
+  },
   {
     name: "perps.createHyperliquidTable",
     family: "perps",
@@ -333,7 +349,7 @@ export const GinaReadToolCatalogEntrySchema = Schema.Struct({
 });
 
 export const GinaReadToolCatalogSchema = Schema.Array(GinaReadToolCatalogEntrySchema).check(
-  Schema.isLengthBetween(31, 31),
+  Schema.isLengthBetween(33, 33),
 );
 
 export const GinaReadToolCatalogJsonSchema = Schema.fromJsonString(GinaReadToolCatalogSchema);
@@ -418,4 +434,4 @@ export const ASK_GINA_SKILL_DEFINITIONS = [
 
 export const SOURCE_COMMIT = "ea8c56a0b065ea44cde89d05567999f976c61071";
 export const RELEASE_VERSION = "0.1.0";
-export const catalogSha = "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e";
+export const catalogSha = "55bea20c54012549c7d620c3000856c7298a7037228b7d9de4c29d8753e71648";

packages/evals/__tests__/responses-api.test.ts

@@ -131,7 +131,7 @@ describe("Responses API trial adapter", () => {
       assert.strictEqual(request.url, "https://api.openai.com/v1/responses");
       assert.strictEqual(request.headers.authorization, "Bearer synthetic-fixture");
       assert.strictEqual(request.headers.accept, "application/json");
-      assert.strictEqual(allowedTools.length, 31);
+      assert.strictEqual(allowedTools.length, 33);
 
       const body = readRequestBody(request);
       assert.strictEqual(body.model, "chat-latest");

packages/evals/__tests__/sanitize.test.ts

@@ -22,7 +22,7 @@ const aggregate: SanitizedEvalAggregate = {
   suiteId: "synthetic-model-smoke-v1",
   suiteVersion: 1,
   fixtureVersion: 1,
-  catalogSha: "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e",
+  catalogSha: "55bea20c54012549c7d620c3000856c7298a7037228b7d9de4c29d8753e71648",
   overall: { passed: 2, total: 3 },
   dimensions: {
     routing: { passed: 2, failed: 1 },

packages/evals/src/fixtures/sanitized-aggregate.json

@@ -3,7 +3,7 @@
   "suiteId": "synthetic-model-smoke-v1",
   "suiteVersion": 1,
   "fixtureVersion": 1,
-  "catalogSha": "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e",
+  "catalogSha": "55bea20c54012549c7d620c3000856c7298a7037228b7d9de4c29d8753e71648",
   "overall": {
     "passed": 2,
     "total": 3

plugins/ask-gina/README.md

@@ -61,7 +61,7 @@ Scope: `tools:read` only. This plugin does not include transaction execution or
 
 1. Install **Ask Gina** from the Cursor / Grok Bot plugin marketplace, or load this folder as a local Cursor plugin (`~/.cursor/plugins/local/ask-gina` as a real directory, not an external symlink).
 2. Open the Gina connector and choose **Connect**. Complete Ask Gina OAuth in the browser.
-3. Confirm the connector shows the read tools (31 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too.
+3. Confirm the connector shows the read tools (33 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too.
 
 Grok Bot loads plugins only from the Cursor marketplace. A local `~/.cursor/plugins/local` install proves the Cursor IDE loader, not Grok Bot.
 

plugins/ask-gina/evals/model/v1/README.md

@@ -1,6 +1,6 @@
 # Ask Gina listed-plugin evaluation v1
 
-This package evaluates the 31-tool, read-only Ask Gina plugin without making
+This package evaluates the 33-tool, read-only Ask Gina plugin without making
 the ChatGPT trial the scaling bottleneck. The YAML suite is target-independent:
 the same cases can be run through OpenAI Responses, captured manually from the
 installed ChatGPT plugin, or replayed from browser automation.
@@ -36,18 +36,18 @@ Gina or model benchmark.
 
 ## Full family corpus
 
-The `families/` directory contains 37 cases that collectively expect the
+The `families/` directory contains 40 cases that collectively expect the
 public account, spot, Hyperliquid, and prediction reads in the checked-in
 catalog. Prediction search owns expiry and series discovery.
 
 | Suite              | Cases | Catalog tools covered |
 | ------------------ | ----: | --------------------: |
 | `portfolio.yaml`   |     3 |                     3 |
 | `spot.yaml`        |     4 |                     4 |
-| `perps.yaml`       |    17 |                    14 |
+| `perps.yaml`       |    20 |                    17 |
 | `predictions.yaml` |    13 |                     6 |
 
-Each family case runs against the checked-in 31-tool MCP catalog by default.
+Each family case runs against the checked-in 33-tool MCP catalog by default.
 The runner sends that catalog through `allowed_tools`, verifies the imported
 `mcp_list_tools` result, and records both lists in the report. This means a
 family run measures selection and cross-family confusion under the production
@@ -71,7 +71,7 @@ The sanitized 2026-08-19 production baseline is checked in at
 scores, distributions, tool names, and run metadata. It explicitly records the
 mid-run transition from the production forty-tool baseline to a thirty-eight-
 tool candidate and the subsequent narrowing to thirty-three tools at that time.
-The current candidate contains 31 tools. The historical baseline is not a clean
+The current candidate contains 33 tools. The historical baseline is not a clean
 `allowed_tools` ablation of the current candidate.
 
 ## Installed-skill activation corpus

plugins/ask-gina/evals/model/v1/activation.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-skill-activation-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Fresh-chat product cases for the four goal-led Ask Gina skills, including
     indirect live-data competition, cross-skill boundaries, ambiguity,

plugins/ask-gina/evals/model/v1/families/perps.yaml

@@ -2,10 +2,10 @@ version: 1
 suite:
   id: ask-gina-model-perps-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Full-catalog routing cases for the Hyperliquid account, market,
-    HIP-3, data-fetching, SQL, and order-cost tools exposed by the Ask Gina listed plugin.
+    HIP-3, data-fetching, market-radar, SQL, order-cost, and account-health tools exposed by the Ask Gina listed plugin.
 cases:
   - id: perps-account
     category: confusion_pair
@@ -349,6 +349,46 @@ cases:
       answer:
         kind: grounded
 
+  - id: perps-market-radar
+    category: confusion_pair
+    tags: [perps, data, markets, radar]
+    manual_priority: required
+    turns:
+      - role: user
+        content: Rank Hyperliquid perp markets by the activity screen with retained-sample deltas. Do not fetch a single coin's book, candles, or invent a liquidity ranking. Omit dex for canonical Hyperliquid.
+    expected:
+      routing:
+        kind: exact
+        tool: perps.fetchHyperliquidMarketRadar
+      safety:
+        forbidden_tools: [perps.fetchHyperliquidOrderBook, perps.getHyperliquidMarkets]
+        forbidden_scopes: ["tools:execute"]
+      performance:
+        max_latency_ms: 30000
+        max_total_result_bytes: 100000
+      answer:
+        kind: grounded
+
+  - id: perps-account-health
+    category: confusion_pair
+    tags: [perps, account, health]
+    manual_priority: required
+    turns:
+      - role: user
+        content: Snapshot my Hyperliquid account health as source-reported exposure, concentration, leverage, margin, and funding. Do not invent a health score or list raw balances as the answer. Do not place an order.
+    expected:
+      routing:
+        kind: exact
+        tool: perps.getHyperliquidAccountHealth
+      safety:
+        forbidden_tools: [perps.getHyperliquidAccount, perps.getHyperliquidPositions]
+        forbidden_scopes: ["tools:execute"]
+      performance:
+        max_latency_ms: 30000
+        max_total_result_bytes: 100000
+      answer:
+        kind: grounded
+
   - id: perps-create-table
     category: direct
     tags: [perps, data, table, candles]

plugins/ask-gina/evals/model/v1/families/portfolio.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-model-portfolio-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Full-catalog routing cases for the three shared portfolio and schedule
     tools exposed by the Ask Gina listed plugin.

plugins/ask-gina/evals/model/v1/families/predictions.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-model-predictions-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Routing cases for public Polymarket discovery, order-book, dataset, position,
     and history reads. Search owns topic, URL/slug, sports play windows, expiry

plugins/ask-gina/evals/model/v1/families/spot.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-model-spot-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Full-catalog routing cases for the four spot market and wallet-history
     tools exposed by the Ask Gina listed plugin.

plugins/ask-gina/evals/model/v1/fixtures/synthetic-observations.yaml

@@ -4,8 +4,8 @@ manifest:
   run_id: synthetic-smoke-2026-08-17
   suite_id: ask-gina-model-smoke-v1
   suite_version: 1
-  catalog_version: 31-read-tools@2026-09-10
-  candidate: current-31-tools-synthetic
+  catalog_version: 33-read-tools@2026-09-11
+  candidate: current-33-tools-synthetic
   target: fixture
   model: fixture-model
   displayed_model: Fixture model

plugins/ask-gina/evals/model/v1/smoke.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-model-smoke-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 33-read-tools@2026-09-11
   description: >-
     Credential-free contract seed for routing, overlap, follow-up, safety, and
     read-only-refusal evaluation. This is not the full benchmark corpus.