Troubleshooting

• 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 status as RUNNABLE, RUNNABLE WITH WARNINGS, or BLOCKED before deciding whether to execute or edit.
• Use ota doctor --fix --dry-run to preview the current contract-aware safe repo-hygiene fix surface before writing; today that means .gitignore hygiene for .ota/state/ and .ota/receipts/ on repos that already have a valid ota.yaml.
• When doctor reports env blockers, run ota env before you change shell values or declared sources so the active precedence is visible first.
• When doctor reports an unverifiable required service, use ota assist declare-readiness if the service already has a truthful start path, or ota assist declare-service if the managed service shape itself is still incomplete.
• When doctor reports a missing-file precondition, use ota up or ota run setup if tasks.setup already exists, or add that setup path with ota assist wire-setup if the contract is still missing it.
• When doctor reports a taskless contract, review ota detect --dry-run before you write inferred tasks, and use ota assist add-task only when the right fix is one explicit runnable task.
• Run ota validate when the contract is malformed.
• Use ota tasks --json when you want a machine-readable inventory.
• Use ota run --debug <task> when execution needs tracing.

ota validateota doctorota doctor --fix --dry-runota tasks --jsonota run --debug test

Explicit paths should point at the repo you mean. If they do not, start there before assuming the contract is wrong.

ota doctor /path/to/repocd /path/to/repo && ota doctor