@kleros/agentkit 0.1.0

package/dist/index.js

@@ -0,0 +1,477 @@
+// src/contracts/abis/v2.ts
+import { getContractsViem } from "@kleros/kleros-v2-contracts/cjs/deployments";
+async function getV2Contracts(publicClient, deployment) {
+  return getContractsViem({ publicClient, deployment });
+}
+
+// src/contracts/registry.ts
+var V1_CONTRACTS = {
+  ethereum: {
+    KlerosLiquid: {
+      name: "KlerosLiquid",
+      proxyAddress: "0x988b3A538b618C7A603e1c11Ab82Cd16dbE28069"
+    },
+    PolicyRegistry: {
+      name: "PolicyRegistry",
+      proxyAddress: "0xcf1f07713d5193fae5c1653c9f61953d048bece4"
+    },
+    PNK: {
+      name: "PNK",
+      proxyAddress: "0x93ED3FBe21207Ec2E8f2d3c3de6e058Cb73Bc04d"
+    },
+    KlerosLiquidExtraViews: {
+      name: "KlerosLiquidExtraViews",
+      proxyAddress: "0x2B562ea613ad2f58746935C842d09EB147E1E940"
+    },
+    ArbitrableProxy: {
+      name: "ArbitrableProxy",
+      proxyAddress: "0x99489D7bb33539F3D1A401741E56e8f02B9AE0Cf"
+    },
+    TransactionBatcher: {
+      name: "TransactionBatcher",
+      proxyAddress: "0x82458d1C812D7c930Bb3229c9e159cbabD9AA8Cb"
+    },
+    RNG: {
+      name: "RNG",
+      proxyAddress: "0x90992fb4E15ce0C59aEFfb376460Fda4Ee19C879"
+    }
+  },
+  gnosis: {
+    KlerosLiquid: {
+      name: "xKlerosLiquid",
+      proxyAddress: "0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002",
+      implementationAddress: "0x87E1bfEB31Ac4FA857a08471847122ec338F3cF2"
+    },
+    PolicyRegistry: {
+      name: "PolicyRegistry",
+      proxyAddress: "0x9d494768936b6bDaabc46733b8D53A937A6c6D7e"
+    },
+    xPNK: {
+      name: "xPNK",
+      proxyAddress: "0x37b60f4E9A31A64cCc0024dce7D0fD07eAA0F7B3",
+      implementationAddress: "0xf8d1677c8a0c961938bf2f9adc3f3cfda759a9d9"
+    },
+    stPNK: {
+      name: "stPNK",
+      proxyAddress: "0xcb3231aBA3b451343e0Fddfc45883c842f223846",
+      implementationAddress: "0xad17051DBA7d6992DaB13a0989ecB8E3B2aE519B"
+    },
+    KlerosLiquidExtraViews: {
+      name: "KlerosLiquidExtraViews",
+      proxyAddress: "0xFA71f907B48f27d22f670d9E446f8137b0769e4B"
+    },
+    ArbitrableProxy: {
+      name: "ArbitrableProxy",
+      proxyAddress: "0xC7aDD3C961f7935CB4914E37DA991D2f1Cd7986c"
+    },
+    TransactionBatcher: {
+      name: "TransactionBatcher",
+      proxyAddress: "0x6426800F8508b15AED271337498fa5e7D0794d46"
+    },
+    RNG: {
+      name: "RNG",
+      proxyAddress: "0x52a2a2cD6775f35E53ea757Dd2F7E96ee81d7DD7"
+    }
+  },
+  sepolia: {
+    KlerosLiquid: {
+      name: "KlerosLiquid",
+      proxyAddress: "0x90992fb4E15ce0C59aEFfb376460Fda4Ee19C879"
+    },
+    KlerosLiquidExtraViews: {
+      name: "KlerosLiquidExtraViews",
+      proxyAddress: "0x5562Ac605764DC4039fb6aB56a74f7321396Cdf2"
+    },
+    PolicyRegistry: {
+      name: "PolicyRegistry",
+      proxyAddress: "0x88Fb25D399310c07d35cB9091b8346d8b1893aa5"
+    },
+    ArbitrableProxy: {
+      name: "ArbitrableProxy",
+      proxyAddress: "0x009cA5A0B816156F91B29A93d7688c52480BaB24"
+    }
+  }
+};
+function getV1Contract(chainId, contractName) {
+  return V1_CONTRACTS[chainId]?.[contractName];
+}
+
+// src/contracts/versions.ts
+function getContractsByChain(config) {
+  if (config.version === "v1") {
+    return {
+      version: "v1",
+      getContract: (name) => getV1Contract(config.id, name)
+    };
+  }
+  return {
+    version: "v2",
+    // RULE-07: config.deployment is threaded through. The cast is safe here — the only
+    // caller today (src/infra/onchain.ts fetchDisputeOnChainData) checks config.deployment
+    // for undefined and returns DomainErrorCode.DEPLOYMENT_NOT_CONFIGURED BEFORE ever
+    // reaching this call site. A future second v2 on-chain caller should either replicate
+    // that guard or hoist the check into this function itself.
+    getContracts: (publicClient) => getV2Contracts(publicClient, config.deployment)
+  };
+}
+
+// src/core/types.ts
+function ok(data) {
+  return { success: true, data };
+}
+function error(code, message, details = {}) {
+  return { success: false, code, message, details };
+}
+
+// src/types/errors.ts
+var InfraErrorCode = {
+  SUBGRAPH_ERROR: "SUBGRAPH_ERROR",
+  IPFS_ERROR: "IPFS_ERROR",
+  RPC_ERROR: "RPC_ERROR",
+  API_ERROR: "API_ERROR",
+  TIMEOUT_ERROR: "TIMEOUT_ERROR",
+  BODY_TOO_LARGE: "BODY_TOO_LARGE",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  WALLET_NOT_CONFIGURED: "WALLET_NOT_CONFIGURED",
+  // Phase 4 scaffold: write commands needing a wallet
+  IPFS_UNAVAILABLE: "IPFS_UNAVAILABLE"
+  // Phase 15 (RELY-02): cdn.kleros.link cannot serve this CID after one attempt — the repin signal. Default-gateway only (see D-28 in src/infra/ipfs.ts). Reserved names AUTH_REQUIRED/QUOTA_EXCEEDED belong to a future SEED-012 — do not reuse them here.
+};
+var DomainErrorCode = {
+  DISPUTE_NOT_FOUND: "DISPUTE_NOT_FOUND",
+  COURT_NOT_FOUND: "COURT_NOT_FOUND",
+  CHAIN_NOT_SUPPORTED: "CHAIN_NOT_SUPPORTED",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONTRACT_NOT_FOUND: "CONTRACT_NOT_FOUND",
+  // Phase 2 additions (per D-05)
+  JUROR_NOT_FOUND: "JUROR_NOT_FOUND",
+  EVIDENCE_NOT_FOUND: "EVIDENCE_NOT_FOUND",
+  STAKE_NOT_FOUND: "STAKE_NOT_FOUND",
+  INVALID_ADDRESS: "INVALID_ADDRESS",
+  INVALID_STATUS: "INVALID_STATUS",
+  // Phase 4 additions (LIST-01..04)
+  INVALID_LIMIT: "INVALID_LIMIT",
+  INVALID_ORDER_BY: "INVALID_ORDER_BY",
+  INVALID_ORDER_DIRECTION: "INVALID_ORDER_DIRECTION",
+  INVALID_CURSOR: "INVALID_CURSOR",
+  // Phase 6 additions
+  CHAIN_REQUIRED_FOR_COURT_FILTER: "CHAIN_REQUIRED_FOR_COURT_FILTER",
+  // --court requires --chain (D-20)
+  CHAIN_REQUIRED: "CHAIN_REQUIRED",
+  // command requires explicit --chain (e.g. juror info)
+  INVALID_COURT_ID: "INVALID_COURT_ID",
+  // --court value is not a non-negative integer (juror top)
+  // Phase 7 additions
+  INVALID_CONFIG_KEY: "INVALID_CONFIG_KEY",
+  // config set/unset received an unrecognised key
+  // Phase 9 additions (Meta-Evidence Resolver + Reality Handler)
+  // Resolver-layer hard failures — surfaced as success: false to callers:
+  META_EVIDENCE_NOT_FOUND: "META_EVIDENCE_NOT_FOUND",
+  META_EVIDENCE_PARSE_ERROR: "META_EVIDENCE_PARSE_ERROR",
+  // Handler-layer soft failures — caught by dispatcher, surfaced as enrichment.handler_warnings[]:
+  // These are returned from handler as error() but NEVER propagate as top-level success: false
+  // (D-10/D-11: KlerosResult<MetaEvidence> is success: true whenever MetaEvidence was fetched+parsed)
+  REALITY_DISPUTE_QUESTION_NOT_FOUND: "REALITY_DISPUTE_QUESTION_NOT_FOUND",
+  REALITY_QUESTION_NOT_FOUND: "REALITY_QUESTION_NOT_FOUND",
+  REALITY_TEMPLATE_NOT_FOUND: "REALITY_TEMPLATE_NOT_FOUND",
+  REALITY_HANDLER_FAILURE: "REALITY_HANDLER_FAILURE",
+  // Phase 12 additions (Composite Brief + Feedback Loop)
+  RATE_LIMITED: "RATE_LIMITED",
+  // report-issue: 3/60s sliding window exceeded (FB-04)
+  GITHUB_TOKEN_MISSING: "GITHUB_TOKEN_MISSING",
+  // --submit but GITHUB_TOKEN env var absent (D-09)
+  REPORT_WRITE_FAILED: "REPORT_WRITE_FAILED",
+  // local file write to ~/.kleros/reports/ failed
+  // Phase 14 additions (Ruling Semantics + URI Cleanup + Deployment Threading)
+  DISPUTE_ENRICHMENT_FAILED: "DISPUTE_ENRICHMENT_FAILED",
+  // on-chain ruling read failed on an existing dispute
+  DEPLOYMENT_NOT_CONFIGURED: "DEPLOYMENT_NOT_CONFIGURED"
+  // v2 ChainConfig missing `deployment`
+};
+
+// src/infra/http.ts
+var DEFAULT_TIMEOUT = 1e4;
+async function fetchJson(url, options) {
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(timeout)
+    });
+    if (!response.ok) {
+      return error(InfraErrorCode.API_ERROR, `HTTP ${response.status} ${response.statusText}`, {
+        url,
+        status: response.status
+      });
+    }
+    const data = await response.json();
+    return ok(data);
+  } catch (e) {
+    if (e instanceof DOMException && (e.name === "TimeoutError" || e.name === "AbortError")) {
+      return error(InfraErrorCode.TIMEOUT_ERROR, "HTTP fetch timed out", { url, timeout });
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    return error(InfraErrorCode.API_ERROR, message, { url });
+  }
+}
+
+// src/infra/ipfs.ts
+import QuickLRU from "quick-lru";
+
+// src/infra/codec.ts
+function decodeAsJson(bytes) {
+  try {
+    const text = new TextDecoder().decode(bytes);
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function decodeAsText(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+
+// src/infra/ipfs.ts
+var DEFAULT_GATEWAY = "https://cdn.kleros.link";
+var DEFAULT_TIMEOUT2 = 1e4;
+var MAX_CACHED_BODY_BYTES = 1048576;
+var _ipfsCache = new QuickLRU({
+  maxSize: 200
+});
+var _inflight = /* @__PURE__ */ new Map();
+function normalizeIpfsCid(uri) {
+  if (uri.startsWith("ipfs://")) return uri.slice(7);
+  if (uri.startsWith("/ipfs/")) return uri.slice(6);
+  return uri;
+}
+async function _fetchRaw(url, timeout, uri, isDefaultGateway, maxBodyBytes) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeout) });
+    if (!response.ok) {
+      if (isDefaultGateway && response.status >= 500) {
+        const cid = normalizeIpfsCid(uri);
+        return error(
+          InfraErrorCode.IPFS_UNAVAILABLE,
+          `IPFS_UNAVAILABLE: cdn.kleros.link returned ${response.status} ${response.statusText} for this CID \u2014 content may be unpinned. No automatic gateway fallback is attempted (by design).`,
+          { uri, cid, status: response.status, reason: "http-5xx" }
+        );
+      }
+      return error(
+        InfraErrorCode.IPFS_ERROR,
+        `IPFS fetch failed: ${response.status} ${response.statusText}`,
+        { uri, status: response.status }
+      );
+    }
+    if (maxBodyBytes !== void 0) {
+      const cl = response.headers.get("content-length");
+      if (cl !== null) {
+        const clNum = Number(cl);
+        if (!Number.isNaN(clNum) && clNum > maxBodyBytes) {
+          return error(
+            InfraErrorCode.BODY_TOO_LARGE,
+            `IPFS body too large: Content-Length ${clNum} exceeds ${maxBodyBytes}`,
+            { uri, contentLength: clNum, maxBodyBytes }
+          );
+        }
+      }
+    }
+    const contentType = response.headers.get("content-type");
+    const arrayBuffer = await response.arrayBuffer();
+    const body = new Uint8Array(arrayBuffer);
+    return ok({ body, contentType });
+  } catch (e) {
+    if (e instanceof DOMException && (e.name === "TimeoutError" || e.name === "AbortError")) {
+      if (isDefaultGateway) {
+        const cid = normalizeIpfsCid(uri);
+        return error(
+          InfraErrorCode.IPFS_UNAVAILABLE,
+          "IPFS_UNAVAILABLE: cdn.kleros.link timed out fetching this CID \u2014 content may be unpinned. No automatic gateway fallback is attempted (by design).",
+          { uri, cid, timeout, reason: "timeout" }
+        );
+      }
+      return error(InfraErrorCode.TIMEOUT_ERROR, "IPFS fetch timed out", { uri, timeout });
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    return error(InfraErrorCode.IPFS_ERROR, message, { uri });
+  }
+}
+function _fetchRawCoalesced(url, timeout, uri, isDefaultGateway, maxBodyBytes, cid, gateway) {
+  const key = `${cid}|${maxBodyBytes ?? "none"}|${gateway}`;
+  const existing = _inflight.get(key);
+  if (existing !== void 0) return existing;
+  const promise = _fetchRaw(url, timeout, uri, isDefaultGateway, maxBodyBytes).finally(() => {
+    _inflight.delete(key);
+  });
+  _inflight.set(key, promise);
+  return promise;
+}
+async function fetchIpfs(uri, options) {
+  const gateway = options?.gateway ?? DEFAULT_GATEWAY;
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT2;
+  const cid = normalizeIpfsCid(uri);
+  const cacheKey = `${gateway}|${cid}`;
+  const cached = _ipfsCache.get(cacheKey);
+  if (cached !== void 0) {
+    const json2 = decodeAsJson(cached.body);
+    if (json2 !== null) return ok(json2);
+    return ok(decodeAsText(cached.body));
+  }
+  const url = `${gateway}/ipfs/${cid}`;
+  const isDefaultGateway = gateway === DEFAULT_GATEWAY;
+  const raw = await _fetchRawCoalesced(
+    url,
+    timeout,
+    uri,
+    isDefaultGateway,
+    void 0,
+    cid,
+    gateway
+  );
+  if (!raw.success) return raw;
+  if (raw.data.body.length <= MAX_CACHED_BODY_BYTES) {
+    _ipfsCache.set(cacheKey, raw.data);
+  }
+  const json = decodeAsJson(raw.data.body);
+  if (json !== null) return ok(json);
+  return ok(decodeAsText(raw.data.body));
+}
+
+// src/infra/ipfs-walk.ts
+import { fileTypeFromBuffer } from "file-type";
+
+// src/infra/rpc.ts
+import { createPublicClient, http } from "viem";
+
+// src/types/network.ts
+function getSubgraphUrl(chain, type) {
+  const envKey = `KLEROS_SUBGRAPH_URL_${chain.id.toUpperCase().replace("-", "_")}_${type.toUpperCase()}`;
+  const envValue = process.env[envKey];
+  if (envValue) return envValue;
+  return type === "core" ? chain.subgraph.core : chain.subgraph.drt;
+}
+function getRpcUrl(chain) {
+  const envKey = `KLEROS_RPC_URL_${chain.id.toUpperCase().replace("-", "_")}`;
+  const envValue = process.env[envKey];
+  if (envValue) return envValue;
+  return chain.rpcUrl;
+}
+
+// src/infra/rpc.ts
+function createKlerosClient(config) {
+  return createPublicClient({
+    chain: config.viemChain,
+    transport: http(getRpcUrl(config))
+  });
+}
+
+// src/infra/subgraph.ts
+import { GraphQLClient } from "graphql-request";
+async function querySubgraph(url, query, variables) {
+  try {
+    const client = new GraphQLClient(url);
+    const data = await client.request(query, variables);
+    return ok(data);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return error(InfraErrorCode.SUBGRAPH_ERROR, message, { url, query });
+  }
+}
+async function querySubgraphPaginated(url, query, entityName, variables, pageSize = 100) {
+  const client = new GraphQLClient(url);
+  const allEntities = [];
+  let lastId = "";
+  try {
+    while (true) {
+      const vars = { ...variables, first: pageSize, lastId };
+      const data = await client.request(query, vars);
+      const page = data[entityName];
+      if (!page || page.length === 0) {
+        break;
+      }
+      allEntities.push(...page);
+      if (page.length < pageSize) {
+        break;
+      }
+      lastId = page[page.length - 1].id;
+    }
+    return ok(allEntities);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return error(InfraErrorCode.SUBGRAPH_ERROR, message, { url, entityName });
+  }
+}
+
+// src/types/chains.ts
+import { arbitrumSepolia, gnosis, mainnet, sepolia } from "viem/chains";
+var CHAIN_CONFIGS = {
+  ethereum: {
+    id: "ethereum",
+    chainId: 1,
+    viemChain: mainnet,
+    version: "v1",
+    name: "Ethereum",
+    rpcUrl: "https://eth.llamarpc.com",
+    subgraph: {
+      core: "https://gateway.thegraph.com/api/28aec30509f7a09a74a0690880025e3b/subgraphs/id/BqbBhB4R5pNAtdYya2kcojMrQMp8nVHioUnP22qN8JoN"
+    }
+  },
+  gnosis: {
+    id: "gnosis",
+    chainId: 100,
+    viemChain: gnosis,
+    version: "v1",
+    name: "Gnosis",
+    rpcUrl: "https://rpc.gnosischain.com",
+    subgraph: {
+      core: "https://gateway.thegraph.com/api/28aec30509f7a09a74a0690880025e3b/subgraphs/id/FxhLntVBELrZ4t1c2HNNvLWEYfBjpB8iKZiEymuFSPSr"
+    }
+  },
+  "arbitrum-sepolia": {
+    id: "arbitrum-sepolia",
+    chainId: 421614,
+    viemChain: arbitrumSepolia,
+    version: "v2",
+    name: "Arbitrum Sepolia (devnet)",
+    rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc",
+    subgraph: {
+      core: "https://gateway.thegraph.com/api/28aec30509f7a09a74a0690880025e3b/subgraphs/id/4Rg3NAW99hX8RDD281ycfeRWxp92k6RdqpW3pf6imGTS",
+      drt: "https://gateway.thegraph.com/api/28aec30509f7a09a74a0690880025e3b/subgraphs/id/HZHLr6QXebWvttsCuJsSEzYGuQLHZNdVLfEcGUSESoMs"
+    },
+    deployment: "devnet"
+  },
+  sepolia: {
+    id: "sepolia",
+    chainId: 11155111,
+    viemChain: sepolia,
+    version: "v1",
+    name: "Sepolia (testnet)",
+    rpcUrl: "https://ethereum-sepolia-rpc.publicnode.com",
+    // DEFAULT — override via KLEROS_RPC_URL_SEPOLIA (Infura/Alchemy required for event scans)
+    subgraph: {
+      core: "https://gateway.thegraph.com/api/28aec30509f7a09a74a0690880025e3b/subgraphs/id/DCc7YMYrpTodkQpmmyduPmtbaQNkNtx5UMm1RsuVX7vn"
+    }
+  }
+};
+var DEFAULT_CHAIN = "ethereum";
+function resolveChainConfig(id) {
+  return CHAIN_CONFIGS[id];
+}
+export {
+  CHAIN_CONFIGS,
+  DEFAULT_CHAIN,
+  DomainErrorCode,
+  InfraErrorCode,
+  V1_CONTRACTS,
+  createKlerosClient,
+  error,
+  fetchIpfs,
+  fetchJson,
+  getContractsByChain,
+  getRpcUrl,
+  getSubgraphUrl,
+  getV1Contract,
+  getV2Contracts,
+  ok,
+  querySubgraph,
+  querySubgraphPaginated,
+  resolveChainConfig
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@kleros/agentkit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Agent-first CLI/MCP/HTTP toolkit for Kleros dispute resolution",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kleros/agentkit.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "kleros": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills/agentkit/SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "test": "vitest",
+    "test:integration": "vitest --config vitest.integration.config.ts",
+    "lint": "biome check .",
+    "format": "biome format . --write",
+    "lint:no-eval": "! grep -rE 'eval\\(|new Function\\(|vm\\.runInNewContext\\(' src/contracts/ src/core/",
+    "verify:skill": "bash scripts/verify-skill-commands.sh",
+    "update-deployment-blocks": "tsx scripts/update-deployment-blocks.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@kleros/kleros-v2-contracts": "^2.0.0-rc.2",
+    "conf": "^15.1.0",
+    "dotenv": "^17.3.1",
+    "file-type": "~21.3.4",
+    "graphql": "^16.10.0",
+    "graphql-request": "^7.4.0",
+    "incur": "~0.4.11",
+    "picocolors": "^1.1.1",
+    "quick-lru": "^7.3.0",
+    "viem": "^2.47.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "~5.8.3",
+    "vitest": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}

