Skip to content

Agent integration

The vendor tree is arranged so an agent can discover and search source context with ordinary filesystem tools. No okr-specific API is required for basic use.

Human-readable manifest

deps-src/_manifest.md begins by marking the tree as generated, read-only reference material and prints its environment digest. Packages and references have separate tables.

Package rows include name, version, source, license, path, and the normalized Title from DESCRIPTION. Reference rows use the pinned commit in place of a package version and include a DESCRIPTION title when the repository provides one.

This is the best entry point for a person or general-purpose coding agent:

Read deps-src/_manifest.md, then inspect the relevant package under
deps-src/. Treat the tree as generated reference material and do not edit it.

Machine-readable manifest

deps-src/_manifest.json is schema-versioned and includes the same entries plus integrity fields. Its top-level shape is:

{
  "schema": 1,
  "environment_digest": "sha256:...",
  "entries": [
    {
      "kind": "package",
      "name": "admiral",
      "version": "1.3.0",
      "commit": "...",
      "source": "github::pharmaverse/admiral",
      "license": "Apache License (>= 2)",
      "path": "deps-src/admiral",
      "title": "...",
      "tree_digest": "sha256:...",
      "artifact_digest": "sha256:..."
    }
  ]
}

Optional metadata is represented as null. Evaluation harnesses should check schema before consuming entries and use okr verify --json as the integrity gate rather than trusting a manifest in isolation.

Automatic AGENTS.md discovery

With manifest.agents-file = true, sync creates or updates this block:

<!-- okr:begin -->
Vendored R dependency sources and reference repos live in `deps-src/`
(see `deps-src/_manifest.md`). Read them to understand APIs and
internals. Do not edit them; they are generated by `okr sync` and
verified by hash.
<!-- okr:end -->

Only the marker-delimited block is managed. Project-specific instructions before and after it remain untouched. Malformed or duplicate marker pairs are a configuration error rather than an invitation to rewrite the file.

Read-only means generated

The source tree is not an R library and is not intended as an editable vendor fork. Changes inside it fail verification and are replaced by a later sync.

When a source fix is needed, make it in the upstream repository or change the declaration to the desired ref, then run okr sync again. When the context is too broad, adjust vendor.exclude or a per-entry exclusion in okr.toml and regenerate the tree so the lock records the new bytes.

The default .gitignore entry avoids accidentally committing large generated trees. When a sealed evaluation repository intentionally commits the source context, set vendor.gitignore = false and remove any vendor entry that init already added to .gitignore.