Generate a Sondage Manifest

Define and validate the manifest contract that powers Sonde runners and downstream report tooling.

Purpose

A simple, machine-readable contract that describes CLI identity, scenarios, expected behavior, and scoring weights. It is designed for AI-native CLIs and intended to be reusable as a shared standard.

Inputs

Target CLI binary accessible from environment.
Help text from root and subcommands.

Outputs

sondage.manifest.json with validated manifest structure.
Global options and command-level options for runtime preference selection.
JSON Schema id: https://sonde.dev/schemas/stm-manifest-v1.schema.json.

Versioning and compatibility

Manifest version is strict semantic versioning (major.minor.patch).
Sonde currently supports manifest major version 1 (for example 1.0.0, 1.1.0).
A manifest with unsupported major version fails loading with UNSUPPORTED_VERSION.
Additive, backward-compatible fields should increment minor; breaking changes must increment major.

Key flow

Probe <cli> --help.
Probe each discovered subcommand with --help.
Generate the manifest contract and write sondage.manifest.json.
Validate manifest on load before run, score, or serve.

Deterministic examples

Generate:

sonde generate vercel --json

Typical JSON response shape:

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "generate",
  "cli": "vercel",
  "result": {
    "manifest": {
      "version": "1.0.0"
    },
    "outputPath": "sondage.manifest.json",
    "commandCount": 0
  }
}

Edge cases

Help probing uses a per-command timeout.
Subcommand discovery quality depends on target CLI help formatting.
run and score consume manifest.cli.binary, not the <cli> argument.