Documentation Maintenance

TeaQL documentation is a product surface. Commands, generated method shapes, defaults, compatibility, and security behavior must be maintained with the same care as runtime APIs.

Ownership Model

Until named maintainers are published, use responsibility-based ownership:

Area	Responsible role
Concepts and modeling	Model/generator maintainers.
Java stack	Java runtime and integration maintainers.
Rust stack	Rust runtime and provider maintainers.
Agent workflow	Agent Kit and generator-rule maintainers.
Cookbook	Feature owner for the demonstrated workflow.
Compliance	Mechanism owner plus security/compliance reviewer.
Reference	Source-code owner for the command, option, property, error, or compatibility row.
Upgrade and release	Release owner for every affected component.

Every substantial documentation change should have one accountable reviewer from the responsible role.

Evidence Classes

Use these terms consistently:

Status	Required evidence
Verified	Named source/command and a repeatable check against a recorded version.
Version-sensitive	Verified only for the version stated on the page.
Provisional	Current useful evidence, but not a complete or stable contract.
Unverified	Known gap; must not be presented as an exact default or support promise.

Do not use complete, comprehensive, always, or guaranteed unless the source and supported scope justify the claim.

Version-Sensitive Page Metadata

Reference, upgrade, provider, and runnable example pages should include or display the following information:

Status:
Authority:
Scope:
Verified version:
Verification command or test:
Update trigger:
Owner:

Not yet recorded is acceptable during migration. An invented version or default is not.

Every non-index Reference page, every Compliance page, and every Cookbook recipe also carries machine-readable front matter:

verification_status: provisional
verified_version: not-recorded
authority: source-or-command-identifier
owner: responsible-maintainer-role
update_trigger: behavior-that-requires-review

CI validates the five fields and accepted verification status for every non-index Reference and Compliance page. Every non-index Cookbook page must carry the same five machine-readable fields and show a reader-facing Evidence status near its introduction. A recipe may remain unverified, but it may not hide that state.

The latest-version check reads https://api.teaql.io/latest/version/ and fails when the documented Generator Server, teaql-java, or teaql-rs baseline is stale. It also reads the crates.io index and TeaQL Maven metadata, then rejects stale cargo-teaql installation commands, fully qualified Maven plugin commands, TeaQL Java dependency blocks, and direct TeaQL Rust dependency pins under maintained docs/ and src/ content. Historical blog posts are intentionally outside this operational snippet check.

Dated client, target, generated-workspace, build, runtime, and blocker results belong in the Verification Evidence ledger. The documentation workflow retains its manifest, raw check/build logs, and successful static build as a 30-day CI artifact. Java/Rust Golden Path jobs use the same manifest-and-log pattern in the manually dispatched Golden Path workflow. Record its run identifier in the evidence ledger after execution.

The Examples and Evidence Index classifies committed fixtures, locally executed paths, retained CI artifacts, contract-checked illustrations, and historical evaluations. An example may move to a stronger class only when the required model, commands, versions, expected result, and durable evidence are present.

Required Review by Change Type

Model or Generator Change

Review:

• KSML vocabulary and validation errors;
• generated directory layout;
• exact entity/request method names;
• Java/Rust regeneration instructions;
• agent rules and generated-file boundaries;
• golden-path examples.

Runtime or Provider Change

Review:

• configuration and environment reference;
• compatibility matrix;
• transactions and schema behavior;
• logging, audit, masking, tenancy, and authorization claims;
• provider-switch and troubleshooting recipes.

CLI or Maven Plugin Change

Review:

• command help and flags;
• generation/evaluation examples;
• Markdown report behavior;
• CI commands;
• output paths and generated dependency sets.

Release

Review:

• release notes;
• version and compatibility policy;
• migration and rollback guidance;
• Java/Rust golden-path evidence;
• changed defaults, errors, and configuration;
• known limitations.

Page Quality Gates

Guides

• State the reader outcome.
• Use commands and APIs verified for a named scope.
• Show expected evidence.
• Link to exact reference entries.

Cookbook

• Start from a concrete task.
• Explain applicability and non-applicability.
• Use the smallest viable implementation shape.
• Include verification and failure modes.
• Avoid duplicating option tables.

Troubleshooting

