CLAUDE.md git:20261026.ffb1c09A

Immutable. This exact content never changes and is served at /api/v1/blob/be25ce12f5d969e6.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

aibtc-mcp-server is an MCP (Model Context Protocol) server that enables Claude to:
1. **Discover and execute x402 API endpoints** - Paid API calls for DeFi analytics, AI services, market data
2. **Execute Stacks blockchain transactions** - Transfer STX, call smart contracts, deploy contracts

The plugin automatically handles x402 payment challenges when accessing paid endpoints.

## API Sources

`list_x402_endpoints` covers these x402 API sources; `execute_x402_endpoint` also accepts any x402 URL. Hosts that publish `openapi.json` are read live (`src/services/x402-discovery.service.ts`, 10-minute cache, a failed fetch is reported as an unavailable source); the rest are static entries in `src/endpoints/registry.ts`:

| Source | URL | Endpoints |
|--------|-----|-----------|
| x402.biwas.xyz | https://x402.biwas.xyz | DeFi analytics, market data, wallet analysis (static) |
| x402.aibtc.com | https://x402.aibtc.com (testnet: x402.aibtc.dev) | Inference, Stacks utilities, hashing, storage (live, [openapi](https://x402.aibtc.com/openapi.json)) |
| stx402.com | https://stx402.com | x402 endpoint registry, agent registry (ERC-8004), links (live, [openapi](https://stx402.com/openapi.json)) |
| directory | https://stx402.com/registry/list | Third-party x402 endpoints registered at stx402.com (live, mainnet; verified only unless `includeUnverified`) |
| aibtc.com | https://aibtc.com | Inbox messaging (static) |

## Build Commands

```bash
npm install       # Install dependencies
npm run build     # Compile TypeScript to dist/
npm run dev       # Run in development mode with tsx
npm start         # Run compiled server
```

## Publishing & Releases

Releases are cut by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-please.yml`). Don't run `npm version` or push tags by hand.

1. Merge PRs to `main` with [Conventional Commit](https://www.conventionalcommits.org) titles (they're squash-merged, so the PR title is the commit).
2. release-please opens or updates a `chore(main): release mcp-server X.Y.Z` PR. It bumps `package.json`, `package-lock.json`, `server.json`, `skill/SKILL.md` and `.release-please-manifest.json`, and writes `CHANGELOG.md`.
3. To release, merge that PR. The workflow then tags `mcp-server-vX.Y.Z`, creates the GitHub release, and publishes to npm.

The commit type picks the version bump:
- `fix:` → patch (2.6.0 → 2.6.1)
- `feat:` → minor (2.6.0 → 2.7.0)
- `feat!:` / `BREAKING CHANGE:` footer → major (2.6.0 → 3.0.0)
- `chore:`, `docs:`, `ci:`, `test:` → no release on their own

To republish the current version without a new release, run the workflow manually from `main` with `publish_existing`.

## Code Principles

**CRITICAL: Follow these principles when writing code in this repository:**

1. **No Dummy Implementations** - Never write placeholder/stub code that returns fake data. If a feature can't be fully implemented, don't implement it at all. Remove the feature rather than shipping non-functional code.

2. **No Defensive Programming with Fallback Dummies** - Do not catch errors and return default/dummy values. If an operation fails, let it fail. Don't hide failures behind fake success responses.

3. **Real Implementation or Nothing** - Every function must do real work. If you can't make a real API call, contract call, or data fetch, don't write the function.

4. **Delete Over Stub** - When removing functionality, delete it completely. Don't leave behind commented code, stub methods, or "TODO" implementations.

5. **Errors Should Surface** - Let errors propagate to the user. Don't swallow exceptions or return fallback values that mask failures.

## Architecture

```
Claude Code
    ↓ (MCP stdio transport)
aibtc-mcp-server MCP Server (src/index.ts)
    ↓
┌─────────────────────────────────────────────────────────┐
│  x402 Endpoints                          Stacks TX      │
│  (x402.service)                          (builder.ts)   │
│  ┌─────────────┐  ┌─────────────┐                       │
│  │x402.biwas.xyz│  │ stx402.com  │                       │
│  └─────────────┘  └─────────────┘                       │
└─────────────────────────────────────────────────────────┘
         ↓                    ↓                    ↓
   x402 API Server     x402 API Server     Stacks Blockchain
