Initial commit: coin-hunter skill

references/user-data-layout.md

@@ -0,0 +1,143 @@
+# User Data Layout
+
+Store private coin-hunter data outside the skill directory.
+
+## Root directory
+
+Use:
+
+```text
+~/.coin-hunter/
+```
+
+This keeps personal accounts, positions, and watchlists out of packaged skill artifacts.
+
+## Layout
+
+```text
+~/.coin-hunter/
+├── config.json
+├── accounts.json
+├── positions.json
+├── watchlist.json
+├── notes.json
+└── cache/
+```
+
+## File roles
+
+### config.json
+Store user-level defaults.
+
+Suggested fields:
+- `default_exchange`
+- `default_quote_currency`
+- `timezone`
+- `preferred_chains`
+
+Example:
+
+```json
+{
+  "default_exchange": "bybit",
+  "default_quote_currency": "USDT",
+  "timezone": "Asia/Shanghai",
+  "preferred_chains": ["solana", "base"]
+}
+```
+
+### accounts.json
+Store exchange accounts and balances.
+
+Example:
+
+```json
+{
+  "accounts": [
+    {
+      "id": "bybit-main",
+      "exchange": "bybit",
+      "label": "Bybit Main",
+      "currency": "USDT",
+      "cash_balance": 0,
+      "available_cash": 0,
+      "updated_at": null,
+      "note": ""
+    }
+  ]
+}
+```
+
+### positions.json
+Store coin positions.
+
+Example:
+
+```json
+{
+  "positions": [
+    {
+      "account_id": "bybit-main",
+      "symbol": "BTCUSDT",
+      "base_asset": "BTC",
+      "quote_asset": "USDT",
+      "market_type": "spot",
+      "quantity": 0,
+      "avg_cost": 0,
+      "opened_at": null,
+      "updated_at": null,
+      "note": ""
+    }
+  ]
+}
+```
+
+### watchlist.json
+Store watched coins.
+
+Example:
+
+```json
+{
+  "watchlist": [
+    {
+      "symbol": "FARTCOIN",
+      "chain": "solana",
+      "contract_address": null,
+      "source": "manual",
+      "status": "watching",
+      "added_at": null,
+      "note": ""
+    }
+  ]
+}
+```
+
+### notes.json
+Store discretionary notes and thesis fragments.
+
+Example:
+
+```json
+{
+  "notes": [
+    {
+      "symbol": "FARTCOIN",
+      "title": "Why this stays on radar",
+      "body": "Good liquidity, strong meme spread, only for high-risk observation.",
+      "updated_at": null
+    }
+  ]
+}
+```
+
+### cache/
+Store disposable API results or normalized snapshots. Never treat this as source-of-truth portfolio state.
+
+## Rules
+
+- Keep personal data only under `~/.coin-hunter/`
+- Never write personal account or position data into `skills/coin-hunter/`
+- Treat `cache/` as disposable
+- Prefer stable IDs for accounts like `bybit-main`
+- For meme coins, include `chain` and `contract_address` when known