# 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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 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: | Field | Requirement | Meaning | | --- | --- | --- | | `type` | Always stored | An open-ended kind such as `Architecture Decision`, `Playbook`, or `API Endpoint`. Structured creates default to `Reference`; imported OKF documents must declare it. | | `title` | Always stored | The human-readable concept name. For an imported document, Ozone can infer it from the first level-one heading or supplied path. | | `description` | Optional | One sentence used in indexes, search results, and previews. | | `resource` | Optional | The canonical URI for an asset the concept describes. The editor labels this **Source link**. | | `tags` | Optional | Cross-cutting OKF labels such as `auth`, `payments`, or `incident`. | | `timestamp` | Generated | The time of the last stored update. | 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: | Actor | Knowledge rights | | --- | --- | | Human member, or an org-wide `knowledge:write` API key | Create, edit, tag, and delete the organization's documents. | | A project-scoped `knowledge:write` API key | Read and write only documents tagged to its own project. It cannot delete, cannot change which projects a document is tagged to, and cannot edit a document shared with another project — it reads those but never writes them. Untagged org-wide documents are invisible to it. | | Any project agent run | Read, create, and update documents tagged to its project. It cannot delete documents or change tagging. | 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: | Command | What it does | | --- | --- | | `ozone context` | Confirms the authenticated run, project, repositories, and task before the agent acts. | | `ozone knowledge tree` | Prints the bundle hierarchy and summaries, leaving out document bodies. `index` is an alias. Add `--json` and each concept carries a short excerpt as well. | | `ozone knowledge list` | Lists concepts, optionally filtered by exact type, tag, or path prefix. | | `ozone knowledge search ` | Searches paths, metadata, and bodies and returns excerpts for progressive discovery. | | `ozone knowledge get ` | Reads one complete concept and its current revision. Add `--json` for structured output or `--document` for canonical OKF Markdown. | | `ozone knowledge save` | Creates a project-local concept from fields, stdin, a body file, or a complete OKF document. | | `ozone knowledge update ` | Revises or moves a project-local concept using its current revision and an evidence note. | ```sh 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 --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: ```sh 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: ```md --- 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: ```sh 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: ```sh 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.