Atlas: Contributing

Atlas documents itself here rather than in a separate wiki — if this page gets out of date, that’s a bug in Atlas.

Adding a page

1. Pick the audience: does this belong in content/docs/public/** or content/docs/internal/**? If you’re unsure, it’s internal — public is the opt-in direction, not the default.
2. Create the .mdx file under the right section directory.
3. Fill in required frontmatter: title, description, visibility, type. See src/content.config.ts for the full schema and enums.
4. Run npm run dev:public or npm run dev:internal to preview.
5. Run npm run docs:validate before opening a PR.

Frontmatter

Field	Required	Notes
title	yes
description	yes	One sentence, shows in search + /llms.txt
visibility	yes	Must match the directory (public/internal)
type	yes	guide, concept, tutorial, reference, system, service, adr, rfc, runbook, specification, incident, postmortem, experiment
status	no (default active)	draft, active, deprecated, proposed, accepted, superseded, archived
owner	recommended	See config/owners.yml
lastReviewed / reviewInterval	recommended for anything operational	Powers npm run docs:freshness
verified	no (default true)	Set false and use <MurmurCallout kind="unverified"> for anything not confirmed against source

Using components

Import from ~/components/atlas/* (see src/components/atlas/README.md for the full catalog). Reach for plain Markdown first — a component should earn its place over a table, list, or blockquote.

Adding a diagram

Prefer D2 (diagrams/source/*.d2) for real topology/architecture; Mermaid is fine inline for a simple sequence diagram. Run npm run diagrams after editing a .d2 file and commit the regenerated SVG — CI (npm run diagrams:check) fails a PR that doesn’t.

Generating reference docs

Never hand-edit a file under content/docs/public/reference/** or .../developers/*-reference.mdx — those are generated. Edit the source (schemas/manifests/*.json, schemas/openapi/*.yaml) and run npm run docs:generate.

Templates

templates/*.md has starting points for ADR, RFC, RUNBOOK, SYSTEM, SERVICE, INCIDENT, POSTMORTEM, EXPERIMENT, and SPEC documents. Copy one into the right content directory rather than starting from a blank file.

Public vs. internal

NEVER LINK PUBLIC -> INTERNAL

A public page must never link to an internal path. npm run docs:validate checks broken links within each audience but can’t catch a public page linking to a URL that only resolves internally — review this by eye.

See ADR-0002 for how isolation is enforced at the build level.

Reviewing stale docs

npm run docs:freshness reports pages past their reviewInterval, grouped by severity. It’s advisory, not a merge gate — see the script’s own header comment for the severity rules.

Deployment

Static output only — see docs/engineering/cloudflare-access.md for the Cloudflare Pages + Access deployment model.

Troubleshooting the docs build

• A page 404s locally — did you run npm run stage:public / stage:internal (or dev:public/dev:internal, which do it for you) after adding the file? src/content/docs/ is regenerated, not live.
• Build fails with a schema error — check the frontmatter against src/content.config.ts; type/status are strict enums.
• npm run check fails on diagrams — you edited a .d2 file without running npm run diagrams afterward; commit the regenerated SVG.