diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
new file mode 100644
index 0000000..04b7f63
--- /dev/null
+++ b/.github/workflows/build.yml
@@ -0,0 +1,66 @@
+name: CI / build
+
+on:
+ push:
+ branches: [ main ]
+ pull_request:
+ branches: [ main ]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: build (${{ matrix.python-version }})
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: [ "3.11", "3.12" ]
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+
+ - name: Upgrade pip
+ run: python -m pip install --upgrade pip
+
+ - name: Install Poetry
+ run: pip install poetry
+
+ - name: Install dependencies
+ run: poetry install --no-interaction
+
+ - name: Ruff
+ run: poetry run ruff check .
+
+ - name: Black (check)
+ run: poetry run black --check .
+
+ - name: Pytest
+ env:
+ PYTHONPATH: src
+ run: poetry run pytest -q
+
+ - name: Mypy
+ run: poetry run mypy src
+
+ - name: Package & smoke-test CLI
+ run: |
+ poetry build
+ poetry run python -m pip install .
+ mkdir -p _intel
+ diff-risk examples/sample_apv.json -f md -o _intel/report.md
+
+ - name: Upload sample report
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: sample-report
+ path: _intel/report.md
diff --git a/README.md b/README.md
index bb2942a..2c09975 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,14 @@
# ⭐ diff-risk-dashboard — APV → Risk Summary (Python CLI)
-
-[](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.
+[](docs/MANUAL.md)
+
+
+
[](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/build.yml)
[](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/codeql.yml)
[](https://github.com/CoderDeltaLAN/diff-risk-dashboard/releases)
@@ -17,7 +19,6 @@ Designed for **always-green CI**, with strict checks and exit codes per risk lev
---
-
## Repo layout
```text
diff --git a/docs/MANUAL.md b/docs/MANUAL.md
index 76ef81d..6f333d1 100644
--- a/docs/MANUAL.md
+++ b/docs/MANUAL.md
@@ -1,13 +1,300 @@
-# 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
+# Diff Risk Dashboard — User Manual
+
+> **Version:** v0.4.x • **Scope:** Complete guide for end‑users and maintainers
+> **Project:** `diff-risk-dashboard` — APV → Risk Summary (Python CLI)
+
+---
+
+## Table of Contents
+- [1. What is this?](#1-what-is-this)
+- [2. Who is it for](#2-who-is-it-for)
+- [3. Installation](#3-installation)
+- [4. Quick Start](#4-quick-start)
+- [5. Inputs (APV JSON)](#5-inputs-apv-json)
+- [6. Output formats](#6-output-formats)
+- [7. Exit codes & CI gating](#7-exit-codes--ci-gating)
+- [8. Short wrappers](#8-short-wrappers)
+- [9. CLI reference](#9-cli-reference)
+- [10. CI/CD integration (GitHub Actions)](#10-cicd-integration-github-actions)
+- [11. Color/TTY tips](#11-colortty-tips)
+- [12. Troubleshooting](#12-troubleshooting)
+- [13. FAQ](#13-faq)
+- [14. Security & Privacy](#14-security--privacy)
+- [15. Contributing](#15-contributing)
+- [16. Versioning & Releases](#16-versioning--releases)
+- [17. Support](#17-support)
+- [18. License](#18-license)
+
+---
+
+## 1. What is this?
+`diff-risk-dashboard` is a lean, production‑grade **Python CLI** that ingests
+**ai‑patch‑verifier (APV)** JSON and emits a **risk summary** in **table**, **JSON**,
+or **Markdown**. It is designed for **always‑green CI**, providing clear **exit codes**
+to gate merges by risk level.
+
+### Key capabilities
+- Normalize APV severities (`CRITICAL|HIGH|MEDIUM|LOW|INFO`, case‑insensitive).
+- Summaries: `total`, `by_severity`, `worst`, and aggregate `risk_level`.
+- Output suitable for **terminals**, **bots**, **PR comments**, and **dashboards**.
+
+---
+
+## 2. Who is it for
+- **Developers & DevOps**: need deterministic summaries to automate merge gates.
+- **Security/QA**: require exportable JSON/Markdown for audits and reporting.
+- **Team leads**: want a quick “is it safe to merge?” signal in CI.
+
+---
+
+## 3. Installation
+
+### Option A — pipx (recommended)
+```bash
+pipx install . # run in project root, or: pipx install git+https://github.com/CoderDeltaLAN/diff-risk-dashboard.git
+```
+
+### Option B — pip (user site)
+```bash
+python -m pip install --user .
+```
+
+### Option C — development (Poetry)
+```bash
+pip install poetry
+poetry install --no-interaction
+```
+
+> After installing, the `diff-risk` command is available on your PATH.
+
+---
+
+## 4. Quick Start
+
+Run with the bundled sample:
+```bash
+diff-risk examples/sample_apv.json -f table
+```
+
+Generate Markdown to a file:
+```bash
+diff-risk examples/sample_apv.json -f md -o report.md
+```
+
+Inline JSON (single quotes outside, double inside):
+```bash
+diff-risk '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}' -f table
+```
+
+---
+
+## 5. Inputs (APV JSON)
+
+The tool accepts either:
+1) **File path** to JSON, or
+2) **Inline JSON** text (starting with `{` or `[`).
+
+Minimum shapes supported:
+- **Aggregated**:
+ ```json
+ { "by_severity": { "HIGH": 1, "MEDIUM": 2, "LOW": 3 } }
+ ```
+- **Flat list** (each item has a severity/level field):
+ ```json
+ [
+ {"severity":"high", "title":"..."},
+ {"predicted_risk":"medium", "id": 42}
+ ]
+ ```
+
+The CLI normalizes severities and computes:
+- `total`
+- `by_severity` (both UPPER and lower keys are included for convenience)
+- `worst` (string)
+- `risk_level`: `"red" | "yellow" | "green"`
+
+---
+
+## 6. Output formats
+
+### Table (TTY‑friendly)
+```bash
+diff-risk input.json -f table
+```
+
+### JSON (machines/CI)
+```bash
+diff-risk input.json -f json
+```
+
+Example JSON:
+```json
+{
+ "total": 3,
+ "by_severity": {
+ "CRITICAL": 0, "HIGH": 1, "MEDIUM": 1, "LOW": 1, "INFO": 0,
+ "critical": 0, "high": 1, "medium": 1, "low": 1, "info": 0
+ },
+ "worst": "HIGH",
+ "risk_level": "red"
+}
+```
+
+### Markdown (reports/PRs)
+```bash
+diff-risk input.json -f md -o _intel/report.md
+```
+
+---
+
+## 7. Exit codes & CI gating
+
+Default behavior (raw CLI):
+- `green` → exit **0**
+- `yellow` → exit **1**
+- `red` → exit **2**
+
+To force **always 0** (useful locally or for non‑blocking jobs):
+```bash
+diff-risk input.json --no-exit-by-risk
+```
+
+---
+
+## 8. Short wrappers
+
+Convenience scripts (installed in `bin/`):
+- `drt ` — colored table (TTY)
+- `drb ` — bars (logs)
+- `drj ` — JSON (CI)
+- `drmd ` — Markdown (stdout)
+
+Examples:
+```bash
+drt examples/sample_apv.json
+drt '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}'
+APV="/absolute/path/to/your_apv.json"; drt "$APV"
+```
+
+Add to PATH:
+```bash
+mkdir -p ~/.local/bin && ln -sf "$PWD/bin/"* ~/.local/bin/ && hash -r
+```
+
+---
+
+## 9. CLI reference
+
+```bash
+diff-risk -h
+```
+
+Options (common):
+- `-f, --format {table,json,md,bar}` — output format
+- `-o, --output` — file path; `-` = stdout
+- `--no-exit-by-risk` — disable exit code gating
+
+---
+
+## 10. CI/CD integration (GitHub Actions)
+
+Minimal job (Python 3.11 / 3.12):
+```yaml
+- uses: actions/checkout@v4
+- uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+- run: python -m pip install --upgrade pip
+- run: pip install poetry
+- run: poetry install --no-interaction
+- run: poetry run ruff check .
+- run: poetry run black --check .
+- env:
+ PYTHONPATH: src
+ run: poetry run pytest -q
+- run: poetry run mypy src
+# Smoke:
+- run: |
+ poetry build
+ poetry run python -m pip install .
+ diff-risk examples/sample_apv.json -f md -o _intel/report.md
+```
+
+Upload report artifact:
+```yaml
+- uses: actions/upload-artifact@v4
+ with:
+ name: sample-report
+ path: _intel/report.md
+```
+
+---
+
+## 11. Color/TTY tips
+
+To force colorized output in recordings/CI logs:
+```bash
+script -qfc "drt examples/sample_apv.json" /dev/null
+```
+
+---
+
+## 12. Troubleshooting
+
+- **JSONDecodeError**: Your argument is neither a readable file nor valid JSON.
+ Use a valid path or wrap inline JSON like: `'{"by_severity":{"HIGH":1}}'`.
+
+- **Exit code > 0 unexpectedly**: You likely used the raw CLI without
+ `--no-exit-by-risk`. The wrappers already add it for you.
+
+- **Command not found**: Ensure the package is installed and/or PATH updated
+ when using wrappers.
+
+---
+
+## 13. FAQ
+
+**Q:** Can I feed arbitrary JSON?
+**A:** Provide either the aggregated `by_severity` or a list with `severity`/`predicted_risk` keys.
+
+**Q:** Why duplicate lower & upper keys in `by_severity`?
+**A:** Convenience for consumers with strict schemas.
+
+---
+
+## 14. Security & Privacy
+
+- No credentials required. Do **not** upload sensitive JSON to public PRs.
+- CodeQL runs in CI; keep dependencies updated.
+
+---
+
+## 15. Contributing
+
+- Follow **Conventional Commits**.
+- Keep **ruff/black/pytest/mypy** green before requesting review.
+- Prefer small PRs with auto‑merge enabled after checks.
+
+---
+
+## 16. Versioning & Releases
+
+- Tags `vMAJOR.MINOR.PATCH`. Release notes are drafted automatically.
+- Use GitHub Releases to fetch artifacts and changelog.
+
+---
+
+## 17. Support
+
+- Open Issues or Discussions on GitHub.
+- For commercial support, contact the repository owner.
+
+---
+
+## 18. License
+
+Released under the **MIT License**. See [LICENSE](../LICENSE).
+
+---
+
+> **Tip:** The README “Manual” badge links to this page.