> **`npm run dev` が黙って失敗する場合**（出力なしで終了する場合）は、代わりに Node を直接実行してください：
> ```bash
> node --trace-warnings server.mjs
> ```
> これにより、一部のシステム（特に Windows の PowerShell）でエラーを飲み込む可能性がある npm のスクリプトランナーを回避できます。正確な問題を診断するには `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` | Federal Reserve Economic Data | [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` | US Energy Information Administration | [api.eia.gov](https://www.eia.gov/opendata/register.php) — 即時、無料 |

この3つで、最も価値の高い経済・衛星データを利用できます。それぞれ登録に約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` | *(任意)* ボットコマンドのポーリング間隔（ミリ秒、デフォルト: 5000） |

### Discord ボット＋アラート（任意）

| キー | 入手方法 |
|-----|------------|
| `DISCORD_BOT_TOKEN` | [Discord Developer Portal](https://discord.com/developers/applications) → Bot → Token で作成 |
| `DISCORD_CHANNEL_ID` | Discord でチャンネルを右クリック（開発者モードON）→ チャンネルIDをコピー |
| `DISCORD_GUILD_ID` | *(任意)* サーバーを右クリック → サーバーIDをコピー。スラッシュコマンドを即時登録できます（それ以外はグローバルコマンドで最大1時間かかります） |
| `DISCORD_WEBHOOK_URL` | *(任意)* チャンネル設定 → 連携 → Webhooks → New Webhook → 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

Please provide the Markdown content to translate.```bash
# macOS / Linux
lsof -ti:3117 | xargs kill

Crucix には Node.js 22 以降が必要です。古いバージョンをお使いの場合は、[nodejs.org](https://nodejs.org/) から最新の LTS をダウンロードしてください。

### 初回起動後にダッシュボードのパネルが空になる

これは正常です — 最初のスイープは全 27 ソースへのクエリに 30〜60 秒かかります。スイープが完了すると、ダッシュボードには自動的にデータが表示されます。スイープの進行ログはターミナルで確認してください。

### 一部のソースでエラーが表示される

これは想定された動作です。API キーが必要なソースは、キーが設定されていない場合に構造化エラーを返します。残りのスイープは通常どおり続行されます。ダッシュボードの Source Integrity セクション(またはサーバーログ)で、どのソースが失敗したか、その理由を確認してください。追加すべき最も影響力のある無料キーは、`FRED_API_KEY`、`FIRMS_MAP_KEY`、`EIA_API_KEY` の 3 つです。

OpenSky は、パブリックホットスポットへのクエリが過剰に行われると `HTTP 429` を返すこともあります。Crucix はその制限を回避しようとはしません。代わりに、ソースの健全性にスロットル/エラーを表示し、スロットルがかかったスイープでもダッシュボードのフライトレイヤーが突然空白にならないよう、`runs/` 内の最新の空でない航空交通スナップショットを保持します。

### Telegram ボットがコマンドに応答しない

`TELEGRAM_BOT_TOKEN` と `TELEGRAM_CHAT_ID` の両方が `.env` に設定されていることを確認してください。ボットは設定されたチャット ID からのメッセージにのみ応答します(セキュリティ対策)。起動時にサーバーログで `[Crucix] Telegram alerts enabled` と `[Crucix] Bot command polling started` が表示されるはずです。表示されない場合は、`curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe` でトークンを再確認してください。

### Discord ボットがスラッシュコマンドに応答しない

以下を順番に確認してください:
1. `DISCORD_BOT_TOKEN` と `DISCORD_CHANNEL_ID` が `.env` に設定されていることを確認してください
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` → "Capture full size screenshot")または GIF 用の [LICEcap](https://www.cockos.com/licecap/) などのツールを使用してください。

---

## コントリビューション

バグを発見しましたか? 28 番目のソースを追加したいですか? PR 歓迎です。各ソースは `apis/sources/` 内の独立したモジュールです — 構造化データを返す `briefing()` 関数をエクスポートし、`apis/briefing.mjs` のオーケストレーターに追加するだけです。

これが役に立つと思ったら、スターを付けてもらえると他の人も見つけやすくなります。

コントリビューションガイドライン、レビューの期待値、ソース追加のルールについては、`CONTRIBUTING.md` を参照してください。セキュリティ報告については、`SECURITY.md` を参照してください。

## 連絡先

パートナーシップ、統合、その他の issue 以外のお問い合わせは、`[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="Star History Chart" src="https://assets.kitploit.com/production/public/readmes/41561/7cd00fa07216305d19bb2b6ece0de2b2dd36eeb2786d065aef0359159e4598a8/43d9ce4f0049392bf903058716bccb8009e9bdf415dc7e9e892487d4c1f75365-display-v1.webp" />
  </picture>
</a>

---

## ライセンス

AGPL-3.0