```

### Key Files

- `src/index.ts` - MCP server with all tool definitions
- `src/services/x402.service.ts` - x402 API client (`createApiClient`) with automatic 402 payment handling, spend metering, and dedup
- `src/transactions/builder.ts` - Stacks transaction building and signing (`transferStx`, `callContract`, `deployContract`)
- `src/services/wallet-manager.ts` - Managed wallet creation, encryption, and session management
- `src/services/defi.service.ts` - ALEX DEX (via alex-sdk) and Zest Protocol integrations
- `src/services/bitflow.service.ts` - Bitflow DEX integration (via @bitflowlabs/core-sdk)
- `src/services/mempool-api.ts` - mempool.space API client for Bitcoin UTXO, fee, and broadcast
- `src/transactions/bitcoin-builder.ts` - Bitcoin transaction building and signing (P2WPKH)
- `src/endpoints/registry.ts` - Static x402 endpoint entries for hosts without an OpenAPI spec (x402.biwas.xyz, aibtc.com inbox)
- `src/services/x402-discovery.service.ts` - Live endpoint discovery from x402.aibtc.com / stx402.com `openapi.json` and the stx402.com directory
- `src/services/bns.service.ts` - BNS name resolution (supports both V1 and V2)
- `src/services/hiro-api.ts` - Hiro API client + BNS V2 API client
- `src/config/contracts.ts` - Contract addresses and Zest asset configuration (LP tokens, oracles, decimals)
- `src/services/scaffold.service.ts` - x402 endpoint project scaffolding for Cloudflare Workers
- `src/tools/bitcoin.tools.ts` - Bitcoin L1 tools (balance, fees, UTXOs, transfer)
- `src/services/stacking.service.ts` / `src/tools/stacking.tools.ts` - PoX-5 staking (signer managers, stake/stake-update/unstake, reward claims)
- `src/tools/news.tools.ts` - AIBTC News tools (**deprecated** — aibtc.news API returns 410; each `news_*` tool returns a redirect to `legion_*`)
- `src/tools/legion.tools.ts` - AIBTC News Legion governance (inscribe → propose → vote → conclude, contribute, sponsor)
- `src/services/legion.service.ts` - Legion chain reads, network-pinned account, phase/outcome derivation
- `src/config/legion.ts` - Legion mainnet contract ids (constants), network derivation, contract error codes
- `src/tools/at-stake.tools.ts` - At Stake market (elsalvadorstakesbtc.com — complete-set mint/merge, bids, transfer, redeem, resolve-idle)
- `src/tools/at-stake-legion.tools.ts` - At Stake side legions (aibtc.com/legions — propose, vote, conclude, vault settlement)
- `src/services/at-stake.service.ts` - At Stake chain reads, network-pinned account, conclude-outcome prediction
- `src/config/at-stake.ts` - At Stake contract ids, side mapping (BONDED=yes, IDLE=no), contract error codes
- `src/tools/profiles.ts` - Tool profiles: the lean `CORE_TOOLS` set, `TOOL_GROUPS`, and `AIBTC_TOOLS` / `--profile` resolution (groups are assigned per module in `src/tools/index.ts`)
- `src/tools/competition.tools.ts` - AIBTC Trading Competition (concluded; **not registered** — module kept for the `computeCampaignStats` P&L reference, exposes no MCP tools)
- `src/tools/psbt.tools.ts` - PSBT create/sign/broadcast/decode (used by ordinals marketplace, P2P and taproot multisig flows)
- `src/tools/settings.tools.ts` - Hiro API key, custom Stacks API URL, server version
- `src/tools/pillar.tools.ts` - Pillar smart wallet tools (handoff model)
- `src/services/pillar-api.service.ts` - Pillar API client
- `src/config/pillar.ts` - Pillar configuration (API URL, API key)

### BNS V1 vs V2

The agent supports both BNS naming systems:

| System | API | Usage |
|--------|-----|-------|
| BNS V1 | `api.hiro.so/v1/names/{name}` | Legacy names (older registrations) |
| BNS V2 | `api.bnsv2.com/names/{name}` | Current system (most .btc names) |

BNS tools automatically check V2 first for `.btc` names, falling back to V1 for legacy support.

### x402 Payment Flow

1. Client makes request to x402 endpoint
2. Endpoint returns HTTP 402 with payment requirements
3. The response interceptor in `createApiClient` (`src/services/x402.service.ts`) intercepts the 402
4. Interceptor signs and broadcasts payment transaction
5. Request is retried with payment proof
6. Endpoint returns actual response

## Configuration

The server never reads a `.env` file: it would load the `.env` of whatever project the MCP client was opened in. Installed users set these in the client config's `env` block (`--install` writes it) or the shell. In this repo, `npm run dev` / `npm start` load `./.env` explicitly (`--env-file-if-exists`):
- `CLIENT_MNEMONIC` - 24-word Stacks wallet mnemonic (optional - can use managed wallets instead)
- `NETWORK` - "mainnet" or "testnet" (default: mainnet)
- `AIBTC_TOOLS` - `core` (lean set, written by `--install`), `core,<group,...>`, or `all`. Unset loads everything so pre-profile configs keep their tools; `--profile full` = `all`, `--profile lean` = `core`
- `OPENROUTER_API_KEY` / `OPENROUTER_MODEL` - Only used by the `bridge` subcommand (drive tools via an OpenRouter model)
- `SPEND_LIMIT_ENABLED` - Wallet spending limit on/off (default: true)
- `SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX` - STX spend cap per day / per unlock in micro-STX (default: 50000000 = 50 STX)
- `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` - BTC spend cap per day / per unlock in sats (default: 50000)
- `AIBTC_ALLOW_BLIND_SIGN` - `true` lets `schnorr_sign_digest` sign raw digests (off by default: a signed sighash spends outside the limit)

### Spending Limit

A default-on safety rail (`src/services/spend-limiter.ts`) meters every signed spend against a cumulative per-session **and** per-day cap, tracked in two ledgers (`uSTX`, `sats`) and persisted to `~/.aibtc/spend-state.json`. Each spend is booked with `reserve()` **before it is signed or broadcast**: the cap check and the booking are one step under the shared `x402-guards.lock` lease, so two processes on one ledger (this server and the skills engine) cannot both pass against the same day total. A spend over the cap throws; the message tells the agent to ask the user (never how to disable the rail). A spend is given back with `release()` only when it provably never left: signing failed, the node returned an explicit rejection (Stacks `error` response, mempool 4xx), or the sponsor relay refused it. A broadcast that throws, a Lightning/L402 payment that throws, or an x402 request that already carried the payment keeps its booking (over-counting is the safe direction). `release()` is idempotent and never throws. If the lease cannot be taken, `reserve()` refuses; a stale lease whose holder is provably dead is reclaimed by the same `.reclaim` protocol the skills engine uses. The session ledger resets on wallet unlock/lock. The chokepoints:
- **STX transfers**: `transferStx` (`builder.ts`) meters amount + fee; `sponsoredStxTransfer` (`sponsor-builder.ts`) books the amount and releases it when the relay refuses (before the direct fallback, which books its own amount + fee).
- **Contract calls**: `callContract` and `sponsoredContractCall` go through `planContractCallSpends` (`spend-limiter.ts`). Caller-owned `eq`/`lt`/`lte` STX and sBTC post conditions are the cap (no price oracle); a caller-owned `gt`/`gte` on STX/sBTC is refused (no upper bound). Post condition mode **Allow** requires `callerSpendCaps` (`{ ustx, sats }`), which become chain-enforced `lte` post conditions on the caller and are metered; `call_contract` exposes them as `maxStxSpend` / `maxSbtcSpend`. Direct calls add the fee to the `ustx` ledger. Non-sBTC tokens are not metered (no ledger). Bitflow swaps route through `callContract`. The Legion sBTC spends sign an exact `willSendEq` and must not meter again at the tool.
- **Bitcoin L1**: every tool that broadcasts a transaction spending this wallet's BTC calls `meteredBtcBroadcast` (`src/services/btc-spend.ts`), which values each input from its previous output and meters own inputs minus outputs back to the wallet's SegWit/Taproot addresses (payment + fee). `psbt_sign` meters the inputs it signed at signing time (a signed PSBT can be broadcast by anyone) and refuses inputs without a `witnessUtxo` amount.
- **x402/L402** auto-payments (`x402.service.ts`; x402 books the amount plus the sender's STX fee in `ustx`) and manual `lightning_pay_invoice` (`lightning.tools.ts` — decodes the BOLT-11 amount, refuses amountless invoices). Lightning keys the `sats` ledger by the active Stacks address, falling back to a dedicated `__lightning__` bucket when the main STX wallet is locked.
- **Blind signing**: `schnorr_sign_digest` is refused unless `AIBTC_ALLOW_BLIND_SIGN=true`, since a signed sighash spends outside every meter.

The rail runs in this process: it does not contain an agent with shell access to the machine (it could edit the client config or, given the password, decrypt the keystore). `wallet_export` is left out of the lean core for that reason.

### Wallet Storage

Managed wallets are stored encrypted in `~/.aibtc/`:
```
~/.aibtc/
├── wallets.json       # Wallet index (metadata only)
├── config.json        # Active wallet, settings
└── wallets/
    └── [wallet-id]/
        └── keystore.json  # Encrypted mnemonic (AES-256-GCM)
