Typical signals

the runtime, package manager, and dependency hydration have one typed owner
service exposure and readiness are declared instead of inferred from launch logs
finite verification, long-running launch, workflow selection, and agent boundaries remain separate

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 readiness, setup, and execution explainable in receipts and diagnostics

Example contract

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.

It demonstrates how major v1.6.26 surfaces fit together: toolchains, prepare, command, aggregate, launch, surfaces, readiness, workflows, and agent. Use focused, version-matched examples for capabilities outside this scenario.

ota.yamlyaml

version: 1metadata:  ota:    minimum_version: "1.6.27"project:  name: full-contract  description: Comprehensive example of major Ota v1.6.26 contract surfacestoolchains:  node:    version: "22"    package_managers:      pnpm: "10"    fulfillment:      source: corepack      mode: runexecution:  default_context: host  contexts:    host:      backend: nativeenv:  vars:    APP_ENV:      default: local      allowed:        - local        - ci    DATABASE_URL:      required: true  sources:    - kind: dotenv      path: .env.localsurfaces:  app:    kind: http    label: Application preview    purpose: Browser-facing local development service    visibility: internal    port: 3000    path: /health    readiness:      kind: http      path: /health      timeout: 10sreadiness:  probes:    app-ready:      kind: http      target:        kind: task        name: dev        listener: app        address_view: host      path: /health      timeout: 10000tasks:  setup:    description: Hydrate dependencies through the declared pnpm lane    prepare:      kind: dependency_hydration      medium: package_dependencies      source:        kind: node_package_manager        cwd: .        manager: pnpm        mode: install        frozen_lockfile: true    requirements:      toolchains:        - node    effects:      writes:        - node_modules      network: true      network_kind: dependency_hydration  lint:    command:      exe: pnpm      args:        - lint    depends_on:      - setup    requirements:      toolchains:        - node  test:    command:      exe: pnpm      args:        - test    depends_on:      - setup    requirements:      toolchains:        - node  verify:    description: Run the finite verification closure after a change    aggregate:      tasks:        - lint        - test  dev:    description: Start the local application service    launch:      kind: command      exe: pnpm      args:        - dev        - --host        - 127.0.0.1        - --port        - "3000"    depends_on:      - setup    requirements:      toolchains:        - node    runtime:      kind: service      surfaces:        - appworkflows:  default: verify  verify:    intent: validation    setup:      task: setup    run:      task: verify  development:    intent: local_development    setup:      task: setup    run:      task: dev    readiness:      surfaces:        - app    exposes:      - surface: appchecks:  - name: node-installed    kind: precondition    severity: error    run: node --version  - name: app-ready    kind: health    severity: warn    probe: app-readyagent:  entrypoint: setup  default_task: verify  safe_tasks:    - setup    - lint    - test    - verify  verify_after_changes:    - verify  writable_paths:    - src    - tests    - docs    - node_modules  protected_paths:    - ota.yaml    - .env.local  notes: |    Start with `ota doctor`, then use `ota up --workflow development` for the service path.    Use `ota run verify --agent` after changes; do not add service startup to the finite verification task.