Knowledge

The knowledge library holds documents about your codebase that Ozone reads while reviewing your code. It's how the reviewer learns what a new team member would have to be told: which inputs are already validated upstream, which patterns are deliberate, what past incidents taught you. Underneath, each document is an Open Knowledge Format (OKF) v0.1 concept — the format matters when you work through the API or the agent CLI, and the sections below use OKF's vocabulary when they describe those.

Documents are tagged to projects. A review sandbox reads only documents tagged to its own project, never another project's, so tag an organization-wide convention to every project where it applies. An untagged document is read by nobody.

Browsing the library#

Knowledge in the sidebar opens the library as a folder browser: you are always inside a folder, starting at All documents, with breadcrumbs back up. Folders come from document paths, so architecture/auth.md files itself under architecture/. Start typing in the search box and the folders give way to a flat list of matches from across the library, with Back to folders to return. A project dropdown narrows the view.

New document opens the editor with Cancel and Create. An existing document opens in the same editor, which has no separate view and edit modes — click any part of it to change it — and Discard and Save appear once something is dirty. Above the sheet, Document settings carries the type, the path, tags, a source link, and the projects the document is tagged to. Deleting is permanent, and the agent stops reading the document in reviews of its tagged projects.

What goes in it#

Anything that changes how code should be judged:

• Conventions — "all handlers behind requireAuth can assume a valid org id."
• Architecture notes — trust boundaries, which services face the internet, where secrets live.
• Past decisions — "we accept X risk in the exporter because…", so it isn't re-flagged every review.
• False-positive patterns — when you close a finding as a false positive, the note you write is exactly this kind of knowledge.

Each concept has a Markdown body of up to 100,000 UTF-8 bytes. Its OKF fields are deliberately small:

The bundle-relative path, such as architecture/auth.md, is the concept's OKF concept ID and bundle location rather than a frontmatter field. It may change when the concept moves; Ozone's stable kd_… document id remains the same. Ozone generates a collision-resistant root path when you omit it.

Ozone can render every concept as a complete Markdown document with OKF frontmatter. The CLI's tree command is the live index, so agents progressively open only relevant concepts without maintaining a second filesystem copy.

Concept bodies can use standard Markdown links. Cross-concept links use bundle-root paths such as [auth model](/architecture/auth.md) so moving the source concept does not break them. A link is also a directed relationship: explain in the surrounding sentence whether the source depends on, is secured by, dispatches to, or otherwise relates to the target.

Who writes it#

Humans and project agents have slightly different rights:

There is no separate knowledge-writing run type. The run's instructions and matching skill tell the agent whether knowledge work belongs in its task. Knowledge remains untrusted reference data: future agents check important claims against code, and every change has a revision record.

Agent navigation#

The run-scoped ozone CLI is the single authoritative way for an agent to navigate the library. Knowledge is not copied into its sandbox. The CLI works from any directory; concept references are bundle paths, not filesystem paths:

ozone context
ozone knowledge tree
ozone knowledge list --type "Architecture Decision" --tag auth
ozone knowledge search "token rotation" --path-prefix playbooks/
ozone knowledge get architecture/auth.md
ozone knowledge get kd_… --json
ozone knowledge get architecture/auth.md --document > /tmp/auth.md

list, search, and tree follow every result page unless --limit is supplied. All three support exact --type and --tag filters plus --path-prefix. get accepts either a document id or an OKF bundle path, including /-rooted paths copied from markdown links.

Start with context, then tree; narrow with metadata filters and open only the relevant concepts. This keeps large libraries navigable without loading every body into the model context. The CLI rejects unknown flags and unexpected arguments instead of silently guessing what an agent intended. Run ozone knowledge --help for the workflow or ozone knowledge <command> --help for that command's exact flags and output contract.

Local --file and --body-file inputs may use relative or absolute filesystem paths and are resolved from the shell's current directory. A knowledge --path is different: it is the remote bundle location and does not need to exist in the sandbox.

Agent writing#

When knowledge work is part of its task, the agent searches before writing and saves only durable, source-backed information. A new concept uses the same fields exposed by the API:

