diff --git a/README.md b/README.md
index f8e162e..d3b59de 100644
--- a/README.md
+++ b/README.md
@@ -119,6 +119,8 @@ _Also vendored under `skills/`._
 | [`api-security-review`](https://github.com/apisec-inc/apisec-skills) | Full OWASP API Top 10 review. | [apisec-inc](https://github.com/apisec-inc) |
 | [`security-test-generator`](https://github.com/apisec-inc/apisec-skills) | Generates security test suites. | [apisec-inc](https://github.com/apisec-inc) |
 
+> ⚠️ `api-security-review` is two unrelated skills sharing one name: the OWASP one vendored in `skills/` (security pillar, above) and the apisec-inc one in this table. Only the OWASP copy ships in this repository. Install the one your workflow needs — with both present, agents that resolve by skill name report a collision.
+
 ### 🏗️ Architecture
 
 | Skill | What it does | Owner |
@@ -133,28 +135,31 @@ _Also vendored under `skills/`._
 ## Quick start
 
 ```bash
-# 1. Copy workflows into your agent's skills directory
-# Hermes Agent:
-cp workflows/*.md ~/.hermes/skills/software-development/
+# 1. Copy the workflows into your agent's skills directory.
+# Each skill needs its own directory containing a SKILL.md -- a loose .md
+# file sitting in a category folder is not indexed (neither Hermes nor
+# Claude Code loads it), so the loop below builds the right shape.
+SKILLS_DIR="$HOME/.hermes/skills/software-development"
+# Claude Code: SKILLS_DIR="$HOME/.claude/skills"
 
-# Claude Code: each skill needs its own directory (won't load a loose .md)
-mkdir -p ~/.claude/skills
 for f in workflows/*.md; do
   name=$(basename "$f" .md)
-  mkdir -p "$HOME/.claude/skills/$name"
-  cp "$f" "$HOME/.claude/skills/$name/SKILL.md"
+  mkdir -p "$SKILLS_DIR/$name"
+  cp "$f" "$SKILLS_DIR/$name/SKILL.md"
 done
 
 # 2. (Optional, for security review) the supporting skills are already
-# vendored in skills/ -- no external clone needed, just copy (Hermes; for
-# Claude Code use the same loop as step 1, swapping "workflows" for "skills"):
-cp -r skills/* ~/.hermes/skills/
+# vendored in skills/ -- no external clone needed, just copy:
+cp -r skills/* "$HOME/.hermes/skills/"
 
 # 3. Use it
 # "review this PR for security"  -> wf-security-review loads
 # "build a new page"              -> wf-frontend loads
 ```
 
+Verify the install took: the workflows should show up in your agent's skill
+list (`hermes skills list` for Hermes Agent).
+
 ## The QA harness
 
 The `qa/` directory keeps the workflows themselves honest:
@@ -171,7 +176,7 @@ The meta-tests are the interesting part. They deliberately break the harness and
 
 ## Quality tests and measured gains
 
-These are real numbers from the harness runs, stored in `qa/snapshots/`. The baseline column is the state before the refinement work; the final column is the result after it.
+These are real numbers from the harness runs, stored in `qa/snapshots/baseline-final.json`. The baseline column is the state before the refinement work; the final column is the result after it.
 
 ### Workflow quality score (same harness, before → after)
 
@@ -185,7 +190,7 @@ These are real numbers from the harness runs, stored in `qa/snapshots/`. The bas
 
 That is almost exactly double the quality of the workflows, measured with the same ruler.
 
-The ruler itself also grew stricter over the project (13 → 30+ criteria: verification per phase, real commands, anti-patterns, acceptance criteria, artifacts, flow). That is why the early snapshots show lower totals: `base-364` (13 criteria) → `baseline-v2` (536.7) → `baseline-v3` (675.0) → `baseline-v4` (884.6) → `baseline-final` (1613.2 with four workflows). The fair before/after comparison above uses the final ruler for both sides.
+The ruler itself also grew stricter over the project (13 → 30+ criteria: verification per phase, real commands, anti-patterns, acceptance criteria, artifacts, flow). That is why the early runs show lower totals: `base-364` (13 criteria) → `baseline-v2` (536.7) → `baseline-v3` (675.0) → `baseline-v4` (884.6) → `baseline-final` (1613.2 across the four scored workflows). Only the final snapshot is committed, as `qa/snapshots/baseline-final.json` — that is the file the gates read and the file to update when scoring changes. The fair before/after comparison above uses the final ruler for both sides.
 
 ### Gates (regression checks): all green
 
@@ -218,11 +223,23 @@ The harness has a physical ceiling (sum of all criterion caps). The numeric "2×
 dev-workflows/
 ├── README.md            # this file
 ├── README.pt-BR.md      # Portuguese version
-├── workflows/           # the four SKILL.md workflows
+├── workflows/           # the five SKILL.md workflows
 │   ├── wf-frontend.md
 │   ├── wf-backend.md
 │   ├── wf-architecture.md
-│   └── wf-security-review.md
+│   ├── wf-security-review.md
+│   └── wf-readme.md
+├── skills/              # the security pillar, vendored (see skills/NOTICE.md)
+│   ├── safedeps/        #   + plays/, templates/, schemas/, docs/ support files
+│   ├── sca-audit/
+│   ├── code-review-security/
+│   ├── api-security-review/
+│   ├── web-security-review/
+│   ├── secrets-scan/
+│   ├── cve-triage/
+│   ├── patch-prioritization/
+│   ├── dependency-scanning/
+│   └── hermaguard/
 ├── docs/
 │   └── SKILLS.md        # full skill inventory + install steps
 ├── CONTRIBUTING.md      # what to improve, local checks, PR process
@@ -230,7 +247,9 @@ dev-workflows/
     ├── wf_quality_harness.py
     ├── test_quality.py
     ├── test_tests.py
+    ├── baseline.json
     └── snapshots/
+        └── baseline-final.json
 ```
 
 ## License
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 0eb6c6a..b7b9058 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -119,6 +119,8 @@ _Também vendorizadas em `skills/`._
 | [`api-security-review`](https://github.com/apisec-inc/apisec-skills) | Review completo OWASP API Top 10. | [apisec-inc](https://github.com/apisec-inc) |
 | [`security-test-generator`](https://github.com/apisec-inc/apisec-skills) | Gera suítes de testes de segurança. | [apisec-inc](https://github.com/apisec-inc) |
 
+> ⚠️ `api-security-review` são duas skills diferentes com o mesmo nome: a da OWASP vendorizada em `skills/` (pilar de segurança, acima) e a da apisec-inc nesta tabela. Só a cópia da OWASP vem neste repositório. Instale a que o seu workflow precisa -- com as duas presentes, agentes que resolvem por nome de skill acusam colisão.
+
 ### 🏗️ Arquitetura
 
 | Skill | O que faz | Dono |
@@ -133,28 +135,31 @@ _Também vendorizadas em `skills/`._
 ## Começo rápido
 
 ```bash
-# 1. Copie os workflows pro diretório de skills do seu agente
-# Hermes Agent:
-cp workflows/*.md ~/.hermes/skills/software-development/
+# 1. Copie os workflows pro diretório de skills do seu agente.
+# Cada skill precisa do seu próprio diretório com um SKILL.md dentro -- um
+# .md solto numa pasta de categoria não é indexado (nem o Hermes nem o
+# Claude Code carregam), por isso o loop abaixo monta a estrutura certa.
+SKILLS_DIR="$HOME/.hermes/skills/software-development"
+# Claude Code: SKILLS_DIR="$HOME/.claude/skills"
 
-# Claude Code: cada skill no seu proprio diretorio (nao aceita .md solto)
-mkdir -p ~/.claude/skills
 for f in workflows/*.md; do
   nome=$(basename "$f" .md)
-  mkdir -p "$HOME/.claude/skills/$nome"
-  cp "$f" "$HOME/.claude/skills/$nome/SKILL.md"
+  mkdir -p "$SKILLS_DIR/$nome"
+  cp "$f" "$SKILLS_DIR/$nome/SKILL.md"
 done
 
-# 2. (Opcional, pro security review) as skills de apoio ja vem vendorizadas
-# em skills/ -- sem clone externo, so copiar (Hermes; pra Claude Code use o
-# mesmo loop do passo 1 trocando "workflows" por "skills"):
-cp -r skills/* ~/.hermes/skills/
+# 2. (Opcional, pro security review) as skills de apoio já vêm vendorizadas
+# em skills/ -- sem clone externo, só copiar:
+cp -r skills/* "$HOME/.hermes/skills/"
 
 # 3. Use
 # "review this PR for security"  -> wf-security-review carrega
 # "build a new page"              -> wf-frontend carrega
 ```
 
+Pra conferir se a instalação pegou: os workflows devem aparecer na lista de
+skills do agente (`hermes skills list` no Hermes Agent).
+
 ## O harness de QA
 
 O diretório `qa/` mantém os próprios workflows honestos:
@@ -171,7 +176,7 @@ Os meta-testes são a parte legal. Eles quebram o harness e os workflows de prop
 
 ## Testes de qualidade e ganhos medidos
 
-Números reais das execuções do harness, guardados em `qa/snapshots/`. A coluna "Antes" é o estado anterior ao refinamento; "Depois" é o resultado após ele.
+Números reais das execuções do harness, guardados em `qa/snapshots/baseline-final.json`. A coluna "Antes" é o estado anterior ao refinamento; "Depois" é o resultado após ele.
 
 ### Score de qualidade dos workflows (mesma régua, antes → depois)
 
@@ -185,7 +190,7 @@ Números reais das execuções do harness, guardados em `qa/snapshots/`. A colun
 
 Isso é quase exatamente o dobro da qualidade dos workflows, medido com a mesma régua.
 
-A própria régua também ficou mais exigente ao longo do projeto (13 → 30+ critérios: verificação por fase, comandos reais, anti-padrões, critérios de aceite, artefatos, fluxo). Por isso os snapshots antigos mostram totais menores: `base-364` (13 critérios) → `baseline-v2` (536.7) → `baseline-v3` (675.0) → `baseline-v4` (884.6) → `baseline-final` (1613.2 com quatro workflows). A comparação justa acima usa a régua final dos dois lados.
+A própria régua também ficou mais exigente ao longo do projeto (13 → 30+ critérios: verificação por fase, comandos reais, anti-padrões, critérios de aceite, artefatos, fluxo). Por isso as execuções antigas mostram totais menores: `base-364` (13 critérios) → `baseline-v2` (536.7) → `baseline-v3` (675.0) → `baseline-v4` (884.6) → `baseline-final` (1613.2 nos quatro workflows pontuados). Só o snapshot final está commitado, em `qa/snapshots/baseline-final.json` -- é ele que os gates leem e é ele que se atualiza quando a pontuação muda. A comparação justa acima usa a régua final dos dois lados.
 
 ### Gates (checagens de regressão): todos verdes
 
@@ -218,11 +223,23 @@ O harness tem um teto físico (soma dos caps dos critérios). A meta numérica d
 dev-workflows/
 ├── README.md            # versão em inglês
 ├── README.pt-BR.md      # este arquivo
-├── workflows/           # os quatro workflows em SKILL.md
+├── workflows/           # os cinco workflows em SKILL.md
 │   ├── wf-frontend.md
 │   ├── wf-backend.md
 │   ├── wf-architecture.md
-│   └── wf-security-review.md
+│   ├── wf-security-review.md
+│   └── wf-readme.md
+├── skills/              # o pilar de segurança, vendorizado (ver skills/NOTICE.md)
+│   ├── safedeps/        #   + arquivos de apoio plays/, templates/, schemas/, docs/
+│   ├── sca-audit/
+│   ├── code-review-security/
+│   ├── api-security-review/
+│   ├── web-security-review/
+│   ├── secrets-scan/
+│   ├── cve-triage/
+│   ├── patch-prioritization/
+│   ├── dependency-scanning/
+│   └── hermaguard/
 ├── docs/
 │   └── SKILLS.md        # inventário completo de skills + instalação
 ├── CONTRIBUTING.md      # o que melhorar, checks locais, processo de PR
@@ -230,7 +247,9 @@ dev-workflows/
     ├── wf_quality_harness.py
     ├── test_quality.py
     ├── test_tests.py
+    ├── baseline.json
     └── snapshots/
+        └── baseline-final.json
 ```
 
 ## Licença
diff --git a/docs/SKILLS.md b/docs/SKILLS.md
index 6c71c82..499367b 100644
--- a/docs/SKILLS.md
+++ b/docs/SKILLS.md
@@ -1,9 +1,10 @@
 # Skills usadas e de onde vieram
 
 Este é o inventário do que os workflows carregam. Cada skill é um diretório
-com um `SKILL.md`; para o Hermes Agent, vão em `~/.hermes/skills/`; para
-Claude Code, em `~/.claude/skills/<nome>/SKILL.md` (subdiretório por skill —
-Claude Code não carrega arquivo `.md` solto, precisa do diretório).
+com um `SKILL.md` dentro, e esse diretório é obrigatório nos dois agentes
+(a skill é `<nome>/SKILL.md`, nunca um `.md` solto, que não é indexado):
+no Hermes Agent, em `~/.hermes/skills/<nome>/SKILL.md`; no Claude Code, em
+`~/.claude/skills/<nome>/SKILL.md`.
 
 ## Workflows orquestradores (em `workflows/`)
 
@@ -91,15 +92,16 @@ clone externo. Copie direto:
 cp -r skills/* ~/.hermes/skills/
 
 # Claude Code (cada skill no seu próprio diretório):
-mkdir -p ~/.claude/skills
+mkdir -p "$HOME/.claude/skills"
 for d in skills/*/; do
-  nome=$(basename "$d")
-  [ "$nome" = "NOTICE.md" ] && continue
-  mkdir -p "~/.claude/skills/$nome"
-  cp -r "$d." "~/.claude/skills/$nome/"
+  cp -r "$d" "$HOME/.claude/skills/"
 done
 ```
 
+Os arquivos de apoio que cada skill referencia (`plays/`, `templates/`,
+`schemas/`, `docs/`) ficam dentro do diretório da própria skill, então o
+`cp -r` os leva junto. Origem e licença de cada um: `skills/NOTICE.md`.
+
 **Frontend/backend/arquitetura** (ainda não vendorizadas, instalam de fora):
 a maioria via `npx skills` (formato agentskills.io):