disambiguate 0.1.0__tar.gz

disambiguate-0.1.0/.agents/skills/documenting-decisions/README.md

@@ -0,0 +1,35 @@
+# Agent Instructions for Checkpoint Awareness
+
+These are deliberately minimal — per the ETH Zurich AGENTbench study, verbose instruction files increase agent step count and cost without improving outcomes. Include only what the agent cannot infer from the codebase itself.
+
+## Combining blocks
+
+Pick the minimal version plus whichever additional blocks match your risk profile. A typical combination for a web app with auth:
+
+1. decision-markers.md (always)
+2. pre-approval-gate.md (if tasks are large or loosely specified)
+3. security-hardening.md (if auth/payments/user data exist)
+4. irreversibility-protection.md (if the agent has DB access)
+
+Resist the urge to add all blocks. Each instruction the agent reads adds steps and cost. Start minimal, add rules only after you observe a failure mode that the rule would have prevented.
+
+If using the CODER/REVIEWER/TESTER subagent architecture:
+
+```markdown
+## Review protocol
+
+CODER: When making noteworthy decisions during implementation, annotate them
+inline with DECISION:<CATEGORY> markers. After completing the task, generate
+DECISION_LOG.md from all markers in changed files.
+
+REVIEWER: Verify decision markers against the actual diff:
+
+- Every checkpoint-category change in the diff has a corresponding DECISION: marker
+- No DECISION: markers reference code that doesn't exist
+- Run: git diff origin/main --name-only | xargs grep -n "DECISION:" 2>/dev/null
+- Flag any unlogged checkpoint changes as "UNLOGGED: [category] — [description]"
+- If UNLOGGED items exist, the PR should not auto-merge regardless of test results
+
+TESTER: Verify that tests exist for any DECISION:IFACE changes and that
+DECISION:SEC changes have corresponding security test cases.
+```

disambiguate-0.1.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

disambiguate-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2026 Frankify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

disambiguate-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: disambiguate
+Version: 0.1.0
+Summary: A tool to resolve markdown glossary terms and their transitive dependencies in topological order in a GitHub project or Obsidian vault.
+Project-URL: Bug Tracker, https://github.com/frankify-app/disambiguate/issues
+Project-URL: Changelog, https://github.com/frankify-app/disambiguate/blob/main/CHANGELOG.md
+Project-URL: documentation, https://disambiguate.readthedocs.io
+Project-URL: repository, https://github.com/frankify-app/disambiguate
+Author-email: Frankify <creator@frankify.app>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Disambiguate
+
+<p align="center">
+  <a href="https://github.com/frankify-app/disambiguate/actions/workflows/ci.yml?query=branch%3Amain">
+    <img src="https://img.shields.io/github/actions/workflow/status/frankify-app/disambiguate/ci.yml?branch=main&label=CI&logo=github&style=flat-square" alt="CI Status" >
+  </a>
+  <a href="https://codecov.io/gh/frankify-app/disambiguate">
+    <img src="https://img.shields.io/codecov/c/github/frankify-app/disambiguate.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
+  </a>
+</p>
+<p align="center">
+  <a href="https://github.com/astral-sh/uv">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
+  </a>
+  <a href="https://github.com/astral-sh/ruff">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
+  </a>
+  <a href="https://github.com/j178/prek">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json" alt="prek">
+  </a>
+</p>
+<p align="center">
+  <a href="https://pypi.org/project/disambiguate/">
+    <img src="https://img.shields.io/pypi/v/disambiguate.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
+  </a>
+  <img src="https://img.shields.io/pypi/pyversions/disambiguate.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
+  <img src="https://img.shields.io/pypi/l/disambiguate.svg?style=flat-square" alt="License">
+</p>
+
+---
+
+**Source Code**: <a href="https://github.com/frankify-app/disambiguate" target="_blank">https://github.com/frankify-app/disambiguate </a>
+
+---
+
+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](docs/glossary/github-format.md) or
+[Obsidian format](docs/glossary/obsidian-format.md), ask for a slug or two,
+and get back a self-contained markdown document where every term is
+defined before it is referenced.
+
+## Quickstart
+
+```bash
+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
+```
+
+The runtime is stdlib-only — `pip install disambiguate` brings in nothing
+else. `uvx` works without an explicit install.
+
+## Installation
+
+```bash
+pip install disambiguate
+```
+
+## How it works
+
+The pipeline parses each [term](docs/glossary/term.md) into a body plus a
+list of [cross-references](docs/glossary/cross-reference.md), builds a
+[dependency](docs/glossary/dependency.md) graph from those references, then
+runs the [resolver](docs/glossary/resolver.md) to produce
+[topological order](docs/glossary/topological-order.md). The same pipeline
+backs [from-mode](docs/glossary/from-mode.md) and `--explain`.
+
+For the architectural map, see [docs/architecture.md](docs/architecture.md).
+For the full vocabulary, see the
+[bundled glossary](docs/glossary/disambiguate.md) — Disambiguate's own
+dogfood.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Conventional commits required —
+the release workflow uses them to compute the next version.

