Understand what Atlas is showing

The Companion scans supported files locally and sends structural metadata to Atlas. When locally derived descriptions are enabled, Explorer also shows a short description taken from explicit file metadata, a script synopsis or explanatory file text. Atlas keeps that description against the workspace, relative path and current file content hash, so another authorised Companion can move the workspace without losing it; the description is replaced only after the file changes. Sync updates file metadata, connection state and maps. Run review to prepare one source snapshot for deterministic checks, semantic checks and contextual reference validation. Its confirmed findings, investigation items and coverage determine one assessment. Start with Overview, use Findings to filter and inspect exact evidence, assign owners and manage work in the same Findings list, and follow affected relationships in Impact. Use Findings → Groups for existing group assignments and notes. Unconfirmed references have their own Needs investigation filter; they are not confirmed defects. Review and Executive report show summaries instead of repeating the list. The report can include a detailed recorded appendix when printing. After a fix, sync the changed source and run Review. Free sync updates file metadata; it does not silently start paid processing or publish new findings.

The deterministic stage uses the same repeatable rules for Companion and GitHub workspaces. It creates reference candidates rather than declaring every unresolved filename a defect. AI processing inside the approved Review interprets context before publication. Atlas displays structural finding severity as Low, Medium and High, matching the dashboard and Findings page. Legacy scanner labels Info, Warning and Error map to Low, Medium and High respectively; Atlas does not use a “critical” structural-finding level. AI findings also support Critical. Recorded raw scanner scores are preserved in legacy records and diagnostic details. They do not determine the new Review assessment. This historical calculation starts at 100 and uses Healthy for 90–100, Needs attention for 70–89, and High risk for 0–69.

Broken references · High

The raw scanner deducts 8 points for each unresolved supported relative path, capped at 30 points. This diagnostic suspicion is not proof of a missing dependency; contextual adjudication determines whether Review publishes a finding.

Workflow resolution · High

A missing workflow entry, referenced artifact or checklist costs 10 points, capped at 25 points.

Orphaned files · Medium

A file with no incoming, outgoing or workflow relationship is orphaned. The deduction is proportional to affected files and is capped at 20 points.

Missing descriptions · Low

A file without native description metadata is reported. The proportional deduction is capped at 15 points.

Duplicate names · Medium

Each affected duplicate identity costs 2 points, capped at 5 points. This identifies ambiguous names, not duplicate content.

Dependency cycles · Medium

Each file participating in a dependency cycle costs 1 point, capped at 5 points.

Disconnected groups · Medium

Each linked group that does not connect to the workflow costs 2 points, capped at 5 points.

Context size · Medium when large

Normal is below 4,000 estimated tokens; Elevated is 4,000–7,999; Large is 8,000–15,999; Very large is 16,000 or more. Large and Very large create findings but do not currently reduce the structural score.

Complexity · Medium when high

The weighted complexity score combines tokens, sections, incoming and outgoing references, workflow participation and dependency depth. Low is 0–24; Moderate is 25–49; High is 50–74; Very high is 75–100. High and Very high create findings but do not currently reduce the structural score.

Metadata and classification · Medium

Invalid platform conventions and files without explicit artifact-type metadata are reported for review. They do not currently reduce the structural score.

Finding limits affect how many details a plan retains, not how Atlas calculates the score. Sync changes, then run review to publish a new contextual result. Metadata sync does not replace the completed Review.

Explorer and Health use the same investigation view to explain what Atlas found, show available evidence, describe impact, recommend a fix and provide a copyable AI repair prompt. Generating a tailored repair prompt is a separate 2-credit action. Normal sync remains metadata-only. To include short line-numbered source excerpts, the Companion operator must enable Upload short issue evidence excerpts for that workspace and run a new sync. The option is off by default, secret-like lines are redacted or withheld, organisation members can view stored excerpts, and only the current source version is retained. Turning the option off requests immediate deletion and retries after reconnecting if necessary.

Atlas first validates official platform conventions, then trusted Atlas metadata. For everything else it weighs filenames and folders against the file's dominant purpose; content wins when a non-official name is misleading. Weak or conflicting evidence remains Unknown.

Every recognised category is first-class

Each category below keeps its own Atlas type, count, colour and graph identity. Atlas does not hide Policy under Rule, Playbook under Workflow, or Test under Gate.

Core

Intent, Rule, Skill, Workflow, Agent, Tool, MCP, Script, Hook, Checklist, Evidence, Register, Specification, Configuration, Prompt, Knowledge and Gate.

Governance

Policy, Guideline, Standard, Instruction, Constraints, Permission, Ownership and Secrets Reference.

Processes and actors

Playbook, Runbook, Procedure, Plan, Task, Command, Persona and Role.

Verification

Validator, Test, Evaluation (including Eval), Benchmark, Fixture and Scenario.

Definitions and configuration

Contract, Schema, Spec, ADR, Decision, Dependency Definition, Data Dictionary, Output Definition, Manifest, Environment, Profile, State and Model Configuration.

Knowledge and reusable material

Reference, Example, Memory, Dataset, Resource, Template and Document.

Registers and tracking

