bmad-plus 0.23.0 → 0.23.1

package/src/bmad-plus/agents/agent-maker/SKILL.md

@@ -135,20 +135,33 @@ pack: {pack-name}
 ```
 
 #### 3. `pack-definition.yaml`
-A ready-to-merge snippet for `module.yaml`:
+A ready-to-merge snippet for the `packs:` mapping of `registry.yaml`, the single source of truth
+for packs and agents. `order` must be an integer no other pack uses, `cli.icon` a non-empty
+string, and `summary` must not hard-code a count of agents, skills or workflows (the build
+derives those):
 
 ```yaml
 {pack-name}:
-  name: "{Pack Display Name}"
-  icon: "{icon}"
-  description: "{description}"
+  order: {next free integer}
+  display_name: "{Pack Display Name}"
+  icon_emoji: "{icon}"
+  cli: { name: "{Short CLI name}", icon: "{one letter}", desc: "{CLI description}" }
   required: false
-  agents:
-    - agent-{name}
+  runtime: [node]
+  summary: "{one sentence, no counts}"
+  agents: [agent-{name}]
+  personas:
+    - { id: agent-{name}, name: {PersonaName}, role: {Title}, description: "{description}" }
   skills: []
-  required_keys: []  # if any API keys needed
+  install_layout: loose
+  compliance_tags: []
+  required_keys: []  # only if API keys are needed
 ```
 
+`install_layout: loose` copies the agent directory `agents/agent-{name}/` into the project. A
+pack that ships its files in one folder uses `install_layout: packaged` with `pack_dir`,
+`pack_src_dir` and `doctor.pack_agents` instead: see the existing `backup` entry.
+
 #### 4. `INTEGRATION.md`
 Instructions for integrating the agent into BMAD+:
 
@@ -158,14 +171,26 @@ Instructions for integrating the agent into BMAD+:
 ## Files to copy
 - `agents/agent-{name}/` → `src/bmad-plus/agents/agent-{name}/`
 
-## module.yaml update
-Add the pack definition from `pack-definition.yaml` to the `packs:` section.
+## Register the pack (registry first)
+`registry.yaml` is the single source of truth. Never edit the files generated from it
+(`tools/cli/lib/packs.js`, the pack metadata of `src/bmad-plus/module.yaml`, `AGENTS.md` and the
+other adapters).
+- New pack: add the entry from `pack-definition.yaml` under `packs:` in `registry.yaml`.
+- New agent in an existing pack: add its id to that pack's `agents:` list and a line to its
+  `personas:` list (and to `doctor.pack_agents` when the pack uses the packaged layout).
 
 ## module-help.csv update
-Add: bmad-plus-agent-{name},"{help text}"
-
-## installer update
-Add pack to `PACKS` object in `tools/cli/commands/install.js`
+This file is maintained by hand. Add to `src/bmad-plus/module-help.csv`:
+bmad-plus-agent-{name},"{help text}"
+
+## Regenerate and check
+From the repository root, in this order:
+1. `npm run build` regenerates `tools/cli/lib/packs.js` and `src/bmad-plus/module.yaml`.
+2. `node tools/build/generate-adapters.js --adopt` regenerates `AGENTS.md` and the tool adapters
+   (`CLAUDE.md`, `GEMINI.md`, ...) with the new roster.
+3. `npm run build:check`, `node tools/build/generate-adapters.js --check --adopt` and
+   `npm run check:counts` must report no drift; `npm run check:triggers` too if you added
+   role triggers to `src/bmad-plus/data/role-triggers.yaml`.
 
 ## Test
 Run `npx bmad-plus install --packs {pack-name}` in a test project.
@@ -175,7 +200,7 @@ Run `npx bmad-plus install --packs {pack-name}` in a test project.
 After generating, run a self-check:
 - [ ] SKILL.md follows v6 format
 - [ ] Manifest has all required fields
-- [ ] Pack definition is valid YAML
+- [ ] Pack definition is a valid `registry.yaml` pack entry (unique `order`, `cli`, `personas`)
 - [ ] Capabilities have unique 2-letter codes
 - [ ] Integration guide is complete
 

package/src/bmad-plus/module.yaml

@@ -22,7 +22,7 @@ install_packs:
     - value: maker
       label: 🧬 Agent Creator — Design, build, validate, and package new BMAD+-compatible agents.
     - value: shield
-      label: 🛡️ Shield — GRC Compliance — 27 compliance agents + 11 workflows across 26+ frameworks.
+      label: 🛡️ Shield — GRC Compliance — 27 compliance agents + 11 workflows across 27+ frameworks.
     - value: seo
       label: 🔍 SEO Audit 360 — 3 agents (Scout, Chief, Judge) + 6-phase audit + PageSpeed loop.
     - value: memory
@@ -136,13 +136,14 @@ packs:
       - agent-shadow
     skills: []
     external_package: osint-agent-package
-    required_keys:
-      - APIFY_API_TOKEN
     optional_keys:
+      - APIFY_API_TOKEN
       - PERPLEXITY_API_KEY
       - EXA_API_KEY
       - TAVILY_API_KEY
       - JINA_API_KEY
+      - PARALLEL_API_KEY
+      - BRIGHTDATA_MCP_URL
   maker:
     name: Agent Creator
     icon: 🧬
@@ -155,7 +156,7 @@ packs:
   shield:
     name: Shield — GRC Compliance
     icon: 🛡️
-    description: 27 compliance agents + 11 workflows across 26+ frameworks.
+    description: 27 compliance agents + 11 workflows across 27+ frameworks.
     required: false
     agents:
       - shield-orchestrator

package/src/bmad-plus/packs/pack-animated/animated-website-agent.md

@@ -7,10 +7,12 @@ Tu es un expert en création de sites web animés de luxe. Tu convertis des vid
 Déclenché par les requêtes contenant : "animated website", "scroll animation", "video to website", "Apple-style page", "scroll-driven site", "frame animation", "convert video to website", "luxury website from video", "site animé", "animation scroll".
 
 ## Pré-requis
-- FFmpeg + FFprobe installés
-- Python 3
+- FFmpeg + FFprobe installés, avec l'encodeur `libwebp` (vérification : `ffmpeg -hide_banner -encoders`, la liste doit contenir `libwebp`)
+- Python 3 (uniquement pour l'aperçu local de l'étape 5 ; tout autre serveur de fichiers statiques convient)
 - Fichier vidéo MP4 source
 
+Ce pack ne livre aucun script d'extraction : les frames s'extraient avec les commandes FFmpeg de l'étape 2.
+
 ---
 
 ## Processus Complet
@@ -44,24 +46,38 @@ Recommander le nombre de frames :
 
 ### Étape 2 — Extraire et optimiser les frames
 
-Utiliser le script `extract_frames.py` :
+Deux commandes FFmpeg suffisent (aucun script à installer). Soit `D` la durée en secondes relevée à l'étape 1 et `N` le nombre de frames confirmé par l'utilisateur ; le filtre `fps=N/D` échantillonne la vidéo à intervalles réguliers et `-frames:v N` plafonne la sortie à `N` images. Créer d'abord les dossiers de sortie, FFmpeg ne les crée pas.
+
+Durée de la vidéo, si elle n'a pas été relevée :
+```bash
+ffprobe -v error -show_entries format=duration -of csv=p=0 "/path/to/video.mp4"
+```
 
-**Windows :**
+**Windows (PowerShell) :**
 ```powershell
