bmad-plus 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to BMAD+ will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.1] — 2026-07-01
+
+### Fixed — Credibility (honest status)
+- **Real CI on push/PR** (`.github/workflows/ci.yml`): lint + test + npm audit, all blocking. Previously the only workflow ran at release-tag and swallowed failures with `|| echo`.
+- **Test harness repaired**: mock ESM `@clack/prompts` so Jest loads the autoconfig suite — `npm test` now genuinely passes (176 tests, 10/10 suites). It did not before.
+- **Lint restored**: added flat `eslint.config.js` (ESLint v9); removed legacy `.eslintrc.json` + deprecated `--ext`. `npm run lint` runs with 0 errors.
+- **Lockfile resynced** to the correct version with full devDependency tree — `npm ci` works from a clean clone.
+- Publish workflow no longer masks `npm publish` failures; npm audit is blocking.
+- Removed hardcoded VPS IP from `mcp-server/server.py` docstring.
+
+### Documentation — Honesty correction
+- Removed the unverifiable **"143 tests / 0 vulnerabilities / Score A+"** badges from README and README-DIST.
+- Fixed the corrupted version-history table (0.9.0/0.8.0 were duplicated).
+- **Note on 0.9.0 below:** the "64/64 fixed, score A+" and "auth on all endpoints" claims in the 0.9.0 entry were **overstated**. A 2026-07-01 adversarial re-audit (see `audit/2026-07-01/`) found 102 open findings and re-graded the project **C+**. The MCP token *is* checked by middleware on `/sse` and `/messages/`, but the prior "all endpoints" phrasing and the A+ score were not accurate. This release begins the honest remediation.
+
 ## [0.9.0] — 2026-06-24
 
 ### Security

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Laurent Rochetta
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Laurent Rochetta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,34 +8,82 @@
   🌐 <b>English</b> | <a href="readme-international/README.fr.md">Français</a> | <a href="readme-international/README.es.md">Español</a> | <a href="readme-international/README.de.md">Deutsch</a>
 </div>
 
-> **56+ agents · 9 modular packs · Autopilot mode · Parallel execution · 143 tests**
+> **Multi-role agents · 9 modular packs · Autopilot mode · Parallel execution**
 > Smart fork of [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) — Self-activating agents with 3-level context detection, GRC compliance (Shield), full SDLC pipeline (Dev Studio), OSINT intelligence, SEO audit, persistent cross-session memory, and a 10-language CLI installer.
 
 ---
 
 ## 📋 Table of Contents
 
-- [Why BMAD+?](#-why-bmad-)
+- [What is BMAD+?](#-what-is-bmad)
 - [Quick Start](#-quick-start)
-- [Architecture](#-architecture)
 - [The 56+ Agents](#the-56-agents)
 - [Pack System](#-pack-system)
 - [Innovations](#-innovations)
+- [CLI Reference](#-cli-commands)
 - [Supported IDEs](#-supported-ides)
-- [Project Structure](#-project-structure)
 - [Configuration](#-configuration)
 - [Version History](#-version-history)
 - [License](#-license)
 
 ---
 
-## 💡 Why BMAD+?
+## 💡 What is BMAD+?
 
-BMAD-METHOD is an excellent framework with 9 specialized agents. But for a solo developer or a small team, 9 agents is too fragmented. BMAD+ solves this problem:
+BMAD+ is a **multi-agent AI framework** that turns your AI coding assistant into a full team. Install it in any project, talk to specialized agents by name, and let them handle strategy, architecture, code, testing, compliance, OSINT, SEO — everything from idea to production.
+
+### At a Glance
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  🚀 BMAD+ — What You Get                                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  56+ Agents        Talk to Atlas, Forge, Sentinel, Nexus,            │
+│                  Shadow, Zecher — each handles multiple roles       │
+│                                                                     │
+│  9 Packs         Core dev · OSINT · GRC compliance · SDLC          │
+│                  · SEO audit · Memory · Backup · Maker · Animated  │
+│                                                                     │
+│  Autopilot       Say "autopilot" → Nexus orchestrates              │
+│                  idea → PRD → architecture → code → tests → ship   │
+│                                                                     │
+│  Parallel        Independent tasks run concurrently                 │
+│                  with conflict detection and supervision            │
+│                                                                     │
+│  Memory          Persistent brain across sessions                   │
+│                  with project scanner and Karpathy guardrails       │
+│                                                                     │
+│  5 IDEs          Claude Code · Gemini CLI · Antigravity            │
+│                  · Codex CLI · OpenCode — auto-detected             │
+│                                                                     │
+│  10 Languages    CLI installer in EN, FR, ES, DE, IT, PT,          │
+│                  NL, RU, ZH, JA                                     │
+│                                                                     │
+│  143 Tests       Full functional + unit test coverage               │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Not Just Development
+
+| Domain | What BMAD+ Does | Agent/Pack |
+|--------|----------------|------------|
+| 📊 **Strategy** | Market research, SWOT, product briefs, PRDs, UX design | Atlas (Core) |
+| 🏗️ **Development** | Architecture, TDD, code generation, documentation | Forge (Core) |
+| 🔍 **Quality** | Code review, E2E tests, UX audit, accessibility | Sentinel (Core) |
+| 🎼 **Management** | Sprint planning, story breakdown, retrospectives | Nexus (Core) |
+| 🕵️ **OSINT** | Person investigation, social scraping, psychoprofiling | Shadow (OSINT Pack) |
+| 🛡️ **Compliance** | GDPR, ISO 27001, SOC 2, HIPAA, EU AI Act — 25+ frameworks | 38 agents (Shield Pack) |
+| 🔎 **SEO** | 6-phase audit, PageSpeed loop, Google APIs, competitor analysis | Scout/Chief/Judge (SEO Pack) |
+| 🧠 **Memory** | Cross-session brain, decision recall, session handoffs | Zecher (Memory Pack) |
+| 🧬 **Agent Creation** | Design, build, validate and package new agents | Maker (Maker Pack) |
+
+### Why BMAD+ over BMAD-METHOD?
 
 | BMAD-METHOD | BMAD+ |
 |---|---|
-| 9 specialized agents | **56+ agents** across 9 packs |
+| 9 specialized agents | **56+ agents** (12 roles total) |
 | Manual activation only | **Intelligent auto-activation** at 3 levels |
 | No automated pipeline | **Autopilot Mode**: idea → delivery |
 | Sequential execution | **Supervised parallelism** |
@@ -107,6 +155,7 @@ The installer:
 | Recall past decisions/context | **Zecher** 🧠 | `Zecher, what did we decide about the auth strategy?` |
 | Session handoff summary | **Zecher** 🧠 | `Zecher, create a handoff for the next session` |
 
+
 #### 🚀 Typical Workflow (manual mode)
 
 ```
@@ -203,21 +252,21 @@ npx bmad-plus scan D:\DEV --yes --depth 6
 ```mermaid
 graph TB
     subgraph Core["⚙️ Core Pack"]
-        AT["Atlas 🎯"]
-        FG["Forge 🏗️"]
-        SN["Sentinel 🔍"]
-        NX["Nexus 🎼"]
+        AT["Atlas 🎯<br/>Strategy & Product"]
+        FG["Forge 🏗️<br/>Architecture & Code"]
+        SN["Sentinel 🔍<br/>QA & UX Review"]
+        NX["Nexus 🎼<br/>Orchestrator"]
     end
 
     subgraph Packs["📦 Modular Packs"]
-        SH["Shadow 🕵️ OSINT"]
-        MK["Maker 🧬"]
-        ZC["Zecher 🧠 Memory"]
-        SD["Shield 🛡️ GRC 38 agents"]
-        DS["Dev Studio 🏗️ SDLC 6 agents"]
-        SEO["SEO Engine 🔎 3 agents"]
-        BK["Backup 🗂️"]
-        AN["Animated 🎬"]
+        SH["Shadow 🕵️<br/>OSINT Intelligence"]
+        MK["Maker 🧬<br/>Agent Creator"]
+        ZC["Zecher 🧠<br/>Memory Guardian"]
+        SD["Shield 🛡️<br/>GRC Compliance (38 agents)"]
+        DS["Dev Studio 🏗️<br/>Full SDLC (6 agents)"]
+        SEO["SEO Engine 🔎<br/>3 agents · 6 phases"]
+        BK["Backup 🗂️<br/>Smart Archive"]
+        AN["Animated 🎬<br/>Scroll-Driven Sites"]
     end
 
     subgraph Skills["⚡ Core Skills"]
@@ -334,6 +383,22 @@ graph TB
 
 ---
 
+### Zecher — Memory Guardian 🧠 *(Memory Pack)*
+
+**Persistent cross-session brain agent.** Maintains project knowledge across conversations.
+
+| Capability | Description |
+|-----------|-------------|
+| **Session Handoff** | Auto-creates session summaries with decisions, patterns, and lessons learned |
+| **Context Recall** | Retrieves relevant past decisions/patterns at conversation start |
+| **Brain Health** | Monitors memory files integrity and detects staleness |
+| **Cross-Project** | Links project memory to the global brain (`~/.bmad-plus/brain/`) |
+| **Karpathy Guardrails** | Prevents hallucinated memories — every entry needs source evidence |
+
+**Memory files:** `decisions.md`, `lessons.md`, `patterns.md`, `context.md`, `sessions/`
+
+---
+
 ## 📦 Pack System
 
 BMAD+ uses a modular pack system. Core is always installed, additional packs are optional.
@@ -346,32 +411,28 @@ npx bmad-plus install
 
    🔍 OSINT — Shadow (investigation, scraping, psychoprofiling)
    🧬 Agent Creator — Maker (design, build, package)
-   🛡️ Shield GRC — 38 compliance agents (GDPR, ISO 27001, SOC 2, HIPAA...)
-   🏗️ Dev Studio — 6 SDLC agents (full lifecycle: design to deploy)
-   🔎 SEO Engine — Scout, Chief, Judge (6-phase audit, PageSpeed)
-   🧠 Memory — Zecher (persistent brain, session handoffs)
-   🗂️ Backup — Smart archive with versioning
-   🎬 Animated — Scroll-driven animated websites
+   🛡️ Security Audit — Shield (vulnerability scan)
    🤖 Install everything
    None — Core only
 ```
 
-| Pack | Agents | Description | Status |
+| Pack | Agents | What it does | Status |
 |------|--------|-------------|--------|
-| ⚙️ **Core** | Atlas, Forge, Sentinel, Nexus | Strategy, dev, QA, orchestration | ✅ Stable |
-| 🔍 **OSINT** | Shadow | OSINT intelligence, 55+ Apify actors, 7 APIs | ✅ Stable |
-| 🧬 **Maker** | Maker | Design, build, validate new BMAD+ agents | ✅ Stable |
-| 🛡️ **Shield** | 38 GRC agents | GDPR, ISO 27001, SOC 2, HIPAA, EU AI Act | ✅ Stable |
-| 🏗️ **Dev Studio** | 6 SDLC agents | Full lifecycle: design to deploy | ✅ Stable |
-| 🔎 **SEO** | Scout, Chief, Judge | 6-phase audit, PageSpeed loop, Google APIs | ✅ Stable |
-| 🧠 **Memory** | Zecher | Cross-session brain, decision recall, handoffs | ✅ Stable |
-| 🗂️ **Backup** | Backup Agent | Smart archive with versioning | ✅ Stable |
-| 🎬 **Animated** | Creative Agent | Scroll-driven animated websites | ✅ Stable |
+| ⚙️ **Core** | Atlas, Forge, Sentinel, Nexus | Full dev lifecycle: strategy → architecture → code → QA | ✅ Stable |
+| 🔍 **OSINT** | Shadow | Person investigation, social scraping, psychoprofiling (55+ Apify actors) | ✅ Stable |
+| 🧬 **Maker** | Maker | Design, build, validate, and package new BMAD+ agents | ✅ Stable |
+| 🛡️ **Shield** | 38 compliance agents | GRC across 25+ frameworks: GDPR, ISO 27001, SOC 2, HIPAA, PCI DSS, EU AI Act, DORA, NIS2 | ✅ Stable |
+| 🏗️ **Dev Studio** | 6 specialized SDLC agents | Full SDLC: brainstorm → PRD → architecture → TDD → review (30 workflows, BWML DSL) | ✅ Stable |
+| 🔍 **SEO** | Scout, Chief, Judge | 6-phase SEO audit, PageSpeed perfection loop, Google APIs, competitor benchmark | ✅ Stable |
+| 🗂️ **Backup** | Backup Agent | Timestamped ZIP with smart exclusions (node_modules, .git, dist...) | ✅ Stable |
+| 🎬 **Animated** | Animated Website Agent | Luxury scroll-driven website from video input | ✅ Stable |
+| 🧠 **Memory** | Zecher | Cross-session brain, project scanner, Karpathy guardrails | ✅ Stable |
 
 Each pack defines:
-- Its agents and skills
-- Its required/optional API keys
-- Its external package (if applicable)
+- Its agents, skills, and workflows
+- Required/optional API keys
+- External packages (if applicable)
+- Cohabitation rules with other packs
 
 ---
 
@@ -412,7 +473,7 @@ Give a project idea → Nexus orchestrates the complete pipeline:
 ```
 
 **Configurable checkpoints:**
-- `require_approval` (🔴) — Pause, wait for approval
+- `require_approval` (🔴) — Pause, WhatsApp notification, wait
 - `notify_only` (🟡) — Notification, continues unless intervened
 - `auto` (🟢) — Continues automatically
 
@@ -442,51 +503,8 @@ The installer automatically detects IDEs and generates configs:
 | Codex CLI | `AGENTS.md` | `.codex/` folder |
 | OpenCode | `OPENCODE.md` | opencode config |
 
----
 
-## 📁 Project Structure
 
-```
-BMAD+/
-├── README.md                      ← This file (English)
-├── readme-international/          ← Translated READMEs (fr, es, de)
-├── CHANGELOG.md                   ← Version history
-├── CLAUDE.md                      ← Claude Code Config
-├── GEMINI.md                      ← Gemini CLI Config
-├── AGENTS.md                      ← Codex CLI / OpenCode Config
-├── .gitignore
-│
-├── src/
-│   └── bmad-plus/                 ⭐ CUSTOM MODULE
-│       ├── module.yaml            ← Module + packs config
-│       ├── module-help.csv        ← Contextual help
-│       ├── agents/
-│       │   ├── agent-strategist/  ← Atlas (analyst + pm)
-│       │   ├── agent-architect-dev/ ← Forge (architect + dev + tw)
-│       │   ├── agent-quality/     ← Sentinel (qa + ux)
-│       │   ├── agent-orchestrator/ ← Nexus (sm + qf + autopilot + parallel)
-│       │   ├── agent-maker/       ← Maker (meta-agent) [pack: maker]
-│       │   └── agent-shadow/      ← Shadow (osint) [pack: osint]
-│       ├── skills/
-│       │   ├── bmad-plus-autopilot/ ← Automated pipeline
-│       │   └── bmad-plus-parallel/  ← Parallel execution
-│       └── data/
-│           └── role-triggers.yaml ← Auto-activation rules
-│
-├── tools/
-│   └── cli/                       🛠️ NPX INSTALLER
-│       └── install.js             ← npx bmad-plus install
-│
-├── osint-agent-package/           🔍 OSINT PACKAGE
-│   ├── agents/                    ← Shadow Agent (OSINT investigator)
-│   ├── skills/                    ← 55+ Apify actors
-│   └── install.ps1                ← Installation script
-│
-└── upstream/                      📦 UPSTREAM REFERENCE
-    └── (clone of BMAD-METHOD)     ← Excluded from repo (.gitignore)
-```
-
----
 
 ## ⚙️ Configuration
 
@@ -505,6 +523,8 @@ BMAD+/
 
 | Key | Pack | Usage |
 |-----|------|-------|
+| `GEMINI_API_KEY` | Monitor | AI Analysis of upstream diffs |
+| `EVOLUTION_API_KEY` | Monitor | WhatsApp Notifications |
 | `APIFY_API_TOKEN` | OSINT | Social media scraping |
 | `PERPLEXITY_API_KEY` | OSINT | Enriched search |
 
@@ -514,7 +534,7 @@ BMAD+/
 
 | Version | Date | Description |
 |---------|------|-------------|
-| **0.1.0** | 2026-03-17 | 🎉 Foundation — 56+ agents (Atlas, Forge, Sentinel, Nexus, Shadow, Maker), 3 skills, pack system, multi-IDE support |
+| **0.1.0** | 2026-03-17 | 🎉 Foundation — 56+ agents (Atlas, Forge, Sentinel, Nexus, Shadow, Maker), 3 skills, pack system, monitoring, multi-IDE support |
 | **0.2.0** | 2026-03-18 | 🔀 Oveanet Fusion — 3 new utility packs: SEO Audit 360, Universal Backup, Animated Website |
 | **0.3.0** | 2026-03-19 | 🚀 SEO Engine v2.0 — 3 multi-role agents, 4 Python scripts, 6-phase workflow, PageSpeed loop, GEO analysis |
 | **0.4.0** | 2026-03-19 | 🏢 SEO Engine v2.1 — SKILL.md orchestrator, Google APIs, HTML reports, competitor benchmark, 50 tests, GSC + GA4 extensions |
@@ -524,8 +544,8 @@ BMAD+/
 | **0.4.4** | 2026-05-17 | 🔧 UTF-8 encoding fix, complete i18n 10 languages, 62 unit tests |
 | **0.5.0** | 2026-05-17 | 🛡️ **Pack Shield** — 38 GRC compliance agents, 7 categories, 25+ frameworks (GDPR, ISO 27001, SOC 2, EU AI Act...) |
 | **0.6.0** | 2026-05-17 | 🏗️ **Pack Dev Studio** — 6 SDLC agents (Miriam, Yosef, Bezalel...) + 30 SDLC workflows, BWML DSL |
-| **0.9.0** | 2026-06-24 | 🚀 **Augmented & Secure** — 3 new packs (animated, backup, seo), P0 security remediation, 143/143 tests |
-| **0.8.0** | 2026-06-24 | 🚀 **Augmented & Secure** — 3 new packs (animated, backup, seo), P0 security remediation, 143/143 tests |
+| **0.8.0** | 2026-06-24 | 🚀 **Augmented** — 3 new packs (animated, backup, seo), security remediation pass, i18n sync |
+| **0.9.0** | 2026-06-24 | 🔒 **Secure** — audit remediation cycle, npm audit clean, shared pack registry (`lib/packs.js`) |
 
 See [CHANGELOG.md](CHANGELOG.md) for full details.
 

package/osint-agent-package/README.md

@@ -1,88 +1,88 @@
-# 🔍 OSINT Agent Package — BMAD Compatible
-
-Agent d'intelligence OSINT pour les installations BMAD. De un nom ou pseudo à un dossier complet avec psychoprofil, parcours professionnel et grades de confiance.
-
-## Features
-- 🔎 Investigation complète Phase 0→6 (recherche → dossier formaté)
-- 🧠 Psychoprofile MBTI / Big Five
-- 📊 55+ Apify actors (Instagram, LinkedIn, Facebook, TikTok, YouTube...)
-- 🌐 7 APIs de recherche (Perplexity, Exa, Tavily, Jina, Parallel, BrightData)
-- ⚡ Recherche parallèle multi-moteurs
-- 🐍 **100% Python stdlib** — zéro dépendance externe
-- 🖥️ **Cross-platform** — Windows, macOS, Linux
-
-## Prérequis
-- Python 3.10+
-- BMAD Method installé
-- Au minimum 1 clé API (voir [SETUP_KEYS.md](SETUP_KEYS.md))
-
-## Installation rapide
-
-### Option 1 : Script automatique (Windows)
-```powershell
-.\install.ps1
-```
-
-### Option 2 : Manuel
-1. Copier l'agent dans BMAD :
-```
-agents/osint-investigator.md  →  {project}/_bmad/bmm/agents/
-```
-
-2. Copier les 2 skills :
-```
-skills/bmad-osint-investigator/  →  {project}/.agents/skills/
-skills/bmad-osint-investigate/   →  {project}/.agents/skills/
-```
-
-3. Configurer les clés API (voir [SETUP_KEYS.md](SETUP_KEYS.md))
-
-4. Tester :
-```
-python skills/bmad-osint-investigate/osint/scripts/diagnose.py
-```
-
-## Utilisation
-1. Invoquer le skill `bmad-osint-investigator` dans votre AI agent
-2. L'agent "Shadow" s'active avec son menu :
-   - `[INV]` Investigation complète
-   - `[QS]` Recherche rapide
-   - `[LI]` Scrape LinkedIn
-   - `[IG]` Scrape Instagram
-   - `[PP]` Psychoprofile
-   - `[CE]` Enrichissement contact
-   - `[DG]` Diagnostic outils
-
-## Structure du package
-```
-osint-agent-package/
-├── README.md               ← Ce fichier
-├── SETUP_KEYS.md            ← Guide de configuration des clés API
-├── install.ps1              ← Script d'installation (Windows)
-├── install.sh               ← Script d'installation (macOS/Linux)
-├── agents/
-│   └── osint-investigator.md   ← Agent BMAD "Shadow"
-└── skills/
-    ├── bmad-osint-investigator/
-    │   └── SKILL.md            ← Point d'entrée agent
-    └── bmad-osint-investigate/
-        ├── SKILL.md            ← Skill d'investigation
-        └── osint/
-            ├── SKILL.md        ← Pipeline complet (452 lignes)
-            ├── assets/         ← Template dossier
-            ├── references/     ← Docs plateformes, outils, psycho
-            └── scripts/        ← 10 scripts Python (stdlib only)
-```
-
-## Sécurité
-- ✅ Audit de sécurité complet réalisé (14 fichiers analysés)
-- ✅ Aucun trojan, backdoor, ou code malveillant
-- ✅ Zéro dépendance externe — uniquement Python stdlib
-- ✅ Les clés API restent locales (variables d'environnement)
-
-## Crédits
-- Pipeline OSINT basé sur [smixs/osint-skill](https://github.com/smixs/osint-skill) (MIT License)
-- Apify Actor Runner intégré de [apify/agent-skills](https://github.com/apify/agent-skills) (MIT License)
-
-## Licence
-MIT
+# 🔍 OSINT Agent Package — BMAD Compatible
+
+Agent d'intelligence OSINT pour les installations BMAD. De un nom ou pseudo à un dossier complet avec psychoprofil, parcours professionnel et grades de confiance.
+
+## Features
+- 🔎 Investigation complète Phase 0→6 (recherche → dossier formaté)
+- 🧠 Psychoprofile MBTI / Big Five
+- 📊 55+ Apify actors (Instagram, LinkedIn, Facebook, TikTok, YouTube...)
+- 🌐 7 APIs de recherche (Perplexity, Exa, Tavily, Jina, Parallel, BrightData)
+- ⚡ Recherche parallèle multi-moteurs
+- 🐍 **100% Python stdlib** — zéro dépendance externe
+- 🖥️ **Cross-platform** — Windows, macOS, Linux
+
+## Prérequis
+- Python 3.10+
+- BMAD Method installé
+- Au minimum 1 clé API (voir [SETUP_KEYS.md](SETUP_KEYS.md))
+
+## Installation rapide
+
+### Option 1 : Script automatique (Windows)
+```powershell
+.\install.ps1
+```
+
+### Option 2 : Manuel
+1. Copier l'agent dans BMAD :
+```
+agents/osint-investigator.md  →  {project}/_bmad/bmm/agents/
+```
+
+2. Copier les 2 skills :
+```
+skills/bmad-osint-investigator/  →  {project}/.agents/skills/
+skills/bmad-osint-investigate/   →  {project}/.agents/skills/
+```
+
+3. Configurer les clés API (voir [SETUP_KEYS.md](SETUP_KEYS.md))
+
+4. Tester :
+```
+python skills/bmad-osint-investigate/osint/scripts/diagnose.py
+```
+
+## Utilisation
+1. Invoquer le skill `bmad-osint-investigator` dans votre AI agent
+2. L'agent "Shadow" s'active avec son menu :
+   - `[INV]` Investigation complète
+   - `[QS]` Recherche rapide
+   - `[LI]` Scrape LinkedIn
+   - `[IG]` Scrape Instagram
+   - `[PP]` Psychoprofile
+   - `[CE]` Enrichissement contact
+   - `[DG]` Diagnostic outils
+
+## Structure du package
+```
+osint-agent-package/
+├── README.md               ← Ce fichier
+├── SETUP_KEYS.md            ← Guide de configuration des clés API
+├── install.ps1              ← Script d'installation (Windows)
+├── install.sh               ← Script d'installation (macOS/Linux)
+├── agents/
+│   └── osint-investigator.md   ← Agent BMAD "Shadow"
+└── skills/
+    ├── bmad-osint-investigator/
+    │   └── SKILL.md            ← Point d'entrée agent
+    └── bmad-osint-investigate/
+        ├── SKILL.md            ← Skill d'investigation
+        └── osint/
+            ├── SKILL.md        ← Pipeline complet (452 lignes)
+            ├── assets/         ← Template dossier
+            ├── references/     ← Docs plateformes, outils, psycho
+            └── scripts/        ← 10 scripts Python (stdlib only)
+```
+
+## Sécurité
+- ✅ Audit de sécurité complet réalisé (14 fichiers analysés)
+- ✅ Aucun trojan, backdoor, ou code malveillant
+- ✅ Zéro dépendance externe — uniquement Python stdlib
+- ✅ Les clés API restent locales (variables d'environnement)
+
+## Crédits
+- Pipeline OSINT basé sur [smixs/osint-skill](https://github.com/smixs/osint-skill) (MIT License)
+- Apify Actor Runner intégré de [apify/agent-skills](https://github.com/apify/agent-skills) (MIT License)
+
+## Licence
+MIT