@ngocsangairvds/vsaf 4.1.9 → 4.1.11

package/skills/vds-skill/runtime/docs/agents/how-to/04-using-progress-reports.md

@@ -0,0 +1,240 @@
+<!-- diátaxis: how-to -->
+
+# How To: Generate Progress Reports
+
+## Prerequisites
+
+1. **Repos synced**: `vds-cli audit sync repos --bitbucket-project INSURANCE-AI`
+2. **BMAD knowledge graph**: Must exist at `~/.vds/cache/repos/INSURANCE-AI-project/bmad_ntbh/`
+3. **Database** (optional): Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` for persistence
+
+## Quick Start
+
+```bash
+# Structural-only report (fast, ~2s)
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync
+
+# Check your score
+vds-cli progress db status
+```
+
+## Common Workflows
+
+### Daily Score Check
+
+```bash
+# Generate report and check trend
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
+vds-cli progress db status
+```
+
+### Deep-Dive a Specific FR
+
+```bash
+# FR8 analysis in JSON
+vds-cli progress report -p INSURANCE-AI --fr FR8 --dimensions structural --format json --skip-sync -q
+```
+
+### Scripted/CI Usage
+
+Use `--quiet` (`-q`) and `--format json` for clean machine-readable output:
+
+```bash
+SCORE=$(vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['overall_score'])")
+echo "Current score: $SCORE"
+```
+
+### Resume an Interrupted Run
+
+If a run fails mid-pipeline, the checkpoint is saved in the DB:
+
+```bash
+# The run_id is printed in the log output
+vds-cli progress report -p INSURANCE-AI --resume-run-id <uuid-from-failed-run>
+```
+
+### Topology Exploration
+
+```bash
+# List all FRs in the knowledge graph
+vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
+
+# Count services
+vds-cli progress topology -p INSURANCE-AI -q | jq '.service_catalog | length'
+```
+
+## LLM Provider Selection (Phase 3)
+
+Use `--llm-provider` to control which LLM backend scores dimensions 7-8:
+
+```bash
+# Auto-detect from environment (default)
+vds-cli progress report -p INSURANCE-AI --llm-provider auto
+
+# Explicit provider
+vds-cli progress report -p INSURANCE-AI --llm-provider openai    # requires OPENAI_API_KEY
+vds-cli progress report -p INSURANCE-AI --llm-provider anthropic # requires ANTHROPIC_AUTH_TOKEN
+vds-cli progress report -p INSURANCE-AI --llm-provider ollama    # requires Ollama on localhost:11434
+
+# Disable LLM entirely (equivalent to --dimensions structural)
+vds-cli progress report -p INSURANCE-AI --llm-provider none --skip-sync
+```
+
+Auto-detect order: explicit `--profile` → `VDS_AUDIT_LLM_ENABLED=0` hard-disable → `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` env → structural-only.
+
+**Ollama is NOT auto-detected** — it must be requested via `--llm-provider ollama` explicitly. This is because Ollama's installed models may be cloud-routed, embedding-only, or reasoning models that need different token budgets, so aggressive auto-detection caused score regressions. When auto mode finds no provider, it leaves dims 7-8 as `None` and scores renormalize across structural dimensions only — **auto-detect is guaranteed to produce the same score as `--llm-provider none`**.
+
+## JSON Report Schema (Phase 3)
+
+Phase 3 reports include three new top-level keys in `--format json` output:
+
+```bash
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | jq '{heatmap: .heatmap, repo_health: .repo_health, coverage: .dimension_coverage}'
+```
+
+- **`heatmap`**: List of FR × dimension objects — boolean pass/fail and numeric scores per FR
+- **`repo_health`**: Per-repo test ratio and `green`/`yellow`/`red` health indicator
+- **`dimension_coverage`**: Pass-rates and averages across all FRs (e.g. `service_exists: 0.9`)
+
+## Scripted Score + Coverage
+
+```bash
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q | \
+  python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(f'Score: {d[\"overall_score\"]}')
+print(f'Doc chain: {d[\"dimension_coverage\"].get(\"doc_chain_complete\", \"N/A\")}')
+print(f'Recommendations: {sum(len(s[\"recommendations\"]) for s in d[\"sections\"])}')
+"
+```
+
+## Progressive Disclosure Modes (Phase 4)
+
+`--mode` picks a rendering tier. All four modes use the same underlying computation — only the rendered output differs:
+
+```bash
+# Exec: ≤20 lines. Slack pastes, email digests, GitHub status checks.
+vds-cli progress report -p INSURANCE-AI --mode exec --skip-sync -q
+
+# Summary: ≤100 lines. Standup review, code-review context, daily digest.
+vds-cli progress report -p INSURANCE-AI --mode summary --skip-sync -q
+
+# Standard: ~564 lines. Default. Byte-identical to pre-Phase-4 output (heatmap,
+# per-FR detail, trend, risk register). Use when daily development review.
+vds-cli progress report -p INSURANCE-AI --skip-sync -q   # --mode standard is implicit
+
+# Full: ~581 lines. Standard + stratified cluster sub-reports + appendices.
+# Use for quarterly audits, retrospectives, compliance packets.
+vds-cli progress report -p INSURANCE-AI --mode full --skip-sync -q
+```
+
+**Tip**: Start with `--mode exec` when piping into chat notifications and bump up to `summary` or `full` only when someone asks "why did the score move?"
+
+## CI/CD Quality Gates (Phase 4)
+
+Make progress report failures break your pipeline. `vds-cli progress report` exits with:
+
+- `0` — report generated, no gates tripped
+- `1` — runtime error (missing DSN, sync failed, crash)
+- `2` — **quality gate failed** (report file still written)
+
+```bash
+# Fail the build if overall score drops below 60
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
+
+# Fail if any FR regressed by more than 15 points vs the previous run
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-on-regression -q
+
+# Compare against a specific historical run instead of "previous"
+vds-cli progress report -p INSURANCE-AI --skip-sync \
+  --fail-on-regression --baseline <run-id> -q
+
+# Combine gates — any trip exits 2
+vds-cli progress report -p INSURANCE-AI --skip-sync \
+  --fail-under 60 --fail-on-regression -q
+echo $?   # 2 if either gate fails
+```
+
+**Important**: Unlike SonarQube's `sonar-scanner` (which silently exits 0 even on gate failure unless you pass `-Dsonar.qualitygate.wait=true`), `vds-cli progress` honors gate flags immediately when set. The report file is always written before the non-zero exit, so your CI can still upload it as an artifact.
+
+**GitHub Actions example**:
+
+```yaml
+- name: Progress check
+  run: |
+    vds-cli progress report -p INSURANCE-AI --skip-sync \
+      --fail-under 60 --mode exec -q > progress.txt
+  continue-on-error: false   # exit 2 fails the step
+
+- name: Upload report
+  if: always()   # still upload when the step failed
+  uses: actions/upload-artifact@v4
+  with:
+    path: ~/.vds/cache/progress-reports/
+```
+
+## Bimodal Distribution / Stratified Clusters (Phase 4)
+
+When your FR scores split cleanly into "passing FRs" and "failing FRs" with no middle tier, the report emits a `bimodal_warning` block. This is the **valence-gap heuristic** — a UX signal, not statistical bimodality (ADR-Q7).
+
+Detection rules (all must hold):
+
+1. `total_frs ≥ 10`
+2. `medium == 0`
+3. `high_count > 0 AND low_count > 0`
+4. `min(high, low) / total ≥ 0.25` (dominance guard — kills skewed-unimodal false positives like 14/0/1)
+
+When detected, `summary` and `full` modes render **stratified sub-reports**: a high-cluster mini-report (passing FRs, avg score, weakest remaining dim, top remaining action) and a low-cluster mini-report (blocked FRs, dominant blocker, highest-priority fix).
+
+Extract cluster data from JSON:
+
+```bash
+vds-cli progress report -p INSURANCE-AI --format json --skip-sync -q \
+  | jq '.bimodal_warning'
+# {
+#   "detected": true,
+#   "stratification_variable": "service_exists",
+#   "high_cluster": {
+#     "label": "passing",
+#     "fr_ids": ["FR6", "FR7", "FR8", ...],
+#     "avg_score": 83.6,
+#     "dominant_blocker": "test_coverage",
+#     "top_recommendation_fr": "FR8"
+#   },
+#   "low_cluster": { ... }
+# }
+```
+
+**Interpretation**: A bimodal warning usually means *"the services that exist are healthy; the ones that are failing aren't built yet"* — your work is recipe-style scaffolding, not debugging the passing services. Use `dominant_blocker` to pick the next sprint focus and `top_recommendation_fr` as the starting FR.
+
+## Trend Regression Bucketing (Phase 4)
+
+When a previous run exists, the report bucketizes FR deltas vs baseline:
+
+| Δ score | Bucket | Render |
+|---------|--------|--------|
+| `Δ ≤ -15` | **Critical regression** | Loud callout + risk register entry |
+| `-15 < Δ ≤ -5` | Minor regression | Subtle callout |
+| `-5 < Δ < 5` | Noise floor | Ignored |
+| `5 ≤ Δ < 15` | Improvement | Noted |
+| `Δ ≥ 15` | Major improvement | Highlighted |
+
+Thresholds are intentionally simple for Phase 4. Phase 4.1 will upgrade to **Western Electric Rules** (3σ single-point, 2-of-3 at 2σ, 4-of-5 at 1σ) using rolling mean/stddev from `daily_scores`.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "no DSN provided" | Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` |
+| "bmad_ntbh not found" | Run `vds-cli audit sync repos --bitbucket-project INSURANCE-AI` |
+| Structlog lines in output | Use `-q` flag or redirect stderr (`2>/dev/null`) |
+| Score unchanged after code changes | Re-sync repos (remove `--skip-sync`) |
+| LLM not detected | Check `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in `~/.vds/.env`, or use `--llm-provider none` |
+| CI shows exit 0 when score is low | Confirm `--fail-under <score>` flag is set — gates are opt-in |
+| `--fail-on-regression` not tripping | No baseline exists yet (first run) or baseline is outside the noise floor — pass `--baseline <run-id>` explicitly |
+| `bimodal_warning.detected: false` when I expected true | Check `total_frs ≥ 10`, `medium == 0`, dominance `≥ 0.25` — skewed distributions like 14/0/1 are rejected by design |
+| `--mode exec` output missing trend | Exec mode is deliberately ≤20 lines; use `--mode summary` for trend sparklines |
+| Standard mode output looks different | Should be byte-identical to Phase 3. File a bug if it's not — the G-Q11c structural invariants test guards this. |

package/skills/vds-skill/runtime/docs/agents/how-to/08-semantic-search.md

@@ -0,0 +1,46 @@
+<!-- diátaxis: how-to -->
+
+# Semantic Search
+
+> Use semantic search to find code and documentation by meaning, not exact string.
+
+## Scope
+
+- **Does:** Search by concept, intent, and semantic meaning across code and docs.
+- **Does NOT:** Replace exact-string search (`rg`) when you know the symbol name.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli research --help
+
+# Direct entry
+vds-cli research --help
+```
+
+## Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| `search` | Semantic search |
+| `score` | Score evidence quality |
+
+## Workflow
+
+### Search by Meaning
+
+1. Run: `vds-cli research search "credential resolution pattern"`
+2. Review ranked results by relevance
+3. Filter by source: `--tool tavily`, `--tool grepai`
+
+```bash
+# Example: find how VDS handles retry
+grepai search "retry pattern with exponential backoff"
+```
+
+## Related
+
+- [Search Tools Reference](../reference/search-tools.md)
+- [Research Orchestrator](../reference/research-orchestrator.md)
+- [Memory Orchestrator](../reference/memory-orchestrator.md)

