merge: dev3 → master — docs fact-check lancio CLI-first (README, guide, beta, roadmap, security) + autore reale negli installer desktop

Author: leopu00

.github/CONTRIBUTING.md

@@ -45,6 +45,8 @@ Full contributor setup (Node 20+, tmux, agent CLIs, TUI/CLI build from source) i
 - **Do not push directly to `master`**
 - Open a Pull Request and wait for review
 
+> ℹ️ You'll see merge commits from `devN` branches (`dev1`, `dev2`, …) in the history: that's how the core team works — several parallel `devN` worktrees at a time, each merged into `master` when its slice is done. External contributions follow the `feat/`/`fix/` + PR flow above.
+
 ## What your PR should show
 
 We love evidence. The clearer you show that your change makes things

BACKLOG.md

@@ -26,7 +26,7 @@
 - ⬜ **[JHT-REALTIME-SCALE]** — event-driven sync is live and degrades gracefully; scale refinements for many users (reconnect-rate monitor, Realtime connection ceiling, thundering herd, unified auth, tunable parachute).
 - ⬜ **[JHT-CLOUDSYNC-01]** — remaining P0 flow-correctness items; living doc: `docs/internal/architecture/cloud-sync-architecture.md` § Pending.
 - ⬜ **[JHT-ONBOARDING-04]** — periodic agent-results push.
-- 🟠 **[JHT-CASE-STUDIES-WEB]** — publish run #4 (Kimi weekly-distributed, data collected, processing pending) and re-run #5 (Claude Max with proper instrumentation); optional charts (team efficiency, Kimi burn sparkline, per-day timeline).
+- 🟠 **[JHT-CASE-STUDIES-WEB]** — publish the Kimi weekly-distributed run (data collected, processing pending) and the Claude Max re-run (with proper instrumentation); optional charts (team efficiency, Kimi burn sparkline, per-day timeline).
 - ⬜ **[JHT-WEB-02-CHECKSUM]** — SHA256 checksums on the download page.
 - ⬜ **[JHT-SETUP-LOCAL-FIRST]** — re-elevate Local PC to a first-class path; align execution-mode copy.
 

README.md

@@ -36,13 +36,13 @@ The whole pipeline runs **locally in a container**, on your machine or your VPS
 
 I originally built JHT for my own job hunt. It worked. So I rebuilt it as open source, so anyone could use it.
 
