docs: M6 — mental model, production recipes, boundaries, godoc polish

[ehabterra]

Summary

The M6 docs milestone, delivered as ROADMAP defined it — "the deep pass, grounded in the dogfood app (not before)". Stacked on #28 (the recipes reference the migration diff).

docs/guides/MENTAL_MODEL.md — how to think in Petri nets

The narrative guide: unlearning the status VARCHAR habit (a marking is a set), parallelism as state not threads, the three kinds of "or" and who decides each (data → XOR guards, first-arriving branch → OR-input, everyone → AND-join), cycles, reset arcs as declared cancellation, host-driven time, and the instance-per-entity vs shared-pool modeling choice. Ends with a worked six-requirement → six-construct translation. Every idea names its expense_approval counterpart.

docs/guides/PRODUCTION_RECIPES.md — crash windows and idempotency (friction #5–8)

• Execute retry resets — the silent append-on-retry bug, with the reset rule (friction add badges #6)
• Exactly-once audit — WithTxSideEffect / WithFireDueTxSideEffect, with the tests that prove rollback
• Webhook idempotency by error mapping — the ErrNotEnabled → 200-no-op table
• Cross-instance saga — ordered idempotent writes + one reconciler case per crash window, from the dogfood's Reconcile (friction support yaml and guard expr #5)
• Creation seed — one-Execute seeding makes the crash artifact precisely characterizable, then GC it (friction unit tests #8)
• Listener at-least-once semantics, token-query lock re-entrancy (friction Badges #7, wrong-vs-right example), migration approval as a policy over the diff
• Closes with a 7-point checklist for any persistence-touching feature

docs/BOUNDARIES.md — what the library deliberately does not do

The ROADMAP's honest statements written out — not a durable-execution engine, no internal clock, listeners at-least-once, history opt-in, org structure in the host, cross-instance atomicity is a seam, no static analyzer yet — each with the host-side pattern and where its worked example lives.

Godoc polish

Refreshed package doc (Execute write path, transactional effects, token read-model, current flowchart renderer — it still said "state diagram"); RETRY RESETS callout with example on Manager.Execute; LOCK RE-ENTRANCY warning on token_query.go (file header + every predicate-taking API).

Housekeeping

README gains a documentation index table; FRICTION entries 5–8 marked ✅ documented (every entry in the log is now shipped or documented); ROADMAP M6 marked ✅ delivered — the full README rewrite deliberately stays at the v1.0 gate.

Checklist

• gofmt -s -l . prints nothing / go vet ./... passes (code changes are comments only)
• go test ./... passes (root + examples, run serialized)
• All new docs' relative links verified to resolve
• CHANGELOG.md updated under [Unreleased]
• Docs/examples only describe behavior the engine can actually execute (test names and API signatures verified against code)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• main
• develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b983d06-4379-4ed9-bf4f-ca9df4f783df

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch m6-guides

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.29%. Comparing base (7753a00) to head (dc97285).

Additional details and impacted files

@@                Coverage Diff                @@
##           fingerprint-diff      #29   +/-   ##
=================================================
  Coverage             81.29%   81.29%           
=================================================
  Files                    30       30           
  Lines                  3128     3128           
=================================================
  Hits                   2543     2543           
  Misses                  366      366           
  Partials                219      219           

Files with missing lines	Coverage Δ
manager.go	84.87% <ø> (ø)
token_query.go	68.29% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.