• Begin with a searchable symptom or exact message.
• Put the most likely cause first.
• Preserve Markdown reports and first errors.
• Prefer model/configuration/handwritten-source fixes over generated patches.
• End with a verification step and escalation evidence.

Reference

• Identify authority and verified version.
• List accepted values and defaults only when evidenced.
• Distinguish documented, tested, and supported compatibility.
• State precedence, reload behavior, and deprecation when applicable.

Automated Checks

Pull requests should run:

npm ci
npm run check:docs-contracts
npm run test:docs-contracts
npm run check:latest-versions
npm run test:latest-versions
npm run test:doc-evidence
npm run build

The contract check scans executable Java and Rust code blocks. It rejects query examples unless every execution chain ends with comment → purpose → execute, executeForXxx, or execute_for_xxx, entity save/update calls without auditAs/audit_as, and historical Rust provider crate names in executable examples. The execution matcher intentionally covers new executeForXxx and execute_for_xxx variants instead of maintaining a small terminal-method allowlist. Non-query terminals named execute, such as an external tool with a separate purpose/audit contract, require a nearby reasoned doc-contract-ignore. It also rejects documentation pages that are not reachable from the main sidebar. Cookbook pages additionally fail when evidence status, verified version, authority, owner, update trigger, or the visible evidence statement is missing. The same query and mutation checks apply to code snippets stored in the homepage data module, every Java/Rust scenario in the public Model Explorer data, and static Java/Rust CodeBlock templates anywhere under src/. It also rejects empty/thin pages and a focused set of absolute accuracy, authorization, audit, security, and infrastructure claims. Current-state prose is additionally checked for SQLx-labeled Rust providers, older universal MustComment<T> claims, non-mutating _dryrun/automatic schema self-healing promises, and operational Shell examples that use formatter-layer TEAQL_*_LOG names as generated-workspace settings. Historical, migration, and explicitly negative explanations remain allowed. The maintained Agent Rules page must state comment → purpose → execution and that purpose is immediately before the execution terminal. Intentionally invalid teaching examples may use a nearby doc-contract-ignore comment with a concrete reason.

The checker has Node built-in regression tests in scripts/check-doc-contracts.test.mjs. The suite creates temporary miniature documentation sites and proves both allowed and rejected behavior without modifying maintained pages. Every new contract rule should add at least one passing context and one failing context where ambiguity is possible.

The live version check delegates parsing and source scanning to scripts/latest-versions-lib.mjs. Its offline test suite covers the official Markdown table shape, crates.io yanked-release handling, Maven release metadata, accepted current pins, and stale Cargo/Maven/Java/Rust pins with source lines. The offline tests do not prove that the network sources are reachable or still use the expected shape; retain the live check as a separate gate.

scripts/write-doc-evidence.test.mjs verifies documentation evidence manifest schema version 3 and its Markdown summary for complete CI outcomes and an environment with no CI metadata. Adding or renaming an outcome requires an explicit schema-version change and a matching regression-test update.

The Docusaurus build fails on broken site links and broken Markdown links.

Where practical, future CI should also:

• execute Java and Rust golden paths;
• compile maintained examples;
• compare CLI help with command reference;
• extract configuration/default catalogs from source;
• detect stale compatibility rows;
• preserve Markdown reports as artifacts when validation fails.

Stale-Page Policy

A version-sensitive page is stale when:

• its verified version is outside the maintained release line;
• an update trigger occurred without review;
• commands or examples no longer compile;
• source and documented defaults differ;
• provider or framework names were removed;
• a release changes generated API shape without corresponding migration notes.

Mark stale material as historical or provisional immediately. Do not leave it presented as current while waiting for a full rewrite.

Rename and Removal Policy

Before moving or deleting a public page:

1. Search internal and external inbound links where possible.
2. Move the useful content or explain its replacement.
3. Preserve a redirect for established routes.
4. Update sidebar, homepage, footer, FAQ, and release links.
5. Run the production build.

Definition of Done for a Documentation Change

• The reader outcome is satisfied.
• Claims are scoped and evidence-backed.
• Generated method names were inspected rather than guessed.
• Links and navigation are updated.
• Relevant compatibility/migration/reference pages are updated.
• npm run build passes.
• Review ownership is clear.