Skip to content

Documentation workflow

Documentation is a release artifact of the same commit as the behavior it describes.

One change, one pull request

Any change to a tool, required field, authorization scope, error, migration, deployment behavior, or continuity rule must update its documentation in the same pull request.

The pull request checklist is:

  • source code and tests updated;
  • human guide updated if the user workflow changed;
  • agent contract and tool reference updated if the schema changed;
  • ADR added or updated for an accepted architectural decision;
  • synthetic examples still pass validation;
  • python scripts/export_mcp_contract.py --check passes;
  • python scripts/check_docs_contract.py passes, including the OpenAPI route and MCP manifest checks;
  • mkdocs build --strict passes;
  • no secrets, credentials, memory bodies, or private infrastructure details were added.

Publication

The documentation site is built from main and published to https://docs.heyaira.eu. Pull requests produce a preview; only main updates the production domain. The deployment records the source commit so a site can be traced back to Git.

The Git-connected Cloudflare Pages project uses the following production build settings:

Build command: pip install -r docs-requirements.txt && python scripts/export_mcp_contract.py --check && python scripts/check_docs_contract.py && mkdocs build --strict
Output directory: site
Production branch: main

The repository push is the update trigger. Cloudflare Pages checks out the connected main branch, runs the contract checks, builds, and publishes the site. The GitHub Actions workflow performs the same checks on pull requests and as a post-push validation; it does not publish a second deployment. A source change that alters a tool without updating the generated contract fails before publication.

Versioning policy

Documentation follows the HeyAira product contract, not every internal commit. Use a version when a public contract is released, for example v0.1. Keep the current development docs in the repository and publish a stable version only when its examples and tool schemas have passed acceptance.

Human and agent review

Every documentation change is reviewed twice:

  1. a human checks clarity, safety, and whether the instructions are usable;
  2. an agent checks that the startup sequence, required fields, error behavior, and examples match the current MCP schema.

This makes the human-facing and agent-facing layers consistent without forcing either audience to read the other audience’s material.