```

## Adding to an MCP Client

This is a standard stdio MCP server, so it works with any MCP-compatible client. The `--install` helper writes the right config for a target; Claude Code is the default, others are selected with a flag. The install registry lives in `src/index.ts` (`INSTALL_TARGETS`).

```bash
npx @aibtc/mcp-server@latest --install              # Claude Code (default)
npx @aibtc/mcp-server@latest --install --desktop    # Claude Desktop (OS-detected path)
npx @aibtc/mcp-server@latest --install --cursor     # Cursor
npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI (TOML)
npx @aibtc/mcp-server@latest --install --vscode     # VS Code (./.vscode/mcp.json)
```

Each installer merges into the existing config rather than overwriting it. After writing the config, `--install` creates a wallet for the target network if none exists (`ensureInstallWallet` in `src/index.ts`): the generated password and mnemonic are printed once, the mnemonic is stored encrypted in `~/.aibtc/`, the password is never persisted. `--no-wallet` skips it. Zed and Cline are manual-config only (their schemas/paths vary by version) — see README for snippets. The `@latest` tag ensures users always get the newest features.

**For testnet:** Add `--testnet` to any install command, e.g. `npx @aibtc/mcp-server@latest --install --cursor --testnet`

**Note:** `CLIENT_MNEMONIC` is optional. Users can either:
1. **Managed wallets (recommended)**: Use `wallet_create` or `wallet_import` to generate/import wallets with password protection
2. **Environment mnemonic**: Set `CLIENT_MNEMONIC` in env (for power users)

## OpenRouter Bridge

`bridge` is a CLI subcommand (`src/bridge/index.ts`, routed in `src/index.ts` next to `yield-hunter`) that lets an [OpenRouter](https://openrouter.ai) model drive the tools without an MCP host. It spawns this same binary in server mode over stdio, lists tools, converts each to an OpenAI function-tool schema (verbatim `inputSchema` passthrough), and runs the tool-call loop against `https://openrouter.ai/api/v1/chat/completions`. This is OpenRouter's own client-side MCP pattern ([cookbook](https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers)) ported to Node — the client connects to MCP; there is no OpenRouter-side MCP hosting.

