llms.txt
# llms.txt
The execution contract for AI agents, shared with humans and CI across software repositories.
## Metadata
- site: ota
- canonical_origin: https://ota.run
- generated_at: 2026-10-10T10:14:46.037Z
- format_version: 1.1
- language: en-US
- docs_indexed: 113
- blog_indexed: 110
- learn_lessons_indexed: 25
## Purpose
- Explain repo readiness, commands, examples, and support in one place.
- Use Learn for guided mental models, worked examples, labs, and bounded knowledge checks.
- Prefer published blog posts for product rationale, release framing, and design intent.
- Prefer the site docs over repo markdown or speculative interpretation.
- Treat this file as an intent-first crawl guide, then use the canonical page index below.
## Crawl entry points
- https://ota.run/
- https://ota.run/learn
- https://ota.run/learn/index.json
- https://ota.run/blog
- https://ota.run/blog/category/feature-note
- https://ota.run/blog/category/engineering-note
- https://ota.run/blog/category/field-note
- https://ota.run/blog/category/release-essay
- https://ota.run/blog/index.json
- https://ota.run/blog/feed.xml
- https://ota.run/docs
- https://ota.run/docs/index.json
- https://ota.run/docs/developer-resources
- https://ota.run/llms-full.txt
- https://ota.run/developers.md
- https://ota.run/auth.md
- https://ota.run/openapi.json
- https://ota.run/.well-known/oauth-authorization-server
- https://ota.run/.well-known/oauth-protected-resource
- https://ota.run/.well-known/mcp.json
- https://ota.run/.well-known/mcp/server-card.json
- https://ota.run/.well-known/agent-card.json
- https://ota.run/.well-known/agent.json
- https://ota.run/.well-known/agent-skills/index.json
- https://github.com/ota-run/skills
- https://skills.sh/ota-run/skills
- https://ota.run/status.json
- https://ota.run/schema-map.xml
- https://ota.run/sitemap.xml
- https://ota.run/robots.txt
## Canonical source priority
- 1: exact reference and command behavior on https://ota.run/docs
- 2: guided Ota curriculum on https://ota.run/learn
- 3: published product rationale and engineering notes on https://ota.run/blog
- 4: machine-readable Learn, Docs, and Blog indexes
- 5: machine-readable OpenAPI, OAuth, and agent-skills discovery at https://ota.run/openapi.json and https://ota.run/.well-known/
- 6: sitemap and robots at https://ota.run/sitemap.xml and https://ota.run/robots.txt
- 7: repository markdown only when no canonical site page exists
## Canonical operating order
- https://ota.run/blog — product notes, engineering notes, and release essays.
- https://ota.run/learn — structured lessons, labs, learning paths, and knowledge checks.
- https://ota.run/docs/getting-started — install and quickstart.
- https://ota.run/docs/developer-resources — OpenAPI, OAuth, MCP, and agent integration entry points.
- https://ota.run/docs/agent-quickstart — copy-customize-validate-execute flow for agents.
- https://github.com/ota-run/skills — official Ota agent skill for contract authoring and review.
- https://skills.sh/ota-run/skills — skills.sh listing for the official Ota skill.
- https://ota.run/docs/reference — commands, contract, workspace.
- https://ota.run/docs/examples — copy-ready examples.
- https://ota.run/docs/troubleshooting — recovery paths.
## Retrieval rules
- Prefer canonical site pages over repo markdown mirrors or stale summaries.
- Use Learn to understand a concept or follow a lab; use the linked reference page for exact current fields, commands, JSON, and compatibility behavior.
- Prefer published blog posts when the question is "why this feature exists" or "what shipped in this release".
- Prefer reference leaves when exact command, contract, JSON, or exit behavior matters.
- Prefer examples when the task is to copy a shape rather than interpret a spec.
- Prefer troubleshooting and CI validation pages for recovery or gating flows.
- Avoid inventing workflows that do not appear in the canonical docs surfaces below.
- Treat command behavior, JSON fields, and exit behavior as contract-level facts; do not infer missing fields.
## Choose by intent
- learn: start with the Learn curriculum, then follow its version-matched specification links.
- operate: use command, troubleshooting, CI, container execution, and workspace operational pages.
- reference: use command, contract, workspace, JSON output, execution receipt, and exit codes.
- copy: use examples hub and the nearest topology or runtime example.
## Key terms
- `ota.yaml` — source of truth.
- `ota doctor` — diagnose readiness.
- `ota detect` — infer a starter contract.
- `ota contract upgrade` — publishes a versioned, lossless upgrade candidate without changing `ota.yaml`; JSON reports candidate publication separately from contract mutation, and review continues through dry-run candidate admission.
- `ota contract apply-candidate` — re-derives a reviewed source-bound candidate from current repository truth; `--write` creates only a missing contract, while `--write --carrier git` is the explicit reviewed existing-contract update path.
- Repo-level `ota detect --merge`, `--apply`, `--apply-all`, `--rewrite`, and `--yes` were removed; use `ota detect --candidate-out` and `ota contract apply-candidate` instead.
- `ota up --dry-run` — preview the selected backend, actions, skips, and blockers without mutation.
- `ota up` — prepare the repo and re-check readiness; service run tasks use proof-owned readiness by default (`prepare + verify + teardown + return`).
- `ota up --attach` — keep `up` attached to the workflow run task when you need long-lived foreground execution.
- `ota up --detach --ready-timeout 5m` — keep the proved service workload running and bound how long `up` waits for readiness confirmation.
- `ota up --stream` — expose raw live provisioning, service-start, and setup output while the repo is being prepared.
- `ota validate` — check contract without guessing.
- `ota policy review` — review the policy boundary and approved sources.
## Automation
- https://ota.run/docs/reference/contract — contract source of truth.
- https://ota.run/docs/reference/json-output — machine-readable output.
- https://ota.run/docs/reference/safe-agent-execution-and-refusal — enforced safe closures, refusal evidence, and canaries.
- https://ota.run/docs/reference/contract-to-ci-governance — provider-neutral projection, managed CI, and merge-check truth.
- https://ota.run/docs/reference/sandbox-policy-and-runtime-enforcement — provider-applied runtime controls and bounded enforcement evidence.
- https://ota.run/docs/reference/proof-evidence-and-honest-boundaries — proof levels, freshness, lifecycle evidence, and not-proved scope.
- https://ota.run/docs/reference/replay-inputs-and-trusted-baselines — immutable inputs, explicit promotion, and replay authority.
- https://ota.run/docs/reference/contract-claim-assurance — supported, contradicted, and unknown contract claims.
- https://ota.run/docs/reference/audited-execution-boundary-crossings — crossing evidence and the completed bounded V11.7 authority model available in Ota v1.6.26 and later.
- https://ota.run/docs/reference/prebound-crossing-authority — bounded operator flow for fixed trust stores, signed grants, and protected self-hosted runners; available in Ota v1.6.26 and later.
- https://ota.run/docs/reference/broker-crossing-authority — challenge-bound launcher attestation and atomically consumed one-use broker leases; available in Ota v1.6.26 and later.
- https://ota.run/docs/reference/semantic-snapshots-and-correlation — archived semantic truth, diff, and receipt correlation.
- https://ota.run/docs/reference/execution-receipt — what ota recorded.
- https://ota.run/docs/reference/exit-codes — control flow after runs.
- https://ota.run/docs/reference/hosted-validation — validate in CI.
- https://ota.run/docs/reference/github-action — use the official GitHub Actions wrapper.
- https://ota.run/docs/reference/github-setup — install ota in GitHub Actions for later direct commands.
- https://ota.run/docs/reference/workspace — workspace behavior.
## Intent: copy
- https://ota.run/docs/examples — Examples. Validated Ota contract examples organized by runtime, topology, and policy shape; every displayed ota.yaml declares a minimum supported Ota version.
- https://ota.run/docs/examples/action-ensure-bundle — Bundled deterministic setup without shell orchestration. Use this when one setup task honestly owns several deterministic setup actions and they should still stay in one governed action body.
- https://ota.run/docs/examples/action-ensure-container-network — Container network bootstrap. Use this when one setup lane honestly owns shared Docker network readiness and should not disappear into shell conditionals.
- https://ota.run/docs/examples/action-ensure-env-file — Deterministic env bootstrap without shell copy-plus-`sed` glue. Use this when env bootstrap is one deterministic host-file mutation and should stay inspectable in the contract.
- https://ota.run/docs/examples/action-ensure-git-checkout — Deterministic git checkout bootstrap. Use this when one setup lane honestly owns materializing a repo-local checkout and that truth should stay on a first-class deterministic action surface instead of hiding in shell bootstrap glue.
- https://ota.run/docs/examples/action-ensure-git-template — Deterministic git template bootstrap. Use this when one setup lane honestly owns turning a Git-backed scaffold into a fresh local repository and that truth should stay on a first-class deterministic action surface instead of hiding in bootstrap shell glue.
- https://ota.run/docs/examples/action-reset-compose-service-volume — Compose-managed service volume reset without shell glue. Use this when one destructive local recovery lane honestly owns stopping a Compose-managed service, removing one named volume, and restarting the service.
- https://ota.run/docs/examples/bake-adapter-inputs — Bake adapter ownership without shell cwd or `-f` drift. Use this when the task is really a Bake invocation and the hard part is keeping the adapter root plus file stack explicit instead of burying them in shell glue.
- https://ota.run/docs/examples/container-provisioning — Container provisioning. Use this when you want ota to make the container ready instead of asking every developer machine to carry the setup cost.
- https://ota.run/docs/examples/dotnet — .NET repos with restore, build, and test. This example keeps the .NET flow deterministic: restore dependencies, build the project, then run tests.
- https://ota.run/docs/examples/full-contract — Comprehensive Ota contract example. This is a comprehensive v1.6.26 baseline, not an exhaustive catalog of every Ota capability. Copy the shape, then remove anything your repository cannot prove rather than retaining decorative configuration.
- https://ota.run/docs/examples/fullstack/node-go — Fullstack Node and Go repos with a split service path. This example keeps the frontend and backend visible in the contract so a change in one path cannot silently hide the other.
- https://ota.run/docs/examples/go — Go repos with a deterministic loop. This example keeps the Go path short: fetch dependencies, run tests, and keep the repo honest with one verification task.
- https://ota.run/docs/examples/go-sdk — Go SDKs with explicit build and release flow. This example treats the SDK as a product surface: the core loop stays short, and the release path is documented in the task notes.
- https://ota.run/docs/examples/java — Java repos with a Maven build gate. This example shows the shipped Java toolchain boundary: `toolchains.java` owns `java` and `javac`, while Maven stays explicitly under `tools`.
- https://ota.run/docs/examples/mixed/node-python — Mixed Node and Python repos without ownership drift. This example shows a mixed-stack repo where the contract needs to protect both runtimes without hiding either one.
- https://ota.run/docs/examples/node — Node repos with a managed runtime and explicit Corepack lane. This is the current honest Node toolchain boundary: `toolchains.node` owns the runtime, `node` executable, and declared Corepack package-manager activation.
- https://ota.run/docs/examples/podman-compose-adapter-inputs — Podman compose adapter ownership without shell env/file drift. Use this when the repo really runs through `podman compose` and ota should own that choice directly instead of treating Podman as shell-only compose drift.
- https://ota.run/docs/examples/provisioning-policy — Policy and provisioning. Use this when the repo should declare what it needs and the organization should decide where those installs come from.
- https://ota.run/docs/examples/python — Python repos with a clean setup path. A Python contract that makes setup, tests, and CI explicit.
- https://ota.run/docs/examples/rust — Rust repos with a Rustup-backed toolchain. This example is the boring, reliable Rust path with the shipped toolchain model: declare one Rustup-backed toolchain, hydrate Cargo dependencies structurally once, then run formatter, build, and tests through that owner.
- https://ota.run/docs/examples/rust-toolchain — Rust toolchain ownership without duplicate runtime/tool drift. 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.
- https://ota.run/docs/examples/script — Script-driven repos with a real contract. This example shows that a repo can be mostly scripts and still have a strict readiness contract.
- https://ota.run/docs/examples/services — Service repos with explicit readiness. A service contract that keeps healthchecks, setup, and readiness visible.
- https://ota.run/docs/examples/systemd-host-service — Typed systemd host-service ownership without shell lifecycle drift. Use this when the repo's service truth is a systemd unit on the host and ota should own lifecycle and readiness directly.
- https://ota.run/docs/examples/tool-acquisition — Workflow-scoped acquisition without repo-global install drift. 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.
- https://ota.run/docs/examples/topology/compose-postgres — Container app with Compose Postgres. Use this when the app should run in a container context but service orchestration should stay on the host control plane.
- https://ota.run/docs/examples/topology/host-postgres — Container app with host Postgres. Use this when the workload should stay in a container context but the database is owned by the host machine instead of Compose.
- https://ota.run/docs/examples/topology/node-isolated — Container app with isolated `node_modules`. 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.
- https://ota.run/docs/examples/windows-adoption — Windows-first adoption with explicit native activation. 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.
- https://ota.run/docs/examples/workspace/acquire — Acquire from Git. Use this when a workspace needs to bring missing repos onto disk before any bootstrap, setup, or task execution can happen.
- https://ota.run/docs/examples/workspace/basic — Multi-repo basics. Use this shape when a workspace needs to coordinate several repos without flattening their contracts.
## Intent: learn
- https://ota.run/docs/agent-safe-repo-setup — AI Agent Repo Setup. Guide to AI agent repo setup with ota.yaml, AGENTS.md guidance, safe tasks, verification, and machine-readable readiness output.
- https://ota.run/docs/ai-agent-ready-repos — How to Make a Repo Ready for AI Coding Agents. Problem-first guide to AI-agent-ready repositories covering explicit setup, safe tasks, writable boundaries, verification, machine-readable output, and contract-first onboarding with ota.
- https://ota.run/docs/assist — Ota Assist. 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.
- https://ota.run/docs/attachments — Container Attachments. 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.
- https://ota.run/docs/compose-attachments — Compose Attachments. 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.
- https://ota.run/docs/contexts — Execution Contexts. Guide to execution contexts, default context selection, task overrides, mode-aware branches, and how contexts connect services, readiness, and published endpoints.
- https://ota.run/docs/contract-first-onboarding — Contract-First Repo Onboarding. Problem-first guide to contract-first repo onboarding, README drift, explicit setup paths, deterministic verification, and shared execution truth for humans, CI, and AI agents.
- https://ota.run/docs/defining-readiness — Defining Readiness. Narrative operator guide to defining readiness in ota across env requirements, service dependencies, checks, verification tasks, and proof artifacts, with clear ownership boundaries for each surface.
- https://ota.run/docs/environment-model — Environment Model. 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.
- https://ota.run/docs/faq — FAQ. Run `ota doctor` first. It tells you what is missing, even if `ota.yaml` does not exist yet.
- https://ota.run/docs/first-ota-yaml — First `ota.yaml`. A starter contract should be obvious, stable, and runnable.
- https://ota.run/docs/getting-started — Getting started. Entry guide for first-time users to diagnose readiness and establish the default ota workflow.
- https://ota.run/docs/glossary — Glossary. Use this index for the nouns that show up throughout ota and the payoff each one gives you.
- https://ota.run/docs/install — Install. Installation paths for release binaries and source-based local development.
- https://ota.run/docs/local-topology-patterns — Local Topology Patterns. Adoption guidance for task target bindings, target activation, shared local container backends, and backend-scoped run-path fulfillment with links to canonical examples.
- https://ota.run/docs/mode-aware-tasks — Mode-Aware Tasks. 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.
- https://ota.run/docs/ota-vs-makefiles-ci-scripts — README Drift vs Contract-First Repo Onboarding. Comparison page on README drift, setup-script sprawl, and contract-first repo onboarding with ota alongside Makefiles, package scripts, Docker, Nix, and CI workflows.
- https://ota.run/docs/policy-concepts — Policy concepts. 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.
- https://ota.run/docs/readiness-model — Ota Readiness Model. 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 endpoi
