---
title: Contributing
---

# Contributing

This is the complete guide for choosing, creating, or indexing durable documents in Flexcompute Atlas.
Endpoint paths below (`memo-number.json`, `llms.txt`, `llms-index.json`, and friends) are
relative to the site root, the page that linked you here.

## Atlas in one minute

Atlas is Flexcompute's knowledge base. Documents live in the `flex` and
`compute` repositories; Atlas makes them findable, for people on this site and
for agents through the Atlas MCP server. Everything lands by pull request. If
it should still be findable next month, it belongs in Atlas.

Where does it go?

- **How one component works** → next to its code: a README, or
  `<component>/docs/` for design notes, runbooks and local ADRs.
- **A plan, roadmap or spec in flight** → `docs/projects/<name>/`, with an owner
  named in the folder README.
- **A cross-team decision or standard meant to last** → a memo. Change it with
  a newer memo, not by rewriting it.
- **Evidence, analysis, a one-off investigation** → an exploration: a dated
  snapshot.
- **Status, discussion, review** → Jira, Slack or the pull request, not Atlas.
- **A useful document that already exists** → leave it where it is and
  [index it](#indexing-existing-repo-docs-in-place).

Unsure? Write an exploration.

A claude.ai artifact is a view, not a record: its link is random, often
private, and rarely opened again after a day. If a write-up backs a decision or
will be cited later, file it in Atlas and share the Atlas link next to the
artifact.

## Choose the right home

| Home | Kept true by | How it changes |
| --- | --- | --- |
| **Next to code**: README, `<component>/docs/` | The code's owners | In the same pull request as the code |
| **Project folder**: `docs/projects/<name>/` | The owner named in the folder README | Edited as the work moves |
| **Memo**: `docs/memos/NNNN/` | Nobody; it is a record | Small fixes in place; real changes in a newer memo that names the one it replaces or changes |
| **Exploration**: `docs/explorations/YYYY-MM-DD-slug/` | Nobody; it was true on its date | Not revised; link forward to newer work |

- Plans and roadmaps are never memos. If a plan commits another team to
  something, put that commitment in a short memo or a local ADR that cites the
  plan.
- If you expect to rewrite it within a quarter, it is not a memo.
- Organize by code and project, not by team. Team folders go stale when teams
  change.

Code owners and project owners keep their local formats (ADR, RFC, PRD, TDD,
incident, runbook); Atlas indexes them where they live. Indexing a document
does not move ownership or make its format canonical. A memo can record a
decision, but is not inherently a decision.

## What lives here

- **Memos** are durable, cross-cutting decisions, standards, and positions.
  They use global four-digit numbers (`0042`) shared across repositories and
  are meant to stay worth reading years later.
- **Explorations** are dated snapshots of evidence and analysis. Their folders
  use `YYYY-MM-DD-slug` names. Lower bar, no numbering, not kept current.
- **Docs** are code and project docs. They stay where they live and show up
  in Atlas once `docs/knowledge.yml` covers their path; check it in the same
  pull request ([how](#indexing-existing-repo-docs-in-place)).

Documents live in two GitHub repositories:

- `flexcompute/flex` is the default home for broadly useful new memos and
  explorations.
- `flexcompute/compute` is the home for privileged memos and explorations, such
  as solver-internal material.

The repository a document lives in determines who can read it on the site.

The site is a rendered view of those repositories. Publishing means merging a
pull request; nothing is edited on the site itself.

## Creating a memo

1. Choose the repository — `flex` by default, `compute` only for privileged
   content (see above) — and clone it or use an existing checkout:

   ```bash
   git clone git@github.com:flexcompute/flex.git
   # or: git clone git@github.com:flexcompute/compute.git
   ```

2. Pick the memo number. Fetch public `memo-number.json` from this site and
   read `nextMemoNumber`. It is derived from published memos and eligible open
   PR artifacts, so the site acts as the advisory reservation ledger:

   ```bash
   curl -fsSL https://atlas.internal.flexcompute.com/memo-number.json | jq -r .nextMemoNumber
   ```

   The number must also be greater than anything already in your clone, so
   cross-check and take the larger:

   ```bash
   ls docs/memos | sort -n | tail -1
   ```

   If `memo-number.json` is unavailable, rely on the clone check here plus the
   open-PR check in the next step.

3. Check that no open pull request already adds the memo, then create a branch.
   An eligible open PR artifact reserves the number; a branch name does not:

   ```bash
   gh pr list --state open --limit 1000 --json number,isDraft,files,url \
     --jq '.[] | select(any(.files[]; .path == "docs/memos/0042/README.md")) | [.number, .isDraft, .url] | @tsv'
   git checkout -b memo-0042
   ```

   Use this listing as a collision check. Only a ready PR with a published,
   eligible Atlas artifact reserves the number.

4. Create `docs/memos/0042/README.md` (four-digit folder, no slug, the file is
   literally `README.md`). Start from this frontmatter:

   ```yaml
   ---
   title: Your Memo Title
   authors:
     - name: Your Name
   tags:
     - your-topic
   ---
   ```

5. Write the body in MyST Markdown (CommonMark plus admonitions; TeX math is
   rendered with KaTeX). Put images and other assets in the same folder as the
   README and reference them with relative paths. Reference other memos inline
   as `memo 0002`; references and backlinks are picked up automatically. Before
   writing, fetch `map.md` from this site. It lists topic neighborhoods and
   navigation anchors derived from existing citations. Cite documents that
   materially support the new work, whether or not the map selects them as an
   anchor.

   Prefer source-addressed links when citing Atlas-indexed documents. For
   same-repository links, use normal relative Markdown links to the source
   document. For cross-repository links, use source-address links such as
   `flex:/docs/explorations/example/README.md` or
   `compute:/docs/memos/0031/README.md`. When the linked repository is included
   in the Atlas build, those links are rewritten to the rendered Atlas page and
   become reference-table and hover-card entries. If the linked repository is
   not part of a partial build, the links fall back to GitHub source URLs.
   Avoid rendered Atlas URLs in authored source when a repository path can
   identify the document.

   When you need to share a rendered Atlas URL outside the source document, use
   the page URL shown in the browser. Atlas rendered page URLs use the
   source-path form directly; for example, `/workspace/v2/flex/docs/memos/0042/`.
   Explicit PR review URLs keep the same document path and add a PR suffix such
   as `/workspace/v2/flex/docs/memos/0042/pr/123/current/` or
   `/workspace/v2/flex/docs/memos/0042/pr/123/<sha>/`.
   The bare document URL renders the published page when one exists; otherwise
   it renders the selected open PR preview. When multiple open PRs touch the
   same source document, the page shows a PR previews panel instead of changing
   URL shape.

6. Commit and push. The flex repository enforces conventional commits:

   ```bash
   git add docs/memos/0042
   git commit -m "docs(memos): add memo 0042 your memo title"
   git push -u origin memo-0042
   ```

   (In `compute`, use a plain imperative subject instead:
   `Add memo 0042 your memo title`.)

7. Open a pull request. **The eligible open PR artifact is the reservation of
   the memo number.** Once the PR is ready for review and its Atlas validation
   and artifact publication succeed, `memo-number.json` includes it in the
   next-number calculation. The site build fails on duplicate memo numbers, so
   a collision is caught before it ships.

Only the fields in the frontmatter reference below are supported. Status is
derived from git (open while the document is on an unmerged branch, published
once merged), visibility comes from the repository the document lives in, and
dates come from git history. The one date exception is `created`, which may
override the derived date when importing something written earlier.

Validated same-repository memo and exploration PRs appear on the live dev site
once two runs finish: the artifact publish for the PR, and the aggregate
refresh that publish queues. Neither waits for the reconciliation cron. Draft
PRs, fork PRs, and PRs whose knowledge-site validation has not passed are
excluded before the shared indexes are written, so they never appear.

## Creating an exploration

Same flow as a memo without the numbering: create
`docs/explorations/YYYY-MM-DD-slug/README.md` (date prefix required, slug in
lowercase-kebab-case), use the same frontmatter shape, branch
`exploration-YYYY-MM-DD-slug`, and open a PR.

Explorations need no code owner review. A PR that only touches
`docs/explorations/` is approved automatically and merges once its checks
pass, so the [contract](#frontmatter-reference) is the bar. Nobody reads it
for you first: check it contains nothing about customers, pricing,
competitors, people or secrets before you push.

## Interactive pages

A memo or exploration can ship self-contained HTML pages, such as an
interactive map or chart, next to its README. Link each page from the README
with a relative link (`[Open the map](map.html)`); fragments such as
`map.html#level=3` are kept. Linked `.html` files inside the document folder
are published with the document and open on Atlas; unlinked pages are not
published, and links to HTML elsewhere in the repository keep pointing at the
source on GitHub. Pages can link to each other with relative links.

Pages run in a sandbox that blocks API calls and external subresources:
inline every script, style, image, and font (`data:` URLs work), and expect
`fetch`, `localStorage`, and
cookies to be unavailable. Outbound link navigation remains possible.
Pages cannot be embedded in the document; link to them instead.
In `flex`, a page over 300 KB must be stored with Git LFS (add a
`.gitattributes` rule for its path).

## Importing from Notion, Google Docs, or elsewhere

Writing and discussing drafts in Notion or Google Docs is normal and
supported. When the document is worth keeping, bring it into the repo:

1. Fetch the source document (Notion or Drive integration, an export, or a
   readable share link).
2. Convert to MyST Markdown. Watch the usual conversion traps: Notion toggles
   and callouts become plain sections or admonitions, tables become Markdown
   tables, and embedded images must be **downloaded into the document folder**
   — do not hot-link Notion or Drive image URLs; they expire.
3. Follow the memo or exploration flow above. The repo copy is the durable
   record. If an outside discussion is relevant to understanding the decision,
   link it in prose where the context belongs.

## Indexing existing repo docs in place

Code and project docs, new or existing, are indexed where they live. Check
the repository's existing `docs/knowledge.yml` coverage first, including glob
entries, and add an entry only when the document is not already covered. Use
exact paths or globs (`*` within one folder, `**` across subfolders; patterns
must end in `.md`, `.markdown`, or `.tex`). An optional `exclude` list removes
specific files a glob would otherwise pick up, such as directory landing
READMEs, changelogs, or templates:

```yaml
include:
  - path: docs/projects/example/*.md
  - path: docs/runbooks/**/*.md
exclude:
  - path: docs/projects/example/README.md
```

Manifest-indexed docs are default-branch only. They become visible on Atlas
after the pull request merges and the default-branch rebuild runs. Unlike
memos and explorations, they do not get open-PR artifact pages while review is
in progress.

## Indexing LaTeX documents

LaTeX documents are indexed like any other doc — they just render
differently: the site compiles them (with `tectonic`) and publishes the
PDF as the artifact, with a landing page carrying the title, authors,
abstract, and section list extracted from the source. The text of the PDF
is searchable like any other document. Register each one explicitly under
`include` in the same `docs/knowledge.yml`. Use exact `.tex` paths rather than
globs, since every entry costs a compile at build time:

```yaml
include:
  - path: src/solver/docs/example-note.tex
```

The document's `\title{}`, `\author{}`, and `\begin{abstract}` blocks feed
the landing page; keep them populated. The files do not move.

## Frontmatter reference

| Field            | Required | Meaning                                              |
| ---------------- | -------- | ---------------------------------------------------- |
| `title`          | yes      | Document title shown everywhere                      |
| `authors`        | yes      | List of `- name: ...` entries (or a single string)   |
| `tags`           | no       | List of lowercase-kebab-case topic tags              |
| `created`        | no       | Override the derived creation date (`YYYY-MM-DD`)    |

A pull request that adds or changes a memo or exploration must pass the
`Atlas docs` check: frontmatter with only these fields, exploration folders
named `YYYY-MM-DD-slug` with a real date, and every image, page and relative
link resolving and every mermaid diagram rendering. Published documents are not
re-checked, so code moving under an old link does not block anyone. In `flex`,
`pnpm --dir utils/knowledge-site generate` reports the same problems locally.

## Reading the site programmatically

- `memo-number.json` — public advisory next memo number, derived from
  published memos plus current open PR artifacts.
- `llms.txt` — concise index of every visible document with one-line
  metadata. Start here.
- `map.md` — distilled topic map of the citation graph: topic neighborhoods
  with navigation anchors, most-cited documents, and documents with no links
  yet. One fetch to understand the shape of the workspace; citation rank does
  not establish authority.
- `llms-index.json` — compact schema-versioned metadata including
  `nextMemoNumber`, per-document URLs, excerpts, status, and visibility.
- `knowledge-index.json` — search corpus with capped body text. Filter it
  with `jq`; do not paste it into model context.
- Every rendered document page has a raw Markdown twin at `index.md` relative
  to the page URL (for example `memos/0042/index.md`) containing the verbatim
  source including frontmatter.

Reading the site requires signing in; the raw version of this guide
(`contribute.md`) and `memo-number.json` are the only paths served without it.
If a fetch redirects to a sign-in page, sign in through a browser, or work from
a git clone instead — the repositories are the source of truth and contain
everything the site renders.