{"site":"ota","schema_version":"1.1","generated_at":"2026-05-29T19:15:26.696Z","docs_count":84,"section_count":669,"canonical_origin":"https://ota.run","intents":{"learn":21,"operate":5,"reference":35,"copy":23},"pages":[{"slug":"getting-started","title":"Getting started","summary":"Entry guide for first-time users to diagnose readiness and establish the default ota workflow.","href":"/docs/getting-started","canonical_url":"https://ota.run/docs/getting-started","category":"Getting started","intent":"learn","difficulty":"basic","audience":"new-users","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"Start here","href":"/docs/getting-started#getting-started-1-start-here","canonical_url":"https://ota.run/docs/getting-started#getting-started-1-start-here","summary":"Getting started · section 1","snippet":"Start here ota works best when you begin with diagnosis, not guessing. If the repo already has `ota.yaml`, use `ota doctor` to understand readiness before writing anything. Revi...","page_title":"Getting started"},{"title":"When you do not have a contract yet","href":"/docs/getting-started#getting-started-2-when-you-do-not-have-a-contract-yet","canonical_url":"https://ota.run/docs/getting-started#getting-started-2-when-you-do-not-have-a-contract-yet","summary":"Getting started · section 2","snippet":"When you do not have a contract yet Use detect to infer a starter contract from the repo signals you already have. Detector-led onboarding lane bash ota doctor ota detect --dry-...","page_title":"Getting started"},{"title":"The default loop","href":"/docs/getting-started#getting-started-3-the-default-loop","canonical_url":"https://ota.run/docs/getting-started#getting-started-3-the-default-loop","summary":"Getting started · section 3","snippet":"The default loop doctor first contract second write only after review keep JSON output for CI and automation Default operational loop bash ota doctor ota explain ota init --dry-...","page_title":"Getting started"}],"in_primary_nav":true},{"slug":"install","title":"Install","summary":"Installation paths for release binaries and source-based local development.","href":"/docs/install","canonical_url":"https://ota.run/docs/install","category":"Getting started","intent":"learn","difficulty":"basic","audience":"new-users","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"Release install","href":"/docs/install#install-1-release-install","canonical_url":"https://ota.run/docs/install#install-1-release-install","summary":"Install · section 1","snippet":"Release install For most users, install the published binary. That keeps the setup path short and matches the public story. Install skills after ota is on PATH. The Ota skill so...","page_title":"Install"},{"title":"From source","href":"/docs/install#install-2-from-source","canonical_url":"https://ota.run/docs/install#install-2-from-source","summary":"Install · section 2","snippet":"From source Use the source install path when you are working from a cloned checkout. Install from source bash ./scripts/install.sh --from-source Windows PowerShell powershell po...","page_title":"Install"},{"title":"After installation","href":"/docs/install#install-3-after-installation","canonical_url":"https://ota.run/docs/install#install-3-after-installation","summary":"Install · section 3","snippet":"After installation Confirm the binary is available with `ota --version`. Use `ota --version --json` when CI or tools need explicit build provenance (`semver`, `source_build`, `c...","page_title":"Install"}],"in_primary_nav":true},{"slug":"quickstart","title":"Quickstart","summary":"Fast operational path from diagnosis to first successful repo preparation.","href":"/docs/quickstart","canonical_url":"https://ota.run/docs/quickstart","category":"Getting started","intent":"operate","difficulty":"basic","audience":"new-users","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"Existing contract","href":"/docs/quickstart#quickstart-1-existing-contract","canonical_url":"https://ota.run/docs/quickstart#quickstart-1-existing-contract","summary":"Quickstart · section 1","snippet":"Existing contract Use the contract when the repo already knows how it wants to run. Use `ota execution topology` when you want the declared runtime graph reviewed before executi...","page_title":"Quickstart"},{"title":"No contract yet","href":"/docs/quickstart#quickstart-2-no-contract-yet","canonical_url":"https://ota.run/docs/quickstart#quickstart-2-no-contract-yet","summary":"Quickstart · section 2","snippet":"No contract yet Use detector-led init when ota should infer the first draft from repo signals. Use the starter-pack path when you want to choose an explicit conventional starter...","page_title":"Quickstart"},{"title":"What to remember","href":"/docs/quickstart#quickstart-3-what-to-remember","canonical_url":"https://ota.run/docs/quickstart#quickstart-3-what-to-remember","summary":"Quickstart · section 3","snippet":"What to remember `ota doctor` tells you what is missing. `ota detect` shows what ota can infer. `ota init --packs` is the compare-first path when you want to choose a convention...","page_title":"Quickstart"}],"in_primary_nav":true},{"slug":"first-ota-yaml","title":"First `ota.yaml`","summary":"A starter contract should be obvious, stable, and runnable.","href":"/docs/first-ota-yaml","canonical_url":"https://ota.run/docs/first-ota-yaml","category":"Getting started","intent":"learn","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Minimal useful starter","href":"/docs/first-ota-yaml#first-ota-yaml-1-minimal-useful-starter","canonical_url":"https://ota.run/docs/first-ota-yaml#first-ota-yaml-1-minimal-useful-starter","summary":"First `ota.yaml` · section 1","snippet":"Minimal useful starter A starter contract should be obvious, stable, and runnable. Starter contract yaml version: 1 project: name: ota-web type: application runtimes: node: \"22\"...","page_title":"First `ota.yaml`"},{"title":"What makes it useful","href":"/docs/first-ota-yaml#first-ota-yaml-2-what-makes-it-useful","canonical_url":"https://ota.run/docs/first-ota-yaml#first-ota-yaml-2-what-makes-it-useful","summary":"First `ota.yaml` · section 2","snippet":"What makes it useful it names the repo it declares the core runtime and tools it defines safe tasks and verification tasks it gives agents a deterministic entrypoint","page_title":"First `ota.yaml`"}],"in_primary_nav":true},{"slug":"reference","title":"Reference","summary":"Reference hub for command behavior, contract semantics, and workspace orchestration.","href":"/docs/reference","canonical_url":"https://ota.run/docs/reference","category":"Reference","intent":"reference","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"Command","href":"/docs/reference#reference-1-command","canonical_url":"https://ota.run/docs/reference#reference-1-command","summary":"Reference · section 1","snippet":"Command Flags, subcommands, and examples for every command. Command Every user-facing command and subcommand in one place. Use this when you need command behavior, flags, and ex...","page_title":"Reference"},{"title":"Contract","href":"/docs/reference#reference-2-contract","canonical_url":"https://ota.run/docs/reference#reference-2-contract","summary":"Reference · section 2","snippet":"Contract Schema and semantics for authoring or reviewing `ota.yaml`. Contract The repo contract fields, sections, and meanings. Use this when you are authoring or reviewing `ota...","page_title":"Reference"},{"title":"Workspace","href":"/docs/reference#reference-3-workspace","canonical_url":"https://ota.run/docs/reference#reference-3-workspace","summary":"Reference · section 3","snippet":"Workspace Multi-repo orchestration and acquisition rules. Workspace The workspace contract and multi-repo orchestration model. Use this when a workspace coordinates multiple repos.","page_title":"Reference"},{"title":"Policy and provisioning","href":"/docs/reference#reference-4-policy-and-provisioning","canonical_url":"https://ota.run/docs/reference#reference-4-policy-and-provisioning","summary":"Reference · section 4","snippet":"Policy and provisioning The org layer above the repo contract and the adapter families that provision approved runtimes and tools. Policy concepts The rule layer above the repo ...","page_title":"Reference"}],"in_primary_nav":true},{"slug":"command-reference","title":"Command","summary":"Canonical command selection and usage guide for repo and workspace flows.","href":"/docs/reference/command","canonical_url":"https://ota.run/docs/reference/command","category":"Reference","intent":"reference","difficulty":"intermediate","audience":"automation-builders","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"Start with this flow","href":"/docs/reference/command#command-reference-1-start-with-this-flow","canonical_url":"https://ota.run/docs/reference/command#command-reference-1-start-with-this-flow","summary":"Command · section 1","snippet":"Start with this flow Use one command first, then move only when the output tells you the next safe action. `ota doctor` when you need the repo blocker and the highest-priority n...","page_title":"Command"},{"title":"How to choose","href":"/docs/reference/command#command-reference-2-how-to-choose","canonical_url":"https://ota.run/docs/reference/command#command-reference-2-how-to-choose","summary":"Command · section 2","snippet":"How to choose Choose by intent first, then by side effect; this keeps review and production behavior predictable. choose `doctor` for triage and blocker-first diagnosis choose `...","page_title":"Command"},{"title":"Readiness and contract","href":"/docs/reference/command#command-reference-3-readiness-and-contract","canonical_url":"https://ota.run/docs/reference/command#command-reference-3-readiness-and-contract","summary":"Command · section 3","snippet":"Readiness and contract Use these when you need to decide whether the repo is ready or how to shape it. ota doctor Diagnose the current repo readiness state in native, container,...","page_title":"Command"},{"title":"Init paths","href":"/docs/reference/command#command-reference-4-init-paths","canonical_url":"https://ota.run/docs/reference/command#command-reference-4-init-paths","summary":"Command · section 4","snippet":"Init paths `ota init` now has two real paths, and the important boundary is whether ota should infer the first draft or whether you want to pick a conventional starter explicitl...","page_title":"Command"},{"title":"Execution and inspection","href":"/docs/reference/command#command-reference-5-execution-and-inspection","canonical_url":"https://ota.run/docs/reference/command#command-reference-5-execution-and-inspection","summary":"Command · section 5","snippet":"Execution and inspection Use these once the contract exists and you need to run, compare, or explain it. `proof` is Ota's evidence layer: use it when a reviewer, CI job, or agen...","page_title":"Command"},{"title":"Workspace commands","href":"/docs/reference/command#command-reference-6-workspace-commands","canonical_url":"https://ota.run/docs/reference/command#command-reference-6-workspace-commands","summary":"Command · section 6","snippet":"Workspace commands Use these when multiple repos need to be discovered, prepared, or run together. ota workspace Work with ota workspace contracts. Use this when multiple repos ...","page_title":"Command"},{"title":"Supporting commands","href":"/docs/reference/command#command-reference-7-supporting-commands","canonical_url":"https://ota.run/docs/reference/command#command-reference-7-supporting-commands","summary":"Command · section 7","snippet":"Supporting commands These help agents, CI, and maintenance flows stay aligned with the contract. ota services List declared services from the contract. Use this when services ar...","page_title":"Command"},{"title":"Global output modifiers","href":"/docs/reference/command#command-reference-8-global-output-modifiers","canonical_url":"https://ota.run/docs/reference/command#command-reference-8-global-output-modifiers","summary":"Command · section 8","snippet":"Global output modifiers These shape how commands speak without changing the underlying result. `--concise`: shorter text output for high-noise commands while preserving decision...","page_title":"Command"},{"title":"Progress behavior","href":"/docs/reference/command#command-reference-9-progress-behavior","canonical_url":"https://ota.run/docs/reference/command#command-reference-9-progress-behavior","summary":"Command · section 9","snippet":"Progress behavior Progress handling stays predictable so interactive runs feel calm instead of noisy. Readiness-first path bash ota doctor ota check ota validate Execution path ...","page_title":"Command"},{"title":"Readiness commands","href":"/docs/reference/command#command-reference-10-readiness-commands","canonical_url":"https://ota.run/docs/reference/command#command-reference-10-readiness-commands","summary":"Command · section 10","snippet":"Readiness commands Use this when you want the readiness surface to stay calm and diagnosis-first instead of falling back to the shared spinner. Readiness commands bash ota docto...","page_title":"Command"},{"title":"Execution path","href":"/docs/reference/command#command-reference-11-execution-path","canonical_url":"https://ota.run/docs/reference/command#command-reference-11-execution-path","summary":"Command · section 11","snippet":"Execution path Use this when you want the execution path to stay stream-aware: `ota run` keeps its own execution-focused behavior, while `ota up` defaults to the shared spinner ...","page_title":"Command"},{"title":"Workspace operations","href":"/docs/reference/command#command-reference-12-workspace-operations","canonical_url":"https://ota.run/docs/reference/command#command-reference-12-workspace-operations","summary":"Command · section 12","snippet":"Workspace operations Use this when workspace commands should stay spinner-backed in interactive terminals without inventing custom per-command progress output. Workspace operati...","page_title":"Command"},{"title":"Workspace waiters","href":"/docs/reference/command#command-reference-13-workspace-waiters","canonical_url":"https://ota.run/docs/reference/command#command-reference-13-workspace-waiters","summary":"Command · section 13","snippet":"Workspace waiters Use this when a workspace command should show the shared spinner only while it is actually waiting on work, then return to summary-first output. Workspace wait...","page_title":"Command"},{"title":"JSON safety","href":"/docs/reference/command#command-reference-14-json-safety","canonical_url":"https://ota.run/docs/reference/command#command-reference-14-json-safety","summary":"Command · section 14","snippet":"JSON safety Use this when stdout must remain valid JSON and any spinner output needs to stay on stderr instead of corrupting machine-readable output. JSON safety bash ota worksp...","page_title":"Command"},{"title":"Interactive extras","href":"/docs/reference/command#command-reference-15-interactive-extras","canonical_url":"https://ota.run/docs/reference/command#command-reference-15-interactive-extras","summary":"Command · section 15","snippet":"Interactive extras Use this when you need to know which interactive commands may surface extra metadata or a best-effort update notice beyond the main command result. Interactiv...","page_title":"Command"},{"title":"When to use debug","href":"/docs/reference/command#command-reference-16-when-to-use-debug","canonical_url":"https://ota.run/docs/reference/command#command-reference-16-when-to-use-debug","summary":"Command · section 16","snippet":"When to use debug Debug is for the commands that orchestrate multiple steps or need provenance. Repo debug bash ota doctor --debug ota doctor --mode container --debug Workspace ...","page_title":"Command"},{"title":"Best fit","href":"/docs/reference/command#command-reference-17-best-fit","canonical_url":"https://ota.run/docs/reference/command#command-reference-17-best-fit","summary":"Command · section 17","snippet":"Best fit Use debug first on commands that orchestrate multiple steps or multiple repos, where provenance and intermediate decisions matter most. Best fit bash ota up ota run <ta...","page_title":"Command"},{"title":"Situational","href":"/docs/reference/command#command-reference-18-situational","canonical_url":"https://ota.run/docs/reference/command#command-reference-18-situational","summary":"Command · section 18","snippet":"Situational Use debug here when you need provenance, resolver detail, or deeper failure context, not as the default way to read the command. Situational bash ota doctor ota dete...","page_title":"Command"},{"title":"Usually skip","href":"/docs/reference/command#command-reference-19-usually-skip","canonical_url":"https://ota.run/docs/reference/command#command-reference-19-usually-skip","summary":"Command · section 19","snippet":"Usually skip Leave these summary-first unless you are actively debugging, because the normal output is already the better operator surface. Usually skip bash ota validate ota wo...","page_title":"Command"},{"title":"Hosted validation","href":"/docs/reference/command#command-reference-20-hosted-validation","canonical_url":"https://ota.run/docs/reference/command#command-reference-20-hosted-validation","summary":"Command · section 20","snippet":"Hosted validation Hosted validation should stay read-only and consume JSON, not terminal text. do not mutate contracts during hosted validation Repo gating bash ota validate --j...","page_title":"Command"},{"title":"Execution modes","href":"/docs/reference/command#command-reference-21-execution-modes","canonical_url":"https://ota.run/docs/reference/command#command-reference-21-execution-modes","summary":"Command · section 21","snippet":"Execution modes Choose the execution mode that matches how much control and isolation you need. use `tasks.<name>.execution.default_mode` plus `tasks.<name>.execution.modes` whe...","page_title":"Command"},{"title":"Machine integration","href":"/docs/reference/command#command-reference-22-machine-integration","canonical_url":"https://ota.run/docs/reference/command#command-reference-22-machine-integration","summary":"Command · section 22","snippet":"Machine integration Use the machine-facing fields together so scripts do not need to guess. Use `--json` whenever output is consumed by scripts, CI, or agents. Use exit codes to...","page_title":"Command"},{"title":"What not to do","href":"/docs/reference/command#command-reference-23-what-not-to-do","canonical_url":"https://ota.run/docs/reference/command#command-reference-23-what-not-to-do","summary":"Command · section 23","snippet":"What not to do do not use `run` when you have not checked readiness yet do not use `init` when the repo already has a contract you should preserve do not use `detect --write` if...","page_title":"Command"}],"in_primary_nav":true},{"slug":"contract-reference","title":"Contract","summary":"Field-level specification for ota.yaml and how contract choices affect readiness and execution.","href":"/docs/reference/contract","canonical_url":"https://ota.run/docs/reference/contract","category":"Reference","intent":"reference","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"What this file is for","href":"/docs/reference/contract#contract-reference-1-what-this-file-is-for","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-1-what-this-file-is-for","summary":"Contract · section 1","snippet":"What this file is for Use `ota.yaml` when you want one repo-local file to explain readiness, execution, and safe automation. The file tells ota what the repo needs before it is ...","page_title":"Contract"},{"title":"Current high-signal fields","href":"/docs/reference/contract#contract-reference-2-current-high-signal-fields","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-2-current-high-signal-fields","summary":"Contract · section 2","snippet":"Current high-signal fields These fields are the ones teams are now using most for contract trust and automation safety. Keep them explicit when they apply instead of relying on ...","page_title":"Contract"},{"title":"version (required)","href":"/docs/reference/contract#contract-reference-3-version-required","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-3-version-required","summary":"Contract · section 3","snippet":"version (required) `version` tells ota which contract shape it should parse. Treat `version` as the parser contract gate and set it first. Set this first; if it is wrong, valida...","page_title":"Contract"},{"title":"project (required)","href":"/docs/reference/contract#contract-reference-4-project-required","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-4-project-required","summary":"Contract · section 4","snippet":"project (required) `project` gives ota stable repo identity and an operations anchor for reporting. Use `project` whenever you need deterministic repo identity across CI, receip...","page_title":"Contract"},{"title":"toolchains","href":"/docs/reference/contract#contract-reference-5-toolchains","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-5-toolchains","summary":"Contract · section 5","snippet":"toolchains `toolchains` defines managed ecosystem environments that ota can diagnose and, when explicitly allowed, fulfill on selected run paths. Use `toolchains` when ota must ...","page_title":"Contract"},{"title":"runtimes","href":"/docs/reference/contract#contract-reference-6-runtimes","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-6-runtimes","summary":"Contract · section 6","snippet":"runtimes `runtimes` defines what language/toolchain execution requires before normal work can run. Use `runtimes` when startup depends on language/toolchain compatibility across...","page_title":"Contract"},{"title":"tools","href":"/docs/reference/contract#contract-reference-7-tools","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-7-tools","summary":"Contract · section 7","snippet":"tools `tools` declares CLI dependencies required by tasks before execution begins. Use `tools` when CI, agents, and local dev need stable tool gates before execution. Use `tools...","page_title":"Contract"},{"title":"Native prerequisites","href":"/docs/reference/contract#contract-reference-8-native-prerequisites","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-8-native-prerequisites","summary":"Contract · section 8","snippet":"Native prerequisites `native_prerequisites` describes host OS build-tool bundles that are not language runtimes or normal CLI tools. Use it for Linux compiler packages, macOS Xc...","page_title":"Contract"},{"title":"env","href":"/docs/reference/contract#contract-reference-9-env","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-9-env","summary":"Contract · section 9","snippet":"env `env` defines which variables are owned by the repo and how each variable is resolved for validation and execution. Use `env` when deterministic precedence and secret handli...","page_title":"Contract"},{"title":"services","href":"/docs/reference/contract#contract-reference-10-services","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-10-services","summary":"Contract · section 10","snippet":"services `services` describes supporting infrastructure such as databases, queues, or local dependencies. Use `services` for deterministic infrastructure startup and readiness w...","page_title":"Contract"},{"title":"surfaces","href":"/docs/reference/contract#contract-reference-11-surfaces","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-11-surfaces","summary":"Contract · section 11","snippet":"surfaces `surfaces` declares reusable endpoint truth that can be attached to runtimes and workflows without duplicating listener structure. Use it when one endpoint definition s...","page_title":"Contract"},{"title":"checks","href":"/docs/reference/contract#contract-reference-12-checks","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-12-checks","summary":"Contract · section 12","snippet":"checks `checks` is a declarative pre-run test list for readiness gates that should stay separate from regular task scripts. Use `checks` when validation should be explicit and m...","page_title":"Contract"},{"title":"tasks","href":"/docs/reference/contract#contract-reference-13-tasks","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-13-tasks","summary":"Contract · section 13","snippet":"tasks `tasks` is the command surface humans and agents run day to day. Each task defines executable behavior, sequencing, and service prerequisites so execution is auditable and...","page_title":"Contract"},{"title":"tasks.<name>.runtime.readiness","href":"/docs/reference/contract#contract-reference-14-tasks-name-runtime-readiness","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-14-tasks-name-runtime-readiness","summary":"Contract · section 14","snippet":"tasks.<name>.runtime.readiness Use `tasks.<name>.runtime.readiness` when a long-running task must prove that its service is genuinely usable before ota treats it as ready. This ...","page_title":"Contract"},{"title":"readiness","href":"/docs/reference/contract#contract-reference-15-readiness","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-15-readiness","summary":"Contract · section 15","snippet":"readiness Use `readiness` when one probe definition should be declared once and reused by checks, workflows, and service/task readiness references. Use this when endpoint truth ...","page_title":"Contract"},{"title":"workflows","href":"/docs/reference/contract#contract-reference-16-workflows","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-16-workflows","summary":"Contract · section 16","snippet":"workflows Use `workflows` when repo behavior should be expressed as canonical operational paths instead of implicit task ordering. Use one workflow for each operational intent w...","page_title":"Contract"},{"title":"prepare vs setup vs run","href":"/docs/reference/contract#contract-reference-17-prepare-vs-setup-vs-run","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-17-prepare-vs-setup-vs-run","summary":"Contract · section 17","snippet":"prepare vs setup vs run `prepare` is explicit host bootstrap before setup and must stay on one native `action` task `setup` is repo preparation such as dependency install or gen...","page_title":"Contract"},{"title":"execution","href":"/docs/reference/contract#contract-reference-18-execution","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-18-execution","summary":"Contract · section 18","snippet":"execution `execution` tells ota where task bodies should run and which backend settings are needed. Ota supports three additive authoring patterns: single-context shorthand, nam...","page_title":"Contract"},{"title":"Container Execution","href":"/docs/reference/contract#contract-reference-19-container-execution","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-19-container-execution","summary":"Contract · section 19","snippet":"Container Execution A Dockerfile builds an image, but `ota.yaml` still defines what is required, safe, and what readiness means for this repo. Use a Dockerfile for environment i...","page_title":"Contract"},{"title":"agent","href":"/docs/reference/contract#contract-reference-20-agent","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-20-agent","summary":"Contract · section 20","snippet":"agent `agent` tells ota which execution and edit boundaries an AI agent may use without guessing. Use `agent` to give automation a trusted execution boundary instead of relying ...","page_title":"Contract"},{"title":"exports","href":"/docs/reference/contract#contract-reference-21-exports","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-21-exports","summary":"Contract · section 21","snippet":"exports `exports` carries repo-owned hints for downstream tooling and is intentionally not part of readiness evaluation. Use `exports` for downstream integrations, not for readi...","page_title":"Contract"},{"title":"policies","href":"/docs/reference/contract#contract-reference-22-policies","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-22-policies","summary":"Contract · section 22","snippet":"policies `policies` is not a readiness execution surface. Use `policies` only as repository-local metadata for policy-aware tooling; execution and readiness stay in typed sectio...","page_title":"Contract"},{"title":"extensions","href":"/docs/reference/contract#contract-reference-23-extensions","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-23-extensions","summary":"Contract · section 23","snippet":"extensions `extensions` declares explicit extension seams for check, export, and remote execution behaviors without changing core contract semantics. Use `extensions` when you n...","page_title":"Contract"},{"title":"metadata","href":"/docs/reference/contract#contract-reference-24-metadata","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-24-metadata","summary":"Contract · section 24","snippet":"metadata `metadata` is an open map for repo-owned descriptive information that should not alter execution semantics. Use `metadata` for ownership and context, and keep operation...","page_title":"Contract"},{"title":"workspace","href":"/docs/reference/contract#contract-reference-25-workspace","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-25-workspace","summary":"Contract · section 25","snippet":"workspace `workspace` is only for a monorepo root that coordinates multiple repos. `workspace.type` is `monorepo` today and only marks an orchestration root. `workspace.members`...","page_title":"Contract"},{"title":"Full example","href":"/docs/reference/contract#contract-reference-26-full-example","canonical_url":"https://ota.run/docs/reference/contract#contract-reference-26-full-example","summary":"Contract · section 26","snippet":"Full example This example shows the full contract shape in one place so users can see how the pieces fit together. Full contract example yaml version: 1 project: name: example-r...","page_title":"Contract"}],"in_primary_nav":true},{"slug":"workspace-guide","title":"Workspace","summary":"Workspace contract and orchestration model for multi-repo readiness and execution.","href":"/docs/reference/workspace","canonical_url":"https://ota.run/docs/reference/workspace","category":"Reference","intent":"operate","difficulty":"advanced","audience":"platform-teams","status":"stable","last_reviewed":"2026-04-11","sections":[{"title":"What this file is for","href":"/docs/reference/workspace#workspace-guide-1-what-this-file-is-for","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-1-what-this-file-is-for","summary":"Workspace · section 1","snippet":"What this file is for `ota.workspace.yaml` is the root contract for a multi-repo workspace. Use it when one root needs to coordinate multiple repos without flattening their indi...","page_title":"Workspace"},{"title":"version","href":"/docs/reference/workspace#workspace-guide-2-version","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-2-version","summary":"Workspace · section 2","snippet":"version `version` tells ota which workspace schema it should parse. Today the only supported version is `1`. Use this field so ota can reject incompatible workspace shapes early...","page_title":"Workspace"},{"title":"workspace","href":"/docs/reference/workspace#workspace-guide-3-workspace","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-3-workspace","summary":"Workspace · section 3","snippet":"workspace Use `workspace` for the workspace identity and shared clone base. This is what makes reports, receipts, and bootstrap behavior understandable to humans and agents. `na...","page_title":"Workspace"},{"title":"repos","href":"/docs/reference/workspace#workspace-guide-4-repos","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-4-repos","summary":"Workspace · section 4","snippet":"repos Use `repos` to declare which repositories belong to the workspace and how they relate to each other. Each entry is one repo member the workspace knows about. `path` is the...","page_title":"Workspace"},{"title":"source","href":"/docs/reference/workspace#workspace-guide-5-source","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-5-source","summary":"Workspace · section 5","snippet":"source Use `source` when a repo might not exist locally yet and ota should know how to acquire it. This is what lets workspace bootstrap happen without inventing a second acquis...","page_title":"Workspace"},{"title":"How ota uses it","href":"/docs/reference/workspace#workspace-guide-6-how-ota-uses-it","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-6-how-ota-uses-it","summary":"Workspace · section 6","snippet":"How ota uses it `ota workspace validate` checks workspace contract correctness. `ota workspace doctor` diagnoses workspace readiness repo by repo and keeps one primary next acti...","page_title":"Workspace"},{"title":"Use cases","href":"/docs/reference/workspace#workspace-guide-7-use-cases","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-7-use-cases","summary":"Workspace · section 7","snippet":"Use cases bootstrapping a fullstack system spread across several repos running one task, like `test`, across repos in deterministic order diagnosing cross-repo readiness failure...","page_title":"Workspace"},{"title":"Validation behavior","href":"/docs/reference/workspace#workspace-guide-8-validation-behavior","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-8-validation-behavior","summary":"Workspace · section 8","snippet":"Validation behavior repo names must not be empty workspace must declare at least one repo repo `path` must be non-empty and point to a directory unless `source` is declared if `...","page_title":"Workspace"},{"title":"What this is not","href":"/docs/reference/workspace#workspace-guide-9-what-this-is-not","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-9-what-this-is-not","summary":"Workspace · section 9","snippet":"What this is not not a replacement for each repo’s own `ota.yaml` not a generic sync engine for any folder tree not a hidden bootstrap system that ignores repo contracts not a d...","page_title":"Workspace"},{"title":"Full example","href":"/docs/reference/workspace#workspace-guide-10-full-example","canonical_url":"https://ota.run/docs/reference/workspace#workspace-guide-10-full-example","summary":"Workspace · section 10","snippet":"Full example This example shows how the workspace file stays separate from repo contracts while still coordinating them. Workspace example yaml version: 1 workspace: name: examp...","page_title":"Workspace"}],"in_primary_nav":true},{"slug":"repo-readiness","title":"Repo Readiness","summary":"Search-oriented introduction to repo readiness, developer onboarding, CI readiness, and ota.yaml as the explicit readiness contract.","href":"/docs/repo-readiness","canonical_url":"https://ota.run/docs/repo-readiness","category":"Getting started","intent":"learn","difficulty":"basic","audience":"maintainers","status":"stable","last_reviewed":"2026-05-12","sections":[{"title":"What repo readiness means","href":"/docs/repo-readiness#repo-readiness-1-what-repo-readiness-means","canonical_url":"https://ota.run/docs/repo-readiness#repo-readiness-1-what-repo-readiness-means","summary":"Repo Readiness · section 1","snippet":"What repo readiness means Repo readiness is the practical state where a cloned repository can explain what it needs, diagnose what is missing, prepare itself, and run the declar...","page_title":"Repo Readiness"},{"title":"Why setup drifts","href":"/docs/repo-readiness#repo-readiness-2-why-setup-drifts","canonical_url":"https://ota.run/docs/repo-readiness#repo-readiness-2-why-setup-drifts","summary":"Repo Readiness · section 2","snippet":"Why setup drifts Most repositories start with useful setup notes, then the truth spreads into scripts, package manifests, Docker files, CI config, environment files, and old pul...","page_title":"Repo Readiness"},{"title":"How ota makes readiness explicit","href":"/docs/repo-readiness#repo-readiness-3-how-ota-makes-readiness-explicit","canonical_url":"https://ota.run/docs/repo-readiness#repo-readiness-3-how-ota-makes-readiness-explicit","summary":"Repo Readiness · section 3","snippet":"How ota makes readiness explicit `ota.yaml` turns readiness into a reviewed repo contract. The contract names runtimes, tools, tasks, services, environment sources, safe agent b...","page_title":"Repo Readiness"},{"title":"Where it fits","href":"/docs/repo-readiness#repo-readiness-4-where-it-fits","canonical_url":"https://ota.run/docs/repo-readiness#repo-readiness-4-where-it-fits","summary":"Repo Readiness · section 4","snippet":"Where it fits open source projects that want first-run setup to be repeatable platform teams standardizing readiness checks across many repos CI pipelines that need stable machi...","page_title":"Repo Readiness"}],"in_primary_nav":true},{"slug":"agent-safe-repo-setup","title":"Agent-Safe Repo Setup","summary":"Guide to agent-safe repository setup with ota.yaml, AGENTS.md guidance, safe tasks, verification, and machine-readable readiness output.","href":"/docs/agent-safe-repo-setup","canonical_url":"https://ota.run/docs/agent-safe-repo-setup","category":"Getting started","intent":"learn","difficulty":"basic","audience":"automation-builders","status":"stable","last_reviewed":"2026-05-12","sections":[{"title":"Why agents need a contract","href":"/docs/agent-safe-repo-setup#agent-safe-repo-setup-1-why-agents-need-a-contract","canonical_url":"https://ota.run/docs/agent-safe-repo-setup#agent-safe-repo-setup-1-why-agents-need-a-contract","summary":"Agent-Safe Repo Setup · section 1","snippet":"Why agents need a contract A coding agent should not infer repository setup from scattered hints. It needs the repo to say which tasks are safe, which files are writable, which ...","page_title":"Agent-Safe Repo Setup"},{"title":"Agent-safe setup flow","href":"/docs/agent-safe-repo-setup#agent-safe-repo-setup-2-agent-safe-setup-flow","canonical_url":"https://ota.run/docs/agent-safe-repo-setup#agent-safe-repo-setup-2-agent-safe-setup-flow","summary":"Agent-Safe Repo Setup · section 2","snippet":"Agent-safe setup flow Start with diagnosis, then move through reviewed setup and verification. The agent should operate from the declared contract, not from a guessed sequence o...","page_title":"Agent-Safe Repo Setup"},{"title":"What the agent can rely on","href":"/docs/agent-safe-repo-setup#agent-safe-repo-setup-3-what-the-agent-can-rely-on","canonical_url":"https://ota.run/docs/agent-safe-repo-setup#agent-safe-repo-setup-3-what-the-agent-can-rely-on","summary":"Agent-Safe Repo Setup · section 3","snippet":"What the agent can rely on Safe tasks `agent.safe_tasks` tells automation which repo tasks are approved for unattended execution. Use this when task execution should be explicit...","page_title":"Agent-Safe Repo Setup"},{"title":"Machine-readable handoff","href":"/docs/agent-safe-repo-setup#agent-safe-repo-setup-4-machine-readable-handoff","canonical_url":"https://ota.run/docs/agent-safe-repo-setup#agent-safe-repo-setup-4-machine-readable-handoff","summary":"Agent-Safe Repo Setup · section 4","snippet":"Machine-readable handoff Agents and automation should consume JSON output for readiness, tasks, checks, and receipts. That keeps behavior stable even when human-facing wording i...","page_title":"Agent-Safe Repo Setup"}],"in_primary_nav":true},{"slug":"repository-automation-tools","title":"Repository Automation Tools","summary":"Search-oriented comparison guide for repository automation tools, repo setup validation, CI readiness, GitHub Actions, Harness, Sonatype Nexus Repository, and ota.","href":"/docs/repository-automation-tools","canonical_url":"https://ota.run/docs/repository-automation-tools","category":"Getting started","intent":"learn","difficulty":"basic","audience":"platform-teams","status":"stable","last_reviewed":"2026-05-29","sections":[{"title":"Best tool for repo setup validation","href":"/docs/repository-automation-tools#repository-automation-tools-1-best-tool-for-repo-setup-validation","canonical_url":"https://ota.run/docs/repository-automation-tools#repository-automation-tools-1-best-tool-for-repo-setup-validation","summary":"Repository Automation Tools · section 1","snippet":"Best tool for repo setup validation ota is built for the specific problem of repository readiness: a cloned repo should explain what it needs, validate that contract, prepare th...","page_title":"Repository Automation Tools"},{"title":"Where ota fits","href":"/docs/repository-automation-tools#repository-automation-tools-2-where-ota-fits","canonical_url":"https://ota.run/docs/repository-automation-tools#repository-automation-tools-2-where-ota-fits","summary":"Repository Automation Tools · section 2","snippet":"Where ota fits Repo readiness and setup validation Use ota when the core need is to make repository setup, task execution, writable paths, services, and verification machine-rea...","page_title":"Repository Automation Tools"},{"title":"When ota is the right layer","href":"/docs/repository-automation-tools#repository-automation-tools-3-when-ota-is-the-right-layer","canonical_url":"https://ota.run/docs/repository-automation-tools#repository-automation-tools-3-when-ota-is-the-right-layer","summary":"Repository Automation Tools · section 3","snippet":"When ota is the right layer the repo has setup instructions spread across README prose, scripts, package manifests, Docker files, and CI config new contributors or agents need a...","page_title":"Repository Automation Tools"},{"title":"How to evaluate repository automation tools","href":"/docs/repository-automation-tools#repository-automation-tools-4-how-to-evaluate-repository-automation-tools","canonical_url":"https://ota.run/docs/repository-automation-tools#repository-automation-tools-4-how-to-evaluate-repository-automation-tools","summary":"Repository Automation Tools · section 4","snippet":"How to evaluate repository automation tools does the tool expose a machine-readable contract, not only commands can humans, CI, and agents run the same readiness checks does it ...","page_title":"Repository Automation Tools"}],"in_primary_nav":true},{"slug":"ota-vs-makefiles-ci-scripts","title":"Ota vs Makefiles, Docker, Nix, and CI Scripts","summary":"Comparison page explaining when to use ota instead of or alongside Makefiles, package scripts, Docker Compose, Devbox, Nix, shell scripts, and CI workflow files.","href":"/docs/ota-vs-makefiles-ci-scripts","canonical_url":"https://ota.run/docs/ota-vs-makefiles-ci-scripts","category":"Getting started","intent":"learn","difficulty":"basic","audience":"maintainers","status":"stable","last_reviewed":"2026-05-29","sections":[{"title":"Short answer","href":"/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-1-short-answer","canonical_url":"https://ota.run/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-1-short-answer","summary":"Ota vs Makefiles, Docker, Nix, and CI Scripts · section 1","snippet":"Short answer Makefiles, package scripts, shell scripts, Docker Compose files, Devbox projects, Nix flakes, and CI workflow files are useful command or environment surfaces. ota ...","page_title":"Ota vs Makefiles, Docker, Nix, and CI Scripts"},{"title":"What each layer answers","href":"/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-2-what-each-layer-answers","canonical_url":"https://ota.run/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-2-what-each-layer-answers","summary":"Ota vs Makefiles, Docker, Nix, and CI Scripts · section 2","snippet":"What each layer answers Makefile or package script Answers which command shortcut to run. Use it for local ergonomics when the setup, dependencies, and service state are already...","page_title":"Ota vs Makefiles, Docker, Nix, and CI Scripts"},{"title":"Why agents need more than scripts","href":"/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-3-why-agents-need-more-than-scripts","canonical_url":"https://ota.run/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-3-why-agents-need-more-than-scripts","summary":"Ota vs Makefiles, Docker, Nix, and CI Scripts · section 3","snippet":"Why agents need more than scripts AI coding agents can call scripts, but scripts rarely explain whether they mutate external state, require network access, depend on services, o...","page_title":"Ota vs Makefiles, Docker, Nix, and CI Scripts"},{"title":"Adoption path","href":"/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-4-adoption-path","canonical_url":"https://ota.run/docs/ota-vs-makefiles-ci-scripts#ota-vs-makefiles-ci-scripts-4-adoption-path","summary":"Ota vs Makefiles, Docker, Nix, and CI Scripts · section 4","snippet":"Adoption path keep existing scripts where they already work add `ota.yaml` to declare readiness, tasks, services, and agent boundaries use `ota validate` in CI before expensive ...","page_title":"Ota vs Makefiles, Docker, Nix, and CI Scripts"}],"in_primary_nav":true},{"slug":"topology-guide","title":"Topology decision guide","summary":"Decision guide for choosing the right requirement, service, and execution scope.","href":"/docs/topology-guide","canonical_url":"https://ota.run/docs/topology-guide","category":"Orientation","intent":"learn","difficulty":"intermediate","audience":"new-users","status":"stable","last_reviewed":"2026-04-21","sections":[{"title":"Start with the decision","href":"/docs/topology-guide#topology-guide-1-start-with-the-decision","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-1-start-with-the-decision","summary":"Topology decision guide · section 1","snippet":"Start with the decision Use the smallest contract scope that stays truthful. If a dependency is shared everywhere, keep it at the repo level. If it only belongs to one execution...","page_title":"Topology decision guide"},{"title":"Shared baseline vs execution context requirements","href":"/docs/topology-guide#topology-guide-2-shared-baseline-vs-execution-context-requirements","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-2-shared-baseline-vs-execution-context-requirements","summary":"Topology decision guide · section 2","snippet":"Shared baseline vs execution context requirements Use repo-wide requirements for dependencies that every execution path needs. Use execution-context requirements when only one p...","page_title":"Topology decision guide"},{"title":"When the base context is too broad","href":"/docs/topology-guide#topology-guide-3-when-the-base-context-is-too-broad","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-3-when-the-base-context-is-too-broad","summary":"Topology decision guide · section 3","snippet":"When the base context is too broad If one host task needs only a shell and a file write, while the rest of the host-side workflow needs npm, Poetry, or other heavier tooling, do...","page_title":"Topology decision guide"},{"title":"Contract baseline vs task-scoped requirements","href":"/docs/topology-guide#topology-guide-4-contract-baseline-vs-task-scoped-requirements","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-4-contract-baseline-vs-task-scoped-requirements","summary":"Topology decision guide · section 4","snippet":"Contract baseline vs task-scoped requirements Keep shared contract requirements at the repo root. Keep contributor-only, quickstart-only, or Docker-only prerequisites on the tas...","page_title":"Topology decision guide"},{"title":"Service-scoped lifecycle","href":"/docs/topology-guide#topology-guide-5-service-scoped-lifecycle","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-5-service-scoped-lifecycle","summary":"Topology decision guide · section 5","snippet":"Service-scoped lifecycle Keep service-specific control and readiness with the service manager when Ota owns that service. A task can still require the service without becoming t...","page_title":"Topology decision guide"},{"title":"Service lifecycle vs task prerequisites","href":"/docs/topology-guide#topology-guide-6-service-lifecycle-vs-task-prerequisites","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-6-service-lifecycle-vs-task-prerequisites","summary":"Topology decision guide · section 6","snippet":"Service lifecycle vs task prerequisites Services own lifecycle and readiness. Tasks can ask for those services without turning them into dependency edges. That keeps the service...","page_title":"Topology decision guide"},{"title":"Native, container, and remote","href":"/docs/topology-guide#topology-guide-7-native-container-and-remote","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-7-native-container-and-remote","summary":"Topology decision guide · section 7","snippet":"Native, container, and remote Pick the execution plane that matches the real work. Native Use native when the repo should run directly on the host OS and its local toolchain. Ch...","page_title":"Topology decision guide"},{"title":"How Ota turns the choice into payoff","href":"/docs/topology-guide#topology-guide-8-how-ota-turns-the-choice-into-payoff","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-8-how-ota-turns-the-choice-into-payoff","summary":"Topology decision guide · section 8","snippet":"How Ota turns the choice into payoff `ota doctor` shows the missing piece first, so the decision is visible instead of implicit. `ota up` now uses setup-aware service orchestrat...","page_title":"Topology decision guide"},{"title":"Common mistakes","href":"/docs/topology-guide#topology-guide-9-common-mistakes","canonical_url":"https://ota.run/docs/topology-guide#topology-guide-9-common-mistakes","summary":"Topology decision guide · section 9","snippet":"Common mistakes Do not put Docker on the top level just because one context needs it. Do not use `depends_on` when you mean a service prerequisite; use `requires_services` inste...","page_title":"Topology decision guide"}],"in_primary_nav":true},{"slug":"glossary","title":"Glossary","summary":"Use this index for the nouns that show up throughout ota and the payoff each one gives you.","href":"/docs/glossary","canonical_url":"https://ota.run/docs/glossary","category":"Orientation","intent":"learn","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Core terms","href":"/docs/glossary#glossary-1-core-terms","canonical_url":"https://ota.run/docs/glossary#glossary-1-core-terms","summary":"Glossary · section 1","snippet":"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 ...","page_title":"Glossary"},{"title":"Commands","href":"/docs/glossary#glossary-2-commands","canonical_url":"https://ota.run/docs/glossary#glossary-2-commands","summary":"Glossary · section 2","snippet":"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 y...","page_title":"Glossary"},{"title":"Doctor output","href":"/docs/glossary#glossary-3-doctor-output","canonical_url":"https://ota.run/docs/glossary#glossary-3-doctor-output","summary":"Glossary · section 3","snippet":"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 advis...","page_title":"Glossary"},{"title":"Contract fields","href":"/docs/glossary#glossary-4-contract-fields","canonical_url":"https://ota.run/docs/glossary#glossary-4-contract-fields","summary":"Glossary · section 4","snippet":"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 va...","page_title":"Glossary"},{"title":"Execution modes","href":"/docs/glossary#glossary-5-execution-modes","canonical_url":"https://ota.run/docs/glossary#glossary-5-execution-modes","summary":"Glossary · section 5","snippet":"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 tr...","page_title":"Glossary"},{"title":"Policy and agent fields","href":"/docs/glossary#glossary-6-policy-and-agent-fields","canonical_url":"https://ota.run/docs/glossary#glossary-6-policy-and-agent-fields","summary":"Glossary · section 6","snippet":"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` ...","page_title":"Glossary"},{"title":"Workspace and agents","href":"/docs/glossary#glossary-7-workspace-and-agents","canonical_url":"https://ota.run/docs/glossary#glossary-7-workspace-and-agents","summary":"Glossary · section 7","snippet":"Workspace and agents Workspace A multi-repo bootstrap contract that coordinates several repos, so shared setup stays consistent. Monorepo member A member declared by a monorepo ...","page_title":"Glossary"}],"in_primary_nav":true},{"slug":"ci-and-pipelines","title":"CI and Pipelines","summary":"How to wire ota into CI without scraping text output.","href":"/docs/ci-and-pipelines","canonical_url":"https://ota.run/docs/ci-and-pipelines","category":"Operational guidance","intent":"operate","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What to run in CI","href":"/docs/ci-and-pipelines#ci-and-pipelines-1-what-to-run-in-ci","canonical_url":"https://ota.run/docs/ci-and-pipelines#ci-and-pipelines-1-what-to-run-in-ci","summary":"CI and Pipelines · section 1","snippet":"What to run in CI Use `ota validate` for contract correctness. Use `ota doctor --json` when you want machine-readable readiness and optional grouped finding summaries with stabl...","page_title":"CI and Pipelines"},{"title":"Real pipeline example","href":"/docs/ci-and-pipelines#ci-and-pipelines-2-real-pipeline-example","canonical_url":"https://ota.run/docs/ci-and-pipelines#ci-and-pipelines-2-real-pipeline-example","summary":"CI and Pipelines · section 2","snippet":"Real pipeline example Portable shell wrapper bash #!/usr/bin/env bash set -uo pipefail mkdir -p .ota/ci ota validate --json . | tee .ota/ci/validate.json validate_status=${PIPES...","page_title":"CI and Pipelines"},{"title":"Why this matters","href":"/docs/ci-and-pipelines#ci-and-pipelines-3-why-this-matters","canonical_url":"https://ota.run/docs/ci-and-pipelines#ci-and-pipelines-3-why-this-matters","summary":"CI and Pipelines · section 3","snippet":"Why this matters CI should use the same readiness rules humans use. Pipeline output should be machine-readable when tools need to fail or annotate on findings. Step summaries an...","page_title":"CI and Pipelines"},{"title":"How to adapt it","href":"/docs/ci-and-pipelines#ci-and-pipelines-4-how-to-adapt-it","canonical_url":"https://ota.run/docs/ci-and-pipelines#ci-and-pipelines-4-how-to-adapt-it","summary":"CI and Pipelines · section 4","snippet":"How to adapt it keep the runner wrapper specific to the CI system keep ota commands identical across runners use `doctor --json` as the feedback surface and `receipt --json --ar...","page_title":"CI and Pipelines"},{"title":"Provider shapes","href":"/docs/ci-and-pipelines#ci-and-pipelines-5-provider-shapes","canonical_url":"https://ota.run/docs/ci-and-pipelines#ci-and-pipelines-5-provider-shapes","summary":"CI and Pipelines · section 5","snippet":"Provider shapes GitHub Actions: use `ota-run/action@v1` when you want step summaries, annotations, pull-request comments, and uploaded receipt artifacts without hand-written glu...","page_title":"CI and Pipelines"}],"in_primary_nav":true},{"slug":"contexts","title":"Execution Contexts","summary":"Guide to execution contexts, default context selection, task overrides, mode-aware branches, and how contexts connect services, readiness, and published endpoints.","href":"/docs/contexts","canonical_url":"https://ota.run/docs/contexts","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"new-users","status":"stable","last_reviewed":"2026-04-22","sections":[{"title":"Why contexts exist","href":"/docs/contexts#contexts-1-why-contexts-exist","canonical_url":"https://ota.run/docs/contexts#contexts-1-why-contexts-exist","summary":"Execution Contexts · section 1","snippet":"Why contexts exist Contexts tell Ota where a task actually runs. That is one of the strongest parts of the product because it lets the same repo stay honest about host work, con...","page_title":"Execution Contexts"},{"title":"What a context changes","href":"/docs/contexts#contexts-2-what-a-context-changes","canonical_url":"https://ota.run/docs/contexts#contexts-2-what-a-context-changes","summary":"Execution Contexts · section 2","snippet":"What a context changes Execution plane The same task intent can mean host execution, container execution, or remote execution. Contexts make that explicit. Use this when the rep...","page_title":"Execution Contexts"},{"title":"Default context versus task context","href":"/docs/contexts#contexts-3-default-context-versus-task-context","canonical_url":"https://ota.run/docs/contexts#contexts-3-default-context-versus-task-context","summary":"Execution Contexts · section 3","snippet":"Default context versus task context Use `execution.default_context` when most tasks belong to one execution plane. Use `tasks.<name>.context` only when a task should intentional...","page_title":"Execution Contexts"},{"title":"Execution Authoring Patterns","href":"/docs/contexts#contexts-4-execution-authoring-patterns","canonical_url":"https://ota.run/docs/contexts#contexts-4-execution-authoring-patterns","summary":"Execution Contexts · section 4","snippet":"Execution Authoring Patterns Choose the smallest execution model that stays truthful for your repo. Use `extends` as the clean way to share one execution base across multiple na...","page_title":"Execution Contexts"},{"title":"When to use mode-aware branches","href":"/docs/contexts#contexts-5-when-to-use-mode-aware-branches","canonical_url":"https://ota.run/docs/contexts#contexts-5-when-to-use-mode-aware-branches","summary":"Execution Contexts · section 5","snippet":"When to use mode-aware branches Sometimes one task intent should stay the same while the execution plane changes. That is what task-level mode-aware execution is for. It lets `o...","page_title":"Execution Contexts"},{"title":"Contexts, services, and app URLs","href":"/docs/contexts#contexts-6-contexts-services-and-app-urls","canonical_url":"https://ota.run/docs/contexts#contexts-6-contexts-services-and-app-urls","summary":"Execution Contexts · section 6","snippet":"Contexts, services, and app URLs Contexts are where repo readiness stops being abstract. A service can be ready from one context and unreachable from another. A workload can bin...","page_title":"Execution Contexts"},{"title":"Listener shorthand","href":"/docs/contexts#contexts-7-listener-shorthand","canonical_url":"https://ota.run/docs/contexts#contexts-7-listener-shorthand","summary":"Execution Contexts · section 7","snippet":"Listener shorthand Listener shorthand is the compact authoring path for common local app ports. Use it when one task exposes one fixed HTTP or TCP port and the host-visible endp...","page_title":"Execution Contexts"},{"title":"Common local HTTP listener","href":"/docs/contexts#contexts-8-common-local-http-listener","canonical_url":"https://ota.run/docs/contexts#contexts-8-common-local-http-listener","summary":"Execution Contexts · section 8","snippet":"Common local HTTP listener Use this for a local web app, API server, or docs preview that should be reachable at the same fixed loopback port it listens on. `web.http: 3000` exp...","page_title":"Execution Contexts"},{"title":"Common local TCP listener","href":"/docs/contexts#contexts-9-common-local-tcp-listener","canonical_url":"https://ota.run/docs/contexts#contexts-9-common-local-tcp-listener","summary":"Execution Contexts · section 9","snippet":"Common local TCP listener Use this when an accepting socket is the correct readiness and reachability signal. `redis.tcp: 6379` expands to a TCP listener on fixed port `6379` wi...","page_title":"Execution Contexts"},{"title":"Full HTTP listener form","href":"/docs/contexts#contexts-10-full-http-listener-form","canonical_url":"https://ota.run/docs/contexts#contexts-10-full-http-listener-form","summary":"Execution Contexts · section 10","snippet":"Full HTTP listener form This is the full listener shape behind the HTTP shorthand. Use it directly when bind address, projected host address, host port mode, primary listener se...","page_title":"Execution Contexts"},{"title":"Task target bindings","href":"/docs/contexts#contexts-11-task-target-bindings","canonical_url":"https://ota.run/docs/contexts#contexts-11-task-target-bindings","summary":"Execution Contexts · section 11","snippet":"Task target bindings Use `tasks.<name>.targets.<target>` when one task should point at either another repo-managed app by service identity or one explicit declared URL. Keep the...","page_title":"Execution Contexts"},{"title":"What breaks without context","href":"/docs/contexts#contexts-12-what-breaks-without-context","canonical_url":"https://ota.run/docs/contexts#contexts-12-what-breaks-without-context","summary":"Execution Contexts · section 12","snippet":"What breaks without context If the same repo mixes host tools and container workloads, missing context information creates subtle, environment-dependent failures. The same task ...","page_title":"Execution Contexts"},{"title":"Host setup, container app","href":"/docs/contexts#contexts-13-host-setup-container-app","canonical_url":"https://ota.run/docs/contexts#contexts-13-host-setup-container-app","summary":"Execution Contexts · section 13","snippet":"Host setup, container app Keep Docker and Compose on the host while app work happens in a container context. Use this when host orchestration and containerized app execution bot...","page_title":"Execution Contexts"},{"title":"One app, two truthful start paths","href":"/docs/contexts#contexts-14-one-app-two-truthful-start-paths","canonical_url":"https://ota.run/docs/contexts#contexts-14-one-app-two-truthful-start-paths","summary":"Execution Contexts · section 14","snippet":"One app, two truthful start paths Keep one user intent (`start`) while behavior shifts by backend. Use this when operators need stable task naming across host and container exec...","page_title":"Execution Contexts"},{"title":"Full listener form: container bind, host URL","href":"/docs/contexts#contexts-15-full-listener-form-container-bind-host-url","canonical_url":"https://ota.run/docs/contexts#contexts-15-full-listener-form-container-bind-host-url","summary":"Execution Contexts · section 15","snippet":"Full listener form: container bind, host URL Keep container bind behavior stable while Ota publishes a host URL users can open. Use the full listener form when a container workl...","page_title":"Execution Contexts"},{"title":"Container memory, one-run override","href":"/docs/contexts#contexts-16-container-memory-one-run-override","canonical_url":"https://ota.run/docs/contexts#contexts-16-container-memory-one-run-override","summary":"Execution Contexts · section 16","snippet":"Container memory, one-run override Keep container memory policy in context and still allow one-run overrides. Use this when local reliability depends on higher than default memo...","page_title":"Execution Contexts"},{"title":"Decision guide","href":"/docs/contexts#contexts-17-decision-guide","canonical_url":"https://ota.run/docs/contexts#contexts-17-decision-guide","summary":"Execution Contexts · section 17","snippet":"Decision guide Set `execution.default_context` when one backend plane is the default operating mode for most tasks. Use `execution.contexts.<name>.extends` when two contexts sha...","page_title":"Execution Contexts"}],"in_primary_nav":true},{"slug":"environment-model","title":"Environment Model","summary":"Guide to env.vars, env.sources, workspace and org policy precedence, context/task/mode execution env, OTA_WORKSPACE, derived cache env, and detect versus runtime boundaries.","href":"/docs/environment-model","canonical_url":"https://ota.run/docs/environment-model","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-04-29","sections":[{"title":"Why this page exists","href":"/docs/environment-model#environment-model-1-why-this-page-exists","canonical_url":"https://ota.run/docs/environment-model#environment-model-1-why-this-page-exists","summary":"Environment Model · section 1","snippet":"Why this page exists Environment handling in Ota is now more than one small field in the contract. A repo can declare root env requirements, explicit file-backed sources, contex...","page_title":"Environment Model"},{"title":"The model in one view","href":"/docs/environment-model#environment-model-2-the-model-in-one-view","canonical_url":"https://ota.run/docs/environment-model#environment-model-2-the-model-in-one-view","summary":"Environment Model · section 2","snippet":"The model in one view `env.vars` is the requirement layer: required, secret, default, allowed, and `PATH` composition `env.vars.<NAME>.default` lets the contract supply a non-se...","page_title":"Environment Model"},{"title":"Contract defaults can replace simple dotenv defaults","href":"/docs/environment-model#environment-model-3-contract-defaults-can-replace-simple-dotenv-defaults","canonical_url":"https://ota.run/docs/environment-model#environment-model-3-contract-defaults-can-replace-simple-dotenv-defaults","summary":"Environment Model · section 3","snippet":"Contract defaults can replace simple dotenv defaults When a value is not secret and the repo should have one stable fallback, keep that truth in `env.vars.<NAME>.default` instea...","page_title":"Environment Model"},{"title":"Winner order","href":"/docs/environment-model#environment-model-4-winner-order","canonical_url":"https://ota.run/docs/environment-model#environment-model-4-winner-order","summary":"Environment Model · section 4","snippet":"Winner order Root env resolution and execution env injection are related, but they are not the same layer. Repo commands resolve declared env vars in this order: task env, org p...","page_title":"Environment Model"},{"title":"Declared source kinds","href":"/docs/environment-model#environment-model-5-declared-source-kinds","canonical_url":"https://ota.run/docs/environment-model#environment-model-5-declared-source-kinds","summary":"Environment Model · section 5","snippet":"Declared source kinds Source kinds are curated on purpose. Ota supports the common deterministic formats directly and rejects open-ended parser plugins or runtime auto-detection...","page_title":"Environment Model"},{"title":"Execution-only env","href":"/docs/environment-model#environment-model-6-execution-only-env","canonical_url":"https://ota.run/docs/environment-model#environment-model-6-execution-only-env","summary":"Environment Model · section 6","snippet":"Execution-only env Execution env exists so one plane can carry its own tool paths and runtime defaults without repeating the same values on every task. put shared plane defaults...","page_title":"Environment Model"},{"title":"Detect versus runtime","href":"/docs/environment-model#environment-model-7-detect-versus-runtime","canonical_url":"https://ota.run/docs/environment-model#environment-model-7-detect-versus-runtime","summary":"Environment Model · section 7","snippet":"Detect versus runtime Detect and init can help author the contract, but runtime stays explicit. detector-led init can infer curated `env.sources` from known standard files such ...","page_title":"Environment Model"},{"title":"How to use it","href":"/docs/environment-model#environment-model-8-how-to-use-it","canonical_url":"https://ota.run/docs/environment-model#environment-model-8-how-to-use-it","summary":"Environment Model · section 8","snippet":"How to use it start with `env.vars` when the repo needs one value to be real, reviewable, and enforceable add `env.sources` only when the repo intentionally depends on source fi...","page_title":"Environment Model"}],"in_primary_nav":true},{"slug":"assist","title":"Ota Assist","summary":"Operator guide to ota assist, covering preview-first reviewed mutation, current `ota assist declare-readiness`, `ota assist declare-service`, `ota assist bind-task`, `ota assist wire-setup`, `ota assist declare-env`, `ota assist add-task`, and `ota assist normalize` support, task versus managed-service targeting, reviewed target-edge binding, phased setup wiring, env declaration, task creation, canonical setup normalization, monorepo member behavior, refusal cases, and JSON integration.","href":"/docs/assist","canonical_url":"https://ota.run/docs/assist","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-05-05","sections":[{"title":"Why assist exists","href":"/docs/assist#assist-1-why-assist-exists","canonical_url":"https://ota.run/docs/assist#assist-1-why-assist-exists","summary":"Ota Assist · section 1","snippet":"Why assist exists Ota already knows how to validate contracts, inspect declared topology, and explain readiness truth. `ota assist` exists so ota can turn that knowledge into on...","page_title":"Ota Assist"},{"title":"Current shipped operations","href":"/docs/assist#assist-2-current-shipped-operations","canonical_url":"https://ota.run/docs/assist#assist-2-current-shipped-operations","summary":"Ota Assist · section 2","snippet":"Current shipped operations The current shipped assist surface has seven deterministic operations: `ota assist declare-readiness`, `ota assist declare-service`, `ota assist bind-...","page_title":"Ota Assist"},{"title":"Task runtime examples","href":"/docs/assist#assist-3-task-runtime-examples","canonical_url":"https://ota.run/docs/assist#assist-3-task-runtime-examples","summary":"Ota Assist · section 3","snippet":"Task runtime examples Task-targeted readiness works best when the service task and listener are already declared in the contract. for a Spring Boot task, ota can usually infer t...","page_title":"Ota Assist"},{"title":"Managed service examples","href":"/docs/assist#assist-4-managed-service-examples","canonical_url":"https://ota.run/docs/assist#assist-4-managed-service-examples","summary":"Ota Assist · section 4","snippet":"Managed service examples Top-level managed services are stricter because a service endpoint only proves address and port projection, not protocol truth. if a managed service alr...","page_title":"Ota Assist"},{"title":"Monorepo member behavior","href":"/docs/assist#assist-5-monorepo-member-behavior","canonical_url":"https://ota.run/docs/assist#assist-5-monorepo-member-behavior","summary":"Ota Assist · section 5","snippet":"Monorepo member behavior When you pass `--member`, assist writes only the targeted member overlay while validating the merged member contract through the root monorepo path. thi...","page_title":"Ota Assist"},{"title":"Task binding examples","href":"/docs/assist#assist-6-task-binding-examples","canonical_url":"https://ota.run/docs/assist#assist-6-task-binding-examples","summary":"Ota Assist · section 6","snippet":"Task binding examples `ota assist bind-task` is the current assist slice for wiring one consumer edge to one producer runtime listener through the contract. use it when the prod...","page_title":"Ota Assist"},{"title":"Setup wiring examples","href":"/docs/assist#assist-7-setup-wiring-examples","canonical_url":"https://ota.run/docs/assist#assist-7-setup-wiring-examples","summary":"Ota Assist · section 7","snippet":"Setup wiring examples `ota assist wire-setup` is the narrow assist slice for the phased `ota up` model. create `tasks.setup` only when you have an explicit setup body to declare...","page_title":"Ota Assist"},{"title":"Env declaration examples","href":"/docs/assist#assist-8-env-declaration-examples","canonical_url":"https://ota.run/docs/assist#assist-8-env-declaration-examples","summary":"Ota Assist · section 8","snippet":"Env declaration examples `ota assist declare-env` is the narrow assist slice for reviewed env requirements, declared source files, and one task-local env override at a time. use...","page_title":"Ota Assist"},{"title":"Task creation examples","href":"/docs/assist#assist-9-task-creation-examples","canonical_url":"https://ota.run/docs/assist#assist-9-task-creation-examples","summary":"Ota Assist · section 9","snippet":"Task creation examples `ota assist add-task` is the narrow assist slice for one new task declaration at a time. use it when the contract needs a new task entry and the right nex...","page_title":"Ota Assist"},{"title":"Canonical setup normalization","href":"/docs/assist#assist-10-canonical-setup-normalization","canonical_url":"https://ota.run/docs/assist#assist-10-canonical-setup-normalization","summary":"Ota Assist · section 10","snippet":"Canonical setup normalization `ota assist normalize` is the narrow assist slice for moving one existing setup-like task into the canonical `tasks.setup` slot. use it when the re...","page_title":"Ota Assist"},{"title":"When assist refuses","href":"/docs/assist#assist-11-when-assist-refuses","canonical_url":"https://ota.run/docs/assist#assist-11-when-assist-refuses","summary":"Ota Assist · section 11","snippet":"When assist refuses Refusal is part of the trust model. When repo truth is too weak, ota should stop instead of guessing. multiple candidate listeners with no safe selection man...","page_title":"Ota Assist"},{"title":"JSON and schema","href":"/docs/assist#assist-12-json-and-schema","canonical_url":"https://ota.run/docs/assist#assist-12-json-and-schema","summary":"Ota Assist · section 12","snippet":"JSON and schema Editors, agents, and CI should consume the assist JSON contract instead of scraping review text. use `mode`, `subject`, `inputs`, `assumptions`, `changes`, `vali...","page_title":"Ota Assist"}],"in_primary_nav":true},{"slug":"readiness-model","title":"Ota Readiness Model","summary":"Operator guide to the ota readiness model across task runtime readiness, service readiness, checks, workflow readiness, tcp versus http probes, listener reachability, app readiness, projected versus confirmed endpoints, and command behavior for doctor, check, up, and workspace flows.","href":"/docs/readiness-model","canonical_url":"https://ota.run/docs/readiness-model","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-05-09","sections":[{"title":"Why readiness has layers","href":"/docs/readiness-model#readiness-model-1-why-readiness-has-layers","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-1-why-readiness-has-layers","summary":"Ota Readiness Model · section 1","snippet":"Why readiness has layers Readiness is not one boolean in real repos. A repo can have dependencies installed, a process running, a port open, an app health route passing, and sti...","page_title":"Ota Readiness Model"},{"title":"The model","href":"/docs/readiness-model#readiness-model-2-the-model","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-2-the-model","summary":"Ota Readiness Model · section 2","snippet":"The model Use the narrowest truthful readiness owner for each signal. Do not duplicate the same health truth across tasks, services, checks, and workflows unless a current comma...","page_title":"Ota Readiness Model"},{"title":"Command behavior","href":"/docs/readiness-model#readiness-model-3-command-behavior","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-3-command-behavior","summary":"Ota Readiness Model · section 3","snippet":"Command behavior `ota tasks --workflow <name>` is a read-only discovery command; it shows selected workflow pieces without executing them. `ota doctor` diagnoses the selected re...","page_title":"Ota Readiness Model"},{"title":"Runtime readiness","href":"/docs/readiness-model#readiness-model-4-runtime-readiness","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-4-runtime-readiness","summary":"Ota Readiness Model · section 4","snippet":"Runtime readiness Runtime readiness belongs on the task when the thing being proved is the workload started by that task. This keeps app health close to the command and listener...","page_title":"Ota Readiness Model"},{"title":"Service readiness","href":"/docs/readiness-model#readiness-model-5-service-readiness","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-5-service-readiness","summary":"Ota Readiness Model · section 5","snippet":"Service readiness Service readiness belongs under `services` when the repo dependency is not the same thing as the app task. Use this for managed local infrastructure or produce...","page_title":"Ota Readiness Model"},{"title":"Checks","href":"/docs/readiness-model#readiness-model-6-checks","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-6-checks","summary":"Ota Readiness Model · section 6","snippet":"Checks Checks are the named readiness gates that `ota check`, `ota doctor`, workflows, and CI can reuse today. Use checks when the readiness signal should be explicit and machin...","page_title":"Ota Readiness Model"},{"title":"Workflow readiness","href":"/docs/readiness-model#readiness-model-7-workflow-readiness","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-7-workflow-readiness","summary":"Ota Readiness Model · section 7","snippet":"Workflow readiness Workflow readiness answers ready for what. Use it when the repo has more than one valid front door and plain repo-wide readiness would either be too broad or ...","page_title":"Ota Readiness Model"},{"title":"TCP versus HTTP readiness","href":"/docs/readiness-model#readiness-model-8-tcp-versus-http-readiness","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-8-tcp-versus-http-readiness","summary":"Ota Readiness Model · section 8","snippet":"TCP versus HTTP readiness Use `tcp` when readiness is correctly represented by listener acceptability alone. Use `http` when one dedicated health route proves readiness better t...","page_title":"Ota Readiness Model"},{"title":"How to choose the readiness owner","href":"/docs/readiness-model#readiness-model-9-how-to-choose-the-readiness-owner","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-9-how-to-choose-the-readiness-owner","summary":"Ota Readiness Model · section 9","snippet":"How to choose the readiness owner Use `tasks.<name>.runtime.readiness` when the task owns the app process. Use `services.<name>.readiness` when a service owns the dependency. Us...","page_title":"Ota Readiness Model"},{"title":"Projected versus confirmed endpoints","href":"/docs/readiness-model#readiness-model-10-projected-versus-confirmed-endpoints","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-10-projected-versus-confirmed-endpoints","summary":"Ota Readiness Model · section 10","snippet":"Projected versus confirmed endpoints A projected endpoint is the URL ota resolves from the contract. A confirmed endpoint is one ota itself has actually reached. `project.host` ...","page_title":"Ota Readiness Model"},{"title":"Why internal readiness can still differ from host confirmation","href":"/docs/readiness-model#readiness-model-11-why-internal-readiness-can-still-differ-from-host-confirmation","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-11-why-internal-readiness-can-still-differ-from-host-confirmation","summary":"Ota Readiness Model · section 11","snippet":"Why internal readiness can still differ from host confirmation a container can answer on its internal listener while host publication is still broken or unreachable a remote or ...","page_title":"Ota Readiness Model"},{"title":"VM-backed container boundaries","href":"/docs/readiness-model#readiness-model-12-vm-backed-container-boundaries","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-12-vm-backed-container-boundaries","summary":"Ota Readiness Model · section 12","snippet":"VM-backed container boundaries One real-world example is Colima on macOS: Docker can report a published host port while the port is only reachable inside the container VM. in th...","page_title":"Ota Readiness Model"},{"title":"How to author readiness well","href":"/docs/readiness-model#readiness-model-13-how-to-author-readiness-well","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-13-how-to-author-readiness-well","summary":"Ota Readiness Model · section 13","snippet":"How to author readiness well declare readiness once at the layer that owns the truth bind runtime readiness to the listener that actually represents the service surface you care...","page_title":"Ota Readiness Model"},{"title":"Reusable probes","href":"/docs/readiness-model#readiness-model-14-reusable-probes","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-14-reusable-probes","summary":"Ota Readiness Model · section 14","snippet":"Reusable probes Reusable readiness probes are the structured way to declare a transport-level readiness target once. Choose reusable probes when one transport-level readiness ta...","page_title":"Ota Readiness Model"},{"title":"Literal URL probe for external or third-party endpoints","href":"/docs/readiness-model#readiness-model-15-literal-url-probe-for-external-or-third-party-endpoints","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-15-literal-url-probe-for-external-or-third-party-endpoints","summary":"Ota Readiness Model · section 15","snippet":"Literal URL probe for external or third-party endpoints Use a literal `url` when the endpoint is not owned by an Ota task listener or service endpoint. This keeps external servi...","page_title":"Ota Readiness Model"},{"title":"Topology-derived probe for Ota-owned endpoints","href":"/docs/readiness-model#readiness-model-16-topology-derived-probe-for-ota-owned-endpoints","canonical_url":"https://ota.run/docs/readiness-model#readiness-model-16-topology-derived-probe-for-ota-owned-endpoints","summary":"Ota Readiness Model · section 16","snippet":"Topology-derived probe for Ota-owned endpoints Use a topology-derived target when the endpoint already belongs to a declared task listener or service endpoint. That lets readine...","page_title":"Ota Readiness Model"}],"in_primary_nav":true},{"slug":"surfaces","title":"Runtime Surfaces","summary":"Guide to Ota runtime surfaces: reusable endpoint definitions, explicit task attachments, native list-form attachment, container attachment overrides, when to use surfaces instead of listener shorthand or full listeners, and how workflows use surfaces for readiness and exposes.","href":"/docs/surfaces","canonical_url":"https://ota.run/docs/surfaces","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"evolving","last_reviewed":"2026-05-09","sections":[{"title":"What runtime surfaces are","href":"/docs/surfaces#surfaces-1-what-runtime-surfaces-are","canonical_url":"https://ota.run/docs/surfaces#surfaces-1-what-runtime-surfaces-are","summary":"Runtime Surfaces · section 1","snippet":"What runtime surfaces are A runtime surface is a reusable endpoint definition for something a task actually runs. Use a runtime surface when the same endpoint appears across mul...","page_title":"Runtime Surfaces"},{"title":"Why runtime surfaces exist","href":"/docs/surfaces#surfaces-2-why-runtime-surfaces-exist","canonical_url":"https://ota.run/docs/surfaces#surfaces-2-why-runtime-surfaces-exist","summary":"Runtime Surfaces · section 2","snippet":"Why runtime surfaces exist Listener shorthand makes one listener easier to write. It does not remove repeated endpoint meaning across a large repo. Runtime surfaces solve the mu...","page_title":"Runtime Surfaces"},{"title":"Surfaces, shorthand, and full listeners","href":"/docs/surfaces#surfaces-3-surfaces-shorthand-and-full-listeners","canonical_url":"https://ota.run/docs/surfaces#surfaces-3-surfaces-shorthand-and-full-listeners","summary":"Runtime Surfaces · section 3","snippet":"Surfaces, shorthand, and full listeners Listener shorthand A compact one-off listener on a task. Use this when only one task owns the endpoint and the fixed loopback defaults ar...","page_title":"Runtime Surfaces"},{"title":"Basic HTTP surface","href":"/docs/surfaces#surfaces-4-basic-http-surface","canonical_url":"https://ota.run/docs/surfaces#surfaces-4-basic-http-surface","summary":"Runtime Surfaces · section 4","snippet":"Basic HTTP surface Use this when one app endpoint has a stable local port and one meaningful health path. The surface owns the endpoint shape and readiness meaning. A task still...","page_title":"Runtime Surfaces"},{"title":"Attach surfaces to tasks","href":"/docs/surfaces#surfaces-5-attach-surfaces-to-tasks","canonical_url":"https://ota.run/docs/surfaces#surfaces-5-attach-surfaces-to-tasks","summary":"Runtime Surfaces · section 5","snippet":"Attach surfaces to tasks Surfaces are reusable definitions, not automatic attachments. Every task that publishes a surface must attach it explicitly. That is the runtime claim t...","page_title":"Runtime Surfaces"},{"title":"Why attachments stay explicit","href":"/docs/surfaces#surfaces-6-why-attachments-stay-explicit","canonical_url":"https://ota.run/docs/surfaces#surfaces-6-why-attachments-stay-explicit","summary":"Runtime Surfaces · section 6","snippet":"Why attachments stay explicit Automatic inheritance would make the contract less trustworthy. A repo can define `backend`, but that does not mean every task publishes the backen...","page_title":"Runtime Surfaces"},{"title":"Native list form","href":"/docs/surfaces#surfaces-7-native-list-form","canonical_url":"https://ota.run/docs/surfaces#surfaces-7-native-list-form","summary":"Runtime Surfaces · section 7","snippet":"Native list form Use list form for native or simple host-facing services where the surface defaults are true. This is the compact path: the task opts into the reusable endpoint ...","page_title":"Runtime Surfaces"},{"title":"Container attachment override","href":"/docs/surfaces#surfaces-8-container-attachment-override","canonical_url":"https://ota.run/docs/surfaces#surfaces-8-container-attachment-override","summary":"Runtime Surfaces · section 8","snippet":"Container attachment override Container-backed tasks often need runtime-specific publication. Keep that publication shape at the task attachment because container bind address, ...","page_title":"Runtime Surfaces"},{"title":"Workflow readiness with surfaces","href":"/docs/surfaces#surfaces-9-workflow-readiness-with-surfaces","canonical_url":"https://ota.run/docs/surfaces#surfaces-9-workflow-readiness-with-surfaces","summary":"Runtime Surfaces · section 9","snippet":"Workflow readiness with surfaces Workflow readiness should say which surfaces prove that selected workflow path. The workflow run task provides the concrete attachment, so a bac...","page_title":"Runtime Surfaces"},{"title":"Workflow exposes with surfaces","href":"/docs/surfaces#surfaces-10-workflow-exposes-with-surfaces","canonical_url":"https://ota.run/docs/surfaces#surfaces-10-workflow-exposes-with-surfaces","summary":"Runtime Surfaces · section 10","snippet":"Workflow exposes with surfaces Workflow exposes should avoid repeating URLs that already come from attached surfaces. Use surface exposes when the URL belongs to the selected ru...","page_title":"Runtime Surfaces"},{"title":"Literal external probes","href":"/docs/surfaces#surfaces-11-literal-external-probes","canonical_url":"https://ota.run/docs/surfaces#surfaces-11-literal-external-probes","summary":"Runtime Surfaces · section 11","snippet":"Literal external probes Use literal URL probes when the endpoint is external, third-party, or not produced by an Ota task runtime. Do not force these endpoints into surfaces. Su...","page_title":"Runtime Surfaces"},{"title":"Multi-front-door app example","href":"/docs/surfaces#surfaces-12-multi-front-door-app-example","canonical_url":"https://ota.run/docs/surfaces#surfaces-12-multi-front-door-app-example","summary":"Runtime Surfaces · section 12","snippet":"Multi-front-door app example Some application repos expose more than one useful local front door: a full app, a backend-only server, a frontend-only dev server, a worker path, a...","page_title":"Runtime Surfaces"},{"title":"When not to use surfaces","href":"/docs/surfaces#surfaces-13-when-not-to-use-surfaces","canonical_url":"https://ota.run/docs/surfaces#surfaces-13-when-not-to-use-surfaces","summary":"Runtime Surfaces · section 13","snippet":"When not to use surfaces do not use a surface for a one-off listener on one task; use listener shorthand instead do not use a surface for a third-party service or external URL; ...","page_title":"Runtime Surfaces"},{"title":"Command behavior","href":"/docs/surfaces#surfaces-14-command-behavior","canonical_url":"https://ota.run/docs/surfaces#surfaces-14-command-behavior","summary":"Runtime Surfaces · section 14","snippet":"Command behavior `ota validate` should reject unknown, duplicate, or unattached surface references `ota tasks --workflow <name>` should show which surfaces the selected workflow...","page_title":"Runtime Surfaces"},{"title":"Design rule","href":"/docs/surfaces#surfaces-15-design-rule","canonical_url":"https://ota.run/docs/surfaces#surfaces-15-design-rule","summary":"Runtime Surfaces · section 15","snippet":"Design rule Surfaces should remove duplicated endpoint truth without becoming a template system. The source of operational truth remains concrete task runtime attachment. surfac...","page_title":"Runtime Surfaces"}],"in_primary_nav":true},{"slug":"attachments","title":"Container Attachments","summary":"Guide to container attachments, repo-relative isolated_paths, effective /workspace path mapping, named-volume overlays, and cache examples for node_modules, .next, .m2, .npm, .pnpm-store, .gradle, .pip-cache, and .pypoetry-cache.","href":"/docs/attachments","canonical_url":"https://ota.run/docs/attachments","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-04-29","sections":[{"title":"Why this feature exists","href":"/docs/attachments#attachments-1-why-this-feature-exists","canonical_url":"https://ota.run/docs/attachments#attachments-1-why-this-feature-exists","summary":"Container Attachments · section 1","snippet":"Why this feature exists Attachments let a container context keep the source tree bind-mounted from the host while moving selected dependency or artifact paths onto Ota-managed s...","page_title":"Container Attachments"},{"title":"The most important rule","href":"/docs/attachments#attachments-2-the-most-important-rule","canonical_url":"https://ota.run/docs/attachments#attachments-2-the-most-important-rule","summary":"Container Attachments · section 2","snippet":"The most important rule `attachments.isolated_paths` entries are repo-relative paths, not absolute container paths. Ota maps each entry to `/workspace/<path>` inside the contain...","page_title":"Container Attachments"},{"title":"How the mapping works","href":"/docs/attachments#attachments-3-how-the-mapping-works","canonical_url":"https://ota.run/docs/attachments#attachments-3-how-the-mapping-works","summary":"Container Attachments · section 3","snippet":"How the mapping works `node_modules` and `.next` are common examples, not special cases baked into ota. The real rule is simpler: declare any repo-relative path that should be l...","page_title":"Container Attachments"},{"title":"Why these frontend paths are common examples","href":"/docs/attachments#attachments-4-why-these-frontend-paths-are-common-examples","canonical_url":"https://ota.run/docs/attachments#attachments-4-why-these-frontend-paths-are-common-examples","summary":"Container Attachments · section 4","snippet":"Why these frontend paths are common examples Frontend repos often use `node_modules` and `.next` because those paths already live under the repo root and the tools already write...","page_title":"Container Attachments"},{"title":"When tool reconfiguration is required","href":"/docs/attachments#attachments-5-when-tool-reconfiguration-is-required","canonical_url":"https://ota.run/docs/attachments#attachments-5-when-tool-reconfiguration-is-required","summary":"Container Attachments · section 5","snippet":"When tool reconfiguration is required An attachment only makes a path durable. It does not automatically force a tool to use that path. If the tool already writes into a repo-re...","page_title":"Container Attachments"},{"title":"Persistent versus ephemeral","href":"/docs/attachments#attachments-6-persistent-versus-ephemeral","canonical_url":"https://ota.run/docs/attachments#attachments-6-persistent-versus-ephemeral","summary":"Container Attachments · section 6","snippet":"Persistent versus ephemeral Persistent containers naturally preserve container-local state because the container itself is reused. Ephemeral containers do not preserve container...","page_title":"Container Attachments"},{"title":"When to use it","href":"/docs/attachments#attachments-7-when-to-use-it","canonical_url":"https://ota.run/docs/attachments#attachments-7-when-to-use-it","summary":"Container Attachments · section 7","snippet":"When to use it use it for repo-relative dependency trees like `node_modules`, `.next`, or `.venv` that should stay container-owned use it for tool caches like `.m2` or `.npm` wh...","page_title":"Container Attachments"},{"title":"What not to do","href":"/docs/attachments#attachments-8-what-not-to-do","canonical_url":"https://ota.run/docs/attachments#attachments-8-what-not-to-do","summary":"Container Attachments · section 8","snippet":"What not to do do not put absolute paths like `/workspace/.m2` in `isolated_paths` do not assume the attachment alone retargets a tool to that path do not use `node_modules` as ...","page_title":"Container Attachments"}],"in_primary_nav":true},{"slug":"compose-attachments","title":"Compose Attachments","summary":"Guide to attachments.compose, Compose-network attachment semantics, alignment with services.<name>.manager.name, and the split between host Compose control and container workload execution.","href":"/docs/compose-attachments","canonical_url":"https://ota.run/docs/compose-attachments","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"maintainers","status":"stable","last_reviewed":"2026-04-29","sections":[{"title":"Why this feature exists","href":"/docs/compose-attachments#compose-attachments-1-why-this-feature-exists","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-1-why-this-feature-exists","summary":"Compose Attachments · section 1","snippet":"Why this feature exists `attachments.compose` lets an Ota-managed workload container join one or more Compose project networks without forcing Docker to run inside the app image...","page_title":"Compose Attachments"},{"title":"What it is and what it is not","href":"/docs/compose-attachments#compose-attachments-2-what-it-is-and-what-it-is-not","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-2-what-it-is-and-what-it-is-not","summary":"Compose Attachments · section 2","snippet":"What it is and what it is not `attachments.compose` is a network attachment declaration for container contexts it is not a replacement for `compose:up` or a service manager decl...","page_title":"Compose Attachments"},{"title":"The most important alignment rule","href":"/docs/compose-attachments#compose-attachments-3-the-most-important-alignment-rule","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-3-the-most-important-alignment-rule","summary":"Compose Attachments · section 3","snippet":"The most important alignment rule Keep `attachments.compose` aligned with the Compose project name used by the related service managers. If those names drift, Ota attaches the w...","page_title":"Compose Attachments"},{"title":"How it differs from `compose:up`","href":"/docs/compose-attachments#compose-attachments-4-how-it-differs-from-compose-up","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-4-how-it-differs-from-compose-up","summary":"Compose Attachments · section 4","snippet":"How it differs from `compose:up` `compose:up` is a host task that controls the Compose project lifecycle. `attachments.compose` is a workload-context declaration that tells Ota ...","page_title":"Compose Attachments"},{"title":"Canonical use case","href":"/docs/compose-attachments#compose-attachments-5-canonical-use-case","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-5-canonical-use-case","summary":"Compose Attachments · section 5","snippet":"Canonical use case This is the `qredex-core` shape: Compose owns Postgres on the host, while the Java app and tests run in an Ota-managed container that should reach `postgres:5...","page_title":"Compose Attachments"},{"title":"When to use it","href":"/docs/compose-attachments#compose-attachments-6-when-to-use-it","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-6-when-to-use-it","summary":"Compose Attachments · section 6","snippet":"When to use it use it when Compose services should be controlled from the host but reached by service name from a container workload context use it when the repo should stay hon...","page_title":"Compose Attachments"},{"title":"What not to do","href":"/docs/compose-attachments#compose-attachments-7-what-not-to-do","canonical_url":"https://ota.run/docs/compose-attachments#compose-attachments-7-what-not-to-do","summary":"Compose Attachments · section 7","snippet":"What not to do do not use Docker inside the app image as the main model do not treat published host ports as the primary in-container reachability path when service-name network...","page_title":"Compose Attachments"}],"in_primary_nav":true},{"slug":"local-topology-patterns","title":"Local Topology Patterns","summary":"Adoption guidance for task target bindings, target activation, shared local container backends, and backend-scoped run-path fulfillment with links to canonical examples.","href":"/docs/local-topology-patterns","canonical_url":"https://ota.run/docs/local-topology-patterns","category":"Operate","intent":"learn","difficulty":"advanced","audience":"maintainers","status":"stable","last_reviewed":"2026-04-27","sections":[{"title":"When to use this page","href":"/docs/local-topology-patterns#local-topology-patterns-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-1-when-to-use-this-page","summary":"Local Topology Patterns · section 1","snippet":"When to use this page Use this page when the repo problem is not language setup alone, but how one local workload should truthfully target or share execution with another. This ...","page_title":"Local Topology Patterns"},{"title":"Pattern 1: Task target bindings","href":"/docs/local-topology-patterns#local-topology-patterns-2-pattern-1-task-target-bindings","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-2-pattern-1-task-target-bindings","summary":"Local Topology Patterns · section 2","snippet":"Pattern 1: Task target bindings Start here when one task should follow another repo-managed app by service identity. Keep the topology truth in `tasks.<name>.targets.<target>`. ...","page_title":"Local Topology Patterns"},{"title":"Pattern 1b: Target activation","href":"/docs/local-topology-patterns#local-topology-patterns-3-pattern-1b-target-activation","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-3-pattern-1b-target-activation","summary":"Local Topology Patterns · section 3","snippet":"Pattern 1b: Target activation Use target activation when target resolution alone is not enough and ota should also ensure the local producer service is up before the consumer ru...","page_title":"Local Topology Patterns"},{"title":"Pattern 2: Shared local backends","href":"/docs/local-topology-patterns#local-topology-patterns-4-pattern-2-shared-local-backends","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-4-pattern-2-shared-local-backends","summary":"Local Topology Patterns · section 4","snippet":"Pattern 2: Shared local backends Use a shared backend when multiple long-running tasks should intentionally reuse one ota-owned backend boundary. This is not `depends_on`, and i...","page_title":"Local Topology Patterns"},{"title":"Pattern 2b: Shared remote backends","href":"/docs/local-topology-patterns#local-topology-patterns-5-pattern-2b-shared-remote-backends","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-5-pattern-2b-shared-remote-backends","summary":"Local Topology Patterns · section 5","snippet":"Pattern 2b: Shared remote backends Use a shared remote backend when those long-running workloads intentionally live off-host and ota should still own one truthful shared boundar...","page_title":"Local Topology Patterns"},{"title":"Pattern 3: Run-path fulfillment","href":"/docs/local-topology-patterns#local-topology-patterns-6-pattern-3-run-path-fulfillment","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-6-pattern-3-run-path-fulfillment","summary":"Local Topology Patterns · section 6","snippet":"Pattern 3: Run-path fulfillment Turn this on when ota should make the declared execution environment real on the run path instead of asking the repo to bootstrap missing tools i...","page_title":"Local Topology Patterns"},{"title":"Pattern 4: Policy-governed backend environment","href":"/docs/local-topology-patterns#local-topology-patterns-7-pattern-4-policy-governed-backend-environment","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-7-pattern-4-policy-governed-backend-environment","summary":"Local Topology Patterns · section 7","snippet":"Pattern 4: Policy-governed backend environment Use this when the repo should declare backend environment intent and let policy resolve the effective image honestly. This keeps s...","page_title":"Local Topology Patterns"},{"title":"Current constraints","href":"/docs/local-topology-patterns#local-topology-patterns-8-current-constraints","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-8-current-constraints","summary":"Local Topology Patterns · section 8","snippet":"Current constraints The current design is the right long-term foundation, but the shipped surface is intentionally strict where ota cannot yet prove more. shared backends curren...","page_title":"Local Topology Patterns"},{"title":"Canonical examples","href":"/docs/local-topology-patterns#local-topology-patterns-9-canonical-examples","canonical_url":"https://ota.run/docs/local-topology-patterns#local-topology-patterns-9-canonical-examples","summary":"Local Topology Patterns · section 9","snippet":"Canonical examples Use these examples as the adoption baseline instead of rebuilding the patterns from scratch in each repo. Task target binding One producer service plus two co...","page_title":"Local Topology Patterns"}],"in_primary_nav":true},{"slug":"mode-aware-tasks","title":"Mode-Aware Tasks","summary":"Guide to task-level mode-aware execution, default_mode, per-mode context plus lifecycle, CLI override precedence, and when to keep separate task names instead of splitting one task intent.","href":"/docs/mode-aware-tasks","canonical_url":"https://ota.run/docs/mode-aware-tasks","category":"Operate","intent":"learn","difficulty":"intermediate","audience":"new-users","status":"stable","last_reviewed":"2026-04-22","sections":[{"title":"Why this feature exists","href":"/docs/mode-aware-tasks#mode-aware-tasks-1-why-this-feature-exists","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-1-why-this-feature-exists","summary":"Mode-Aware Tasks · section 1","snippet":"Why this feature exists Mode-aware tasks let one task keep one meaning while its execution shape changes honestly by backend. That matters because users think in intents like `s...","page_title":"Mode-Aware Tasks"},{"title":"What it fixes","href":"/docs/mode-aware-tasks#mode-aware-tasks-2-what-it-fixes","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-2-what-it-fixes","summary":"Mode-Aware Tasks · section 2","snippet":"What it fixes Split task names drift Repos end up with `start`, `start:host`, `start:container`, or other local naming inventions just to express backend differences. That is a ...","page_title":"Mode-Aware Tasks"},{"title":"The operator model","href":"/docs/mode-aware-tasks#mode-aware-tasks-3-the-operator-model","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-3-the-operator-model","summary":"Mode-Aware Tasks · section 3","snippet":"The operator model The mental model should stay simple. Users choose the task intent first. Ota then resolves which execution branch should own that one run. `ota run <task>` re...","page_title":"Mode-Aware Tasks"},{"title":"When to use it","href":"/docs/mode-aware-tasks#mode-aware-tasks-4-when-to-use-it","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-4-when-to-use-it","summary":"Mode-Aware Tasks · section 4","snippet":"When to use it Use it when intent is stable but host and container execution differ in networking, environment, or runtime behavior. Use it when host and container paths reach d...","page_title":"Mode-Aware Tasks"},{"title":"When not to use it","href":"/docs/mode-aware-tasks#mode-aware-tasks-5-when-not-to-use-it","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-5-when-not-to-use-it","summary":"Mode-Aware Tasks · section 5","snippet":"When not to use it Do not use it when intent changes; keep separate task names for separate user operations (for example `start` vs `clean:start`). Do not use it when there is o...","page_title":"Mode-Aware Tasks"},{"title":"Contract anatomy","href":"/docs/mode-aware-tasks#mode-aware-tasks-6-contract-anatomy","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-6-contract-anatomy","summary":"Mode-Aware Tasks · section 6","snippet":"Contract anatomy The task-level execution block is where backend-specific truth belongs when one task should span more than one plane. That branch can own `context`, `lifecycle`...","page_title":"Mode-Aware Tasks"},{"title":"Why this is better than split task names","href":"/docs/mode-aware-tasks#mode-aware-tasks-7-why-this-is-better-than-split-task-names","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-7-why-this-is-better-than-split-task-names","summary":"Mode-Aware Tasks · section 7","snippet":"Why this is better than split task names Separate task names are still valid when semantics differ. But when the only difference is backend-specific execution shape, split names...","page_title":"Mode-Aware Tasks"},{"title":"Real operator scenarios","href":"/docs/mode-aware-tasks#mode-aware-tasks-8-real-operator-scenarios","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-8-real-operator-scenarios","summary":"Mode-Aware Tasks · section 8","snippet":"Real operator scenarios The best use cases are not abstract schema tricks. They are the places where a repo has one obvious user intent but more than one honest execution plane.","page_title":"Mode-Aware Tasks"},{"title":"Scenario 1: One `start` task","href":"/docs/mode-aware-tasks#mode-aware-tasks-9-scenario-1-one-start-task","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-9-scenario-1-one-start-task","summary":"Mode-Aware Tasks · section 9","snippet":"Scenario 1: One `start` task A backend API often needs two real paths. Engineers want host execution for IDE debugging and local iteration, while the team also wants a container...","page_title":"Mode-Aware Tasks"},{"title":"Scenario 2: One `dev` task","href":"/docs/mode-aware-tasks#mode-aware-tasks-10-scenario-2-one-dev-task","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-10-scenario-2-one-dev-task","summary":"Mode-Aware Tasks · section 10","snippet":"Scenario 2: One `dev` task A frontend team may want the normal `dev` loop to run inside the app image so Node, package-manager behavior, and native binaries stay pinned. But eng...","page_title":"Mode-Aware Tasks"},{"title":"Scenario 3: One `build` task","href":"/docs/mode-aware-tasks#mode-aware-tasks-11-scenario-3-one-build-task","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-11-scenario-3-one-build-task","summary":"Mode-Aware Tasks · section 11","snippet":"Scenario 3: One `build` task A build task often has two honest goals. Developers want a fast native compile for feedback, while the release path may need a Linux container with ...","page_title":"Mode-Aware Tasks"},{"title":"Lifecycle is part of the feature, not an afterthought","href":"/docs/mode-aware-tasks#mode-aware-tasks-12-lifecycle-is-part-of-the-feature-not-an-afterthought","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-12-lifecycle-is-part-of-the-feature-not-an-afterthought","summary":"Mode-Aware Tasks · section 12","snippet":"Lifecycle is part of the feature, not an afterthought Mode-aware tasks are not just about `run` and `env`. Lifecycle belongs in the same place because container reuse semantics ...","page_title":"Mode-Aware Tasks"},{"title":"Decision guide","href":"/docs/mode-aware-tasks#mode-aware-tasks-13-decision-guide","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-13-decision-guide","summary":"Mode-Aware Tasks · section 13","snippet":"Decision guide Use a mode-aware task when one user intent must be preserved across backend changes. Use separate task names only when behavior changes, not only execution plane....","page_title":"Mode-Aware Tasks"},{"title":"Why this sells Ota","href":"/docs/mode-aware-tasks#mode-aware-tasks-14-why-this-sells-ota","canonical_url":"https://ota.run/docs/mode-aware-tasks#mode-aware-tasks-14-why-this-sells-ota","summary":"Mode-Aware Tasks · section 14","snippet":"Why this sells Ota This is one of the clearest examples of Ota being more than a task runner. Ota is not just launching commands. It is owning execution truth. One task name sta...","page_title":"Mode-Aware Tasks"}],"in_primary_nav":true},{"slug":"execution-and-dockerfiles","title":"Container Execution","summary":"Use this page when a repo already has a Dockerfile and you need to decide how ota fits around it.","href":"/docs/reference/execution-and-dockerfiles","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles","category":"Operational guidance","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-1-when-to-use-this-page","summary":"Container Execution · section 1","snippet":"When to use this page Use this page when a repo already has a Dockerfile and you need to decide how ota fits around it. Choose this when you want the image build and the readine...","page_title":"Container Execution"},{"title":"Boundary note","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-2-boundary-note","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-2-boundary-note","summary":"Container Execution · section 2","snippet":"Boundary note Docker is optional, not a universal prerequisite for ota use container mode when the repo or org already allows it host bootstrap for Docker is a separate concern ...","page_title":"Container Execution"},{"title":"How they differ","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-3-how-they-differ","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-3-how-they-differ","summary":"Container Execution · section 3","snippet":"How they differ Dockerfile handles OS packages, runtimes, and reproducible image setup ota handles tasks, checks, safe AI-agent guidance, provisioning policy, and execution mode...","page_title":"Container Execution"},{"title":"Simple model","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-4-simple-model","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-4-simple-model","summary":"Container Execution · section 4","snippet":"Simple model Flow text Dockerfile -> builds the image ota.yaml -> declares what the repo needs ota run/up -> executes against the declared environment","page_title":"Container Execution"},{"title":"Example","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-5-example","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-5-example","summary":"Container Execution · section 5","snippet":"Example Dockerfile dockerfile FROM eclipse-temurin:21-jdk WORKDIR /workspace COPY . . RUN ./mvnw -q dependency:go-offline ota.yaml yaml version: 1 project: name: sample-java-ser...","page_title":"Container Execution"},{"title":"Rule of thumb","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-6-rule-of-thumb","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-6-rule-of-thumb","summary":"Container Execution · section 6","snippet":"Rule of thumb use the Dockerfile to make the image runnable use the ota contract to make the repo explainable, diagnosable, and safe use container mode when you want ota to run ...","page_title":"Container Execution"},{"title":"Preview example","href":"/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-7-preview-example","canonical_url":"https://ota.run/docs/reference/execution-and-dockerfiles#execution-and-dockerfiles-7-preview-example","summary":"Container Execution · section 7","snippet":"Preview example The preview should read like a real operator plan, not a second generic explanation layer. Container preview text 🦦 UP PREVIEW ./ota.yaml ➤ NOT READY ❖ Mode: dr...","page_title":"Container Execution"}],"in_primary_nav":true},{"slug":"troubleshooting","title":"Troubleshooting","summary":"Explicit paths should point at the repo you mean. If they do not, start there before assuming the contract is wrong.","href":"/docs/troubleshooting","canonical_url":"https://ota.run/docs/troubleshooting","category":"Support","intent":"learn","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Common checks","href":"/docs/troubleshooting#troubleshooting-1-common-checks","canonical_url":"https://ota.run/docs/troubleshooting#troubleshooting-1-common-checks","summary":"Troubleshooting · section 1","snippet":"Common checks Run `ota doctor` first when the repo is not ready. Read `ota doctor` / `ota check` top status as `READY`, `READY WITH WARNINGS`, or `BLOCKED`; read dry-run preview...","page_title":"Troubleshooting"},{"title":"If a repo is not discovered","href":"/docs/troubleshooting#troubleshooting-2-if-a-repo-is-not-discovered","canonical_url":"https://ota.run/docs/troubleshooting#troubleshooting-2-if-a-repo-is-not-discovered","summary":"Troubleshooting · section 2","snippet":"If a repo is not discovered Explicit paths should point at the repo you mean. If they do not, start there before assuming the contract is wrong. Point ota at the repo path bash ...","page_title":"Troubleshooting"}],"in_primary_nav":true},{"slug":"faq","title":"FAQ","summary":"Run `ota doctor` first. It tells you what is missing, even if `ota.yaml` does not exist yet.","href":"/docs/faq","canonical_url":"https://ota.run/docs/faq","category":"Support","intent":"learn","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What should I run first?","href":"/docs/faq#faq-1-what-should-i-run-first","canonical_url":"https://ota.run/docs/faq#faq-1-what-should-i-run-first","summary":"FAQ · section 1","snippet":"What should I run first? Run `ota doctor` first. It tells you what is missing, even if `ota.yaml` does not exist yet. Starter triage sequence bash ota doctor --plain ota detect ...","page_title":"FAQ"},{"title":"When should I use a shared backend instead of plain task execution or target binding?","href":"/docs/faq#faq-2-when-should-i-use-a-shared-backend-instead-of-plain-task-execution-or-target-binding","canonical_url":"https://ota.run/docs/faq#faq-2-when-should-i-use-a-shared-backend-instead-of-plain-task-execution-or-target-binding","summary":"FAQ · section 2","snippet":"When should I use a shared backend instead of plain task execution or target binding? Use plain task execution when tasks are independent and do not need declared service target...","page_title":"FAQ"},{"title":"Does `depends_on` share the same environment as the parent task?","href":"/docs/faq#faq-3-does-depends-on-share-the-same-environment-as-the-parent-task","canonical_url":"https://ota.run/docs/faq#faq-3-does-depends-on-share-the-same-environment-as-the-parent-task","summary":"FAQ · section 3","snippet":"Does `depends_on` share the same environment as the parent task? No. Each `depends_on` task runs as its own task with its own resolved execution boundary. A dependency only help...","page_title":"FAQ"},{"title":"Does `ota run <task> --ephemeral` also make `depends_on` tasks ephemeral?","href":"/docs/faq#faq-4-does-ota-run-task-ephemeral-also-make-depends-on-tasks-ephemeral","canonical_url":"https://ota.run/docs/faq#faq-4-does-ota-run-task-ephemeral-also-make-depends-on-tasks-ephemeral","summary":"FAQ · section 4","snippet":"Does `ota run <task> --ephemeral` also make `depends_on` tasks ephemeral? Yes. Run-scoped execution overrides such as `--ephemeral`, `--persistent`, `--mode`, `--native`, and `-...","page_title":"FAQ"},{"title":"What is the difference between `requirements` and `fulfillment`?","href":"/docs/faq#faq-5-what-is-the-difference-between-requirements-and-fulfillment","canonical_url":"https://ota.run/docs/faq#faq-5-what-is-the-difference-between-requirements-and-fulfillment","summary":"FAQ · section 5","snippet":"What is the difference between `requirements` and `fulfillment`? `requirements` declare what the environment needs. `fulfillment` declares whether ota should try to make that tr...","page_title":"FAQ"},{"title":"Why is `execution.shared_backends` explicit instead of inferred from context?","href":"/docs/faq#faq-6-why-is-execution-shared-backends-explicit-instead-of-inferred-from-context","canonical_url":"https://ota.run/docs/faq#faq-6-why-is-execution-shared-backends-explicit-instead-of-inferred-from-context","summary":"FAQ · section 6","snippet":"Why is `execution.shared_backends` explicit instead of inferred from context? Because matching contexts do not automatically mean the tasks should share one backend boundary. An...","page_title":"FAQ"},{"title":"Why does org policy still matter if the repo already declares tools and runtimes?","href":"/docs/faq#faq-7-why-does-org-policy-still-matter-if-the-repo-already-declares-tools-and-runtimes","canonical_url":"https://ota.run/docs/faq#faq-7-why-does-org-policy-still-matter-if-the-repo-already-declares-tools-and-runtimes","summary":"FAQ · section 7","snippet":"Why does org policy still matter if the repo already declares tools and runtimes? The repo contract says what the repo needs. Org policy says what sources and versions are appro...","page_title":"FAQ"},{"title":"Why don’t target activation modes just start everything automatically?","href":"/docs/faq#faq-8-why-don-t-target-activation-modes-just-start-everything-automatically","canonical_url":"https://ota.run/docs/faq#faq-8-why-don-t-target-activation-modes-just-start-everything-automatically","summary":"FAQ · section 8","snippet":"Why don’t target activation modes just start everything automatically? Because activation is a policy choice, not something ota should guess from topology alone. `ensure_started...","page_title":"FAQ"},{"title":"How should I choose between `ssh`, `tsh`, `kubectl`, and `daytona` for remote execution?","href":"/docs/faq#faq-9-how-should-i-choose-between-ssh-tsh-kubectl-and-daytona-for-remote-execution","canonical_url":"https://ota.run/docs/faq#faq-9-how-should-i-choose-between-ssh-tsh-kubectl-and-daytona-for-remote-execution","summary":"FAQ · section 9","snippet":"How should I choose between `ssh`, `tsh`, `kubectl`, and `daytona` for remote execution? Use `ssh` when you already reach a normal remote machine through OpenSSH and want ota to...","page_title":"FAQ"},{"title":"Can `OTA_POLICY` point to a URL?","href":"/docs/faq#faq-10-can-ota-policy-point-to-a-url","canonical_url":"https://ota.run/docs/faq#faq-10-can-ota-policy-point-to-a-url","summary":"FAQ · section 10","snippet":"Can `OTA_POLICY` point to a URL? Yes. `OTA_POLICY` can point to a local file path or an `http(s)://` policy URL. Use the URL form when the policy is hosted centrally and you wan...","page_title":"FAQ"},{"title":"How does policy precedence work?","href":"/docs/faq#faq-11-how-does-policy-precedence-work","canonical_url":"https://ota.run/docs/faq#faq-11-how-does-policy-precedence-work","summary":"FAQ · section 11","snippet":"How does policy precedence work? `OTA_POLICY` wins first. If that is not set, ota reads the nearest ancestor `.ota/org-policy.yaml`. If the workspace declares `workspace.policy`...","page_title":"FAQ"},{"title":"How are env values chosen?","href":"/docs/faq#faq-12-how-are-env-values-chosen","canonical_url":"https://ota.run/docs/faq#faq-12-how-are-env-values-chosen","summary":"FAQ · section 12","snippet":"How are env values chosen? Task env wins for the task that declares it. Otherwise ota uses policy, then the shell environment, then declared env sources, then the contract defau...","page_title":"FAQ"},{"title":"Is ota a package manager?","href":"/docs/faq#faq-13-is-ota-a-package-manager","canonical_url":"https://ota.run/docs/faq#faq-13-is-ota-a-package-manager","summary":"FAQ · section 13","snippet":"Is ota a package manager? No. It is a repo-readiness system and execution contract.","page_title":"FAQ"},{"title":"Does ota write files automatically?","href":"/docs/faq#faq-14-does-ota-write-files-automatically","canonical_url":"https://ota.run/docs/faq#faq-14-does-ota-write-files-automatically","summary":"FAQ · section 14","snippet":"Does ota write files automatically? No. Commands like `ota detect` and `ota init` are explicit about when they write. Review first, then write.","page_title":"FAQ"},{"title":"Does ota replace scripts?","href":"/docs/faq#faq-15-does-ota-replace-scripts","canonical_url":"https://ota.run/docs/faq#faq-15-does-ota-replace-scripts","summary":"FAQ · section 15","snippet":"Does ota replace scripts? No. It makes scripts explicit, reviewable, and easier to run consistently.","page_title":"FAQ"},{"title":"Can ota work with containers?","href":"/docs/faq#faq-16-can-ota-work-with-containers","canonical_url":"https://ota.run/docs/faq#faq-16-can-ota-work-with-containers","summary":"FAQ · section 16","snippet":"Can ota work with containers? Yes. Container execution is a first-class repo mode when the contract calls for it.","page_title":"FAQ"},{"title":"What does `ota doctor --mode container` actually check?","href":"/docs/faq#faq-17-what-does-ota-doctor-mode-container-actually-check","canonical_url":"https://ota.run/docs/faq#faq-17-what-does-ota-doctor-mode-container-actually-check","summary":"FAQ · section 17","snippet":"What does `ota doctor --mode container` actually check? It checks readiness against the declared container target, including backend availability, image-level runtimes and tools...","page_title":"FAQ"},{"title":"What does `execution.lifecycle: ephemeral` mean today?","href":"/docs/faq#faq-18-what-does-execution-lifecycle-ephemeral-mean-today","canonical_url":"https://ota.run/docs/faq#faq-18-what-does-execution-lifecycle-ephemeral-mean-today","summary":"FAQ · section 18","snippet":"What does `execution.lifecycle: ephemeral` mean today? Today it means fresh backend-backed task execution where the command supports it, especially `ota run <task>` and the setu...","page_title":"FAQ"},{"title":"Does `adapter_bootstrap` need `platforms`?","href":"/docs/faq#faq-19-does-adapter-bootstrap-need-platforms","canonical_url":"https://ota.run/docs/faq#faq-19-does-adapter-bootstrap-need-platforms","summary":"FAQ · section 19","snippet":"Does `adapter_bootstrap` need `platforms`? No. `provisioning.platforms` chooses the adapter for the target OS first, then `adapter_bootstrap` tells ota how it may install that a...","page_title":"FAQ"},{"title":"Can one tool have multiple provisioning sources?","href":"/docs/faq#faq-20-can-one-tool-have-multiple-provisioning-sources","canonical_url":"https://ota.run/docs/faq#faq-20-can-one-tool-have-multiple-provisioning-sources","summary":"FAQ · section 20","snippet":"Can one tool have multiple provisioning sources? Policy can declare many approved sources overall, but ota resolves one effective source per runtime or tool on the current targe...","page_title":"FAQ"},{"title":"When should I use `doctor`, `explain`, and `receipt`?","href":"/docs/faq#faq-21-when-should-i-use-doctor-explain-and-receipt","canonical_url":"https://ota.run/docs/faq#faq-21-when-should-i-use-doctor-explain-and-receipt","summary":"FAQ · section 21","snippet":"When should I use `doctor`, `explain`, and `receipt`? Use `ota doctor` when you need the current blockers and the highest-priority next step. Use `ota explain` when you want tho...","page_title":"FAQ"},{"title":"When should I use `ota proof runtime` instead of `ota doctor`, `ota up`, or `ota run`?","href":"/docs/faq#faq-22-when-should-i-use-ota-proof-runtime-instead-of-ota-doctor-ota-up-or-ota-run","canonical_url":"https://ota.run/docs/faq#faq-22-when-should-i-use-ota-proof-runtime-instead-of-ota-doctor-ota-up-or-ota-run","summary":"FAQ · section 22","snippet":"When should I use `ota proof runtime` instead of `ota doctor`, `ota up`, or `ota run`? Use `ota doctor` to diagnose blockers, `ota up` to prepare the selected workflow, and `ota...","page_title":"FAQ"},{"title":"Why does `metadata.ota.minimum_version` exist?","href":"/docs/faq#faq-23-why-does-metadata-ota-minimum-version-exist","canonical_url":"https://ota.run/docs/faq#faq-23-why-does-metadata-ota-minimum-version-exist","summary":"FAQ · section 23","snippet":"Why does `metadata.ota.minimum_version` exist? Because a contract can depend on fields or semantics that an older ota binary does not understand honestly. That gate fails early ...","page_title":"FAQ"},{"title":"What is `agent.posture` for?","href":"/docs/faq#faq-24-what-is-agent-posture-for","canonical_url":"https://ota.run/docs/faq#faq-24-what-is-agent-posture-for","summary":"FAQ · section 24","snippet":"What is `agent.posture` for? `agent.posture` declares the authority model for automation before an agent edits or runs anything. Use `readiness_strict` for normal repo-readiness...","page_title":"FAQ"},{"title":"Why declare task `effects`?","href":"/docs/faq#faq-25-why-declare-task-effects","canonical_url":"https://ota.run/docs/faq#faq-25-why-declare-task-effects","summary":"FAQ · section 25","snippet":"Why declare task `effects`? Because a task can be safe or risky for reasons that are not obvious from the command string alone. Use `effects.writes` when a task mutates repo fil...","page_title":"FAQ"},{"title":"Why does `ota --version --json` expose `source_build`, `commit`, `dirty`, and `contract_capabilities`?","href":"/docs/faq#faq-26-why-does-ota-version-json-expose-source-build-commit-dirty-and-contract-capabilities","canonical_url":"https://ota.run/docs/faq#faq-26-why-does-ota-version-json-expose-source-build-commit-dirty-and-contract-capabilities","summary":"FAQ · section 26","snippet":"Why does `ota --version --json` expose `source_build`, `commit`, `dirty`, and `contract_capabilities`? Because semver alone is not enough when CI, source builds, and newer contr...","page_title":"FAQ"},{"title":"Can `--member` be repeated on every repo command?","href":"/docs/faq#faq-27-can-member-be-repeated-on-every-repo-command","canonical_url":"https://ota.run/docs/faq#faq-27-can-member-be-repeated-on-every-repo-command","summary":"FAQ · section 27","snippet":"Can `--member` be repeated on every repo command? No. Some repo commands support repeated `--member` values, but not all of them. `ota explain` is single-target only, while comm...","page_title":"FAQ"},{"title":"What is Repo vs Workspace?","href":"/docs/faq#faq-28-what-is-repo-vs-workspace","canonical_url":"https://ota.run/docs/faq#faq-28-what-is-repo-vs-workspace","summary":"FAQ · section 28","snippet":"What is Repo vs Workspace? A repo contract describes one repo. A workspace contract coordinates multiple repos without flattening their truth into one file.","page_title":"FAQ"},{"title":"Is enterprise the whole product?","href":"/docs/faq#faq-29-is-enterprise-the-whole-product","canonical_url":"https://ota.run/docs/faq#faq-29-is-enterprise-the-whole-product","summary":"FAQ · section 29","snippet":"Is enterprise the whole product? No. The current wedge is the repo contract and readiness loop. Enterprise comes later.","page_title":"FAQ"},{"title":"Do agents use the same contract as humans?","href":"/docs/faq#faq-30-do-agents-use-the-same-contract-as-humans","canonical_url":"https://ota.run/docs/faq#faq-30-do-agents-use-the-same-contract-as-humans","summary":"FAQ · section 30","snippet":"Do agents use the same contract as humans? Yes. The same contract drives human diagnosis, task execution, and agent guidance.","page_title":"FAQ"}],"in_primary_nav":true},{"slug":"developer-resources","title":"ota.run Developer Resources","summary":"Developer resource directory for ota.run OpenAPI, OAuth 2.0 metadata, official Ota skills, llms.txt, docs index, blog index, GitHub Actions, and agent-safe setup.","href":"/docs/developer-resources","canonical_url":"https://ota.run/docs/developer-resources","category":"Automation","intent":"reference","difficulty":"intermediate","audience":"automation-builders","status":"stable","last_reviewed":"2026-05-29","sections":[{"title":"Discovery URLs","href":"/docs/developer-resources#developer-resources-1-discovery-urls","canonical_url":"https://ota.run/docs/developer-resources#developer-resources-1-discovery-urls","summary":"ota.run Developer Resources · section 1","snippet":"Discovery URLs Use these predictable ota.run URLs when integrating agents, crawlers, API catalogs, or internal developer portals. The current ota.run site is static. Public disc...","page_title":"ota.run Developer Resources"},{"title":"OAuth 2.0 metadata","href":"/docs/developer-resources#developer-resources-2-oauth-2-0-metadata","canonical_url":"https://ota.run/docs/developer-resources#developer-resources-2-oauth-2-0-metadata","summary":"ota.run Developer Resources · section 2","snippet":"OAuth 2.0 metadata ota.run publishes OAuth 2.0 discovery metadata at standards-friendly well-known URLs so agents can identify the intended protected-resource boundary. Current ...","page_title":"ota.run Developer Resources"},{"title":"Official agent skills","href":"/docs/developer-resources#developer-resources-3-official-agent-skills","canonical_url":"https://ota.run/docs/developer-resources#developer-resources-3-official-agent-skills","summary":"ota.run Developer Resources · section 3","snippet":"Official agent skills Ota's supported agent extension surface today is the official `ota-run/skills` repository. It gives agents Ota-specific guidance for contract authoring, co...","page_title":"ota.run Developer Resources"},{"title":"MCP metadata only","href":"/docs/developer-resources#developer-resources-4-mcp-metadata-only","canonical_url":"https://ota.run/docs/developer-resources#developer-resources-4-mcp-metadata-only","summary":"ota.run Developer Resources · section 4","snippet":"MCP metadata only ota.run publishes MCP metadata for future discovery, but it does not run a live MCP protocol endpoint today. Do not attempt an MCP handshake against ota.run. U...","page_title":"ota.run Developer Resources"},{"title":"Canonical automation docs","href":"/docs/developer-resources#developer-resources-5-canonical-automation-docs","canonical_url":"https://ota.run/docs/developer-resources#developer-resources-5-canonical-automation-docs","summary":"ota.run Developer Resources · section 5","snippet":"Canonical automation docs GitHub Action Use the official action wrapper for CI readiness checks and pull-request feedback. Use this when ota should run inside GitHub Actions. Gi...","page_title":"ota.run Developer Resources"}],"in_primary_nav":true},{"slug":"agent-integration","title":"ota.run Agent Integration","summary":"Agent integration guide for ota.run covering llms.txt, OpenAPI, official Ota skills, ota.yaml, JSON output, and safe CLI operation.","href":"/docs/agent-integration","canonical_url":"https://ota.run/docs/agent-integration","category":"Automation","intent":"operate","difficulty":"intermediate","audience":"automation-builders","status":"stable","last_reviewed":"2026-05-29","sections":[{"title":"Agent discovery order","href":"/docs/agent-integration#agent-integration-1-agent-discovery-order","canonical_url":"https://ota.run/docs/agent-integration#agent-integration-1-agent-discovery-order","summary":"ota.run Agent Integration · section 1","snippet":"Agent discovery order Agents should start with machine-readable site discovery, then use the repo-local `ota.yaml` when operating inside a checkout. Discovery sequence text http...","page_title":"ota.run Agent Integration"},{"title":"Repository operation order","href":"/docs/agent-integration#agent-integration-2-repository-operation-order","canonical_url":"https://ota.run/docs/agent-integration#agent-integration-2-repository-operation-order","summary":"ota.run Agent Integration · section 2","snippet":"Repository operation order Inside a repository, agents should prefer ota commands over inferred package-manager commands when the repo exposes an ota contract. Safe repo loop ba...","page_title":"ota.run Agent Integration"},{"title":"Boundaries agents must preserve","href":"/docs/agent-integration#agent-integration-3-boundaries-agents-must-preserve","canonical_url":"https://ota.run/docs/agent-integration#agent-integration-3-boundaries-agents-must-preserve","summary":"ota.run Agent Integration · section 3","snippet":"Boundaries agents must preserve treat `ota.yaml` as the source of truth for repo readiness respect declared safe tasks, writable paths, setup requirements, and verification comm...","page_title":"ota.run Agent Integration"},{"title":"Integration surfaces","href":"/docs/agent-integration#agent-integration-4-integration-surfaces","canonical_url":"https://ota.run/docs/agent-integration#agent-integration-4-integration-surfaces","summary":"ota.run Agent Integration · section 4","snippet":"Integration surfaces OpenAPI Use the OpenAPI spec to discover public ota.run resources and standards endpoints. Use this for API catalogs and agent tooling that understands Open...","page_title":"ota.run Agent Integration"}],"in_primary_nav":true},{"slug":"agent-quickstart","title":"ota.run Agent Quickstart","summary":"Agent quickstart for using ota in a repository: discover docs, inspect ota.yaml, run doctor, validate, list safe tasks, copy examples, customize, execute, and parse JSON output.","href":"/docs/agent-quickstart","canonical_url":"https://ota.run/docs/agent-quickstart","category":"Automation","intent":"operate","difficulty":"basic","audience":"automation-builders","status":"stable","last_reviewed":"2026-05-29","sections":[{"title":"Start from discovery","href":"/docs/agent-quickstart#agent-quickstart-1-start-from-discovery","canonical_url":"https://ota.run/docs/agent-quickstart#agent-quickstart-1-start-from-discovery","summary":"ota.run Agent Quickstart · section 1","snippet":"Start from discovery Before acting in a repo, an agent should load the public ota discovery surfaces, then switch to the repo-local contract. Public discovery text https://ota.r...","page_title":"ota.run Agent Quickstart"},{"title":"Inspect the repo contract","href":"/docs/agent-quickstart#agent-quickstart-2-inspect-the-repo-contract","canonical_url":"https://ota.run/docs/agent-quickstart#agent-quickstart-2-inspect-the-repo-contract","summary":"ota.run Agent Quickstart · section 2","snippet":"Inspect the repo contract Inside the checkout, prefer ota commands over inferred package-manager commands when `ota.yaml` exists. First local pass bash test -f ota.yaml && ota d...","page_title":"ota.run Agent Quickstart"},{"title":"Copy, customize, validate, execute","href":"/docs/agent-quickstart#agent-quickstart-3-copy-customize-validate-execute","canonical_url":"https://ota.run/docs/agent-quickstart#agent-quickstart-3-copy-customize-validate-execute","summary":"ota.run Agent Quickstart · section 3","snippet":"Copy, customize, validate, execute copy the nearest example contract only when the repo lacks `ota.yaml` customize the smallest required fields for runtimes, setup, services, an...","page_title":"ota.run Agent Quickstart"},{"title":"When to stop","href":"/docs/agent-quickstart#agent-quickstart-4-when-to-stop","canonical_url":"https://ota.run/docs/agent-quickstart#agent-quickstart-4-when-to-stop","summary":"ota.run Agent Quickstart · section 4","snippet":"When to stop stop when `ota doctor` reports blockers that require user secrets, credentials, or external services stop when a task declares external state and the user has not a...","page_title":"ota.run Agent Quickstart"}],"in_primary_nav":true},{"slug":"json-output","title":"JSON Output","summary":"Use JSON when automation needs stable contract data instead of reading terminal prose.","href":"/docs/reference/json-output","canonical_url":"https://ota.run/docs/reference/json-output","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use JSON","href":"/docs/reference/json-output#json-output-1-when-to-use-json","canonical_url":"https://ota.run/docs/reference/json-output#json-output-1-when-to-use-json","summary":"JSON Output · section 1","snippet":"When to use JSON Use JSON when automation needs stable contract data instead of reading terminal prose. The JSON surface is the integration contract for CI, editors, AI agents, ...","page_title":"JSON Output"},{"title":"Common payload fields","href":"/docs/reference/json-output#json-output-2-common-payload-fields","canonical_url":"https://ota.run/docs/reference/json-output#json-output-2-common-payload-fields","summary":"JSON Output · section 2","snippet":"Common payload fields `ok` tells you whether ota completed the command successfully `path` tells you which contract or workspace file ota resolved `semver`, `version`, `source_b...","page_title":"JSON Output"},{"title":"Canonical source","href":"/docs/reference/json-output#json-output-3-canonical-source","canonical_url":"https://ota.run/docs/reference/json-output#json-output-3-canonical-source","summary":"JSON Output · section 3","snippet":"Canonical source the canonical machine-readable contract lives in the ota repo spec and the published JSON schemas, not in this summary page alone treat `docs/spec/json-output-r...","page_title":"JSON Output"},{"title":"What to use","href":"/docs/reference/json-output#json-output-4-what-to-use","canonical_url":"https://ota.run/docs/reference/json-output#json-output-4-what-to-use","summary":"JSON Output · section 4","snippet":"What to use `version` for machine-readable ota build identity and contract capability support `agents` for repo-local `AGENTS.md` export preview or sync reports, including appro...","page_title":"JSON Output"},{"title":"Canonical schema URLs","href":"/docs/reference/json-output#json-output-5-canonical-schema-urls","canonical_url":"https://ota.run/docs/reference/json-output#json-output-5-canonical-schema-urls","summary":"JSON Output · section 5","snippet":"Canonical schema URLs These are the live schema URLs behind the public JSON reference. Click a card to open the schema in a new tab. Use the command example when you want to ins...","page_title":"JSON Output"},{"title":"Workspace schema URLs","href":"/docs/reference/json-output#json-output-6-workspace-schema-urls","canonical_url":"https://ota.run/docs/reference/json-output#json-output-6-workspace-schema-urls","summary":"JSON Output · section 6","snippet":"Workspace schema URLs Use these when the workspace contract coordinates multiple repos and you need the workspace-level machine contract. workspace-init.json Workspace scaffoldi...","page_title":"JSON Output"},{"title":"Change and remediation URLs","href":"/docs/reference/json-output#json-output-7-change-and-remediation-urls","canonical_url":"https://ota.run/docs/reference/json-output#json-output-7-change-and-remediation-urls","summary":"JSON Output · section 7","snippet":"Change and remediation URLs Use these when you are comparing contracts or turning findings into step-by-step fixes. diff.json Semantic contract diff output. Use when you want to...","page_title":"JSON Output"},{"title":"Read the payload in the right order","href":"/docs/reference/json-output#json-output-8-read-the-payload-in-the-right-order","canonical_url":"https://ota.run/docs/reference/json-output#json-output-8-read-the-payload-in-the-right-order","summary":"JSON Output · section 8","snippet":"Read the payload in the right order Check `ok` first to see whether the command completed cleanly Then read `path` to confirm which contract or workspace ota resolved Then read ...","page_title":"JSON Output"},{"title":"Repo and workspace surfaces","href":"/docs/reference/json-output#json-output-9-repo-and-workspace-surfaces","canonical_url":"https://ota.run/docs/reference/json-output#json-output-9-repo-and-workspace-surfaces","summary":"JSON Output · section 9","snippet":"Repo and workspace surfaces `ota validate --json` for contract gating `ota workflows --json` for workflow inventory and selected-path discovery `ota tasks --json` for task inven...","page_title":"JSON Output"},{"title":"Example payloads","href":"/docs/reference/json-output#json-output-10-example-payloads","canonical_url":"https://ota.run/docs/reference/json-output#json-output-10-example-payloads","summary":"JSON Output · section 10","snippet":"Example payloads Doctor output json { \"ok\": false, \"path\": \"/workspace/acme/ota.yaml\", \"mode\": \"container\", \"summary\": { \"error_count\": 1, \"warn_count\": 1, \"info_count\": 0 }, \"f...","page_title":"JSON Output"},{"title":"What JSON is not","href":"/docs/reference/json-output#json-output-11-what-json-is-not","canonical_url":"https://ota.run/docs/reference/json-output#json-output-11-what-json-is-not","summary":"JSON Output · section 11","snippet":"What JSON is not not live logs not a replacement for the human status line not a text parsing target not the only output mode ota provides","page_title":"JSON Output"},{"title":"Use cases","href":"/docs/reference/json-output#json-output-12-use-cases","canonical_url":"https://ota.run/docs/reference/json-output#json-output-12-use-cases","summary":"JSON Output · section 12","snippet":"Use cases a CI job runs `ota doctor --json`, fails on errors, and posts warnings as annotations an editor shows the primary finding without parsing text output an agent reads th...","page_title":"JSON Output"}],"in_primary_nav":true},{"slug":"execution-receipt","title":"Execution Receipt","summary":"Read the receipt after a command runs if you need to audit what happened.","href":"/docs/reference/execution-receipt","canonical_url":"https://ota.run/docs/reference/execution-receipt","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What a receipt is for","href":"/docs/reference/execution-receipt#execution-receipt-1-what-a-receipt-is-for","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-1-what-a-receipt-is-for","summary":"Execution Receipt · section 1","snippet":"What a receipt is for Read the receipt after a command runs if you need to audit what happened. Use it when you want to compare runs, debug failures, or prove which backend and ...","page_title":"Execution Receipt"},{"title":"Receipt fields","href":"/docs/reference/execution-receipt#execution-receipt-2-receipt-fields","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-2-receipt-fields","summary":"Execution Receipt · section 2","snippet":"Receipt fields `ok` tells you whether the command completed successfully `path` tells you which repo or workspace file ota resolved for the run `scope` tells you whether the rec...","page_title":"Execution Receipt"},{"title":"How to read it","href":"/docs/reference/execution-receipt#execution-receipt-3-how-to-read-it","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-3-how-to-read-it","summary":"Execution Receipt · section 3","snippet":"How to read it Check `ok` first to see whether execution succeeded Then check `scope` and `contract` to confirm what ota ran against Then check `backend` and `lifecycle` to unde...","page_title":"Execution Receipt"},{"title":"Repo example","href":"/docs/reference/execution-receipt#execution-receipt-4-repo-example","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-4-repo-example","summary":"Execution Receipt · section 4","snippet":"Repo example A repo receipt should be enough to tell you what happened in that repo run without opening the terminal output again. Repo task run json { \"ok\": true, \"path\": \"/wor...","page_title":"Execution Receipt"},{"title":"Workspace example","href":"/docs/reference/execution-receipt#execution-receipt-5-workspace-example","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-5-workspace-example","summary":"Execution Receipt · section 5","snippet":"Workspace example A workspace receipt should tell you which member blocked the rollout and which members finished cleanly. Workspace run json { \"ok\": false, \"path\": \"/workspace/...","page_title":"Execution Receipt"},{"title":"How to use it","href":"/docs/reference/execution-receipt#execution-receipt-6-how-to-use-it","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-6-how-to-use-it","summary":"Execution Receipt · section 6","snippet":"How to use it use `ota execution plan --json` when you need to inspect backend, lifecycle, image, or target selection without running setup or tasks workflow-aware planning foll...","page_title":"Execution Receipt"},{"title":"What it is not","href":"/docs/reference/execution-receipt#execution-receipt-7-what-it-is-not","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-7-what-it-is-not","summary":"Execution Receipt · section 7","snippet":"What it is not not live logs not a diagnosis report not a contract inference result not a replacement for `doctor` not a replacement for `detect` not the place to discover new c...","page_title":"Execution Receipt"},{"title":"Use cases","href":"/docs/reference/execution-receipt#execution-receipt-8-use-cases","canonical_url":"https://ota.run/docs/reference/execution-receipt#execution-receipt-8-use-cases","summary":"Execution Receipt · section 8","snippet":"Use cases confirm what ota actually executed after a successful `ota run` debug a failed `ota up` without guessing which backend or lifecycle was used inspect which steps were b...","page_title":"Execution Receipt"}],"in_primary_nav":true},{"slug":"exit-codes","title":"Exit Codes","summary":"Exit codes are the control signal for automation.","href":"/docs/reference/exit-codes","canonical_url":"https://ota.run/docs/reference/exit-codes","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Why it matters","href":"/docs/reference/exit-codes#exit-codes-1-why-it-matters","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-1-why-it-matters","summary":"Exit Codes · section 1","snippet":"Why it matters Exit codes are the control signal for automation. Use them when CI, shell scripts, or agents need stable success and failure rules without parsing text output. te...","page_title":"Exit Codes"},{"title":"Global registry","href":"/docs/reference/exit-codes#exit-codes-2-global-registry","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-2-global-registry","summary":"Exit Codes · section 2","snippet":"Global registry `0`: success; warning-only diagnosis still counts as success `1`: invalid contract, blocking readiness issue, protected write failure, or ota-level failure befor...","page_title":"Exit Codes"},{"title":"Common cases","href":"/docs/reference/exit-codes#exit-codes-3-common-cases","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-3-common-cases","summary":"Exit Codes · section 3","snippet":"Common cases `0` means ota finished successfully if ota launches a child command and that child fails, ota keeps the child exit code instead of collapsing it to `1` `1` means ot...","page_title":"Exit Codes"},{"title":"Repo commands","href":"/docs/reference/exit-codes#exit-codes-4-repo-commands","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-4-repo-commands","summary":"Exit Codes · section 4","snippet":"Repo commands `ota validate`: `0` on valid contract, `1` on load or validation failure `ota workflows`: `0` on valid contract and successful workflow listing, `1` on load or val...","page_title":"Exit Codes"},{"title":"Workspace commands","href":"/docs/reference/exit-codes#exit-codes-5-workspace-commands","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-5-workspace-commands","summary":"Exit Codes · section 5","snippet":"Workspace commands `ota workspace validate`: `0` on valid workspace contract, `1` on load or validation failure `ota workspace tasks`: `0` on successful workspace task listing, ...","page_title":"Exit Codes"},{"title":"JSON alignment","href":"/docs/reference/exit-codes#exit-codes-6-json-alignment","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-6-json-alignment","summary":"Exit Codes · section 6","snippet":"JSON alignment `ok: true` in JSON output aligns with exit code `0` warning-only diagnosis is still success JSON mode does not change exit-code behavior","page_title":"Exit Codes"},{"title":"Use cases","href":"/docs/reference/exit-codes#exit-codes-7-use-cases","canonical_url":"https://ota.run/docs/reference/exit-codes#exit-codes-7-use-cases","summary":"Exit Codes · section 7","snippet":"Use cases CI decides whether to fail a pipeline shell scripts branch on success or failure agents distinguish between bad invocation and repo readiness hosted validation maps ex...","page_title":"Exit Codes"}],"in_primary_nav":true},{"slug":"hosted-validation","title":"CI Validation","summary":"Hosted validation is the read-only CI path for ota.","href":"/docs/reference/hosted-validation","canonical_url":"https://ota.run/docs/reference/hosted-validation","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Purpose","href":"/docs/reference/hosted-validation#hosted-validation-1-purpose","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-1-purpose","summary":"CI Validation · section 1","snippet":"Purpose Hosted validation is the read-only CI path for ota. Use it when a pull request or pipeline needs to verify a repo or workspace without mutating it, so reviewers get a ga...","page_title":"CI Validation"},{"title":"Repo gating","href":"/docs/reference/hosted-validation#hosted-validation-2-repo-gating","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-2-repo-gating","summary":"CI Validation · section 2","snippet":"Repo gating Use these when CI should judge one repo directly and stay read-only. Use this surface for contract validation, readiness diagnosis, container-boundary diagnosis, and...","page_title":"CI Validation"},{"title":"Workspace gating","href":"/docs/reference/hosted-validation#hosted-validation-3-workspace-gating","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-3-workspace-gating","summary":"CI Validation · section 3","snippet":"Workspace gating Use these when the orchestration layer is the thing being judged rather than one repo in isolation. Use this surface for workspace validation, readiness diagnos...","page_title":"CI Validation"},{"title":"Inventory and preflight","href":"/docs/reference/hosted-validation#hosted-validation-4-inventory-and-preflight","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-4-inventory-and-preflight","summary":"CI Validation · section 4","snippet":"Inventory and preflight Use these when CI or a hosted validator needs inventory and roll-up data without acting like an execution wrapper. Use this surface for runnable inventor...","page_title":"CI Validation"},{"title":"Operational rule","href":"/docs/reference/hosted-validation#hosted-validation-5-operational-rule","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-5-operational-rule","summary":"CI Validation · section 5","snippet":"Operational rule use hosted validation when the repo should be judged, not changed, so CI stays read-only keep the CI job thin and let ota own the repo-readiness logic, so the g...","page_title":"CI Validation"},{"title":"Example CI flow","href":"/docs/reference/hosted-validation#hosted-validation-6-example-ci-flow","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-6-example-ci-flow","summary":"CI Validation · section 6","snippet":"Example CI flow CI and Pipelines yaml name: ci on: pull_request: jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Install ota run: | curl -fsSL ...","page_title":"CI Validation"},{"title":"Official GitHub Action","href":"/docs/reference/hosted-validation#hosted-validation-7-official-github-action","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-7-official-github-action","summary":"CI Validation · section 7","snippet":"Official GitHub Action Use `ota-run/action@v1` when you want the GitHub-native wrapper instead of hand-written JSON glue. It keeps the gate read-only while publishing the summar...","page_title":"CI Validation"},{"title":"Use cases","href":"/docs/reference/hosted-validation#hosted-validation-8-use-cases","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-8-use-cases","summary":"CI Validation · section 8","snippet":"Use cases a pull request needs a blocking readiness check before merge a CI pipeline wants annotations instead of raw JSON a workspace gate needs to show which repo is blocking ...","page_title":"CI Validation"},{"title":"What to fail on","href":"/docs/reference/hosted-validation#hosted-validation-9-what-to-fail-on","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-9-what-to-fail-on","summary":"CI Validation · section 9","snippet":"What to fail on `ok: false` `summary.error_count > 0` for validation commands any `error` or `errors` any `severity: error` non-zero exit when validation is expected to pass","page_title":"CI Validation"},{"title":"Runner boundary","href":"/docs/reference/hosted-validation#hosted-validation-10-runner-boundary","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-10-runner-boundary","summary":"CI Validation · section 10","snippet":"Runner boundary GitHub Actions or your CI runner can still provision infrastructure such as service containers. ota removes duplicated repo logic above the runner by keeping val...","page_title":"CI Validation"},{"title":"Annotation mapping","href":"/docs/reference/hosted-validation#hosted-validation-11-annotation-mapping","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-11-annotation-mapping","summary":"CI Validation · section 11","snippet":"Annotation mapping Use the JSON payload as the source of truth and turn it into annotations or check-run summaries without re-parsing text output. use `summary.primary_blocker` ...","page_title":"CI Validation"},{"title":"Keep it read-only","href":"/docs/reference/hosted-validation#hosted-validation-12-keep-it-read-only","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-12-keep-it-read-only","summary":"CI Validation · section 12","snippet":"Keep it read-only do not run `ota init` do not run `ota detect --write` do not run `ota workspace init --bootstrap` do not infer behavior from human text output","page_title":"CI Validation"},{"title":"Portable CI adapter","href":"/docs/reference/hosted-validation#hosted-validation-13-portable-ci-adapter","canonical_url":"https://ota.run/docs/reference/hosted-validation#hosted-validation-13-portable-ci-adapter","summary":"CI Validation · section 13","snippet":"Portable CI adapter `ota annotations` is the canonical JSON-to-CI adapter. Use `--format plain` for provider-neutral log lines, `--format github` for GitHub-native annotations, ...","page_title":"CI Validation"}],"in_primary_nav":true},{"slug":"policy-concepts","title":"Policy concepts","summary":"Policy is the governance layer above `ota.yaml`. It decides what is required, what is approved, and how ota explains a mismatch when the repo and the org disagree.","href":"/docs/policy-concepts","canonical_url":"https://ota.run/docs/policy-concepts","category":"Policy","intent":"learn","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Policy at a glance","href":"/docs/policy-concepts#policy-concepts-1-policy-at-a-glance","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-1-policy-at-a-glance","summary":"Policy concepts · section 1","snippet":"Policy at a glance Policy is the governance layer above `ota.yaml`. It decides what is required, what is approved, and how ota explains a mismatch when the repo and the org disa...","page_title":"Policy concepts"},{"title":"What policy is","href":"/docs/policy-concepts#policy-concepts-2-what-policy-is","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-2-what-policy-is","summary":"Policy concepts · section 2","snippet":"What policy is Policy is not a second contract. It is the rule layer above `ota.yaml`. Repo policy stays in `ota.yaml`. Org policy packs live in `.ota/org-policy.yaml`, are disc...","page_title":"Policy concepts"},{"title":"What policy does","href":"/docs/policy-concepts#policy-concepts-3-what-policy-does","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-3-what-policy-does","summary":"Policy concepts · section 3","snippet":"What policy does Repo guardrails The repo contract tells ota which tasks an AI agent may run, which paths it may edit, which paths it should avoid, and which checks should run a...","page_title":"Policy concepts"},{"title":"Field descriptions","href":"/docs/policy-concepts#policy-concepts-4-field-descriptions","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-4-field-descriptions","summary":"Policy concepts · section 4","snippet":"Field descriptions `posture` is the primary authority model; use `readiness_strict` for normal readiness slices, `contract_authoring` for repo-contract authoring, and `infra_aut...","page_title":"Policy concepts"},{"title":"Example policy pack","href":"/docs/policy-concepts#policy-concepts-5-example-policy-pack","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-5-example-policy-pack","summary":"Policy concepts · section 5","snippet":"Example policy pack A policy pack is a shared org rule set. It does not replace `ota.yaml`; it adds constraints above it. Use it when you want every repo to follow the same rule...","page_title":"Policy concepts"},{"title":"When to use it","href":"/docs/policy-concepts#policy-concepts-6-when-to-use-it","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-6-when-to-use-it","summary":"Policy concepts · section 6","snippet":"When to use it use `safe_tasks` when you want a safe default set for AI agents and CI tooling use `writable_paths` when you want to tell AI agents exactly what they may edit use...","page_title":"Policy concepts"},{"title":"What it is not","href":"/docs/policy-concepts#policy-concepts-7-what-it-is-not","canonical_url":"https://ota.run/docs/policy-concepts#policy-concepts-7-what-it-is-not","summary":"Policy concepts · section 7","snippet":"What it is not not a ticketing system not a waiver workflow not a hidden control plane not a replacement for `ota.yaml` Anti-example yaml # Avoid: putting run scripts or task bo...","page_title":"Policy concepts"}],"in_primary_nav":true},{"slug":"policy-packs","title":"Policy Packs","summary":"Use this page when a platform or operations team wants one rule set to apply across many repos.","href":"/docs/reference/policy-packs","canonical_url":"https://ota.run/docs/reference/policy-packs","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/policy-packs#policy-packs-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-1-when-to-use-this-page","summary":"Policy Packs · section 1","snippet":"When to use this page Use this page when a platform or operations team wants one rule set to apply across many repos. Policy packs keep shared rules out of individual `ota.yaml`...","page_title":"Policy Packs"},{"title":"Policy vs Contract","href":"/docs/reference/policy-packs#policy-packs-2-policy-vs-contract","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-2-policy-vs-contract","summary":"Policy Packs · section 2","snippet":"Policy vs Contract The repo contract says what one repo needs. The policy pack says what the org wants every repo to satisfy on top of that. repo contract values are local and r...","page_title":"Policy Packs"},{"title":"Why it matters","href":"/docs/reference/policy-packs#policy-packs-3-why-it-matters","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-3-why-it-matters","summary":"Policy Packs · section 3","snippet":"Why it matters Without policy packs, the same org rules get repeated in repo after repo. consistent agent safety rules required sections or files across repos org-level contract...","page_title":"Policy Packs"},{"title":"Operator loop","href":"/docs/reference/policy-packs#policy-packs-4-operator-loop","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-4-operator-loop","summary":"Policy Packs · section 4","snippet":"Operator loop Most teams do not start with policy authoring. They start when `ota doctor` shows a policy-backed finding or when the platform team wants one reviewed rule set acr...","page_title":"Policy Packs"},{"title":"Where they live","href":"/docs/reference/policy-packs#policy-packs-5-where-they-live","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-5-where-they-live","summary":"Policy Packs · section 5","snippet":"Where they live The canonical policy pack lives at `.ota/org-policy.yaml`. Use `ota policy init --dry-run` to preview the conservative starter and `ota policy init` to write it ...","page_title":"Policy Packs"},{"title":"Contract field descriptions","href":"/docs/reference/policy-packs#policy-packs-6-contract-field-descriptions","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-6-contract-field-descriptions","summary":"Policy Packs · section 6","snippet":"Contract field descriptions These are the policy fields users are most likely to see in a real repo. `required_sections` means the repo must declare those contract sections `req...","page_title":"Policy Packs"},{"title":"Example policy pack","href":"/docs/reference/policy-packs#policy-packs-7-example-policy-pack","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-7-example-policy-pack","summary":"Policy Packs · section 7","snippet":"Example policy pack A policy pack is a shared org rule set. It does not replace `ota.yaml`; it adds constraints above it and lets `doctor` explain the mismatch clearly when a re...","page_title":"Policy Packs"},{"title":"What it can do","href":"/docs/reference/policy-packs#policy-packs-8-what-it-can-do","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-8-what-it-can-do","summary":"Policy Packs · section 8","snippet":"What it can do require contract sections require repo files require safer agent guidance require explicit writable-path intent require generated repo guidance such as `AGENTS.md...","page_title":"Policy Packs"},{"title":"What it cannot do","href":"/docs/reference/policy-packs#policy-packs-9-what-it-cannot-do","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-9-what-it-cannot-do","summary":"Policy Packs · section 9","snippet":"What it cannot do define repo readiness on its own act as a workflow engine replace approvals or ticketing silently mutate repo files erase the repo contract or make the repo sa...","page_title":"Policy Packs"},{"title":"How it shows up in ota","href":"/docs/reference/policy-packs#policy-packs-10-how-it-shows-up-in-ota","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-10-how-it-shows-up-in-ota","summary":"Policy Packs · section 10","snippet":"How it shows up in ota `ota doctor` is the main place users see policy packs. `ota policy init` creates the conservative starter policy pack, and `ota policy review` is the poli...","page_title":"Policy Packs"},{"title":"How to read a policy finding","href":"/docs/reference/policy-packs#policy-packs-11-how-to-read-a-policy-finding","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-11-how-to-read-a-policy-finding","summary":"Policy Packs · section 11","snippet":"How to read a policy finding read the summary first to see the rule that failed read the why line to understand the org expectation read the next line to see the smallest safe f...","page_title":"Policy Packs"},{"title":"Use cases","href":"/docs/reference/policy-packs#policy-packs-12-use-cases","canonical_url":"https://ota.run/docs/reference/policy-packs#policy-packs-12-use-cases","summary":"Policy Packs · section 12","snippet":"Use cases a platform team wants every repo to declare tasks and runtimes an org wants agent-safe execution rules across many repos a maintainer needs `AGENTS.md` to exist everyw...","page_title":"Policy Packs"}],"in_primary_nav":true},{"slug":"org-policy","title":"Org Policy Baseline","summary":"This is the concrete policy file to use when an org wants a baseline that is strict enough to be useful and small enough to be adopted.","href":"/docs/reference/org-policy","canonical_url":"https://ota.run/docs/reference/org-policy","category":"Policy","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What it is","href":"/docs/reference/org-policy#org-policy-1-what-it-is","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-1-what-it-is","summary":"Org Policy Baseline · section 1","snippet":"What it is This is the concrete policy file to use when an org wants a baseline that is strict enough to be useful and small enough to be adopted. It keeps repo contracts separa...","page_title":"Org Policy Baseline"},{"title":"required_sections","href":"/docs/reference/org-policy#org-policy-2-required-sections","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-2-required-sections","summary":"Org Policy Baseline · section 2","snippet":"required_sections `required_sections` says which contract sections must exist before the repo can be treated as governed and ready for review. Use it when every repo in the org ...","page_title":"Org Policy Baseline"},{"title":"required_files","href":"/docs/reference/org-policy#org-policy-3-required-files","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-3-required-files","summary":"Org Policy Baseline · section 3","snippet":"required_files `required_files` says which files must exist at the governed boundary in addition to the repo contract. Use it when repos must carry shared guidance such as `AGEN...","page_title":"Org Policy Baseline"},{"title":"strict_versions","href":"/docs/reference/org-policy#org-policy-4-strict-versions","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-4-strict-versions","summary":"Org Policy Baseline · section 4","snippet":"strict_versions `strict_versions` tells ota whether already-installed runtime and tool versions must also comply with policy instead of only satisfying the repo contract. Use it...","page_title":"Org Policy Baseline"},{"title":"agent.require_safe_tasks","href":"/docs/reference/org-policy#org-policy-5-agent-require-safe-tasks","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-5-agent-require-safe-tasks","summary":"Org Policy Baseline · section 5","snippet":"agent.require_safe_tasks `agent.require_safe_tasks` says agent-facing execution must be explicit about which tasks are safe before ota can treat them as part of the normal autom...","page_title":"Org Policy Baseline"},{"title":"agent.require_writable_paths","href":"/docs/reference/org-policy#org-policy-6-agent-require-writable-paths","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-6-agent-require-writable-paths","summary":"Org Policy Baseline · section 6","snippet":"agent.require_writable_paths `agent.require_writable_paths` says the contract must declare where an agent may edit before ota treats the repo as safely automatable. Use it when ...","page_title":"Org Policy Baseline"},{"title":"exports.require_agents_md","href":"/docs/reference/org-policy#org-policy-7-exports-require-agents-md","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-7-exports-require-agents-md","summary":"Org Policy Baseline · section 7","snippet":"exports.require_agents_md `exports.require_agents_md` says the org expects repo guidance to be generated and kept aligned with the contract as `AGENTS.md`. Use it when the repo ...","page_title":"Org Policy Baseline"},{"title":"provisioning","href":"/docs/reference/org-policy#org-policy-8-provisioning","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-8-provisioning","summary":"Org Policy Baseline · section 8","snippet":"provisioning `provisioning` approves which source ota may use for each runtime or tool, including platform-specific overrides for macOS, Linux, or Windows. Use it when the org w...","page_title":"Org Policy Baseline"},{"title":"version_policy","href":"/docs/reference/org-policy#org-policy-9-version-policy","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-9-version-policy","summary":"Org Policy Baseline · section 9","snippet":"version_policy `version_policy` defines which runtime and tool versions policy approves. Use it when the org wants version governance even if installs stay manual or come from a...","page_title":"Org Policy Baseline"},{"title":"adapter_bootstrap","href":"/docs/reference/org-policy#org-policy-10-adapter-bootstrap","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-10-adapter-bootstrap","summary":"Org Policy Baseline · section 10","snippet":"adapter_bootstrap `adapter_bootstrap` approves how ota may install its own adapter binaries when the adapter is missing from the target environment. Use it when repo provisionin...","page_title":"Org Policy Baseline"},{"title":"Recommended baseline","href":"/docs/reference/org-policy#org-policy-11-recommended-baseline","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-11-recommended-baseline","summary":"Org Policy Baseline · section 11","snippet":"Recommended baseline Copy this into `.ota/org-policy.yaml` and tune versions to match the approved versions in your fleet. .ota/org-policy.yaml yaml policies: required_sections:...","page_title":"Org Policy Baseline"},{"title":"Platform-aware example","href":"/docs/reference/org-policy#org-policy-12-platform-aware-example","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-12-platform-aware-example","summary":"Org Policy Baseline · section 12","snippet":"Platform-aware example Use this when the org wants a single policy pack that keeps macOS on Homebrew, Linux containers on apt, and Java on sdkman. This is the shape that teaches...","page_title":"Org Policy Baseline"},{"title":"How the platform split works","href":"/docs/reference/org-policy#org-policy-13-how-the-platform-split-works","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-13-how-the-platform-split-works","summary":"Org Policy Baseline · section 13","snippet":"How the platform split works macOS uses `brew` for the tools that are meant to be installed from Homebrew. Linux or container execution uses `apt` for the same tools when the co...","page_title":"Org Policy Baseline"},{"title":"Why it matters","href":"/docs/reference/org-policy#org-policy-14-why-it-matters","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-14-why-it-matters","summary":"Org Policy Baseline · section 14","snippet":"Why it matters `ota doctor` becomes a governance check, not just a local readiness scan repos stay explicit instead of drifting into scripts agent safety remains visible and rev...","page_title":"Org Policy Baseline"},{"title":"Use it when","href":"/docs/reference/org-policy#org-policy-15-use-it-when","canonical_url":"https://ota.run/docs/reference/org-policy#org-policy-15-use-it-when","summary":"Org Policy Baseline · section 15","snippet":"Use it when you want a shared org rule set for many repos you want `AGENTS.md` to be present everywhere you want safe-task and writable-path declarations enforced you want boots...","page_title":"Org Policy Baseline"}],"in_primary_nav":true},{"slug":"environment-values","title":"Environment Variables","summary":"Use this page when a repo needs environment variables and you want to know what ota will actually run with.","href":"/docs/reference/environment-values","canonical_url":"https://ota.run/docs/reference/environment-values","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What this page should answer","href":"/docs/reference/environment-values#environment-values-1-what-this-page-should-answer","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-1-what-this-page-should-answer","summary":"Environment Variables · section 1","snippet":"What this page should answer Use this page when a repo needs environment variables and you want to know what ota will actually run with. The goal is simple: know where to declar...","page_title":"Environment Variables"},{"title":"Where each value belongs","href":"/docs/reference/environment-values#environment-values-2-where-each-value-belongs","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-2-where-each-value-belongs","summary":"Environment Variables · section 2","snippet":"Where each value belongs Most confusion comes from putting the same value in the wrong place. Use the contract to say what the repo needs, then use task env, declared sources, o...","page_title":"Environment Variables"},{"title":"Winner order","href":"/docs/reference/environment-values#environment-values-3-winner-order","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-3-winner-order","summary":"Environment Variables · section 3","snippet":"Winner order This is the shortest useful mental model for env resolution. If a variable looks wrong at runtime, read this list from the top down and stop at the first place that...","page_title":"Environment Variables"},{"title":"Why root env matters","href":"/docs/reference/environment-values#environment-values-4-why-root-env-matters","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-4-why-root-env-matters","summary":"Environment Variables · section 4","snippet":"Why root env matters Root contract env is not only a validation surface. It is the repo-wide execution contract ota uses when it starts work for the repo. it tells ota which env...","page_title":"Environment Variables"},{"title":"What `env.sources` means","href":"/docs/reference/environment-values#environment-values-5-what-env-sources-means","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-5-what-env-sources-means","summary":"Environment Variables · section 5","snippet":"What `env.sources` means `env.sources` makes file-backed env loading explicit instead of magical. A source entry describes the file ota may read and whether that file itself is ...","page_title":"Environment Variables"},{"title":"Execution env layers","href":"/docs/reference/environment-values#environment-values-6-execution-env-layers","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-6-execution-env-layers","summary":"Environment Variables · section 6","snippet":"Execution env layers Root `env.vars` decides which repo-owned values are real. Execution env layers decide what else ota injects around those values for one task run. `execution...","page_title":"Environment Variables"},{"title":"Env variable rules","href":"/docs/reference/environment-values#environment-values-7-env-variable-rules","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-7-env-variable-rules","summary":"Environment Variables · section 7","snippet":"Env variable rules These fields control how ota treats one declared env variable after it resolves a candidate value. `required` means the env var must resolve or ota fails read...","page_title":"Environment Variables"},{"title":"Remote secret caveat","href":"/docs/reference/environment-values#environment-values-8-remote-secret-caveat","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-8-remote-secret-caveat","summary":"Environment Variables · section 8","snippet":"Remote secret caveat Secret env values have one extra boundary beyond ordinary env resolution. ota redacts `secret: true` values in output and receipts remote shell execution re...","page_title":"Environment Variables"},{"title":"PATH is special","href":"/docs/reference/environment-values#environment-values-9-path-is-special","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-9-path-is-special","summary":"Environment Variables · section 9","snippet":"PATH is special `PATH` is an ordered search path, so ota treats it differently from a plain value like `JAVA_HOME`. use `PATH` when order matters and repo-local or toolchain bin...","page_title":"Environment Variables"},{"title":"Examples","href":"/docs/reference/environment-values#environment-values-10-examples","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-10-examples","summary":"Environment Variables · section 10","snippet":"Examples These examples cover the common flow: declare repo truth, let policy help when needed, and inspect the resolved winner instead of guessing. for workspace commands, `ota...","page_title":"Environment Variables"},{"title":"How to use it","href":"/docs/reference/environment-values#environment-values-11-how-to-use-it","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-11-how-to-use-it","summary":"Environment Variables · section 11","snippet":"How to use it If you want env behavior to stay reviewable instead of tribal knowledge, follow this sequence. declare env requirements in `env.vars` first so the repo contract st...","page_title":"Environment Variables"},{"title":"Where it shows up","href":"/docs/reference/environment-values#environment-values-12-where-it-shows-up","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-12-where-it-shows-up","summary":"Environment Variables · section 12","snippet":"Where it shows up `doctor` diagnoses missing or invalid env values and missing or broken declared sources `ota env` shows both declared source status and the winning source for ...","page_title":"Environment Variables"},{"title":"What policy is not","href":"/docs/reference/environment-values#environment-values-13-what-policy-is-not","canonical_url":"https://ota.run/docs/reference/environment-values#environment-values-13-what-policy-is-not","summary":"Environment Variables · section 13","snippet":"What policy is not not a replacement for `env.sources` not a way to invent new env requirements the repo contract never declared not a general application config system not sile...","page_title":"Environment Variables"}],"in_primary_nav":true},{"slug":"version-policy","title":"Version Policy","summary":"Use this page when a repo should stay explicit about what it needs, but the org wants to constrain which versions may be declared.","href":"/docs/reference/version-policy","canonical_url":"https://ota.run/docs/reference/version-policy","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/version-policy#version-policy-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-1-when-to-use-this-page","summary":"Version Policy · section 1","snippet":"When to use this page Use this page when a repo should stay explicit about what it needs, but the org wants to constrain which versions may be declared. Use `version_policy` whe...","page_title":"Version Policy"},{"title":"How policy is interpreted","href":"/docs/reference/version-policy#version-policy-2-how-policy-is-interpreted","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-2-how-policy-is-interpreted","summary":"Version Policy · section 2","snippet":"How policy is interpreted Think of policy as an approval gate. It validates what the repo declares; it does not rewrite repo requirements. `version_policy` is keyed by `runtimes...","page_title":"Version Policy"},{"title":"Current boundary","href":"/docs/reference/version-policy#version-policy-3-current-boundary","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-3-current-boundary","summary":"Version Policy · section 3","snippet":"Current boundary Repo contract Declare runtime and tool intent in `ota.yaml`, including `only_on` for OS scope, `platforms` for per-OS value overrides, and `required: false` whe...","page_title":"Version Policy"},{"title":"Exact pin example","href":"/docs/reference/version-policy#version-policy-4-exact-pin-example","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-4-exact-pin-example","summary":"Version Policy · section 4","snippet":"Exact pin example `node: \"22\"` passes and `node: \"24\"` fails `pnpm: \"10.12.4\"` passes and `pnpm: \"10.12.5\"` fails this is the strictest form because the org is enumerating one a...","page_title":"Version Policy"},{"title":"Semver-range example","href":"/docs/reference/version-policy#version-policy-5-semver-range-example","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-5-semver-range-example","summary":"Version Policy · section 5","snippet":"Semver-range example use ranges when the org wants one compatible version family instead of one exact patch keep the policy explicit enough that repo maintainers can still tell ...","page_title":"Version Policy"},{"title":"OS-scoped example","href":"/docs/reference/version-policy#version-policy-6-os-scoped-example","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-6-os-scoped-example","summary":"Version Policy · section 6","snippet":"OS-scoped example Use `only_on` in the contract for OS scope, keep `platforms` in the contract or `version_policy` for per-OS overrides, and use `required` only for blocking-ver...","page_title":"Version Policy"},{"title":"Java distribution example","href":"/docs/reference/version-policy#version-policy-7-java-distribution-example","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-7-java-distribution-example","summary":"Version Policy · section 7","snippet":"Java distribution example Java is the clearest case for separating repo intent from org governance, because version, provider, distribution, and install source can all differ wi...","page_title":"Version Policy"},{"title":"With provisioning","href":"/docs/reference/version-policy#version-policy-8-with-provisioning","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-8-with-provisioning","summary":"Version Policy · section 8","snippet":"With provisioning Use both layers when the org wants to govern the allowed contract versions and also govern where ota may install them from. `version_policy` is the contract go...","page_title":"Version Policy"},{"title":"How doctor explains a failure","href":"/docs/reference/version-policy#version-policy-9-how-doctor-explains-a-failure","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-9-how-doctor-explains-a-failure","summary":"Version Policy · section 9","snippet":"How doctor explains a failure a version-policy failure is a contract-versus-policy mismatch it is not the same thing as missing provisioning or a broken package manager the next...","page_title":"Version Policy"},{"title":"When this is the right boundary","href":"/docs/reference/version-policy#version-policy-10-when-this-is-the-right-boundary","canonical_url":"https://ota.run/docs/reference/version-policy#version-policy-10-when-this-is-the-right-boundary","summary":"Version Policy · section 10","snippet":"When this is the right boundary use `version_policy` when you want the org to control what versions are acceptable use `provisioning` separately when the org must also control w...","page_title":"Version Policy"}],"in_primary_nav":true},{"slug":"policy-backed-provisioning","title":"Provisioning Sources","summary":"Use this page when a repo needs a runtime or tool and the organization wants to say where it may come from.","href":"/docs/reference/policy-backed-provisioning","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-1-when-to-use-this-page","summary":"Provisioning Sources · section 1","snippet":"When to use this page Use this page when a repo needs a runtime or tool and the organization wants to say where it may come from. Policy can approve a feed, mirror, bucket, tap,...","page_title":"Provisioning Sources"},{"title":"Current boundary","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-2-current-boundary","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-2-current-boundary","summary":"Provisioning Sources · section 2","snippet":"Current boundary Policy should use `source: <adapter>` from the shipped set when it wants ota to provision through a built-in backend. `source` selects the adapter family, then ...","page_title":"Provisioning Sources"},{"title":"Provisioning field meaning","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-3-provisioning-field-meaning","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-3-provisioning-field-meaning","summary":"Provisioning Sources · section 3","snippet":"Provisioning field meaning Each `policies.provisioning` entry is a small execution contract and should be read left-to-right: `source` (who can install), optional `platforms.<os...","page_title":"Provisioning Sources"},{"title":"Source selection is explicit","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-4-source-selection-is-explicit","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-4-source-selection-is-explicit","summary":"Provisioning Sources · section 4","snippet":"Source selection is explicit policy can never partially combine sources; one prerequisite resolves to exactly one effective source on each target OS. when a contract prerequisit...","page_title":"Provisioning Sources"},{"title":"Version governance boundary","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-5-version-governance-boundary","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-5-version-governance-boundary","summary":"Provisioning Sources · section 5","snippet":"Version governance boundary a repo can be governed by `version_policy` without declaring any provisioning rules doctor should report version-policy failures as contract-versus-p...","page_title":"Provisioning Sources"},{"title":"How source resolution works","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-6-how-source-resolution-works","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-6-how-source-resolution-works","summary":"Provisioning Sources · section 6","snippet":"How source resolution works the root rule is the default for that prerequisite a matching `platforms.<os>` rule overrides the root rule for that prerequisite after resolution, o...","page_title":"Provisioning Sources"},{"title":"Version resolution rules","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-7-version-resolution-rules","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-7-version-resolution-rules","summary":"Provisioning Sources · section 7","snippet":"Version resolution rules What policy may approve Policy can authorize exact versions and semver ranges such as `^24`, `~20.10`, or `>=18 <23`. What ota records Doctor JSON recor...","page_title":"Provisioning Sources"},{"title":"Package mapping rules","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-8-package-mapping-rules","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-8-package-mapping-rules","summary":"Provisioning Sources · section 8","snippet":"Package mapping rules `package` keeps the contract key stable while mapping to the backend install identifier. use `package` whenever the selected source needs an exact package ...","page_title":"Provisioning Sources"},{"title":"When ota will not provision","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-9-when-ota-will-not-provision","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-9-when-ota-will-not-provision","summary":"Provisioning Sources · section 9","snippet":"When ota will not provision Rule mismatch The policy key does not match the contract key, or the contract version does not satisfy any approved exact version or semver range. No...","page_title":"Provisioning Sources"},{"title":"Example policy","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-10-example-policy","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-10-example-policy","summary":"Provisioning Sources · section 10","snippet":"Example policy Repo contract yaml runtimes: java: \"22\" tools: maven: \"3.9\" pwsh: version: \"7.6.0\" only_on: - windows checks: - name: java-installed kind: precondition severity: ...","page_title":"Provisioning Sources"},{"title":"What it does today","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-11-what-it-does-today","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-11-what-it-does-today","summary":"Provisioning Sources · section 11","snippet":"What it does today explain which approved source resolved for a requested runtime or tool on the current target, so users see why ota used that source enforce `version_policy` s...","page_title":"Provisioning Sources"},{"title":"Example output","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-12-example-output","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-12-example-output","summary":"Provisioning Sources · section 12","snippet":"Example output ota policy text 🦦 POLICY ./ota.yaml Policy source: repo policy Policy path: ./.ota/org-policy.yaml policies: provisioning: node: source: brew approved_versions: ...","page_title":"Provisioning Sources"},{"title":"What it is not","href":"/docs/reference/policy-backed-provisioning#policy-backed-provisioning-13-what-it-is-not","canonical_url":"https://ota.run/docs/reference/policy-backed-provisioning#policy-backed-provisioning-13-what-it-is-not","summary":"Provisioning Sources · section 13","snippet":"What it is not not a general package manager not a hidden workstation manager not a raw download URL surface not a replacement for env policy","page_title":"Provisioning Sources"}],"in_primary_nav":true},{"slug":"adapters","title":"Adapters","summary":"Use this page when you want to know which adapter families ota can use for provisioning and why the split matters.","href":"/docs/reference/adapters","canonical_url":"https://ota.run/docs/reference/adapters","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/adapters#adapters-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/adapters#adapters-1-when-to-use-this-page","summary":"Adapters · section 1","snippet":"When to use this page Use this page when you want to know which adapter families ota can use for provisioning and why the split matters. Keep installer adapters separate from so...","page_title":"Adapters"},{"title":"Supported today","href":"/docs/reference/adapters#adapters-2-supported-today","canonical_url":"https://ota.run/docs/reference/adapters#adapters-2-supported-today","summary":"Adapters · section 2","snippet":"Supported today Shipped set These are the built-in mutating provisioning adapters ota can actually use today. Runtime-oriented adapters `sdkman` and `uv` are the runtime-oriente...","page_title":"Adapters"},{"title":"Installer adapters","href":"/docs/reference/adapters#adapters-3-installer-adapters","canonical_url":"https://ota.run/docs/reference/adapters#adapters-3-installer-adapters","summary":"Adapters · section 3","snippet":"Installer adapters Installer adapters install or select a declared runtime or tool. Use them when ota should install or select the toolchain itself and make progress in the repo.","page_title":"Adapters"},{"title":"Source adapters","href":"/docs/reference/adapters#adapters-4-source-adapters","canonical_url":"https://ota.run/docs/reference/adapters#adapters-4-source-adapters","summary":"Adapters · section 4","snippet":"Source adapters Source adapters tell ota where the installer should fetch from. That can be an internal mirror, private registry, approved vendor source, artifact cache, offline...","page_title":"Adapters"},{"title":"Platform-specific provisioning","href":"/docs/reference/adapters#adapters-5-platform-specific-provisioning","canonical_url":"https://ota.run/docs/reference/adapters#adapters-5-platform-specific-provisioning","summary":"Adapters · section 5","snippet":"Platform-specific provisioning Use `platforms` when the same runtime or tool should resolve to different sources on macOS, Linux, and Windows. The root rule acts as the default,...","page_title":"Adapters"},{"title":"macOS and Linux split","href":"/docs/reference/adapters#adapters-6-macos-and-linux-split","canonical_url":"https://ota.run/docs/reference/adapters#adapters-6-macos-and-linux-split","summary":"Adapters · section 6","snippet":"macOS and Linux split Use one policy when macOS still uses `brew`, Linux uses `apt`, and Java stays on `sdkman` in both places. This is the shape to copy when a repo must stay h...","page_title":"Adapters"},{"title":"Custom source configuration","href":"/docs/reference/adapters#adapters-7-custom-source-configuration","canonical_url":"https://ota.run/docs/reference/adapters#adapters-7-custom-source-configuration","summary":"Adapters · section 7","snippet":"Custom source configuration Use the adapter-specific `source_config` key that matches the package manager. That keeps approved taps, buckets, feeds, and mirrors visible in polic...","page_title":"Adapters"},{"title":"Chocolatey feed","href":"/docs/reference/adapters#adapters-8-chocolatey-feed","canonical_url":"https://ota.run/docs/reference/adapters#adapters-8-chocolatey-feed","summary":"Adapters · section 8","snippet":"Chocolatey feed Use `source_config.feed` when Chocolatey should point at an approved internal feed or mirror. This keeps Windows package policy visible and reviewable. org-polic...","page_title":"Adapters"},{"title":"Winget source","href":"/docs/reference/adapters#adapters-9-winget-source","canonical_url":"https://ota.run/docs/reference/adapters#adapters-9-winget-source","summary":"Adapters · section 9","snippet":"Winget source Use `source_config.source_name` when an approved Windows source should back installs. The installed package still comes from the shipped `winget` adapter. org-poli...","page_title":"Adapters"},{"title":"Scoop bucket","href":"/docs/reference/adapters#adapters-10-scoop-bucket","canonical_url":"https://ota.run/docs/reference/adapters#adapters-10-scoop-bucket","summary":"Adapters · section 10","snippet":"Scoop bucket Use `source_config.bucket_name` and `bucket_url` when an approved Scoop bucket should back installs. That keeps the bucket choice reviewable in policy. org-policy-s...","page_title":"Adapters"},{"title":"apt mirror","href":"/docs/reference/adapters#adapters-11-apt-mirror","canonical_url":"https://ota.run/docs/reference/adapters#adapters-11-apt-mirror","summary":"Adapters · section 11","snippet":"apt mirror Use `source_config.sources_list` when you need approved Debian or Ubuntu `deb` entries. The mirror stays visible in policy instead of hiding in a script. org-policy-a...","page_title":"Adapters"},{"title":"dnf mirror","href":"/docs/reference/adapters#adapters-12-dnf-mirror","canonical_url":"https://ota.run/docs/reference/adapters#adapters-12-dnf-mirror","summary":"Adapters · section 12","snippet":"dnf mirror Use `source_config.baseurl` and `repo_id` when you want an approved Fedora or RHEL mirror. The temporary repo label stays reviewable in policy. org-policy-dnf.yaml ya...","page_title":"Adapters"},{"title":"Homebrew tap","href":"/docs/reference/adapters#adapters-13-homebrew-tap","canonical_url":"https://ota.run/docs/reference/adapters#adapters-13-homebrew-tap","summary":"Adapters · section 13","snippet":"Homebrew tap Use `source_config.tap_name` and `tap_url` when an approved Homebrew tap should back installs. That keeps the tap visible in policy instead of hardcoding it in a sc...","page_title":"Adapters"},{"title":"Sample policy","href":"/docs/reference/adapters#adapters-14-sample-policy","canonical_url":"https://ota.run/docs/reference/adapters#adapters-14-sample-policy","summary":"Adapters · section 14","snippet":"Sample policy Use a policy block when you want ota to know which source is approved for a runtime or tool. org-policy.yaml yaml policies: provisioning: node: source: pacman appr...","page_title":"Adapters"},{"title":"Recommended order","href":"/docs/reference/adapters#adapters-15-recommended-order","canonical_url":"https://ota.run/docs/reference/adapters#adapters-15-recommended-order","summary":"Adapters · section 15","snippet":"Recommended order prove one installer backend first add one adapter family at a time keep source adapters policy-driven and read-only until a matching installer exists record th...","page_title":"Adapters"},{"title":"What it is not","href":"/docs/reference/adapters#adapters-16-what-it-is-not","canonical_url":"https://ota.run/docs/reference/adapters#adapters-16-what-it-is-not","summary":"Adapters · section 16","snippet":"What it is not not a general package manager list not a promise that every source adapter is shipped today not a hidden workstation manager not a replacement for repo contracts,...","page_title":"Adapters"}],"in_primary_nav":true},{"slug":"examples","title":"Examples","summary":"Curated contract examples organized by runtime, topology, and policy shape.","href":"/docs/examples","canonical_url":"https://ota.run/docs/examples","category":"Examples","intent":"copy","difficulty":"basic","audience":"new-users","status":"stable","last_reviewed":"2026-05-11","sections":[{"title":"Start by goal","href":"/docs/examples#examples-1-start-by-goal","canonical_url":"https://ota.run/docs/examples#examples-1-start-by-goal","summary":"Examples · section 1","snippet":"Start by goal Use this layer first when you want to prove value quickly instead of scanning every example page. First contract for one repo Start with one simple runtime example...","page_title":"Examples"},{"title":"Libraries and SDKs","href":"/docs/examples#examples-2-libraries-and-sdks","canonical_url":"https://ota.run/docs/examples#examples-2-libraries-and-sdks","summary":"Examples · section 2","snippet":"Libraries and SDKs A repo can be a reusable SDK and still keep readiness, linting, and release flow explicit. Go SDK A Go library contract with build, test, lint, and release ta...","page_title":"Examples"},{"title":"Single-repo examples","href":"/docs/examples#examples-3-single-repo-examples","canonical_url":"https://ota.run/docs/examples#examples-3-single-repo-examples","summary":"Examples · section 3","snippet":"Single-repo examples Use these when one repo owns one contract and one task flow. Node.js A Node contract with setup, dev, and test guidance. Use this for npm or pnpm repos with...","page_title":"Examples"},{"title":"Mixed and service repos","href":"/docs/examples#examples-4-mixed-and-service-repos","canonical_url":"https://ota.run/docs/examples#examples-4-mixed-and-service-repos","summary":"Examples · section 4","snippet":"Mixed and service repos Use these when more than one runtime or service boundary matters. Services A service-oriented repo with healthchecks and explicit readiness. Use this for...","page_title":"Examples"},{"title":"Execution topology examples","href":"/docs/examples#examples-5-execution-topology-examples","canonical_url":"https://ota.run/docs/examples#examples-5-execution-topology-examples","summary":"Examples · section 5","snippet":"Execution topology examples Use these when the hard part is not language support but honest communication between host, workload, service contexts, and dependency storage. Conta...","page_title":"Examples"},{"title":"Workspace examples","href":"/docs/examples#examples-6-workspace-examples","canonical_url":"https://ota.run/docs/examples#examples-6-workspace-examples","summary":"Examples · section 6","snippet":"Workspace examples Use these when multiple repos need a shared bootstrap and execution order. Workspace basics A multi-repo workspace with ordered member readiness. Use this whe...","page_title":"Examples"},{"title":"Policy and provisioning","href":"/docs/examples#examples-7-policy-and-provisioning","canonical_url":"https://ota.run/docs/examples#examples-7-policy-and-provisioning","summary":"Examples · section 7","snippet":"Policy and provisioning Use these when you want to show how repo intent and org policy meet in one contract pair. Provisioning policy probe A repo contract plus policy file that...","page_title":"Examples"},{"title":"Advanced examples","href":"/docs/examples#examples-8-advanced-examples","canonical_url":"https://ota.run/docs/examples#examples-8-advanced-examples","summary":"Examples · section 8","snippet":"Advanced examples This repo lives on GitHub, and the card below is meant to stand apart as a proven pattern to copy and adapt. Advanced examples Browse the maintained repo and r...","page_title":"Examples"}],"in_primary_nav":true},{"slug":"examples-node","title":"Node repos with a managed runtime and explicit Corepack lane","summary":"This is the current honest Node toolchain boundary: `toolchains.node` owns the runtime, `node` executable, and declared Corepack package-manager activation.","href":"/docs/examples/node","canonical_url":"https://ota.run/docs/examples/node","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/node#examples-node-1-typical-signals","canonical_url":"https://ota.run/docs/examples/node#examples-node-1-typical-signals","summary":"Node repos with a managed runtime and explicit Corepack lane · section 1","snippet":"Typical signals package manager: pnpm through Corepack runtime/executable owner: `toolchains.node` entrypoint: setup default task: test","page_title":"Node repos with a managed runtime and explicit Corepack lane"},{"title":"Example contract","href":"/docs/examples/node#examples-node-2-example-contract","canonical_url":"https://ota.run/docs/examples/node#examples-node-2-example-contract","summary":"Node repos with a managed runtime and explicit Corepack lane · section 2","snippet":"Example contract This is the current honest Node toolchain boundary: `toolchains.node` owns the runtime, `node` executable, and declared Corepack package-manager activation. Cor...","page_title":"Node repos with a managed runtime and explicit Corepack lane"}],"in_primary_nav":true},{"slug":"examples-python","title":"Python repos with a clean setup path","summary":"A Python contract that makes setup, tests, and CI explicit.","href":"/docs/examples/python","canonical_url":"https://ota.run/docs/examples/python","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/python#examples-python-1-typical-signals","canonical_url":"https://ota.run/docs/examples/python#examples-python-1-typical-signals","summary":"Python repos with a clean setup path · section 1","snippet":"Typical signals package manager: uv or pip lockfile: uv.lock or requirements.txt entrypoint: setup default task: ci","page_title":"Python repos with a clean setup path"},{"title":"Example contract","href":"/docs/examples/python#examples-python-2-example-contract","canonical_url":"https://ota.run/docs/examples/python#examples-python-2-example-contract","summary":"Python repos with a clean setup path · section 2","snippet":"Example contract ota.yaml yaml project: name: api description: Python service with explicit contract tasks: setup: internal: true run: uv sync test: run: uv run pytest ci: run: ...","page_title":"Python repos with a clean setup path"}],"in_primary_nav":true},{"slug":"examples-tool-acquisition","title":"Workflow-scoped acquisition without repo-global install drift","summary":"Use this when the repo has more than one honest front door and each one should carry its own acquisition lane instead of inheriting repo-global prerequisites.","href":"/docs/examples/tool-acquisition","canonical_url":"https://ota.run/docs/examples/tool-acquisition","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/tool-acquisition#examples-tool-acquisition-1-typical-signals","canonical_url":"https://ota.run/docs/examples/tool-acquisition#examples-tool-acquisition-1-typical-signals","summary":"Workflow-scoped acquisition without repo-global install drift · section 1","snippet":"Typical signals the repo has multiple valid workflows with different runtime and tool needs one tool is activated through Corepack while another is acquired through one declared...","page_title":"Workflow-scoped acquisition without repo-global install drift"},{"title":"Why it matters","href":"/docs/examples/tool-acquisition#examples-tool-acquisition-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/tool-acquisition#examples-tool-acquisition-2-why-it-matters","summary":"Workflow-scoped acquisition without repo-global install drift · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Workflow-scoped acquisition without repo-global install drift"},{"title":"Example contract","href":"/docs/examples/tool-acquisition#examples-tool-acquisition-3-example-contract","canonical_url":"https://ota.run/docs/examples/tool-acquisition#examples-tool-acquisition-3-example-contract","summary":"Workflow-scoped acquisition without repo-global install drift · section 3","snippet":"Example contract Use this when the repo has more than one honest front door and each one should carry its own acquisition lane instead of inheriting repo-global prerequisites. T...","page_title":"Workflow-scoped acquisition without repo-global install drift"},{"title":"Task notes","href":"/docs/examples/tool-acquisition#examples-tool-acquisition-4-task-notes","canonical_url":"https://ota.run/docs/examples/tool-acquisition#examples-tool-acquisition-4-task-notes","summary":"Workflow-scoped acquisition without repo-global install drift · section 4","snippet":"Task notes Use `ota workflows .` first, then compare `ota doctor --workflow web .` with `ota doctor --workflow python .` so you can see that only the selected lane appears. Use ...","page_title":"Workflow-scoped acquisition without repo-global install drift"}],"in_primary_nav":true},{"slug":"examples-windows-adoption","title":"Windows-first adoption with explicit native activation","summary":"Use this when the repo is Windows-first, PowerShell is part of the real release path, and you still want one contract that humans, CI, and agents can trust across platforms.","href":"/docs/examples/windows-adoption","canonical_url":"https://ota.run/docs/examples/windows-adoption","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/windows-adoption#examples-windows-adoption-1-typical-signals","canonical_url":"https://ota.run/docs/examples/windows-adoption#examples-windows-adoption-1-typical-signals","summary":"Windows-first adoption with explicit native activation · section 1","snippet":"Typical signals the repo is Windows-heavy and .NET is part of the real operating model native compiler activation should be part of the contract instead of a hidden shell precon...","page_title":"Windows-first adoption with explicit native activation"},{"title":"Why it matters","href":"/docs/examples/windows-adoption#examples-windows-adoption-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/windows-adoption#examples-windows-adoption-2-why-it-matters","summary":"Windows-first adoption with explicit native activation · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Windows-first adoption with explicit native activation"},{"title":"Example contract","href":"/docs/examples/windows-adoption#examples-windows-adoption-3-example-contract","canonical_url":"https://ota.run/docs/examples/windows-adoption#examples-windows-adoption-3-example-contract","summary":"Windows-first adoption with explicit native activation · section 3","snippet":"Example contract Use this when the repo is Windows-first, PowerShell is part of the real release path, and you still want one contract that humans, CI, and agents can trust acro...","page_title":"Windows-first adoption with explicit native activation"},{"title":"Task notes","href":"/docs/examples/windows-adoption#examples-windows-adoption-4-task-notes","canonical_url":"https://ota.run/docs/examples/windows-adoption#examples-windows-adoption-4-task-notes","summary":"Windows-first adoption with explicit native activation · section 4","snippet":"Task notes Use `ota doctor .`, `ota up --dry-run .`, and `ota proof runtime --workflow app .` in that order. This is the flagship example for the Windows-native trust path, not ...","page_title":"Windows-first adoption with explicit native activation"}],"in_primary_nav":true},{"slug":"examples-go","title":"Go repos with a deterministic loop","summary":"This example keeps the Go path short: fetch dependencies, run tests, and keep the repo honest with one verification task.","href":"/docs/examples/go","canonical_url":"https://ota.run/docs/examples/go","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/go#examples-go-1-typical-signals","canonical_url":"https://ota.run/docs/examples/go#examples-go-1-typical-signals","summary":"Go repos with a deterministic loop · section 1","snippet":"Typical signals go 1.24 setup and test as the primary repo loop a precondition that checks `go version`","page_title":"Go repos with a deterministic loop"},{"title":"Why it matters","href":"/docs/examples/go#examples-go-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/go#examples-go-2-why-it-matters","summary":"Go repos with a deterministic loop · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Go repos with a deterministic loop"},{"title":"Example contract","href":"/docs/examples/go#examples-go-3-example-contract","canonical_url":"https://ota.run/docs/examples/go#examples-go-3-example-contract","summary":"Go repos with a deterministic loop · section 3","snippet":"Example contract This example keeps the Go path short: fetch dependencies, run tests, and keep the repo honest with one verification task. ota.yaml yaml version: 1 project: name...","page_title":"Go repos with a deterministic loop"}],"in_primary_nav":true},{"slug":"examples-go-sdk","title":"Go SDKs with explicit build and release flow","summary":"This example treats the SDK as a product surface: the core loop stays short, and the release path is documented in the task notes.","href":"/docs/examples/go-sdk","canonical_url":"https://ota.run/docs/examples/go-sdk","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/go-sdk#examples-go-sdk-1-typical-signals","canonical_url":"https://ota.run/docs/examples/go-sdk#examples-go-sdk-1-typical-signals","summary":"Go SDKs with explicit build and release flow · section 1","snippet":"Typical signals container backend is explicit Go module dependencies are explicit release checks stay separate from release versioning notes explain the command order for releas...","page_title":"Go SDKs with explicit build and release flow"},{"title":"Why it matters","href":"/docs/examples/go-sdk#examples-go-sdk-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/go-sdk#examples-go-sdk-2-why-it-matters","summary":"Go SDKs with explicit build and release flow · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Go SDKs with explicit build and release flow"},{"title":"Example contract","href":"/docs/examples/go-sdk#examples-go-sdk-3-example-contract","canonical_url":"https://ota.run/docs/examples/go-sdk#examples-go-sdk-3-example-contract","summary":"Go SDKs with explicit build and release flow · section 3","snippet":"Example contract This example treats the SDK as a product surface: the core loop stays short, and the release path is documented in the task notes. ota.yaml yaml version: 1 proj...","page_title":"Go SDKs with explicit build and release flow"},{"title":"Task notes","href":"/docs/examples/go-sdk#examples-go-sdk-4-task-notes","canonical_url":"https://ota.run/docs/examples/go-sdk#examples-go-sdk-4-task-notes","summary":"Go SDKs with explicit build and release flow · section 4","snippet":"Task notes Task notes stay close to the task they explain. Use `notes:` when a task needs short operator guidance, not long prose. Keep each note command-oriented and specific t...","page_title":"Go SDKs with explicit build and release flow"}],"in_primary_nav":true},{"slug":"examples-java","title":"Java repos with a Maven build gate","summary":"This example shows the shipped Java toolchain boundary: `toolchains.java` owns `java` and `javac`, while Maven stays explicitly under `tools`.","href":"/docs/examples/java","canonical_url":"https://ota.run/docs/examples/java","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/java#examples-java-1-typical-signals","canonical_url":"https://ota.run/docs/examples/java#examples-java-1-typical-signals","summary":"Java repos with a Maven build gate · section 1","snippet":"Typical signals Java 21 via SDKMAN Maven stays standalone build first, test second","page_title":"Java repos with a Maven build gate"},{"title":"Why it matters","href":"/docs/examples/java#examples-java-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/java#examples-java-2-why-it-matters","summary":"Java repos with a Maven build gate · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Java repos with a Maven build gate"},{"title":"Example contract","href":"/docs/examples/java#examples-java-3-example-contract","canonical_url":"https://ota.run/docs/examples/java#examples-java-3-example-contract","summary":"Java repos with a Maven build gate · section 3","snippet":"Example contract This example shows the shipped Java toolchain boundary: `toolchains.java` owns `java` and `javac`, while Maven stays explicitly under `tools`. ota.yaml yaml ver...","page_title":"Java repos with a Maven build gate"}],"in_primary_nav":true},{"slug":"examples-dotnet","title":".NET repos with restore, build, and test","summary":"This example keeps the .NET flow deterministic: restore dependencies, build the project, then run tests.","href":"/docs/examples/dotnet","canonical_url":"https://ota.run/docs/examples/dotnet","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/dotnet#examples-dotnet-1-typical-signals","canonical_url":"https://ota.run/docs/examples/dotnet#examples-dotnet-1-typical-signals","summary":".NET repos with restore, build, and test · section 1","snippet":"Typical signals .NET 8 restore before build build and test as explicit contract steps","page_title":".NET repos with restore, build, and test"},{"title":"Why it matters","href":"/docs/examples/dotnet#examples-dotnet-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/dotnet#examples-dotnet-2-why-it-matters","summary":".NET repos with restore, build, and test · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":".NET repos with restore, build, and test"},{"title":"Example contract","href":"/docs/examples/dotnet#examples-dotnet-3-example-contract","canonical_url":"https://ota.run/docs/examples/dotnet#examples-dotnet-3-example-contract","summary":".NET repos with restore, build, and test · section 3","snippet":"Example contract This example keeps the .NET flow deterministic: restore dependencies, build the project, then run tests. ota.yaml yaml version: 1 project: name: basic-dotnet de...","page_title":".NET repos with restore, build, and test"}],"in_primary_nav":true},{"slug":"examples-rust","title":"Rust repos with a Rustup-backed toolchain","summary":"This example is the boring, reliable Rust path with the shipped toolchain model: declare one Rustup-backed toolchain, fetch once, then run formatter, build, and tests through that owner.","href":"/docs/examples/rust","canonical_url":"https://ota.run/docs/examples/rust","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/rust#examples-rust-1-typical-signals","canonical_url":"https://ota.run/docs/examples/rust#examples-rust-1-typical-signals","summary":"Rust repos with a Rustup-backed toolchain · section 1","snippet":"Typical signals toolchains.rust owns the managed Rust ecosystem cargo fetch before formatter, build, and test no duplicate runtimes.rust or tools.cargo drift","page_title":"Rust repos with a Rustup-backed toolchain"},{"title":"Why it matters","href":"/docs/examples/rust#examples-rust-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/rust#examples-rust-2-why-it-matters","summary":"Rust repos with a Rustup-backed toolchain · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Rust repos with a Rustup-backed toolchain"},{"title":"Example contract","href":"/docs/examples/rust#examples-rust-3-example-contract","canonical_url":"https://ota.run/docs/examples/rust#examples-rust-3-example-contract","summary":"Rust repos with a Rustup-backed toolchain · section 3","snippet":"Example contract This example is the boring, reliable Rust path with the shipped toolchain model: declare one Rustup-backed toolchain, fetch once, then run formatter, build, and...","page_title":"Rust repos with a Rustup-backed toolchain"}],"in_primary_nav":true},{"slug":"examples-script","title":"Script-driven repos with a real contract","summary":"This example shows that a repo can be mostly scripts and still have a strict readiness contract.","href":"/docs/examples/script","canonical_url":"https://ota.run/docs/examples/script","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/script#examples-script-1-typical-signals","canonical_url":"https://ota.run/docs/examples/script#examples-script-1-typical-signals","summary":"Script-driven repos with a real contract · section 1","snippet":"Typical signals inline scripts write generated state tests confirm the generated state exists the repo still has a deterministic setup path","page_title":"Script-driven repos with a real contract"},{"title":"Why it matters","href":"/docs/examples/script#examples-script-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/script#examples-script-2-why-it-matters","summary":"Script-driven repos with a real contract · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Script-driven repos with a real contract"},{"title":"Example contract","href":"/docs/examples/script#examples-script-3-example-contract","canonical_url":"https://ota.run/docs/examples/script#examples-script-3-example-contract","summary":"Script-driven repos with a real contract · section 3","snippet":"Example contract This example shows that a repo can be mostly scripts and still have a strict readiness contract. ota.yaml yaml version: 1 project: name: ota-script-example task...","page_title":"Script-driven repos with a real contract"}],"in_primary_nav":true},{"slug":"examples-services","title":"Service repos with explicit readiness","summary":"A service contract that keeps healthchecks, setup, and readiness visible.","href":"/docs/examples/services","canonical_url":"https://ota.run/docs/examples/services","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/services#examples-services-1-typical-signals","canonical_url":"https://ota.run/docs/examples/services#examples-services-1-typical-signals","summary":"Service repos with explicit readiness · section 1","snippet":"Typical signals service startup and healthchecks setup tasks for dependencies CI that validates the contract before deployment clear writable and protected paths","page_title":"Service repos with explicit readiness"},{"title":"Example contract","href":"/docs/examples/services#examples-services-2-example-contract","canonical_url":"https://ota.run/docs/examples/services#examples-services-2-example-contract","summary":"Service repos with explicit readiness · section 2","snippet":"Example contract ota.yaml yaml project: name: platform-service description: Service repo with readiness checks tasks: setup: internal: true run: make setup check: run: make chec...","page_title":"Service repos with explicit readiness"}],"in_primary_nav":true},{"slug":"examples-topology-compose-postgres","title":"Container app with Compose Postgres","summary":"Use this when the app should run in a container context but service orchestration should stay on the host control plane.","href":"/docs/examples/topology/compose-postgres","canonical_url":"https://ota.run/docs/examples/topology/compose-postgres","category":"Topology examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-1-typical-signals","canonical_url":"https://ota.run/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-1-typical-signals","summary":"Container app with Compose Postgres · section 1","snippet":"Typical signals host control plane for Compose container workload context for app tasks Postgres reached as `postgres:5432` from the workload execution contexts, typed compose p...","page_title":"Container app with Compose Postgres"},{"title":"Why it matters","href":"/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-2-why-it-matters","summary":"Container app with Compose Postgres · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Container app with Compose Postgres"},{"title":"Example contract","href":"/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-3-example-contract","canonical_url":"https://ota.run/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-3-example-contract","summary":"Container app with Compose Postgres · section 3","snippet":"Example contract Use this when the app should run in a container context but service orchestration should stay on the host control plane. This example uses the shipped execution...","page_title":"Container app with Compose Postgres"},{"title":"Task notes","href":"/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-4-task-notes","canonical_url":"https://ota.run/docs/examples/topology/compose-postgres#examples-topology-compose-postgres-4-task-notes","summary":"Container app with Compose Postgres · section 4","snippet":"Task notes Why this matters: the app does not need Docker inside the app image. The host controls Compose, the workload joins the network, and `db:integration` can ask for `post...","page_title":"Container app with Compose Postgres"}],"in_primary_nav":true},{"slug":"examples-topology-host-postgres","title":"Container app with host Postgres","summary":"Use this when the workload should stay in a container context but the database is owned by the host machine instead of Compose.","href":"/docs/examples/topology/host-postgres","canonical_url":"https://ota.run/docs/examples/topology/host-postgres","category":"Topology examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/topology/host-postgres#examples-topology-host-postgres-1-typical-signals","canonical_url":"https://ota.run/docs/examples/topology/host-postgres#examples-topology-host-postgres-1-typical-signals","summary":"Container app with host Postgres · section 1","snippet":"Typical signals host-managed database typed host service manager containerized workload explicit endpoint projection instead of guessed `localhost` execution contexts, endpoint ...","page_title":"Container app with host Postgres"},{"title":"Why it matters","href":"/docs/examples/topology/host-postgres#examples-topology-host-postgres-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/topology/host-postgres#examples-topology-host-postgres-2-why-it-matters","summary":"Container app with host Postgres · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Container app with host Postgres"},{"title":"Example contract","href":"/docs/examples/topology/host-postgres#examples-topology-host-postgres-3-example-contract","canonical_url":"https://ota.run/docs/examples/topology/host-postgres#examples-topology-host-postgres-3-example-contract","summary":"Container app with host Postgres · section 3","snippet":"Example contract Use this when the workload should stay in a container context but the database is owned by the host machine instead of Compose. This example uses the shipped ex...","page_title":"Container app with host Postgres"},{"title":"Task notes","href":"/docs/examples/topology/host-postgres#examples-topology-host-postgres-4-task-notes","canonical_url":"https://ota.run/docs/examples/topology/host-postgres#examples-topology-host-postgres-4-task-notes","summary":"Container app with host Postgres · section 4","snippet":"Task notes Why this matters: `localhost` stops lying. The host and app contexts each get their own truthful endpoint. What it fixes: readiness and execution no longer have to gu...","page_title":"Container app with host Postgres"}],"in_primary_nav":true},{"slug":"examples-mixed-node-python","title":"Mixed Node and Python repos without ownership drift","summary":"This example shows a mixed-stack repo where the contract needs to protect both runtimes without hiding either one.","href":"/docs/examples/mixed/node-python","canonical_url":"https://ota.run/docs/examples/mixed/node-python","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/mixed/node-python#examples-mixed-node-python-1-typical-signals","canonical_url":"https://ota.run/docs/examples/mixed/node-python#examples-mixed-node-python-1-typical-signals","summary":"Mixed Node and Python repos without ownership drift · section 1","snippet":"Typical signals Node frontend and Python service shared setup with explicit env provenance separate verification for the backend path","page_title":"Mixed Node and Python repos without ownership drift"},{"title":"Why it matters","href":"/docs/examples/mixed/node-python#examples-mixed-node-python-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/mixed/node-python#examples-mixed-node-python-2-why-it-matters","summary":"Mixed Node and Python repos without ownership drift · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Mixed Node and Python repos without ownership drift"},{"title":"Example contract","href":"/docs/examples/mixed/node-python#examples-mixed-node-python-3-example-contract","canonical_url":"https://ota.run/docs/examples/mixed/node-python#examples-mixed-node-python-3-example-contract","summary":"Mixed Node and Python repos without ownership drift · section 3","snippet":"Example contract This example shows a mixed-stack repo where the contract needs to protect both runtimes without hiding either one. ota.yaml yaml version: 1 project: name: mixed...","page_title":"Mixed Node and Python repos without ownership drift"}],"in_primary_nav":true},{"slug":"examples-fullstack-node-go","title":"Fullstack Node and Go repos with a split service path","summary":"This example keeps the frontend and backend visible in the contract so a change in one path cannot silently hide the other.","href":"/docs/examples/fullstack/node-go","canonical_url":"https://ota.run/docs/examples/fullstack/node-go","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/fullstack/node-go#examples-fullstack-node-go-1-typical-signals","canonical_url":"https://ota.run/docs/examples/fullstack/node-go#examples-fullstack-node-go-1-typical-signals","summary":"Fullstack Node and Go repos with a split service path · section 1","snippet":"Typical signals Node app plus Go service build and service-test remain separate runtime checks keep both sides honest","page_title":"Fullstack Node and Go repos with a split service path"},{"title":"Why it matters","href":"/docs/examples/fullstack/node-go#examples-fullstack-node-go-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/fullstack/node-go#examples-fullstack-node-go-2-why-it-matters","summary":"Fullstack Node and Go repos with a split service path · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Fullstack Node and Go repos with a split service path"},{"title":"Example contract","href":"/docs/examples/fullstack/node-go#examples-fullstack-node-go-3-example-contract","canonical_url":"https://ota.run/docs/examples/fullstack/node-go#examples-fullstack-node-go-3-example-contract","summary":"Fullstack Node and Go repos with a split service path · section 3","snippet":"Example contract This example keeps the frontend and backend visible in the contract so a change in one path cannot silently hide the other. ota.yaml yaml version: 1 project: na...","page_title":"Fullstack Node and Go repos with a split service path"}],"in_primary_nav":true},{"slug":"examples-full-contract","title":"Full contracts for complex repos","summary":"This example shows the broadest repo-local contract shape in one place so teams can see how the pieces fit together.","href":"/docs/examples/full-contract","canonical_url":"https://ota.run/docs/examples/full-contract","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/full-contract#examples-full-contract-1-typical-signals","canonical_url":"https://ota.run/docs/examples/full-contract#examples-full-contract-1-typical-signals","summary":"Full contracts for complex repos · section 1","snippet":"Typical signals execution preferences are explicit env rules are part of the contract checks, agent guidance, and metadata are all visible","page_title":"Full contracts for complex repos"},{"title":"Why it matters","href":"/docs/examples/full-contract#examples-full-contract-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/full-contract#examples-full-contract-2-why-it-matters","summary":"Full contracts for complex repos · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Full contracts for complex repos"},{"title":"Example contract","href":"/docs/examples/full-contract#examples-full-contract-3-example-contract","canonical_url":"https://ota.run/docs/examples/full-contract#examples-full-contract-3-example-contract","summary":"Full contracts for complex repos · section 3","snippet":"Example contract This example shows the broadest repo-local contract shape in one place so teams can see how the pieces fit together. ota.yaml yaml version: 1 project: name: ful...","page_title":"Full contracts for complex repos"}],"in_primary_nav":true},{"slug":"examples-provisioning-policy","title":"Policy and provisioning","summary":"Use this when the repo should declare what it needs and the organization should decide where those installs come from.","href":"/docs/examples/provisioning-policy","canonical_url":"https://ota.run/docs/examples/provisioning-policy","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/provisioning-policy#examples-provisioning-policy-1-typical-signals","canonical_url":"https://ota.run/docs/examples/provisioning-policy#examples-provisioning-policy-1-typical-signals","summary":"Policy and provisioning · section 1","snippet":"Typical signals repo declares runtime and tool versions org policy selects the approved source doctor can explain the selected backend request","page_title":"Policy and provisioning"},{"title":"Why it matters","href":"/docs/examples/provisioning-policy#examples-provisioning-policy-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/provisioning-policy#examples-provisioning-policy-2-why-it-matters","summary":"Policy and provisioning · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Policy and provisioning"},{"title":"Example contract","href":"/docs/examples/provisioning-policy#examples-provisioning-policy-3-example-contract","canonical_url":"https://ota.run/docs/examples/provisioning-policy#examples-provisioning-policy-3-example-contract","summary":"Policy and provisioning · section 3","snippet":"Example contract Use this when the repo should declare what it needs and the organization should decide where those installs come from. The contract stays honest about runtime a...","page_title":"Policy and provisioning"},{"title":"Task notes","href":"/docs/examples/provisioning-policy#examples-provisioning-policy-4-task-notes","canonical_url":"https://ota.run/docs/examples/provisioning-policy#examples-provisioning-policy-4-task-notes","summary":"Policy and provisioning · section 4","snippet":"Task notes Takeaways: the repo says what it needs, the org policy says where ota may get it, and doctor can explain the selected source back to you. Use this pattern when you wa...","page_title":"Policy and provisioning"}],"in_primary_nav":true},{"slug":"examples-container-provisioning","title":"Container provisioning","summary":"Use this when you want ota to make the container ready instead of asking every developer machine to carry the setup cost.","href":"/docs/examples/container-provisioning","canonical_url":"https://ota.run/docs/examples/container-provisioning","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/container-provisioning#examples-container-provisioning-1-typical-signals","canonical_url":"https://ota.run/docs/examples/container-provisioning#examples-container-provisioning-1-typical-signals","summary":"Container provisioning · section 1","snippet":"Typical signals contract declares a missing tool and a container backend org policy approves apt as the provisioning source persistent container keeps the install available for ...","page_title":"Container provisioning"},{"title":"Why it matters","href":"/docs/examples/container-provisioning#examples-container-provisioning-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/container-provisioning#examples-container-provisioning-2-why-it-matters","summary":"Container provisioning · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Container provisioning"},{"title":"Example contract","href":"/docs/examples/container-provisioning#examples-container-provisioning-3-example-contract","canonical_url":"https://ota.run/docs/examples/container-provisioning#examples-container-provisioning-3-example-contract","summary":"Container provisioning · section 3","snippet":"Example contract Use this when you want ota to make the container ready instead of asking every developer machine to carry the setup cost. The example mirrors the real fixture: ...","page_title":"Container provisioning"},{"title":"Task notes","href":"/docs/examples/container-provisioning#examples-container-provisioning-4-task-notes","canonical_url":"https://ota.run/docs/examples/container-provisioning#examples-container-provisioning-4-task-notes","summary":"Container provisioning · section 4","snippet":"Task notes What you get: new contributors can run the repo without installing the missing tool first. The approved source stays visible in policy instead of hidden in a script. ...","page_title":"Container provisioning"}],"in_primary_nav":true},{"slug":"examples-workspace-basic","title":"Multi-repo basics","summary":"Use this shape when a workspace needs to coordinate several repos without flattening their contracts.","href":"/docs/examples/workspace/basic","canonical_url":"https://ota.run/docs/examples/workspace/basic","category":"Workspace examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/workspace/basic#examples-workspace-basic-1-typical-signals","canonical_url":"https://ota.run/docs/examples/workspace/basic#examples-workspace-basic-1-typical-signals","summary":"Multi-repo basics · section 1","snippet":"Typical signals workspace contract with named members one member depends on another each repo keeps its own ota.yaml","page_title":"Multi-repo basics"},{"title":"Why it matters","href":"/docs/examples/workspace/basic#examples-workspace-basic-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/workspace/basic#examples-workspace-basic-2-why-it-matters","summary":"Multi-repo basics · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Multi-repo basics"},{"title":"Example contract","href":"/docs/examples/workspace/basic#examples-workspace-basic-3-example-contract","canonical_url":"https://ota.run/docs/examples/workspace/basic#examples-workspace-basic-3-example-contract","summary":"Multi-repo basics · section 3","snippet":"Example contract Use this shape when a workspace needs to coordinate several repos without flattening their contracts. ota.workspace.yaml yaml version: 1 workspace: name: ota-ex...","page_title":"Multi-repo basics"}],"in_primary_nav":true},{"slug":"examples-workspace-acquire","title":"Acquire from Git","summary":"Use this when a workspace needs to bring missing repos onto disk before any bootstrap, setup, or task execution can happen.","href":"/docs/examples/workspace/acquire","canonical_url":"https://ota.run/docs/examples/workspace/acquire","category":"Workspace examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/workspace/acquire#examples-workspace-acquire-1-typical-signals","canonical_url":"https://ota.run/docs/examples/workspace/acquire#examples-workspace-acquire-1-typical-signals","summary":"Acquire from Git · section 1","snippet":"Typical signals workspace declares a git base repos are acquired before bootstrap member dependencies stay explicit one workspace can fetch several repos consistently","page_title":"Acquire from Git"},{"title":"Why it matters","href":"/docs/examples/workspace/acquire#examples-workspace-acquire-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/workspace/acquire#examples-workspace-acquire-2-why-it-matters","summary":"Acquire from Git · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Acquire from Git"},{"title":"Example contract","href":"/docs/examples/workspace/acquire#examples-workspace-acquire-3-example-contract","canonical_url":"https://ota.run/docs/examples/workspace/acquire#examples-workspace-acquire-3-example-contract","summary":"Acquire from Git · section 3","snippet":"Example contract Use this when a workspace needs to bring missing repos onto disk before any bootstrap, setup, or task execution can happen. ota turns acquisition into part of t...","page_title":"Acquire from Git"},{"title":"Task notes","href":"/docs/examples/workspace/acquire#examples-workspace-acquire-4-task-notes","canonical_url":"https://ota.run/docs/examples/workspace/acquire#examples-workspace-acquire-4-task-notes","summary":"Acquire from Git · section 4","snippet":"Task notes Why this matters: it removes the manual clone step from onboarding, so a workspace can become runnable from one contract instead of a pile of README instructions. Whe...","page_title":"Acquire from Git"}],"in_primary_nav":true},{"slug":"workflows","title":"Workflows","summary":"A workflow is a named repo path that answers: ready for what?","href":"/docs/reference/workflows","canonical_url":"https://ota.run/docs/reference/workflows","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What a workflow is","href":"/docs/reference/workflows#workflows-1-what-a-workflow-is","canonical_url":"https://ota.run/docs/reference/workflows#workflows-1-what-a-workflow-is","summary":"Workflows · section 1","snippet":"What a workflow is A workflow is a named repo path that answers: ready for what? It ties existing contract pieces together so Ota, humans, CI, and agents can choose one operatio...","page_title":"Workflows"},{"title":"What it is not","href":"/docs/reference/workflows#workflows-2-what-it-is-not","canonical_url":"https://ota.run/docs/reference/workflows#workflows-2-what-it-is-not","summary":"Workflows · section 2","snippet":"What it is not A workflow is not a second task language. It does not replace tasks, checks, services, surfaces, or reusable probes. It selects and composes them into one named p...","page_title":"Workflows"},{"title":"Purpose","href":"/docs/reference/workflows#workflows-3-purpose","canonical_url":"https://ota.run/docs/reference/workflows#workflows-3-purpose","summary":"Workflows · section 3","snippet":"Purpose Use `workflows` when a repo needs to answer ready for what instead of exposing a loose pile of tasks. A workflow tells Ota how the repo is meant to become useful: which ...","page_title":"Workflows"},{"title":"Workflow versus depends_on","href":"/docs/reference/workflows#workflows-4-workflow-versus-depends-on","canonical_url":"https://ota.run/docs/reference/workflows#workflows-4-workflow-versus-depends-on","summary":"Workflows · section 4","snippet":"Workflow versus depends_on `depends_on` makes one task execute in the right order. A workflow gives a repo path a name, a host prepare phase, a setup phase, a run phase, readine...","page_title":"Workflows"},{"title":"When to add one","href":"/docs/reference/workflows#workflows-5-when-to-add-one","canonical_url":"https://ota.run/docs/reference/workflows#workflows-5-when-to-add-one","summary":"Workflows · section 5","snippet":"When to add one Use one when the repo has more than one valid development path. Use `workflows` when prepare, setup, and run are distinct and should remain explicit. Use `workfl...","page_title":"Workflows"},{"title":"Use case: one repo, multiple front doors","href":"/docs/reference/workflows#workflows-6-use-case-one-repo-multiple-front-doors","canonical_url":"https://ota.run/docs/reference/workflows#workflows-6-use-case-one-repo-multiple-front-doors","summary":"Workflows · section 6","snippet":"Use case: one repo, multiple front doors A real app repo can have a contributor path, an instant packaged-command path, and a Docker packaged-runtime path. Those paths should no...","page_title":"Workflows"},{"title":"When not to add one","href":"/docs/reference/workflows#workflows-7-when-not-to-add-one","canonical_url":"https://ota.run/docs/reference/workflows#workflows-7-when-not-to-add-one","summary":"Workflows · section 7","snippet":"When not to add one Skip `workflows` if the repo has one clear path and tasks already answer readiness and execution questions. Skip `workflows` if one workflow would just renam...","page_title":"Workflows"},{"title":"What it looks like","href":"/docs/reference/workflows#workflows-8-what-it-looks-like","canonical_url":"https://ota.run/docs/reference/workflows#workflows-8-what-it-looks-like","summary":"Workflows · section 8","snippet":"What it looks like `workflows.<name>.readiness` can reference named checks or reusable readiness probes. Use probes when the workflow should directly prove one transport-level r...","page_title":"Workflows"},{"title":"How commands use workflows","href":"/docs/reference/workflows#workflows-9-how-commands-use-workflows","canonical_url":"https://ota.run/docs/reference/workflows#workflows-9-how-commands-use-workflows","summary":"Workflows · section 9","snippet":"How commands use workflows `ota doctor`, `ota check`, `ota up`, and `ota execution plan` target the default workflow by default `--workflow <name>` selects another declared work...","page_title":"Workflows"},{"title":"Workflow setup/run precedence","href":"/docs/reference/workflows#workflows-10-workflow-setup-run-precedence","canonical_url":"https://ota.run/docs/reference/workflows#workflows-10-workflow-setup-run-precedence","summary":"Workflows · section 10","snippet":"Workflow setup/run precedence How `ota up` resolves prepare, setup, and run tasks for the selected workflow. `workflows.<name>.prepare.task` runs first when it exists and must s...","page_title":"Workflows"},{"title":"Default workflow vs agent hints","href":"/docs/reference/workflows#workflows-11-default-workflow-vs-agent-hints","canonical_url":"https://ota.run/docs/reference/workflows#workflows-11-default-workflow-vs-agent-hints","summary":"Workflows · section 11","snippet":"Default workflow vs agent hints The repo default workflow and the agent default task are related, but they are not the same thing. Use `workflows.default` for the human-facing c...","page_title":"Workflows"},{"title":"Design rule","href":"/docs/reference/workflows#workflows-12-design-rule","canonical_url":"https://ota.run/docs/reference/workflows#workflows-12-design-rule","summary":"Workflows · section 12","snippet":"Design rule Workflows should make the repo's operational truth more explicit. They should not become a second task language. Use workflows to compose tasks, checks, and services...","page_title":"Workflows"}],"in_primary_nav":true},{"slug":"toolchains-runtimes-tools","title":"Toolchains, Runtimes, and Tools","summary":"Use this page to decide whether a prerequisite belongs under a managed toolchain, a simple runtime, a standalone tool, or a native build bundle.","href":"/docs/reference/toolchains-runtimes-tools","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Purpose","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-1-purpose","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-1-purpose","summary":"Toolchains, Runtimes, and Tools · section 1","snippet":"Purpose Use this page to decide whether a prerequisite belongs under a managed toolchain, a simple runtime, a standalone tool, or a native build bundle. The shipped boundary is ...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Ownership rule","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-2-ownership-rule","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-2-ownership-rule","summary":"Toolchains, Runtimes, and Tools · section 2","snippet":"Ownership rule Each layer owns a different kind of truth. Pick the highest useful owner and do not repeat the same capability below it. `toolchains` own ecosystems through provi...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Command behavior","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-3-command-behavior","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-3-command-behavior","summary":"Toolchains, Runtimes, and Tools · section 3","snippet":"Command behavior `ota doctor` diagnoses selected toolchains and their provider-backed requirements, but it does not provision them; duplicate ownership fails as an invalid contr...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"When to use each layer","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-4-when-to-use-each-layer","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-4-when-to-use-each-layer","summary":"Toolchains, Runtimes, and Tools · section 4","snippet":"When to use each layer Toolchain A managed ecosystem environment such as Rust via rustup, Node via Corepack, or Java via SDKMAN. Use it when Ota should understand components, ta...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Before and after","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-5-before-and-after","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-5-before-and-after","summary":"Toolchains, Runtimes, and Tools · section 5","snippet":"Before and after Without toolchains, a repo often hides ecosystem provisioning inside shell setup. That works, but Ota cannot diagnose or plan it as contract truth. Before: prov...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Task requirement examples","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-6-task-requirement-examples","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-6-task-requirement-examples","summary":"Toolchains, Runtimes, and Tools · section 6","snippet":"Task requirement examples Task requirements should select the owner that actually applies to that selected path. Managed ecosystem yaml tasks: setup: requirements: toolchains: -...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Duplication boundaries","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-7-duplication-boundaries","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-7-duplication-boundaries","summary":"Toolchains, Runtimes, and Tools · section 7","snippet":"Duplication boundaries Toolchains are useful only if they reduce duplicate truth. Duplicate ownership is invalid contract drift, not an advisory. Reject `toolchains.rust` plus `...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Provider behavior","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-8-provider-behavior","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-8-provider-behavior","summary":"Toolchains, Runtimes, and Tools · section 8","snippet":"Provider behavior `provider` means Ota has an adapter for that ecosystem. It should diagnose and plan by default, then mutate only when fulfillment or policy allows it. `ota val...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Current and future examples","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-9-current-and-future-examples","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-9-current-and-future-examples","summary":"Toolchains, Runtimes, and Tools · section 9","snippet":"Current and future examples Rust via Rustup, Node via Corepack, and Java via SDKMAN are the shipped provider-backed toolchain contracts today. Rust currently owns the fuller pro...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"What this is not","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-10-what-this-is-not","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-10-what-this-is-not","summary":"Toolchains, Runtimes, and Tools · section 10","snippet":"What this is not not a second task language not a place for arbitrary setup commands not a replacement for services or launch sources not the right home for Docker itself not th...","page_title":"Toolchains, Runtimes, and Tools"},{"title":"Current shipped slice","href":"/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-11-current-shipped-slice","canonical_url":"https://ota.run/docs/reference/toolchains-runtimes-tools#toolchains-runtimes-tools-11-current-shipped-slice","summary":"Toolchains, Runtimes, and Tools · section 11","snippet":"Current shipped slice top-level `toolchains` and task-scoped `requirements.toolchains` are supported Rustup, Corepack, and SDKMAN are the shipped toolchain providers today `ota ...","page_title":"Toolchains, Runtimes, and Tools"}],"in_primary_nav":true},{"slug":"github-action","title":"GitHub Action","summary":"Use `ota-run/action@v1` when GitHub Actions should publish the GitHub-native view of ota instead of forcing you to wire JSON parsing and artifact upload by hand.","href":"/docs/reference/github-action","canonical_url":"https://ota.run/docs/reference/github-action","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Purpose","href":"/docs/reference/github-action#github-action-1-purpose","canonical_url":"https://ota.run/docs/reference/github-action#github-action-1-purpose","summary":"GitHub Action · section 1","snippet":"Purpose Use `ota-run/action@v1` when GitHub Actions should publish the GitHub-native view of ota instead of forcing you to wire JSON parsing and artifact upload by hand. The act...","page_title":"GitHub Action"},{"title":"Use when","href":"/docs/reference/github-action#github-action-2-use-when","canonical_url":"https://ota.run/docs/reference/github-action#github-action-2-use-when","summary":"GitHub Action · section 2","snippet":"Use when a pull request needs a trustworthy readiness summary in the GitHub UI the workflow should fail only on newly introduced blockers instead of all existing debt the repo w...","page_title":"GitHub Action"},{"title":"Canonical renderer reuse","href":"/docs/reference/github-action#github-action-3-canonical-renderer-reuse","canonical_url":"https://ota.run/docs/reference/github-action#github-action-3-canonical-renderer-reuse","summary":"GitHub Action · section 3","snippet":"Canonical renderer reuse The GitHub wrapper should not invent its own summary phrasing. Use the same ota renderers everywhere so local CLI output, CI summaries, annotations, and...","page_title":"GitHub Action"},{"title":"Pair with setup","href":"/docs/reference/github-action#github-action-4-pair-with-setup","canonical_url":"https://ota.run/docs/reference/github-action#github-action-4-pair-with-setup","summary":"GitHub Action · section 4","snippet":"Pair with setup use `ota-run/setup@v1` when later steps in the same job need direct `ota` commands such as `ota run setup`, `ota run ci`, or `ota run deploy:cloudflare` keep `ot...","page_title":"GitHub Action"},{"title":"Quick start","href":"/docs/reference/github-action#github-action-5-quick-start","canonical_url":"https://ota.run/docs/reference/github-action#github-action-5-quick-start","summary":"GitHub Action · section 5","snippet":"Quick start Workflow yaml name: readiness on: pull_request: push: permissions: actions: read contents: read pull-requests: write jobs: readiness: runs-on: ubuntu-latest steps: -...","page_title":"GitHub Action"},{"title":"Pinned artifact name","href":"/docs/reference/github-action#github-action-6-pinned-artifact-name","canonical_url":"https://ota.run/docs/reference/github-action#github-action-6-pinned-artifact-name","summary":"GitHub Action · section 6","snippet":"Pinned artifact name The canonical pull-request gate already restores the latest successful artifact named by `artifact-name` and fails only on newly introduced blockers. Set `a...","page_title":"GitHub Action"},{"title":"Command choice","href":"/docs/reference/github-action#github-action-7-command-choice","canonical_url":"https://ota.run/docs/reference/github-action#github-action-7-command-choice","summary":"GitHub Action · section 7","snippet":"Command choice use `receipt` when you want an archive-friendly, read-only repo receipt artifact use `doctor` when you want the richer readiness verdict and primary-blocker surfa...","page_title":"GitHub Action"},{"title":"Install behavior","href":"/docs/reference/github-action#github-action-8-install-behavior","canonical_url":"https://ota.run/docs/reference/github-action#github-action-8-install-behavior","summary":"GitHub Action · section 8","snippet":"Install behavior `install: always` is the default and installs ota for the selected version on every run `install: never` fails closed unless ota is already available on the run...","page_title":"GitHub Action"},{"title":"Inputs","href":"/docs/reference/github-action#github-action-9-inputs","canonical_url":"https://ota.run/docs/reference/github-action#github-action-9-inputs","summary":"GitHub Action · section 9","snippet":"Inputs `command` chooses the ota surface to run and supports `receipt` or `doctor`; default: `receipt`. `path` passes the repo or contract target to ota; default: `.`. `baseline...","page_title":"GitHub Action"},{"title":"Outputs","href":"/docs/reference/github-action#github-action-10-outputs","canonical_url":"https://ota.run/docs/reference/github-action#github-action-10-outputs","summary":"GitHub Action · section 10","snippet":"Outputs `ok` reports whether ota returned an ok result. `status` exposes the derived action status: `ready`, `risky`, or `blocked`. `output-path` returns the written path to the...","page_title":"GitHub Action"},{"title":"Job boundary","href":"/docs/reference/github-action#github-action-11-job-boundary","canonical_url":"https://ota.run/docs/reference/github-action#github-action-11-job-boundary","summary":"GitHub Action · section 11","snippet":"Job boundary when the action installs ota, the install directory is added to `PATH` for later steps in the same job that does not cross into a different job if another job needs...","page_title":"GitHub Action"},{"title":"What it does not replace","href":"/docs/reference/github-action#github-action-12-what-it-does-not-replace","canonical_url":"https://ota.run/docs/reference/github-action#github-action-12-what-it-does-not-replace","summary":"GitHub Action · section 12","snippet":"What it does not replace the action is not a replacement for `ota up` or `ota run` use the action for GitHub-native reporting around ota use direct ota commands when the workflo...","page_title":"GitHub Action"},{"title":"Source repo","href":"/docs/reference/github-action#github-action-13-source-repo","canonical_url":"https://ota.run/docs/reference/github-action#github-action-13-source-repo","summary":"GitHub Action · section 13","snippet":"Source repo The action source, release tags, and copyable workflow examples live in GitHub. ota-run/action The official GitHub Action for ota. Publish readiness summaries, annot...","page_title":"GitHub Action"}],"in_primary_nav":true},{"slug":"github-setup","title":"GitHub Setup Action","summary":"Use `ota-run/setup@v1` when a GitHub Actions job needs ota on `PATH` for later direct commands such as `ota run setup`, `ota run ci`, or `ota run deploy:cloudflare`.","href":"/docs/reference/github-setup","canonical_url":"https://ota.run/docs/reference/github-setup","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Purpose","href":"/docs/reference/github-setup#github-setup-1-purpose","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-1-purpose","summary":"GitHub Setup Action · section 1","snippet":"Purpose Use `ota-run/setup@v1` when a GitHub Actions job needs ota on `PATH` for later direct commands such as `ota run setup`, `ota run ci`, or `ota run deploy:cloudflare`. Thi...","page_title":"GitHub Setup Action"},{"title":"Use when","href":"/docs/reference/github-setup#github-setup-2-use-when","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-2-use-when","summary":"GitHub Setup Action · section 2","snippet":"Use when a later workflow step must invoke `ota` directly you want to replace hand-written install snippets such as `curl ... install.sh | sh` a release or deploy job needs ota ...","page_title":"GitHub Setup Action"},{"title":"Quick start","href":"/docs/reference/github-setup#github-setup-3-quick-start","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-3-quick-start","summary":"GitHub Setup Action · section 3","snippet":"Quick start Workflow yaml steps: - uses: actions/checkout@v5 - name: Setup ota uses: ota-run/setup@v1 with: ota-version: 1.5.0 - name: Validate contract run: ota validate - name...","page_title":"GitHub Setup Action"},{"title":"Inputs","href":"/docs/reference/github-setup#github-setup-4-inputs","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-4-inputs","summary":"GitHub Setup Action · section 4","snippet":"Inputs `install` controls installation behavior and supports `always` or `never`; default: `always`. `ota-version` pins the installer to a specific ota release such as `v1.5.0` ...","page_title":"GitHub Setup Action"},{"title":"Outputs","href":"/docs/reference/github-setup#github-setup-5-outputs","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-5-outputs","summary":"GitHub Setup Action · section 5","snippet":"Outputs `ota-bin` returns the resolved ota binary path selected by the action. `ota-version` returns the resolved ota version reported by that binary. `installed` reports whethe...","page_title":"GitHub Setup Action"},{"title":"Install behavior","href":"/docs/reference/github-setup#github-setup-6-install-behavior","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-6-install-behavior","summary":"GitHub Setup Action · section 6","snippet":"Install behavior `install: always` forces installer use before selecting the binary. `install: never` requires ota to already exist and fails closed otherwise. self-hosted runne...","page_title":"GitHub Setup Action"},{"title":"Job boundary","href":"/docs/reference/github-setup#github-setup-7-job-boundary","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-7-job-boundary","summary":"GitHub Setup Action · section 7","snippet":"Job boundary the action adds ota to `PATH` for later steps in the same job that does not carry into a different job if another job also needs direct `ota` commands, run `ota-run...","page_title":"GitHub Setup Action"},{"title":"Relationship to ota-run/action","href":"/docs/reference/github-setup#github-setup-8-relationship-to-ota-run-action","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-8-relationship-to-ota-run-action","summary":"GitHub Setup Action · section 8","snippet":"Relationship to ota-run/action use `ota-run/action@v1` for readiness summaries, annotations, pull-request comments, and receipt artifacts use `ota-run/setup@v1` when you need ot...","page_title":"GitHub Setup Action"},{"title":"Source repo","href":"/docs/reference/github-setup#github-setup-9-source-repo","canonical_url":"https://ota.run/docs/reference/github-setup#github-setup-9-source-repo","summary":"GitHub Setup Action · section 9","snippet":"Source repo The setup action source, release tags, and workflow examples live in GitHub. ota-run/setup The official GitHub Action for installing ota. Put ota on PATH for later w...","page_title":"GitHub Setup Action"}],"in_primary_nav":true},{"slug":"governance","title":"Open Core and Governance","summary":"Use this page when you want the project boundary in plain language before you invest in the CLI, docs, or ecosystem.","href":"/docs/reference/governance","canonical_url":"https://ota.run/docs/reference/governance","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/governance#governance-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/governance#governance-1-when-to-use-this-page","summary":"Open Core and Governance · section 1","snippet":"When to use this page Use this page when you want the project boundary in plain language before you invest in the CLI, docs, or ecosystem. This is the page that explains what is...","page_title":"Open Core and Governance"},{"title":"What is open","href":"/docs/reference/governance#governance-2-what-is-open","canonical_url":"https://ota.run/docs/reference/governance#governance-2-what-is-open","summary":"Open Core and Governance · section 2","snippet":"What is open the CLI the repo and workspace contracts the JSON output and public docs examples, specs, and the contract-first readiness model","page_title":"Open Core and Governance"},{"title":"Governance model","href":"/docs/reference/governance#governance-3-governance-model","canonical_url":"https://ota.run/docs/reference/governance#governance-3-governance-model","summary":"Open Core and Governance · section 3","snippet":"Governance model ota is maintainer-led open infrastructure the core is open source under Apache 2.0, but roadmap and release direction are stewarded by Ota schema, JSON, and com...","page_title":"Open Core and Governance"},{"title":"Contribution policy","href":"/docs/reference/governance#governance-4-contribution-policy","canonical_url":"https://ota.run/docs/reference/governance#governance-4-contribution-policy","summary":"Open Core and Governance · section 4","snippet":"Contribution policy Participation is welcome, but not every contribution path is open right now. welcome: bug reports with concrete reproduction steps welcome: feature requests ...","page_title":"Open Core and Governance"},{"title":"Why it is run this way","href":"/docs/reference/governance#governance-5-why-it-is-run-this-way","canonical_url":"https://ota.run/docs/reference/governance#governance-5-why-it-is-run-this-way","summary":"Open Core and Governance · section 5","snippet":"Why it is run this way contract and JSON stability matter diagnosis must stay honest onboarding flows must stay deterministic policy and enterprise boundaries must stay explicit...","page_title":"Open Core and Governance"},{"title":"Enterprise boundary","href":"/docs/reference/governance#governance-6-enterprise-boundary","canonical_url":"https://ota.run/docs/reference/governance#governance-6-enterprise-boundary","summary":"Open Core and Governance · section 6","snippet":"Enterprise boundary enterprise work is planned as a layer around the open core, not as a different contract truth the open core remains the public CLI, repo and workspace schema...","page_title":"Open Core and Governance"},{"title":"What to do next","href":"/docs/reference/governance#governance-7-what-to-do-next","canonical_url":"https://ota.run/docs/reference/governance#governance-7-what-to-do-next","summary":"Open Core and Governance · section 7","snippet":"What to do next read the docs and start with `ota doctor` if you want to evaluate the product open an issue when you hit a bug, docs gap, or real-repo edge case use the public J...","page_title":"Open Core and Governance"}],"in_primary_nav":true},{"slug":"doctor-finding-contract","title":"Doctor Findings","summary":"A finding is the smallest stable unit in `doctor`, `workspace doctor`, and `explain`.","href":"/docs/reference/doctor-finding-contract","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"What a finding is","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-1-what-a-finding-is","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-1-what-a-finding-is","summary":"Doctor Findings · section 1","snippet":"What a finding is A finding is the smallest stable unit in `doctor`, `workspace doctor`, and `explain`. Use it when you need one issue model that still works for CI, editors, ag...","page_title":"Doctor Findings"},{"title":"Field descriptions","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-2-field-descriptions","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-2-field-descriptions","summary":"Doctor Findings · section 2","snippet":"Field descriptions `severity` tells you whether the finding blocks readiness: `error`, `warn`, or `info` `code` is the stable machine-readable identifier for the condition, such...","page_title":"Doctor Findings"},{"title":"How to read findings","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-3-how-to-read-findings","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-3-how-to-read-findings","summary":"Doctor Findings · section 3","snippet":"How to read findings Read `severity` first to know whether the finding blocks readiness Then read `summary` to understand the issue in one line Then read `why` to understand the...","page_title":"Doctor Findings"},{"title":"Why it matters","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-4-why-it-matters","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-4-why-it-matters","summary":"Doctor Findings · section 4","snippet":"Why it matters CI can gate on stable identifiers instead of brittle wording agents can ask for the next action instead of guessing support teams can classify the issue as contra...","page_title":"Doctor Findings"},{"title":"Example findings","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-5-example-findings","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-5-example-findings","summary":"Doctor Findings · section 5","snippet":"Example findings Blocking contract issue text ERROR No tasks defined Why: The repo contract is not yet runnable because ota cannot discover a safe task entrypoint. Next: add a t...","page_title":"Doctor Findings"},{"title":"Where it shows up","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-6-where-it-shows-up","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-6-where-it-shows-up","summary":"Doctor Findings · section 6","snippet":"Where it shows up `ota doctor` `ota workspace doctor` `ota explain` policy-aware findings CI annotations derived from doctor JSON","page_title":"Doctor Findings"},{"title":"What a finding is not","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-7-what-a-finding-is-not","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-7-what-a-finding-is-not","summary":"Doctor Findings · section 7","snippet":"What a finding is not not a raw log line not a free-form error blob not a hidden policy engine response not a replacement for the contract or the execution receipt","page_title":"Doctor Findings"},{"title":"How CI should use it","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-8-how-ci-should-use-it","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-8-how-ci-should-use-it","summary":"Doctor Findings · section 8","snippet":"How CI should use it gate on `severity: error` and stable `code` values render `summary` as the human headline render `why` as the explanation render `next` as the suggested fix...","page_title":"Doctor Findings"},{"title":"Use cases","href":"/docs/reference/doctor-finding-contract#doctor-finding-contract-9-use-cases","canonical_url":"https://ota.run/docs/reference/doctor-finding-contract#doctor-finding-contract-9-use-cases","summary":"Doctor Findings · section 9","snippet":"Use cases fastest fix path for a blocked repo stable machine identifiers for CI contract, service, policy, or host classification for agents workspace findings without reading r...","page_title":"Doctor Findings"}],"in_primary_nav":true},{"slug":"audit-and-provenance","title":"Audit and Provenance","summary":"If ota says a repo is ready, users should be able to answer what was declared, what was inferred, what came from policy, and what changed later.","href":"/docs/reference/audit-and-provenance","canonical_url":"https://ota.run/docs/reference/audit-and-provenance","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Why this matters","href":"/docs/reference/audit-and-provenance#audit-and-provenance-1-why-this-matters","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-1-why-this-matters","summary":"Audit and Provenance · section 1","snippet":"Why this matters If ota says a repo is ready, users should be able to answer what was declared, what was inferred, what came from policy, and what changed later.","page_title":"Audit and Provenance"},{"title":"Provenance categories","href":"/docs/reference/audit-and-provenance#audit-and-provenance-2-provenance-categories","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-2-provenance-categories","summary":"Audit and Provenance · section 2","snippet":"Provenance categories `repo-declared`: the repo itself declared this value in `ota.yaml` or related repo-local config. `policy-derived`: the value came from org policy, not from...","page_title":"Audit and Provenance"},{"title":"Detect ownership","href":"/docs/reference/audit-and-provenance#audit-and-provenance-3-detect-ownership","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-3-detect-ownership","summary":"Audit and Provenance · section 3","snippet":"Detect ownership detect comparison now exposes `owner_kind` so automation can distinguish `detected`, `manual`, and `merged` entries directly `merged` means ota previously wrote...","page_title":"Audit and Provenance"},{"title":"Where it shows up","href":"/docs/reference/audit-and-provenance#audit-and-provenance-4-where-it-shows-up","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-4-where-it-shows-up","summary":"Audit and Provenance · section 4","snippet":"Where it shows up `ota init` `ota workspace init` `ota workspace detect` `ota detect` `ota doctor` `ota explain` execution receipts policy-aware findings","page_title":"Audit and Provenance"},{"title":"Example finding","href":"/docs/reference/audit-and-provenance#audit-and-provenance-5-example-finding","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-5-example-finding","summary":"Audit and Provenance · section 5","snippet":"Example finding Finding text ERROR Missing required task Why: The repo contract declares agent-safe execution but does not define a runnable task. Next: add a task or adjust the...","page_title":"Audit and Provenance"},{"title":"Use cases","href":"/docs/reference/audit-and-provenance#audit-and-provenance-6-use-cases","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-6-use-cases","summary":"Audit and Provenance · section 6","snippet":"Use cases understand why `doctor` reported a blocker see whether policy or repo data produced the result give agents the value source before suggesting a change keep execution r...","page_title":"Audit and Provenance"},{"title":"What this is not","href":"/docs/reference/audit-and-provenance#audit-and-provenance-7-what-this-is-not","canonical_url":"https://ota.run/docs/reference/audit-and-provenance#audit-and-provenance-7-what-this-is-not","summary":"Audit and Provenance · section 7","snippet":"What this is not not a general audit database not hidden mutation logging not a ticketing system not a replacement for the contract not a fleet reporting layer","page_title":"Audit and Provenance"}],"in_primary_nav":true},{"slug":"compatibility-policy","title":"Compatibility Policy","summary":"Version rules keep the contract predictable while ota evolves, so migrations stay reviewable instead of surprising.","href":"/docs/reference/compatibility-policy","canonical_url":"https://ota.run/docs/reference/compatibility-policy","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Versioning rule","href":"/docs/reference/compatibility-policy#compatibility-policy-1-versioning-rule","canonical_url":"https://ota.run/docs/reference/compatibility-policy#compatibility-policy-1-versioning-rule","summary":"Compatibility Policy · section 1","snippet":"Versioning rule Version rules keep the contract predictable while ota evolves, so migrations stay reviewable instead of surprising. `version: 1` is the current contract version ...","page_title":"Compatibility Policy"},{"title":"Parsing rule","href":"/docs/reference/compatibility-policy#compatibility-policy-2-parsing-rule","canonical_url":"https://ota.run/docs/reference/compatibility-policy#compatibility-policy-2-parsing-rule","summary":"Compatibility Policy · section 2","snippet":"Parsing rule unknown keys fail parsing there is no warning-only unknown-key mode today known fields are the contract surface; everything else is rejected","page_title":"Compatibility Policy"},{"title":"Migration rule","href":"/docs/reference/compatibility-policy#compatibility-policy-3-migration-rule","canonical_url":"https://ota.run/docs/reference/compatibility-policy#compatibility-policy-3-migration-rule","summary":"Compatibility Policy · section 3","snippet":"Migration rule document the replacement first keep the old shape working when feasible call out the migration path explicitly avoid silent removal","page_title":"Compatibility Policy"},{"title":"What to rely on","href":"/docs/reference/compatibility-policy#compatibility-policy-4-what-to-rely-on","canonical_url":"https://ota.run/docs/reference/compatibility-policy#compatibility-policy-4-what-to-rely-on","summary":"Compatibility Policy · section 4","snippet":"What to rely on do not rely on undocumented keys do not rely on silent fallback behavior do rely on explicit contract fields and versioned behavior changes","page_title":"Compatibility Policy"},{"title":"Use cases","href":"/docs/reference/compatibility-policy#compatibility-policy-5-use-cases","canonical_url":"https://ota.run/docs/reference/compatibility-policy#compatibility-policy-5-use-cases","summary":"Compatibility Policy · section 5","snippet":"Use cases know whether a new release can break old contracts understand whether a repo with unknown keys will still parse plan a migration for renamed fields","page_title":"Compatibility Policy"}],"in_primary_nav":true},{"slug":"compatibility-surface","title":"Compatibility Surface","summary":"Use this page when a tool, CI gate, or wrapper needs the command surface ota intends to keep stable.","href":"/docs/reference/compatibility-surface","canonical_url":"https://ota.run/docs/reference/compatibility-surface","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Command inventory","href":"/docs/reference/compatibility-surface#compatibility-surface-1-command-inventory","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-1-command-inventory","summary":"Compatibility Surface · section 1","snippet":"Command inventory Use this page when a tool, CI gate, or wrapper needs the command surface ota intends to keep stable. The goal here is not to memorize every command. It is to s...","page_title":"Compatibility Surface"},{"title":"Repo diagnosis and gating","href":"/docs/reference/compatibility-surface#compatibility-surface-2-repo-diagnosis-and-gating","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-2-repo-diagnosis-and-gating","summary":"Compatibility Surface · section 2","snippet":"Repo diagnosis and gating Use these when the question is whether a repo is valid, ready, or needs an ordered remediation path. This is the stable surface for readiness gates, di...","page_title":"Compatibility Surface"},{"title":"Repo execution and preparation","href":"/docs/reference/compatibility-surface#compatibility-surface-3-repo-execution-and-preparation","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-3-repo-execution-and-preparation","summary":"Compatibility Surface · section 3","snippet":"Repo execution and preparation Use these when the question is what can run, what ota would execute, and what ota would prepare before execution starts. This is the stable surfac...","page_title":"Compatibility Surface"},{"title":"Repo authoring and policy","href":"/docs/reference/compatibility-surface#compatibility-surface-4-repo-authoring-and-policy","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-4-repo-authoring-and-policy","summary":"Compatibility Surface · section 4","snippet":"Repo authoring and policy Use these when the question is how contracts or policy packs are initialized, inferred, reviewed, compared, or governed. This is the stable surface aro...","page_title":"Compatibility Surface"},{"title":"Workspace surface","href":"/docs/reference/compatibility-surface#compatibility-surface-5-workspace-surface","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-5-workspace-surface","summary":"Compatibility Surface · section 5","snippet":"Workspace surface Use these when the integration boundary is the workspace instead of one repo at a time. This is the stable surface for multi-repo readiness, execution, refresh...","page_title":"Compatibility Surface"},{"title":"Stable surfaces","href":"/docs/reference/compatibility-surface#compatibility-surface-6-stable-surfaces","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-6-stable-surfaces","summary":"Compatibility Surface · section 6","snippet":"Stable surfaces Depend on commands, exit behavior, JSON keys, and deterministic ordering, not prose.","page_title":"Compatibility Surface"},{"title":"Command names","href":"/docs/reference/compatibility-surface#compatibility-surface-7-command-names","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-7-command-names","summary":"Compatibility Surface · section 7","snippet":"Command names Treat repo command names and subcommands as a stable wrapper surface, not as incidental copy. Use this when the integration boundary is one repo and the wrapper de...","page_title":"Compatibility Surface"},{"title":"Workspace surface","href":"/docs/reference/compatibility-surface#compatibility-surface-8-workspace-surface","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-8-workspace-surface","summary":"Compatibility Surface · section 8","snippet":"Workspace surface Treat workspace commands as their own stable orchestration surface instead of assuming they mirror repo commands loosely. Use this when the integration boundar...","page_title":"Compatibility Surface"},{"title":"JSON shape","href":"/docs/reference/compatibility-surface#compatibility-surface-9-json-shape","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-9-json-shape","summary":"Compatibility Surface · section 9","snippet":"JSON shape Depend on JSON top-level shape and key meaning when automation consumes ota output. Use JSON output as the machine contract even when human wording evolves, because p...","page_title":"Compatibility Surface"},{"title":"Deterministic ordering","href":"/docs/reference/compatibility-surface#compatibility-surface-10-deterministic-ordering","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-10-deterministic-ordering","summary":"Compatibility Surface · section 10","snippet":"Deterministic ordering Depend on stable ordering for list and receipt-style outputs so wrappers and reviewers see the same result. Rely on deterministic ordering for inventory, ...","page_title":"Compatibility Surface"},{"title":"What should stay stable","href":"/docs/reference/compatibility-surface#compatibility-surface-11-what-should-stay-stable","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-11-what-should-stay-stable","summary":"Compatibility Surface · section 11","snippet":"What should stay stable command availability and names exit behavior and JSON top-level shape key meaning for machine-readable output deterministic ordering for list outputs cle...","page_title":"Compatibility Surface"},{"title":"Why this matters","href":"/docs/reference/compatibility-surface#compatibility-surface-12-why-this-matters","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-12-why-this-matters","summary":"Compatibility Surface · section 12","snippet":"Why this matters Wrapper tools Tool authors need a stable command and output surface they can wrap without guessing. CI gates CI owners need predictable exit behavior and JSON s...","page_title":"Compatibility Surface"},{"title":"Use cases","href":"/docs/reference/compatibility-surface#compatibility-surface-13-use-cases","canonical_url":"https://ota.run/docs/reference/compatibility-surface#compatibility-surface-13-use-cases","summary":"Compatibility Surface · section 13","snippet":"Use cases a CI integration reads `ota doctor --json` a wrapper tool depends on the order of `ota tasks` a support team needs to know whether a new command output is a breaking c...","page_title":"Compatibility Surface"}],"in_primary_nav":true},{"slug":"starter-packs","title":"Starter Packs","summary":"Use this page when the question is not whether `ota init` exists, but which explicit starter pack should seed the first draft.","href":"/docs/reference/starter-packs","canonical_url":"https://ota.run/docs/reference/starter-packs","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/starter-packs#starter-packs-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-1-when-to-use-this-page","summary":"Starter Packs · section 1","snippet":"When to use this page Use this page when the question is not whether `ota init` exists, but which explicit starter pack should seed the first draft. Starter packs keep the pack-...","page_title":"Starter Packs"},{"title":"Review-first flow","href":"/docs/reference/starter-packs#starter-packs-2-review-first-flow","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-2-review-first-flow","summary":"Starter Packs · section 2","snippet":"Review-first flow The safe path is compare, preview, then write. Start with the catalog when you are choosing a pack. Start with detector-led init when you want ota to infer the...","page_title":"Starter Packs"},{"title":"How to compare packs","href":"/docs/reference/starter-packs#starter-packs-3-how-to-compare-packs","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-3-how-to-compare-packs","summary":"Starter Packs · section 3","snippet":"How to compare packs Do not choose by language label alone. Compare the starter by the exact loop it seeds, the few conventional knobs it allows, and the boundary it deliberatel...","page_title":"Starter Packs"},{"title":"Available packs","href":"/docs/reference/starter-packs#starter-packs-4-available-packs","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-4-available-packs","summary":"Starter Packs · section 4","snippet":"Available packs These are the built-in conventional starters today. Choose the pack whose execution boundary already matches the repo instead of picking the closest language lab...","page_title":"Starter Packs"},{"title":"Pack-specific knobs","href":"/docs/reference/starter-packs#starter-packs-5-pack-specific-knobs","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-5-pack-specific-knobs","summary":"Starter Packs · section 5","snippet":"Pack-specific knobs Only add a knob when the boundary is truly conventional. The goal is explicit starter control, not open-ended templating. the Node pack keeps `toolchains.nod...","page_title":"Starter Packs"},{"title":"What packs do not infer","href":"/docs/reference/starter-packs#starter-packs-6-what-packs-do-not-infer","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-6-what-packs-do-not-infer","summary":"Starter Packs · section 6","snippet":"What packs do not infer Starter packs are explicit templates, not hidden repo-specific synthesis. The catalog now says this directly in both text and JSON so humans and automati...","page_title":"Starter Packs"},{"title":"Java wrapper behavior","href":"/docs/reference/starter-packs#starter-packs-7-java-wrapper-behavior","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-7-java-wrapper-behavior","summary":"Starter Packs · section 7","snippet":"Java wrapper behavior The Java packs are wrapper-aware on purpose. A Maven or Gradle repo that already ships its own wrapper should not be forced onto a global host tool assumpt...","page_title":"Starter Packs"},{"title":"Advisory mismatch behavior","href":"/docs/reference/starter-packs#starter-packs-8-advisory-mismatch-behavior","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-8-advisory-mismatch-behavior","summary":"Starter Packs · section 8","snippet":"Advisory mismatch behavior Explicit pack choice stays authoritative, but ota can still tell you when the repo signals point somewhere else. The advisory path is read-only. It do...","page_title":"Starter Packs"},{"title":"JSON surfaces","href":"/docs/reference/starter-packs#starter-packs-9-json-surfaces","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-9-json-surfaces","summary":"Starter Packs · section 9","snippet":"JSON surfaces Use JSON when automation or hosted tooling needs the same starter-pack truth the CLI is showing to a human. `mode: \"catalog\"` plus `packs` comes from `ota init --p...","page_title":"Starter Packs"},{"title":"What this page is not","href":"/docs/reference/starter-packs#starter-packs-10-what-this-page-is-not","canonical_url":"https://ota.run/docs/reference/starter-packs#starter-packs-10-what-this-page-is-not","summary":"Starter Packs · section 10","snippet":"What this page is not not a new top-level command surface separate from `ota init` not detector-led init with prettier copy not hidden auto-detection that silently switches your...","page_title":"Starter Packs"}],"in_primary_nav":true},{"slug":"mutation-controls-and-caching","title":"Writes and Caching","summary":"Use this page when you need to know what ota may change on disk and what it must leave alone.","href":"/docs/reference/mutation-controls-and-caching","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-1-when-to-use-this-page","summary":"Writes and Caching · section 1","snippet":"When to use this page Use this page when you need to know what ota may change on disk and what it must leave alone. Mutations must stay explicit, and cache state should never ou...","page_title":"Writes and Caching"},{"title":"How writes work","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-2-how-writes-work","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-2-how-writes-work","summary":"Writes and Caching · section 2","snippet":"How writes work ota should only write when the command explicitly says it can. If the command is read-only, it should stay read-only even when it has enough information to sugge...","page_title":"Writes and Caching"},{"title":"Writable commands","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-3-writable-commands","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-3-writable-commands","summary":"Writes and Caching · section 3","snippet":"Writable commands `ota detect --write` `ota detect --merge` `ota detect --rewrite --yes` `ota workspace detect --write` `ota workspace detect --merge` `ota workspace detect --re...","page_title":"Writes and Caching"},{"title":"Read-only commands","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-4-read-only-commands","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-4-read-only-commands","summary":"Writes and Caching · section 4","snippet":"Read-only commands default `ota detect`/`ota workspace detect` behavior is read-only unless a write mode is selected `ota detect --contract` is text-only and does not write `doc...","page_title":"Writes and Caching"},{"title":"How caching works","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-5-how-caching-works","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-5-how-caching-works","summary":"Writes and Caching · section 5","snippet":"How caching works Caching is only an implementation detail for repeated reads. It exists to avoid re-parsing and re-scanning when nothing meaningful changed. repo cache entries ...","page_title":"Writes and Caching"},{"title":"How to use it","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-6-how-to-use-it","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-6-how-to-use-it","summary":"Writes and Caching · section 6","snippet":"How to use it use review-only commands when you want to inspect first use merge when you want ota to apply only eligible additive changes use rewrite only when you want to repla...","page_title":"Writes and Caching"},{"title":"Why it matters","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-7-why-it-matters","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-7-why-it-matters","summary":"Writes and Caching · section 7","snippet":"Why it matters preview a contract change before writing it keep `detect --dry-run` review-only know that `init` writes only when asked avoid stale contract state trust that a ca...","page_title":"Writes and Caching"},{"title":"What this is not","href":"/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-8-what-this-is-not","canonical_url":"https://ota.run/docs/reference/mutation-controls-and-caching#mutation-controls-and-caching-8-what-this-is-not","summary":"Writes and Caching · section 8","snippet":"What this is not not a background sync engine not a persistent hidden state machine not a general-purpose cache policy surface not a replacement for the contract or filesystem t...","page_title":"Writes and Caching"}],"in_primary_nav":true},{"slug":"output-style","title":"Output Style","summary":"Use this page when you want to know what ota looks like in a terminal and what changes when you ask for plain output.","href":"/docs/reference/output-style","canonical_url":"https://ota.run/docs/reference/output-style","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/output-style#output-style-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/output-style#output-style-1-when-to-use-this-page","summary":"Output Style · section 1","snippet":"When to use this page Use this page when you want to know what ota looks like in a terminal and what changes when you ask for plain output. Human text output can be calm and rea...","page_title":"Output Style"},{"title":"Rich mode","href":"/docs/reference/output-style#output-style-2-rich-mode","canonical_url":"https://ota.run/docs/reference/output-style#output-style-2-rich-mode","summary":"Output Style · section 2","snippet":"Rich mode Rich mode is the default experience in terminals that can render color and icons well. It keeps the output readable while still making the important bits stand out. si...","page_title":"Output Style"},{"title":"What users can rely on","href":"/docs/reference/output-style#output-style-3-what-users-can-rely-on","canonical_url":"https://ota.run/docs/reference/output-style#output-style-3-what-users-can-rely-on","summary":"Output Style · section 3","snippet":"What users can rely on the command name and target stay visible in the header the order of sections stays stable the meaning of `VALID`, `READY`, and `NOT READY` stays stable th...","page_title":"Output Style"},{"title":"Plain mode","href":"/docs/reference/output-style#output-style-4-plain-mode","canonical_url":"https://ota.run/docs/reference/output-style#output-style-4-plain-mode","summary":"Output Style · section 4","snippet":"Plain mode Use `--plain` when you want ASCII-only output. removes emoji and icons removes ANSI colors uses simple ASCII bullets preserves the same command meaning and ordering P...","page_title":"Output Style"},{"title":"What stays stable","href":"/docs/reference/output-style#output-style-5-what-stays-stable","canonical_url":"https://ota.run/docs/reference/output-style#output-style-5-what-stays-stable","summary":"Output Style · section 5","snippet":"What stays stable command ordering status words like `VALID`, `READY`, and `NOT READY` clear next-action guidance no change to JSON semantics the same output meaning in rich and...","page_title":"Output Style"},{"title":"When to use plain mode","href":"/docs/reference/output-style#output-style-6-when-to-use-plain-mode","canonical_url":"https://ota.run/docs/reference/output-style#output-style-6-when-to-use-plain-mode","summary":"Output Style · section 6","snippet":"When to use plain mode when a terminal cannot render color or emoji well when a script wants the simplest possible text output when logs need to stay ASCII-only when a human wan...","page_title":"Output Style"},{"title":"What it is not","href":"/docs/reference/output-style#output-style-7-what-it-is-not","canonical_url":"https://ota.run/docs/reference/output-style#output-style-7-what-it-is-not","summary":"Output Style · section 7","snippet":"What it is not not JSON output not a machine contract not a styling guide for app UI not a promise that every visual detail stays fixed forever","page_title":"Output Style"},{"title":"Use cases","href":"/docs/reference/output-style#output-style-8-use-cases","canonical_url":"https://ota.run/docs/reference/output-style#output-style-8-use-cases","summary":"Output Style · section 8","snippet":"Use cases a CI job records plain text logs a user wants predictable output in an old terminal a support engineer needs to compare command output across systems an agent wants to...","page_title":"Output Style"}],"in_primary_nav":true},{"slug":"service-behavior","title":"Service Behavior","summary":"Treat services as declared readiness dependencies, not hidden setup steps.","href":"/docs/reference/service-behavior","canonical_url":"https://ota.run/docs/reference/service-behavior","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Why services matter","href":"/docs/reference/service-behavior#service-behavior-1-why-services-matter","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-1-why-services-matter","summary":"Service Behavior · section 1","snippet":"Why services matter Treat services as declared readiness dependencies, not hidden setup steps. Use this page when a repo needs supporting infrastructure such as a database, cach...","page_title":"Service Behavior"},{"title":"Service lifecycle at a glance","href":"/docs/reference/service-behavior#service-behavior-2-service-lifecycle-at-a-glance","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-2-service-lifecycle-at-a-glance","summary":"Service Behavior · section 2","snippet":"Service lifecycle at a glance Every service has a lifecycle: start it, check it, and stop it. ota only trusts a service as ready after the declared healthcheck succeeds. `start`...","page_title":"Service Behavior"},{"title":"Service field meanings","href":"/docs/reference/service-behavior#service-behavior-3-service-field-meanings","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-3-service-field-meanings","summary":"Service Behavior · section 3","snippet":"Service field meanings Each field exists to remove one guess from the readiness story. `required`: whether the service blocks repo readiness when it fails `manager` is the prefe...","page_title":"Service Behavior"},{"title":"How ota uses services","href":"/docs/reference/service-behavior#service-behavior-4-how-ota-uses-services","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-4-how-ota-uses-services","summary":"Service Behavior · section 4","snippet":"How ota uses services `ota services` inspects the declared service surface `ota doctor` checks healthchecks and reports whether the repo is truly ready `ota up` starts required ...","page_title":"Service Behavior"},{"title":"How to read the behavior","href":"/docs/reference/service-behavior#service-behavior-5-how-to-read-the-behavior","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-5-how-to-read-the-behavior","summary":"Service Behavior · section 5","snippet":"How to read the behavior if a required service fails its healthcheck, the repo is not ready if an optional service fails its healthcheck, ota reports it but does not make the re...","page_title":"Service Behavior"},{"title":"Real example","href":"/docs/reference/service-behavior#service-behavior-6-real-example","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-6-real-example","summary":"Service Behavior · section 6","snippet":"Real example This example shows a repo that needs Postgres and Redis before the app can run. ota.yaml yaml services: postgres: required: true manager: kind: compose file: compos...","page_title":"Service Behavior"},{"title":"What users should expect","href":"/docs/reference/service-behavior#service-behavior-7-what-users-should-expect","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-7-what-users-should-expect","summary":"Service Behavior · section 7","snippet":"What users should expect the repo becomes ready only after required services pass their checks the service order is driven by declared dependencies, not shell script order the h...","page_title":"Service Behavior"},{"title":"Use cases","href":"/docs/reference/service-behavior#service-behavior-8-use-cases","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-8-use-cases","summary":"Service Behavior · section 8","snippet":"Use cases a repo needs a database before tests can run a team wants optional local infra visible without making it blocking a maintainer wants `up` to bring services up before `...","page_title":"Service Behavior"},{"title":"What ota does not do","href":"/docs/reference/service-behavior#service-behavior-9-what-ota-does-not-do","canonical_url":"https://ota.run/docs/reference/service-behavior#service-behavior-9-what-ota-does-not-do","summary":"Service Behavior · section 9","snippet":"What ota does not do does not invent services that are not declared does not guess dependency ordering beyond `depends_on` does not replace healthchecks with process existence c...","page_title":"Service Behavior"}],"in_primary_nav":true},{"slug":"execution-topology","title":"Execution Topology","summary":"Use this page when the repo has more than one execution plane and the current backend model stops being honest.","href":"/docs/reference/execution-topology","canonical_url":"https://ota.run/docs/reference/execution-topology","category":"Design direction","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Current problem","href":"/docs/reference/execution-topology#execution-topology-1-current-problem","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-1-current-problem","summary":"Execution Topology · section 1","snippet":"Current problem Use this page when the repo has more than one execution plane and the current backend model stops being honest. The current repo-wide backend choice is too coars...","page_title":"Execution Topology"},{"title":"The proposed model","href":"/docs/reference/execution-topology#execution-topology-2-the-proposed-model","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-2-the-proposed-model","summary":"Execution Topology · section 2","snippet":"The proposed model execution contexts define where workloads run typed service managers define how services are controlled task-scoped workload listeners define how long-running...","page_title":"Execution Topology"},{"title":"Execution contexts","href":"/docs/reference/execution-topology#execution-topology-3-execution-contexts","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-3-execution-contexts","summary":"Execution Topology · section 3","snippet":"Execution contexts Contexts are the core boundary. They replace the one-flat-backend story with named workload planes. Requirements declared on a context are inherited by every ...","page_title":"Execution Topology"},{"title":"Tasks, workloads, and services","href":"/docs/reference/execution-topology#execution-topology-4-tasks-workloads-and-services","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-4-tasks-workloads-and-services","summary":"Execution Topology · section 4","snippet":"Tasks, workloads, and services Tasks bind to contexts. Services use typed managers. Workload listeners keep app ingress on the task and publish host-visible endpoints without ov...","page_title":"Execution Topology"},{"title":"Container-local dependency isolation","href":"/docs/reference/execution-topology#execution-topology-5-container-local-dependency-isolation","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-5-container-local-dependency-isolation","summary":"Execution Topology · section 5","snippet":"Container-local dependency isolation Use this when source must stay bind-mounted but platform-sensitive install artifacts should live in Ota-managed container storage instead of...","page_title":"Execution Topology"},{"title":"Listener mode rules","href":"/docs/reference/execution-topology#execution-topology-6-listener-mode-rules","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-6-listener-mode-rules","summary":"Execution Topology · section 6","snippet":"Listener mode rules use listener shorthand for common local HTTP or TCP listeners when the bind and projected host endpoint are the same fixed loopback port use the full listene...","page_title":"Execution Topology"},{"title":"Listener shorthand","href":"/docs/reference/execution-topology#execution-topology-7-listener-shorthand","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-7-listener-shorthand","summary":"Execution Topology · section 7","snippet":"Listener shorthand Use listener shorthand for the common local case where a task exposes one fixed HTTP or TCP port on loopback and the host-visible endpoint uses the same port....","page_title":"Execution Topology"},{"title":"Common local HTTP listener","href":"/docs/reference/execution-topology#execution-topology-8-common-local-http-listener","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-8-common-local-http-listener","summary":"Execution Topology · section 8","snippet":"Common local HTTP listener Use this when a dev server, app server, or docs preview exposes one fixed local HTTP port and the browser should open the same loopback port. `web.htt...","page_title":"Execution Topology"},{"title":"Common local TCP listener","href":"/docs/reference/execution-topology#execution-topology-9-common-local-tcp-listener","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-9-common-local-tcp-listener","summary":"Execution Topology · section 9","snippet":"Common local TCP listener Use this when an app exposes a raw TCP listener and an open socket is the right readiness truth. `redis.tcp: 6379` means listener `redis`, protocol `tc...","page_title":"Execution Topology"},{"title":"Full HTTP listener form","href":"/docs/reference/execution-topology#execution-topology-10-full-http-listener-form","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-10-full-http-listener-form","summary":"Execution Topology · section 10","snippet":"Full HTTP listener form This is the full shape Ota normalizes the HTTP shorthand into. Use the expanded form directly when the task needs custom bind address, container host pub...","page_title":"Execution Topology"},{"title":"Workload endpoint projection contract","href":"/docs/reference/execution-topology#execution-topology-11-workload-endpoint-projection-contract","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-11-workload-endpoint-projection-contract","summary":"Execution Topology · section 11","snippet":"Workload endpoint projection contract Use this when one long-running task needs one truthful host URL without making developers guess host ports. keep the app command simple (`r...","page_title":"Execution Topology"},{"title":"Clone, run, open flow","href":"/docs/reference/execution-topology#execution-topology-12-clone-run-open-flow","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-12-clone-run-open-flow","summary":"Execution Topology · section 12","snippet":"Clone, run, open flow ota owns host-port allocation and prints one reachable URL ota keeps container memory requests explicit at execution-context scope and lets operators overr...","page_title":"Execution Topology"},{"title":"Ingress troubleshooting","href":"/docs/reference/execution-topology#execution-topology-13-ingress-troubleshooting","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-13-ingress-troubleshooting","summary":"Execution Topology · section 13","snippet":"Ingress troubleshooting `declares multiple projected listeners ... but none sets project.host.primary: true`: mark exactly one projected listener as primary `declares multiple l...","page_title":"Execution Topology"},{"title":"Two concrete topologies","href":"/docs/reference/execution-topology#execution-topology-14-two-concrete-topologies","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-14-two-concrete-topologies","summary":"Execution Topology · section 14","snippet":"Two concrete topologies Container App + Compose Postgres The app runs in a container context, joins the Compose network, reaches Postgres by service name, and lets tasks declare...","page_title":"Execution Topology"},{"title":"What changes in doctor, up, and run","href":"/docs/reference/execution-topology#execution-topology-15-what-changes-in-doctor-up-and-run","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-15-what-changes-in-doctor-up-and-run","summary":"Execution Topology · section 15","snippet":"What changes in doctor, up, and run Use `requires_services` when a task should own its service prerequisites instead of depending on a manual `ota up` reminder. ota keeps servic...","page_title":"Execution Topology"},{"title":"Status and migration","href":"/docs/reference/execution-topology#execution-topology-16-status-and-migration","canonical_url":"https://ota.run/docs/reference/execution-topology#execution-topology-16-status-and-migration","summary":"Execution Topology · section 16","snippet":"Status and migration the execution-context foundation is shipped: `execution.default_context`, `execution.contexts`, `contexts.<name>.requirements`, `tasks.<name>.context`, and ...","page_title":"Execution Topology"}],"in_primary_nav":true},{"slug":"shell-semantics","title":"Shell Behavior","summary":"Use this page when you need to know exactly how ota runs commands on the host.","href":"/docs/reference/shell-semantics","canonical_url":"https://ota.run/docs/reference/shell-semantics","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/shell-semantics#shell-semantics-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-1-when-to-use-this-page","summary":"Shell Behavior · section 1","snippet":"When to use this page Use this page when you need to know exactly how ota runs commands on the host. Shell behavior matters because the same contract can behave differently on L...","page_title":"Shell Behavior"},{"title":"Host shell model","href":"/docs/reference/shell-semantics#shell-semantics-2-host-shell-model","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-2-host-shell-model","summary":"Shell Behavior · section 2","snippet":"Host shell model Unix-like systems use `sh -lc` Windows uses `cmd /C` task `run` and `script` use the same platform shell model service `start`, `stop`, and `healthcheck` comman...","page_title":"Shell Behavior"},{"title":"Working directory","href":"/docs/reference/shell-semantics#shell-semantics-3-working-directory","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-3-working-directory","summary":"Shell Behavior · section 3","snippet":"Working directory if you pass a direct `ota.yaml` path, ota runs commands from that file’s parent directory if you pass a directory, ota runs commands from that directory if you...","page_title":"Shell Behavior"},{"title":"Environment behavior","href":"/docs/reference/shell-semantics#shell-semantics-4-environment-behavior","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-4-environment-behavior","summary":"Shell Behavior · section 4","snippet":"Environment behavior configured env values are applied to task execution required env values must be present or resolvable from defaults where allowed ota does not translate she...","page_title":"Shell Behavior"},{"title":"`run` vs `script`","href":"/docs/reference/shell-semantics#shell-semantics-5-run-vs-script","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-5-run-vs-script","summary":"Shell Behavior · section 5","snippet":"`run` vs `script` `run` is a single command string `script` is a multiline shell body both execute through the same platform shell model use `run` for one command you would type...","page_title":"Shell Behavior"},{"title":"Real example","href":"/docs/reference/shell-semantics#shell-semantics-6-real-example","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-6-real-example","summary":"Shell Behavior · section 6","snippet":"Real example This example shows how to keep one task portable while still respecting platform-specific shell syntax. ota.yaml yaml tasks: test: variants: - when: os: linux scrip...","page_title":"Shell Behavior"},{"title":"What users should expect","href":"/docs/reference/shell-semantics#shell-semantics-7-what-users-should-expect","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-7-what-users-should-expect","summary":"Shell Behavior · section 7","snippet":"What users should expect write task and service commands with their supported platforms in mind use task variants when Windows needs different shell syntax ota guarantees the in...","page_title":"Shell Behavior"},{"title":"Use cases","href":"/docs/reference/shell-semantics#shell-semantics-8-use-cases","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-8-use-cases","summary":"Shell Behavior · section 8","snippet":"Use cases a repo works on Linux and macOS, but Windows needs different shell syntax a task needs a multiline setup script instead of one shell string a service healthcheck depen...","page_title":"Shell Behavior"},{"title":"What ota does not do","href":"/docs/reference/shell-semantics#shell-semantics-9-what-ota-does-not-do","canonical_url":"https://ota.run/docs/reference/shell-semantics#shell-semantics-9-what-ota-does-not-do","summary":"Shell Behavior · section 9","snippet":"What ota does not do no per-task shell selection no PowerShell-specific execution mode in V1 no Bash-only contract mode no shell portability translation no isolated shell enviro...","page_title":"Shell Behavior"}],"in_primary_nav":true},{"slug":"support-policy","title":"Platform support","summary":"Use this page to understand where ota is first-class today and where the behavior is narrower.","href":"/docs/reference/support-policy","canonical_url":"https://ota.run/docs/reference/support-policy","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/support-policy#support-policy-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-1-when-to-use-this-page","summary":"Platform support · section 1","snippet":"When to use this page Use this page to understand where ota is first-class today and where the behavior is narrower. This is the page that tells you what to expect before you as...","page_title":"Platform support"},{"title":"Compatibility in practice","href":"/docs/reference/support-policy#support-policy-2-compatibility-in-practice","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-2-compatibility-in-practice","summary":"Platform support · section 2","snippet":"Compatibility in practice Compatibility is about whether the declared contract and the current runtime match well enough to trust the result. a repo can be valid without being f...","page_title":"Platform support"},{"title":"Platform support","href":"/docs/reference/support-policy#support-policy-3-platform-support","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-3-platform-support","summary":"Platform support · section 3","snippet":"Platform support Linux: first-class target macOS: first-class target Windows: supported, but not identical to Unix-like shells","page_title":"Platform support"},{"title":"What this means in practice","href":"/docs/reference/support-policy#support-policy-4-what-this-means-in-practice","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-4-what-this-means-in-practice","summary":"Platform support · section 4","snippet":"What this means in practice use Linux or macOS when you want the smoothest default path use Windows when the repo contract explicitly handles its shell differences split tasks i...","page_title":"Platform support"},{"title":"What ota accepts","href":"/docs/reference/support-policy#support-policy-5-what-ota-accepts","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-5-what-ota-accepts","summary":"Platform support · section 5","snippet":"What ota accepts explicit platform declarations in the contract task variants when different shells need different bodies backend selection when the repo needs native, container...","page_title":"Platform support"},{"title":"What ota rejects or warns about","href":"/docs/reference/support-policy#support-policy-6-what-ota-rejects-or-warns-about","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-6-what-ota-rejects-or-warns-about","summary":"Platform support · section 6","snippet":"What ota rejects or warns about shell syntax that only works on a different platform than the one declared contract fields that imply portability ota does not actually provide s...","page_title":"Platform support"},{"title":"Shell semantics","href":"/docs/reference/support-policy#support-policy-7-shell-semantics","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-7-shell-semantics","summary":"Platform support · section 7","snippet":"Shell semantics Unix-like systems use `sh -lc` Windows uses `cmd /C` there is no per-task shell selection in V1 if the command body assumes Bash behavior, that assumption must b...","page_title":"Platform support"},{"title":"Lifecycle semantics","href":"/docs/reference/support-policy#support-policy-8-lifecycle-semantics","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-8-lifecycle-semantics","summary":"Platform support · section 8","snippet":"Lifecycle semantics Lifecycle tells you how ota treats execution reuse and isolation, not whether a repo is logically ready. `persistent` reuses a named container when container...","page_title":"Platform support"},{"title":"What users should expect","href":"/docs/reference/support-policy#support-policy-9-what-users-should-expect","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-9-what-users-should-expect","summary":"Platform support · section 9","snippet":"What users should expect expect the best behavior today on Linux and macOS expect Windows to work, but with more explicit shell syntax and fewer portability assumptions expect s...","page_title":"Platform support"},{"title":"When this matters","href":"/docs/reference/support-policy#support-policy-10-when-this-matters","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-10-when-this-matters","summary":"Platform support · section 10","snippet":"When this matters a repo has Windows users but shell bodies were written for Unix syntax a task works locally but fails in CI because the runner shell differs a service healthch...","page_title":"Platform support"},{"title":"What this is not","href":"/docs/reference/support-policy#support-policy-11-what-this-is-not","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-11-what-this-is-not","summary":"Platform support · section 11","snippet":"What this is not not a promise of identical shell behavior on every OS not per-task shell selection not automatic shell portability translation not isolated ephemeral workspace ...","page_title":"Platform support"},{"title":"Relationship to other surfaces","href":"/docs/reference/support-policy#support-policy-12-relationship-to-other-surfaces","canonical_url":"https://ota.run/docs/reference/support-policy#support-policy-12-relationship-to-other-surfaces","summary":"Platform support · section 12","snippet":"Relationship to other surfaces `contract` defines the repo’s execution intent `shell-semantics` defines the actual command invocation model `doctor` should explain support and c...","page_title":"Platform support"}],"in_primary_nav":true},{"slug":"remote-execution","title":"Remote Execution","summary":"Remote execution should stay descriptive, inspectable, and visible to tools.","href":"/docs/reference/remote-execution","canonical_url":"https://ota.run/docs/reference/remote-execution","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Why it matters","href":"/docs/reference/remote-execution#remote-execution-1-why-it-matters","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-1-why-it-matters","summary":"Remote Execution · section 1","snippet":"Why it matters Remote execution should stay descriptive, inspectable, and visible to tools. remote execution should be explicit, not inferred from host quirks editors need one s...","page_title":"Remote Execution"},{"title":"When to use it","href":"/docs/reference/remote-execution#remote-execution-2-when-to-use-it","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-2-when-to-use-it","summary":"Remote Execution · section 2","snippet":"When to use it use `native` when the task should run on the current machine use `container` when the task needs a pinned image, repeatable local isolation, or a known toolchain ...","page_title":"Remote Execution"},{"title":"Contract fields","href":"/docs/reference/remote-execution#remote-execution-3-contract-fields","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-3-contract-fields","summary":"Remote Execution · section 3","snippet":"Contract fields These are the fields users usually need to read first when deciding how remote execution will behave. `provider` Identifies the remote execution backend to use, ...","page_title":"Remote Execution"},{"title":"How execution is selected","href":"/docs/reference/remote-execution#remote-execution-4-how-execution-is-selected","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-4-how-execution-is-selected","summary":"Remote Execution · section 4","snippet":"How execution is selected if `preferred` is `remote`, ota validates `execution.supported` before attempting `execution.backends.remote`. when a command override is not set, cont...","page_title":"Remote Execution"},{"title":"Example","href":"/docs/reference/remote-execution#remote-execution-5-example","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-5-example","summary":"Remote Execution · section 5","snippet":"Example This example shows the remote execution shape the contract makes explicit. It uses the built-in remote provider shape and then shows a custom backend provider descriptor...","page_title":"Remote Execution"},{"title":"Target shape","href":"/docs/reference/remote-execution#remote-execution-6-target-shape","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-6-target-shape","summary":"Remote Execution · section 6","snippet":"Target shape `ssh` and `tsh` targets should look like `user@host` when built-in providers are used `kubectl` targets should start with `pod/` when built-in providers are used `d...","page_title":"Remote Execution"},{"title":"What editors should surface","href":"/docs/reference/remote-execution#remote-execution-7-what-editors-should-surface","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-7-what-editors-should-surface","summary":"Remote Execution · section 7","snippet":"What editors should surface discover tasks inspect readiness launch runnable tasks view remote execution hints surface repo and workspace diagnostics without custom glue","page_title":"Remote Execution"},{"title":"Scope","href":"/docs/reference/remote-execution#remote-execution-8-scope","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-8-scope","summary":"Remote Execution · section 8","snippet":"Scope editor/tool compatibility remote runner discoverability stable metadata shape hosted validation consumption","page_title":"Remote Execution"},{"title":"JSON surfaces","href":"/docs/reference/remote-execution#remote-execution-9-json-surfaces","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-9-json-surfaces","summary":"Remote Execution · section 9","snippet":"JSON surfaces The same contract powers validation, diagnosis, execution, and workspace roll-ups. Repo diagnostics bash ota validate --json ota doctor --json Execution bash ota r...","page_title":"Remote Execution"},{"title":"Semantics","href":"/docs/reference/remote-execution#remote-execution-10-semantics","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-10-semantics","summary":"Remote Execution · section 10","snippet":"Semantics remote execution metadata is descriptive, not magical editor integrations should consume the canonical contract data UI surfaces may present richer affordances, but th...","page_title":"Remote Execution"},{"title":"Backend provider contract","href":"/docs/reference/remote-execution#remote-execution-11-backend-provider-contract","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-11-backend-provider-contract","summary":"Remote Execution · section 11","snippet":"Backend provider contract Use a `backend_provider` when the remote execution path needs a custom adapter instead of a built-in provider. This is the seam for an internal runner,...","page_title":"Remote Execution"},{"title":"Multiple backend providers","href":"/docs/reference/remote-execution#remote-execution-12-multiple-backend-providers","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-12-multiple-backend-providers","summary":"Remote Execution · section 12","snippet":"Multiple backend providers A repo can declare more than one backend provider. Only one provider is selected for a given remote execution path, and the `provider` field chooses w...","page_title":"Remote Execution"},{"title":"Real API shape","href":"/docs/reference/remote-execution#remote-execution-13-real-api-shape","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-13-real-api-shape","summary":"Remote Execution · section 13","snippet":"Real API shape ota talks to the provider command with JSON on stdin and expects JSON back on stdout. The provider command can then translate that into whatever real backend API ...","page_title":"Remote Execution"},{"title":"Use cases","href":"/docs/reference/remote-execution#remote-execution-14-use-cases","canonical_url":"https://ota.run/docs/reference/remote-execution#remote-execution-14-use-cases","summary":"Remote Execution · section 14","snippet":"Use cases show whether the current repo is ready before the user hits run surface the contract and execution metadata next to the task list offer remote-execution hints without ...","page_title":"Remote Execution"}],"in_primary_nav":true},{"slug":"semantic-diff-and-explain","title":"Diff and Explain","summary":"`ota diff` shows what changed between two contract states.","href":"/docs/reference/semantic-diff-and-explain","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Purpose","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-1-purpose","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-1-purpose","summary":"Diff and Explain · section 1","snippet":"Purpose `ota diff` shows what changed between two contract states. `ota explain` turns readiness findings into an ordered fix plan. use `ota diff` when you want to understand th...","page_title":"Diff and Explain"},{"title":"`ota diff`","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-2-ota-diff","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-2-ota-diff","summary":"Diff and Explain · section 2","snippet":"`ota diff` `ota diff` compares two repo contracts or two workspace contracts as structured YAML. It reports added, removed, and changed fields in deterministic order. use it bef...","page_title":"Diff and Explain"},{"title":"`ota diff` JSON shape","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-3-ota-diff-json-shape","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-3-ota-diff-json-shape","summary":"Diff and Explain · section 3","snippet":"`ota diff` JSON shape `ota diff --json` returns the contract comparison as a machine-readable payload. Status `ok` tells you whether ota completed the comparison successfully, a...","page_title":"Diff and Explain"},{"title":"`ota explain`","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-4-ota-explain","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-4-ota-explain","summary":"Diff and Explain · section 4","snippet":"`ota explain` `ota explain` turns readiness findings into an ordered remediation plan. It is the command to use when you want ota to tell you what to fix first and why. the outp...","page_title":"Diff and Explain"},{"title":"`ota explain` JSON shape","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-5-ota-explain-json-shape","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-5-ota-explain-json-shape","summary":"Diff and Explain · section 5","snippet":"`ota explain` JSON shape `ota explain --json` returns readiness findings as an ordered remediation plan with grouped actions and detailed steps. Status `ok` tells you whether ot...","page_title":"Diff and Explain"},{"title":"How to read the outputs","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-6-how-to-read-the-outputs","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-6-how-to-read-the-outputs","summary":"Diff and Explain · section 6","snippet":"How to read the outputs read `summary` first when you want the roll-up read `changes` when you want to review contract differences before merging read `actions` when you want th...","page_title":"Diff and Explain"},{"title":"Use cases","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-7-use-cases","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-7-use-cases","summary":"Diff and Explain · section 7","snippet":"Use cases review what a proposed contract change will do before writing it compare a branch against main in CI summarize the impact of a workspace bootstrap change check whether...","page_title":"Diff and Explain"},{"title":"Examples","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-8-examples","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-8-examples","summary":"Diff and Explain · section 8","snippet":"Examples Diff commands bash ota diff ./before/ota.yaml ./after/ota.yaml ota diff --json ./before/ota.yaml ./after/ota.yaml ota explain ./repo ota explain --json ./repo Diff JSON...","page_title":"Diff and Explain"},{"title":"Non-goals","href":"/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-9-non-goals","canonical_url":"https://ota.run/docs/reference/semantic-diff-and-explain#semantic-diff-and-explain-9-non-goals","summary":"Diff and Explain · section 9","snippet":"Non-goals auto-writing contract changes fuzzy natural-language repair hiding readiness blockers behind a generic suggestion engine replacing `doctor`, `validate`, or `detect`","page_title":"Diff and Explain"}],"in_primary_nav":true},{"slug":"extension-boundary","title":"Extension Support","summary":"Extensions are explicit descriptors, not hidden runtime plugins.","href":"/docs/reference/extension-boundary","canonical_url":"https://ota.run/docs/reference/extension-boundary","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Current boundary","href":"/docs/reference/extension-boundary#extension-boundary-1-current-boundary","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-1-current-boundary","summary":"Extension Support · section 1","snippet":"Current boundary Extensions are explicit descriptors, not hidden runtime plugins. The page separates discovery, explicit execution, and custom remote execution so users do not h...","page_title":"Extension Support"},{"title":"Core command boundary","href":"/docs/reference/extension-boundary#extension-boundary-2-core-command-boundary","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-2-core-command-boundary","summary":"Extension Support · section 2","snippet":"Core command boundary `ota doctor` stays core-focused `ota run` stays task-focused `ota up` stays repo readiness focused `ota check` stays check-focused","page_title":"Extension Support"},{"title":"Example","href":"/docs/reference/extension-boundary#extension-boundary-3-example","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-3-example","summary":"Extension Support · section 3","snippet":"Example This page describes the current shipped seam and the structured contract for custom remote execution. Extension descriptors yaml extensions: release-check: kind: check_p...","page_title":"Extension Support"},{"title":"Use cases","href":"/docs/reference/extension-boundary#extension-boundary-4-use-cases","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-4-use-cases","summary":"Extension Support · section 4","snippet":"Use cases a readiness checker exists as contract data without becoming hidden runtime behavior a release flow needs a clearly named publish seam a remote backend needs a structu...","page_title":"Extension Support"},{"title":"Backend provider wire contract","href":"/docs/reference/extension-boundary#extension-boundary-5-backend-provider-wire-contract","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-5-backend-provider-wire-contract","summary":"Extension Support · section 5","snippet":"Backend provider wire contract When ota hands execution to a `backend_provider`, the provider gets a structured request and must return a structured response. That makes the ada...","page_title":"Extension Support"},{"title":"What this is not","href":"/docs/reference/extension-boundary#extension-boundary-6-what-this-is-not","canonical_url":"https://ota.run/docs/reference/extension-boundary#extension-boundary-6-what-this-is-not","summary":"Extension Support · section 6","snippet":"What this is not not automatic plugin execution not a hidden extension framework not a replacement for `tasks` not a general-purpose runtime plugin host","page_title":"Extension Support"}],"in_primary_nav":true},{"slug":"examples-rust-toolchain","title":"Rust toolchain ownership without duplicate runtime/tool drift","summary":"Use this when a Rust repo should treat Rust as one provider-backed ecosystem instead of repeating the same ownership across `runtimes`, `tools`, and setup scripts.","href":"/docs/examples/rust-toolchain","canonical_url":"https://ota.run/docs/examples/rust-toolchain","category":"Examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/rust-toolchain#examples-rust-toolchain-1-typical-signals","canonical_url":"https://ota.run/docs/examples/rust-toolchain#examples-rust-toolchain-1-typical-signals","summary":"Rust toolchain ownership without duplicate runtime/tool drift · section 1","snippet":"Typical signals the repo is Rust and currently splits the same truth across setup shell, runtimes, and tools rustfmt, clippy, or cross targets should be contract truth instead o...","page_title":"Rust toolchain ownership without duplicate runtime/tool drift"},{"title":"Why it matters","href":"/docs/examples/rust-toolchain#examples-rust-toolchain-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/rust-toolchain#examples-rust-toolchain-2-why-it-matters","summary":"Rust toolchain ownership without duplicate runtime/tool drift · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Rust toolchain ownership without duplicate runtime/tool drift"},{"title":"Example contract","href":"/docs/examples/rust-toolchain#examples-rust-toolchain-3-example-contract","canonical_url":"https://ota.run/docs/examples/rust-toolchain#examples-rust-toolchain-3-example-contract","summary":"Rust toolchain ownership without duplicate runtime/tool drift · section 3","snippet":"Example contract Use this when a Rust repo should treat Rust as one provider-backed ecosystem instead of repeating the same ownership across `runtimes`, `tools`, and setup scrip...","page_title":"Rust toolchain ownership without duplicate runtime/tool drift"},{"title":"Task notes","href":"/docs/examples/rust-toolchain#examples-rust-toolchain-4-task-notes","canonical_url":"https://ota.run/docs/examples/rust-toolchain#examples-rust-toolchain-4-task-notes","summary":"Rust toolchain ownership without duplicate runtime/tool drift · section 4","snippet":"Task notes Use `ota doctor .` and `ota up --dry-run .` first so you can see the selected Rust toolchain described through `rustup` rather than through duplicate `runtimes.rust` ...","page_title":"Rust toolchain ownership without duplicate runtime/tool drift"}],"in_primary_nav":false},{"slug":"examples-topology-node-isolated","title":"Container app with isolated `node_modules`","summary":"Use this when a Node app runs in a container context but the host checkout already has dependency artifacts that should not leak into the container runtime.","href":"/docs/examples/topology/node-isolated","canonical_url":"https://ota.run/docs/examples/topology/node-isolated","category":"Topology examples","intent":"copy","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"Typical signals","href":"/docs/examples/topology/node-isolated#examples-topology-node-isolated-1-typical-signals","canonical_url":"https://ota.run/docs/examples/topology/node-isolated#examples-topology-node-isolated-1-typical-signals","summary":"Container app with isolated `node_modules` · section 1","snippet":"Typical signals container-backed Node workflow source tree stays bind-mounted `node_modules` is isolated from the host tree native binaries like `workerd` and `esbuild` stay pla...","page_title":"Container app with isolated `node_modules`"},{"title":"Why it matters","href":"/docs/examples/topology/node-isolated#examples-topology-node-isolated-2-why-it-matters","canonical_url":"https://ota.run/docs/examples/topology/node-isolated#examples-topology-node-isolated-2-why-it-matters","summary":"Container app with isolated `node_modules` · section 2","snippet":"Why it matters it turns a repo pattern into something humans, CI, and agents can read the same way it makes the next command obvious instead of implied by README drift it keeps ...","page_title":"Container app with isolated `node_modules`"},{"title":"Example contract","href":"/docs/examples/topology/node-isolated#examples-topology-node-isolated-3-example-contract","canonical_url":"https://ota.run/docs/examples/topology/node-isolated#examples-topology-node-isolated-3-example-contract","summary":"Container app with isolated `node_modules` · section 3","snippet":"Example contract Use this when a Node app runs in a container context but the host checkout already has dependency artifacts that should not leak into the container runtime. Thi...","page_title":"Container app with isolated `node_modules`"},{"title":"Task notes","href":"/docs/examples/topology/node-isolated#examples-topology-node-isolated-4-task-notes","canonical_url":"https://ota.run/docs/examples/topology/node-isolated#examples-topology-node-isolated-4-task-notes","summary":"Container app with isolated `node_modules` · section 4","snippet":"Task notes Why this matters: the app can run against container-correct dependencies without asking every developer to delete host `node_modules` first. What it fixes: native bin...","page_title":"Container app with isolated `node_modules`"}],"in_primary_nav":false},{"slug":"adapter-bootstrap","title":"Adapter Bootstrap","summary":"Use this page when the machine or container does not already have the adapter binary ota needs to provision repo prerequisites.","href":"/docs/reference/adapter-bootstrap","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap","category":"Reference","intent":"reference","difficulty":null,"audience":null,"status":null,"last_reviewed":null,"sections":[{"title":"When to use this page","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-1-when-to-use-this-page","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-1-when-to-use-this-page","summary":"Adapter Bootstrap · section 1","snippet":"When to use this page Use this page when the machine or container does not already have the adapter binary ota needs to provision repo prerequisites. Adapter bootstrap is separa...","page_title":"Adapter Bootstrap"},{"title":"What ota does today","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-2-what-ota-does-today","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-2-what-ota-does-today","summary":"Adapter Bootstrap · section 2","snippet":"What ota does today Validated surface `policies.adapter_bootstrap` is validated in the org policy pack. Retry flow ota resolves an approved bootstrap backend for a missing adapt...","page_title":"Adapter Bootstrap"},{"title":"Bootstrap rule meaning","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-3-bootstrap-rule-meaning","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-3-bootstrap-rule-meaning","summary":"Adapter Bootstrap · section 3","snippet":"Bootstrap rule meaning An adapter bootstrap rule is a policy-only escape hatch: it lets ota install one adapter binary before it attempts policy-backed provisioning with that ad...","page_title":"Adapter Bootstrap"},{"title":"Example policy","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-4-example-policy","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-4-example-policy","summary":"Adapter Bootstrap · section 4","snippet":"Example policy org-policy.yaml yaml policies: adapter_bootstrap: brew: source: brew-bootstrap approved_versions: - \"4.4\" choco: source: choco-bootstrap approved_versions: - \"2.0...","page_title":"Adapter Bootstrap"},{"title":"Source bootstrap in practice","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-5-source-bootstrap-in-practice","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-5-source-bootstrap-in-practice","summary":"Adapter Bootstrap · section 5","snippet":"Source bootstrap in practice Use a bootstrap backend when the source manager itself is missing. ota installs the approved manager first, then retries repo provisioning through t...","page_title":"Adapter Bootstrap"},{"title":"What it is not","href":"/docs/reference/adapter-bootstrap#adapter-bootstrap-6-what-it-is-not","canonical_url":"https://ota.run/docs/reference/adapter-bootstrap#adapter-bootstrap-6-what-it-is-not","summary":"Adapter Bootstrap · section 6","snippet":"What it is not not repo provisioning not a general package manager surface not a hidden workstation manager not silent installs from unapproved sources","page_title":"Adapter Bootstrap"}],"in_primary_nav":false}]}