Skip to content
binder

What binder is

binder has these commands:

  • convert walks a directory of ordinary markdown files and writes an OKF v0.2 bundle: one concept per non-reserved .md, standard markdown links and [[wikilinks]] rewritten to bundle-relative form, frontmatter-ref edges, #hashtags merged into tags, per-directory index.md navigation, and a generated provenance stamp.
  • enrich adds the missing required frontmatter (type, title, generated) to a source markdown tree in place: frontmatter only, no body changes. It is additive/never-clobber, atomic, and safe on a git-tracked repo, and idempotent unless a verified stamp advances (see enrich).
  • validate checks a bundle against the OKF v0.2 §11 conformance rules and reports trust/lifecycle well-formedness as advisories.
  • index (re)generates per-directory index.md navigation for a bundle, and can add a type-grouped # Catalog to the root index (--group-by-type).
  • review summarizes a bundle: concepts by type, trust tiers, stale/attested, orphans, and unresolved links.
  • lint reports source-corpus health before conversion (writes nothing): broken links (incl. #anchors), missing titles, orphans, stale concepts, and schema violations. --strict gives a non-zero CI gate.
  • graph exports the concept graph (edges = resolved links) as dot/json/graphml/html.
  • infer inspects a source markdown corpus and proposes a directory-to-type mapping string (e.g. docs=Guide,subsystems=Subsystem) using deterministic heuristics (folders, patterns, frontmatter) and optional Gemini semantic inference (--gemini). It is proposal-only and never writes to disk.
  • config manages persistent configuration (get, set, unset, list) and displays the resolved effective configuration with source attribution.
  • mcp runs binder as a stdio MCP server, exposing seven tools: the additive verbs (convert/validate/review/lint/graph) plus the two read-only graph tools list_graphs (schema introspection) and query_graph (bounded traversal). They return the same binder.report/v1 payloads as --json (see MCP server).

convert can also declaratively stamp trust and lifecycle metadata across directory sections — --status-map, --stale-after-map, and --verified-by (#7) — and six commands support --strict to gate advisories in CI (see Declarative trust & lifecycle flags and Strict mode).

Two properties make it trustworthy for pipelines:

  • Deterministic output. convert honours SOURCE_DATE_EPOCH for any synthesised timestamps, so identical input yields byte-identical output.
  • Lossless frontmatter round-trip, where binder recognises the fence. Unmodified YAML frontmatter is re-emitted verbatim — including nested-map and list key order — so every authored key and value survives untouched and a round-trip changes nothing it did not have to change. This is scoped to files whose frontmatter binder recognises and that need no read-boundary normalization: the fence must open with --- and a newline (LF or CRLF) at the very start. A leading UTF-8 BOM or a lone-CR (classic-Mac) fence is now recognised too, but is first normalized at the read boundary (#124) — the fence and any verified: block it guards are preserved, but the round-trip does not preserve the original encoding and is disclosed via a normalized signal and a top-level advisory in the run report. That advisory never gates (see Strict mode). Recognition still leaves byte-level bounds; for the ones known today, see Residual bounds under enrich. Scoped to the frontmatter: convert also pipelines the body and synthesises index.md, so the guarantee does not extend to a whole-file comparison.