chain-insights 0.2.30 → 0.2.32

package/README.md

@@ -194,6 +194,10 @@ result envelope. Use explicit `LIMIT` and pagination in your query when you
 want bounded result sets. Endpoint access and authentication are configured
 separately; see [MCP proxy](docs/mcp-proxy.md).
 
+Agent installs include `chain-insights-cypher` for generic layer-aware
+GQL/Cypher work and `chain-insights-bittensor-cypher` for Bittensor-specific
+schema notes and examples.
+
 ## AML Tools
 
 The high-level AML tools are Chain Insights workflows built around graph access

package/docs/graph-tools.md

@@ -37,6 +37,16 @@ assumed to exist on the GraphRAG MCP endpoint.
 - `per_query_timeout_seconds` is optional and capped at `10` by default.
 - Returned rows live in `structuredContent.facts`.
 
+Agent installers ship two graph-query skills:
+
+- `chain-insights-cypher`: generic layer selection, schema capture, and
+  portable read-only GQL/Cypher examples. Its
+  `references/memgraph-examples.md` file includes staging-tested Memgraph-style
+  recipes, archive/facts reads, and fixed-hop traversal fallbacks for native
+  Memgraph deep traversal syntax that the hosted GraphRAG MCP path may reject.
+- `chain-insights-bittensor-cypher`: Bittensor-specific schema notes for SS58
+  and EVM-pallet addresses under `network=bittensor`.
+
 Check public-free usage:
 
 ```bash
@@ -313,12 +323,19 @@ Large JSON belongs under workspace report directories, not inline in evidence.
 Fresh workspaces include a runtime schema skill and schema capture directory.
 Before the first case query against a network, capture the live graph schema and
 use the observed labels, relationship types, and property names in subsequent
-queries.
+queries. Different networks can expose different fact nodes and relationship
+properties, so do not assume a query that works on Bittensor will work on Base,
+Ethereum, or TRON without a fresh schema probe.
 
 Useful schema probes:
 
 ```bash
 cia mcp call graph_query_batch \
   network=bittensor \
-  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels LIMIT 5"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN src.address AS source, dst.address AS target, f.period_granularity AS granularity LIMIT 5"},{"id":"facts_sample","query":"USE facts MATCH (a:Address)-[:HAS_FEATURE]->(f:AddressFeature) RETURN a.address AS address, f.sent_count AS sent_count LIMIT 5"}]'
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
 ```
+
+Use projections like `n.address` and `flow.tx_count` in probes. Metadata
+functions such as `keys()`, `labels()`, and `type()` are not portable across
+every GraphRAG MCP layer.

package/docs/mcp-proxy.md

@@ -132,6 +132,11 @@ current caller's quota status. Public free access does not include
 usage and batches. Use explicit LIMIT and pagination in your query when you
 want bounded result sets.
 
+For custom graph reads, install the shipped `chain-insights-cypher` skill. Its
+Memgraph examples reference distinguishes staging-tested GraphRAG MCP query
+patterns from direct Memgraph deep traversal syntax that needs a fixed-hop
+`graph_query_batch` fallback through the hosted endpoint.
+
 Paid x402 mode:
 
 ```bash
@@ -165,6 +170,11 @@ directory and registers the stdio MCP proxy in the Hermes config.
 After installing, open an initialized investigation workspace in the agent and
 operate over the workspace files.
 
