Contract version and corpus revision are different
The public read contract is v1. JSON schemaVersion is the string "1", not a number. The capability and OpenAPI contract version is 1.0.0. The current corpus revision for this guide is 22ce5d34dbcb5a78, a 16-character lowercase hexadecimal value. A content correction or other corpus update can change revision without introducing a new API contract.
Document IDs are stable retrieval identities, not titles or summaries. Copy an exact ID from the current index; never create one by slugifying a title. A stable ID does not freeze the article's text, category, headings, source links, or availability forever. Always inspect the current record. If an ID is absent, handle NOT_FOUND and re-list rather than silently choosing a similar title.
Reject stale combinations
- Discover capabilities and retain the observed revision.
- Compare that value with the index and any search index, document, or export you fetch. The complete export's outer revision applies to its nested documents.
- For a document, also compare the returned id with the requested exact ID. For raw Markdown, check its frontmatter id and revision; the full Markdown export has a corpus revision.
- On mismatch, stop using the mixed results. Rediscover and reselect before continuing. Do not overwrite the expected revision merely to make a stale check pass.
CLI --revision rejects mismatches with STALE_REVISION. Browser query, reset, and copy accept expectedRevision and reject stale page state; the browser also compares downloaded resources with its page revision. Reload and rediscover if the page is stale. These checks do not make a series of independent HTTP requests atomic.
Preserve raw=1 and v on advertised Markdown URLs. raw=1 preserves raw file delivery through the hosting layer; v is a revision hint, not an archive or rollback service. Requesting an old v does not retrieve old content. At the published canonical origin https://robust-reef-dmr6.here.now, the gateway's X-Corpus-Revision identifies its configured snapshot and Cache-Control: no-store avoids caching at that delivery layer, but clients must still compare actual bodies. Cached local files must be keyed by revision and representation, not only by document ID. Canonical pages vary by Accept and Accept-Encoding; HTML and Markdown are not interchangeable cache entries. Local static previews do not provide these HTTP delivery guarantees.
Compatible and breaking changes
Clients should accept additive JSON fields and newly listed documents or categories, while validating the fields they depend on and the supported schemaVersion. Do not hard-code the current document count, titles, category set, or revision. Treat sources and headings as current metadata, not immutable IDs for server operations.
A breaking read-contract change requires a new version path, such as /api/v2/. A new version must not silently replace v1 responses under /api/v1/ or reinterpret v1 fields. Its supported schemas, discovery links, and migration guidance must be explicit. Unversioned discovery and export resources must advertise their supported schemaVersion; incompatible payloads must not masquerade as schemaVersion "1". Content revisions alone do not authorize incompatible schema changes.
Deprecation and sunset policy
No deprecation or retirement is currently scheduled for the public read contract. There is no promised release calendar, support deadline, archival retention period, or availability SLA. Any future retirement must be announced explicitly with the affected paths and migration guidance, not inferred from a corpus revision or a changed article title. Breaking changes still require the new version path and explicit schemas described above; a retirement announcement does not permit silently changing v1 responses.
For exact resource schemas, HTTP error codes, CLI bounds, and browser clipboard permissions, use the Agent Fieldnotes API documentation and OpenAPI description. The about guide explains source provenance and public access; the contact guide explains how to report a compatibility problem without sharing private information.