@mcptoolshop/registry-stats 1.2.4 → 2.1.0

package/README.it.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <strong>Italiano</strong> | <a href="README.pt-BR.md">Português</a>
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.md">English</a> | <a href="README.pt-BR.md">Português (BR)</a>
 </p>
 
 <p align="center">
@@ -7,31 +7,69 @@
 </p>
 
 <p align="center">
-  One command. Five registries. All your download stats.
+  Five registries. One engine. Dashboard included.
 </p>
 
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
   <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
+  <a href="https://mcp-tool-shop-org.github.io/registry-stats/dashboard/"><img src="https://img.shields.io/badge/Dashboard-live-green" alt="Dashboard"></a>
   <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
 
 <p align="center">
-  <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
+  <a href="#dashboard">Dashboard</a> &middot;
+  <a href="#desktop-app">Desktop App</a> &middot;
   <a href="#install">Install</a> &middot;
   <a href="#cli">CLI</a> &middot;
-  <a href="#config-file">Config</a> &middot;
   <a href="#programmatic-api">API</a> &middot;
   <a href="#rest-api-server">REST Server</a> &middot;
+  <a href="#config-file">Config</a> &middot;
   <a href="#license">License</a>
 </p>
 
 ---
 
-Se pubblicate su npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, attualmente avete bisogno di cinque API diverse per rispondere alla domanda "quanti download ho avuto questo mese?". Questa libreria vi offre un'unica interfaccia per tutte, sia come interfaccia a riga di comando (CLI) che come API programmatica.
+Pubblica su npm, PyPI, NuGet, il Marketplace di VS Code e Docker Hub. Attualmente, rispondere alla domanda "come stanno andando i miei pacchetti?" significa controllare cinque siti diversi. **registry-stats** è la piattaforma completa: un motore TypeScript (CLI + API + server REST), una dashboard web interattiva e un'applicazione desktop nativa per Windows, il tutto proveniente da un unico repository.
+
+Nessuna dipendenza a runtime. Utilizza la funzione nativa `fetch()`. Node 18 o superiore.
+
+## Cosa c'è all'interno
+
+| Livello | Cosa fa |
+|-------|-------------|
+| **Engine** | Libreria TypeScript + CLI + server REST. Interroga cinque registri con un'unica interfaccia. Pubblicato su npm come `@mcptoolshop/registry-stats`. |
+| **Dashboard** | Applicazione web basata su Astro. Assistente chat AI, sei grafici interattivi, motore di crescita intelligente e guida con schede. Ricostruita settimanalmente tramite CI. |
+| **Desktop** | Applicazione nativa per Windows realizzata con WinUI 3 + WebView2. Include la dashboard offline e scarica le statistiche in tempo reale su richiesta. |
+
+## Dashboard
+
+Una dashboard con aggiornamenti automatici è disponibile all'indirizzo [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
 
-Nessuna dipendenza. Utilizza la funzione nativa `fetch()`. Node 18 o superiore.
+- **Interfaccia a schede** — Schede Home, Analytics, Leaderboard e Help
+- **Assistente chat AI** — Registry Assistant alimentato da Ollama con contesto RAG, risposte in streaming, selettore di modelli e memoria della conversazione
+- **Riepilogo esecutivo** — punteggio di salute (0–100), indice di diversità, variazione settimanale, download totali da tutti i registri
+- **Sei grafici interattivi** — tendenza a 30 giorni (vista aggregata / per registro / top 5), quota del registro (area polare), rischio del portafoglio (istogramma + Gini & P90), top 10 momentum, tracker della velocità con sparkline e mappa termica a 30 giorni con rilevamento picchi (>2σ)
+- **Motore di crescita intelligente** — gestisce la distorsione dei piccoli denominatori con soglia di base, limite percentuale e formula di velocità smorzata
+- **Insight azionabili** — raccomandazioni auto-generate e avvisi di attenzione per i pacchetti in calo
+- **Classifica** — tutti i pacchetti classificati per download settimanali con sparkline a 30 giorni e badge di tendenza intelligenti
+- **Pagina di configurazione** — editor del portafoglio con validazione, sezione registry-sync e panoramica della pipeline
+- **Scheda di aiuto** — guida intuitiva che copre ogni scheda, concetti chiave, suggerimenti per l'assistente AI, pipeline dei dati e link utili
+- **Tema chiaro/scuro** — segue le preferenze del sistema
+
+I dati vengono scaricati al momento della compilazione e la dashboard viene ricostruita settimanalmente tramite CI (il lunedì alle 06:00 UTC). Configura i pacchetti da monitorare in `site/src/data/packages.json`.
+
+## Applicazione Desktop
+
+Un'applicazione nativa per Windows che integra la dashboard in un ambiente WebView2 locale:
+
+- **Funziona offline** — include file HTML/CSS/JS; funziona senza connessione a Internet.
+- **Aggiornamento in tempo reale** — scarica `stats.json` da GitHub Pages su richiesta.
+- **Esportazione CSV** — esporta i dati della classifica con un solo clic.
+- **Pacchetto MSIX** — creato e firmato tramite CI utilizzando `desktop-ci.yml`.
+
+Il codice sorgente dell'applicazione desktop si trova nella cartella `desktop/`. Realizzata con .NET 10 MAUI e destinata a WinUI 3.
 
 ## Installazione
 