```bash
export OPENROUTER_API_KEY=sk-or-...
npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3..."
```

Safety flags (default exposes all tools; constrain with these):
- `--read-only` — heuristic allowlist; never includes a transfer/swap/deploy/spend tool
- `--allow a,b` / `--block a,b` — explicit overrides (`--block` wins)
- `--max-spend-ustx <n>` / `--max-spend-sats <n>` — forwarded to the spawned server's `SPEND_LIMIT_SESSION_*` rail
- `--list-tools` — preview exposed set, no API key needed
- `--model` / `--network` / `--max-turns`

The allowlist is re-enforced at `tools/call` time, so the model can't reach a tool outside the exposed set. Frameworks with native MCP support (`@openrouter/agent`, OpenAI/Claude Agents SDKs) can point at the server directly instead.

## Available Tools

> **Profiles:** new installs get `AIBTC_TOOLS=core`, which registers only the 24-tool lean core in `src/tools/profiles.ts`; everything else loads by group (`AIBTC_TOOLS=core,defi`) or with `all`. An unset `AIBTC_TOOLS` (configs from before profiles) registers everything. A new tool goes in its module's group automatically; add it to `CORE_TOOLS` only if a fresh install needs it.

> **Full tool reference:** [`docs/TOOLS.md`](docs/TOOLS.md) — per-tool parameters,
> examples, contract addresses, asset tables, and P&L methodology. The MCP server also exposes each tool's description at runtime, so the
> table below is just a discovery map. Read the reference doc before working on a tool's
> behavior.

