GroundAtlas

The source-grounded repository control plane for humans and agents.

GroundAtlas turns a repository into a deterministic, auditable map of where truth lives before a human or AI agent changes code. It is deliberately not a wiki, not an AI memory store, and not a second source of truth. It is the layer underneath those experiences: the map, truth routing, freshness gate, and change-control surface that keeps generated context honest.

OpenWiki can write a wiki. GroundAtlas tells you which source owns the truth, whether the generated map is fresh, and what an agent must inspect before it touches production code.

# Public npm package:
npm install -g groundatlas

# From source:
bun install
bun run build
node dist/cli.js init
node dist/cli.js manifest project.manifest.json --json
node dist/cli.js update
node dist/cli.js audit
node dist/cli.js explain "validation commands"
node dist/cli.js impact --since main
node dist/cli.js fleet . --require-atlas

The package exposes both groundatlas and the short daily-driver command ga. It also exports a typed library API from groundatlas for tools that want to consume the scanner, audit, renderer, explain, impact, and manifest-validation primitives directly. The groundatlas/manifest subpath is a read-only bridge toward a future standalone vendor-neutral manifest library.

Why this exists

Modern teams have two bad defaults:

1. No repo map — knowledge lives in people, Slack, stale docs, and whatever an agent guesses from a partial prompt.
2. Generated wiki as truth — prose looks useful, then quietly becomes a competing authority that drifts away from code, tests, schemas, ADRs, and release evidence.

GroundAtlas takes the third path: generated context is useful, but canonical truth stays in the files that own it. Delete .groundatlas/ and no truth should be lost.

Open-source promise

GroundAtlas is built to be useful without buying into any vendor, model provider, agent runtime, or company doctrine:

• core scan/audit path is deterministic;
• no network or model key is required for local/CI use;
• generated output is deletable and non-authoritative;
• project identity can live in a neutral project.manifest.json;
• tool-specific files such as CLAUDE.md, Cursor rules, or Copilot instructions are optional adapters, not requirements;
• future AI features must sit on top of source-owned citations, not replace them.

Started by SylphxAI, maintained as an open-source primitive: the best way to show engineering quality is to make the useful part general enough for everyone.

Market position

GroundAtlas is the source-grounded repository control plane.

It is not competing to be the prettiest wiki. It is the trust layer underneath wikis, agents, docs sites, code search, and CI:

| Category | What it gives you | What GroundAtlas adds | | --- | --- | --- | | No tool | No new dependency | GroundAtlas removes tribal onboarding and agent guesswork. | | Generated wiki | Fast prose | GroundAtlas keeps generated context subordinate to source truth. | | Code search | Find text fast | GroundAtlas explains which files own which facts. | | Docs site | Polished publishing | GroundAtlas audits repository truth and freshness before publishing. | | Agent runtime | Automation | GroundAtlas gives agents a safe read order and non-SSOT boundary. |

Value by audience

| Audience | Value | | --- | --- | | Users/new joiners | Start from one map and know what to read first. | | Maintainers | Catch stale generated context and missing truth homes in CI. | | Developer experience teams | Standardize repository onboarding without forcing a vendor stack. | | AI agents | Use JSON/Markdown maps to find canonical files before editing. | | Open-source communities | Share a small, inspectable convention instead of a hosted black box. |

Project control file

For multi-project use, one neutral control file per project is the cleanest default:

project.manifest.json

It records stable project identity, truth-home pointers, public surfaces, validation commands, and adoption status. Those manifest-declared commands are used as the validation-command source for non-package repositories, so Python, docs-only, infrastructure, and policy repos do not need a fake package.json to be dogfooded. Only the selected highest-priority valid neutral manifest contributes commands. GroundAtlas also recognizes groundatlas.project.json, .project/manifest.json, and ecosystem adapters such as .doctrine/project.json, but those adapters are not the public default. ga fleet validates neutral manifests, selects the highest-priority neutral manifest when present, and reports ecosystem files under manifestAdapters so malformed project metadata cannot be mistaken for adopted dogfooding.

See:

• Project Control File Guide
• Project manifest schema — also exported as groundatlas/schemas/project.manifest.schema.json
• Example manifest
• GitHub Action gate
• Multi-project Control Plane

