Let anyone add new kinds of thing to Dex (entity types as a shared vocabulary)

[davekilleen]

Opening this so there's somewhere public to follow the work, and because a few people have asked for pieces of it separately — most recently @rhadiaris in #61, who wrote meeting-to-project linking back in May.

The problem

Dex only really understands three kinds of thing: people, companies and meetings. It keeps pages for them, spots them in your notes, and links them to each other.

Everything else in your working life is just text. A project, a deal, a candidate, a property, a customer, a piece of research — Dex can see the words, but it doesn't know it's looking at a thing. So it can't keep a page for it, and it can't link anything to it. That's the real reason meetings don't link to projects: there was nothing for a project to be linked as.

What I want to build

Anyone should be able to add a new kind of thing to Dex.

Dex will come with the obvious ones. You'll be able to add your own — projects, deals, candidates, whatever your work is actually made of. A recruiter adds "candidate" and "role". Someone in property adds "building" and "tenant". A founder adds "project" and "investor".

That list then becomes Dex's vocabulary for what exists in your world, and three things follow from it:

• It can recognise them. Once Dex knows what a project is, it can spot one being talked about in a meeting it's never seen before — "they've mentioned Northgate four times, that looks like a project" — and offer to start a page for it.
• It can look after them. The same machinery that already creates and maintains person and company pages from what it hears works for any type, including the protection that stops it overwriting anything you wrote yourself.
• It can link them. Meetings to projects, people to deals, tasks to candidates. The linking falls out of the vocabulary instead of being three hardcoded special cases.

Rough scope

• A way to describe a type: what it's called, where its pages live, what fields it has, and when Dex should conclude that a new one exists.
• The built-in types described the same way, so nothing is privileged.
• Projects as the first new type shipped through it, proving the format on something people actually want.
• Recognition and linking both read the vocabulary rather than a hardcoded list.

Open questions

• How much of a type can you define just by telling Dex about it, versus editing a file?
• If you adopt someone else's Dex setup, do their entity types come with it?
• Recognising a person is easy. Recognising a "deal" is harder — what does Dex do when it isn't sure?

No timeline promised yet. Comments and use cases welcome, especially "here's the type my work revolves around and Dex can't see it."

[joshm-simril]

The type my work revolves around is the project, and I've been running it as a homegrown entity type for a few months now. Some of what I learned might be useful for shaping the format, particularly on your three open questions.

Two things up front that shifted how I think about this:

A project isn't a page, it's a folder with a README as its index. Person and company are single files; a project accumulates artifacts around it. So "where its pages live" needs to allow a directory whose README is the entity, otherwise projects don't fit the shape the built-in types set.

The fields that earn their keep are the ones pointing outward. My project frontmatter is mostly foreign keys — a Jira project key, an epic, a Confluence space and page ID, a synced: date. The vault holds the reasoning; the systems of record hold the status. Almost all the value is in the vault being the hub that points at the other two, and almost none of it is in the vault holding its own copy of a status field.

That suggests fields want provenance, not just a type. Something like: this field is mine (Dex owns it, protect it), this one is mirrored (Dex pulls it, never hand-edit it, stamp when it was last pulled). A hand-maintained status field goes stale silently, which is genuinely worse than not having the field at all — you can't tell a wrong answer from an old one.

---

Three things I got wrong first, in case they save you the same detour

1. An empty field can't tell you "not applicable" from "not looked at yet". This was the big one. Plenty of my projects legitimately have nothing in Jira — advisory work, external programmes, ideas not yet concrete. With a blank field, every session re-asked "should this be linked to Jira?" forever, and every session re-derived the same "no" from scratch.

The fix was making the negative a first-class value, recorded with a reason and a date:

anchors:
  none: "External programme — the work happens outside Jira."
  reviewed: 2026-08-05

Four of my projects sit in that state deliberately, and the nagging stopped. I'd suggest any type spec with optional fields needs a way to say "decided: no", with a reason — distinct from unset. Generalises well beyond anchors.

