Open Knowledge CLI Documentation
Frontmatter5 fields
Trust
UnverifiedDefault
Status
StableDefault
type
Changelog
title
CLI Changelog
description
Release-level history for the Open Knowledge CLI.
tags
timestamp

CLI Changelog

Current behavior belongs in the command reference. This page records release-level changes.

Unreleased

Setup

  • okn setup now discovers ordinary repository Markdown without required frontmatter or links. Users select paths and choose copy or in-place mode.
  • Setup shows a deterministic change plan. Copy mode preserves sources, and in-place mode does not move or delete existing documents.
  • Empty repositories receive a tailored agent task. Installed agents appear before the copy and save choices.
  • Existing OKF bundles continue with check, review, or upgrade.
  • Source: packages/cli/cmd/openknowledge/setup_command.go and packages/cli/internal/okf/setup_import.go.
  • Docs: README.md and Wiki/features/commands/setup.md.

Knowledge lifecycle

  • New okn check combines configured validation, links, freshness, retrieval, claims, and publication checks into one status.
  • okn search now searches unmanaged Markdown and marks the result status.
  • New top-level review, publish, and upgrade commands complete the primary knowledge lifecycle. Publish refuses unmanaged or blocked input.
  • Root help now places the lifecycle commands under Start here. Existing lower-level commands remain available under Advanced.
  • Source: packages/cli/cmd/openknowledge/{check,publish,upgrade}_command.go, packages/cli/cmd/openknowledge/main.go, and packages/cli/internal/okf/{loose_markdown,upgrade}.go.
  • Docs: Wiki/features/commands/{check,search,review,publish,upgrade}.md, Wiki/features/tooling-model.md, and Wiki/decisions/product-interface.md.

Machine contracts

  • New check.schema.json defines unified check JSON. Single-bundle search contracts now identify managed and unmanaged results.
  • Source: packages/cli/schemas/v1/{check,search-context,search-results}.schema.json.
  • Docs: Wiki/features/machine-contracts.md.

v0.13.0 — 2026-08-31

Knowledge that guides agents can now use the same controls as code.

This release connects local Markdown, deterministic CI, evidence-backed review, and production MCP in one Git-native lifecycle. Open Knowledge finds stale, conflicting, and missing knowledge before agents use it.

Teams can test retrieval and evidence changes before publication. The runtime then serves an immutable generation with explicit passing or degraded health and rollback support.

Start with the lightweight base setup. Add evidence, GitHub automation, quality gates, or the runtime only when the workflow needs them.

Release highlights

  • Create a validated, searchable knowledge base before optional governance or runtime configuration.
  • Keep high-risk facts tied to exact evidence, review history, and explicit lifecycle states.
  • Test retrieval, answers, citations, and freshness with deterministic regression gates.
  • Publish only configured viewer or MCP outputs. Retain rollback to earlier production generations.
  • Browse documents, claims, entities, and graphs in one connected workspace.

Setup and GitHub automation

  • New setup use cases are base, trusted, and custom. base is the default, and all use cases use the same OKF format.
  • The setup wizard creates a validated search result before optional agent instructions, observation, claims, or runtime configuration.
  • The documentation start page now links to installation and setup references. It does not prescribe project-specific validation or search commands.
  • New okn setup github creates the canonical GitHub workflow, a starter eval dataset, and a source baseline.
  • The root composite Action maps pull requests, pushes, schedules, and manual runs to okn automation github.
  • [release].outputs is the only publication switch. It accepts viewer, mcp, or both. An empty value keeps the bundle local.
  • Source: action.yml, packages/cli/cmd/openknowledge/setup_product_command.go, and packages/cli/cmd/openknowledge/automation_github.go.
  • Docs: README.md, Wiki/features/commands/setup.md, Wiki/features/commands/automation.md, and Wiki/features/configuration.md.

Claims, evidence, and corpus contracts

  • Typed Claims v1 adds ontology terms, globally unique occurrences, typed objects, structured evidence, verification records, and explicit lifecycle relations.
  • Evidence selectors bind to pinned source artifacts. Validation verifies supported selectors against exact bytes and reports unavailable bytes.
  • New okn evidence pin creates a content-addressed evidence artifact and an immutable receipt.
  • New okn claims stale and okn claims reconcile detect and resolve evidence drift without removal of reviewed history.
  • Entity alias and merge proposals provide impact previews. Approved merges update references and retain deprecated entity IDs.
  • Corpus Schema v1 adds optional document, metadata, typed-link, and migration rules. OKF Markdown and YAML remain canonical.
  • OKF 0.2 now requires explicit ISO 8601 offsets in timestamp fields.
  • Source: packages/cli/internal/okf/claims_*.go, packages/cli/internal/claimops/, and packages/cli/internal/okf/corpus_schema.go.
  • Docs: Wiki/features/claim-profile.md, Wiki/features/claim-freshness.md, Wiki/features/corpus-schema.md, and Wiki/features/commands/{claims,evidence}.md.

