Optima documentation

This repository publishes the engineering documentation for Optima: a chain-independent inference engine and the proposal, referee, attribution, and reward system used to improve it.

The code repository remains authoritative for executable contracts. This site turns those contracts into task-oriented guides, architecture explanations, and reference material. In particular, it keeps four states separate:

1. a submitted proposal;
2. a reproducibly measured crown;
3. a reviewed integrated contribution; and
4. a signed Optima Engine release.

No state implies the next. The validator loop may settle a causally ready, two-pass proposal into a crown automatically, but integration and release remain separate reviewed authorities.

Build locally

Python 3.10 or newer is sufficient for the documentation toolchain.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

python scripts/check_docs.py
mkdocs build --strict

Preview separately because the server is intentionally blocking:

mkdocs serve

The local preview is served at http://127.0.0.1:8000/. The documentation checker and successful strict build are the publication gates.

Repository map

Path	Purpose
docs/get-started/	Product orientation and a CPU-only local loop
docs/architecture/	Product model, stack identities, pipeline, and release boundary
docs/miner-guide/	Building and submitting a bounded contribution
docs/validator-guide/	Deploying the intake, referee, settlement, and weight control planes
docs/engine/	Integrating reviewed source and producing signed Engine releases
docs/security/	Threat model, execution isolation, and evidence authority
docs/reference/	CLI, catalogs, schemas, arena types, and terminology
docs/dev/	Maintainer environment and SGLang compatibility process

Navigation and site configuration live in mkdocs.yml. Styling is deliberately small and local under docs/assets/; content remains ordinary Markdown.

Documentation rules

• Prefer source-backed contracts over implementation folklore. Link to stable files in the Optima repository rather than to local checkout paths or line numbers.
• Label production operations, developer diagnostics, historical evidence, and remaining proof separately.
• Never imply that one qualification pass is a crown, a crown is integrated source, or integrated source is a release.
• Keep credentials, infrastructure addresses, prices, private worklogs, and transient operator details out of public documentation.
• Put time-sensitive measurements in the state-of-record page. Keep task guides timeless unless a version is itself part of the contract.
• Run python scripts/check_docs.py and mkdocs build --strict before submitting a change.