FAQ

Run ota doctor first. It tells you what is missing, even if ota.yaml does not exist yet.

ota doctor --plainota detect --dry-runota detect --contractota init --dry-run

Use plain task execution when tasks are independent and do not need declared service targeting or one intentional shared backend boundary.

Use target binding when one task just needs to reach another service by declared identity.

Use a shared backend when the backend boundary itself matters: multiple long-running tasks should intentionally reuse one ota-owned execution boundary for lifecycle, fulfillment, and truthful co-location semantics.

If the tasks are independent and only talk through normal published endpoints, target binding is usually the simpler and more honest model.

No. Each depends_on task runs as its own task with its own resolved execution boundary.

If the parent task resolves to a backend and the dependency truthfully supports that same plane through execution.default_mode or execution.modes.<mode>, ota keeps the dependency on that plane for the invocation instead of silently falling back to the dependency's canonical default.

A dependency only helps the parent through durable shared surfaces such as repo files, shared caches, external services, or one real persistent/shared backend boundary.

Do not rely on depends_on to carry shell state, exported variables, or one-off ephemeral container setup into the parent task unless both tasks intentionally reuse the same durable execution boundary.

Yes. Run-scoped execution overrides such as --ephemeral, --persistent, --mode, --native, and --container apply to the whole task graph for that invocation, including depends_on tasks.

That means the dependency and the requested task resolve under the same invocation override, but they still execute as separate tasks rather than one shared shell or session.

If the override changes the real execution boundary, only durable shared surfaces still carry value across the dependency edge. For container tasks, that includes explicit attachment-backed dependency paths such as attachments.isolated_paths: [.m2] when the tool is configured to use /workspace/.m2 instead of its default container-local cache path.

requirements declare what the environment needs.

fulfillment declares whether ota should try to make that true on the run path.

That separation keeps diagnosis, contract truth, and runtime mutation explicit instead of guessing that every declared requirement should be installed automatically.

Because matching contexts do not automatically mean the tasks should share one backend boundary.

An explicit shared backend gives ota one declared place to own reuse, readiness reachability, fulfillment, publication conflict checks, and later broader backend families without guessing.

The repo contract says what the repo needs.

Org policy says what sources and versions are approved to satisfy that need.

With strict_versions: true, policy can also reject an already-installed version that satisfies the repo but is not compliant with org standards.

Because activation is a policy choice, not something ota should guess from topology alone.

ensure_started, restart_ready, ensure_running, and ensure_ready only claim producer startup where ota can own reuse, observation, and cleanup honestly.

That keeps target truth, explicit overrides, and startup behavior separate instead of turning every target reference into implicit orchestration.

Use ssh when you already reach a normal remote machine through OpenSSH and want ota to follow your existing SSH config and agent behavior.

Use tsh when the remote host is reached through Teleport-managed SSH access. Use kubectl when the workload lives in a pod-local execution plane you already operate through Kubernetes. Use daytona when the boundary is a Daytona-managed remote workspace.

Choose the provider that already matches the real operational boundary. Do not force a pod into ssh semantics or a normal host into Kubernetes semantics just to make the contract look uniform.

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 want ota to read that policy directly.

# repo-local policy fileexport OTA_POLICY=.ota/org-policy.yaml# or central policy URL# export OTA_POLICY=https://policies.example.com/ota-org.yamlota doctor --json

OTA_POLICY wins first.

If that is not set, ota reads the nearest ancestor .ota/org-policy.yaml.

If the workspace declares workspace.policy, ota uses that as the workspace-level fallback.

If none of those exist, ota continues without org policy.

OTA_POLICY=/tmp/policy.yaml ota doctor --jsonota doctor --json | grep -n "policy_source"

Task env wins for the task that declares it.

Otherwise ota uses policy, then the shell environment, then declared env sources, then the contract default.

PATH is special because ota can prepend and append directories around the chosen base value.