Retrieval and semantic queries

  • Search now combines BM25 with deterministic local vectors. Repeatable --filter type=<value>|tag=<value> options filter candidates before rank.
  • Hybrid retrieval can combine caller-supplied text, SPARQL, and Datalog routes through reciprocal-rank fusion.
  • New okn query sparql, okn query datalog, and okn query hybrid commands query one immutable corpus revision.
  • New okn export rdf writes a deterministic RDF 1.1 N-Quads projection with claims, evidence, access, lifecycle, and provenance data.
  • Optional OpenAI-compatible embedding services can replace local hash vectors. The CLI caches vectors by exact input and model fingerprint.
  • Access and lifecycle filters run before semantic evaluation. Direct MCP semantic queries remain public-only.
  • The Go API exposes reusable context, semantic fact, RDF, vector, SPARQL, Datalog, and hybrid snapshots.
  • Source: packages/cli/internal/okf/{search,embedding,rdf,sparql,datalog,hybrid}*.go and packages/cli/cmd/openknowledge/query_command.go.
  • Docs: Wiki/features/commands/{search,query,mcp}.md, Wiki/features/exporters/rdf.md, and Wiki/features/go-api.md.

Eval, audit, and quality

  • okn eval run adds strict retrieval, answer, citation, groundedness, trust, freshness, lifecycle, and source expectations.
  • Base comparisons identify changed paths, affected questions, affected agents, and uncovered knowledge paths.
  • New okn eval retrieval reports MRR, Recall@k, and nDCG@k with absolute and embedding-uplift gates.
  • New okn eval claims replays claims at immutable Git revisions and reports supported, stale, hallucinated, and unverified claims.
  • New okn audit reports evidence-backed risks for sources, ownership, staleness, dependencies, duplicates, usage, and claim conflicts.
  • New okn quality report combines usage, feedback, eval, audit, claims, and intervention data without a global quality score.
  • Text, JSON, Markdown, and offline HTML outputs support local review and continuous integration.
  • Source: packages/cli/internal/{eval,audit,quality,intervention}/ and packages/cli/cmd/openknowledge/{eval,audit,quality}_command.go.
  • Docs: Wiki/features/commands/{eval,audit,quality}.md, Wiki/features/golden-path.md, and Wiki/features/machine-contracts.md.

Runtime, publication, and maintenance

  • Runtime retrieval returns generation identity, policy decisions, selected evidence, conflicts, access labels, and structured refusal reasons.
  • Access profiles provide separate HTTP and MCP tokens, knowledge base allowlists, and agent, team, or use-case labels.
  • Immutable generations support stage, preview, pin, list, and rollback operations. Failed builds keep the previous production generation.
  • Publication policies are follow-main and last-passing. Required GitHub checks and knowledge gates determine passing or degraded generation health.
  • Private runtime usage and reason-coded feedback retain generation and evidence identity without storing raw query text by default.
  • Generation-bound retrieval caches validate content identity and rebuild after missing or invalid cache data.
  • Audit findings can create risk-routed maintenance proposals. Automated publication requires exact checks and the active verified commit.
  • setup runtime selects GitHub Actions or runtime jobs as the maintenance executor.
  • Source: packages/cli/cmd/openknowledge/runtime_*.go, packages/cli/internal/runtime/, and packages/cli/internal/{usage,feedback,insights}/.
  • Docs: Wiki/features/commands/{runtime,insights,jobs}.md, Wiki/features/knowledge-architecture.md, and Wiki/features/telemetry.md.

Viewer

  • The viewer hides Claims when a knowledge base has no typed claim occurrences. Claim profiles, ontology terms, and references no longer create an empty Claims workspace.
  • Registry mode now provides one Documents and Graph workspace across connected knowledge bases. Each knowledge base retains separate indexes.
  • Typed bundles add a Claims workspace, document claim panels, claim history, impact data, relationships, and contextual entity inspectors.
  • Graph filters cover documents, claims, entities, and source knowledge bases. Large graphs use bounded layout work.
  • Local document requests reuse parsed data and load graph or claim projections only when required.
  • okn view watches local Markdown and assets. Live reload preserves valid document, graph, and scroll state.
  • Pointer dragging takes immediate control of horizontally stacked documents, even when a previous smooth navigation is still settling.
  • Markdown images use safe asset routes and portable static exports. Linked images, alt text, titles, lazy loading, and SVG sandboxing are supported.
  • Browser-native narration reads visible document content and omits code, metadata, diagrams, and hidden interface content.
  • Source: packages/cli/cmd/openknowledge/viewer_*.go and packages/web/src/viewer/.
  • Docs: Wiki/features/commands/view.md, Wiki/features/exporters/html.md, and Wiki/examples/markdown-showcase.md.

Validation and automation foundations

  • okn validate --profile bundle|okf separates OKF core checks from Open Knowledge extension checks.
  • New bundles enable the built-in project and writing rules. Explicit rule selections replace these defaults.
  • okn prompt review content creates a deterministic content review for a complete bundle or changed Git scope.
  • Markdown supports bounded agent-context annotations. Reader search omits this agent-only content.
  • Jobs can run deterministic preflight commands before an agent starts. Validation-only jobs can omit the agent runtime.
  • Strict v1 schemas cover new claim, evidence, retrieval, eval, quality, feedback, runtime, and intervention outputs.
  • Source: packages/cli/internal/okf/validation_*.go, packages/cli/internal/okf/content_review.go, and packages/cli/internal/agents/.
  • Docs: Wiki/features/commands/{validate,rules,review,jobs}.md and Wiki/features/machine-contracts.md.

