Disambiguate

Source Code: https://github.com/frankify-app/disambiguate

Disambiguate resolves markdown glossary terms and their transitive dependencies in topological order. Point it at a directory of *.md term files in either GitHub format or Obsidian format, ask for a slug or two, and get back a self-contained markdown document where every term is defined before it is referenced.

Quickstart

uvx disambiguate                       # render the entire glossary
uvx disambiguate topological-order     # render one term and its dependency closure
uvx disambiguate --from notes.md       # extract glossary-shaped links from a doc
uvx disambiguate --explain             # render Disambiguate's own bundled spec
uvx disambiguate --lint                # validate the glossary
uvx disambiguate --drift               # detect prose drifting from the glossary
uvx disambiguate prune                 # remove terms no file links

The runtime is stdlib-only — pip install disambiguate brings in nothing else. uvx works without an explicit install.

Installation

pip install disambiguate

How it works

Prune removes terms no file in the repository links. It serves repos that acquire a shared term set and use only part of it. A term consents by carrying an auto-prune annotation.

The pipeline parses each term into a body plus a list of cross-references, builds a dependency graph from those references, then runs the resolver to produce topological order. The same pipeline backs from-mode and --explain.

--drift detects drift — prose that uses the vocabulary without following it: terms mentioned but never linked, and (as the checks grow) forbidden synonyms and wrong casing. Each drift-check reports fatal findings named by a stable rule-code; false positives are silenced precisely with ignore-hints, and already-drifted repos adopt incrementally through a checked-in drift-baseline.

For the architectural map, see docs/architecture.md. For the full vocabulary, see the bundled glossary — Disambiguate's own dogfood.

Contributing

See CONTRIBUTING.md. Conventional commits required. A release is a version bump merged to main (docs/releasing.md).

Org glossary

Org-genome terms stamped in by the template (rooted here so disambiguate --lint can reach them): org, org genome, pando, pando cell, reinset, principal, agent session, memory repo, decision-memory, evidence-memory, session-memory, pandoscope template, template stamp.