@@ -52,10 +90,6 @@ registry-stats express
 
 # Time series with monthly breakdown + trend
 registry-stats express -r npm --range 2025-01-01:2025-06-30
-#  2025-01  142,359,021
-#  2025-02  147,522,528
-#  ...
-#  Total: 448,383,383  Avg/day: 4,982,038  Trend: flat (-0.46%)
 
 # Raw JSON output
 registry-stats express -r npm --json
@@ -74,14 +108,6 @@ registry-stats
 
 # Compare across registries
 registry-stats express --compare
-#  express — comparison
-#
-#  Metric        npm         pypi
-#  ─────────────────────────────────
-#  Total         -           -
-#  Month         283,472     47,201
-#  Week          67,367      11,800
-#  Day           11,566      1,686
 
 # Export as CSV or chart-friendly JSON
 registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -161,7 +187,6 @@ calc.toChartData(daily, 'express');        // { labels: [...], datasets: [{ labe
 
 // Comparison — same package across registries
 const comparison = await stats.compare('express');
-// → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
 await stats.compare('express', ['npm', 'pypi']);  // specific registries only
 
 // Caching (5 min TTL, in-memory)
@@ -173,7 +198,7 @@ await stats('npm', 'express', { cache });  // cache hit
 ## Supporto per i registri
 
 | Registro | Formato del pacchetto | Serie temporali | Dati disponibili |
-| ---------- | --------------- | ------------- | ---------------- |
+|----------|---------------|-------------|----------------|
 | `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | giorno precedente, settimana precedente, mese precedente |
 | `pypi` | `requests` | Sì (180 giorni) | giorno precedente, settimana precedente, mese precedente, totale |
 | `nuget` | `Newtonsoft.Json` | No | totale |
@@ -192,7 +217,6 @@ await stats('npm', 'express', { cache });  // cache hit
 Eseguite come microservizio o integrate nel vostro server:
 
 ```bash
-# CLI
 registry-stats serve --port 3000
 ```
 
@@ -240,13 +264,53 @@ registerProvider(cargo);
 await stats('cargo', 'serde');
 ```
 
-## Sito web
+## Struttura del Repository
+
+```
+registry-stats/
+├── src/        # TypeScript engine (published to npm)
+├── site/       # Astro dashboard + landing page (deployed to GitHub Pages)
+├── desktop/    # WinUI 3 desktop app (.NET 10 MAUI)
+└── test/       # Library tests (vitest)
+```
+
+## Sviluppo
+
+```bash
+# Engine
+npm install && npm run build && npm test
+
+# Dashboard (dev server)
+npm run site:dev
+
+# Dashboard (production build)
+npm run site:build
+```
+
+## Sicurezza e ambito dei dati
+
+| Aspetto | Dettaglio |
+|--------|--------|
+| **Data touched** | Statistiche di download pubbliche da npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache in memoria (opzionale). |
+| **Data NOT touched** | Nessuna telemetria. Nessuna analisi. Nessun archivio di credenziali. Nessun dato utente. Nessuna scrittura di file. |
+| **Permissions** | Lettura: API pubbliche dei registri tramite HTTPS. Scrittura: solo stdout/stderr. |
+| **Network** | Uscite HTTPS verso le API pubbliche dei registri. Server REST locale opzionale. |
+| **Telemetry** | Nessuno raccolto o inviato. |
+
+Consulta [SECURITY.md](SECURITY.md) per la segnalazione di vulnerabilità.
+
+## Tabella di valutazione
 