+For manual graph-language work, agents should use the shipped
+`chain-insights-cypher` skill. For Bittensor queries, load
+`chain-insights-bittensor-cypher` after the generic skill so SS58 and
+EVM-pallet addresses stay under `network=bittensor`.
+
 ## Claude Desktop
 
 Claude Desktop is supported for basic MCP calls. It is not the primary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "AML investigation CLI and MCP proxy for blockchain risk, fund-flow tracing, case reports, and GraphRAG MCP access",
   "homepage": "https://chain-insights.ai",
   "repository": {

package/skills/chain-insights-bittensor-cypher/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: chain-insights-bittensor-cypher
+description: Use when writing Chain Insights graph_query or graph_query_batch reads for network=bittensor, Bittensor SS58 and EVM-pallet addresses, TAO FLOWS_TO, STAKES_IN, hotkey/coldkey/neuron facts, or Bittensor-specific schema checks.
+---
+
+# Chain Insights Bittensor Cypher
+
+Load `chain-insights-cypher` first for generic layer rules. This skill adds the
+Bittensor schema and examples.
+
+## Network Rule
+
+Bittensor contains both native Substrate/SS58 addresses such as `5...` and
+EVM-pallet `0x...` addresses in one investigation network:
+
+- Use `network=bittensor` for both address families.
+- Do not switch networks just because an address is `0x...`.
+- Preserve the exact returned `address`, `address_type`, and `network` fields.
+- If an endpoint advertises legacy `bittensor_evm`, treat it as compatibility
+  evidence, not a reason to split the investigation unless the user asks.
+
+## Current Schema Notes
+
+Observed against staging on 2026-05-29:
+
+- `network_capabilities` advertises Bittensor as default with topology, facts,
+  risk, `graph_query`, and `graph_query_batch` available; dataset coverage was
+  `unknown`.
+- `live_topology` accepted `Address` and `FLOWS_TO` projection queries. Sample
+  `Address` rows included `address`, `network`, and `address_type`; `labels`,
+  `is_exchange`, degree, and tx-count fields were sparse in the sample.
+- `live_topology` accepted `STAKES_IN` count/projection shape but returned zero
+  rows in the staging sample.
+- `archive_topology` accepted `Address` to `FLOWS_TO` historical queries and
+  returned SS58 addresses with `edge_id`, `period_granularity`, amount fields,
+  tx count, and first/last timestamps.
+- `archive_topology` exposed `TopologySnapshot` in the staging sample.
+- Source mappings include archive `STAKES_IN` and facts labels/features/neuron
+  context, but staging returned generic backend errors for those sample reads;
+  verify them with a fresh schema probe before relying on them.
+- On 2026-05-29, staging accepted practical Memgraph-style reads such as
+  `WHERE STARTS WITH`, `WITH` aggregations, `CASE`, address-family counts, and
+  fixed-hop `FLOWS_TO` patterns. It rejected native Memgraph deep traversal
+  operators through the hosted GraphRAG MCP path, including `*BFS`,
+  `*WSHORTEST`, `*ALLSHORTEST`, `*KSHORTEST`, and variable-length relationship
+  syntax. Use the generic skill reference
+  `references/memgraph-examples.md` for tested examples and fixed-hop
+  fallbacks.
+
+## Bittensor Shapes
+
+Live topology:
+
+```cypher
+USE live_topology
+MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address)
+RETURN src.address AS from_address,
+       dst.address AS to_address,
+       flow.amount_sum AS amount_sum,
+       flow.amount_usd_sum AS amount_usd_sum,
+       flow.tx_count AS tx_count,
+       flow.first_seen_timestamp AS first_seen_timestamp,
+       flow.last_seen_timestamp AS last_seen_timestamp
+LIMIT 25
+```
+
+Archive topology:
+
+```cypher
+USE archive_topology
+MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address)
+RETURN src.address AS from_address,
+       dst.address AS to_address,
+       flow.edge_id AS edge_id,
+       flow.period_granularity AS period_granularity,
+       flow.amount_sum AS amount_sum,
+       flow.amount_usd_sum AS amount_usd_sum,
+       flow.tx_count AS tx_count,
+       flow.first_seen_timestamp AS first_seen_timestamp,
+       flow.last_seen_timestamp AS last_seen_timestamp
+LIMIT 25
+```
+
+Stake topology, when the endpoint proves it:
+
+```cypher
+USE live_topology
+MATCH (coldkey:Address)-[stake:STAKES_IN]->(hotkey:Address)
+RETURN coldkey.address AS coldkey,
+       hotkey.address AS hotkey,
+       stake.netuid AS netuid,
+       stake.amount AS amount,
+       stake.source_role AS source_role,
+       stake.destination_role AS destination_role,
+       stake.source_backend AS source_backend
+LIMIT 25
+```
+
+Facts, when the endpoint proves the mapping:
+
+```cypher
+USE facts
+MATCH (coldkey:Address)-[:REGISTERED_NEURON]->(hotkey:Hotkey)-[:SERVED_FROM]->(ip:IPAddress)
+RETURN coldkey.address AS coldkey,
+       hotkey.address AS hotkey,
+       ip.ip_address AS ip_address
+LIMIT 25
+```
+
+## Schema Probe
+
+Use this before a custom Bittensor query session:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_projection","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange, n.address_type AS address_type, n.network AS network LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"live_stake_count","query":"USE live_topology MATCH (:Address)-[stake:STAKES_IN]->(:Address) RETURN count(stake) AS stake_edges LIMIT 1"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.edge_id AS edge_id, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"archive_snapshot","query":"USE archive_topology MATCH (s:TopologySnapshot) RETURN s.graph_name AS graph_name, s.default_period_granularity AS default_period_granularity, s.available_granularities AS available_granularities LIMIT 5"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
+```
+
+Avoid `keys()`, `labels()`, `type()`, native BFS syntax, and variable-length
+paths in schema probes. They may be valid in a direct Memgraph console but are
+not portable across the GraphRAG MCP federation path.
+
+## Investigation Patterns
+
+Outflows from a SS58 or `0x...` Bittensor address:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address {address: "FULL_BITTENSOR_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_usd_sum DESC LIMIT 50'
+```
+
+Find likely address completions from a prefix:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) WHERE a.address STARTS WITH "5Ggf" RETURN a.address AS address, a.address_type AS address_type, a.network AS network LIMIT 10'
+```
+
+Show how the combined Bittensor network currently splits address families:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) RETURN a.address_type AS address_type, a.network AS source_network, count(a) AS addresses ORDER BY addresses DESC LIMIT 10'
+```
+
+Historical archive read for the same address:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address {address: "FULL_BITTENSOR_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 50'
+```
+
+When comparing amounts, remember that archive StarRocks-backed numeric fields
+may arrive as strings while live Memgraph fields may arrive as numbers.

package/skills/chain-insights-bittensor-cypher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bittensor Cypher"
+  short_description: "Write Bittensor-specific Chain Insights graph reads"
+  default_prompt: "Use Chain Insights graph_query or graph_query_batch on network=bittensor with SS58 and EVM-pallet address handling, Bittensor topology fields, bounded Cypher, and fresh schema probes."

package/skills/chain-insights-cypher/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: chain-insights-cypher
+description: Use when writing, reviewing, or debugging Chain Insights graph_query or graph_query_batch GQL/Cypher, choosing live_topology, archive_topology, or facts, capturing schema, or making schema-aware graph reads across networks.
+---
+
+# Chain Insights Cypher
+
+Use this for manual `graph_query` and `graph_query_batch` work. For case work,
+combine it with `chain-insights-investigation`. If a network-specific Cypher
+skill exists, load it after this one.
+
+## First Moves
+
+1. Inspect the endpoint before writing network-specific queries:
+   ```bash
+   cia mcp networks
+   cia mcp call usage_status
+   ```
+2. Always pass an explicit `network`.
+3. Always add your own `LIMIT`; GraphRAG MCP does not append one.
+4. Use `graph_query_batch` for related schema, topology, and facts reads.
+5. Save material query output as workspace evidence before summarizing it.
+
+For practical query recipes and Memgraph deep traversal fallbacks, read
+`references/memgraph-examples.md`. It contains staging-tested examples for
+`MATCH`, `WHERE`, `WITH`, aggregates, `CASE`, archive/facts projections, and
+fixed-hop traversal batches.
+
+## Layer Choice
+
+| Layer | Use for | Query style |
+| --- | --- | --- |
+| `USE live_topology` | Current or recent route discovery and fast topology reads | Memgraph-backed Cypher over topology nodes and relationships. Prefer directed `MATCH` patterns and narrow projections. |
+| `USE archive_topology` | Historical money-flow and long-window topology facts | StarRocks/MemGQL GQL-Cypher subset. Keep to simple `MATCH`, `WHERE`, property projections, aggregates, `ORDER BY`, and `LIMIT`. |
+| `USE facts` | Labels, address features, risk scores, assets, and enrichment | StarRocks/MemGQL facts mapping. Verify the current network schema before assuming fact labels or relationships exist. |
+
+Treat `archive_topology` and `facts` as mapped graph views, not full Memgraph.
+Avoid backend-specific functions such as `keys()`, `labels()`, `type()`,
+procedures, native BFS syntax, catalog operations, and variable-length path
+tricks unless the current endpoint has just accepted the exact pattern. When a
+Memgraph deep traversal pattern fails, rewrite it as a bounded
+`graph_query_batch` of explicit fixed-hop `FLOWS_TO` patterns.
+
+## Common Schema
+
+Topology is intentionally stable across networks:
+
+- Node: `(:Address)` with `address`, usually sparse `labels` and `is_exchange`.
+- Edge: `(:Address)-[:FLOWS_TO]->(:Address)` for money flow.
+- Archive flow fields commonly include `edge_id`, `from_address`, `to_address`,
+  `period_granularity`, `period_start_date`, `period_end_date`,
+  `asset_contract`, `asset_symbol`, `tx_count`, `amount_sum`,
+  `amount_usd_sum`, `first_seen_timestamp`, `last_seen_timestamp`,
+  `first_tx_id`, and `last_tx_id`.
+- Facts may expose `AddressFeature`, `AddressLabel`, `RiskScore`, `Asset`, and
+  network-specific fact nodes.
+
+Different networks expose different schemas. Do not reuse a Bittensor stake
+query on Base or Ethereum unless that network advertises and proves the same
+labels and fields.
+
+## Schema Capture
+
+Use projections instead of metadata functions so the same probe works on both
+Memgraph-backed and mapped layers:
+
+```bash
+cia mcp call graph_query_batch \
+  network=<network> \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"live_address_sample","query":"USE live_topology MATCH (n:Address) RETURN n.address AS address, n.labels AS labels, n.is_exchange AS is_exchange LIMIT 10"},{"id":"live_flow_sample","query":"USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp LIMIT 10"},{"id":"archive_flow_sample","query":"USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count LIMIT 10"},{"id":"facts_address_sample","query":"USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 10"}]'
+```
+
+If a query fails with a generic backend error, narrow it before changing the
+investigation claim: remove metadata functions, remove cross-graph joins, use
+one relationship, project fewer fields, and lower the limit.
+
+## Query Examples
+
+Live outflows from one address:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE live_topology MATCH (src:Address {address: "FULL_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_usd_sum DESC LIMIT 50'
+```
+
+Archive flow history:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE archive_topology MATCH (src:Address {address: "FULL_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.first_seen_timestamp AS first_seen_timestamp, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 50'
+```
+
+Facts lookup after schema proof:
+
+```bash
+cia mcp call graph_query \
+  network=<network> \
+  'query=USE facts MATCH (a:Address {address: "FULL_ADDRESS"})-[:HAS_LABEL]->(label:AddressLabel) RETURN label.label AS label, label.entity_type AS entity_type, label.address_type AS address_type, label.source AS source LIMIT 25'
+```
+
+More examples: `references/memgraph-examples.md`.
+
+## Hard Stops
+
+- No writes or catalog changes: no `CREATE`, `MERGE`, `SET`, `DELETE`,
+  `REMOVE`, `DROP`, `ADD`, `CONNECT`, or `CALL`.
+- No raw StarRocks table names through GraphRAG MCP.
+- Do not rely on dynamic labels such as `:Exchange`; use `is_exchange` or
+  label facts when the schema proves they exist.
+- Empty results mean no indexed match in the selected layer, not proof of
+  safety or non-existence.

package/skills/chain-insights-cypher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Chain Insights Cypher"
+  short_description: "Write schema-aware GraphRAG MCP GQL/Cypher"
+  default_prompt: "Use Chain Insights graph_query or graph_query_batch with explicit network, layer selection, bounded read-only Cypher, schema capture, and evidence-safe output handling."

package/skills/chain-insights-cypher/references/memgraph-examples.md

@@ -0,0 +1,193 @@
+# GraphRAG MCP Cypher Examples
+
+Use these examples when an investigation needs practical graph-language reads
+instead of only schema probes. They are adapted from Memgraph query and deep
+path traversal features, then bounded to the Chain Insights GraphRAG MCP
+surface.
+
+Official Memgraph references:
+
+- Querying: https://memgraph.com/docs/querying
+- Deep path traversal: https://memgraph.com/docs/advanced-algorithms/deep-path-traversal
+
+## Staging Validation
+
+Validated against hosted staging on 2026-05-29 with `network=bittensor` and
+`per_query_timeout_seconds=5`.
+
+Accepted through GraphRAG MCP:
+
+- `MATCH`, directed relationship patterns, property equality, `WHERE`
+- `STARTS WITH`
+- `WITH`, `count`, `sum`
+- `CASE`
+- `ORDER BY`, explicit `LIMIT`
+- fixed-hop patterns written as explicit relationships
+- simple `archive_topology` counts and filtered projections
+- `facts` `Address` projection
+
+Rejected through the current hosted path with a generic backend error:
+
+- variable-length relationship syntax such as `[:FLOWS_TO*1..2]`
+- Memgraph native BFS syntax such as `*BFS` and `USING HOPS LIMIT`
+- weighted/all/K shortest path operators: `*WSHORTEST`, `*ALLSHORTEST`,
+  `*KSHORTEST`
+- `OPTIONAL MATCH`
+- `UNION ALL`
+
+Treat rejected syntax as direct-Memgraph reference material only unless the
+current endpoint accepts the exact query. For Chain Insights agents, use the
+fixed-hop `graph_query_batch` fallback below for traversal.
+
+## Live Topology Examples
+
+Top outflows by amount:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_sum DESC LIMIT 25'
+```
+
+Rank addresses by live out-degree and transferred amount:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) WITH src, count(dst) AS out_degree, sum(flow.amount_sum) AS total_amount RETURN src.address AS address, out_degree, total_amount ORDER BY out_degree DESC LIMIT 25'
+```
+
+Bucket flows for quick triage:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, CASE WHEN flow.amount_sum IS NULL THEN "unknown" WHEN flow.amount_sum >= 100 THEN "large" WHEN flow.amount_sum >= 10 THEN "medium" ELSE "small" END AS amount_bucket, flow.amount_sum AS amount_sum LIMIT 25'
+```
+
+Prefix search for address completion:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) WHERE a.address STARTS WITH "5Ggf" RETURN a.address AS address, a.address_type AS address_type, a.network AS network LIMIT 10'
+```
+
+Address-family census for a combined network:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) RETURN a.address_type AS address_type, a.network AS source_network, count(a) AS addresses ORDER BY addresses DESC LIMIT 10'
+```
+
+Bittensor EVM-pallet flow under the same investigation network:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address {address: "0x20d09f2881602eee806147ceee9275d33ff31df8"})-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, src.address_type AS from_type, src.network AS from_network, dst.address AS to_address, dst.address_type AS to_type, dst.network AS to_network, flow.amount_sum AS amount_sum LIMIT 10'
+```
+
+## Archive Topology Examples
+
+Recent historical flows:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 25'
+```
+
+Count archive flow edges by granularity:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (:Address)-[flow:FLOWS_TO]->(:Address) RETURN flow.period_granularity AS period_granularity, count(flow) AS flow_edges LIMIT 10'
+```
+
+Filter daily archive flows:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) WHERE flow.period_granularity = "daily" RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.tx_count AS tx_count ORDER BY flow.amount_sum DESC LIMIT 25'
+```
+
+Remember that archive numeric fields may arrive as strings.
+
+## Facts Examples
+
+Facts `Address` projection:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 25'
+```
+
+Only use richer fact labels or relationships after a fresh schema probe proves
+the current network exposes them. On 2026-05-29, staging accepted facts
+`Address` projection but rejected `Address` to `AddressLabel` relationship
+samples.
+
+## Fixed-Hop Traversal Fallback
+
+Memgraph deep traversal docs cover BFS, weighted shortest path, all shortest
+paths, and K shortest paths. Through the current GraphRAG MCP path, those
+native operators were rejected on staging. Use explicit fixed-hop batches for
+Chain Insights traversal instead.
+
+One-hop path:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"hop_1","query":"USE live_topology MATCH (src:Address {address: \"FULL_SOURCE_ADDRESS\"})-[r1:FLOWS_TO]->(dst:Address {address: \"FULL_TARGET_ADDRESS\"}) RETURN src.address AS from_address, dst.address AS to_address, 1 AS hops, r1.amount_sum AS amount_sum, r1.tx_count AS tx_count LIMIT 25"}]'
+```
+
+Two-hop expansion with exchange-stopped intermediate nodes:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"hop_2","query":"USE live_topology MATCH (src:Address {address: \"FULL_SOURCE_ADDRESS\"})-[r1:FLOWS_TO]->(mid:Address)-[r2:FLOWS_TO]->(dst:Address) WHERE mid.is_exchange IS NULL RETURN src.address AS from_address, mid.address AS mid_address, dst.address AS to_address, 2 AS hops, r1.amount_sum AS first_amount, r2.amount_sum AS second_amount LIMIT 25"}]'
+```
+
+Generate one query per depth when investigating a path. Keep each query
+directed, stop expansion at exchange nodes, preserve full addresses, and use a
+small `LIMIT` while exploring.
+
+## Direct Memgraph Reference Syntax
+
+Use this syntax only in a direct Memgraph console or after the GraphRAG MCP
+endpoint accepts the same pattern.
+
+Native BFS:
+
+```cypher
+MATCH path=(src:Address {address: "FULL_SOURCE_ADDRESS"})-[:FLOWS_TO *BFS]->(dst:Address {address: "FULL_TARGET_ADDRESS"})
+RETURN path
+LIMIT 5;
+```
+
+Weighted shortest path:
+
+```cypher
+MATCH path=(src:Address {address: "FULL_SOURCE_ADDRESS"})-[:FLOWS_TO *WSHORTEST (r, n | coalesce(r.amount_sum, 1)) total_weight]->(dst:Address {address: "FULL_TARGET_ADDRESS"})
+RETURN path, total_weight
+LIMIT 5;
+```
+
+K shortest alternatives:
+
+```cypher
+MATCH (src:Address {address: "FULL_SOURCE_ADDRESS"}), (dst:Address {address: "FULL_TARGET_ADDRESS"})
+WITH src, dst
+MATCH path=(src)-[:FLOWS_TO *KSHORTEST|3]->(dst)
+RETURN path
+LIMIT 3;
+```

package/skills/chain-insights-developer-experience/SKILL.md

@@ -40,6 +40,10 @@ Chain Insights tools should be implemented as local AML workflows over these
 generic graph primitives unless there is a product reason to add a new
 primitive.
 
+For manual graph-language guidance, use the shipped `chain-insights-cypher`
+skill. For Bittensor schema-specific queries, load
+`chain-insights-bittensor-cypher` after the generic skill.
+
 ## Topology Language
 
 Use these names consistently:

package/skills/chain-insights-investigation/SKILL.md

@@ -188,6 +188,8 @@ Use manual `graph_query_batch` for custom topology or fact questions. Use
 `USE live_topology` for recent topology, `USE archive_topology` for historical
 topology, and `USE facts` for facts and enrichment.
 Use `graph_query` or `graph_query_batch` for all graph-language reads.
+When writing custom Cypher, use the shipped `chain-insights-cypher` skill; for
+Bittensor, also use `chain-insights-bittensor-cypher`.
 
 ## Query And Evidence Loop