docs

ATLAS Documentation

Task-oriented index for everything under docs/. For a directory-by-directory map of the repository itself, see MAP.md.

翻訳 / 번역 / 翻译: 简体中文 · 日本語 · 한국어 (README, SETUP, ARCHITECTURE, TROUBLESHOOTING are translated; everything else is English-only.)

---

What are you trying to do?

Install ATLAS

• GETTING_STARTED.md — the beginner path: reality-check your hardware, install, verify, and run a first task.
• SETUP.md — all install paths: one-shot bootstrap, Docker Compose, bare metal, K3s. Start at § Pick your install path.
• SETUP_MACOS.md — Apple Silicon (native Metal llama-server + Docker for the rest).
• Sizing questions before you download anything: SETUP.md § Supported GPUs and TROUBLESHOOTING.md § What fits on my GPU?
• What is and isn't supported, with evidence: SUPPORT_MATRIX.md

Use ATLAS day to day

• CLI.md — the TUI and every atlas subcommand: panes, slash commands, permission modes, atlas model / tier fit / onboard / bench / lens / asa.
• CONFIGURATION.md — every environment variable and internal constant, per service; includes adding your own model.
• OPERATIONS.md — health, logs, runbooks, upgrade, rollback, backup/restore.
• PUBLISHING.md — share trained Lens / ASA artifacts (HuggingFace upload + registry PR).

Integrate with ATLAS

• API.md — HTTP reference for all four services (proxy, v3-service, geometric-lens, sandbox).
• PROTOCOL.md — the typed SSE event envelope shared by proxy, v3-service, and clients.
• schemas/ — machine-readable contracts: proxy_openapi.yaml, error_envelope.schema.json, sse_envelope.schema.json.

Fix a problem

1. TROUBLESHOOTING.md § Quick Diagnostics — find which service is unhappy in three commands.
2. TROUBLESHOOTING.md — issues organized by service (Docker/GPU, llama-server, proxy, lens, sandbox, benchmarks), with an exact-error index up top.
3. atlas doctor for a one-shot health report, and atlas diagnostics collect for a shareable, redacted support bundle (both documented in CLI.md).
4. Still stuck? Open an issue — paste the doctor output.

Understand how it works

• ARCHITECTURE.md — the two-layer design: outer agent loop, inner V3 pipeline, Geometric Lens, sandbox.
• PLAN_MODE.md — per-turn pre-flight planning.
• SOURCES.md — the research papers behind each component.
• reports/V3_ABLATION_STUDY.md — where the headline benchmark number comes from, phase by phase.
• reports/CALL_GRAPH_REASONING_V3.md — structural call-graph reasoning design notes.
• adr/ — architecture decision records (trust model, Redis to SQLite, per-model bundles, fail-soft V3, lens optionality, release strategy).
• STORY.md — why this project exists.

Contribute

• ../CONTRIBUTING.md — workflow, style, tests, and the developer quality gate (scripts/production-readiness.py).
• DEVELOPMENT.md — dev mode, targeted rebuilds, running the proxy on the host against the compose stack.
• RELEASE.md — the release contract and verification levels.
• CONTAINER_PACKAGING.md — image accounts, writable dirs, dependency pinning.
• ../GOVERNANCE.md, ../MAINTAINERS.md, ../SECURITY.md, ../CODE_OF_CONDUCT.md

---

Shortcuts by situation

New to ATLAS. GETTING_STARTED.md, which walks the whole first hour; keep TROUBLESHOOTING.md open in a tab.

Know what you need. Use the section index above, or MAP.md if you're looking for code rather than docs.

Something's broken. TROUBLESHOOTING.md § Quick Diagnostics → the per-service section for whichever health field is false → atlas doctor → open an issue with the output.

Want to read everything. Follow the start-to-finish reading order below.

---

Core terms (one line each)

• Direct agent / outer loop — the Go proxy's tool-calling loop; works with any GGUF, no per-model training (ARCHITECTURE.md).
• V3 pipeline / inner layer — multi-candidate generation, scoring, sandbox verification, and repair for non-trivial files (ARCHITECTURE.md, reports/V3_ABLATION_STUDY.md).
• Tiers (T0–T3) — per-message and per-file complexity classification; T0 is conversational, T1 writes directly, and T2/T3 use the V3 pipeline (ARCHITECTURE.md).
• Geometric Lens, C(x) / G(x) — energy-based candidate scoring over the model's own embeddings; per-model trained bundle (ARCHITECTURE.md, ../SUPPORT_MATRIX.md).
• ASA — activation-steering control vector nudging tool selection; per-model, opt-in until validated (CLI.md, PUBLISHING.md).
• Sandbox — isolated multi-language execution used for verification (ARCHITECTURE.md, API.md).
• GBNF grammar enforcement — token-level constrained decoding that strongly steers tool calls toward the expected JSON schema, with proxy-side recovery for malformed or truncated output (ARCHITECTURE.md).

---

Read ATLAS start to finish

In order, each building on the last:

1. ../README.md — what and why
2. STORY.md — background
3. GETTING_STARTED.md — the first hour
4. SETUP.md / SETUP_MACOS.md — install
5. CLI.md — the surface you actually touch
6. TROUBLESHOOTING.md — failure modes and diagnosis
7. CONFIGURATION.md — every knob, per service
8. ARCHITECTURE.md — how the pieces fit
9. PLAN_MODE.md — pre-flight planning
10. PROTOCOL.md — the event contract
11. API.md — the full HTTP surface
12. reports/V3_ABLATION_STUDY.md — evidence
13. reports/CALL_GRAPH_REASONING_V3.md
14. SOURCES.md — the research it stands on
15. adr/ — decisions 0001 through 0007, in order
16. ../SUPPORT_MATRIX.md — claims and their evidence
17. OPERATIONS.md — running it long-term
18. DEVELOPMENT.md, ../CONTRIBUTING.md, RELEASE.md, PUBLISHING.md, CONTAINER_PACKAGING.md — working on it
19. ../CHANGELOG.md — how it got here