Registry, Catalogue (including Catalog), Dependency Register, Risk Register, Decision Register, Exception Register, Progress, History, Log, Roadmap, Backlog, Changelog, Status, Inventory, Index, Decision Log, Assumptions Log, Known Issues and API Catalogue.

Maps and architecture

Service Map, Repository Map, Dependency Map, System Map, Architecture Map, Capability Map, Data Flow Map, API Map, Domain Map, Architecture Overview, Big Picture and Glossary.

Provider conventions

Validated Cursor, Claude, Codex, Agent Skills and GitHub Copilot conventions are recognised. Generic folders such as rules/, skills/ and workflows/ remain clues rather than proof.

Unknown

Ambiguous files remain Unknown rather than being guessed. Health flags files that have no explicit type in their body so their classification can be reviewed.

Referenced images

PNG, JPEG, GIF, BMP, WebP and SVG references are detected. Companion can optionally upload a small preview for safely decodable raster images; original image files are never uploaded. A full organisation member can ask Atlas to describe an uploaded preview with AI after reviewing the credit estimate. The cloud description is reused until the image changes.

Review never starts paid processing silently. Atlas first asks the active workspace source to prepare the scope and estimate. Companion workspaces prepare it locally. GitHub workspaces use an isolated temporary checkout of the exact scanned commit. New Reviews cover one complete pinned snapshot; historical recent-changes reviews keep their recorded legacy scope. You see the file count, batches and estimated Atlas credits before approval. Review combines structural facts with semantic checks and contextual reference validation. The scanner identifies possible missing targets; AI reads the sentence, paragraph and prerequisite steps to distinguish a required dependency from an example, incidental mention, historical reference or expected future output. New findings remain unpublished until every required stage finishes. The previous completed Review remains available with its recorded date and an Out of date indicator where appropriate. Without a completed Review, Atlas shows scan metadata rather than a misleading zero-finding result. History retains one entry per completed Review and explicitly labelled legacy scans and AI reviews. Temporary GitHub checkouts are destroyed after the operation and repository files are not retained by Atlas. A missing-description finding on a Companion workspace also offers a focused repair: for each eligible file up to 2,000,000 characters, Companion redacts sensitive-looking lines, analyses the complete file in temporary chunks, and synthesises one description from every chunk. Atlas estimates all requests before approval. Review and commit generated file edits yourself, then sync again.

The header source icon combines connected Companion installations and active GitHub workspace sources. Its number is the total currently available. Open it to see which source supplies each workspace; browsers and users are not counted.

Use Atlas Companion for local folders, shared drives and private servers. A paid organisation Owner can instead connect an explicitly selected GitHub repository, branch and optional folder. GitHub source files are checked out temporarily in isolated Atlas-controlled compute, converted to the same structural metadata as Companion, and removed after each operation. Atlas does not deliberately retain the checkout, Git credentials or complete repository files.

1. Give each Companion computer a recognisable device name.
2. Use GitHub when the authoritative source is already a repository and hosted processing is acceptable.
3. Each workspace has exactly one active writer, so Companion and GitHub cannot race to update it.
4. GitHub supports free metadata sync and the same complete contextual Review as Companion. Existing complete and recent-changes AI reviews remain available as legacy records. Image analysis, automatic push scanning and repository writes remain unavailable.

For the smoothest map, Flow and Tour experience, turn on hardware acceleration in your browser settings. This lets Atlas use your computer's graphics hardware for its 3D visualisation. You may need to restart the browser after changing the setting.

Review

One assessment combining repeatable file checks, semantic analysis and contextual validation. New findings are published only after all required stages finish.

Reference candidate

A filename occurrence the scanner could not resolve. It is evidence to interpret, not automatically a confirmed defect.

Needs investigation

The review could not establish the intended relationship from the available context. This is separate from confirmed defect totals and must not trigger an unsupported edit.

Deterministic check

A repeatable local check that produces the same result from the same metadata and consumes no AI credits.

Context footprint

An estimate of how much AI context the supported files could require. It does not by itself determine the Review assessment.

AI processing

The context and meaning stages inside Review. Atlas estimates their credit cost and requires approval before execution.

Downstream reach

Items that may be affected because they directly or indirectly depend on the selected item.

Overall assessment

The findings-based conclusion of one completed Review for its recorded source and enabled checks. It does not average numerical scores or certify a release.

Severity and recommended order

Critical is red, High orange, Medium amber and Low blue. Unknown is neutral. Numbered recommendations rank groups by highest severity, finding count and title. Group severity does not change individual findings.

Action group

Related findings grouped into one planning item. Its owner and status apply to the group, not automatically to each finding.

Individual finding

One specific detected issue. Track it separately, copy the group owner explicitly if needed, and save its assignment and status.

Marked complete

A manual decision that work is done, not proof that Atlas has verified the fix. Sync changes and compare a new completed Review with equivalent coverage.

Source version

The saved workspace snapshot used to connect findings, actions and reports to a particular sync.

1. Read the status or error message and follow its suggested action.
2. Confirm the correct workspace and data-freshness time shown at the top of the page.
3. Open the Companion and check whether it is connected and using the intended workspace.
4. Run a normal sync before requesting a Review if the source changed.
5. If the problem remains, contact Support and include the page, workspace and approximate time—never send passwords, API keys or source files.