Skip to content

Source code

Agon Ātrium documentation site

Read the repository’s AGENTS.md, the matching agent guidance, and the site build and hosting guide. Resolve repository paths relative to this skill’s directory, two levels up. Use development setup for the pinned runtime and workspace commands.

Choose the maintained source

  • Edit canonical prose in docs/ or its existing root or package document. docs/publication/registry.json classifies Markdown as published or excluded and defines stable routes and navigation order. The references list supplies local reading pages for linked agent guidance, skills, and verification records, outside main navigation and search. Explicit references override broad exclusions. Unreferenced ledgers and audits remain excluded.
  • Edit the private Astro/Starlight renderer in src/documentation/ for the documentation shell, styles, and controls. Collection, link rewriting, search, legal notices, and build qualification belong in src/scripts/documentation/. The renderer and its dependencies must stay outside the four distributable packages.
  • Keep the home-page and sidebar Live demo links on /go/demo/. Deployed NGINX reads ATRIUM_DEMO_URL at startup, with production as the default. Follow environment link configuration, preserve the static preview fallback, and verify overrides without JavaScript. Never rewrite verified site bytes at container startup.
  • Preserve the source fingerprints and stable heading IDs in docs/publication/metadata.json. Follow the guide’s authoring procedure after reviewing source changes. Run yarn docs:refresh, review its diff, then run yarn docs:build. With optional pre-commit hooks installed, documentation-metadata refreshes automatically as the final hook, after the header-date updater and every other hook that can modify Markdown. Keep it last when adding hooks, and review and stage source and metadata edits together before retrying the commit. Package SemVer changes use yarn version:bump and also require this review/refresh cycle. Preserve established routes and heading IDs when inbound links must survive a rename.

Keep README badges out of collected content. Keep every repository reference local. Use sourceFiles for highlighted source viewers, sourceDirectories for bundled folder indexes and media, and references for supplemental Markdown pages. Never restore a GitLab fallback. Register missing destinations and retain the build checks that reject unresolved references and repository-host links. Preserve local media and fully local Pagefind search. Do not bypass collection checks for missing references, unsafe HTML, symlinks, or remote resources. English is the maintained published locale. Add reviewed translations before enabling others, and follow the documented rendering requirements before introducing Mermaid.

Verify the affected site

Use yarn lint:prose and formatting checks for changed Markdown. yarn docs:build validates collection, rendered links and anchors, legal evidence, and artifact budgets before promoting .build/documentation/release/. Edit maintained inputs instead of generated candidate or release files. Use yarn docs:verify after renderer, collector, search, or artifact changes to check independent-build determinism. After an authorized documentation dependency change, refresh and review notices with yarn docs:legal before verification.

For visual changes, preview with yarn docs:preview and follow the guide’s build and preview procedure. Run the affected site browser checks in src/tests/sites/ for layout, navigation, search, accessibility, and no-JavaScript reading. Use yarn sites:prepare, yarn sites:images, and yarn sites:test when checking the actual NGINX images. The static fixture alternative does not verify NGINX HTTP behavior. Stop owned previews and temporary services as documented.

For hosting or delivery changes, read CI guidance and the site’s CI artifact chain. Keep infrastructure in resources/infrastructure/.docker/ and resources/infrastructure/.deploy/. Local checks build and qualify artifacts. External publication and deployment require the user’s authorization, and hosted delivery jobs must never run locally. Preserve immutable image references and stable-release eligibility for production.

Author

Laurent Declercq l.declercq@agon-innovation.ch

Version

Version: 20260923