-python scripts/extract_frames.py --input "C:/path/to/video.mp4" --output "output/frames" --frames 120 --quality 80
+New-Item -ItemType Directory -Force "output/frames/desktop", "output/frames/mobile"
+ffmpeg -i "C:/path/to/video.mp4" -vf "fps=120/12.4,scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080" -c:v libwebp -quality 80 -compression_level 6 -frames:v 120 -start_number 0 "output/frames/desktop/frame-%04d.webp"
+ffmpeg -i "C:/path/to/video.mp4" -vf "fps=120/12.4,scale=960:540:force_original_aspect_ratio=increase,crop=960:540" -c:v libwebp -quality 80 -compression_level 6 -frames:v 120 -start_number 0 "output/frames/mobile/frame-%04d.webp"
 ```
 
 **Mac/Linux :**
 ```bash
-python3 scripts/extract_frames.py --input "/path/to/video.mp4" --output "output/frames" --frames 120 --quality 80
+mkdir -p output/frames/desktop output/frames/mobile
+ffmpeg -i "/path/to/video.mp4" -vf "fps=120/12.4,scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080" -c:v libwebp -quality 80 -compression_level 6 -frames:v 120 -start_number 0 "output/frames/desktop/frame-%04d.webp"
+ffmpeg -i "/path/to/video.mp4" -vf "fps=120/12.4,scale=960:540:force_original_aspect_ratio=increase,crop=960:540" -c:v libwebp -quality 80 -compression_level 6 -frames:v 120 -start_number 0 "output/frames/mobile/frame-%04d.webp"
 ```
 
-Le script produit :
-- `frames/desktop/` — WebP 1920x1080
-- `frames/mobile/` — WebP 960x540
-- `frames/manifest.json` — métadonnées
+Les exemples supposent `N = 120` et `D = 12.4` : remplacer `120/12.4` et `-frames:v 120` par les valeurs réelles. `-quality 80` est la qualité WebP (1-100).
+
+Résultat :
+- `frames/desktop/` — WebP 1920x1080, `frame-0000.webp` à `frame-<N-1>.webp`
+- `frames/mobile/` — WebP 960x540, même numérotation
+
+`scale=…:force_original_aspect_ratio=increase,crop=…` remplit le cadre 16:9 et rogne les bords d'une source qui n'est pas en 16:9 ; pour une source verticale, demander à l'utilisateur quel cadrage il veut avant d'extraire.
 
-**Budget payload :** Desktop < 10MB, Mobile < 5MB.
+Écrire ensuite `frames/manifest.json` avec le nombre de frames et le motif de nom (par exemple `{"count":120,"pattern":"frame-%04d.webp","desktop":"1920x1080","mobile":"960x540"}`) : c'est la valeur `FRAME_COUNT` du site généré. Vérifier que le nombre de fichiers de chaque dossier est égal à `N`.
+
+**Budget payload :** Desktop < 10MB, Mobile < 5MB. Mesurer la taille des deux dossiers (`du -sh output/frames/desktop output/frames/mobile`, ou la somme des tailles de fichiers sous PowerShell) avant de continuer.
 
 ### Étape 3 — Contenu des 6 sections
 
@@ -126,6 +142,16 @@ python3 -m http.server 8080
 - **Labels :** DM Sans, 8-9px, weight 500, uppercase, letter-spacing 0.25-0.35em
 - **Hero :** `clamp(42px, 5.5vw, 76px)` — grand mais light
 
+#### Chargement des polices : un choix à faire avec l'utilisateur
+
+Playfair Display et DM Sans ne sont pas embarquées par BMAD+. Avant de générer le site, demander laquelle de ces options l'utilisateur veut (la première si aucune réponse) :
+
+1. **Polices système (défaut).** Ne rien charger : les piles de `--heading` et `--body` ci-dessus retombent sur Georgia et sur la police système. Aucune requête externe.
+2. **Polices auto-hébergées.** L'utilisateur fournit les fichiers `.woff2` (Playfair Display et DM Sans sont sous licence SIL Open Font ; il vérifie la licence de toute autre police), à placer dans le dossier du site et à déclarer avec `@font-face`. Aucune requête vers un tiers.
+3. **Google Fonts.** À n'utiliser que sur demande explicite, après avoir prévenu l'utilisateur que le navigateur de **chaque visiteur du site généré** contactera fonts.googleapis.com et fonts.gstatic.com (son adresse IP est donc transmise à Google) et que cela peut exiger une mention dans la politique de confidentialité du site. Cette requête est une propriété du site généré, pas de BMAD+ : BMAD+ lui-même n'envoie rien à Google.
+
+Balise à insérer uniquement pour l'option 3 :
+
 ```html
 <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,300;0,400;0,500;0,600;1,300;1,400&family=Playfair+Display:ital,wght@0,300;0,400;0,500;0,600;0,700;1,300;1,400&display=swap" rel="stylesheet">
 ```
@@ -213,7 +239,7 @@ Fichier HTML unique. Ordre structurel :
 
 ```
 HTML :
