[DemchaAV]

Why

api-query --tasks had routes for layout and tables and none for exporting to Word. An agent asking how to write a .docx got the surfaces, which list buildDocx, DocumentSession.export and DocxSemanticBackend.builder() side by side without saying which to use, what each costs, or which of them is @Beta.

What changed

• knowledge/routing/tasks.json — a new route, export.docx:
  • use: session.buildDocx(path), writeDocx(stream) or toDocxBytes() — one call, a default backend per export; buildDocx builds the bytes first and moves them over the file only on success. No report, and the package carries the export's date. Experimental in 2.5.
  • instead, when the report or the same bytes on every run are wanted: session.export(DocxSemanticBackend.builder().deterministic(true).reportSink(...).build(), path) — the path the render-docx README settled on. The builder and DocxExportReport are @Beta; the bytes go straight over the file, so a write that breaks part-way can truncate it where buildDocx keeps the old one; it throws a plain Exception; the bytes match on one platform, not across platforms, and a {date} header or footer token still changes them with the day unless -Dgraphcompose.renderDate pins it.
  • instead, when only Stable API may be used: session.export(new DocxSemanticBackend(), path), as docs/api-stability.md keeps it.
  • instead, when the reader must see the page as laid out: buildPdf.
  • read: render-docx/README.md#usage. The prose also cites docs/recipes/docx-export.md#byte-identical-output, #finding-out-what-the-export-could-not-carry and docs/api-stability.md#1-stability-tiers; check-routes resolves each.
  • confirmedBy: null — the mechanical checks pass, and api-query prints the route as not yet confirmed until a maintainer sets it. No constraints: no DOCX behaviour claim exists in knowledge/claims/index.json to point at.
• CHANGELOG.md — a 2.5 Documentation bullet.

No Java, no public API, no generated file changed.

Verification

• node knowledge/tools/routing/check-routes.mjs — 6 routes hold up (was 5).
• node knowledge/tools/api-query/api-query.mjs --task export.docx prints the route.
• Each of the 11 symbols resolves in its surface (DocumentSession.* in authoring; DocxSemanticBackend, its builder, DocxExportReport.notes in backends).
• Claims checked at the call site: DocumentRenderingFacade.buildSemantic (bytes, then AtomicFileOutput.write); DocxSemanticBackend writing context.outputFile() with Files.write; DocumentSession.export throws Exception against DocumentRenderingException on the three convenience methods; DocxBackendProvider building new DocxSemanticBackend(), so the convenience methods keep live dates.
• Sabotage of the new route, file restored byte-identical after: a renamed docs: anchor, a broken prose anchor, a mis-cased page and an invented symbol — check-routes exits 1 naming export.docx for each of the 4.
• gate.sh (reactor clean verify as CI runs it, the four JDK 17 knowledge checks, core javadoc, install and the examples tests) — GATE PASS on fad7dc370; the follow-up commit changes two sentences of route prose, re-checked with check-routes, the sabotage and check-claims.
• check-claims --check, check-stability-doc, and the routing and claims fixture suites pass; ./mvnw test -pl :graph-compose-core -Dtest='com.demcha.documentation.*Test' — 173 tests, 0 failures.