The installed macOS app reading
samples/storefront β an online
store described by Markdown files in a folder. Meaning changes remain visible
in files and Git diffs for a person to inspect, correct, reject, or keep; the
feature inventory is the current behavior
contract.
This screen reads Atlas's own repository rather than the storefront
example, because measured import traffic needs a connected code folder.
Architecture stays separate from the map. It sets what a person reviewed beside
what an agent observed in the code, one role per row, with the difference in the
middle; every stroke states its own sentence, and the same profile always draws
the same picture. **Findings & history** keeps every inspection receipt. Pattern
names such as Feature-Sliced Design, Hexagonal or Clean Architecture are reviewed
declarations: conformance is derived from source evidence, never inferred from
folder names.
### 6. Review a relation beside its node
Atlas shows a directional preview on the map, then a compact review of the
source, type, target, reason, and exact frontmatter fields. **Confirm and write**
is the only point that changes the file.
### 7. Review the change, then record it
Whatever wrote β you, the map editor, the CLI, or an agent over MCP β lands here
first as a diff you read before it becomes history. Above is the change confirmed
in step 6: two frontmatter lines, still unsaved. Git is scoped to the vault, and
files outside the folder you picked are never touched.
The CLI writes the same two lines, says what it would do before touching a file,
and refuses a dependency nobody explained (`$ATLAS` is the entrypoint set in
[Running from source](#running-from-source)):
```console
$ node $ATLAS relate capabilities/order-cancel capabilities/refund dependencies ./storefront --dry-run \
--why "Cancelling a paid order has to give the money back, so cancellation cannot finish without refund processing."
capabilities/order-cancel --dependencies--> capabilities/refund
verdict matches_existing_schema Β· exists no
schema capability --dependencies--> capability
pattern count 53 Β· resolved 53 Β· external 0 Β· unresolved 0
recommendation safe_to_add Β· No exact or inverse edge found; capability --dependencies--> capability is an existing schema pattern.
dry-run would write dependencies on capabilities/order-cancel β capabilities/refund (no file changed)
```
Drop the `--why` and it stops rather than guessing one. An edge in a shape the
vault has never used comes back as `new_schema_pattern Β· review_new_schema`, so a
drifting agent is visible before it writes.
### 8. Keep it healthy
Insights opens on a Brief across concepts, wiki pages, guidance and agent activity.
Choose a subject to inspect its evidence. When Wiki or Guidance cannot yet show
measurements, distinct examples explain source-to-page checks or guidance across
code areas. Select an example to reveal the required setup and its Library or
Harness destination; examples never count as your data or create files.
The Concepts subject shows the folder's measurements and maintenance questions.
**Do next** is one row per kind of finding, and the counts add up to the title,
always. Where a missing back-link can be repaired from two facts already on disk,
one sheet names each file it would touch and nothing is written until you apply.
**Growth** replays the folder's own Git history week by week and stores nothing β
the numbers are recomputed from commits each time the tab opens. A folder with no
commits is told there is no history to show rather than drawn as a row of zeroes,
because a zero would claim the folder was empty.
### 9. Choose a project by its purpose
The project index stays compact: each row shows the project name, its explicitly
authored one-line description, a recent update, and direct routes to details and
the map. Composition and construction controls remain on the project detail page.
## What your agent gets
Ask which recorded dependencies deserve inspection for a change. Atlas follows
declared relationships; their presence alone does not establish human approval
or complete runtime impact:
```console
$ node $ATLAS blast-radius capabilities/mcp-tool-server docs/ontology --depth 2
capabilities/mcp-tool-server β blast radius (depth 2, incoming)
risk unknown Β· 1 node Β· 1 relation Β· 0 cross-domain
impact certainty unknown Β· declared 1 Β· rationale 0 Β· source-backed 0
Counts below follow declared depends_on only. Use reachability/subgraph for structure;
do not read unknown as low risk.
```
- **Focused context, not a repository dump.** A brief carries the project,
domain, evidence, impact boundary, first tools, and stop conditions; for a task
that only reads, `OATLAS_READ_ONLY=1` returns one compact batch.
- **Typed answers.** Paths and reachability explain structure, blast radius
follows declared dependencies only. No graph database, no hosted memory.
- **Writes that survive review.** Analysis is side-effect free by default,
destructive operations dry-run first, renames repair backlinks, and mtime guards
protect concurrent human edits.
The CLI carries the same authority for sessions that cannot attach a connector:
[MCP guide](https://github.com/wlsdks/ontology-atlas/blob/HEAD/mcp/README.md) Β· [CLI reference](https://github.com/wlsdks/ontology-atlas/blob/HEAD/cli/README.md).
## What we measured, and the mistake we found in it
A paired benchmark gives two sides the same source and question β one with a
prepared vault, one with nothing. The first run looked like a large win, 0.25
against 0.875, until re-scoring showed most of that gap was not a comparison: the
answer key mostly required Atlas's own concept names, which exist only inside the
vault. We had published, in part, a vocabulary test that only one side could sit.
| Subject | The part **both sides** could earn | The part **only Atlas** could earn | What we published before |
|---|---|---|---|
| Greenfield fixture | 0.75 β 1.00 | 0 β 0.83 | 0.25 β 0.875 |
| Brownfield fixture | 0.75 β 1.00 | 0 β 0.57 | 0.28 β 0.74 |
Each cell reads *without Atlas β with Atlas*. The control side named 100% of the
source files it should have named in every run, and the gap left over rests on one
word: the key wanted *excludes*, and an answer saying *"explicitly outside it"*
scored zero.
**So the honest status is that we have not yet measured a difference in answer
quality**, and Atlas was slower β a median of 17 and 33 seconds here, 28.2 and
51.1 in a separate run that carried one change through code, tests, commit, merge
and cleanup on both sides. What it does show is narrower: only the Atlas side
returned names you can look something up by. `capabilities/checkout` is an address
a person or an agent can resolve next session, in another tool, months from now;
"the checkout feature" is not. The re-scoring found a bug on our side too β the
Atlas run dropped its own concept names in a third of the harder cases. Blind
human grading is next; a stronger claim waits on unfamiliar repositories, that
grading, and the measured cost of maintaining a vault. Method and every raw
answer:
[paired findings](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/benchmark/FINDINGS-2026-08-31.md) Β·
[the correction](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/benchmark/FINDINGS-2026-08-31-metric-split.md) Β·
[change-flow run](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/benchmark/FINDINGS-2026-08-31-change-flow.md) Β·
[benchmark log](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/benchmark/README.md).
## Why not just use a notes tool
Local Markdown, git diffs, and MCP are table stakes; notes tools such as
[Basic Memory](https://github.com/basicmachines-co/basic-memory) already provide
them. Atlas adds a product ontology and a workbench where people and agents judge
the same facts. If you only need an agent to remember conversations, a notes tool
is lighter.
| | Notes with MCP | Hosted graph memory | Ontology Atlas |
|---|---|---|---|
| Store | Markdown you own | Vendor database | Markdown you own |
| Structure | Freeform notes and links | Vendor-defined types | Project β domain β capability β element, documents, typed relations |
| Graph questions | Note traversal | Graph engine | Blast radius, reachability, cycles, paths, centrality, health |
| Evidence from code | Hand-authored | Corpus ingestion | Bounded read-only proposals; nothing lands until approval |
| Human surface | Notes app | Vendor console | Local Map, Architecture, Library, Insights, Projects, Agents, MCP, History |
The argument and its sources are in [Foundations](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/FOUNDATIONS.md).
---
## A vault is just files
Everything below is the contract rather than the tour: how the folder is stored,
what Atlas will never do, and how to run and verify it from source.
One Markdown file is one node. Frontmatter is the machine-readable record; the
body is the explanation a person judges.
```yaml
---
uid: 71890f3e-7b5d-4c0a-8f14-123456789abc # permanent identity, kept through renames
slug: capabilities/token-issue
kind: capability
title: Token issue
domain: domains/auth
path: src/auth/token-service.ts # a path β code evidence
elements:
- elements/jwt-signer # a slug β an implementation-role node
dependencies:
- capabilities/session-refresh # a slug β another node
---
Issues access and refresh tokens for authenticated users.
```
**A path points at code; a slug points at a node.** Mixing them is the most
common first mistake, and `node $ATLAS validate` reports it as a dangling
reference. `uid` is the permanent identity, minted once and kept through a
rename; the slug is the readable current address; a source location belongs in
`path:`, never in a slug. Relations sit on the declaring file the same way, one
frontmatter line from which Atlas derives the edge and its backlink β
`dependencies` directed, `relates` symmetric, so the map never turns similarity
into causality.
The reading spine is small on purpose β `project β domain β capability β
element`, with `document` describing concepts anywhere on it β and an artifact
earns a node only when it helps someone understand a capability, trace impact, or
run the right proof. Curated, not exhaustive. There is **no cap on how many nodes
a vault holds**: a wide hub is a review signal, not a limit, an analyzer's packet
bound keeps one proposal readable and is never a graph bound, a bridge node has
to earn its layer, and an external field trial's ontology is never merged into
this product's vault. Each rule's authority is the
[quality authority map](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ONTOLOGY-QUALITY.md), and the practical test is
[what becomes a node?](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/guide/what-becomes-a-node.md).
Three kinds of file share the folder, and only one is the graph:
| Kind | Where | What makes it that | In the graph? |
|---|---|---|---|
| Raw source | `sources/**` | any format, kept exactly as it arrived | no β only `.md` reaches the parser |
| Wiki page | `wiki/**.md` | Markdown with **no `kind:`** | no β `kind:` is what makes a node |
| Ontology node | anywhere else | `kind:` in frontmatter | yes, and only these |
Inside `wiki/`, `_template.md` is the shape every page is held to and `_log.md`
records each compile or check; `_`-prefixed files are furniture, not pages. The
folder is always named `atlas/` ([step 1](#1-open-a-folder)), fixed so a teammate
can say it and an agent's config can point at it without guessing, and
`init --documents` writes the same folder without the node starters for people who
have documents and no code. Full contracts: the
[relations guide](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/guide/relations.md) and the
[vault specification](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ONTOLOGY-ATLAS-SPEC.md).
## Local-first, by construction
- **Your disk is the database.** Frontmatter is the graph, confirmed writes go
back to the folder you picked, and Git is the history. There is no other store.
- **No Atlas backend, account, or telemetry.** The web app is a static export; the
desktop app checks the public updater manifest once a day and uploads no vault
content. A connected coding agent talks to its own provider only when you ask;
a model key or the optional Jev check sends only what you press send on, and
each transfer is a line in the folder's `.ontology-atlas/llm-audit.jsonl`.
- **Two ways in, one folder.** The hosted web app can open a local folder through
the File System Access API. The desktop app uses a Tauri bridge to your selected
folder and keeps it open as a workspace.
- **The Tauri macOS shell is a shell, not a silo.** MCP and CLI still read the
selected folder directly, and the bundled server is a file your agent launches
itself, so it keeps working when the app is closed.
## What this is not
- **Not a general-purpose ontology editor.** The ontology describes a codebase; a
business concept belongs there when it explains what that codebase builds, why a
boundary exists, or what a change can affect. The Library takes general sources
and wiki pages with no code nodes at all.
- **Not a code index, and not an IDE.** Grep, language servers, AST indexes and
CodeGraph answer where a symbol lives and what calls it; Atlas replaces none of
them and answers why that artifact matters, which capability it serves, and what
to verify before changing it. An IDE for codebase *meaning* is the useful
analogy, and it stops there: Atlas does not edit, build, run, or debug code.
- **No automatic acceptance of generated knowledge.** Saving a wiki page or answer
preserves it for review; it does not make its claims true or promote it into
accepted ontology meaning.
- **Not an RDF, OWL, SKOS, or SHACL implementation.** The export is a bounded
graph shape; the vault is not an RDF serialization, the validator is not a SHACL
processor, and the query engine is not a reasoner. A persisted relation is a
declared claim, never an entailment; an absent one is a visible gap, never a
negative fact. [Specification Β§5.2](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ONTOLOGY-ATLAS-SPEC.md#52-standards-boundary).
- **Not a service, and not on npm.** No backend, account, telemetry, daemon, or
port; `npx ontology-atlas` is a 404 and not a future feature. The MCP server
still reaches the ecosystem's registries as a release bundle or a container
image, neither of which is a package registry.
- **Not extensible by running other people's code.** There will be no third-party
plugin runtime. Extension happens through MCP tools, agent skills, and files in
your own vault β things a `git diff` shows you before they run.
- **Still evolving.** The [download page](https://ontologyatlas.com/en/download/)
records current release availability and platform status.
## Running from source
Linux and every other platform without a packaged build run the browser app, or
the CLI and MCP server from a source checkout: Node.js 24 and pnpm, one clone
outside the project you are describing, then `init` inside your own repository
and `mcp-verify` to prove the live connection. The exact commands, the two
required installs, and the reason `init` refuses to run inside the Atlas clone
are in [set up from a source checkout](https://github.com/wlsdks/ontology-atlas/blob/HEAD/cli/README.md#set-up-from-a-source-checkout).
## Documentation
**Use it:** [hosted guide](https://ontologyatlas.com/en/guide/) Β·
[features](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/FEATURES.md) Β· [MCP setup](https://github.com/wlsdks/ontology-atlas/blob/HEAD/mcp/README.md) Β·
[CLI reference](https://github.com/wlsdks/ontology-atlas/blob/HEAD/cli/README.md)
**Model a vault:** [what becomes a node?](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/guide/what-becomes-a-node.md) Β·
[relations](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/guide/relations.md) Β·
[v2 specification](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ONTOLOGY-ATLAS-SPEC.md) Β·
[quality authority map](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ONTOLOGY-QUALITY.md)
**Understand it:** [product direction](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/PRODUCT-DIRECTION.md) Β·
[foundations](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/FOUNDATIONS.md) Β· [architecture](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/ARCHITECTURE.md) Β·
[security](https://github.com/wlsdks/ontology-atlas/blob/HEAD/SECURITY.md) Β· [decisions](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/DECISIONS.md)
## Contributing
Issues and pull requests are welcome, and the most valuable report today is
pointing Atlas at a real repository and showing where the proposed meaning, the
agent handoff, or the validation falls short.
Read [CONTRIBUTING.md](https://github.com/wlsdks/ontology-atlas/blob/HEAD/CONTRIBUTING.md) first β external pull requests come from
forks, and that is a security boundary rather than a formality. Inside this
repository [AGENTS.md](https://github.com/wlsdks/ontology-atlas/blob/HEAD/AGENTS.md) is canonical for people and agents alike, and
product decisions route through `pnpm po:route -- --help` from change facts
rather than a self-declared risk.
Start with `pnpm checks:changed -- --run`: it picks the focused gates for the
files you changed, runs every recommendation, and stops at the first failure.
Open pull requests as drafts and land them with `pnpm pr:land `, which
queues them for a landing train: up to 20 queued pull requests merge behind one
CI run, and a red train is bisected
([details](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/DEVELOPMENT-CHECKS.md)). A pull request already green on its own
head and disjoint from `main` merges at once on the fast path. Branches that must
be resolved together land through `/land-bundle` as one integration branch.
| Command | What it answers |
|---|---|
| `pnpm agents:check` | Each harness's instruction integrity; independent Codex and Claude files need not match |
| `pnpm backlog` Β· `pnpm backlog:check` | Current task records and concurrent-state conflicts; append a UUID record per worktree observation ([guide](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/BACKLOG.md)) |
| `pnpm bundle:plan` Β· `pnpm bundle:prune` | Land several branches as one: plan the merge (which carry work, shared files, trial conflicts) and afterwards prune the component branches main provably contains. See `/land-bundle` |
| `pnpm checks:changed` | Which gates this change actually needs |
| `pnpm conflicts:scan` | Which open pull requests (and `-- --match=` local branches) change the same files as this branch, and whether a trial merge with each conflicts; read-only, one `gh` call |
| `pnpm decisions:find ` Β· `pnpm decisions:check` | The decision record to cite or overturn, and whether this change owes one |
| `pnpm doc:new -- --type= --area= --slug=` | A new living document from its template in `docs/.templates/`, at the path its kind decides |
| `pnpm docs:check` | Docs gates, including `pnpm docs:language`, `pnpm source:language`, `pnpm changelog:check`, `pnpm dev-checks:check`, `pnpm docs:meta` |
| `pnpm docs:meta` Β· `pnpm doc:history -- ` | Whether every living document carries its kind, status and area with pointers that resolve; one document's commits across moves, which is its version |
| `pnpm docs:move` | Moves the documents listed in `docs/.moved.json` and rewrites every reference; rerun it after merging main into an older branch (`-- --check` only reports) |
| `pnpm e2e:durations -- ` | Rewrites the per-file weights that balance the browser shards from downloaded `playwright-timings-*` reports |
| `pnpm e2e:sleeps:check` | A change may not add a fixed `waitForTimeout` to an e2e spec unless a `// measurement window:` note says why |
| `pnpm gates:yield -- --runs=200` | Which CI checks ever failed, per distinct run, from the lane reports `checks.yml` uploads (cached in `~/.cache/atlas-gate-yield`); a row with 50+ runs, no failed run and 60+ days of history reads `no CI failure`, a check to examine rather than delete, since pre-push and `pnpm checks:changed` catches are not in this data. Reports start with the change that added them |
| `pnpm gateway:capture -- --base-url=` | Re-shoots the six app screens the download page shows, Korean and English (`public/gateway/..png`), from a served `pnpm build`, against this repository's own ontology |
| `pnpm knip` | Dead files, exports and types across every scope |
| `pnpm lessons` Β· `pnpm lessons:check` | Shared harness lessons that are open or verified but not yet fixed; record and review them with `/harness-retro` ([records guide](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/records/README.md#harness-lessons)) |
| `pnpm messages:build` Β· `pnpm messages:check` Β· `pnpm messages:adopt` | Compose the ignored `messages/.json` from one file per namespace (`messages//.json`), prove it current, and carry a pre-split branch's catalogue edits onto the parts while merging main |
| `pnpm perf:mcp:memory` Β· `pnpm perf:mcp:memory:check` | Whether the MCP server keeps memory it should release: heap after two forced collections across 50 repeated calls per tool and across moved Git HEADs, on a generated vault; about a minute, kept out of pre-push |
| `pnpm pr:ci ` | Fire CI on a draft now, so a green, disjoint change can take the fast path |
| `pnpm pr:land --plan ` Β· `pnpm pr:land --conduct` | Dry-run what a landing would do without writing to GitHub, and run trains until the queue is empty |
| `pnpm pr:land ` Β· `pnpm pr:queue` | Queue a pull request for the landing train (or merge it on the fast path), and show the queue and the train in flight |
| `pnpm typecheck` | Types across every file, with Next's generated route and page types, so the browser build need not check them again |
Rows stay sorted by command, and the reference's entries by area, so two
branches that each add one land on different lines; `pnpm dev-checks:check`
names the line to move and `-- --fix` sorts both.
[Development checks](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/DEVELOPMENT-CHECKS.md) is the full gate reference, one
entry per area; [map testability](https://github.com/wlsdks/ontology-atlas/blob/HEAD/docs/engineering/map-testability.md) owns canvas
performance, readability, contrast, and instrumentation.
## License
[MIT](https://github.com/wlsdks/ontology-atlas/blob/HEAD/LICENSE)