-Il sito web e la documentazione si trovano nella directory `site/`.
+| Categoria | Punteggio |
+|----------|-------|
+| A. Sicurezza | 10 |
+| B. Gestione degli errori | 10 |
+| C. Documentazione per gli operatori | 10 |
+| D. Igiene della distribuzione | 10 |
+| E. Identità (soft) | 10 |
+| **Overall** | **50/50** |
 
-- Sviluppo: `npm run site:dev`
-- Build: `npm run site:build`
-- Anteprima: `npm run site:preview`
+> Analisi completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
 
 ## Licenza
 

package/README.ja.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="README.md">English</a> | <strong>日本語</strong> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
 </p>
 
 <p align="center">
@@ -7,31 +7,69 @@
 </p>
 
 <p align="center">
-  One command. Five registries. All your download stats.
+  Five registries. One engine. Dashboard included.
 </p>
 
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
   <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
+  <a href="https://mcp-tool-shop-org.github.io/registry-stats/dashboard/"><img src="https://img.shields.io/badge/Dashboard-live-green" alt="Dashboard"></a>
   <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
 
 <p align="center">
-  <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
+  <a href="#dashboard">Dashboard</a> &middot;
+  <a href="#desktop-app">Desktop App</a> &middot;
   <a href="#install">Install</a> &middot;
   <a href="#cli">CLI</a> &middot;
-  <a href="#config-file">Config</a> &middot;
   <a href="#programmatic-api">API</a> &middot;
   <a href="#rest-api-server">REST Server</a> &middot;
+  <a href="#config-file">Config</a> &middot;
   <a href="#license">License</a>
 </p>
 
 ---
 
