The field guide

Unicron is a second brain built on a folder of plain markdown files — no database. Every note is a file, and every link between notes is an edge. Each note also has a type and a schema it's checked against, which is what makes the vault a small knowledge graph rather than a pile of linked notes: typed things, with defined relationships the app can read and reason over. It reads those files and draws them as a living graph you can browse and search.

What you actually do is capture — paste a meeting transcript, jot a thought, drop something in the inbox. Claude Code is the engine that turns that into structure: running locally, it reads your messy input, writes it into a typed note, and works out where the note belongs: its area, its project, the people it involves. From that the app infers the graph's edges, and you skim and confirm. You never assemble the graph by hand; you capture, Claude Code structures it, and the relationships fall out.

This guide covers what the vault knows, how it works out relationships on its own, and where it's headed. It's meant to grow — a map we keep updating as we build, with a status badge on everything so it stays honest about what's real.

Once you think of the vault as a knowledge graph, four words show up everywhere:

• T-Box (terminological) — the schema. The kinds of note that exist and the links allowed between them. It lives in ontology.md.
• A-Box (assertional) — the assertions. Your actual notes, and the links between them.
• Predicate — a typed edge. Not just "A links to B" but how: belongsTo, involves, mentions.
• Provenance — where a fact came from and how sure we are. A link you wrote by hand, or one the app inferred.

There are really two graphs hiding in a vault.

The one you started with is an entity graph: it describes what exists and how things sit together — areas, projects, people, and meetings, joined by containment and mention.

The second is a process graph: what happens, and what leads to what. A decision, the steps it sets off, the outcome it produces. That's the decision module, and it's live now — a genuinely different shape from the entity graph. The web standardized this shape long ago as PROV-O, the Provenance Ontology (Agent, Activity, Entity), which is a good sign it holds well beyond a personal vault.

Sketch how something actually gets done — who's acting, the steps they take, the things those touch, the result it produces — and it maps almost one-to-one onto PROV-O, the web's standard for provenance.

• The one making the calls is an Agent — you, or Claude working on your behalf.
• The steps are Activities.
• The things they touch are Entities.
• The result is the Outcome.

Nearly every edge in that picture you can assert for free: an agent performed a step, a step produced a result. Plain facts, no judgment call. The edge you can't is the causal one. That the outcome followed the plan is checkable; that it was caused by the plan is a claim only you should confirm. So that edge — a decision's leadsTo — stays dotted and proposed until you sign off.

That's the aim: your ordinary planning, captured as a graph with real provenance, where the app asserts what it can prove and leaves the causal claims to you.

This graph stays true as it grows by running a loop between two halves that fail in opposite ways.

• Neuro — Claude reads your messy notes and proposes structure. High recall, but it can guess wrong.
• Symbolic — the ontology and its rules check each proposal, store it with its provenance, and never invent anything. High precision.
• You — view and confirm. Confirmed facts ground the next pass.

You already run this loop every day. It's called triage: Claude proposes where a capture belongs, you confirm. Everything here is that same pattern, widened from filing notes to confirming relationships.

One rule keeps it from rotting: inferred and proposed facts stay re-derivable and never get hand-edited. The moment you edit a guessed edge as if you wrote it, the system can't tell truth from guess anymore.

Every note declares a type. The Graph view colors each note by its type, using the same hues shown above. The legend is read straight from your vault's ontology.md, so it's your actual schema — not a description of it.

Notes under raw/ stay untyped on purpose — they're quick captures waiting for triage, not part of the graph yet.

Notes connect through typed relationships — predicates. Each one is derived: the app reads it from a frontmatter field, a folder, or a link you wrote. The provenance says how the edge came to be — one you authored (a link you typed) or one the app inferred (worked out from structure). This table reads live from ontology.md.

Rules the vault can quietly break — read live from ontology.md. They're advisory: the app checks your notes against them and flags what's drifted, but never blocks or edits anything. See how your vault does just below.

