ef2c6470fb
26-source OSINT intelligence engine with live Jarvis dashboard, auto-refresh via SSE, optional LLM layer (4 providers), delta/memory system, and Telegram breaking news alerts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
187 lines
7.3 KiB
Markdown
187 lines
7.3 KiB
Markdown
# Crucix — Claude Code Project Instructions
|
|
|
|
## What This Is
|
|
|
|
Crucix is a local intelligence engine that aggregates 25 OSINT data sources in parallel and produces structured JSON. Claude's job is to synthesize that raw data into two outputs: a written intelligence briefing and a visual Jarvis-style dashboard.
|
|
|
|
## Project Layout
|
|
|
|
```
|
|
Crucix/
|
|
├── apis/
|
|
│ ├── briefing.mjs # Master orchestrator — runs all 25 sources
|
|
│ ├── BRIEFING_PROMPT.md # Intelligence synthesis protocol (READ THIS)
|
|
│ ├── BRIEFING_TEMPLATE.md # Output template for written briefings
|
|
│ └── sources/ # Individual source modules
|
|
├── dashboard/
|
|
│ ├── public/jarvis.html # Self-contained Jarvis HUD dashboard
|
|
│ └── inject.mjs # Data synthesis + injection script
|
|
├── runs/
|
|
│ └── latest.json # Most recent sweep output
|
|
└── CLAUDE.md # You are here
|
|
```
|
|
|
|
## Trigger Phrases
|
|
|
|
When the user says any of the following (or similar):
|
|
- "brief me"
|
|
- "what's going on"
|
|
- "what's the latest"
|
|
- "time for my brief"
|
|
- "what's happening in the world"
|
|
- "run a sweep"
|
|
- "update the dashboard"
|
|
|
|
Execute the **Full Briefing Flow** below.
|
|
|
|
## Full Briefing Flow
|
|
|
|
### Step 1: Run the Crucix Sweep
|
|
|
|
```bash
|
|
cd C:/Users/ishan/Documents/Crucix && node apis/briefing.mjs > runs/latest.json 2>&1
|
|
```
|
|
|
|
This runs all 25 OSINT sources in parallel (~30-60 seconds). Output goes to `runs/latest.json`. If a timestamped backup is desired:
|
|
|
|
```bash
|
|
cp runs/latest.json runs/briefing_$(date -u +%Y-%m-%dT%H-%M-%SZ).json
|
|
```
|
|
|
|
### Step 2: Gather Live Market Data
|
|
|
|
Use the Alpaca MCP tools to pull real-time context:
|
|
|
|
- **Broad indexes**: Get latest quotes/snapshots for SPY, QQQ, DIA, IWM
|
|
- **Rates proxies**: TLT, HYG, LQD
|
|
- **Commodities**: GLD, SLV, USO, UNG
|
|
- **Crypto**: BTC/USD, ETH/USD
|
|
- **VIX**: Get CBOE VIX latest
|
|
|
|
This supplements the FRED/EIA/BLS data in `latest.json` with live market prices.
|
|
|
|
### Step 3: Search for Breaking Developments
|
|
|
|
Use web search to check for breaking news in the last 6 hours:
|
|
- Geopolitical escalation or de-escalation
|
|
- Central bank actions or statements
|
|
- Major economic data releases
|
|
- Conflict developments
|
|
- Health emergencies
|
|
- Sanctions or policy shifts
|
|
|
|
### Step 4: Read the Briefing Protocol
|
|
|
|
Read `apis/BRIEFING_PROMPT.md` for the full intelligence synthesis protocol. Read `apis/BRIEFING_TEMPLATE.md` for the output structure.
|
|
|
|
Key principles:
|
|
- **Leverage first** — always lead with what the user can act on
|
|
- **Cross-correlate** — connect signals across conflict, economic, health, and market domains
|
|
- **Strong view** — form an opinion backed by evidence, not hedged filler
|
|
- **8 sections**: Leverageable Ideas → Executive Thesis → Situation Awareness → Pattern Recognition → Historical Parallels → Market Implications → Decision Board → Source Integrity
|
|
|
|
### Step 5: Write the Intelligence Briefing
|
|
|
|
Synthesize all inputs (Crucix sweep + Alpaca live data + web search) into a briefing following `BRIEFING_TEMPLATE.md`. Write it as markdown.
|
|
|
|
Save the briefing to:
|
|
```
|
|
runs/briefing_YYYY-MM-DDTHH-MM-SSZ.md
|
|
```
|
|
|
|
### Step 6: Generate the Jarvis Dashboard
|
|
|
|
After the briefing is written, update the visual dashboard:
|
|
|
|
```bash
|
|
cd C:/Users/ishan/Documents/Crucix && node dashboard/inject.mjs
|
|
```
|
|
|
|
This script:
|
|
1. Reads `runs/latest.json`
|
|
2. Fetches RSS news from BBC, NYT, Al Jazeera and geo-tags them
|
|
3. Generates signal-based Leverageable Ideas from cross-source correlation
|
|
4. Synthesizes the raw data into a compact format (~18KB)
|
|
5. Injects it into `dashboard/public/jarvis.html` replacing the data placeholder
|
|
6. Filters non-English Telegram posts (Cyrillic detection)
|
|
7. **Auto-opens the dashboard in the user's default browser**
|
|
|
|
The dashboard is a self-contained HTML file — no server needed. It opens automatically after injection.
|
|
|
|
### Step 7: Confirm to User
|
|
|
|
Tell the user:
|
|
1. Briefing is ready (share key highlights from Leverageable Ideas and Executive Thesis)
|
|
2. Dashboard has been updated and auto-opened in their browser (if they already had it open, they should refresh)
|
|
3. Note any source failures or degraded data quality
|
|
|
|
## Dashboard Architecture
|
|
|
|
The Jarvis HUD (`dashboard/public/jarvis.html`) is a single self-contained file:
|
|
- **CDN dependencies**: GSAP (animations), D3.js + topojson (world map)
|
|
- **Visual style**: Glassmorphism, cyan-on-dark, IBM Plex Mono + Space Grotesk
|
|
- **Boot sequence**: Cinematic 3-4 second reveal with spinning logo ring
|
|
- **Layout**: 3-column grid
|
|
- Left rail: Threat Mesh layers, Nuclear Watch, Risk Gauges
|
|
- Center: D3 world map with 7 marker types + region filters + lower macro grid
|
|
- Right rail: English-only OSINT stream + WHO alerts + Signal Core metrics
|
|
|
|
### Map Marker Types
|
|
- Green circles: Air traffic hotspots (OpenSky)
|
|
- Red circles: Thermal/fire detections (FIRMS)
|
|
- Cyan dots: SDR receivers in conflict zones (KiwiSDR)
|
|
- Yellow circles: Nuclear monitoring sites (Safecast)
|
|
- Purple diamonds: Maritime chokepoints
|
|
- Orange circles: OSINT events (Telegram urgent)
|
|
- Green circles (small): WHO health alerts
|
|
- Light blue broadcast icons: Geolocated world news (RSS) — click for article popup
|
|
|
|
### Region Filters
|
|
World, Americas, Europe, Middle East, Asia Pacific, Africa — with smooth D3 zoom transitions.
|
|
|
|
## Data Synthesis (inject.mjs)
|
|
|
|
The inject script maps raw `latest.json` fields to what the HTML expects:
|
|
|
|
| HTML property | Raw source | Key fields |
|
|
|---|---|---|
|
|
| `D.air` | OpenSky.hotspots | total, noCallsign, highAlt, region |
|
|
| `D.thermal` | FIRMS.hotspots | det, night, hc, fires[{lat,lon,frp}] |
|
|
| `D.chokepoints` | Maritime.chokepoints | label, note, lat, lon |
|
|
| `D.nuke` | Safecast.sites | site, anom, cpm, n |
|
|
| `D.sdr` | KiwiSDR | total, online, zones[{region,count,receivers}] |
|
|
| `D.tg` | Telegram | posts, urgent[], topPosts[] (English only) |
|
|
| `D.who` | WHO.diseaseOutbreakNews | title, date, summary |
|
|
| `D.fred` | FRED.indicators | id, value, momChange, etc. |
|
|
| `D.energy` | EIA | wti, brent, natgas, crudeStocks, wtiRecent[] |
|
|
| `D.bls` | BLS.indicators | id, value, momChange, momChangePct |
|
|
| `D.treasury` | Treasury.debt[0] | totalDebt |
|
|
| `D.gscpi` | GSCPI.latest | value, interpretation |
|
|
| `D.defense` | USAspending.recentDefenseContracts | recipient, amount, desc |
|
|
| `D.health` | All sources | name, error status |
|
|
|
|
## If Only Dashboard Update is Requested
|
|
|
|
If the user just says "update the dashboard" or "refresh the dashboard" (without wanting a full briefing):
|
|
|
|
1. Run the sweep: `node apis/briefing.mjs > runs/latest.json 2>&1`
|
|
2. Inject data: `node dashboard/inject.mjs`
|
|
3. Confirm dashboard is updated
|
|
|
|
## If Only Briefing is Requested
|
|
|
|
If the user just wants the written briefing without the dashboard:
|
|
|
|
1. Run the sweep
|
|
2. Gather Alpaca + web context
|
|
3. Read and follow BRIEFING_PROMPT.md
|
|
4. Write the briefing following BRIEFING_TEMPLATE.md
|
|
5. Share the briefing
|
|
|
|
## Source Notes
|
|
|
|
- **25 sources**: GDELT, OpenSky, FIRMS, Maritime, Safecast, ACLED, ReliefWeb, WHO, OFAC, OpenSanctions, ADS-B, FRED, Treasury, BLS, EIA, GSCPI, USAspending, Comtrade, NOAA, EPA, Patents, Bluesky, Reddit, Telegram, KiwiSDR
|
|
- Zero npm dependencies, pure ESM, Node 22+
|
|
- Some sources may return errors (ACLED rate limits, GDELT empty results) — note this in Source Integrity
|
|
- Telegram posts filtered for English (Cyrillic detection) — Russian-language posts are skipped in both briefing and dashboard
|