Skip to main content

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.

Start with the documentation gap​

Use the seven-language coverage matrix to record reader tasks separately from runtime evidence. Reuse an existing qualified example and receipt when writing a tutorial, API explanation or recovery procedure. Only an unsupported or contradictory concrete behavior claim calls for a minimal reproduction. A missing explanation or navigation link does not require a new seven-runtime validation campaign. Preserve dated receipts and release markers; check edited prose, excerpts and navigation with the documentation gates.

Maintain natural-search entry points​

Give a reader task one primary explanation page, then link native walkthroughs from it. Keep existing article URLs when improving titles and summaries. Align visible headings, the opening answer and internal link labels with the page's actual subject; do not add unsupported capability or benchmark claims to target a query. See Google's guidance on descriptive titles, snippets and crawlable contextual links.

Search intent / target phrasePrimary explanationNative continuation
MyBatis alternative for JavaOrder-page comparisonJava Order read, query and isolation tutorials.
Rust ORM partial loading; SQL NULL vs NotLoadedPartial-entity loadingRust Order reads and preload troubleshooting.
Generated query APIs vs handwritten SQLQuery-authoring tradeoffsSeven-language Order API usage.
Keyset vs offset pagination; exact count and random accessPagination choicesSeven-language export and retained-ID recipes.
Vercel AI SDK database tools; typed tools without raw SQLAI SDK database-tool boundaryThe recorded TypeScript adapter and separately scoped isolation tutorials.

These are editorial targets, not measured Google positions or search-volume estimates. The 2026-10-28 review found public search visibility for several article-shaped long tails, but did not obtain a verifiable Google results page. After publication, use Search Console performance data: exclude TeaQL brand queries, keep country/device and comparison periods fixed, and compare query/page impressions, clicks, CTR and average position. Separate indexing of a new page from changes in an existing page's visibility. A local production build verifies rendered metadata and links; it does not establish that a page has been published, crawled or improved in ranking.

Inspect the exact canonical URL before diagnosing a missing search result. Record the stored index status, last crawl and Google-selected canonical separately from the live fetch, live canonical and sitemap membership. An old stored canonical can describe a pre-fix crawl; a successful live test establishes crawlability, not completed indexing. A site: query or absence from the first results page is not a substitute for URL Inspection. Google's recrawl guidance also notes that repeated requests do not make the same URL get crawled faster. Submit reviewed public changes once, keep the dated receipt and compare later observations without rewriting the baseline or claiming a ranking cause Google has not supplied.

Ownership Model​

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

AreaResponsible role
Concepts and modelingModel/generator maintainers.
Java stackJava runtime and integration maintainers.
Rust stackRust runtime and provider maintainers.
TypeScript, Python, Go, .NET, and SwiftRespective runtime, provider, and generated-workspace maintainers.
Agent workflowAgent Kit and generator-rule maintainers.
CookbookFeature owner for the demonstrated workflow.
ComplianceMechanism owner plus security/compliance reviewer.
ReferenceSource-code owner for the command, option, property, error, or compatibility row.
Upgrade and releaseRelease owner for every affected component.

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

Evidence Classes​

Use these terms consistently:

StatusRequired evidence
VerifiedNamed source/command and a repeatable check against a recorded version.
Version-sensitiveVerified only for the version stated on the page.
ProvisionalCurrent useful evidence, but not a complete or stable contract.
UnverifiedKnown 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 the official generator endpoint and package registries for all seven runtimes. It compares each runtime's generator-selected and independently published version in the corresponding Latest Versions table cells; another row containing the same version cannot satisfy that check. It also rejects stale Cargo/Maven client commands and fixed runtime dependency versions in maintained docs/ and src/ content: Maven/Cargo declarations, Go module references, npm commands and dependencies, Python requirements, NuGet commands and project references, and Swift package declarations. Operational runtime pins follow the generator selection. A newly generated workspace should keep its emitted dependency manifest; historical version narratives and blog posts are not instructions to upgrade or downgrade it.

Dated client, target, generated-workspace, build, runtime, and blocker results belong in dated evidence records such as the School run. The July Verification Evidence Archive remains historical. The documentation workflow retains its manifest, raw check/build logs and successful static build for 30 days. The Golden Path workflow now generates the same School model for all seven runtimes, compiles the application examples, checks real SQLite data and verifies restart readback. It runs when the fixture or runner changes and supports manual dispatch. Go currently selects the explicitly pinned workspace runtime and is labeled WORKSPACE PASS — RELEASE PENDING. The default runner still selects public dependencies; no automatic source fallback is allowed. Retain the public Go failure separately until a new release passes that default command. Workspace evidence includes commit, dirty state, source hash and native module resolution; source changes after compilation invalidate verification. Record a remote run identifier before claiming retained CI 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;
  • all seven School Golden Path results, including build blockers and unrun phases;
  • 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:conformance-snapshot