Every note, measured against the rules above. A broken reference — a project: or area: slug that points at a note that doesn't exist — is flagged in red; softer drifts (a project with no area, an area missing from your profile's ## Areas list, an unfamiliar kind or status) in amber. Most carry a picker that sets the field for you; a few — like an area missing from your profile — just open the note, because the repair is a line of prose somewhere else rather than a value to choose. Nothing here changes your files on its own.

The fastest way in is Add — the + in the top bar, or ⌘N. Pick what you're capturing (a Meeting, Project, Person, Area, Decision, Journal, or a quick Task), paste or jot what you've got, and Claude Code writes it into a properly-typed note in the right folder. For a meeting you can paste the whole transcript; it pulls out who was there, updates those people, and files the note under its area.

Anything you drop in raw (a paste, a note from your phone, a Shortcut) lands in the inbox, untyped and waiting. Run Triage and Claude reads each capture, works out its type and where it belongs, and files it as a real note — you review the result. The top bar flags the inbox whenever something's waiting.

Five places across the top: Today (your daily brief), Tasks, Library (every note, filtered by type in the left rail), Graph, and Ask. In the Library rail, click a type to isolate it (⌘-click to combine a few), and drill into an area or project to see what lives under it. Press ⇧⌘J to jump to any note by name, or / to filter the current list. Ask is a read-only chat: it reads your notes to answer, and sends you to the terminal for anything that would change them.

A note opens in preview; hit ⌘E (or the pencil) to edit. In edit mode, type @ and a name to drop in a person link (the path is worked out for you), and / for a menu of formatting and blocks. Tables edit cell by cell, with row and column controls. Save, and the app re-reads the note so the graph stays current.

Diagrams. A fenced mermaid block renders as a diagram in preview, and stays plain text in edit mode and in every other markdown editor — it's a code fence, not a special file format:

```mermaid
flowchart LR
  A[Opened] --> B[Consent] --> C[Identity]
```

Flowcharts, sequence diagrams, state diagrams, ER diagrams — mermaid's syntax covers all of it. A diagram wider than the reading column scrolls inside its own box rather than stretching the page, and one that fails to parse shows the error and its source instead of taking the note down with it.

You can theme a diagram inline with a %%{init: …}%% directive on its first line. When you do, that wins — the app only applies its own light/dark theme to diagrams that haven't asked for one.

Any - [ ] line in any note is a task, and the Tasks view gathers them all — no separate to-do app. But not every checkbox is yours to act on, so the view splits them by who owns the item:

• Mine — your actual to-do list, and the bucket that counts as load. Check things off, defer one to a later date, or hit Select to mark, or assign, a whole batch at once. Checking a task writes straight back to the note it came from.
• Waiting on — things other people owe you. Put a name in front of the task (**Jane** — send the contract), or write it in that person's note, and it lands here instead of Mine. No checkbox and no count: you scan them to see who owes you what, you don't maintain them. When someone finally delivers, whatever you do next is a fresh task of your own.
• Threads — ambient context in a client area that was never a to-do. Anything under a client area — its projects, meetings and decisions, not just the area note itself — that doesn't name an owner lands here. Same passive treatment as Waiting on.

Who owns a task is read from the line, so the fix for one in the wrong bucket is to say whose it is. The ⋯ menu on any row has Assign to, and Select mode has the same thing in its bar for doing a batch at once. It writes the name into the markdown — - [ ] **Jane** — send the contract — so you sort a line once and it stays sorted. ⌘Z takes it back like any other change.

Assigning is the one thing Waiting on and Threads allow, because pulling back work that's actually yours is the only way something leaves those buckets. Everything else there stays passive — you don't complete other people's commitments.

Writing one by hand, the shape is - [ ] **Sam** — send the contract. Shared work takes a list — **Sam + Alex** or **Sam / Alex** — and **Unassigned** is the honest answer when nobody's holding it yet. A task with no owner at all is a guess the app has to keep making, so Claude names one whenever it files a task. Bare lines in your vault predate that, and assigning them is how they get retired.

Later is the fourth chip: anything you've deferred, counted and sorted by when it comes back, out of the other buckets until then.