Release safety and compatibility

  • Go 1.26.6 is the build baseline. It includes standard library security fixes for the CLI, viewer, runtime, and GitHub integration paths.
  • Go and JavaScript dependencies move past the affected x/sys, x/text, and nanoid releases reported by the dependency scanner.
  • Knowledge audit and eval jobs build viewer assets before they compile the embedded CLI.
  • Release verification runs CLI tests on macOS and Windows. Windows tests use a 20-minute package timeout.
  • Windows tests now drain Git archive streams correctly. Viewer caches detect same-size edits even on coarse-timestamp filesystems, Git diagnostics stay out of changed-path results, and path and permission checks follow Windows behavior.
  • Release verification runs govulncheck and OSV Scanner before it can create the version commit or tag.
  • The GitHub release body uses the matching dated section from this changelog. A missing version section stops the release before repository writes.
  • Source: .github/workflows/{ci,knowledge-eval,release}.yml, packages/cli/go.mod, packages/cli/go.sum, package.json, pnpm-lock.yaml, go.work, Dockerfile, docker/runtime.Dockerfile, and scripts/extract-release-notes.mjs.
  • Docs: Wiki/features/operations.md and Wiki/workflows/changelog-updates.md.

v0.12.0 — 2026-08-11

Version 0.12 expands the multi-knowledge-base viewer. It supports non-Git setup, makes HTML source archives optional, adds examples, and requires Node 20.

Viewer

  • Source and text files now open as syntax-highlighted note cards in the document stack. Markdown cards include collapsed typed frontmatter and OKF 0.2 signals.
  • The viewer sidebar now has separate Documents, Graph, and Knowledge bases items. The registry workspace lists connected knowledge base trees and can connect another local knowledge base.
  • Registry search now covers all connected knowledge bases and identifies each result's source. Connections are read-only unless the user enables editor links. A folder without a knowledge base shows its okn setup command.
  • The combined registry graph uses saved knowledge-base colors. It does not create links between knowledge bases. New controls support pan, zoom, node drag, filters, display options, force settings, and animation control.
  • Source: packages/cli/cmd/openknowledge/viewer_templates.go, packages/cli/cmd/openknowledge/viewer.go, packages/cli/cmd/openknowledge/viewer_test.go, packages/web/src/viewer/app.js, packages/web/src/viewer/search.js, packages/web/src/viewer/styles/, and packages/web/scripts/browser.e2e.mjs.
  • Docs: Wiki/features/commands/view.md and Wiki/features/exporters/html.md.

Export

  • okn export html --no-source-archive now omits the portable source archive and its connect manifest. Viewer HTML exports include both files by default.
  • Source: packages/cli/cmd/openknowledge/main.go, packages/cli/cmd/openknowledge/viewer_export.go, and packages/cli/cmd/openknowledge/command_help.go.
  • Docs: Wiki/features/commands/export.md, Wiki/features/exporters/html.md, and Wiki/features/exporters/tar.md.

Setup

  • Setup and project skill installation now support knowledge bases outside Git repositories. Git remains optional for an OKF bundle.
  • Source: packages/cli/cmd/openknowledge/setup_command.go, packages/cli/cmd/openknowledge/setup_lifecycle_command.go, packages/cli/cmd/openknowledge/setup_skill_command.go, and packages/cli/internal/integration/.
  • Docs: Wiki/features/commands/setup.md, Wiki/features/tooling-model.md, Wiki/features/knowledge-architecture.md, and Wiki/decisions/product-interface.md.

Website

  • The landing and getting-started pages now use Google Advanced Consent Mode v2. Google receives cookieless measurements while analytics_storage is denied. Selecting Allow enables Analytics cookies. Advertising storage, user data, and personalization remain denied.
  • Source: packages/web/src/analytics.js, packages/web/index.html, packages/web/getting-started/index.html, and packages/web/scripts/browser.e2e.mjs.
  • Docs: Wiki/features/telemetry.md and Wiki/features/operations.md.
  • The three examples cover project context, release memory, and research synthesis. Each example includes validation, search, export, and tests.
  • pnpm test:demos verifies all three knowledge bases against the current CLI.
  • The guides use ASD-STE100 rules and supported CLI command syntax.
  • Source: examples/, scripts/test-demo-knowledge-bases.sh, and package.json.
  • Docs: Wiki/index.md, Wiki/features/operations.md, and Wiki/changelog/cli.md.

Compatibility

  • Node 20 is now the minimum version for the npm wrapper, website development, and JavaScript tests. The baseline CI job verifies Node 20.
  • Source: package.json, packages/npm/package.json, packages/web/package.json, .github/workflows/ci.yml, and scripts/check-versions.mjs.
  • Docs: packages/npm/README.md, Wiki/features/installation.md, Wiki/features/operations.md, and Wiki/changelog/cli.md.

Security

  • Mermaid diagram rendering now uses Mermaid 11.16.1. Its dependency updates include DOMPurify 3.4.13 and nanoid 3.3.17 to fix seven known vulnerabilities.
  • Source: package.json, packages/web/package.json, pnpm-lock.yaml.
  • Docs: Wiki/changelog/cli.md.

v0.11.0 — 2026-08-08

Version 0.11 adds privacy-safe product telemetry, standalone skill setup, a new website guide, and a refreshed default viewer theme.

Viewer

  • The local viewer and interactive HTML exports now use the light blue Open Knowledge theme on the first visit and after a settings reset.
  • The Night theme remains available. A saved browser preference overrides the new default.
  • Source: packages/cli/cmd/openknowledge/viewer_theme.css, Wiki/assets/openknowledge-site.css, packages/cli/cmd/openknowledge/viewer_templates.go, packages/web/src/viewer/.
  • Docs: Wiki/features/commands/view.md, Wiki/features/exporters/html.md.

Release automation

  • The release guide now documents the repository's four release jobs, input formats, credential preflight, exact commit handoff, and tag reuse rule.
  • Source: .github/workflows/release.yml.
  • Docs: Wiki/features/operations.md.

