okf-tools

README

okf-tools

Tooling for authoring and maintaining Open Knowledge Format (OKF) bundles.

What's here

Two Go CLIs and a Nix flake:

• okftool — lints, formats, and scaffolds OKF bundles.
• okfpub — publishes a bundle to a backend (Notion, or the filesystem for dry runs).
• a dev shell bundling qmd (local hybrid search over markdown), with both CLIs on PATH.

The flake exposes each CLI as its own package and app:

nix run github:sigma/okf-tools#okftool -- lint
nix run github:sigma/okf-tools#okfpub  -- run --dry-run

Downstream projects consume the dev shell with:

use flake github:sigma/okf-tools

Both CLIs ship lockstep from the same release tag, and each is also installable in CI without Nix — see setup-okftool and setup-okfpub.

okftool

A small, deterministic Go CLI for OKF bundles — the mechanical half of what an agent currently does "by interpretation." It moves reproducible checks (frontmatter/type conformance, link style, index sync, citation shape, orphans, broken-link reporting) into a testable tool, and hands the genuinely semantic work (contradictions, near-duplicates, staleness) back to the agent as a structured worklist.

okftool lint [paths…]   # run the rule catalog; --fix, --fail-on, --select/--ignore, --exit-zero
okftool index --check   # verify index.md is in sync   (--write regenerates it)
okftool fmt   --check   # normalize frontmatter/timestamps/citations/link-style (--write applies)
okftool new <path> --type <T> [--title …]   # scaffold a conformant concept page
okftool graph --format json|dot             # emit the concept link graph
okftool gaps <concept>                      # concepts near <concept> but unlinked (needs qmd)
okftool skill                               # print the bundled agent SKILL.md

okftool skill emits a Claude Code skill teaching an agent how and when to use the tool — install it with okftool skill > .claude/skills/okftool/SKILL.md, so the guidance versions with the binary. The Nix package also installs the same file at share/okftool/SKILL.md for consumers that prefer to reference it from the store.

Every command takes --bundle <dir> (else auto-discover), --config <path> (else okf.toml at the bundle root), and --format human|json (lint also sarif). Run it via the flake — nix run github:sigma/okf-tools#okftool -- lint, or on PATH inside the dev shell.

In CI (without Nix)

Downstream GitHub Actions workflows can install okftool without Nix using the setup-okftool action from this repo. It downloads the matching released binary (verifying its SHA-256 checksum) and puts okftool on PATH; later steps just run okftool:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sigma/okf-tools/actions/setup-okftool@v0
      - run: okftool lint --bundle path/to/bundle

Pin @v0 for the latest v0.x release, or an exact @vX.Y.Z for a fixed version — the action tag resolves to the okftool binary released at that same tag. The action installs on ubuntu-* and macos-* runners (linux/darwin × amd64/arm64) and exposes the installed version as the version output; it takes no version: input. Windows runners are not yet supported.

Implemented: conformance rules OKF001–OKF004, policy OKF101–OKF107, and worklist OKF201/OKF202/OKF203/OKF206, with autofix for the safe ones. Optional and opt-in extensions (the OKFEXT-* namespace, off by default; OKF0xx/1xx/2xx stays reserved for the spec): OKFEXT-QMD-01/OKFEXT-QMD-02 (qmd-backed semantic near-duplicate detection and index staleness, needs qmd on PATH), OKFEXT-GLOSSARY-* (anchor-checked single-file glossaries), and OKFEXT-SCHEMA-01 (frontmatter validated against a closed schema.json). Not yet built: the Claude Code hook wiring (a consuming-bundle artifact).

okfpub

Publishes an OKF bundle to a backend, mirroring each page's content, its frontmatter-derived properties, and its cross-references — concept links become real links between published pages, and glossary-term citations resolve to in-page anchors. Change detection is hash-based, so a re-run touches only the pages whose source actually changed.

okfpub run [flags]   # publish the bundle to a backend
okfpub version       # print the version

Run flags:

--backend  notion|fake|fs   (default notion)
--bundle   bundle root      (default ".")
--config   okf.toml path    (default: discovered)
--areas    areas.json path  (default: <root>/areas.json if present)
--schema   schema.json path (default: <root>/schema.json if present)
--out      fs/export output dir   (default: okfpub-export)
--dry-run  export to the filesystem instead of publishing (implies --backend fs)
--recompute                 full live-block scan (true drift + self-heal)

--dry-run renders the whole pipeline to a local directory tree instead of calling the backend — the same generation, optimization, and transport code path that publishes to Notion, so it is a faithful preview. --recompute rebuilds each live page's fingerprint from the backend rather than trusting stored state, which detects out-of-band edits and re-heals them.

The Notion backend reads its credentials from the environment:

NOTION_TOKEN    Notion integration token
NOTION_DB_ID    Notion data-source id
OKF_SOURCE_URL  repo web base for the generated-page banner deep-link
                (default: GITHUB_SERVER_URL/GITHUB_REPOSITORY, else local git)
OKF_SOURCE_REF  branch the banner's /edit/ link targets (default: git branch, else main)

NOTION_DB_ID is a data-source id, not a database id. Under the 2025-09-03 API a database can host several data sources, so the id in a Notion URL is the wrong one. Resolve it with GET /v1/databases/{id} and read .data_sources[].

Published pages carry a disclaimer banner linking back to the source file — on by default, configurable in okf.toml (see docs/okf.example.toml).

In CI (without Nix)

setup-okfpub mirrors setup-okftool, with the same tag-pinning rules:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sigma/okf-tools/actions/setup-okfpub@v0
      - run: okfpub run --bundle path/to/bundle
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
          NOTION_DB_ID: ${{ secrets.NOTION_DB_ID }}

Reference

• docs/DESIGN.md — architecture, CLI surface, bundle/link model, workflow integration, roadmap, open questions.
• docs/RULES.md — the canonical rule catalog (IDs, categories, severities, autofix).
• docs/okf.example.toml — annotated per-bundle config schema.