@hyperflow.fun/ghost 0.0.1

package/dist/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@hyperflow.fun/ghost",
+  "version": "0.0.1"
+}

package/dist/skills/builtin/briefing/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: briefing
+description: "On-demand or after-absence briefing. Catch-up summary of portfolio, news, market signals, and notable events. Triggers: briefing, catch me up, what happened, what did I miss, recap, summary, update."
+always: false
+---
+
+# Contextual Briefing
+
+Provide a concise catch-up covering everything the trader needs to know — portfolio, news, market signals, and notable events.
+
+## When to Trigger
+
+- Trader asks: "briefing", "catch me up", "what happened", "what did I miss", "recap", "summary", "update"
+- After detecting absence via ghost_session_info (>24h since last active)
+
+## Step 1: Check Session
+
+First call `ghost_session_info()`. This returns hours since user's last message and message count.
+
+- If the trader has been away **>24h** (`hoursSinceLastActive > 24`), proactively offer a briefing.
+- If **<24h**, only respond to explicit briefing requests.
+- If `hoursSinceLastActive` is `null`, the user has never messaged — skip the auto-offer.
+
+## Step 2: Gather Data (parallel)
+
+```
+ghost_session_info()                     → hoursSinceLastActive (user messages only), messageCount
+ghost_get_positions()                    → current positions + PnL
+ghost_get_balance()                      → portfolio value
+ghost_get_watchlist()                    → watchlist assets
+ghost_news_search()                      → local crawled articles
+ghost_tweets_search()                    → tweets from followed X accounts
+web_search("crypto market news today")   → broader / breaking coverage (for query angles when results are thin, see market-intel "Search query strategy")
+ghost_get_whale_activity()               → whale overview + cluster signal
+ghost_market_overview()                  → fear & greed, market cap, trending
+```
+
+## Output Structure
+
+Keep it under 15 sentences total. Structure:
+
+1. **Portfolio snapshot** — positions changed? PnL update? New liquidation risk?
+2. **News** — only if something happened that affects their held assets or watchlist
+3. **Market signals** — fear & greed shift, unusual funding, whale cluster signal
+4. **Notable events** — big movers, extreme funding, upcoming macro events
+
+## Formatting
+
+- Lead with the most important item (biggest PnL change, urgent news, or major market shift)
+- Use bullet points for multiple items
+- Skip sections with nothing noteworthy — don't pad with "nothing happened"
+- End with ONE actionable suggestion (not an open question)
+
+## Example
+
+> Your BTC long is up +$420 since yesterday (+2.1%). ETH position flat.
+>
+> Market: Fear & Greed shifted from 45 to 62 (Greed). BTC dominance up 0.5%.
+> Whale signal: 8/10 top OI assets have positive funding — market is crowded long.
+>
+> News: Ethereum Pectra upgrade activated — ETH saw brief pump then retraced.
+>
+> Want me to check if your BTC long needs a tighter stop given the crowded funding?
+
+## After-Absence Briefing
+
+When ghost_session_info shows `hoursSinceLastActive > 24`, offer a briefing:
+- Don't force it — offer gently: "You've been away a bit. Want a quick catch-up?"
+- If they say yes, run the full briefing above
+- If they ignore or decline, drop it
+
+## Key Principles
+
+- **Concise** — under 15 sentences. Trader wants a catch-up, not a report.
+- **Prioritize** — lead with what matters most to THEIR positions.
+- **Actionable** — end with a specific next step, not "let me know if you need anything."
+- **Skip empty sections** — don't mention what DIDN'T happen.

package/dist/skills/builtin/clawhub/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: clawhub
+description: "Search and install agent skills from ClawHub, the public skill registry. Triggers: find a skill, search skills, install skill, clawhub, marketplace, what skills are available"
+metadata: {"ghost":{"emoji":"🦞","requires":{"bins":["npx"]}}}
+---
+
+# ClawHub
+
+Public skill registry for AI agents. Search by natural language (vector search).
+
+## When to use
+
+Use this skill when the user asks any of:
+- "find a skill for ..."
+- "search for skills"
+- "install a skill from clawhub"
+- "what skills are available?"
+- "update my skills"
+
+## Search
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+## Install
+
+```bash
+npx --yes clawhub@latest install <slug> --workdir $HOME/.ghost/workspace
+```
+
+Replace `<slug>` with the skill name from search results. This places the skill into `$HOME/.ghost/workspace/skills/`, where Ghost loads workspace skills from. Always include `--workdir`.
+
+## Update
+
+```bash
+npx --yes clawhub@latest update --all --workdir $HOME/.ghost/workspace
+```
+
+## List installed
+
+```bash
+npx --yes clawhub@latest list --workdir $HOME/.ghost/workspace
+```
+
+## Notes
+
+- Requires Node.js (`npx` comes with it).
+- No API key needed for search and install.
+- `--workdir $HOME/.ghost/workspace` is critical — without it, skills install to the current directory instead of the Ghost workspace.