Telemetry

  • The CLI now discloses default-on anonymous usage and sanitized error telemetry before it sends the first event. Telemetry commands inspect the payload, report status, and save an opt-in or opt-out.
  • --no-telemetry saves an opt-out before the command runs. Installer preflight and continuous integration do not send events.
  • The first-party website relay validates an exact event allowlist. Website page and copy events require consent.
  • The /install redirect records an aggregate source and client family without a browser or installation identifier.
  • The relay now maps accepted events to PostHog's batch ingestion protocol, keeps the project token server-side, and disables person-profile processing.
  • The relay now maps each cli_error to a synthetic PostHog $exception event. Native issue grouping receives no raw message, stack trace, path, or output.
  • The CLI schema does not change. The CLI does not include the PostHog Go SDK or a PostHog project token.
  • Product telemetry stays separate from opt-in local session observation.
  • Source: packages/cli/internal/telemetry/, packages/cli/cmd/openknowledge/telemetry_command.go, install, and packages/web/.
  • Docs: Wiki/features/telemetry.md and Wiki/features/commands/telemetry.md.

Setup

  • okn setup skill now installs global or project instructions without the complete knowledge-base setup flow. Interactive use selects the scope, project target when required, and detected harnesses.
  • Noninteractive use supports --scope, repeatable --harness, and --project. A global installation does not require a Wiki or registry entry.
  • Source: packages/cli/cmd/openknowledge/setup_skill_command.go.
  • Docs: Wiki/features/commands/setup.md.

v0.10.0 — 2026-08-04

Version 0.10 makes OKF 0.2 the default, unifies setup, expands provenance views, and improves viewer navigation, registry refreshes, and local automation.

OKF 0.2

  • The latest selector now uses OKF 0.2. Explicit OKF 0.1 reads remain available.
  • The parser normalizes a single verified mapping for OKF 0.2 consumers.
  • Validation reports malformed optional provenance, trust, lifecycle, source, and Attested Computation metadata as warnings.
  • Each validation uses the rule profile for its selected OKF version. Shared configuration can contain rules from multiple profiles.
  • New scaffolds use OKF 0.2. Use okn scaffold --spec 0.1 to create a complete version-matched OKF 0.1 scaffold.
  • The scaffold handoff validates the selected OKF version.
  • New insights use OKF 0.2 lifecycle and generated metadata. Status changes convert legacy insight provenance to OKF 0.2.
  • okn list shows trust, lifecycle status, and stale content. List and graph JSON also expose a derived okf02 contract.
  • Graph output connects sources, computations, executors, and attesters with typed provenance edges.
  • Viewer pages and HTML exports show provenance, linked sources, and Attested Computation contracts.
  • The CLI preserves executor and attester declarations. It never runs these resources automatically.

Setup

  • okn setup starts a terminal wizard. Without terminal input, it prints a complete task for an agent.
  • Explicit flags print the task, start the wizard, or launch a supported agent harness.
  • okn setup complete validates and connects the bundle. It also installs selected skills and configures optional observation.
  • Setup commands now report status, repair managed files, and control observation.
  • The CLI removed integration, agent integrate, prompt setup, and prompt from.
  • Source-based setup no longer requires a predefined knowledge-base type.
  • Bundle configuration now uses .openknowledge.toml. The CLI does not load the legacy name.
  • Both configuration names remain private in viewer and publication output.
  • The generated task starts with an open-ended setup interview for Wiki.
  • The README and website explain setup with an existing agent or a selected CLI runtime. The website copy action includes complete agent instructions.
  • The README workflow diagram includes MCP.

Viewer

  • The Frontmatter disclosure contains OKF 0.2 trust, lifecycle, provenance, source, and computation details.
  • Authored Markdown starts the visible document without a separate metadata block above it.
  • Mobile sidebar and note navigation now show destinations immediately without transition delays.
  • The file explorer stays visible during open-beside navigation. Resize it from its 25vw default within its limits.
  • The viewer keeps the header, note workspace, and horizontal scroll rail in the main content column.
  • Open a Mermaid diagram with a click, Enter, or Space. The viewport dialog provides zoom, pan, Fit, and 100% controls.
  • The local viewer and interactive HTML exports use the same diagram controls.

Automation

  • A scheduled job runs once for each job ID and schedule slot. Repository or job-file changes do not replay that slot.
  • Each private jobs worker uses its runtime-specific state directory.
  • Workers remove terminal worktrees and large temporary artifacts after proposal export. Publishers remove branch bundles after publication.
  • On Windows, a command timeout stops the complete child process tree.
  • The CLI releases private run logs when a run finishes.

Registry

  • Registry refreshes tolerate temporary Git files that disappear during a scan.
  • A refresh still stops when a bundle file or staging root is missing.

Distribution

  • Source distributions exclude compiled viewer JavaScript and CSS.
  • Supported build, test, security, and release workflows generate viewer assets when required.

Compatibility

  • okn connect reads canonical Windows file:// URLs for manifests and archives. Windows drive URLs use file:///C:/path.
  • Insight creation reports stable slash-separated project paths on all operating systems.

v0.9.0 — 2026-07-30

2026-07-30 — Automatic release version update

  • The manual release workflow now updates all package and CLI versions from the requested release version.
  • The workflow runs the release checks before it creates and pushes the version commit. Release tags and npm packages use that verified commit.
  • Source: .github/workflows/release.yml, scripts/set-release-version.mjs.
  • Docs: Wiki/features/operations.md.