Guides

• User Guide
• Developer Experience Guide
• Agent Guide
• Open-source Strategy
• Control-plane Business Case
• Static landing page
• Published website

60-second demo

# First run in a repository
ga init
# GroundAtlas initialized .groundatlas/
# - .groundatlas/atlas.json
# - .groundatlas/README.md
# - .groundatlas/source-map.md
# - .groundatlas/change-guide.md

ga audit
# GroundAtlas audit passed.

ga explain "validation commands" --json
# [{ "path": "project.manifest.json", ... }] or [{ "path": "package.json", ... }]

ga impact --since main
# | Status | Changed path | Matched atlas sources |

# If a canonical source changes but the map was not regenerated:
ga audit
# - error `stale-atlas`: .groundatlas/atlas.json does not match the current repository scan.
#   Run ga update and commit or regenerate the output according to repo policy.

The key behavior: GroundAtlas fails stale generated context instead of letting a pretty map silently drift away from source truth.

Current status

Product-ready initial CLI/library slice:

• deterministic scanner and atlas JSON;
• vendor-neutral project.manifest.json control file schema and example;
• dependency-free static landing page under docs/website/;
• reusable GitHub Action gate under action.yml with manifest/fleet JSON report artifacts;
• ga init, ga update, ga scan, ga audit, ga explain, ga impact;
• standalone ga manifest validation for vendor-neutral project manifests and recognized ecosystem adapters;
• ga fleet / ga inventory / ga score for adopted/warning/blocked dogfooding reports and neutral manifest validation across one or more repositories;
• explicit fact-scoped SSOT model and repository orientation route;
• generated Markdown maps with non-SSOT banners;
• freshness audit using file hashes, not just generated prose;
• secret-path skipping and narrow write boundary;
• typed library exports;
• tests, CI, dogfooding, package dry-run, packed-package smoke, and composite-action smoke against the packed tarball;
• release workflow with npm provenance, registry readback, post-publish dogfood, and JSON evidence artifacts.

[email protected] is published on npm and read back from the registry. The remaining release-infrastructure gap is to migrate the bounded NPM_TOKEN fallback to npm trusted publishing/OIDC before treating it as permanent.

What GroundAtlas is

• A CLI-first knowledge control plane for repositories.
• A deterministic read-model over source code, schemas, tests, specs, ADRs, manifests, workflows, docs, runbooks, and package metadata.
• A fact-scoped SSOT router: it tells you which file owns which kind of truth.
• A CI-friendly audit gate for generated map integrity and freshness.
• A safe bootstrap for future agent workflows: every map points back to the files that own the truth.

What GroundAtlas is not

• It is not an autonomous code writer.
• It is not an LLM memory store.
• It is not a hosted docs site.
• It is not the canonical source for architecture, API contracts, project identity, release status, or implementation behavior.
• It does not read secrets or .env files.
• It does not mutate AGENTS.md, tool-specific agent adapters such as CLAUDE.md, source files, schemas, specs, tests, ADRs, workflows, package manifests, or machine project manifests.

If deleting .groundatlas/ would remove important project truth, the project is using GroundAtlas incorrectly.

Required truth files for serious adoption

GroundAtlas works best when a repository exposes real truth homes instead of asking generated docs to invent authority.

