[gvegayon]

NH-3 of natural-history.md (Section 11): the docs and the model diagrams, written once against the final API (natural histories, variants by id, plain classes). The other half of NH-3, the epiworld-benchmark runners and rerun, is UofUEpiBio/epiworld-benchmark#35: attack rates agree, but the simulation time regressed in three rows; the profile traces it to the natural-history engine's reset (not to V-1 or V-2), to be fixed in an epiworld PR before Phase 4.

Diagrams drawn from the declarations

• NaturalHistory::draw_mermaid(prefix, stages): the stages and transitions as the body of a mermaid flowchart. Infectious, carrier and contact-0 stages get the classes infectious, carrier and away; each transition is an edge labeled with its name (unless the default "From -> To"), its kind and its value (infection: Transmission probability, rate: 1 / Hospitalization period, after: lognormal(Incubation period, Incubation period sd), since Rash, ...), with --> for infections and rates, ==> for durations, -.-> for external transitions; branches go to each target with its probability; status transitions list their when() stages.
• Model::draw_natural_history(): the whole model, stages and (if any) statuses in their own subgraphs. Needs no run.
• make diagrams (script/draw-diagrams.cpp) writes include/epiworld/models/<id>.mmd and include/measles/<id>.mmd for every registered model (and SIRLogit, built directly). The hand-drawn files of the old state products are replaced; surv.mmd is new. AGENTS.md now says to rerun it when a model's declarations change.
• Test 12 (diagrams) checks the SEIR's nodes, classes and edges, a statuses subgraph with a when() and a since(), and that a model without a natural history throws.
• The PNGs in docs/assets/img are rendered from the new files with the existing make all (mermaid.ink); seirquarantine.png is new and linked from its header. surv.png is not included: the render service returned "Service Unavailable" for it; rerun make -C include/epiworld/models all to add it.

Docs

• README: no longer "a template library" or C++11 (C++17); the features name natural histories, statuses and layers; the two programs' output is the current one (helloworld.cpp updated to the code the README shows); "Simulation Steps" and "Agents" describe stages, statuses, the four kinds of transition, the day's order, and one virus per agent.
• docs/impl:
  • extending-the-library-with-models.md rewritten: declaring a natural history (the four kinds, values, durations, branches, samplers, statuses, reactions), the current ModelSIS, the run loop, and events (applied in queue order; a transition applies only if the agent is still in a source: not LIFO).
  • extending-the-library.md: custom behaviors as value functions, statuses and reactions; network rewiring through set_rewiring(); the global-event and data examples use the current API.
  • Three pages that were empty are written: virus-and-tool-distribution.md (assign), quarantine-isolation-and-contact-tracing.md (statuses, reactions, layer logs), events-and-multi-event-handling.md (what a stage proposes each day, and how competing events resolve).
  • core-simulation-models.md: stages and statuses, diagrams, the registry; the SIRLogit and Surveillance constructors fixed.
  • data-collection-and-analysis.md: counts by (status, stage), get_today_total_stage() / get_today_total_status(), transitions by name, get_run_outputs(); the example that called the database's recorders directly is gone.
  • transmission-sampling.md: which stages are pushed to, in terms of the declarations (no update functions, no RTTI).
  • mixing-and-entity-distribution.md (titled "Mixing by Group"): the overview said a contact matrix's rows sum to 1; it holds expected contacts per day. distribute_tool_to_groups() became assign::group_shares().
  • Template mentions removed from library-architecture.md, performance-optimization.md, queueing-system.md; the models' @briefs no longer say "Template for".
• Every new code example was compiled and run against these headers.

Checks

make test WITH_OPENMP=0 in the container: all 137 test cases pass. helloworld.cpp and readme.cpp run.

Runbook (11.6): NH row and "Next" updated; V row marks #365 merged.

🤖 Generated with Claude Code

[github-actions]

Thank you for your contribution @gvegayon 🚀! Your documentation-site-pr-366 is ready for download 👉 here 👈!
_{(The artifact expires on 2027-02-05T09:28:21Z. You can re-generate it by re-running the workflow here.)}

[codecov]

Codecov Report

❌ Patch coverage is 72.32143% with 31 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v1-layers@d571d3e). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
include/epiworld/naturalhistory-meat.hpp	63.95%	14 Missing and 17 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             v1-layers     #366   +/-   ##
============================================
  Coverage             ?   77.07%           
============================================
  Files                ?       70           
  Lines                ?     8005           
  Branches             ?     1569           
============================================
  Hits                 ?     6170           
  Misses               ?     1336           
  Partials             ?      499           

Flag	Coverage Δ
unittests	77.07% <72.32%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[gvegayon]

Review finding: docs/assets/img/measlesmixing.png is not a PNG; it is a 19-byte plain-text response, "Service Unavailable". This makes the documentation render a broken image. Please rerun image rendering after the service is available (or omit the generated asset until then) and commit a valid PNG.