Folder structure

A vault is simply a Markdown folder. The only special part is the frontmatter at the top of each file.

---
uid: 01890f3e-7b5d-4c0a-8f14-123456789abc
kind: capability
slug: token-issue
title: Token Issuance
domain: auth
---

# Token Issuance

Issues a session token to users who have successfully logged in.

uid and slug: Permanent Identity and Current Address

Every node has both identifiers.

uid is a lowercase UUIDv4 issued only once when the writer creates a node. It is not calculated from slug, title, or file path, nor is it reused for new nodes copied from existing ones. rename and reclassify preserve the UID. merge preserves the UID of the surviving node and records the absorbed UID in merged_uids, ensuring lookups by the old UID still point to the same node.

uid: 21890f3e-7b5d-4c0a-8f14-123456789abc
merged_uids:
  - 01890f3e-7b5d-4c0a-8f14-123456789abc
slug: token-issue

merged_uids is history specific to merge_concepts. Do not issue it manually or fix it via general patch. validate blocks UID duplicates, invalid formats, and self-referential survival UIDs as hard errors.

This specification follows RFC 9562, which defines random UUIDv4, and W3C JSON-LD 1.1, which requires JSON-LD node identifiers to be IRIs. When exporting, urn:uuid:<uid> is used, so changing the slug does not change the external identity.

Converting an Existing Vault Without UIDs to v2

It does not modify files upon reading. From the Ontology Atlas source checkout root, first preview the changes.

pnpm vault:migrate 2026-08-02-add-node-uids --vault /path/to/vault

After reviewing, apply them by adding --write to the same command. If there are uncommitted Markdown files in git, conversion will be rejected, so you must commit or stash first. Valid existing UIDs are preserved, but invalid or duplicate primary/merged UIDs fail before writing the first file.

kind: What the file is

kind defines what the file is. It becomes more specific as you go down.

Relationships

People and tools read relationships with names like contains, depends_on, broader. The canonical storage key for depends_on in Markdown frontmatter is dependencies:.

---
uid: 11890f3e-7b5d-4c0a-8f14-123456789abc
kind: capability
slug: token-issue
title: Token Issuance
domain: auth
dependencies: [jwt-signer, session-store]
---

Project membership is not specified separately. It is determined automatically by traversing the contains chain. Writing only domain: auth automatically links to the project above it. Relationship values can use slugs instead of UIDs, allowing people to read the graph just by opening the file. The rename tool atomically updates these relationship values as well.

Names in Two Languages

Using display_ko / display_en renders the name appropriate for the screen language on maps and lists. title serves as the source of truth for search/matching and should not be changed.

Fill in all languages used by the vault. If only one side is filled, the original text will be exposed to users of the other language.

Where to Place It

Typically, you place it within the repository you are managing. This way, code and meaning are committed together and reviewed simultaneously.

your-repo/
├── src/
└── docs/ontology/     ← Vault
    ├── project.md
    ├── domains/
    ├── capabilities/
    └── elements/

This repository does the same. It documents itself in docs/ontology/, and those files are used to build this product.

The Vault is Files

The frontmatter is the vault. There is no separate approval process or sync button. Editing a file updates the graph directly. Even if an agent writes it, it appears as a git diff, and you can manually correct it if needed.