| Surface | Required for commercial-grade repos | Owns | | --- | --- | --- | | AGENTS.md | Preferred | Tool-neutral agent adapter and repo hazards. Tool-specific adapters such as CLAUDE.md, .cursor/rules, or .github/copilot-instructions.md are detected when present but are not required. | | PROJECT.md | Yes | Human project identity, lifecycle, boundary, public surfaces, delivery proof. | | project.manifest.json, groundatlas.project.json, .project/manifest.json, or recognized ecosystem adapter | Yes for fleet/commercial governance | Machine-readable project manifest and adoption state. .doctrine/project.json is the SylphxAI Doctrine adapter, not the public default. | | README.md | Yes | Public start-here promise and install/use contract. | | docs/specs/**, DESIGN.md, or design.md | Yes | Product intent, operating contracts, acceptance criteria. | | docs/adr/** | Yes once durable decisions exist | Architecture/product/security/commercial decisions. | | package.json, schemas, migrations, exported types | When applicable | Commands, package/API/data contracts, machine surfaces. | | src/**, lib/** | When applicable | Implemented behavior. | | test/**, tests/**, evals | Yes | Behavior proof and regressions. | | .github/workflows/** | Yes | CI and delivery gates. | | docs/runbooks/**, SECURITY.md, CHANGELOG.md | Yes for public/customer-facing repos | Operations, security reporting, release/support status. |

GroundAtlas reads these homes, classifies them, and generates a map. It does not replace them.

See Source Truth Model, Fleet Adoption Contract, Project Control File Guide, and Multi-project Control Plane.

SSOT rule

GroundAtlas uses fact-scoped SSOT:

• project identity lives in PROJECT.md plus a machine-readable project manifest such as project.manifest.json, groundatlas.project.json, .project/manifest.json, or a recognized adapter such as .doctrine/project.json;
• durable decisions live in ADRs;
• product intent lives in specs/design docs;
• contracts live in schemas, exported types, package manifests, and migrations;
• behavior lives in source code;
• behavior proof lives in tests/evals;
• delivery proof lives in workflows, release artifacts, registry readback, changelog, and runbooks;
• generated .groundatlas/** output is navigation only.

Conflict rule: identify the disputed fact, fix its owning source, run validation, then run ga update && ga audit. Never patch generated output to hide drift.

How it works

flowchart LR
  A["Repo truth homes"] --> B["Safe scanner"]
  B --> C["Source classifier"]
  C --> D["Atlas JSON with truth model"]
  D --> E["Markdown maps"]
  D --> F["Freshness + non-SSOT audit"]
  D --> G["Explain / impact / future query"]

GroundAtlas reads repository metadata and non-secret file hashes through a safe scanner, classifies files by truth-home type, builds an atlas JSON model, renders human docs, and audits the result. Generated maps always point back to canonical source files.

See Operating Model.

Commands

| Command | Purpose | | --- | --- | | ga init | Create groundatlas.config.json and generated maps under .groundatlas/. | | ga update | Refresh generated maps from current repository sources. | | ga scan --json | Inspect sources without writing files. | | ga audit | Verify generated maps, non-SSOT boundary, schema version, error risks, and freshness. | | ga explain <query> | Find source-grounded files related to a query. | | ga impact --since <ref> | Map git diff paths to known atlas sources. | | ga manifest [path] | Validate a vendor-neutral project manifest or recognized adapter without writing generated maps. | | ga fleet [paths...] | Report adopted/warning/blocked dogfooding status and validate neutral project manifests across one or more repositories. |

Aliases: ingest → scan; validate → audit; query → explain; manifest validate → manifest; inventory / score → fleet; map / export → update.

Generated output

ga init / ga update creates:

.groundatlas/
  atlas.json        # machine-readable source map and truth model
  README.md         # human/agent entry point
  source-map.md     # canonical and supporting sources
  change-guide.md   # validation and handoff guide

Every generated Markdown file starts with a banner that says it is generated and not a source of truth.

Dogfooding

GroundAtlas dogfoods itself in bun run check: it typechecks, tests, lints, validates the project manifest, builds the CLI, runs the CLI against this repository, audits generated output freshness/non-SSOT policy, verifies npm package dry-run, checks its own ga fleet . --require-atlas adoption report, validates its own project.manifest.json through the standalone manifest command, smoke-runs the reusable GitHub Action against a packed tarball and verifies manifest/fleet JSON reports, and smoke-installs the packed tarball. The packed-package smoke imports both groundatlas and groundatlas/manifest, then runs the installed CLI against a fixture containing both project.manifest.json and .doctrine/project.json, proving the neutral manifest is selected and the Doctrine file stays an adapter.

CI also runs a packed-tarball external dogfood pilot against a clean public checkout and uploads groundatlas-external-dogfood as external dogfood evidence. That report must keep claimBoundary: "pre-npm-pilot-only" and groundatlasPackageSource: "packed-local-tarball" until npm publish plus registry readback exists; it is confidence evidence, not fleet package adoption.

See Dogfooding Contract.

Competitive position

| Choice | What you get | What you risk | | --- | --- | --- | | No tool | No new dependency. | Slow onboarding, tribal knowledge, stale docs, agent hallucination, weak impact analysis. | | GroundAtlas | Deterministic source map, truth routing, freshness audit, CLI/library surface, no model key required. | Less magical prose today; citation graph and optional AI adapters are still build-forward work. | | OpenWiki | AI-generated/maintained openwiki/ docs and interactive documentation CLI. | Generated docs can become another truth surface; provider/model configuration is central. | | OpenClaw | Personal AI assistant/gateway across channels, tools, apps, and skills. | Different category; powerful assistant UX but not a repo SSOT/read-model gate by itself. | | Repo packers / code search / docs sites | Useful context snapshots, search, or polished publishing. | Usually not a project-local truth hierarchy with generated-map freshness gates. |

GroundAtlas is currently ahead on SSOT discipline, deterministic/no-key baseline, write-boundary safety, and CI-gate posture. It is intentionally behind LLM-first wiki tools on prose generation and provider integrations until the source-grounded substrate is trustworthy.

See Competitive Positioning.

Roadmap (not yet shipped)

Current shipped behavior is listed in Current status. The next star-worthy slices are deliberately source-grounded rather than AI-magic-first:

• first npm publication with provenance and registry readback;
• richer HTML output and hosted docs/site publishing;
• future extraction of the manifest validator subpath into a standalone vendor-neutral control-plane library once the package/repo name is decided;
• claim/citation graph with exact source anchors;
• query answers that cite canonical files, not generated memory;
• deeper dependency-aware PR impact analysis;
• PR comment/report mode for CI;
• fleet dashboard from neutral project.manifest.json files;
• optional AI adapters only after deterministic citation gates are trustworthy.

See Final Product Goal.

Permission model

GroundAtlas is intentionally narrow:

• Reads repository file names, non-secret file metadata, and SHA-256 hashes of non-secret files for freshness detection.
• Runs read-only git commands (status, rev-parse, remote, diff).
• Writes only:
  • groundatlas.config.json during init;
  • files inside the configured output directory, default .groundatlas/.
• Uses no network, no provider API, no LangSmith/tracing, and no hidden remote state in the deterministic scan/audit path.

Development

bun install
bun run check

bun run check runs typecheck, tests, Biome, build, CLI help, local GroundAtlas update/audit, npm pack dry-run, and clean installed-package smoke from the packed tarball.

Library publication

[email protected] is published on npm as the public package for the CLI, library API, GitHub Action package spec, manifest bridge, and exported schema. bun run release:readback installs the immutable registry package and runs the same installed-package fleet smoke. Package-based downstream pilots use GROUNDATLAS_DOGFOOD_PACKAGE_SPEC=groundatlas@<version> bun run dogfood:external against copied repositories.

On a real v*.*.* tag release, the workflow stores groundatlas-release-evidence with registry readback JSON and post-publish npm-registry dogfood JSON. Workflow dispatch remains preflight-only and cannot be used to claim package publication.

The first successful publish used the organization NPM_TOKEN as a bounded bootstrap fallback. Future release hardening should migrate to npm trusted publishing/OIDC; do not republish an existing npm version.

See Publishing Runbook.

GitHub Action gate

GroundAtlas includes a reusable composite action in action.yml. After npm publish/readback and a version tag, downstream repositories can run:

- id: groundatlas
  uses: SylphxAI/[email protected]
  with:
    package-spec: [email protected]
    require-atlas: "true"
    strict: "true"
- uses: actions/upload-artifact@v5
  if: always()
  with:
    name: groundatlas-reports
    path: |
      ${{ steps.groundatlas.outputs.manifest-report-path }}
      ${{ steps.groundatlas.outputs.fleet-report-path }}
      ${{ steps.groundatlas.outputs.fleet-markdown-report-path }}

This proves a target repository is using the released package/action. It still does not make .groundatlas/** truth, and it does not claim organization-wide fleet adoption until each target repository adds its own CI gate. The action also appends the Markdown scorecard to GITHUB_STEP_SUMMARY when GitHub provides it, so humans and agents can review the same gate output without treating the scorecard as SSOT.