docs: correct the install instructions and the repository layout

The Quick start told Hermes users to copy the workflows as loose .md files
into ~/.hermes/skills/software-development/. Hermes indexes skills by
walking for SKILL.md, so those files were never listed and never loaded.
Reproduced with the real loader (agent.skill_utils.iter_skill_index_files)
against a scratch HERMES_HOME: the documented command indexed 0 of 5
workflows, the loop now documented indexes 5 of 5.

- README.md / README.pt-BR.md: one loop for both agents, with SKILLS_DIR
  swapped for Claude Code; install verification hint (hermes skills list).
- README layout tree: five workflows (wf-readme.md was missing), the whole
  vendored skills/ tree, and the actual qa/ contents.
- The snapshot provenance claim listed base-364/v2/v3/v4 as if they lived
  in qa/snapshots/, but only baseline-final.json is committed; corrected,
  and it is now named as the file the gates read.
- Documented that api-security-review is two unrelated skills sharing one
  name (OWASP vendored vs apisec-inc external).
- docs/SKILLS.md: the Claude Code block did mkdir -p "~/.claude/..." with
  the tilde inside quotes, which creates a literal "~" directory instead of
  expanding; replaced with $HOME. Also corrected the claim that only Claude
  Code needs a per-skill directory.

Verified: installing from both documented blocks into a scratch HOME yields
15/15 skills indexed and carries the support files along.

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
+# 1. Copy the workflows into your agent's skills directory.
-# Hermes Agent:
+# Each skill needs its own directory containing a SKILL.md -- a loose .md
-cp workflows/*.md ~/.hermes/skills/software-development/
+# 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"
+  mkdir -p "$SKILLS_DIR/$name"
-  cp "$f" "$HOME/.claude/skills/$name/SKILL.md"
+  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
+# vendored in skills/ -- no external clone needed, just copy:
-# Claude Code use the same loop as step 1, swapping "workflows" for "skills"):
+cp -r skills/* "$HOME/.hermes/skills/"
-cp -r skills/* ~/.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

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
+# 1. Copie os workflows pro diretório de skills do seu agente.
-# Hermes Agent:
+# Cada skill precisa do seu próprio diretório com um SKILL.md dentro -- um
-cp workflows/*.md ~/.hermes/skills/software-development/
+# .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"
+  mkdir -p "$SKILLS_DIR/$nome"
-  cp "$f" "$HOME/.claude/skills/$nome/SKILL.md"
+  cp "$f" "$SKILLS_DIR/$nome/SKILL.md"
 done
 
-# 2. (Opcional, pro security review) as skills de apoio ja vem vendorizadas
+# 2. (Opcional, pro security review) as skills de apoio já vêm vendorizadas
-# em skills/ -- sem clone externo, so copiar (Hermes; pra Claude Code use o
+# em skills/ -- sem clone externo, só copiar:
-# mesmo loop do passo 1 trocando "workflows" por "skills"):
+cp -r skills/* "$HOME/.hermes/skills/"
-cp -r skills/* ~/.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

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
+com um `SKILL.md` dentro, e esse diretório é obrigatório nos dois agentes
-Claude Code, em `~/.claude/skills/<nome>/SKILL.md` (subdiretório por skill —
+(a skill é `<nome>/SKILL.md`, nunca um `.md` solto, que não é indexado):
-Claude Code não carrega arquivo `.md` solto, precisa do diretório).
+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")
+  cp -r "$d" "$HOME/.claude/skills/"
-  [ "$nome" = "NOTICE.md" ] && continue
-  mkdir -p "~/.claude/skills/$nome"
-  cp -r "$d." "~/.claude/skills/$nome/"
 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):