2026-07-30 — Streamlined multi-panel viewer

  • The viewer no longer duplicates open panels in a fixed bottom navigator.
  • Links open beside the active panel by default. The current panel mode remains available through the header control.
  • Each panel keeps its close control. The horizontal scroll rail remains available for multi-panel navigation.
  • Source: packages/web/src/viewer/, packages/web/scripts/browser.e2e.mjs.
  • Docs: Wiki/features/commands/view.md.

2026-07-29 — Focused viewer navigation

  • A persistent header control now selects the current panel mode or the open-beside mode. Shift temporarily uses the other mode.
  • A visible navigator now lists open panels and can close one panel or all panels.
  • Search results now group section matches by document. The file explorer now reveals the active branch and can collapse directories.
  • The knowledge graph now reports its selected note and connection count. A left detail panel now keeps graph instructions outside the canvas. High-contrast mode also applies to graph colors.
  • Viewer settings now provide a reset-to-defaults action.
  • Source: packages/web/src/viewer/, packages/web/scripts/browser.e2e.mjs.
  • Docs: Wiki/features/commands/view.md.

2026-07-29 — Unified product story

  • The website, README, npm package, wiki, setup prompt, and root help now use one product description.
  • The description presents flexible Markdown knowledge bases that agents can create, retrieve, maintain, validate, and publish for different use cases.
  • Source: packages/web/, packages/npm/README.md, packages/cli/{cmd/openknowledge,internal/okf/setup.go}.
  • Docs: README.md, Wiki/index.md.

2026-07-28 — Shared Vite viewer build

  • Vite built the landing page and the shared viewer assets.
  • The web workspace added TypeScript checks and Oxlint.
  • Local and static viewers used the same generated JavaScript and CSS bundle.
  • Static HTML pages referenced one shared data file instead of embedding the complete note collection in every page.
  • Static exports became independent of installed editor applications and supported nested pages through direct file:// URLs.
  • Browser tests covered Mermaid errors and direct file viewing.
  • Source: packages/web/src/, packages/web/vite*.config.ts, packages/cli/cmd/openknowledge/{viewer_export,viewer_assets}.go.
  • Docs: Wiki/features/{exporters/html,commands/view,operations}.md.

2026-07-28 — Explicit automation namespace

  • okn automation became the canonical namespace for jobs, insights, runtime, and deploy.
  • Root help separated local work, sharing, and automation.
  • The old top-level forms remained functional as hidden compatibility aliases.
  • JSON error envelopes reported the canonical automation command identity for both forms.
  • Generated job and deployment commands used the automation namespace.
  • Source: packages/cli/cmd/openknowledge/{automation_command,command_catalog}.go.
  • Docs: Wiki/features/commands/{automation,index,help}.md, Wiki/features/tooling-model.md.

2026-07-28 — Runtime-specific project integration

  • okn integration install installed only the selected runtime skill.
  • Session observation became opt-in through --observe.
  • The new status command reported missing and modified managed files without changing them.
  • The new remove command deleted unchanged owned files. It preserved user changes and unrelated hook settings.
  • The integration manifest restricted managed paths to the selected runtime.
  • okn agent integrate remained as a deprecated alias.
  • Automated okn setup --agent installed the selected skill without an observation hook.
  • Source: packages/cli/cmd/openknowledge/{integrate_command,setup_command}.go, packages/cli/internal/integration/{integration,manage}.go.
  • Docs: Wiki/features/commands/{integration,integrate,setup}.md.

2026-07-28 — Focused README

  • The README became a short product entrypoint.
  • It now gives one setup path, one local usage path, and one publication path.
  • Publication guidance now distinguishes a local public bundle from deployment and a live HTTP MCP endpoint. It also states the Markdown publication default.
  • Detailed command, runtime, deployment, validation, and release information now stays in the current-state wiki.
  • The product summary now matches the workflow groups in CLI help and the wiki.
  • Docs: README.md, Wiki/features/.

2026-07-28 — Portable setup by default

  • okn setup printed portable instructions by default.
  • The new --agent flag ran the instructions, validated the result, and installed project integration.
  • If --runtime was absent, interactive agent mode detected installed runtimes and asked the user to select one.
  • Non-interactive agent mode required --runtime.
  • Source: packages/cli/cmd/openknowledge/{command_catalog,setup_command}.go.
  • Docs: Wiki/features/commands/{index,setup}.md, Wiki/index.md.

2026-07-28 — Mermaid diagrams in the viewer

  • The viewer rendered fenced mermaid blocks as theme-aware diagrams on local and static pages. The viewer no longer displayed these blocks as ordinary code.
  • The viewer kept the escaped source visible when Mermaid was unavailable or a diagram was invalid.
  • The viewer configured Mermaid with strict security mode for generated SVG.
  • Source: packages/cli/internal/okf/markdown.go, packages/cli/cmd/openknowledge/{viewer,viewer_assets}.go, packages/web/src/viewer/.
  • Docs: Wiki/features/commands/view.md, Wiki/features/exporters/html.md.

