Skip to content

Contracts

Purpose

This section defines the public behavior promises that the repository is willing to treat as binding. These are not explanations of implementation shape. They are the promises users, automation, and integrations may rely on.

flowchart TD
    A[Public behavior] --> B[Documented contract]
    B --> C[Test and review evidence]
    C --> D[Compatibility promise]

This diagram shows the contract ladder for the whole section. Public behavior becomes a contract only when it is documented and backed by reviewable evidence, which is what turns it into a compatibility promise.

mindmap
  root((Contracts))
    Interface
      command identity
      flags
      exit codes
    Output
      success envelope
      error envelope
      stream routing
    Plugins
      namespace
      lifecycle
      trust and limits
    Distribution
      package naming
      binary ownership
    Change policy
      deprecation
      schema evolution

The mindmap groups the contract surfaces by domain so readers can quickly tell whether their question is about interface identity, output, plugins, or distribution ownership.

Read This Set In Order

  1. Interface And Compatibility
  2. Output And Stream Contracts
  3. Plugin Contracts
  4. Distribution And Ownership

Scope

These pages are intentionally normative:

  • they define what is promised, not merely what exists today
  • they should be smaller and more stable than guides or architecture docs
  • unsupported behavior should be named as unsupported, not implied as stable

Machine-Readable Contract Assets

These files are part of the kept contract surface and should be reviewed alongside the markdown pages when a contract changes. The canonical source of truth lives under contracts/. The documentation site publishes copies under its contracts/ path:

  • contracts/schemas/output-envelope-v1.schema.json
  • contracts/schemas/error-envelope-v1.schema.json
  • contracts/schemas/plugin-manifest-v2.schema.json
  • contracts/official_product_namespace_registry.json
  • contracts/product_mount_metadata_contract.json

Next Step

If you need implementation shape, go to Architecture. If you need exact lookup tables, go to Reference.