okf-harness

# OKF Harness full LLM context

> Generated from public repository documentation. Do not edit this file by hand. Run `pnpm docs:llms` after changing the source docs listed below.

OKF Harness is an agent-first, local-first, terminal-native harness for maintaining OKF-compatible LLM Wikis through supported agents.

OKF Harness is independent. It is not affiliated with or endorsed by Andrej Karpathy or Google, and it is not an official Open Knowledge Format implementation.

This file is meant for AI tools that need one public context bundle. It excludes private maintainer notes, generated release checks, local machine paths, and internal implementation documents.

## Source files

- README.md: Project README
- CONTEXT.md: Product terminology
- docs/WORKFLOWS.md: User workflows
- docs/CLI.md: CLI reference
- docs/ROADMAP.md: Public roadmap
- packages/cli/README.md: CLI package README
- packages/core/README.md: Core package README
- packages/agent-pack/README.md: Agent pack README
- packages/setup/README.md: Setup package README
- packages/native-integration/README.md: Native integration README

## Project README

Source path: `README.md`

### OKF Harness

[![CI](https://github.com/pumblus/okf-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/pumblus/okf-harness/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
[![Local terminal](https://img.shields.io/badge/platform-local%20terminal-lightgrey.svg)](docs/CLI.md)
[![BundleDex](https://bundledex.net/badge/okf-harness.svg)](https://bundledex.net/bundles/okf-harness/)

English | [中文](README.zh-CN.md)

An agent-first, local-first, terminal-native harness for maintaining OKF-compatible LLM Wikis.

OKF Harness is an independent open-source project built on two upstream ideas: Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern for agent-maintained living wikis, and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) for portable markdown knowledge bundles.

```text
source files or URLs
        |
        v
raw/sources + .okfh/manifest.jsonl
        |
        v
wiki/*.md with citations
        |
        v
supported agents use okfh evidence/read/graph
```

OKF Harness does not ask you to learn a new knowledge-base app. You run setup once for the agents you use, create one local workspace per knowledge domain, then ask your agent to add sources, maintain the wiki, and answer from it.

#### Origins

OKF Harness builds on:

- Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): the agent-maintained wiki pattern of index, log, linked pages, ingest, query, and lint.
- Google's [Open Knowledge Format announcement](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) and [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md): the markdown-plus-frontmatter bundle shape that keeps knowledge portable across tools.

Within that, OKF Harness draws two lines of its own:

- Change history lives in the workspace's git repository, not in the wiki. The wiki holds knowledge only.
- Harness checks the source trail — whether each citation really lands on the bytes of a registered source. It does not judge whether the wiki is right, and it does not require every sentence to carry a citation.

This repository is not affiliated with or endorsed by Andrej Karpathy or Google.

#### Install Once

The recommended installer script for your operating system runs universal setup.

If you're on macOS or Linux, run this script:

```bash
curl -fsSL https://okf-harness.dev/install.sh | sh
```

In Windows PowerShell, run this instead:

```powershell
irm https://okf-harness.dev/install.ps1 | iex
```

Already have Node.js 22 or newer?

```bash
npx @okf-harness/setup@latest
```

Normal use needs Node.js 22 or newer, the workspace recovery dependency checked by setup, and at least one supported agent integration. Repository development additionally needs `pnpm`.

OKF Harness is local-first, not air-gapped: workspace files stay on your machine, but the first use of each newly pinned runtime version fetches that runtime once from npm.

Setup detects supported agent clients and installs the selected native integrations. It does not install a global `okfh`; the unified host entrypoint resolves each workspace's pinned runtime through the launcher. Direct native install paths are available for users who already know their agent:

| Agent | Native install command |
|---|---|
| Claude Code | `claude plugin marketplace add pumblus/okf-harness && claude plugin install okf-harness@okf-harness` |
| Codex | `codex plugin marketplace add pumblus/okf-harness --json && codex plugin add okf-harness@okf-harness --json` |
| OpenCode | `opencode plugin @pumblus/okf-harness --global` |
| Pi | `pi install npm:@pumblus/okf-harness` |
| Hermes Agent | `hermes skills tap add pumblus/okf-harness && hermes skills install pumblus/okf-harness/okf-harness` |
| OpenClaw | `openclaw skills install @pumblus/okf-harness --global` |

On a compatible agent client outside the supported agent set? The [Agent Plugin install page](docs/AGENT-PLUGIN.md) documents the manual install paths.

Advanced direct CLI use is documented in the CLI reference. It does not write agent entrypoints.

After setup, use the same `okf-harness` entrypoint before and inside a workspace. Workspace-local guidance may add detail for supported agents, but it does not introduce another prefix.

The recommended parent folder is only a convention, not a hidden CLI default. On macOS or Linux, use `$HOME/Documents/OKF Harness`. On Windows PowerShell, use `$env:USERPROFILE\Documents\OKF Harness`. On Command Prompt, use `%USERPROFILE%\Documents\OKF Harness`.

#### Start With Your Agent

Use the OKF Harness entrypoint name exposed by the agent you already use. The entrypoint name is stable; the calling syntax belongs to the agent. Codex usually uses `$okf-harness`, Claude Code usually uses `/okf-harness`, and other native integrations expose the same entrypoint name through their own skill or plugin UI.

When copying a prompt below, replace the bracketed entrypoint with your agent's actual invocation.

```text
<okf-harness> Set up a workspace for my AI research notes in my Documents folder.
```

Use the same prefix inside the workspace:

```text
<okf-harness> Check this workspace and tell me whether it is ready.
```

The entrypoint can discover or select a workspace from a local workspace collection, repair supported workspace-local guidance, and route daily maintenance internally. It never claims a workspace-local adapter was installed when only the host integration is present.

For a transient diagnostic command:

```bash
npx --package @okf-harness/cli okfh doctor --json
```

This does not add a global `okfh` binary.

#### Common Next Steps

Add a source:

```text
<okf-harness> Add this PDF to my workspace, update the wiki with citations, then check the workspace again.
```

Ask a question:

```text
<okf-harness> What does my workspace say about LLM Wiki structure?
```

#### Why OKF Harness

Most personal knowledge tools make the app the center. OKF Harness makes the local folder the center:

- raw source material stays inspectable under `raw/sources/`
- synthesized knowledge lives in ordinary markdown under `wiki/`
- citations connect topic pages back to reference pages and source IDs
- `okfh --json` gives agents a deterministic tool surface
- the graph report is a local HTML file, not a hosted service

The recommended layout is one workspace per knowledge domain, research area, or privacy boundary. Keep them under a local `Documents/OKF Harness/` folder unless you have a reason to separate them.

The product stays narrow on purpose: local files, terminal-native commands, bounded evidence, bounded reads, and explicit provenance come first. Broader surfaces such as GUI, cloud sync, Obsidian helpers, source connectors, and vector retrieval belong in the roadmap only when they preserve those guarantees.

#### What It Does

- Initializes a local OKF Harness workspace.
- Installs supported workspace guidance for agents with workspace adapters.
- Registers files and URL pointers as raw sources.
- Produces ingest plans so an agent can update the wiki with citations.
- Prepares bounded evidence briefs from synthesized wiki pages before answers.
- Searches and reads synthesized wiki pages for debugging and bounded continuation.
- Checks OKF conformance and Harness lint findings.
- Generates a self-contained graph report.

#### What Happens Behind The Scenes

The host entrypoint invokes the version-independent launcher through your local shell; the launcher delegates to the exact runtime pinned by the workspace. For example:

- first setup resolves the workspace collection, confirms writes, runs workspace creation through an on-demand runtime, and returns agent context refresh guidance
- ingest delegates `source add` and `ingest plan` through the launcher
- answers use `okfh evidence`, then at most one bounded `okfh read` when a continuation cue is needed
- validation uses `okfh check`
- graph reports use `okfh graph`

Developers can call the CLI directly when they need to script or debug a workspace:

```bash
okfh check --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh search "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh read topics/llm-wiki --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

#### Troubleshooting

If the `okf-harness` entrypoint is missing, stale, or blocked by an unmanaged same-name skill, run:

```bash
npx --yes --package @okf-harness/cli@latest okfh doctor --json
```

`doctor` reports runtime, native integration, host entrypoint, and workspace checks separately. Use `okfh bootstrap status|repair --agents codex|claude|all --json` only as advanced fallback repair tooling for Claude/Codex; the primary setup workflow is setup plus the agent prompt above.

#### Docs

- [Workflows](docs/WORKFLOWS.md) explains the user-facing agent flows, including the first-start check.
- [CLI reference](docs/CLI.md) lists commands, options, and JSON behavior.
- [Roadmap](docs/ROADMAP.md) shows the current focus and demand-ranked ideas.
- [Example workspace](examples/ai-research-workspace/README.md) gives a small lintable workspace.
- [Contributing](CONTRIBUTING.md) explains project scope and verification.
- [Security](SECURITY.md) explains local data boundaries and reporting.

#### Development

```bash
pnpm install
pnpm docs:llms
pnpm test
pnpm typecheck
pnpm build
```

See [CONTEXT.md](CONTEXT.md) for the project glossary and [docs/adr](docs/adr) for architecture decisions.

#### Acknowledgements

Thanks to Andrej Karpathy for publishing the LLM Wiki pattern, and to Google for publishing Open Knowledge Format as a simple, portable shape for markdown knowledge bundles. OKF Harness adapts those ideas for a local, agent-first workflow.

Thanks also to Tw93's [Waza](https://github.com/tw93/waza) and Matt Pocock's [Skills for Real Engineers](https://github.com/mattpocock/skills) for shaping the development behind this project.

#### License

Apache-2.0. See [LICENSE](LICENSE).

## Product terminology

Source path: `CONTEXT.md`

### OKF Harness

OKF Harness is the product context for an agent-first, local-first, terminal-native harness that helps people maintain OKF-compatible local LLM Wikis through coding agents.

#### Language

**OKF Harness**:
A local harness for maintaining OKF bundles through Claude Code, Codex, and future coding agents. It builds on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing). It is an independent project around the format, not the OKF specification itself, an official implementation, a standalone knowledge-base application, or an Obsidian plugin.
_Avoid_: OKF app, Obsidian plugin, private agent runtime

**Public homepage**:
The first browser entry at `okf-harness.dev` that orients a new visitor, states the product boundary, and points to install, docs, and repository paths. It is a trusted first entry, not the full documentation site, installer implementation, release source, or product application.
_Avoid_: docs site, installer site, product app, full product website

**Harness**:
The deterministic support layer around an OKF bundle that gives agents reliable tools for setup, source registration, planning, validation, search, graph generation, and integration. It supports agent work but does not replace the agent or become a knowledge-base application.
_Avoid_: framework, platform, agent runtime

**Harness CLI**:
The `okfh` command-line tool that provides a deterministic tool surface for agent clients and developers. An agent-first knowledge worker should not need to learn CLI language for normal use; they should interact with OKF Harness through natural-language requests to an agent.
_Avoid_: user interface, primary workflow, app

**Command envelope (JSON envelope)**:
The machine-readable JSON contract every `okfh` command writes to stdout (`--json`) or stderr (errors): `ok`, `command`, optional `workspace`, `data`, `warnings`, `next`, and on failure `error`. It is the agent-facing API of the Harness CLI, bound by ADR-0001 and ADR-0037; human-readable output renders the same envelope, never a second contract.
_Avoid_: response format, output schema, JSON result wrapper

**Terminal-native tool channel**:
The default way an agent client operates OKF Harness by running explicit local shell commands, especially `okfh --json`, through the user's local terminal environment. This means local, observable, and debuggable command execution across supported operating systems; it does not require the user to learn CLI language.
_Avoid_: alternate default tool channel, OS-specific command channel, user-facing CLI workflow

**Prompt-first workflow**:
The normal user experience where a person asks Claude Code, Codex, or another agent client to maintain an OKF Harness workspace with an agent-facing prompt rather than CLI commands. The prompt may use a stable workflow prefix such as `$okf-harness` or `/okf-harness`, but the person should not need to learn `okfh` command names for ordinary setup, ingest, check, query, or maintenance work.
_Avoid_: CLI-first workflow, command tutorial, hidden app UI

**First useful loop**:
The first successful product journey where a person gets from a new or selected workspace to registered local source material, agent-synthesized wiki content, workspace check feedback, and one evidence-backed answer. It is not merely successful installation, an empty workspace, CLI-generated wiki content, or automatic webpage fetching.
_Avoid_: onboarding completion, first install, empty setup, auto-ingest, web crawl

**First-answer check**:
A short default question set used to prove the first useful loop after local source material is synthesized. It asks one sentence each for what the source is about, its key conclusions, and where the evidence comes from; user-facing next-step prompts should spell out those questions instead of relying on the term alone.
_Avoid_: full summary, report, benchmark question, broad review

**First-loop blocker**:
The specific step that prevents the first useful loop from completing, such as source registration, wiki synthesis, workspace check, or evidence-backed answering. It should be reported with one concrete next action rather than triggering automatic online search, source substitution, or broader scope.
_Avoid_: generic error, automatic recovery, silent scope expansion

**Unified agent entrypoint**:
The single OKF Harness workflow entrypoint exposed to an agent client, named `okf-harness`. It exists before a workspace is selected and keeps the same prefix inside one while routing setup, check, ingest, reconciliation, answer, and graph intents internally.
_Avoid_: multiple user-facing workflow skills, command menu, CLI alias

**Host-level entrypoint**:
The host-installed copy of the unified `okf-harness` skill. It invokes the runtime launcher, routes workspace creation when none resolves, and handles daily work inside a resolved workspace without implying that a workspace-local adapter was installed.
_Avoid_: workspace-local adapter, global runtime, bootstrap-only skill

**Workspace-local entrypoint**:
The high-frequency `okf-harness` entrypoint loaded from a specific OKF Harness workspace's agent guidance. It handles workspace operations such as check, ingest, answer, and graph after the workspace context is selected.
_Avoid_: global entrypoint, bootstrap command, workspace selector

**Internal workflow**:
An agent-guidance route behind the unified `okf-harness` entrypoint, such as setup, check, ingest, answer, or graph. Internal workflows keep guidance organized, but they are not separate user-facing skill names.
_Avoid_: user-facing skill, CLI command, separate product entrypoint

**Answer workflow**:
The internal agent workflow for answering a person's question from synthesized OKF bundle content by using deterministic search, bounded reads, and citations. It is named for the agent's job and should not imply an `okfh query` command or a black-box answer engine.
_Avoid_: query command, answer engine, raw-source search

**Agent context refresh**:
The handoff after setup or guidance changes where a person starts a fresh conversation in the current agent client so the client can load the new workspace guidance. The wording should match the agent client and operating-system conventions, using concrete local paths when known, without turning the handoff into a CLI tutorial.
_Avoid_: app restart, cache clear, manual reload ritual

**Self-report determination**:
The way the portable Agent Plugin distribution chooses the `--agents` target during setup or repair: the agent states which client it is running in, Claude Code and Codex map to those adapters, and any other client maps to `--agents none`. It replaces a hard-coded adapter identifier because no single identifier is true for every compatible client, and a wrong guess writes workspace-local guidance that misleads every later session while `none` can always be repaired afterwards.
_Avoid_: client detection, heuristic adapter guessing

**OKF**:
The external [Open Knowledge Format specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md): a minimal, human- and agent-friendly format for representing knowledge as markdown files with YAML frontmatter. OKF is a format, not this product.
_Avoid_: OKF Harness, Google wiki, knowledge app

**OKF bundle**:
A portable directory of OKF concept documents. It is the knowledge content that agents read and maintain, separate from product-specific workspace files.
_Avoid_: workspace, vault, repository

**OKF conformance**:
The minimum compatibility check that an OKF bundle follows the external OKF specification closely enough for tolerant OKF consumers to read it. It must describe standard-level requirements separately from OKF Harness quality preferences.
_Avoid_: Harness lint, product quality score, strict style check

**OKF version**:
The external OKF specification version used for a conformance check, such as `0.1`. Workspace check output should show it plainly so people know which standard version the result refers to.
_Avoid_: hidden default, product version, CLI version

**Bundle metadata**:
Non-concept frontmatter that describes an OKF bundle itself, such as `okf_version` on the bundle root `index.md`. It is not concept frontmatter and should not turn a reserved document into a concept document.
_Avoid_: concept metadata, Harness package metadata, wiki page metadata

**Concept document**:
A markdown file in an OKF bundle that represents one readable and linkable knowledge unit, such as a topic, entity, project, decision, question, or reference.
_Avoid_: note, wiki page, knowledge content

**Reference document**:
A concept document that records the origin, summary, key evidence, and citation relationships for one raw source. It is the evidence bridge between a raw source and other concept documents, not the raw source itself.
_Avoid_: source copy, source summary, attachment

**OKF Harness workspace**:
The operating-system-independent local directory managed by OKF Harness around one OKF bundle, its source material, agent guidance, and harness state. People may have multiple workspaces on one machine, usually one per knowledge domain, research area, or privacy boundary; this is product-specific and should not be confused with the OKF bundle itself. In prompt-first contexts where OKF Harness is already established, "workspace" can be used as the natural shorthand.
_Avoid_: OKF workspace, Obsidian vault, project repo, global knowledge base

**Workspace collection**:
The set of separate OKF Harness workspaces a person keeps on one machine. It is a loose local organization pattern that the host entrypoint may inspect from a parent folder, not a global database, registry, or synchronized account.
_Avoid_: global workspace, account, cloud library

**Workspace plan**:
The JSON-readable plan for creating an OKF Harness workspace: directories, files, placeholder agent guidance, post-create checks, and warnings. It is primarily for the Harness CLI and agent clients, not a document an agent-first knowledge worker must read directly.
_Avoid_: setup doc, user-facing checklist, installer script

**Workspace resolution**:
The way OKF Harness decides which local workspace a command should operate on, either from an explicit workspace path or by finding the nearest `okfh.config.yaml` from the current directory. Command output should expose the resolved workspace so agents and people can verify the target.
_Avoid_: current project guess, global default workspace, hidden app state

**Workspace runtime pin**:
The exact Harness runtime version a workspace records in the `runtime` block of its `okfh.config.yaml`, answering which code may write those files. It is separate from the workspace format version (`version: "0.1"`), which answers what shape the files are, so a runtime patch is not a format migration. The Harness runtime is its only writer; a workspace created before pins existed keeps working and adopts one in a single step without the person choosing a version.
_Avoid_: workspace format version, version range, dist-tag, user-chosen version

**Runtime launcher**:
The version-independent `launch` subcommand of universal setup that resolves an OKF Harness workspace, reads its workspace runtime pin, and delegates unchanged runtime arguments through `npx` to that exact Harness runtime version. It never writes the workspace, guesses a version, or falls back to a dist-tag; pin-less and invalid workspaces produce machine-readable outcomes for the agent to handle.
_Avoid_: Harness runtime, global runtime, workspace writer, version fallback

**Shadowing global runtime**:
A leftover global `okfh` executable or globally installed bootstrap package that can bypass workspace runtime pins. Universal setup offers one bounded cleanup command for these retired installs, and doctor warns until they are gone.
_Avoid_: workspace runtime pin, runtime launcher, native agent integration

**Source material**:
Original material that a person wants to bring into the knowledge base, such as a file, URL, markdown document, text snippet, or clipboard content. It is evidence for later synthesis, not the synthesized wiki content itself.
_Avoid_: data, document, note

**Raw source**:
The immutable registered copy or record of source material inside an OKF Harness workspace. Raw sources are for ingest and source-audit workflows, not normal answer workflows; if the material needs correction, a new raw source should be added rather than editing the old one.
_Avoid_: source material, wiki page, attachment

**URL source**:
A raw source record that preserves a URL as a traceable source pointer. It is not a fetched webpage snapshot; if a webpage version must be preserved, its content should be saved and registered as separate source material.
_Avoid_: webpage archive, fetched page, URL snapshot

**Source registration**:
The act of bringing source material under OKF Harness management by creating or reusing a raw source record. Registration preserves evidence identity; it is not the same as synthesizing knowledge into concept documents.
_Avoid_: import, upload, wiki edit

**Online source review**:
An explicit workflow where an agent searches, fetches, or previews public online material so a person can decide whether it should become source material. It is source acquisition support, not normal wiki query, background crawling, or automatic web ingestion.
_Avoid_: web search query, background crawler, raw-source-wide answer

**Source provenance**:
The non-sensitive traceability information that identifies where source material came from and how a raw source relates to it. Provenance should preserve evidence identity without exposing private local filesystem context.
_Avoid_: absolute file path, audit log, file metadata dump

**Source manifest**:
The append-friendly evidence register for raw sources in an OKF Harness workspace. It must be trustworthy as a whole; invalid entries are evidence integrity problems, not rows to silently ignore.
_Avoid_: cache, index, source list output

**Harness lint**:
The OKF Harness quality check for provenance, source and manifest integrity, source drift, index coverage, and maintainability signals around an OKF bundle. It can be stricter than OKF conformance, but it must not claim product preferences are OKF specification failures.
_Avoid_: OKF conformance, standard compliance, formatter

**Workspace check**:
The user-facing validation workflow that tells a person and their agent whether an OKF Harness workspace is standards-readable and maintainable. It reports OKF conformance and Harness lint together without making people choose between validation modes.
_Avoid_: lint command, formatter, developer-only validation

**Check status**:
The plain-language outcome of a workspace check: Ready, Needs attention, or Blocked. Blocked is reserved for OKF conformance hard failures; serious Harness lint findings should be surfaced as Needs attention unless they also make the OKF bundle non-conformant.
_Avoid_: exit code, lint severity, raw issue list

**Workspace next step**:
A person-facing concrete next action OKF Harness reports for a workspace's current state, especially to help a person continue the first useful loop. It is based on local, deterministic workspace facts such as check status, registered sources, and synthesized wiki content, and should be phrased so the person can hand it to their agent as the next request.
_Avoid_: state machine, onboarding progress, auto-fix, task list, semantic score

**Workspace recovery**:
The local capability that records completed workspace states and lets an agent list or revisit them through closed Harness verbs. It remains internal to workspace operation and stays outside the wiki and normal evidence path.
_Avoid_: backup product, wiki history, user-facing version control

**Workspace snapshot**:
The internal read-side mechanism by which the Harness loads a workspace once per command: resolved root, config, full wiki scan, source manifest, and reconciliation ledger, plus the deterministic facts derived from them. Read-side entry points load exactly one snapshot and thread it through, so every module observes the same workspace state and the wiki tree is scanned once per command; it is invisible to agents and never appears in command output.
_Avoid_: cache, index, session state, agent-visible read model

**Completion**:
A known-good full workspace state recorded when a maintenance cycle completes. It has an opaque completion id and stores only the non-reproducible judgment for that cycle; the initialization baseline is not a completion. `okfh history` lists completions newest first, and `okfh restore` steps back to one; history is recovery context, never citable evidence.
_Avoid_: individual write, intermediate edit, proposal, raw internal identifier

**Harness priority**:
The priority assigned to Harness lint findings inside a workspace check. High priority covers evidence integrity problems such as source drift, missing registered sources, or reference documents that cannot be tied to source records; medium priority covers maintenance gaps such as missing index entries; low priority covers tolerated navigation or cleanup issues such as broken links.
_Avoid_: check status, OKF conformance severity, raw issue code

**Suspected revision**:
A later raw source that Harness suspects revises an earlier one because the two registered copies share the same original filename but differ in content. The suspected-revision edge is the exact unit `okfh source reconcile` acknowledges; an acknowledgment covers that edge only, never a later revision.
_Avoid_: source update, blanket approval, drift label

**Source reconciliation**:
The agent-owned act of updating synthesized wiki content for a specific suspected source revision and recording that judgment through `okfh source reconcile`. Its acknowledgment applies only to that exact revision edge and never covers a later revision.
_Avoid_: source review, blanket approval, manual ledger edit

**Promoted source**:
A registered source the wiki has promoted: its source ID appears in the evidence links of the bundle's reference documents. Promotion is computed from the links Harness already walks, never declared on a page; the currency seal covers promoted sources only, and the promoted-source count is reporting only.
_Avoid_: wiki endorsement, freshness score, source ranking

**Currency seal**:
The Harness-computed guarantee inside a workspace check that every promoted raw source has no unreconciled suspected revision. The seal is positive only when workspace validation has no error findings and no promoted source has a dangling reconciliation; otherwise the check reports the workspace as not sealed with deterministic diagnostics rather than a false seal. Currency is a report, never a write gate, and never changes the check status or exit code.
_Avoid_: freshness score, agent-claimed currency, write gate, version ranking

**Consumption seal**:
The Harness-computed refusal at the evidence answer layer when physical source damage is anchored by a missing source, changed source hash, or reference to an unregistered source, or when an invalid config or source manifest leaves no trustworthy chain. Anchored seals withhold the affected reference document and concepts that cite it directly; unanchored seals withhold every concept document. Each seal records the factual basis and never blocks writes, changes check status, or recommends a repair.
_Avoid_: currency seal, workspace lock, write barrier, automatic repair, semantic contamination analysis

**Ingest**:
The workflow of registering source material, planning how it should affect the knowledge base, and having an agent synthesize it into the OKF bundle. Ingest is not a promise that the CLI automatically writes final wiki content.
_Avoid_: import, upload, summarize, auto-ingest

**Ingest plan**:
A deterministic work plan that tells an agent how a raw source may relate to existing concept documents before synthesis begins. It is guidance for agent work, not source reading, a complete search result, or an automatic wiki rewrite.
_Avoid_: search result, summary, source digest, auto-ingest output

**Suggested new concept**:
A proposed concept document named by an ingest plan from source metadata when registered source material does not clearly match an existing concept. It is a prompt for agent or user confirmation, not a file created by the CLI or a claim of source understanding.
_Avoid_: auto-created concept, generated wiki page, semantic extraction

**Query**:
A user intent to get an answer from an OKF bundle by finding and reading relevant concept documents, then following cited reference documents when factual precision matters. Query is not an OKF Harness command or internal workflow, and it is not a raw-source discovery pass; registered source material that has not been synthesized into concept documents remains outside normal answers.
_Avoid_: query command, agent workflow, raw-source search, RAG, auto-ingest

**Evidence brief**:
The user-facing name for a bounded evidence package prepared before an agent answers from an OKF bundle. It is a temporary work packet for one question, not a durable collection that tries to gather all possibly relevant knowledge.
_Avoid_: evidence pool, answer, summary, RAG response

**Continuation cue**:
A bounded pointer that tells an agent exactly where it may continue reading after a read result or evidence brief is truncated or incomplete. It is not permission to search raw sources, browse online, or freely expand scope.
_Avoid_: next search, auto research, unbounded follow-up

**Write-back offer**:
The agent's one-clause offer to keep an answer the wiki could not supply, appended to the disclosure already owed when an evidence brief proves a coverage gap: no concept document matched the question. The no-match guidance string is the whole permission — no structured field and no write-back command — and the offer is ephemeral: an accepted offer writes one ordinary concept page and its index link, and an ignored one persists nothing. A sealed or truncated brief is not a gap and never carries the offer.
_Avoid_: save mode, write queue, proposal, auto-capture, conversation source

**Evidence sufficiency**:
The agent-owned judgment that an evidence brief and any bounded follow-up reads are enough to answer a person's question responsibly. OKF Harness can expose mechanical limits, but it should not claim semantic sufficiency.
_Avoid_: CLI confidence, harness answer score, automatic truth judgment

**Evidence item**:
A selected, bounded wiki excerpt included in an evidence brief with provenance and continuation metadata. It is an inspectable input for an agent answer, not a summary, confidence claim, or final answer.
_Avoid_: answer excerpt, confidence item, generated summary

**Candidate concept**:
A concept document surfaced as possibly relevant before its content is selected as evidence or updated during ingest. In ingest planning, candidate concepts are existing content pages that may be affected by a source, not reference documents.
_Avoid_: evidence item, answer excerpt, selected proof, reference document

**Search result**:
A candidate concept list that helps an agent decide which full concept documents to read. It may describe matched fields and hit counts, but it is not final evidence for an answer and should not be treated as a snippet-based search engine page.
_Avoid_: answer excerpt, evidence snippet, source digest

**Search miss**:
A query outcome where deterministic search finds no relevant concept documents in the OKF bundle. It means the synthesized wiki has no matching concept yet; it must not be presented as proof that registered source material contains no answer.
_Avoid_: no source evidence, knowledge base disproved it, raw source absence

**Index document**:
The reserved wiki document that acts as the OKF bundle's human-maintained navigation surface and orientation map. It should be read first to discover likely concept documents, but a homepage link is not by itself evidence or an importance ranking. Like other reserved documents, it may be read for orientation but is never presented as a concept.
_Avoid_: ranking source, concept document, search result

**Graph report**:
A local structure report that helps a person or agent understand links between concept documents in an OKF bundle. It is a maintenance and orientation aid, not an editing interface or standalone knowledge-base browser.
_Avoid_: GUI, graph editor, knowledge-base app

**Evidence link**:
A relationship from a synthesized concept document to the reference document or source ID that supports a factual claim. It is part of the wiki's traceability model; it does not turn raw source files into normal graph nodes.
_Avoid_: raw source node, attachment link, proof of truth

**Provenance trail**:
The walkable chain from a concept document through its citations and reference documents to registered source IDs. When a load-bearing claim in an answer rests on pages whose provenance payload is empty, the answer names where the trail ends instead of discounting the claim.
_Avoid_: raw source body, citation log, source dump

**Unanchored page**:
A concept page with no evidence links to a registered source, such as a page written back from a conversation. Zero anchors is legitimate and silent: no lint finding, no frontmatter marker, and no concept type record it. When a written-back page drew on unanchored pages, its prose names them as derived-from with plain links; that lineage is prose for the reader, never parsed metadata.
_Avoid_: forgotten citation, unverified claim, source-less claim

**Agent-first knowledge worker**:
A person who maintains a local knowledge base primarily by asking an agent to organize, query, and validate it, rather than by learning command-line workflows.
_Avoid_: developer, CLI user, Obsidian user

**Agent client**:
The user-facing client where a person talks to an agent, such as a desktop app or terminal interface. OKF Harness workflows should feel consistent across agent clients, with differences only where a client has different capabilities.
_Avoid_: agent, model, runtime

**Supported agent set**:
The agent clients OKF Harness actively considers for installation, native integration, documentation, and compatibility checks in a release. The current supported set includes Claude Code, Codex, OpenCode, Pi, Hermes Agent, and OpenClaw. Native-supported status is separate from default selection: OpenClaw requires explicit opt-in.
_Avoid_: all agents, model providers, future integrations

**Agent guidance**:
The workspace instructions and configuration that tell an agent how to operate OKF Harness safely and consistently. Agent guidance is product workflow metadata, not knowledge content, and it is kept layered so an agent loads only the guidance a workflow needs.
_Avoid_: schema, documentation, wiki content

**Agent adapter**:
The rendered set of agent guidance files for a specific agent client, such as Claude Code or Codex. An adapter translates shared OKF Harness workflows into the conventions that client can discover and use.
_Avoid_: agent client, plugin, integration

**Universal setup**:
The broad setup path for people who use multiple agent clients or do not know which agent integration they need. It detects supported agent clients and offers native integrations containing the unified host entrypoint without installing a global Harness runtime.
_Avoid_: CLI install, native plugin, workspace setup

**Setup plan**:
A user-readable proposal produced by universal setup before it writes agent integrations or workspace files. It names the detected agent clients, selected integrations, native install commands and verification actions, required runtime checks, and files or directories that would change.
_Avoid_: hidden install, onboarding state, CLI dry run

**Interactive agent selection**:
The universal setup step where OKF Harness automatically detects supported agent clients on the machine, then asks the person which detected or supported agent integrations to install. Supported clients missing from the machine stay visible as install-later options with their install commands, never as failures. Detection is automatic; choosing where OKF Harness is installed remains explicit.
_Avoid_: silent auto-install, manual agent discovery, adapter prompt

**Native agent integration**:
A distribution path that installs the unified host-level `okf-harness` entrypoint into an agent client. It has two forms: a host-specific form shaped to one client's own plugin, extension, skill, or package mechanism, and the portable Agent Plugin form, where one standards-conforming package serves every compatible client. It invokes the runtime launcher and remains distinct from a workspace-local adapter. Unless a sentence explicitly names the Agent Plugin form, "native agent integration" refers to the host-specific form.
_Avoid_: Harness runtime, custom agent runtime, workspace-local adapter

**Agent Plugin**:
The portable form of native agent integration, named for the external [Agent Plugins standard](https://agent-plugins.org/) it conforms to: a single directory with `plugin.json` at its root plus fixed component locations such as `skills/`, installable by every compatible agent client without a host-specific package shape. The bare word "plugin" stays avoided for OKF Harness's own artifacts, and the rejection of an internal plugin architecture (ADR 0039) is unchanged. The okf-harness Agent Plugin carries agent guidance as skills and invokes the runtime launcher; the Harness CLI is the runtime it delegates to, never part of the package.
_Avoid_: plugin (unqualified), extension, marketplace plugin, agent adapter

**Host probe**:
The shared internal mechanism by which universal setup, doctor, and refresh guidance locate host executables on PATH, run native integration probe commands, and detect shadowing global installs. One lookup policy answers the same "is this executable on the host" question in every surface, so setup and doctor cannot disagree about a machine; it is invisible to agents and never appears in command output.
_Avoid_: shell detection, PATH lookup, command runner

**Native integration verification**:
Evidence that a supported agent client recognizes the exact OKF Harness native agent integration from its canonical distribution source as installed and, when the client exposes integration-level activation, enabled. User-controlled activation of individual resources inside an installed integration is outside setup verification.
_Avoid_: install command completion, agent client detection, resource preference audit

**Native install command**:
The concrete command or short command sequence that installs an OKF Harness native agent integration through the agent client's own plugin, extension, skill, or package mechanism. Universal setup should show this command before running it so the person can audit what will change.
_Avoid_: hidden write, runtime command, workspace command

**Installer script**:
A convenience wrapper for universal setup that reduces copy-paste friction on a specific operating system. It should delegate product behavior to OKF Harness setup logic rather than becoming a separate implementation of agent detection or workspace management.
_Avoid_: package manager, agent integration, runtime

**Resolved setup version**:
The concrete OKF Harness setup version selected by a latest or version-pinned installer path at runtime. Installer output should show this version before making changes so the person can audit what release is being installed.
_Avoid_: hidden latest, package range, release promise

**Recommended install path**:
The default install path shown first to ordinary users. This is the operating-system installer script that launches universal setup; single-agent native install paths remain available below it for users who already know their preferred agent client.
_Avoid_: only install path, CLI install, advanced install

**Agent skill**:
A discoverable workflow instruction inside an agent adapter. The current user-facing skill is the unified `okf-harness` entrypoint, while setup, check, ingest, answer, and graph remain internal workflows. Retired workflow skills are backed up under `.okfh/backups/agent-skills/` during migration, never deleted outright.
_Avoid_: command, script, template

**Harness-managed guidance block**:
A clearly marked section inside a generated OKF Harness workspace's agent guidance file that OKF Harness may insert, replace, or remove without owning the rest of the file. It lets agent adapters update their own instructions while preserving user-written project guidance.
_Avoid_: full-file ownership, silent overwrite, prompt injection

**Release unit**:
The smallest body of committed work that warrants a versioned release: one or more complete feature arcs, each recorded in an ADR with its docs, tests, glossary, and install paths updated together. Release size (major, minor, or patch) is decided per case from the arcs' scope, not by calendar cadence or commit thresholds; version PRDs plan committed work but do not by themselves trigger releases.
_Avoid_: calendar release, commit threshold, milestone promise

## User workflows

Source path: `docs/WORKFLOWS.md`

### OKF Harness Workflows

English | [中文](zh-CN/WORKFLOWS.md)

OKF Harness is built for people who work through a supported agent. The CLI is still visible, but normal work starts with the agent.

The workflow follows Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and uses Google's [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) as the bundle format.

OKF Harness is independent and is not affiliated with or endorsed by Andrej Karpathy or Google.

#### Workspace Model

Create one workspace per knowledge domain, research area, or privacy boundary. Good examples:

- `~/Documents/OKF Harness/ai-research`
- `~/Documents/OKF Harness/company-strategy`
- `~/Documents/OKF Harness/personal-health-reading`

On Windows, use the same convention under `%USERPROFILE%\Documents\OKF Harness\...`.

Avoid one hidden global knowledge base. Separate workspaces make agent prompts clearer, keep private material apart, and make check/search output easier to trust.

#### Before You Start

Install OKF Harness once with the [README install instructions](../README.md#install-once), then continue with your agent below.

#### Start With Your Agent

Use the OKF Harness entrypoint name for your current agent. Codex usually uses `$okf-harness`, Claude Code usually uses `/okf-harness`, and other native integrations expose `okf-harness` through their skill or plugin UI.

The same prefix works before and inside a workspace:

```text
<okf-harness> Set up a workspace for my AI research notes in my Documents folder.
```

The entrypoint first invokes the launcher. If no workspace resolves, it discovers a shallow local workspace collection or creates a workspace after inferring the display name, target folder, and current agent. If a workspace resolves, it routes directly to check, ingest, reconciliation, answer, graph, or repair work. A missing runtime pin is handled by running the launcher's exact adopt command and retrying; no global `okfh` is required.

Workspace-local adapters remain available for Claude Code and Codex and may add workspace-specific guidance under the same name. Other native integrations keep using the host-level entrypoint for daily work; the skill does not claim that a workspace-local adapter was installed for them.

To verify first start end to end:

1. Run setup in a clean environment.
2. Open a supported agent.
3. Confirm `okf-harness` is discoverable.
4. Use it to create one empty workspace.
5. From inside that workspace, use the same prefix to run a check.

For readability, command blocks below show the delegated runtime's `okfh` form. The host skill never searches `PATH` for that command; it passes the same arguments through `npx @okf-harness/setup@latest launch`.

#### Add A Source

```text
<okf-harness> Add ~/Downloads/llm-wiki-note.md to this workspace, update the wiki with citations, then check the workspace again.
```

The agent should call:

```bash
okfh source add <path-or-url> --workspace <workspace> --json
okfh ingest plan <source-id-or-path> --workspace <workspace> --json
```

Then the agent reads the registered raw source, writes or updates reference and topic pages, updates indexes, runs check, and records the completed cycle with `okfh checkpoint --judgment "<why this cycle completed>"`.

Raw sources should not be edited in place. If a source needs correction, register a new source.

##### First Useful Loop

A first useful loop starts with local source material. Register a local file, let the agent synthesize wiki pages from that registered source, run `okfh check --workspace <workspace> --json`, then ask the first-answer check: what the source is mainly about, what its key conclusions are, and where the evidence comes from.

URL sources stay as source pointers. OKF Harness records the URL, but does not fetch webpage contents automatically.

`okfh status` and `okfh check` can return a Workspace next step in JSON `next`, and human-readable output can show it as `Next: ...`. Treat that line as the next prompt for your agent in this loop: add one local source file, save webpage content as a local file instead of relying on a URL pointer, update the wiki with citations, handle check findings, or run the first-answer check. The CLI reports the step; it does not fetch pages, repair findings, score content quality, or synthesize wiki pages for you.

#### Reconcile A Source Revision

```text
<okf-harness> Reconcile the revised research note with this workspace, update every affected wiki claim, and verify the workspace currency seal.
```

OKF Harness detects a suspected source revision when a later local source has the same original filename as an earlier registered file but different contents. If the revised local file is not registered yet, the agent first calls:

```bash
okfh source add <revised-path> --workspace <workspace> --json
```

If `check` already detected a registered suspected revision, skip that registration. In either case, the agent identifies the exact prior and revision records with:

```bash
okfh source list --workspace <workspace> --json
okfh check --workspace <workspace> --json
```

Using the returned source IDs and recorded paths, the agent reads both immutable registered copies and inspects the reference, concept, and index files promoted from or affected by them. It then edits every affected wiki claim to reflect the revision. Reconciliation means the wiki reflects the revision; merely inspecting both copies is not reconciliation. The CLI reports the revision but does not repair the wiki automatically.

After updating the wiki, the agent validates the edits, records its judgment for that exact prior-and-revision pair, and checks the currency seal again:

```bash
okfh check --workspace <workspace> --json
okfh source reconcile <prior-source-id> <revision-source-id> --note "<what changed in the wiki>" --workspace <workspace> --json
okfh check --workspace <workspace> --json
```

The first source ID must be the prior copy and the second its revision. The final `check` verifies that this pair is no longer pending; `data.currency.sealed` is `true` only when no other promoted source has a pending reconciliation and no validation error remains. Never edit registered files under `raw/sources/` or Harness-managed reconciliation state by hand. Once the wiki reflects the revision, the agent completes the cycle with `okfh checkpoint`.

#### Undo A Bad Change

```text
<okf-harness> What did we change recently, and can you undo the pricing rewrite?
```

The agent should call:

```bash
okfh history --workspace <workspace> --json
okfh restore <completion-id> --workspace <workspace> --json
```

`history` lists workspace completions newest first, each with an opaque completion id and the judgment recorded when that cycle completed. The agent reads those judgments to decide which completion you mean, then restores it; you describe the change in plain language and never pick an identifier yourself.

Restore reaches any completion, not only the most recent, so a change noticed several cycles late is still recoverable. The completions moved through stay listed afterwards, so the workspace can move back and forth. Restore refuses to run while the workspace has changes that are not part of a completion yet: complete or discard them first.

There is no `wiki/log.md`. Workspace history is computed from the workspace itself, so it never competes with the wiki for your attention and is never citable as evidence.

#### Ask A Question

```text
<okf-harness> What does my workspace say about LLM Wiki structure?
```

The agent should call:

```bash
okfh status --workspace <workspace> --json
okfh evidence "<question>" --workspace <workspace> --json
# optional, only when the evidence result includes a needed continuation cue:
okfh read <concept-id-or-path> --workspace <workspace> --offset <offset> --limit <limit> --json
```

There is no `okfh query` command in the current CLI. The agent prepares an evidence brief first, confirms that the returned question matches the request, follows at most one bounded continuation cue when needed, then answers or says that the evidence is missing, weak, truncated, or citation-poor. When a load-bearing claim rests on pages whose provenance payload is empty, the answer names that the knowledge came from conversation rather than an ingested source, so you always see where the provenance trail ends; the claim is not discounted.

Normal answers use synthesized `wiki/` content. The agent should not read `raw/` source bodies unless you explicitly ask for a source-audit or ingest workflow. `search` and `read` remain available for retrieval debugging, candidate inspection, and bounded continuation, but they are no longer the default first step for answering.

When the evidence brief proves that nothing in the wiki matched your question, the agent works the answer out from the conversation and may append one clause to the sentence that already tells you the wiki had no evidence: keep this answer? Saying yes writes one ordinary concept page plus its index link. Saying nothing writes nothing and persists nothing, and asking the same question later reopens the offer. The offer appears only on a proven coverage gap, so a withheld-evidence result or a brief that was merely truncated never produces one.

#### Maintain A Workspace

```text
<okf-harness> Check this workspace and tell me whether it is ready.
```

The agent should call:

```bash
okfh check --workspace <workspace> --json
```

`check` reports `ready`, `needs_attention`, or `blocked`. It keeps OKF conformance separate from Harness lint, so broken links or missing index entries do not become OKF specification failures. After any wiki edit, the agent should run check again and show the changed files.

#### Generate A Graph

```text
<okf-harness> Generate the local graph report for this workspace and tell me where the HTML file is.
```

The agent should call:

```bash
okfh graph --workspace <workspace> --json
```

Use `--open` only when you want the operating system to open the HTML report in the system default browser. In a Linux environment without a GUI or opener command, open the generated HTML file manually.

#### Repair Agent Support

If a workspace exists but the current agent does not discover OKF Harness guidance, ask through the same entrypoint:

```text
<okf-harness> Repair this workspace's OKF Harness support.
```

The agent should repair the current workspace-local adapter when one exists:

```bash
okfh agent install codex --workspace <workspace> --json
okfh agent install claude --workspace <workspace> --json
```

Use the command that matches the current workspace adapter. Use `all` only when you explicitly ask for both workspace adapters. Use `--force` only after reviewing conflicts. For native integrations without a workspace adapter, use setup or the host integration's repair flow instead.

#### Troubleshoot The Entrypoint

If the `okf-harness` entrypoint is missing, stale, or blocked by unmanaged same-name content, run:

```bash
npx --yes --package @okf-harness/cli@latest okfh doctor --json
```

`doctor` reports runtime, native integration, host entrypoint, and workspace checks separately. Use `okfh bootstrap status|repair --agents codex|claude|all --json` as advanced Claude Code and Codex fallback repair tooling, not as the primary setup workflow.

#### What Goes Where

```text
raw/inbox/        temporary place to drop unregistered material
raw/sources/      registered raw sources, treated as immutable
wiki/             synthesized OKF markdown concept documents
.okfh/manifest    source register with hashes and source IDs
.okfh/reports/    generated reports such as graph.html
AGENTS.md         workspace guidance when the Codex adapter is installed
CLAUDE.md         workspace guidance when the Claude Code adapter is installed
```

#### Design Restraint

OKF Harness keeps the workflow local, inspectable, and easy to debug from normal terminal commands. Agent answers are built from synthesized `wiki/` evidence briefs plus bounded continuation reads when needed, while broader product surfaces such as GUI, cloud sync, source connectors, vector retrieval, and Obsidian helpers stay on the roadmap until they can preserve those guarantees.

## CLI reference

Source path: `docs/CLI.md`

### OKF Harness CLI

English | [中文](zh-CN/CLI.md)

The npm package is `@okf-harness/cli`. It installs the `okfh` command and the longer `okf-harness` alias. Documentation uses `okfh`.

#### Run Directly

Most users should use the recommended setup flow in the [README](../README.md). Workspaces run their pinned package version through the launcher. For a transient diagnostic:

```bash
npx --package @okf-harness/cli okfh doctor --json
```

This does not add a global `okfh` binary.

Requirements for normal use:

- macOS, Windows, or Linux
- Node.js 22 or newer
- workspace recovery dependency (checked by setup or `okfh doctor --json`)
- npm access when a pinned runtime version is first fetched

Repository development additionally requires `pnpm`; check that environment with `okfh doctor --dev --json`.

Normal first setup should start from `@okf-harness/setup` or a native agent integration. Universal setup shows each selected integration's read-only verification commands and expected identity, then succeeds only when every final state is `verified`; `failed` and `unavailable` states exit nonzero. `--dry-run` shows the same plan without probing. Direct CLI use does not write the unified host entrypoint.

#### Workspace Rules

Use one workspace per knowledge domain, research area, or privacy boundary. The recommended parent folder is only a documentation convention. OKF Harness does not resolve a hidden global workspace from it.

| Environment | Recommended parent folder |
|---|---|
| macOS or Linux shell | `$HOME/Documents/OKF Harness` |
| Windows PowerShell | `$env:USERPROFILE\Documents\OKF Harness` |
| Windows Command Prompt | `%USERPROFILE%\Documents\OKF Harness` |

Most commands resolve a workspace from `--workspace <path>` or by finding the nearest `okfh.config.yaml` from the current directory. Source-changing commands require an explicit workspace path so files are not registered into the wrong folder.

#### JSON Shape

Commands that support `--json` return the same envelope:

```json
{
  "ok": true,
  "command": "status",
  "workspace": "/absolute/workspace/path",
  "data": {},
  "warnings": [],
  "next": []
}
```

Failures use the same shape with `ok: false` and an `error` object. Agent guidance should rely on this JSON contract rather than parsing human terminal output.

For workspace `status` and `check`, `next` reports the top-priority Workspace next step when one is available. This is person-facing guidance for what to ask the agent to do next, not a new command, machine-readable state code, or menu.

#### Commands

##### doctor

Checks the running CLI, Node.js, the workspace recovery dependency, runtime platform, native host CLI detection, unified host entrypoint status, and workspace readiness when a workspace can be resolved. `pnpm` is required only for repository development and is checked by `--dev`.

```bash
okfh doctor --json
okfh doctor --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh doctor --dev --json
```

`doctor` does not write files. For a pin-less workspace, the `workspace-runtime-pin` check reports `details.adoptCommand` as an exact executable-and-arguments object that runs `@okf-harness/cli@0.8.1` through `npx`; it does not require a global `okfh`.

In JSON output, `data.checks` remains the flat compatibility list. `data.groups` separates `runtime`, `nativeIntegrations`, `legacyBootstrapFallback`, and `workspace` checks. The historical `legacyBootstrapFallback` key reports the Claude Code and Codex host entrypoints. `nativeIntegrations` keeps `native-host-cli-*` detection separate from `native-integration-*` verification: a missing host CLI skips verification, a verified integration passes, and a failed or unavailable verification warns without failing the overall doctor run. Probe diagnostics identify the client, command, outcome, stable reason, expected identity, and relevant exit code, never raw host output.

##### init

Creates a workspace and optionally renders workspace-local adapter files. The current CLI workspace adapters are `codex` and `claude`; native agent integrations are installed through setup or their host package surfaces and do not imply `okfh init --agents` support.

```bash
okfh init "$HOME/Documents/OKF Harness/ai-research" --name "AI Research" --agents codex --json
okfh init "$HOME/Documents/OKF Harness/ai-research" --name "AI Research" --agents claude --json
```

Options:

- `--name <name>` is required.
- `--agents codex|claude|all|none|claude,codex` is required and controls adapter rendering.
- `--dry-run` returns the planned writes without creating files.

Workspace recovery is established automatically and remains internal. Use the adapter for the workspace-local agent you are currently setting up: `codex` for Codex or `claude` for Claude Code. Use `all` only when you explicitly want both workspace adapters. Use `none` only for advanced or developer setup.

##### history

Lists workspace completions newest first. Each completion contains an opaque completion id and its stored judgment. A new workspace has no completions, so it returns an empty list and exits successfully.

```bash
okfh history --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

The JSON payload is `data.completions`, with entries shaped as `{ "id": "...", "judgment": "..." }`.

##### checkpoint

Creates a durable completion at the end of a maintenance cycle, storing only the judgment that summarizes why the completion happened. Everything else about the completion is computed from the workspace when needed. Workspaces created before workspace recovery became automatic adopt it on their first checkpoint.

```bash
okfh checkpoint --judgment "Folded the source revision into the wiki." --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

- `--judgment <text>` is required and must be non-blank.

The JSON payload is `data.completion`, shaped as `{ "id": "...", "judgment": "..." }`. The completion then appears in `okfh history`.

##### restore

Steps the workspace back to the state at a prior completion, addressed by the opaque completion id from `okfh history`. Restore reaches any completion, not only the latest, and the completions moved through remain listed in `okfh history`, so you can move back and forth. Restore refuses to run while the workspace has changes that are not part of a completion yet.

```bash
okfh restore <completion-id> --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

The JSON payload is `data.completion`, the completion the workspace was restored to.

##### agent install

Installs or repairs workspace-local adapter files in an existing workspace. This command currently covers the `codex` and `claude` adapters.

```bash
okfh agent install codex --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh agent install claude --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh agent install all --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

Use the current workspace adapter by default. Use `all` only when you explicitly want both workspace adapters. Use `--dry-run` to inspect planned writes. Use `--force` only after reviewing conflicts.

##### bootstrap

Advanced diagnostic and repair tooling for the unified host-level `okf-harness` skill in Claude Code and Codex. The command name remains for compatibility; normal setup starts from `@okf-harness/setup` or a native agent integration.

```bash
okfh bootstrap install --agents codex --json
okfh bootstrap install --agents claude --json
okfh bootstrap install --agents all --json
okfh bootstrap status --agents codex --json
okfh bootstrap repair --agents codex --json
okfh bootstrap uninstall --agents codex --json
```

Use `--agents codex`, `--agents claude`, or `--agents all`. `status` reports `missing`, `installed`, `version-drifted`, `unmanaged-conflict`, or `unwritable-target`. `install` and `repair` create or update the managed `okf-harness` host skill and remove the retired managed `okf-harness-bootstrap` directory. They refuse unmanaged same-name content and report unreadable or unwritable host targets instead of throwing. `uninstall` removes only managed host files. Use `--dry-run --json` with write-capable actions to inspect planned writes or removals.

##### status

Reports workspace initialization, wiki file count, concept count, concise check state, available capabilities, and a Workspace next step through the existing `next` field.

```bash
okfh status --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

When human-readable output has a next step, `status` shows the first one as `Next: ...`. In the current CLI, `evidence`, `search`, `read`, and `graph` are available. There is no `okfh query` command.

##### check

Checks OKF conformance and OKF Harness maintainability.

```bash
okfh check --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

`check` returns one of three statuses under `data.status`:

- `ready`: OKF conformance passes and Harness lint has no findings.
- `needs_attention`: OKF conformance passes, but Harness lint found maintainability or evidence-integrity issues.
- `blocked`: OKF conformance fails and the workspace is not OKF-readable.

The JSON response reports the OKF version as `data.okfVersion`, currently `0.1`. It keeps OKF conformance in `data.okfConformance`, Harness lint in `data.harnessLint`, and the promoted-source reconciliation seal in `data.currency`. Currency is informational and does not affect status or the exit code. `data.currency.sealed` is `true` only when workspace validation has no error findings and no promoted source has a dangling reconciliation; otherwise it is `false` and `data.currency.diagnostics` lists the deterministic error codes. `data.currency.promotedSources` counts the sources the wiki has promoted; it is reporting only and never enters the seal. The human view shows `Currency: sealed` when promoted sources are present and reconciled, `Currency: no promoted sources to reconcile` when the workspace has promoted none, or `Currency: not sealed (...)` with the implicated source filenames or diagnostic codes; a check envelope that carries no currency verdict renders `Currency: no currency verdict` instead of implying a pass.

`check` uses the same Workspace next-step decision as `status` and reports it through the existing top-level `next` field. When human-readable output has a next step, `check` shows the first one as `Next: ...`.

`ready` and `needs_attention` return top-level `ok: true` and exit `0`. `blocked` returns top-level `ok: false` and exits non-zero.

##### adopt-runtime

Records the running Harness runtime's version as the workspace runtime pin, the exact runtime version allowed to write the workspace. It takes no version argument: `okfh init` already stamps new workspaces, and this command records one into a workspace created before pins existed.

```bash
okfh adopt-runtime --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh adopt-runtime --workspace "$HOME/Documents/OKF Harness/ai-research" --dry-run --json
```

The JSON payload reports `data.runtime.version` and `data.state`, one of `recorded`, `already-pinned`, or `would-record`. An already-pinned workspace is left untouched, so the command is safe to rerun, and `--dry-run` reports the pin it would record without writing. A pin is an exact version in the `runtime` block of `okfh.config.yaml`, separate from the top-level `version` key, which stays the workspace format version. A malformed pin or an unreadable config is reported as `CONFIG_INVALID` and nothing is written. `okfh doctor` reports the pin, or reports it missing with this command in the check details, and never fails the run over it.

##### source add

Registers a local file or URL pointer as source material.

```bash
okfh source add ~/Downloads/paper.pdf --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh source add https://example.com/article --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

File sources are copied under `raw/sources/YYYY/MM/` and recorded in `.okfh/manifest.jsonl` with a SHA-256 hash. URL sources record the URL as a source pointer. The current CLI does not fetch webpage contents automatically.

Use `--dry-run` to see the planned source record without writing.

##### source reconcile

Records that an agent has reconciled one suspected source revision.

```bash
okfh source reconcile src_20260615_0001 src_20260615_0002 --note "Updated affected concept documents for the revision." --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

The first source id is the prior source and the second is its revision. `--note` is required and records the agent's judgment. Successful JSON output returns the recorded entry as `data.acknowledgement`. The manifest must support that exact suspected-revision edge; an acknowledgment does not cover a later revision.

##### source list

Lists registered source records.

```bash
okfh source list --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

##### ingest plan

Creates a deterministic checklist for how an agent should synthesize a registered source into the wiki.

```bash
okfh ingest plan src_20260615_0001 --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

The plan uses metadata only. The agent must read the source before writing semantic wiki content.

JSON data includes:

- `recommendedReferencePath`: the reference document path for the registered source.
- `candidateConcepts`: up to five existing non-reference content pages that may be affected by the source. Candidates include `id`, `path`, `type`, optional `title`, and a mechanical `reason`; they do not include confidence or semantic relevance scores.
- `suggestedNewConcept`: omitted when it does not apply. When present, it is one metadata-derived `Topic` suggestion with `title`, `path`, `type`, and `reason`. The CLI does not create the file.
- `nextStep`: one person-facing handoff prompt for the agent.

##### search

Searches synthesized wiki concept documents. It does not search raw sources.

```bash
okfh search "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh search "type:Topic LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --limit 20 --json
```

Supported filters:

- `type:<value>`
- `tag:<value>`
- `path:<prefix>`

Search results are candidate cards, not final evidence. Use `evidence` before answering.

##### evidence

Prepares a bounded evidence brief from synthesized wiki concept documents. It does not answer the question and does not search raw sources.

```bash
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --budget compact --json
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --max-chars 120000 --json
```

Options:

- `--budget compact|standard|large` selects a deterministic evidence-text character budget. Use compact around 256k, standard around 400k, and large around 1M when either the model or agent client has that context window. These are selection guides, not token estimates or guarantees that the full JSON fits a context window.
- `--max-chars <number>` overrides the preset with an explicit evidence-text character limit.

The JSON data echoes the question and returns `budget`, selected `evidence`, thin `candidates`, `seals`, `limits`, and short `guidance`. Empty evidence is successful when the workspace is readable: an ordinary miss includes `NO_MATCHES`, while a fully sealed result keeps `ok: true` without returning the damaged documents.

On the no-match result only, `guidance` carries one extra string permitting the agent to offer to write the answer back into the wiki as one concept page. Its presence is the whole permission; there is no structured write-back field and no write-back command. A fully sealed result, a truncated brief, and an ordinary match do not carry it, so an offer can never route around a seal or duplicate a page the wiki already holds.

When a registered source is missing, its hash has drifted, or a reference names an unregistered source, evidence withholds that reference document and concepts that cite it directly. Concepts that cite only a sealed concept remain available. Sealed documents are also excluded from `candidates`, so unrelated documents in the same workspace can still be returned. If an invalid config or broken source manifest makes those chains uncomputable, evidence withholds every concept document instead. OKF conformance findings continue to produce a blocked result.

Each `seals` entry carries the condition `code`, affected concept IDs under `sealed`, and a factual `basis`. Anchored seals also carry `sourceId` and `sourcePath` when registered; workspace-wide seals omit both source fields. Seals contain no repair advice. Human output shows the same seal fields. `limits` now reports only mechanical boundaries such as no matches or truncation; these source-integrity conditions are carried by `seals`, not `WORKSPACE_RISK`.

The agent decides whether the remaining evidence is enough to answer. Evidence items include provenance pointers under `provenance`: citations, citation issues, reference pages, source IDs, and safe source-manifest metadata. Normal answer workflows use the synthesized `wiki/` excerpts returned by evidence and do not read `raw/` source bodies.

When an evidence item is truncated, its `range` includes `contentLength`, `returnedChars`, and `truncated`, and `continuationCues` gives a bounded `okfh read` command with `--offset` and `--limit`. Use search and read as lower-level tools for retrieval debugging, candidate inspection, or one bounded continuation.

##### read

Reads a bounded OKF wiki document by concept ID, path, or `index`.

```bash
okfh read index --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh read topics/llm-wiki --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh read wiki/topics/llm-wiki.md --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

Options:

- `--section <heading>` reads a section by heading.
- `--section-id <id>` reads a stable section ID.
- `--offset <number> --limit <number>` reads a range.
- `--full` explicitly asks for a full bounded read.

When content is truncated, the JSON response tells the agent how to continue.

`wiki/log.md` is not part of a workspace and `log` is not a read target. Workspace history is not wiki knowledge, so it is never citable evidence; use `okfh history` instead. A workspace scaffolded before the removal may still carry the file, but it stays unreadable.

##### graph

Builds backlink data and a self-contained local HTML report.

```bash
okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --open --json
```

The report is written under `.okfh/reports/graph.html`. The graph does not upload data.

`--open` asks the operating system to open the report in the system default browser or HTML handler. On Linux environments without a GUI or opener command, OKF Harness still writes the report and returns a clear error telling you to open the HTML file manually.

#### Exit Behavior

Successful commands return exit code `0`. Validation, workspace, or source command failures return a non-zero exit code and include `ok: false` in JSON when `--json` is present. For `check`, `ready` and `needs_attention` exit `0`; `blocked` exits non-zero.

#### Developer Install From Source

For repository development:

```bash
pnpm install
pnpm build
node packages/cli/dist/main.js doctor --json
```

## Public roadmap

Source path: `docs/ROADMAP.md`

### OKF Harness Roadmap

English | [中文](zh-CN/ROADMAP.md)

This is the public product roadmap for OKF Harness. Roadmap items are not release promises. Ideas move into committed work only after they have a clear user story, safety boundary, and verification path.

#### Positioning

OKF Harness is an agent-native, file-contract-first, no-app-required knowledge harness.

It is an independent project that builds on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

It is not affiliated with or endorsed by Andrej Karpathy or Google.

The key difference from full desktop LLM Wiki applications is deliberate: OKF Harness does not try to become the primary knowledge-base app. A person keeps working in a supported agent client; the harness provides a transparent local workspace, deterministic CLI, bounded evidence, bounded reads, lint, and graph reports around ordinary markdown files.

This means OKF Harness should compete on:

- Agent-native workflows instead of a bundled desktop GUI.
- Inspectable markdown and JSON contracts instead of hidden app state.
- Bounded evidence and explicit provenance instead of unbounded context stuffing.
- Local-first, auditable operation through `okfh --json`.
- Optional integrations that never replace the default terminal-native workflow.

#### Roadmap Restraints

- User-facing docs should lead with natural-language prompts to agents, not command tutorials.
- Answers are based on bounded evidence from synthesized `wiki/` content, not raw-source-wide discovery.
- There is no `okfh query` or LLM answer command; agents prepare evidence briefs, then answer from the returned evidence and disclosed limits.
- Search returns candidate concept documents, not answer evidence, and remains a lower-level debugging tool.
- Read output is bounded by default, with explicit continuation options for evidence follow-up.
- Graph reports show concept links and evidence links; raw source files remain metadata, not graph nodes.
- GUI, cloud sync, accounts, vector search, RAG, automatic web crawling, and Obsidian runtime code stay in demand buckets until they can preserve the local, inspectable workflow.

#### High Demand

##### Agent Adapter Expansion

Goal: support additional agent clients and deepen current integrations without weakening the default local-shell model.

Candidates:

- Workspace-local adapters for native integrations that currently provide only the host-level entrypoint.
- Adapter conformance tests shared across clients.
- Improved supported-agent detection as each new adapter is added.
- Investigation for Cursor, VS Code, Aider, Goose, Continue, and GitHub Copilot coding agent.
- Universal setup install offers and doctor recognition for Agent Plugins–compatible clients beyond the supported agent set (VS Code, Cursor, GitHub Copilot CLI, Kiro), building on the portable Agent Plugin form of the OKF Harness native agent integration. Until this lands, those clients follow the documented manual install paths.

Constraint: new adapters must preserve the same workflow contracts as supported agents. They should not force a private runtime into the default product path.

#### Medium Demand

##### Source Connectors

Goal: let users bring source material from common work tools while preserving provenance and explicit user control.

Candidate idea: Feishu / Lark support.

Possible shapes:

- Register a Feishu document URL as a URL source pointer.
- Export a Feishu document to markdown or PDF, then register the exported file as source material.
- Provide a connector workflow that fetches content only after explicit user authorization.

Questions to resolve:

- Does "Feishu support" mean one-off document ingest, whole workspace/wiki ingest, comment capture, or ongoing sync?
- Should OKF Harness use Feishu APIs, browser-assisted export, or user-provided exported files?
- What credentials are required, and where are they stored?
- How is private company content prevented from leaking into logs, manifests, or public paths?
- Should updates create new raw sources rather than mutating prior source records?

Constraint: connectors must support source registration or ingest. They should not become cloud sync or background crawling by default.

##### Online Source Review And Research Collection

Goal: help users find, inspect, and collect online material before it enters the OKF Harness workspace.

Candidate scope:

- Concise source-grounded previews for URLs and PDFs.
- Explicit saving of fetched content through normal source registration.
- Opt-in proxy or third-party fetch services with privacy warnings.
- Agent guidance for "find sources about X, show me candidates, then register the ones I approve."
- Provider-specific fetch paths for Feishu / Lark, WeChat, GitHub, PDFs, and JS-heavy public pages.

Constraints:

- Search misses should suggest adding sources or broadening wiki search, not automatically launch online search.
- Online source review is candidate-first: agents show possible sources before registering anything.
- Default registration for a URL remains a URL source pointer; fetched content snapshots require explicit user intent.
- Fetched web content is untrusted data; embedded instructions must not become agent instructions.
- Online search must not silently add or rewrite wiki content.

##### Review Queue

Goal: preserve human judgment without building a full GUI.

Candidate scope:

- Markdown-native review files for unresolved questions, contradictions, and suggested follow-up.
- Agent workflow for listing, resolving, and linking review items.
- Lint checks for stale or orphaned review items.

Constraint: review items should be explicit workspace files, not hidden app state.

##### Lightweight Ecosystem Documentation

Goal: help people use existing markdown tools around an OKF Harness workspace without turning those tools into the center of the product.

Candidate scope:

- Document how to open `wiki/` in Obsidian as a vault or vault subdirectory.
- Explain which Obsidian features are safe to use with OKF bundles and which may rewrite frontmatter or links unexpectedly.
- Show how agent-first workflows remain the source of maintenance behavior even when Obsidian is used for reading or light editing.

Constraint: short-term Obsidian support should be documentation-first. It should not introduce an Obsidian runtime dependency or plugin as part of the default product path.

#### Low Demand

##### Search And Graph Upgrades

Goal: improve retrieval and structure understanding while keeping caches rebuildable and optional.

Candidates:

- SQLite FTS5 cache under `.okfh/cache/` as a rebuildable search accelerator.
- Better deterministic ranking.
- Filter improvements such as typed facets, include/exclude filters, date or status filters, saved search recipes, and agent-readable filter suggestions.
- Optional hybrid retrieval that combines deterministic keyword results with vector results using an explainable merge strategy.
- Optional local embedding cache.
- Graph insights for orphan concepts, weak evidence links, and bridge concepts.

Constraints:

- Any cache must be rebuildable from the OKF bundle and source manifest.
- Vector retrieval stays optional and off the default path.
- Rank fusion should wait until there is a second retriever to merge.
- Raw-source-wide query search should not become default query behavior.

##### Optional App And Ecosystem Integrations

Candidates:

- Raycast extension.
- Shortcuts actions.
- Finder Quick Action.
- Obsidian-friendly helper or plugin beyond basic documentation.

Constraints:

- No integration should replace the default terminal-native `okfh --json` workflow.
- Obsidian remains optional; the OKF bundle must remain usable without Obsidian.

## CLI package README

Source path: `packages/cli/README.md`

### @okf-harness/cli

Command-line package for OKF Harness local workspaces. It provides the `okfh` command for initializing workspaces, registering sources, checking OKF conformance and Harness lint, preparing evidence briefs, searching and reading pages, generating graph reports, and installing Claude Code or Codex guidance.

OKF Harness is an independent open-source project built on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

Most users should start from the recommended setup flow in the main README. Workspaces pin this runtime package exactly, and the host skill resolves it on demand through `@okf-harness/setup`.

Try a transient diagnostic without a global install:

```bash
npx --package @okf-harness/cli okfh doctor --json
```

Runtime requirements are macOS, Windows, or Linux; Node.js 22 or newer; the workspace recovery dependency checked by `okfh doctor --json`; and this package. Repository development additionally requires `pnpm` and can be checked with `okfh doctor --dev --json`.

Direct CLI use does not write the unified host entrypoint. Use `@okf-harness/setup` or a native agent integration for ordinary setup, and use `okfh doctor --json` or the compatibility-named `okfh bootstrap` only for diagnostics or advanced fallback repair.

Common commands:

```bash
okfh init "$HOME/Documents/OKF Harness/ai-research" --name "AI Research" --agents codex --json
okfh history --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh check --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh source add ~/Downloads/paper.pdf --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh ingest plan <source-id> --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh evidence "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh search "LLM Wiki" --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh read topics/llm-wiki --workspace "$HOME/Documents/OKF Harness/ai-research" --json
okfh graph --workspace "$HOME/Documents/OKF Harness/ai-research" --json
```

On Windows PowerShell, use `$env:USERPROFILE\Documents\OKF Harness` for the workspace parent folder. On Command Prompt, use `%USERPROFILE%\Documents\OKF Harness`.

OKF Harness keeps raw sources under `raw/sources/`, synthesized knowledge under `wiki/`, source records in `.okfh/manifest.jsonl`, and generated reports under `.okfh/reports/`.

For project overview, workflows, security notes, and LLM-readable context, see the [main repository README](https://github.com/pumblus/okf-harness#readme) and [llms.txt](https://github.com/pumblus/okf-harness/blob/main/llms.txt).

## Core package README

Source path: `packages/core/README.md`

### @okf-harness/core

Core library for OKF Harness workspace parsing, config loading, manifest handling, path safety, linting, search, graph generation, and source registration.

OKF Harness is an independent open-source project built on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

Most users should start from the recommended setup flow in the main README. Advanced transient CLI use belongs in the CLI package docs.

For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).

## Agent pack README

Source path: `packages/agent-pack/README.md`

### @okf-harness/agent-pack

Adapter renderer package for OKF Harness agent guidance. It renders shared Claude Code and Codex instructions from one source so workspace setup stays consistent across supported agents.

OKF Harness is an independent open-source project built on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

Most users should start from the recommended setup flow in the main README. Advanced transient CLI use belongs in the CLI package docs.

For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).

## Setup package README

Source path: `packages/setup/README.md`

### @okf-harness/setup

Universal setup planner for local OKF Harness agent integrations.

OKF Harness is an independent open-source project built on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).

Try the local setup plan:

```bash
npx @okf-harness/setup --dry-run
```

Run a workspace's exact pinned runtime without a global install:

```bash
npx @okf-harness/setup@latest launch --workspace "/path/to/workspace" -- status --json
```

Arguments after `--` pass to `okfh` unchanged. A direct runtime result means `DELEGATED`; its exit code and streams pass through unchanged. Launcher-only failures are JSON on stderr with a closed outcome code and, when a runtime cannot be fetched or executed, the attempted invocation. `RUNTIME_PIN_MISSING` returns `data.adoptCommand` as an exact executable-and-arguments object.

Setup checks Node.js 22+, detects supported agent clients on `PATH`, installs selected native integrations containing the unified `okf-harness` host entrypoint, and keeps `--dry-run` local-only with no network checks or filesystem writes. It never installs a global `okfh`; workspace operations resolve their pinned runtime through `launch`.

For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).

## Native integration README

Source path: `packages/native-integration/README.md`

### OKF Harness Native Integration

This package exposes the unified `okf-harness` host entrypoint for Pi, OpenCode, and OpenClaw.

#### Install

```bash
pi install npm:@pumblus/okf-harness
```

```bash
opencode plugin @pumblus/okf-harness --global
```

```bash
openclaw skills install @pumblus/okf-harness --global
```

The entrypoint invokes the version-independent launcher, which resolves each workspace's pinned Harness runtime on demand. Nothing is installed globally.

#### Scope

The host entrypoint handles workspace setup and daily maintenance. This package does not install workspace-local adapters for Pi, OpenCode, or OpenClaw.