Core terms

Use this index for the nouns that show up throughout ota and the payoff each one gives you.

Repo readiness

The state of a repo being runnable and diagnosable, so the next safe step is obvious.

Contract

The explicit ota.yaml that defines repo readiness, so teams stop guessing.

Repo signals

The files and conventions ota inspects to infer the contract without hand-writing it.

Inference

What ota concludes from repo signals when it helps you bootstrap faster.

`ota.yaml`

The repo-local source of truth for readiness, execution, and safe AI-agent guidance.

Doctor

The command that explains blockers and the next safe action, so you know what to fix first.

Build identity

The machine-readable ota binary identity, so CI and automation can distinguish release builds, source builds, and supported contract capabilities.

Commands

Detect

The command that infers a contract from repo signals, so you can compare reality to the current contract.

Init

The command that writes a starter ota.yaml, so you can bootstrap quickly from repo signals.

Validate

The command that checks contract structure and semantics, so edits fail early instead of in use.

Check

The command that runs readiness checks without execution, so you can verify readiness without side effects.

Diff

The command that compares two contracts, so change impact is obvious before merge.

Explain

The command that turns findings into a remediation plan, so the next action is obvious.

Receipt

The read-only receipt artifact from ota receipt or ota workspace receipt, so CI and humans can archive the same readiness state without mutating the repo.

Proof runtime

The evidence command that proves one selected workflow really starts and reaches readiness, so CI or reviewers do not rely on a verbal claim.

Policy review

The ota policy review command that shows the policy-authority boundary, so repo truth and org approval do not get conflated.

`ota up`

The command that prepares the repo and re-checks readiness; service workflow run tasks use proof-owned readiness by default (prepare + verify + teardown + return) unless --detach is selected.

`ota run`

The command that executes a named task, so humans, CI, and agents follow the same path.

Doctor output

Primary Blocker

The headline issue when readiness is blocked, so you fix the right thing first.

Primary Finding

The headline issue when readiness is risky or advisory, so you know what still needs attention.

Finding groups

Grouped summaries with a stable action key, so repeated fixes stay readable.

Contract fields

Tasks

The named repo actions ota can run from the contract, so execution stays explicit.

Checks

The contract-defined checks ota can run to prove readiness, so validation stays repeatable.

Execution

The part of the contract that says how work should run, so the environment boundary stays clear.

Effects

Declared task side effects such as repo writes, network use, or external state mutation, so safety and review are explicit before a task runs.

Toolchain

A managed ecosystem environment, so ota can diagnose and fulfill capabilities like Rust components without hiding them in shell setup.

Runtime

A required runtime version, so toolchain drift is visible early.

Tool

A required command-line dependency version, so local setup matches the contract.

Minimum Ota version

The metadata.ota.minimum_version gate that prevents an older ota binary from pretending it understands a newer contract.

Execution modes

Native vs container vs remote

native runs commands on the host. container uses a container backend, and remote forwards execution to the declared remote transport target.

Policy and agent fields

Policy

The org-level rules that constrain readiness and provisioning, so shared standards stay consistent.

Policy Pack

The shared .ota/org-policy.yaml rules above repo contracts, so many repos can share guardrails.

Effect governance

The policies.effects rules that decide whether selected task-path side effects are allowed, warned, or denied before execution starts.

Effect override

The --effect-override <effect>=<allow|warn|deny> one-invocation override for ota run and ota up when a reviewed temporary policy decision is needed.

`OTA_POLICY`

An explicit override for a local policy file or hosted policy URL, so ota uses the right source.

Workspace policy

A workspace-level policy source declared in ota.workspace.yaml, so one rule set can cover several repos.

Environment Variables

How ota decides which environment values apply, so the result is explainable.

Provisioning

The contract-driven path that installs or selects required runtimes and tools, so setup is repeatable.

Provisioning source

The effective approved source ota resolves for one runtime or tool on the current target, so installs stay auditable.

Adapter bootstrap

The separate policy layer that tells ota how it may install a missing adapter such as brew, choco, or sdkman before repo provisioning retries.

Provenance

The evidence about where a value, inference, or policy decision came from, so receipts, detect, and explain output stay trustworthy.

Safe tasks

The tasks an AI agent may run safely, so automation has a default path.

Agent posture

The declared authority model for agent edits, so strict readiness slices and broader authoring slices stay distinct.

Verify after changes

The tasks to rerun after edits, so the review loop stays obvious.

Writable paths

The paths an AI agent may edit, so the edit boundary is explicit.

Protected paths

The paths an AI agent should avoid changing casually, so sensitive files stay protected.

Container backend

The execution mode that runs setup and provisioning inside a container, so host setup stays isolated.