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, idempotent (verified stamps deduplicate by actor by), and safe on a git-tracked repo (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) and can enforce a minimum trust tier floor in CI via --require-tier (machine-confirmed or human-reviewed).
  • lint reports source-corpus health before conversion (writes nothing): broken links (incl. #anchors), missing titles, orphans, stale concepts, schema violations, and unquoted colon-space scalars (a frontmatter value like title: Multi-View: Tabs that YAML tries and rejects as a nested mapping). --strict gives a non-zero CI gate; entrypoints and the colon-space advisory are the two buckets it never gates on.
  • 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.
  • project projects a bundle into offline, credential-free property-graph DDL for Spanner SQL/PGQ: schema.ddl, the loader rows (nodes.csv, edges.csv, load.sql), and the provenance artifacts (node_verified.csv, derivation.sql). It reuses the same node/edge model as graph, writes to --out, and prints a binder.report/v1 summary; --target spanner is the only value this release accepts.
  • 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 via --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 applies to files whose frontmatter opens with --- and a newline (LF or CRLF) at byte 0. Inputs with a leading UTF-8 BOM or a classic-Mac lone-CR (\r) fence are normalized at the read boundary before recognition (#124) so the fence and any verified: block it guards are preserved. Because normalization changes the file encoding, the run discloses it via a per-file normalized signal and a top-level advisory that never gates (see Strict mode and Lossless frontmatter round-trip). Scoped to the frontmatter: convert also pipelines the body and synthesises index.md, so the guarantee does not extend to a whole-file comparison.

Verdicts are differential-validated against the vendor-neutral okfcli/okf validator in both directions as part of the exit gate.