2026-07-28 — Focused onboarding and document-coherent retrieval

  • The CLI reduced project activation to openknowledge setup. The zero-argument command used the current repository as its source and wrote Wiki.
  • Explicit targets and alternate sources remained optional workflows. The viewer, publishing, registry, runtime, jobs, scaffold, and portable prompts also remained optional.
  • Section ranking included whole-document evidence, filename relevance, stronger body evidence, and query coverage. These changes let overview documents compete with specialized pages.
  • Context packing preserved the strongest lexical seeds. It added siblings from the same document and parent or child evidence.
  • Context packing labeled non-lexical hierarchy as document-context. It truncated prioritized oversized evidence. It did not skip that evidence for lower-ranked sections.
  • Source: packages/cli/cmd/openknowledge/{command_catalog,setup_command}.go, packages/cli/internal/okf/{search_knowledge,context_selection,setup,from,new}.go, packages/cli/schemas/v1/search-context.schema.json.
  • Docs: README.md, packages/web/index.html, Wiki/features/commands/{index,setup,search}.md.

2026-07-28 — Onboarding, release, and verification hardening

  • The setup command verified the selected agent executable before it started the interactive workflow.
  • The CLI added exact recovery guidance for doctor and authentication failures.
  • One command catalog replaced duplicate root command dispatch and help definitions.
  • An explicit writer handled diagnostics. The CLI no longer replaced the process-wide standard error stream temporarily.
  • The release workflow closed the shell injection path for manual release input.
  • A YAML parser and regression tests replaced text-based permission scans.
  • The shell installer rejected custom plain-HTTP mirrors before download. It retained file:// only for controlled local transaction tests.
  • The pull-request workflow added security scans, race tests, coverage runs, and CLI certification on Linux, macOS, and Windows.
  • Verification added Node 18 compatibility, packed npm installation, browser setup, search, and keyboard journeys.
  • Verification also added pre-tag GoReleaser snapshot checks.
  • The verification suite added parser/archive fuzz targets.
  • It also added 100/1,000/10,000-section search/index benchmarks.
  • The README, website, and command or operations references clarified the canonical zero-argument setup path and runtime recovery.
  • These references also clarified fail-closed publication permission and the default validation warning policy.
  • Source: packages/cli/cmd/openknowledge/{setup_command,command_catalog,cli_io}.go, packages/cli/internal/okf/{fuzz,search_benchmark}_test.go, packages/cli/internal/tools/checkworkflowpermissions/, .github/workflows/{ci,release,security}.yml, scripts/, packages/web/scripts/browser.e2e.mjs.
  • Docs: README.md, packages/web/index.html, Wiki/features/commands/setup.md, Wiki/features/operations.md.

2026-07-21 — Anchor-aware graph retrieval

  • Machine-readable links preserved canonical Markdown fragments. Search graphs and one-hop outgoing or backlink expansion resolved each fragment to its content chunk.
  • Lower-level headings resolved to their containing retrieval chunk. Missing fragments no longer resolved to an unrelated first chunk.
  • Parallel source and search graph edges preserved repeated authored links. Each occurrence kept its href, label, target anchor, and source line.
  • The strongest relationship-derived score promoted weak lexical matches. Search did not discard graph evidence or return a duplicate result.
  • Each context index included an immutable BM25 corpus. Generation-scoped caches no longer tokenized the complete corpus for each query.
  • Source: packages/cli/internal/okf/ast_links.go, packages/cli/internal/okf/context_sections.go, packages/cli/internal/okf/graph.go, packages/cli/internal/okf/search_knowledge.go, packages/cli/schemas/v1/common.schema.json, packages/cli/schemas/v1/graph.schema.json.
  • Docs: Wiki/features/exporters/graph.md, Wiki/features/commands/search.md.

2026-07-19 — Generation-scoped runtime search indexes

  • The runtime built each search context index once before it activated the immutable generation.
  • The runtime reused the index for _search requests. It no longer parsed and validated the search projection for each query.
  • A new content digest replaced the cached index atomically. A failed index build retained the last valid generation.
  • Source: packages/cli/cmd/openknowledge/runtime_serve.go, packages/cli/cmd/openknowledge/runtime_command_test.go.
  • Docs: Wiki/features/commands/runtime.md.

2026-07-18 — Static viewer CSP compatibility

  • The exporter moved generated viewer JavaScript from executable inline <script> blocks to same-origin assets.
  • Railway and runtime deployments then worked with the default script-src 'self' https: policy without unsafe-inline.
  • Runtime viewer pages and assets used Cache-Control: no-cache for revalidation.
  • Browsers no longer retained an older generation after a source-triggered deployment.
  • Deployment-owned head injection remained explicit. Some deployments still required a deployment-specific nonce or hash for custom inline scripts.
  • The --script-src option remained compatible with permitted external sources.
  • Source: packages/cli/cmd/openknowledge/viewer.go, packages/cli/cmd/openknowledge/viewer_test.go, packages/cli/cmd/openknowledge/runtime_serve.go, packages/cli/cmd/openknowledge/runtime_command_test.go.
  • Docs: Wiki/features/exporters/html.md, Wiki/features/commands/runtime.md.

2026-07-18 — Private Railway endpoint reconciliation

  • The --no-public-endpoint option listed and deleted existing Railway service domains and custom domains.
  • The option no longer trusted possibly stale local endpoint state.
  • Source: packages/cli/cmd/openknowledge/deploy_command.go.

2026-07-18 — Railway prune removes service volumes

  • The --prune option listed and deleted persistent volumes for omitted services before it deleted those services.
  • This sequence prevented provider-orphaned agent state during migration to the immutable one-service topology.
  • Source: packages/cli/cmd/openknowledge/deploy_command.go.

2026-07-18 — Immutable Railway deployment by default

  • The default Railway topology changed to one serve service.
  • Its multi-stage Docker image built and embedded the knowledge artifact for the source commit that triggered the build.
  • The --runtimes option made Git polling, the private publisher, persistent agent state, and isolated workers explicit.
  • Deployment no longer inferred enabled jobs.
  • Default deployment requirements no longer included GitHub, model, artifact-sync, or exchange credentials.
  • The project added a committed generated runtime.toml.
  • The generated image started as serve. The image supported local tests without Railway-specific variables.
  • The --prune option provided an explicit fail-closed migration path. It deleted publisher and worker services that the new topology omitted.
  • Existing deployments required a reviewed dry run before migration. The migration command was openknowledge deploy railway Wiki --prune --yes.
  • Source: packages/cli/cmd/openknowledge/deploy_command.go, packages/cli/cmd/openknowledge/deploy_runtime_scaffold.go.
  • Docs: README.md, Wiki/features/commands/deploy.md, Wiki/features/commands/runtime.md.

2026-07-18 — Runtime log severity

  • The runtime moved successful lifecycle events from standard error to standard output.
  • Railway and other hosting platforms no longer classified healthy listening, synchronization, publication, or activation messages as errors.
  • Usage diagnostics, failed passes, retained-generation warnings, and archive failures remained on standard error.
  • Source: packages/cli/cmd/openknowledge/runtime_command.go, packages/cli/cmd/openknowledge/runtime_private_api.go, packages/cli/cmd/openknowledge/runtime_serve.go, packages/cli/cmd/openknowledge/runtime_worker.go.
  • Docs: Wiki/features/commands/runtime.md.

v0.7.2 — 2026-07-18

This cumulative section records the v0.7 release line. v0.7.0 moved Railway to a repository-owned runtime, v0.7.1 removed a redundant source redeploy, and v0.7.2 completed non-root persistent-volume startup.

2026-07-18 — Repository-owned Railway runtime

  • The CLI added openknowledge deploy railway init. This command generated a project-owned non-root runtime Dockerfile.
  • The Dockerfile used independent Open Knowledge and agent CLI pins. The --force option was necessary to replace existing project choices.
  • Railway provisioning changed from published GHCR role images to the target GitHub repository source.
  • Services shared the committed Dockerfile. They retained separate roles, ingress, volumes, and credentials.
  • The migration converted version 1 deployment state to repository sources in place.
  • The release workflow no longer published runtime images.
  • The Railway source connection became the initial deployment trigger. The CLI no longer issued an immediate conflicting redeploy.
  • During startup, the generated entrypoint repaired persistent-volume ownership. It then dropped to UID/GID 10001.
  • The ownership repair also supported volumes that an older root-based runtime image created.
  • Source: packages/cli/cmd/openknowledge/deploy_runtime_scaffold.go, packages/cli/cmd/openknowledge/deploy_command.go, .github/workflows/release.yml.

2026-07-18 — Railway non-root volume startup

  • Publisher checkout, build, and lock state remained on ephemeral container storage.
  • Published artifacts and exchange data remained on the persistent Railway volume.
  • Worker state used a process-owned child directory below its mount.
  • The runtime avoided redundant permission changes when its state directory was already private. It still restricted a permissive existing directory.
  • An ephemeral Basic extra header authenticated private GitHub Smart HTTP clone and fetch operations. It replaced a rejected Bearer header.
  • Credentials remained absent from repository URLs and command arguments.
  • Source: packages/cli/cmd/openknowledge/deploy_command.go, packages/cli/cmd/openknowledge/runtime_worker.go.

2026-07-18 — Short CLI alias

  • The shell and npm installers added okn as an installed alias for openknowledge. They retained the original command name.
  • The shell installer refused to overwrite an unrelated existing okn command.
  • Source: install, scripts/test-install.sh, packages/npm/.

2026-07-18 — Railway CLI v5 deployment recovery

  • The CLI separated Railway progress diagnostics from JSON standard output.
  • Successful v5 service creation then recorded provider IDs. It did not fail after mutation.
  • The v5 volume command placed the service selector before the nested subcommand. It addressed the service by provider ID.
  • The CLI saved the selected existing project before service creation.
  • An interrupted first apply left recoverable secret-free state.
  • Source: packages/cli/cmd/openknowledge/deploy_command.go.

2026-07-18 — CLI-led onboarding

  • The CLI, README, and website established openknowledge setup Wiki --from . as the primary project-wiki activation path.
  • Documentation clarified that setup launched the selected agent. The command then validated the bundle and installed project integration.
  • The scaffold command remained the deterministic agent-free primitive.
  • Documentation added runtime build --out <dir>. It included the single-selection requirement and versioned result shape.
  • Source: packages/cli/cmd/openknowledge/{main,setup_command,runtime_command}.go.

2026-07-17 — Workflow-oriented command surface

  • The CLI consolidated managed onboarding under setup.
  • Portable instructions moved to prompt setup|from|rules|review.
  • The CLI renamed new to scaffold and to to export.
  • It renamed the experimental agents group to jobs. It also renamed detached spawn to start.
  • Connection changes remained under connect and disconnect.
  • The registry command owned listing, integrity status, refresh, and path resolution.
  • Root help used create/maintain, use/publish, service, and validate/connect workflows.
  • Source: packages/cli/cmd/openknowledge/{main,setup_command,prompt_command}.go.

