From 8f6877daccfb1f6c3f9b41521f5f43a9dc1f77ae Mon Sep 17 00:00:00 2001
From: Bruno Vicco <bfvicco@gmail.com>
Date: Mon, 20 Jul 2026 08:25:40 -0300
Subject: [PATCH] docs(readme): add five-minute evaluation and use/do-not-use
 guidance

Mirrors the sibling codex-python-engineering-harness README: a disposable,
credential-free local evaluation ending in a single quality-gate run, and
the explicit anti-sell sentence. Closes the last README asymmetry between
the siblings.
---
 CHANGELOG.md |  6 ++++++
 README.md    | 17 +++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52128e4..54ee814 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+### Added
+
+- README "Five-minute evaluation" section, matching the sibling
+  `codex-python-engineering-harness`: a disposable, credential-free local evaluation with a
+  single quality-gate command, plus explicit use / do-not-use guidance.
+
 ## 1.0.0 - 2026-07-19
 
 First tagged release. Consolidates the loop foundation below and closes the structural-parity gap
diff --git a/README.md b/README.md
index 028c7f5..a5bbe0f 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,23 @@ For a short hands-on walkthrough, generated tree, profile comparison, and explic
 criteria, see the [evaluation guide](docs/EVALUATION.md). A complete generated service is available
 in [`brunovicco/claude-python-engineering-harness-example`](https://github.com/brunovicco/claude-python-engineering-harness-example).
 
+## Five-minute evaluation
+
+Requirements: Python 3.12 or newer and `uv`.
+
+```bash
+target="$(mktemp -d)/harness-evaluation"
+python3 bootstrap.py --name evaluation --package evaluation --target "$target" --profile service
+cd "$target"
+uv sync --all-groups
+uv run python scripts/quality_gate.py
+```
+
+Then inspect `CLAUDE.md`, `.claude/settings.json`, `.claude/rules/`, `.claude/hooks/`, and
+`docs/ARCHITECTURE.md`. This evaluation creates only a disposable local project and requires no
+credentials. Use the harness when you want an opinionated, repository-owned engineering baseline;
+do not use it when an existing project cannot adopt its uv workflow or architectural constraints.
+
 ## Profiles
 
 - `service` keeps Pydantic, structlog, Clean Architecture, Docker, and optional Langfuse tracing.