docs: production-readiness audit + usefulness doc (dogfooded), and a README demo fix

[ajaysurya1221]

What & why

Two durable docs for new users / skeptical reviewers, plus a small correctness fix to the flagship README demo. No code behavior, warrant schema, checker grammar, exit-code, fold-policy, or security-posture change.

1. fix(docs) — README quickstart claim kind (67a09eb)

The "Try it in 30 seconds" demo claim — "handler() lives in app.py", backed by a C3 symbol: existence checker — was tagged kind: "behavior". That is precisely the mismatch the project's own --strength-gate=fail refuses (a load-bearing behavior claim backed only by an existence check), so the headline demo violated the gate dorian now ships and promotes. Retagged reference. Behavior-preserving under the default gate (off); the recipe still seals on verify and revokes on drift. The black-box README test's mirrored copy is synced — its assertions check the commands, not the kind, so all tests stay green.

2. docs — audit + usefulness + dogfood (88f064d)

• docs/PRODUCTION_READINESS_AUDIT.md — evidence-backed readiness review: live test matrix, first-hand golden-path transcript, isolated wheel-install (zero-dep) check, full security-boundary map, verdict (MOSTLY READY — with listed risks), and a ranked punch list. Honestly flags Dependabot chore(deps): bump actions/upload-artifact from 4.6.2 to 7.0.1 #9–chore(deps): bump actions/attest-build-provenance from 1.4.4 to 4.1.0 #13 as deferred (their green ci check does not exercise the release/publish workflows the major action bumps actually touch).
• docs/DORIAN_USEFULNESS.md — why dorian matters: the verification-debt problem, what it uniquely preserves, strength-labeled evidence, the trigger-vs-truth ceiling, a copy-paste user journey, and adoption fit. No invented citations.
• Dogfood: docs/changes/production-readiness-audit.md is sealed under --strength-gate=fail (verified 7/7, 0 load-bearing high-risk), with its *.claims.json and the sealed *.md.warrant committed — matching the existing docs/changes/ convention. Load-bearing facts pinned: the two-axis implementation (binding gate = trigger, strength gate = truth) and the audit's invariants — Python >=3.11 and a zero-dependency core (config-value: checkers).

Evidence (this branch's base, local)

• ruff check / ruff format --check: pass.
• Full suite: 944 tests green (853 fast + 91 slow); packaging/determinism/action/README tests re-run green with the new committed files present.
• Golden path + strength-gate ladder (off/warn/fail, atomic no-write) verified first-hand in a temp repo.

Notes

• Companion context: this opens after PR feat(seal): opt-in truth-axis --strength-gate for weak claim evidence #18 (--strength-gate) was merged to main.
• Defers Dependabot chore(deps): bump actions/upload-artifact from 4.6.2 to 7.0.1 #9–chore(deps): bump actions/attest-build-provenance from 1.4.4 to 4.1.0 #13 with a concrete verification path (see audit §8) rather than merging unverified release-path bumps.

Summary by CodeRabbit

• Documentation

  • Added new docs explaining Dorian’s role, verification approach, and production-readiness status.
  • Added a new change note and supporting claim records for the readiness audit.
  • Updated the quick-start example so the sample claim type matches the intended workflow.

• Tests

  • Updated the end-to-end README example test to align with the revised sample claim type.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR changes the README example claim kind and matching test to reference, adds a usefulness guide, and adds production-readiness audit documentation with claims and warrant files.

Changes

Production-readiness documentation

Layer / File(s)	Summary
Example claim kind README.md, tests/test_readme_example.py	The README sample claim and its test fixture change kind from behavior to reference while keeping load_bearing: true.
Usefulness guide docs/DORIAN_USEFULNESS.md	The new guide describes Dorian’s purpose, warrant mechanics, strengths, limitations, determinism properties, adoption fit, and example workflow.
Audit bundle docs/changes/production-readiness-audit.md, docs/PRODUCTION_READINESS_AUDIT.md, docs/changes/production-readiness-audit.claims.json, docs/changes/production-readiness-audit.md.warrant	The change note, audit report, claims file, and warrant document capture the production-readiness snapshot, claim set, and sealing metadata.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ajaysurya1221/dorian#18: Changes the same README/test claim kind from behavior to reference, aligning the demo with strength-gate semantics.

Poem

A rabbit hopped through docs at dawn,
With reference claims now cleanly drawn.
The warrant glowed, the audit shone,
And truth-gate crumbs were safely sewn.
🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two documentation additions and the README demo fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/production-readiness

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/PRODUCTION_READINESS_AUDIT.md (1)

87-87: 📐 Maintainability & Code Quality | 🔵 Trivial

Add language specifier to fenced code block.

The golden-path transcript code block is missing a language tag. Add bash or text to satisfy MD040 and improve rendering.

-```
+```bash

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/PRODUCTION_READINESS_AUDIT.md` at line 87, The golden-path transcript
fenced block is missing a language specifier, so update the Markdown code fence
in the production readiness audit doc to include a tag such as bash or text.
Locate the fenced block in the transcript section and make the opening fence
explicitly typed so it satisfies MD040 and renders correctly.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/PRODUCTION_READINESS_AUDIT.md`:
- Line 87: The golden-path transcript fenced block is missing a language
specifier, so update the Markdown code fence in the production readiness audit
doc to include a tag such as bash or text. Locate the fenced block in the
transcript section and make the opening fence explicitly typed so it satisfies
MD040 and renders correctly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0cd5a619-2295-414d-8669-4d5067b0e736

📥 Commits

Reviewing files that changed from the base of the PR and between b63c4db and 88f064d.

📒 Files selected for processing (7)

• README.md
• docs/DORIAN_USEFULNESS.md
• docs/PRODUCTION_READINESS_AUDIT.md
• docs/changes/production-readiness-audit.claims.json
• docs/changes/production-readiness-audit.md
• docs/changes/production-readiness-audit.md.warrant
• tests/test_readme_example.py