disambiguate-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Disambiguate
+
+<p align="center">
+  <a href="https://github.com/frankify-app/disambiguate/actions/workflows/ci.yml?query=branch%3Amain">
+    <img src="https://img.shields.io/github/actions/workflow/status/frankify-app/disambiguate/ci.yml?branch=main&label=CI&logo=github&style=flat-square" alt="CI Status" >
+  </a>
+  <a href="https://codecov.io/gh/frankify-app/disambiguate">
+    <img src="https://img.shields.io/codecov/c/github/frankify-app/disambiguate.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
+  </a>
+</p>
+<p align="center">
+  <a href="https://github.com/astral-sh/uv">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
+  </a>
+  <a href="https://github.com/astral-sh/ruff">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
+  </a>
+  <a href="https://github.com/j178/prek">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json" alt="prek">
+  </a>
+</p>
+<p align="center">
+  <a href="https://pypi.org/project/disambiguate/">
+    <img src="https://img.shields.io/pypi/v/disambiguate.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
+  </a>
+  <img src="https://img.shields.io/pypi/pyversions/disambiguate.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
+  <img src="https://img.shields.io/pypi/l/disambiguate.svg?style=flat-square" alt="License">
+</p>
+
+---
+
+**Source Code**: <a href="https://github.com/frankify-app/disambiguate" target="_blank">https://github.com/frankify-app/disambiguate </a>
+
+---
+
+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](docs/glossary/github-format.md) or
+[Obsidian format](docs/glossary/obsidian-format.md), ask for a slug or two,
+and get back a self-contained markdown document where every term is
+defined before it is referenced.
+
+## Quickstart
+
+```bash
+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
+```
+
+The runtime is stdlib-only — `pip install disambiguate` brings in nothing
+else. `uvx` works without an explicit install.
+
+## Installation
+
+```bash
+pip install disambiguate
+```
+
+## How it works
+
+The pipeline parses each [term](docs/glossary/term.md) into a body plus a
+list of [cross-references](docs/glossary/cross-reference.md), builds a
+[dependency](docs/glossary/dependency.md) graph from those references, then
+runs the [resolver](docs/glossary/resolver.md) to produce
+[topological order](docs/glossary/topological-order.md). The same pipeline
+backs [from-mode](docs/glossary/from-mode.md) and `--explain`.
+
+For the architectural map, see [docs/architecture.md](docs/architecture.md).
+For the full vocabulary, see the
+[bundled glossary](docs/glossary/disambiguate.md) — Disambiguate's own
+dogfood.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Conventional commits required —
+the release workflow uses them to compute the next version.

disambiguate-0.1.0/docs/glossary/basename-resolution.md

@@ -0,0 +1,20 @@
+## Basename resolution
+
+The rule that a [cross-reference](cross-reference.md) is resolved to a term
+purely by its basename, ignoring any directory components and the `.md`
+extension.
+
+All three of the following resolve identically to the term with
+[slug](slug.md) `foo`:
+
+- `[label](foo.md)`
+- `[label](path/to/foo.md)`
+- `[[foo]]`
+
+This means a glossary can be moved or reorganized without rewriting links,
+and the same term can be referenced consistently regardless of where the
+referencing file lives. The trade-off: two terms cannot share a basename
+even if they live in different subdirectories.
+
+Non-`.md` links and absolute URLs are not subject to basename resolution and
+are ignored entirely by the resolver.

disambiguate-0.1.0/docs/glossary/cross-reference.md

