diff --git a/README.md b/README.md
index 3d8912d..d15f8fe 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,79 @@
-# quality-docs-validator
+# Quality Docs Validator
+
+### Catch potential inconsistencies between PFMEA and Control Plan — before technical review
+
+
+
+A **local-first Python CLI** for quality, process and manufacturing engineers. Compare two `.xlsx` workbooks, surface severity-classified **potential findings**, and produce Markdown or JSON reports without sending your files to a cloud service.
[](https://github.com/migmcc/quality-docs-validator/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
-> Detect **potential inconsistencies between PFMEA and Control Plan** before audits, customer
-> submissions or production issues — locally, with simple files, explicit rules and clear reports.
+**[Quick start](#quick-start)** · **[See a real example](#see-it-in-action)** · **[What it checks](#what-it-validates)** · **[Limitations](#what-it-does-not-validate-by-design)** · **[Architecture](docs/ARCHITECTURE.md)**
-`quality-docs-validator` (CLI: `qdv`) is a **local-first, forkable** tool for quality engineers.
+---
-## The problem
+## See it in action
+
+Run the **bundled synthetic example** containing deliberately seeded gaps:
+
+```bash
+git clone https://github.com/migmcc/quality-docs-validator.git
+cd quality-docs-validator
+pip install -e .
+qdv pfmea-control-plan \
+ --pfmea examples/pfmea.xlsx \
+ --control-plan examples/control-plan.xlsx \
+ --out report.md
+```
+
+
+
+**Documented sample terminal output (abridged):**
+
+```text
+Potential findings
+ UNMATCHED_PROCESS_STEP warning Op 40
+ SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical Op 20
+ MISSING_REACTION_PLAN critical Op 20
+ WEAK_DETECTION_METHOD warning Op 20
+ HIGH_SEVERITY_WEAK_CONTROL warning Op 20
+ MISSING_CONTROL critical Op 30
+
+Score: 43/100 Verdict: FAIL
+Critical: 3 Warnings: 3
+```
+
+[Read the full committed sample report →](examples/report.md)
-Quality documents are reviewed one at a time, but the real risk lives **between** them: a
-high-severity PFMEA failure mode with no matching Control Plan control, a special characteristic
-missing from the inspection plan, a missing reaction plan exactly where risk is highest. These gaps
-surface late — at audits, customer submissions or as field complaints. This tool cross-checks the
-two documents and surfaces those gaps as **severity-classified potential findings**.
+> **Important:** Findings are *potential inconsistencies* for an engineer to judge. This is **not** a regulatory or standards compliance certification and **does not replace human technical review**.
-> ⚠️ It **supports, and does not replace, human technical review.** Findings are *potential*
-> inconsistencies for an engineer to judge; the tool makes no regulatory or normative conformance
-> claim.
+## The problem
+
+A PFMEA and its Control Plan can look complete when reviewed separately while disagreeing **between** documents: an unmatched process step, a special characteristic not reflected in controls, or no reaction plan where severity is high. Those gaps deserve attention before an audit or submission.
## Who it's for
-Quality / Process / Manufacturing Engineers, SQEs, internal auditors and APQP/PPAP teams — and
-anyone using coding agents to automate quality workflows. Runs entirely on your machine, so
-confidential supplier/customer data never leaves it.
+Quality / Process / Manufacturing Engineers, supplier-quality teams, internal auditors and APQP/PPAP teams working with Excel-based documents.
## What it validates
-A single module: **PFMEA ↔ Control Plan consistency checker**.
-
-- Reads a PFMEA `.xlsx` and a Control Plan `.xlsx` (recommended template + common header aliases —
- e.g. `Operation No`, `Op #`, `Severity Rating`, `Special Characteristic`, `Reaction Plan`).
-- Matches rows by `operation_id` / process step.
-- Applies six explicit, documented checks (see [docs/FINDINGS.md](docs/FINDINGS.md)):
- `UNMATCHED_PROCESS_STEP`, `MISSING_CONTROL`, `SPECIAL_CHARACTERISTIC_NOT_CONTROLLED`,
- `MISSING_REACTION_PLAN`, `WEAK_DETECTION_METHOD` (warning), `HIGH_SEVERITY_WEAK_CONTROL` (warning).
-- Computes a **severity-weighted score (0–100)** with verdict bands
- (PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL).
-- Generates a **Markdown report** plus a **rich terminal summary**.
+The current module is a **PFMEA ↔ Control Plan consistency checker**.
-## What it does *not* validate (by design)
+| Capability | How it works |
+| --- | --- |
+| Excel input | Reads PFMEA and Control Plan `.xlsx` workbooks, with a recommended template and common header aliases. |
+| Matching | Matches normalised operation IDs and process steps. |
+| Six checks | Flags unmatched steps, missing controls, uncontrolled special characteristics, missing reaction plans and two warning-level weak-method heuristics. |
+| Scoring | Severity-weighted 0–100 score with PASS / PASS-WITH-WARNINGS / NEEDS-REVIEW / FAIL verdicts. |
+| Reports | Rich terminal summary plus Markdown or JSON, suitable for review and automation. |
-- ❌ CSV / other input formats — `.xlsx` only (CSV planned for v0.2).
-- ❌ Configurable column mapping — recommended template + fixed aliases only (v0.2).
-- ❌ Other document pairs (Process Flow ↔ PFMEA, Work Instructions, PPAP, 8D, SPC, MSA).
-- ❌ Web UI, ERP/MES/QMS integration, PDF/OCR, or any AI dependency.
-- ❌ Regulatory/standard conformance certification, or replacing human judgement.
+**[Read the exact finding triggers and scoring rules →](docs/FINDINGS.md)**
-Scope is deliberately narrow — see [docs/MVP_SCOPE.md](docs/MVP_SCOPE.md),
-[docs/DECISIONS.md](docs/DECISIONS.md) and the [roadmap](docs/ROADMAP.md).
+## Quick start
-## Quickstart
+**Requirements:** Python 3.12+ and a local checkout of this repository.
```bash
pip install -e .
@@ -62,35 +83,9 @@ qdv pfmea-control-plan \
--out report.md
```
-This runs against the bundled synthetic examples (which contain a deliberately seeded gap) and
-writes `report.md` plus a terminal summary. Regenerate the examples with
-`python examples/generate_examples.py`.
-
-Expected terminal summary (abridged):
-
-```text
- Potential findings
- Type Level Op Detail
- ─────────────────────────────────────────────────────────────────
- UNMATCHED_PROCESS_STEP warning 40 no Control Plan row
- SPECIAL_CHARACTERISTIC_NOT_CONTROLLED critical 20 not marked special in CP
- MISSING_REACTION_PLAN critical 20 S=9, no reaction plan
- WEAK_DETECTION_METHOD warning 20 visual inspection
- HIGH_SEVERITY_WEAK_CONTROL warning 20 S=9 + weak control
- MISSING_CONTROL critical 30 no control method
-
-╭───────────────── quality-docs-validator ─────────────────╮
-│ Score: 43/100 Verdict: FAIL Critical: 3 Warnings: 3 │
-╰───────────────────────────────────────────────────────────╯
-```
+The bundled examples are synthetic and intentionally contain a gap. To regenerate them, run `python examples/generate_examples.py`.
-The full Markdown report is written to `report.md`; a committed sample lives at
-[examples/report.md](examples/report.md). Finding types and scoring are documented in
-[docs/FINDINGS.md](docs/FINDINGS.md).
-
-### JSON output
-
-For automation, emit a machine-readable report with `--format json`:
+### JSON output for automation
```bash
qdv pfmea-control-plan \
@@ -99,13 +94,9 @@ qdv pfmea-control-plan \
--format json --out report.json
```
-Markdown remains the default. The JSON contains `metadata` (tool, version, UTC timestamp),
-`verdict`, `score`, a `summary` (counts by severity and by finding type) and the full `findings`
-list.
+The JSON report includes metadata, verdict, score, summary and findings.
-### Multi-sheet workbooks
-
-If a workbook has several sheets, pick the right one by name (otherwise the active sheet is used):
+### Select sheets in multi-sheet workbooks
```bash
qdv pfmea-control-plan \
@@ -114,12 +105,28 @@ qdv pfmea-control-plan \
--out report.md
```
-If the named sheet does not exist, the error lists the available sheet names.
+If a specified sheet does not exist, the error lists available sheet names.
+
+## What it does not validate (by design)
+
+- Formats other than `.xlsx`; CSV is not currently supported.
+- Arbitrary column mapping beyond the recommended template and supported aliases.
+- Other document pairs (Process Flow, Work Instructions, PPAP, 8D, SPC, MSA).
+- Web interface, ERP / MES / QMS integration, PDF / OCR or AI-based interpretation.
+- Regulatory conformity, audit certification or replacements for engineering judgement.
+
+See [scope](docs/MVP_SCOPE.md), [decisions](docs/DECISIONS.md) and [roadmap](docs/ROADMAP.md).
+
+## How it works
+
+`PFMEA.xlsx + Control Plan.xlsx → operation matching → six checks → scoring → terminal / Markdown / JSON`
-## Architecture
+The rules and scoring are explicitly documented and testable rather than based on an LLM. For implementation details, see [architecture](docs/ARCHITECTURE.md) and [finding reference](docs/FINDINGS.md).
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the module layout and data flow.
+## Get involved
-## License
+- [Explore the repository](https://github.com/migmcc/quality-docs-validator)
+- [Open an issue](https://github.com/migmcc/quality-docs-validator/issues)
+- [Contribute](CONTRIBUTING.md)
-[MIT](LICENSE). Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Licensed under [MIT](LICENSE).
diff --git a/docs/assets/example-output.svg b/docs/assets/example-output.svg
new file mode 100644
index 0000000..7e44ed7
--- /dev/null
+++ b/docs/assets/example-output.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/validation-flow.svg b/docs/assets/validation-flow.svg
new file mode 100644
index 0000000..a8b2723
--- /dev/null
+++ b/docs/assets/validation-flow.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 98e9398..d320868 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -58,3 +58,7 @@ addopts = "-q"
line-length = 100
target-version = "py312"
src = ["src", "tests"]
+
+[tool.ruff.lint.per-file-ignores]
+# Typer declares CLI arguments with Option(...) defaults by design.
+"src/quality_docs_validator/cli.py" = ["B008"]
diff --git a/src/quality_docs_validator/core/report.py b/src/quality_docs_validator/core/report.py
index 516cc4f..3057902 100644
--- a/src/quality_docs_validator/core/report.py
+++ b/src/quality_docs_validator/core/report.py
@@ -9,7 +9,7 @@
import json
from collections import Counter
-from datetime import datetime, timezone
+from datetime import UTC, datetime
from pathlib import Path
from rich.console import Console
@@ -36,7 +36,7 @@
def render_markdown(result: ValidationResult, pfmea_name: str, control_plan_name: str) -> str:
- generated = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+ generated = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
lines: list[str] = []
lines.append("# PFMEA ↔ Control Plan Validation Report")
lines.append("")
@@ -93,7 +93,7 @@ def build_report_data(
"metadata": {
"tool": TOOL_NAME,
"version": __version__,
- "generated_at": datetime.now(timezone.utc).isoformat(),
+ "generated_at": datetime.now(UTC).isoformat(),
"format": "json",
},
"inputs": {
diff --git a/tests/test_json_output.py b/tests/test_json_output.py
index 375d8f1..206f1d4 100644
--- a/tests/test_json_output.py
+++ b/tests/test_json_output.py
@@ -55,7 +55,7 @@ def test_json_generated_with_flag(example_files, tmp_path: Path) -> None:
assert out.exists()
# Parseable JSON.
data = json.loads(out.read_text(encoding="utf-8"))
- assert set(["metadata", "verdict", "score", "summary", "findings"]) <= set(data)
+ assert {"metadata", "verdict", "score", "summary", "findings"} <= set(data)
def test_json_metadata_shape(example_files, tmp_path: Path) -> None: