groundatlas

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:

• No repo map — knowledge lives in people, Slack, stale docs, and whatever an agent guesses from a partial prompt.
• 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.

groundatlas@0.1.3 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

groundatlas@0.1.3 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/groundatlas@v0.1.3
  with:
    package-spec: groundatlas@0.1.3
    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.