feat(schema): --schema on every command, plus response shapes

[dspangen]

--schema now works on every API command — GETs, DELETEs, and the hand-written ones included — and the emitted document gained a response section, so response shapes are no longer invisible. Previously --schema on a bodyless command was an unknown flag error (13 audited incidents), and nothing could tell you that e.g. models validate returns a bare array.

• Bodyless ops describe their positional args and queryParams, with an explicit "body": null.
• response shows the lowest declared 2xx schema (wildcard 2XX accepted), rendered with the same --depth handling as bodies.
• Body-op output is backward compatible — the new sections are additive.
• Still zero-friction: no args, no token, no network call.

Details: flag-collision policy, response capture rules, trade-offs, and verification

What changed

• --schema (and --field/--depth) on every generated command. Registration and the Args/RunE short-circuit moved into a shared openapi.RegisterSchemaFlag helper.
• Bodyless operations describe themselves. The document carries args (name, placeholder, type, description) and queryParams (flag, name, type, enum, required, description), and an explicit "body": null so "takes no body" is unambiguous rather than merely absent.
• response section for all operations. Captured in operationInfo and rendered through the existing describer.simplify, honoring --depth. A contentless status (e.g. 204) reports its status with a null schema.
• --field still drills the request body only — documented in the flag help, and it returns a clear error instead of silently doing nothing when the operation has no body schema.
• Hand-written commands too: models create-branch and users set-attributes emit the same document shape from a static description of the body the CLI assembles, so agent-help's "every API command" claim holds.
• omni agent-help documents the four sections and that --schema works everywhere.

Flag-collision policy

A spec parameter always keeps its own flag name — it is the operation's contract, and silently reinterpreting an endpoint's --depth query param as a discovery control would corrupt requests. When a parameter owns schema, field or depth, that discovery flag is registered under a deterministic fallback instead: --schema-doc, --schema-field, --schema-depth (and -2, -3… if those are taken too). The rename is announced in the flag's --help text ("named --schema-doc here because --schema is a parameter of this endpoint") and echoed in a schemaFlags section of the emitted document. Discovery is therefore never unavailable, only occasionally renamed. The current spec has no such collisions; the behavior is covered by a synthetic spec whose GET declares query params named schema, field and depth.

Response capture

The success response is the lowest declared 2xx status, falling back to an OpenAPI range key (2XX) when only that is declared — a specific code always beats the wildcard. Media-type selection prefers application/json with a schema, then the first type that carries a schema; a media type declared without a schema is still reported by name with a null schema, since "comes back as text/csv, shape undocumented" beats implying an empty response. requestBodySchema shares the same picker so request and response selection cannot drift.

Trade-off worth knowing

Response schemas make some documents large — documents v2-* now dumps ~165 KB at the default depth of 8, the same order as its request body already did. --depth N and --field PATH remain the way to narrow that, and agent-help points at them.

Verification

• make build && make test — all packages pass.
• New unit tests (including the review follow-ups: flag-name collisions, 2XX-only and 2XX-vs-specific responses, media types without a schema, and freeFlagName exhausting its fallbacks): --schema on a GET with path/query params (including required + enum), bare-array 200 response, contentless 204, --depth truncating the response, --field on a bodyless op erroring, body-op backward compatibility, --schema registered on every command generated from the real spec, --schema skipping arg validation, plus create-branch --schema / set-attributes --schema and their --field rejection.
• Swept the built binary: --schema --compact succeeds on all 210 API subcommands (the only non-accepting commands are completion and config, which make no API call); every operation reports a response section.
• Sanity: ./omni models list --schema, ./omni query run --schema, ./omni models validate --schema (previously an unknown-flag error).

🤖 Generated with Claude Code

https://claude.ai/code/session_014TwwKSAsAGPBToNb4iUe5s

[Copilot]

Pull request overview

Extends schema discovery across all API commands and adds response-shape metadata.

Changes:

• Registers collision-safe schema discovery flags on every generated command.
• Adds arguments, query parameters, request bodies, and success responses to schema output.
• Supports hand-written API commands and updates agent guidance and tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/openapi/schema.go	Expands schema documents and shared flag handling.
internal/openapi/schema_test.go	Tests responses, bodyless operations, and collisions.
internal/openapi/generate.go	Captures responses and registers schema flags globally.
internal/openapi/generate_test.go	Tests universal registration and validation bypass.
internal/openapi/body_shorthand.go	Adapts field resolution API.
internal/openapi/body_shorthand_test.go	Updates shorthand field checks.
cmd/omni/user_commands.go	Adds static schema output for set-attributes.
cmd/omni/user_commands_test.go	Tests set-attributes schema output.
cmd/omni/branch_commands.go	Adds static schema output for create-branch.
cmd/omni/branch_commands_test.go	Tests create-branch schema behavior.
cmd/omni/agent_help.go	Documents expanded schema discovery.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[n8agrin]

Some initial Claude findings:

Review complete for [PR #79](https://github.com/exploreomni/cli/pull/79) — 15 findings reported, ranked most severe first.

Top issues (confirmed correctness bugs):

--depth is a silent no-op on both hand-written commands — branch_commands.go:99 and user_commands.go:103. RegisterSchemaFlag registers --depth with help text promising it truncates nesting, but create-branch --schema and set-attributes --schema ignore it entirely (verified by building the binary and diffing --depth 0 vs --depth 8 output — byte-identical).
--schema output can be corrupted by cobra's deprecation notice — schema.go:132. On any deprecated command (3 exist today: documents put/update/transfer-ownership), --schema --compact 2>&1 prints a plain-text warning before the JSON, breaking the "clean JSON, no side content" contract for any caller that merges stdout/stderr.

Maintainability (confirmed): both hand-written commands' --schema docs are fully hand-transcribed copies of the real body-assembly code and the spec's response schema, with no shared source of truth and no test that would catch drift (branch_commands.go:109, user_commands.go:129). Also duplicated: a --field-rejection closure and str() helper across both files, and two near-identical test helpers in schema_test.go.

Efficiency: describeBody computes the (potentially ~165KB) response schema before validating --field, wasting that work whenever --field is invalid (schema.go:254).

Conventions: two new doc comments in schema.go (lines 48 and 92) exceed your global CLAUDE.md's "1–2 sentences, 3 max" rule for code comments.