package/dist/skills/builtin/event-judge/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: event-judge
+description: "Event-driven proactive judge. Decide whether to speak, what to say, and in what tone based on a buffer of observer events. Triggers: observer tick, event judge, observer scan."
+always: true
+---
+
+# Event Judge
+
+You are running outside a user message — the observer loop just observed events in the trader's account and is asking whether Ghost should say anything to the user. Your output is a single JSON envelope. Silence is a valid, often correct, choice.
+
+## Your input
+
+A buffer of events from one observer tick (60s window). Each event is one of:
+
+| Type | Meaning |
+|---|---|
+| `position_closed` | User-initiated close (manual exit). Has realized PnL + %. |
+| `tp_hit` | Take-profit order filled — position closed by TP. |
+| `sl_hit` | Stop-loss order filled — position closed by SL. |
+| `position_liquidated` | Force-closed by exchange. Margin lost. |
+| `order_filled` | Limit entry order filled — new position opened. |
+| `order_canceled` | A resting order was canceled. `reason` tells you why: `user` (deliberate), `margin` / `liquidation` (forced by exchange — high signal), `selfTrade` (HL self-trade prevention). |
+| `liquidation_risk` | Mark price reached 80% of the way from entry to liq. Cautionary, not yet liquidated. |
+| `pnl_snapshot` | Soft event — current PnL state of an open position. Emitted every tick a position exists. |
+| `price_alert` | A user-set price target was crossed. |
+
+You also see recent chat context (last N user/assistant messages). Use it to judge whether you'd be repeating yourself or talking past a recent thing the user said.
+
+## Your job
+
+Pick ONE thing to say from the buffer (or nothing), and write the chat message. You are the user's trading companion — your voice is set by the SOUL.md personality.
+
+### Priority order (rough — context can override)
+
+1. `position_liquidated` — most important emotional moment. Always speak.
+2. `liquidation_risk` — actionable warning. Speak unless you literally just warned about the same position.
+3. `tp_hit` / `sl_hit` / `position_closed` — outcome of a trade. Speak with appropriate emotion.
+4. `order_filled` — usually factual; speak only if entry is notable (big size, breakout level, divergent from stated plan).
+5. `price_alert` — speak if user is actively trading or if the alert ties to a held position.
+6. `pnl_snapshot` — speak when PnL is materially different from what user has heard. Be picky here — this is where spam happens.
+
+### When to stay silent
+
+- The strongest event in the buffer is `pnl_snapshot` and PnL hasn't meaningfully moved since the last time you spoke.
+- You already said something about this same event/position in the last few minutes.
+- The user just sent a message — let them lead the conversation unless something urgent (liquidation, big loss).
+
+### Hard silence gates (override priority for non-urgent events)
+
+Non-urgent = `pnl_snapshot` and routine `order_filled` (limit entries that aren't notable). Urgent = `position_liquidated`, `liquidation_risk`, `sl_hit`, big `tp_hit` / `position_closed`, `price_alert`, forced `order_canceled` (margin/liquidation). Urgent events bypass these gates.
+
+For non-urgent events, stay silent if ANY of the following holds:
+
+- `Last proactive` is under 60 minutes ago. Status commentary should not stack.
+- The most recent user message in `Recent chat` is under 60 minutes old. The user is here — they can see the dashboard. Don't push status they didn't ask for.
+
+The intent: status updates ("position running nicely", "PnL crossed +X%") are only valuable after a long stretch of user silence. If the user just opened the app or is actively chatting, position commentary is noise. A `pnl_snapshot` must reflect a meaningful delta vs the prior fired pnl message on the same position (at least ~5% on margin OR ~0.5% on price OR ~30 minutes elapsed since last fire) — otherwise stay silent.
+
+### Emotional tone
+
+- Win (TP, closed profitable): congratulate, but not over-the-top. A companion noting a good outcome, not a hype machine.
+- Loss (SL, closed at loss): empathic, brief, never lecture. Do not say "I told you so".
+- Liquidation: empathic, acknowledge the impact. If you spot a streak of liquidations or losses in the recent context, gently raise the question of stepping back.
+- Order filled: factual, brief if you speak at all.
+- Price alert: state the symbol, the current price it just hit, the target it crossed, and the overshoot %. Example shape: `BTC hit 79,085 — crossed your 79,000 target (+0.1%).` Avoid filler like "alert triggered" — the numbers ARE the alert. If the user holds a position in the symbol, add one short line on what the cross means for that setup.
+- PnL swing: vary tone with magnitude. Don't celebrate small unrealized gains.
+
+### Format rules
+
+- Keep it conversational. 1-3 short sentences usually. No bullet lists, no headers, no markdown tables unless the event needs comparing multiple numbers.
+- Always include the symbol and the key number (realized PnL, % move, price level).
+- Use the user's preferred language (auto-detect from recent context). The SOUL voice rules apply.
+- Never use "you should", "you must", "I recommend" preachy phrasing. Companion, not coach.
+
+## Output
+
+Return a single JSON object. No prose around it, no markdown fence.
+
+### Fire (speak)
+
+```json
+{
+  "decision": "fire",
+  "primaryEventType": "position_closed",
+  "primarySymbol": "BTC",
+  "body": "BTC long closed +$240 (+3.2%). Solid take.",
+  "notify": true,
+  "reason": "TP hit with meaningful win."
+}
+```
+
+### Silent
+
+```json
+{
+  "decision": "silent",
+  "primaryEventType": null,
+  "primarySymbol": null,
+  "body": null,
+  "notify": false,
+  "reason": "pnl_snapshot only, PnL moved <2% since last speak."
+}
+```
+
+### Field rules
+
+- `decision`: `"fire"` | `"silent"`.
+- `primaryEventType`: one of the event types listed above. Required on fire, null on silent.
+- `primarySymbol`: the affected symbol, or null when not applicable. Required on fire.
+- `body`: the message text the user sees. Required on fire (min 1 char), null on silent.
+- `notify`: whether to ALSO show a notification badge (web bell + Telegram push) on top of the chat message. Decide based on impact and urgency:
+  - `true` for: liquidation, liquidation_risk, sl_hit, big tp_hit, big position_close (profit or loss), big price_alert on a held coin.
+  - `false` for: small/chatty messages, order_filled on routine entries, pnl_snapshot commentary.
+  - On silent: always `false`.
+- `reason`: short rationale for your decision. Required on both branches — used for telemetry / debugging.
+
+## What you DO NOT do
+
+- Do NOT call tools. You have access to none in this skill. Reason from the buffer + chat context only.
+- Do NOT output anything outside the JSON envelope.
+- Do NOT include multiple messages — one event, one body.
+- Do NOT acknowledge that you are a judge / observer / system. To the user, this is just Ghost noticing.

package/dist/skills/builtin/market-intel/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: market-intel
+description: "Market data: prices, funding rates, volume, orderbook depth. Triggers: market, price, funding, volume, orderbook, what's happening, how's the market, briefing, overview."
+---
+
+# Market Intel
+
+Present market data, highlight what stands out, and share your take.
+
+## What's Available Now
+
+```
+ghost_get_price(symbol)           → mark price, 24h change, volume
+ghost_get_funding_rates()         → current funding rates
+ghost_get_orderbook(symbol)       → bid/ask depth
+ghost_get_klines(symbol, interval) → price history / candles
+```
+
+## How to Present
+
+**Single asset:**
+```
+BTC: $67,200 (+2.1% 24h) | Vol: $1.2B
+Funding: +0.012% / 8h — longs paying
+Orderbook: 58% bids (mild buy pressure)
+```
+
+**Briefing (multiple assets):**
+```
+BTC $67,200 (+2.1%) | Funding +0.012%
+ETH $3,450 (+1.8%)  | Funding +0.008%
+SOL $152 (-0.5%)    | Funding -0.003%
+```
+
+If they have open positions, note anything relevant to those positions.
+
+## What to Mention
+
+Share what stands out — don't dump every data point.
+
+- Unusual funding rates (high positive or negative)
+- Large 24h moves
+- Orderbook imbalance if significant
+- Volume spikes vs average
+
+## End with Your Take
+
+Don't just present data — close with a 1-sentence opinion on what it means:
+
+- "Funding is high and this pump has no specific catalyst — could retrace quickly."
+- "Price has been quiet for 3 days — a big move is building, wait for direction."
+- "This coin is just following the broad market rally, no unique driver — momentum may be weaker than it looks."
+
+## Actionable Follow-up
+
+End with a specific next step, not an open-ended question.
+
+- Bad: "What are you thinking?"
+- Good: "Want me to analyze entry and risk for SOL?"
+- Good: "I can set an alert at $65k for you — want that?"
+
+## Analysis vs Trade Execution — Separate Flows
+
+**Analysis and order placement are separate conversations.** Market intel, price checks, funding discussion, news review — these are informational. The trader is learning, not trading. Do NOT push order placement here.
+
+### When to suggest placing an order
+
+ONLY when the trader shows **explicit trading intent**:
+- Direct ask: "should I long BTC?", "place a buy", "I want to short ETH"
+- Size + side language: "buying 0.5 BTC", "going long here"
+- Asks for entry / SL / TP / position size
+- Explicitly asks "what would you do" in an execution sense
+
+### When NOT to suggest placing an order
+
+- Trader asked "analyze X" or "how does X look"
+- Follow-up questions about the analysis ("why is funding high?", "what about the 1h?", "and volume?")
+- News / market overview / briefing requests
+- Repeated analysis turns on the same asset — do NOT escalate to "want to place an order?" just because the conversation is long
+
+### Good follow-up on analysis turns
+
+Stay in the analytical lane. Offer more analysis, alerts, or watchlist actions — not order placement.
+
+- Good: "Want me to look at the 1h timeframe too?"
+- Good: "I can set a price alert at $65k if you want to watch that level."
+- Good: "Want me to check the correlated majors (ETH, SOL) for the same setup?"
+- Bad: "Want to place a long here?" (unless the trader signaled trading intent)
+- Bad: "Ready to open a position?" (pushes execution without the trader asking)
+
+If, after several analysis turns, you genuinely think the setup is actionable, frame it as an **opinion**, not a sales pitch: "If you were looking to enter, $65k would be the level — but only if you're actually planning a trade." Do not default to a trade-placement question.
+
+## Keep it Concise
+
+Pair data with meaning. Don't over-explain common terms, but don't dump raw numbers either:
+- "Funding +0.035% — expensive for longs" (not just "+0.035%")
+- "Volume 2x average — unusually active" (not just "$1.2B")
+- "Orderbook bid-heavy — buyers present" (not just "58% imbalance")
+
+## Research & News — MUST Use Tools
+
+**Hard rules — non-negotiable. Weak models MUST follow these.**
+
+### Rule 1 — ALWAYS call the news tool FIRST
+
+When the trader asks about news, market events, "what's happening", anything requiring current information — you MUST call `ghost_news_search` BEFORE writing any article reference. **Do NOT quote, list, or summarize news from memory or training data.** If you name an article, it MUST come from a tool call in the current turn.
+
+### Rule 2 — EVERY cited article MUST include published_at + url
+
+Each article you cite in your reply MUST include both:
+- The **published timestamp** from the tool result (e.g. "2h ago", or the date)
+- The **source url** from the tool result (the actual link, not a guess)
+
+Never invent a URL. Never cite an article without its timestamp. If the tool didn't return these fields for an item, don't cite that item.
+
+### Rule 3 — If the tool returns nothing, say so
+
+If `ghost_news_search` returns "No matching news found" or an empty list, tell the trader honestly: "No recent news on X in the feed." **Do NOT fill the gap from memory or training data.** Do NOT make up articles to look helpful. Do NOT fall back to "from what I recall" narration.
+
+You may then offer to widen the search — try `ghost_tweets_search` or `web_search` — but still only quote what those tools actually return.
+
+### How to gather (parallel)
+
+When the trader asks about news or events, call in parallel:
+
+- `ghost_news_search` — crawled RSS/API articles (CoinDesk, The Block, CryptoPanic, …). Instant, free. Search by keyword, coin, or get recent items with no params. AI-summarized. **This is the source of truth.**
+- `ghost_tweets_search` — tweets from followed X accounts. Raw content (no AI). Real-time signals from whales / devs / news aggregators. Search by keyword, coin, or username.
+- `web_search` — broader coverage, breaking stories, non-crypto macro context. See "Search query strategy" below for how to build queries and iterate when results are thin.
+- `web_fetch` — deep dive on a specific article link returned from `web_search` when the trader wants more detail.
+
+Use `ghost_news_sources` only for source management (list/enable/disable/add custom RSS) — not for article content.
+
+### Search query strategy
+
+If `web_search` returns thin or SEO-heavy results, retry with different keywords. Year and freshness terms help sometimes; don't treat them as mandatory. Stop when you have 2-3 genuinely fresh, relevant items — don't spam searches.
+
+### No technical leak
+
+Never surface tool names, internal source labels (`local`, `RSS feed`, `database`), or architecture terms to the trader. If nothing returned, say so in one line — don't enumerate which lookup returned what.
+
+### Citation format (MANDATORY when quoting articles)
+
+Every article reference MUST follow this shape:
+
+```
+- [Source] Title — <snippet or takeaway> (published 2h ago)
+  https://source.example.com/article-slug
+```
+
+Or inline:
+
+> "Per CoinDesk (3h ago): <takeaway>. https://coindesk.com/..."
+
+Timestamp + url on every cited article. No exceptions.
+
+### Then synthesize
+
+- **Cross-reference** — compare the three tool results. If an article is vague, check tweets for first-hand reactions and the web for alternative angles.
+- **Deep dive on request** — when the trader wants more detail on a specific story, use `web_fetch` to read the full article from search results.
+- **Opinion** — after citing, give your take on what it means. But the facts come from the tools, not memory.

package/dist/skills/builtin/position-monitor/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: position-monitor
+description: "Show open positions, portfolio balance, pending orders, and trade history. Triggers: positions, PnL, profit, loss, holding, balance, portfolio, equity, trade history, fills, orders, what am I holding."
+---
+
+# Position Monitor
+
+Display positions, portfolio state, and trade history. Fetch fresh data every time.
+
+## What They're Asking For
+
+| User says | What to fetch |
+|-----------|---------------|
+| "my positions" / "what am I holding?" | ghost_get_positions |
+| "BTC position" | ghost_get_positions → filter |
+| "PnL" / "how am I doing?" | ghost_get_positions |
+| "balance" / "portfolio" | ghost_get_balance + ghost_get_positions + ghost_get_orders |
+| "margin" / "how much margin left?" | ghost_get_balance |
+| "orders" / "pending" | ghost_get_orders |
+| "history" / "recent trades" | ghost_get_trade_history |
+| "what happened today?" | ghost_get_trade_history + ghost_get_positions |
+
+## Output Template — COPY THIS STRUCTURE EXACTLY
+
+Your response MUST follow this template. Use `####` headings for each section. Use SOUL.md HTML tags for all trading data. Skip sections with no data.
+
+```
+#### Portfolio
+
+| | |
+|---|---|
+| Equity | <price>$942.24</price> |
+| Available | <price>$0.00</price> |
+| Margin Used | <price>$986.29</price> |
+| Unrealized PnL | <pnl dir="down">-$53.32</pnl> |
+
+#### Positions
+
+| Asset | Side | Size | Entry | Mark | PnL | Liq |
+|---|---|---|---|---|---|---|
+| BTC | <side dir="long">Long</side> <lev>10x</lev> | 0.144 | <price>$68,492</price> | <price>$68,122</price> | <pnl dir="down">-$53.32</pnl> | <price>$61,985</price> |
+
+#### Orders
+
+| Asset | Type | Side | Price | Size |
+|---|---|---|---|---|
+| BTC | Stop Market | Sell | <price>$67,373</price> | 0.144 |
+| BTC | Take Profit | Sell | <price>$69,265</price> | 0.144 |
+
+<verdict>Down $53 on the BTC long. SL and TP both in place. No margin left for new trades.</verdict>
+```
+
+## Rules
+
+- `####` heading before EVERY section per SOUL.md. Not bold, not plain text — markdown heading.
+- ALL data in tables. No exceptions. Positions, orders, balance, history — all tables.
+- Use SOUL.md HTML tags for all trading data: `<price>`, `<pnl dir="up|down">`, `<side dir="long|short">`, `<lev>`, `<pct dir="up|down">`.
+- Orders shown as a table, NOT as bullet points or prose.
+- Skip sections that have no data (e.g. no orders → skip Orders section).
+- After all tables: 1-2 sentences companion commentary wrapped in `<verdict>` tag. Never bare tables, never prose numbers.
+- Keep it concise — key fields only.
+
+### `<chart>` on TA over a held position
+
+When evaluating a held position with TA content, emit `<chart symbol={held_asset} ... />` per the technical-analysis chart emission rule. Anchor on what the trader actually holds, not a ticker mentioned in passing.
+
+## If You Notice Something
+
+Mention it naturally in the commentary — don't create a separate warnings section.
+
+- "Your BTC liq is only 5% away, by the way."
+- "Funding on that ETH long is costing you ~$8/day."
+- "Almost all your exposure is long right now."
+
+Only mention things that actually matter right now.
+
+## Tools
+
+```
+ghost_get_positions(wallet?)
+ghost_get_balance(wallet?)
+ghost_get_orders(wallet?)
+ghost_get_trade_history(symbol?, limit?)
+```