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

Atlas re-checks every source about every 15 minutes, whether or not the project auto-updates. 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". A project with auto-update on then gives its stale sources a delta run on its cadence; unchanged sources are skipped entirely. A manual project stays marked stale until you run it.

When a source can't be reached

If the check fails outright — the repository was deleted or renamed, or the credential expired — the source is marked "Unreachable" and the card shows the exact error the check got back (repository not found, could not read Password for github.com, …).

Unreachable is shown ahead of Stale and ahead of the last run's status: a run that succeeded weeks ago says nothing about a source that has since disappeared. The project reads Unreachable on the Atlas home for as long as any of its sources are, and its source count says how many.

It clears itself on the next successful check — about 15 minutes after you fix the cause:

Credential expired or revoked → replace the token, see [[Atlas credentials]].
Repository moved or renamed → update the source's location.
Repository deleted → remove the source, or leave it and keep the badge as the reminder. Its already-generated pages stay where they are either way.

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.