2026-07-17 — Agents, insights, and jobs

  • The CLI added a steered local agent interface for Codex, Claude Code, and OpenCode.
  • The interface supported interactive and non-interactive modes, executable discovery, doctor, model overrides, and optional isolated worktrees.
  • The CLI added project and global integration with bounded observation hooks.
  • The insights command became the shared interface for deterministic capture, review, dismissal, direct execution, and scheduled processing of private knowledge gaps.
  • Job and service runtimes supported the same three harnesses.
  • Jobs used strict runtime and model selection, per-harness credential scoping, external private state, observable detached runs, cancellation, and versioned records.
  • Source: packages/cli/cmd/openknowledge/{agent_command,insights_command,agents_command}.go, packages/cli/internal/{agents,insights,integration}/.

2026-07-17 — Isolated runtime and Railway deployment

  • The runtime added immutable generation planning, building, serving, and private worker reconciliation.
  • These features supported one repository and multiple routed knowledge bases.
  • The runtime separated GitHub publication from model execution.
  • The publisher, serve service, and each harness worker used distinct images, credentials, volumes, and network boundaries.
  • The CLI added deploy railway with secret-free dry runs and explicit mutation consent.
  • The command also provided idempotent state, generated, custom, or private endpoint modes, and worker inference from enabled jobs.
  • The runtime added authenticated private artifact and Git-bundle exchange for providers without shared volumes.
  • Invalid updates retained the last verified generation.
  • Source: packages/cli/cmd/openknowledge/runtime_*.go, packages/cli/cmd/openknowledge/deploy_command.go, packages/cli/internal/runtime/, docker/runtime.Dockerfile, deploy/runtime/.

2026-07-17 — Explicit publication contract

  • Public HTML, portable public source, and runtime generation failed closed unless [publish] enabled = true.
  • The project added okf_targets.viewer|search|mcp|llms|sitemap.
  • The runtime used separate projections for the viewer, search, and MCP.
  • Public non-Markdown files included only [publish].assets.
  • Artifacts excluded project configuration, .openknowledge state, denied Markdown, and assets outside the allowlist.
  • Source: packages/cli/internal/okf/{project_config,publish}.go, packages/cli/internal/runtime/generation.go.

2026-07-15 — Machine and retrieval contracts

  • The CLI added versioned JSON envelopes and published Draft 2020-12 schemas.
  • The schemas covered CLI errors, AST, validation, bundle, list, registry, search, context, federation, graphs, jobs, portable manifests, and storage records.
  • The root command added the --error-format text|json diagnostic envelope.
  • Search added revision-bound provenance with content digests and okf+sha256:// locators.
  • Search also added registry-wide reciprocal-rank fusion.
  • The project added a public read-only Go API. The API supported parsing, validation, retrieval, graphs, and registry resolution.
  • Source: packages/cli/schemas/, packages/cli/internal/okf/, packages/cli/okf/.

2026-07-15 — Remote registry integrity

  • The registry added strict versioned registry and provenance storage.
  • It also added offline integrity status with atomic refresh and deletion.
  • The registry added Git ref and monorepo subdirectory selection.
  • It also added source-addressed caches, bounded non-interactive transport, archive limits, staging-tree limits, and secret-safe URL handling.
  • Remote materialization used locked sibling staging and transactional publication.
  • A failed refresh preserved the previous generation.
  • Source: packages/cli/cmd/openknowledge/main.go, packages/cli/internal/okf/registry.go, packages/cli/schemas/storage/v1/.

2026-07-15 — Viewer, packaging, and release hardening

  • The project unified local viewer search with canonical heading-section retrieval and content-bound cache invalidation.
  • Registry workspaces followed live validated snapshots.
  • The project strengthened static serving, containers, release permissions, workflow pins, scheduled security scans, and npm or shell binary installation.
  • The release process added reproducible portable archives and transactional export publication.
  • It also added signed release provenance and default-branch-only release dispatch.
  • Source: packages/cli/cmd/openknowledge/viewer*.go, packages/web/, install, packages/npm/, .github/workflows/, Dockerfile.

v0.6.1 — 2026-07-18

  • The runtime corrected Railway persistent-volume ownership for isolated runtime roles.

v0.6.0 — 2026-07-18

2026-07-09 — Retrieval and viewer polish

  • Search used source-preserving Markdown context as its default output.
  • The viewer added typed frontmatter inspection, tag facets, and breadcrumbs.
  • It also added reading and accessibility settings, better search navigation, and visual updates.
  • The public website and wiki landing page matched the LLM-oriented knowledge workflow.

v0.5.0 — 2026-07-08

  • The CLI added source-to-wiki prompts, maintenance rules, advisory review, and the first experimental local job runner.
  • It added exact get, structural list, ranked search, registry-backed view, and search graph workflows.
  • The viewer added static discovery files, analytics and head injection, and portable viewer connection assets.
  • Validation expanded its JSON output and added configurable rule severities.

v0.4.0 — 2026-06-23

  • The CLI added AST output, source and search graph exporters, and query-oriented context.
  • Bundle commands added key-or-path resolution.
  • The viewer improved themes, search highlights, shortcuts, panel navigation, responsive layout, and graph presentation.
  • The project added website deployment, install redirects, and static wiki publication.

v0.3.0 — 2026-06-20

  • The CLI added connected bundle commands and registry-backed local viewing.
  • The exporter added static HTML, portable manifests, and bundle metadata.
  • The viewer added themes, syntax highlighting, tables, asset previews, and source links.
  • Validation strengthened its UTF-8, frontmatter, Markdown, link, and reserved-file checks.
  • The project moved CLI documentation into this colocated OKF wiki.

Initial wiki maintenance — 2026-06-18

  • The project added the repository wiki, embedded OKF specification, command references, update workflows, and validation loop.
Powered by OpenKnowledge.sh