Documentation Contract
Hexis documentation must make the difference between reality and intent impossible to miss. Every page carries structured status, freshness, AI-context, and executability metadata. The site banner, validation, and generated AI artifacts all read that same source.
Status vocabulary
| Status | Meaning |
|---|---|
| Documentation policy | Rules for maintaining or interpreting the docs |
| Current-source evidence | Verified observation of the named current checkout, with explicit evidence limits |
| Target contract | Normative behavior Hexis intends to implement; syntax may not ship yet |
| Future direction | Product research useful for planning but not binding |
| Implemented | Verified against a named implementation and every required acceptance lane |
| Legacy v3 reference | Historical API material retained during replacement and excluded from normal AI context |
An example on a planned page is a proposed acceptance example, not evidence that the call works today.
What is normative
The target architecture is normative about:
- ownership between Lua, Java/native code, and server packs;
- action lifecycle, cancellation, cleanup, and error semantics;
- capability permissions and the
hexis.rawboundary; - server-agnostic core behavior;
- the validation gates required before an API is marked implemented.
Cross-cutting lifecycle and result rules are normative. Navigation syntax is the first frozen vertical-slice target. Other domain operation names and request tables remain candidate vocabulary until their representative tasks establish the correct semantic center.
Source-of-truth order
When sources disagree, use this order:
- current runtime behavior and focused tests;
- the current
hexis-modsource; - an implemented contract page tied to a build;
- target architecture pages;
- legacy API pages and historical discussions.
No documentation claim can promote itself to Implemented merely because it was written first.
Change protocol
Every new capability should land vertically:
- choose a representative user task;
- stabilize one Java/native mechanism;
- define its typed contract and permissions;
- expose one Lua binding;
- use it in a realistic script;
- test cancellation, failure, cleanup, and world changes;
- evaluate AI generation and repair;
- revise the contract, then mark that slice implemented.
Documentation and contract tests should be reviewed in the same change as the
binding. A page becomes Implemented only when it sets executable: true and
points implementation_ref at versioned source and tests. The documentation
check rejects invalid promotions.
The documentation pipeline generates the AI discovery index, implementation bundle, runnable API bundle, clean per-page Markdown, and machine-readable manifest from authored metadata. The runnable bundle intentionally remains empty until a capability passes its acceptance matrix.
Legacy pages
Legacy v3 pages stay reachable through the legacy archive because they contain useful implementation history. They are unlisted, excluded from normal search and generated AI context, and are not the foundation of the redesign. Verify any legacy call against the current mod before using it in a production script.