fix(dog-intelligence): hygiene items #2, #4, #5 from issue #598

skills/dog-intelligence/AGENT.md

@@ -0,0 +1,77 @@
+---
+name: dog-intelligence-agent
+skill: dog-intelligence
+description: "Autonomous operation rules for DOG rune on-chain intelligence — read-only analytics with forensic profiling, multi-chain whale tracking, multi-exchange market data, and conviction metrics."
+---
+
+# dog-intelligence — Autonomous Operation Rules
+
+## Decision Flow
+
+1. **Always run `doctor` before any action.** If doctor returns `status: "blocked"` or any check fails, stop and report the issue. Do not proceed to `run`.
+2. **Never expose API keys in logs or output.** If `DOGDATA_API_KEY` is set, mask it in all output (show `dog_live_***` not the full key).
+3. **All outputs are strict JSON.** No plaintext, no markdown, no mixed formats. Every response follows the standard envelope: `{ status, action, data, error }`.
+4. **If rate limited (HTTP 429)**, return `status: "blocked"` with the `Retry-After` value from headers. Never retry silently or loop.
+5. **Data is read-only.** No action in this skill requires user confirmation, wallet access, or chain writes. No funds are moved, no transactions are signed.
+6. **Always include `source` and `timestamp` in returned data.** Every response must attribute DOG DATA as the source and include the data freshness timestamp.
+
+## Safety Protocols
+
+- **No chain writes.** This skill reads public blockchain data only.
+- **No wallet interaction.** Does not access, unlock, or reference any wallet.
+- **No sensitive data.** Does not process private keys, mnemonics, passwords, or PII.
+- **Mainnet safe.** All endpoints are read-only GET requests against dogdata.xyz.
+- **Fail open.** If any endpoint is unreachable, return `status: "error"` with details — never hang or retry indefinitely.
+- **Timeout enforcement.** Every HTTP request has a 10-second timeout. AbortController is used to prevent hanging.
+
+## Spending Limits
+
+None. This skill has zero cost — all data comes from a free public API. No sBTC, STX, or BTC is spent at any point.
+
+## Refusal Conditions
+
+- Refuse to run any action if `doctor` has not been run in the current session.
+- Refuse to run if the API returns 5xx errors (service down) — report and wait.
+- Refuse to expose raw API keys in any output or log.
+- Refuse to make POST/PUT/DELETE requests — this skill is GET-only.
+
+## Whale Alert Thresholds
+
+- **Default threshold:** > 1,000,000 DOG (1M) per transaction — applied by the `/whale-alerts` endpoint
+- **HIGH severity:** Large individual whale move flagged by DOG DATA's classification engine
+- **CRITICAL severity:** Exceptional move — likely top-10 holder or exchange-scale transfer
+- **Major holder change:** Any top-25 holder whose balance changes > 5% between checks
+- **Multi-chain context:** Whale alerts cover Bitcoin L1, Stacks, and Solana — always check `chain` field
+
+## Data Interpretation Guidelines
+
+- **MVRV < 1.0:** DOG trades below realized value — historically undervalued zone. Flag as "accumulation territory."
+- **MVRV > 3.0:** DOG trades well above realized value — overheated. Flag as "distribution risk."
+- **LTH % > 75%:** Strong long-term conviction. Supply is locked. Bullish structural signal.
+- **LTH % < 50%:** Weak conviction. Supply is mobile. Higher sell pressure risk.
+- **Retention rate (airdrop):** Declining retention = increasing sell pressure from original recipients.
+- **Gini > 0.8:** High concentration — top holders control significant supply. LP risk factor.
+- **Price spread across exchanges > 1%:** Arbitrage opportunity exists. May indicate low liquidity on some venues.
+- **Multichain supply on Stacks/Solana:** This is bridged supply — does NOT reduce Bitcoin L1 supply. Track separately.
+- **Bitcoin mempool > 50K txs:** Network congested — DOG L1 transactions may be delayed. Flag to user.
+- **Fee > 50 sat/vB:** High fee environment. Large DOG transfers become expensive. Advise batching.
+
+## Action Selection Guide
+
+| Situation | Recommended Action |
+|-----------|-------------------|
+| Quick market check | `pulse` |
+| Large move detected / whale alert | `whales` |
+| Narrative / conviction analysis | `diamond` |
+| Historical distribution context | `airdrop` |
+| Supply-side sentiment | `lth-sth` |
+| LP / arbitrage / exchange comparison | `markets` |
+| Cross-chain bridge analysis | `multichain` |
+| Fee planning / transaction timing | `bitcoin` |
+
+## Cooldowns
+
+- Do not call the same endpoint more than once per 3 minutes (respect 20 req/hr public limit).
+- For autonomous loop integration, one `pulse` per cycle (5 min) is the recommended cadence.
+- `whales`, `diamond`, and `markets` are heavier queries — limit to once per 15 minutes in autonomous mode.
+- `bitcoin` and `multichain` update every 5 minutes on the server side — calling more often returns cached data.

skills/dog-intelligence/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: dog-intelligence
+description: "On-chain intelligence for DOG•GO•TO•THE•MOON rune — forensic analysis, LTH vs STH metrics, multi-chain whale tracking, multi-exchange markets, cross-chain data, and airdrop analytics powered by DOG DATA's Bitcoin full node."
+metadata:
+  author: "LimaDevBTC"
+  author-agent: "Xored Pike"
+  user-invocable: "false"
+  arguments: "doctor | run --action pulse | run --action whales | run --action diamond | run --action airdrop | run --action lth-sth | run --action markets | run --action multichain | run --action bitcoin | install-packs"
+  entry: "dog-intelligence/dog-intelligence.ts"
+  tags: "read-only, infrastructure, defi, l1"
+---
+
+# dog-intelligence
+
+On-chain intelligence hub for **DOG•GO•TO•THE•MOON** — the largest Bitcoin rune by holders (89K+). Pulls data directly from a Bitcoin Core + Ord full node via the [DOG DATA](https://dogdata.xyz) API.
+
+## What it does
+
+DOG intelligence provides 8 sub-commands that give agents real-time and historical analytics on the DOG rune:
+
+| Action | What it returns |
+|--------|----------------|
+| **pulse** | Full market snapshot: price aggregated across all exchanges, MVRV ratio, holder count, LTH vs STH ratio, Diamond Paws count, retention rate. One call, complete picture. |
+| **whales** | Multi-chain whale alerts with severity (CRITICAL/HIGH), USD value, classification, and top 25 holder positions. Covers Bitcoin L1, Stacks, and Solana. |
+| **diamond** | Forensic behavioral profiles — Diamond Paws, Dog Legends, Paper Hands breakdown. Proprietary Diamond Score ratings across 14 holder categories. |
+| **airdrop** | Origin story analytics: the Runestone→DOG airdrop (100B tokens, 75,490 recipients, zero pre-sale). Retention rate, behavior breakdown, current holder status. |
+| **lth-sth** | The trademark metric: Long-Term Holder vs Short-Term Holder supply ratio. HODL waves, UTXO age distribution, median age, and supply conviction analysis. |
+| **markets** | Full multi-exchange view: prices and volumes from 20+ exchanges (CEX + Solana DEX). Spread analysis, trust scores, and 24h high/low from Kraken. |
+| **multichain** | Cross-chain DOG intelligence: bridged supply on Stacks and Solana. Holder count, market cap, liquidity, and 24h metrics per chain. |
+| **bitcoin** | Bitcoin network context: latest block, hashrate, difficulty adjustment progress, mempool depth, and fee recommendations. |
+
+## Why agents need it
+
+DOG is the #1 rune by holder count (89,020+) and the most liquid rune across CEX + DEX markets. Agents operating in Bitcoin DeFi need:
+
+- **Holder concentration** (Gini coefficient, top 10/100/1000 %) to assess LP impermanent loss risk
+- **MVRV ratio** for timing entry/exit — currently 0.27, meaning DOG trades at 27% of its realized value (historically undervalued)
+- **Multi-chain whale alerts** for frontrunning protection — severity ratings (CRITICAL/HIGH), USD value, and classification across Bitcoin L1, Stacks, and Solana. Threshold: >1M DOG per transaction.
+- **Forensic profiles** for narrative-grade intelligence — no other data source classifies 75K+ wallets into Diamond Paws, Paper Hands, Dog Legends, etc.
+- **LTH vs STH ratio** — the single most predictive metric for supply-side conviction. 79%+ of DOG supply is in long-term hands.
+- **Multi-exchange markets** — 20+ exchanges including Solana DEX (Orca, Raydium, Meteora, Jupiter) and 6 CEX. Full spread and volume analysis.
+- **Cross-chain data** — DOG bridged to Stacks (via Bitflow) and Solana. Track bridged supply, liquidity, and holder count per chain.
+- **Bitcoin network context** — fee conditions and mempool state matter when planning large DOG transactions.
+
+No other API offers Diamond Score, forensic categorization, or LTH/STH breakdown for any rune. This is Glassnode-grade analytics for Bitcoin's fungible token layer.
+
+## Safety notes
+
+- **Read-only skill.** Does not write to chain, does not move funds, does not sign transactions.
+- No sensitive data processed. No private keys, no mnemonics, no wallet access required.
+- All data sourced from DOG DATA's public API (dogdata.xyz) — GET requests only.
+- Safe for mainnet and testnet. No network-specific risk.
+- Rate limited: 20 req/hr without API key, 100 req/hr with free key, 5,000 req/hr with pro key.
+- If rate limited (HTTP 429), the skill returns `status: "blocked"` with retry information — never retries silently.
+
+## Data source
+
+[DOG DATA](https://dogdata.xyz) — the world's most comprehensive DOG rune data platform. Runs its own Bitcoin Core + Ord full node. No third-party API dependency. 40 REST endpoints, MCP server, SSE real-time events.
+
+- API Discovery: https://www.dogdata.xyz/api
+- Agent Capabilities: https://www.dogdata.xyz/api/agent/capabilities
+- OpenAPI Spec: https://www.dogdata.xyz/api/openapi.json
+- LLM Context: https://www.dogdata.xyz/llms.txt
+
+## Commands
+
+### Pre-flight check
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts doctor
+```
+
+Checks API health, connectivity, API key status, and smoke-tests all new endpoints. **Always run before other commands.**
+
+### Market pulse snapshot
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action pulse
+```
+
+### Whale tracking (multi-chain, >1M DOG threshold)
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action whales
+```
+
+### Diamond Score forensics
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action diamond
+```
+
+### Airdrop origin story
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action airdrop
+```
+
+### LTH vs STH conviction analysis
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action lth-sth
+```
+
+### Multi-exchange market data
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action markets
+```
+
+### Cross-chain data (Stacks + Solana)
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action multichain
+```
+
+### Bitcoin network status
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts run --action bitcoin
+```
+
+### Install optional SDK
+
+```bash
+bun run dog-intelligence/dog-intelligence.ts install-packs
+```
+
+## Output contract
+
+All outputs are JSON to stdout using a consistent envelope:
+
+**Success:**
+```json
+{
+  "status": "success",
+  "action": "descriptive message",
+  "data": {},
+  "error": null,
+  "source": "dogdata.xyz",
+  "timestamp": "ISO-8601"
+}
+```
+
+**Error:**
+```json
+{
+  "status": "error",
+  "action": "context of what failed",
+  "data": null,
+  "error": "descriptive error message",
+  "source": "dogdata.xyz",
+  "timestamp": "ISO-8601"
+}
+```
+
+**Rate limited:**
+```json
+{
+  "status": "blocked",
+  "action": "rate_limited",
+  "data": null,
+  "error": "Rate limited on /endpoint. Retry after 60s.",
+  "source": "dogdata.xyz",
+  "timestamp": "ISO-8601"
+}
+```