Ontology Atlas

In 30 seconds

When an agent finishes a change, you still need to judge what it understood, which rules matter, and what needs your attention. File lists and the producing agent's summary are starting points; they do not by themselves establish that the system's meaning or boundaries were preserved.

Atlas keeps those answers in an atlas/ folder of Markdown inside the repository, so meaning is cloned, branched, and reviewed with the code. Each file's frontmatter declares what it is — project, domain, capability, element, or a linked document — and what it points at. That folder is the whole database.

Atlas compiles that folder into a typed graph. Your coding agent can request context for a task: recorded capabilities, implementation anchors, declared dependencies, evidence, and unknowns. You can inspect those same records and relations in the workbench, open their evidence, and decide which proposed meaning changes to keep. The files remain available to the next person or agent, alongside the code in Git.

The goal is understanding and actionable control, with confidence proportionate to the evidence. A graph path is a declared relationship, not proof of a complete runtime blast radius. A current source path does not prove its recorded meaning is correct. Atlas keeps those distinctions visible so missing evidence can lead to further inspection rather than automatic reassurance. Its five-kind discriminator and standards boundary live in the vault specification.

Use it in the next task

With a populated vault and an MCP connection, ask your agent for the context of the change you want to make. The current task-aware entry is query_ontology with operation: "agent_brief", detail: "compact", a selected project, and your task. It supplies bounded context and follow-up reads; the coding agent still inspects source and verifies its work.

When meaning changes, review the exact proposal and its evidence, then keep the accepted Markdown change with the code's Git history. You need not open Atlas for every task; its map, documents, and change review are there when you need to understand or correct the recorded meaning. Meaning acceptance, code review, merge, and deployment are separate decisions. Host support and configured permissions determine how agent writes reach review; an MCP connection alone does not enforce every agent's behavior.

What still needs proof: reliable meaning reconstruction from unfamiliar legacy code, a complete task-bound Meaning Diff, and improved outcomes across successive real tasks remain development and validation work. Current graph, write-review, and task-context features do not guarantee that an agent's code change is safe. See the quality authority map and development priorities.

Status — read this before installing

The download page is the release authority: a generated record of the published tag, real asset sizes, checksums, platforms, and signing state. This README pins no tag, so it cannot contradict the files you are about to install. GitHub Releases is the second direct source.

• The unsigned Windows beta is a real risk, not a formality. SmartScreen may warn about an unknown publisher, and a managed work PC may refuse the installer outright. Security states what is and is not promised.
• Installing the desktop app installs the agent surface. Both bundles carry the compiled MCP server. There is no npm package; every other platform runs the browser app, the CLI and MCP server from a source checkout, or the MCP server as an .mcpb bundle or a container image (channels).
• A -rc.N build walks the same signing, notarization, installer, and updater checks as a final one — what it lacks is a wide run behind it. The in-app updater reads a fixed Pages manifest staged from the newest non-draft release, release candidates included, and every archive must pass the bundled signature check before installation.
• Screenshots demonstrate the product journey, not release availability.

Where it stands

Not a roadmap. This summarizes behavior documented in the feature inventory, the specification, and the decision history and independent record workflow.

Each worktree adds its own decision/change/pilot fragments with pnpm record:new and pnpm po:record. pnpm test:records checks composition and writer contracts. Docs Vault JSON and public copies are ignored build products, materialized by installation and checkout/merge hooks; use pnpm docs-vault:build after an installation with scripts disabled.

Working today

• A Markdown folder is the whole database — read and written in place, with no import step, no index to build, and no account.
• The macOS app, Developer ID signed and notarized, with the compiled MCP server inside its bundle, and the hosted web app as a no-install gateway.
• MCP over stdio for Claude Code, Cursor, VS Code, Codex, and any other client, typed and advertised through tools/list. Agent guide.
• One-button agent setup that ends in a real proof — paths shown before writing, then an agent restart and mcp-verify. File presence is never presented as a live connection.
• A CLI with the same authority as the agent — scaffold, validate, dry-run writes, traversal, blast radius, commit preflight, agent handoff. CLI reference.
• Every surface reads that one folder — Map, Architecture, Library, Insights, Projects, Agents, MCP, and Git History.
• Saved constellations keep a task's concept set together — name a set in Galaxy, record its purpose, reopen the whole set on the map, inspect its real members in Library, or recover the same read-only context through MCP and CLI.
• Versioned AI analysis kept as local Markdown, with its evidence and selectable history, and measured violations instead of an invented maintainability score. Analysis records.
• Documents of any format gather in the Library, kept byte for byte, with wiki pages required to cite their source on every fact.
• External MCP servers attach to the in-app chat — one switch per server, off by default, tokens only in the keychain. Atlas never sits in that path.
• JSON-LD and GraphML export off the same deterministic compile artifact, so the vault opens in rdflib, Protégé, Gephi, Cytoscape, NetworkX, or Neo4j.
• init installs the agent's procedures where the agent runs, and prints the one sentence to paste into your own CLAUDE.md or AGENTS.md. Atlas does not edit files you wrote.

Shipping, not settled

• Windows x64 is an intentionally unsigned public beta — same folder and MCP surface as macOS, no signature.
• The vault format is v2.0-rc, an RFC open for comment that documents behavior already enforced by contract tests here and carries its own kill criterion. Specification §0.
• Linux has no packaged build — the browser app or a source checkout, same vault, fewer screens.
• **Web and