| Domain | Key tools | Notes |
|--------|-----------|-------|
| Discovery | `list_x402_endpoints` | Start here to find x402 actions |
| Earning | `earning_opportunities` | Static "how to put your assets to work" menu; surface after `identity_register` |
| Bounties | `bounty_list/get/submissions` (read) + `bounty_submit/create/accept/paid/cancel` (BIP-322 auth) + `bounty_my_posted/my_submissions` | aibtc.com sBTC bounty board; most direct way to earn. Submit needs Registered (L1+); create needs Genesis (L2+); bc1q/P2WPKH signing; accepted submission paid in sBTC |
| Wallet & balance | `get_wallet_info`, `get_stx_balance` | |
| Wallet mgmt | `wallet_create/import/unlock/lock/list/switch/delete/export/status` | On mainnet, create/import also derive a Spark Lightning wallet from the same mnemonic |
| Bitcoin L1 | `get_btc_balance/fees/utxos`, `transfer_btc` | mempool.space; P2WPKH; sats |
| Mempool watch | `get_btc_mempool_info`, `get_btc_transaction_status`, `get_btc_address_txs` | |
| Lightning (L402) | `lightning_create/import/unlock/lock/status/fund_from_btc/claim_deposit/pay_invoice/create_invoice` | Mainnet only; Spark SDK; `L402_MAX_SATS_PER_INVOICE` cap |
| Stacks tx | `transfer_stx`, `call_contract`, `deploy_contract`, `get_transaction_status`, `broadcast_transaction` | |
| Stacking (PoX-5) | `get_pox_info`, `get_stacking_status`, `list_stacking_signers`, `get_stacking_rewards` (read) + `stack_stx`, `extend_stacking`, `unstake_stx`, `claim_stacking_rewards` | Every stake names a signer manager contract; rewards are sBTC paid through that manager (claim path read from its interface; some pay off-chain). Stake/update/unstake refused in the prepare phase. Locks carry pox-5 staking / pox post-conditions, not STX transfer ones, and are not spend-metered. `pillar_direct_stack_stx` (fast-pool) and `pillar_direct_revoke_fast_pool` are refused while pox-4 is not active — the Pillar wallet contract hardcodes pox-4 |
| x402 | `execute_x402_endpoint` | Any x402 URL, auto-payment |
| Scaffolding | `scaffold_x402_endpoint`, `scaffold_x402_ai_endpoint` | Cloudflare Worker projects |
| OpenRouter | `openrouter_integration_guide`, `openrouter_models` | AI feature integration |
| ALEX DEX | `alex_list_pools/get_swap_quote/swap/get_pool_info` | Mainnet only; `alex-sdk` |
| Zest | `zest_list_assets/get_position/supply/withdraw/borrow/repay` | Mainnet only; 10 assets |
| Bitflow DEX | `bitflow_get_ticker/tokens/swap_targets/quote/routes/swap` + Keeper tools | Mainnet only; public endpoints, no API key; `BITFLOW_KEEPER_API_HOST` overrides the keeper host |
| Pillar | `pillar_connect/disconnect/status/send/fund/supply/boost/unwind/auto_compound/position/create_wallet/add_admin/invite` | Browser handoff for passkey signing |
| AIBTC News | `news_*` (17 tools) | **Deprecated** — the aibtc.news API is retired (410). Tools stay registered but only return a pointer to `legion_*` |
| News Legion | `legion_status/list_stories/get_story/my_position` (read) + `legion_contribute/sponsor/propose_story/vote/conclude` + `legion_inscribe_story/inscribe_reveal` | **Stacks mainnet, real sBTC**, pinned by contract address — never follows global `NETWORK`. No veto, no quorum, no faucet. Proposals blocked until 21 members join (`u441`); a story also needs yes weight ≥ 20× its payout. `contribute`/`sponsor` meter the `SPEND_LIMIT_*` sats rail. Inscription is the exception: native L1 BTC on whatever `NETWORK` names, gated by `confirmMainnetSpend` |
| At Stake | `atstake_market_status/position/subject/get_bid` (read) + `atstake_mint_complete_set/merge_complete_set/place_bid/cancel_bid/transfer_shares/redeem/resolve_idle` + `atstake_legion_status/list_proposals/get_proposal/propose/vote/conclude/redeem_vault/claim_credit` | **Stacks mainnet, real sBTC**, pinned by contract address. Minting is a hedge, not a bet; legion weight is the live share balance (min 1,000) |
| Settings | `set/get/delete_hiro_api_key`, `set/get/delete_stacks_api_url`, `get_server_version` | Stored in `~/.aibtc/config.json` |
| PSBT | `psbt_create_ordinal_buy`, `psbt_sign`, `psbt_broadcast`, `psbt_decode` | Signing step for ordinals marketplace / P2P / taproot multisig flows |
| Inbox | `send_inbox_message_direct` | Mainnet only; **gasless** — the inbox 402 advertises `extra.feePayer`, so x402-stacks signs a sponsored sBTC transfer (fee 0) and the relay pays STX gas (relay `sponsorPayment`, one pending payment per sender). Without `feePayer` it falls back to a self-paid transfer signed by `createApiClient` (fee capped at the `sbtc_transfer` clamp, 0.003 STX). Meters the sBTC cost against the spend limit. `send_inbox_message` is **deprecated** — it no longer sends and just redirects here |

