Skip to content

Docs text pass: every user-facing page to the writing.md standard#1113

Merged
JeroenDeDauw merged 16 commits into
masterfrom
docs/text-pass-fleet
Jul 21, 2026
Merged

Docs text pass: every user-facing page to the writing.md standard#1113
JeroenDeDauw merged 16 commits into
masterfrom
docs/text-pass-fleet

Conversation

@JeroenDeDauw

Copy link
Copy Markdown
Member

Follows-up to #1106 and applies docs/writing.md across every user-facing docs page: 15 files, 590 insertions, 1112 deletions, one commit per file so any single page can be reverted alone.

Each page went through a three-stage pipeline: a rewrite agent bound to the page's genre row and required to verify every behavioral claim against source before keeping or tightening it; a fresh-context judge seeing only the artifact and the standard; and a conservative apply step that re-verified the judge's factual findings before touching the file. A review pass followed and restored three over-cuts: the $wgNamespaceProtection caveat and the OpenAPI spec-registration snippet in rest-api.md, and the parameter-injection note in query-api.md.

The pass removed false claims, not just noise. Notable corrections:

  • schema-format.md listed date/dateTime as reserved/not implemented; both are registered, working types. Their fields are now documented, as are text's previously undocumented minLength/maxLength.
  • person-to-edm.md's Person Schema snippet lacked the required propertyDefinitions wrapper, so it could not be pasted as-is.
  • installation.md's "share the demo" docker compose command was not runnable as written.
  • parser-functions.md counted "three parser functions" while documenting four, and misdescribed {{#view}}'s behavior for a nonexistent Subject ID.
  • qualifiers-and-references.md described relation-carried qualifiers as Schema-typed and validated; relation properties are free-form.
  • rest-api.md named a nonexistent "Mapping" read endpoint in the permissions list; GET /subject-labels is now documented as the exception that does not enforce per-page read, and expand=relations as also dropping targets on unreadable pages.
  • rdf-export.md claimed the projection is "lossless and self-sufficient" (it drops unrepresentable values and Subjects with unavailable Schemas) and listed a neo-graph: prefix that is deliberately not emitted; the value-type list said date-time where the type name is dateTime.
  • graph-model.md said each Statement becomes a node property (relation Statements become relationships) and stated the uniqueness constraints unconditionally (a never-rebuilt graph lacks them). The PropertyType-to-Neo4j type mapping, the backtick-escaping rule for property keys, fixed-property collision behavior, and how to recognize a deleted-but-retained Subject node are now documented.
  • lua-api.md's return and getSchema tables were missing their date/dateTime/boolean rows; glossary.md called url a Value Type (it is a Property Type storing a StringValue) and carried a published TODO.
Per-file ledger: considered-omitted cuts, skipped judge findings, unverified claims

glossary.md (151→135) — omitted: dedicated Validation entry (validation-codes.md is the home); "no stored Default Layout entity" clarification; inline Cypher example. Unverified: none.

api/graph-model.md (128→119) — omitted: overview restating the diagram; ISO-conversion note; constraint-idempotency mechanism; duplicate namespace examples. Skipped: exact stored date serialization (below wire register). Unverified: "Founded at: 2019" rendering (code-consistent, not run live).

api/query-api.md (375→267) — omitted: the ~80-line curl walkthrough (restated the contracts); temporal-rendering paragraph (folded into the table); apihighlimits rationale; $wgNeoWikiQueryLimits override PHP example (key remains documented); SPARQL "differences from Cypher" bullets. Unverified: duration/point JSON shapes fall through to the Laudis driver.

api/rest-api.md (177→~173) — omitted: DOC-INTENT editorial comment (superseded by writing.md); "render without follow-up" narration. Skipped: write auth/CSRF mechanics (standard MediaWiki); pagination signaling (deferred to OpenAPI). Unverified: demo-wiki spec URL liveness.

api/schema-format.md (316→234) — omitted: reserved-types roadmap list (email/phone/…: absent from code, no wire contract); boolean frontend-display note; endpoint re-listing (rest-api.md owns it); trivial one-line examples. Unverified: precision is display-only (not enforced in PHP); select id→label display resolution not inspected.

api/subject-format.md (297→215) — omitted: Overview section (folded); per-type value examples the new shape table covers; facts homed in validation-codes/graph-model/rest-api. Unverified: none.

authoring/lua-api.md (409→405) — omitted: "use this when" preambles; conversion-table restatement. Skipped: exact accepted Lua parameter types for nw.query (could not cheaply verify; no unverified contract asserted). Unverified: integer-comparison toInteger advice kept as defensive guidance.

authoring/parser-functions.md (205→194) — omitted: Related-Documentation footer; header-restating notes; unregistered-type edge case. Skipped: propertyName case-sensitivity (unverified match semantics); relation "label" definition (glossary's job). Unverified: client-side rendering behaviors (frontend half inferred).

examples/person-to-edm.md (250→215) — omitted: origin/meta framing of the toy model; standalone "findings" section (each folded into its home section); forward-looking seam notes. Unverified: instance-specific literals (page ids, timestamps — flagged in-doc); external CIDOC-CRM path is illustrative.

extending/extending.md (472→451) — omitted: 21-line RDF value-mapper listing identical to the linked RedHerbHooks.php (contract kept in prose). Skipped: one judge finding whose premise was false in code (the adjacent real inaccuracy was fixed instead). Unverified: four pre-existing behavioral claims not traced (SVG icon type, rebuild delete loop, failure paths, no-mapper omission).

operations/installation.md (274→267) — omitted: heading-restating intro; reassurance sentences; SPARQL "no validator needed" mechanism. Skipped: third-party Neo4j provisioning steps (explicitly delegated). Unverified: "Neo4j 5.x" minimum is pinned nowhere in-repo (left as stated).

operations/maintenance.md (70→63) — omitted: stale intro enumeration; outage/rebuild duplication; "lives only in Neo4j, so" mechanism. Skipped: a wipe-the-data-volume command (deployment-specific); naming a changelog source (none verified to exist).

qualifiers-and-references.md (143→100) — omitted: "The short version" duplicate walkthrough; "Why this approach" advocacy section (two content-bearing points moved to the intro); dev-state issue links; RDF reification mechanism (round-trip contract kept). Skipped: a novalue/somevalue modeling recipe (would be speculative). Unverified: RDF round-trip losslessness for the qualified-value pattern.

rdf/ontology-mapping.md (171→137) — omitted: projection-selection curl/DumpRdf duplication (rdf-export.md owns it); rationale clauses; raw issue link. Skipped: two judge findings whose premises were wrong (named graphs share a store); reserved-prefix trap (could not prove, would risk asserting falsehood).

rdf/rdf-export.md (160→149) — omitted: IRI-encoding security justification; autodiscovery rationale; "later concerns" intro. Skipped: authentication (MediaWiki-level, not this page's home); full emitted-predicate enumeration (NativeRdfProjection.md's home). Unverified: illustrative example IRIs.

AI-authored — Claude Code; rewrite/judge/apply fleet of 42 Opus 4.8 (max) agents over a deterministic Workflow pipeline, spec, review pass, restorations and glossary by Fable 5 (max), directed by @JeroenDeDauw; not yet human-reviewed; every behavioral claim source-verified by the rewriters, judge findings re-verified before application, spot re-verification in review (three restorations), CI pending at submission.

JeroenDeDauw and others added 15 commits July 21, 2026 00:08
Per docs/writing.md: cut the two formerly-called parentheticals and a TODO
(production history), fix the Value Type example (url is a Property Type; the
Value Type is string), state which Value Types are multi-part (String, Relation)
and which are single (Number, Boolean), add the missing Property Type entry and
its link to Value Types, tie Statement propertyName to the Subject's Schema,
deduplicate the View Type example triplet and the Display Rule prose/bullets,
unify examples on infobox/card/table, remove the no-Layout fallback restated
from the View section, and reduce Page Property lifecycle mechanism to the
Extending pointer.

A fresh-context blind judge reviewed the intermediate state; its surviving
findings (multi-part ambiguity, Property Type entry, Schema linkage) are
applied here.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…etion contracts

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…-safety notes

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…nclusive

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…tement and unregistered-type facts

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@JeroenDeDauw
JeroenDeDauw marked this pull request as ready for review July 20, 2026 23:12
@JeroenDeDauw

Copy link
Copy Markdown
Member Author

Did a cursory review and did not spot issues

Resolve the graph-model.md conflict from #1080 (stub Subject nodes).
The branch's rewrite claimed a removed-but-referenced node "keeps its
Schema labels and dynamic properties"; #1080 changed the code to strip
such nodes to id + wiki_id + Subject-label stubs, making that claim
false. Take master's Stub-Subject-nodes section and its corrected
one-line deletion paragraph; the rest of the branch's rewrite stands.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@JeroenDeDauw
JeroenDeDauw merged commit dcf94bf into master Jul 21, 2026
6 checks passed
@JeroenDeDauw
JeroenDeDauw deleted the docs/text-pass-fleet branch July 21, 2026 14:45
alistair3149 pushed a commit that referenced this pull request Jul 21, 2026
The docs-fleet rewrite agent's closing tool-call tags (</content>, </invoke>)
ended up as the file's last two lines in #1113. VitePress runs markdown through
the Vue template compiler, which rejects the stray end tags, so every website
build syncing master docs fails. Two-line deletion; the fleet's other 14 files
audited clean for the same token class.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant