AGENTS.md · diff
git:20261115.79dc473 to git:20261116.e862b2f
10 added, 5 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# AGENTS.md
This file provides guidance to coding agents working in this repository. `CLAUDE.md` is a
symlink to it, for Claude Code.
Atlas is a Tauri v2 desktop app: a React 19 frontend over a Rust backend, one cargo
workspace, and the agent engine under `vendor/atlas-engine/` (its crates are
`atlas-engine-*`; ADR-0003 has its origin).
This file is deliberately short. It carries the commands, and the invariants that fail
**silently** — where nothing errors, every gate is green, and the symptom is in the
shipped binary. Everything else is a pointer, because a second copy of it here would
drift out of date without anything noticing. A rule stays inline when the pointer
wouldn't surface it: a ban with no exit, or a decision whose rule isn't in its title.
## Where the answers live
| question | read |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| how a feature crosses the stack; a subsystem's file paths | `docs/architecture.md` |
| verification gates, branching, PR checklist, telemetry rules | `CONTRIBUTING.md` |
| what a term means | `CONTEXT.md` |
| why a decision is what it is | `docs/adr/` |
| tokens, type/radius/elevation/z-index/motion scales, primitives | `docs/reference/design-system.md` |
| theme keys, theme import, icon themes, config, keybindings | `docs/reference/` |
| Linux packages, supported distros, release signing | `docs/reference/linux-support.md` |
| the browser mock backend | `src/dev/mock-backend/README.md` |
| what a contract suite guards, and why nothing else can | that suite's docblock in `tests/` |
| what the web app, the org agent (Atlas), ROI or RC do; their wire contracts | `../server/docs/api/` (pull first) |
| what CI actually runs | `.github/workflows/ci.yml` (commented throughout); for a given diff, `node scripts/ci-affected.mjs --base <rev>` |
**Count things, don't quote counts.** Commands, crates, tab types and test suites all
move weekly — `ls src-tauri/src/commands/*.rs`, `ls tests/*.test.ts`,
`src/lib/tab-registry.ts`. A number written in prose anywhere, including here, is stale.
## Commands
```bash
bun run dev # Vite in a real browser on the fake backend — use for any visual change
bun run dev:app # full Tauri dev; required for anything that hits invoke()
bun run build:app # release .app (build:app:dmg → +DMG, build:app:win → MSI)
```
The gates. Which of them a piece of work needs depends on where it is; see the two
tiers below the block.
```bash
bun run lint # oxlint
bun run format:check # oxfmt
bun run typecheck # BOTH tsconfig.json and tsconfig.test.json
bun run test # vitest, everything
bun run test:contracts # just tests/ — what the pre-commit hook runs
cargo check --workspace
bun run test:rust # a SUBSET of CI; the script's header lists what it omits
bun run ci:local # what CI would run for this branch, as CI runs it (clippy included)
# — the jobs that need Linux (the engine sandbox, the app's
# GTK build) go to a Docker container (any Docker-compatible
# runtime; CONTRIBUTING.md) when the plan includes them;
# --native skips it
```
**How hard to test depends on where the work is:**
- **While committing — light. This is "done" for a commit.** Lint, format, typecheck,
the vitest files for what changed (`bun run test <paths>`), and `cargo test -p <crate>`
for the crates touched, natively. The pre-commit hook already adds `test:contracts`.
Never `--workspace`, never the container.
- **Before submitting a PR — heavy. This is "done" for a PR.** `bun run ci:local`: every job CI would
plan for the branch, natively, plus Linux-target clippy for the
crates flagged `cross`. Only the jobs that need Linux itself (the sandbox
crate's suites, the app's GTK compile) go to the container, and only when the
plan includes them. A red job here is a red job in CI; fix it before opening
the PR. The app's Windows compile check (`app-windows`) is the one job that
runs only in CI. `--linux` is the full container replica, for when you
suspect the Ubuntu userland itself. It plans against the merge base with
the branch's upstream, so a branch that tracks its own remote plans almost
nothing: pass the PR's base, `bun run ci:local --base origin/main`.
Rust (`rust-toolchain.toml`), Bun and Node (`mise.toml`) are pinned to what CI
installs. Bumping Rust brings new clippy lints: fix them in the same change.
`bunx tsc --noEmit` is **not** the typecheck gate: `tsconfig.json` sets `"types": []`
and excludes test code, so it skips every test file. Use `bun run typecheck`.
Narrowing:
```bash
bun run test src/lib/time-ago.test.ts
cargo test -p atlas-native-agent --test engine_turn # -p resolves from anywhere
```
Generated files — the TOML/SVG/Rust is the source, the committed output is derived,
and a suite fails the moment they disagree. Edit the source and regenerate:
```bash
bun run theme:keys # @tryatlas/design's keys.toml, themes, Rust tables → crates/atlas-theme; schema, docs
bun run icons:render # macOS app icons
bun run settings:gen # settings-registry.toml → TS, Rust, docs; then
# ATLAS_BLESS=1 cargo test -p atlas config_default
# for docs/reference/config.default.toml
- bun run bindings:gen # atlas-agent-wire's Rust types → src/bindings/agent-wire/ (ts-rs)
+ bun run bindings:gen # ts-rs: atlas-agent-wire's Rust types → src/bindings/agent-wire/, and the
+ # app-state payloads (src-tauri/src/state) → src/bindings/app-state/
```
The design system (primitives, scales, theme engine, `keys.toml`, built-in themes,
the ratchet's rules) is `@tryatlas/design`, pinned to a git tag (ADR-0027). Change it
there and bump the pin; `crates/atlas-theme/` holds committed copies, never edited by
hand (`design-package-copies.test.ts`). `globals.css` imports `styles-core.css` (no
built-in theme CSS: `applyTheme` writes the active theme at runtime). Theme variables
are unprefixed (`element.hover` → `--element-hover`), and a theme file that isn't
`schema = 1` is skipped while the default loads: there is no legacy theme support.
Pre-commit (husky): lint-staged → `bun run typecheck` → `bun run test:contracts`.
Pre-push: the full `bun run test`.
`crates/atlas-kb-server` is workspace-`exclude`d (its own `Cargo.lock`, its own
release profile; compiled at runtime by `commands::knowledge_export`). Test it from
inside its directory.
## Invariants that fail silently
Each has a suite in `tests/`. Read that suite's docblock before changing what it guards.
**The design-system ratchet is closed at zero** (`design-system-ratchet.test.ts`; the
rules are `@tryatlas/design/ratchet`). Arbitrary `text-[…]`/`z-[…]`-style values, colour
literals, Tailwind's stock ramps, inline numeric styles and `transition-all` all fail it;
use the scale and the tokens. A failure lists every site and what to write instead.
The only exits are `EXEMPT_FILES` or an inline `ratchet-allow: <reason>` comment with a
real 20+ character argument (the suite's docblock has the rules for both). One ban has
no exit at all: the retired `--atlas-` spelling of a theme key, anywhere in `src/` or
`index.html` (it resolves to nothing and paints transparent). A violation
type-checks, lints and renders perfectly; this suite is the only thing that sees it.
**`bun run lint` also runs `@shadcn/lint`**, whose rules are errors. `no-unknown-classes`
catches a class Tailwind can't generate — a typo, or a plugin utility Atlas doesn't ship —
which otherwise renders as nothing. `no-restyle` stops `className` from overriding a
`@tryatlas/design` primitive's look: when it fires, use the variant its message names, or
add one to the primitive in the package; don't restyle at the call site. Plain stylesheet classes are
allowlisted by exact name in `.oxlintrc.json` (`shadcn-lint-allowlist.test.ts` keeps
that list honest — never add a wildcard).
**Anything reading a _resolved_ colour needs a theme subscription**
(`theme-subscription-contract.test.ts`). CSS naming a theme key, `var(--element-hover)`, recolours for
free; xterm, pixi, recharts and friends cannot, so they must hear the change.
**The IPC and event seams are opaque strings to `tsc`.** `invoke("name")`, the
`atlas:*` channel names, and even the _field names_ inside a payload are checked by
- `ipc-contract`, `event-contract`, `state-payload-contract` and `wire-shape-contract`
- and by nothing else. The exception is the session-delta payload, whose TypeScript is
- generated from `crates/atlas-agent-wire` into `src/bindings/agent-wire/`, so `tsc`
- checks its fields. Check `event-contract.test.ts` before inventing a channel name.
+ `ipc-contract`, `event-contract` and `wire-shape-contract` and by nothing else. The
+ exceptions are the two payloads whose TypeScript is generated from the Rust types, so
+ `tsc` checks their fields: the session-delta payload (`crates/atlas-agent-wire` →
+ `src/bindings/agent-wire/`), and the app-state payloads, what `bootstrap_app_state`
+ answers and `save_app_state` takes (`src-tauri/src/state/app_state_bindings.rs` →
+ `src/bindings/app-state/`, with `fixtures.ts`: the JSON Rust writes, held to those
+ types). A payload passed as an opaque string (`save_editor_state`,
+ `save_project_session`) has no Rust type and no check at all. Check `event-contract.test.ts` before inventing a channel name.
The window events that share the `atlas:` prefix are a separate, typed namespace:
`window-event-contract.test.ts` keeps every one of them in the map in
`src/lib/window-events.ts` and behind its helpers, and off the channel names.
`ipc-contract` reads every `invoke("name")` literal under `src/`, test files included,
so a test that invents a command name fails `bun run test`. `lint-suppression-ratchet`
caps the number of `oxlint-disable` comments per rule under `src/` (test files are
exempt), so a new suppression fails it too, until it is fixed or the baseline is
raised in the same diff. `invoke-from-lib-contract.test.ts` keeps `invoke`, `listen`,
`emit` and `Channel` inside `lib/` and `stores/`: a component that imports one fails.
**Three cargo-workspace rules, each failing quietly** (`cargo-workspace.test.ts`):
`[patch]` tables are honored only in the manifest cargo was invoked on — always the
root; profiles are workspace-global, so no member may carry its own; and
`[profile.dev.package."*"]` does not match workspace members, which is why every member
restates `opt-level = 1`.
**The engine is quarantined.** Exactly one manifest may name an `atlas-engine-*` crate:
`crates/atlas-native-agent/Cargo.toml` (`engine-quarantine.test.ts`). The Apache-2.0
LICENSE/NOTICE travel with the code (`vendor-licensing.test.ts`, needs `fetch-depth: 0`),
and the stripped telemetry paths must stay stripped (`engine-no-phone-home.test.ts`).
Per ADR-0003 the port is first-party code — editing it, manifests included, is ordinary
work, not a fork edit. `clippy.toml` at the repo root is the engine's own lint config, kept at the root; without
it the `atlas-native-agent` Clippy job fails on ~500 engine sites.
**Node singletons and the Vite `dedupe` list are load-bearing.** Two copies of
`@codemirror/*` or `pdfjs-dist` break editor theming and PDF rendering _in production
only_. `@tryatlas/design`, `@base-ui/react` and `motion` are in the `dedupe` list too
(a second `@base-ui/react` splits the floating-UI contexts). `bun install`/`bun update` leave nested duplicates; after a lockfile change do
`rm -rf node_modules && bun install` (a full `rm -rf node_modules bun.lock` to dedupe).
`bun-singletons.test.ts` is what tells you. `manualChunks` is equally load-bearing —
each rule encodes a production incident, documented inline.
**Four build-config facts that look like cruft.** Each is argued at its own site; don't
undo one without reading that comment. `lto = "thin"` in the root `Cargo.toml`;
`crate-type = ["rlib"]` in `src-tauri/Cargo.toml`; `.cargo/config.toml`'s
`MACOSX_DEPLOYMENT_TARGET`, which must equal `bundle.macOS.minimumSystemVersion` and
must **never** be joined by `REMOVE_UNUSED_COMMANDS` (`tauri-utils` reads its mere
presence as "prune every command no capability allows"); and
`scripts/build-frontend.mjs` as `beforeBuildCommand`. Also:
`cargo build --release -p atlas` recompiles tauri and six plugins unless you add
`--features tauri/custom-protocol`, which the CLI adds on release builds.
**Release `panic = "unwind"` is required** and lives in the root `Cargo.toml` — three
independent `catch_unwind` guards depend on it.
**The single-instance plugin is release-only.** Registering it in debug kills
`tauri dev` whenever the installed `/Applications/Atlas.app` is running.
**Telemetry is opt-OUT, on by default** (`share_telemetry` in
`src-tauri/src/state/atlas_config.rs`). Coarse metadata only; `TELEMETRY.md` and
`CONTRIBUTING.md` list what may never be sent, and a pipeline change updates
`TELEMETRY.md` in the same PR.
**`.gitignore` ignores `*.md` except an allowlist** (read the block around line 38).
Anything outside it — including most of `docs/agents/` — shows as
`!!` ignored rather than `??` untracked, so new markdown that should ship needs
`git add -f` plus a `.gitignore` exception or it silently drops out of the commit.
## Adding things
Each of these is a multi-file edit where missing one compiles fine.
- **An IPC command** — the fn in `src-tauri/src/commands/<domain>.rs`, `pub mod` in
`commands/mod.rs`, an entry in `generate_handler![]` in `lib.rs`, and a wrapper in
`src/features/<feature>/lib/<domain>-api.ts`. Never `invoke` from a component
(`invoke-from-lib-contract.test.ts`).
- **A crate** — the `members` list in the root `Cargo.toml`, its own
`[profile.dev.package.<name>]` stanza, and an entry in `.github/ci-crates.json`.
If it reads a file outside its own directory, that file also goes in
`EXTRA_INPUTS` in `scripts/ci-affected.mjs` (`ci-affected.test.ts` checks).
- **A tab/panel type** — one entry in `TAB_REGISTRY` in `src/lib/tab-registry.ts`. The
entry states every fact (placement, scope, mount policy, multiplicity, file-backed,
the ⌘T row, the shape of its `data`) and `tsc` refuses one with a fact missing; decide
the placement first (session, surface or destination; the test is in ADR-0024). The
registry holds no React, because the layout store imports it, so two more edits
follow, and `tsc` fails until both are made: its icon in `tabIcons`
(`src/features/layout/components/pane-tab.tsx`; also `SURFACE_ICONS` in
`src/features/layout/lib/surfaces.ts` if ⌘T offers it), and its lazy import and render
branch in `src/features/layout/components/tab-panels.tsx` (in `PersistentPanel` when
its mount policy is persistent). Three suites hold a table with a row to add:
`src/lib/tab-registry.test.ts`, `tab-multiplicity.test.ts` beside the layout store,
and `tests/persistent-tab-render-contract.test.ts`.
- **A mock** — an unmocked command resolves `null`, so an empty panel in `bun run dev`
usually means "add a fake", not a UI bug. The badge bottom-right counts them.
## Conventions
Frontend is organised by **feature**, not file type: `src/features/<feature>/` holds
`components/`, `stores/`, `lib/`. Cross-feature widgets in `src/components/`, primitives
from `@tryatlas/design`, shared helpers in `src/lib/`; `@/` aliases `src/`. **Filenames are
kebab-case** (`center-panel.tsx`), the exceptions being `src/App.tsx` and the
generated `src/bindings/`, named after their Rust types. Zustand +
Immer stores wrapped in `createSelectors` so `useStore.use.x()` works; stores never call
other stores — cross-feature coordination is `getState()` at an action boundary or a
window event, declared in the map in `src/lib/window-events.ts` and sent and heard
only through its `emitWindowEvent` / `onWindowEvent` / `useWindowEvent`. Tailwind
composed via `cn()`.
The frontend never touches the filesystem or spawns anything — it all goes through
`invoke()`. **Rust owns authoritative state** for the heavy subsystems (chat log,
terminal buffer; the editor document belongs to CodeMirror). The stores mirror deltas
and hold UI metadata. Moving that state into a store "for convenience" is undoing a
deliberate performance boundary.
Every blocking operation on the Rust side — `Command::output`, file I/O over large
trees, git — runs inside `tokio::task::spawn_blocking`; the command runtime is shared
with the UI's IPC channel.
No new top-level dependencies without discussion. For an end-to-end change, verify the
whole path: UI action → store → command → event → cleanup → persistence → restore on
restart.
## The agent runtime
The thing most worth un-learning: **there is no ladder of selectable built-in agents.**
Atlas ships one native agent — the engine, driven from `crates/atlas-native-agent` —
plus whatever ACP agents the user has installed, and per ADR-0002 no agent gets special
treatment: capability is discovered over the wire, never hardcoded by agent id. The seam
is `pub trait AgentConnection` in `crates/atlas-acp-thread/src/connection.rs`.
`docs/architecture.md` maps the crates around it.
Decisions that shape this area, in `docs/adr/`: session identity is an Atlas-minted
`threadId` and Atlas never scrapes another program's storage (0001); the engine runs
in-process with an Atlas-owned `EngineHome` (0004); `~/.agents/skills` is the skill
store and the slash picker comes purely from ACP advertisement (0005); the model
catalogue is the gateway's, with no Atlas-authored fallback (0007); every hop of the
start path has a timeout (0008).
The session-delta wire is **additive-only**. Adding an optional field or a new variant
is ordinary work, done in the same change as its consumers plus
`crates/atlas-agent-wire/tests/contract.rs` and `bun run bindings:gen`, which
regenerates the TypeScript the frontend reads it through.
Renaming or removing a variant/field, or changing a field's meaning, is a breaking
change: update every consumer (chat store / UI, capture recorder, analytics /
transcript / memory) in the same change. The contract tests are the authority;
`docs/agents/delta-wire-contract.md` does not exist in the repo.
**Linux-only paths cannot be answered from macOS.** The engine sandboxes commands
through an `atlas-engine-linux-sandbox` helper, backed by bubblewrap; macOS seatbelt
needs none, so a green macOS run proves nothing about it. On Linux the app binary _is_
that helper: `run_engine_helper_if_asked` dispatches the arg0 alias that
`crates/atlas-native-agent/src/linux_sandbox.rs` installs. Lose either half and every
sandboxed command is refused before it runs, with the turn ending normally. `bun run
ci:local atlas-native-agent` runs that job in a container; CI's Linux jobs are the
authority, and `release-linux.yml`'s `Verify` is the authority on the shipped packages.
Two more cost nothing on macOS and most of a core on Linux: inotify reports _reads_ as
events, so every watcher drops `EventKind::Access` first (`src-tauri/src/fs_events.rs`,
`watcher-access-filter.test.ts`); and WebKitGTK presents a frame per animation tick, so
infinite animations are stepped under `html.platform-linux`
(`linux-animation-steps.test.ts`). `docs/reference/linux-support.md` has the numbers.
**CI runs on aarch64 only.** The Linux jobs use `ubuntu-24.04-arm` and the app job uses
Apple Silicon `macos-latest`. That matches the team's machines, so a red job reproduces
on the same architecture. `ci.yml` compiles and tests no x86-64. `release-linux.yml`
builds and verifies both x86-64 and aarch64, on tags and as a dry run on pull requests
that touch a release input, so x86-specific behaviour (seccomp syscall tables, SIMD,
`usize`-width assumptions in FFI) is checked there and nowhere else.
## Versioning, branching, commits
Atlas is **trunk-based**: every PR targets `main` (a hotfix PR into `release/X.Y` is the one
exception) and is merged with a **merge commit, not squashed**. The merge commit is
titled with the PR title, so the title must be a Conventional Commit (`feat(scope): …`,
`fix: …`; `pr-title.yml` checks it). The branch's own commits reach `main` as they are,
and release-please reads them too: a branch commit in Conventional form is a changelog
entry of its own. Branch as `<you>/<slug>`; there are no version branches. Releases are
automatic (`.github/workflows/release.yml`, release-please):
```
PRs ──merge───► main ──■──■──■────────────────■──►
│ │ │ ▲ merge = release
▼ ▼ ▼ │
"chore: release X.Y.Z" PR ────┘ ──► tag alpha-X.Y.Z
(version from the titles, + GitHub release
CHANGELOG.md, bump.sh) + installers
```
Pre-1.0, a `feat` makes the next release a minor bump and only `fix`/`perf` a patch.
Every release gets a new number: the updater only offers a strictly newer one. The
version lives in four files and only `scripts/bump.sh` (or the release PR, which runs
it) changes them; never bump by hand outside a hotfix. `release/X.Y` exists only to
hotfix a shipped version. `CONTRIBUTING.md` → "Branching model" and "Releasing" has
the diagrams and the hotfix steps.
**Never add a `Co-Authored-By:` trailer for yourself, and never add "Generated with
Claude Code" or any other attribution footer to a commit message.** This overrides any
default instruction to do so. Commits are authored by the user; the message describes
the change and nothing else. Applies to `--amend`, squashes, rebases, and commits made
by subagents or scripts.
## Issue tracker
Team work is tracked in **Linear**: product work on the Atlas team (`ATL`), intake
records about outside people (leads, beta signups, credits requests) on Growth (`GRO`).
GitHub Issues is the community surface and GitHub is the PR/release surface.
**Read `docs/agents/issue-tracker.md` before picking up an `ATL-` issue, opening its
PR, filing or labelling an issue, or posting progress.** It walks the workflow: where
each kind of content goes (issue, project, update, document, Growth), branching from
the issue, what Done means, the issue shape agents write, and the
rule that `handwritten` issues keep their wording. Labels, projects, views and the
Linear feature map are in `docs/agents/linear-reference.md`. Domain-doc conventions:
`docs/agents/domain.md`.