## Agent Behavior Guidelines

When a user asks for something:

1. **For "transfer X STX to Y"** → Use `transfer_stx` directly
2. **For "send X BTC to Y"** → Use `transfer_btc` (wallet must be unlocked)
3. **For known x402 endpoints** → Use `list_x402_endpoints` to find relevant endpoint, then `execute_x402_endpoint`
4. **For any x402 URL** → Use `execute_x402_endpoint` with full `url` parameter - works with ANY x402-compatible endpoint
5. **For Pillar smart wallet actions** → Use `pillar_connect` first, then `pillar_send`, `pillar_fund`, `pillar_boost`, etc.
6. **For aibtc.news / News Legion governance** → Start with `legion_status` (check `membership.activated` — proposals are blocked until the legion activates), then `legion_list_stories`. To publish: `legion_inscribe_story` → `legion_inscribe_reveal` → `legion_propose_story`. To judge: `legion_get_story` (open its `contentUrl` and read the piece) → `legion_vote` with a rationale → `legion_conclude`
7. **For unknown actions** → Ask user for the x402 endpoint URL or check if it's a direct blockchain action

See [`docs/TOOLS.md`](docs/TOOLS.md) for the full example-request → tool mapping.

---

## Knowledge Base References

Use the local knowledge base for Stacks/Clarity and protocol guidance: `/Users/biwas/claudex402/claude-knowledge`

### Quick Reference (Nuggets)
Fast lookups for common facts and gotchas:

- `nuggets/stacks.md` - Tenero API, SIWS, SIP-018 signing standards quick reference
- `nuggets/clarity.md` - Core principles, gotchas, error handling, testing commands
- `nuggets/cloudflare.md` - Worker deployment best practices (prefer CI/CD over direct deploy)
- `nuggets/github.md` - GitHub API, Actions, and Pages workflows

### Deep Reference (Context)
Comprehensive documentation for detailed guidance:

- `context/clarity-reference.md` - Complete Clarity language reference
- `context/siws-guide.md` and `context/sip-siws.md` - SIWS auth flows and implementation
- `context/sip-018.md` - Signed Structured Data standard for on-chain verification
- `context/tenero-api.md` and `downloads/2025-01-06-tenero-openapi-spec.json` - Market data APIs

### Patterns & Best Practices
Reusable code patterns and architectural guidance:

- `patterns/clarity-patterns.md` - Comprehensive Clarity code patterns (public functions, events, error handling, bit flags, multi-send, whitelisting, DAO proposals, fixed-point math, treasury patterns)
- `patterns/clarity-testing.md` - Testing tooling and patterns for Clarity contracts
- `patterns/skill-organization.md` - Three-layer pattern (SKILL → RUNBOOK → HELPERS) for maintainable workflows

### Architectural Decisions
Design principles and workflow patterns:

- `decisions/0002-clarity-design-principles.md` - Contract design rules, security patterns, Clarity 4 features
- `decisions/0001-workflow-component-design.md` - Development workflow component patterns (OODA loop, planning flows, composable workflows)

### Runbooks
Step-by-step operational guides:

- `runbook/clarity-development.md` - Clarity dev workflows and checklists
- `runbook/cloudflare-scaffold.md` - Cloudflare Worker setup, wrangler config, credentials, deployment patterns
- `runbook/aibtc-shared-logger.md` - Shared logging utilities for AIBTC services
- `runbook/daily-summary.md` - Daily summary generation workflow
- `runbook/setup-github-pat.md` - GitHub Personal Access Token setup
- `runbook/setup-sprout-cron.md` - Sprout documentation cron job setup
- `runbook/sprout-docs-inline.md` - Sprout documentation system overview
- `runbook/sprout-docs-github-pages.md` - Documentation site deployment with GitHub Pages
- `runbook/updating-claude-knowledge.md` - Knowledge base maintenance and sanitization guidelines