ozone knowledge save \
  --title "Authentication boundary" \
  --body-file /tmp/auth.md \
  --path architecture/auth.md \
  --type "Architecture Decision" \
  --description "Where authentication and organization isolation are enforced." \
  --tags auth,security \
  --note "Verified against api/src/auth/middleware.ts and route mounting."

title, the body, and an evidence note are required. If path is omitted, the response returns the generated path. The concept is automatically assigned only to the authenticated run's project, and the evidence note is stored with its first audit snapshot.

An agent or API client can also submit a complete OKF Markdown document directly. For example, /tmp/auth.md can contain:

---
type: Architecture Decision
title: Authentication boundary
description: Where authentication and organization isolation are enforced.
tags: [auth, security]
---

# Authentication boundary

All `/v1` routes are protected by the authentication middleware. Agent routes use
the separate run-scoped agent-token boundary.

Ozone parses the standard frontmatter fields and stores the Markdown body. Explicit metadata flags override corresponding frontmatter fields, while --path selects its bundle location:

ozone knowledge save \
  --file /tmp/auth.md \
  --path architecture/auth.md \
  --note "Verified against the current authentication middleware."

The imported document must have a non-empty type. title may come from frontmatter, the first level-one Markdown heading, or the supplied bundle path. Producer-specific extension fields are accepted but are not stored by Ozone.

An evidence-backed revision or move requires a reason and the revision returned by get. The revision precondition prevents an agent or human from overwriting a concept that changed while they were working. The reason appears in the revision history:

ozone knowledge get architecture/auth.md
ozone knowledge update architecture/auth.md \
  --expected-revision 3 \
  --path architecture/security/auth.md \
  --body-file /tmp/auth.md \
  --note "Verified against api/src/auth/middleware.ts and current route mounting."

For a whole-document edit, export with --document, modify the file, and pass it back with --file plus the same revision precondition.

The agent never silently overwrites on save, never creates a revision when an update is identical, and never hard-deletes. Updating a shared concept changes it for every assigned project, so the maintenance skill tells agents to verify that the evidence is truly shared first.

Continuous maintenance#

New projects arrive with the built-in Continuous maintenance task switched on. Its knowledge half runs after the default branch moves, at most once a day — not on a fixed nightly slot — so a library that already matches the code costs nothing. Organization admins can create another schedule with their own knowledge-maintenance instructions. It follows the same bounded pattern as OpenWiki's scheduled updates:

1. Confirm the run with ozone context, read the live OKF tree, and search before writing.
2. Tie each proposed edit to current default-branch code, tests, configuration, or history.
3. Make surgical updates: refresh stale claims, consolidate obvious duplication, move misplaced concepts, repair links, and improve retrieval metadata.
4. Leave the library unchanged when it is already current.

The run may create or update up to 100 concepts, but cannot delete them. To consolidate duplicates, it moves durable content to one canonical concept and turns the redundant concept into a short deprecation link. Every create or update stores an internal full audit snapshot.

Organization admins can pause it or run it on demand from Schedules; being managed, it cannot be edited or deleted. It is an ordinary project-agent run, told to read and follow the knowledge-maintenance skill.

Tagging documents to projects#

A document can be tagged to one project or many, and a project's reviews read only what is tagged to it. Tag organization-wide policy everywhere; keep service-specific knowledge on its own service. Tag from the Projects row in the document editor, or from the project page.

An agent working in any tagged project may revise a shared document, which changes it for every project it touches — the revision check stops one edit from silently overwriting another.

Getting the most out of it#

Write knowledge the way you'd brief a careful new reviewer: concrete, specific, and honest about tradeoffs. "We don't sanitize in the DAO layer — it's done at the API boundary in middleware/validate.ts" saves the agent a wrong finding and teaches it where to look when the boundary moves.

Use the metadata for navigation, not as a substitute for the body. A good description helps the agent decide whether to open a document; headings, examples, tables, and links in the body help it use the document correctly.

Knowledge is reference evidence, not an instruction channel. Agents check important claims against the current repository, and a document should never carry credentials, secrets, transient pull-request state, or unsupported guesses.