docs: correct privacy and diagnostics claims

Author: itigges22

README.md

@@ -37,8 +37,8 @@
 * **Verify before accepting.** Generated code can be compiled, tested, and corrected inside an isolated execution environment.
 * **Spend compute where it matters.** Straightforward edits take a shorter path, while harder tasks receive more candidates, reasoning, and validation.
 * **Run your own model.** Use a compatible GGUF model on NVIDIA, AMD, Apple Silicon, Vulkan, or CPU-supported hardware.
-* **Keep everything local.** Your repository, inference, test execution, and learned artifacts stay on your machine.
-* **Own the full stack.** ATLAS is open source, self-hosted, and has no required hosted API or per-token fee.
+* **Keep control local.** ATLAS does not intentionally upload your repository or prompts to a hosted model or ATLAS-operated service. Sandbox commands have outbound network access by default; set `ATLAS_SANDBOX_NET_INTERNAL=true` to disable it.
+* **Own the full stack.** ATLAS is open source and self-hosted. It requires no hosted model or third-party model-provider API key; a local per-installation service token authenticates ATLAS services.
 
 ---
 
@@ -76,7 +76,7 @@
 
 2. **[atlas-proxy](docs/ARCHITECTURE.md#3-atlas-proxy-outer-layer)** - Go agent loop that orchestrates the system.
    - [Tool-call routing](docs/ARCHITECTURE.md#tools) - classifies file operations by complexity tier
-   - [Grammar enforcement](docs/ARCHITECTURE.md#grammar-enforcement) - GBNF schemas keep JSON output valid
+   - [Grammar enforcement](docs/ARCHITECTURE.md#grammar-enforcement) - GBNF schemas strongly steer output toward the expected JSON shapes, with proxy-side recovery for malformed or truncated output
    - [BiasBusters](docs/ARCHITECTURE.md#tool-selection-bias-mitigations) - four composed mitigations (descriptions, grammar bans, system notes, ASA steering) that push the model toward `ast_edit` for structural code edits
    - [Safety limits](docs/ARCHITECTURE.md#safety-limits) - turn caps, token budgets, timeouts
 

docs/GETTING_STARTED.md

@@ -11,9 +11,10 @@ depth, follow the link.
 
 ATLAS is a local coding agent: a model running on your own GPU, wrapped in
 machinery that plans changes, verifies generated code in an isolated sandbox,
-and repairs what fails. Everything — inference, scoring, test execution, and
-learned state — stays on your machine. It is not a hosted service, there is
-no API key, and nothing is billed per token.
+and repairs what fails. ATLAS runs locally and does not require a hosted model
+or third-party model-provider API key. It creates a local per-installation
+service token for communication between ATLAS services, and nothing is billed
+per token.
 
 One expectation to set: a compact local model with verification is a
 different experience from a frontier hosted model. It shines on bounded,
@@ -48,10 +49,13 @@ roughly 20 GB of disk. Everything it changes is listed in
 pinned-release and review-before-running variants if you'd rather not pipe a
 script into bash.
 
-One security fact worth knowing before your first task: the agent executes
-model-authored shell commands inside a locked-down sandbox container (not on
-your host), and your code never leaves the machine — but generated code is
-still code; review diffs before you commit them.
+One security fact worth knowing before your first task: ATLAS does not
+intentionally upload your repository or prompts to a hosted model or
+ATLAS-operated service. Model-authored shell commands run inside a locked-down
+sandbox container rather than on your host, but sandbox commands have outbound
+network access by default so toolchains can fetch dependencies. Set
+`ATLAS_SANDBOX_NET_INTERNAL=true` to disable sandbox egress. Review generated
+code, commands, and diffs before you commit them.
 
 ## Install
 

docs/README.md

@@ -119,17 +119,19 @@ whole first hour; keep [TROUBLESHOOTING.md](TROUBLESHOOTING.md) open in a tab.
 - **V3 pipeline / inner layer** — multi-candidate generation, scoring,
   sandbox verification, and repair for non-trivial files
   ([ARCHITECTURE.md](ARCHITECTURE.md), [reports/V3_ABLATION_STUDY.md](reports/V3_ABLATION_STUDY.md)).
-- **Tiers (T0–T2)** — per-message and per-file complexity classification;
-  T1 writes directly, T2 runs V3 ([ARCHITECTURE.md](ARCHITECTURE.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](ARCHITECTURE.md)).
 - **Geometric Lens, C(x) / G(x)** — energy-based candidate scoring over the
   model's own embeddings; per-model trained bundle
   ([ARCHITECTURE.md](ARCHITECTURE.md), [../SUPPORT_MATRIX.md](../SUPPORT_MATRIX.md)).
 - **ASA** — activation-steering control vector nudging tool selection;
   per-model, opt-in until validated ([CLI.md](CLI.md), [PUBLISHING.md](PUBLISHING.md)).
 - **Sandbox** — isolated multi-language execution used for verification
   ([ARCHITECTURE.md](ARCHITECTURE.md), [API.md](API.md)).
-- **GBNF grammar enforcement** — token-level constrained decoding that keeps
-  tool calls valid JSON ([ARCHITECTURE.md](ARCHITECTURE.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](ARCHITECTURE.md)).
 
 ---
 

docs/TROUBLESHOOTING.md

@@ -6,19 +6,29 @@ Common issues and solutions, organized by service.
 
 ## Quick Diagnostics
 
-Run these first to identify where the problem is:
+Start with `atlas doctor`, then use Compose status and logs to identify where
+the problem is:
 
 ```bash
-# Docker Compose — check all services at once
+atlas doctor
 docker compose ps
-
-# GPU status
-nvidia-smi
-
-# Docker Compose logs (last 50 lines per service)
 docker compose logs --tail 50
 ```
 
+`atlas doctor` is the preferred first diagnostic because it checks the host,
+configuration, and service health together. `docker compose ps` identifies
+services that failed to start, and the logs provide the next level of detail.
+Use a hardware-specific check only when the first results point to the
+inference backend:
+
+| Backend | Diagnostic command or check |
+|---|---|
+| NVIDIA CUDA | `nvidia-smi` |
+| AMD ROCm | Run `rocm-smi` and verify `/dev/kfd` exists. |
+| Apple Silicon / Metal | Run `atlas doctor`; if the native server is not listening, start `./scripts/atlas-llama-macos.sh` and inspect its foreground launcher output as described in [SETUP_MACOS.md](SETUP_MACOS.md#troubleshooting). |
+| Vulkan | Verify `/dev/dri` exists, then run `docker compose -f docker-compose.yml -f docker-compose.vulkan.yml exec llama-server vulkaninfo --summary`. |
+| CPU-only | Confirm the `docker-compose.vulkan.yml` and `docker-compose.cpu.yml` overlays are active. `atlas doctor` should warn and exit successfully rather than fail solely because no GPU exists. |
+
 For the per-service health-check curls, see [SETUP.md § Verify Installation](SETUP.md#verify-installation). The atlas-proxy health endpoint is the most useful for triage — it reports the status of all upstream services:
 ```json
 {

proxy/README.md

@@ -25,9 +25,10 @@ Each user message drives an agent loop that runs until the model emits
    called to seed an explicit step list. 3 candidates sampled, scored
    heuristically, best plan pinned. The active step is injected into
    the system prompt every turn (`plan_reminder.go`).
-2. **Grammar-constrained generation** — `llama-server` produces a JSON
-   envelope: `tool_call`, `text`, or `done`. GBNF + `response_format:
-   json_object` makes invalid output unrepresentable.
+2. **Grammar-constrained generation** — `llama-server` is strongly steered
+   toward a JSON envelope: `tool_call`, `text`, or `done`. GBNF +
+   `response_format: json_object` constrains decoding, while the proxy recovers
+   malformed or truncated output and treats parsing as fallible.
 3. **Tool dispatch + validation** — 14 tools (`read_file`,
    `outline_file`, `search_files`, `list_directory`, `find_file`,
    `write_file`, `edit_file`, `ast_edit`, `delete_file`, `move_file`,