docs: add sequence diagrams and per-audience mental models

[mvandeberg]

The Boost review asked for up-front mental models for each kind of reader and for sequence diagrams of the component interactions (#399).

Mental models and diagrams:

• New Mental Models page, after Conventions. It has a sequence diagram of a task starting, suspending on I/O and resuming through the executor. A short model and reading path follow for each of the three audiences that P4172R1 section 3 defines: application developers (with a subsection for protocol libraries on streams), framework authors and I/O library authors. Each audience gets the facilities the paper assigns it, and the paths name example programs where they exist.
• 4f gains "The Cancellation Sequence": a sequence diagram of a stop request reaching a suspended task, the race between the stop callback and normal completion, and a warning about that race.
• Each diagram has a numbered step list that matches its arrows, plus mermaid accTitle/accDescr, so the content survives without JS. The messages sit on a white rect panel so they read in dark mode: mermaid draws Incorrectly assuming operator-> exists #333 lines on a transparent SVG, and mermaid 10 strips themeCSS from diagram directives.
• Linked from nav, index Next Steps, the 4c execution model and the examples intro.

Stoppable awaitables:

• The "correct pattern" snippet on 4e and 4f posted the coroutine from the stop callback unconditionally, so it resumed twice when the operation also completed. The Dangerous Pattern now shows that mistake. Inline resume is covered by a link to 4e.
• The replacement, read_op in 4f_cancellation.cpp, races the stop callback and the completion on one atomic claim. An arrival count makes the winner wait for the end of await_suspend, so the coroutine cannot resume and free the awaiter or its io_env while await_suspend still runs, even on a thread_pool. 4e links to it instead of keeping its own copy.
• The test races complete() against request_stop() from the moment the wait is armed, on a two-thread pool. It is TSan-clean, and TSan reports each mutation that drops a claim or the arrival count.

Tests and lint:

• mental_models_trace.cpp runs the How a Task Runs sequence on a recording executor and exits non-zero if the order differs from the diagram's 13 arrows.
• doc-lint exempts [mermaid] blocks from B2 and SHAPE, unless they are also [source,...]. The selftest covers both properties.
• 4f_cancellation.cpp suppresses a GCC -O3 maybe-uninitialized false positive on std::optionalstd::stop_callback in a coroutine frame.

Also fixes the gated wording findings on index.adoc and the doc-audit findings on lines this branch changed.

Closes #399

[cppalliance-bot]

An automated preview of the documentation is available at https://454.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-10-17 14:04:13 UTC

[cppalliance-bot]

GCOVR code coverage report https://454.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://454.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://454.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-10-17 14:18:17 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.33%. Comparing base (f764adc) to head (4574848).
⚠️ Report is 7 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #454      +/-   ##
===========================================
+ Coverage    98.09%   98.33%   +0.24%     
===========================================
  Files          130      137       +7     
  Lines         6289     7316    +1027     
===========================================
+ Hits          6169     7194    +1025     
- Misses         120      122       +2     

Flag	Coverage Δ
linux	98.15% <ø> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 71 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f764adc...4574848. Read the comment docs.

🚀 New features to boost your workflow:

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