-もし、npm、PyPI、NuGet、VS Code Marketplace、またはDocker Hubに公開している場合、現在、"今月ダウンロード数は何件ですか？"という質問に答えるために、5つの異なるAPIが必要になります。このライブラリは、それらすべてに対して、CLIまたはプログラムAPIとして、単一のインターフェースを提供します。
+npm、PyPI、NuGet、Visual Studio Code Marketplace、Docker Hub などのプラットフォームに公開できます。現在、「私のパッケージの状況はどうなっているか？」を知るには、5つの異なるサイトを確認する必要があります。**registry-stats** は、それらを統合したプラットフォームです。TypeScript で構築されたエンジン（CLI + API + REST サーバー）、リアルタイムの Web ダッシュボード、そしてネイティブの Windows デスクトップ アプリケーション。これらはすべて、1つのリポジトリから提供されます。
+
+実行時の依存関係はありません。ネイティブの `fetch()` を使用します。Node 18 以降が必要です。
+
+## 構成要素
+
+| レイヤー | 機能 |
+|-------|-------------|
+| **Engine** | TypeScript ライブラリ + CLI + REST サーバー。1つのインターフェースで、5つのレジストリをクエリできます。npm で `@mcptoolshop/registry-stats` として公開されています。 |
+| **Dashboard** | Astro で構築された Web アプリケーション。AI チャットアシスタント、6つのインタラクティブチャート、スマート成長エンジン、タブ付きヘルプガイド。毎週、CI によって再構築されます。 |
+| **Desktop** | WinUI 3 + WebView2 を使用したネイティブ Windows アプリケーション。ダッシュボードをオフラインで利用できるようにバンドルし、必要に応じてリアルタイムの統計情報を取得します。 |
+
+## ダッシュボード
+
+自己更新型の統計ダッシュボードは、[`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/) にあります。
 
-依存関係はゼロです。ネイティブの`fetch()`を使用します。Node 18以降が必要です。
+- **タブインターフェース** — Home、Analytics、Leaderboard、Help タブ
+- **AI チャットアシスタント** — Ollama を使用した Registry Assistant。RAG コンテキスト注入、ストリーミング応答、モデルセレクター、会話メモリ
+- **エグゼクティブスナップショット** — ヘルススコア（0–100）、多様性インデックス、週次変動、全レジストリの合計ダウンロード数
+- **6つのインタラクティブチャート** — 30日トレンド（合計 / レジストリ別 / トップ5切り替え）、レジストリシェア（ポーラーエリア）、ポートフォリオリスク（分布ヒストグラム + Gini & P90）、トップ10モメンタム、スパークライン付きベロシティトラッカー、30日ヒートマップ（スパイク検出 >2σ）
+- **スマート成長エンジン** — 小さな分母の歪みを処理。ベースライン閾値、パーセンテージキャップ、減衰ベロシティ式
+- **アクション可能なインサイト** — 自動生成された推奨事項と減少パッケージの注意アラート
+- **ランキング** — 全パッケージを週次ダウンロード数でランク付け、30日スパークラインとスマートトレンドバッジ付き
+- **セットアップページ** — ポートフォリオエディター、バリデーション、registry-sync コンパニオンセクション、パイプライン概要
+- **ヘルプタブ** — 各タブ、キーコンセプト、AI アシスタントの使い方、データパイプライン、便利なリンクをカバーする人間に優しいガイド
+- **テーマ** — システム設定に従って、ダークモードまたはライトモードを切り替え。
+
+データはビルド時に取得され、毎週 CI によって再構築されます（月曜日 06:00 UTC）。追跡するパッケージは、`site/src/data/packages.json` で設定します。
+
+## デスクトップ アプリケーション
+
+ダッシュボードをローカルの WebView2 シェルでラップした、ネイティブの Windows アプリケーションです。
+
+- **オフライン対応**：HTML/CSS/JS がバンドルされているため、インターネット接続なしで動作します。
+- **リアルタイム更新**：GitHub Pages から `stats.json` をオンデマンドで取得します。
+- **CSV エクスポート**：ランキングデータをワンクリックで CSV 形式でエクスポートできます。
+- **MSIX パッケージ**：CI で `desktop-ci.yml` を使用してビルドおよび署名されます。
+
+デスクトップアプリケーションのソースコードは、`desktop/` にあります。 .NET 10 MAUI を使用して、WinUI 3 をターゲットに構築されています。
 
 ## インストール
 
@@ -52,10 +90,6 @@ registry-stats express
 
 # Time series with monthly breakdown + trend
 registry-stats express -r npm --range 2025-01-01:2025-06-30
-#  2025-01  142,359,021
-#  2025-02  147,522,528
-#  ...
-#  Total: 448,383,383  Avg/day: 4,982,038  Trend: flat (-0.46%)
 
 # Raw JSON output
 registry-stats express -r npm --json
@@ -74,14 +108,6 @@ registry-stats
 
 # Compare across registries
 registry-stats express --compare
-#  express — comparison
-#
-#  Metric        npm         pypi
-#  ─────────────────────────────────
-#  Total         -           -
-#  Month         283,472     47,201
-#  Week          67,367      11,800
-#  Day           11,566      1,686
 
 # Export as CSV or chart-friendly JSON
 registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -161,7 +187,6 @@ calc.toChartData(daily, 'express');        // { labels: [...], datasets: [{ labe
 
 // Comparison — same package across registries
 const comparison = await stats.compare('express');
-// → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
 await stats.compare('express', ['npm', 'pypi']);  // specific registries only
 
 // Caching (5 min TTL, in-memory)
@@ -173,7 +198,7 @@ await stats('npm', 'express', { cache });  // cache hit
 ## レジストリのサポート
 
 | レジストリ | パッケージ形式 | 時系列データ | 利用可能なデータ |
-| ---------- | --------------- | ------------- | ---------------- |
+|----------|---------------|-------------|----------------|
 | `npm` | `express`, `@scope/pkg` | はい (549日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月) |
 | `pypi` | `requests` | はい (180日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月), total (合計) |
 | `nuget` | `Newtonsoft.Json` | No | total (合計) |
@@ -192,7 +217,6 @@ await stats('npm', 'express', { cache });  // cache hit
 マイクロサービスとして実行するか、独自のサーバーに組み込むことができます。
 
 ```bash
-# CLI
 registry-stats serve --port 3000
 ```
 
@@ -240,13 +264,53 @@ registerProvider(cargo);
 await stats('cargo', 'serde');
 ```
 
-## ウェブサイト
+## リポジトリの構成
+
+```
+registry-stats/
+├── src/        # TypeScript engine (published to npm)
+├── site/       # Astro dashboard + landing page (deployed to GitHub Pages)
+├── desktop/    # WinUI 3 desktop app (.NET 10 MAUI)
+└── test/       # Library tests (vitest)
+```
+
+## 開発
+
+```bash
+# Engine
+npm install && npm run build && npm test
+
+# Dashboard (dev server)
+npm run site:dev
+
+# Dashboard (production build)
+npm run site:build
+```
+
+## セキュリティとデータ範囲
+
+| 側面 | 詳細 |
+|--------|--------|
+| **Data touched** | npm、PyPI、NuGet、Visual Studio Code Marketplace、Docker Hub から取得する公開ダウンロード統計。オプションで、メモリ内キャッシュを使用します。 |
+| **Data NOT touched** | テレメトリー、分析、認証情報の保存、ユーザーデータ、ファイル書き込みは一切行いません。 |
+| **Permissions** | 読み込み：HTTPS を使用した公開レジストリ API。書き込み：標準出力/標準エラー出力のみ。 |
+| **Network** | HTTPS を使用して公開レジストリ API にアクセスします。オプションで、ローカルの REST サーバーを使用します。 |
+| **Telemetry** | 収集または送信されるデータはありません。 |
+
+脆弱性に関する報告については、[SECURITY.md](SECURITY.md) を参照してください。
+
+## スコアカード
 
-ドキュメント/ランディングページは`site/`にあります。
+| カテゴリ | スコア |
+|----------|-------|
+| A. セキュリティ | 10 |
+| B. エラー処理 | 10 |
+| C. 運用ドキュメント | 10 |
+| D. ソフトウェアの品質 | 10 |
+| E. 識別情報（重要度：低） | 10 |
+| **Overall** | **50/50** |
 
-- 開発: `npm run site:dev`
-- ビルド: `npm run site:build`
-- プレビュー: `npm run site:preview`
+詳細な監査：[SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
 
 ## ライセンス
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <strong>English</strong> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
 </p>
 
 <p align="center">
@@ -7,32 +7,69 @@
 </p>
 
 <p align="center">
-  One command. Five registries. All your download stats.
+  Five registries. One engine. Dashboard included.
 </p>
 
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
   <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
+  <a href="https://mcp-tool-shop-org.github.io/registry-stats/dashboard/"><img src="https://img.shields.io/badge/Dashboard-live-green" alt="Dashboard"></a>
   <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
 
 <p align="center">
-  <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
+  <a href="#dashboard">Dashboard</a> &middot;
+  <a href="#desktop-app">Desktop App</a> &middot;
   <a href="#install">Install</a> &middot;
   <a href="#cli">CLI</a> &middot;
-  <a href="#config-file">Config</a> &middot;
   <a href="#programmatic-api">API</a> &middot;
   <a href="#rest-api-server">REST Server</a> &middot;
-  <a href="#dashboard">Dashboard</a> &middot;
+  <a href="#config-file">Config</a> &middot;
   <a href="#license">License</a>
 </p>
 
 ---
 
-If you publish to npm, PyPI, NuGet, VS Code Marketplace, or Docker Hub, you currently need five different APIs to answer "how many downloads did I get this month?" This library gives you one interface for all of them — as a CLI or programmatic API.
+You publish to npm, PyPI, NuGet, the VS Code Marketplace, and Docker Hub. Right now, answering "how are my packages doing?" means checking five different sites. **registry-stats** is the complete platform: a TypeScript engine (CLI + API + REST server), a live web dashboard, and a native Windows desktop app — all from one repo.
+
+Zero runtime dependencies. Uses native `fetch()`. Node 18+.
+
+## What's inside
+
+| Layer | What it does |
+|-------|-------------|
+| **Engine** | TypeScript library + CLI + REST server. Query five registries with one interface. Published to npm as `@mcptoolshop/registry-stats`. |
+| **Dashboard** | Astro-powered web app with AI chat assistant, six interactive charts, smart growth engine, and tabbed Help guide. Rebuilt weekly by CI. |
+| **Desktop** | WinUI 3 + WebView2 native Windows app. Bundles the dashboard offline, fetches live stats on demand. |
+
+## Dashboard
+
+A self-updating stats dashboard lives at [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
+
+- **Tabbed interface** — Home, Analytics, Leaderboard, and Help tabs
+- **AI chat assistant** — Ollama-powered Registry Assistant with RAG context, streaming responses, model selector, and conversation memory
+- **Executive snapshot** — health score (0–100), diversity index, weekly change, total downloads across all registries
+- **Six interactive charts** — 30-day trend (aggregate / per-registry / top-5 toggles), registry share (polar area), portfolio risk (histogram + Gini & P90), top-10 momentum, velocity tracker with sparklines, and 30-day heatmap with spike detection (>2σ)
+- **Smart growth engine** — handles small-denominator distortion with baseline threshold, percentage cap, and damped velocity formula
+- **Actionable insights** — auto-generated recommendations and attention alerts for declining packages
+- **Leaderboard** — all packages ranked by weekly downloads with inline 30-day sparklines and smart trend badges
+- **Setup page** — portfolio editor with validation, registry-sync companion section, and pipeline overview
+- **Help tab** — human-friendly guide covering every tab, key concepts, AI assistant tips, data pipeline, and useful links
+- **Dark / light theme** — follows system preference
 
-Zero dependencies. Uses native `fetch()`. Node 18+.
+Data is fetched at build time and rebuilt weekly by CI (Mondays 06:00 UTC). Configure tracked packages in `site/src/data/packages.json`.
+
+## Desktop App
+
+A native Windows app that wraps the dashboard in a local WebView2 shell:
+
+- **Offline-capable** — ships bundled HTML/CSS/JS; works without internet
+- **Live refresh** — fetches `stats.json` from GitHub Pages on demand
+- **CSV export** — export leaderboard data with one click
+- **MSIX packaged** — built and signed in CI via `desktop-ci.yml`
+
+The desktop source lives in `desktop/`. Built with .NET 10 MAUI targeting WinUI 3.
 
 ## Install
 
@@ -53,10 +90,6 @@ registry-stats express
 
 # Time series with monthly breakdown + trend
 registry-stats express -r npm --range 2025-01-01:2025-06-30
-#  2025-01  142,359,021
-#  2025-02  147,522,528
-#  ...
-#  Total: 448,383,383  Avg/day: 4,982,038  Trend: flat (-0.46%)
 
 # Raw JSON output
 registry-stats express -r npm --json
@@ -75,14 +108,6 @@ registry-stats
 
 # Compare across registries
 registry-stats express --compare
-#  express — comparison
-#
-#  Metric        npm         pypi
-#  ─────────────────────────────────
-#  Total         -           -
-#  Month         283,472     47,201
-#  Week          67,367      11,800
-#  Day           11,566      1,686
 
 # Export as CSV or chart-friendly JSON
 registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -162,7 +187,6 @@ calc.toChartData(daily, 'express');        // { labels: [...], datasets: [{ labe
 
 // Comparison — same package across registries
 const comparison = await stats.compare('express');
-// → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
 await stats.compare('express', ['npm', 'pypi']);  // specific registries only
 
 // Caching (5 min TTL, in-memory)
@@ -193,7 +217,6 @@ await stats('npm', 'express', { cache });  // cache hit
 Run as a microservice or embed in your own server:
 
 ```bash
-# CLI
 registry-stats serve --port 3000
 ```
 
@@ -241,25 +264,28 @@ registerProvider(cargo);
 await stats('cargo', 'serde');
 ```
 
-## Dashboard
-
-A self-updating stats dashboard ships with the library at [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
+## Repo Structure
 
-- **Executive snapshot** — one-sentence weekly narrative (top registry, top package, top gainer, concentration, data confidence)
-- **Growth Pulse** — top gainers, decliners, and newly active packages (npm 7d vs prior 7d)
-- **Data Health** — per-registry coverage, confidence badges, expandable error details
-- **Breakdown** — per-registry bars and 30-day aggregate sparkline
-- **Leaderboard** — all packages ranked by weekly downloads with per-row 30d sparklines
+```
+registry-stats/
+├── src/        # TypeScript engine (published to npm)
+├── site/       # Astro dashboard + landing page (deployed to GitHub Pages)
+├── desktop/    # WinUI 3 desktop app (.NET 10 MAUI)
+└── test/       # Library tests (vitest)
+```
 
-Data is fetched at build time via `npm run fetch-stats` and rebuilt weekly by CI (Mondays 06:00 UTC). Dark and light themes supported.
+## Development
 
-## Website
+```bash
+# Engine
+npm install && npm run build && npm test
 
-Docs / landing page lives in `site/`.
+# Dashboard (dev server)
+npm run site:dev
 
-- Dev: `npm run site:dev`
-- Build: `npm run site:build`
-- Preview: `npm run site:preview`
+# Dashboard (production build)
+npm run site:build
+```
 
 ## Security & Data Scope