docs: audit accuracy, measure coverage, and reorganize #79

Merged

gabogg merged 3 commits from docs/audit-and-reorganize into master

2026-09-25 00:03:47 +00:00

gabogg commented

2026-09-24 23:05:38 +00:00

Owner

Problem

Documentation mixes current behavior, historical proposals, and dated audits. The former API guide named 19 method/path pairs: 11 matched the registered app routes, 8 were stale, and 55 of 66 registered operations were absent. Other high-impact mismatches include the default port, business-cycle reset and DST arithmetic, the calibration audit table, and the door measurements glossary.

Approach

Audit the current docs against OpenAPI, config, facility-time code, schema, and domain decisions; record evidence, coverage limits, and remaining gaps in docs/audit/documentation-coverage-2026-09-24.md.
Reorganize the index by reader task. Move historical proposals into docs/design-history/, move the math background into docs/explanations/, normalize moved filenames, and repair links and agent pointers.
Replace the API guide with a complete 66-operation route inventory and add scripts/check_docs.py to detect route drift and broken local Markdown targets.
Correct confirmed current-doc errors in the system overview, README, statistical cycle explanation, and door glossary.

Verification

Documentation checker: 33 Markdown files and 66/66 registered HTTP operations.
Ruff lint and format checks.
pytest -q: 283 passed.
Documentation link and route check added to CI.
node --test tests/frontend/*.test.js: 6 passed.
Review findings resolved; current documentation checked for reset and route consistency.

The operation count measures route presence, not prose accuracy. The audit did not verify vendor .docx content, host-specific operations, or every sentence in the baseline docs. No application behavior changes and no merge requested.

Domain and model wording: #40, #49, #66, #76, #77.
Build/design history: #57.
Telemetry and localization contracts: #67, #73.

These issues remain open under their own acceptance criteria; this PR only corrects the documented portions named in the audit.

## Problem Documentation mixes current behavior, historical proposals, and dated audits. The former API guide named 19 method/path pairs: 11 matched the registered app routes, 8 were stale, and 55 of 66 registered operations were absent. Other high-impact mismatches include the default port, business-cycle reset and DST arithmetic, the calibration audit table, and the door measurements glossary. ## Approach - Audit the current docs against OpenAPI, config, facility-time code, schema, and domain decisions; record evidence, coverage limits, and remaining gaps in `docs/audit/documentation-coverage-2026-09-24.md`. - Reorganize the index by reader task. Move historical proposals into `docs/design-history/`, move the math background into `docs/explanations/`, normalize moved filenames, and repair links and agent pointers. - Replace the API guide with a complete 66-operation route inventory and add `scripts/check_docs.py` to detect route drift and broken local Markdown targets. - Correct confirmed current-doc errors in the system overview, README, statistical cycle explanation, and door glossary. ## Verification - [x] Documentation checker: 33 Markdown files and 66/66 registered HTTP operations. - [x] Ruff lint and format checks. - [x] `pytest -q`: 283 passed. - [x] Documentation link and route check added to CI. - [x] `node --test tests/frontend/*.test.js`: 6 passed. - [x] Review findings resolved; current documentation checked for reset and route consistency. The operation count measures route presence, not prose accuracy. The audit did not verify vendor `.docx` content, host-specific operations, or every sentence in the baseline docs. No application behavior changes and no merge requested. ## Related issues - Domain and model wording: #40, #49, #66, #76, #77. - Build/design history: #57. - Telemetry and localization contracts: #67, #73. These issues remain open under their own acceptance criteria; this PR only corrects the documented portions named in the audit.

gabogg added 1 commit

2026-09-24 23:05:39 +00:00

docs: audit code coverage and reorganize documentation

CI / lint-and-test (pull_request) Successful in 1m25s

Details

fe6e455fa0

gabogg added 1 commit

2026-09-24 23:31:08 +00:00

docs: resolve PR 79 review findings and verify references

CI / lint-and-test (pull_request) Successful in 1m25s

Details

804091fa38

gabogg changed title from ~~WIP: docs: audit accuracy, measure coverage, and reorganize~~ to docs: audit accuracy, measure coverage, and reorganize

2026-09-24 23:31:37 +00:00

gabogg added 1 commit

2026-09-25 00:03:04 +00:00

test(docs): annotate documentation checker test

CI / lint-and-test (pull_request) Successful in 1m24s

Details

c10ed01c6d

gabogg merged commit 7377d5afb7 into master

2026-09-25 00:03:47 +00:00

gabogg referenced this pull request from a commit

2026-09-25 00:03:48 +00:00

Merge pull request 'docs: audit accuracy, measure coverage, and reorganize' (#79) from docs/audit-and-reorganize into master