-> 📊 **From the original private build** — ~200 offers analyzed · ~20 tailored applications · **5 interview invites in 2 weeks**. Full background in [`docs/about/STORY.md`](docs/about/STORY.md).
+> 📊 **From the original private build** — ~200 offers analyzed · ~20 tailored applications · **5 interview invites within a few weeks**. Full background in [`docs/about/STORY.md`](docs/about/STORY.md).
 
 > 📈 **From the public stack (June 2026)** — a Codex-powered team ran **one month unattended**: **649 positions found · 513 scored**, closing its weekly budget at **99–100% for four straight weeks** with zero human interventions. Data in [`docs/about/RESULTS.md`](docs/about/RESULTS.md), live on [jobhunterteam.ai/case-studies](https://jobhunterteam.ai/case-studies).
 
 ## 🎬 Demo
 
-> 🚧 **Coming soon** — animated GIFs of the dashboard, team pipeline, and onboarding flow.
+The best demo is real data: [jobhunterteam.ai/case-studies](https://jobhunterteam.ai/case-studies) renders the live dashboards of the beta runs — including the month-long autonomous Codex run (649 positions found, 513 scored, weekly budget self-managed at 99–100%). Animated GIFs of the dashboard and onboarding are in the works.
 
 ## The Team
 
@@ -106,7 +106,7 @@ See [`docs/internal/ops/INFRA.md`](docs/internal/ops/INFRA.md) for the full infr
 
 ## Install
 
-> 🧪 **Beta — installer maturing.** The team and the agents work end-to-end. The desktop installer and the onboarding wizard are still rounding off rough edges — if you hit a snag, see [`docs/guides/BETA.md`](docs/guides/BETA.md) and join the beta program.
+> 🧪 **Beta — CLI-first.** The team and the agents work end-to-end; the supported entry points today are the CLI one-liner below and the [AI-agent path](#-ai-agents-can-drive-jht). The desktop app is **not part of the beta yet** — it works up to a point and is under active development ([`desktop/STATUS.md`](desktop/STATUS.md)). If you hit a snag, see [`docs/guides/BETA.md`](docs/guides/BETA.md) and join the beta program.
 
 **Before you start** — JHT runs ~**400M tokens/month** (many agents working in parallel, around the clock). To make this affordable, JHT runs on **LLM subscriptions, not pay-per-use API keys** — the same usage on the API would cost $1,000–$2,500/mo. See [`docs/about/PROVIDERS.md`](docs/about/PROVIDERS.md) and [ADR-0004](docs/adr/0004-subscription-only-no-api-keys.md) for the full reasoning.
 
@@ -128,7 +128,7 @@ Three subscriptions cover the ~400M tokens/month requirement:
 curl -fsSL https://jobhunterteam.ai/install.sh | bash
 ```
 
-**Desktop app** — `.dmg` / `.exe` / `.AppImage` / `.deb` from [`/download`](https://jobhunterteam.ai/download) or GitHub Releases.
+**Desktop app** — in development, not part of the beta. Unsupported preview builds land on [GitHub Releases](https://github.com/leopu00/job-hunter-team/releases) for contributors, but the website's download page is intentionally disabled until the app is ready. State, gaps and roadmap in [`desktop/STATUS.md`](desktop/STATUS.md).
 
 Expert mode, contributor setup, and the full walkthrough are in [`docs/guides/QUICKSTART.md`](docs/guides/QUICKSTART.md).
 
@@ -137,9 +137,9 @@ Expert mode, contributor setup, and the full walkthrough are in [`docs/guides/QU
 | | Interface | Launch | Stack |
 |---|---|---|---|
 | 🌐 | **Web Dashboard** | `cd web && npm run dev:host` | Next.js · React · Tailwind · Supabase |
-| 🖥️ | **Desktop App** | open `JHT Desktop` | Electron · electron-builder *(interaction cockpit — start/stop, chat, file upload; the web dashboard is view-only)* |
+| 🖥️ | **Desktop App** *(in development)* | build from source — [`desktop/STATUS.md`](desktop/STATUS.md) | Electron · electron-builder *(interaction cockpit — start/stop, chat, file upload; not yet publicly released)* |
 | ⌨️ | **CLI** | `jht team start` | Node.js · Commander *(full reference: [`docs/guides/CLI-REFERENCE.md`](docs/guides/CLI-REFERENCE.md). Also designed to be driven by AI agents — see [`docs/guides/AI-AGENT-INTEGRATION.md`](docs/guides/AI-AGENT-INTEGRATION.md))* |
-| 💬 | **Telegram** | bidirectional bot bridge | grammy |
+| 💬 | **Telegram** | 3 bots — Assistant · Captain · Mentor | Python bot bridge *(field-validated — the recommended channel for teams on a VPS or dedicated PC)* |
 
 ## 🤖 AI agents can drive JHT
 
@@ -168,9 +168,9 @@ See [`docs/guides/AI-AGENT-INTEGRATION.md`](docs/guides/AI-AGENT-INTEGRATION.md)
 
 ## Status
 
-- ✅ **Done** — agent team (always-on core: Captain · Sentinel · Assistant · Mentor + dynamic worker pool: Scout · Analyst · Scorer · Writer · Critic + one-shot: Dottore · Mantenitore), monitored by 📡 Bridge; CLI + TUI + web dashboard (54 pages + 143 API routes wired to real Supabase data); desktop installers (`.dmg` / `.exe` / `.AppImage` / `.deb`); i18n in 7 languages (en/it/hu/es/de/fr/pt — UI and agent prompts); 150+ test files; tested end-to-end on Claude Max x20, Kimi €40 (75h + 10-day beta), and Codex ~€100 (**1-month autonomous run**)
-- 🔨 **In progress** — Desktop installer onboarding polish · Kimi tier hardening (two multi-week beta teams in observation)
-- ⏭️ **Next** — Code signing + auto-update for desktop · contributor missions M1–M8 (see the roadmap)
+- ✅ **Done** — agent team (always-on core: Captain · Sentinel · Assistant · Mentor + dynamic worker pool: Scout · Analyst · Scorer · Writer · Critic + one-shot: Dottore · Mantenitore), monitored by 📡 Bridge; CLI + TUI + web dashboard (54 pages + 142 API routes wired to real Supabase data); full UI i18n in 7 languages (en/it/hu/es/de/fr/pt — agent-prompt translations still catching up in places); 250+ test files; tested end-to-end on Claude Max x20, Kimi €40 (75h + 10-day beta), and Codex ~€100 (**1-month autonomous run**)
+- 🔨 **In progress** — Desktop app toward public beta (installers build for macOS/Windows/Linux and onboarding runs end-to-end, but dashboard parity, agent lifecycle controls and cross-platform QA are open — [`desktop/STATUS.md`](desktop/STATUS.md)) · Kimi tier hardening (two multi-week beta teams in observation)
+- ⏭️ **Next** — Demo GIFs + launch assets · desktop auto-update + tray/notifications · contributor missions M1–M5 (see the roadmap)
 
 Full roadmap: [`docs/about/ROADMAP.md`](docs/about/ROADMAP.md).
 
@@ -193,7 +193,8 @@ Full roadmap: [`docs/about/ROADMAP.md`](docs/about/ROADMAP.md).
 
 PRs and issues welcome. See [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the dev setup, PR flow, commit conventions, and agent-specific guides.
 
-- 🙌 **Where you can help** — the [contributor missions](docs/about/ROADMAP.md#-where-you-can-help--contributor-missions) (M1–M8) are the bigger directions we'd love a hand with; each breaks into `good first issue` entry-points
+- 🙌 **Where you can help** — the [contributor missions](docs/about/ROADMAP.md#-where-you-can-help--contributor-missions) (M1–M5, with M6–M8 on the horizon) are the bigger directions we'd love a hand with; each breaks into `good first issue` entry-points. The **desktop app** is the highest-impact area right now — the ranked list is in [`desktop/STATUS.md`](desktop/STATUS.md)
+- 🌿 **How development flows** — the core team works on several parallel `devN` branches (four active at the moment), each merged into `master` when its slice is done; external contributions come in as `feat/`/`fix/` branches → PR
 - 🧪 **Beta tester?** See [`docs/guides/BETA.md`](docs/guides/BETA.md) — we want real job-seekers to break things and tell us how
 - 🔐 **Found a security issue?** See [`SECURITY.md`](SECURITY.md) for responsible disclosure — please don't open a public issue. Internal pre-launch audit + hardening sprint results live in [`docs/security/`](docs/security/)
 - 🤝 **Code of conduct**: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1

SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-JHT (Job Hunter Team) is a **local-first desktop app for a single user**. It runs on your own machine, orchestrates AI agents in a Docker container, and reads/writes only files you control. The full threat model lives in [`docs/security/04-threat-model.md`](docs/security/04-threat-model.md) — this file is the short, public-facing version.
+JHT (Job Hunter Team) is a **local-first, single-user system** (CLI today; a desktop app is in development). It runs on your own machine, orchestrates AI agents in a Docker container, and reads/writes only files you control. The full threat model lives in [`docs/security/04-threat-model.md`](docs/security/04-threat-model.md) — this file is the short, public-facing version.
 
 ## Reporting a vulnerability
 
@@ -65,7 +65,7 @@ To set expectations honestly:
 - **No enterprise SLA** — use at your own risk.
 - **No 100% prompt-injection-proof guarantee** — active research area.
 - **No container-escape guarantee** — Docker/OS responsibility.
-- **No signed binary releases yet** — code signing is on the roadmap, post-MVP.
+- **No signed binary releases** — code signing is deferred by choice during beta; open source + building from source is the trust signal.
 
 ## Hardening status
 

cli/package.json

@@ -14,5 +14,12 @@
     "@supabase/supabase-js": "^2.108.2",
     "commander": "^13.1.0",
     "picocolors": "^1.1.1"
-  }
+  },
+  "license": "MIT",
+  "author": "Leone Emanuel Puglisi <leopu00@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leopu00/job-hunter-team.git"
+  },
+  "description": "jht CLI — control surface for the Job Hunter Team agent stack"
 }

desktop/README.md

@@ -29,7 +29,7 @@ assets/ · build/     icons & packaging resources
 ```bash
 npm run dev          # launch in dev
 npm test             # unit tests
-npm run dist:mac     # build signed .dmg  (also dist:win / dist:linux)
+npm run dist:mac     # build .dmg — ad-hoc signature, code signing deferred during beta  (also dist:win / dist:linux)
 ```
 
 ## See also

desktop/STATUS.md

@@ -37,7 +37,7 @@ desktop app is where we want contributors to help.
 
 The full first-run flow is real and has been driven end-to-end on Windows:
 
-1. **Install** — signed-in NSIS/dmg/AppImage installer, one click.
+1. **Install** — NSIS/dmg/AppImage installer, one click (unsigned during beta).
 2. **Welcome + language** — first screen carries the language picker; switching
    it re-translates the whole screen live. 7 languages.
 3. **Readiness check** — detects and installs WSL2, Git and Docker Desktop

desktop/package.json

@@ -4,8 +4,12 @@
   "private": true,
   "description": "Desktop launcher for Job Hunter Team",
   "author": {
-    "name": "Mario Rossi",
-    "email": "owner@example.com"
+    "name": "Leone Emanuel Puglisi",
+    "email": "leopu00@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leopu00/job-hunter-team.git"
   },
   "homepage": "https://jobhunterteam.ai",
   "license": "MIT",
@@ -134,7 +138,7 @@
     "linux": {
       "artifactName": "job-hunter-team-${version}-linux.${ext}",
       "icon": "assets/icon.png",
-      "maintainer": "Mario Rossi <owner@example.com>",
+      "maintainer": "Leone Emanuel Puglisi <leopu00@gmail.com>",
       "target": [
         "AppImage",
         "deb"

docs/README.md

@@ -1,41 +1,41 @@
-# 📚 Documentazione — Job Hunter Team
+# 📚 Documentation — Job Hunter Team
 
-Indice di primo livello della documentazione. Le cartelle sono ordinate dalla più
-utente-facing alla più interna.
+Top-level index of the documentation. Folders are ordered from the most
+user-facing to the most internal.
 
 ---
 
-## 🎯 [`about/`](about/) — cos'è JHT e se funziona
-Doc pubblica per chi valuta JHT, in due cluster (vedi [indice](about/README.md)):
-- 📖 **Narrativa:** `VISION` · `STORY` · `ROADMAP`
-- 🔬 **Prove & economia:** `PROVIDERS` · `MONITORING` · `RESULTS`
+## 🎯 [`about/`](about/) — what JHT is and whether it works
+Public docs for anyone evaluating JHT, in two clusters (see the [index](about/README.md)):
+- 📖 **Narrative:** `VISION` · `STORY` · `ROADMAP`
+- 🔬 **Evidence & economics:** `PROVIDERS` · `MONITORING` · `RESULTS`
 
-## 📘 [`guides/`](guides/) — guide operative
-Setup, uso e operazioni (vedi [indice](guides/README.md)). Tutte in inglese, naming `UPPERCASE-KEBAB`.
+## 📘 [`guides/`](guides/) — operational guides
+Setup, usage and operations (see the [index](guides/README.md)). All in English, `UPPERCASE-KEBAB` naming.
 - 🚀 **Start:** `QUICKSTART` · `CLI-INSTALL` · `CLI-REFERENCE` · `AI-AGENT-INTEGRATION`
 - ☁️ **VPS:** `VPS-SETUP-WIZARD` · `VPS-SETUP`
-- 🧪 **Beta:** `BETA` · `FEEDBACK-TICKETING`
+- 🧪 **Beta:** `BETA` · `FEEDBACK-TICKETING` · `EMAIL-FORWARDING`
 
-## 🏛️ [`adr/`](adr/) — decisioni architetturali
-Le scelte vincolanti e il loro perché (Architecture Decision Records).
-`0001` Colima · `0002` 3 CLI agenti · `0003` single-writer · `0004` no-API-keys · `0005` provider-risk
+## 🏛️ [`adr/`](adr/) — architecture decision records
+The binding choices and their rationale.
+`0001` Colima · `0002` 3 agent CLIs · `0003` single-writer · `0004` no-API-keys · `0005` provider-risk · `0006` user-choice container runtime *(supersedes 0001)*
 
-## 🔒 [`security/`](security/) — sicurezza
-Review pre-launch, threat model, checklist, comparazioni.
+## 🔒 [`security/`](security/) — security
+Pre-launch review, threat model, checklist, comparisons.
 `01`→`06` + `README`
 
-## 🚀 [`launch/`](launch/) — materiali di lancio
-`demo-storyboard` (le bozze di post pubblici — Show HN ecc. — stanno fuori dalla repo, in `prima-release/`)
+## 🚀 [`launch/`](launch/) — launch materials
+`demo-storyboard` (drafts of public posts — Show HN etc. — live outside the repo)
 
-## 📊 [`sessions/`](sessions/) — log run reali
-Una cartella per run agenti (Codex/Kimi/long-session) con README + dump dati.
+## 📊 [`sessions/`](sessions/) — real-run logs
+One folder per agent run (Codex/Kimi/long-session) with a README + data dumps.
 
-## 🔧 [`internal/`](internal/) — note di lavoro interne
-Architettura viva, postmortem, esperimenti, roadmap, ops. Vedi
-[`internal/README.md`](internal/README.md) per l'indice per categoria:
-`architecture/` · `postmortems/` · `experiments/` · `roadmap/` · `ops/` · `qa-reports/` · `_archive/`
+## 🔧 [`internal/`](internal/) — internal working notes
+Living architecture notes, postmortems, experiments, roadmap, ops. See
+[`internal/README.md`](internal/README.md) for the per-category index:
+`architecture/` · `postmortems/` · `experiments/` · `roadmap/` · `ops/` · `prototypes/` · `_archive/`
 
 ---
 
-> 📄 Documenti meta nella root del repo: `README.md` · `CHANGELOG.md` ·
+> 📄 Meta documents in the repo root: `README.md` · `CHANGELOG.md` ·
 > `BACKLOG.md` · `SECURITY.md` · `CODE_OF_CONDUCT.md`.

docs/REVIEW-LOG.md

@@ -160,9 +160,9 @@ Serve a tenere traccia di cosa hai già letto e cosa è cambiato dopo l'ultima l
 | `docs/internal/2026-05-01-team-session-report.md` | Report sessione team 30 apr/1 mag UTC | — | 2026-05-02 | ✅ |
 | [docs/internal/experiments/2026-05-03-rate-kimi-weights.md](./internal/experiments/2026-05-03-rate-kimi-weights.md) | Calibrazione empirica pesi rate Kimi K2 | — | 2026-05-03 | ✅ |
 | `docs/internal/2026-05-04-vps-deployment-design.md` | Design deploy VPS (3 path: SSH manuale / web pairing / launcher) | — | 2026-05-04 | ✅ |
-| [docs/internal/TODO-bridge-v7.md](./internal/_archive/TODO-bridge-v7.md) | 📌 Punch list bridge V7 + token monitor (entry point) | — | 2026-05-02 | ✅ |
+| `docs/internal/TODO-bridge-v7.md` *(file rimosso)* | 📌 Punch list bridge V7 + token monitor (entry point) | — | 2026-05-02 | ✅ |
 | `docs/internal/2026-05-06-host-container-split.md` | ⚙️ Split host/container — CLI wrapper + dev compose, design e razionale | — | 2026-05-06 | ✅ |
-| [docs/internal/2026-05-06-launch-infra-costs.md](./internal/_archive/2026-05-06-launch-infra-costs.md) | 💰 Stima costi infra per public launch (Vercel/Supabase/domain) | — | 2026-05-06 | ✅ |
+| `docs/internal/2026-05-06-launch-infra-costs.md` *(file rimosso)* | 💰 Stima costi infra per public launch (Vercel/Supabase/domain) | — | 2026-05-06 | ✅ |
 | [docs/internal/experiments/2026-05-06-prompt-decomposition-skill-vs-manual.md](./internal/experiments/2026-05-06-prompt-decomposition-skill-vs-manual.md) | 🧩 Architettura prompt decomposition — quando usare CLAUDE.md / Skill / Manual con token math | — | 2026-05-09 | ✅ |
 | [docs/internal/experiments/2026-05-06-agent-prompts-i18n.md](./internal/experiments/2026-05-06-agent-prompts-i18n.md) | _(da compilare nel JSON)_ | — | 2026-05-06 | ✅ |
 | `docs/internal/2026-05-06-vps-providers-research.md` | _(da compilare nel JSON)_ | — | 2026-05-09 | ✅ |