Atlas

---
name: atlas
description: Create, update, or finalize a note in the kolu Atlas (docs/atlas) — frontmatter, the MDX component kit, build + check-sync, and the preview/share links. Use whenever authoring or editing an Atlas note (e.g. a /be plan-of-record), so the mechanics live in one place.
argument-hint: "<slug | what the note is about>"
---

# Atlas note

A self-contained Astro project at `docs/atlas/`. Author MDX in
`docs/atlas/src/content/atlas/<slug>.mdx` (flat, ancestry-free slug); Astro
renders the committed `docs/atlas/dist/<slug>.html`. Sync rules:
`.apm/instructions/atlas.instructions.md`.

## 1. Author

```yaml
---
title: Title in Title Case
description: One line — what this note is about.
kind: reference        # bug · feature · analysis · reference (the index section)
status: proposed        # optional — proposed → accepted → implemented → superseded
maturity: seedling      # seedling → budding → evergreen
parents: [slug]         # optional — nests under same-kind parents; cross-kind ⇒ a "related" link
---
```

- Prose in markdown; reach for the **kit** in `docs/atlas/src/components/` only where markdown can't (`<Cite>`, `<Callout>`, `<PrLink>`, `<Terminal>`, `<AtlasMockup>`, `<D2>`, …).
- **Headings are an outline, not a count.** Decide the 3–5 *concepts* the note is about, name each as a `##`, then write the body under them. The TOC should read as an outline, not a flat enumeration. Do **not** hit the number by re-leveling: taking a flat list of `##`s and demoting some to `###` to satisfy "≈4" is the wrong move — if you're changing `#` counts on existing headers rather than moving content, you're cheating the rule, not following it. Every `##` must be a genuine peer concept; never invent a catch-all bucket ("Building it", "Details", "Misc", "Other") for whatever's left over. A `###` lives under its parent because it's *part of that concept*, not because the parent had a free slot.
- **Lead structural notes with an architecture diagram.** Any note that proposes or analyzes structure (a `feature`/`analysis` plan, a module split, a package boundary) MUST include a **D2 diagram of the module/package connections**, via `<D2 caption="…" code={`…`} />` (`src/components/D2.astro`). Use **`direction: down`** — a vertical stack fits the column's aspect ratio; `direction: right` renders wide and shrinks the text to unreadable. Quote any key/label with spaces or special chars. The `d2` binary comes from the Nix devShell (pinned; `--sketch=false`/`--layout=dagre` baked in so the SVG is byte-deterministic and `check-sync`'s host-independence gate stays green).
- A **note-local** component is defined **inline in the `.mdx`** (`export const Foo = …`), never a separate file — promote it to `src/components/` only once it's reused across notes. Never hand-edit `dist/`.

## 2. Build & verify

`just atlas::build`, then stage `docs/atlas/dist/`. Finish with `just
atlas::check-sync` (the `ci::atlas-sync` gate): it rebuilds and fails if the
committed HTML is stale or host-dependent.

## 3. Preview & share

Each `dist/<slug>.html` is self-contained: it previews in kolu's Code tab, and —
once the branch is pushed — reads on GitHub via
`https://htmlpreview.github.io/?https://github.com/<owner>/<repo>/blob/<branch>/docs/atlas/dist/<slug>.html`
(`<owner>/<repo>` ← `gh repo view --json nameWithOwner -q .nameWithOwner`,
`<branch>` ← `git branch --show-current`).

## 4. Lifecycle

Notes are **living** — git is the history, no frozen copies. Advance `status` as
it matures and link the implementing PR with `<PrLink pr={<n>} />`. A contributor
proposal is just a note carrying `status: proposed` (see `CONTRIBUTING.md`);
acceptance flips the status, not the `kind`.

ARGUMENTS: $ARGUMENTS