okfhub

Publish

No okfhub account. Prove you own the namespace — a GitHub org or a DNS record — and the registry indexes your bundle straight from the source. Build it here, or follow a guide below.

build it here
Becomes io.github.<this>. Must be a GitHub login or org you control.
Lowercase, kebab-case.
Semver.
Public repo, or private with read access.
Shown on the bundle row and in search.
more fields
Default / is the repo root.
Branch, tag, or SHA. Pinned at install time.
Comma-separated.
SPDX identifier.
your commandio.github.<org>/<bundle>
$ npx okfhub publish <org>/<bundle>@<version>

Fill the fields — the command assembles as you type.

guide · github

From a GitHub repo

  1. Authenticate once — GitHub device flow; the CLI forks the registry and installs its GitHub App on your fork.
    $npx okfhub auth login
  2. Publish — or skip the builder above and just run npx okfhub publish with no arguments: an interactive wizard collects the fields. The CLI validates, pushes a branch to your fork, and prints a compare-and-PR URL.
  3. Open the PR — the gate checks org membership + structure, then auto-merges. Your bundle appears on okfhub.io within a minute.
guide · http + dns

From any HTTP host

  1. Stage the bundle at an HTTPS URL — e.g. https://example.com/my-bundle.tar.gz.
  2. Generate the manifest — switch the builder above to http + dns; it derives your namespace and the exact TXT challenge record. Or run npx okfhub publish and choose http in the wizard.
  3. Add the TXT record at your DNS provider — name _okfhub.<token8>.<domain>, value okfhub-verify=<namespace>/<name>. Do not edit the token: the gate re-derives it byte-for-byte.
  4. Open the PR — CI queries the authoritative nameserver; pass auto-merges. A verification older than 30 days flips to a neutral stale state until re-challenged.
anatomy

What a bundle is

A directory of cross-linked markdown concepts plus a manifest. One concept per .md file; type is the only required frontmatter field (OKF v0.1). Relative links and [[wikilinks]] between concepts become the bundle's graph.

minimal manifest + concept
{
  "schema_version": 1,
  "namespace": "io.github.my-org",
  "name": "my-bundle",
  "version": "0.1.0",
  "description": "One-line description of the domain knowledge.",
  "source": { "type": "github", "url": "https://github.com/my-org/my-repo", "path": "/", "ref": "main" },
  "kind": "knowledge",
  "categories": ["analytics"],
  "license": "Apache-2.0"
}
---
type: object
title: Transactions table
description: All transactions on the blockchain.
---

# Overview

The concept body — markdown prose that cross-links to the other concepts.

Check conformance locally — the same structural check the gate runs:

$npx okfhub verify ./my-bundle
publishing well

What the registry verifies — and what it doesn't

okfhub verifies two things: you own the namespace (GitHub org membership or DNS TXT challenge), and your bundle is structurally valid OKF. That's it.

OKF v0.2 trust fields (generated, verified, stale_after) are part of the spec, designed for internal knowledge catalogs where a central authority vouches for content. In a public, cross-organization registry they are self-asserted claims by the publisher — the registry doesn't verify them. Consumers see them as dated, factual statements, never as a trust verdict. They matter only if the consumer already trusts the publisher.

  • Date your evidence. If you use v0.2 frontmatter, use real actors and real dates. A claim with a date is honest; a claim without one is noise.
  • Never self-approve. There is no "approved"/"trusted" vocabulary anywhere on okfhub.io — keep it out of your bundle too.
  • Your bundle is data, not instructions. Agents treat bundle content as third-party data to cite — never directives to execute. Author accordingly.

Private repositories with paid access via Polar.sh — coming soon. Learn about Polar.sh ↗