default provides the safe fallback, and allowed still constrains the winning value no matter which layer supplied it.

# task contextota env --task buildOTA_TOKEN=override ota env --task buildota env --task build --json

No. It is a repo-readiness system and execution contract.

No. Commands like ota detect and ota init are explicit about when they write. Review first, then write.

No. It makes scripts explicit, reviewable, and easier to run consistently.

Yes. Container execution is a first-class repo mode when the contract calls for it.

It checks readiness against the declared container target, including backend availability, image-level runtimes and tools, and whether the supported provisioning adapters can actually satisfy the declared pins there.

Use ota doctor --container as the shorthand for --mode container, and add --ephemeral or --persistent when you want the diagnosis and rerun guidance to stay pinned to that selected container lifecycle.

It does not pretend host-bound diagnosis is the same thing. Host env checks, host-local diagnosis, and full repo cleanup semantics still live on the native side.

Today it means fresh backend-backed task execution where the command supports it, especially ota run <task> and the setup phase inside ota up.

It does not yet mean full repo teardown, host diagnosis isolation, or ephemeral healthchecks across every command surface. Use ota clean when a persistent container-backed run needs a manual reset after a hard stop or stale state.

No. provisioning.platforms chooses the adapter for the target OS first, then adapter_bootstrap tells ota how it may install that adapter if it is missing.

For example, a Windows tool can resolve to source: choco, and ota then looks up adapter_bootstrap.choco without another platform layer.

Policy can declare many approved sources overall, but ota resolves one effective source per runtime or tool on the current target.

For example, node can resolve to brew on macOS, apt on Linux, and choco on Windows through platforms overrides.

That is not the same as ota trying several adapters on one machine and picking a winner at runtime.

Use ota doctor when you need the current blockers and the highest-priority next step.

Use ota explain when you want those findings turned into an ordered remediation plan.

Use ota receipt when you need the same readiness scan packaged as a read-only artifact for CI, archiving, or automation.

Use ota doctor to diagnose blockers, ota up to prepare the selected workflow, and ota run to execute one declared task.

Use ota proof runtime when someone needs evidence that one workflow really started and reached readiness on a clean boundary, not just that the contract validates or a preview looks runnable.

That is the right lane for setup/runtime pull requests, clean-machine CI proof, and reviewer or agent workflows that need artifact-backed success or failure evidence under .ota/proof/<workflow>/.

Because a contract can depend on fields or semantics that an older ota binary does not understand honestly.

That gate fails early with an explicit upgrade lane instead of letting a stale binary validate, preview, or run against a contract it cannot interpret correctly.

Use it when the contract truly depends on newer ota behavior, not as a decorative version pin.

agent.posture declares the authority model for automation before an agent edits or runs anything.

Use readiness_strict for normal repo-readiness slices. Use broader postures only when the contract intentionally allows contract or infra authoring as part of the work.

It does not replace agent.writable_paths or agent.protected_paths; it tells ota how strict the boundary should be interpreted.

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 files, effects.adapter_state when durable state is adapter-owned rather than repo-owned, effects.network when it depends on network access, and effects.external_state when it changes state outside the repo boundary.

That makes review, automation, and agent safety more honest before a task runs.

Because semver alone is not enough when CI, source builds, and newer contract features all exist at the same time.

Those fields let automation distinguish a released binary from a local source build, tie the current binary to an exact commit, and see which additive contract features it claims to support.

Use that surface when version identity or capability support needs to be machine-checkable instead of inferred from text.

No. Some repo commands support repeated --member values, but not all of them.

ota explain is single-target only, while commands such as tasks, services, doctor, check, run, up, and clean can group repeated member results when the command contract allows it.

A repo contract describes one repo. A workspace contract coordinates multiple repos without flattening their truth into one file.

No. The current wedge is the repo contract and readiness loop. Enterprise comes later.

Yes. The same contract drives human diagnosis, task execution, and agent guidance.