Command help for 0.12.7

sonny is an interactive CLI tool for testing and running prompt recipes
with various LLM providers. It supports Language Server Protocol (LSP) integration,
agent management, and comprehensive tool execution.

Usage:
  sonny [flags]
  sonny [command]

Available Commands:
  a2a              Agent-to-Agent (A2A) protocol commands
  arch             Architecture DSL evaluation
  bench            Benchmark harnesses for `sonny recipe eval` / `sonny recipe optimize`
  canary           Embedded Canary: requirement migration and test evidence
  capabilities     Report which toolchain capabilities this project needs and which are usable
  catalog          Manage the installable model-catalog registry
  commitmsg        Validate commit messages against the Conventional Commit + work-item policy (ENG-4428)
  completion       Generate the autocompletion script for the specified shell
  config           Manage configuration
  conformance      Run the conformance harness, qualification matrix, and release dossier
  context          Inspect, validate, and assemble context-efficiency data
  context-stats    Summarize context-efficiency metrics for a session or time range
  context-validate Verify context-efficiency invariants for a session
  control          Inspect Sonny's authority control plane
  credentials      Inspect credential resolution and manage the OAuth credential migration to the credential broker
  cue              Plan, import, run, analyze, and report context-use evaluations
  editor-rpc       Serve a JSON-RPC editor client of the supervisor over stdin/stdout
  freeze           Contain a tenant with a signed freeze epoch
  help             Help about any command
  hooks            Inspect and validate the session hooks configuration
  init             Initialize sonny's directories and example config
  isolation        Inspect and verify session isolation
  lsp              Inspect and validate Language Server Protocol configuration
  mcp              Inspect resolved MCP server and tool configuration
  mcp-server       Run Sonny tools or a traced external MCP proxy over stdio
  mesh             Distributed mesh session management
  models           Inspect and manage model categories, fitness, and pricing
  policy           Validate, inspect and control DPolicy decision policies
  precommitci      Run the authoritative CI pre-commit/commit-range gates (ENG-4429)
  prompt           Display the rendered system prompt for a recipe
  recipe           Manage recipes and git-backed recipe sources
  routing          Inspect routing decisions and evaluation evidence
  run              Run interactive chat with a prompt recipe
  session          Run deterministic full-session evaluation and optimization
  supervisor       Manage the supervisor daemon: ensure, serve, status, stop
  tools            List and manage available tools
  trace            Inspect conversation traces without opening the JSONL files by hand
  training         Aggregate and export conversation traces as training data
  update           Manage signed Sonny application updates
  variant          Sync and inspect upstream model-variant bundles
  version          Print version information, the license, the changelog, or SCA build info
  workspace        Grant, revoke, or inspect workspace trust
  worktrees        Manage the Git worktrees Sonny creates for delegated child agents

Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
  -h, --help                   help for sonny
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -v, --version                version for sonny
  -C, --workdir string         working directory (default ".")

Use "sonny [command] --help" for more information about a command.

Serve sonny as an A2A agent, render its AgentCard, or call a remote A2A agent.

Usage:
  sonny a2a [command]

Available Commands:
  call        Send a single SendMessage RPC to a remote A2A agent
  card        Print the A2A AgentCard sonny would advertise
  serve       Serve sonny as an A2A endpoint (jsonrpc + rest + sse + discovery)

Flags:
  -h, --help   help for a2a

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny a2a [command] --help" for more information about a command.

Send a single SendMessage RPC to a remote A2A agent

Usage:
  sonny a2a call [flags]

