![\"Ontology](\"public/brand/lockup-dark@2x.png\")
\n \n \n
\n Understand what your codebase builds, why it is structured that way,
\n and what a change will affect.\n
\n One codebase ontology in repository Markdown, maintained by people and AI agents.\n
\n\n\n Download for macOS\n ·\n Windows x64 beta unsigned\n ·\n Live demo\n ·\n Guide\n ·\n Status\n
\n\n\n ![\"Listed](\"https://mcpservers.org/badge.svg\"){kind=icon}
\n
\n \n
\n The installed macOS app reading\n samples/storefront — an online\n store written as nothing but Markdown files in a folder. Every write, human or\n agent, lands as Markdown a person reviews in a Git diff; the\n feature inventory is the current behavior\n contract.\n
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-5e6ad2.svg\"){kind=icon}
\n ![\"MCP](\"https://img.shields.io/badge/MCP-runtime_inventory-5e6ad2.svg\"){kind=icon}
\n ![\"Local](\"https://img.shields.io/badge/CLI-local_tools-5e6ad2.svg\"){kind=icon}
\n ![\"Local-first\"](\"https://img.shields.io/badge/storage-local--first-17181f.svg\"){kind=icon}
\n
\n This screen reads Atlas's own repository rather than the storefront\n example, because measured import traffic needs a connected code folder.\n
\n\nArchitecture stays separate from the map. It sets what a person reviewed beside\nwhat an agent observed in the code, one role per row, with the difference in the\nmiddle; every stroke states its own sentence, and the same profile always draws\nthe same picture. **Findings & history** keeps every inspection receipt. Pattern\nnames such as Feature-Sliced Design, Hexagonal or Clean Architecture are reviewed\ndeclarations: conformance is derived from source evidence, never inferred from\nfolder names.\n\n### 6. Review a relation beside its node\n\n\n\nAtlas shows a directional preview on the map, then a compact review of the\nsource, type, target, reason, and exact frontmatter fields. **Confirm and write**\nis the only point that changes the file.\n\n### 7. Review the change, then record it\n\n\n\nWhatever wrote — you, the map editor, the CLI, or an agent over MCP — lands here\nfirst as a diff you read before it becomes history. Above is the change confirmed\nin step 6: two frontmatter lines, still unsaved. Git is scoped to the vault, and\nfiles outside the folder you picked are never touched.\n\nThe CLI writes the same two lines, says what it would do before touching a file,\nand refuses a dependency nobody explained (`$ATLAS` is the entrypoint set in\n[Running from source](#running-from-source)):\n\n```console\n$ node $ATLAS relate capabilities/order-cancel capabilities/refund dependencies ./storefront --dry-run \\\n --why \"Cancelling a paid order has to give the money back, so cancellation cannot finish without refund processing.\"\n\ncapabilities/order-cancel --dependencies--> capabilities/refund\n verdict matches_existing_schema · exists no\n schema capability --dependencies--> capability\n pattern count 53 · resolved 53 · external 0 · unresolved 0\n recommendation safe_to_add · No exact or inverse edge found; capability --dependencies--> capability is an existing schema pattern.\n\ndry-run would write dependencies on capabilities/order-cancel → capabilities/refund (no file changed)\n```\n\nDrop the `--why` and it stops rather than guessing one. An edge in a shape the\nvault has never used comes back as `new_schema_pattern · review_new_schema`, so a\ndrifting agent is visible before it writes.\n\n### 8. Keep it healthy\n\n\n\nInsights opens on four measurements: concepts by kind, relations by type, the\nfolder's health in words rather than a score, and the last four weeks of change.\n**Do next** is one row per kind of finding, and the counts add up to the title,\nalways. Where a missing back-link can be repaired from two facts already on disk,\none sheet names each file it would touch and nothing is written until you apply.\n\n**Growth** replays the folder's own Git history week by week and stores nothing —\nthe numbers are recomputed from commits each time the tab opens. A folder with no\ncommits is told there is no history to show rather than drawn as a row of zeroes,\nbecause a zero would claim the folder was empty.\n\n### 9. See the shape of the whole project\n\n\n\nNothing here is maintained by hand. Frontmatter has no `project:` key — the\nruntime walks the containment graph from each `project` root and derives coverage\nfrom how the documents link to each other.\n\n## What your agent gets\n\nAsk *what breaks if I change this?* and Atlas follows only approved dependency\ndeclarations. It does not turn folder structure into causal confidence:\n\n```console\n$ node $ATLAS blast-radius capabilities/mcp-server docs/ontology --depth 2\ncapabilities/mcp-server — blast radius (depth 2, incoming)\n risk unknown · 1 node · 1 relation · 0 cross-domain\n\nimpact certainty unknown · declared 1 · rationale 0 · source-backed 0\nCounts below follow declared depends_on only. Use reachability/subgraph for structure;\ndo not read unknown as low risk.\n```\n\n- **Focused context, not a repository dump.** A brief carries the project,\n domain, evidence, impact boundary, first tools, and stop conditions; for a task\n that only reads, `OATLAS_READ_ONLY=1` returns one compact batch.\n- **Typed answers.** Paths and reachability explain structure, blast radius\n follows declared dependencies only. No graph database, no hosted memory.\n- **Writes that survive review.** Analysis is side-effect free by default,\n destructive operations dry-run first, renames repair backlinks, and mtime guards\n protect concurrent human edits.\n\nThe CLI carries the same authority for sessions that cannot attach a connector:\n[MCP guide](mcp/README.md) · [CLI reference](cli/README.md).\n\n## What we measured, and the mistake we found in it\n\nA paired benchmark gives two sides the same source and question — one with a\nprepared vault, one with nothing. The first run looked like a large win, 0.25\nagainst 0.875, until re-scoring showed most of that gap was not a comparison: the\nanswer key mostly required Atlas's own concept names, which exist only inside the\nvault. We had published, in part, a vocabulary test that only one side could sit.\n\n| Subject | The part **both sides** could earn | The part **only Atlas** could earn | What we published before |\n|---|---|---|---|\n| Greenfield fixture | 0.75 → 1.00 | 0 → 0.83 | 0.25 → 0.875 |\n| Brownfield fixture | 0.75 → 1.00 | 0 → 0.57 | 0.28 → 0.74 |\n\nEach cell reads *without Atlas → with Atlas*. The control side named 100% of the\nsource files it should have named in every run, and the gap left over rests on one\nword: the key wanted *excludes*, and an answer saying *\"explicitly outside it\"*\nscored zero.\n\n**So the honest status is that we have not yet measured a difference in answer\nquality**, and Atlas was slower — a median of 17 and 33 seconds here, 28.2 and\n51.1 in a separate run that carried one change through code, tests, commit, merge\nand cleanup on both sides. What it does show is narrower: only the Atlas side\nreturned names you can look something up by. `capabilities/checkout` is an address\na person or an agent can resolve next session, in another tool, months from now;\n\"the checkout feature\" is not. The re-scoring found a bug on our side too — the\nAtlas run dropped its own concept names in a third of the harder cases. Blind\nhuman grading is next; a stronger claim waits on unfamiliar repositories, that\ngrading, and the measured cost of maintaining a vault. Method and every raw\nanswer:\n[paired findings](docs/benchmark/FINDINGS-2026-08-31.md) ·\n[the correction](docs/benchmark/FINDINGS-2026-08-31-metric-split.md) ·\n[change-flow run](docs/benchmark/FINDINGS-2026-08-31-change-flow.md) ·\n[benchmark log](docs/benchmark/README.md).\n\n## Why not just use a notes tool\n\nLocal Markdown, git diffs, and MCP are table stakes; notes tools such as\n[Basic Memory](https://github.com/basicmachines-co/basic-memory) already provide\nthem. Atlas adds a product ontology and a workbench where people and agents judge\nthe same facts. If you only need an agent to remember conversations, a notes tool\nis lighter.\n\n| | Notes with MCP | Hosted graph memory | Ontology Atlas |\n|---|---|---|---|\n| Store | Markdown you own | Vendor database | Markdown you own |\n| Structure | Freeform notes and links | Vendor-defined types | Project → domain → capability → element, documents, typed relations |\n| Graph questions | Note traversal | Graph engine | Blast radius, reachability, cycles, paths, centrality, health |\n| Evidence from code | Hand-authored | Corpus ingestion | Bounded read-only proposals; nothing lands until approval |\n| Human surface | Notes app | Vendor console | Local Map, Architecture, Docs, Library, Insights, Projects, Agents, MCP, History |\n\nThe argument and its sources are in [Foundations](docs/FOUNDATIONS.md).\n\n---\n\n## A vault is just files\n\nEverything below is the contract rather than the tour: how the folder is stored,\nwhat Atlas will never do, and how to run and verify it from source.\n\nOne Markdown file is one node. Frontmatter is the machine-readable record; the\nbody is the explanation a person judges.\n\n```yaml\n---\nuid: 71890f3e-7b5d-4c0a-8f14-123456789abc # permanent identity, kept through renames\nslug: capabilities/token-issue\nkind: capability\ntitle: Token issue\ndomain: domains/auth\npath: src/auth/token-service.ts # a path — code evidence\nelements:\n - elements/jwt-signer # a slug — an implementation-role node\ndependencies:\n - capabilities/session-refresh # a slug — another node\n---\n\nIssues access and refresh tokens for authenticated users.\n```\n\n**A path points at code; a slug points at a node.** Mixing them is the most\ncommon first mistake, and `node $ATLAS validate` reports it as a dangling\nreference. `uid` is the permanent identity, minted once and kept through a\nrename; the slug is the readable current address; a source location belongs in\n`path:`, never in a slug. Relations sit on the declaring file the same way, one\nfrontmatter line from which Atlas derives the edge and its backlink —\n`dependencies` directed, `relates` symmetric, so the map never turns similarity\ninto causality.\n\nThe reading spine is small on purpose — `project → domain → capability →\nelement`, with `document` describing concepts anywhere on it — and an artifact\nearns a node only when it helps someone understand a capability, trace impact, or\nrun the right proof. Curated, not exhaustive. There is **no cap on how many nodes\na vault holds**: a wide hub is a review signal, not a limit, an analyzer's packet\nbound keeps one proposal readable and is never a graph bound, a bridge node has\nto earn its layer, and an external field trial's ontology is never merged into\nthis product's vault. Each rule's authority is the\n[quality authority map](docs/ONTOLOGY-QUALITY.md), and the practical test is\n[what becomes a node?](docs/guide/what-becomes-a-node.md).\n\nThree kinds of file share the folder, and only one is the graph:\n\n| Kind | Where | What makes it that | In the graph? |\n|---|---|---|---|\n| Raw source | `sources/**` | any format, kept exactly as it arrived | no — only `.md` reaches the parser |\n| Wiki page | `wiki/**.md` | Markdown with **no `kind:`** | no — `kind:` is what makes a node |\n| Ontology node | anywhere else | `kind:` in frontmatter | yes, and only these |\n\nInside `wiki/`, `_template.md` is the shape every page is held to and `_log.md`\nrecords each compile or check; `_`-prefixed files are furniture, not pages. The\nfolder is always named `atlas/` ([step 1](#1-open-a-folder)), fixed so a teammate\ncan say it and an agent's config can point at it without guessing, and\n`init --documents` writes the same folder without the node starters for people who\nhave documents and no code. Full contracts: the\n[relations guide](docs/guide/relations.md) and the\n[vault specification](docs/ONTOLOGY-ATLAS-SPEC.md).\n\n## Local-first, by construction\n\n- **Your disk is the database.** Frontmatter is the graph, confirmed writes go\n back to the folder you picked, and Git is the history. There is no other store.\n- **No Atlas backend, account, or telemetry.** The web app is a static export; the\n desktop app checks the public updater manifest once a day and uploads no vault\n content. A connected coding agent talks to its own provider only when you ask.\n- **Two ways in, one folder.** The hosted web app can open a local folder through\n the File System Access API. The desktop app uses a Tauri bridge to your selected\n folder and keeps it open as a workspace.\n- **The Tauri macOS shell is a shell, not a silo.** MCP and CLI still read the\n selected folder directly, and the bundled server is a file your agent launches\n itself, so it keeps working when the app is closed.\n\n## What this is not\n\n- **Not a general-purpose ontology editor.** The ontology describes a codebase; a\n business concept belongs there when it explains what that codebase builds, why a\n boundary exists, or what a change can affect. The Library takes general sources\n and wiki pages with no code nodes at all.\n- **Not a code index, and not an IDE.** Grep, language servers, AST indexes and\n CodeGraph answer where a symbol lives and what calls it; Atlas replaces none of\n them and answers why that artifact matters, which capability it serves, and what\n to verify before changing it. An IDE for codebase *meaning* is the useful\n analogy, and it stops there: Atlas does not edit, build, run, or debug code.\n- **No automatic acceptance of generated knowledge.** Saving a wiki page or answer\n preserves it for review; it does not make its claims true or promote it into\n accepted ontology meaning.\n- **Not an RDF, OWL, SKOS, or SHACL implementation.** The export is a bounded\n graph shape; the vault is not an RDF serialization, the validator is not a SHACL\n processor, and the query engine is not a reasoner. A persisted relation is a\n declared claim, never an entailment; an absent one is a visible gap, never a\n negative fact. [Specification §5.2](docs/ONTOLOGY-ATLAS-SPEC.md#52-standards-boundary).\n- **Not a service, and not on npm.** No backend, account, telemetry, daemon, or\n port; `npx ontology-atlas` is a 404 and not a future feature. The MCP server\n still reaches the ecosystem's registries as a release bundle or a container\n image, neither of which is a package registry.\n- **Not extensible by running other people's code.** There will be no third-party\n plugin runtime. Extension happens through MCP tools, agent skills, and files in\n your own vault — things a `git diff` shows you before they run.\n- **Not finished.** Every public build so far is a release candidate.\n\n## Running from source\n\nLinux and every other platform without a packaged build run the browser app, or\nthe CLI and MCP server from a source checkout: Node.js 24 and pnpm, one clone\noutside the project you are describing, then `init` inside your own repository\nand `mcp-verify` to prove the live connection. The exact commands, the two\nrequired installs, and the reason `init` refuses to run inside the Atlas clone\nare in [set up from a source checkout](cli/README.md#set-up-from-a-source-checkout).\n\n## Documentation\n\n**Use it:** [hosted guide](https://ontologyatlas.com/en/guide/) ·\n[features](docs/FEATURES.md) · [MCP setup](mcp/README.md) ·\n[CLI reference](cli/README.md)\n**Model a vault:** [what becomes a node?](docs/guide/what-becomes-a-node.md) ·\n[relations](docs/guide/relations.md) ·\n[v2 specification](docs/ONTOLOGY-ATLAS-SPEC.md) ·\n[quality authority map](docs/ONTOLOGY-QUALITY.md)\n**Understand it:** [product direction](docs/PRODUCT-DIRECTION.md) ·\n[foundations](docs/FOUNDATIONS.md) · [architecture](docs/ARCHITECTURE.md) ·\n[security](SECURITY.md) · [decisions](docs/DECISIONS.md)\n\n## Contributing\n\nIssues and pull requests are welcome, and the most valuable report today is\npointing Atlas at a real repository and showing where the proposed meaning, the\nagent handoff, or the validation falls short.\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) first — external pull requests come from\nforks, and that is a security boundary rather than a formality. Inside this\nrepository [AGENTS.md](AGENTS.md) is canonical for people and agents alike, and\nproduct decisions route through `pnpm po:route -- --help` from change facts\nrather than a self-declared risk.\n\nPre-push keeps quick checks local; full contract and Knip scans belong to PR CI.\nMain CI reuses a successful PR only for the identical Git tree with complete\nlive required-check proof; unproven pushes use their diff. Daily and manual\nruns remain exhaustive. Exact test-file duplicates are collapsed within a\nlocal check run. Browser CI shares one build and balances whole test files by\nmeasured duration; `node --test scripts/run-playwright-ci.test.mjs` verifies allocation.\nMCP harness probes use `pnpm test:mcp:rpc`; full CI keeps the unique CLI boundary\nthrough `pnpm integration:cli:architecture`. Catalogue checks use captured inputs;\n`pnpm mcp:catalogue:check-online` explicitly checks current registry facts.\nDetails: [development checks](docs/DEVELOPMENT-CHECKS.md).\n\nVerification starts with `pnpm checks:changed`, which picks the focused gates for\nthe files you changed; `-- --run` executes every recommendation and stops at the\nfirst failure, and it is the last command before a pull request.\n\nOpen the pull request as a **draft** (`gh pr create --draft`), which runs no CI,\nand land it with `pnpm pr:land