@@ -0,0 +1,15 @@
+## Cross-reference
+
+A link from one [term](term.md) to another. Cross-references come in two
+syntactic forms, both supported:
+
+- Standard markdown: `[some text](path/to/foo.md)` — resolves to the term
+  whose slug matches the link's basename, regardless of path.
+- Wiki-style: `[[foo]]` — resolves directly to the term with slug `foo`.
+
+Cross-references are the edges of the dependency graph. A term that
+cross-references another depends on it: when rendered, the referenced term
+must come first.
+
+Cross-references inside fenced code blocks are ignored — code samples that
+happen to contain link-shaped text do not create edges.

disambiguate-0.1.0/docs/glossary/dependency.md

@@ -0,0 +1,14 @@
+## Dependency
+
+A directed edge from one [term](term.md) to another, created by a
+[cross-reference](cross-reference.md) inside the term's body. If term `a`
+cross-references term `b`, then `a` depends on `b`: `b` must appear before
+`a` in the rendered output, because `a`'s definition assumes `b` is already
+defined.
+
+Dependencies are transitive. Resolving a term pulls in everything it depends
+on, recursively. The complete dependency closure of a term is the set of all
+terms reachable by following edges out from it.
+
+The dependency graph is required to be acyclic. Cycles are a lint error —
+they make ordering impossible.

disambiguate-0.1.0/docs/glossary/disambiguate.md

@@ -0,0 +1,27 @@
+## Disambiguate
+
+The CLI tool this glossary describes. Capitalized "Disambiguate" when
+referring to the tool as a proper noun; lowercase only as the command-line
+invocation `uvx disambiguate`.
+
+Disambiguate takes a markdown [glossary](glossary.md), follows the
+[dependency](dependency.md) edges between [terms](term.md), and emits the
+selected closure in [topological order](topological-order.md). Three
+operating modes:
+
+- **Default**: render selected slugs (or the whole glossary) — the
+  [resolver](resolver.md) is the engine.
+- **`--from <doc>`**: extract the slugs implicitly used in a document and
+  resolve those — see [from-mode](from-mode.md).
+- **`--lint`**: validate the glossary's structural integrity — see
+  [lint](lint.md).
+
+Plus `--explain`, which always renders Disambiguate's own bundled glossary
+(this very glossary) regardless of which user glossary is in scope. The
+intended audience for `--explain` is an LLM agent that needs to understand
+Disambiguate's vocabulary before generating glossary content of its own.
+
+Disambiguate has no third-party runtime dependencies. The implementation
+fits inside the Python standard library — `argparse`, `graphlib`,
+`pathlib`, `re`, `glob`, `importlib.resources`, `logging`. Installable as a
+single wheel; runnable via `uvx disambiguate` with no environment setup.

disambiguate-0.1.0/docs/glossary/from-mode.md

@@ -0,0 +1,22 @@
+## From-mode
+
+The CLI mode triggered by `--from <path>`: extract glossary-shaped
+[cross-references](cross-reference.md) from a document, then run the
+[resolver](resolver.md) over the extracted [slugs](slug.md).
+
+The path argument can be `-` (or omitted entirely) to read the source
+document from standard input. Useful for piping prose through Disambiguate
+to produce a glossary preamble for whatever vocabulary it actually uses.
+
+Link classification:
+
+- A link whose basename matches a slug in the active glossary is treated as
+  a request for that term.
+- A glossary-shaped link with a broken slug — basename ending in `.md` but
+  not matching any term — is an error. From-mode does not silently ignore
+  unresolvable references.
+- Non-glossary links (external URLs, image paths, links to non-`.md` files)
+  are silently ignored.
+
+Output is identical to a direct `disambiguate <slug> ...` invocation: the
+dependency closure in topological order.

disambiguate-0.1.0/docs/glossary/github-format.md

@@ -0,0 +1,18 @@
+## GitHub format
+
+The [glossary-format](glossary-format.md) variant intended for GitHub
+projects. Terms live at `docs/glossary/` (or another path inside the repo)
+and are rendered by GitHub's standard markdown renderer.
+
+[Cross-references](cross-reference.md) use standard markdown links:
+`[label](other.md)` or `[label](path/to/other.md)`. GitHub renders these
+inline; the link target resolves at the repository level when viewed on
+GitHub.
+
+Wiki-style `[[slug]]` links also work for Disambiguate's purposes — they
+will not render as live links on GitHub, but the resolver still picks them
+up. Use them only if you also intend the glossary to be browsable as an
+Obsidian vault.
+
+This is the default variant. A new project setting up a glossary should
+assume the GitHub format unless there is a specific reason to do otherwise.

