Atlas runs, coverage & freshness

A run generates or updates the docs for one source. Trigger a full run from a source; Atlas does the rest and publishes into the space.

The pipeline

A run moves through these stages:

Acquire — clone or fetch the source at a pinned ref.
Analyze — enumerate files, extract the surface inventory, chunk code with line ranges, embed chunks, and build the retrieval index.
Plan pages — decide what pages to write, seeded by the surface inventory so must-cover items are guaranteed a home.
Draft — write each page, grounded in the embedded chunks and cited to the source.
Refine — multi-pass critique and expansion of the drafts.
Validate — audit coverage (surface items mentioned vs. total), citations (file:line links that resolve), and diagram structure.
Repair — regenerate any coverage gaps; loops until the must-cover threshold is met or the per-run budget is exhausted.
Publish — write the finished pages into the space.

Full and delta runs

Every manually triggered run is a full run: it re-ingests the entire source from scratch.

When auto-update is on, Atlas instead runs a delta: it compares the current source to the last run's ref — for git, a commit diff via git diff; for Jira, issues updated since the last stored timestamp — and rebuilds only the affected pages. The rest stay intact. You can see the run kind (full or delta) in the run list.

[!NOTE] Triggering a run manually always starts a full run, even if the source isn't stale. Use this to force a complete regeneration.

The run queue

[!NOTE] Atlas runs one at a time by default — a single global queue — so generation never overwhelms the shared AI that also powers Ask and research.

A waiting run shows as "Queued" and starts automatically when the one ahead of it finishes.
The queue is durable: a server restart never strands a queued run.

Resilience

A transient failure on a single page does not fail the whole run — that page is either dropped to a coverage gap or its prior draft is kept. A run only fails if everything fails.

Coverage

Each run reports how much of the source's surface is documented. The report includes:

Metric	Meaning
Coverage	Fraction of all surface items mentioned somewhere in the docs.
Must-cover	The critical subset: entry points, HTTP routes, CLI flags, environment variables, and data models. Atlas aims to keep this at 100%.
Citations	Count of source-linked claims in the generated pages.
Diagrams	Mermaid diagrams generated, with a count of those that passed structural validation.

Atlas writes deterministic reference pages that enumerate the surface with links — e.g. "Components & Exported Types", "API & Routes", "Entry Points, Flags & Environment" — alongside narrative topic pages.

[!TIP] Each source's root folder page is a coverage overview: run stats, coverage numbers, a surface inventory, and the full page list. Start there after a run finishes.

Run statistics

After a run finishes, the overview page and the run panel show:

Stat	What it is
Files	Number of files ingested from the source.
Surface	Number of surface items found and tracked (the spine).
Chunks	Code/text chunks embedded for retrieval.
Pages	Wiki pages generated or updated.
Duration	Wall-clock time for the full pipeline.
Model	The chat and embed model names used.
Tokens	Prompt, completion, and embed token counts.
Cost	Estimated USD cost — only shown when the LLM connection has per-token pricing configured (0 for local/free endpoints).

Citations

Every significant claim links to its source:

git → a blob URL at the exact commit and line range (e.g. a GitHub permalink).
Jira → a browse URL for the issue (e.g. https://your-org.atlassian.net/browse/COM-123).

Freshness & staleness

A project with auto-update on re-checks its sources on its cadence. The check is cheap — no full re-ingest:

git: Atlas runs git ls-remote against the remote to compare HEAD to the stored ref. No clone needed.
Jira: Atlas queries the most-recently-updated issue timestamp against the stored ref. One small API call.

If anything changed, the source is marked "Stale". On the next cadence tick, stale sources get a delta run; unchanged sources are skipped entirely.

Via MCP

Agents can list projects, trigger runs, and poll status using three Atlas MCP tools:

Tool	What it does
`atlas_list_projects`	List the projects the caller can see (personal + org).
`atlas_run`	Trigger a full run for a project (requires manage access). Returns one run ID per source.
`atlas_run_status`	Read a run's current status, stage, coverage metrics, and run statistics.

See [[Agents & MCP]] for how to connect an agent to tela.

[[Atlas projects & sources]] — cadence and auto-update are set on the project.
[[Search & ask your docs]] — generated pages and their citations are searchable and answerable.