docs: publish reviewed engine guide and validation handbook

.gitattributes

@@ -6,3 +6,5 @@
 *.png binary
 *.ppm binary
 docs/reports/generated/* linguist-generated=true
+*.docx binary
+*.xlsx binary

README.md

@@ -158,3 +158,8 @@ unverified compilers/platforms. See [docs/operations.md](docs/operations.md).
 ## License
 
 [MIT](LICENSE)
+## Documentation editions
+
+Start with the [organized handbook](docs/handbook.md) for current usage, design, security and test guidance. Reviewed downloadable editions: [project-guide.docx](docs/reports/project-guide.docx).
+
+[Publication identities and source scope](docs/reports/publications.json) · [Documentation validation record](docs/reports/documentation-refresh-2026-11-09.md). Historical results retain their own tested revision and date.

docs/file-catalog.md

@@ -95,3 +95,12 @@ For declaration-level locations, see the generated [code index](code-index.md).
 | `docs/reports/test-summary.md` | Records test scope, dated local results, and limitations. |
 | `docs/reports/validation.md` | Records compiler, SDL, repository, artifact, and pending hosted-CI validation. |
 | `docs/reports/generated/.gitkeep` | Preserves the otherwise-empty directory used for generated CI reports. |
+
+## Reviewed documentation editions
+
+| File | Responsibility |
+| --- | --- |
+| `docs/handbook.md` | Organizes current usage, design, security and validation guidance. |
+| `docs/reports/project-guide.docx` | Reviewed readable Word guide of the cited public source and dated evidence. |
+| `docs/reports/publications.json` | Binds exact Office bytes, source revision, page review and workflow observations. |
+| `docs/reports/documentation-refresh-2026-11-09.md` | Records publication checks, current review and historical-evidence limits. |

docs/handbook.md

@@ -0,0 +1,53 @@
+# Forge2D Engine handbook
+
+By Jason Stys.
+
+The implementation adds bidirectional collision category and mask filters, versioned scene migration, deterministic state hashes and initial/final overlap CSV inspection.
+
+Supports practical game-world collision layers and reproducible debugging against independent geometry oracles.
+
+## Read the documentation
+
+| Edition | Audience and contents |
+| --- | --- |
+| [project-guide.docx](reports/project-guide.docx) | User and developer guide: purpose, current usage, design, boundaries and source references. |
+
+The editable Markdown remains the maintenance source. The Word files are readable editions, and the workbook is an evidence index rather than a test runner. See [publication identities and review](reports/publications.json) and the [documentation refresh record](reports/documentation-refresh-2026-11-09.md).
+
+## Current usage and help
+
+[README quick start](../README.md) is the entry point. Use the project-specific guides below before changing inputs, operating modes or deployment assumptions.
+
+### Usage and operations
+
+- [operations](operations.md)
+
+### Design and contracts
+
+- [adr/0001 headless core and optional sdl3](adr/0001-headless-core-and-optional-sdl3.md)
+- [api](api.md)
+- [architecture](architecture.md)
+- [complexity](complexity.md)
+- [research](research.md)
+
+### Security and validation
+
+- [testing](testing.md)
+
+## Historical results and reproduction
+
+The reviewed source is [`43fd93f79043231230a4c19346bdb8a4c356d9ce`](https://github.com/JasonStys/forge2d-engine/tree/43fd93f79043231230a4c19346bdb8a4c356d9ce). The observed functional workflow baseline is `43fd93f79043231230a4c19346bdb8a4c356d9ce`; those observations are recorded at `2026-11-10T05:25:40.628667+00:00`. They do not certify an unrun later revision.
+
+- [Detailed recorded validation](reports/practical-workflows-20261109.md)
+- [Current Actions](https://github.com/JasonStys/forge2d-engine/actions) records later integration checks separately.
+- Preserve dated measurements and follow the existing testing guide to reproduce them; a test-source inventory alone does not establish execution.
+
+## Practical boundaries
+
+- Category/mask filtering selects AABB query candidates; it does not add physical collision response, enter/exit callbacks or navigation changes.
+- Filter words change numeric state fingerprints even for legacy default filters; replay input grammar remains version 1.
+- Raw queries cannot establish current entity-generation validity; World owns lifetime checks. This is a fictional integer 2D game engine.
+
+## Maintaining these editions
+
+Update the editable usage/design/test documents first. Rebuild and visually review every Word page and workbook tab before replacing an edition; verify the exact binary digests and evidence source in publications.json. Keep account data, logs with secrets, installed-app state and private test stores out of documentation. Source and release assets retain their existing security and licensing boundaries.

docs/reports/documentation-refresh-2026-11-09.md

@@ -0,0 +1,37 @@
+# Documentation refresh — 2026-11-09
+
+By Jason Stys.
+
+This documentation-only edition describes source `43fd93f79043231230a4c19346bdb8a4c356d9ce`. It does not change application behavior, accounts, private data, installers or published releases.
+
+## Published editions and completed review
+
+| File | Bytes | SHA-256 | Reviewed scope |
+| --- | ---: | --- | --- |
+| [project-guide.docx](project-guide.docx) | 45218 | `f8b0f4ed73dd19cd3d58991091df0519c93916d864c10f4b392ecbfd1f3372c1` | 5 pages, each viewed individually |
+
+Word review checked plain black titles, readable pagination, whole table rows, source references, practical limits and absence of clipping or overflow. Render receipts were matched to the current DOCX digest before approval. Workbook review inspected both tab previews and actual exported Table/autoFilter elements; recalculated success/failure summaries were compared independently with workflow metadata. Static previews do not draw Excel dropdown arrows; the exported workbook contains the actual filters.
+
+## Evidence and change boundary
+
+- Functional baseline: `43fd93f79043231230a4c19346bdb8a4c356d9ce`.
+- Workflow observation: `2026-11-10T05:25:40.628667+00:00`; exact run URLs and source identities remain in [publications.json](publications.json).
+- Local document-package validation verifies exact copied bytes, Office ZIP integrity, approved page/tab identities and internal documentation links. Repository-specific documentation and source-policy commands are run separately and recorded in the integration handoff.
+- Source/index metadata is regenerated using the repository’s existing tools. Existing privacy, security, coverage and workflow gates are retained.
+- PR and later main workflows must pass independently. This record does not claim future or unrun integration CI success.
+
+## Interpretation
+
+The Word files document the cited source; dated source reports retain their original execution scope. A passing workflow is distinct from completed analysis with zero findings, and neither establishes production suitability. The Excel source inventory is not a per-test execution report. Checksums identify exact bytes, not a signature or publisher attestation.
+
+Use the [handbook](../handbook.md) to choose usage, design, security and test documentation. Keep editable Markdown and reviewed editions together; do not replace historical measurements with undated claims.
+
+## Integration-local validation
+
+The exact copied Word package, current DOCX/render/page hashes, Office ZIP integrity,
+source/workflow identities and handbook/report links passed independent checks.
+`node scripts/generate-code-index.mjs --check` and
+`node scripts/validate-repository.mjs` passed; `git diff --check` passed.
+These documentation checks do not rerun native simulations or replace subsequent
+PR and main CI. Runtime, user data, installed software and public releases are
+unchanged.

docs/reports/practical-workflows-20261109.md

@@ -8,27 +8,27 @@ matching. The optimized spatial query and independent quadratic reference apply
 their own inclusion predicates; World propagates body metadata unchanged. Drawing,
 position integration and boundary response stay independent of filtering.
 
-Scene writers use v2; v1 remains readable with category1/all mask bits. Both filter
+Scene writers use v2; v1 remains readable with category 1 / all mask bits. Both filter
 words belong to state hashing, intentionally changing old numeric fingerprints.
 The replay input format is unchanged. Unknown versions and bad/missing/negative/
 overflowing filter fields remain errors. A v2 fuzz seed exercises the new grammar.
 
 ## Observed local evidence
 
-- MSVC warning-as-error release build and10/10 native test groups passed.
-  150 fixed-seed50-item scenes with varied masks/categories exactly match the
+- MSVC warning-as-error release build and 10/10 native test groups passed.
+  150 fixed-seed 50-item scenes with varied masks/categories exactly match the
   independent quadratic oracle. A hand matrix requires exactly player/character
   and player/zone matches; reverse ordering, bit31, zero masks, invalid categories,
   real World propagation, invalid-spawn atomicity and v1/v2 round trips are tested.
-- Both actual CLI demonstrations completed360ticks. The five-entity filtered
+- Both actual CLI demonstrations completed 360 ticks. The five-entity filtered
   example yielded exactly two initial pairs and zero final pairs; CSV rows list
   the correct category/mask values. Canonical scene, replay and PPM were produced.
   Initial/final are two snapshots, not collision episode/trajectory evidence.
-- Existing20,000-entity benchmark passed unchanged budgets: storage1.267ms,
-  broadphase7.181ms, simulation4.651ms on this PC. Timings are not real-time claims.
+- Existing 20,000-entity benchmark passed unchanged budgets: storage 1.267 ms,
+  broadphase 7.181 ms, simulation 4.651 ms on this PC. Timings are not real-time claims.
 - Formatting and generated source-index/repository checks passed. A native
   header/library/CMake-target install into a fresh project-local prefix passed.
-  Optional SDL3.4.16 frontend rebuilt from the existing pinned local source.
+  Optional SDL 3.4.16 frontend rebuilt from the existing pinned local source.
   Warning-denying Clang-tidy passed on all five changed implementation/test units;
   existing vendor-header warnings remained outside the configured user-code scope.
   Its first attempt lacked standard-library include paths; the identical policy
@@ -40,10 +40,10 @@ overflowing filter fields remain errors. A v2 fuzz seed exercises the new gramma
 
 ## Limits
 
-This is a fictional integer2D game-engine query feature, with no real-world
+This is a fictional integer 2D game-engine query feature, with no real-world
 tracking, targeting, flight, physics calibration or weapon control. Filtering
 does not prevent bodies from passing through each other, apply forces or supply
 enter/exit trigger callbacks. Consumers own gameplay reactions and must pass
 currently valid handles to raw queries. State hashes are deterministic fingerprints,
 not cryptographic attestation. No user scenes, existing outputs or services were
-deleted. Parent owns remote CI/publication; no Actions triggered here.
+deleted. This dated local session did not execute hosted workflows; source-specific hosted results are linked separately in the documentation edition.

docs/reports/publications.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "project": "forge2d-engine",
+  "author": "Jason Stys",
+  "editionDate": "2026-11-09",
+  "sourceBaseline": "43fd93f79043231230a4c19346bdb8a4c356d9ce",
+  "sourceUrl": "https://github.com/JasonStys/forge2d-engine/tree/43fd93f79043231230a4c19346bdb8a4c356d9ce",
+  "functionalEvidenceBaseline": "43fd93f79043231230a4c19346bdb8a4c356d9ce",
+  "evidenceObservedAt": "2026-11-10T05:25:40.628667+00:00",
+  "workflowEvidence": [
+    {
+      "conclusion": "success",
+      "databaseId": 42714064217,
+      "event": "push",
+      "headSha": "43fd93f79043231230a4c19346bdb8a4c356d9ce",
+      "name": "CI",
+      "status": "completed",
+      "url": "https://github.com/JasonStys/forge2d-engine/actions/runs/42714064217"
+    },
+    {
+      "conclusion": "success",
+      "databaseId": 42714064589,
+      "event": "push",
+      "headSha": "43fd93f79043231230a4c19346bdb8a4c356d9ce",
+      "name": "CodeQL",
+      "status": "completed",
+      "url": "https://github.com/JasonStys/forge2d-engine/actions/runs/42714064589"
+    }
+  ],
+  "summary": "The implementation adds bidirectional collision category and mask filters, versioned scene migration, deterministic state hashes and initial/final overlap CSV inspection.",
+  "rationale": "Supports practical game-world collision layers and reproducible debugging against independent geometry oracles.",
+  "limitations": [
+    "Category/mask filtering selects AABB query candidates; it does not add physical collision response, enter/exit callbacks or navigation changes.",
+    "Filter words change numeric state fingerprints even for legacy default filters; replay input grammar remains version 1.",
+    "Raw queries cannot establish current entity-generation validity; World owns lifetime checks. This is a fictional integer 2D game engine."
+  ],
+  "documents": [
+    {
+      "filename": "project-guide.docx",
+      "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "bytes": 45218,
+      "sha256": "f8b0f4ed73dd19cd3d58991091df0519c93916d864c10f4b392ecbfd1f3372c1",
+      "sourceBaseline": "43fd93f79043231230a4c19346bdb8a4c356d9ce",
+      "visualReview": {
+        "approved": true,
+        "method": "Every rendered page individually viewed at readable original resolution",
+        "pageCount": 5,
+        "renderedPageSha256": {
+          "page-1.png": "ed3d4acc6f5d060dfbbf0059d8b32fd40718cfab01df809fd302aaa5d73219e8",
+          "page-2.png": "69892ce958fb026019c2e321e984f8a13ec7541b7f0822caa2bd8cb48a9ea564",
+          "page-3.png": "ef62413c61cdc31de1e23d4c1cc29bd8c981a6288c99ea64e1c5cc5c8e830230",
+          "page-4.png": "db32dd727c0a38ed9920b60bfd22b32cc87b83421fd83565419fec1178e3a8b0",
+          "page-5.png": "46d3b7b19fd6fff5046c29d59c95b0a2a75983976541904288b815029c69b91c"
+        }
+      }
+    }
+  ],
+  "scope": "Reviewed documentation editions of the cited source. Checksums identify bytes, not authorship. Historical measurements retain their own dates; integration CI must be checked separately."
+}