disambiguate-0.1.0/docs/glossary/glossary-format.md

@@ -0,0 +1,25 @@
+## Glossary format
+
+The shared shape of a Disambiguate-compatible [glossary](glossary.md). A
+single directory containing one [term](term.md) per markdown file.
+
+Per-file structure:
+
+- File basename (with `.md` stripped) is the [slug](slug.md). Slugs must be
+  unique across the directory and use lowercase ASCII letters, digits, and
+  hyphens.
+- The first H2 heading (`## Canonical Name`) is the term's display name. The
+  H2 is mandatory.
+- Body is free-form markdown.
+- [Cross-references](cross-reference.md) to other terms use either standard
+  markdown (`[text](other.md)`) or wiki-style (`[[other]]`). Both resolve by
+  basename.
+
+The format is intentionally minimal — anything outside of H2 + cross-link
+syntax is just markdown, rendered as-is. This keeps glossaries portable
+between platforms with different markdown extensions, while letting each
+platform's variant of the format add its own conventions on top.
+
+Two such variants exist today — one for GitHub-rendered repositories and
+one for Obsidian vaults. Both are special cases of the format defined here,
+with platform-specific tweaks.

disambiguate-0.1.0/docs/glossary/glossary.md

@@ -0,0 +1,12 @@
+## Glossary
+
+A directory of [term](term.md) files. The glossary is the unit Disambiguate
+operates on: load it, resolve from it, render from it, lint it.
+
+By convention the glossary lives at `docs/glossary/` or `glossary/` at the
+root of a project. Disambiguate auto-discovers the nearest such directory by
+walking up from the current working directory. The location can be overridden
+with `--glossary <path>` or the `DISAMBIGUATE_GLOSSARY` environment variable.
+
+A glossary contains zero or more terms. Slug uniqueness is enforced across
+the directory — two files with the same basename are an error.

disambiguate-0.1.0/docs/glossary/lint.md

@@ -0,0 +1,29 @@
+## Lint
+
+The `--lint` mode validates a [glossary](glossary.md) against six
+constraints. Any violation is fatal — the command exits non-zero with the
+problem reported to stderr.
+
+Checks:
+
+- **Cycles** in the [dependency](dependency.md) graph. A cycle makes
+  topological ordering impossible.
+- **Broken cross-references**: a [cross-reference](cross-reference.md) whose
+  basename does not match any term in the glossary.
+- **Duplicate slugs**: two term files sharing a basename.
+- **Missing H2 heading**: a term file with no `## ` heading on any line. The
+  H2 is the canonical name; without it the term has no identity.
+- **Invalid slug format**: a [slug](slug.md) that does not match the canonical
+  format `^[a-z0-9]+(?:-[a-z0-9]+)*$` — lowercase letters, digits, and single
+  hyphens between segments.
+- **Reachability orphans**: terms that no configured root document can reach
+  by following markdown links. Roots default to the repository's
+  `README.md`; override with `--roots` or `DISAMBIGUATE_ROOTS`.
+
+Reachability uses a visited-set walk over both glossary terms and external
+markdown documents. Cycles in external documents are tolerated — the walk
+does not topo-sort, it just collects everything visitable.
+
+The orphan check exists to keep the glossary honest. If a term is not
+linked from anywhere a reader is likely to start, it is dead vocabulary,
+and the lint says so.

disambiguate-0.1.0/docs/glossary/obsidian-format.md

@@ -0,0 +1,18 @@
+## Obsidian format
+
+The [glossary-format](glossary-format.md) variant intended for use as an
+Obsidian vault. Terms live in a folder inside the vault, browsed and edited
+through Obsidian.
+
+[Cross-references](cross-reference.md) typically use the wiki-style syntax:
+`[[slug]]`. Obsidian renders these as live, clickable backlinks and shows
+them in the graph view, which is the main reason to choose this variant.
+
+Standard markdown links (`[label](other.md)`) also work for the resolver
+and render correctly in Obsidian, but lose the backlink and graph view
+benefits. Use wiki-style links by preference; fall back to markdown links
+only when a particular section needs custom link text.
+
+The on-disk file shape is identical to the GitHub format variant — the
+same glossary directory can serve both audiences if links are written in
+either syntax consistently.