package/skills/vds-skill/runtime/docs/agents/how-to/apply-phase3-migration.md

@@ -0,0 +1,148 @@
+<!-- diátaxis: how-to -->
+
+# How to apply the Phase 3 alembic migration
+
+> Operator runbook to bring the live `sched.ecosystem_report_runs` schema into
+> alignment with the Phase 3 collector code merged at `412b067b`.
+
+**Time budget**: ≤ 10 minutes. **Risk**: low (additive migration; reversible).
+
+## Why
+
+Phase 3 of the ecosystem-daily-report (`edr-phase3/intelligent-watchdog`,
+merged at `412b067bcbb44c466cf62f5f62a11d0888090848` on 2026-04-30) added
+five new collectors and a Slack delivery step. Their results are persisted
+to **new columns** on `sched.ecosystem_report_runs`:
+
+- `llm_summary` (JSONB) — LLM provider/model token totals + USD cost
+- `dora_summary` (JSONB) — deploy frequency, lead time, CFR, time-to-restore
+- `trend_summary` (JSONB) — z-scores + sparklines + trend directions
+- `security_summary` (JSONB) — placeholder for SecurityAdvisoryCollector
+- `slack_delivered` (boolean), `slack_delivered_at` (timestamptz)
+
+Plus a new table `sched.ecosystem_report_archive` with a GIN-indexed
+`full_report` JSONB column for historical search.
+
+The migration file shipped at `412b067b` (revision `b2c3d4e5f8a9`,
+down-revision `a1b2c3d4e5f8`) but the live database still points at
+the Phase 2 head. **Until you run `alembic upgrade head`**, the cron
+that fires at 06:00 UTC will hand the SQLAlchemy model rows containing
+the Phase 3 columns to a database that does not have those columns,
+which leads to either persistence failure or silent loss of Phase 3 data
+depending on driver behavior.
+
+## When
+
+After the Phase 3 merge has landed on master (verify with
+`git log --oneline 412b067b -1`) and **before** you rely on persisted
+Phase 3 reports — i.e. before the next 06:00 UTC cron fire, or before
+the next manual `vds-cli scheduler schedules trigger-now ecosystem-daily-report`.
+
+## Prerequisites
+
+- `~/.vds/.env` populated (Postgres DSN, `VDS_SCHEDULER_ENABLED=true`).
+- Working tree at master `412b067b` or later.
+- Postgres 16 healthy (`docker ps | grep postgres` shows the
+  `vds-postgres` container with status `healthy`).
+
+## Steps
+
+### 1. Apply the migration
+
+```bash
+cd WHO-project/vds-scripts
+./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic upgrade head
+```
+
+Expected output:
+
+```
+INFO  [alembic.runtime.migration] Running upgrade a1b2c3d4e5f8 -> b2c3d4e5f8a9, add_phase3_report_columns
+```
+
+### 2. Verify the scheduler service is running
+
+```bash
+docker ps | grep scheduler                      # vds-scheduler container healthy
+vds-cli scheduler schedules show ecosystem-daily-report
+```
+
+The schedule should be listed with status `active` (not `paused`) and a
+`next_run` timestamp set to the next 06:00 UTC. If `Status: paused`, run
+`vds-cli scheduler schedules resume ecosystem-daily-report`.
+
+### 3. Trigger one workflow run for verification
+
+Don't wait for 06:00 UTC; force one fire so you can confirm the new
+schema is being written through:
+
+```bash
+vds-cli scheduler schedules trigger-now ecosystem-daily-report
+```
+
+Then check the workflow result:
+
+```bash
+vds-cli scheduler workflows list --status SUCCESS --limit 1
+```
+
+A new `reports/ecosystem/<today>-ecosystem-report.md` file should also
+appear in the worktree.
+
+### 4. Confirm the new row populates Phase 3 columns
+
+```bash
+vds-cli ecosystem report history --days 1
+```
+
+The latest row should show non-NULL `dora_summary`, `trend_summary`,
+`llm_summary`, `slack_delivered`, `slack_delivered_at`. NULL or
+`[unavailable]` payloads are *also* acceptable — what matters is that
+the cron successfully wrote through the migrated schema rather than
+crashing on `column does not exist`.
+
+> Caveat: `llm_summary` will report `[unavailable]` until the Phase 4
+> producer-wiring task lands (see the spec's "Phase 4 Followup — JSONL
+> Producer Wiring" note). This is graceful degradation per AC-P3.9, not
+> a regression.
+
+## Verification
+
+You will know the migration worked when:
+
+- `alembic current` shows `b2c3d4e5f8a9 (head)`.
+- `psql ... -c "\d sched.ecosystem_report_runs"` lists the six new
+  columns above.
+- `psql ... -c "\d sched.ecosystem_report_archive"` shows the new
+  archive table with a GIN index on `full_report`.
+- A fresh row from `vds-cli ecosystem report history --days 1` is
+  written without error after step 3.
+
+## Rollback
+
+If you need to revert (for example, a downstream consumer is not yet
+ready for the new columns):
+
+```bash
+# 1. Pause the schedule so the next cron does not crash on the
+#    pre-Phase-3 schema.
+vds-cli scheduler schedules pause ecosystem-daily-report
+
+# 2. Downgrade.
+cd WHO-project/vds-scripts
+./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic downgrade -1
+```
+
+`alembic downgrade -1` reverts to `a1b2c3d4e5f8` (Phase 2 head), drops
+the six Phase 3 columns and the `ecosystem_report_archive` table.
+**Do not resume the schedule** until either you re-apply the migration
+or you check out a pre-`412b067b` master tip whose model code matches
+the Phase 2 schema.
+
+## See also
+
+- Spec post-merge runbook: `.gpt-5.4/specs/ecosystem-daily-report/tasks.md`
+  → "Post-Merge Operator Runbook"
+- DORA bootstrap criterion: `.gpt-5.4/specs/ecosystem-daily-report/design.md`
+  → "Bootstrap criterion (verdict locked 2026-04-30, Lane Alpha)"
+- Existing daily-report runbook: `docs/agents/how-to/run-ecosystem-daily-report.md`

package/skills/vds-skill/runtime/docs/agents/how-to/choose-the-right-command-or-skill.md

@@ -0,0 +1,34 @@
+<!-- diátaxis: how-to -->
+
+# Choose The Right WHO Command Or Skill
+
+Use this guide when you know the task you want to perform but are not sure whether to start with a CLI command family or a specialist skill.
+
+## Step 1: Is this a platform-routing question?
+
+Use `vds-scripts-skill` when you need to:
+- find the right WHO command family
+- bootstrap the scripts workspace
+- understand which workspace capability owns a task
+- route to the correct specialist skill
+
+## Step 2: Route by task intent
+
+| Intent | Start Here |
+|-------|------------|
+| Run audit workflow, readiness, rerun, upload | `audit-orchestrator-skill` + `vds-cli audit` |
+| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` |
+| Create or update specs | `spec-creation-skill` + `vds-cli spec` |
+| Develop a CLI/orchestrator | `cli-development-skill` |
+| Use Jira/Confluence/Bitbucket/Git | `vds-scripts-skill` + `vds-cli` integration family |
+| Validate docs, links, schemas, OpenAPI, diagrams, sheets | `vds-scripts-skill` + validation family |
+| Configure LSP | `lsp-skill` |
+| Analyze dependency cycles | `circular-dependency-skill` |
+| Research across local + external sources | `research-skill` |
+
+## Step 3: Follow canonical sources
+
+- Scripts: `WHO-project/vds-scripts/`
+- Skills: `WHO-project/vds-skills/skills/`
+- Do not edit `.agent/skills/` directly
+- For shared env/config/cache path behavior, use `../reference/portable-paths-and-config.md`

package/skills/vds-skill/runtime/docs/agents/how-to/contribute-new-orchestrator.md

@@ -0,0 +1,149 @@
+<!-- diátaxis: how-to -->
+
+# Contribute a New Orchestrator
+
+## Prerequisites
+
+- Python 3.14+
+- uv installed
+- Docker (for testing with Postgres/Redis)
+- Familiarity with Typer and structlog
+
+## Workflow
+
+### 1. Create Branch
+
+```bash
+# From vds-scripts root
+git checkout -b feature/my-new-orchestrator
+```
+
+### 2. Scaffold the Orchestrator
+
+```bash
+# Create directory
+cd vds-scripts
+mkdir my_orchestrator
+cd my_orchestrator
+
+# Initialize uv project
+uv init --lib
+
+# Add dependencies
+uv add typer structlog pydantic-settings
+```
+
+### 3. Implement the CLI
+
+Create `my_orchestrator/src/my_orchestrator/cli.py`:
+
+```python
+import typer
+import structlog
+
+app = typer.Typer(help="My new orchestrator")
+logger = structlog.get_logger(__name__)
+
+@app.command()
+def run(input: str):
+    """Run my orchestrator."""
+    logger.info("starting", input=input)
+    # Implementation here
+    logger.info("completed", input=input)
+
+if __name__ == "__main__":
+    app()
+```
+
+### 4. Add Entry Point
+
+Update `pyproject.toml`:
+
+```toml
+[project.scripts]
+vds-my-orchestrator = "my_orchestrator.cli:app"
+```
+
+### 5. Register in Router
+
+Add to `vds_cli/src/vds_cli/router.py`:
+
+```python
+ORCHESTRATORS = {
+    # ... existing entries
+    "my_orchestrator": {
+        "module": "my_orchestrator.cli",
+        "path": "my_orchestrator",
+        "entry": "vds-my-orchestrator",
+    },
+}
+```
+
+### 6. Write Tests
+
+Create `tests/test_my_orchestrator.py`:
+
+```python
+import pytest
+from my_orchestrator.cli import app
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+def test_run():
+    result = runner.invoke(app, ["run", "test-input"])
+    assert result.exit_code == 0
+    assert "completed" in result.output
+```
+
+### 7. Add Documentation
+
+Create `docs/agents/reference/my-orchestrator.md` following the Diátaxis pattern.
+
+### 8. Update Ecosystem Files
+
+- Add to `AGENTS.md` router section
+- Append to `llms.txt`
+- Update `ECOSYSTEM-DOCS.md`
+
+### 9. Run Validation
+
+```bash
+vds-cli docs validate
+pytest
+```
+
+### 10. Commit and PR
+
+```bash
+git add .
+git commit -m "feat: add my-orchestrator orchestrator
+
+- Implements X functionality
+- Adds Y tests
+- Updates docs and AGENTS.md"
+```
+
+## PR Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Docs validated (`vds-cli docs validate`)
+- [ ] AGENTS.md line count ≤250
+- [ ] New doc has YAML frontmatter
+- [ ] Entry point registered in router
+- [ ] No hardcoded secrets
+- [ ] Error handling with context
+
+## Code Review Criteria
+
+Reviews check for:
+- Correct Typer/structlog patterns
+- Proper error handling
+- Test coverage ≥80%
+- Documentation completeness
+- No external API calls in tests (use mocks)
+
+## See Also
+
+- [Orchestrator Architecture](../reference/orchestrator-architecture.md)
+- [Add a Skill](../how-to/add-a-skill.md)

package/skills/vds-skill/runtime/docs/agents/how-to/decision-tree.md

@@ -0,0 +1,63 @@
+<!-- diátaxis: how-to -->
+# What Kind of Doc Am I Writing?
+
+Quick decision tree for choosing the correct Diátaxis quadrant.
+
+---
+
+## The One-Question Method
+
+Start at the top and answer each question. The first "YES" tells you the quadrant.
+
+```
+Q1: Is this for someone who has NEVER done this before?
+     → YES → TUTORIAL
+     → NO → Q2
+
+Q2: Is this a step-by-step recipe for a SPECIFIC task?
+     → YES → HOW-TO GUIDE
+     → NO → Q3
+
+Q3: Is this listing exact flags, contracts, or API surfaces?
+     → YES → REFERENCE
+     → NO → Q4
+
+Q4: Is this explaining WHY something works or background concepts?
+     → YES → EXPLANATION
+     → NO → Re-examine your scope. You may be mixing quadrants.
+```
+
+---
+
+## Examples by Quadrant
+
+| Doc Title | Quadrant | Why |
+|-----------|----------|-----|
+| "Day 0: Install the WHO toolchain" | Tutorial | First-time learner |
+| "How to add a new skill to the catalog" | How-to | Specific task |
+| `vds-cli --help` auto-generated docs | Reference | Exact flags |
+| "Why we use Diátaxis for doc architecture" | Explanation | Background concept |
+
+---
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Tutorial sneaks in unrelated tasks | Split to a separate How-to |
+| Reference doc tells a story | Delete narrative; keep only facts |
+| How-to explains the "why" | Move "why" to a linked Explanation doc |
+| Explanation gives step-by-step commands | Move commands to a How-to |
+
+---
+
+## Header Convention
+
+Every `.md` in `docs/agents/` should include its quadrant as the very first line:
+
+```markdown
+<!-- diátaxis: tutorial -->
+# Title
+```
+
+Valid values: `tutorial`, `how-to`, `reference`, `explanation`