Flags:
      --allow-insecure-token    allow sending the --token-file token over plain http:// to a non-loopback host (isolated networks only)
      --card                    fetch the remote AgentCard instead of sending a message
      --discovery-base string   remote base URL for --card
      --endpoint string         remote A2A JSON-RPC URL (e.g. http://host:port/a2a/jsonrpc)
  -h, --help                    help for call
      --text string             message text (default "hello")
      --token-file string       file holding the bearer token the remote a2a serve --auth-token-file requires

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the A2A AgentCard sonny would advertise

Usage:
  sonny a2a card [flags]

Flags:
      --base-url string      externally reachable base URL (default "http://localhost:8080")
      --description string   agent description (default "sonny pack-driven coding agent")
  -h, --help                 help for card
      --name string          agent name (default "sonny")
      --push                 advertise push-notification capability
      --streaming            advertise streaming capability (default true)
      --version string       agent version (default "dev")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Serve sonny as an A2A endpoint (jsonrpc + rest + sse + discovery)

Usage:
  sonny a2a serve [flags]

Flags:
      --auth-token-file string       file holding the bearer token every request but the agent card must send (Authorization: Bearer <token>); required with --shell-mode
      --base-url string              externally reachable base URL for the AgentCard (default "http://localhost:8080")
      --bind string                  address to listen on (default ":8080")
      --deny-tool stringArray        with --shell-mode: tool handle the shell-mode permission gate must refuse even though --shell-mode grants it (repeatable; deny wins)
  -h, --help                         help for serve
      --isolation-assurance string   minimum shell-mode isolation assurance
      --isolation-backend string     required shell-mode isolation backend
      --isolation-machine string     absolute trusted isolation machine configuration for shell mode
      --isolation-policy string      absolute trusted isolation policy file for shell mode
      --llm-api-key string           LLM provider API key
      --llm-base-url string          LLM provider base URL
      --model string                 LLM model id (required)
      --name string                  advertised agent name (default "sonny")
      --no-auth                      permit unauthenticated requests (dev only; refused with --shell-mode)
      --no-auth-unsafe-remote        acknowledge and allow unauthenticated A2A requests on a non-loopback address
      --provider string              LLM provider id (openai | openai-compatible) (default "openai-compatible")
      --shell-mode                   interpret every SendMessage prompt as a shell command (mesh-exec orchestration)
      --shell-mode-unsafe-remote     acknowledge and allow --shell-mode to bind a non-loopback address; shell-mode executes incoming A2A prompts as shell commands and must only be exposed off-loopback in an isolated, authenticated deployment
      --system-prompt string         system prompt applied to every turn

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Architecture DSL evaluation

Usage:
  sonny arch [command]

Available Commands:
  advise       Report architecture style, coupling and complexity as advice
  eval         Run the bootstrap-only architecture-DSL promotion gate
  requirements Check that every requirement token has implementation and test evidence

Flags:
  -h, --help   help for arch

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny arch [command] --help" for more information about a command.

Report architecture style, per-package external fan-out and per-function cyclomatic complexity over a source tree, plus every edge the analysis could not resolve. Every finding is advice: the command exits 0 whenever it ran, however much it reported. It exits 3 when a root or document cannot be read and 2 on a malformed invocation.

Usage:
  sonny arch advise [flags]

Flags:
      --arch string                optional .arch document to classify
      --complexity-threshold int   report functions at or above this cyclomatic count (default 20)
      --fan-out-threshold int      report packages at or above this external import count (default 12)
  -h, --help                       help for advise
      --json                       emit the report as JSON
      --max-edges int              maximum edges to report (default 40000)
      --max-files int              maximum source files to walk (default 8000)
      --root string                source tree to analyze (default ".")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run the bootstrap-only architecture-DSL promotion gate

Usage:
  sonny arch eval [flags]

Flags:
      --corpus string   corpus JSON path
  -h, --help            help for eval
      --runs int        number of isolated bootstrap-only runs (minimum 2) (default 2)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Resolve every requirement token in the manifest against the source tree. A token whose implementation or test binding is missing or does not resolve is unproven and fails the command with exit 9; the output names the token and which half is missing. With --test-events a token is verified only when its declared tests passed in the supplied go test -json run. Exit 3 when the manifest or the root cannot be read or parsed, 2 on a malformed invocation.

Usage:
  sonny arch requirements [flags]

Flags:
  -h, --help                 help for requirements
      --json                 emit the result as JSON
      --manifest string      requirement manifest path (default "docs/assurance/requirements/manifest.yaml")
      --root string          repository root the bindings resolve against (default ".")
      --test-events string   optional go test -json stream proving the declared tests passed

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Benchmark harnesses for `sonny recipe eval` / `sonny recipe optimize`

Usage:
  sonny bench [command]

Available Commands:
  campaign    Verify and print a frozen benchmark-campaign document (mpr/v1/benchmark-campaign)
  catalog     The embedded benchmark catalog and its adapter wiring
  conformance Sonny-specific conformance contracts and the tests that cover them
  exec        Run one benchmark task through the headless agent and write a result document
  scorecard   Score a sonny-bench-result/v1 ledger: both denominators, pass@k, pass^k, cost, latency and budget
  security    Inspect security benchmark decisions, verify manifests and score independent grades
  skillopt    SkillOpt-Lite benchmark splits as pack-eval suites (see packs/skillopt/README.md)

Flags:
  -h, --help   help for bench

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny bench [command] --help" for more information about a command.

Verify and print a frozen benchmark-campaign document (mpr/v1/benchmark-campaign)

Usage:
  sonny bench campaign [command]

Available Commands:
  show        Print the frozen arms, benchmarks, split policy and promotion rule of a campaign
  verify      Recompute a campaign document's digest, and optionally bind it to its frozen preregistration

Flags:
  -h, --help   help for campaign

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny bench campaign [command] --help" for more information about a command.

Print the frozen arms, benchmarks, split policy and promotion rule of a campaign

Usage:
  sonny bench campaign show <campaign.json> [flags]

Flags:
      --format string   text or json (default "text")
  -h, --help            help for show

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

verify revalidates every rule the frozen benchmark-campaign document carries - the A-F arm contract, the split discipline, the predeclared exclusion set and the promotion rule's declared thresholds - and recomputes the self-excluding campaign digest. With --preregistration it also checks that the campaign pins that frozen Phase 0 document. A campaign is verified before it is read; it never authorizes a run because its schema_version parsed.

Usage:
  sonny bench campaign verify <campaign.json> [flags]

Flags:
      --format string            text or json (default "text")
  -h, --help                     help for verify
      --preregistration string   frozen Phase 0 document the campaign must pin

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

The embedded benchmark catalog and its adapter wiring

Usage:
  sonny bench catalog [command]

Available Commands:
  list        List catalog entries with their adapter class and status
  show        Print every field of one benchmark, e.g. `sonny bench catalog show B20`
  verify      Validate the embedded catalog and print its digest (nonzero exit on failure)

Flags:
  -h, --help   help for catalog

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny bench catalog [command] --help" for more information about a command.

List catalog entries with their adapter class and status

Usage:
  sonny bench catalog list [flags]

Flags:
      --category string   keep only one category, e.g. "Context/memory"
      --format string     text or json (default "text")
  -h, --help              help for list
      --priority string   keep only P0, P1 or P2
      --status string     keep only runnable, smoke_only, feasibility_recorded or blocked

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print every field of one benchmark, e.g. `sonny bench catalog show B20`

Usage:
  sonny bench catalog show <id> [flags]

Flags:
      --format string   text or json (default "text")
  -h, --help            help for show

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Validate the embedded catalog and print its digest (nonzero exit on failure)

Usage:
  sonny bench catalog verify [flags]

Flags:
      --format string   text or json (default "text")
  -h, --help            help for verify

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the conformance matrix from internal/benchconformance: the nine contracts public benchmarks cannot establish, their necessary cases, and for each case either the Go tests that assert it or the recorded reason it does not run.

These are Sonny regression requirements, not benchmark scores. A not_run row is a first-class outcome; it is never a pass.

Usage:
  sonny bench conformance [flags]

Flags:
      --contract string   print only this contract id (e.g. pack_resolution)
      --format string     text or json (default "text")
  -h, --help              help for conformance

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run one benchmark task through the headless agent and write a result document.

Reads a sonny-bench-task/v1 document, runs it as a single headless turn
in a child `sonny run` process, and writes a sonny-bench-result/v1
document echoing every task field plus what the attempt did: the final
reply, token usage, tool-call counts, latencies, trace location and the
digests that pin which recipe and system prompt actually executed.

This is the boundary the Python suites in benchmarks/sonny_bridge use.
It never decides whether a task was solved -- error_category reports
only whether a scoreable transcript exists. The suite's own scorer
grades.

The result document is written even when the attempt fails, because an
absent file is indistinguishable from a crashed harness.

When the attempt is killed on its wall budget, or dies before writing
its own result document, the tool-call counts, tool latency and trace
identity are rebuilt from the conversation trace -- which is written
incrementally and survives the kill. Such a row reports
accounting_source "trace" and carries NO usage field: provider token
counts are only known once the turn completes, so an absent usage says
"not measured" where a zeroed one would claim the attempt spent nothing.

A recipe is selected either by pack.file (one document, no parents) or by
pack.id plus pack.dir -- a list of recipe directories passed to the child
as repeatable --dir entries, so the id resolves with its parents,
includes and sub-packs. The LAST directory to declare an id wins it. A
task that also asks for a system prompt override or a tool allowlist on
an id-selected recipe gets an overlay directory: the library directory
mirrored, the one recipe document rewritten, appended to the search path.
The library is never written to.

When the task carries a models_file it is exported to the child as
SONNY_MODELS_FILE and its sha256 is recorded on the result, so a recipe
whose llm_profiles name model CATEGORIES resolves them through a
registry the row can name.

When the task carries a non-empty mcp_config, or sets headless_mcp, the
child is run with --headless-mcp so the allowlisted MCP servers are
connected for the attempt's single turn. Without it the headless loop
connects no external MCP server and neither the benchmark's own tools
nor the pack's declared servers ever reach the model. mcp_config implies
the flag and headless_mcp cannot turn that off. The servers still pass
the operator-managed allowlist first: one that is not listed is refused
before it is launched, exactly as in an interactive session.

Examples:
  sonny bench exec --task task.json --out result.json
  sonny bench exec --task task.json --out result.json --binary ./bin/sonny

Usage:
  sonny bench exec [flags]

Flags:
      --binary string      sonny binary to run the attempt with (default: this executable)
  -h, --help               help for exec
      --out string         path to write the sonny-bench-result/v1 document to (required)
      --task string        path to the sonny-bench-task/v1 document to run (required)
      --trace-dir string   conversation trace directory for the attempt (default: a "trace" directory beside --out)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Score a sonny-bench-result/v1 ledger: both denominators, pass@k, pass^k, cost, latency and budget

Usage:
  sonny bench scorecard [flags]

Flags:
      --baseline string      second ledger to compute a paired delta against
      --cluster-key string   bootstrap cluster: group_id, task_id or benchmark_id (default "group_id")
      --confidence float     two-sided interval level (default 0.95)
      --format string        text or json (default "text")
  -h, --help                 help for scorecard
      --k int                k of pass@k and pass^k (1 reports neither) (default 1)
      --metric string        paired metric: success or native_score (default "success")
      --records string       JSONL ledger of scored sonny-bench-result/v1 rows
      --resamples int        bootstrap resamples (default 40000)
      --seed uint            bootstrap seed (the interval is reproducible from it) (default 1)
      --stratum string       second grouping level: split, group_id, arm, track or model

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect security benchmark decisions, verify manifests and score independent grades

Usage:
  sonny bench security [command]

Available Commands:
  baxbench             Run native BaxBench tests in fresh candidate/verifier realm pairs; retain private evidence
  execute              Run a candidate or verifier in a fresh authenticated realm; retain execution evidence
  registry             Print the versioned 43-entry security decision register
  replay               Collect native CWEval calls, invoke candidates and independently replay observations
  review               Score a saved review report using a private evaluator plan
  scorecard            Score security grades separately from native metrics
  seccodebench         Run SecCodeBench native observations in isolated candidate realms; retain private evidence
  secrepobench-observe Import saved SecRepoBench observations as unqualified native diagnostics
  verify               Validate a security manifest and report its digest and corpus overlap
  verify-preset        Check declared paired task setup without executing or qualifying it

Flags:
  -h, --help   help for security

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny bench security [command] --help" for more information about a command.

Run native BaxBench tests in fresh candidate/verifier realm pairs; retain private evidence

Usage:
  sonny bench security baxbench [flags]

Flags:
  -h, --help                      help for baxbench
      --machine string            host-trusted signed-image Docker configuration for the candidate image
      --out string                new private execution evidence JSON file
      --plan string               host-built private BaxBench service plan
      --policy string             host-trusted isolation policy file
      --scored-out string         new private scored JSONL file
      --solver-result string      existing one-row solver result JSONL bound to this completion
      --staging string            host directory for private temporary input snapshots (default: the system temporary directory, $TMPDIR or /tmp)
      --verifier-machine string   host-trusted verifier image configuration; defaults to --machine
      --verifier-policy string    host-trusted verifier policy; defaults to --policy

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run a candidate or verifier in a fresh authenticated realm; retain execution evidence

Usage:
  sonny bench security execute [flags]

Flags:
  -h, --help             help for execute
      --machine string   host-trusted signed-image Docker configuration
      --out string       new private execution-evidence JSON file
      --policy string    host-trusted isolation policy file
      --request string   versioned byte-manifest execution request
      --staging string   host directory for private temporary input snapshots (default: the system temporary directory, $TMPDIR or /tmp)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the versioned 43-entry security decision register

Usage:
  sonny bench security registry [flags]

Flags:
  -h, --help   help for registry

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Collect native CWEval calls, invoke candidates and independently replay observations

Usage:
  sonny bench security replay [flags]

Flags:
  -h, --help                   help for replay
      --machine string         host-trusted signed-image Docker configuration
      --out string             new private replay evidence JSON file
      --plan string            host-built pinned native replay plan
      --policy string          host-trusted isolation policy file
      --scored-out string      new private scored JSONL file for security scorecards
      --solver-result string   existing one-row solver result JSONL to bind to this replay
      --staging string         host directory for private temporary input snapshots (default: the system temporary directory, $TMPDIR or /tmp)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Score a saved review report using a private evaluator plan

Usage:
  sonny bench security review [flags]

Flags:
  -h, --help                   help for review
      --plan string            trusted private review evaluator plan JSON; never pass to solver
      --scored-out string      new private scored JSONL file
      --solver-result string   existing one-row solver result JSONL

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Score security grades separately from native metrics

Usage:
  sonny bench security scorecard [flags]

Flags:
      --baseline string    matched baseline ledger for one benchmark and mode
      --confidence float   confidence interval level (default 0.95)
      --format string      text or json (default "text")
  -h, --help               help for scorecard
      --records string     scored JSONL ledger carrying security grades
      --resamples int      cluster bootstrap resamples (default 40000)
      --seed uint          preregistered bootstrap seed (default 1)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run SecCodeBench native observations in isolated candidate realms; retain private evidence

Usage:
  sonny bench security seccodebench [flags]

Flags:
  -h, --help                   help for seccodebench
      --machine string         host-trusted signed-image Docker configuration
      --out string             new private execution evidence JSON file
      --plan string            host-built private SecCodeBench native-test plan
      --policy string          host-trusted isolation policy file
      --scored-out string      new private scored JSONL file
      --solver-result string   existing solver result JSONL bound to this completion
      --staging string         host directory for private input snapshots (default: the system temporary directory, $TMPDIR or /tmp)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Import saved SecRepoBench observations as unqualified native diagnostics

Usage:
  sonny bench security secrepobench-observe [flags]

Flags:
      --assessment string      saved unqualified SecRepoBench assessment JSON
  -h, --help                   help for secrepobench-observe
      --plan string            private evaluator task/completion binding JSON; never pass to solver
      --scored-out string      new private scored JSONL file
      --solver-result string   existing one-row solver result JSONL

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Validate a security manifest and report its digest and corpus overlap

Usage:
  sonny bench security verify [flags]

Flags:
  -h, --help              help for verify
      --manifest string   versioned security manifest JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Check declared paired task setup without executing or qualifying it

Usage:
  sonny bench security verify-preset <path> [flags]

Flags:
  -h, --help   help for verify-preset

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

SkillOpt-Lite benchmark splits as pack-eval suites (see packs/skillopt/README.md)

Usage:
  sonny bench skillopt [command]

Available Commands:
  score       Rescore a sonny eval ledger (recipe eval --format jsonl, or steps/step_N/eval.jsonl) with the SkillOpt metric
  suite       Render a materialized split as a --suite-file / --holdout-suite-file document
  verify      Check materialized data against manifest.json (rows + sha256)

Flags:
  -h, --help   help for skillopt

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny bench skillopt [command] --help" for more information about a command.

Rescore a sonny eval ledger (recipe eval --format jsonl, or steps/step_N/eval.jsonl) with the SkillOpt metric

Usage:
  sonny bench skillopt score [flags]

Flags:
      --bench string    livemath, searchqa or docvqa
      --data string     materialized data dir (default "packs/skillopt/data")
      --format string   text or json (default "text")
  -h, --help            help for score
      --ledger string   JSONL ledger with case_id/status/reply rows
      --split string    the split spec the suite was rendered from

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Render a materialized split as a --suite-file / --holdout-suite-file document

Usage:
  sonny bench skillopt suite [flags]

Flags:
      --bench string   livemath, searchqa or docvqa
      --data string    materialized data dir (make skillopt-materialize) (default "packs/skillopt/data")
  -h, --help           help for suite
      --limit int      keep a seeded subsample of N cases (0 = all)
      --out string     output suite YAML path
      --seed int       subsample seed (default 42)
      --split string   train, val, test, or e.g. train+val

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Check materialized data against manifest.json (rows + sha256)

Usage:
  sonny bench skillopt verify [flags]

Flags:
      --data string       materialized data dir (default "packs/skillopt/data")
  -h, --help              help for verify
      --manifest string   manifest path (default "packs/skillopt/manifest.json")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Canary runs inside Sonny. No separate canary executable is needed.

  preview         inspect legacy requirement tokens without writing
  migrate         apply a reviewed migration plan
  trust-toolchain inspect or select the Go compiler used to run project tests
  verify          run project tests and record trusted evidence
  trace           manage code-external requirement and gap records

Set up a project with 'sonny init project plan --canary', then apply the
printed plan. 'sonny init project canary' remains an equivalent command path.
Toolchain trust refers to the Go compiler, not to a Canary binary.

Usage:
  sonny canary [command]

Available Commands:
  anchor                Manage Canary trace records
  create                Manage Canary trace records
  export                Manage Canary trace records
  init                  Manage Canary trace records
  list                  Manage Canary trace records
  migrate               Apply a reviewed legacy migration plan id
  migrate-inline-tokens Manage Canary trace records
  notes                 Manage Canary trace records
  preview               Preview the legacy inline-token migration (read-only)
  privacy-audit         Manage Canary trace records
  reanchor              Manage Canary trace records
  show                  Manage Canary trace records
  sync                  Manage Canary trace records
  trace                 Manage Canary trace records
  trust-toolchain       Propose, or record with --path, the trusted go binary for verify
  verify                Run the project's tests under Canary's trusted producer

Flags:
  -h, --help   help for canary

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny canary [command] --help" for more information about a command.

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace anchor",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace anchor:
  -end int
    	1-based end line (inclusive)
  -path string
    	repo-relative file path
  -root string
    	project root (default: cwd)
  -start int
    	1-based start line
  -subject string
    	configured requirement or native subject ID
  -subject-kind string
    	explicit requirement, gap, evidence or decision kind
  -symbol string
    	optional symbol FQN
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown subcommand: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create gap",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace create gap:
  -id string
    	gap ID (e.g. GAP-0016)
  -requirement string
    	requirement ID this gap is against
  -root string
    	project root (default: cwd)
  -severity string
    	critical|high|medium|low (default "medium")
  -status string
    	initial status (default "PROPOSED")
  -summary string
    	one-line summary
  -title string
    	title
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create requirement",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace create requirement:
  -id string
    	requirement ID (e.g. CBIN-211)
  -root string
    	project root (default: cwd)
  -status string
    	initial status (default "PROPOSED")
  -summary string
    	one-line summary
  -title string
    	title
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace export",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace export:
  -redacted
    	apply privacy redaction (default true) (default true)
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace init",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace init:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace list",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace list:
  -kind string
    	requirement|gap (default "gap")
  -limit int
    	max items (capped at 50) (default 10)
  -root string
    	project root (default: cwd)
  -status string
    	filter by status
Error: command failed with exit status 1

Import this project's inline CANARY tokens into the trace store,
bound to the plan id 'sonny init project canary preview' printed. A
plan that changed since the preview writes nothing and exits 4. A
reviewed legacy token conversion first rewrites exactly the token lines
the preview listed (legacy ASPECT/STATUS values onto the current
vocabulary) and declares the listed prefixes in .canary/project.yaml;
otherwise the source tokens stay in place. The tracking mode is not
changed. The report lists missing, changed and unsupported entities;
it exits 3 when parity fails. A migration never claims that tests ran.

Usage:
  sonny canary migrate [flags]

Flags:
  -h, --help         help for migrate
      --json         print the report as one JSON document
      --plan-id ID   the reviewed migration plan ID (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace migrate-inline-tokens",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace migrate-inline-tokens:
  -evidence
    	also import .canary/evidence.json records (default true)
  -expect-plan string
    	apply only if the current plan matches this preview plan ID
  -plan
    	preview migration without initializing or changing tracking data
  -plan-details
    	include before/after documents in the preview
  -plan-limit int
    	preview page size (1-100) (default 20)
  -plan-offset int
    	preview page offset
  -recover
    	recover an interrupted publication without starting another migration
  -root string
    	project root (default: cwd)
  -tracking-mode string
    	explicit native_canary, coexist, or trace routing; default preserves existing mode
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown sub-target: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes config",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes config:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes fetch",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes fetch:
  -remote string
    	git remote (default "origin")
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes push",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes push:
  -remote string
    	git remote (default "origin")
  -root string
    	project root (default: cwd)
  -skip-audit
    	skip the privacy audit (DANGEROUS)
Error: command failed with exit status 1

Preview, read-only, the import of this project's inline CANARY
tokens into the trace store: the plan id, the entities it would create
or change, and the tokens and files it cannot import. Legacy tokens
(free-form ASPECT values, EXEMPT or COMPLETE statuses, prefixes no
source declares) preview their conversion instead. Nothing is written.
The migration needs a git repository with a commit (exit 3 otherwise).
Approve it with 'sonny init project canary migrate --plan-id ID'.

Usage:
  sonny canary preview [flags]

Flags:
  -h, --help   help for preview
      --json   print the preview as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace privacy-audit",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace privacy-audit:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace reanchor",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace reanchor:
  -dry-run
    	compute outcomes without persisting
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace show",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace show:
  -declaration-limit int
    	retained declarations per page (1-100) (default 20)
  -declaration-offset int
    	retained declaration offset
  -expected-declaration-revision string
    	require the prior page's projection revision
  -id string
    	subject ID
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace sync",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown sub-target: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace sync gitlab",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace sync gitlab:
  -limit int
    	max records to check (default 100)
  -project string
    	GitLab project ID or path
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 0. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

Captured stderr:

sonny canary trace — code-external requirement and gap traceability

USAGE
  sonny canary trace <subcommand> [flags]

SUBCOMMANDS
  init                                 bootstrap .canary/trace/ + cache.db
  create requirement -id ID -title T   create a requirement manifest
  create gap -id GAP-N -requirement R  create a gap manifest
  anchor -subject ID -path P -start S  capture a blob_range anchor
         -end E [-symbol FQN]
  show -id ID                          compact JSON for one record
  list -kind requirement|gap [-status] compact JSON list
  reanchor [-dry-run]                  re-resolve every anchor
  verify [-scope repo|subject]         run coherence gates
  notes fetch|push|config              shared refs/notes/canary/* helpers
  sync gitlab -project ID              read-only drift report
  privacy-audit                        scan manifests for secrets/prompts
  export [-redacted]                   build redacted JSON bundle
  migrate-inline-tokens                import legacy CANARY comments

NATIVE CANARY WORKFLOW (embedded in Sonny)
  sonny init project plan --canary -> apply the printed plan
  sonny canary trust-toolchain --path /absolute/path/to/go
  sonny canary verify

AGENT TOOLS
  canary_onboard -> canary_index -> canary_view / canary_next / canary_search
  canary_evidence -> canary_verify

Onboard inspects readiness without initializing an index. Indexing and test
execution require separate admission. Existing inline CANARY workspaces can
stay native. Migration is optional; a trace cache alone is not adoption.
Use tool_search, then tool_exec, if the session's provider tool budget hides tools.

Evidence needs git and go in the admitted realm and an operator-authorized
toolchain/signing profile. Availability preflight does not grant tool admission or producer trust.
The minimal Sonny-only isolation image cannot run this evidence workflow.
Ask the operator for a qualified runtime/profile; do not disable isolation or
trust an arbitrary workspace executable to bypass unavailable tools.

TRACE EXAMPLE (creates local tracking data in the current repository)
  sonny canary create requirement -id SONNY-2110 -title "Requirement tracking"
  sonny canary show -id SONNY-2110

IMPORTANT
  sonny canary trace verify checks trace coherence, not canonical test-evidence verification.
  sonny canary verify runs project tests through the embedded evidence producer.
  No separate Canary executable is needed. A declaration
  such as STATUS=TESTED, a successful command, or a trace record is not proof
  that a requirement is verified.

Data commands write a JSON envelope on stdout; help is written to stderr.

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace anchor",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace anchor:
  -end int
    	1-based end line (inclusive)
  -path string
    	repo-relative file path
  -root string
    	project root (default: cwd)
  -start int
    	1-based start line
  -subject string
    	configured requirement or native subject ID
  -subject-kind string
    	explicit requirement, gap, evidence or decision kind
  -symbol string
    	optional symbol FQN
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown subcommand: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create gap",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace create gap:
  -id string
    	gap ID (e.g. GAP-0016)
  -requirement string
    	requirement ID this gap is against
  -root string
    	project root (default: cwd)
  -severity string
    	critical|high|medium|low (default "medium")
  -status string
    	initial status (default "PROPOSED")
  -summary string
    	one-line summary
  -title string
    	title
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace create requirement",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace create requirement:
  -id string
    	requirement ID (e.g. CBIN-211)
  -root string
    	project root (default: cwd)
  -status string
    	initial status (default "PROPOSED")
  -summary string
    	one-line summary
  -title string
    	title
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace export",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace export:
  -redacted
    	apply privacy redaction (default true) (default true)
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace init",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace init:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace list",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace list:
  -kind string
    	requirement|gap (default "gap")
  -limit int
    	max items (capped at 50) (default 10)
  -root string
    	project root (default: cwd)
  -status string
    	filter by status
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace migrate-inline-tokens",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace migrate-inline-tokens:
  -evidence
    	also import .canary/evidence.json records (default true)
  -expect-plan string
    	apply only if the current plan matches this preview plan ID
  -plan
    	preview migration without initializing or changing tracking data
  -plan-details
    	include before/after documents in the preview
  -plan-limit int
    	preview page size (1-100) (default 20)
  -plan-offset int
    	preview page offset
  -recover
    	recover an interrupted publication without starting another migration
  -root string
    	project root (default: cwd)
  -tracking-mode string
    	explicit native_canary, coexist, or trace routing; default preserves existing mode
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown sub-target: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes config",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes config:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes fetch",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes fetch:
  -remote string
    	git remote (default "origin")
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace notes push",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace notes push:
  -remote string
    	git remote (default "origin")
  -root string
    	project root (default: cwd)
  -skip-audit
    	skip the privacy audit (DANGEROUS)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace privacy-audit",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace privacy-audit:
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace reanchor",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace reanchor:
  -dry-run
    	compute outcomes without persisting
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace show",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace show:
  -declaration-limit int
    	retained declarations per page (1-100) (default 20)
  -declaration-offset int
    	retained declaration offset
  -expected-declaration-revision string
    	require the prior page's projection revision
  -id string
    	subject ID
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace sync",
  "error": {
    "code": "BAD_ARGS",
    "message": "unknown sub-target: --help"
  }
}

Captured stderr:

Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace sync gitlab",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace sync gitlab:
  -limit int
    	max records to check (default 100)
  -project string
    	GitLab project ID or path
  -root string
    	project root (default: cwd)
Error: command failed with exit status 1

This command uses the native Canary dispatcher. This captured --help invocation returned exit 1. Read stdout and stderr below; a nonzero help result does not qualify an operational request.

{
  "ok": false,
  "command": "trace verify",
  "error": {
    "code": "BAD_FLAGS",
    "message": "flag: help requested"
  }
}

Captured stderr:

Usage of trace verify:
  -root string
    	project root (default: cwd)
  -scope string
    	repo|changed_paths|subject (default "repo")
  -strict
    	exit non-zero on any fail finding (default true)
  -subject string
    	subject ID (only for -scope=subject)
Error: command failed with exit status 1

Canary mints trusted (executed) evidence only with a go binary the
operator names in .canary/project.yaml (evidence.toolchain_path); it is
never trusted automatically. Without --path this resolves the project's
go binary (GOROOT/bin/go as 'go env GOROOT' reports it here, symlinks
resolved, so a version-manager shim is not proposed) and writes
nothing. With --path it records that binary, symlinks resolved, as
evidence.toolchain_path. The binary must be the go command itself: a
shim or wrapper script is refused. Plan, apply and status never run
this. A refusal (no scaffold, a project without go.mod, a binary that
is not the go command) exits 3 and writes nothing.

Usage:
  sonny canary trust-toolchain [flags]

Flags:
  -h, --help          help for trust-toolchain
      --json          print the result as one JSON document
      --path binary   record this go binary as evidence.toolchain_path (absolute)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run the first evidence session: index the project, run its Go tests
under Canary's trusted producer (evidence.toolchain_path in
.canary/project.yaml) and record a receipt in .sonny/init/canary/.
It exits 0 only when the run passed with trusted, eligible evidence;
1 when a test failed; 3 when a prerequisite is missing or the
evidence is not eligible (the receipt says why). Interrupting it stops
the test processes and records a cancelled receipt.

The tests run as 'go test -json -timeout=1h0m0s ./...': the timeout
applies to each test binary and defaults to 60m (go test's own 10m
default is too short for a large package on a loaded machine);
--test-timeout sets it and --test-parallelism sets go test -p (test
binaries at once). The receipt records the exact command.

Usage:
  sonny canary verify [flags]

Flags:
  -h, --help                    help for verify
      --json                    print the receipt as one JSON document
      --test-parallelism int    go test -p: test binaries run at once (default: go's, the number of CPUs)
      --test-timeout duration   go test -timeout per test duration (default 60m)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Report toolchain readiness for the current project.

Detection is by root marker: a language server is REQUIRED only when the
project actually contains its marker file (go.mod, package.json,
pyproject.toml, ...). Each required capability is then probed and
reported as required (its binary resolves on PATH), missing, or denied.

Nothing is started and nothing is installed, so nothing is reported
"ready": a binary that resolves is a NOT RUN prerequisite, never proof
that the server initializes or is compatible. --fail-on-missing makes the
command exit nonzero when a required capability is absent, so a headless
caller can gate on readiness before dispatching work.

Under --json, stdout carries the report and nothing else. Wall-clock
members are omitted unless --timestamps is given, so the default output
is byte-stable and diffable across runs.

Exit status (closed set; anything else is an unclassified defect):
  0   ok            the report was produced; with --fail-on-missing, nothing required is missing or failed
  3   config        the workspace is not a readable directory, or its directory config cannot be read
  12  unavailable   --fail-on-missing was given and a required capability is missing or failed
  15  indeterminate --fail-on-missing was given, nothing is missing, but detection was truncated
  70  internal      the report could not be encoded -- a defect in Sonny

Usage:
  sonny capabilities [flags]

Flags:
      --fail-on-missing   exit nonzero when a required capability is missing or failed
  -h, --help              help for capabilities
      --json              emit the versioned JSON report instead of a table
      --timestamps        include first/last observation times (off by default so the report is byte-stable)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Sonny installs model catalogs as signed artifacts into a registry under $XDG_DATA_HOME/sonny/catalogs, independent of recipe sources (D5). Use these subcommands to add, update, remove, inspect, roll back, or sync registry catalogs; see `sonny catalog import-from-recipes` to migrate a recipe source's old-style models: catalog into the registry.

Usage:
  sonny catalog [command]

Available Commands:
  add                 Install a new catalog artifact into the registry
  import-from-recipes Copy recipe-contributed model catalogs (import-from-packs is deprecated; removal in v0.13.0)
  inspect             Show the active version's manifest for an installed catalog
  list                List installed catalogs
  remove              Remove an installed catalog and every retained version
  rollback            Swap an installed catalog back to its last-known-good version
  sync                Re-fetch every installed catalog that has a recorded source
  update              Re-fetch and install the latest version of an installed catalog

Flags:
  -h, --help   help for catalog

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny catalog [command] --help" for more information about a command.

Install a new catalog artifact into the registry

Usage:
  sonny catalog add <git-url|path|sonny://...> [flags]

Flags:
      --git-path string   path to artifact.yaml within the repository (git sources only; default artifact.yaml)
  -h, --help              help for add
      --key string        pin the expected Ed25519 signing key fingerprint
      --ref string        git branch or tag to track (git sources only; default main)
      --unsigned          accept an artifact with no signature (file sources only)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Declared names/aliases: import-from-recipes, import-from-packs.

Reads every recipe source's model catalogs (its models: files, or the default model-registry/models.yaml), wraps each source's merged catalog body in the registry's manifest envelope with provenance pack:<name>, and installs it under catalogs/pack-<name>/versions/<commit-sha>/ as an unsigned, locally-sourced catalog. Re-running against an unchanged recipe source is a no-op; a changed source installs a new version and the prior import stays as last-known-good (D19 Migration §2).

Usage:
  sonny catalog import-from-recipes [flags]

Aliases:
  import-from-recipes, import-from-packs

Flags:
  -h, --help          help for import-from-recipes
      --name string   import only the named pack source

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the active version's manifest for an installed catalog

Usage:
  sonny catalog inspect <id> [flags]

Flags:
  -h, --help   help for inspect

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List installed catalogs

Usage:
  sonny catalog list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Remove an installed catalog and every retained version

Usage:
  sonny catalog remove <id> [flags]

Flags:
  -h, --help   help for remove

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Swap an installed catalog back to its last-known-good version

Usage:
  sonny catalog rollback <id> [flags]

Flags:
  -h, --help   help for rollback

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Re-fetch every installed catalog that has a recorded source

Usage:
  sonny catalog sync [flags]

Flags:
  -h, --help   help for sync

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Re-fetch and install the latest version of an installed catalog

Usage:
  sonny catalog update <id> [flags]

Flags:
  -h, --help   help for update

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Validate commit messages against the Conventional Commit + work-item policy (ENG-4428)

Usage:
  sonny commitmsg [command]

Available Commands:
  check       Validate one commit message file (the local commit-msg hook path)
  range       Validate every commit message in a git commit range (the CI path)

Flags:
  -h, --help   help for commitmsg

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny commitmsg [command] --help" for more information about a command.

check reads the commit message git is about to record from <message-file>
(git invokes the commit-msg hook with this path, conventionally
.git/COMMIT_EDITMSG) and validates it against the ENG-4428 policy: a
Conventional Commit header and a required work-item reference (e.g.
"ENG-4428" or a "Refs: ENG-4428" footer).

Exit status is non-zero when the message fails policy; the failure is
never silent and never bypassable from this command alone.

Usage:
  sonny commitmsg check <message-file> [flags]

Flags:
  -h, --help   help for check
      --json   emit the machine-readable Result as JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

range validates every commit reachable from <head> but not from <base> —
the same commits "git log base..head" would list — against the ENG-4428
policy. It shares the exact same validation call the local commit-msg
hook ("sonny commitmsg check") uses, so a CI job and a contributor's
local hook agree on every commit.

Exit status is non-zero when any commit in the range fails policy.

Usage:
  sonny commitmsg range <base> <head> [flags]

Flags:
  -h, --help   help for range
      --json   emit the machine-readable Results as JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Generate the autocompletion script for sonny for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
  sonny completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Flags:
  -h, --help   help for completion

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny completion [command] --help" for more information about a command.

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

	source <(sonny completion bash)

To load completions for every new session, execute once:

#### Linux:

	sonny completion bash > /etc/bash_completion.d/sonny

#### macOS:

	sonny completion bash > $(brew --prefix)/etc/bash_completion.d/sonny

You will need to start a new shell for this setup to take effect.

Usage:
  sonny completion bash

Flags:
  -h, --help              help for bash
      --no-descriptions   disable completion descriptions

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

	sonny completion fish | source

To load completions for every new session, execute once:

	sonny completion fish > ~/.config/fish/completions/sonny.fish

You will need to start a new shell for this setup to take effect.

Usage:
  sonny completion fish [flags]

Flags:
  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Generate the autocompletion script for powershell.

To load completions in your current shell session:

	sonny completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command
to your powershell profile.

Usage:
  sonny completion powershell [flags]

Flags:
  -h, --help              help for powershell
      --no-descriptions   disable completion descriptions

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

	echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

	source <(sonny completion zsh)

To load completions for every new session, execute once:

#### Linux:

	sonny completion zsh > "${fpath[1]}/_sonny"

#### macOS:

	sonny completion zsh > $(brew --prefix)/share/zsh/site-functions/_sonny

You will need to start a new shell for this setup to take effect.

Usage:
  sonny completion zsh [flags]

Flags:
  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage sonny configuration.

Configuration can be specified via:
- Command line flags
- Environment variables (SONNY_* prefix)
- Configuration file (.sonny.yaml in the working directory, then $HOME)
- Directory configuration (the directory: block of every .sonny.yaml
  from the filesystem root down to the working directory; created by
  `sonny config init`)

Usage:
  sonny config [command]

Available Commands:
  explain        Show which source supplies each configuration value, and which candidates lost
  init           Add a starter directory: block to .sonny.yaml
  path           Show every standard configuration / data / cache path
  resource-reuse Show the effective resource_reuse configuration and its digest
  show           Show current configuration
  validate       Validate resolved analysis configuration and inherited restrictions

Flags:
  -h, --help   help for config

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny config [command] --help" for more information about a command.

explain resolves every configuration key through the one precedence
rule — flag, then environment, then the project .sonny config chain
(deepest directory first), then the per-user config, then the built-in
default — and prints the winner together with every candidate that lost
and where it lives.

Secret-bearing keys report presence and location only; their values are
never printed.

Usage:
  sonny config explain [flags]

Flags:
  -h, --help                           help for explain
      --json                           emit the versioned JSON envelope on stdout
      --supervisor-deployment string   inspect this protected deployment without activation (default: SONNY_SUPERVISOR_DEPLOYMENT)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Add a starter directory: block to .sonny.yaml in the current directory.

The block configures language servers. sonny lsp, sonny capabilities
and sonny-api read it from the working directory only;
sonny config show also merges the blocks of every .sonny.yaml from the
filesystem root down to the working directory.

When ./.sonny.yaml (or ./.sonny.yml) exists, the block is appended to
it and every existing byte is kept. When it does not exist and $HOME
has a .sonny.yaml, init refuses: sonny reads top-level settings from
the first .sonny.yaml it finds (. then $HOME), so a new ./.sonny.yaml
would hide the home file in this directory. A symlinked file is
followed only when its target exists inside the working directory.

--force replaces an existing directory: block (re-encoding the file,
so its comments stay but its layout may change), creates ./.sonny.yaml
even when it hides the home file, and writes through a symlink that
dangles or leaves the working directory.

Usage:
  sonny config init [flags]

Flags:
      --force   replace an existing directory: block, create ./.sonny.yaml even when it hides $HOME/.sonny.yaml, or write through a symlink that dangles or leaves the working directory
  -h, --help    help for init

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the standard sonny path layout for this host.

Includes config (models.yaml, pack-sources.yaml, agents.yaml), data
(sessions.db, packs/), cache (cloned recipe repos), state (including
agent-availability.yaml), and the loaded cobra config file.

These paths follow the XDG basedir spec on Linux, macOS Library layout
on Darwin, and AppData on Windows. Override any of them by setting
$XDG_CONFIG_HOME, $XDG_DATA_HOME, or $XDG_CACHE_HOME.

Usage:
  sonny config path [flags]

Flags:
  -h, --help   help for path

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the effective resource_reuse block: package defaults, overlaid with the
.sonny.yaml resource_reuse section, overlaid with the five SONNY_RESOURCE_REUSE_*
environment variables. There are no flags for this section.

The digest is the value resource-reuse telemetry stamps on its events, so a
recorded event can be matched back to the settings that produced it.

This reports configuration only. It does not read any file, start a session, or
attest that a reuse or a write precondition would be applied to a given call.

Usage:
  sonny config resource-reuse [flags]

Flags:
  -h, --help   help for resource-reuse
      --json   emit the versioned JSON envelope on stdout

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the current effective configuration.

This displays all configuration values from all sources
(files, environment, flags) merged together.

Usage:
  sonny config show [flags]

Flags:
  -h, --help                           help for show
      --supervisor-deployment string   inspect this protected deployment without activation (default: SONNY_SUPERVISOR_DEPLOYMENT)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Validate analysis.version=1 against the selected protected operator base, then user, global, project, environment and invocation layers. Report known startup blockers without activating analysis. Graph and policy validation does not attest provider capabilities or authorize model calls.

Usage:
  sonny config validate [flags]

Flags:
  -h, --help                           help for validate
      --json                           emit the versioned JSON envelope on stdout
      --supervisor-deployment string   inspect this protected deployment without activation (default: SONNY_SUPERVISOR_DEPLOYMENT)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny conformance groups the assurance plane:

  run       execute the invariant corpus against the synthetic organization
  matrix    execute the platform/adapter/provider qualification matrix,
            recording NOT RUN plus the exact operator command for every
            combination this host cannot execute
  gates     print the machine-readable deployment-control contract,
            including effective mode, owner, evidence, and removal release
  drill     execute one or every ENG-4539 recovery drill and record its
            sealed result
  cert      inspect and verify signed conformance certificates
  dossier   assemble the immutable release evidence bundle

NOT RUN is a first-class outcome. A combination this host cannot execute is
never reported as passing.

Usage:
  sonny conformance [command]

Available Commands:
  cert        Inspect and verify signed conformance certificates
  dossier     Assemble the immutable release evidence bundle
  drill       Execute one or every ENG-4539 recovery drill and record its sealed result
  gates       Print the effective runtime migration and removal controls
  matrix      Execute the qualification matrix, recording NOT RUN for what this host cannot run
  run         Execute the invariant corpus against the synthetic organization

Flags:
  -h, --help   help for conformance

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny conformance [command] --help" for more information about a command.

Inspect and verify signed conformance certificates

Usage:
  sonny conformance cert [command]

Available Commands:
  verify      Verify a certificate's signature and expiry against a trusted issuer key

Flags:
  -h, --help   help for cert

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny conformance cert [command] --help" for more information about a command.

conformance cert verify checks a signed conformance certificate two ways:
the certificate's own embedded public key must match the operator-supplied
trusted key (--trusted-key), and the certificate's signature, contract and
expiry must verify against that key. A certificate that merely verifies
against its own embedded key -- without a trusted key pinning who issued it
-- proves nothing: anyone can self-sign. Neither check alone is sufficient;
both must pass for VERIFIED.

Usage:
  sonny conformance cert verify [flags]

Flags:
      --cert string          path to the certificate JSON file (required)
  -h, --help                 help for verify
      --json                 emit the verification result as JSON
      --trusted-key string   path to the trusted issuer's ed25519 public key, base64 or hex encoded (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Assemble the immutable release evidence bundle

Usage:
  sonny conformance dossier [flags]

Flags:
  -h, --help         help for dossier
      --out string   directory to write the immutable bundle into (must not exist) (default "release-dossier")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

conformance drill runs the mandatory ENG-4539 recovery drills: real
operations against a disposable environment, never a tabletop exercise. A
drill whose subsystem does not exist at the pinned baseline is NOT RUN with
the owning issue, never skipped silently.

--id runs a single drill (freeze, restore, rollback, dr-rebuild,
key-rotation, effect-reconciliation, clean-room); omitted, every drill in
the catalog runs in order.

Usage:
  sonny conformance drill [flags]

Flags:
      --allow-unstamped-build   explicitly waive the ldflags build stamp requirement (a plain go build/go test binary; every drill is otherwise capped at NOT RUN)
      --assessor string         independent observer identity recorded on every result (required, ENG-4539)
  -h, --help                    help for drill
      --id string               run only this drill id (default: every drill in the catalog)
      --json                    emit the full report as JSON
      --log-dir string          directory retaining each drill's raw log (default "conformance-logs")
      --script-dir string       directory containing the drill scripts (default "conformance/drill/scripts")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the effective runtime migration and removal controls

Usage:
  sonny conformance gates [flags]

Flags:
  -h, --help   help for gates
      --json   emit the full report as JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Execute the qualification matrix, recording NOT RUN for what this host cannot run

Usage:
  sonny conformance matrix [flags]

Flags:
      --allow-unstamped-build   explicitly waive the ldflags build stamp requirement (a plain go build/go test binary; every cell is otherwise capped at NOT RUN)
      --assessor string         assessor identity recorded on every result (required)
  -h, --help                    help for matrix
      --json                    emit the full report as JSON
      --log-dir string          directory retaining each cell's raw log (default "conformance-logs")
      --provider-tier string    provider tier: emulated, sandbox, or live (default "emulated")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Execute the invariant corpus against the synthetic organization

Usage:
  sonny conformance run [flags]

Flags:
      --allow-unstamped-build   explicitly waive the ldflags build stamp requirement (a plain go build/go test binary; every case is otherwise capped at NOT RUN)
      --assessor string         assessor identity recorded on every result (required)
  -h, --help                    help for run
      --json                    emit the full report as JSON
      --log-dir string          directory retaining each case's raw log (default "conformance-logs")
      --provider-tier string    provider tier: emulated, sandbox, or live (default "emulated")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny context groups the context-efficiency tooling:

  stats     summarize trace-store metrics for a session or time range
            (equivalent to the standalone "sonny context-stats")
  validate  assert cross-plan invariants for a session, exiting
            non-zero on any violation
            (equivalent to the standalone "sonny context-validate")
  pack      offline: assemble a ctxm.Packet from a JSON transcript file
            and a token budget, reporting honest drop accounting
            (dropped_messages/dropped_bytes) -- no trace store involved

Usage:
  sonny context [command]

Available Commands:
  pack        Assemble an offline ctxm.Packet from a transcript file, with honest drop accounting
  stats       Summarize context-efficiency metrics for a session or time range
  validate    Verify context-efficiency invariants for a session

Flags:
  -h, --help   help for context

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny context [command] --help" for more information about a command.

pack reads a flat JSON transcript ([{"role":...,"content":...}, ...])
from --transcript (a file path, "-", or omitted -- all three read
stdin), maps it onto a ctxm.Packet (the first user-role message becomes
the immutable Objective; every other message becomes the recency
window -- see ctxwire.PacketFromMessages), and fits it to a token
budget with ctxm.Assembler.

Report fields:

  dropped_messages / dropped_bytes
      len(before.RecentRaw)-len(after.RecentRaw) and the raw content
      bytes that went with them. This is the FIRST-CLASS honesty gate:
      --strict fails the command when either dropped_messages > 0 OR
      loss_categories is non-empty.

  loss_categories
      ctxm.CheckLossPolicy(before, after) output. For this mapping
      (objective/constraints only -- no phase, frontier, decisions, or
      evidence populated) this is EXPECTED TO BE EMPTY even when
      messages were dropped: CheckLossPolicy cannot see RecentRaw
      trimming at all. It is included for completeness and forward
      compatibility, never as the drop signal -- use dropped_messages
      for that.

  continuation
      ctxm.EvaluateContinuation(before.RecentRaw, after, markers),
      included only when --markers is given; null otherwise.

Exit status: non-zero on a malformed transcript, an
ErrContractExceedsBudget (the objective+constraints alone do not fit
the budget), or --strict catching a drop.

Usage:
  sonny context pack [flags]

Flags:
      --budget int           total token budget (overrides --window when set)
      --format string        text|json (default "text")
  -h, --help                 help for pack
      --markers strings      comma-separated markers to score continuation survival for
      --output-reserve int   tokens reserved for output (default: window-or-budget/10)
      --pretty               pretty-print JSON output (--format json); false emits one line (default true)
      --strict               exit non-zero when dropped_messages > 0 or loss_categories is non-empty
      --transcript string    transcript JSON file ([{"role","content"}, ...]); "-" or omitted reads stdin
      --window int           total token budget (default 8000)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Summarize the headline context-efficiency metrics from the trace store:
cache hit rate, semantic-cache hit precision (per cluster), compression ratio
and retention score, prefix churn, and provider cached-token percentage.

Pass --session to scope to a single session, --tenant to filter by tenant, or
--since (e.g. 24h) to limit to recent activity.

Usage:
  sonny context stats [flags]

Flags:
  -h, --help             help for stats
      --session string   session id to summarize (default: all)
      --since string     time range (e.g. 24h, 7d) (default "24h")
      --store string     path to trace store DB (default: ~/.sonny/trace/cache.db)
      --tenant string    tenant id filter (default: all)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Assert that the cross-plan invariants held for a session:

  - shell stability    : cache_layout.shell_digest never changed mid-session
  - tenant isolation   : no record references a tenant other than the session's
  - retention floor    : every compaction's retention_score stayed above floor
  - return contracts   : every handoff_packet had a matching, well-formed reply

Exits non-zero on any failure so CI pipelines can gate on it.

Usage:
  sonny context validate <session-id> [flags]

Flags:
  -h, --help            help for validate
      --store string    path to trace store DB (default: ~/.sonny/trace/cache.db)
      --tenant string   tenant id this session must be scoped to (optional)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Summarize the headline context-efficiency metrics from the trace store:
cache hit rate, semantic-cache hit precision (per cluster), compression ratio
and retention score, prefix churn, and provider cached-token percentage.

Pass --session to scope to a single session, --tenant to filter by tenant, or
--since (e.g. 24h) to limit to recent activity.

Usage:
  sonny context-stats [flags]

Flags:
  -h, --help             help for context-stats
      --session string   session id to summarize (default: all)
      --since string     time range (e.g. 24h, 7d) (default "24h")
      --store string     path to trace store DB (default: ~/.sonny/trace/cache.db)
      --tenant string    tenant id filter (default: all)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Assert that the cross-plan invariants held for a session:

  - shell stability    : cache_layout.shell_digest never changed mid-session
  - tenant isolation   : no record references a tenant other than the session's
  - retention floor    : every compaction's retention_score stayed above floor
  - return contracts   : every handoff_packet had a matching, well-formed reply

Exits non-zero on any failure so CI pipelines can gate on it.

Usage:
  sonny context-validate <session-id> [flags]

Flags:
  -h, --help            help for context-validate
      --store string    path to trace store DB (default: ~/.sonny/trace/cache.db)
      --tenant string   tenant id this session must be scoped to (optional)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect Sonny's authority control plane

Usage:
  sonny control [command]

Available Commands:
  budgets     Show this month's routing budget spend per organization, project and principal
  gc          Compact and prune the control-plane database, optionally reclaiming file space
  migration   Diagnose or recover a verified SQLite migration boundary
  status      Report the effective authority mode, suppliers, and lease

Flags:
  -h, --help   help for control

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny control [command] --help" for more information about a command.

sonny control budgets lists the organization, project and principal routing
budget accounts of one tenant for one UTC calendar month (default: the
current month): what each has spent, what it holds reserved for calls still
running, and its limit for the month. Those three caps apply per UTC month;
session, turn and child caps are not listed. A lifetime account written
before monthly windows is also listed, with window "lifetime", while it
still exists: it only settles holds reserved before the upgrade.

It reads the control store gc would select and never writes to it: it never
creates a missing SQLite file and never applies a migration. It refuses a
store whose schema is not this binary's; upgrade that store first by running
sonny control gc with this binary, after reading the pre-upgrade notes in the
environment reference if the store is large. When SONNY_CONTROL_PG_DSN is set
it reads that Postgres control plane instead of the local SQLite file.

Usage:
  sonny control budgets [flags]

Flags:
      --control-db string   control-plane SQLite database path (default: $SONNY_CONTROL_DB, then control.db in the data directory; ignored when SONNY_CONTROL_PG_DSN is set)
  -h, --help                help for budgets
      --json                print JSON instead of a table
      --tenant string       tenant whose budgets to show (default "local")
      --window string       UTC month to show, as YYYY-MM (default: the current month)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny control gc runs the control-store sweep to completion: it removes the
checkpoint rows below each runtime session's head (a journal written before
head-only retention keeps every one), prunes runtime sessions whose journal
has not been written for longer than the retention window (default 30 days,
SONNY_CONTROL_RETENTION overrides it, 0/off keeps every session), and
reclaims the blobs those rows pinned. It also removes routing circuit
observations older than the same window (never less than a day), then the
closed circuits left with no observation at all; open and half-open circuits
are always kept. It also removes routing ledgers nothing still needs: a task's
route records once every one is older than the retention and none names a
live session, top-level retry budgets older than the retention (a route
retry budget only once its decision's record is gone too; any other, such
as an analysis branch's, on age alone, so a retry after that is refused),
and reconciled budget reservations no surviving runtime session's journal
names. An active route-budget hold that was never reconciled (its usage
was never reported, overran the hold, or failed to record) is settled once
older than the retention at its full held amount (moved from reserved to
spent: nothing is refunded, and an overrun is charged no more than was
held) and is then pruned like any reconciled reservation. Each batch
logs one warning summarizing the holds it settled (count, tenants, held
cost per currency), and each hold at debug level;
a stale hold whose own reservation or accounts are missing or invalid is
left active and reported as an error on every run, and the rest still
settle. Child and turn budget accounts idle for longer than the retention
with nothing reserved are removed (turn caps apply per 1 h UTC hour
window). Organization, project and principal budget caps apply per UTC
calendar month, one account per month, and session caps per 24 h UTC day
window, one account per day. Such an account is removed only once it has
been idle for longer than the retention with nothing reserved in any
dimension, and either its window ended before the retention cut-off's
window or it is a lifetime account written before its windows; the current
window's accounts are always kept. Transferred child retry budgets and every
other active reservation are always kept.

Plans paused for longer than the paused-plan retention (default 90 days,
SONNY_CONTROL_PAUSED_PLAN_RETENTION or --paused-plan-retention overrides
it, 0/off keeps them) are removed whole, attempts included, even when the
session retention is off. That cut-off is never shorter than the session
retention.

The interactive session runs the same sweep in the background at start-up
and hourly, so this command is for an operator who wants it done now, or
wants the file itself to shrink: deleted rows only free pages for reuse
inside the file, and --vacuum rebuilds the file so the space returns to the
filesystem. VACUUM needs free disk roughly equal to the live data and cannot
run while an interactive session holds the database, so close sonny first.
Stale budget holds the sweep had to leave active do not stop --vacuum: gc
warns, rebuilds the file, and then exits non-zero naming them. Any other
sweep error stops before the vacuum.

When SONNY_CONTROL_PG_DSN is set, gc runs the same sweep against that
Postgres control plane instead of the local SQLite file (--control-db and
SONNY_CONTROL_DB are ignored in that case); --vacuum is rejected there —
Postgres reclaims space automatically via autovacuum, so there is no file to
rebuild.

Usage:
  sonny control gc [flags]

Flags:
      --control-db string              control-plane SQLite database path (default: $SONNY_CONTROL_DB, then control.db in the data directory; ignored when SONNY_CONTROL_PG_DSN is set)
  -h, --help                           help for gc
      --paused-plan-retention string   remove whole plans paused for longer than this Go duration, even when --retention is off; never shorter than --retention (default 2160h; 0 or off keeps paused plans)
      --retention string               remove runtime sessions, routing circuit history and routing ledgers, and settle stale budget holds, untouched for longer than this Go duration (default 720h; 0 or off keeps all of them)
      --vacuum                         rebuild the database file after the sweep so freed pages return to the filesystem (SQLite only; rejected against a Postgres control plane, see SONNY_CONTROL_PG_DSN)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Diagnose or recover a verified SQLite migration boundary

Usage:
  sonny control migration [command]

Available Commands:
  diagnose    Inspect migration metadata without opening the runtime or changing the database
  recover     Back up and repair only an exactly recognized dirty migration 22

Flags:
  -h, --help   help for migration

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny control migration [command] --help" for more information about a command.

Inspect migration metadata without opening the runtime or changing the database

Usage:
  sonny control migration diagnose [flags]

Flags:
      --control-db string   explicit local SQLite database path (required)
  -h, --help                help for diagnose

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Back up and repair only an exactly recognized dirty migration 22

Usage:
  sonny control migration recover [flags]

Flags:
      --control-db string   explicit local SQLite database path (required)
  -h, --help                help for recover

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny control status resolves and prints the effective authority mode
BEFORE any work begins: which of off/observe/enforce is in force, where that
came from (--mode, SONNY_AUTHORITY_MODE, a deprecated legacy switch, or the
package default), any deprecated switches that are set and therefore
ignored, the bound external-governor suppliers, and the build this report
came from.

It is read-only: in off mode it never creates the control database, it only
reports whether one already exists.

Usage:
  sonny control status [flags]

Flags:
      --control-db string   control-plane database path to report (stat'ed only, never created)
  -h, --help                help for status
      --json                emit machine-readable JSON
      --mode string         override the authority mode for this report (off|observe|enforce)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny stores Copilot/Hyper OAuth tokens through the credentials.Broker
(keychain, or a sealed file store) once a one-time migration has copied and
verified every row from the legacy sessions.db table; until then the legacy
store remains authoritative. "migrate-status" drives that migration forward
(it is safe to run repeatedly) and reports where it stands; "retire-legacy"
destroys the now-redundant legacy copies once a confirmation window has
passed since migration completed, or immediately with --force. "resolve"
reports which secret-resolver tier (keyring, bao, environment, .env)
supplies a catalog source's credential, never the value; "delete" removes
the key or sign-in the keyring stores for a source or provider.

Usage:
  sonny credentials [command]

Available Commands:
  delete         Remove the API key or sign-in stored in the keyring for a model source or provider
  migrate-status Migrate (or resume migrating) legacy OAuth tokens to the credential broker, and report status
  resolve        Report which credential tier (keyring, bao, environment, .env) answers a catalog source, never the value
  retire-legacy  Zero and delete the legacy OAuth rows and master key once migration has been verified

Flags:
  -h, --help   help for credentials

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny credentials [command] --help" for more information about a command.

sonny credentials delete removes what Settings' Disconnect removes: every
credential the broker holds under the provider id, and the key a model
source stored under its own account (the keyring tier "sonny credentials
resolve" reports). Environment variables, .env files and Bao are not
touched. Exit 1 when nothing was stored.

Usage:
  sonny credentials delete <source or provider id> [flags]

Flags:
  -h, --help   help for delete

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Migrate (or resume migrating) legacy OAuth tokens to the credential broker, and report status

Usage:
  sonny credentials migrate-status [flags]

Flags:
  -h, --help   help for migrate-status

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

sonny credentials resolve asks the secret resolver the same question the
daemon asks before a hosted turn and the desktop's Settings asks for each
source: for this catalog source, which tier supplies its credential? Tiers
are consulted in the fixed order keyring > bao > environment > .env, for the
source's ONE conventional variable (its env_prefix-derived name, else its
api_key_env), and the first answer wins. Every tier prints one line --
"answered", "checked" (consulted, held nothing) or "skipped (<why>)" -- and
the value is never printed. Exit 0 when a tier answered, 1 otherwise.

Usage:
  sonny credentials resolve <source id> [flags]

Flags:
  -h, --help   help for resolve

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Zero and delete the legacy OAuth rows and master key once migration has been verified

Usage:
  sonny credentials retire-legacy [flags]

Flags:
      --force   retire immediately, bypassing the confirmation window
  -h, --help    help for retire-legacy

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Plan, import, run, analyze, and report context-use evaluations

Usage:
  sonny cue [command]

Available Commands:
  existing-data Import existing traces or classify legacy evidence without inventing missing fields
  plan          Validate a research-only CUE plan without executing model calls
  reanalyze     Recompute CUE tables from retained observations without rerunning models
  report        Render provenance-labeled CUE tables and task/position figures
  testing       Preflight or execute a complete explicitly authorized CUE plan
  verify        Verify a reconstructable CUE archive and every retained artifact

Flags:
  -h, --help   help for cue

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny cue [command] --help" for more information about a command.

Declared names/aliases: existing-data, import.

Import existing traces or classify legacy evidence without inventing missing fields

Usage:
  sonny cue existing-data [flags]

Aliases:
  existing-data, import

Flags:
      --bundle-out string           new owner-only typed import bundle path
  -h, --help                        help for existing-data
      --input string                legacy evidence JSON array
      --out string                  optional output report path
      --pseudonym-key-file string   owner-only 32+ byte HMAC key file for trace import
      --trace-dir string            Sonny trace or flattened-corpus directory

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Validate a research-only CUE plan without executing model calls

Usage:
  sonny cue plan [flags]

Flags:
  -h, --help          help for plan
      --out string    optional output report path
      --plan string   study-plan JSON (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Declared names/aliases: reanalyze, analyze.

Recompute CUE tables from retained observations without rerunning models

Usage:
  sonny cue reanalyze [flags]

Aliases:
  reanalyze, analyze

Flags:
      --analysis string   analysis id (defaults to the deterministic descriptive table)
      --archive string    versioned CUE study archive JSON (required)
  -h, --help              help for reanalyze
      --out string        optional output report path

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Render provenance-labeled CUE tables and task/position figures

Usage:
  sonny cue report [flags]

Flags:
      --archive string   versioned CUE study archive JSON (required)
      --format string    output format: workflow, json, csv, or svg (default "workflow")
  -h, --help             help for report
      --out string       optional output report path

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Declared names/aliases: testing, run.

Preflight or execute a complete explicitly authorized CUE plan

Usage:
  sonny cue testing [flags]

Aliases:
  testing, run

Flags:
      --dry-run            show calls, token/cost limits, and every unresolved setting without execution
  -h, --help               help for testing
      --out string         optional output archive/report path
      --plan string        authorized study-plan JSON (required)
      --preflight string   secret-free resolved config/resources/budget JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Verify a reconstructable CUE archive and every retained artifact

Usage:
  sonny cue verify [flags]

Flags:
      --archive string   versioned CUE study archive JSON (required)
  -h, --help             help for verify
      --out string       optional output report path

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

editor-rpc dials the supervisor and exposes its Runtime to an editor as newline-delimited JSON-RPC 2.0 over stdin/stdout, the client protocol documented in docs/config/client-protocol.md. The first request must be sonny/initialize, which negotiates the protocol version and reports the served capabilities. It never executes a tool locally: every call is dispatched to the supervisor, and a refusal or an unreachable daemon is reported with the same status taxonomy the CLI and TUI use. If the editor closes its end while a request is in flight, the request is still executed once; a client that reconnects must re-issue it with the same idempotency key to learn its outcome rather than assuming it was dropped.

Usage:
  sonny editor-rpc [flags]

Flags:
      --client-instance string   desktop window identifier (DWI) distinguishing this connection's durable supervisor identity from another window's (SONNY-2922); empty leaves the identity exactly client-name@tenant
      --client-name string       client name reported to the supervisor (default "sonny-editor-rpc")
      --endpoint string          supervisor socket (unix) or pipe (windows) path
  -h, --help                     help for editor-rpc
      --human-attach             present the per-user human-attach proof so the supervisor treats this connection as an attached human client, required for the human-only operations (plans.approve, plans.proceed, plans.cancel, plans.pause, plans.resume, plans.replan, plans.confirmEvidence, plans.archive, plans.unarchive, plans.publish, a task skip, human_confirmed evidence, revising a paused plan, approvals.decide, updates.stage, updates.importBundle, updates.activate, updates.recover, and granting workspaces.trust); an unloadable key warns on stderr and continues as an agent connection; for interactive clients only (SONNY-3627)
      --tenant string            tenant this connection speaks for

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

freeze runs the tenant-scoped emergency containment procedure: raise a signed epoch, stop scheduling, revoke live grants, and preserve a signed evidence snapshot.

Usage:
  sonny freeze [command]

Available Commands:
  raise             Raise a signed tenant freeze epoch
  revoke-grants     Revoke every live grant in a frozen tenant
  snapshot-evidence Write an immutable signed snapshot of freeze containment evidence
  stop-scheduling   Engage the durable scheduling kill switch for a frozen tenant
  verify-evidence   Verify a freeze evidence snapshot without the control database

Flags:
  -h, --help   help for freeze

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny freeze [command] --help" for more information about a command.

Raise a signed tenant freeze epoch

Usage:
  sonny freeze raise [flags]

Flags:
      --allow stringArray       emergency principal that remains permitted (repeatable, shrink-only)
      --control-db string       absolute path to the SQLite control-plane database (required)
  -h, --help                    help for raise
      --initiator-id string     active verifier identity authorizing the operation (required)
      --json                    emit machine-readable JSON
      --reason string           incident reason recorded with the signed freeze (required)
      --scope string            tenant scope in the form tenant:<tenant-id> (required)
      --signing-key string      absolute path to the raw 64-byte Ed25519 private key (required)
      --trust-document string   absolute path to the protected evidence trust document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Revoke every live grant in a frozen tenant

Usage:
  sonny freeze revoke-grants [flags]

Flags:
      --cause string            closed revocation cause (default "freeze_epoch")
      --control-db string       absolute path to the SQLite control-plane database (required)
  -h, --help                    help for revoke-grants
      --initiator-id string     active verifier identity authorizing the operation (required)
      --json                    emit machine-readable JSON
      --scope string            tenant scope in the form tenant:<tenant-id> (required)
      --signing-key string      absolute path to the raw 64-byte Ed25519 private key (required)
      --trust-document string   absolute path to the protected evidence trust document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Write an immutable signed snapshot of freeze containment evidence

Usage:
  sonny freeze snapshot-evidence [flags]

Flags:
      --control-db string       absolute path to the SQLite control-plane database (required)
  -h, --help                    help for snapshot-evidence
      --initiator-id string     active verifier identity authorizing the operation (required)
      --json                    emit machine-readable JSON
      --out string              absolute path of the new evidence snapshot directory (required)
      --scope string            tenant scope in the form tenant:<tenant-id> (required)
      --signing-key string      absolute path to the raw 64-byte Ed25519 private key (required)
      --trust-document string   absolute path to the protected evidence trust document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Engage the durable scheduling kill switch for a frozen tenant

Usage:
  sonny freeze stop-scheduling [flags]

Flags:
      --control-db string       absolute path to the SQLite control-plane database (required)
  -h, --help                    help for stop-scheduling
      --initiator-id string     active verifier identity authorizing the operation (required)
      --json                    emit machine-readable JSON
      --reason string           incident reason recorded with the kill switch (required)
      --scope string            tenant scope in the form tenant:<tenant-id> (required)
      --signing-key string      absolute path to the raw 64-byte Ed25519 private key (required)
      --trust-document string   absolute path to the protected evidence trust document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Verify a freeze evidence snapshot without the control database

Usage:
  sonny freeze verify-evidence [flags]

Flags:
  -h, --help                    help for verify-evidence
      --in string               absolute path to the evidence snapshot directory (required)
      --json                    emit machine-readable JSON
      --trust-document string   absolute path to the protected evidence trust document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Help provides help for any command in the application.
Simply type sonny help [path to command] for full details.

Usage:
  sonny help [command] [flags]

Flags:
  -h, --help   help for help

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect and validate the session hooks configuration

Usage:
  sonny hooks [command]

Available Commands:
  check       Validate the user and project hooks configuration

Flags:
  -h, --help   help for hooks

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny hooks [command] --help" for more information about a command.

Load the user (<config>/hooks.yaml) and project (<cwd>/.sonny/hooks.yaml)
hooks exactly as a session would and report the result.

An unknown key, wrong type, duplicate id, unsupported schema_version, or
over-cap file is a FAILURE: the command exits non-zero and names the problem.
--json emits a machine-readable status carrying the active hook IDs and the
configuration digest.

Usage:
  sonny hooks check [flags]

Flags:
  -h, --help   help for check
      --json   emit machine-readable JSON status

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Create sonny's directories on this host and seed a starter
models.yaml. The command is idempotent: running it twice is harmless.

Created directories:
  config dir        (models.yaml, pack-sources.yaml)
  config dir/models.d  (drop-in model catalog fragments)
  data dir/packs    (user recipe YAMLs go here)
  cache dir         (git-backed recipe clones)

Created files (only if missing):
  models.yaml       (embedded example, edit to taste)

Pass --system to use the system layout (/usr/local/share/sonny/...)
in package post-install scripts. Pass --force to overwrite an
existing models.yaml.

Usage:
  sonny init [flags]
  sonny init [command]

Available Commands:
  defaults    Optionally fill missing recipe and model defaults
  project     Generate project prompt recipes in .sonny/ from existing agent files

Flags:
      --default-model string    optionally select a default model as source/model when none is saved
      --default-recipe string   optionally select a default pack when none is saved
      --force                   overwrite existing files (models.yaml)
  -h, --help                    help for init
      --system                  use system data dir (for packagers / post-install scripts)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny init [command] --help" for more information about a command.

Select optional startup defaults. Existing choices are preserved. Skip either flag to keep automatic task routing. List choices with sonny recipe list --recipes and sonny models list.

Usage:
  sonny init defaults [flags]

Flags:
      --default-model string    optionally select a default model as source/model when none is saved
      --default-recipe string   optionally select a default pack when none is saved
  -h, --help                    help for defaults

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Harvest this directory's agent-instruction assets (AGENTS.md,
CLAUDE.md, .claude/ commands, skills and agents, cursor/windsurf/
copilot files) into a generated prompt-pack suite under .sonny/packs/.

The suite's primary recipe inherits (parent:) from the nearest ancestor
directory that has also run 'sonny init project', so instructions
compose down the directory hierarchy. A drift manifest
(.sonny/init-manifest.yaml) records source hashes; 'sonny run'
refreshes the harvested sections automatically when sources change.

By default the configured provider (--provider/--model, .sonny.yaml,
or SONNY_PROVIDER/SONNY_MODEL) writes a synthesized main prompt; pass
--no-llm (or configure no provider) for a deterministic template.
Pass --mcp to also harvest MCP server configs (.mcp.json,
.claude/settings.json, .cursor/mcp.json, .vscode/mcp.json) into
.sonny/mcp.yaml. The choice is remembered: a rerun without --mcp keeps
it, and --mcp=false turns it off (removing an untouched mcp.yaml).

Reruns never overwrite a hand-edited generated file: it is kept and
reported as a conflict. Pass --force to replace hand-edited files.
Pass --json to print the result as one JSON document instead.

The subcommands drive the same init service step by step and never
prompt: plan, then apply --plan-id; status; repair; resume or abandon
an unfinished operation; rollback --to a recorded generation. The
subcommands share one exit-status table: 0 ok, 2 usage, 3 not ready
or blocked, 4 stale plan, 5 lease held, 6 idempotency conflict, 1 any
other failure. This bare command keeps exit 0 when readiness is
blocked, for compatibility; it still exits 2 usage, 3 when an
unfinished init operation must be resumed or abandoned first, 4 stale
plan, 5 lease held, 6 idempotency conflict, 1 any other failure.

Usage:
  sonny init project [flags]
  sonny init project [command]

Available Commands:
  abandon     Abandon an unfinished init operation
  apply       Apply a reviewed init plan by id (never prompts)
  campaigns   List evaluation, optimization, promotion and rollback receipts
  canary      Explicit Canary actions: legacy migration and the evidence session
  dataset     Build and list the project's history datasets
  eval        Evaluate the project's recipe against its imported history dataset
  history     Import this project's attributable agent history (Sonny, Claude, Codex)
  index       Publish the project's local source index
  optimize    Optimize the project's recipe against its history dataset (staged, never activated)
  plan        Show what an init apply would do, without writing anything
  promote     Activate an improved optimization candidate by receipt
  rebind      Bind the project's private init state to this checkout
  repair      Regenerate missing or stale init outputs, keeping hand-edited files
  resume      Resume an unfinished init operation
  rollback    Re-activate a recorded generation of the project's recipes
  setup       Provision local isolation and a protected analysis deployment
  status      Show the project's init state and per-subsystem readiness

Flags:
      --force    replace hand-edited generated files (explicit destructive choice)
  -h, --help     help for project
      --json     print the result as one JSON document
      --mcp      harvest MCP server configs into .sonny/mcp.yaml (remembered; --mcp=false disables)
      --no-llm   skip LLM synthesis; use the deterministic template

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny init project [command] --help" for more information about a command.

Abandon the unfinished init operation OP that 'sonny init project
status' reports: its leftovers are undone, the previous generation
stays active, and the operation is recorded as cancelled. An operation
that already committed is finished forward instead.

Usage:
  sonny init project abandon OP [flags]

Flags:
  -h, --help   help for abandon
      --json   print the result as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Apply the plan 'sonny init project plan' printed. --plan-id is
required: when the project now plans a different id (a source, an
output or the request changed) nothing is written and the command
exits 4. Repeat the --force, --no-llm, --mcp, --canary, --analysis,
--gitignore, --index and --decide flags the plan was computed with.
--decide path=keep|replace resolves one hand-edited output; the command
never prompts.

Usage:
  sonny init project apply [flags]

Flags:
      --analysis                   enable an initial analysis pipeline in .sonny/config.yaml when no custom analysis is configured (remembered; --analysis=false disables; never writes .sonny.yaml or grants)
      --canary                     scaffold project-scoped Canary config under .canary/ (remembered; --canary=false disables; never home or agent files; an existing .canary is kept)
      --decide path=keep|replace   resolve one hand-edited output as path=keep|replace (repeatable)
      --force                      replace hand-edited generated files (explicit destructive choice)
      --gitignore                  keep the managed .gitignore block ignoring .sonny/init/ (default on; remembered; --gitignore=false disables; never removes lines)
  -h, --help                       help for apply
      --idempotency-key KEY        retry-safe KEY: a retry with the same key returns the first operation
      --index                      record the code index registration in .sonny/init/index.json (default on; remembered; --index=false disables)
      --json                       print the result as one JSON document
      --mcp                        harvest MCP server configs into .sonny/mcp.yaml (remembered; --mcp=false disables)
      --no-llm                     skip LLM synthesis; use the deterministic template
      --plan-id ID                 the reviewed plan ID to apply (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List the project's receipts, newest first, read-only: kind,
outcome, generation, calls and, for a campaign, the command line that
reproduces it. A receipt left running by a process that ended is shown
interrupted. No dataset case text is ever printed.

Usage:
  sonny init project campaigns [flags]

Flags:
  -h, --help   help for campaigns
      --json   print the receipts as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Explicit, project-scoped Canary actions. 'sonny init project plan
--canary' (then apply) scaffolds .canary/ in this project; these
subcommands never run as part of plan, apply or status:

  preview         inspect the legacy inline-token migration (read-only)
  migrate         apply a reviewed migration plan id
  trust-toolchain propose, or record with --path, the trusted go binary
  verify          run the project's tests under Canary's trusted producer

Usage:
  sonny init project canary [command]

Available Commands:
  migrate         Apply a reviewed legacy migration plan id
  preview         Preview the legacy inline-token migration (read-only)
  trust-toolchain Propose, or record with --path, the trusted go binary for verify
  verify          Run the project's tests under Canary's trusted producer

Flags:
  -h, --help   help for canary

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny init project canary [command] --help" for more information about a command.

Import this project's inline CANARY tokens into the trace store,
bound to the plan id 'sonny init project canary preview' printed. A
plan that changed since the preview writes nothing and exits 4. A
reviewed legacy token conversion first rewrites exactly the token lines
the preview listed (legacy ASPECT/STATUS values onto the current
vocabulary) and declares the listed prefixes in .canary/project.yaml;
otherwise the source tokens stay in place. The tracking mode is not
changed. The report lists missing, changed and unsupported entities;
it exits 3 when parity fails. A migration never claims that tests ran.

Usage:
  sonny init project canary migrate [flags]

Flags:
  -h, --help         help for migrate
      --json         print the report as one JSON document
      --plan-id ID   the reviewed migration plan ID (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Preview, read-only, the import of this project's inline CANARY
tokens into the trace store: the plan id, the entities it would create
or change, and the tokens and files it cannot import. Legacy tokens
(free-form ASPECT values, EXEMPT or COMPLETE statuses, prefixes no
source declares) preview their conversion instead. Nothing is written.
The migration needs a git repository with a commit (exit 3 otherwise).
Approve it with 'sonny init project canary migrate --plan-id ID'.

Usage:
  sonny init project canary preview [flags]

Flags:
  -h, --help   help for preview
      --json   print the preview as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Canary mints trusted (executed) evidence only with a go binary the
operator names in .canary/project.yaml (evidence.toolchain_path); it is
never trusted automatically. Without --path this resolves the project's
go binary (GOROOT/bin/go as 'go env GOROOT' reports it here, symlinks
resolved, so a version-manager shim is not proposed) and writes
nothing. With --path it records that binary, symlinks resolved, as
evidence.toolchain_path. The binary must be the go command itself: a
shim or wrapper script is refused. Plan, apply and status never run
this. A refusal (no scaffold, a project without go.mod, a binary that
is not the go command) exits 3 and writes nothing.

Usage:
  sonny init project canary trust-toolchain [flags]

Flags:
  -h, --help          help for trust-toolchain
      --json          print the result as one JSON document
      --path binary   record this go binary as evidence.toolchain_path (absolute)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run the first evidence session: index the project, run its Go tests
under Canary's trusted producer (evidence.toolchain_path in
.canary/project.yaml) and record a receipt in .sonny/init/canary/.
It exits 0 only when the run passed with trusted, eligible evidence;
1 when a test failed; 3 when a prerequisite is missing or the
evidence is not eligible (the receipt says why). Interrupting it stops
the test processes and records a cancelled receipt.

The tests run as 'go test -json -timeout=1h0m0s ./...': the timeout
applies to each test binary and defaults to 60m (go test's own 10m
default is too short for a large package on a loaded machine);
--test-timeout sets it and --test-parallelism sets go test -p (test
binaries at once). The receipt records the exact command.

Usage:
  sonny init project canary verify [flags]

Flags:
  -h, --help                    help for verify
      --json                    print the receipt as one JSON document
      --test-parallelism int    go test -p: test binaries run at once (default: go's, the number of CPUs)
      --test-timeout duration   go test -timeout per test duration (default 60m)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Build lineage-disjoint train/val/test datasets from the imported
history, and list them. A dataset is content-addressed (its id is a
digest of the trajectories and every parameter), private
(<data>/projects/<uuid>/datasets/), and its test split is sealed:
nothing here ever prints a case or its text. Evaluation and
optimization campaigns use the newest ready dataset unless --dataset
names one.

  build   publish (or reuse) the dataset of the imported history
  list    show the published datasets, newest first

Usage:
  sonny init project dataset [command]

Available Commands:
  build       Build the dataset of the imported history
  list        List the project's datasets, newest first

Flags:
  -h, --help   help for dataset

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny init project dataset [command] --help" for more information about a command.

Build (or reuse) the content-addressed dataset of this project's
imported history: sessions linked by lineage or a near-duplicate first
prompt stay in one split. It prints the dataset id, its counts and its
state: ready, or data_insufficient below 25 eligible groups. It exits
0 when ready, and 3 when data_insufficient or when no history was
imported (run 'sonny init project history import' first).

Usage:
  sonny init project dataset build [flags]

Flags:
  -h, --help               help for build
      --json               print the dataset summary as one JSON document
      --max-test int       cap on test cases, whole groups only (0: no cap)
      --max-train int      cap on train cases, whole groups only (0: no cap)
      --max-val int        cap on validation cases, whole groups only (0: no cap)
      --seed SEED          the split SEED (part of the dataset id) (default "sonny-init")
      --temporal-holdout   hold out the newest groups as the test split instead of hashing
      --test-pct int       percent of lineage groups in the sealed test split (default 20)
      --val-pct int        percent of lineage groups in the validation split (default 10)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List the published datasets, newest first, read-only: id, state,
counts and parameters. The dataset campaigns use without --dataset is
marked selected. No case or case text is ever printed.

Usage:
  sonny init project dataset list [flags]

Flags:
  -h, --help   help for list
      --json   print the datasets as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run an evaluation campaign: the active generation's primary recipe
over the project's dataset (train and val cases of imported histories),
within the budget. The gates are declared in the receipt before any
model call. Without a dataset of at least 25 eligible cases the outcome
is data_insufficient; without a provider it is unavailable; neither
makes a model call. It exits 0 when evaluated, 3 when data_insufficient
or unavailable, and 1 when cancelled or failed.

To skip a running campaign gracefully (preserving the checkpoint for
later resume), send SIGUSR1 to the process: kill -USR1 <pid>. A skip
writes a cancelled receipt, keeps the checkpoint, and exits 3.

Use --background to detach from the terminal: the campaign runs in a
new session (setsid), stdout/stderr go to a log file under
.sonny/init/campaigns/bg/, and this process exits 0 immediately after
printing the pid and log path.

Usage:
  sonny init project eval [flags]

Flags:
      --background            detach from the terminal and run the campaign in the background; prints the pid and log path, then returns immediately (send SIGUSR1 to the pid to skip a running campaign gracefully)
      --concurrency int       cases evaluated at once through the shared scheduler (default 4)
      --dataset ID            the dataset ID to use (default: the newest ready dataset; list them with sonny init project dataset list)
      --fresh                 discard the checkpoint of an earlier cut or failed run on the same inputs and start over (default: resume it)
      --generation GEN        the generation GEN to measure (default: the active one; optimize always uses it)
  -h, --help                  help for eval
      --json                  print the receipt as one JSON document
      --max-attempts int      attempts of a campaign call that fails retryably (default 1)
      --max-calls int         hard ceiling on model calls (default 500)
      --recipe ID             the pack ID under campaign (default: the project's primary pack)
      --repetitions int       evaluation passes averaged into the score (default 1)
      --wall-clock duration   wall-clock budget (default 30m0s)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Import the agent sessions recorded in this project into private,
redacted trajectories under the sonny data dir
(<data>/projects/<uuid>/histories/). Only sessions whose recorded
working directory is this project (in this checkout, in another
existing checkout of the same git repository, or at a --map old
location of it) enter; everything else is counted, never imported.
The sources are only read, and no history text is ever printed.

  plan     count what an import would take (dry run; writes nothing)
  import   store those sessions (idempotent by source digest; atomic)

Usage:
  sonny init project history [command]

Available Commands:
  import      Import this project's attributable history into private trajectories
  plan        Report what a history import would take (read-only)

Flags:
  -h, --help   help for history

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny init project history [command] --help" for more information about a command.

Import the sessions attributable to this project into private,
redacted trajectories (<data>/projects/<uuid>/histories/). A re-import
of unchanged sources rewrites nothing. The sources are only read;
secrets drop the whole session. It prints counts only, never history
text. It exits 0, or 3 when nothing is attributable to this project.

Usage:
  sonny init project history import [flags]

Flags:
  -h, --help             help for import
      --json             print the report as one JSON document
      --map FROM=TO      attribute sessions recorded under an old location of this project: FROM=TO (absolute paths; repeatable)
      --max-bytes SIZE   read at most SIZE of history in total, e.g. 2GiB or 500MB (default 1GiB)
      --max-files N      read at most N history files in total (default 10000)
      --source SOURCE    read only this history SOURCE (sonny, claude or codex; repeatable; default all three)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Report, read-only, what 'sonny init project history import' would
do: the attributable, ambiguous, unattributed, malformed and skipped
session counts, the time range, and every history root with whether it
exists. A missing root is reported, not an error. Nothing is written.
It exits 0, or 3 when nothing is attributable to this project.

Usage:
  sonny init project history plan [flags]

Flags:
  -h, --help             help for plan
      --json             print the report as one JSON document
      --map FROM=TO      attribute sessions recorded under an old location of this project: FROM=TO (absolute paths; repeatable)
      --max-bytes SIZE   read at most SIZE of history in total, e.g. 2GiB or 500MB (default 1GiB)
      --max-files N      read at most N history files in total (default 10000)
      --source SOURCE    read only this history SOURCE (sonny, claude or codex; repeatable; default all three)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Publish the project's local source index

Usage:
  sonny init project index [flags]

Flags:
      --approve   approve reading this project's repository and Git metadata and storing a private local source index
  -h, --help      help for index
      --json      print index readiness as JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run a bounded optimization campaign on the active generation's
primary pack: the optimizer sees the training cases only; the sealed
holdout split is evaluated by the holdout gate alone. Hard gates: the
holdout verdict is improved, no holdout text leaked into the candidate,
the locked parent tool policy holds, no permission is widened, and the
dataset has at least 25 eligible cases. The quality gate is a holdout
score gain of at least --min-delta. A candidate that passes is staged
as a generation (improved, exit 0) for 'sonny init project promote';
not_improved, rejected, data_insufficient and unavailable exit 3;
cancelled and failed exit 1. Cases run through the shared optimize
scheduler.

To skip a running campaign gracefully (preserving the checkpoint for
later resume), send SIGUSR1 to the process: kill -USR1 <pid>. A skip
writes a cancelled receipt, keeps the checkpoint, and exits 3.

Use --background to detach from the terminal: the campaign runs in a
new session (setsid), stdout/stderr go to a log file under
.sonny/init/campaigns/bg/, and this process exits 0 immediately after
printing the pid and log path.

Usage:
  sonny init project optimize [flags]

Flags:
      --background            detach from the terminal and run the campaign in the background; prints the pid and log path, then returns immediately (send SIGUSR1 to the pid to skip a running campaign gracefully)
      --concurrency int       cases evaluated at once through the shared scheduler (default 4)
      --dataset ID            the dataset ID to use (default: the newest ready dataset; list them with sonny init project dataset list)
      --fresh                 discard the checkpoint of an earlier cut or failed run on the same inputs and start over (default: resume it)
      --generation GEN        the generation GEN to measure (default: the active one; optimize always uses it)
  -h, --help                  help for optimize
      --json                  print the receipt as one JSON document
      --max-attempts int      attempts of a campaign call that fails retryably (default 1)
      --max-calls int         hard ceiling on model calls (default 500)
      --min-delta float       holdout-score gain the quality gate requires (default: init.optimize.min_delta, else 0.02)
      --recipe ID             the pack ID under campaign (default: the project's primary pack)
      --wall-clock duration   wall-clock budget (default 2h0m0s)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Compute the init plan for this directory read-only: the scope
(directory, project uuid, worktree), per-subsystem readiness, the
operations an apply would perform, conflicts, and capabilities.

The plan id binds the reviewed plan: approve it with
'sonny init project apply --plan-id ID', repeating the same --force,
--no-llm, --mcp, --canary, --analysis, --gitignore, --index and --decide
flags.

Usage:
  sonny init project plan [flags]

Flags:
      --analysis                   enable an initial analysis pipeline in .sonny/config.yaml when no custom analysis is configured (remembered; --analysis=false disables; never writes .sonny.yaml or grants)
      --canary                     scaffold project-scoped Canary config under .canary/ (remembered; --canary=false disables; never home or agent files; an existing .canary is kept)
      --decide path=keep|replace   resolve one hand-edited output as path=keep|replace (repeatable)
      --force                      replace hand-edited generated files (explicit destructive choice)
      --gitignore                  keep the managed .gitignore block ignoring .sonny/init/ (default on; remembered; --gitignore=false disables; never removes lines)
  -h, --help                       help for plan
      --index                      record the code index registration in .sonny/init/index.json (default on; remembered; --index=false disables)
      --json                       print the plan as one JSON document
      --mcp                        harvest MCP server configs into .sonny/mcp.yaml (remembered; --mcp=false disables)
      --no-llm                     skip LLM synthesis; use the deterministic template

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Activate the staged candidate of optimization receipt --receipt.
Only an improved receipt whose hard gates all passed is promotable
(exit 3 otherwise). The switch is a compare-and-swap on the active
generation (--expected-active defaults to the one 'sonny init project
status' reports; a different one exits 4), and the receipt's inputs are
recomputed from the current project: a changed source, parent, adapter,
dataset, provider or model exits 4 with stale_receipt. The activation
is journaled like a rollback and records a promotion receipt; undo it
with 'sonny init project rollback --to <previous generation>'.

Usage:
  sonny init project promote [flags]

Flags:
      --expected-active GEN   the generation GEN that must be active (default: the current active generation)
  -h, --help                  help for promote
      --json                  print the result as one JSON document
      --receipt ID            the optimization receipt ID to promote (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Bind the private init state of this project's uuid (imported
histories, datasets, campaign work dirs and checkpoints under the data
dir) to this checkout.

The uuid comes from the committed .sonny/init-manifest.yaml, so another
checkout can assert it too. Private state is therefore bound to the
checkout that created it (and to linked worktrees of the same git
repository); any other checkout with the same uuid is refused (exit 3)
until you run this command there. Run it only when this checkout should
own that state, for example after moving or re-cloning the project. The
checkout it was bound to before is refused from then on.

Usage:
  sonny init project rebind [flags]

Flags:
  -h, --help   help for rebind
      --json   print the result as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Plan and apply in one step the repair of missing or stale
generated outputs of an initialized project. Hand-edited outputs are
kept (reported as conflicts) and no LLM synthesis runs. A project that
was never initialized exits 3: run 'sonny init project' first.

Usage:
  sonny init project repair [flags]

Flags:
  -h, --help   help for repair
      --json   print the result as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Resume the unfinished init operation OP that 'sonny init project
status' reports: its leftovers are undone and its plan is applied again
under the same operation id (exit 4 when its inputs changed since). An
operation that already committed is finished forward.

Usage:
  sonny init project resume OP [flags]

Flags:
  -h, --help   help for resume
      --json   print the result as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Re-activate the recorded generation --to GEN. The switch is a
compare-and-swap on the active generation: --expected-active defaults
to the active generation 'sonny init project status' reports, and a
different active generation exits 4 without writing anything.

Usage:
  sonny init project rollback [flags]

Flags:
      --expected-active GEN   the generation GEN that must be active (default: the current active generation)
  -h, --help                  help for rollback
      --json                  print the result as one JSON document
      --to GEN                the recorded generation GEN to re-activate (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Provision a per-user rootless Docker engine (or use the system Docker engine when it runs with userns-remap), verify a signed Sonny isolation image, and grant this project's enabled analysis pipeline access to its workspace and configured model providers. Existing operator configuration is preserved.

Usage:
  sonny init project setup [flags]

Flags:
      --dir string   project directory (default: current directory)
  -h, --help         help for setup
      --host-local   grant analysis without an isolation realm (selected automatically when no usable isolation Docker engine exists)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Report this directory's init state read-only: the manifest, the
active and recorded generations, drift, conflicts, an unfinished
operation to resume or abandon, per-subsystem readiness, and the next
actions. It exits 3 when the recipes subsystem is blocked or failed.

Usage:
  sonny init project status [flags]

Flags:
  -h, --help   help for status
      --json   print the status as one JSON document

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect and verify session isolation

Usage:
  sonny isolation [command]

Available Commands:
  defaults               Print the complete strict default isolation configuration
  doctor                 Verify backend, policy, image, broker, and cleanup
  explain                Explain a tool's execution plane and effective isolation policy
  export                 Preview or approve a reviewed workspace export
  image-statement-schema Print the Docker image-statement JSON Schema
  machine-schema         Print the Docker machine-trust JSON Schema
  policy-schema          Print the embedded isolation policy JSON Schema
  status                 Show the latest persisted verified isolation posture
  verify-exposures       Verify the hash chain of every isolated role-surface exposure journal

Flags:
  -h, --help   help for isolation

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny isolation [command] --help" for more information about a command.

Print the complete strict default isolation configuration

Usage:
  sonny isolation defaults [flags]

Flags:
  -h, --help   help for defaults
      --json   write canonical JSON instead of YAML

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Verify backend, policy, image, broker, and cleanup

Usage:
  sonny isolation doctor [flags]

Flags:
      --assurance string   minimum assurance: guarded, native, docker, or vm
      --backend string     select backend: auto, native, docker, or vm
  -h, --help               help for doctor
      --json               write bounded machine-readable JSON
      --machine string     absolute trusted machine configuration file
      --mode string        narrow isolation mode: required, preferred, or off
      --policy string      absolute trusted isolation policy file

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Explain a tool's execution plane and effective isolation policy

Usage:
  sonny isolation explain TOOL [flags]

Flags:
      --assurance string   minimum assurance: guarded, native, docker, or vm
      --backend string     select backend: auto, native, docker, or vm
  -h, --help               help for explain
      --json               write bounded machine-readable JSON
      --machine string     absolute trusted machine configuration file
      --mode string        narrow isolation mode: required, preferred, or off
      --policy string      absolute trusted isolation policy file

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Preview or approve a reviewed workspace export

Usage:
  sonny isolation export [flags]

Flags:
      --approve          approve an already staged manifest
      --digest string    exact manifest digest shown by preview (required with --approve)
  -h, --help             help for export
      --json             write bounded machine-readable JSON
      --preview          show the validated manifest without writing host files (default true)
      --session string   session UUID to export

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the Docker image-statement JSON Schema

Usage:
  sonny isolation image-statement-schema [flags]

Flags:
  -h, --help   help for image-statement-schema

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the Docker machine-trust JSON Schema

Usage:
  sonny isolation machine-schema [flags]

Flags:
  -h, --help   help for machine-schema

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the embedded isolation policy JSON Schema

Usage:
  sonny isolation policy-schema [flags]

Flags:
  -h, --help   help for policy-schema

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the latest persisted verified isolation posture

Usage:
  sonny isolation status [flags]

Flags:
  -h, --help             help for status
      --json             write bounded machine-readable JSON
      --session string   specific session UUID (default: latest)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Verify the hash chain of every isolated role-surface exposure journal

Usage:
  sonny isolation verify-exposures [flags]

Flags:
  -h, --help             help for verify-exposures
      --json             write bounded machine-readable JSON
      --session string   only this session's journal segments

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect and validate LSP configuration for code intelligence features.

LSP servers provide features like hover information, go-to-definition,
find references, diagnostics, and more, but are managed IN-PROCESS by
sonny's chat/TUI sessions (each session owns its own manager, started and
stopped alongside the session). This "lsp" command group does not manage
that shared state: every subcommand builds a fresh, short-lived manager
scoped to this single CLI invocation, so "list"/"start"/"stop" here can
neither see nor affect servers a chat session is using. Use these
subcommands to validate that a language's configuration is correct and its
server binary starts successfully, not to administer a long-lived server.

Usage:
  sonny lsp [command]

Available Commands:
  list        List LSP servers running in THIS invocation (always empty)
  servers     List available LSP server configurations
  start       Validate a language's LSP config by starting it once
  stop        Stop a server started by THIS invocation (always a no-op)

Flags:
  -h, --help   help for lsp

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny lsp [command] --help" for more information about a command.

List LSP servers running under this command's own manager.

This subcommand validates configuration for a single CLI invocation: it
builds a brand-new manager that lives only for the duration of this
command, so it always reports zero servers here -- it cannot see servers
started by a chat/TUI session or by a previous "sonny lsp start" (which
also died with its own process). For the readiness view -- what is
actually configured and working right now -- use "sonny capabilities".
Use "sonny lsp servers" to see what's configured for this workspace, or
"sonny lsp start <language>" to validate a server starts successfully.

Usage:
  sonny lsp list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List all configured LSP servers and their settings.

This shows both default servers and any custom servers
configured in the directory: block of .sonny.yaml.

In a workspace that is not trusted, every server listed is blocked by
workspace trust: none of them starts there, and the listing says so.

Usage:
  sonny lsp servers [flags]

Flags:
  -h, --help   help for servers

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Start an LSP server for the specified language, then exit.

This subcommand validates configuration for a single CLI invocation, not
server administration: the manager this creates -- and the server
process it starts -- belongs only to this CLI invocation and is gone the
moment the command exits (nothing keeps it running or lets a later
"sonny lsp list"/"sonny lsp stop" find it). Use it to confirm a
language's server binary is on PATH, its config is valid, and it
initializes successfully. For the readiness view -- what is actually
configured and working right now -- use "sonny capabilities". Chat/TUI
sessions manage their own LSP servers independently of this command.

Like a session, it starts no language server, built-in or declared by the
project, in a workspace that is not trusted: a language server runs the
project's own code while it analyzes it (rust-analyzer runs build.rs,
gopls follows a go.mod toolchain line). There it exits 8 (denied_policy)
and names the command that trusts the workspace, "sonny workspace trust".

Examples:
  sonny lsp start go
  sonny lsp start typescript
  sonny lsp start python

Usage:
  sonny lsp start <language> [flags]

Flags:
  -h, --help   help for start

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Stop an LSP server for the specified language.

This subcommand validates configuration for a single CLI invocation:
"sonny lsp stop" builds its own fresh, empty manager for this single
invocation, so there is never anything for it to stop here -- it cannot
reach a server owned by a chat/TUI session or by a separate
"sonny lsp start" process. It exists for symmetry with "start"/"list"
and will report "no server running" every time it is run as a
standalone command. For the readiness view -- what is actually
configured and working right now -- use "sonny capabilities".

Examples:
  sonny lsp stop go
  sonny lsp stop typescript

Usage:
  sonny lsp stop <language> [flags]

Flags:
  -h, --help   help for stop

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect resolved MCP server and tool configuration

Usage:
  sonny mcp [command]

Available Commands:
  approve     Add MCP servers to the operator allowlist (SEC-002)
  connect     Operator: connect to a configured MCP server and report its tools
  disconnect  Operator: verify clean teardown of a configured MCP server connection
  list        List resolved MCP servers (config + recipe), redacted, with digests

Flags:
  -h, --help   help for mcp

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny mcp [command] --help" for more information about a command.

Approve subcommands resolve and hash MCP server binaries on the
current host and add matching entries to the MCP allowlist at
<config-dir>/mcp.allowlist.yaml (XDG-aware).

A server approved here is trusted on THIS host only; any later
binary update requires re-running approve to re-pin the new hash.

Usage:
  sonny mcp approve [command]

Available Commands:
  dir         Scan a directory for recipe YAMLs and approve their MCP servers
  recipe      Approve MCP servers declared by a recipe (pack is deprecated; removal in v0.13.0)
  registry    Approve the MCP servers a recipe source's mcp_d supplies
  server      Approve a single MCP server by name and --command, --url or --project

Flags:
  -h, --help   help for approve

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny mcp approve [command] --help" for more information about a command.

Walks path for *.yaml / *.yml files, parses each one as a recipe,
collects every mcp.server declaration (last writer wins on duplicate
server name), and approves them. Useful before adding a recipe source
or to re-approve after a binary update.
Pass --write-config to also merge server definitions into mcp.yaml.
For a recipe that is not verified-signed, --write-config refuses $VAR
references in env and auth values, and env keys the untrusted-pack env
gate refuses, unless --write-untrusted-references is also passed.

Usage:
  sonny mcp approve dir <path> [flags]

Flags:
  -h, --help                         help for dir
      --skip-unresolved              silently skip servers whose binary is not installed on this host
      --write-config                 also merge approved server definitions into <config-dir>/mcp.yaml
      --write-untrusted-references   with --write-config: also write $VAR references, refused env keys and egress policy beyond the server's own url host from servers of packs that are not verified-signed into mcp.yaml, where references expand against your environment

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Declared names/aliases: recipe, pack.

Loads the named recipe (using the same discovery as 'sonny recipe inspect'),
extracts every server declared under pack.mcp.servers, resolves each
binary hash on the current host, and adds new entries to the MCP
allowlist. Already-present entries are silently skipped.

Use --dir or --file to target a recipe YAML by path instead of ID.
Pass --write-config to also merge server definitions into mcp.yaml.
For a recipe that is not verified-signed, --write-config refuses $VAR
references in env and auth values, and env keys the untrusted-pack env
gate refuses, unless --write-untrusted-references is also passed. A
preview (command, args, env names, url, auth shape) is printed first;
--dry-run stops there.

Usage:
  sonny mcp approve recipe <recipe-id> [flags]

Aliases:
  recipe, pack

Flags:
      --dir string                   additional pack directory (passed to pack discovery)
      --dry-run                      print what would be approved (command, args, env names, url, auth shape) and write nothing
      --file string                  load a single pack YAML by path instead of by ID
  -h, --help                         help for recipe
      --skip-unresolved              silently skip servers whose binary is not installed on this host
      --write-config                 also merge approved server definitions into <config-dir>/mcp.yaml
      --write-untrusted-references   with --write-config: also write $VAR references, refused env keys and egress policy beyond the server's own url host from servers of packs that are not verified-signed into mcp.yaml, where references expand against your environment

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Loads the mcp_d files of the named recipe source (pack-sources.yaml),
applies the registry loader's gates, resolves each stdio binary on the
current host and records your approval of every server's definition
in the allowlist: the source, its commit, the definition digest and
the pinned launch (command, binary digest, args, work_dir, env digest).
A recipe source's server launches only while its definition matches such
a record, so run this after adding a source with mcp_d and again
whenever an update changes a server's definition. With the source's
mcp_auto_approve on (the default for a source with mcp_d), an approved
server connects, without a prompt, for the recipes from the same source
that name it -- unless it reads a host variable outside the
source's mcp_env_allow (including SSH_AUTH_SOCK, GIT_SSH_COMMAND,
NODE_OPTIONS and PYTHONPATH, which a stdio server with no env_allowlist
receives implicitly), sets a code-execution env key such as LD_PRELOAD
to a literal, runs a shell, a wrapper such as sudo, or inline
interpreter code, or launches an unpinned package or image, or the
clone is dirty or its commit unknown. Those, and any registry server a
local recipe or another source's recipe names, are held to the same record
and the stricter pinning an explicitly approved server gets. A
preview (command, args, env names, code-execution env values, url with
userinfo redacted, auth shape) is printed first; --dry-run stops there.
A changed definition needs a new approval.

Usage:
  sonny mcp approve registry <source> [flags]

Flags:
      --dry-run                      print what would be approved (command, args, env names, url, auth shape) and write nothing
  -h, --help                         help for registry
      --skip-unresolved              silently skip servers whose binary is not installed on this host
      --write-config                 also merge approved server definitions into <config-dir>/mcp.yaml
      --write-untrusted-references   with --write-config: also write $VAR references, refused env keys and egress policy beyond the server's own url host from servers of packs that are not verified-signed into mcp.yaml, where references expand against your environment

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Approve one server without a recipe YAML. For stdio servers, supply
--command, plus the exact --arg (repeatable), --work-dir and --env KEY=VALUE
(repeatable) it is launched with: the entry pins them, with the binary's
SHA-256, and approves only that launch. For SSE/HTTP servers, supply --url.
The binary is resolved and hashed at the current path before the entry is written.
Pass --project to approve, exactly as defined, the server the current
workspace's .sonny/mcp.yaml defines under <name>: a repository's server
launches only on an entry that pins its whole definition.
Pass --write-config to also add the server definition to mcp.yaml.
An SSE server written with --write-config needs --egress-allow-host
naming its URL host (egress.allow_hosts); a loopback http server also
needs --egress-allow-plain-http and --egress-allow-private-networks.

Usage:
  sonny mcp approve server <name> [flags]

Flags:
      --arg stringArray                 with --command: one argument the server is launched with (repeatable, in order); the entry pins the argv
      --command string                  absolute path or bare name of the stdio server binary
      --dry-run                         print what would be approved (command, args, env names, url, auth shape) and write nothing
      --egress-allow-host stringArray   with --url --write-config: host the SSE server may reach (egress.allow_hosts; repeatable; a leading "." admits strict subdomains); required for an SSE entry
      --egress-allow-plain-http         with --url --write-config: permit an http:// URL on a loopback host (egress.allow_plain_http)
      --egress-allow-private-networks   with --url --write-config: permit a private or loopback destination (egress.allow_private_networks)
      --env stringArray                 with --command: KEY=VALUE the server is launched with (repeatable; VALUE may be a $VAR reference); the entry pins the env keys and a digest, never a value
  -h, --help                            help for server
      --project                         approve the server <name> exactly as the current workspace's .sonny/mcp.yaml defines it
      --url string                      full http(s):// URL for an SSE/HTTP server
      --work-dir string                 with --command: the working directory the server is launched in; the entry pins it
      --write-config                    also merge the approved server definition into <config-dir>/mcp.yaml

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Connect to a configured MCP server (operator-only; not a model tool).
Mints an administrative authority with a stated reason and refuses to run
without one. The connection is scoped to this command process.

Usage:
  sonny mcp connect <server> [flags]

Flags:
      --connect-timeout duration   MCP connect timeout (default 15s)
  -h, --help                       help for connect
      --mcp-config string          MCP sidecar config path (default: standard discovery)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Disconnect from a configured MCP server (operator-only; not a model tool).
Mints an administrative authority with a stated reason and refuses to run
without one. Connections are session-scoped, so this verifies the teardown
path rather than closing a long-lived connection.

Usage:
  sonny mcp disconnect <server> [flags]

Flags:
      --connect-timeout duration   MCP connect timeout (default 15s)
  -h, --help                       help for disconnect
      --mcp-config string          MCP sidecar config path (default: standard discovery)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List resolved MCP servers (config + recipe), redacted, with digests

Usage:
  sonny mcp list [flags]

Flags:
      --connect                    connect to enabled servers and enumerate their tools (spawns processes)
      --connect-timeout duration   per-server MCP connect timeout (only used with --connect) (default 15s)
      --format string              text|json (default "text")
  -h, --help                       help for list
      --mcp-config string          MCP sidecar config path (default: standard discovery)
      --recipe-file string         merge this pack's inline mcp.servers over the config

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run Sonny tools or a traced external MCP proxy over stdio

Usage:
  sonny mcp-server [flags]

Flags:
      --allow-host-effects           explicitly allow model-driven filesystem, network, and process effects on this host
      --allowed-tools string         comma-separated tool names to expose (empty exposes none)
  -h, --help                         help for mcp-server
      --proxy-config string          private JSON file containing allowlisted upstream MCP definitions
      --proxy-server string          server name from --proxy-config to expose through Sonny
      --realm-contained              require and use Sonny's verified realm process environment
      --supervisor-endpoint string   connect to an existing supervisor for admitted SCI tools
      --supervisor-session string    existing supervisor session whose SCI exposure is served
      --supervisor-tenant string     tenant authenticated by the supervisor

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

The mesh command group provides tools for managing distributed LLM sessions
across multiple nodes. Sessions can be pushed to remote nodes, transferred between
nodes, and continue running even when disconnected from the local terminal.

Use 'mesh serve' to start a mesh node, 'mesh push' to send sessions to remote nodes,
and 'mesh attach' to connect to running sessions.

Usage:
  sonny mesh [command]

Available Commands:
  adopt       Adopt a running session using a pinned, single-use offer
  attach      Attach to a running session
  detach      Detach from a session
  exec        Run a shell command on a remote mesh node via its A2A endpoint
  host        Bootstrap and manage SSH-reachable mesh hosts
  human-key   Manage the keys that let a device attach to mesh sessions as their human
  identity    Provision and inspect mesh node identity material
  list        List nodes and sessions
  managed     Provision and verify managed-worker authority for mesh serve
  nodes       List mesh nodes
  peers       Print this daemon's mesh participation snapshot as JSON
  push        Push a session to a remote node
  relate      Grant, revoke and list peer relationships between root sessions on two nodes
  serve       Start a mesh node
  sessions    List mesh sessions
  terminate   Terminate one or many mesh sessions
  transfer    Transfer a session to another node

Flags:
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
  -h, --help                     help for mesh
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny mesh [command] --help" for more information about a command.

Adopt a running session using a pinned, single-use offer

Usage:
  sonny mesh adopt [command]

Available Commands:
  offer       Create a short-lived adoption code and QR payload
  redeem      Redeem an adoption offer with certificate pinning

Flags:
  -h, --help   help for adopt

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh adopt [command] --help" for more information about a command.

Create a short-lived adoption code and QR payload

Usage:
  sonny mesh adopt offer <session> [flags]

Flags:
      --address string      reachable source mesh address (default: mesh.advertise_address or mesh.endpoint)
      --cert string         source node certificate presented by the mesh listener (default: mesh.tls_cert or <config>/mesh/node.crt)
      --control-db string   source SQLite control database (default: mesh.control_db or <data>/control.db)
  -h, --help                help for offer
      --kind string         trust ceremony: personal or organization (default inferred from session tenant)
      --max-guesses int     failed proof attempts before the offer is burned (default 5)
      --namespace string    owner namespace (inferred for a personal tenant; required for organization adoption)
      --qr                  render the sonny://adopt payload as a terminal QR code
      --ttl duration        offer lifetime (maximum 15m) (default 5m0s)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Redeem an adoption offer with certificate pinning

Usage:
  sonny mesh adopt redeem <code-or-uri> [flags]

Flags:
      --address string   source mesh address (required for a short code; URI carries it)
  -h, --help             help for redeem

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Attach to a running session on any mesh node.

This connects your terminal to the session's input/output streams,
allowing you to interact with it as if it were local.

Example:
  sonny mesh attach abc123

  # Attach with input disabled (read-only)
  sonny mesh attach abc123 --read-only

Usage:
  sonny mesh attach <session-id> [flags]

Flags:
  -h, --help        help for attach
      --read-only   attach in read-only mode

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Detach from a specified session.

By default, the session continues running in the background.
Use --stop to pause the session instead.

Example:
  # Detach and keep the session running
  sonny mesh detach abc123

  # Detach and pause the session
  sonny mesh detach abc123 --stop

Usage:
  sonny mesh detach [session-id] [flags]

Flags:
  -h, --help           help for detach
      --keep-running   keep session running in background (default true)
      --stop           pause session instead of backgrounding

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Dispatch a shell command to a remote mesh node and stream the
result back. The node must be running a sonny a2a serve --shell-mode
instance (authenticated with --auth-token-file; pass the same token with
--token-file). The token is sent only over https:// or to a loopback
address (front the node with a TLS-terminating proxy or an SSH tunnel)
unless --allow-insecure-token is given. The URL mapping comes from the mesh.agents block of your own
config ($HOME/.sonny.yaml or --config; an untrusted workspace's .sonny.yaml
cannot set it):

  mesh:
    agents:
      lothiriel-mesh: "https://lothiriel.example:18443"

Examples:
  sonny mesh exec --node lothiriel-mesh --token-file ~/.config/sonny/a2a.token -- whoami
  sonny mesh exec --node lothiriel-mesh -- "ls -la /tmp"

Usage:
  sonny mesh exec <command...> [flags]

Flags:
      --allow-insecure-token   allow sending the --token-file token over plain http:// to a non-loopback node (isolated networks only)
  -h, --help                   help for exec
      --node string            mesh node name (must have a mesh.agents mapping)
      --timeout duration       command wall-clock timeout (default 1m0s)
      --token-file string      file holding the bearer token the node's a2a serve --shell-mode --auth-token-file requires

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Bootstrap, update, remove and inspect mesh hosts reached over SSH
(mesh/sshboot): a host with no locally reachable mesh port yet, joined to the
mesh by dialing it over SSH, installing sonny, issuing it a node identity and
tunneling its gRPC and Synapse traffic back through the SSH connection.

On first contact with a host, its SSH host key is not yet pinned: the dial
fails and reports the key's SHA256 fingerprint so it can be confirmed out of
band (the host's own console, a provisioning record, etc.) before re-running
the command with --fingerprint to confirm and pin it.

Usage:
  sonny mesh host [command]

Available Commands:
  add         Bootstrap a new SSH-reachable mesh host
  list        List SSH-managed mesh hosts
  remove      Revoke identity, stop the service and forget an SSH-managed host
  status      Show one SSH-managed mesh host's enrollment state
  update      Resume or upgrade an already-bootstrapped mesh host

Flags:
  -h, --help   help for host

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh host [command] --help" for more information about a command.

Bootstrap a new SSH-reachable mesh host

Usage:
  sonny mesh host add [flags]

Flags:
      --fingerprint string   confirm the remote host key's SHA256 fingerprint (required on first contact with an unpinned host)
  -h, --help                 help for add
      --host string          host name and address to dial (required)
      --key string           path to the SSH private key
      --port int             remote SSH port (default 22)
      --prefix string        remote install prefix (default /opt on POSIX, C:\ProgramData on Windows)
      --user string          remote SSH user

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

List SSH-managed mesh hosts

Usage:
  sonny mesh host list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Revoke identity, stop the service and forget an SSH-managed host

Usage:
  sonny mesh host remove [flags]

Flags:
      --fingerprint string   confirm the remote host key's SHA256 fingerprint (required on first contact with an unpinned host)
  -h, --help                 help for remove
      --host string          host name and address to dial (required)
      --key string           path to the SSH private key
      --port int             remote SSH port (default 22)
      --prefix string        remote install prefix (default /opt on POSIX, C:\ProgramData on Windows)
      --purge                also delete the installed binary
      --user string          remote SSH user

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Show one SSH-managed mesh host's enrollment state

Usage:
  sonny mesh host status [flags]

Flags:
  -h, --help          help for status
      --host string   host name (required)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Resume or upgrade an already-bootstrapped mesh host

Usage:
  sonny mesh host update [flags]

Flags:
      --fingerprint string   confirm the remote host key's SHA256 fingerprint (required on first contact with an unpinned host)
  -h, --help                 help for update
      --host string          host name and address to dial (required)
      --key string           path to the SSH private key
      --port int             remote SSH port (default 22)
      --prefix string        remote install prefix (default /opt on POSIX, C:\ProgramData on Windows)
      --user string          remote SSH user

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

A mesh remote tab acts as the session's human (relayed /plan approve, proceed, revise, pause, resume, cancel) only when it attaches directly to the owning node and signs the stream with a device key the owning node enrolled for the person's mesh identity. Run `create` on the device, then `enroll` on the owning node.

Usage:
  sonny mesh human-key [command]

Available Commands:
  create      Create (or show) this device's mesh human-attach key and print its public key line
  enroll      Enrol a device key on this node for one user mesh identity (operator only)
  list        List this node's enrolled human-attach keys
  revoke      Revoke an enrolled human-attach key on this node (applies at once, including to streams already attached)

Flags:
  -h, --help   help for human-key

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh human-key [command] --help" for more information about a command.

Create (or show) this device's mesh human-attach key and print its public key line

Usage:
  sonny mesh human-key create [flags]

Flags:
  -h, --help   help for create

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Enrol a device key on this node for one user mesh identity (operator only)

Usage:
  sonny mesh human-key enroll --subject <user SPIFFE ID> '<public key line>' [flags]

Flags:
  -h, --help             help for enroll
      --subject string   the person's mesh user SPIFFE ID (spiffe://<domain>/tenant/<tenant>/user/<name>)
      --ttl duration     how long the enrolment lasts (at most 8760h) (default 2160h0m0s)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

List this node's enrolled human-attach keys

Usage:
  sonny mesh human-key list [flags]

Flags:
  -h, --help   help for list

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Revoke an enrolled human-attach key on this node (applies at once, including to streams already attached).

A key id is unpadded base64url, so it can begin with '-'. Pass such an id after `--` (sonny mesh human-key revoke -- <key id>) or as --key-id=<key id>, so it is not read as a flag.

Usage:
  sonny mesh human-key revoke [--] <key id> | revoke --key-id=<key id> [flags]

Flags:
  -h, --help        help for revoke
      --key-id --   the key id to revoke (use this or -- when the id begins with '-')

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Manage the mTLS identity and RBAC policy a mesh node presents.

Provisioning is an explicit operator step; it is never run automatically by a
node at startup. A node with no provisioned identity still fails closed: it
refuses a non-loopback bind and denies every RPC.

Usage:
  sonny mesh identity [command]

Available Commands:
  provision   Write a mesh CA, a per-node SVID, and a default node-role authz.yaml

Flags:
  -h, --help   help for identity

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh identity [command] --help" for more information about a command.

Provision the mTLS identity and RBAC policy for one mesh node.

Writes, under --dir: the mesh CA (ca.crt + ca.key, reused if already present so
successive nodes chain to a common trust root), a per-node SVID (node.crt +
node.key) for spiffe://<trust-domain>/node/<node>, and a default node-role
authz.yaml (only when absent — an existing operator policy is never
overwritten). The default policy grants the built-in node role the mesh RPCs and
nothing else, so a configured node is fail-closed-but-usable.

Guarding the CA private key (ca.key) is the operator's decision; it is written
0600 so the CA can issue further node leaves.

Example:
  sonny mesh identity provision --dir /etc/sonny/mesh --trust-domain mesh.local --node node-a

Usage:
  sonny mesh identity provision [flags]

Flags:
      --dir string            directory to write identity material into (required)
  -h, --help                  help for provision
      --node string           node name for the SVID (spiffe://<trust-domain>/node/<node>) (required)
      --trust-domain string   SPIFFE trust domain for the CA and node SVID (default "mesh.local")
      --ttl duration          validity of the issued node SVID (default 8760h0m0s)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Declared names/aliases: list, ls.

List nodes and sessions

Usage:
  sonny mesh list [flags]

Aliases:
  list, ls

Flags:
  -h, --help   help for list

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Provision the managed-worker authority a production 'sonny mesh serve' needs
before it starts, and verify a provisioned node.

A managed worker starts only with a private deployment manifest
(--managed-manifest) naming its control database, a public verification
keyring, one signed policy per tenant, a grant signing keyring and the
sponsorship each tenant's grants cite. These commands write each of them:

  init         create (or import) the policy signing key, once per fleet
  enroll-node  create a node's grant signing key and trust it
  sign-policy  sign or re-sign a tenant policy before it expires
  seed         create or migrate control.db: freeze epoch, sponsorship, plan
  manifest     write the managed-worker deployment manifest
  verify       run mesh serve's startup validation without serving

Every command is idempotent and ends with "changed: yes" or "changed: no".
No command replaces an existing key unless --force is passed, and none
prints key material. Run seed, manifest and verify as the daemon user, so
the files they create are owned by it.

Usage:
  sonny mesh managed [command]

Available Commands:
  enroll-node Create a node's grant signing key and trust it
  init        Create or import the policy signing key
  manifest    Write the managed-worker deployment manifest
  seed        Create or migrate control.db and seed each tenant's authority
  sign-policy Sign or re-sign a tenant policy
  verify      Run mesh serve's managed-worker startup validation without serving

Flags:
  -h, --help   help for managed

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh managed [command] --help" for more information about a command.

Create the node's grant signing key and add its public key to the node's
verification keyring.

Each node issues the grant for every managed tool call with its own key. The
raw 64-byte Ed25519 key is written to --grant-key (0600) and never leaves the
node; --grant-keyring is the keyring document the manifest names as
grant_issuance.signing_keys. Its public key is added to --verification-keys,
together with every entry of each --trust keyring (normally the policy
verification keys written by init). An existing key is reused; --force
rotates it. A trusted id that already names a different key is refused.

Example:
  sonny mesh managed enroll-node node-a \
    --grant-key /var/lib/sonny/authority/grant.key \
    --grant-keyring /etc/sonny/authority/grant-keyring.json \
    --verification-keys /etc/sonny/authority/verification-keys.json \
    --trust /etc/sonny/authority/policy-verification-keys.json

Usage:
  sonny mesh managed enroll-node <node> [flags]

Flags:
      --force                      rotate: replace an existing grant key and keyring with a new key
      --grant-key string           raw Ed25519 grant private key, created when absent (required)
      --grant-keyring string       grant keyring document the manifest names (required)
  -h, --help                       help for enroll-node
      --key-ttl duration           validity of a newly written key (default 8760h0m0s)
      --trust stringArray          verification keyring whose entries the node also trusts (repeatable)
      --verification-keys string   the node's public verification keyring (required)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Create the fleet's tenant-policy signing key, or import an existing one.

When --policy-key is absent a new Ed25519 key is generated and written there
(0600, raw 64 bytes). When it exists it is imported as-is: copy the key from
your secret store (for example Vault) to --policy-key first. The command then
writes a keyring document naming the key (--policy-keyring) and adds the
public key to --verification-keys, which enroll-node merges into each node's
verification keyring with --trust.

An existing keyring that names another key is refused. --force rotates: it
generates a new key, replaces the private key file and the keyring, and keeps
the old public key in --verification-keys. The private key is never printed.

Example:
  sonny mesh managed init \
    --policy-key /secure/sonny/policy.key \
    --policy-keyring /secure/sonny/policy-keyring.json \
    --verification-keys /secure/sonny/policy-verification-keys.json

Usage:
  sonny mesh managed init [flags]

Flags:
      --force                      rotate: replace an existing key and keyring with a new key
  -h, --help                       help for init
      --key-ttl duration           validity of a newly written key (default 8760h0m0s)
      --policy-key string          raw Ed25519 policy private key, created when absent (required)
      --policy-keyring string      keyring document naming the policy key (required)
      --verification-keys string   public verification keyring to add the policy key to (required)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Write the private deployment manifest mesh serve reads from
--managed-manifest (schema sonny.mesh.serve.managed/v1).

Each tenant's sponsorship is the one seed provisions for its current policy,
unless --sponsor tenant=id names another. Policies are verified against
--verification-keys first, so an expired policy is refused here rather than
at startup. A manifest that already has this content is left untouched.

Example:
  sonny mesh managed manifest --out /etc/sonny/mesh/managed-worker.json \
    --control-db /var/lib/sonny/control.db \
    --verification-keys /etc/sonny/authority/verification-keys.json \
    --policy /etc/sonny/authority/policies/acme.json \
    --grant-keyring /etc/sonny/authority/grant-keyring.json

Usage:
  sonny mesh managed manifest [flags]

Flags:
      --agent-messaging            set agent_messaging: native hosted parent messaging
      --agent-peer-relationships   set agent_peer_relationships: cross-node peer relationships (requires --agent-messaging)
      --control-db string          control database; pass mesh serve the same --control-db (required)
      --grant-keyring string       the node's grant keyring from enroll-node (required)
  -h, --help                       help for manifest
      --out string                 manifest file to write (required)
      --policy stringArray         signed tenant policy (repeatable, required)
      --sponsor stringArray        tenant=sponsor-id overriding the seeded sponsorship (repeatable)
      --verification-keys string   the node's verification keyring (required)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Create (owner-only) or migrate the control database and, for each signed
policy, seed what mesh serve's grant issuance requires:

  - the tenant's freeze epoch;
  - a sponsorship bound to the policy, named by --human, ending when the
    policy expires, with the effect and budget ceilings below;
  - an active plan revision for the tenant's managed work spec.

Everything is written through the control store, never with SQL. A re-run
changes nothing. A re-signed policy gets a new sponsorship and the next
plan revision; the 'sponsor <tenant>:' lines name the sponsorship ids, which
manifest derives the same way. Expired or unverifiable policies are refused.

Example:
  sonny mesh managed seed --control-db /var/lib/sonny/control.db \
    --verification-keys /etc/sonny/authority/verification-keys.json \
    --policy /etc/sonny/authority/policies/acme.json --human user:ops-oncall

Usage:
  sonny mesh managed seed [flags]

Flags:
      --control-db string          SQLite control database mesh serve uses (required)
      --cost-units float           per-grant cost-unit ceiling (default 1)
      --effect strings             effect tags the sponsorship allows (repeatable; add sensitive_read only with a matching policy rule) (default [read,write,delete,execute,network,publish])
  -h, --help                       help for seed
      --human string               human subject who sponsors the managed work (required)
      --issuer string              issuer recorded for the sponsoring human (default "sonny-mesh-managed-seed")
      --policy stringArray         signed tenant policy (repeatable, required)
      --spawns int                 per-grant process-spawn ceiling (default 8)
      --tokens int                 per-grant token ceiling (default 1)
      --tool-calls int             per-grant tool-call ceiling (default 64)
      --verification-keys string   the node's verification keyring (required)
      --wall-time duration         per-grant wall-time ceiling (a grant lasts at most 1h) (default 2h0m0s)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Sign the tenant's managed policy with the policy key and write it to --out.

The policy expires after --ttl. A re-run keeps the existing policy while it
is signed by this key, its rules are unchanged and it expires later than
--renew-before from now; otherwise it signs the next generation, superseding
the current one. Run it on a schedule to renew policies before they expire,
then run seed and manifest on each node and restart mesh serve: a re-signed
policy has a new digest, so it needs a new sponsorship.

--rules is a JSON array of tenant policy rules (see docs/TENANT_POLICY.md).
Without it the policy allows attested humans every action and denies
managed-worker provisioning actions. A policy this key cannot verify is
replaced only with --force; a policy for another tenant never is.

Example:
  sonny mesh managed sign-policy --tenant acme \
    --policy-keyring /secure/sonny/policy-keyring.json \
    --out /secure/sonny/policies/acme.json --ttl 720h

Usage:
  sonny mesh managed sign-policy [flags]

Flags:
      --force                   re-sign even when the existing policy is current
  -h, --help                    help for sign-policy
      --out string              signed policy file to write (required)
      --policy-keyring string   policy keyring document written by init (required)
      --reason string           change reason recorded in the policy
      --renew-before duration   re-sign an existing policy that expires within this window (default 168h0m0s)
      --rules string            JSON array of policy rules (default: attested-human access, no worker provisioning)
      --tenant string           tenant the policy governs (required)
      --ttl duration            policy lifetime (default 720h0m0s)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Check a provisioned node with the validation 'sonny mesh serve' runs before
it opens a listener, and report every problem rather than the first.

It checks the manifest; that --control-db resolves to its control database;
the private-file rules for every file it names; the verification keyring and
each signed policy; the trusted isolation configuration; the grant signing
keyring; the authority plane, grant issuance and every sponsorship; and the
managed authority and audit startup check. It also checks each tenant's
freeze epoch and active plan, which every session needs. It warns when a
policy or sponsorship expires within --expiry-warning.

Run it as the daemon user with the daemon's environment: file ownership and
the isolation configuration are judged for the user that runs it. Like mesh
serve, it opens the control database and applies pending migrations. It does
not contact the Docker engine; run 'sonny isolation doctor' for that.
--control-db resolves as mesh serve's does: the flag, then SONNY_CONTROL_DB,
then mesh.control_db, then <data>/control.db.

Example:
  sonny mesh managed verify --managed-manifest /etc/sonny/mesh/managed-worker.json \
    --control-db /var/lib/sonny/control.db

Usage:
  sonny mesh managed verify [flags]

Flags:
      --control-db string         control database mesh serve is given (default: as mesh serve resolves it)
      --expiry-warning duration   warn when a policy or sponsorship expires within this window (default 168h0m0s)
  -h, --help                      help for verify
      --managed-manifest string   managed-worker deployment manifest (required)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

List all nodes in the mesh network.

Example:
  # List all nodes
  sonny mesh nodes

  # Filter by region
  sonny mesh nodes --region us-west

Usage:
  sonny mesh nodes [flags]

Flags:
  -h, --help            help for nodes
      --region string   filter by region
      --zone string     filter by zone

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Print the local supervisor daemon's mesh status: health, its own node
identity, a bounded page of its peer roster, a bounded page of its owner
device roster, and its locally known session counts by state
(sonny/ops.mesh).

This talks to the local supervisor daemon over the same connection
'sonny supervisor status' uses, not to a remote mesh node's gRPC
endpoint -- it does not take --endpoint/--client-cert from the mesh
command group's persistent flags.

Example:
  # Print this daemon's mesh status
  sonny mesh peers

  # Page through a large peer/device roster
  sonny mesh peers --cursor <cursor-from-previous-call> --limit 50

Usage:
  sonny mesh peers [flags]

Flags:
      --cursor string     opaque paging cursor from a previous call
      --endpoint string   supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help              help for peers
      --limit int32       bound the peer/device page (<=0 selects the backend default, capped at 256)
      --tenant string     tenant this connection speaks for (default "default")

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Create a new session on a remote mesh node.

The session will run on the remote node and continue even if you disconnect.
Use 'mesh attach' to reconnect to the session later.

The target node runs a recipe it already has. Name it with --recipe, or give a
local recipe file with --file and its recipe ID is sent. The session works in
--session-dir on the target node: an absolute path that must exist there and
lie under its SONNY_MESH_CWD_ROOTS. It defaults to the current directory.

Example:
  # Push to best available node
  sonny mesh push --pack my-pack

  # Push to specific node, working in a directory on that node
  sonny mesh push --node worker-1 --pack my-pack --session-dir /srv/work

  # Push the pack a local file names and follow output
  sonny mesh push --file pack.yaml --follow

Usage:
  sonny mesh push [flags]

Flags:
  -f, --file string          local prompt pack file whose pack ID is sent (or use --pack)
      --follow               follow session output after push
  -h, --help                 help for push
      --node string          target node ID (default: best available)
      --persist              persist session on detach (default true)
      --recipe string        ID of the pack the target node runs (or use --file)
      --session-dir string   absolute working directory for the session on the target node (default: the current directory)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Manage this node's half of an operator-granted peer relationship between a
root session hosted here and a root session hosted on another node of the same
mesh and tenant. Mail flows only after BOTH nodes hold a grant for the same
relationship ID. Either half alone authorizes nothing.

The node must run with "agent_peer_relationships": true in its managed
manifest. Each call needs an authenticated user certificate (--client-cert)
and an explicit authz binding for /mesh.v1.AgentPeerAdminService methods.

Typical flow:
  # On node B: find the agent ID of the session to relate
  sonny mesh relate endpoint <session-b> --endpoint node-b:50052 ...
  # On node A: grant A's half (prints the relationship ID)
  sonny mesh relate grant --local-session <session-a> --remote-node node-b \
    --remote-session <session-b> --remote-agent <agent-b> --expires 720h
  # On node B: grant the mirror half with the same relationship ID
  sonny mesh relate grant --relationship <id> --local-session <session-b> \
    --remote-node node-a --remote-session <session-a> --remote-agent <agent-a> --expires 720h
  # Either node: inspect, or revoke its half (final; fences both directions)
  sonny mesh relate list
  sonny mesh relate revoke <id> --expected-revision 1

Usage:
  sonny mesh relate [command]

Available Commands:
  endpoint    Print the node and agent ID of a root session hosted on this node
  grant       Grant or renew this node's half of a peer relationship
  list        List this node's peer grants and whether the other node was observed
  revoke      Revoke this node's half of a peer relationship (final)

Flags:
  -h, --help   help for relate

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Use "sonny mesh relate [command] --help" for more information about a command.

Print the node and agent ID of a root session hosted on this node

Usage:
  sonny mesh relate endpoint <session-id> [flags]

Flags:
  -h, --help   help for endpoint

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Grant this node's half of a peer relationship. Without --relationship a new
relationship ID is generated; give the same ID to the other node's grant.
--expires takes a duration (e.g. 720h) or an RFC 3339 time, at most 90 days
ahead. --kinds narrows the message kinds (info_request, info_response,
intent); the default is info_request, whose replies are also carried.

To renew, repeat the grant with --expected-revision set to the current
revision. A retry of the same change must reuse its --change-id.

Usage:
  sonny mesh relate grant [flags]

Flags:
      --change-id string         change ID for an exact retry (default: generate one)
      --expected-revision uint   current revision when renewing (0 creates)
      --expires string           expiry: a duration such as 720h or an RFC 3339 time (required)
  -h, --help                     help for grant
      --kinds strings            message kinds to carry (default info_request)
      --local-session string     root session hosted on this node
      --relationship string      relationship ID shared by both nodes (default: generate one)
      --remote-agent string      the other root session's agent ID (from 'relate endpoint' on its node)
      --remote-node string       node that hosts the other root session
      --remote-session string    the other root session's ID

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Declared names/aliases: list, ls.

List this node's peer grants and whether the other node was observed

Usage:
  sonny mesh relate list [flags]

Aliases:
  list, ls

Flags:
      --after string   list grants after this relationship ID
  -h, --help           help for list
      --limit uint32   maximum grants to list (at most 256) (default 50)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Revoke this node's half. Delivery stops in both directions at the next route
resolution on either node, and the relationship cannot be granted again: a
new relationship needs new root sessions.

Usage:
  sonny mesh relate revoke <relationship-id> [flags]

Flags:
      --change-id string         change ID for an exact retry (default: generate one)
      --expected-revision uint   current revision of the grant (required)
  -h, --help                     help for revoke

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Start a mesh node that can host and transfer sessions.

The node will:
- Listen for gRPC client connections for session streaming and compatibility
- Advertise on the Synapse QUIC peer plane using protobuf framing by default
- Retain WebSocket and JSON negotiation for rolling-upgrade compatibility
- Accept sessions from other nodes
- Send heartbeats to announce availability

Example:
  # Start a basic mesh node
  sonny mesh serve \
    --managed-manifest /etc/sonny/mesh/managed-worker.json \
    --control-db /var/lib/sonny/control.db \
    --grpc 127.0.0.1:50052 --synapse-listen 127.0.0.1:50053

  # Multi-node mesh with mTLS on both the gRPC and Synapse planes
  sonny mesh serve \
    --managed-manifest /etc/sonny/mesh/managed-worker.json \
    --control-db /var/lib/sonny/control.db \
    --advertise-addr host:50052 \
    --mesh-peer quic://peer:50053 \
    --name "worker-1" \
    --region us-west \
    --cert node.crt --key node.key --ca ca.crt

Usage:
  sonny mesh serve [flags]

Flags:
      --advertise-addr string     address peers should use to reach this node's gRPC surface, e.g. a reachable tailscale DNS name like "lothiriel:9052" (default: --grpc); required on a multi-host mesh because the bind address is not routable from a peer
      --authz-policy string       path to the RBAC policy YAML (default /etc/sonny/mesh/authz.yaml)
      --ca string                 TLS CA certificate file
      --cert string               TLS certificate file
      --control-db string         path to the SQLite mesh control-plane DB (default <data>/control.db)
      --coordinator string        mesh coordinator address (if joining existing mesh)
      --grpc string               gRPC listen address (default ":50052")
  -h, --help                      help for serve
      --key string                TLS key file
      --label strings             node labels (key=value)
      --managed-manifest string   private managed-worker deployment manifest (required in production builds)
      --max-sessions int          maximum concurrent sessions (default 10)
      --mesh-peer strings         quic:// peer URL (preferred), or ws:// development / wss:// mTLS compatibility URL (repeatable)
      --models strings            supported models
      --name string               node name (default: $(whoami)@$(hostname))
      --node-id string            node ID (default: auto-generated UUID)
      --providers strings         supported LLM providers
      --recipes strings           available prompt packs
      --region string             node region (for routing)
      --synapse-listen string     address Synapse listens on for QUIC/UDP (default) and WebSocket/TCP compatibility (default ":50053")
      --trust-domain string       SPIFFE trust domain for peer SVIDs (default mesh.local)
      --zone string               node zone (for routing)

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

List all sessions across the mesh.

A session whose node restarted while it ran, or whose node lost its host
lease, is listed as INTERRUPTED. It is not running, refuses input, and is
not re-hosted. Start a new session, and remove the interrupted one with
'sonny mesh terminate <session-id>'.

Example:
  # List active sessions
  sonny mesh sessions

  # List all sessions including completed
  sonny mesh sessions --all

Usage:
  sonny mesh sessions [flags]

Flags:
  -a, --all                          show all sessions including completed
  -h, --help                         help for sessions
      --isolation-assurance string   filter by achieved assurance
      --isolation-backend string     filter by achieved backend
      --isolation-state string       filter by isolation verification state
      --search string                filter by session, pack, model, provider, or node text
      --sort string                  sort by updated, assurance, backend, or isolation-state (default "updated")

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Declared names/aliases: terminate, kill, stop.

Terminate a running session.

Session IDs may be supplied as an 8-character (or longer) unique
prefix; the prefix is expanded via ListSessions and rejected when
zero or >1 sessions match.

Examples:
  # Terminate one session by full ID or unique prefix
  sonny mesh terminate abc123

  # Terminate every session on a specific node
  sonny mesh terminate --node worker-1 --all

  # Terminate every session everywhere (requires --all and --all-nodes)
  sonny mesh terminate --all --all-nodes

Usage:
  sonny mesh terminate [session-id] [flags]

Aliases:
  terminate, kill, stop

Flags:
      --all             terminate every matching session (requires --node or --all-nodes)
      --all-nodes       with --all, terminate sessions on every node
      --force           force terminate without graceful shutdown
  -h, --help            help for terminate
      --node string     node ID for --all (terminates all sessions on this node)
      --reason string   reason for termination
      --yes             skip the interactive confirm for --all or --all-nodes

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Transfer a running session to another mesh node.

The session state is serialized, transferred, and resumed on the target node.
This is useful for load balancing or moving sessions closer to resources.

Example:
  sonny mesh transfer abc123 worker-2

Usage:
  sonny mesh transfer <session-id> <target-node> [flags]

Flags:
      --force   force transfer even if session is active
  -h, --help    help for transfer

Global Flags:
      --analysis-json string     versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --client-ca string         CA bundle file used to verify the server cert
      --client-cert string       client TLS certificate file (PEM) for mTLS-protected mesh endpoints
      --client-key string        client TLS key (PEM filesystem path OR pkcs11: URI per RFC 7512)
      --client-key-pin string    PIN file for PKCS#11 client key (optional)
      --config string            config file (default: .sonny.yaml in working directory)
      --debug                    enable debug mode
      --dev-insecure-transport   DEVELOPMENT ONLY: allow plaintext, unauthenticated mesh channels on loopback addresses (equivalent to SONNY_MESH_INSECURE_DEV_PROFILE=i-accept-plaintext-mesh-not-for-production)
      --endpoint string          mesh gRPC endpoint (default: mesh.endpoint config, SONNY_MESH_ADDR, or localhost:50052)
      --log-format string        log format: text|json (default "text")
      --log-level string         log level: debug|info|warn|error (default "warn")
  -m, --model string             model to use (overrides pack default)
  -p, --provider string          LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations       suppress schema and legacy recipe-name deprecation warnings
      --server-name string       SNI / cert-SAN match target (required when --client-cert is set)
  -C, --workdir string           working directory (default ".")

Inspect the merged model catalog (models.yaml plus models.d/*.yaml),
see which source/model wins each category under the active routing
policy, refresh cached endpoint pricing, and view or override the
runtime fitness overlay used for category rotation.

Usage:
  sonny models [command]

Available Commands:
  bakeoff     Measure every model of a source on the same eval cases and promote the measured winner
  default     Show or clear the remembered default model
  detail      Show one model with its per-category tuning, evidence, and capability decisions
  disable     Turn a model source off for this profile without deleting its definition or credential
  enable      Turn a disabled model source back on for this profile
  fitness     View or override observed per-category model fitness
  list        Show each category's winning source/model under the routing policy
  prices      Show cached model pricing; --refresh fetches from source pricing endpoints

Flags:
  -h, --help   help for models

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny models [command] --help" for more information about a command.

bakeoff runs the SAME recipe eval cases (--suite-file, or the pack's inline
pack_eval_suite) against every chat model of one or more catalog sources
(--source, repeatable or comma-separated), --repeat times each, and ranks
all of them in ONE table by the Wilson lower bound of their pass rate. Every
model is scored by the same rule: there is no incumbent, prior or baseline
input, and errors count as failures for everyone. By default every chat
model of each source that serves at least one category is enrolled, so new
fleet models are measured without anyone adding them by hand. A
--candidates id served by more than one source must be written source/model.

--apply <models.d file> writes each measured model of that file's own
source(s) with its fitness, a complete evidence block and a tuning_ref
(comments preserved). It refuses when a model declares the category there
but was not measured, so an unmeasured prior can never outrank measured
models. --apply-scope measured (the default is all) instead writes only the
models measured in this run and leaves every other declarer of the category
alone when it already carries a prior measurement (reported as "kept: prior
measurement <tuning_ref>"); an unmeasured prior is demoted strictly below the
category's lowest measured fitness in the file, without evidence, and
reported loudly. That is how a degraded model is --exclude'd from a
promotion run and later re-measured alone (--candidates <model>) and merged.
Evidence records the suite digest and judge in its evaluator; a kept
measurement taken on another suite, judge or evaluator is merged with a
WARNING that the two are not comparable. The output cap belongs to the category's workload: a measured entry
whose effective max_tokens would fall below the category's previous winner's
gains settings.max_tokens at that cap (clamped by --max-output-limits).
--measured-out SOURCE=FILE records SOURCE's measured models into a
measured overlay (version 1, entries of model/category/fitness/tuning_ref/
evidence) for a source whose drop-in is owned elsewhere. Neither write
happens when a model errored at the provider on every case. The exception
is an effort arm the provider refused with a 400/422 configuration
rejection on every case run: that model does not support that effort's
configuration, so the arm is reported as UNSUPPORTED (stderr, the text
table and the report's "unsupported" list, with the provider's message),
left out of the ranking, and the other arms are still written.

--category may be repeated: categories that share one measurement (same
recipe and suites) are measured once and ranked once per category, with
per-category evidence; --apply/--measured-out write every listed category
and --out holds a JSON array of results. Fitness measures reply quality
only: response time changes over time, so a case the model does not answer
within its timeout_seconds is retried with --timeout-retry-seconds and, if it
still times out, dropped for that arm (--timeout-as-failure opts in to
scoring it as a failure instead). Any other infrastructure failure (a provider 429,
5xx, a transport error) is retried (--infra-retries; a 429 backs off on the
rate-limited schedule) and, if it still fails, dropped for THAT arm only and
reported as infra-dropped (the report's infra_drop_reasons counts each
arm's drops by reason_code). An unreadable or refusing shared judge, or an
unresolved outcome over real reply text, is handled the same way.
--judge-model may be an ordered comma list (primary,fallback,...): a judge
turn that fails on one judge -- a provider error such as a content-filter
400, a timeout, a refusal, or a reply still unreadable after its resample
-- is re-asked on the next, and only when every judge fails is the case
run dropped. The evidence's judge records the whole chain, and the
report's judge_fallbacks counts each arm's case runs that needed one. An empty
reply (no text, no provider or refusal signal) is retried too, but if it is
still empty it is that model's failure (empty_reply), never dropped. An arm
whose dropped share exceeds
--max-infra-drop refuses --apply/--measured-out (--out is still written).
--arm-case-concurrency gives every arm the same cap on cases in flight, so a
slow model cannot take the shared slots and overload its own deployment;
--source-case-concurrency caps the cases in flight against one source, so a
single self-hosted server is not overloaded.

Reasoning effort is measured, not assumed: an arm is (source, model,
effort). --reasoning-efforts auto (the default) measures each model at every
effort its --reasoning-capabilities declaration lists (a model with no
declared control keeps one arm at its row's routed config); off measures
one arm per model; a comma list measures those efforts on every model. Each
arm runs the category row's params with reasoning_effort set to its effort,
through the catalog request path routing uses. A model's result for a
category is its best arm; --apply writes that effort as the category's own
settings.reasoning_effort, so one row can carry different efforts for
different categories. Arms multiply the cost: models x efforts x cases x
--repeat. --list-arms prints the arms without calling a model.

Usage:
  sonny models bakeoff [flags]

Flags:
      --apply string                          models.d drop-in to write its own source's measured fitness into
      --apply-scope string                    all: refuse when a model declaring the category was not measured; measured: write only this run's models, keep prior measurements and demote unmeasured priors below the lowest measured fitness (default "all")
      --arm-case-concurrency int              at most N cases in flight per arm (source/model), the SAME for every arm, so a slow model cannot take the shared slots and overload its own deployment into timeouts; 0 = unlimited (default 4)
      --candidates strings                    models to measure, as model or source/model (default: every chat model of every --source)
      --case-concurrency int                  cases in flight across ALL passes (a case waits for a slot before its timeout starts); 1 runs each pass's cases serially (default 1)
      --category strings                      category to measure (required; repeatable or comma-separated -- categories sharing one measurement are measured once)
      --concurrency int                       passes run concurrently across models and repeats (default 1)
      --confidence float                      Wilson interval confidence in (0,1) (default 0.95)
      --dir string                            additional pack directory the --file pack's includes/parent resolve against (like pack eval --dir)
      --exclude strings                       models to leave out, as model or source/model
      --file string                           pack YAML whose prompt is evaluated (required)
      --format string                         text|json (default "text")
  -h, --help                                  help for bakeoff
      --infra-retries int                     retries of a case that fails on infrastructure (429, 5xx, transport) before it is dropped for that arm (default 4)
      --judge-model string                    grade every arm's judge-block cases with this shared judge (model or source/model; trusted); an ordered comma list primary,fallback,... re-asks a judge turn that fails on one judge (provider error such as a content-filter 400, timeout, refusal, or a reply still unreadable after its resample) on the next, the evidence's judge records the whole chain and the report counts judge_fallbacks per arm; unset, judged cases error for every arm alike
      --list-arms                             print the (source, model, effort) arms and their request params, then exit without calling a model
      --max-infra-drop float                  largest share of an arm's case runs that may be dropped for infrastructure before --apply/--measured-out are refused (default 0.05)
      --max-output-limits string              JSON/YAML map of model -> output-token limit; a category's carried max_tokens never exceeds it (unknown models are carried unclamped)
      --max-output-tokens int                 maximum tokens in each evaluated case response for an arm whose catalog row declares no max_tokens (a declared one is the routed cap and is used as is); 0 disables (default 4096)
      --measured-out stringArray              SOURCE=FILE: record SOURCE's measured models into a measured overlay file (repeatable)
      --min-samples int                       models with fewer measured samples are excluded (fitness 0) (default 1)
      --models string                         primary catalog file (default: models.yaml discovery)
      --out string                            write the JSON bakeoff result to this file
      --reasoning-capabilities auto           reasoning-capability declarations file (sonny.reasoning-capabilities/v1, repeatable) that auto enumerates efforts from
      --reasoning-efforts string              reasoning-effort arms per model: auto (every effort --reasoning-capabilities declares for it), off (one arm at the row's routed config), or a comma list (e.g. none,low,high) for every model (default "auto")
      --repeat int                            independent passes per model over every case (default 3)
      --source strings                        catalog source(s) whose models are measured, repeatable or comma-separated (default: the source serving the category's current winner)
      --source-case-concurrency stringArray   SOURCE=N: at most N cases in flight against SOURCE across all its arms (repeatable), so one self-hosted server is not overloaded
      --suite-file stringArray                eval suite YAML (repeatable; default: the pack's inline pack_eval_suite)
      --timeout-as-failure                    opt in to scoring a case the model did not answer within its timeout_seconds as that model's failure (never retried); by default response time is not measured: a timeout is retried with --timeout-retry-seconds, then dropped for that arm
      --timeout-retry-seconds int             per-attempt budget, in seconds, for retrying a case that timed out (0 keeps the case's own timeout_seconds) (default 900)
      --with-inline                           also run the pack's inline pack_eval_suite alongside --suite-file

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage the model sonny starts on when a run names none (the default
set with Tab in /models).

Examples:
  sonny models default --show    # print the current default (if any)
  sonny models default --clear   # forget the default model

Clearing removes only the default model; a default provider is kept.
With no default, startup picks the highest-fitness model for the
pack's default profile category.

Usage:
  sonny models default [flags]

Flags:
      --clear   remove the remembered default model
  -h, --help    help for default
      --show    print the current default model (if any)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Inspect a single configured (source, model) deployment: one model
header followed by one block per category it serves, each carrying the
category's tuning reference, effective parameters and config digest,
declared and observed fitness provenance, and — when the category
requests a reasoning value — the deployment's capability decision for it
(supported, or unsupported with the deployment's actual supported values
and declared aliases).

Usage:
  sonny models detail <source>/<model> [flags]

Flags:
      --format string   deprecated alias for --json (text|json); use --json (default "text")
  -h, --help            help for detail
      --json            emit the machine-readable envelope instead of the text view
      --models string   primary catalog file (default: models.yaml discovery)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

A disabled source keeps its definition and its stored credential but serves
no model: routing, the model pickers and failover skip it until it is
enabled again. The preference is recorded per profile in
disabled-sources.yaml beside models.yaml. A source a signed machine catalog
(organization provisioning) defines is managed and cannot be turned off.

Usage:
  sonny models disable <source id> [flags]

Flags:
  -h, --help   help for disable

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

A disabled source keeps its definition and its stored credential but serves
no model: routing, the model pickers and failover skip it until it is
enabled again. The preference is recorded per profile in
disabled-sources.yaml beside models.yaml. A source a signed machine catalog
(organization provisioning) defines is managed and cannot be turned off.

Usage:
  sonny models enable <source id> [flags]

Flags:
  -h, --help   help for enable

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

View or override observed per-category model fitness

Usage:
  sonny models fitness [command]

Available Commands:
  set         Record an explicit operator fitness override (0..1)
  show        List recorded fitness observations

Flags:
  -h, --help   help for fitness

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny models fitness [command] --help" for more information about a command.

Record an explicit operator fitness override (0..1)

Usage:
  sonny models fitness set <category> <source> <model> <score> [flags]

Flags:
  -h, --help            help for set
      --models string   primary catalog file (default: models.yaml discovery)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List recorded fitness observations

Usage:
  sonny models fitness show [flags]

Flags:
  -h, --help   help for show

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show each category's winning source/model under the routing policy

Usage:
  sonny models list [flags]

Flags:
      --format string   deprecated alias for --json (text|json); use --json (default "text")
  -h, --help            help for list
      --json            emit the machine-readable envelope instead of the table
      --models string   primary catalog file (default: models.yaml discovery)
      --no-check        skip probing source endpoints for model availability

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show cached model pricing; --refresh fetches from source pricing endpoints

Usage:
  sonny models prices [flags]

Flags:
  -h, --help            help for prices
      --models string   primary catalog file (default: models.yaml discovery)
      --refresh         fetch fresh pricing from each source's pricing_url

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

A decision policy (DPolicy) chooses the next semantic action of an agent
turn -- inspect, gather, test, revise, review -- or finishes or abstains.
Sonny owns every effect: the policy names an action, and Sonny runs it
through its own model routing, tool admission, approval and dispatch.
Configure it with the policy: section of .sonny.yaml; see docs/POLICIES.md.

Usage:
  sonny policy [command]

Available Commands:
  eval        Replay recorded or fixture observations through a policy without running anything
  explain     Explain a decision: its feature values, predicate results and artifact evidence
  promote     Validate a policy and make it the one new sessions run
  proposals   Report the proposal arm's cost and failure metrics
  propose     Check a model-written policy and hand it to the evolution inbox
  registry    Publish, qualify, review, promote and select registry policies
  resolve     Settle an effect parked for review with the outcome you established
  resume      Resume a stopped policy (or restore a revoked capability)
  rollback    Restore the previously promoted policy for new sessions
  show        Show the policy configuration, activation and the loaded policy
  status      Show every session's decisions, costs, skips and pending effects
  stop        Stop the policy (or revoke one capability) at the next decision boundary
  validate    Load a policy in the worker and check it against Sonny's actions and features

Flags:
  -h, --help   help for policy

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny policy [command] --help" for more information about a command.

eval decides each observation again with a policy (--policy, default the
configured one) and reports what it decides. With --session it replays the
session's recorded decisions and says whether each agrees; with
--observations it reads a hermetic fixture: one dpolicy-observation/0.1
frame per line. A frame under another feature schema is reported as
schema_mismatch, never decided. Nothing is dispatched.

With --recipe it replays instead the decision policy a session of that recipe
runs: the pack's decision_policy composed for --variant on --target-profile
(the catalog profile, with catalog defaults and no provider params) and
loaded as a new session loads it, exactly as show composes it. --recipe and
--policy are exclusive. With --session, every record --recipe replays must
name the closure --recipe composes (show --session prints it), so --recipe
never replays a session's records through a closure the session did not
run: another closure is refused (pack_closure_mismatch) once the pack's
modules are read and verified, before the worker loads the policy. A
qualified closure's model profile is its target's, so its records replay
only on the target they ran on: a record of a session that ran on another
target than the catalog-default one --recipe composes on, such as one whose
provider profile set params, is refused (pack_target_mismatch), naming
both targets. An unqualified closure replays on any target.

Usage:
  sonny policy eval [flags]

Flags:
      --format string                    policy file format: source or ast_json (default "source")
  -h, --help                             help for eval
      --json                             print JSON
      --observations string              replay a fixture of observation frames, one per line
      --policy string                    policy file (default: the configured source)
      --recipe string                    replay the decision_policy a session of this pack runs, instead of a policy file
      --recipe-dir string                with --pack: load packs from this directory instead of the configured tiers
      --session string                   replay this session's recorded decisions
      --target-profile string            with --pack: the catalog target profile the session runs on (id or id@revision), resolved with catalog defaults and no provider params
      --target-profile-revision string   with --pack: pin the target profile's revision
      --target-profiles string           with --pack: the target-profile catalog (default: the configured one)
      --variant string                   with --pack: the model variant the session installed (default: none, the base contract)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Explain a decision: its feature values, predicate results and artifact evidence

Usage:
  sonny policy explain [flags]

Flags:
  -h, --help             help for explain
      --json             print JSON
      --key string       decision key (default: the latest decision)
      --session string   session id (default: the only session with policy state)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

promote loads the policy, checks it against Sonny's actions and features,
and records it, pinned by its digest, as the activation new sessions use
wherever the configuration names the source it replaces (this workspace's
policy.source). A session that already runs a policy keeps it; one that
fell back at the workspace probe or the load tries the promoted policy at
its next turn. The configured mode is the ceiling of the promoted one.
rollback restores the previous activation.

Usage:
  sonny policy promote <file> [flags]

Flags:
      --format string   policy file format: source or ast_json (default "source")
  -h, --help            help for promote
      --mode string     shadow or active (default "shadow")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

proposals reads the proposal ledger of the policy state directory and
reports what an experiment report charges to the proposal arm: how many
proposals were written, how many the check rejected and with which codes,
and the tokens they cost in all and per checked proposal. A proposal whose
cost was not given is counted apart and left out of the cost figures,
never counted as free. A damaged ledger line is counted, not hidden.

Usage:
  sonny policy proposals [flags]

Flags:
  -h, --help   help for proposals
      --json   print JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

propose checks a policy a model wrote (the file, or standard input for -)
with the host's own load -- the worker compiles it and Sonny's host gate
checks its actions and features -- then writes it, checked or rejected,
to the proposal inbox (dpolicy-proposal-inbox/1, on the llm channel) of
the policy state directory and records it in the proposal ledger with
the tokens it cost (--cost-tokens; without it the cost is recorded as
unknown, never as free). "checked" means the worker compiled it and
Sonny's host gate admits it. A recipe contract's gate (its allow-list and
qualification) is not applied, so a session in recipe mode may still
refuse it. A rejected proposal prints one bounded diagnostic -- the
worker's code and stage (or its limit), or the features and actions
Sonny's gate refused, with at most 160 bytes of detail -- and exits
denied_policy, so an authoring loop can retry. A check that could not
run writes and records nothing: it exits unavailable when the worker
could not judge the policy, and config when Sonny's own catalog or
extractors fail. A proposal is never a review and never activates a
policy: an evolution job evaluates the inbox, and only an operator
promotes. An inbox holding 10000 proposals takes no more until a job
drains it.

Usage:
  sonny policy propose <file|-> [flags]

Flags:
      --author-model string   the model that wrote the policy (required)
      --cost-tokens int       the tokens the proposal cost to produce, charged to the proposal arm (unset: the cost is recorded as unknown)
  -h, --help                  help for propose
      --json                  print JSON
      --template string       the authoring prompt, as pack-id@version (for example policy-author@1)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

registry works with the policy registry that policy.registry names (its
bearer credential is SONNY_UPSTREAM_TOKEN). Every read verifies the
registry's signatures against policy.registry.trusted_keys, and every
module against its digest, before anything is shown or loaded. A version
is immutable: qualify, review, promote and revoke add records, and
nothing is rewritten. See docs/POLICIES.md#registry-mode.

Usage:
  sonny policy registry [command]

Available Commands:
  diff        Compare two versions' verified statements
  list        List the registry's policy names, or one name's versions
  promote     Move a channel's entry for the name to this version
  publish     Check a canonical AST and its imports on this host, then publish them as a new version
  qualify     Load a version on this host for a model target and record its held-out competence
  review      Replay a reviewer's predicted cases on the version and record the review
  revoke      Revoke a version's policy everywhere, and stop it on this node
  rollback    Restore a channel's previous version of the name
  select      Show what a new session on this host would select from the channel, and why
  show        Show a version: its verified statement, status, competence, reviews and revocations

Flags:
  -h, --help   help for registry

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny policy registry [command] --help" for more information about a command.

Compare two versions' verified statements

Usage:
  sonny policy registry diff <name>@<version> <name>@<version> [flags]

Flags:
  -h, --help   help for diff
      --json   print JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List the registry's policy names, or one name's versions

Usage:
  sonny policy registry list [<name>] [flags]

Flags:
  -h, --help   help for list
      --json   print JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

promote moves the channel's entry for the version's name to the version,
at --mode, by compare-and-set on the channel's generation: a move by
someone else meanwhile is refused (conflict), never overwritten. The
registry refuses a promotion by the version's author or recalibrator, an
active entry for a version that is not trusted (reviewed and qualified),
and a revoked or deprecated version. New sessions select from the moved
channel; a session that runs a policy keeps it.

Usage:
  sonny policy registry promote <name>@<version> [flags]

Flags:
      --channel string   the channel (default: the configured one)
  -h, --help             help for promote
      --mode string      shadow or active (default "shadow")
      --reason string    why (recorded in the channel's audit)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

publish loads the root canonical AST and the modules it imports on the
configured worker, as a session would load them, refuses any that is not
in its canonical form, and publishes them as the next version of --name.
The registry records who published it from the caller's credential: a
human publisher may record human authorship (or a lower trust), a service
only a generated one. A new version is neither reviewed nor qualified.

Usage:
  sonny policy registry publish <root.ast.json> [<import.ast.json>...] [flags]

Flags:
      --author-model string   the model that wrote the version, for --source llm
      --category strings      a descriptor category (repeatable)
  -h, --help                  help for publish
      --name string           the policy name
      --recipe string         the pack closure digest the version belongs to (default: none)
      --source string         authorship: human, or the generator (llm, gan, solver, cart, grammar, mle) (default "human")
      --task-scope strings    a task the version is meant for (repeatable)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

qualify loads the version's closure, each module fetched by digest and
verified, on this host for --target, the model target's compatibility
digest (in registry mode, sonny policy show --target-profile <profile>
prints a catalog profile's, with catalog defaults and no provider
params), and records a competence record that names the manifest that
load produced: the tool catalog, extractors, interpreter and model
profile it ran under. Selection admits the version only on a host whose
load produces that manifest, so a changed tool schema makes it
ineligible until it is qualified again. Only held-out results count:
--partition is qualification or outer_validation.

Usage:
  sonny policy registry qualify <name>@<version> [flags]

Flags:
      --evaluator string       who evaluated it
      --evidence string        where the evaluation is recorded
  -h, --help                   help for qualify
      --not-after string       when the record expires (RFC 3339; default never)
      --partition string       qualification or outer_validation (default "qualification")
      --served-model strings   a model that may serve the target (repeatable)
      --successes int          successful held-out trials
      --target string          the model target's compatibility digest (sha256:jcs1:...; policy show --target-profile prints one)
      --task-scope strings     a task evaluated (repeatable; default the version's task scope)
      --trials int             held-out trials

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

review loads the version on this host (unqualified) and decides each case
of --cases, a file of one JSON object per line: {"name": ..., "predicted":
..., "observation": <a dpolicy-observation/0.1 frame>}, where predicted is
the outcome as policy eval prints it. Each case records the prediction,
what the version decided and the observation's digest. An approval needs
every prediction to match: one that does not is refused (denied_evidence)
and nothing is recorded; record it as rejected instead. --scope names the
tasks the review covers: selection runs the version only for a task its
latest review covers. The registry records the reviewer from the caller's
credential, and refuses a review by the version's author or recalibrator,
or by anyone but a human reviewer.

Usage:
  sonny policy registry review <name>@<version> [flags]

Flags:
      --cases string         the reviewer's cases, one JSON object per line
  -h, --help                 help for review
      --json                 print JSON
      --limitation strings   a known limitation (repeatable)
      --scope strings        a task the review covers (repeatable; at least one)
      --verdict string       approved or rejected

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

revoke revokes the version's AST in the registry: no channel selects it
again, under any name or version that shares it. On this node it then
stops, at their next decision, the sessions that run it (a digest stop in
every state directory, as each registry read applies), and says so once
the configured channel's snapshot, read back fresh, lists the revocation.
Other nodes stop theirs at their next registry read. When the revocation
lands but this node cannot read it back, cannot write the stop, or reads a
snapshot that does not confirm it, revoke exits partial and names the
manual stop (sonny policy stop --digest).

Usage:
  sonny policy registry revoke <name>@<version> [flags]

Flags:
  -h, --help            help for revoke
      --reason string   why (recorded, and the reason stopped sessions report)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

rollback restores the channel's previous entry for the name (its version
and mode), by compare-and-set on the channel's generation. Rolling back
the name's first promotion is refused (conflict). The registry checks the
version restored as it checks a promotion: restoring a version revoked or
deprecated since, or an active entry no longer trusted, is refused
(unauthorized).

Usage:
  sonny policy registry rollback <name> [flags]

Flags:
      --channel string   the channel (default: the configured one)
  -h, --help             help for rollback
      --reason string    why (recorded in the channel's audit)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

select reads the configured channel's signed snapshot, applies its
revocations on this node, and selects as a new session on this host would
for --task (default policy.registry.task) and --target (a model target's
compatibility digest; default none, which no qualified version matches):
every candidate with why it is eligible or excluded, every channel entry
the registry itself excluded (revoked, importing a revoked AST,
deprecated), the outcome, and the policy loaded as the session would load
it, or the reason it would run none.

Usage:
  sonny policy registry select [flags]

Flags:
  -h, --help            help for select
      --json            print JSON
      --target string   the model target's compatibility digest (default: none)
      --task string     the task (default: policy.registry.task)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show a version: its verified statement, status, competence, reviews and revocations

Usage:
  sonny policy registry show <name>@<version> [flags]

Flags:
  -h, --help   help for show
      --json   print JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Settle an effect parked for review with the outcome you established

Usage:
  sonny policy resolve [flags]

Flags:
      --class string     succeeded or failed (default "failed")
  -h, --help             help for resolve
      --key string       the entry's idempotency key (status lists them)
      --session string   session id

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

resume clears what stop set: the session's own stop (--session), the stop
for every session (without flags; a session's own stop stays), a stop on a
policy AST digest (--digest), or a capability's revocation (--capability),
in each state directory this configuration's sessions use. A session's own
stop is cleared wherever it is set, including one set before the
session's first policy turn.

Usage:
  sonny policy resume [flags]

Flags:
      --capability string   restore this capability instead of resuming
      --digest string       clear a stop on this policy AST digest
  -h, --help                help for resume
      --session string      one session (default: every session)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

rollback restores, for new sessions, the activation that the last promote
for this workspace's policy.source replaced; each configured source keeps
its own history. Rolling back the first promotion is refused (conflict):
there is no earlier activation. To return to the configured source itself,
promote the configured file.

Usage:
  sonny policy rollback [flags]

Flags:
  -h, --help   help for rollback

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

show prints the policy: block that applies here -- the operator's (--config,
else ~/.sonny.yaml) or a trusted project's own .sonny.yaml, with the
operator's beside it -- the activation promoted for its configured source,
the revoked capabilities and, unless the mode is off, the policy a new
session in this directory would run (loaded with the activation's pin) and
the mode it runs it in, or the typed reason it would run none. When it
would run none but the policy itself loads, the policy is shown as the
configured one, validated, not as one that runs.

When policy.pack is session, each session runs its pack's decision_policy:
name the recipe with --recipe (and the variant and target profile a session
runs, --variant and --target-profile), and show composes and loads that
pack's policy as a new session would, explaining the contract, the variant
applied or why none was, every slot's module and supplier, and the
qualification it needs. --target-profile resolves the catalog profile with
catalog defaults and no provider params, and show labels the target so: a
session whose provider profile sets params runs on another target.

When policy.registry is set, each new session selects its policy from the
registry for its task and model target (sonny policy registry select
shows one selection), and show reports the workspace probe's reason, if
any. --target-profile prints that catalog profile's model target: the
compatibility digest sonny policy registry qualify --target names, with
catalog defaults and no provider params, as in recipe mode. Only a session
that resolves a qualifiable model target can run a registry version.

With --session, show prints instead what that session ran, from its latest
decision record: the policy and manifest digests, the recipe closure, model
profile and target (compatibility digest), and the unsigned overrides.

Usage:
  sonny policy show [flags]

Flags:
  -h, --help                             help for show
      --json                             print JSON
      --recipe string                    pack mode: the pack a session runs, whose decision_policy show composes
      --recipe-dir string                with --pack: load packs from this directory instead of the configured tiers
      --session string                   print what this session ran, from its latest decision record
      --target-profile string            with --pack, or in registry mode: the catalog target profile the session runs on (id or id@revision), resolved with catalog defaults and no provider params
      --target-profile-revision string   with --target-profile: pin the target profile's revision
      --target-profiles string           with --target-profile: the target-profile catalog (default: the configured one)
      --variant string                   with --pack: the model variant the session installed (default: none, the base contract)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

status prints the durable policy state of every session in each state
directory this configuration's sessions use (or of --session): episodes,
entry states, dispatched, intended and skipped decisions, skipped turns,
verifications, rejections, recoveries, every cost spent and reserved, and
the entries parked for review. A session whose state cannot be read in
full is reported with its error beside the others, and status then exits
with a configuration error.

Usage:
  sonny policy status [flags]

Flags:
  -h, --help             help for status
      --json             print JSON
      --session string   one session (default: every session)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

stop returns the session (or, without --session, every session) to Sonny's
ordinary runtime at the next decision boundary; a running action finishes
first. With --capability it instead revokes one capability from the grant:
the next decision that needs it is refused (missing_capability). With
--digest it stops every session, of every workspace sharing the state
directory, that runs the policy with that AST digest. The controls reach
each state directory this configuration's sessions use: the block's own
and, beside a trusted project's block, the operator's. A session's own
stop goes where the session's policy state is or, before its first policy
turn, to every one of them.

Usage:
  sonny policy stop [flags]

Flags:
      --capability string   revoke this capability instead of stopping
      --digest string       stop every session running the policy with this AST digest
  -h, --help                help for stop
      --reason string       why (shown by status) (default "stopped by the operator")
      --session string      one session (default: every session)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Load a policy in the worker and check it against Sonny's actions and features

Usage:
  sonny policy validate <file> [flags]

Flags:
      --format string   policy file format: source or ast_json (default "source")
  -h, --help            help for validate
      --json            print JSON

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run the authoritative CI pre-commit/commit-range gates (ENG-4429)

Usage:
  sonny precommitci [command]

Available Commands:
  run         Select files/range per the pinned CI policy and run every mandatory gate

Flags:
  -h, --help   help for precommitci

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny precommitci [command] --help" for more information about a command.

run implements the ENG-4429 pinned policy exactly: changed files (diffed
against the merge-base of --base/--head) for a merge-request pipeline,
every tracked file for a protected-branch push or a scheduled pipeline
-- detected from GitLab's own CI_MERGE_REQUEST_IID / CI_PIPELINE_SOURCE /
CI_COMMIT_REF_PROTECTED variables, so local and CI runs of this exact
command agree.

Every ENG-4426 mandatory gate always runs (or the whole command fails --
a gate with a missing required binary, or with no wired executor,
is never silently skipped). --artifact-dir receives a JUnit XML report,
a provenance.json (the resolved config/tool digest, commit range, and
file count), and -- for the secret-scan gate -- gitleaks' own native
SARIF report.

Exit status is non-zero when any gate fails, when a required binary is
missing, or when --base/--head do not resolve (e.g. a shallow clone that
never fetched far enough back to find a merge base).

Usage:
  sonny precommitci run [flags]

Flags:
      --artifact-dir string   directory to write junit.xml, provenance.json, and any gate-native reports (e.g. secret-scan.sarif.json) (default "artifacts/precommitci")
      --base string           range start: the merge-request target ref (changed-files mode) or the explicit push range start, e.g. $CI_COMMIT_BEFORE_SHA (all-files mode)
      --head string           range end (the commit this pipeline is validating) (default "HEAD")
  -h, --help                  help for run
      --json                  also print the provenance record as JSON to stdout

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Display the fully rendered system prompt for a recipe.

This command loads a recipe and displays the compiled system prompt that would
be sent to the LLM, including all composed fragments, responsibilities,
guidelines, and constraints.

Examples:
  # Show prompt for default/embedded pack
  sonny prompt

  # Show prompt for a specific pack file
  sonny prompt --pack-file ./my-pack.yaml

  # Emit the full compiler Output as JSON
  sonny prompt --pack-file ./my-pack.yaml --format json

Usage:
  sonny prompt [flags]

Flags:
      --format string        output format: text|json (default "text")
  -h, --help                 help for prompt
      --recipe-dir string    directory containing pack YAML files
      --recipe-file string   single pack YAML file to load

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Declared names/aliases: recipe, pack.

Sonny tracks recipe repositories listed in pack-sources.yaml under $XDG_CONFIG_HOME/sonny. Use these subcommands to add, list, update, or remove tracked repos. Cloned repos live under $XDG_CACHE_HOME/sonny/pack-repos and are loaded by the standard recipe discovery pipeline on startup.

Usage:
  sonny recipe [command]

Aliases:
  recipe, pack

Available Commands:
  add             Register and clone a new recipe source
  approve-routing Trust a recipe source's model routing (endpoints and credential env var names)
  artifact        Inspect captured tool results without putting them in model context
  default         Show, set, or clear the persisted default prompt recipe
  eval            Run a recipe's eval suite through the configured provider
  evidence        Score two per-case ledgers into one paired evidence record and decide promotion
  inspect         Show resolved scope, sub-scopes, validation, and provenance for a recipe
  list            List tracked recipe sources (or --recipes to list prompt recipes)
  migrate         Rewrite a v1 prompt recipe as v2 (in-place by default)
  optimize        Evolve a recipe's system prompt against its eval suite
  pin             Pin a model-pack variant for a session, or as a pack-wide standing default
  qualify         Assemble and freeze a model-variant campaign's qualification document
  reload          Force-refetch one or all tracked recipe sources
  remove          Drop a recipe source and delete its cache directory
  replay          Reproduce a pinned variant decision from a lock and a snapshot
  resolve         Emit the fully-resolved, tool-aware compiled subject for a recipe
  search          BM25-rank loaded prompt recipes against a query
  snapshot        Write a replayable variant-resolution snapshot for one logical recipe
  update          Fetch + reset tracked sources to their upstream branch tip
  validate        Statically validate a recipe YAML file
  variant         Operate on one model recipe variant envelope file
  variants        List the model-pack variants discovery found for one logical recipe

Flags:
  -h, --help   help for recipe

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny recipe [command] --help" for more information about a command.

Register and clone a new recipe source from git-url. A local directory (., ./dir, ~/dir or an absolute path) works too: a git repository is cloned on its checked-out branch, and any other directory is snapshotted into the cache and re-read on every sync or reload (the directory itself is never modified). Append @<ref> to the URL (e.g. https://example.com/[email protected]) to pin the source to a specific semver tag or to @latest for the newest available tag. Pinned sources are frozen: sonny will not auto-update them on startup; use `sonny recipe reload <name>` to refresh.

Usage:
  sonny recipe add <git-url|dir>[@<ref>] [flags]

Flags:
      --approve-mcp                  after cloning, record your approval of the MCP servers every pack from this source declares (inherited ones included), as sonny mcp approve pack does for each: a pack-source server launches only on such an approval
      --approve-routing              after cloning, trust the source's model routing (endpoints and credential env var names its catalogs declare) by copying it into <config-dir>/models.d/pack-<name>-routing.yaml; see sonny pack approve-routing
      --branch string                branch to track (default "main")
      --default-recipe string        override this source's repository default primary pack; an explicitly empty value disables its default
  -h, --help                         help for add
      --mcp-auto-approve             connect this source's MCP servers without a prompt for the packs that name them, once sonny mcp approve registry <name> records your approval of their unchanged definitions; false writes mcp_auto_approve: false, so they get the stricter explicit-approval pinning (unset: on only for a source with --mcp-d) (default true)
      --mcp-d stringArray            mcp.yaml-style directory relative to the clone root whose *.yaml servers load for the packs whose mcp.allowed names them, overriding same-name mcp.yaml servers (repeat for multiple dirs)
      --mcp-env-allow strings        host environment variable NAME this source's MCP servers may read, e.g. the credentials its packs' servers reference (repeat, or comma-separate; persists mcp_env_allow in pack-sources.yaml)
      --model-catalog stringArray    model-catalog YAML path relative to the clone root (repeat for multiple files); replaces the default model-registry/models.yaml
      --models-d stringArray         models.d-style directory relative to the clone root whose *.yaml drop-ins override same-id local sources (repeat for multiple dirs)
      --name string                  override the directory name (defaults to repo basename)
      --no-model-catalog             do not load the source's default model-registry/models.yaml (persists models_auto: false)
      --pin string                   lock this source to a specific version: a semver tag (e.g. v1.2.3) or "latest" to resolve and record the current highest tag; may also be set inline as <url>@<ref>. Pinned sources are not auto-updated on startup; use "sonny pack reload <name>" to refresh.
      --skip-unresolved              with --approve-mcp: silently skip servers whose binary is not installed on this host
      --subdir string                subdir of the repo containing pack YAML files
      --update-policy string         update policy (on_startup|manual) (default "on_startup")
      --write-config                 with --approve-mcp: also merge approved server definitions into <config-dir>/mcp.yaml so they are available globally
      --write-untrusted-references   with --write-config: also write $VAR references, refused env keys and egress policy beyond the server's own url host from servers of packs that are not verified-signed into mcp.yaml, where references expand against your environment

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Recipe catalogs cannot choose provider endpoints or credential env vars, so their sources use each scheme's default endpoint and credential. approve-routing lists the base_url, api_key_env, env_prefix and secret_ref every catalog of <source> declares (names only, never values) and copies them into <config-dir>/models.d/pack-<source>-routing.yaml, which is your own configuration: recipe updates cannot change it. Re-run after a recipe update changes its routing; --revoke deletes the file.

Usage:
  sonny recipe approve-routing <source> [flags]

Flags:
  -h, --help     help for approve-routing
      --revoke   delete the approved routing file for <source>

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Read tool results this host captured OUTSIDE the model's context.

A captured artifact is the complete tool result; what the model saw was a
bounded view of it. These subcommands let a person read the complete,
authorized artifact on their own screen. Doing so puts nothing into any
model's context, and each read is recorded in its own append-only audit
log, separately from the rehydration records the artifact store keeps for
reads that DO reach a model.

Usage:
  sonny recipe artifact [command]

Available Commands:
  inspect     Read a captured artifact for a person and record the inspection

Flags:
  -h, --help   help for artifact

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny recipe artifact [command] --help" for more information about a command.

Read one captured artifact and append one inspection record.

The read is authorized from scratch on this call -- the subject is proved
and the field allow-list applied at release time -- and it puts NOTHING
into any model's context. Exactly one record is appended to the audit log
(--audit-log, by default artifact-inspections.jsonl in this host's state
directory): who read, which handle and version, under which selector
kind, when, how many bytes came back and whether the selection was
complete. The record never carries the content itself, and its
entered_model_context member can only be false.

Choose what to read with --fields (named top-level members) or with
--start/--end (a half-open record range). With neither, the whole
captured record range is read when the artifact admits a range selector.

An inspection that cannot be audited is refused: if the record cannot be
appended, nothing is printed.

Usage:
  sonny recipe artifact inspect <handle> [flags]

Flags:
      --artifact-version string   the exact artifact version to read (required: a handle names a lineage, a version names bytes)
      --audit-log string          append the inspection record to this file instead of the host's default inspection log
      --end int                   stop before this record, 0-based and exclusive (use with --start)
      --fields strings            read these top-level members of the artifact
  -h, --help                      help for inspect
      --json                      emit the selection and its audit record inside the machine envelope
      --start int                 first record to read, 0-based and inclusive (use with --end)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage the prompt recipe that sonny auto-selects on launch.

Examples:
  sonny recipe default crush       # set default to "crush"
  sonny recipe default --show      # print current default (if any)
  sonny recipe default --clear     # remove the persisted default

The default is persisted in the session DB and honored by 'sonny run'.
It overrides defaults declared in a downloaded repository's pack-repository.yaml.
Clearing it restores repository defaults; it does not change downloaded files.
Use 'sonny run --pick-pack' to force the picker for one run without
clearing the default.

Usage:
  sonny recipe default [recipe-id] [flags]

Flags:
      --clear   remove the persisted default
  -h, --help    help for default
      --show    print the current default pack (if any)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

eval runs every case in the recipe's pack_eval_suite (or in --suite-file) through the provider used by chat. Production runners MUST intersect case tools_allowed with the recipe's existing allowed list and honor path constraints; --exit-on-fail makes the first non-pass case the overall exit code so CI gates surface real regressions.

Usage:
  sonny recipe eval <recipe-id> [flags]

Flags:
      --allow-draft-variants             allow a draft (not approved) variant to activate; for a qualification campaign's draft-time measurement only
      --allow-unapproved-profiles        allow a not-yet-approved target profile to activate; for a qualification campaign's draft-time measurement only
      --concurrency int                  run cases through the shared bounded scheduler with up to this many concurrent trials (<=1 is serial) (default 1)
      --confirm int                      run this many independent passes and only report a fail confirmed in every pass (default 1)
      --critic-wire-schema               for a pack that declares an analysis critic, send the composed analysiscritic wire schema (response_format json_schema, narrow scope) the analysis host would send live; --critic-wire-schema=false restores the prompt-only contract (default true)
      --dir string                       additional pack directory
      --exit-on-fail                     stop at first failure and exit nonzero
      --expect-refusal-case strings      case IDs that must refuse (comma-separated)
      --file string                      load a single pack YAML by file path
      --format string                    text|jsonl (default "text")
  -h, --help                             help for eval
      --history-file string              append-only eval history ledger (line-compatible with SkillOpt eval-runs.jsonl)
      --judge-model string               grade every judge block with this model on the run's provider instead of the target model (a case's own judge.model still wins); an ordered comma list primary,fallback,... re-asks a judge turn that fails on one model (provider error such as a content-filter 400, timeout, judge refusal, or a reply still unreadable after its resample) on the next, recording judge_model and judge_fallbacks per row; does not imply --trust-model-judge
      --max-output-tokens int            maximum tokens in each evaluated case response (0 disables) (default 4096)
      --outage-backoff duration          base backoff before an outage-retry pass, doubling per retry (default 2s)
      --outage-retries int               retry a whole pass this many times when every case errors as an infrastructure failure (default 2)
      --reasoning-effort string          run every case at this reasoning effort through a provider runner that applies reasoning (empty = the routed default); a value the provider rejects fails the case with the provider's error
      --repeat int                       run each case this many times per pass and collapse the results (flakiness discipline) (default 1)
      --suite-file string                load cases from external YAML
      --system-prompt-override string    replace the composed system prompt with this file's bytes on every case (the no_skill control); not combinable with --variant/--target-profile
      --target-profile string            evaluate against this catalog target-profile id
      --target-profile-revision string   pin the catalog profile revision
      --target-profiles string           target-profile catalog path (default: <dir>/../model-registry/target-profiles.yaml)
      --trust-model-judge                use model judge verdicts for local eval/optimization grading (the judge is the --judge-model model when given, else the target model); records remain advisory for runtime and release gates
      --variant string                   pin this model variant for every case, or empty for automatic routing

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

evidence pairs a baseline and a candidate eval ledger BY CASE ID, rescores both with the SkillOpt metric, computes every metric's paired delta and BCa interval under the frozen campaign matrix, and writes a sonny.variant-evidence/v1 record. promote, reject and blocked are all honest outcomes of a campaign that ran and all exit ZERO with the record on stdout; only an invalid input exits non-zero. Omitting --live makes the record live=false, which can never promote.

Usage:
  sonny recipe evidence [flags]

Flags:
      --baseline-ledger string              baseline per-case JSONL ledger
      --baseline-tier string                generic or family
      --baseline-variant string             the baseline's model_variant_id (empty for the generic tier)
      --bench string                        livemath, searchqa or docvqa
      --campaign string                     campaign id; must equal the matrix's campaign_id
      --candidate-ledger string             candidate per-case JSONL ledger
      --candidate-tier string               family or exact
      --candidate-variant string            the candidate's model_variant_id
      --data string                         materialized data dir (default "packs/skillopt/data")
      --family-release stringArray          a release the family selector declares (repeatable); required for a family-tier candidate
      --family-weight-variant stringArray   a weight variant the family selector declares (repeatable; empty means the axis is open)
      --format string                       text|json (default "text")
  -h, --help                                help for evidence
      --leave-one-target-out                this comparison held the target out of the optimization and measures transfer onto it
      --live                                assert every scored case came from a real provider call
      --matrix string                       frozen matrix manifest (qualification/matrix/<c>.matrix.json)
      --out string                          output record path (qualification/<c>/evidence/<name>.json)
      --preregistration string              frozen Phase 0 document; the matrix must pin its digest and its gate params
      --security-baseline-ledger string     independently scored output-security baseline JSONL (required by frozen matrix)
      --security-candidate-ledger string    independently scored output-security candidate JSONL (required by frozen matrix)
      --security-manifest string            evaluator-only corpus manifest pinned by the frozen output-security requirement
      --split string                        the sealed split the partition names (test)
      --target string                       profile_id@revision, which must be live in the matrix
      --target-release string               the model release this target serves; required for a family-tier candidate
      --target-weight-variant string        the target's weight variant, when its profile declares one

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show resolved scope, sub-scopes, validation, and provenance for a recipe

Usage:
  sonny recipe inspect <recipe-id> [flags]

Flags:
      --allow-draft-variants   allow a draft (not approved) variant's provenance to be inspected
      --diff string            show scope diff between baseline and sub-pack; with --variant, diff the variant's components against base|<variant-id> instead
      --dir string             additional pack directory
      --file string            load a single pack YAML by file path
      --format string          output format: text|json (default "text")
  -h, --help                   help for inspect
      --show-components        print the per-component provenance table
      --show-prompt            include rendered prompt (secrets masked)
      --show-rules             include resolved tools/agents rules (post-inheritance)
      --variant string         inspect the compiled model variant instead of the base pack

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Without --recipes lists git-backed pack-sources from pack-sources.yaml. With --recipes walks the standard discovery dirs and lists every loaded prompt recipe with id + description + (when --detail=full) author/license/tags/provenance. --json emits the machine-readable envelope for either listing; --tags filters the recipe listing.

Usage:
  sonny recipe list [flags]

Flags:
      --detail string   short|full (only with --packs) (default "short")
      --format string   deprecated alias for --json (text|json); use --json (default "text")
  -h, --help            help for list
      --json            emit the machine-readable envelope instead of the listing
      --recipes         list loaded prompt packs instead of sources
      --tags strings    filter to packs carrying ALL listed tags (only with --packs)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Promotes raw `secrets:` and `auto_models:` blocks into typed PackMeta fields. Idempotent on already-v2 input. Refuses any pack containing legacy shell-form `command.run:` secrets.

Usage:
  sonny recipe migrate <pack.yaml> [flags]

Flags:
      --check    report whether the file would be rewritten; exit non-zero if so
  -h, --help     help for migrate
      --stdout   write migrated YAML to stdout instead of in place

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

optimize runs a bounded SkillOpt-style loop: evaluate the recipe, ask an optimizer model for a patch proposal against the mutable system-prompt components, re-evaluate the candidate, and keep it only when a noise-aware gate says it genuinely beat the current pack. Rejected edits persist in <out>/history.jsonl and feed back into later rounds. The source file is rewritten only with --apply.

Use --suite-file to gate against an external eval suite instead of the pack's inline pack_eval_suite -- e.g. a held-out suite you never optimize against, to avoid overfitting the prompt to the cases that grade it.

A round's gate verdict is one of three outcomes, not two: accepted, genuinely rejected (the candidate was measured and scored no better), or invalid (no candidate gate verdict exists because a proposal could not be parsed/validated/applied, or its eval hit an infrastructure error). Invalid rounds are counted separately (the report's "invalid" field) and, unlike rejections, do NOT seed the rejected-edits buffer: an edit that was never tried must never be taught to future rounds as "did not work".

Usage:
  sonny recipe optimize <recipe-id> [flags]
  sonny recipe optimize [command]

Available Commands:
  matrix      Run the bounded target x tier x benchmark qualification matrix

Flags:
      --allow-draft-variants pack variant approve   allow --export-variant to write a draft (not approved) variant instead of refusing it; for a qualification campaign's draft-time export/measurement only. The exported variant is still recorded trust.status: draft and still requires a separate pack variant approve; this never relaxes a runtime or release activation gate
      --apply                                       rewrite the source pack file with the best result
      --assertion-overlap-ignore-pattern string     regexp matched against each lowercased assertion literal; a match is excluded from both sides of the --max-assertion-overlap ratio (for answer-choice-shaped literals, e.g. a multiple-choice benchmark's label regexes). Preregister it per benchmark; it never relaxes the holdout case-id check
      --concurrency int                             run each eval pass's cases through the shared bounded scheduler with up to this many concurrent trials (<=1 is serial) (default 1)
      --confirm int                                 independent eval passes a failure must be confirmed in (default 1)
      --control-file string                         JSON control file polled between phases (default: <out>/control.json; pause/stop/rounds/proposal_retries/optimizer_timeout)
      --dir string                                  directory holding <pack-id>.yaml
      --dry-run                                     print the plan and call estimate; make no model calls
      --expect-refusal-case strings                 case IDs that must refuse (comma-separated; applies to training and holdout)
      --export-campaign string                      campaign id the exported variant's provenance manifest records (required with --export-variant)
      --export-family-evidence-ref string           qualification record a family-tier export's family_scope points at (required with --export-selector-tier family)
      --export-family-release strings               release a family-tier export declares evidence for (repeatable; default: the resolved target profile's own model release)
      --export-harness-revision string              revision of the harness performing the export, recorded in the provenance manifest (default: sonny@<build commit>; required with --export-variant when the binary carries no commit)
      --export-selector-tier string                 selector tier the exported variant declares: exact (the default) or family (family also requires --export-family-evidence-ref and refuses --parent-variant)
      --export-variant string                       export the best candidate as <pack>.<variant-id>.yaml plus its owned fragments instead of rewriting the source pack (mutually exclusive with --apply)
      --file string                                 pack YAML file to optimize (must be writable)
      --format string                               text|json (default "text")
  -h, --help                                        help for optimize
      --holdout-require string                      what --apply needs from the holdout verdict: no-regression (improved|no-gain|within-noise) or improved (default "no-regression")
      --holdout-suite-file string                   disjoint eval-suite YAML evaluated only for the final baseline-vs-best verdict (skipped when no round was accepted); gates --apply per --holdout-require
      --judge-model string                          grade every judge block with this model on the run's provider instead of the target model (a case's own judge.model still wins); an ordered comma list primary,fallback,... re-asks a judge turn that fails on one model (provider error such as a content-filter 400, timeout, judge refusal, or a reply still unreadable after its resample) on the next, recording judge_model and judge_fallbacks per row; does not imply --trust-model-judge
      --margin-cases int                            holdout gain floor, in case units (default 2)
      --max-assertion-overlap float                 maximum fraction of distinct holdout assertion literals reused from training (0 disables the independence preflight) (default 0.34)
      --max-calls int                               refuse a run whose worst-case model-call count exceeds this ceiling (0 disables) (default 5000)
      --max-changed-chars int                       edit-size cap a --export-variant proposal is validated against: len(target)+len(content) summed over its operations (0 uses the exporter's default of 4000). Required with --export-campaign; declare it in the preregistration's edit_policy
      --max-infra-frac float                        maximum fraction of infrastructure errors before a verdict is called invalid (default 0.2)
      --max-output-tokens int                       maximum tokens in each evaluated case response (0 disables) (default 4096)
      --min-delta float                             minimum hard-score gain a candidate must clear (default 0.01)
      --min-holdout-cases int                       minimum measured holdout cases below which the verdict is split-too-small (default 25)
      --optimizer-model string                      model for the optimizer role (default: the target model)
      --optimizer-provider string                   provider for the optimizer role (default: the target provider)
      --optimizer-timeout duration                  deadline for each optimizer proposal call (0 disables) (default 4m0s)
      --out string                                  artifact directory (default .sonny/optimize/<pack-id>)
      --parent-variant string                       family variant id the exported exact variant extends
      --progress-file string                        append optimization phase events as JSONL (default: <out>/progress.jsonl)
      --progress-stderr                             also render compact progress events on stderr (progress JSONL is always written to --progress-file)
      --proposal-retries int                        bounded retries for malformed optimizer replies (default 2)
      --repeat int                                  eval repeats per pass (flakiness discipline) (default 1)
      --rounds int                                  optimization rounds to run (default 3)
      --stop-on-invalid                             stop after the first unmeasured candidate round and skip holdout/apply
      --suite-file string                           eval suite YAML to optimize against (overrides the pack's inline pack_eval_suite)
      --target-profile string                       catalog target-profile id the variant is trained for (required with --export-variant)
      --target-profile-revision string              pin the catalog profile revision
      --target-profiles string                      target-profile catalog path (default: <dir>/../model-registry/target-profiles.yaml)
      --trust-model-judge                           use model judge verdicts for local eval/optimization grading (the judge is the --judge-model model when given, else the target model); records remain advisory for runtime and release gates
      --variant-root string                         authorized variant output root (default: the directory holding the pack file)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny recipe optimize [command] --help" for more information about a command.

matrix reads the frozen sonny.variant-matrix/v1 campaign plan and the preregistration it pins, verifies the two agree, and runs every runnable (target x tier x benchmark x seed) cell through the shared bounded scheduler. Each cell gets its own candidate identity, its own output directory, its own checkpoint entry and its own result digest; nothing is averaged across targets. A blocked target and a pending tier are recorded as explicit non-results and make no provider call, and the predeclared no_skill control arm is recorded rather than folded into the generic tier. Budgets are hard stops, and --dry-run prints the whole cell plan without dispatching anything.

NOTE: because this is a subcommand of `recipe optimize`, the recipe id "matrix" is reserved here.

Usage:
  sonny recipe optimize matrix [flags]

Flags:
      --capability-digest string      host capability digest stamped onto every loaded target profile
      --concurrency int               maximum concurrent cells dispatched through the shared bounded scheduler (default 1)
      --dry-run                       print the expanded cell plan with each cell's identity and budget share; make no model calls
      --format string                 text|json (default "text")
  -h, --help                          help for matrix
      --live                          declare that every cell reaches a real provider; without it the run manifest records live:false and can never support a promotion
      --matrix-file string            frozen sonny.variant-matrix/v1 campaign plan to execute (required)
      --out string                    artifact directory holding the checkpoint, the run manifest and one directory per cell (default packs/skillopt/results/campaign/<campaign>)
      --preregistration-file string   frozen preregistration the plan pins (default: <matrix-dir>/../preregistration/<campaign>.json)
      --profile-catalog string        target-profile catalog path (default: standard discovery relative to --pack-dir)
      --recipe-dir string             pack directory the target-profile catalog is discovered relative to

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Persists an explicit model-pack variant pin: for one session with
--session <id>, or as a pack-wide standing default when --session is
omitted.

Before writing, the pin is checked the same way an activation would check
it -- against --target-profile, through the same offline resolver
'pack resolve --explain' uses -- and a pin that would not resolve for that
target is refused with its modelvariant error code and never written.

--clear removes the pin instead of writing one; naming a variant id is
optional with --clear.

Usage:
  sonny recipe pin <recipe-id> [variant-id] [flags]

Flags:
      --allow-draft-variants             allow a draft (not approved) variant to be pinned; for a qualification campaign's draft-time measurement only
      --allow-unapproved-profiles        allow a not-yet-approved target profile in the compatibility check; for a qualification campaign's draft-time measurement only
      --capability-digest string         the host's capability-surface digest (default: the offline no-host-surface digest)
      --clear                            remove the pin instead of writing one
      --digest string                    additionally require this exact envelope digest
      --dir string                       pack directory to load, REPLACING standard discovery (not additive)
      --file string                      load a single pack YAML by file path
      --format string                    output format: text|json (default "text")
  -h, --help                             help for pin
      --session string                   pin for one session id instead of a standing default
      --target-profile string            check the pin's compatibility against this catalog target-profile id (required unless --clear)
      --target-profile-revision string   pin the catalog profile revision the compatibility check runs against
      --target-profiles string           target-profile catalog path (default: <dir>/../model-registry/target-profiles.yaml)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

qualify reads the frozen preregistration and matrix, the measured cell descriptors and the paired evidence records, and writes the frozen sonny.qualification/v1 campaign document. Every blocked target gets a reported row with the verdict "unsupported" and no measured cells. Every evidence record's digest is verified and bound to the frozen matrix before it is read, and a promotion is withheld unless the campaign's predeclared controls were measured for that target. promote, reject and blocked all exit ZERO with the document on stdout; only an invalid input exits non-zero. --freeze-preregistration is a stand-alone mode that freezes a Phase 0 document in place.

Usage:
  sonny recipe qualify [flags]

Flags:
      --campaign string                 campaign id; must equal the matrix's campaign_id
      --cells-dir string                directory of measured cell descriptors
      --compiler-version string         the pack compiler version the campaign ran under (default "pack.compile/v2")
      --date string                     YYYY-MM-DD, used only in the printed ledger rows
      --evidence-dir string             directory of sonny.variant-evidence/v1 records
      --format string                   text|json (default "text")
      --freeze-preregistration string   stand-alone mode: freeze a Phase 0 document in place and exit
  -h, --help                            help for qualify
      --ledger-rows                     also print the packs/skillopt/README.md rows
      --matrix string                   frozen matrix manifest
      --notes string                    used only in the printed ledger rows
      --out string                      output document path (qualification/<c>/qualification.json)
      --preregistration string          frozen Phase 0 document
      --run-dir string                  used only in the printed ledger rows

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

reload performs an unconditional git fetch+reset for the named source (or every source when name is omitted). It ignores UpdatePolicy so a manual-policy source still pulls down a new tip on demand.

Usage:
  sonny recipe reload [name] [flags]

Flags:
  -h, --help   help for reload

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Drop a recipe source and delete its cache directory

Usage:
  sonny recipe remove <name> [flags]

Flags:
  -h, --help   help for remove

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Verifies a saved route lock, rebuilds the saved snapshot from its captured
bytes, and reproduces the pinned decision.

It REPRODUCES; it does not re-decide (amendment A-09). The rendered
document is marked origin=replay, its candidate set and its chain are the
LOCK's, and any input that has moved is reported as lock drift naming the
input rather than silently re-resolving to a new answer.

Usage:
  sonny recipe replay [flags]

Flags:
      --format string     output format: text|json (default "text")
  -h, --help              help for replay
      --lock string       saved route lock document (required)
      --snapshot string   saved snapshot document (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Loads a recipe, builds its effective tool registry (native tools scoped
by the pack's allowlist, optionally merged with MCP server tools), renders
the tool-aware system prompt exactly as an interactive session would, and
emits the result as a machine-readable "subject": the rendered prompt,
its components, the tools it was told about, and content-addressable
digests over each. This is the introspection contract external
prompt-optimizers consume.

Without --connect, MCP tools are absent from the render and mcp_digest
hashes only the resolved server configs (no processes are spawned).
With --connect, MCP servers are connected and their tools enumerated
(subject to the operator's MCP allowlist).

Usage:
  sonny recipe resolve <recipe-id> [flags]

Flags:
      --allow-draft-variants             allow a draft (not approved) variant to be selected by this resolution; for a qualification campaign's draft-time measurement only
      --capability-digest string         the host's capability-surface digest (default: the offline no-host-surface digest)
      --connect                          connect to enabled MCP servers and enumerate their tools (spawns processes)
      --connect-timeout duration         per-server MCP connect timeout (only used with --connect) (default 15s)
      --dir string                       pack directory to load, REPLACING standard discovery (not additive)
      --explain                          emit the full selection explanation (compiles nothing, calls no provider)
      --file string                      load a single pack YAML by file path
      --format string                    output format: text|json (default "text")
  -h, --help                             help for resolve
      --lock-out string                  with --explain, write the resolution's redacted route lock here (replayable with pack replay)
      --mcp-config string                MCP sidecar config path (default: standard discovery)
      --snapshot string                  resolve offline against a saved snapshot file
      --subject-version string           subject contract to emit: v1 (legacy shape) or v2 (target profile + component provenance) (default "v1")
      --target-profile string            resolve against this catalog profile id
      --target-profile-revision string   pin the catalog profile revision
      --target-profiles string           target-profile catalog path (default: <dir>/../model-registry/target-profiles.yaml)
      --variant string                   explicit variant pin, or auto for automatic routing (default "auto")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

BM25-rank loaded prompt recipes against a query

Usage:
  sonny recipe search <query> [flags]

Flags:
      --detail string   short|full (default "short")
      --format string   text|json (default "text")
  -h, --help            help for search
      --tags strings    filter to packs carrying ALL listed tags before ranking

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Captures every input a variant resolution depends on -- the discovered
variant documents, the prompt fragments they reference, the base recipe
closure, the target-profile catalog and the effective policy -- into one
portable document, and reports the snapshot digest it computed.

The document carries the captured BYTES, which is what makes it
replayable: recipe replay and recipe resolve --snapshot rebuild the snapshot
from it and refuse any mismatch with the digest it states. It contains no
timestamp, no hostname, no endpoint, no credential and no absolute path.

Usage:
  sonny recipe snapshot <recipe-id> [flags]

Flags:
      --capability-digest string   the host's capability-surface digest (default: the offline no-host-surface digest)
      --dir string                 pack directory to load, REPLACING standard discovery (not additive)
      --file string                load a single pack YAML by file path
      --format string              output format: text|json (default "text")
  -h, --help                       help for snapshot
      --out string                 snapshot document path (required)
      --target-profiles string     target-profile catalog path (default: <dir>/../model-registry/target-profiles.yaml)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Fetch + reset tracked sources to their upstream branch tip

Usage:
  sonny recipe update [flags]

Flags:
  -h, --help          help for update
      --name string   limit update to one source (empty = update all on_startup sources)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Statically validate a recipe YAML file

Usage:
  sonny recipe validate <file> [flags]

Flags:
  -h, --help            help for validate
      --output string   output format: text | jsonl (default "text")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Unlike `recipe variants <recipe-id>`, which lists everything discovery found for a logical recipe, `recipe variant` subcommands address exactly one pack_variant envelope file an operator names.

Usage:
  sonny recipe variant [command]

Available Commands:
  approve     Flip an exported variant envelope's trust.status from draft to approved

Flags:
  -h, --help   help for variant

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny recipe variant [command] --help" for more information about a command.

Sets trust.status: approved on one exported pack_variant envelope so the
runtime activator will serve it: internal/modelvariant's evaluateTrust
admits ONLY approved when require_approval is set (the shipped default),
and the exporter always writes draft -- an exported variant is a proposal,
never born approved.

The envelope's own digest INCLUDES trust.status (VariantEnvelope.Digest
strips only trust.signature, trust.key_id and notes), so approving a
variant changes its digest, and every exact variant that extends it pins
that exact digest in extends.digest. This command therefore also finds
every exact child under --variant-root (or, with --file alone, under the
file's own directory) that extends the approved variant, re-pins its
extends.digest to the new digest, and approves it too, so the chain stays
resolvable with nothing left stale.

An already-approved target is not an error: nothing is written and the
command reports it as already approved. A revoked target refuses: §C.10
gives revocation no policy knob that relaxes it, and this command is not
one either.

Usage:
  sonny recipe variant approve [flags]

Flags:
      --file string           approve this envelope file directly
      --format string         output format: text|json (default "text")
  -h, --help                  help for approve
      --recipe string         logical pack id, with --variant-root
      --variant string        model variant id, with --variant-root
      --variant-root string   variant directory tree: resolves --pack/--variant to <root>/<pack>.<variant>.yaml, and is the tree scanned for exact children extending the approved variant

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Lists every pack_variant document discovery found for the named logical
pack: its tier, its specificity class, its trust status, whether it is
active, shadowed or quarantined, and its envelope and selector digests.

It resolves nothing and activates nothing: no target profile is consulted,
no variant is selected and no prompt is compiled. A recipe with no variants
prints an empty list and exits zero.

--dir REPLACES standard discovery (not additive), the same meaning it has
on recipe resolve: exactly the named directory is walked, so the digests
printed are the repository's own and not a machine's installed packs.

Usage:
  sonny recipe variants <recipe-id> [flags]

Flags:
      --dir string            pack directory to load, REPLACING standard discovery (not additive)
      --file string           load a single pack YAML by file path
      --format string         output format: text|json (default "text")
  -h, --help                  help for variants
      --include-quarantined   include quarantined variants; they are the diagnostic this command exists for (default true)
      --include-shadowed      include variants a higher tier displaced

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

routing exposes why a capability was served by the target it was served by.

Every value shown is identity-free: opaque manifest handles, eligibility
check names, public scores, evidence counts, and the exact ordered tool
declarations sent to the provider. No provider, model, endpoint, or
credential name is ever displayed.

Usage:
  sonny routing [command]

Available Commands:
  canary      Grade a read-only routing canary and write its evidence bundle
  explain     Explain one routing decision

Flags:
  -h, --help   help for routing

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny routing [command] --help" for more information about a command.

Grade a read-only routing canary and write its evidence bundle

Usage:
  sonny routing canary [flags]

Flags:
  -h, --help         help for canary
      --log string   shadow log path
      --out string   write the evidence bundle to this path
      --read-only    required: grade a read-only canary

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Explain one routing decision

Usage:
  sonny routing explain [flags]

Flags:
      --format string   output format (text or json) (default "text")
  -h, --help            help for explain
      --log string      explanation log path (default: state dir)
      --ref string      explanation ref (default: the most recent decision)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run an interactive chat session with a recipe.

This command starts an interactive session where you can chat with the LLM
using the configured prompt pack. The session supports tool execution,
LSP integration, and agent management.

Examples:
  # Run with packs discovered from default locations
  sonny run

  # Run with one or more pack directories (repeatable)
  sonny run --dir ./packs --dir <data-dir>/packs

  # Run with a specific pack file
  sonny run --file ./my-pack.yaml

  # Run with a specific provider and model
  sonny run --provider anthropic --model claude-sonnet-4-20250514

  # Run in simple mode (no TUI)
  sonny run --simple

Usage:
  sonny run [flags]

Flags:
      --continue                         Resume the most recent session
      --control-db string                Path to the control-plane SQLite database (default: $SONNY_CONTROL_DB, then a control.db sibling of the session DB). Only opened/migrated when the control plane is in use (this flag, $SONNY_CONTROL_DB, --mesh-self, or --mesh-addr)
      --critic string                    Comma-separated list of critic agents to run (code_quality,security,architecture,performance,testing,documentation)
      --critic-recipe string             Critic pack ID or path to a pack YAML file (default "critic")
      --dangerously-auto-approve-tools   DANGEROUS: approve every tool call automatically, with no prompt. Denied tools stay denied and isolation is unaffected. Refused when policy forbids it
      --dangerously-bypass-all           DANGEROUS: --dangerously-auto-approve-tools and --dangerously-bypass-isolation together
      --dangerously-bypass-isolation     DANGEROUS: run tools on the host with no isolation realm. Refused when a trusted isolation.yaml sets minimum_mode
  -d, --dir strings                      directory containing pack YAML files (repeatable; env: SONNY_DIR)
      --eval                             run critic and sentiment evaluations on conversation
      --eval-model string                model for evaluations (fast/cheap recommended) (default "gpt-4o-mini")
      --eval-provider string             provider for evaluation model (default "openai")
  -f, --file string                      single pack YAML file to load
      --headless-mcp                     connect the allowlisted MCP servers from --mcp-config in a headless --prompt run without an isolation realm; refused when trusted policy forbids it, same as the interactive session
  -h, --help                             help for run
      --hyper-client-id string           OAuth client ID for Hyperbolic (required for /login hyper)
      --init-models                      Write the example model-category catalog to the user config dir and exit
      --isolation-assurance string       minimum assurance override: guarded, native, docker, or vm
      --isolation-backend string         isolation backend override: auto, native, docker, or vm
      --isolation-machine string         trusted Docker broker configuration (default: user config isolation-docker.yaml)
      --isolation-mode string            isolation mode override: required, preferred, or off
      --isolation-policy string          trusted isolation policy file (default: user config isolation.yaml)
      --mcp-config string                Path to the MCP server config (default: the profile config directory's mcp.yaml)
      --mesh-addr string                 gRPC address of the mesh node to observe (default: SONNY_MESH_ADDR env)
      --mesh-peer strings                gRPC endpoint of a mesh node to show in the UI Connect dialog (repeatable)
      --mesh-self                        expose this chat session over an in-process mesh.Node so remote clients can attach
      --mesh-self-grpc string            gRPC listen address for the in-process mesh node (--mesh-self) (default ":50052")
      --mesh-self-synapse string         synapse listen address for the in-process mesh node (--mesh-self) (default ":50053")
      --models string                    Path to the user model-category catalog (default: $SONNY_MODELS_FILE, then <config-dir>/models.yaml; see 'sonny config path')
      --new                              start a fresh session instead of restoring the last one
      --no-tools                         disable all tools for a headless completion
      --no-trace                         disable conversation tracing (default: on; env: SONNY_TRACE=0)
      --permissions                      Prompt for approval before write/exec tool calls (default off; reads always auto-allow)
      --pick-recipe                      force the prompt-pack picker even when a default is set
      --policy-binding string            path to the decision-policy binding a controller dispatched this worker with (a file path, never the binding itself)
      --prompt string                    run a single headless turn with this text and exit (implies --simple); used to spawn sonny as a one-shot sub-agent
      --recipe string                    select an already-discovered pack by its id (skips the picker)
      --recipe-dir string                DEPRECATED: alias for --dir (single dir)
      --recipe-file string               DEPRECATED: alias for --file
      --result-json string               write the headless turn's result (final reply, usage, tool calls, trace ids) as JSON to this path; requires --prompt
      --session string                   Resume a specific session by UUID; fails fast if id is unknown
      --session-db string                Path to the session SQLite database (default: $XDG_DATA_HOME/sonny/sessions.db)
      --show-prompt                      show rendered system prompt and exit
      --simple                           use simple chat mode (no TUI)
      --supervisor-deployment string     absolute protected JSON deployment for durable interactive supervision (env: SONNY_SUPERVISOR_DEPLOYMENT)
      --task-ref string                  external work-item reference (Jira/GitLab issue URL) governing this session
      --telemetry string                 path to JSONL file for logging interactions
      --trace-ca string                  CA certificate for trace upload
      --trace-cert string                client certificate for trace upload
      --trace-dir string                 directory for saving conversation traces (default: <data-dir>/traces)
      --trace-key string                 client key for trace upload
      --trace-server string              trace aggregation server address (default "localhost:50051")
      --trace-upload                     enable automatic trace upload to aggregation server
      --training-format string           export metadata-bearing training data (openai_chat, openai_tools, sharegpt, sharegpt_tool, or chatml)
      --training-include-tools           include tool calls in training export
      --var stringArray                  Set pack variable (key=value), repeatable
      --variant-constraint string        path to the model-variant constraint packet a parent dispatched this worker with (a file path, never the packet itself)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run deterministic full-session evaluation and optimization

Usage:
  sonny session [command]

Available Commands:
  eval        Evaluate, replay, minimize, and promote full-session regressions
  optimize    Run paired full-session gates for an explicit prompt candidate

Flags:
  -h, --help   help for session

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny session [command] --help" for more information about a command.

Evaluate, replay, minimize, and promote full-session regressions

Usage:
  sonny session eval [command]

Available Commands:
  generate-suite     Generate the canonical virtual and native context-boundary suite
  ingest-traces      Join and privacy-validate production trace segments
  minimize           Deterministically minimize a trace while preserving its failure signature
  promote-fixture    Seal a reviewed complete trace as a content-addressed regression fixture
  regression-request Produce paired baseline/candidate evidence for the regression gate
  replay             Replay an admitted trace scenario through the production session adapter
  run                Run a versioned multi-turn scenario through Sonny's production session engine
  run-suite          Run every canonical suite scenario through the production session engine

Flags:
  -h, --help   help for eval

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny session eval [command] --help" for more information about a command.

Generate the canonical virtual and native context-boundary suite

Usage:
  sonny session eval generate-suite [flags]

Flags:
      --advertised-input int   advertised input tokens (default 32768)
      --force                  replace an existing --out file
  -h, --help                   help for generate-suite
      --id string              suite identifier (default "canonical-session")
      --out string             write suite JSON to this file
      --output-reserve int     reserved output tokens (default 4096)
      --safety-tokens int      safety margin tokens (default 1024)
      --system-tokens int      compiled system prompt tokens (default 2048)
      --tool-tokens int        tool schema tokens (default 2048)
      --workspace string       materialized dir: workspace fixture (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Join and privacy-validate production trace segments

Usage:
  sonny session eval ingest-traces [flags]

Flags:
      --dry-run        validate without writing --out
      --force          replace an existing --out file
  -h, --help           help for ingest-traces
      --out string     write stable JSON output to this file
      --trace string   trace JSONL file or persistent-session directory (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Deterministically minimize a trace while preserving its failure signature

Usage:
  sonny session eval minimize [flags]

Flags:
      --dry-run        validate and minimize in memory without writing --out
      --force          replace an existing --out file
  -h, --help           help for minimize
      --out string     write minimized stable JSON output to this file
      --trace string   trace JSONL file or persistent-session directory (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Seal a reviewed complete trace as a content-addressed regression fixture

Usage:
  sonny session eval promote-fixture [flags]

Flags:
      --dry-run              validate and compute identity without writing
      --force                replace an existing --out file
  -h, --help                 help for promote-fixture
      --out string           fixture output path (required)
      --result string        expected SessionResult JSON (required)
      --reviewed-by string   human reviewer identity (required)
      --scenario string      reviewed scenario JSON or YAML (required)
      --trace string         complete source trace file or directory (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Produce paired baseline/candidate evidence for the regression gate

Usage:
  sonny session eval regression-request <recipe-id> [flags]

Flags:
      --baseline-root string          baseline checkout root (required)
      --candidate-root string         candidate checkout root (required)
      --force                         replace an existing request output
  -h, --help                          help for regression-request
      --impact-plan string            sealed regression impact plan (required)
      --input-price-per-mtok float    approved normalized input price per million tokens (default -1)
      --max-cost-delta-micros int     maximum allowed mean candidate cost increase in micros (default -1)
      --max-latency-delta-ms int      maximum allowed mean candidate latency increase in milliseconds (default -1)
      --max-token-delta int           maximum allowed mean candidate token increase (default -1)
      --max-tool-call-delta int       maximum allowed mean candidate tool-call increase (default -1)
      --min-pairs int                 minimum measured pairs required by the gate (default 25)
      --out string                    regressiongate.Request output path (required)
      --output-price-per-mtok float   approved normalized output price per million tokens (default -1)
      --repeat int                    paired replicates per scenario (default 2)
      --suite string                  baseline-produced full-session suite (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Replay an admitted trace scenario through the production session adapter

Usage:
  sonny session eval replay <recipe-id> [flags]

Flags:
      --dir string               additional pack directory
      --dry-run                  validate trace/scenario without provider calls or writes
      --expected-result string   optional prior SessionResult JSON for exact divergence comparison
      --file string              load the pack from one YAML file
      --force                    replace an existing --out file
  -h, --help                     help for replay
      --out string               write stable JSON output to this file
      --scenario string          reviewed scenario JSON or YAML (required)
      --trace string             source trace file or directory (required)
      --workspace string         materialized workspace directory overriding workspace_fixture

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run a versioned multi-turn scenario through Sonny's production session engine

Usage:
  sonny session eval run <recipe-id> [flags]

Flags:
      --dir string         additional pack directory
      --dry-run            validate and digest inputs without provider calls or writes
      --file string        load the pack from one YAML file
      --force              replace an existing --out file
  -h, --help               help for run
      --hosted             run the scenario on a hosted session of a private daemon with local agent messaging on, so proceed_workers runs real native workers; every turn must be request_expectation: no_request and is graded on host facts (SONNY-4187)
      --out string         write the stable JSON report to this file
      --scenario string    scenario JSON or YAML file (required)
      --workspace string   materialized workspace directory overriding workspace_fixture

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run every canonical suite scenario through the production session engine

Usage:
  sonny session eval run-suite <recipe-id> [flags]

Flags:
      --dir string     additional pack directory
      --dry-run        validate suite and pack without provider calls
      --file string    load the pack from one YAML file
      --force          replace an existing --out file
  -h, --help           help for run-suite
      --out string     write stable JSON report to this file
      --suite string   canonical suite JSON file (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run paired full-session gates for an explicit prompt candidate

Usage:
  sonny session optimize <recipe-id> [flags]

Flags:
      --candidate-file string   candidate pack YAML (required)
      --concurrency int         run scenario/replicate paired trials through the shared bounded scheduler with up to this many concurrent trials (<=1 is serial) (default 1)
      --dir string              additional baseline pack directory
      --dry-run                 validate candidate/scenarios without provider calls or writes
      --file string             baseline pack YAML
      --force                   replace an existing --out file
  -h, --help                    help for optimize
      --journal string          durable arm journal for cancellation-safe resume
      --min-pairs int           minimum valid pairs required by the gate (default 10)
      --out string              write stable JSON output to this file
      --repeat int              paired replicates per scenario (default 10)
      --scenario strings        scenario JSON/YAML file; repeat for a suite (required)
      --workspace string        materialized workspace overriding every fixture

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage the supervisor daemon: ensure, serve, status, stop

Usage:
  sonny supervisor [command]

Available Commands:
  ensure      Discover or safely start the shared user supervisor
  offline     Issue, inspect, and reconcile signed offline bundles
  serve       Run the supervisor daemon in the foreground
  status      Print the supervisor daemon's health snapshot as JSON
  stop        Stop the supervisor daemon

Flags:
  -h, --help   help for supervisor

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny supervisor [command] --help" for more information about a command.

ensure authenticates a compatible local supervisor and prints its resolved endpoint and executable. If the endpoint is unavailable, it serializes startup with other native clients, re-verifies the installed Sonny executable, starts one detached user supervisor, and waits for authenticated readiness. It never resolves a binary from PATH.

Usage:
  sonny supervisor ensure [flags]

Flags:
      --endpoint string   supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help              help for ensure
      --tenant string     tenant this connection speaks for (default "default")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Issue, inspect, and reconcile signed offline bundles

Usage:
  sonny supervisor offline [command]

Available Commands:
  issue       Sign a new offline bundle authorizing bounded disconnected work
  reconcile   Reconcile a local offline journal against its signed bundle
  status      Print a signed offline bundle's health as JSON, without any secret

Flags:
  -h, --help   help for offline

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny supervisor offline [command] --help" for more information about a command.

issue builds a Bundle from its flags, refuses it outright if it claims any effect ENG-4527 prohibits offline or exceeds a matching identity parent grant, signs it with --signing-key, and writes the signed bundle as JSON to --out. Nothing is written when issuance is refused. --tool-digest and --adapter-digest bind implementations by digest: they are written into the bundle before it is signed, so a bound digest cannot be edited afterwards, and reconcile refuses a journaled claim whose handler attestation is missing, names an implementation the bundle did not bind, or carries a different digest.

Usage:
  sonny supervisor offline issue [flags]

Flags:
      --adapter-digest stringArray   bind an adapter implementation as name=sha256:<64 hex digits> (repeatable)
      --catalog-root string          catalog root this bundle is pinned to (required)
      --counter-high uint            highest journal counter this bundle authorizes (required)
      --counter-low uint             lowest journal counter this bundle authorizes (default 1)
      --device-id string             device this bundle authorizes (required)
      --effect stringArray           an effect this bundle authorizes (repeatable, at least one required)
      --expires-in duration          how long after --not-before the bundle remains valid (default 24h0m0s)
      --freeze-epoch string          freeze epoch this bundle is pinned to
  -h, --help                         help for issue
      --id string                    bundle id (default: a generated UUID)
      --max-artifact-bytes int       maximum bytes per journaled artifact
      --max-attempts int             maximum attempts this bundle authorizes
      --max-cost-micros int          maximum cost (in micros) this bundle authorizes
      --max-event-bytes int          maximum bytes per journaled event
      --max-tokens int               maximum tokens this bundle authorizes
      --not-before string            RFC3339 time before which the bundle is not valid (default: now)
      --out string                   path to write the signed bundle JSON (required)
      --parent-grant-ref string      the online execution grant this bundle narrows (required)
      --policy-root string           policy root this bundle is pinned to (required)
      --resource stringArray         a resource this bundle authorizes (repeatable)
      --signing-key string           path to a raw 64-byte ed25519 private key (required)
      --snapshot-root string         snapshot root this bundle is pinned to (required)
      --tenant string                tenant this bundle is issued for (required)
      --tool-digest stringArray      bind a tool implementation as name=sha256:<64 hex digits> (repeatable)
      --worker-id string             worker this bundle authorizes

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

reconcile opens the local journal, verifies the signed bundle against --trusted-key, and imports every journaled claim as evidence -- never as authorization (ENG-4527). It exits non-zero and prints one task per claim it could not resolve on its own (a forbidden effect, an online-history conflict, or content roots that are no longer current).

Usage:
  sonny supervisor offline reconcile [flags]

Flags:
      --accept-missing-head string          with --repair, recreate a missing journal head sidecar, naming the verified tail as <counter>:<hash>
      --accept-missing-head-reason string   why the head sidecar is missing; recorded with --accept-missing-head
      --bundle string                       path to a signed offline bundle JSON file (required)
      --catalog-root string                 current catalog root (default: the bundle's own)
      --device-key string                   path to the journal's raw 64-byte ed25519 device key (required)
      --encryption-key string               path to the journal's raw 32-byte AES-256 key (required)
      --freeze-epoch string                 current freeze epoch (default: the bundle's own)
  -h, --help                                help for reconcile
      --journal-dir string                  path to the local journal directory (required)
      --parent-expires-at string            RFC3339 expiry of the online parent grant (default: not enforced)
      --parent-revoked                      treat the online parent grant as revoked
      --policy-root string                  current policy root (default: the bundle's own)
      --repair                              open the journal writable and repair a crash state (head sidecar one entry behind, torn final line)
      --snapshot-root string                current snapshot root (default: the bundle's own)
      --trusted-key stringArray             path to a raw 32-byte ed25519 public key that may have signed the bundle (repeatable, at least one required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print a signed offline bundle's health as JSON, without any secret

Usage:
  sonny supervisor offline status [flags]

Flags:
      --bundle string   path to a signed offline bundle JSON file (required)
  -h, --help            help for status

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

serve opens the control store, applies its migrations, builds the in-process supervisor.Runtime, binds the local IPC endpoint, and serves peer-bound connections until SIGINT/SIGTERM, then drains and closes.

--profile selects how trust and the control store come up (SONNY-1354,
extended by SONNY-3224/SONNY-3225):
  local        no operator file, no network: a signed single-user
               profile is bootstrapped under the data directory, and
               a mesh adapter is composed in this same process.
  organization an organization bundle is present and its signature
               verifies against its own embedded key: the same
               no-manifest-needed single-user composition the local
               profile builds is used, no --manifest required. A
               bundle that fails verification is a hard error, never
               a silent fallback to local. --manifest is still
               required when no bundle verifies (this combination is
               detection/reporting only, and additionally requires the
               manifest's tenant to match the bundle's).
  manifest     today's behavior: serve exactly the deployment manifest
               named by --manifest.
The default is manifest when --manifest is given, organization when an
organization bundle is detected and verified and --manifest is not
given, and local otherwise.

Usage:
  sonny supervisor serve [flags]

Flags:
      --endpoint string              supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help                         help for serve
      --manifest string              private versioned deployment manifest (required for the manifest and organization profiles)
      --mesh-advertise-addr string   SSH-enrolled local mesh advertised gRPC address
      --mesh-ca string               SSH-enrolled local mesh root CA
      --mesh-cert string             SSH-enrolled local mesh certificate chain
      --mesh-grpc string             SSH-enrolled local mesh gRPC listen address (loopback only)
      --mesh-key string              SSH-enrolled local mesh private key
      --mesh-node-id string          SSH-enrolled local mesh node ID
      --mesh-peer strings            SSH-enrolled local mesh peer URL (repeatable)
      --mesh-synapse-listen string   SSH-enrolled local mesh Synapse listen address (loopback only)
      --mesh-trust-domain string     SSH-enrolled personal mesh trust domain
      --profile string               trust profile: local, organization, or manifest (default: inferred, see --help)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the supervisor daemon's health snapshot as JSON

Usage:
  sonny supervisor status [flags]

Flags:
      --endpoint string   supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help              help for status
      --tenant string     tenant this connection speaks for (default "default")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

stop asks the authenticated local supervisor to shut down gracefully. The daemon acknowledges the request before it stops accepting work, then drains sessions and releases its endpoint. If nothing answers, stopping is a no-op (stop is idempotent).

Usage:
  sonny supervisor stop [flags]

Flags:
      --endpoint string   supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help              help for stop
      --tenant string     tenant this connection speaks for (default "default")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List and manage tools available to the LLM.

Tools provide capabilities like file operations, search, shell commands,
web fetching, and more. This command shows what tools are available and
their descriptions.

Usage:
  sonny tools [command]

Available Commands:
  efficiency  Report the resolved tool-efficiency status
  inventory   Print the core / searchable / retired tool contract recipes are written against
  list        List all available tools

Flags:
  -h, --help   help for tools

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny tools [command] --help" for more information about a command.

Report the tool-efficiency policy this host resolves, and every fact the
one-line status printed during a turn has no room to show.

Without --json this prints that same one-line summary: the resolved
profile and its provenance, how many efficiency stages are active out of
the whole vocabulary, and the counts an operator watches.

With --json it emits the canonical status document -- the identical shape
the headless, daemon and mesh surfaces carry -- inside the standard CLI
envelope, including the per-stage provenance, per-view recovery and
call-site detail no text rendering carries.

This command runs OUTSIDE a turn. Nothing has called a provider, capped a
tool list, admitted a result view, captured an artifact or recorded a
write, so every one of those axes reports "unknown" rather than zero: a
cap nobody measured is not a cap that withheld nothing. With --recipe-file
the policy is resolved from that recipe instead of from the host default,
and its declared provider tool limit is carried into the --json
document's tools object as the CONFIGURED bound -- the OBSERVED figure
still reports unknown until a turn actually measures it.

Usage:
  sonny tools efficiency [flags]

Flags:
  -h, --help                 help for efficiency
      --json                 emit the full status document as JSON instead of the one-line summary
      --recipe-file string   resolve the efficiency policy from this pack file instead of the host default

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print the tool contract prompt recipes are written against, taken from the
registry an unrestricted interactive session builds (no MCP servers):

  core        declared in every session's tools array (intersected with a
              pack's tools.allowed)
  unlocked    declared after the trigger tool first succeeds
  searchable  reachable only through tool_search, then tool_exec with the
              returned exec_name (local.<name>)
  mcp         MCP rows (<server>.<tool>), also tool_search -> tool_exec
  retired     removed or renamed names and what replaces each

Usage:
  sonny tools inventory [flags]

Flags:
      --format string   output format: yaml or json (default "yaml")
  -h, --help            help for inventory

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

List all tools that are available for use by the LLM.

This includes file tools, search tools, shell tools, web tools,
utility tools, agent tools, and LSP tools.

With --json, emit each tool's full schema as JSON Schema -- the shape a
provider's tools array carries -- so the manifest can be measured rather
than guessed at. With --recipe-file, narrow the list to what that recipe would
actually send and report the provider's tool cap. With --mcp-config,
resolve and connect to the configured MCP servers (merging --recipe-file's
inline mcp.servers, same as "sonny mcp list") and include their live tools
in the listing alongside the native ones.

With --category and --file-type, narrow the listing exactly the way the
model's own tool_search tool narrows it. --category matches a category
(workspace), a subcategory (file), the dotted pair (workspace.file), or a
secondary category (code). --file-type takes an extension (json), a dotted
extension (.json), a file name (notes.md) or a path, and a tool that
declares "any" matches every file type. The two combine. MCP tools carry
no catalog classification, so either filter excludes them.

Usage:
  sonny tools list [flags]

Flags:
      --category string            list only tools in this category, subcategory, category.subcategory, or secondary category
      --connect-timeout duration   per-server MCP connect timeout (only used with --mcp-config) (default 15s)
      --file-type string           list only tools that work on this file type (an extension such as json, a file name, or any)
      --format string              deprecated alias for --json (text|json); use --json
  -h, --help                       help for list
      --json                       emit full JSON Schema for each tool instead of a truncated table
      --mcp-config string          resolve and connect to these MCP servers, including their tools in the listing
      --recipe-file string         narrow the list to the tools this pack allows

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Locate, parse, filter, and summarize the conversation traces sonny run
writes (one JSON Lines file per run under <data-dir>/traces/<session>/).

Every subcommand that takes a <ref> accepts a file path, a session
directory, a trace id or a unique prefix of one (the UUID in the file
name), or a session id prefix (the directory name). A session ref loads
every resume segment of that session in order.

The trace directory is read-only: nothing under it is ever created,
modified, or deleted. Pass --json for a machine-readable envelope.

Note: `sonny canary` is a different, unrelated command -- the CANARY
requirement and gap traceability system.

Examples:
  # Newest traces, with session titles from sessions.db
  sonny trace list

  # Everything that went wrong in a trace, by id prefix
  sonny trace errors 862e2758

  # Tool calls on turn 3, as JSON
  sonny trace tools 862e2758 --turn 3 --json

  # Metrics across every trace from the last week, grouped by pack
  sonny trace status --since 2026-09-06 --group-by pack

  # Follow the newest (running) trace
  sonny trace tail

  # Sub-agent tree, following child trace files
  sonny trace agents 0d6c4bf3 --follow

  # Raw events for jq pipelines
  sonny trace events 0d6c4bf3 --type tool_result | jq .tool_result.tool_name

Usage:
  sonny trace [command]

Available Commands:
  agents      Sub-agents a trace spawned, as a tree
  errors      Everything that went wrong in a trace
  events      Stream a trace's events as JSON Lines for jq pipelines
  html        Self-contained HTML timeline and drill-down page for a trace
  list        List conversation traces, newest first
  path        Print the file path(s) a trace reference resolves to
  show        Show a trace as a per-turn timeline
  status      Metrics across one or many traces: tokens, errors, latency, models
  summary     Statistics for a trace, recomputed from its events
  tail        Follow a running conversation trace as it is written
  tools       Tool calls joined to their results

Flags:
  -h, --help               help for trace
      --trace-dir string   directory holding conversation traces, read-only (default: <data-dir>/traces)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny trace [command] --help" for more information about a command.

Show every sub-agent this trace spawned: agent name, process id, turn,
the child's own session id and trace file (from the agent_session
event), exit code, and output size. With --follow each child's trace file
is opened and its own sub-agents are attached beneath it, recursively,
up to --max-depth levels. A child trace that cannot be read is reported
inline rather than failing the command.

Examples:
  sonny trace agents 0d6c4bf3
  sonny trace agents 0d6c4bf3 --follow --max-depth 3 --json

Usage:
  sonny trace agents <ref> [flags]

Flags:
      --follow          open each child's trace file and attach its sub-agents
  -h, --help            help for agents
      --json            emit the machine-readable envelope
      --max-depth int   how many levels of child traces --follow descends (default 8)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

List failures across every event kind in one table: provider errors and
cancellations, tool errors, weak failures (non-zero exit without a hard
error), cascade-skipped calls, MCP tool errors, error events, critic
errors, sub-agent spawn failures, and sub-agents that exited non-zero.
Each row carries the file line, turn, failure class and code, and the
message, so the row can be opened in the raw file directly.

Kinds for --kind: api_error, api_canceled, tool_error, tool_weak_failure,
tool_skipped, mcp_tool_error, error_event, critic_error,
agent_spawn_failure, agent_exit_nonzero.

Examples:
  sonny trace errors 862e2758
  sonny trace errors 862e2758 --kind api_error --kind tool_error --json

Usage:
  sonny trace errors <ref> [flags]

Flags:
  -h, --help               help for errors
      --json               emit the machine-readable envelope
      --kind stringArray   only failures of this kind (repeatable)
      --turn string        only these turns: N, N,M, or N-M

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Print the selected events exactly as they appear on disk (the "event"
object of each record), one JSON object per line. This is the jq-friendly
view: no envelope, no header record, no summary record.

--fields keeps only the named top-level keys of each event (for example
id,timestamp,type,turn,tool_result). Unknown keys are ignored.

Examples:
  sonny trace events 862e2758 --type tool_result | jq -r .tool_result.tool_name
  sonny trace events 862e2758 --errors --fields id,turn,type,error
  sonny trace events 862e2758 --turn 4 --grep spawn_agent

Usage:
  sonny trace events <ref> [flags]

Flags:
      --errors             only events that record a failure
      --fields string      comma-separated top-level event keys to keep (default: all)
      --grep string        only events whose JSON contains this text (case-insensitive)
  -h, --help               help for events
      --limit int          maximum events to print (0 = all)
      --since string       only events at/after this time (RFC3339 or YYYY-MM-DD)
      --tool string        only tool events for this tool (mcp tools as server/tool)
      --turn string        only these turns: N, N,M, or N-M
      --type stringArray   only events of this type (repeatable)
      --until string       only events at/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Render one trace as a single HTML file with a per-turn timeline, tool
call, failure, sub-agent and context-event drill-downs, and data coverage
indicators for the recipe, context, tool and time dimensions. Every total on
the page is computed by the same code as sonny trace summary and sonny
trace status, so the numbers agree by construction.

The page has no scripts, fonts, images or network references and opens
offline. --audience controls what it may contain: operator (everything the
CLI shows), team (names, sizes, digests and outcomes but no user input,
message content, tool parameters, tool results, agent arguments or paths)
or executive (counts, timings and outcomes only). Lower audiences are
enforced when the view is built, not when it is rendered.

Examples:
  sonny trace html 862e2758 --out trace.html
  sonny trace html 862e2758 --audience team --out review.html
  sonny trace html 862e2758 --json | jq .data.view.coverage

Usage:
  sonny trace html <ref> [flags]

Flags:
      --audience string   who may read the page: operator, team or executive (default "operator")
  -h, --help              help for html
      --json              emit the machine-readable envelope with the full view instead of the page
      --max-events int    timeline rows to include; totals always cover every event (default 20000)
      --out string        write the page to this file instead of stdout

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

List the trace files under the trace directory, newest first, with the
recipe, model, event/turn/failure counts, and (when sessions.db is
readable) the session title. Each file is parsed, so --limit bounds the
work; --limit 0 lists everything.

Filters: --session <id prefix>, --pack <id>, --model <name>, --since and
--until (RFC3339 or YYYY-MM-DD, matched against the file's start time),
and --errors (only traces with at least one failure).

Examples:
  sonny trace list
  sonny trace list --errors --since 2026-09-10
  sonny trace list --pack architect --json --limit 0

Usage:
  sonny trace list [flags]

Flags:
      --errors               only traces with at least one failure
  -h, --help                 help for list
      --json                 emit the machine-readable envelope instead of a table
      --limit int            maximum rows (0 = no limit) (default 20)
      --model string         only traces whose header model equals this
      --no-sessions          skip the sessions.db title join
      --recipe string        only traces run with this pack id
      --session string       only traces of sessions whose id starts with this prefix
      --sessions-db string   sessions database to join titles from (default: <data-dir>/sessions.db)
      --since string         only traces started on/after this time (RFC3339 or YYYY-MM-DD)
      --until string         only traces started on/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Resolve a trace reference (file, directory, trace id prefix, or session id
prefix) and print the matching trace file paths, one per line, oldest
first. A session reference prints every resume segment. Useful for
scripting: less "$(sonny trace path 862e2758)".

Examples:
  sonny trace path 862e2758
  sonny trace path 11111111-2222-4333-8444-555555555555 --json

Usage:
  sonny trace path <ref> [flags]

Flags:
  -h, --help   help for path
      --json   emit the machine-readable envelope instead of plain paths

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Print a trace's header, recomputed statistics, and every event as one
line: file line number, wall-clock time, turn, type, and a short
summary. Filters narrow the event list; the header and statistics always
describe the whole trace. --raw prints each selected event's JSON object
instead of the summary line; --full disables summary truncation.

Examples:
  sonny trace show 862e2758
  sonny trace show 862e2758 --turn 3-5 --type tool_call --type tool_result
  sonny trace show 862e2758 --errors --raw

Usage:
  sonny trace show <ref> [flags]

Flags:
      --errors             only events that record a failure
      --full               do not truncate event summaries
      --grep string        only events whose JSON contains this text (case-insensitive)
  -h, --help               help for show
      --json               emit the machine-readable envelope
      --limit int          maximum events to print (0 = all)
      --raw                print selected events as raw JSON objects, one per line
      --since string       only events at/after this time (RFC3339 or YYYY-MM-DD)
      --tool string        only tool events for this tool (mcp tools as server/tool)
      --turn string        only these turns: N, N,M, or N-M
      --type stringArray   only events of this type (repeatable)
      --until string       only events at/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Aggregate metrics over a set of traces. With refs, each ref resolves like
the other subcommands; without refs, every trace under the trace
directory is included. Either way, a persistent session is one trace: all
of its segments (resumes) are grouped and merged together, even when refs
name only some of them, so a session is never split or double-counted.
Filters narrow the set either way: --since/--until on the session's
earliest segment's start time (a bare YYYY-MM-DD --until rounds up to the
end of that UTC day, so the named day is included), --session by id
prefix, --recipe, --provider and --model by the trace header, --errors for
traces with at least one failure, --limit for the N newest.

Reported: trace/session/segment counts, turns, API requests and error,
cancel and rate-limit counts with the error rate, tool calls with error
and weak failure counts and rate, sub-agent spawns, prompt/completion
tokens and tokens per request, API and tool latency (min, p50, p95, p99,
max, mean; nearest-rank), problems (malformed lines) and traces skipped
(unreadable files), failures by kind, a per-model breakout (requests
joined to responses by request id), the busiest tools, and one row per
trace. A trace's duration is the wall-clock span from its first to its
last event, so a resumed session's duration includes the idle time
between segments. --group-by adds a rollup per pack, provider, model,
session, or day; a multi-segment session groups under its FIRST segment's
day, not the day of its most recent resume.

Every selected trace file is parsed, so a large directory with no filters
takes a while; use --since or --limit to bound it.

Examples:
  sonny trace status
  sonny trace status --since 2026-09-06 --group-by pack
  sonny trace status 862e2758 0d6c4bf3 --json | jq .data.report.models
  sonny trace status --errors --per-trace

Usage:
  sonny trace status [ref ...] [flags]

Flags:
      --errors            only traces with at least one failure
      --group-by string   add a rollup per day, model, pack, provider, session
  -h, --help              help for status
      --json              emit the machine-readable envelope
      --limit int         keep only the N newest traces (0 = all)
      --model string      only traces whose header model equals this
      --per-trace         print the per-trace table (text only; JSON always includes it)
      --provider string   only traces whose header provider equals this
      --recipe string     only traces run with this pack id
      --session string    only traces of sessions whose id starts with this prefix
      --since string      only traces started on/after this time (RFC3339 or YYYY-MM-DD)
      --top int           rows in the model and tool tables (text only; 0 = all) (default 10)
      --until string      only traces started on/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Recompute turn, API, tool, token, latency, failure, and sub-agent
statistics from the events, so a trace whose writer never reached the
summary record (a crash, a kill, a still-running session) reports the
same numbers as a closed one. The writer's own summary record, when
present, is included under recorded_summary in --json output.

Examples:
  sonny trace summary 862e2758
  sonny trace summary 11111111-2222 --json | jq .data.stats.tools_by_name

Usage:
  sonny trace summary <ref> [flags]

Flags:
  -h, --help   help for summary
      --json   emit the machine-readable envelope

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Print the newest events of a trace and, unless --no-follow is given,
keep printing new ones as the writer appends them.

With no ref, the most recently modified trace file is followed. A ref
resolves like every other subcommand: a trace id/prefix follows that one
file (a later resume segment is NOT switched to unless --session is
given); a session id/prefix follows the newest segment of that session,
switching to a newer segment when a resume writes one (requires --stay,
since a resume usually happens after this command would otherwise have
already exited on the first segment's summary).

--lines controls how much history is replayed before following (default
10; -1 replays everything; 0 replays nothing). --json prints one raw
event per line, as in `sonny trace events`; --fields keeps only the
named top-level keys (requires --json).

Examples:
  sonny trace tail
  sonny trace tail 862e2758
  sonny trace tail 0d6c4bf3 --session --stay
  sonny trace tail 862e2758 --no-follow --lines -1 --json

Usage:
  sonny trace tail [ref] [flags]

Flags:
      --errors              only events that record a failure
      --fields string       comma-separated top-level event keys to keep (requires --json)
      --grep string         only events whose JSON contains this text (case-insensitive)
  -h, --help                help for tail
      --interval duration   poll period while following (minimum 10ms) (default 250ms)
      --json                print one raw event per line instead of the text timeline
      --lines int           events of history to replay before following (-1 = all, 0 = none) (default 10)
      --no-follow           print the replay and exit instead of following
      --session             treat ref as a session and follow its newest segment
      --since string        only events at/after this time (RFC3339 or YYYY-MM-DD)
      --stay                keep following after the summary record (segments of a followed session can still resume)
      --tool string         only tool events for this tool (mcp tools as server/tool)
      --turn string         only these turns: N, N,M, or N-M
      --type stringArray    only events of this type (repeatable)
      --until string        only events at/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

List every tool invocation (native and MCP) with its result: file line
numbers of the call and the result, turn, latency, exit code, error or
weak-failure state, and the scheduler's parallel group. Calls that never
got a result show as unfinished. --full prints parameters and results;
--errors keeps only failed, weak, skipped, or unfinished calls.

Examples:
  sonny trace tools 862e2758
  sonny trace tools 862e2758 --tool run_command --full
  sonny trace tools 862e2758 --turn 3 --errors --json

Usage:
  sonny trace tools <ref> [flags]

Flags:
      --errors         only events that record a failure
      --full           print complete parameters and results
  -h, --help           help for tools
      --json           emit the machine-readable envelope
      --since string   only events at/after this time (RFC3339 or YYYY-MM-DD)
      --tool string    only tool events for this tool (mcp tools as server/tool)
      --turn string    only these turns: N, N,M, or N-M
      --until string   only events at/before this time (RFC3339 or YYYY-MM-DD)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
      --trace-dir string       directory holding conversation traces, read-only (default: <data-dir>/traces)
  -C, --workdir string         working directory (default ".")

Commands for turning sonny's conversation traces into training data.

The trace service collects conversation traces for training data aggregation.
It supports both server mode (receiving traces) and client mode (uploading
traces), plus offline export of traces already written to disk.

Note: `sonny canary` is a different, unrelated command -- the CANARY
requirement and gap traceability system.

Examples:
  # Start the trace aggregation server
  sonny training server --listen :50051 --storage-dir /var/lib/traces

  # Upload traces to a remote server
  sonny training upload ./traces/ --server traces.example.com:50051 --cert client.crt --key client.key --ca ca.crt

  # Export traces already on disk as training records
  sonny training export --out ./training.jsonl

Usage:
  sonny training [command]

Available Commands:
  collect     Collect conversations from local AI assistants into a redacted corpus JSONL
  dataset     Build train/test eval suites from a collected conversation corpus
  export      Export on-disk conversation traces to a training-data JSONL file
  server      Start the trace aggregation server
  upload      Upload traces to the aggregation server

Flags:
  -h, --help   help for training

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny training [command] --help" for more information about a command.

Collects from: aider, claude, codex, continue, copilot, cursor, gemini, sonny.
aider is excluded unless --include-aider (its collector walks all of $HOME).
Sessions containing credential-shaped text are dropped wholesale; emails, IPs,
and home paths are masked; tool/system turns are stripped.

Usage:
  sonny training collect [flags]

Flags:
  -h, --help               help for collect
      --include-aider      include the aider source (walks all of $HOME)
      --min-messages int   drop sessions with fewer messages (default 2)
      --out string         output corpus JSONL path
      --sources strings    sources to collect (default: all except aider)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Build train/test eval suites from a collected conversation corpus

Usage:
  sonny training dataset [flags]

Flags:
      --corpus sonny training collect   corpus JSONL (from sonny training collect)
  -h, --help                            help for dataset
      --limit int                       max windows harvested (default 125)
      --out-dir string                  output directory for train.suite.yaml/test.suite.yaml/split_manifest.json
      --rules string                    behavior-rules YAML (default: embedded starter set)
      --test-ratio float                fraction of parents routed to the holdout test suite (default 0.4)
      --turns int                       window size in turns (default 6)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Export conversation traces already written to disk into a training
JSONL file, without re-running them.

Each *.jsonl trace file under --trace-dir becomes at most one training
record -- never one per api_request event. Records are produced
through the same TrainingExporter path "sonny run"'s live training
export uses, so on-disk and live export always emit byte-identical
shapes and agree on conversation identity.

Export is fail closed: every exported user turn needs exactly one terminal
verified outcome with explicit consent, pinned redaction provenance, dataset
partition, and parent-group identity. Unknown, partial, model-only, missing,
duplicate, or unconsented outcomes are skipped. Because the outcome projection
must survive export, only openai_chat, openai_tools, sharegpt, sharegpt_tool,
and chatml are accepted.

The trace directory is treated strictly read-only: nothing under it is
ever created, modified, moved, or deleted.

Examples:
  # Export every trace under the default trace directory
  sonny training export --out training.jsonl

  # Export from an explicit directory
  sonny training export --trace-dir ./traces --out training.jsonl

  # Only traces started on/after a given time
  sonny training export --out training.jsonl --since 2026-07-01T00:00:00Z

  # Overwrite an existing output file
  sonny training export --out training.jsonl --force

Usage:
  sonny training export [flags]

Flags:
      --force              overwrite --out if it already exists
      --format string      metadata-bearing training format (openai_chat, openai_tools, sharegpt, sharegpt_tool, or chatml) (default "openai_chat")
  -h, --help               help for export
      --include-tools      include tool calls in the export
      --keep-errors        export traces whose summary shows failures, labeling them with failure metadata instead of dropping them
      --out string         output JSONL file (required)
      --since string       only export traces whose header start_time is on/after this RFC3339 timestamp
      --trace-dir string   directory to scan recursively for conversation trace files (read-only) (default "<owned-temp>/XDG_DATA_HOME/sonny/traces")

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Start a gRPC server that receives and stores conversation traces.

The server can use mTLS for authentication. When certificates are provided,
clients must present valid certificates signed by the configured CA.

Examples:
  # Start server with mTLS
  sonny training server \
    --listen :50051 \
    --storage-dir /var/lib/sonny/traces \
    --cert server.crt \
    --key server.key \
    --ca ca.crt

  # Start without TLS (development only)
  sonny training server --listen 127.0.0.1:50051 --storage-dir ./traces

Usage:
  sonny training server [flags]

Flags:
      --allowed-cn strings   allowed client certificate CNs (optional)
      --ca string            CA certificate for client verification
      --cert string          server certificate file
  -h, --help                 help for server
      --key string           server private key file
      --listen string        gRPC listen address (default "127.0.0.1:50051")
      --storage-dir string   directory for trace storage (required)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Upload trace files to a remote aggregation server.

Supports uploading individual files, directories, or glob patterns.
When uploading directories, all .json files are uploaded.

The upload process uses batching and retry logic for reliability.
Failed uploads are queued for retry with exponential backoff.

Examples:
  # Upload a single trace file
  sonny training upload ./traces/trace_abc123.json

  # Upload all traces from a directory
  sonny training upload ./traces/

  # Upload with mTLS authentication
  sonny training upload ./traces/ \
    --server traces.example.com:50051 \
    --cert client.crt \
    --key client.key \
    --ca ca.crt

  # Upload with custom batch size
  sonny training upload ./traces/ --batch-size 100 --workers 5

  # Watch directory and upload new traces automatically
  sonny training upload ./traces/ --watch

Usage:
  sonny training upload [paths...] [flags]

Flags:
      --batch-size int     number of traces per batch (default 50)
      --ca string          CA certificate for server verification
      --cert string        client certificate file
  -h, --help               help for upload
      --key string         client private key file
      --queue-dir string   directory for persistent upload queue (enables offline resilience)
      --server string      trace aggregation server address (default "localhost:50051")
      --timeout duration   upload timeout per batch (default 30s)
      --watch              watch directory for new traces and upload automatically
      --workers int        number of parallel upload workers (default 3)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage the Sonny application binary through threshold-signed metadata,
verified supply-chain evidence, and atomic health-checked activation.

This command is intentionally separate from "sonny recipe update": application
and prompt-pack updates have different trust roots and cannot update each
other. Update policy is read only from the dedicated per-user or managed
system policy file, never from project configuration or command-line trust
flags.

Usage:
  sonny update [command]

Available Commands:
  apply       Download, verify, and atomically activate an application update
  automatic   Run one policy-gated automatic application-update cycle
  check       Check signed metadata for an eligible application update
  policy      Show the effective application-update policy
  recover     Recover an interrupted application activation

Flags:
  -h, --help   help for update
      --json   emit a machine-readable sanitized result

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny update [command] --help" for more information about a command.

Download, verify, and atomically activate an application update

Usage:
  sonny update apply [flags]

Flags:
  -h, --help   help for apply

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --json                   emit a machine-readable sanitized result
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Run one policy-gated automatic application-update cycle

Usage:
  sonny update automatic [flags]

Flags:
  -h, --help   help for automatic

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --json                   emit a machine-readable sanitized result
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Check signed metadata for an eligible application update

Usage:
  sonny update check [flags]

Flags:
  -h, --help   help for check

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --json                   emit a machine-readable sanitized result
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the effective application-update policy

Usage:
  sonny update policy [flags]

Flags:
  -h, --help   help for policy

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --json                   emit a machine-readable sanitized result
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Recover an interrupted application activation

Usage:
  sonny update recover [flags]

Flags:
  -h, --help   help for recover

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --json                   emit a machine-readable sanitized result
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Install a verified, content-addressed variant bundle from the upstream registry into the local store, report what is installed and how fresh it is, and list the qualifications upstream drift invalidated.

Selection itself always runs locally against the installed snapshot: no subcommand here resolves a variant, and only sync and stale --upstream talk to a registry at all.

Usage:
  sonny variant [command]

Available Commands:
  stale       Report the qualifications one upstream change invalidates
  status      Report the installed bundle, its freshness and the store's lock
  sync        Install one verified variant bundle atomically

Flags:
  -h, --help   help for variant

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny variant [command] --help" for more information about a command.

Name what changed and this reports every (variant, target-profile) qualification cell it invalidates, including the extends descendants a shared ancestor drags with it.

The walk runs locally, over the ACTIVE bundle's discovered catalog and the target-profile catalog, through the same impact graph pack compilation uses. Which variants cover which profile revisions is decided by the resolver's own selector matcher, never by a name comparison. --upstream additionally reads the registry's staleness feed and seeds the walk with every cell it reports, so one upstream fact fans out into the local cells it really touches.

Usage:
  sonny variant stale <recipe-id> [flags]

Flags:
      --changed-fragment stringArray   a changed fragment, by its tier-qualified rel path (repeatable)
      --changed-profile stringArray    a changed target-profile revision, as <profile-id>@<revision> (repeatable)
      --changed-recipe stringArray     a changed base pack, by logical pack id (repeatable)
      --changed-variant stringArray    a changed variant, as <pack-id>/<variant-id>; reports its descendants (repeatable)
      --endpoint string                upstream registry base URL; never echoed in any output
  -h, --help                           help for stale
      --insecure-http                  allow a plain-http registry endpoint, and only when its host is loopback
      --json                           emit the machine-readable document
      --max-age-seconds int            refuse an installed snapshot older than this many seconds (0 leaves the age unbounded)
      --now-unix int                   clock to evaluate install time and expiry against, in seconds since the Unix epoch (0 uses the host clock)
      --profiles string                target-profile catalog file (default: the documented catalog search order)
      --require-revocation-check       treat an unchecked revocation feed as revoked instead of serving the installed snapshot with a stale marker
      --root string                    bundle store root (default <XDG data>/sonny/variant-bundles)
      --trusted-key stringArray        trust bundles signed by this Ed25519 public key, as <key-id>=<path to key file> (repeatable; base64, PEM or ssh-ed25519). A bundle whose manifest is not signed by a trusted key is refused
      --upstream                       also read the registry's staleness feed and seed the walk from it

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Report what the local store holds: the active bundle and when it was installed, every retained generation, the recorded revocation feed's revision and size, the snapshot's age against the configured cap, whether activation is blocked, and whether an install lock is held.

It reads only local state -- no registry is contacted and nothing is written -- and it never refuses: an expired, unchecked or revoked installation is reported as data, with exit status 0, because a command that refused to describe a broken installation would hide exactly what an operator called it to see.

Usage:
  sonny variant status [flags]

Flags:
  -h, --help                       help for status
      --json                       emit the machine-readable document
      --max-age-seconds int        refuse an installed snapshot older than this many seconds (0 leaves the age unbounded)
      --now-unix int               clock to evaluate install time and expiry against, in seconds since the Unix epoch (0 uses the host clock)
      --require-revocation-check   treat an unchecked revocation feed as revoked instead of serving the installed snapshot with a stale marker
      --root string                bundle store root (default <XDG data>/sonny/variant-bundles)
      --trusted-key stringArray    trust bundles signed by this Ed25519 public key, as <key-id>=<path to key file> (repeatable; base64, PEM or ssh-ed25519). A bundle whose manifest is not signed by a trusted key is refused

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Fetch one bundle from the configured registry, verify its manifest and every blob against the digests the manifest declares, verify the manifest's Ed25519 signature against the keys named with --trusted-key, install it atomically, and acknowledge to the registry what this node is now running.

The install is fail-closed: the revocation feed is consulted first, and a revoked bundle, a digest mismatch, an unsigned manifest or one not signed by a trusted key, an oversize asset, a short closure or a held install lock refuses before anything becomes active. It is idempotent: re-syncing the bundle that is already active installs nothing and says so. --dry-run writes nothing at all, on this host or at the registry.

Usage:
  sonny variant sync [flags]

Flags:
      --bundle string              bundle id to install (required)
      --channel string             channel this node follows (default "stable")
      --dry-run                    report what a sync would do and write nothing, here or at the registry
      --endpoint string            upstream registry base URL; never echoed in any output
  -h, --help                       help for sync
      --insecure-http              allow a plain-http registry endpoint, and only when its host is loopback
      --json                       emit the machine-readable document
      --manifest-digest string     refuse any manifest but this one (sha256:jcs1:<hex>)
      --max-age-seconds int        refuse an installed snapshot older than this many seconds (0 leaves the age unbounded)
      --namespace string           tenant namespace this node acknowledges into
      --node-id string             node identity reported in the acknowledgement
      --now-unix int               clock to evaluate install time and expiry against, in seconds since the Unix epoch (0 uses the host clock)
      --registry-name string       display name for the registry, the only registry identity the documents carry
      --require-revocation-check   treat an unchecked revocation feed as revoked instead of serving the installed snapshot with a stale marker
      --retain int                 bundle generations to keep, counting the active one (0 keeps the store default of 3)
      --root string                bundle store root (default <XDG data>/sonny/variant-bundles)
      --trusted-key stringArray    trust bundles signed by this Ed25519 public key, as <key-id>=<path to key file> (repeatable; base64, PEM or ssh-ed25519). A bundle whose manifest is not signed by a trusted key is refused

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Print version information, the license, the changelog, or SCA build info

Usage:
  sonny version [flags]

Flags:
      --changelog              print the CHANGELOG
  -h, --help                   help for version
      --license                print the full LICENSE text
      --sbom                   print the CycloneDX SBOM (JSON)
      --storage                print the source cache's storage runtime report (JSON)
      --third-party-licenses   print dependency licenses (CSV: module,url,spdx-id)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

A workspace -- a registered canonical directory -- gates its own executable
configuration (hooks, MCP servers, LSP sessions, subagent binaries,
command-form secrets, integrations, and project model catalogs) on
whether an operator has reviewed and trusted it. An unregistered or
untrusted workspace refuses all of these; see "Workspace trust" in
docs/config/precedence.md for the full gated-kinds table.

Usage:
  sonny workspace [command]

Available Commands:
  release-legacy-agent Release workspaces a built-in agent client registered before the upgrade
  status               Show the trust state of the workspace at path (default: the current directory)
  trust                Grant trust to the workspace at path (default: the current directory)
  untrust              Revoke trust for the workspace at path (default: the current directory)

Flags:
  -h, --help   help for workspace

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny workspace [command] --help" for more information about a command.

Since SONNY-4067 every agent-kind supervisor connection (no human-attach
proof) has a durable identity ending in "#agent". Workspaces a built-in
agent client registered before the upgrade stay owned by its old identity,
"<client_name>@<tenant>", so their folders refuse to be registered again.
This command lists and releases them for one of the built-in clients that
always connect as agents: sonny-mcp, sonny-editor-host,
sonny-supervisor-cli or sonny-mesh-peers-cli. Any other name is refused,
the desktop's and editor-rpc's included: a human connection holds that same
un-suffixed shape today.

Stop the supervisor first (--endpoint names it when it is not at the
default socket). The command refuses unless it runs at an interactive
terminal, and asks you to confirm the listed folders by typing "release".
It never transfers anything to another identity: a released folder starts
untrusted and unbound, and sessions the old identity created stay in the
journal.

Usage:
  sonny workspace release-legacy-agent [flags]

Flags:
      --client-name string   the built-in agent client: sonny-mcp, sonny-editor-host, sonny-supervisor-cli or sonny-mesh-peers-cli (required)
      --endpoint string      supervisor socket (unix) or pipe (windows) path (default: sockpath.Endpoint())
  -h, --help                 help for release-legacy-agent

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Show the trust state of the workspace at path (default: the current directory)

Usage:
  sonny workspace status [path] [flags]

Flags:
  -h, --help   help for status

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Grant trust to the workspace at path (default: the current directory).

Trust lets the workspace's own hooks, MCP servers, language servers and
other executable configuration run, so it is meant for the operator: the
command refuses unless stdin and stderr are an interactive terminal and no
agent-session marker is set, then asks you to confirm the resolved absolute
root by typing "trust". There is no flag that skips the confirmation. This
stops a plain agent or exec-tool call; it is not a hard boundary against a
process of your own user that allocates a pseudo-terminal (see the
human-attach ADR's residual risk). Revoking trust ("sonny workspace
untrust") is not gated.

Usage:
  sonny workspace trust [path] [flags]

Flags:
  -h, --help   help for trust

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Revoke trust for the workspace at path (default: the current directory).

Every grant you own for the workspace is revoked -- your own, and every one
the desktop app filed under your local profile -- so "sonny workspace status"
then reports it untrusted. The command names each grant it removed. Revoking
only narrows what runs, so it is not gated on an interactive terminal.

Usage:
  sonny workspace untrust [path] [flags]

Flags:
  -h, --help   help for untrust

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Manage the Git worktrees Sonny creates for delegated child agents

Usage:
  sonny worktrees [command]

Available Commands:
  prune       Remove child-agent worktrees that hold no work, and list the ones kept

Flags:
  -h, --help   help for worktrees

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")

Use "sonny worktrees [command] --help" for more information about a command.

prune removes each child-agent worktree of the checkout and its
sonny/child/<hash> branch whose work is provably empty: HEAD and branch still
at the commit the child started from, and nothing modified, staged or
untracked except Sonny's own regenerated .sonny/init-manifest.yaml and
.sonny/packs/generated/ files. Child worktrees live in the per-user cache
(<cache>/sonny/worktrees/<repo>-<hash>/<suffix>, or SONNY_CHILD_WORKTREE_DIR);
ones an older Sonny created next to the checkout as <repo>-sonny-<hash> are
pruned too.

A worktree is never removed while a live session holds its claim in the
control store (a running child, or an integration in progress), while it was
touched within --min-idle, or when it holds any commit or other change. Each
kept worktree is listed with the reason.

Usage:
  sonny worktrees prune [flags]

Flags:
      --control-db string   SQLite control database (default: SONNY_CONTROL_DB, then the data directory)
      --dir string          a directory inside the checkout to prune (default: the current directory)
      --dry-run             report what would be removed without removing anything
  -h, --help                help for prune
      --json                emit the report as JSON
      --min-idle duration   keep worktrees touched more recently than this (default 10m0s)

Global Flags:
      --analysis-json string   versioned analysis JSON patch; protected settings may only narrow (SONNY_ANALYSIS_JSON supplies the environment layer)
      --config string          config file (default: .sonny.yaml in working directory)
      --debug                  enable debug mode
      --log-format string      log format: text|json (default "text")
      --log-level string       log level: debug|info|warn|error (default "warn")
  -m, --model string           model to use (overrides pack default)
  -p, --provider string        LLM provider (openai, anthropic, ollama, etc.)
      --quiet-deprecations     suppress schema and legacy recipe-name deprecation warnings
  -C, --workdir string         working directory (default ".")