Package the validator as the installable okgf command

.github/workflows/conformance.yml

@@ -5,21 +5,39 @@ on:
     branches: [main]
   pull_request:
 
+# Read-only token: this workflow only checks out and validates code, it never
+# writes to the repo. Scoping GITHUB_TOKEN down is the CodeQL-recommended default.
+permissions:
+  contents: read
+
 jobs:
-  validate:
+  test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
-      - name: Install dependencies
-        run: python -m pip install -r requirements-dev.txt
-      - name: Validate example bundles (strict, with signature verification)
+          python-version: ${{ matrix.python-version }}
+      - name: Install the okgf package (with dev + verify extras)
+        run: python -m pip install -e ".[dev]"
+      - name: Validate example bundles with the okgf command (strict, with signature verification)
         run: |
-          python tools/okgf_validate.py --strict \
-            --pubkey examples/governed/ORG_PUBKEY.pem \
-            examples/governed
-          python tools/okgf_validate.py --strict examples/minimal
+          okgf --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+          okgf --strict examples/minimal
+      - name: Back-compat shim still validates
+        run: python tools/okgf_validate.py --strict examples/minimal
       - name: Run tests
         run: python -m pytest tests/ -q
+
+  # Stable required-status context. Branch protection requires the single check
+  # `validate`; this gate passes only when every `test` matrix leg (3.9, 3.12)
+  # passes, so the required check name does not change with the matrix.
+  validate:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "All conformance matrix legs passed."

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: release
+
+# Publish the `okgf` package to PyPI when a version tag is pushed (e.g. v0.1.0).
+# Publishing uses PyPI Trusted Publishing (OIDC): no API token is stored in the repo. The PyPI
+# project must list this repository + workflow + the `pypi` environment as a trusted publisher.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Smoke-test the built wheel
+        run: |
+          python -m pip install dist/*.whl
+          okgf --version
+          okgf --strict examples/minimal
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  bump-homebrew:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    # Optional: open a PR against the tap to update the formula. Needs a HOMEBREW_TAP_TOKEN secret
+    # with push/PR access to OneHillAI/homebrew-tap. Skipped automatically when the secret is absent.
+    if: ${{ false }}
+    steps:
+      - name: Bump the tap formula
+        run: echo "Enable this job and set HOMEBREW_TAP_TOKEN to auto-bump OneHillAI/homebrew-tap."

.gitignore

@@ -1,3 +1,8 @@
 __pycache__/
 *.pyc
 .pytest_cache/
+# Build / packaging artifacts
+build/
+dist/
+*.egg-info/
+.venv/

CONFORMANCE.md

@@ -1,8 +1,9 @@
 # OKGF Conformance
 
 This document defines what it means for a page or bundle to conform to **OKGF v0.1**, and how to check
-it with the reference validator in [`tools/okgf_validate.py`](tools/okgf_validate.py). The normative rules
-live in [`SPEC.md`](SPEC.md); this file restates them as a checklist and describes the tooling.
+it with the reference validator, installable as the `okgf` command (see [`docs/INSTALL.md`](docs/INSTALL.md);
+its source is the [`okgf/`](okgf/) package). The normative rules live in [`SPEC.md`](SPEC.md); this file
+restates them as a checklist and describes the tooling.
 
 ## What conformance means
 
@@ -45,17 +46,17 @@ key is supplied, the validator format-checks the signature and reports it as **u
 ## Checking conformance
 
 The reference validator needs Python 3.9+ and PyYAML. Signature verification additionally needs the
-`cryptography` package and a public key.
+`cryptography` package (the `verify` extra) and a public key.
 
 ```sh
 # Validate pages and/or bundle directories (structure + governance ranges):
-python tools/okgf_validate.py examples/minimal examples/governed
+okgf examples/minimal examples/governed
 
 # Also cryptographically verify signatures against an org public key:
-python tools/okgf_validate.py --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+okgf --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
 
 # Treat warnings (e.g. missing recommended OKF fields, unverified signatures) as failures:
-python tools/okgf_validate.py --strict examples/governed
+okgf --strict examples/governed
 ```
 
 Exit status is `0` when there are no errors (and, under `--strict`, no warnings), otherwise `1`. A usage or

CONTRIBUTING.md

@@ -8,7 +8,8 @@ the reference validator.
 
 - **Spec clarifications or fixes** - wording, ambiguities, or errors in `SPEC.md` / `CONFORMANCE.md`.
 - **New or improved examples** - sample bundles under `examples/` that show a real pattern.
-- **Validator improvements** - bug fixes or checks in `tools/okgf_validate.py`, with tests.
+- **Validator improvements** - bug fixes or checks in the [`okgf/`](okgf/) package (run as the `okgf`
+  command), with tests.
 - **Proposed field or lifecycle changes** - larger changes to the governance model. Open an issue first
   (see below) so we can discuss before you write it.
 
@@ -22,10 +23,10 @@ must not break OKF conformance.
 2. **Branch and make the change.** Keep PRs focused on one thing.
 3. **Run the checks locally:**
    ```sh
-   pip install -r requirements-dev.txt
+   pip install -e ".[dev]"
    python -m pytest tests/ -q
-   python tools/okgf_validate.py --strict examples/minimal
-   python tools/okgf_validate.py --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+   okgf --strict examples/minimal
+   okgf --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
    ```
    New or changed behaviour needs a test. New example bundles must pass the validator (CI enforces this).
 4. **Open a pull request** against `main`. CI runs the validator and the test suite on every PR.

README.md

@@ -29,6 +29,7 @@ is coming soon.
 
 ## Table of Contents
 
+- [Install](#install)
 - [Why OKGF exists](#why-okgf-exists)
 - [How it works](#how-it-works)
 - [The review lifecycle](#the-review-lifecycle)
@@ -38,6 +39,31 @@ is coming soon.
 - [Lineage](#lineage)
 - [Status](#status) · [Contributing](#contributing) · [License](#license)
 
+## Install
+
+Install the reference validator as the `okgf` command. No system Python required - this uses
+[uv](https://docs.astral.sh/uv/) to manage an isolated Python for the tool:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/OneHillAI/okgf/main/install.sh | sh
+```
+
+Or via Homebrew, or straight from PyPI:
+
+```sh
+brew install OneHillAI/tap/okgf
+pipx install okgf        # or: uv tool install okgf, or: pip install okgf
+```
+
+Then validate a bundle:
+
+```sh
+okgf --strict path/to/bundle
+```
+
+Signature verification is optional: add the `verify` extra (`OKGF_VERIFY=1` for the installer above,
+or `pip install 'okgf[verify]'`). See [`docs/INSTALL.md`](docs/INSTALL.md) for all the options.
+
 ## Why OKGF exists
 
 OKF makes knowledge **portable**: markdown plus YAML frontmatter, human- and agent-readable, diffable in
@@ -105,25 +131,28 @@ key is published out of band, so anyone can confirm the org really approved it,
 
 ## Get started
 
-Validate a bundle with the reference validator (Python plus PyYAML):
+With the `okgf` command [installed](#install), validate the example bundles:
 
 ```sh
-python tools/okgf_validate.py examples/minimal examples/governed
+okgf examples/minimal examples/governed
 ```
 
 Add `--pubkey` to cryptographically verify signatures, and `--strict` to treat warnings as errors:
 
 ```sh
-python tools/okgf_validate.py --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
+okgf --strict --pubkey examples/governed/ORG_PUBKEY.pem examples/governed
 ```
 
-Run the tests:
+Developing on the validator? Install it editable and run the tests from a checkout:
 
 ```sh
-pip install -r requirements-dev.txt
+pip install -e ".[dev]"
 python -m pytest tests/ -q
 ```
 
+The historical `python tools/okgf_validate.py ...` entry point still works from a checkout; it is a
+thin shim over the package.
+
 ## Run a store
 
 To actually *use* OKGF, run the reference store: a knowledgebase you ingest into and retrieve from, where
@@ -149,8 +178,9 @@ See [`docs/STORE.md`](docs/STORE.md) for the full API and design.
 
 - **[`SPEC.md`](SPEC.md)** - the v0.1 specification, the additive delta over OKF field by field.
 - **[`CONFORMANCE.md`](CONFORMANCE.md)** - what conformance means and how to check it.
-- **[`tools/okgf_validate.py`](tools/okgf_validate.py)** - the reference validator, with optional Ed25519
-  signature verification.
+- **[`okgf/`](okgf/)** - the reference validator, installable as the `okgf` command (see
+  [`docs/INSTALL.md`](docs/INSTALL.md)), with optional Ed25519 signature verification.
+  [`tools/okgf_validate.py`](tools/okgf_validate.py) remains as a back-compat shim over it.
 - **[`store/`](store/)** - a runnable reference store: ingest, trust-filtered retrieval, the review
   lifecycle, and a zero-dependency HTTP API. See [`docs/STORE.md`](docs/STORE.md).
 - **[`examples/`](examples/)** - two bundles validated in CI: [`minimal/`](examples/minimal/) (OKF baseline,

SECURITY.md

@@ -5,9 +5,9 @@ matter and we take reports on both.
 
 ## Scope
 
-- **The reference validator** (`tools/okgf_validate.py`) - parsing untrusted bundles (YAML, tar-free but
-  file I/O), and signature verification. A bug that lets a malformed bundle crash, hang, or mislead the
-  validator is in scope.
+- **The reference validator** (the [`okgf/`](okgf/) package, run as the `okgf` command) - parsing
+  untrusted bundles (YAML, tar-free but file I/O), and signature verification. A bug that lets a malformed
+  bundle crash, hang, or mislead the validator is in scope.
 - **The trust model in the spec** - the `x-okgf-signature` scheme and the conformance rules. If you
   find a way a page could be treated as trusted when it should not be (or vice versa), that is a spec-level
   security issue and we want to hear it.

SPEC.md

@@ -117,6 +117,7 @@ Consumers MUST tolerate missing governance fields and MUST preserve unrecognized
 
 ## Implementation
 
-Reference validator: [`tools/okgf_validate.py`](tools/okgf_validate.py) in this repository checks
-single-page and whole-bundle conformance, including optional Ed25519 signature verification. This
-**specification** is Apache-2.0, so any tool may implement OKGF freely.
+Reference validator: the [`okgf/`](okgf/) package in this repository, installable as the `okgf`
+command (see [`docs/INSTALL.md`](docs/INSTALL.md)), checks single-page and whole-bundle conformance,
+including optional Ed25519 signature verification. This **specification** is Apache-2.0, so any tool
+may implement OKGF freely.

conftest.py

@@ -0,0 +1,11 @@
+"""Make a fresh source checkout importable as the ``okgf`` package during tests.
+
+The normal path is to install the package first (``pip install -e .``), which makes this a no-op.
+This hook additionally lets ``python -m pytest`` work straight from an uninstalled checkout by putting
+the repository root on ``sys.path``.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

docs/INSTALL.md

@@ -0,0 +1,77 @@
+# Installing the OKGF validator
+
+The reference validator ships as a small Python package named `okgf`. Installing it gives you an
+`okgf` command for validating OKGF pages and bundles. The validator depends only on PyYAML;
+cryptographic signature verification is an optional extra.
+
+## One-line install (recommended)
+
+No system Python required - this uses [uv](https://docs.astral.sh/uv/) to manage an isolated Python
+for the tool:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/OneHillAI/okgf/main/install.sh | sh
+```
+
+To also enable Ed25519 signature verification, set `OKGF_VERIFY=1`:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/OneHillAI/okgf/main/install.sh | OKGF_VERIFY=1 sh
+```
+
+Prefer to read before you run? The script is short: [`install.sh`](../install.sh). It falls back to
+`pipx`, and installs `uv` only if neither `uv` nor `pipx` is present.
+
+## Homebrew (macOS / Linux)
+
+```sh
+brew install OneHillAI/tap/okgf
+```
+
+## With pip, pipx, or uv
+
+If you already manage Python environments, install from PyPI directly:
+
+```sh
+pipx install okgf           # isolated, recommended for a CLI
+uv tool install okgf        # same idea, via uv
+python -m pip install okgf  # into the current environment
+```
+
+Add signature verification with the `verify` extra:
+
+```sh
+pipx install "okgf[verify]"
+```
+
+## Verify the install
+
+```sh
+okgf --version
+okgf --strict path/to/bundle
+okgf --strict --pubkey path/to/ORG_PUBKEY.pem path/to/bundle   # verify signatures
+```
+
+`python -m okgf ...` works identically to the `okgf` command.
+
+## Optional: signature verification
+
+Signature checks need the [`cryptography`](https://cryptography.io/) package, pulled in by the
+`verify` extra (`OKGF_VERIFY=1` for the one-line installer, or `pip install 'okgf[verify]'`). Without
+it, a page that carries an `x-okgf-signature` is still format-checked, but reported as unverified
+rather than trusted - the validator never claims a signature is valid when it cannot check it.
+
+## From a source checkout
+
+Working on the validator itself, or want to run it without installing?
+
+```sh
+git clone https://github.com/OneHillAI/okgf.git
+cd okgf
+python -m pip install -e ".[dev]"   # editable install with test + verify extras
+okgf --strict examples/minimal
+python -m pytest tests/ -q
+```
+
+The historical entry point `python tools/okgf_validate.py ...` still works from a checkout: it is a
+thin shim that re-exports the package, kept so older scripts and docs do not break.

examples/README.md

@@ -22,7 +22,7 @@ A fully governed bundle:
 Verify the signed promotion:
 
 ```sh
-python ../../tools/okgf_validate.py --pubkey governed/ORG_PUBKEY.pem governed
+okgf --pubkey governed/ORG_PUBKEY.pem governed
 ```
 
 The signature in `billing-model.md` was produced with an example-only key. Do not reuse it; a real