npm run check:latest-versions
npm run test:latest-versions
npm run test:doc-evidence
npm run build

The contract check scans Java, Rust, TypeScript/JavaScript, Python, Go, C#/.NET, and Swift code blocks, including common fence aliases. It handles camelCase, snake_case, PascalCase, asynchronous terminals, and Go line-break chaining. Each literal fluent query chain must include non-empty comment and purpose before execution, in either order. Each save/update chain must include a non-empty audit reason. A nested request, earlier statement, comment, or string cannot supply another operation's intent. Blank string literals and null-like metadata are rejected; dynamic values still require runtime validation.

This is a static documentation linter, not a compiler or runtime test. It does not resolve helper methods, infer intent through variables, or verify generated API names. Show intent on the executed chain in an ordinary example. A negative test or non-query tool terminal can use an immediately preceding <!-- doc-contract-ignore: concrete reason -->; that exception applies to one code block only. It must not be used to claim an untested example passes.

The same checks apply to homepage snippets, language-keyed Model Explorer data, and static CodeBlock templates under src/. The checker also requires seven language journeys including Debugging, sidebar reachability, useful page content, and evidence metadata for Cookbook, Reference, and Compliance pages. Language API examples remain illustrative unless separately compiled and run.

Maintained guidance additionally rejects known conflicting intent-order rules, descriptor-only schema guidance (including prose split over lines), generated API source-search instructions, and obsolete publication placeholders. Explicitly historical and negative explanations remain allowed. Existing checks also reject historical SQLx provider labels presented as current guidance, older universal MustComment<T> claims, non-mutating _dryrun promises, automatic schema changes, and operational shell examples using formatter-layer TEAQL_*_LOG names. Agent Rules must state that comment and purpose are both required and can appear in either order.

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, npm, PyPI, NuGet, and GitHub-tag metadata, accepted current pins, and stale Cargo/Maven client pins and all seven runtime dependency pins with source lines, plus separate generator-selection and registry-release table cells. 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 4 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.

The Golden Path matrix covers all seven School console applications. Both basic and advanced suites run in separate matrix jobs. The advanced TypeScript job explicitly selects the recorded workspace deletion fix; its basic job still uses the published package. The Go advanced job applies relation-isolation and ID-set observation patches. Rust, Python and .NET advanced jobs apply the pinned pagination patches. The expanded advanced receipt is 238/238 with two published runtimes and five explicitly selected workspace runtimes awaiting release. Preserve the earlier 210/210 pagination receipt, 161/161 consistency receipt, 77/77 workspace receipt and the 76/77 failure receipt until a corrected TypeScript release passes without the workspace option.

npm run check:school-docs verifies that the fourteen scenario/advanced pages match the executable source excerpts and that the dated receipt matches current source and oracle hashes. The advanced acceptance tests reject wrong filtered totals, global child limits, missing zero-count buckets, wrong aggregates, stale overwrites, duplicate reports and partial results. They also reject wrong empty-page totals, duplicate page boundaries, missing parents after child filtering, incorrect negative relation predicates, accepted blank intent, and tombstone leakage into aggregates, Facets or child lists. The scenario catalog must match the oracle exactly; the receipt total is derived from that catalog.

npm run check:order-contract checks the new Order model/Assist fingerprints, fixture arithmetic, distinct value/null/empty/unselected expectations, all seven runtime tracks and generated documentation tables. npm run test:order-contract exercises rejection of stale evidence, missing runtimes and unsupported PASS claims. This phase is a model and acceptance specification, not a native Order verification suite. Keep the School receipts and pending-release markers intact; Order needs its own published/workspace execution evidence before promotion.

npm run test:school-evidence checks that missing restart data, duplicate roots, seed-version changes and read-time writes cannot receive a passing receipt. It also rejects a workspace runtime masquerading as a published package, an unexpected module checkout, missing source identity, and source drift between build and verification. TypeScript's workspace mode also checks the actual Node package resolution, the packed archive and installed executable bytes; its source hash excludes tracked dist/ build products, which have a separate artifact fingerprint. The CI job checks out the recorded base and applies the maintained source/test patch. Do not replace its qualification with a published-runtime claim merely because the workspace package still declares version 0.3.1. The documentation contract checker also requires all fourteen basic/advanced application files and checks their query intent and mutation audit chains.

Where practical, future CI should also:

  • extend executable coverage beyond the shared School model;
  • 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 checked against scoped Assist or qualified application excerpts rather than guessed.
  • Links and navigation are updated.
  • Relevant compatibility/migration/reference pages are updated.
  • npm run build passes.
  • Review ownership is clear.