Clarify maintainer positioning and quick demo

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.0 - 2026-06-02
+
+- Added a first-impression README pass with clearer maintainer use cases and public validation/release badges.
+- Added a quick demo path so maintainers can validate the kit, install one skill into a temporary target, and try a reusable workflow prompt.
+
 ## 0.3.0 - 2026-06-01
 
 - Added a skill installer script and install/use guide so maintainers can adopt the kit more directly.

README.md

@@ -1,8 +1,13 @@
 # Codex Operator Kit
 
+[![validate](https://github.com/TheRobertRay/codex-operator-kit/actions/workflows/validate.yml/badge.svg)](https://github.com/TheRobertRay/codex-operator-kit/actions/workflows/validate.yml)
+[![release](https://img.shields.io/github/v/release/TheRobertRay/codex-operator-kit?label=release)](https://github.com/TheRobertRay/codex-operator-kit/releases/latest)
+
 Reusable prompt contracts, review gates, and maintenance workflows for running coding agents on real repositories without losing source-of-truth discipline.
 
-This repository is intentionally small. It packages field-tested operator patterns into files that other maintainers can copy into their own repos:
+If you maintain software with coding agents in the loop, this kit gives you copyable operating patterns for the work that usually breaks trust: ambiguous task intake, issue and PR triage, delegated implementation, release readiness, and public/private context screening.
+
+This repository is intentionally small. It packages worked-through operator patterns into files that other maintainers can copy into their own repos:
 
 - `AGENTS.md` prompt intake contract for ambiguous or dictated tasks
 - conversation capture receipts for rough chat, voice notes, and inbox dumps
@@ -12,9 +17,18 @@ This repository is intentionally small. It packages field-tested operator patter
 - validation and publication-risk scripts that check for broken placeholders, missing sections, and private-context leaks
 - public examples for issue triage, PR review, and release-readiness gates
 
+## What You Can Use Today
+
+| Maintainer problem | Use this | Outcome |
+| --- | --- | --- |
+| Rough user input turns into the wrong task | `templates/AGENTS.md` and `conversation-capture-receipts` | A clear receipt before writes happen |
+| Agent work passes local checks but misses the real risk | `milestone-review` and completion critic gates | A second pass against false-positive completion |
+| Private workflow knowledge needs to become public OSS material | `docs/publication-risk.md` and `scripts/check-publication-risk.sh` | Sanitized examples without private paths, hostnames, or secrets |
+| A maintainer wants to try the kit quickly | `scripts/install-skills.sh` and `docs/quick-demo.md` | A dry-run and temp install path before touching an existing setup |
+
 ## Current Status
 
-Codex Operator Kit was published on 2026-06-01 as a public OSS workspace for Codex operator workflows. The first release is intentionally compact: copyable contracts, skills, examples, and validation checks that can be reused by maintainers.
+Codex Operator Kit was published on 2026-06-01 as a public OSS workspace for Codex operator workflows. It is intentionally compact: copyable contracts, skills, examples, and validation checks that can be reused by maintainers.
 
 ## Who This Is For
 
@@ -34,7 +48,9 @@ Copy the contract into a repository:
 cp templates/AGENTS.md AGENTS.md
 ```
 
-Copy one or more skills into your local Codex skills directory:
+Try the maintainer demo in `docs/quick-demo.md` first if you want a temporary install path.
+
+Copy one or more skills into your local Codex skills directory when you are ready to use them in your setup:
 
 ```bash
 bash scripts/install-skills.sh --dry-run
@@ -61,6 +77,7 @@ bash scripts/check-publication-risk.sh
 - `skills/milestone-review/SKILL.md` - milestone and adversarial completion review workflow
 - `docs/maintenance-model.md` - the operating model behind the kit
 - `docs/install-and-use.md` - installer and adoption guide
+- `docs/quick-demo.md` - short maintainer demo path
 - `docs/workflows.md` - copyable maintainer workflows
 - `docs/publication-risk.md` - how to screen workflow packs before publishing
 - `examples/` - sanitized example packets and receipts

docs/quick-demo.md

@@ -0,0 +1,59 @@
+# Quick Demo
+
+This demo shows the smallest useful path through Codex Operator Kit from a repo checkout: validate the public package, install one skill into a temporary target, then use a maintainer workflow prompt on a sanitized example.
+
+## 1. Validate The Kit
+
+```bash
+bash scripts/validate.sh
+```
+
+Expected result:
+
+```text
+publication risk check passed
+application field lengths ok
+validation ok
+```
+
+## 2. Install One Skill Into A Temporary Target
+
+```bash
+demo_target="$(mktemp -d)/skills"
+bash scripts/install-skills.sh --target "$demo_target" conversation-capture-receipts
+```
+
+Expected result:
+
+```text
+installed conversation-capture-receipts -> ...
+```
+
+The installer replaces same-named skill directories in the target. Using a temporary target keeps the demo separate from an existing Codex setup.
+
+## 3. Run A Maintainer Prompt
+
+From the repo checkout in Codex, use this prompt. It asks Codex to read the skill file directly, so the temp install above can stay isolated from your real setup.
+
+```text
+Read skills/conversation-capture-receipts/SKILL.md and examples/conversation-capture-receipt.md. Explain the reusable receipt pattern in plain language. Then draft a fresh no-write receipt for this rough input:
+
+"I think the agent fixed the bug, but I do not know what changed, what was verified, or whether it touched anything private. I need a clear receipt before I merge."
+```
+
+A good answer should produce a no-write receipt that separates:
+
+- what was caught
+- what is still uncertain
+- what would need verification before a merge
+- what should stay private or out of public release notes
+
+## 4. Try The Other Maintainer Workflows
+
+Use the same pattern with:
+
+- `skills/oss-maintainer-triage/SKILL.md` and `examples/issue-triage.md`
+- `skills/milestone-review/SKILL.md` and `examples/pr-review-gate.md`
+- `docs/workflows.md` for release readiness and publication-risk gates
+
+The point is not to adopt a framework. The point is to make agent-assisted maintenance more reviewable, more honest about uncertainty, and safer to publish.

scripts/validate.sh

@@ -15,6 +15,7 @@ required=(
   ".github/ISSUE_TEMPLATE/workflow-improvement.yml"
   "docs/install-and-use.md"
   "docs/maintenance-model.md"
+  "docs/quick-demo.md"
   "docs/publication-risk.md"
   "docs/workflows.md"
   "docs/codex-for-oss-application.md"