A task lives in exactly one note. The note it belongs to is the durable one — a person's note for what they owe, a project or area note for your own work. Meeting notes record what was assigned on the day as plain bullets, not checkboxes, because the same commitment used to get written into the meeting, every person named, and the area note all at once. Four copies, worded a little differently each time, and checking one off left the other three open. Claude writes the checkbox once now, in the note that will still be true next month, and the meeting keeps the full record without competing for it.

Running /focus or /tasks also writes Tasks.md to the vault root: your own open tasks, grouped by area, as plain bullets. It's a read-only mirror for reading the list on a phone through whatever syncs your vault. Nothing reads it back and every run overwrites it, so check things off here or in the source note.

That split runs everywhere tasks show up. A project's Open tasks count is yours alone, with a quiet "Waiting on" list beneath it, and inside a note someone else's - [ ] reads as a plain bullet instead of a checkbox you'd check off.

Filter the whole view to one area or project with the scope control up top.

A document is a long note that belongs to a project — research, thinking, a draft, talking points for a conversation. It's the one note type allowed to run long.

Everything else about it follows from that:

• It always has a project, and through the project, an area. A document is never free-floating. If a piece of writing has no project, it isn't a document — it's a topic, which is where vault-level thinking lives.
• It holds no tasks. A commitment that comes out of writing one belongs on the project note, where the rest of that project's tasks already are. Type a - [ ] into a document and the Field Guide flags it rather than silently swallowing it.
• Its description is what gets indexed, not its body. The project note carries a ## Documents row — title, one line, link — and that row is all most things ever read. That's deliberate: a handful of 400-line documents in the ambient read set would double what the daily brief has to chew through every morning, for material that has nothing to do with today. So write a real description; it's the whole index.

Create one with Add ▸ Document, or /document in the terminal. Pick the project and the area comes with it.

Documents you want left alone entirely can carry readonly: true — see Keeping Claude out.

The Graph view draws the whole vault. Every note is a node, sized by how many links it has; every link is an edge. Two layouts:

• Force — physics pulls connected notes together. The relationship view.
• Tree — a top-down hierarchy rooted at you. The structure view.

Edges come in two kinds, and the Edges toggle in the graph toolbar switches between them:

• Solid — written. A link you actually typed in a note.
• Dashed — inferred. A relationship the app worked out from frontmatter and folders, like a project belonging to its area. Nobody wrote it as a link; Unicron figured it out.

Flip to Written to see only what you wrote by hand. Flip to All to add back everything the app inferred. Hover any edge to see where it came from — a written link, or which predicate inferred it.

You never have to draw those dashed connections yourself.

When you tell a note where it lives — its area:, its project:, or just the folder you keep it in — the app reads that and makes the connection. A project joins its area; a meeting joins its project and its area. You fill in the note, and the relationships appear as dashed edges.

So don't spend effort linking a note back to its own area or project to "connect the graph." The engine already did, and deleting such a link wouldn't pull anything apart — the dashed edge stays.

Areas are the one exception, because an area has nothing above it to be inferred from. What ties it in is its row in the ## Areas list on your profile, and that link is written, not derived. /area and the Capture dialog add it when they create one; if an area is missing from the list you'll see it flagged below, and floating loose in the graph.

The links worth writing by hand are the ones the app can't guess: a person who matters to a project, a meeting that reaches into another area's work, a reference that crosses the usual lines. Those are your solid edges. Write about what's connected and the links follow; you're never gardening the graph to keep it whole.

A decision is a choice you're tracking. Create one with ⌘N ▸ Decision — it lives in its area, like a project. Its steps are just task lines (- [ ]), so they roll into your Tasks, and you can note who made the call with a decidedBy field.

Move it through its lifecycle from the status control — in the note header or in View ▸ Decisions, no YAML editing: open while you're still deciding, made once you've called it, revisited if you come back to it.

When you know how it turned out, hit Record outcome — on the decision in the Decisions view, or from the note header. That writes the outcome note, points the decision's leadsTo at it, and adds a linked ## Outcome section to the decision itself, so the connection is visible when you read the note rather than living only in frontmatter. Recording one by hand is the assertion, so the edge is confirmed straight away.

Once a decision has an outcome, its header shows Outcome: