docs(readme): update usage block; add docs/USAGE.md and MANUAL.md + links

README.md

@@ -1,5 +1,7 @@
 # ⭐ diff-risk-dashboard — APV → Risk Summary (Python CLI)
 
+
+[![Manual](https://img.shields.io/badge/Manual-User%20Guide-blue?style=for-the-badge)](docs/MANUAL.md)
 A lean, production-grade **Python CLI** that ingests **ai-patch-verifier (APV)** JSON and outputs a clear **risk summary** (table / JSON / Markdown).  
 Designed for **always-green CI**, with strict checks and exit codes per risk level to gate merges professionally.
 
@@ -37,35 +39,41 @@ Designed for **always-green CI**, with strict checks and exit codes per risk lev
 
 <!-- diff-risk:usage:start -->
 
-## 🚀 Usage (short aliases)
+## 🚀 Usage
+
+### Short commands
+- `drt <apv.json | raw-json>` – color table (TTY)
+- `drb <apv.json | raw-json>` – text bars (logs)
+- `drj <apv.json | raw-json>` – JSON (CI)
+- `drmd <apv.json | raw-json>` – Markdown (stdout)
 
-### CLI (recommended colorful table)
 ```bash
-# green panel (empty sample)
-./bin/drt examples/sample_apv.empty.json
+# Demo (bundled sample)
+drt examples/sample_apv.json
 
-# real example with findings
-./bin/drt examples/sample_apv.json
-```
+# Inline JSON (single quotes outside, double inside)
+drt '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}'
 
-Other formats:
-```bash
-./bin/drb  examples/sample_apv.json                   # text bars
-./bin/drj  examples/sample_apv.json                   # JSON (CI/machines)
-./bin/drmd examples/sample_apv.json _intel/report.md  # Markdown file
-```
+# Your real file
+APV="/absolute/path/to/your_apv.json"; drt "$APV"
 
-Tip: to call aliases without `./bin/` temporarily:
-```bash
-export PATH="$PWD/bin:$PATH"
-drt examples/sample_apv.json
+# Other formats with the same input
+drb "$APV"              # bars (logs)
+drj "$APV"              # JSON (CI)
+drmd "$APV" > report.md # Markdown to file
+
+# Force colors for recordings
+script -qfc "drt $APV" /dev/null
 ```
 
-**Exit codes**: `0=green`, `1=yellow`, `2=red` (`--no-exit-by-risk` forces `0` for demos).
+> Exit codes: wrappers return `0` thanks to `--no-exit-by-risk`.  
+> CLI raw (without wrappers) sets exit code by risk unless you add `--no-exit-by-risk`.
 
 <!-- diff-risk:usage:end -->
 
 
+
+
 > Sin cambios en tu sistema ni shell. Usa el proyecto como **app Python** con su comando **`diff-risk`** tras instalarlo.
 
 ```bash

README_USAGE_BLOCK.md

@@ -0,0 +1,33 @@
+<!-- diff-risk:usage:start -->
+
+## 🚀 Usage
+
+### Short commands
+- `drt <apv.json | raw-json>` – color table (TTY)
+- `drb <apv.json | raw-json>` – text bars (logs)
+- `drj <apv.json | raw-json>` – JSON (CI)
+- `drmd <apv.json | raw-json>` – Markdown (stdout)
+
+```bash
+# Demo (bundled sample)
+drt examples/sample_apv.json
+
+# Inline JSON (single quotes outside, double inside)
+drt '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}'
+
+# Your real file
+APV="/absolute/path/to/your_apv.json"; drt "$APV"
+
+# Other formats with the same input
+drb "$APV"              # bars (logs)
+drj "$APV"              # JSON (CI)
+drmd "$APV" > report.md # Markdown to file
+
+# Force colors for recordings
+script -qfc "drt $APV" /dev/null
+```
+
+> Exit codes: wrappers return `0` thanks to `--no-exit-by-risk`.  
+> CLI raw (without wrappers) sets exit code by risk unless you add `--no-exit-by-risk`.
+
+<!-- diff-risk:usage:end -->

docs/MANUAL.md

@@ -0,0 +1,13 @@
+# Diff Risk Dashboard — Manual
+
+This manual complements **docs/USAGE.md** with project context.
+- Quick usage & CLI examples: see **docs/USAGE.md**.
+- Short wrappers: drt/drb/drj/drmd (file or inline JSON).
+- Exit codes: 0 (green), 1 (yellow), 2 (red). Use `--no-exit-by-risk` to force 0.
+
+More sections to expand:
+1) Installation & environment
+2) Input format (APV JSON)
+3) Output formats (table, bar, json, md)
+4) CI usage & exit codes
+5) Troubleshooting

docs/USAGE.md

@@ -0,0 +1,33 @@
+<!-- diff-risk:usage:start -->
+
+## 🚀 Usage
+
+### Short commands
+- `drt <apv.json | raw-json>` – color table (TTY)
+- `drb <apv.json | raw-json>` – text bars (logs)
+- `drj <apv.json | raw-json>` – JSON (CI)
+- `drmd <apv.json | raw-json>` – Markdown (stdout)
+
+```bash
+# Demo (bundled sample)
+drt examples/sample_apv.json
+
+# Inline JSON (single quotes outside, double inside)
+drt '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}'
+
+# Your real file
+APV="/absolute/path/to/your_apv.json"; drt "$APV"
+
+# Other formats with the same input
+drb "$APV"              # bars (logs)
+drj "$APV"              # JSON (CI)
+drmd "$APV" > report.md # Markdown to file
+
+# Force colors for recordings
+script -qfc "drt $APV" /dev/null
+```
+
+> Exit codes: wrappers return `0` thanks to `--no-exit-by-risk`.  
+> CLI raw (without wrappers) sets exit code by risk unless you add `--no-exit-by-risk`.
+
+<!-- diff-risk:usage:end -->

update_readme_usage.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Usage: ./update_readme_usage.sh [USAGE_BLOCK] [README]
+BLK="${1:-README_USAGE_BLOCK.md}"
+READ="${2:-README.md}"
+TMP="$READ.tmp"
+
+# Replace existing block delimited by markers, or append if not present.
+if grep -q '<!-- diff-risk:usage:start -->' "$READ"; then
+  awk -v F="$BLK" '
+    BEGIN { while ((getline l < F) > 0) blk = blk l ORS; close(F) }
+    /<!-- diff-risk:usage:start -->/ { print blk; inside=1; next }
+    /<!-- diff-risk:usage:end -->/   { inside=0; next }
+    !inside { print }
+  ' "$READ" > "$TMP" && mv "$TMP" "$READ"
+else
+  printf '\n' >> "$READ"
+  cat "$BLK" >> "$READ"
+fi
+
+echo "README usage block updated ✅"