chain-insights 0.8.22 → 0.18.19

package/README.md

@@ -1,49 +1,238 @@
 # Chain Insights
 
+[![npm version](https://img.shields.io/npm/v/chain-insights)](https://www.npmjs.com/package/chain-insights)
+[![CI](https://img.shields.io/github/actions/workflow/status/chainswarm/chain-insights/verify.yml?branch=main)](https://github.com/chainswarm/chain-insights/actions/workflows/verify.yml)
+[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/chainswarm/chain-insights)](https://securityscorecards.dev/viewer/?uri=github.com/chainswarm/chain-insights)
+[![License](https://img.shields.io/npm/l/chain-insights)](https://github.com/chainswarm/chain-insights/blob/main/LICENSE)
+
 [Website](https://chain-insights.ai) | [npm](https://www.npmjs.com/package/chain-insights)
 
 Chain Insights is an open-source AML investigation toolkit for AI agents and
-analysts. Install it from npm to screen blockchain addresses, trace role-specific
-fund flows, manage workspace evidence, and generate graph reports.
+analysts. It screens blockchain addresses, explores fund flows through graph
+queries, manages local evidence workspaces, and generates graph reports.
+
+## Quickstart
+
+All shell snippets in this documentation are for **Linux** (bash). They work
+as-is on macOS; on Windows use WSL.
+
+```bash
+npx chain-insights@latest --help   # run without installing
+npm install -g chain-insights      # or install the cia CLI globally
+cia init ~/cases                   # scaffold an investigation workspace
+cia networks                       # supported networks + public tool surface
+```
+
+![Terminal demo: help, workspace init, and the network tool surface in under a minute](docs/images/quickstart-demo.svg)
+
+Sixty seconds gets you the CLI, a workspace, and the live tool catalog.
+To call the same tools from an agent, register the MCP proxy:
+`cia setup claude-code` (or `codex` / `hermes`).
+
+## Purpose And Ownership
 
-Graph access is configuration-driven. The package defaults to a local Chain
-Insights Graph endpoint for development; hosted endpoints are set explicitly with
-`graphMcpEndpoint` or `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT`.
+One public npm package (`chain-insights`) providing the `cia` CLI and a
+stdio MCP proxy over a Chain Insights Graph endpoint.
 
-## What You Can Do Today
+Owning group: chainswarm org, infra group.
+
+## What It Does
+
+Owns:
+
+- The `cia` / `chain-insights` CLI and the `chain-insights-mcp-proxy` MCP
+  server (source under `src/`).
+- The canonical public tool surface: prefixed `aml_*` / `graph_*` / `meta_*`
+  / `wallet_*` tools.
+- Local wallet and payment on Base mainnet (payment chain only).
+- Investigation workspaces, graph reports, and visualization.
+- `cia monitor`: per-case tracking with rendered dossiers on an external
+  schedule.
+- Shipped product skills under `skills/` (`chain-insights-*`), packaged
+  into the npm tarball.
+- The local Bittensor graph devkit under `devkit/`.
+
+Never touches:
+
+- Blockchain indexing, graph database storage, or graph serving — those
+  belong to the Chain Insights Graph backend.
+- Automatic risk labeling. Address labels are served by the Chain Insights
+  Graph backend and read through `aml_address_risk`; the CLI never writes
+  labels.
+- Custodial wallets or hosted case databases. Investigation data stays in
+  the local workspace unless the operator exports it.
+
+### What You Can Do Today
 
 | Tool | Use it for |
 | --- | --- |
 | `aml_address_risk` | Screen one address for risk, behavior, neighborhood context, and exchange exposure |
-| `aml_trace_victim_funds` | Trace victim/source funds forward to exchange deposit candidates |
-| `aml_trace_deposit_sources` | Trace backward from suspected deposit/cashout addresses to upstream sources and convergence |
-| `aml_trace_suspect_funds` | Trace suspected scammer, mule, operator, or laundering-ring funds forward to cashout topology |
 | `graph_query` | Run one read-only GQL/Cypher query against a Chain Insights Graph layer |
 | `graph_query_batch` | Run related read-only graph queries as one MCP call |
 | `meta_network_capabilities` | Check supported Chain Insights networks and graph tools |
 | `meta_usage_status` | Check the caller's daily free-tier graph query allowance |
+| `meta_help` | Show Chain Insights tool and workflow guidance |
 | `wallet_balance` | Show the local payment wallet amount |
 
-## Quick Start
+### Continuous Monitoring
 
-Install from npm:
+`cia monitor` re-renders each open case's dossier on a schedule. It turns one
+investigation into a standing view: seeds, scope changes, and render state
+stay as plain files in the workspace.
 
-```bash
-npm install -g chain-insights
+| Command | What it does |
+| --- | --- |
+| `cia monitor run` | One pass: render the dossier of every open case |
+| `cia monitor status` | Open cases and the last run |
+| `cia monitor render` | Re-render all open cases (or one case) from the case document |
+| `cia monitor init victim` | Bootstrap a stolen-funds case-tracking config in one command |
+| `cia monitor case add` | Register a monitor case with one or more seed addresses |
+| `cia monitor case list` | List monitor cases (open by default, `--all` for closed) |
+| `cia monitor case add-seed` | Widen an open case's seed set, timestamped |
+| `cia monitor case remove-seed` | Narrow an open case's seed set |
+| `cia monitor case close` | Close a case; passes skip it |
+
+Three things to know before scheduling it:
+
+- **`cia monitor run` is a one-shot.** One pass, then exit. Schedule it with
+  cron, pm2 (`cron_restart` plus `autorestart: false`), or your agent
+  harness's scheduled tasks.
+- **Exit `2` means an isolated case failed** while every other case
+  completed. Partial success, not a crash. Only exit `1` means nothing ran.
+- **An unchanged case is skipped, not re-rendered.** The run document
+  records `skipped_reason: 'unchanged'`, so a quiet watch reads as healthy
+  by design.
+
+See [Continuous monitoring](docs/monitoring.md) for the full surface.
+
+## Dependencies
+
+Upstream:
+
+- **Chain Insights Graph MCP endpoint** — all graph queries and AML
+  primitives. Configured via `graphMcpEndpoint`; defaults to a local
+  endpoint.
+- **Base mainnet RPC** — wallet balance and payment only
+  (`BASE_RPC_URL` override). Not a graph-support claim.
+- **Devkit fixture data** — pre-generated from the upstream export path
+  and committed under `devkit/data/`.
+
+Downstream:
+
+- Analysts and AI agents install the npm package and call the CLI or the
+  MCP tools.
+- Monitor case dossiers render as Markdown under the workspace
+  (`published/cases/<case_id>/`), ready for review and handoff.
+
+## Architecture
+
+Chain Insights is the investigation layer above the Chain Insights Graph.
+The CLI and MCP proxy call graph tools over one MCP endpoint, keep all
+evidence in local workspace folders, and never write to the graph.
+
+```text
+Agent or CLI user
+  -> Chain Insights CLI / MCP proxy
+  -> local config, wallet, workspace, artifacts, reports
+  -> Chain Insights Graph
+  -> graph intelligence for AML workflows
 ```
 
-Check the CLI:
+Source modules (hand-maintained):
 
-```bash
-cia --version
-cia update --check
-```
+| Module | Entrypoint | Component doc |
+|---|---|---|
+| `config` | `src/config` | [components/config.md](docs/architecture/components/config.md) |
+| `federation` | `src/federation` | [components/federation.md](docs/architecture/components/federation.md) |
+| `investigation` | `src/investigation` | [components/investigation.md](docs/architecture/components/investigation.md) |
+| `mcp` | `src/mcp` | [components/mcp.md](docs/architecture/components/mcp.md) |
+| `monitor` | `src/monitor` | [components/monitor.md](docs/architecture/components/monitor.md) |
+| `server` | `src/server` | [components/server.md](docs/architecture/components/server.md) |
+| `viz` | `src/viz` | [components/viz.md](docs/architecture/components/viz.md) |
+| `wallet` | `src/wallet` | [components/wallet.md](docs/architecture/components/wallet.md) |
+
+Entry points:
+
+- `bin/cli.js` → `src/cli.ts` (CLI bins: `cia`, `chain-insights`).
+- `bin/mcp-proxy.cjs` → `src/mcp/proxy.ts` (bin:
+  `chain-insights-mcp-proxy`).
+- `src/index.ts` — library exports.
+
+Full architecture docs: [docs/architecture/](docs/architecture/ARCHITECTURE.md),
+including C4 diagrams, [data contracts](docs/architecture/data-contracts.md),
+and [operating rules](docs/architecture/operating-rules.md).
+
+### Graph Access
+
+Graph queries choose the read graph explicitly:
+
+| Graph | Use it for |
+| --- | --- |
+| `topology` | The unified address / FLOWS_TO / LINKED graph — recent and full historical fund-flow traversal, plus the node `risk_score`/`risk_level` verdict |
+| `facts` | Labels, features, assets, and enrichment |
+
+One rule is worth reading before writing a query by hand: the `network`
+argument selects the graph, not the addresses inside it. The address-space
+split lives on the `:Address.network` node property. A `USE topology` match
+on `:Address` without an exact address must scope itself with
+`WHERE a.network = "..."`. On `USE facts` each network has its own backing
+database and `Address` carries no `network` property at all. See
+[Graph query compatibility](docs/graph-query-compatibility.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 (the bundled devkit serves a Bittensor fixture).
+
+## Billing: Billable Units
+
+Chain Insights Graph bills by **billable units**.
+
+- A **billable unit** is one row, node, or edge in your returned payload.
+- Bigger responses cost more. Narrow queries cost less.
+- The server reports `billable_units` on every graph response.
+
+**Check your own count.** `src/lib/recount-units.ts` mirrors the server's
+counting logic. Use it client-side to recount units in a response and
+confirm the billed amount matches what you received.
 
-Run `cia update` to update a global npm install from the public npmjs registry.
-`cia init` also checks for a newer npm release in interactive terminals and
-prompts before updating.
+**Watch for `truncated: true`.** A response can hit the row limit and get
+cut off. When you see `truncated: true`:
 
-From a local checkout:
+- Narrow the query with `LIMIT` to ask for fewer rows.
+- Page through results with `SKIP` to fetch the next batch.
+- Add a tighter `WHERE` filter before raising the limit.
+
+**Workflow tools carry a `usage` block.** `aml_address_risk` runs many graph
+queries behind the scenes to answer one question. Every response includes a
+`usage` block with the total cost of all of them:
+
+- **`billable_units`** — total units billed across every internal graph
+  query this workflow ran.
+- **`query_count`** — how many internal graph queries it took.
+- **`truncated_queries`** — how many of those internal queries hit their
+  row limit and got cut off.
+
+Use `usage` to see the real cost of a workflow call, not just of one
+`graph_query`.
+
+## Prerequisites And Environment Setup
+
+- **Linux** is the reference platform; shell snippets use bash (macOS works
+  the same; on Windows use WSL).
+- **Node.js 22 or newer** (`package.json` engines) and npm.
+- Optional: Docker with the Compose plugin, for the local devkit backend.
+- Optional: pm2 or cron, for standing-watch monitoring.
+
+`.env.example` documents the two supported overrides:
+
+| Variable | Purpose |
+| --- | --- |
+| `BASE_RPC_URL` | Base RPC override for wallet balance and the local top-up page |
+| `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` | Chain Insights Graph endpoint override; local HTTP loopback allowed, remote hosts must use `https://` |
+
+## Run
+
+### Local (from a checkout)
 
 ```bash
 npm install
@@ -52,250 +241,215 @@ npm install -g .
 cia --version
 ```
 
-Create an investigation workspace:
+Or install the released package:
+
+```bash
+npm install -g chain-insights
+cia --version
+cia update --check
+```
+
+Create an investigation workspace and run a first screen:
 
 ```bash
 mkdir -p ./chain-insights-investigations
 cd ./chain-insights-investigations
 cia init .
-```
 
-Chain Insights workspaces are plain local folders. Use any editor or agent
-tooling you want to inspect workspace files, graph reports, artifacts, and
-published outputs.
+cia mcp call aml_address_risk \
+  network=robinhood address=0xYourAddressHere
 
-## Configure Chain Insights Graph Endpoint
+find reports -maxdepth 3 -type f | sort
+```
 
-`cia` uses `graphMcpEndpoint` for all Chain Insights Graph calls. The npm
-package does not hardcode a hosted endpoint. Configure the endpoint explicitly for the
-environment you intend to use.
+Workspaces are plain local folders. Reports, graph JSON, graph HTML, and
+published bundles live under the initialized workspace. Export only when
+you need to share, hand off, or archive a review checkpoint — the handoff
+package lands under `published/<workspace-slug>/`.
 
-Local development endpoint (default):
+Example queries. Direct topology:
 
 ```bash
-cia config set graphMcpEndpoint http://127.0.0.1:8012/mcp
+cia mcp call graph_query \
+  network=robinhood \
+  "query=USE topology MATCH (a:Address) RETURN a.address AS address, a.network AS network, a.labels AS labels, a.risk_level AS risk_level LIMIT 10"
 ```
 
-For a deterministic local Bittensor backend, use the RBMK-managed devkit
-runbook and point Chain Insights at it persistently:
+Batch across graph views:
 
 ```bash
-cia debug on --token <any-string> --endpoint http://127.0.0.1:18012/mcp
+cia mcp call graph_query_batch \
+  network=robinhood \
+  'queries=[{"id":"count","query":"USE topology MATCH (a:Address) RETURN count(a) AS count LIMIT 1"},{"id":"flows","query":"USE topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN src.address AS source, dst.address AS target, f.amount_usd_sum AS amount_usd_sum, f.tx_count AS tx_count LIMIT 3"},{"id":"linked","query":"USE topology MATCH (a:Address)-[l:LINKED]-(b:Address) RETURN a.address AS address, b.address AS linked_address, l.basis AS basis, l.confidence AS confidence LIMIT 3"},{"id":"node_metrics","query":"USE topology MATCH (a:Address {address:\"FULL_ADDRESS\"}) RETURN a.address AS address, a.tx_out_count AS tx_out_count, a.tx_in_count AS tx_in_count LIMIT 1"}]'
 ```
 
-The devkit backend is unmetered and never issues a paid challenge, so
-`cia config set graphMcpEndpoint http://127.0.0.1:18012/mcp` alone also works;
-`debug on` just skips payment negotiation outright.
+More query examples (manual fund-flow reads, pagination):
+[Graph tools](docs/graph-tools.md).
 
-Hosted staging endpoint for approved testers:
+### Dev Compose (local devkit backend)
 
-```bash
-cia config set graphMcpEndpoint https://staging-mcp.chain-insights.ai/mcp
-```
+The devkit runs a deterministic local Bittensor Chain Insights Graph
+backend. Compose file: `devkit/docker-compose.yml` (default compose
+project network). Services: `starrocks`, `memgraph`,
+`starrocks-import`, `memgraph-import` (one-shot), and
+`chain-insights-graph-devkit`. Images build locally with
+`docker compose build` — never pulled from a registry.
 
-For now, use the staging endpoint only for tester activation. Production is not
-live yet.
+Start from a clean state:
 
-Hosted access also needs an access mode, such as an approved access key or a
-prepared wallet. Keep those credentials out of README examples; setup commands
-live in [MCP proxy](docs/mcp-proxy.md). For paid access, run
-`cia wallet ready`; it checks funding and finishes one-time payment setup.
+```bash
+docker compose -f devkit/docker-compose.yml down -v --remove-orphans
+docker compose -f devkit/docker-compose.yml up -d --build
+```
 
-Optional one-shot override from the environment:
+One-shot import services must exit 0. `starrocks`, `memgraph`, and
+`chain-insights-graph-devkit` must stay running. The MCP endpoint is
+`http://127.0.0.1:18012/mcp`, unmetered:
 
 ```bash
-export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=https://staging-mcp.chain-insights.ai/mcp
+export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=http://127.0.0.1:18012/mcp
 ```
 
-Validation rules:
-
-- `http://` is accepted only for `localhost` / loopback addresses.
-- Remote hosts must use `https://`.
-- Endpoint URLs with credentials, query strings, or fragments are rejected.
+Full contract and procedures live in the devkit directory's own README.
 
-Configuration precedence for `graphMcpEndpoint`:
+## Configure
 
-1. `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` env var (`GRAPH_MCP_ENDPOINT` legacy alias also supported)
-2. `cia config set graphMcpEndpoint ...` saved value
-3. Local default `http://127.0.0.1:8012/mcp`
+`cia` uses `graphMcpEndpoint` for all Chain Insights Graph calls. The npm
+package does not hardcode a hosted endpoint.
 
-Check the configured endpoint and current Chain Insights Graph capabilities:
+Local development endpoint (default):
 
 ```bash
-cia config get graphMcpEndpoint
-cia mcp networks
-cia mcp call meta_usage_status
-cia mcp tools --refresh
+cia config set graphMcpEndpoint http://127.0.0.1:8012/mcp
 ```
 
-If network or tool discovery fails, check the endpoint and access mode first.
-The CLI can still initialize workspaces and continue investigation workflow
-without a reachable Chain Insights Graph endpoint.
-
-Hosted Chain Insights Graph includes a small public free tier for `graph_query`
-before paid access is required. The default public free tier is 10 execution seconds
-per IP per UTC day. Use `meta_usage_status` to see the current caller allowance.
-Prepared wallet users receive the daily free tier first, then paid access
-continues automatically after the allowance is exhausted.
-If you do not have a prepared wallet yet, use bounded single `graph_query`
-calls within the free tier, then prepare a wallet or use an invited tester
-access key when the allowance is exhausted.
-
-Run a focused investigation in the initialized workspace:
+Public production Graph (operator configuration, never a package default).
+Use the host root. Do not add `/mcp`.
 
 ```bash
-cia init .
-
-cia mcp trace-victim-funds \
-  --network bittensor \
-  --victim-addresses 5GTjfJaLpBNrgybhY24NqhDnKW9r94z72RSYLxeodxJfSkj5
+cia config set graphMcpEndpoint https://mcp.chain-insights.ai/
 ```
 
-Then inspect:
+Optional one-shot override from the environment:
 
 ```bash
-find reports -maxdepth 3 -type f | sort
+export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=https://mcp.chain-insights.ai/
 ```
 
-## Export Only When Sharing
+Configuration precedence:
 
-Normal local work happens in the workspace. Export only when you need
-to share, hand it off to a partner, ingest into LLM Wiki, or archive a
-review checkpoint.
+1. `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` env var (`GRAPH_MCP_ENDPOINT`
+   legacy alias also supported).
+2. `cia config set graphMcpEndpoint ...` saved value.
+3. Local default `http://127.0.0.1:8012/mcp`.
 
-```bash
-# Use your configured workspace export flow to produce the handoff package.
-published/<workspace-slug>/
-```
+Validation rules:
+
+- `http://` is accepted only for localhost / loopback addresses.
+- Remote hosts must use `https://`.
+- Endpoint URLs with credentials, query strings, or fragments are rejected.
 
-Workspace-generated reports, graph JSON, graph HTML, and published bundles live
-under the initialized workspace. Treat those files as the durable handoff
-surface.
+Hosted access also needs an access mode, such as an approved access key or
+a prepared wallet. For paid access, run `cia wallet ready` — it checks
+funding and finishes one-time payment setup. Setup commands live in
+[MCP proxy](docs/mcp-proxy.md).
 
-## Examples
+The hosted graph includes a small public free tier for `graph_query`
+(default: 10 execution seconds per IP per UTC day). Use
+`meta_usage_status` to see the current caller allowance. Prepared wallet
+users receive the free tier first, then paid access continues
+automatically.
 
-Run a direct live topology query:
+Search bounds (hops, row limits, frontiers) are tunable per call, per
+network, or globally — see [Search limits](docs/search-limits.md).
 
-```bash
-cia mcp call graph_query \
-  network=bittensor \
-  "query=USE live_topology MATCH (i:Identity) RETURN i.identity_id AS identity_id, i.labels AS labels, i.risk_level AS risk_level LIMIT 10"
-```
+## Test
 
-Run a batch across graph views:
+Local gate, in order:
 
 ```bash
-cia mcp call graph_query_batch \
-  network=bittensor \
-  'queries=[{"id":"count","query":"USE live_topology MATCH (i:Identity) RETURN count(i) AS count LIMIT 1"},{"id":"archive_flows","query":"USE archive_topology MATCH (src:Identity)-[f:FLOWS_TO]->(dst:Identity) RETURN f.period_granularity AS granularity, src.identity_id AS source, dst.identity_id AS target, f.amount_usd_sum AS amount_usd_sum LIMIT 3"},{"id":"archive_member_address","query":"USE archive_topology MATCH (i:Identity)-[:HAS_ADDRESS]->(m:Address) RETURN i.identity_id AS identity_id, m.address AS member_address, m.network AS member_network LIMIT 3"},{"id":"facts_sample","query":"USE facts MATCH (i:Identity)-[:HAS_FEATURE]->(f:AddressFeature) RETURN i.identity_id AS identity_id, f.tx_out_count AS tx_out_count LIMIT 3"}]'
+npm run typecheck
+npm run build
+npm test
+npm run release:check   # PR-only step in verify.yml
 ```
 
-For no-wallet public free-tier usage, prefer the single-query example first.
-Batch calls reserve worst-case execution time and can ask for paid access even
-when a small free allowance remains.
-
-Run suspect topology without requiring an incident timestamp:
+Devkit-backed tiers (need the dev compose lane running):
 
 ```bash
-cia mcp trace-suspect-funds \
-  --network bittensor \
-  --suspect-addresses 5... \
-  --max-hops 16
+npm run devkit:smoke
+npm run devkit:smoke:parity
+npm run test:devkit
 ```
 
-## How It Fits Together
+CI install step, when reproducing CI:
 
-```text
-Agent or CLI user
-  -> Chain Insights CLI / MCP proxy
-  -> local config, wallet, workspace, artifacts, reports
-  -> Chain Insights Graph
-  -> graph intelligence for AML workflows
+```bash
+npm ci --ignore-scripts --audit=false --fund=false
 ```
 
-Chain Insights stores investigation outputs in initialized local workspaces.
-Chain Insights Graph performs graph-language reads against network-specific
-layers.
+CI workflows: `.github/workflows/verify.yml` (typecheck, build,
+release:check, tests, npm pack contents), `security.yml`, `scorecard.yml`,
+`docs.yml`.
 
-## Graph Access
+## Debug
 
-Graph queries must choose the right read layer explicitly:
-
-| Layer | Use it for |
-| --- | --- |
-| `live_topology` | Recent topology and fast traversal |
-| `archive_topology` | Historical fund-flow context |
-| `facts` | Labels, features, risk scores, assets, and enrichment |
+- Diagnostics and debug workflows: [docs/debugging.md](docs/debugging.md).
+- Skip payment negotiation against the unmetered devkit:
+  `cia debug on --token <any-string> --endpoint http://127.0.0.1:18012/mcp`.
+- MCP proxy structured logs: `~/.chain-insights/runtime/logs/mcp-proxy.jsonl`.
 
-Use `graph_query_batch` when related reads should share one call and one
-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).
+Health checks (each is runnable):
 
-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.
+```bash
+# Configured endpoint
+cia config get graphMcpEndpoint
 
-## AML Tools
+# Endpoint reachable, networks listed
+cia mcp networks
 
-The high-level AML tools are Chain Insights workflows built around graph access
-and local workspace state:
+# Caller allowance / metering status
+cia mcp call meta_usage_status
 
-- `aml_address_risk` starts a single-address screen with risk, behavior,
-  neighborhood context, and exchange exposure.
-- `aml_trace_victim_funds` traces victim/source funds forward through
-  intermediaries to exchange deposit candidates.
-- `aml_trace_deposit_sources` traces backward from suspected deposit/cashout
-  addresses to upstream sources and shared-source convergence.
-- `aml_trace_suspect_funds` traces suspected scammer, mule, operator, or
-  laundering-ring funds forward to cashout topology.
+# Fresh tool discovery
+cia mcp tools --refresh
 
-AML tools accept full blockchain addresses and return blockchain addresses as
-the public result surface. Chain Insights resolves those addresses to
-identity-grain topology internally and includes identity resolution metadata for
-audit/debug use.
+# Installed CLI sanity
+cia --version && cia update --check
 
-The three trace tools share `chain-insights.trace.v1` and return compact,
-chainable results. Full graph/table/report artifacts remain on disk under the
-workspace, with pointers in the tool result and workspace evidence.
+# Devkit service state (all imports exited 0, backends running)
+docker compose -f devkit/docker-compose.yml ps -a
+```
 
-Trace traversal treats exchange hot wallets as terminal endpoints only. Tools do
-not expand through exchange nodes or classify them as deposit, suspect, or
-intermediate candidates.
+If network or tool discovery fails, check the endpoint and access mode
+first. The CLI can still initialize workspaces and continue local
+investigation workflow without a reachable endpoint.
 
-When investigation output is large, tools can save compact evidence pointers and
-graph reports under the workspace instead of embedding large payloads in human
-notes.
+## Documentation Links
 
-## Docs Map
+Product docs:
 
 | Doc | Use it for |
 | --- | --- |
-| [Graph tools](docs/graph-tools.md) | Chain Insights Graph layers, `graph_query`, `graph_query_batch`, AML tool contracts, graph reports, evidence pointers |
-| Bittensor devkit parity workflow (RBMK) | Local Chain Insights Graph backend with deterministic Bittensor fixture data for Chain Insights development |
-| [Investigation workspaces](docs/investigation-workspaces.md) | `cia init`, workspace layout, artifacts, imports, templates, sessions, reports, and visualization outputs |
-| [MCP proxy](docs/mcp-proxy.md) | Stdio proxy behavior, endpoint configuration, agent installers, local tools, auth modes, Inspector validation |
-| [Architecture](docs/architecture.md) | Product layers, data flow, local storage, security model, config keys |
+| [Graph tools](docs/graph-tools.md) | Graph layers, `graph_query`, `graph_query_batch`, AML tool contracts, graph reports |
+| [Graph query compatibility](docs/graph-query-compatibility.md) | GQL/Cypher support per layer, rewrite recipes, traversal guidance |
+| [Search limits](docs/search-limits.md) | Tunable search/row/frontier/hop bounds, precedence, ceilings |
+| [Investigation workspaces](docs/investigation-workspaces.md) | `cia init`, workspace layout, artifacts, templates, reports, visualization |
+| [Continuous monitoring](docs/monitoring.md) | `cia monitor` commands, case tracking, dossier rendering, scheduling, exit codes |
+| [MCP proxy](docs/mcp-proxy.md) | Stdio proxy behavior, endpoint configuration, agent installers, auth modes |
+| [Architecture overview](docs/architecture.md) | Product layers, data flow, local storage, security model, config keys |
 | [Development](docs/development.md) | Build, test, and local install commands |
 | [Contributing](docs/contributing.md) | Development workflow, pull requests, release expectations |
+| [Stability policy](docs/stability.md) | Guaranteed surfaces (exit codes, MCP tool names, workspace layout), deprecation rules |
 | [Debugging](docs/debugging.md) | Local troubleshooting, diagnostics, debug workflows |
+| Bittensor devkit (in this repo under `devkit/`) | Local Bittensor graph backend contract, fixture, smoke procedures |
 
-## What It Is Not
-
-Chain Insights is not a custodial wallet, hosted case database, or replacement
-for analyst review. It does not write risk labels automatically. Investigation
-data stays in the local workspace unless the operator exports or shares it.
+Architecture depth:
 
-## Workers
-
-<!-- gsd: workers -->
-| Worker | Entrypoint | Component doc |
-|---|---|---|
-| `claude-desktop` | `src/claude-desktop` | [components/claude-desktop.md](docs/architecture/components/claude-desktop.md) |
-| `config` | `src/config` | [components/config.md](docs/architecture/components/config.md) |
-| `investigation` | `src/investigation` | [components/investigation.md](docs/architecture/components/investigation.md) |
-| `mcp` | `src/mcp` | [components/mcp.md](docs/architecture/components/mcp.md) |
-| `server` | `src/server` | [components/server.md](docs/architecture/components/server.md) |
-| `viz` | `src/viz` | [components/viz.md](docs/architecture/components/viz.md) |
-| `wallet` | `src/wallet` | [components/wallet.md](docs/architecture/components/wallet.md) |
-<!-- /gsd: workers -->
+- [docs/architecture/](docs/architecture/ARCHITECTURE.md) — index, C4
+  diagrams, context, containers, components.
+- [Data contracts](docs/architecture/data-contracts.md) — tool surface,
+  search limits, endpoint rules, shared-graph model, devkit contract.
+- [Operating rules](docs/architecture/operating-rules.md) — repo
+  invariants, findings rules, CI gotchas.
+- [docs/acceptance/](docs/acceptance/) — per-component acceptance evidence.