Holon

Agents that act and follow through. Run Holon on your computer or a team server. Connect events and schedules so agents can act, save progress, and ask for your input when needed.

Documentation workflow

The Holon website is a mdorigin content root under docs/website/. Source pages are Markdown files that can render as HTML or be fetched as Markdown.

Edit content

Add or update Markdown files in docs/website/. Use directory README.md files for section landing pages:

docs/website/
  README.md
  concepts/
    README.md
    runtime-model.md
  guides/
    README.md

Keep public-facing website copy concise. Detailed runtime contracts and design records still belong under the repository docs/ tree.

Check contract references

The docs CI checks repository-local Markdown links and heading anchors in:

Focused specs may also declare implementation paths in their Last verified quote or an Implementation references section. Write repository paths there as code spans, for example:

> **Last verified:** against `src/runtime/scheduler.rs` and
> `src/runtime/waiting.rs`.

Elsewhere, use a real Markdown link when a source path should be enforced:

[`src/http/mod.rs`](../../../src/http/mod.rs)

Fenced examples, placeholders, and ordinary code spans are not interpreted as current implementation contracts. A historical or proposed reference on an otherwise checked line can be excluded only by placing a non-empty reason immediately after that specific reference:

`src/runtime/proposed.rs` <!-- contract-ref-ignore: proposed file from accepted RFC -->

Run the checks from the repository root:

python3 docs/website/.tools/check-links.py
python3 docs/website/.tools/test-check-contract-refs.py
python3 docs/website/.tools/check-contract-refs.py

Failures use file:line:target diagnostics so editors and CI logs can locate the declaration directly.

Preview locally

cd docs/website
mdorigin dev --root .

Refresh indexes

Documentation landing pages use one managed catalog as the source of article links. Keep introductory prose and cross-section links outside it, but do not copy the catalog into the body or translate it as a second list. Translate each article's title and summary, then regenerate the index. Run npm --prefix .tools run check:directories from docs/website to check for duplicates.

Directory pages may contain managed index blocks:

<!-- INDEX:START -->
<!-- INDEX:END -->

Regenerate them with:

mdorigin build index --root .

Build deployable assets

mdorigin build search --root . --out dist/search
mdorigin build cloudflare --root . --search dist/search

The generated dist/ directory is ignored and should not be committed.

Generated pages and locales

Some pages are produced by a generator rather than written by hand. Today that is reference/models.md, generated with:

cargo run --bin holon-docgen -- models > docs/website/reference/models.md

Do not hand-translate a generated page: the next regeneration would discard the translation. Register the page in .tools/generated-pages.json instead, then sync its localized copies:

npm --prefix .tools run sync:generated

The script copies the generated English page to each configured locale path, replaces the listed front matter fields with localized values, and adds a notice that the page body is generated. Commit the copy together with the regenerated source page. Docs CI runs the same script with --check and fails when a generated page and its copies disagree, so a regeneration needs one extra command — never a new translation.

Language detection

The site ships two locales: en (default) and zh-CN. mdorigin.config.json enables localeDetection, so a request to / redirects once to the visitor's preferred locale root. Deep links are never redirected, an explicit choice made with the header language switcher wins, and crawler traffic stays on the default root.

Refresh generated contract snapshots

OpenAPI, HTTP route, CLI, runtime status enum, and model tool schema snapshots are checked separately by the main CI. Run make snapshots-check before publishing a contract change. When a change is intentional, run make snapshots-refresh, review the generated diff, and then rerun make snapshots-check.

Publishing note

siteUrl is configured as https://holon.run so publishing exposes canonical sitemap and feed URLs for the production domain.