> **`npm run dev`이 조용히 실패하는 경우** (출력 없이 종료됨), Node를 직접 실행하세요:
> ```bash
> node --trace-warnings server.mjs
> ```
> 이 방법은 npm의 스크립트 실행기를 우회하며, 일부 시스템(특히 Windows PowerShell)에서 오류가 삼켜지는 문제를 해결합니다. 또한 `node diag.mjs`를 실행하여 정확한 문제를 진단할 수 있습니다. Node 버전 확인, 각 모듈 임포트 개별 테스트, 포트 가용성 검증을 수행합니다. 자세한 내용은 [트러블슈팅](#troubleshooting)을 참조하세요.

대시보드는 `http://localhost:3117`에서 자동으로 열리며 즉시 첫 번째 정보 수집을 시작합니다. 이 첫 번째 수집은 27개 소스를 병렬로 쿼리하며 일반적으로 30–60초가 소요됩니다. 수집이 완료되어 첫 데이터 업데이트가 푸시될 때까지 대시보드는 빈 상태로 나타납니다. 그 후에는 SSE(Server-Sent Events)를 통해 15분마다 자동으로 새로고침됩니다. 수동 페이지 새로고침이 필요하지 않습니다.

**요구사항:** Node.js 22+ (네이티브 `fetch`, 최상위 `await`, ESM 사용)

### Docker```bash
git clone https://github.com/calesthio/Crucix.git
cd Crucix
cp .env.example .env    # add your API keys
docker compose up -d

### 최상의 결과를 위해 필요 (모두 무료)

| 키 | 출처 | 획득 방법 |
|-----|--------|------------|
| `FRED_API_KEY` | 연방준비제도 경제 데이터 | [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html) — 즉시, 무료 |
| `FIRMS_MAP_KEY` | NASA FIRMS (위성 화재 데이터) | [firms.modaps.eosdis.nasa.gov](https://firms.modaps.eosdis.nasa.gov/api/area/) — 즉시, 무료 |
| `EIA_API_KEY` | 미국 에너지 정보청 | [api.eia.gov](https://www.eia.gov/opendata/register.php) — 즉시, 무료 |

이 세 가지는 가장 가치 있는 경제 및 위성 데이터에 접근할 수 있게 해줍니다. 각각 등록하는 데 약 60초 정도 소요됩니다.

### 선택 사항 (추가 소스 활성화)

| 키 | 출처 | 획득 방법 |
|-----|--------|------------|
| `ACLED_EMAIL` + `ACLED_PASSWORD` | 무력 충돌 사건 데이터 | [acleddata.com/register](https://acleddata.com/register/) — 무료, OAuth2 |
| `AISSTREAM_API_KEY` | 해양 AIS 선박 추적 | [aisstream.io](https://aisstream.io/) — 무료 |
| `ADSB_API_KEY` | 필터링 없는 항공편 추적 | [RapidAPI](https://rapidapi.com/adsbexchange/api/adsbexchange-com1) — 월 약 $10 |

### LLM 제공자 (선택 사항, AI 강화 아이디어용)

`LLM_PROVIDER`를 다음 중 하나로 설정: `anthropic`, `openai`, `gemini`, `codex`, `openrouter`, `minimax`, `mistral`, `grok`

| 제공자 | 필요한 키 | 기본 모델 |
|----------|-------------|---------------|
| `anthropic` | `LLM_API_KEY` | claude-sonnet-4-6 |
| `openai` | `LLM_API_KEY` | gpt-5.4 |
| `gemini` | `LLM_API_KEY` | gemini-3.1-pro |
| `openrouter` | `LLM_API_KEY` | openrouter/auto |
| `codex` | 없음 (`~/.codex/auth.json` 사용) | gpt-5.3-codex |
| `minimax` | `LLM_API_KEY` | MiniMax-M2.5 |
| `mistral` | `LLM_API_KEY` | mistral-large-latest |
| `grok` | `LLM_API_KEY` | grok-4-latest |

Codex의 경우, `npx @openai/codex login`을 실행하여 ChatGPT 구독을 통해 인증하세요.

### Telegram 봇 + 알림 (선택 사항)

| 키 | 획득 방법 |
|-----|------------|
| `TELEGRAM_BOT_TOKEN` | Telegram에서 [@BotFather](https://t.me/BotFather)를 통해 생성 |
| `TELEGRAM_CHAT_ID` | [@userinfobot](https://t.me/userinfobot)을 통해 획득 |
| `TELEGRAM_CHANNELS` | *(선택 사항)* 17개의 내장 채널 외에 모니터링할 추가 채널 ID (쉼표로 구분) |
| `TELEGRAM_POLL_INTERVAL` | *(선택 사항)* 봇 명령 폴링 간격 (ms 단위, 기본값: 5000) |

### Discord 봇 + 알림 (선택 사항)

| 키 | 획득 방법 |
|-----|------------|
| `DISCORD_BOT_TOKEN` | [Discord Developer Portal](https://discord.com/developers/applications) → Bot → Token에서 생성 |
| `DISCORD_CHANNEL_ID` | Discord에서 채널 우클릭 (개발자 모드 켜짐) → 채널 ID 복사 |
| `DISCORD_GUILD_ID` | *(선택 사항)* 서버 우클릭 → 서버 ID 복사. 즉시 슬래시 명령 등록 가능 (그렇지 않으면 전역 명령에 최대 1시간 소요) |
| `DISCORD_WEBHOOK_URL` | *(선택 사항)* 채널 설정 → 통합 → 웹후크 → 새 웹후크 → URL 복사. 봇 없이 알림 전용 모드로 사용 |

**Discord 봇 설정:**
1. [Discord Developer Portal](https://discord.com/developers/applications)로 이동하여 새 애플리케이션 생성
2. **Bot**으로 이동 → **Reset Token** 클릭 → 토큰을 `DISCORD_BOT_TOKEN`에 복사
3. **Privileged Gateway Intents**에서 **Message Content Intent** 활성화
4. **OAuth2** → **URL Generator**로 이동 → `bot` + `applications.commands` 범위 선택 → `Send Messages` + `Embed Links` 권한 선택
5. 생성된 URL을 복사하여 브라우저에서 열어 봇을 서버에 초대
6. 의존성 설치: `npm install discord.js`

알림은 Telegram과 Discord 모두에서 LLM 유무와 관계없이 작동합니다. LLM이 구성되면 신호 평가가 더 풍부해지고 컨텍스트를 더 잘 인식합니다. LLM이 없으면 결정론적 규칙 엔진이 심각도, 교차 도메인 상관관계 및 신호 수를 기반으로 신호를 평가합니다.

### 키 없이 사용

Crucix는 API 키 없이도 작동합니다. 18개 이상의 소스는 인증이 전혀 필요하지 않습니다. 키가 필요한 소스는 구조화된 오류를 반환하며 나머지 스윕은 정상적으로 계속됩니다.

---

## 아키텍처```
crucix/
├── server.mjs                 # Express dev server (SSE, auto-refresh, LLM, bot commands)
├── crucix.config.mjs          # Configuration with env var overrides + delta thresholds
├── diag.mjs                   # Diagnostic script — run if server fails to start
├── .env.example               # All documented env vars
├── package.json               # Runtime: express | Optional: discord.js
├── docs/                      # Screenshots for README
│
├── apis/
│   ├── briefing.mjs           # Master orchestrator — runs all 27 sources in parallel
│   ├── save-briefing.mjs      # CLI: save timestamped + latest.json
│   ├── BRIEFING_PROMPT.md     # Intelligence synthesis protocol
│   ├── BRIEFING_TEMPLATE.md   # Briefing output structure
│   ├── utils/
│   │   ├── fetch.mjs          # safeFetch() — timeout, retries, abort, auto-JSON
│   │   └── env.mjs            # .env loader (no dotenv dependency)
│   └── sources/               # 27 self-contained source modules
│       ├── gdelt.mjs          # Each exports briefing() → structured data
│       ├── fred.mjs           # Can run standalone: node apis/sources/fred.mjs
│       ├── space.mjs          # CelesTrak satellite tracking
│       ├── yfinance.mjs       # Yahoo Finance — free live market data
│       └── ...                # 23 more
│
├── dashboard/
│   ├── inject.mjs             # Data synthesis + standalone HTML injection
│   └── public/
│       └── jarvis.html        # Self-contained Jarvis HUD
│
├── lib/
│   ├── llm/                   # LLM abstraction (8 providers, raw fetch, no SDKs)
│   │   ├── provider.mjs       # Base class
│   │   ├── anthropic.mjs      # Claude
│   │   ├── openai.mjs         # GPT
│   │   ├── gemini.mjs         # Gemini
│   │   ├── grok.mjs           # Grok
│   │   ├── openrouter.mjs     # OpenRouter (Unified API)
│   │   ├── codex.mjs          # Codex (ChatGPT subscription)
│   │   ├── minimax.mjs        # MiniMax (M2.5, 204K context)
│   │   ├── mistral.mjs        # Mistral AI
│   │   ├── ideas.mjs          # LLM-powered trade idea generation
│   │   └── index.mjs          # Factory: createLLMProvider()
│   ├── delta/                 # Change tracking between sweeps
│   │   ├── engine.mjs         # Delta computation — semantic dedup, configurable thresholds, severity scoring
│   │   ├── memory.mjs         # Hot memory (3 runs, atomic writes) + cold storage (daily archives)
│   │   └── index.mjs          # Re-exports
│   └── alerts/
│       ├── telegram.mjs       # Multi-tier alerts (FLASH/PRIORITY/ROUTINE) + two-way bot commands
│       └── discord.mjs        # Discord bot (slash commands, rich embeds) + webhook fallback
│
└── runs/                      # Runtime data (gitignored)
    ├── latest.json            # Most recent sweep output
    └── memory/                # Delta memory (hot.json + cold/YYYY-MM-DD.json)

이는 `npm run dev`와 기능적으로 동일하지만 전체 오류 출력을 제공합니다.

**2. 진단 스크립트 실행:**```bash
node diag.mjs

### ⚠️ 면책 조항
| ⚠️ 면책 조항 |
|-------------|
| 이 프로젝트는 교육, 윤리적 해킹, 보안 연구 목적으로 코드와 예제를 논의하고 제공합니다. 여기에는 패스워드 크래킹, 네트워크 보안 테스트, 취약점 평가 등과 관련된 기능이 포함됩니다. |
| |
| **이러한 도구와 기법은 책임감 있게, 그리고 승인된 환경에서만 사용해야 합니다.** 예를 들어 본인이 소유하거나 테스트 권한을 명시적으로 허가받은 시스템에서만 사용해야 합니다. 이러한 도구를 무단으로 사용하는 것은 불법이며 현지, 국가 및 국제법을 위반할 수 있습니다. |
| |
| 저자는 이 코드의 오용이나 불법적인 사용으로 인해 발생하는 손해, 법적 문제 또는 결과에 대해 **책임을 지지 않습니다**. |
| |
| 이 내용을 읽었다면 계속하기 전에 저장소 루트에 있는 **DISCLAIMER.md** 파일을 반드시 읽고 동의해야 합니다. |```bash
# macOS / Linux
lsof -ti:3117 | xargs kill

Crucix는 Node.js 22 이상이 필요합니다. 이전 버전을 사용 중이라면 [nodejs.org](https://nodejs.org/)에서 최신 LTS를 다운로드하세요.

### 대시보드가 처음 시작 후 빈 패널을 표시합니다

이는 정상입니다 — 첫 번째 스윕이 27개 소스를 모두 쿼리하는 데 30~60초가 소요됩니다. 스윕이 완료되면 대시보드가 자동으로 채워집니다. 터미널에서 스윕 진행 로그를 확인하세요.

### 일부 소스에서 오류가 표시됩니다

예상된 동작입니다. API 키가 필요한 소스는 키가 설정되지 않은 경우 구조화된 오류를 반환합니다. 나머지 스윕은 정상적으로 계속됩니다. 대시보드의 소스 무결성 섹션(또는 서버 로그)에서 어떤 소스가 실패했고 그 이유를 확인하세요. 추가할 가장 영향력 있는 무료 키 3개는 `FRED_API_KEY`, `FIRMS_MAP_KEY`, `EIA_API_KEY`입니다.

OpenSky는 공용 핫스팟이 너무 공격적으로 쿼리될 때 `HTTP 429`를 반환할 수도 있습니다. Crucix는 해당 제한을 회피하려고 시도하지 않습니다. 대신, 소스 상태에서 스로틀/오류를 표시하고 `runs/`에서 가장 최근의 비어 있지 않은 항공 교통 스냅샷을 보존하여 스로틀된 스윕에서 대시보드 비행 레이어가 갑자기 비어 있지 않도록 합니다.

### Telegram 봇이 명령에 응답하지 않습니다

`.env`에 `TELEGRAM_BOT_TOKEN`과 `TELEGRAM_CHAT_ID`가 모두 설정되어 있는지 확인하세요. 봇은 구성된 채팅 ID의 메시지에만 응답합니다(보안 조치). 시작 시 서버 로그에 `[Crucix] Telegram alerts enabled`와 `[Crucix] Bot command polling started`가 표시되어야 합니다. 그렇지 않으면 `curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe`로 토큰을 다시 확인하세요.

### Discord 봇이 슬래시 명령에 응답하지 않습니다

다음 순서로 확인하세요:
1. `.env`에 `DISCORD_BOT_TOKEN`과 `DISCORD_CHANNEL_ID`가 설정되어 있는지 확인하세요
2. `discord.js`가 설치되었는지 확인하세요: `npm ls discord.js`. 없으면 `npm install discord.js`를 실행하세요
3. 슬래시 명령이 나타나지 않으면 `DISCORD_GUILD_ID`를 설정하세요 — 설정하지 않으면 전역 명령이 전파되는 데 최대 1시간이 걸릴 수 있습니다. 길드별 명령은 즉시 등록됩니다.
4. 봇이 `bot` + `applications.commands` 범위로 초대되었고 대상 채널에서 `Send Messages` + `Embed Links` 권한이 있는지 확인하세요
5. 시작 시 서버 로그에서 `[Discord] Bot logged in as ...`를 확인하세요. `[Discord] discord.js not installed`가 보이면 설치하고 다시 시작하세요.
6. **Webhook 전용 대체:** 슬래시 명령 없이 알림만 원하면 봇 토큰 대신 `DISCORD_WEBHOOK_URL`을 설정하세요. `discord.js`가 필요하지 않습니다.

---

## 스크린샷

`docs/` 폴더에는 이 README에서 참조하는 대시보드 스크린샷이 포함되어 있습니다:

| 파일 | 설명 |
|------|------|
| `docs/dashboard.png` | 전체 대시보드 — 이 README 상단의 히어로 이미지 |
| `docs/boot.png` | 영화 같은 부트 시퀀스 애니메이션 |
| `docs/map.png` | 마커 유형과 비행 호가 포함된 D3 세계 지도 |
| `docs/globe.png` | 대기광과 마커가 있는 3D WebGL 지구본 보기 |

업데이트하려면: 대시보드를 실행하고 스윕이 완료될 때까지 기다린 다음 브라우저의 DevTools(`F12` → `Ctrl+Shift+P` → "전체 크기 스크린샷 캡처") 또는 [LICEcap](https://www.cockos.com/licecap/) 같은 도구를 사용하여 GIF를 만드세요.

---

## 기여하기

버그를 발견하셨나요? 28번째 소스를 추가하고 싶으신가요? PR을 환영합니다. 각 소스는 `apis/sources/`의 독립 모듈입니다 — 구조화된 데이터를 반환하는 `briefing()` 함수를 내보내고 `apis/briefing.mjs`의 오케스트레이터에 추가하기만 하면 됩니다.

유용하게 사용하셨다면, 별표를 눌러 다른 사람들도 찾을 수 있게 도와주세요.

기여 지침, 리뷰 기준 및 소스 추가 규칙은 `CONTRIBUTING.md`를 참조하세요. 보안 보고는 `SECURITY.md`를 참조하세요.

## 연락처

파트너십, 통합 또는 기타 이슈가 아닌 문의 사항은 `[email protected]`으로 연락해 주세요.

버그 및 기능 요청은 GitHub Issues를 사용해 주세요. 그래야 논의가 투명하고 실행 가능하게 유지됩니다.

---

## 별표 기록

<a href="https://www.star-history.com/?repos=calesthio%2FCrucix&type=date&legend=top-left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=calesthio/Crucix&type=date&theme=dark&legend=top-left" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=calesthio/Crucix&type=date&legend=top-left" />
    <img alt="별표 기록 차트" src="https://assets.kitploit.com/production/public/readmes/placeholders/f0fc86cfe65f76d40e15aaec61704ec8220a56dc89d4be03c46f67cb31b9fa8c.svg" />
  </picture>
</a>

---

## 라이선스

AGPL-3.0