-  1. Google Fonts link
+  1. Chargement des polices (option choisie : système, auto-hébergée ou lien Google Fonts)
   2. <style> — tout le CSS
   3. Cursor custom divs (#cursor-dot, #cursor-ring)
   4. Film grain overlay
@@ -316,8 +342,8 @@ Avant livraison, vérifier :
 | Problème | Solution |
 |---------|---------|
 | FFmpeg non trouvé | `winget install FFmpeg` (Win), `brew install ffmpeg` (Mac) |
-| Pas de libwebp | Reinstaller FFmpeg ou installer Pillow |
-| Frames trop lourdes (>10MB) | `--quality 60` ou `--frames 90` |
+| Pas de libwebp | Installer une build de FFmpeg qui inclut `libwebp` (`ffmpeg -hide_banner -encoders` doit le lister) |
+| Frames trop lourdes (>10MB) | `-quality 60` ou `-frames:v 90` (avec `fps=90/D`) |
 | Animation saccadée | Réduire frames, vérifier DPR cap à 2, réduire particules |
 | Flash blanc entre frames | Vérifier extraction, fallback nearest-frame |
 | Canvas blanc sur mobile | Vérifier existence des frames mobile, chemin FRAME_DIR |

package/src/bmad-plus/packs/pack-animated/templates/animated-website-workflow.md

@@ -8,32 +8,33 @@ Converts an MP4 video into a luxury scroll-driven animated website with canvas f
 
 ## Pre-requisites
 
-1. FFmpeg installed (`winget install FFmpeg` on Windows, `brew install ffmpeg` on Mac)
-2. Python 3 installed
+1. FFmpeg installed, with the `libwebp` encoder (`winget install FFmpeg` on Windows, `brew install ffmpeg` on Mac; `ffmpeg -hide_banner -encoders` must list `libwebp`)
+2. Python 3 installed (only for the local preview in step 6; any static file server works)
 3. Source MP4 video file
 
+This pack ships no extraction script: the frames are extracted with the FFmpeg commands of step 3.
+
 ## Steps
 
 1. Ask the user for:
    - Path to the MP4 video file
    - Website concept (product, real estate, portfolio, etc.)
    - Optional: brand colors, section content, target frame count
+   - How fonts are loaded in the generated site (see step 5)
 
 2. Analyze the video:
 ```bash
 ffprobe -v quiet -print_format json -show_format -show_streams "VIDEO_PATH"
 ```
 
-3. Extract frames using the script:
+3. Extract the frames with FFmpeg. `DURATION` is the video length in seconds from step 2; create the two output folders first (`mkdir -p OUTPUT_DIR/frames/desktop OUTPUT_DIR/frames/mobile`):
 ```bash
-python3 scripts/extract_frames.py \
-  --input "VIDEO_PATH" \
-  --output "OUTPUT_DIR/frames" \
-  --frames FRAME_COUNT \
-  --quality 80
+ffmpeg -i "VIDEO_PATH" -vf "fps=FRAME_COUNT/DURATION,scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080" -c:v libwebp -quality 80 -compression_level 6 -frames:v FRAME_COUNT -start_number 0 "OUTPUT_DIR/frames/desktop/frame-%04d.webp"
+ffmpeg -i "VIDEO_PATH" -vf "fps=FRAME_COUNT/DURATION,scale=960:540:force_original_aspect_ratio=increase,crop=960:540" -c:v libwebp -quality 80 -compression_level 6 -frames:v FRAME_COUNT -start_number 0 "OUTPUT_DIR/frames/mobile/frame-%04d.webp"
 ```
+Then write `OUTPUT_DIR/frames/manifest.json` with the frame count and the file name pattern, and check that each folder holds `FRAME_COUNT` files and stays under the payload budget (desktop under 10 MB, mobile under 5 MB).
 
-4. Generate the complete index.html following the design system in `agent/animated-website-agent.md`:
+4. Generate the complete index.html following the design system in `animated-website-agent.md` (the agent file of this pack):
    - Canvas frame-by-frame scroll animation
    - Scroll dwell engine with Gaussian density
    - 6 overlay sections (Hero, Vision, Details, Grid, Context, CTA)
@@ -42,14 +43,16 @@ python3 scripts/extract_frames.py \
    - Custom cursor, chapter markers, branded loader
    - Gallery with parallax
 
-5. Serve and preview:
+5. Fonts. Use system fonts by default. Self-hosted `.woff2` files are the alternative that sends nothing to a third party. Use Google Fonts only when the user explicitly asks for it, after telling them that each visitor's browser will then contact Google's font servers (this concerns the generated site, not BMAD+).
+
+6. Serve and preview:
 ```bash
 cd OUTPUT_DIR
 python3 -m http.server 8080
 ```
 
-6. Iterate based on user feedback (scroll speed, colors, content, etc.)
+7. Iterate based on user feedback (scroll speed, colors, content, etc.)
 
 ## Reference
 
-See `agent/animated-website-agent.md` for the complete design system, code architecture, and quality checklist.
+See `animated-website-agent.md` for the complete design system, code architecture, and quality checklist.

package/src/bmad-plus/packs/pack-backup/backup-agent.md

@@ -35,7 +35,8 @@ PROJECT_NAME=$(basename "$PROJECT_ROOT")
 mkdir -p "$PROJECT_ROOT/backups"
 cd "$PROJECT_ROOT" && zip -r "backups/${PROJECT_NAME}_backup_$TIMESTAMP.zip" . \
   -x "backups/*" "node_modules/*" ".git/*" "vendor/*" "__pycache__/*" "*.backup_*"
-echo "✅ Backup: ${PROJECT_NAME}_backup_$TIMESTAMP.zip"
+SIZE=$(du -h "backups/${PROJECT_NAME}_backup_$TIMESTAMP.zip" | cut -f1)
+echo "✅ Backup: ${PROJECT_NAME}_backup_$TIMESTAMP.zip ($SIZE)"
 ```
 
 ### 2. `/backup-list` — Lister les backups

package/src/bmad-plus/packs/pack-backup/templates/backup-workflow.md

@@ -40,6 +40,8 @@ PROJECT_NAME=$(basename "$PROJECT_ROOT")
 mkdir -p "$PROJECT_ROOT/backups"
 cd "$PROJECT_ROOT" && zip -r "backups/${PROJECT_NAME}_backup_$TIMESTAMP.zip" . \
   -x "backups/*" "node_modules/*" ".git/*" "vendor/*" "__pycache__/*" "*.backup_*"
+SIZE=$(du -h "backups/${PROJECT_NAME}_backup_$TIMESTAMP.zip" | cut -f1)
+echo "Backup: ${PROJECT_NAME}_backup_$TIMESTAMP.zip ($SIZE)"
 ```
 
 2. Confirm the backup was created and report the file name and size.

package/src/bmad-plus/packs/pack-memory/zecher-agent.md

@@ -101,7 +101,7 @@ You are NOT an orchestrator. You are a **utility agent** — called upon by othe
       Recursively walk the target path
       Identify project roots by marker files (package.json, .git, Cargo.toml, etc.)
       Skip: node_modules, .git internals, vendor, __pycache__, dist, build
-      Depth limit: configurable (default 3 levels)
+      Depth limit: configurable with `bmad-plus scan --depth <n>` (default 4 levels below the scanned directory)
     </step>
     <step n="2" goal="Analyze each project">
       For each discovered project root:

package/src/bmad-plus/packs/pack-shield/README.md

@@ -41,7 +41,7 @@ Pack Shield transforms BMAD+ into a comprehensive GRC (Governance, Risk & Compli
 | Agent | Framework | Jurisdiction |
 |-------|-----------|-------------|
 | `soc2-agent` | SOC 2 Type I/II | US/Global |
-| `pci-dss-agent` | PCI DSS v4.0 | International |
+| `pci-dss-agent` | PCI DSS v4.0.1 | International |
 | `hipaa-agent` | HIPAA | US Healthcare |
 | `swift-csp-agent` | SWIFT CSP | Intl. Banking |
 | `dora-agent` | DORA | EU Financial |

package/src/bmad-plus/packs/pack-shield/SKILL.md

@@ -8,7 +8,7 @@
 
 ## Overview
 
-Shield transforms BMAD+ into a comprehensive GRC (Governance, Risk & Compliance) assistant. It serves as an intelligent orchestrator for 27 compliance agents across 6 categories, plus 11 GDPR & AI Act workflows, covering 25+ regulatory frameworks. Route requests to the appropriate specialist agent, combine insights for cross-framework analysis, and provide consolidated compliance reports.
+Shield transforms BMAD+ into a comprehensive GRC (Governance, Risk & Compliance) assistant. It serves as an intelligent orchestrator for 27 compliance agents across 6 categories, plus 11 GDPR & AI Act workflows, covering 27 regulatory frameworks. Route requests to the appropriate specialist agent, combine insights for cross-framework analysis, and provide consolidated compliance reports.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Shield transforms BMAD+ into a comprehensive GRC (Governance, Risk & Compliance)
 
 ### Industry Compliance (6 frameworks)
 - **SOC 2 Type I/II** — Service Organization Controls
-- **PCI DSS v4.0** — Payment Card Industry
+- **PCI DSS v4.0.1** — Payment Card Industry
 - **HIPAA** — Healthcare Privacy & Security
 - **SWIFT CSP** — Banking Security
 - **DORA** — EU Digital Operational Resilience
@@ -66,7 +66,7 @@ Shield transforms BMAD+ into a comprehensive GRC (Governance, Risk & Compliance)
 To use Shield, include this pack in your BMAD+ installation:
 
 ```bash
-npx bmad-plus install --pack shield
+npx bmad-plus install --packs shield
 ```
 
 Then invoke the orchestrator from any conversation:

package/src/bmad-plus/packs/pack-shield/categories/industry-compliance/pci-dss-agent.md

@@ -1,7 +1,7 @@
 # PCI DSS Compliance Agent
 
 > **Pack:** Shield (GRC Audit) -- Industry Compliance
-> **Framework:** PCI DSS v4.0
+> **Framework:** PCI DSS v4.0.1
 > **Version:** 1.0.0
 > **Based on:** Claude Skills for GRC by Hemant Naik (Sushegaad) -- MIT License
 > **Upstream:** https://github.com/Sushegaad/Claude-Skills-Governance-Risk-and-Compliance

package/src/bmad-plus/packs/pack-shield/shield-orchestrator.md

@@ -11,7 +11,7 @@
 
 ## Persona
 
-You are **Shield**, an expert GRC (Governance, Risk & Compliance) orchestrator. You serve as the intelligent entry point for regulatory and compliance queries. You understand 25+ compliance frameworks and 11 workflow agents. You route requests to the appropriate specialist agent, combine insights from multiple agents for cross-framework analysis, and provide consolidated compliance reports.
+You are **Shield**, an expert GRC (Governance, Risk & Compliance) orchestrator. You serve as the intelligent entry point for regulatory and compliance queries. You understand 27 compliance frameworks and 11 workflow agents. You route requests to the appropriate specialist agent, combine insights from multiple agents for cross-framework analysis, and provide consolidated compliance reports.
 
 ---
 
@@ -40,7 +40,7 @@ You are **Shield**, an expert GRC (Governance, Risk & Compliance) orchestrator.
 | Agent | Framework | Jurisdiction |
 |-------|-----------|-------------|
 | `soc2-agent` | SOC 2 Type I/II | US (global use) |
-| `pci-dss-agent` | PCI DSS v4.0 | International |
+| `pci-dss-agent` | PCI DSS v4.0.1 | International |
 | `hipaa-agent` | HIPAA Privacy & Security | US Healthcare |
 | `swift-csp-agent` | SWIFT CSP | International Banking |
 | `dora-agent` | DORA (EU 2022/2554) | EU Financial |

package/src/bmad-plus/skills/bmad-plus-parallel/SKILL.md

@@ -109,7 +109,7 @@ This skill is automatically invoked by the Autopilot when `{parallel_execution}`
 ## Swarms
 
 Parallel stories share one goal and differ in content; a **swarm** repeats one kind of work
-across many units. Four kinds, one runtime (`bmad-plus swarm`), one moderator skill
+across many units. Three kinds, one runtime (`bmad-plus swarm`), one moderator skill
 (`bmad-plus-swarm`):
 
 | Kind | Units | Substrate |

package/src/bmad-plus/skills/bmad-plus-swarm/SKILL.md

@@ -22,7 +22,7 @@ definition + profile|list|units ─► init ─► cards.json ─► briefs ─
 
 Read `ref/definition.md` for the four file contracts with one example each.
 
-## The four kinds
+## The three kinds
 
 | Kind | Units come from | Typical use | Tally |
 |---|---|---|---|

package/tools/build/adapters.config.js

@@ -72,7 +72,7 @@ const UPDATE_INSTRUCTIONS = [
   '## Framework updates',
   '',
   'Once per session, check the installed framework before starting project work. If this is the BMAD+ source checkout, use `node tools/cli/bmad-plus-cli.js update-check --json`; otherwise use `npx --no-install bmad-plus update-check --json` from the project root.',
-  'If the command is unavailable or the result is off, unknown, offline or stale, continue the user task. Do not install a CLI just to perform this check or claim that an offline version is current.',
+  'If the command is unavailable (for example npx cannot find `bmad-plus` because the project has no local copy of the package), or the result is off, unknown, offline or stale, continue the user task without mentioning the check. Do not install a CLI just to perform this check or claim that an offline version is current.',
   'When `updateAvailable` is true and `canAutoApply` is true, run the same CLI with `update --latest --auto`. This follows the project update policy; it does not grant permission to expand that policy.',
   'When an update is available but automatic application is not eligible, explain the version and reason. An explicit request to update can be fulfilled with `update --latest --yes`; do not change the policy, overwrite customized files, or resolve conflicts without the user request covering that action.',
   'After a successful update, reread the project spine and relevant installed skills, or start a fresh session if the client cannot reload them. Respect preserved local instructions. Check only once even when several adapters include this section.',

package/tools/build/generate-adapters.js

@@ -468,7 +468,7 @@ function userMarkerLines() {
   return [
     '<!-- ' + GENERATED_MARKER + ' — DO NOT EDIT. -->',
     '<!-- ' + USER_CONFIG_MARKER + ' -->',
-    '<!-- Refresh installed adapters with: npx bmad-plus update -->',
+    '<!-- Refresh installed adapters with: npx bmad-plus@latest update -->',
   ];
 }
 

package/tools/cli/commands/install.js

@@ -561,15 +561,15 @@ module.exports = {
       }
 
       if (selectedPacks.includes('seo')) {
-        agentGuide.push(`  ${i.guide_seo.padEnd(28)} →  "/seo audit <url>"`);
+        agentGuide.push(`  ${i.guide_seo.padEnd(28)} →  "/seo full <url>"`);
       }
 
       if (selectedPacks.includes('backup')) {
-        agentGuide.push(`  ${i.guide_backup.padEnd(28)} →  "/backup create"`);
+        agentGuide.push(`  ${i.guide_backup.padEnd(28)} →  "/backup"`);
       }
 
       if (selectedPacks.includes('animated')) {
-        agentGuide.push(`  ${i.guide_animated.padEnd(28)} →  "/animated build <video>"`);
+        agentGuide.push(`  ${i.guide_animated.padEnd(28)} →  "animated website from <video.mp4>"`);
       }
 
       if (selectedPacks.includes('design')) {
@@ -609,7 +609,7 @@ module.exports = {
         '',
         `📦 ${i.guide_cli_title || 'CLI Commands'}:`,
         `  npx bmad-plus install    ${i.guide_cli_install || '— Install agents & skills'}`,
-        `  npx bmad-plus update     ${i.guide_cli_update || '— Update agents (keeps config)'}`,
+        `  npx bmad-plus@latest update ${i.guide_cli_update || '— Update agents (keeps config)'}`,
         `  npx bmad-plus doctor     ${i.guide_cli_doctor || '— Check installation health'}`,
         `  npx bmad-plus uninstall  ${i.guide_cli_uninstall || '— Remove BMAD+ from project'}`
       );
@@ -617,15 +617,15 @@ module.exports = {
       // Add pack-specific examples
       const examples = [];
       if (selectedPacks.includes('seo')) {
-        examples.push(`  ${i.guide_example_seo || '🔍 SEO: "/seo audit https://example.com"'}`);
+        examples.push(`  ${i.guide_example_seo || '🔍 SEO: "/seo full https://example.com"'}`);
       }
       if (selectedPacks.includes('backup')) {
-        examples.push(
-          `  ${i.guide_example_backup || '🗂️  Backup: "/backup create" → ZIP timestamped'}`
-        );
+        examples.push(`  ${i.guide_example_backup || '🗂️  Backup: "/backup" → ZIP timestamped'}`);
       }
       if (selectedPacks.includes('animated')) {
-        examples.push(`  ${i.guide_example_animated || '🎬 Animated: "/animated build hero.mp4"'}`);
+        examples.push(
+          `  ${i.guide_example_animated || '🎬 Animated: "animated website from hero.mp4"'}`
+        );
       }
       if (selectedPacks.includes('design')) {
         examples.push(
@@ -786,6 +786,13 @@ function mergeSettings(existing, defaults, explicit) {
   return merged;
 }
 
+/**
+ * Plain YAML under every supported js-yaml: forceQuotes is avoided because 5.2.x
+ * tags forced scalars (`!!bool 'true'`, `!!int '3'`) while 5.5 does not. Strings that
+ * would read as another type are still quoted by the dumper.
+ */
+const CONFIG_DUMP = { lineWidth: -1, quotingType: '"' };
+
 /** Returns null when the existing file is not a YAML mapping (left untouched). */
 function mergeConfigYaml(existingText, generatedText, explicit = {}) {
   let existing;
@@ -801,7 +808,7 @@ function mergeConfigYaml(existingText, generatedText, explicit = {}) {
     changed: true,
     content:
       '# BMAD+ Project Configuration\n# Generated by bmad-plus install; existing settings preserved\n\n' +
-      yaml.dump(merged, { lineWidth: -1, forceQuotes: true, quotingType: '"' }),
+      yaml.dump(merged, CONFIG_DUMP),
   };
 }
 
@@ -847,7 +854,7 @@ function generateConfigYaml(
         // never covered by a budget, the host always asks.
         swarm: { ...SWARM_DEFAULTS },
       },
-      { lineWidth: -1, forceQuotes: true, quotingType: '"' }
+      CONFIG_DUMP
     )
   );
 }

package/tools/cli/commands/nexus.js

@@ -105,7 +105,8 @@ module.exports = {
       process.exitCode = 1;
       if (options.json)
         console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
-      else console.error('Nexus: ' + error.message);
+      else
+        console.error(/^Nexus: /.test(error.message) ? error.message : 'Nexus: ' + error.message);
     }
   },
 };

package/tools/cli/commands/review.js

@@ -205,7 +205,7 @@ module.exports = {
   options: [
     ['-d, --directory <path>', 'Project directory'],
     ['--dir <path>', 'Review folder inside the project', review.DEFAULT_DIR],
-    ['--base <ref>', 'Base commit or branch (default HEAD~1)'],
+    ['--base <ref>', 'Base commit or branch (default HEAD~1, HEAD with --workspace)'],
     ['--head <ref>', 'Head commit or branch (default HEAD)'],
     ['--workspace', 'Review the working tree, untracked files included, against the base'],
     ['--include <glob>', 'Only review matching paths (repeatable)', (v, all) => [...all, v], []],

package/tools/cli/commands/update.js

@@ -20,7 +20,33 @@ const { planUpdate, applyPlan, restoreUpdate, MANIFEST } = require('../lib/updat
 function authorizeAuto(projectDir, version) {
   const { readUpdatePolicy, authorizeTarget } = require('../lib/update-policy');
   const decision = authorizeTarget(readUpdatePolicy(projectDir), version);
-  if (!decision.allowed) throw new Error('Automatic update refused: ' + decision.reason);
+  if (!decision.allowed) throw require('../lib/update-dispatch').autoRefusal(decision.reason);
+}
+
+// npx runs a cached or project-local copy of the package before it asks the registry, so a plain
+// `update` can install an older release than the published one. Say so instead of staying silent.
+async function warnIfBehindRegistry(projectDir, version) {
+  let check;
+  try {
+    check = await require('../lib/update-check').checkForUpdate({
+      projectDir,
+      runningVersion: version,
+    });
+  } catch {
+    return;
+  }
+  const latest = check.latestVersion;
+  if (!isExactVersion(latest) || !semver.gt(latest, version)) return;
+  clack.log.warn(
+    'This copy of BMAD+ is v' +
+      version +
+      ' but v' +
+      latest +
+      ' is published (npx reuses a cached copy). Stop and run `npx bmad-plus@latest update`, or ' +
+      '`npx bmad-plus update --latest`, to install v' +
+      latest +
+      '.'
+  );
 }
 
 async function confirmAction(options, message, lang = 'en') {
@@ -118,6 +144,9 @@ module.exports = {
         throw new Error('Downgrade refused: ' + manifest.version + ' -> ' + version);
       const lang = options.lang || manifest.uiLanguage || 'en';
       clack.log.info('Installed: v' + manifest.version + ' -> Executing package: v' + version);
+      if (!options.auto && !options.expectedVersion) {
+        await warnIfBehindRegistry(projectDir, version);
+      }
       if (manifest.version === version) {
         clack.log.success(
           'The installed version matches this executing package. Use --latest to check the registry.'