package/skills/agentkit/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: agentkit
+description: Query the Kleros dispute resolution protocol — disputes, courts, jurors, evidence, policy, arbitrable contracts — and compose peer MCPs (markitdown) for binary content.
+trigger: when the user asks about Kleros disputes, court policy, juror behavior, PNK staking, dispute evidence, or arbitrable contract classification
+---
+
+## What this skill does
+
+AgentKit (`@kleros/agentkit`) is a token-efficient CLI/MCP/HTTP toolkit for the Kleros dispute resolution protocol. It ships three command groups: v1.0 (courts, disputes, evidence, jurors, stakes, config — Ethereum and Gnosis), v1.1 (juror leaderboard — cross-chain), and v1.2 (dispute policy, composite brief, arbitrable classification, issue reporting — v1 chains only). All output defaults to TOON format (40% fewer tokens); use `--format json`, `--format yaml`, or `--format md` when structured parsing is needed.
+
+## Command surface
+
+| Command | What it does | Chains | Version |
+|---------|-------------|--------|---------|
+| `kleros arbitrable classify <address>` | Classify an arbitrable contract as a known Kleros type (curated registry hit) or free-text category (Meta-Evidence fallback — callers must not branch on category value). Requires `--chain`. | ethereum, gnosis | v1.2 |
+| `kleros config get <key>` | Read a single persisted configuration value by key. | any | v1.0 |
+| `kleros config list` | List all persisted configuration values. | any | v1.0 |
+| `kleros config set <key> <value>` | Persist a configuration default (e.g., chain) so subsequent commands inherit it without `--chain`. | any | v1.0 |
+| `kleros config unset <key>` | Remove a persisted configuration key. | any | v1.0 |
+| `kleros court get <id>` | Fetch detailed parameters for a specific court: timing, fee, min stake, parent, hidden votes. | ethereum, gnosis | v1.0 |
+| `kleros court list` | List all Kleros arbitration courts with stake requirements and fee structure. | ethereum, gnosis | v1.0 |
+| `kleros court policy <id>` | Retrieve the arbitration policy document for a court from IPFS. | ethereum, gnosis | v1.0 |
+| `kleros dispute brief <id>` | Composite snapshot: policy URIs, evidence with IPFS hints, ruling labels, parties, appeal state. `--depth 0` subgraph only; `--depth 1` (default) resolved URIs; `--depth 2` full IPFS content with extractionHints. **v1 only** — arbitrum-sepolia returns `CHAIN_NOT_SUPPORTED`. | ethereum, gnosis | v1.2 |
+| `kleros dispute get <id>` | Fetch full dispute details: period, juror count, ruling, deadlines, arbitrated contract. | ethereum, gnosis, arbitrum-sepolia | v1.0 |
+| `kleros dispute list` | List disputes with optional filters (court, status, chain). | ethereum, gnosis, arbitrum-sepolia | v1.0 |
+| `kleros dispute policy <id>` | Fetch dispute-specific policy via Meta-Evidence chain. Returns `metaEvidenceUri`, `policyUri`, and enrichment. Effective constraint = court ∩ dispute — always also fetch court policy. **v1 only** — arbitrum-sepolia returns `CHAIN_NOT_SUPPORTED`. | ethereum, gnosis | v1.2 |
+| `kleros evidence list` | List evidence submitted for a dispute including resolved IPFS metadata. Items with binary attachments carry `extractionHint` for markitdown-mcp composition. | ethereum, gnosis, arbitrum-sepolia | v1.0/v1.2 |
+| `kleros juror info` | Fetch a juror's profile: PNK balance breakdown, active dispute count, coherence score, per-court stake positions. | ethereum, gnosis | v1.0 |
+| `kleros juror top` | Rank jurors by total staked PNK. Without `--chain`, merges ethereum + gnosis. | ethereum, gnosis | v1.1 |
+| `kleros report-issue create` | Create a feedback report. Writes a local `.md` file by default; `--submit` posts to GitHub Issues (requires `GITHUB_TOKEN`). | any | v1.2 |
+| `kleros stake list` | List PNK token stakes held by a juror address across courts. | ethereum, gnosis | v1.0 |
+
+Run `kleros --llms-full` for the full manifest. Run `kleros <command> --schema` for argument details.
+
+## Common workflows
+
+### Example 1 — Policy resolution (intersection rule)
+
+```
+Q: What does Kleros consider when ruling on dispute 797?
+
+A: Run two commands together — the effective juror constraint is the intersection:
+
+   kleros court policy <courtId> --chain gnosis
+   kleros dispute policy 797 --chain gnosis
+
+   court policy = what the court always requires
+   dispute policy = what this dispute adds
+
+   The effective juror constraint = court ∩ dispute. The juror must satisfy BOTH.
+   Neither alone is sufficient.
+```
+
+### Example 2 — Evidence with binary attachments
+
+```
+Q: What evidence was submitted, including the attached PDFs?
+
+A: Step 1: kleros evidence list --dispute 797 --chain gnosis
+   Step 2: For each item with an extractionHint field:
+     Call peer MCP: convert_to_markdown(uri=<extractionHint.uri>)
+     AgentKit returns URIs and extractionHints — markitdown-mcp does the text extraction.
+     AgentKit never extracts the binary itself.
+```
+
+### Example 3 — Composite brief
+
+```
+Q: Give me everything about dispute 797 in one call.
+
+A: kleros dispute brief 797 --chain gnosis --depth 1
+
+   Returns: policy URIs, evidence list with extractionHints, ruling labels, parties, appeal state.
+   For full IPFS-resolved content: --depth 2 (higher token cost).
+   Note: roundHistoryNote will explain round history is deferred to v1.3.
+```
+
+## Composing peer MCPs — markitdown-mcp
+
+When `evidence list` or `dispute brief` returns an item with an `extractionHint`, the agent should call the peer MCP server `markitdown-mcp` to extract text content from the binary attachment. AgentKit never bundles or calls markitdown directly — it returns URIs and lets agents compose the peer MCP.
+
+**Wire format:**
+
+```
+Agent receives extractionHint:
+  { recommendedTool: "markitdown", mcpToolName: "convert_to_markdown", uri: "ipfs://Qm..." }
+
+Agent calls peer MCP:
+  convert_to_markdown(uri="ipfs://Qm...")
+```
+
+The `uri` field accepts `http:`, `https:`, `ipfs:`, `file:`, and `data:` schemes.
+
+Install: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
+
+```
+pip install markitdown-mcp
+```
+
+## Common gotchas
+
+- **Chain-specificity:** Court and arbitrable addresses differ between `ethereum` and `gnosis`. Always pass `--chain` when querying a specific dispute, court, or arbitrable contract. Without `--chain`, the default is `ethereum`.
+- **v1/v2 boundary:** `dispute policy`, `dispute brief`, and `arbitrable classify` are **v1 only**. Running any of these on `--chain arbitrum-sepolia` returns `CHAIN_NOT_SUPPORTED`. `dispute get`, `dispute list`, and `evidence list` work on all chains including v2.
+- **`category` is advisory, not structural:** `arbitrable classify` may return a free-text `category` field under `curationSource: 'ipfs-category'`. Never branch logic on this value — it is derived from unstructured Meta-Evidence and is advisory only.
+- **Intersection rule:** Court policy and dispute policy are **both required**. `court policy` defines the court-wide rules; `dispute policy` adds dispute-specific constraints. The effective juror constraint is their intersection (court ∩ dispute). Running only one will miss critical context.
+- **Ruling labels may be absent:** `dispute get` returns `rulingOptions.titles[]` and `rulingLabel` after Meta-Evidence enrichment. These fields may be absent if the dispute has no associated Meta-Evidence or if enrichment fails. Treat them as optional in downstream logic.
+- **`dispute get` is live on-chain; `dispute list` is a subgraph snapshot:** `dispute get`'s `ruling`/`ruled` fields are read directly from the arbitrator contract (`currentRuling()`/`disputes()`), on both v1 and v2, on every invocation shape (`--chain` or the default multi-chain probe) — authoritative arbitrator-side state. `dispute list` items stay subgraph-sourced for performance and may show v2 `ruled` flipping up to ~2h before the arbitrable contract is actually notified (the subgraph's `ruled` is set when the `Ruling` event fires inside `passPeriod`, which is the arbitrator-side period transition — not when `executeRuling()` is later called to notify the arbitrable). Use `dispute get` when the ruling value must be current.
+- **Dead IPFS content surfaces as `IPFS_UNAVAILABLE`, not a generic error:** when `cdn.kleros.link` times out or returns a 5xx for a specific CID, `evidence list` (per-item `error` field), `dispute policy`, and `dispute brief` (per-section `error.code`) all report the distinct `IPFS_UNAVAILABLE` code instead of the generic `IPFS_ERROR`/`TIMEOUT_ERROR`. This is a single-attempt classification — AgentKit does not retry internally and does not try a second gateway (a client-side fallback would mask the signal that the content genuinely needs repinning, since `cdn.kleros.link` already fans out server-side). If you see `IPFS_UNAVAILABLE`, retrying later may help (transient failures do happen); a gateway swap will not.
+- **`dispute brief` is single-chain by design, not a bug:** it always returns `CHAIN_REQUIRED` with an actionable CTA when invoked without an explicit `--chain`. There is no multi-chain fan-out for `dispute brief` — pass `--chain ethereum` or `--chain gnosis` explicitly. This mirrors the v1/v2 boundary bullet above: a deliberate design constraint, not something to route around.
+
+## Feedback
+
+When something unexpected happens — unknown script CID, missing ruling labels, wrong arbitrable classification, or evidence content that does not load — file a feedback report:
+
+```
+kleros report-issue create --type mcp-gap --description "Dispute 797 on gnosis: evidence item QmXxx returned no extractionHint but file extension is .pdf"
+```
+
+Use `--submit` to post directly to GitHub Issues (requires `$GITHUB_TOKEN`):
+
+```
+kleros report-issue create --type mcp-gap --description "..." --submit
+```
+
+Reports are stored locally as `.md` files and optionally posted upstream. Filing a report helps improve coverage in future AgentKit releases.