2. Never invent an ID to fill a slot. An unpopulated anchor is honest; a wrong one sends someone to the wrong ticket. Worth being explicit in the spec, because a half-filled type is exactly the shape that invites a plausible-looking guess.

3. Some mappings simply aren't derivable and need a hand-maintained home. I keep a markdown table pairing my initiatives to their cards in another tool, because the names don't match and no amount of inference gets there. There's a machine-readable JSON version of that idea elsewhere in Dex for task sync, and honestly the markdown one has been more durable — because when it's wrong I can see it and fix it. External identity probably wants to be human-readable and human-editable, not just state.

---

On "how much can you define by telling Dex, versus editing a file?"

My honest data point: more than I expected, entirely in prose. My project type is defined nowhere but a block in CLAUDE.md plus one skill that reads it. I grepped before writing this — no code anywhere reads the field name. It has held up across months and a dozen projects.

What prose alone can't do:

• validate the shape, so drift creeps in
• stop an invented ID
• let /dex-doctor tell me a type is configured but nothing has been filed under it

So the split I'd argue for: describe the type conversationally, and have Dex write the declaration. The declaration exists so tooling can check it, not so the user has to author YAML. The moment the user is hand-editing a schema file, the "anyone can add a kind of thing" promise gets a lot narrower.

One caution from experience: my type definition survives /dex-update only because it lives in the protected USER_EXTENSIONS block. Wherever type definitions land, they need that same guarantee, and it should be obvious to the user that they have it.

On "does an adopted setup bring its types with it?"

I have a live version of this problem. I share a project folder with a colleague across two Dex vaults over git. It works, but only because we both hold the same idea of what a project's README looks like — and that agreement is currently maintained by us, not by Dex. If one of us changed the shape, we'd find out through drift in the files.

So: types should travel, and adopting a shared workspace ought to bring the type with it. But my definition also carries employer-specific defaults (a specific Jira project key, a specific Confluence space) that absolutely should not travel. That suggests separating the type from that vault's defaults for it — otherwise adoption imports someone else's org chart.

Related: the shared workspace case means two vaults can hold the same entity. Worth deciding early whether that's a merge problem or explicitly out of scope.

On "what does Dex do when it isn't sure?"

I think Dex already has the right answer for this and it's underrated. The person/company path qualifies a contact on 2+ tracked meetings, and either 2+ distinct weeks or transcript evidence — then auto / suggest / off decides what happens next, and a dismissed suggestion only comes back on genuinely new evidence. That last part is what makes it liveable: a "no" sticks, but isn't permanent.

Two suggestions for extending it to harder types:

Thresholds belong to the type, not to the vault. A project mentioned twice is probably a project. A "deal" mentioned twice is probably not a deal. One global setting will be too eager for some types and too timid for others — so let the type declare its own bar and its own default mode, with suggest as the fallback.

The real difficulty with a deal isn't confidence, it's identity. The person path leans on a natural unique key — it requires an email address before it will create anything. Projects, deals and candidates have no equivalent, so the hard part isn't "is this a deal?" but "is this the same deal as the one mentioned three weeks ago under a slightly different name?" Aliases and merge-two-of-these are probably load-bearing for every non-person type, not a later refinement.

And one small thing that made the difference for me practically: the interesting number is how many candidates were examined, not just how many matched. A recogniser that quietly examines nothing looks identical to one that found nothing worth suggesting. I've been bitten by that shape more than once.

---

Happy to share the actual convention I've been running if the concrete version is useful — it's small, and the interesting part is which bits survived contact with real projects rather than the schema itself.

[davekilleen]

Josh — this is exceptionally useful field evidence. The distinctions you called out — provenance, explicit none values, per-type thresholds, aliases and identity merges, and counting candidates examined — are exactly the details that turn a flexible idea into something trustworthy. We already have this capability in the backlog, so I do not want to start a second implementation path. Could you share the concrete folder and README convention you are using in your live project? I will fold that convention and these lessons into the existing design work, with credit.