---
name: chain-insights-developer-experience
description: Use when changing Chain Insights README, docs, skills, CLI UX, AML tool contracts, or developer-facing workflows. Keeps Chain Insights product-first while preserving accurate GraphRAG MCP and investigation details.
---

# Chain Insights Developer Experience

Use this skill when improving Chain Insights as a product or developer-facing
framework.

## Product Frame

Chain Insights is an AML tool framework layered on top of GraphRAG MCP.
GraphRAG MCP provides generic graph-language access. Chain Insights provides
investigation workflows, AML recipes, local cases, evidence, dossiers, reports,
and graph visualizations.

Use "GraphRAG MCP" in product-facing docs. Only use lower-level implementation
names in debugging or contributor docs when the detail is necessary.

## Current AML Tools

- `address_risk`: screen one address for risk, behavior, neighborhood context,
  and exchange exposure.
- `stake_insights`: explain Bittensor coldkey-hotkey-netuid staking behavior,
  net stake movement, counterparties, activity range, and source backend.
- `track_funds`: trace victim/source funds through intermediaries to exchange
  deposit candidates.
- `scam_topology`: expand known victim incident topology into reviewable scam
  infrastructure and label candidates.

## GraphRAG MCP Layer

GraphRAG MCP exposes generic tools such as:

- `graph_query`
- `graph_query_batch`

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.

## Topology Language

Use these names consistently:

- `live_topology`: fast, cheaper, recent/hot topology.
- `archive_topology`: wider historical topology; slower and potentially more
  costly.
- `facts`: labels, features, risk scores, assets, and enrichment.

Tell users to discover current network capabilities before assuming data is
available:

```bash
cia mcp networks
cia mcp tools --refresh
```

## README Rules

README starts from the product experience:

1. What Chain Insights is.
2. What users can do today.
3. Fast setup and one working demo.
4. AML tools.
5. GraphRAG MCP and topology model.
6. Links to deeper docs.

Do not put debug-token setup, local bypasses, release gates, full test
matrices, or client-specific desktop setup in README. Link to focused docs.

## Adding AML Tools

Every new AML tool needs:

- User problem and intended analyst workflow.
- Required inputs and optional inputs.
- GraphRAG MCP primitives used.
- Topology/facts scope.
- Result contract.
- Case evidence behavior.
- Graph report behavior.
- Tests.
- Dogfood or UAT path.

## Dogfood from a clean workspace

Before claiming the developer experience is good, run from a clean directory
outside this repository:

```bash
mkdir -p /tmp/chain-insights-dx-dogfood
cd /tmp/chain-insights-dx-dogfood
cia --version
cia init .
cia mcp networks
cia mcp tools --refresh
```

Run at least one small investigation command, inspect generated files, and feed
the friction back into README, docs, CLI help, or follow-up issues.
