Ontology Atlas

Slice 0 (PRODUCT-PLAN-2026-07.md §4/§9) — the "absorption tool". Converts a CLAUDE.md/AGENTS.md-style markdown file into typed vault nodes so a tech lead's existing agent-instruction file stops needing dual maintenance. Splits the file by `##` sections and classifies each: - rule/policy/decision sections → `kind: document` nodes with a `role: policy` frontmatter extra. - architecture/component sections → element/capability SUGGESTIONS only — never auto-written; review and land with add_concept if useful. - sections matching an injection-suspect pattern (Tier 1 — imperative instruction-hijack phrasing, shell/SQL fragments) are excluded from absorption regardless of category and reported for human review. The file body is always treated as untrusted data; parsing never executes or evaluates its content. Two-stage safety, same shape as delete_concept: 1. Without confirm: true the call is a dry-run — returns the classification plan per section, no writes. 2. With confirm: true, absorbed sections are written as document nodes, the source file is backed up to `<file>.pre-absorb.bak`, then rewritten into a "slim pointer" that reproduces every non-absorbed section (suggested, unclassified, or injection-suspect) verbatim — content is never destroyed. Throws instead of overwriting an existing backup file. The canonical source path must be inside repoRoot; outside paths (including symlink escapes) require an reviewed dry-run plus explicit allowOutsideRepo:true.

Create a new ontology node (.md file). Call when an AI agent finds a new capability / element / project from code analysis. Throws if the slug already exists — use patch_concept in that case. The frontmatter is normalized per kind (project gets `domains/capabilities/elements` empty arrays; capability gets `elements: []`; capability/element should also set `domain:` so the tree has a parent — missing extras come back as `warnings` in the response, not as an error. If another node already has the same title, a near-duplicate `warning` is included too — prefer patch_concept on the existing node over forking a duplicate. Successful writes return compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers so agents can immediately see graph cleanup / relation suggestions after the new node lands. **For bulk creation (e.g. bootstrap flow with 5+ nodes) use `add_concepts({concepts: [...]})` (batch, max 50, partial result) — saves K-1 round-trips.** When `kind` is `element`: an element names a CONCEPT a capability uses (e.g. "jwt-token"), not a file. If your `title` is a bare path or ends in a source extension, you are describing evidence, not the concept — rename `title` to the role and put the path in `path:`, or if 3+ siblings under the same parent already look like this, call `get_concept` on the parent and consider `patch_concept` on an existing sibling instead of adding another file-mirror node. The same rule binds the `slug`: flat under the kind folder (`elements/<role-name>`), never a code path (`elements/src/views/home` is rejected) — path-style slugs collide the moment two files share a basename and the graph silently merges distinct nodes.

Batch-create multiple nodes in one call — same per-row shape as `add_concept`. Use after `analyze_repo_structure` or another reviewed proposal flow when the agent has K accepted candidates from the user — replaces K×`add_concept` round-trips. Each row is processed independently: existing-slug / invalid-kind / missing-required-fields / non-object row shape / unknown row fields surface as `{ slug, ok: false, error }` rows whose errors include a `concepts[n]` row label, single unknown-field rows include `receivedField` plus one-row `unknownFields`, multi unknown-field rows report every unknown field with nearest hints and `Received fields: ...`, and duplicate input slugs report the later `concepts[n]` row plus first-seen `concepts[m]` with structured `rowName` / `firstSeenAt`; the rest still land. A row whose normalized title matches an earlier landed row in the same batch still lands but carries a near-duplicate `warning` — `patch_concept` the earlier node instead of forking the same concept (duplicates are the #1 growing-vault failure mode). `concepts[]` order in the response matches the input. Cap = 50 per call (split into multiple batches for larger sets). NO atomic rollback — if you need all-or-nothing semantics use single `add_concept` calls. Invalid-only batches return no row-level write metadata and no top-level `postWriteMaintenance`. When at least one row changes the vault, the response includes one compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers for the final graph. Rows whose `title` is a bare file path follow the same rule as `add_concept` above. Prefer one capability node covering a directory plus a short `elements:` list over one row per file, unless each file's role differs in a stated sentence.

Add a semantic relation between two nodes. Appends to the matching frontmatter graph key (domains / capabilities / elements / dependencies / relates / contains / describes); `domain` sets the source node's inline parent domain. The relation type picks which key receives the entry. A new `depends_on` relation requires a nonblank `why`; an already-existing edge remains an idempotent read even if legacy data has no rationale. **R11**: optional `expected_mtime` — pass the source-side `mtime` from a prior get_concept so concurrent external edits throw VaultConflictError. Invalid relation `type` is rejected before endpoint slug resolution with a closest-value hint and structured `valueName` / `receivedValue` / `suggestion` / `allowedValues` repair fields in `structuredContent`, with no `changed`, `alreadyExists`, or `postWriteMaintenance` write metadata. Changed writes return compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers so agents can immediately see graph cleanup / relation suggestions after the edge lands. **For multiple already-approved semantic edges use `add_relations({relations: [...]})` (batch, idempotent, max 50). `infer_imports.moduleEdges` require exact-evidence review, a semantic rationale, and human approval first.**

Batch-add multiple relations in one call — same per-row shape as `add_relation`. Use after `analyze_repo_structure` or another review flow when the agent has K semantic edges accepted by the user — replaces K×`add_relation` round-trips. Inferred module edges are not accepted merely because imports exist; review exact evidence and include the required nonblank `why` for every new `depends_on`. Each row is processed independently and idempotently: existing edges return `{ok: true, alreadyExists: true}`; missing source/target slugs / unknown type / non-object row shape / unknown row fields surface as `{ok: false, error}` with a `relations[n]` row label and structured `rowName`; unknown type rows include a closest-value hint with structured `valueName` / `receivedValue` / `suggestion` / `allowedValues`; single unknown-field rows include `receivedField` plus one-row `unknownFields`; multi unknown-field rows report every unknown field with nearest hints, `allowedFields`, `receivedFields`, and `Received fields: ...`. `relations[]` order in the response matches the input. Cap = 50 per call. NO atomic rollback — for all-or-nothing semantics use single `add_relation` calls. Tip: avoid `expected_mtime` in batch when multiple rows share the same `from` slug — the first row mutates that file so the second would see a stale mtime. Invalid-only batches return no row-level `changed` / `alreadyExists` write metadata and no top-level `postWriteMaintenance`. When at least one row changes the vault, the response includes one compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers for the final graph.

R16 (autonomous ingest base) — analyze a code repository and propose ontology node candidates. side effect 0 (vault frontmatter NOT modified). Returns deterministic candidates the agent must turn into an evidence-backed proposal and move through the construction lifecycle before any exact batch-writer rows are released. Repository structure is implementation evidence, not automatic business meaning: extractionContract and proposedBusinessOntology make that uncertainty explicit. Detects: - package.json `name` → project candidate - README.md first H1 → project title fallback - README.md H2 sections (skipping generic "Usage"/"Installation"/etc) → domain candidates - src/features|entities|widgets|views/* (FSD) → capability/element candidates - src/* depth-1 folders (generic) → capability candidates + index entry → element - apps/* and packages/* members with package.json → implementation element candidates - README.rst + bounded static setup.py → Python project/package evidence without execution - mixed current and future/negated/deprecated README prose → exact current candidate excerpt plus bounded line-scoped `reviewRequiredEvidence`; review units stay visible but cannot support a proposal claim - selected safe README sections share the existing 1,200-character budget deterministically; no document, heading, or excerpt cap grows - root Python packages plus at most 12 import-connected implementation boundaries → direct modules plus up to 2 exact security/policy/risk file anchors; unused files are not mirrored and no capability is inferred from imports - bounded root Cargo package or repo-contained literal direct workspace members → typed feature declaration + literal cfg/cfg_attr source provenance; predicates are not evaluated and no runtime/import/semantic dependency is inferred - a complete proposal may select at most 4 additional exact TypeScript, JavaScript, Python, or Rust file endpoints already observed by infer_imports for distinct navi…

Compile the whole markdown vault into a deterministic graph artifact: canonical nodes, edges, aliases, graph issues, graph-array canonicalization actions, and optional adjacency indexes. This is the compiler-style read path for graph-database-like use: call it before advanced reasoning, indexing, export, or non-developer-friendly graph views. Includes a stable semantic graphHash and maxMtime for cache invalidation. side effect 0. Large vaults (100+ nodes) can exceed the MCP token cap with the default full payload — use `summary: true` for cheap polling (counts + graphHash, no arrays), or `nodesLimit/nodesOffset` / `edgesLimit/edgesOffset` to slice arrays. The response includes `nodesPagination` / `edgesPagination` meta with `{offset, limit, total, returned, hasMore, nextOffset}` when sliced.

Bind a project node to the local code folder it describes, measure it, and write the source receipt. This is what `nextAction: connect_source` (and `repair_source_binding` / `measure_source` / `remeasure_source`) asks for. Omit `rootPath` and the server infers it: the git repository enclosing the vault wins, otherwise the nearest ancestor folder carrying a project manifest. Without `confirm: true` nothing is written — you get the proposed folder, how many declared `path:` claims actually land in it, and the exact confirming call. Re-running with a different `rootPath` replaces the binding; `disconnect_project_source` removes it. The absolute root stays in the local gitignored sidecar `.ontology-atlas/project-sources.json` and never enters the receipt, the graph markdown, or any handoff.

Return the exact active vault root and code-repository root used by this MCP process, including how each root was resolved. Call first when a client may have stale configuration or multiple workspaces. Root changes require restarting the MCP process.

⚠ DESTRUCTIVE — permanently deletes the vault .md file. Two-stage safety: Both preview and confirmed responses identify the node by permanent `uid` plus current `slug`. 1. Without confirm: true the call is a dry-run — returns a backlinks preview without deleting. 2. If any backlinks exist the call throws — refuses while other nodes still reference this slug. Pass force: true to delete anyway (the referrers become dangling). Successful deletion returns the frontmatter + body so a user who deleted by mistake can recreate the node via add_concept. Directories are left untouched. Pass `expected_mtime` to guard against concurrent external edits — throws if the file changed on disk since you read it. Confirmed deletes return compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers for the final graph.

Remove a project node's local source binding and its receipt. The reversal of connect_project_source — use it when the wrong folder was bound, or to stop measuring. Without `confirm: true` it only reports what would be removed. Other projects' bindings are never touched, and no ontology markdown changes.

Finalize the current project competency Markdown after concept/relation writes, vault validation, and a complete project compile. The server derives the current body digest, project graph hash, source fingerprint, and witness inventory itself; callers cannot submit or restamp those values. This writes only a small provenance receipt to `.ontology-atlas/project-meaning.json`. It never stores raw answers, witness text, absolute source roots, or remote coordinates. `ok: true` means the receipt was written, not that source currentness is verified; read `meaningAssessment` or a fresh `agent_brief` for the fail-closed categorical result.

Return every node that points to the target slug. Scans both frontmatter array keys (capabilities / elements / dependencies / relates / contains / describes etc.) and the wikilinks / markdown links in the body. Used by AI agents to walk the graph from a node to its dependents.

Find vault docs that mention a given concept by title. Useful when an AI agent asks where a capability is realized in code or docs. Each match includes a prose `excerpt` (max 200 chars, headings/tables/code skipped) so agents see *what the matching doc says* without an extra get_concept call. Matches are RANKED by a deterministic relevance `score` (title match > frontmatter ref > body, plus a title token-overlap tiebreaker), then by whether the doc is a graph node, then slug — best-first. **A vault holds ordinary markdown too** (meeting notes, memos, drafts have no `kind:` and are not graph nodes); every row says which it is via `isNode`, non-nodes rank below nodes of equal relevance, and `nodesOnly: true` filters them out. Do not cite a non-node as graph evidence without saying so. Pass `limit` for the top-N. When zero docs mention the title, the response includes a `growthHint` — near-titled vault nodes to check first, or an add_concept scaffold if the concept looks genuinely new.

Return the one-hop graph neighborhood around a node. Unlike find_backlinks, this is graph-frontmatter only and can include outgoing, incoming, or both directions. Returns canonical edges plus neighbor node summaries so agents can inspect a local subgraph in one call.

List orphan nodes — docs that no other node references via any frontmatter array key. Useful as a cleanup starting point or to answer "which nodes are unused?". Same matching policy as find_backlinks (full slug or final segment). Root/sentinel kinds like project and vault-readme are excluded by default.

Shortest path between two nodes (undirected BFS). Returns `{ from, to, hops: [slug...], nodes: [{uid, slug, kind, title, domain?}], edges: [{from, to, via, rationale?}] }` where each `via` is the frontmatter key (`domains` / `domain` / `capabilities` / `elements` / `dependencies` / `relates` / `contains` / `describes`) that linked the two slugs and `rationale` is the one-line `relation_notes` sentence the declaring document stores for that pair (present only when one is stored) — so the agent sees not just *that* A and B are connected but by which key and, when someone wrote it down, *why*. Returns `{ found: false }` when no path is found within maxHops, plus a `growthHint` — a concrete add_relation (both endpoints exist) or add_concept (an endpoint is missing) example so the unanswered question becomes a vault-growth signal instead of a dead end. maxHops defaults to 5 and is capped at 20.

Fetch one node by exactly one selector: `slug` (canonical slug or unique alias) or immutable `uid`. Successful responses always carry both the permanent `uid` and current canonical `slug`; graph relations and graph-operation inputs remain slug-based. Returns frontmatter, body, direct graph neighbors, outgoingEdges (each `{to, via, rationale?}`, the rationale being the stored `relation_notes` sentence when one exists), and mtime. **By default you get `excerpt` — the first prose paragraph only. The node body is where the construction rules put definition, evidence, confidence, and in-scope/out-of-scope, so pass `body: "full"` whenever you are reading a node to answer a question rather than just to identify it.** `bodyInfo` always reports `totalChars` / `returnedChars` / `truncated`, so a partial read is never silent. **For K specific selectors in one call use `get_concepts({slugs: [...]})` or `get_concepts({uids: [...]})`.** When a slug does not resolve, structured growth guidance remains available.

Fetch multiple nodes by exactly one selector array: `slugs` (canonical slugs or unique aliases) or immutable `uids`. Same per-row shape as `get_concept`; successful rows always return permanent `uid` plus current canonical `slug`. Order matches the selected input array. Missing or invalid slug rows return partial `{slug, ok:false, error, ...repairFields}` rows, so later valid slugs still resolve; UID misses likewise return `{uid, ok:false, error, ...repairFields}` without aborting the batch. Graph relations and graph-operation inputs remain slug-based.

Read commit history scoped to the active vault path only. Returns bounded newest-first hashes, subjects, and authored timestamps plus limited/hasMore, shallow-repository state, and historyComplete so agents do not mistake a truncated or shallow view for complete evidence. Commits that touched only files outside the vault are excluded. Read-only; never initializes, fetches, pulls, commits, or pushes.

Create a local, vault-scoped Git checkpoint. Dry-run by default and returns exact expectedHead, files, validation, risk, and the shared previewReady/canConfirm/wouldChange/blockedReasons safety contract. confirm:true requires that expectedHead, blocks validator errors and Git operations in progress, commits only the vault pathspec, leaves outside files untouched, and never pushes.

Inspect local Git state for the active vault only. Returns HEAD/branch, vault files, outside-vault change counts, staged-outside-vault warnings, and in-progress operation risk. Read-only; never initializes, stages, commits, or pushes.

Project ontology indexing plan — run analyze_repo_structure + infer_imports + validate_vault in one read-only call. Use for large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing. Its extractionContract treats source facts as observed evidence, README/folder meanings as proposals, and only persisted ontology meanings as shared; it also returns competency questions, uncertainty, approval gates, and whether active-vault validation actually applies to the analyzed project. The plan distinguishes raw candidates into existing, ambiguous-alias review, and genuinely new buckets, then returns exact reviewCalls for retrieving full rows. side effect 0: this tool never writes markdown. CLI `index --apply` may write analyzer-proposed concepts and containment, but inferred imports remain review-only and are never auto-promoted to depends_on.

R17 (autonomous ingest deeper) — walk TS/JS files in a code repo and infer file-level + module-level import edges. It also walks bounded root Python packages, bounded src/source-layout Python packages, and deterministic Rust use/file-module/literal-include dependencies. A valid root Go module additionally exposes typed local package-import evidence; it stays separate from legacy file edges and never self-approves a semantic relation. Structured `coverage` names the supported languages; Rust support is bounded static text evidence and does not expand macros, evaluate cfg, resolve symbols, or prove runtime impact. side effect 0 (vault frontmatter NOT modified). `moduleEdges` are source-backed review candidates, never self-approving semantic `depends_on` relations. When you know an implementation file, set `focusPath` (or `reviewMode:"focus"`) before considering `full`: Atlas returns bounded exact incoming/outgoing static import receipts, counts, and a cursor without requiring a vault. This focused source boundary is not runtime impact or a semantic relation. Omit `reviewMode` for size-safe automatic delivery: scans whose estimated full MCP result is at most 128 KiB keep the complete response; larger reconciled scans return exactly one compact, non-writing `nextRelationReview:v1` packet plus a delivery receipt and stateless cursor. Use `reviewMode:"next"` to request that bounded packet explicitly. `reviewMode:"full"` preserves the complete shape, but a result over 128 KiB additionally requires `allowLargeResponse:true`; this second confirmation prevents coding agents from accidentally opting into a multi-megabyte response. Oversized raw scans without a loadable reconciliation vault fail with an actionable error instead of emitting an unbounded default response. Every compact candidate carries `absentEndpoints`. If an endpoint is missing, `nextCalls` is empty and `endpointModelling` separates an evidence-only analysis call from the complete `rootPath + proposal` valida…

Read one reviewed architecture-profile/v1 document from the active vault, scan the connected repository with the existing bounded static import analyzer, and return an architectureBrief:v1 for humans and coding agents. The profile declares scoped roles, intended dependency rules, and which known import usages those rules govern; source imports remain observed evidence with usage-qualified receipts. The result distinguishes conforms, violated, and unknown, and never treats unsupported languages, unclassified import usage, empty role mappings, or unmapped edges as compliance. Pattern labels are human/document declarations, not folder-name inference. side effect 0.

List every ontology node in the vault (each .md file with a frontmatter `kind:`). Filter by `kind`, `domain`, and/or `since` (mtime-based incremental sync). Large vaults are resumable with `offset` + `limit`; always follow `pagination.nextOffset` while `hasMore` is true. AI agents call this first to grasp the codebase's mental model.

Vault kind distribution — { total, byKind: { capability: N, ... } }. A quick census so AI agents can size up the vault without paging through list_concepts.

⚠ DESTRUCTIVE MULTI-FILE WRITE — fold one node into another. Every backlink to fromSlug is redirected to intoSlug (frontmatter array entries + body links), then fromSlug is deleted. The survivor keeps its UID while the source UID/history is recorded in canonical `merged_uids`. The intoSlug prose and non-identity frontmatter are preserved as-is — they are not merged automatically (use patch_concept after if you want to combine descriptions). Tail-only references are also redirected. Two-stage safety: 1. Without confirm: true the call is a dry-run — returns the redirect plan + list of deletions without writing. 2. With confirm: true the rewrites and the delete happen in one pass. Throws if either slug is missing. Confirmed writes return compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers for the final graph.

Update the frontmatter and/or body of an existing ontology node. Use when an AI agent revises, deepens, or reclassifies a node. Frontmatter patches are key-by-key — null deletes a key, omission preserves it. Body is fully replaced when provided, otherwise preserved. Pass `expected_mtime` (from the previous get_concept response) to detect concurrent external edits — throws VaultConflictError if the file has changed on disk since you read it. Changed writes return compact `postWriteMaintenance` (maintenance_plan) with count-safe `byPhase` / `bySeverity` / `byKind` queue buckets, action `score`, executable `proposedAction`, and current-page `nextExecutableAction` / `nextReviewAction` pointers so agents can immediately continue graph cleanup.

Typed filter DSL — search vault nodes by predicate. Built for saved-filter / smart-list cases that find_path (BFS) cannot answer, such as "which capabilities have zero elements?", "stub-only nodes in domain=auth", or "has(depends_on) excluding vault-readme". Grammar (case-insensitive keywords, whitespace-tolerant): filter := atom (AND|OR atom)* atom := NOT? predicate predicate := key=value | key!=value | has(key) Keys: kind / domain / slug / title for equality, plus any graph frontmatter array key for has(...). kind and has(...) keys are enum-validated with nearest-value hints. Example: `kind=capability AND domain=auth AND NOT has(elements)` — capabilities under domain auth that have zero elements (= unfinished caps). When total=0, the response includes a `growthHint` — it names any referenced kind/domain that has 0 nodes in this vault, or nudges you to loosen the filter.