[GreenGrassBlueOcean]

Problem

The README has three tables that describe the code: gateway profiles, the WHO subsystem catalog and the per-module coverage table. They were kept up to date by hand, or by two separate helper scripts that nobody had to run. CI checked none of them, so they drifted:

• WHO 17 listed only OWNSceneEvent, although OWNSceneCommand exists and is exported.
• The Declarative Hardware Profiles bullet named 6 gateways. canonical_profiles() defines 14.
• Some prose was tied to one release: "2.0.0-b7", "3,087 / 3,087 statements", "Now Live". It went stale at the next release.

Solution

New script: scripts/sync_documentation.py. It regenerates each table from the code and writes it between its README markers:

README block	Generated from
START/END_GATEWAY_PROFILES_TABLE	OWNd.profiles.canonical_profiles()
START/END_WHO_CATALOG_TABLE (new markers)	_COMMAND_DISPATCH / _EVENT_DISPATCH, plus explicit classes for WHO 3, 15, 16 and 25. Every class must exist in OWNd.message.__all__, otherwise the script fails.
START/END_COVERAGE_TABLE + coverage.svg	coverage.xml

It has two modes:

• python scripts/sync_documentation.py rewrites README.md and coverage.svg in place.
• python scripts/sync_documentation.py --check changes nothing. It exits 0 when everything is in sync. It exits 1 with a unified diff on drift, on a stale coverage.svg, or on CRLF line endings in the README. If coverage.xml is missing, it skips the coverage check.

Other changes

• CI: the quality job runs sync_documentation.py --check. That job does not build coverage.xml, so CI enforces the profiles and WHO tables only. The coverage table and badge are still refreshed locally.
• README: adds markers around the WHO table, adds OWNSceneCommand to WHO 17, lists all 14 profiles and removes the release-specific wording.
• update_readme_profiles.py now imports the table builder and markers from the new script instead of keeping its own copy. update_readme_coverage.py gets the same profiles note.

Testing

tests/test_sync_documentation.py adds 13 tests:

• table generation: profiles, WHO catalog, coverage table, SVG badge
• class validation: an unknown class or a class missing from __all__ raises an error
• verify_who_catalog_coverage(): every WHO key in _COMMAND_DISPATCH has a row in the catalog
• coverage filename normalisation and marker replacement edge cases
• the real README is in sync
• drift detection and in-place update, SVG drift in --check, CRLF detection, missing coverage.xml
• CLI modes and argument handling

Local results:

Command	Result
ruff check OWNd tests setup.py scripts	clean
mypy OWNd tests/typing	0 issues (26 files)
python scripts/verify_library_standards.py	pass
python scripts/sync_documentation.py --check	in sync, exit 0
pytest tests/	1,292 passed

All CI checks pass, including the MyHOME test suite and the golden corpus gates.

Traces

No traces are needed. The PR changes documentation and tooling only. It changes no frame parsing, no command building and no gateway behaviour.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fedem95]

Approving. Tooling and docs only (no change under OWNd/). Merged locally into current master: sync_documentation.py --check exits 0 and the suite passes (1300). CI green.

Two notes:

• --check doesn't call verify_who_catalog_coverage(), and the table is built from the fixed WHO_DEFINITIONS, so a registered WHO without a definition is silently left out of the README. Only test_who_catalog_dispatch_coverage catches it. Merging #100 on top as a test: --check still exits 0 with no WHO 6/8 rows, and that test fails with "WHO 6 / WHO 8 registered in _COMMAND_DISPATCH but not mapped in WHO_DEFINITIONS". So #100 will need two definitions, and it may be worth running the coverage check from --check too.
• Only _COMMAND_DISPATCH is checked. Event-only WHOs (0 and 9: OWNScenarioEvent, OWNAuxEvent) have no row of their own; OWNScenarioEvent (WHO 0) is listed under WHO 15.

[GreenGrassBlueOcean]

Addressed in #105:

1. sync_documentation.py --check now calls verify_who_catalog_coverage() so that any registered WHO subsystem missing from WHO_DEFINITIONS is caught during documentation anti-drift checks and in CI quality runs.
2. verify_who_catalog_coverage() now checks both _COMMAND_DISPATCH and _EVENT_DISPATCH. Dedicated rows were added to WHO_DEFINITIONS and README.md for event-only subsystems WHO 0 (OWNScenarioEvent) and WHO 9 (OWNAuxEvent), with OWNScenarioEvent cleanly removed from WHO 15.