@lovrozagar/honey 0.6.5 → 0.7.0

package/src/codegen-go-cli.ts

@@ -1,11 +1,11 @@
 /* Go CLI emitter — generates a complete cobra-based Go CLI module from an OpenAPI 3.1 spec.
  *
- * Mirrors the pattern used by codegen-go.ts:
+ *   - Input is the SDK request model (codegen-sdk-model.ts), shared with the Go SDK emitter.
  *   - Static runtime files (config.go, auth.go, output.go, errors.go, stream.go, multipart.go,
- *     version.go, root.go) are read from ./cli-go/ at module load time and copied verbatim
- *     into the output file map under "cli-go/<name>".
+ *     version.go, root.go) are read from ./cli-go/ and copied verbatim under "internal/cli/".
  *   - Per-resource cobra command files are emitted as cmd/<resource>.go.
- *   - main.go and cmd/root.go wire cobra + auth + exit-code mapping.
+ *   - URLs, query encoding, SSE parsing and status errors go through the SDK's exported
+ *     Honey* helpers, so the CLI sends exactly what the SDK sends.
  *
  * Two SDK wiring modes:
  *   - sdkModulePath set → go.mod emits `require` + `replace`; no internal/sdk/ files.
@@ -15,10 +15,13 @@
 
 import { readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
-import { generateGoSDK, safeResourceName } from "./codegen-go.ts"
-import { collectSDKMethods, extractOpenApiPathParams, isSSEOperation, resolveRefs } from "./codegen.ts"
-import { toIR } from "./codegen-ir.ts"
-import { goPascal } from "./go-type-emitter.ts"
+import type { OpenApiSpecInput } from "./codegen.ts"
+import { serviceMapOf } from "./codegen.ts"
+import { GO_KEYWORDS, GO_PREDECLARED, NameScope, cmpCodeUnit, goExported, goLocal, goString } from "./codegen-lang.ts"
+import type { IRInfo, IRParam, IRSchema } from "./codegen-ir.ts"
+import { buildSdkModel } from "./codegen-sdk-model.ts"
+import type { SdkModel, SdkOp } from "./codegen-sdk-model.ts"
+import { generateGoSDK } from "./codegen-go.ts"
 
 const DEFAULT_MODULE_PATH = "example.com/cli"
 
@@ -26,14 +29,6 @@ function resolveModulePath(options: GoCLIOptions): string {
 	return options.modulePath ?? DEFAULT_MODULE_PATH
 }
 
-function enumStrings(schema: Record<string, unknown>): string[] {
-	return Array.isArray(schema.enum) ? (schema.enum as unknown[]).map((v) => String(v)) : []
-}
-
-function isLastEventIdName(name: string): boolean {
-	return name === "last-event-id" || name === "last_event_id" || name === "lastEventId"
-}
-
 /* ── types ── */
 
 export type GoCLIOptions = {
@@ -52,66 +47,47 @@ export type GeneratedGoCLI = {
 	skippedOperations: string[]
 }
 
-type OpenApiSpec = {
-	components?: { schemas?: Record<string, Record<string, unknown>> }
-	info: { description?: string; title: string; version: string }
-	openapi: string
-	paths: Record<string, Record<string, Record<string, unknown>>>
-}
+type FlagKind = "string" | "int" | "float" | "bool" | "strings"
 
-type ParamInfo = {
+type Flag = {
+	/** Wire name of the param / property. */
 	name: string
 	flagName: string
 	varName: string
+	kind: FlagKind
 	required: boolean
-	schema: Record<string, unknown>
-	defaultValue: unknown
-	enumValues: string[]
-}
-
-type BodyScalarInfo = {
-	propName: string
-	flagName: string
-	varName: string
-	schemaType: string
 	enumValues: string[]
+	defaultValue: unknown
+	where: "path" | "query" | "header" | "body" | "file"
 }
 
 type BodyShape =
 	| { kind: "none" }
-	| { kind: "json-flat"; scalars: BodyScalarInfo[]; required: boolean }
-	| { kind: "json-complex"; required: boolean }
-	| {
-			kind: "multipart"
-			binaryFields: { name: string; required: boolean }[]
-			scalarFields: BodyScalarInfo[]
-			useGenericFileFlag: boolean
-	  }
+	| { kind: "json-flat"; scalars: Flag[]; required: boolean; dataVar: string }
+	| { kind: "json-complex"; required: boolean; dataVar: string }
+	| { kind: "form"; scalars: Flag[]; required: boolean }
+	| { kind: "multipart"; scalars: Flag[]; files: Flag[] }
+	| { kind: "raw"; contentType: string; required: boolean; dataVar: string }
 
 type CommandInfo = {
-	opId: string
-	resource: string
-	action: string /* joined-with-dash deeper-than-2 dot segments */
-	cmdVarName: string /* e.g. "usersGetCmd" */
-	cmdUse: string /* e.g. "get" */
-	method: string /* GET, POST, ... */
-	path: string
-	summary: string
-	description: string
-	pathParams: ParamInfo[]
-	queryParams: ParamInfo[]
+	op: SdkOp
+	cmdVarName: string
+	cmdUse: string
+	pathFlags: Flag[]
+	queryFlags: Flag[]
+	headerFlags: Flag[]
 	body: BodyShape
-	isSSE: boolean
-	hasLastEventId: boolean
-	has204: boolean
-	responseType: "json" | "none"
+	lastEventIdVar?: string
 }
 
 type ResourceGroup = {
-	resource: string /* raw resource e.g. "apiKey" */
-	cmdUse: string /* kebab e.g. "api-key" */
-	cmdVarBase: string /* Go var prefix e.g. "apiKey" or "type_" */
-	fileName: string /* e.g. "apiKey.go" (matches raw resource) */
+	resource: string
+	cmdUse: string
+	/** prefix for per-command var names */
+	cmdVarBase: string
+	/** the resource's own cobra.Command var */
+	groupVar: string
+	fileName: string
 	commands: CommandInfo[]
 }
 
@@ -123,13 +99,13 @@ export function toKebab(s: string): string {
 	return s
 		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
 		.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-		.replace(/[\s_]+/g, "-")
-		.replace(/-+/g, "-")
+		.replace(/[^A-Za-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
 		.toLowerCase()
 }
 
 export function toFlagName(paramName: string): string {
-	return toKebab(paramName)
+	return toKebab(paramName) || "value"
 }
 
 /** Upper snake case for env var: toSnakeUpper("project-id") → "PROJECT_ID". */
@@ -141,21 +117,6 @@ export function envVarFromFlag(flagName: string, envPrefix: string): string {
 	return `${envPrefix}_${toSnakeUpper(flagName)}`
 }
 
-/** Go var name from a param name: snake_case or kebab-case → camelCase with preserved acronyms.
- *  e.g. "project_id" → "projectID", "user-name" → "userName", "type" → "type_". */
-function goCamelVar(name: string): string {
-	const pascal = goPascal(name)
-	if (!pascal) return pascal
-	/* preserve acronym tail: "Id" → "ID", "Url" → "URL" */
-	const fixed = pascal
-		.replace(/\bId\b/g, "ID")
-		.replace(/\bUrl\b/g, "URL")
-		.replace(/Id$/, "ID")
-		.replace(/Url$/, "URL")
-	const camel = fixed.charAt(0).toLowerCase() + fixed.slice(1)
-	return safeResourceName(camel)
-}
-
 /* ── runtime template loader ── */
 
 let runtimeCache: Map<string, string> | null = null
@@ -179,260 +140,228 @@ export function loadGoCliRuntimeTemplates(): Map<string, string> {
 	return cache
 }
 
-/* ── param + body helpers ── */
-
-function getPathParams(op: Record<string, unknown>, rawPath: string): ParamInfo[] {
-	const declared = extractOpenApiPathParams(rawPath)
-	const byName = new Map<string, Record<string, unknown>>()
-	const parameters = (op.parameters as Array<Record<string, unknown>> | undefined) ?? []
-	for (const p of parameters) {
-		if (p.in !== "path") continue
-		byName.set(String(p.name), p)
-	}
-
-	const out: ParamInfo[] = []
-	for (const name of declared) {
-		const param = byName.get(name)
-		const schema = (param?.schema as Record<string, unknown>) ?? { type: "string" }
-		out.push({
-			defaultValue: schema.default,
-			enumValues: enumStrings(schema),
-			flagName: toFlagName(name),
-			name,
-			required: true,
-			schema,
-			varName: goCamelVar(name),
-		})
-	}
-	return out
+/* ── naming ── */
+
+/** Persistent flags on the root command, plus cobra's own. A command flag must not shadow them. */
+const GLOBAL_FLAGS = ["api-key", "base-url", "output", "verbose", "config", "timeout", "help", "version"]
+
+/** Identifiers every cmd/*.go file shares: imports and the package-level names root.go declares. */
+const CMD_PACKAGE_NAMES = [
+	...GO_KEYWORDS,
+	...GO_PREDECLARED,
+	"rootCmd",
+	"Execute",
+	"configFromCtx",
+	"configKey",
+	"runtimeConfig",
+	"EnvPrefix",
+	"ConfigName",
+	"DefaultBaseURL",
+	"AuthHeaderName",
+	"AuthHeaderPrefix",
+	"newHTTPClient",
+	"doJSON",
+	"init",
+]
+
+/** File stems Go treats specially, or that the generator writes itself. */
+const GOOS_GOARCH =
+	/_(aix|android|darwin|dragonfly|freebsd|hurd|illumos|ios|js|linux|nacl|netbsd|openbsd|plan9|solaris|wasip1|windows|zos|386|amd64|arm|arm64|loong64|mips|mipsle|mips64|mips64le|ppc64|ppc64le|riscv64|s390x|wasm|test)$/
+
+function resourceFileName(resource: string, taken: NameScope): string {
+	let stem = resource.replace(/[^A-Za-z0-9_-]/g, "_").replace(/^[-_.]+/, "")
+	if (stem === "" || /^(root|main|doc)$/i.test(stem) || GOOS_GOARCH.test(stem.toLowerCase())) stem = `res_${stem}`
+	return `${taken.claim(stem)}.go`
 }
 
-function getQueryParams(op: Record<string, unknown>): ParamInfo[] {
-	const parameters = (op.parameters as Array<Record<string, unknown>> | undefined) ?? []
-	const out: ParamInfo[] = []
-	for (const p of parameters) {
-		if (p.in !== "query") continue
-		const name = String(p.name)
-		const schema = (p.schema as Record<string, unknown>) ?? { type: "string" }
-		out.push({
-			defaultValue: schema.default,
-			enumValues: enumStrings(schema),
-			flagName: toFlagName(name),
-			name,
-			required: p.required === true,
-			schema,
-			varName: goCamelVar(name),
-		})
+function flagKind(schema: IRSchema, resolve: (s: IRSchema) => IRSchema): FlagKind {
+	let s = resolve(schema)
+	if (s.kind === "nullable") s = resolve(s.inner)
+	if (s.kind === "array") {
+		return "strings"
 	}
-	return out
-}
-
-function isScalarType(t: unknown): t is "string" | "integer" | "number" | "boolean" {
-	return t === "string" || t === "integer" || t === "number" || t === "boolean"
-}
-
-function detectBodyShape(op: Record<string, unknown>): BodyShape {
-	const requestBody = op.requestBody as Record<string, unknown> | undefined
-	if (!requestBody) return { kind: "none" }
-	const required = requestBody.required === true
-	const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-	if (!content) return { kind: "none" }
-
-	/* multipart wins over json */
-	const multipart = content["multipart/form-data"]
-	if (multipart) {
-		const schema = (multipart.schema as Record<string, unknown>) ?? {}
-		const props = (schema.properties as Record<string, Record<string, unknown>>) ?? {}
-		const reqList = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : [])
-		const binaryFields: { name: string; required: boolean }[] = []
-		const scalarFields: BodyScalarInfo[] = []
-		for (const [propName, propSchema] of Object.entries(props)) {
-			const type = propSchema.type
-			const format = propSchema.format
-			if (type === "string" && format === "binary") {
-				binaryFields.push({ name: propName, required: reqList.has(propName) })
-			} else if (isScalarType(type)) {
-				scalarFields.push({
-					enumValues: enumStrings(propSchema),
-					flagName: toFlagName(propName),
-					propName,
-					schemaType: String(type),
-					varName: goCamelVar(propName),
-				})
-			}
-		}
-		return {
-			binaryFields,
-			kind: "multipart",
-			scalarFields,
-			useGenericFileFlag: binaryFields.length === 1,
-		}
-	}
-
-	const jsonContent = content["application/json"]
-	if (!jsonContent) return { kind: "none" }
-	const schema = (jsonContent.schema as Record<string, unknown>) ?? {}
-
-	/* oneOf/anyOf/allOf, array-root, or non-object → complex */
-	if (schema.oneOf || schema.anyOf || schema.allOf) {
-		return { kind: "json-complex", required }
-	}
-	if (schema.type !== "object") {
-		return { kind: "json-complex", required }
+	if (s.kind === "scalar") {
+		if (s.type === "integer") return "int"
+		if (s.type === "number") return "float"
+		if (s.type === "boolean") return "bool"
 	}
+	if (s.kind === "const" && typeof s.value === "boolean") return "bool"
+	return "string"
+}
 
-	const props = (schema.properties as Record<string, Record<string, unknown>>) ?? {}
-	const scalars: BodyScalarInfo[] = []
-	let allScalar = true
-	for (const [propName, propSchema] of Object.entries(props)) {
-		if (!isScalarType(propSchema.type)) {
-			allScalar = false
-			break
-		}
-		scalars.push({
-			enumValues: enumStrings(propSchema),
-			flagName: toFlagName(propName),
-			propName,
-			schemaType: String(propSchema.type),
-			varName: goCamelVar(propName),
-		})
-	}
-	if (!allScalar) return { kind: "json-complex", required }
-	return { kind: "json-flat", required, scalars }
+function enumOf(schema: IRSchema, resolve: (s: IRSchema) => IRSchema): string[] {
+	let s = resolve(schema)
+	if (s.kind === "nullable") s = resolve(s.inner)
+	if (s.kind === "scalar" && s.enum) return s.enum.map(String)
+	return []
 }
 
-function has204Response(op: Record<string, unknown>): boolean {
-	const responses = op.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return false
-	return Object.prototype.hasOwnProperty.call(responses, "204")
+function isScalarSchema(schema: IRSchema, resolve: (s: IRSchema) => IRSchema): boolean {
+	let s = resolve(schema)
+	if (s.kind === "nullable") s = resolve(s.inner)
+	return s.kind === "scalar" || s.kind === "const"
 }
 
-function hasJsonResponse(op: Record<string, unknown>): boolean {
-	const responses = op.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return false
-	for (const [code, resp] of Object.entries(responses)) {
-		const n = Number.parseInt(code, 10)
-		if (n < 200 || n >= 300 || n === 204) continue
-		const content = resp.content as Record<string, Record<string, unknown>> | undefined
-		if (content?.["application/json"]) return true
+/** Go literal for a flag default, or the zero value. */
+function flagDefault(f: Flag): string {
+	const d = f.defaultValue
+	switch (f.kind) {
+		case "int":
+			return typeof d === "number" && Number.isInteger(d) ? String(d) : "0"
+		case "float":
+			return typeof d === "number" && Number.isFinite(d) ? String(d) : "0"
+		case "bool":
+			return d === true ? "true" : "false"
+		case "strings":
+			return Array.isArray(d) ? `[]string{${d.map((x) => goString(String(x))).join(", ")}}` : "nil"
+		default:
+			return typeof d === "string" ? goString(d) : `""`
 	}
-	return false
 }
 
 /* ── command collection ── */
 
-function collectCLIMethods(spec: Record<string, unknown>): {
-	groups: Map<string, ResourceGroup>
-	skipped: string[]
-	serviceMap: Record<string, Record<string, unknown>>
-} {
-	toIR(spec as Parameters<typeof toIR>[0])
-	const { serviceMap } = collectSDKMethods(spec as Parameters<typeof collectSDKMethods>[0])
-	const resolved = resolveRefs(spec as Parameters<typeof resolveRefs>[0]) as unknown as OpenApiSpec
-
+function collectCLIMethods(model: SdkModel, pkg: NameScope): { groups: Map<string, ResourceGroup>; skipped: string[] } {
 	const groups = new Map<string, ResourceGroup>()
 	const skipped: string[] = []
 	const seenCmdPaths = new Map<string, string>()
+	const fileNames = new NameScope(["root", "main"], (n) => n.toLowerCase())
+	const { resolve } = model
 
-	for (const [rawPath, pathMethods] of Object.entries(resolved.paths ?? {})) {
-		for (const [method, operation] of Object.entries(pathMethods)) {
-			const op = operation as Record<string, unknown>
-			const operationId = op.operationId as string | undefined
-			if (!operationId) continue
+	for (const op of model.ops) {
+		if (op.stream === "ws" || op.stream === "realtime") {
+			skipped.push(op.id)
+			continue
+		}
 
-			if (op["x-websocket"] === true) {
-				skipped.push(operationId)
-				continue
+		const segments = op.segments
+		const resource = segments[0] ?? op.id
+		/* Top-level ops (single segment) become `<resource> call` — cobra rejects leading dashes. */
+		const actionSegments = segments.length === 1 ? ["call"] : segments.slice(1).map((seg) => toKebab(seg))
+		const cmdUse = actionSegments.join("-")
+
+		/* collision check: (resource, cmdUse) must be unique */
+		const key = `${resource}|${cmdUse}`
+		const prior = seenCmdPaths.get(key)
+		if (prior !== undefined) {
+			throw new Error(
+				`go-cli codegen: command path collision for ${resource} ${cmdUse} — operations: ${prior}, ${op.id}`,
+			)
+		}
+		seenCmdPaths.set(key, op.id)
+
+		let group = groups.get(resource)
+		if (!group) {
+			const cmdVarBase = goLocal(resource)
+			group = {
+				cmdUse: toKebab(resource) || "resource",
+				cmdVarBase,
+				groupVar: pkg.claim(`${cmdVarBase}Cmd`),
+				commands: [],
+				fileName: resourceFileName(resource, fileNames),
+				resource,
 			}
+			groups.set(resource, group)
+		}
 
-			const segments = operationId.split(".")
-			const resource = segments[0]
-			/* Top-level ops (single segment) are conventionally marked `_call` in the
-			 * SDK IR. For the CLI tree we use "call" so the emitted subcommand is
-			 * `<resource> call` — cobra rejects leading dashes. */
-			const actionSegments = segments.length === 1 ? ["call"] : segments.slice(1).map((seg) => toKebab(seg))
-			const action = actionSegments.join("-")
-			const cmdUse = action
-
-			/* collision check: (resource, cmdUse) must be unique */
-			const key = `${resource}|${cmdUse}`
-			if (seenCmdPaths.has(key)) {
-				throw new Error(
-					`go-cli codegen: command path collision for ${resource} ${cmdUse} — operations: ${seenCmdPaths.get(key)}, ${operationId}`,
-				)
+		const cmdVarName = pkg.claim(`${group.cmdVarBase}${goExported(cmdUse)}Cmd`)
+		const flagScope = new NameScope(GLOBAL_FLAGS)
+		const varFor = (flag: string) => pkg.claim(`${cmdVarName}${goExported(flag)}Var`)
+		const claimFlag = (name: string, prefix: string): string => {
+			const base = toFlagName(name)
+			return flagScope.has(base) ? flagScope.claim(`${prefix}-${base}`) : flagScope.claim(base)
+		}
+		const mkFlag = (p: IRParam, where: Flag["where"], prefix: string): Flag => {
+			const flagName = claimFlag(p.name, prefix)
+			return {
+				defaultValue: where === "query" || where === "header" ? p.default : undefined,
+				enumValues: enumOf(p.schema, resolve),
+				flagName,
+				kind: flagKind(p.schema, resolve),
+				name: p.name,
+				required: where === "path" || p.required === true,
+				varName: varFor(flagName),
+				where,
 			}
-			seenCmdPaths.set(key, operationId)
-
-			let group = groups.get(resource)
-			if (!group) {
-				group = {
-					cmdUse: toKebab(resource),
-					cmdVarBase: safeResourceName(resource.charAt(0).toLowerCase() + resource.slice(1)),
-					commands: [],
-					fileName: `${resource}.go`,
-					resource,
+		}
+
+		/* path flags claim first: a path param keeps its plain flag name */
+		const pathFlags = op.pathParams.map((p) => ({ ...mkFlag(p, "path", "path"), kind: "string" as const }))
+		const queryFlags: Flag[] = []
+		let lastEventIdVar: string | undefined
+		for (const q of op.query) {
+			if (op.stream === "sse" && /^last[-_]?event[-_]?id$/i.test(q.name)) continue
+			queryFlags.push(mkFlag(q, "query", "query"))
+		}
+		const headerFlags = op.headers.map((h) => mkFlag(h, "header", "header"))
+		if (op.stream === "sse") {
+			const flagName = flagScope.claim("last-event-id")
+			lastEventIdVar = varFor(flagName)
+		}
+
+		let body: BodyShape = { kind: "none" }
+		const b = op.body
+		if (b) {
+			const scalarFlags = (schema: IRSchema): Flag[] | null => {
+				const s = resolve(schema)
+				if (s.kind !== "object") return null
+				const out: Flag[] = []
+				for (const f of s.fields) {
+					if (!isScalarSchema(f.schema, resolve)) return null
+					out.push(mkFlag({ name: f.name, required: false, schema: f.schema }, "body", "body"))
 				}
-				groups.set(resource, group)
+				return out
 			}
-
-			const pathParams = getPathParams(op, rawPath)
-			const queryParams = getQueryParams(op)
-			const body = detectBodyShape(op)
-			const sse = isSSEOperation(op)
-			const hasLastEventId = queryParams.some((q) => isLastEventIdName(q.name))
-
-			/* body rename: if a body scalar conflicts with a path param, rename flag to "body-<name>" */
-			if (body.kind === "json-flat") {
-				const pathNames = new Set(pathParams.map((p) => p.flagName))
-				body.scalars = body.scalars.map((s) => {
-					if (pathNames.has(s.flagName)) {
-						return { ...s, flagName: `body-${s.flagName}`, varName: `body${goPascal(s.propName)}` }
+			if (b.kind === "json") {
+				const dataFlag = flagScope.claim("data")
+				const dataVar = varFor(dataFlag)
+				const scalars = scalarFlags(b.schema)
+				body = scalars
+					? { dataVar, kind: "json-flat", required: b.required, scalars }
+					: { dataVar, kind: "json-complex", required: b.required }
+			} else if (b.kind === "form") {
+				body = { kind: "form", required: b.required, scalars: scalarFlags(b.schema) ?? [] }
+			} else if (b.kind === "multipart") {
+				const scalars: Flag[] = []
+				const files: Flag[] = []
+				const fileParts = b.parts.filter((p) => p.type === "file")
+				for (const part of b.parts) {
+					if (part.type === "file") {
+						const flagName = fileParts.length === 1 ? flagScope.claim("file") : claimFlag(part.name, "file")
+						files.push({
+							defaultValue: undefined,
+							enumValues: [],
+							flagName,
+							kind: "string",
+							name: part.name,
+							required: fileParts.length === 1 && b.required,
+							varName: varFor(flagName),
+							where: "file",
+						})
+					} else if (part.schema && isScalarSchema(part.schema, resolve)) {
+						scalars.push(mkFlag({ name: part.name, required: false, schema: part.schema }, "body", "body"))
 					}
-					return s
-				})
-			}
-
-			/* query rename: cobra reserves --help, --version */
-			for (const q of queryParams) {
-				if (q.flagName === "help" || q.flagName === "version") {
-					q.flagName = `query-${q.flagName}`
 				}
+				body = { files, kind: "multipart", scalars }
+			} else {
+				const dataFlag = flagScope.claim("data")
+				body = { contentType: b.contentType, dataVar: varFor(dataFlag), kind: "raw", required: b.required }
 			}
-
-			const actionPascal = goPascal(action)
-			const cmdVarName = `${group.cmdVarBase}${actionPascal}Cmd`
-			const has204 = has204Response(op)
-			const hasJson = hasJsonResponse(op)
-			let responseType: "json" | "none" = "none"
-			if (!sse && hasJson) responseType = "json"
-
-			group.commands.push({
-				action,
-				body,
-				cmdUse,
-				cmdVarName,
-				description: String(op.description ?? ""),
-				has204,
-				hasLastEventId,
-				isSSE: sse,
-				method: method.toUpperCase(),
-				opId: operationId,
-				path: rawPath,
-				pathParams,
-				queryParams,
-				resource,
-				responseType,
-				summary: String(op.summary ?? ""),
-			})
 		}
+
+		group.commands.push({ body, cmdUse, cmdVarName, headerFlags, lastEventIdVar, op, pathFlags, queryFlags })
 	}
 
-	return { groups, serviceMap: serviceMap as Record<string, Record<string, unknown>>, skipped }
+	return { groups, skipped }
 }
 
 /* ── emit: cmd/root.go ── */
 
-function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
+function emitRootFile(
+	groups: ResourceGroup[],
+	options: GoCLIOptions,
+	auth: { headerName: string; prefix: string },
+): string {
 	const envPrefix = options.envPrefix ?? toSnakeUpper(options.binaryName)
 	const configName = options.configName ?? options.binaryName
 	const defaultBase = options.defaultBaseURL ?? ""
@@ -444,24 +373,27 @@ function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
 	l.push(`import (`)
 	l.push(`\t"context"`)
 	l.push(`\t"fmt"`)
-	l.push(`\t"os"`)
+	l.push(`\t"net/http"`)
+	l.push(`\t"time"`)
 	l.push(``)
 	l.push(`\t"github.com/spf13/cobra"`)
 	l.push(``)
-	l.push(`\tcli "${cliImportPath(options)}"`)
+	l.push(`\tcli ${goString(cliImportPath(options))}`)
 	l.push(`)`)
 	l.push(``)
-	l.push(`var _ = fmt.Sprintf`)
-	l.push(`var _ = os.Exit`)
-	l.push(``)
 	l.push(`// EnvPrefix is the prefix used for all <PREFIX>_<FLAG> environment variables.`)
-	l.push(`const EnvPrefix = ${JSON.stringify(envPrefix)}`)
+	l.push(`const EnvPrefix = ${goString(envPrefix)}`)
 	l.push(``)
 	l.push(`// ConfigName is the directory name under $XDG_CONFIG_HOME / ~/.config for the config file.`)
-	l.push(`const ConfigName = ${JSON.stringify(configName)}`)
+	l.push(`const ConfigName = ${goString(configName)}`)
 	l.push(``)
 	l.push(`// DefaultBaseURL is used when neither --base-url, env var, nor the config file provide one.`)
-	l.push(`const DefaultBaseURL = ${JSON.stringify(defaultBase)}`)
+	l.push(`const DefaultBaseURL = ${goString(defaultBase)}`)
+	l.push(``)
+	l.push(`// AuthHeaderName and AuthHeaderPrefix come from the API's security scheme.`)
+	l.push(`const AuthHeaderName = ${goString(auth.headerName)}`)
+	l.push(``)
+	l.push(`const AuthHeaderPrefix = ${goString(auth.prefix)}`)
 	l.push(``)
 	l.push(`type configKey struct{}`)
 	l.push(``)
@@ -470,13 +402,27 @@ function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
 	l.push(`\tCfg cli.Config`)
 	l.push(`}`)
 	l.push(``)
-	l.push(`// rootCmd is the top-level cobra command for the ${options.binaryName} CLI.`)
+	l.push(`// started is set once flags, args and required flags are valid; any error`)
+	l.push(`// before that is a usage error (exit 4), whatever cobra calls it.`)
+	l.push(`var started bool`)
+	l.push(``)
+	l.push(`// rootCmd is the top-level cobra command for the CLI.`)
 	l.push(`var rootCmd = &cobra.Command{`)
-	l.push(`\tUse:     ${JSON.stringify(options.binaryName)},`)
-	l.push(`\tShort:   ${JSON.stringify(options.description ?? `${options.binaryName} CLI`)},`)
+	l.push(`\tUse:     ${goString(options.binaryName)},`)
+	l.push(`\tShort:   ${goString(options.description ?? `${options.binaryName} CLI`)},`)
 	l.push(`\tVersion: cli.Version,`)
 	l.push(`\tSilenceUsage: true,`)
+	l.push(`\tSilenceErrors: true,`)
 	l.push(`\tPersistentPreRunE: func(cmd *cobra.Command, args []string) error {`)
+	l.push(`\t\t/* cobra checks required flags only after this hook, so a missing one would`)
+	l.push(`\t\t   surface as a generic error (exit 3): check them here, as usage errors */`)
+	l.push(`\t\tif err := cmd.ValidateRequiredFlags(); err != nil {`)
+	l.push(`\t\t\treturn cli.Usage(err)`)
+	l.push(`\t\t}`)
+	l.push(`\t\tif err := cmd.ValidateFlagGroups(); err != nil {`)
+	l.push(`\t\t\treturn cli.Usage(err)`)
+	l.push(`\t\t}`)
+	l.push(`\t\tstarted = true`)
 	l.push(`\t\tcfg, err := cli.LoadConfig(cmd.Flags(), EnvPrefix, ConfigName)`)
 	l.push(`\t\tif err != nil {`)
 	l.push(`\t\t\treturn err`)
@@ -484,6 +430,9 @@ function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
 	l.push(`\t\tif cfg.BaseURL == "" {`)
 	l.push(`\t\t\tcfg.BaseURL = DefaultBaseURL`)
 	l.push(`\t\t}`)
+	l.push(`\t\tif _, err := time.ParseDuration(cfg.Timeout); err != nil {`)
+	l.push(`\t\t\treturn cli.Usage(err)`)
+	l.push(`\t\t}`)
 	l.push(`\t\tctx := context.WithValue(cmd.Context(), configKey{}, runtimeConfig{Cfg: cfg})`)
 	l.push(`\t\tcmd.SetContext(ctx)`)
 	l.push(`\t\treturn nil`)
@@ -492,7 +441,20 @@ function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
 	l.push(``)
 	l.push(`// Execute runs the root command.`)
 	l.push(`func Execute() error {`)
-	l.push(`\treturn rootCmd.Execute()`)
+	l.push(`\terr := rootCmd.Execute()`)
+	l.push(`\tif err != nil && !started {`)
+	l.push(`\t\treturn cli.Usage(err)`)
+	l.push(`\t}`)
+	l.push(`\treturn err`)
+	l.push(`}`)
+	l.push(``)
+	l.push(`// groupRun shows a bare group's help and rejects an unknown subcommand as a`)
+	l.push(`// usage error (cobra would print help and exit 0).`)
+	l.push(`func groupRun(cmd *cobra.Command, args []string) error {`)
+	l.push(`\tif len(args) > 0 {`)
+	l.push(`\t\treturn cli.Usage(fmt.Errorf("unknown command %q for %q", args[0], cmd.CommandPath()))`)
+	l.push(`\t}`)
+	l.push(`\treturn cmd.Help()`)
 	l.push(`}`)
 	l.push(``)
 	l.push(`func configFromCtx(ctx context.Context) cli.Config {`)
@@ -502,17 +464,35 @@ function emitRootFile(groups: ResourceGroup[], options: GoCLIOptions): string {
 	l.push(`\treturn cli.Config{}`)
 	l.push(`}`)
 	l.push(``)
+	l.push(`// newHTTPClient returns a client without an overall timeout: regular calls`)
+	l.push(`// bound themselves with --timeout, streams and uploads do not.`)
+	l.push(`func newHTTPClient() *http.Client {`)
+	l.push(`\treturn &http.Client{`)
+	l.push(`\t\tCheckRedirect: func(req *http.Request, via []*http.Request) error {`)
+	l.push(`\t\t\t/* never forward the API key to another host */`)
+	l.push(`\t\t\tif len(via) >= 10 || req.URL.Host != via[0].URL.Host || req.URL.Scheme != via[0].URL.Scheme {`)
+	l.push(`\t\t\t\treturn http.ErrUseLastResponse`)
+	l.push(`\t\t\t}`)
+	l.push(`\t\t\treturn nil`)
+	l.push(`\t\t},`)
+	l.push(`\t}`)
+	l.push(`}`)
+	l.push(``)
 	l.push(`func init() {`)
-	l.push(`\trootCmd.PersistentFlags().String("api-key", "", "API key (overrides env + config file)")`)
+	l.push(
+		`\trootCmd.PersistentFlags().String("api-key", "", "API key (overrides env + config file; visible to other local users in the process list, prefer the env var)")`,
+	)
 	l.push(`\trootCmd.PersistentFlags().String("base-url", "", "Override API base URL")`)
 	l.push(`\trootCmd.PersistentFlags().String("output", "json", "Output mode: json|ndjson|yaml|table")`)
 	l.push(`\trootCmd.PersistentFlags().Bool("verbose", false, "Print request metadata to stderr")`)
 	l.push(`\trootCmd.PersistentFlags().String("config", "", "Path to config file")`)
-	l.push(`\trootCmd.PersistentFlags().String("timeout", "30s", "Request timeout (Go duration)")`)
-	for (const g of groups) {
-		const cmdVar = `${g.cmdVarBase}Cmd`
-		l.push(`\trootCmd.AddCommand(${cmdVar})`)
-	}
+	l.push(
+		`\trootCmd.PersistentFlags().String("timeout", "30s", "Request timeout (Go duration); streams are not bounded")`,
+	)
+	l.push(`\trootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {`)
+	l.push(`\t\treturn cli.Usage(err)`)
+	l.push(`\t})`)
+	for (const g of groups) l.push(`\trootCmd.AddCommand(${g.groupVar})`)
 	l.push(`}`)
 	l.push(``)
 	return l.join("\n")
@@ -530,114 +510,101 @@ function sdkImportPath(options: GoCLIOptions): string {
 /* ── emit: cmd/<resource>.go ── */
 
 function emitResourceFile(group: ResourceGroup, options: GoCLIOptions): string {
+	const body: string[] = []
+
+	const resShort = group.commands[0]?.op.summary || `${group.cmdUse} commands`
+	body.push(`var ${group.groupVar} = &cobra.Command{`)
+	body.push(`\tUse:   ${goString(group.cmdUse)},`)
+	body.push(`\tShort: ${goString(firstLine(resShort))},`)
+	body.push(`\tArgs:  cobra.ArbitraryArgs,`)
+	body.push(`\tRunE:  groupRun,`)
+	body.push(`}`)
+	body.push(``)
+
+	for (const cmd of group.commands) emitCommand(body, cmd)
+
+	/* init() wires subcommands + registers their flags */
+	body.push(`func init() {`)
+	for (const cmd of group.commands) body.push(`\t${group.groupVar}.AddCommand(${cmd.cmdVarName})`)
+	for (const cmd of group.commands) emitFlagRegistrations(body, cmd)
+	body.push(`}`)
+	body.push(``)
+
+	const src = body.join("\n")
+	const imports: string[] = []
+	const uses = (re: RegExp) => re.test(src)
+	if (uses(/\bcontext\./)) imports.push("context")
+	if (uses(/\bbytes\./)) imports.push("bytes")
+	if (uses(/\bjson\./)) imports.push("encoding/json")
+	if (uses(/\berrors\./)) imports.push("errors")
+	if (uses(/\bfmt\./)) imports.push("fmt")
+	if (uses(/\bio\./)) imports.push("io")
+	if (uses(/\bhttp\./)) imports.push("net/http")
+	if (uses(/\burl\./)) imports.push("net/url")
+	if (uses(/\bos\./)) imports.push("os")
+	if (uses(/\bslices\./)) imports.push("slices")
+	if (uses(/\bstrconv\./)) imports.push("strconv")
+	if (uses(/\bstrings\./)) imports.push("strings")
+	if (uses(/\btime\./)) imports.push("time")
+
 	const l: string[] = []
-	const hasSSE = group.commands.some((c) => c.isSSE)
 	l.push(`// Code generated by honey. DO NOT EDIT.`)
 	l.push(`package cmd`)
 	l.push(``)
 	l.push(`import (`)
-	l.push(`\t"bytes"`)
-	l.push(`\t"context"`)
-	l.push(`\t"encoding/json"`)
-	l.push(`\t"fmt"`)
-	l.push(`\t"io"`)
-	if (hasSSE) l.push(`\t"iter"`)
-	l.push(`\t"net/http"`)
-	l.push(`\t"net/url"`)
-	l.push(`\t"os"`)
-	l.push(`\t"slices"`)
-	l.push(`\t"strings"`)
-	l.push(`\t"time"`)
+	for (const p of imports.sort(cmpCodeUnit)) l.push(`\t"${p}"`)
 	l.push(``)
 	l.push(`\t"github.com/spf13/cobra"`)
 	l.push(``)
-	l.push(`\tcli "${cliImportPath(options)}"`)
-	l.push(`\tsdk "${sdkImportPath(options)}"`)
+	l.push(`\tcli ${goString(cliImportPath(options))}`)
+	if (uses(/\bsdk\./)) l.push(`\tsdk ${goString(sdkImportPath(options))}`)
 	l.push(`)`)
 	l.push(``)
-	l.push(`var _ = bytes.NewReader`)
-	l.push(`var _ = context.TODO`)
-	l.push(`var _ = json.Marshal`)
-	l.push(`var _ = fmt.Sprintf`)
-	l.push(`var _ = io.Discard`)
-	l.push(`var _ = http.MethodGet`)
-	l.push(`var _ = url.PathEscape`)
-	l.push(`var _ = os.Stdout`)
-	l.push(`var _ = slices.Contains[[]string]`)
-	l.push(`var _ = strings.NewReader`)
-	l.push(`var _ = time.Second`)
-	l.push(`var _ = sdk.SSEEvent{}`)
-	l.push(`var _ = cli.Version`)
-	if (hasSSE) l.push(`var _ iter.Seq2[cli.SSEEvent, error]`)
-	l.push(``)
+	l.push(src)
+	return l.join("\n")
+}
 
-	/* resource-level var */
-	const resShort = group.commands[0]?.summary ?? `${group.cmdUse} commands`
-	l.push(`var ${group.cmdVarBase}Cmd = &cobra.Command{`)
-	l.push(`\tUse:   ${JSON.stringify(group.cmdUse)},`)
-	l.push(`\tShort: ${JSON.stringify(resShort)},`)
-	l.push(`}`)
-	l.push(``)
+function firstLine(s: string): string {
+	return s.split(/\r\n|\r|\n/)[0] ?? ""
+}
 
-	/* per-command vars */
-	for (const cmd of group.commands) {
-		emitCommand(l, group, cmd, options)
-	}
+function allFlags(cmd: CommandInfo): Flag[] {
+	const out = [...cmd.pathFlags, ...cmd.queryFlags, ...cmd.headerFlags]
+	if (cmd.body.kind === "json-flat" || cmd.body.kind === "form") out.push(...cmd.body.scalars)
+	if (cmd.body.kind === "multipart") out.push(...cmd.body.scalars, ...cmd.body.files)
+	return out
+}
 
-	/* init() wires subcommands + registers their flags */
-	l.push(`func init() {`)
-	for (const cmd of group.commands) {
-		l.push(`\t${group.cmdVarBase}Cmd.AddCommand(${cmd.cmdVarName})`)
-	}
-	for (const cmd of group.commands) {
-		emitFlagRegistrations(l, cmd)
+function goVarType(kind: FlagKind): string {
+	switch (kind) {
+		case "int":
+			return "int64"
+		case "float":
+			return "float64"
+		case "bool":
+			return "bool"
+		case "strings":
+			return "[]string"
+		default:
+			return "string"
 	}
-	l.push(`}`)
-	l.push(``)
-
-	return l.join("\n")
 }
 
 /** Emits var declarations for every flag-backing Go variable + the cobra.Command literal. */
-function emitCommand(l: string[], group: ResourceGroup, cmd: CommandInfo, options: GoCLIOptions): void {
-	/* flag-backing vars */
-	for (const p of cmd.pathParams) {
-		l.push(`var ${cmd.cmdVarName}${goPascal(p.name)}Var string`)
-	}
-	for (const q of cmd.queryParams) {
-		l.push(`var ${cmd.cmdVarName}${goPascal(q.name)}Var ${goFlagVarType(q)}`)
-	}
-	if (cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex") {
-		l.push(`var ${cmd.cmdVarName}DataVar string`)
-	}
-	if (cmd.body.kind === "json-flat") {
-		for (const s of cmd.body.scalars) {
-			l.push(`var ${cmd.cmdVarName}${goPascal(s.propName)}Var ${goScalarVarType(s.schemaType)}`)
-		}
-	}
-	if (cmd.body.kind === "multipart") {
-		for (const s of cmd.body.scalarFields) {
-			l.push(`var ${cmd.cmdVarName}${goPascal(s.propName)}Var ${goScalarVarType(s.schemaType)}`)
-		}
-		if (cmd.body.useGenericFileFlag) {
-			l.push(`var ${cmd.cmdVarName}FileVar string`)
-		} else {
-			for (const f of cmd.body.binaryFields) {
-				l.push(`var ${cmd.cmdVarName}${goPascal(f.name)}Var string`)
-			}
-		}
-	}
-	if (cmd.hasLastEventId) {
-		l.push(`var ${cmd.cmdVarName}LastEventIDVar string`)
+function emitCommand(l: string[], cmd: CommandInfo): void {
+	for (const f of allFlags(cmd)) l.push(`var ${f.varName} ${goVarType(f.kind)}`)
+	if (cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex" || cmd.body.kind === "raw") {
+		l.push(`var ${cmd.body.dataVar} string`)
 	}
+	if (cmd.lastEventIdVar) l.push(`var ${cmd.lastEventIdVar} string`)
 	l.push(``)
 
-	const shortDesc = cmd.summary || cmd.action
+	const shortDesc = firstLine(cmd.op.summary) || cmd.cmdUse
 	l.push(`var ${cmd.cmdVarName} = &cobra.Command{`)
-	l.push(`\tUse:   ${JSON.stringify(cmd.cmdUse)},`)
-	l.push(`\tShort: ${JSON.stringify(shortDesc)},`)
+	l.push(`\tUse:   ${goString(cmd.cmdUse)},`)
+	l.push(`\tShort: ${goString(shortDesc)},`)
+	if (cmd.op.description) l.push(`\tLong:  ${goString(cmd.op.description)},`)
 
-	/* PreRunE: validate required body + enums */
 	const preRunELines = emitPreRunE(cmd)
 	if (preRunELines.length > 0) {
 		l.push(`\tPreRunE: func(cmd *cobra.Command, args []string) error {`)
@@ -647,285 +614,251 @@ function emitCommand(l: string[], group: ResourceGroup, cmd: CommandInfo, option
 	}
 
 	l.push(`\tRunE: func(cmd *cobra.Command, args []string) error {`)
-	emitRunE(l, cmd, options)
+	emitRunE(l, cmd)
 	l.push(`\t},`)
 	l.push(`}`)
 	l.push(``)
 }
 
-function goFlagVarType(q: ParamInfo): string {
-	const t = q.schema.type
-	if (t === "integer") return "int64"
-	if (t === "number") return "float64"
-	if (t === "boolean") return "bool"
-	if (t === "array") return "[]string"
-	return "string"
-}
-
-function goScalarVarType(t: string): string {
-	if (t === "integer") return "int64"
-	if (t === "number") return "float64"
-	if (t === "boolean") return "bool"
-	return "string"
-}
-
 function emitFlagRegistrations(l: string[], cmd: CommandInfo): void {
-	for (const p of cmd.pathParams) {
-		const v = `${cmd.cmdVarName}${goPascal(p.name)}Var`
-		/* flag docstring references original param name for discoverability */
-		l.push(`\t/* Path flag — Use: ${JSON.stringify(p.name)} */`)
-		l.push(
-			`\t${cmd.cmdVarName}.Flags().StringVar(&${v}, ${JSON.stringify(p.flagName)}, "", ${JSON.stringify(`Path parameter ${p.name}`)})`,
-		)
-		l.push(`\t${cmd.cmdVarName}.MarkFlagRequired(${JSON.stringify(p.flagName)})`)
-	}
-	for (const q of cmd.queryParams) {
-		if (isLastEventIdName(q.name)) continue
-		emitQueryFlag(l, cmd, q)
-	}
-	if (cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex") {
-		l.push(
-			`\t${cmd.cmdVarName}.Flags().StringVar(&${cmd.cmdVarName}DataVar, "data", "", "Request body: JSON literal, @file, or - for stdin")`,
-		)
-	}
-	if (cmd.body.kind === "json-flat") {
-		for (const s of cmd.body.scalars) {
-			emitBodyScalarFlag(l, cmd, s)
-		}
-	}
-	if (cmd.body.kind === "multipart") {
-		for (const s of cmd.body.scalarFields) {
-			emitBodyScalarFlag(l, cmd, s)
+	const c = cmd.cmdVarName
+	for (const f of allFlags(cmd)) {
+		let help: string
+		switch (f.where) {
+			case "path":
+				help = `Path parameter ${f.name}`
+				break
+			case "query":
+				help = `Query param ${f.name}`
+				break
+			case "header":
+				help = `Header ${f.name}`
+				break
+			case "file":
+				help = `Path to the ${f.name} file to upload`
+				break
+			default:
+				help = `Body field ${f.name}`
 		}
-		if (cmd.body.useGenericFileFlag) {
-			l.push(`\t${cmd.cmdVarName}.Flags().StringVar(&${cmd.cmdVarName}FileVar, "file", "", "Path to file to upload")`)
-			const bin = cmd.body.binaryFields[0]
-			if (bin?.required) {
-				l.push(`\t${cmd.cmdVarName}.MarkFlagRequired("file")`)
-			}
-		} else {
-			for (const f of cmd.body.binaryFields) {
-				const v = `${cmd.cmdVarName}${goPascal(f.name)}Var`
-				l.push(
-					`\t${cmd.cmdVarName}.Flags().StringVar(&${v}, ${JSON.stringify(toFlagName(f.name))}, "", ${JSON.stringify(`Path to ${f.name} file`)})`,
-				)
-				if (f.required) {
-					l.push(`\t${cmd.cmdVarName}.MarkFlagRequired(${JSON.stringify(toFlagName(f.name))})`)
-				}
-			}
+		if (f.enumValues.length > 0) help += ` (one of: ${f.enumValues.join(", ")})`
+		const h = goString(help)
+		const n = goString(f.flagName)
+		const def = flagDefault(f)
+		switch (f.kind) {
+			case "int":
+				l.push(`\t${c}.Flags().Int64Var(&${f.varName}, ${n}, ${def}, ${h})`)
+				break
+			case "float":
+				l.push(`\t${c}.Flags().Float64Var(&${f.varName}, ${n}, ${def}, ${h})`)
+				break
+			case "bool":
+				l.push(`\t${c}.Flags().BoolVar(&${f.varName}, ${n}, ${def}, ${h})`)
+				break
+			case "strings":
+				l.push(`\t${c}.Flags().StringSliceVar(&${f.varName}, ${n}, ${def}, ${h})`)
+				break
+			default:
+				l.push(`\t${c}.Flags().StringVar(&${f.varName}, ${n}, ${def}, ${h})`)
 		}
+		if (f.required) l.push(`\t${c}.MarkFlagRequired(${n})`)
 	}
-	if (cmd.hasLastEventId) {
-		l.push(
-			`\t${cmd.cmdVarName}.Flags().StringVar(&${cmd.cmdVarName}LastEventIDVar, "last-event-id", "", "SSE Last-Event-ID resume token")`,
-		)
+	if (cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex" || cmd.body.kind === "raw") {
+		l.push(`\t${c}.Flags().StringVar(&${cmd.body.dataVar}, "data", "", "Request body: literal, @file, or - for stdin")`)
 	}
-}
-
-function emitQueryFlag(l: string[], cmd: CommandInfo, q: ParamInfo): void {
-	const v = `${cmd.cmdVarName}${goPascal(q.name)}Var`
-	const t = q.schema.type
-	const help =
-		q.enumValues.length > 0 ? `Query param ${q.name} (one of: ${q.enumValues.join(", ")})` : `Query param ${q.name}`
-	const helpStr = JSON.stringify(help)
-
-	if (t === "integer") {
-		const def = typeof q.defaultValue === "number" ? q.defaultValue : 0
-		l.push(`\t${cmd.cmdVarName}.Flags().Int64Var(&${v}, ${JSON.stringify(q.flagName)}, ${def}, ${helpStr})`)
-	} else if (t === "number") {
-		const def = typeof q.defaultValue === "number" ? q.defaultValue : 0
-		l.push(`\t${cmd.cmdVarName}.Flags().Float64Var(&${v}, ${JSON.stringify(q.flagName)}, ${def}, ${helpStr})`)
-	} else if (t === "boolean") {
-		const def = q.defaultValue === true
-		l.push(
-			`\t${cmd.cmdVarName}.Flags().BoolVar(&${v}, ${JSON.stringify(q.flagName)}, ${def ? "true" : "false"}, ${helpStr})`,
-		)
-	} else if (t === "array") {
-		const defArr = Array.isArray(q.defaultValue) ? q.defaultValue : []
-		const defStr = `[]string{${defArr.map((x) => JSON.stringify(String(x))).join(", ")}}`
-		l.push(`\t${cmd.cmdVarName}.Flags().StringSliceVar(&${v}, ${JSON.stringify(q.flagName)}, ${defStr}, ${helpStr})`)
-	} else {
-		const def = typeof q.defaultValue === "string" ? q.defaultValue : ""
-		l.push(
-			`\t${cmd.cmdVarName}.Flags().StringVar(&${v}, ${JSON.stringify(q.flagName)}, ${JSON.stringify(def)}, ${helpStr})`,
-		)
-	}
-	if (q.required) {
-		l.push(`\t${cmd.cmdVarName}.MarkFlagRequired(${JSON.stringify(q.flagName)})`)
-	}
-}
-
-function emitBodyScalarFlag(l: string[], cmd: CommandInfo, s: BodyScalarInfo): void {
-	const v = `${cmd.cmdVarName}${goPascal(s.propName)}Var`
-	const help =
-		s.enumValues.length > 0
-			? `Body field ${s.propName} (one of: ${s.enumValues.join(", ")})`
-			: `Body field ${s.propName}`
-	const helpStr = JSON.stringify(help)
-	if (s.schemaType === "integer") {
-		l.push(`\t${cmd.cmdVarName}.Flags().Int64Var(&${v}, ${JSON.stringify(s.flagName)}, 0, ${helpStr})`)
-	} else if (s.schemaType === "number") {
-		l.push(`\t${cmd.cmdVarName}.Flags().Float64Var(&${v}, ${JSON.stringify(s.flagName)}, 0, ${helpStr})`)
-	} else if (s.schemaType === "boolean") {
-		l.push(`\t${cmd.cmdVarName}.Flags().BoolVar(&${v}, ${JSON.stringify(s.flagName)}, false, ${helpStr})`)
-	} else {
-		l.push(`\t${cmd.cmdVarName}.Flags().StringVar(&${v}, ${JSON.stringify(s.flagName)}, "", ${helpStr})`)
+	if (cmd.lastEventIdVar) {
+		l.push(`\t${c}.Flags().StringVar(&${cmd.lastEventIdVar}, "last-event-id", "", "SSE Last-Event-ID resume token")`)
 	}
 }
 
 function emitPreRunE(cmd: CommandInfo): string[] {
 	const lines: string[] = []
-	/* required body on POST/PUT/PATCH */
 	if (
-		(cmd.method === "POST" || cmd.method === "PUT" || cmd.method === "PATCH") &&
-		(cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex") &&
+		(cmd.body.kind === "json-flat" || cmd.body.kind === "json-complex" || cmd.body.kind === "raw") &&
 		cmd.body.required
 	) {
-		const dataVar = `${cmd.cmdVarName}DataVar`
 		const anyFlag =
 			cmd.body.kind === "json-flat" && cmd.body.scalars.length > 0
-				? cmd.body.scalars.map((s) => `cmd.Flags().Changed(${JSON.stringify(s.flagName)})`).join(" || ")
+				? cmd.body.scalars.map((s) => `cmd.Flags().Changed(${goString(s.flagName)})`).join(" || ")
 				: "false"
-		lines.push(`if ${dataVar} == "" && !(${anyFlag}) {`)
-		lines.push(`\treturn fmt.Errorf("body required: pass --data or per-field flags")`)
+		lines.push(`if ${cmd.body.dataVar} == "" && !(${anyFlag}) {`)
+		lines.push(`\treturn cli.Usage(errors.New("body required: pass --data or per-field flags"))`)
 		lines.push(`}`)
 	}
-	/* enum validation: query + body-flat */
-	for (const q of cmd.queryParams) {
-		if (q.enumValues.length === 0) continue
-		if (q.schema.type !== "string") continue
-		const v = `${cmd.cmdVarName}${goPascal(q.name)}Var`
-		const values = q.enumValues.map((x) => JSON.stringify(x)).join(", ")
-		lines.push(`if cmd.Flags().Changed(${JSON.stringify(q.flagName)}) && !slices.Contains([]string{${values}}, ${v}) {`)
-		lines.push(`\treturn fmt.Errorf("--${q.flagName} must be one of: ${q.enumValues.join(", ")}")`)
+	for (const f of allFlags(cmd)) {
+		if (f.enumValues.length === 0 || f.kind !== "string") continue
+		const values = f.enumValues.map(goString).join(", ")
+		const msg = goString(`--${f.flagName} must be one of: ${f.enumValues.join(", ")}`)
+		lines.push(
+			`if cmd.Flags().Changed(${goString(f.flagName)}) && !slices.Contains([]string{${values}}, ${f.varName}) {`,
+		)
+		lines.push(`\treturn cli.Usage(errors.New(${msg}))`)
 		lines.push(`}`)
 	}
-	if (cmd.body.kind === "json-flat") {
-		for (const s of cmd.body.scalars) {
-			if (s.enumValues.length === 0) continue
-			if (s.schemaType !== "string") continue
-			const v = `${cmd.cmdVarName}${goPascal(s.propName)}Var`
-			const values = s.enumValues.map((x) => JSON.stringify(x)).join(", ")
-			lines.push(
-				`if cmd.Flags().Changed(${JSON.stringify(s.flagName)}) && !slices.Contains([]string{${values}}, ${v}) {`,
-			)
-			lines.push(`\treturn fmt.Errorf("--${s.flagName} must be one of: ${s.enumValues.join(", ")}")`)
-			lines.push(`}`)
-		}
-	}
 	return lines
 }
 
-function emitRunE(l: string[], cmd: CommandInfo, _options: GoCLIOptions): void {
+/** Go expression rendering a flag variable as a wire string. */
+function scalarString(f: Flag, expr = f.varName): string {
+	switch (f.kind) {
+		case "int":
+			return `strconv.FormatInt(${expr}, 10)`
+		case "float":
+			return `strconv.FormatFloat(${expr}, 'g', -1, 64)`
+		case "bool":
+			return `strconv.FormatBool(${expr})`
+		default:
+			return expr
+	}
+}
+
+function emitRunE(l: string[], cmd: CommandInfo): void {
 	const ind = "\t\t"
+	const { op } = cmd
 	l.push(`${ind}ctx := cmd.Context()`)
 	l.push(`${ind}cfg := configFromCtx(ctx)`)
 	l.push(`${ind}apiKey, err := cli.ResolveAPIKey(cfg)`)
-	l.push(`${ind}if err != nil { return err }`)
-	l.push(`${ind}_ = apiKey`)
-	l.push(`${ind}baseURL := cfg.BaseURL`)
-	l.push(`${ind}if baseURL == "" { return fmt.Errorf("base URL required: set --base-url, env, or config") }`)
-	l.push(`${ind}timeout := 30 * time.Second`)
-	l.push(`${ind}if cfg.Timeout != "" {`)
-	l.push(`${ind}\tif d, perr := time.ParseDuration(cfg.Timeout); perr == nil { timeout = d }`)
+	l.push(`${ind}if err != nil {`)
+	l.push(`${ind}\treturn err`)
+	l.push(`${ind}}`)
+	l.push(`${ind}if cfg.BaseURL == "" {`)
+	l.push(`${ind}\treturn cli.Usage(errors.New("base URL required: set --base-url, env, or config"))`)
 	l.push(`${ind}}`)
-	l.push(`${ind}httpClient := &http.Client{Timeout: timeout}`)
 
-	/* path-param local aliases: short Go-idiomatic names used in URL assembly */
-	for (const p of cmd.pathParams) {
-		const storageVar = `${cmd.cmdVarName}${goPascal(p.name)}Var`
-		l.push(`${ind}${p.varName} := ${storageVar}`)
+	/* path */
+	if (cmd.pathFlags.length > 0) {
+		const params = cmd.pathFlags.map((f) => `${goString(f.name)}: ${f.varName}`).join(", ")
+		l.push(`${ind}path, err := sdk.HoneyExpandPath(${goString(op.path)}, map[string]string{${params}})`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn cli.Usage(err)`)
+		l.push(`${ind}}`)
+	} else {
+		l.push(`${ind}path := ${goString(op.path)}`)
 	}
 
-	/* URL assembly */
-	const pathExpr = buildPathExpr(cmd)
-	l.push(`${ind}reqURL := baseURL + ${pathExpr}`)
-	l.push(`${ind}q := url.Values{}`)
-	for (const q of cmd.queryParams) {
-		if (isLastEventIdName(q.name)) continue
-		emitQueryAssembly(l, ind, cmd, q)
+	/* query: a required flag is always sent, an optional one only when set */
+	l.push(`${ind}var query [][2]string`)
+	for (const f of cmd.queryFlags) {
+		const guard = f.required ? "" : `if cmd.Flags().Changed(${goString(f.flagName)}) `
+		if (f.kind === "strings") {
+			l.push(`${ind}${guard}{`)
+			l.push(`${ind}\tfor _, v := range ${f.varName} {`)
+			l.push(`${ind}\t\tquery = append(query, [2]string{${goString(f.name)}, v})`)
+			l.push(`${ind}\t}`)
+			l.push(`${ind}}`)
+		} else {
+			l.push(`${ind}${guard}{`)
+			l.push(`${ind}\tquery = append(query, [2]string{${goString(f.name)}, ${scalarString(f)}})`)
+			l.push(`${ind}}`)
+		}
 	}
-	l.push(`${ind}if len(q) > 0 { reqURL += "?" + q.Encode() }`)
+	l.push(`${ind}reqURL, err := sdk.HoneyBuildURL(cfg.BaseURL, path, query)`)
+	l.push(`${ind}if err != nil {`)
+	l.push(`${ind}\treturn cli.Usage(err)`)
+	l.push(`${ind}}`)
 
-	/* body prep */
-	let bodyReaderExpr = "nil"
-	let contentType = ""
-	if (cmd.body.kind === "json-flat") {
-		l.push(`${ind}// merge --data + per-prop flags`)
+	/* body */
+	let bodyExpr = "nil"
+	let contentTypeExpr = ""
+	const b = cmd.body
+	if (b.kind === "json-flat") {
 		l.push(`${ind}merged := map[string]any{}`)
-		l.push(`${ind}if ${cmd.cmdVarName}DataVar != "" {`)
-		l.push(`${ind}\tdataBytes, derr := cli.ReadDataFlag(${cmd.cmdVarName}DataVar)`)
-		l.push(`${ind}\tif derr != nil { return derr }`)
+		l.push(`${ind}if ${b.dataVar} != "" {`)
+		l.push(`${ind}\tdataBytes, derr := cli.ReadDataFlag(${b.dataVar})`)
+		l.push(`${ind}\tif derr != nil {`)
+		l.push(`${ind}\t\treturn cli.Usage(derr)`)
+		l.push(`${ind}\t}`)
 		l.push(`${ind}\tif len(dataBytes) > 0 {`)
-		l.push(
-			`${ind}\t\tif jerr := json.Unmarshal(dataBytes, &merged); jerr != nil { return fmt.Errorf("parse --data: %w", jerr) }`,
-		)
+		l.push(`${ind}\t\tif jerr := json.Unmarshal(dataBytes, &merged); jerr != nil {`)
+		l.push(`${ind}\t\t\treturn cli.Usage(fmt.Errorf("parse --data: %w", jerr))`)
+		l.push(`${ind}\t\t}`)
 		l.push(`${ind}\t}`)
 		l.push(`${ind}}`)
-		for (const s of cmd.body.scalars) {
-			const v = `${cmd.cmdVarName}${goPascal(s.propName)}Var`
-			l.push(
-				`${ind}if cmd.Flags().Changed(${JSON.stringify(s.flagName)}) { merged[${JSON.stringify(s.propName)}] = ${v} }`,
-			)
+		for (const s of b.scalars) {
+			l.push(`${ind}if cmd.Flags().Changed(${goString(s.flagName)}) {`)
+			l.push(`${ind}\tmerged[${goString(s.name)}] = ${s.varName}`)
+			l.push(`${ind}}`)
 		}
-		l.push(`${ind}bodyBytes, merr := json.Marshal(merged)`)
-		l.push(`${ind}if merr != nil { return merr }`)
-		bodyReaderExpr = "bytes.NewReader(bodyBytes)"
-		contentType = "application/json"
-	} else if (cmd.body.kind === "json-complex") {
-		l.push(`${ind}bodyBytes, derr := cli.ReadDataFlag(${cmd.cmdVarName}DataVar)`)
-		l.push(`${ind}if derr != nil { return derr }`)
-		bodyReaderExpr = "bytes.NewReader(bodyBytes)"
-		contentType = "application/json"
-	} else if (cmd.body.kind === "multipart") {
+		l.push(`${ind}bodyBytes, err := json.Marshal(merged)`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn err`)
+		l.push(`${ind}}`)
+		bodyExpr = "bytes.NewReader(bodyBytes)"
+		contentTypeExpr = goString(op.body?.contentType ?? "application/json")
+	} else if (b.kind === "json-complex" || b.kind === "raw") {
+		l.push(`${ind}bodyBytes, err := cli.ReadDataFlag(${b.dataVar})`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn cli.Usage(err)`)
+		l.push(`${ind}}`)
+		bodyExpr = "bytes.NewReader(bodyBytes)"
+		contentTypeExpr = goString(op.body?.contentType ?? "application/json")
+	} else if (b.kind === "form") {
+		l.push(`${ind}form := url.Values{}`)
+		for (const s of b.scalars) {
+			l.push(`${ind}if cmd.Flags().Changed(${goString(s.flagName)}) {`)
+			l.push(`${ind}\tform.Set(${goString(s.name)}, ${scalarString(s)})`)
+			l.push(`${ind}}`)
+		}
+		bodyExpr = "strings.NewReader(form.Encode())"
+		contentTypeExpr = `"application/x-www-form-urlencoded"`
+	} else if (b.kind === "multipart") {
 		l.push(`${ind}fields := map[string]string{}`)
-		for (const s of cmd.body.scalarFields) {
-			const v = `${cmd.cmdVarName}${goPascal(s.propName)}Var`
-			if (s.schemaType === "string") {
-				l.push(
-					`${ind}if cmd.Flags().Changed(${JSON.stringify(s.flagName)}) { fields[${JSON.stringify(s.propName)}] = ${v} }`,
-				)
-			} else {
-				l.push(
-					`${ind}if cmd.Flags().Changed(${JSON.stringify(s.flagName)}) { fields[${JSON.stringify(s.propName)}] = fmt.Sprint(${v}) }`,
-				)
-			}
+		for (const s of b.scalars) {
+			l.push(`${ind}if cmd.Flags().Changed(${goString(s.flagName)}) {`)
+			l.push(`${ind}\tfields[${goString(s.name)}] = ${scalarString(s)}`)
+			l.push(`${ind}}`)
 		}
 		l.push(`${ind}files := map[string]string{}`)
-		if (cmd.body.useGenericFileFlag) {
-			const bin = cmd.body.binaryFields[0]
-			l.push(
-				`${ind}if ${cmd.cmdVarName}FileVar != "" { files[${JSON.stringify(bin.name)}] = ${cmd.cmdVarName}FileVar }`,
-			)
-		} else {
-			for (const f of cmd.body.binaryFields) {
-				const v = `${cmd.cmdVarName}${goPascal(f.name)}Var`
-				l.push(`${ind}if ${v} != "" { files[${JSON.stringify(f.name)}] = ${v} }`)
-			}
+		for (const f of b.files) {
+			l.push(`${ind}if ${f.varName} != "" {`)
+			l.push(`${ind}\tfiles[${goString(f.name)}] = ${f.varName}`)
+			l.push(`${ind}}`)
 		}
-		l.push(`${ind}mpReader, mpCT, mpErr := cli.BuildMultipart(fields, files)`)
-		l.push(`${ind}if mpErr != nil { return mpErr }`)
-		l.push(`${ind}_ = mpCT`)
-		bodyReaderExpr = "mpReader"
-		contentType = "__multipart__"
+		l.push(`${ind}mpReader, mpCT, err := cli.BuildMultipart(fields, files)`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn err`)
+		l.push(`${ind}}`)
+		bodyExpr = "mpReader"
+		contentTypeExpr = "mpCT"
+	}
+
+	/* regular calls get --timeout; streams and uploads only stop on ^C */
+	const bounded = op.stream === null && b.kind !== "multipart"
+	if (bounded) {
+		l.push(`${ind}timeout, err := time.ParseDuration(cfg.Timeout)`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn cli.Usage(err)`)
+		l.push(`${ind}}`)
+		l.push(`${ind}ctx, cancel := context.WithTimeout(ctx, timeout)`)
+		l.push(`${ind}defer cancel()`)
+	}
+
+	l.push(`${ind}req, err := http.NewRequestWithContext(ctx, ${goString(op.method)}, reqURL, ${bodyExpr})`)
+	l.push(`${ind}if err != nil {`)
+	l.push(`${ind}\treturn err`)
+	l.push(`${ind}}`)
+	if (contentTypeExpr) l.push(`${ind}req.Header.Set("Content-Type", ${contentTypeExpr})`)
+	for (const f of cmd.headerFlags) {
+		const guard = f.required ? "" : `if cmd.Flags().Changed(${goString(f.flagName)}) `
+		const value = f.kind === "strings" ? `strings.Join(${f.varName}, ",")` : scalarString(f)
+		l.push(`${ind}${guard}{`)
+		l.push(`${ind}\treq.Header.Set(${goString(f.name)}, ${value})`)
+		l.push(`${ind}}`)
 	}
+	l.push(`${ind}cli.ApplyAuth(req.Header, AuthHeaderName, AuthHeaderPrefix, apiKey)`)
 
-	/* SSE */
-	if (cmd.isSSE) {
-		l.push(`${ind}req, rerr := http.NewRequestWithContext(ctx, "GET", reqURL, nil)`)
-		l.push(`${ind}if rerr != nil { return rerr }`)
+	if (op.stream === "sse") {
 		l.push(`${ind}req.Header.Set("Accept", "text/event-stream")`)
-		l.push(`${ind}if apiKey != "" { req.Header.Set("Authorization", "Bearer "+apiKey) }`)
-		if (cmd.hasLastEventId) {
-			l.push(
-				`${ind}if ${cmd.cmdVarName}LastEventIDVar != "" { req.Header.Set("Last-Event-ID", ${cmd.cmdVarName}LastEventIDVar) }`,
-			)
+		if (cmd.lastEventIdVar) {
+			l.push(`${ind}if ${cmd.lastEventIdVar} != "" {`)
+			l.push(`${ind}\treq.Header.Set("Last-Event-ID", ${cmd.lastEventIdVar})`)
+			l.push(`${ind}}`)
 		}
-		l.push(`${ind}resp, herr := httpClient.Do(req)`)
-		l.push(`${ind}if herr != nil { return herr }`)
-		l.push(`${ind}defer resp.Body.Close()`)
-		l.push(`${ind}it := sdk.ParseSSEStreamExported(ctx, resp)`)
+		l.push(`${ind}resp, err := newHTTPClient().Do(req)`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn err`)
+		l.push(`${ind}}`)
 		/* wrap SDK's Seq2[sdk.SSEEvent] → Seq2[cli.SSEEvent] so the runtime stays SDK-agnostic. */
+		l.push(`${ind}it := sdk.HoneyParseSSEStream(ctx, resp)`)
 		l.push(`${ind}wrapped := func(yield func(cli.SSEEvent, error) bool) {`)
 		l.push(`${ind}\tfor ev, iterErr := range it {`)
 		l.push(`${ind}\t\tif !yield(cli.SSEEvent{Data: ev.Data, Event: ev.Event, ID: ev.ID, Retry: ev.Retry}, iterErr) {`)
@@ -937,75 +870,33 @@ function emitRunE(l: string[], cmd: CommandInfo, _options: GoCLIOptions): void {
 		return
 	}
 
-	/* regular HTTP */
-	l.push(`${ind}req, rerr := http.NewRequestWithContext(ctx, "${cmd.method}", reqURL, ${bodyReaderExpr})`)
-	l.push(`${ind}if rerr != nil { return rerr }`)
-	if (contentType === "application/json") {
-		l.push(`${ind}req.Header.Set("Content-Type", "application/json")`)
-	} else if (contentType === "__multipart__") {
-		l.push(`${ind}req.Header.Set("Content-Type", mpCT) // multipart/form-data; boundary=...`)
-	}
-	l.push(`${ind}if apiKey != "" { req.Header.Set("Authorization", "Bearer "+apiKey) }`)
-	l.push(`${ind}resp, herr := httpClient.Do(req)`)
-	l.push(`${ind}if herr != nil { return herr }`)
+	l.push(`${ind}resp, err := newHTTPClient().Do(req)`)
+	l.push(`${ind}if err != nil {`)
+	l.push(`${ind}\treturn err`)
+	l.push(`${ind}}`)
 	l.push(`${ind}defer resp.Body.Close()`)
-	l.push(`${ind}body, berr := io.ReadAll(resp.Body)`)
-	l.push(`${ind}if berr != nil { return berr }`)
-	l.push(`${ind}if resp.StatusCode >= 400 {`)
-	l.push(
-		`${ind}\treturn &sdk.StatusError{StatusCode: resp.StatusCode, Body: body, Response: resp, Message: string(body)}`,
-	)
+	l.push(`${ind}body, err := io.ReadAll(resp.Body)`)
+	l.push(`${ind}if err != nil {`)
+	l.push(`${ind}\treturn err`)
 	l.push(`${ind}}`)
-	if (cmd.has204) {
-		l.push(`${ind}if resp.StatusCode == http.StatusNoContent { return nil }`)
-	}
-	if (cmd.responseType === "json") {
-		l.push(`${ind}var out any`)
-		l.push(`${ind}if len(body) > 0 {`)
-		l.push(`${ind}\tif jerr := json.Unmarshal(body, &out); jerr != nil { return jerr }`)
+	l.push(`${ind}if err := sdk.HoneyRaiseForStatus(resp, body); err != nil {`)
+	l.push(`${ind}\treturn err`)
+	l.push(`${ind}}`)
+	const kind = op.success.kind
+	if (kind === "json") {
+		l.push(`${ind}out, err := cli.DecodeJSON(body)`)
+		l.push(`${ind}if err != nil {`)
+		l.push(`${ind}\treturn err`)
 		l.push(`${ind}}`)
 		l.push(`${ind}return cli.Emit(out, cfg.Output, os.Stdout)`)
+	} else if (kind === "text" || kind === "binary") {
+		l.push(`${ind}_, err = os.Stdout.Write(body)`)
+		l.push(`${ind}return err`)
 	} else {
 		l.push(`${ind}return nil`)
 	}
 }
 
-function buildPathExpr(cmd: CommandInfo): string {
-	if (cmd.pathParams.length === 0) return JSON.stringify(cmd.path)
-	let expr = JSON.stringify(cmd.path)
-	for (const p of cmd.pathParams) {
-		expr = expr.replace(`{${p.name}}`, `" + url.PathEscape(${p.varName}) + "`)
-	}
-	expr = expr.replace(/"" \+ /g, "").replace(/ \+ ""/g, "")
-	return expr
-}
-
-function querySetStmt(q: ParamInfo, v: string): string {
-	const name = JSON.stringify(q.name)
-	switch (q.schema.type) {
-		case "integer":
-			return `q.Set(${name}, fmt.Sprintf("%d", ${v}))`
-		case "number":
-			return `q.Set(${name}, fmt.Sprintf("%g", ${v}))`
-		case "boolean":
-			return `q.Set(${name}, fmt.Sprintf("%t", ${v}))`
-		case "array":
-			return `for _, v := range ${v} { q.Add(${name}, v) }`
-		default:
-			return `q.Set(${name}, ${v})`
-	}
-}
-
-function emitQueryAssembly(l: string[], ind: string, cmd: CommandInfo, q: ParamInfo): void {
-	const v = `${cmd.cmdVarName}${goPascal(q.name)}Var`
-	const stmt = querySetStmt(q, v)
-	if (q.required) {
-		l.push(`${ind}${stmt}`)
-		return
-	}
-	l.push(`${ind}if cmd.Flags().Changed(${JSON.stringify(q.flagName)}) { ${stmt} }`)
-}
-
 /* ── emit: main.go ── */
 
 function emitMainFile(options: GoCLIOptions): string {
@@ -1018,13 +909,13 @@ function emitMainFile(options: GoCLIOptions): string {
 	l.push(`\t"fmt"`)
 	l.push(`\t"os"`)
 	l.push(``)
-	l.push(`\tcli "${module}/internal/cli"`)
-	l.push(`\t"${module}/cmd"`)
+	l.push(`\tcli ${goString(`${module}/internal/cli`)}`)
+	l.push(`\t${goString(`${module}/cmd`)}`)
 	l.push(`)`)
 	l.push(``)
 	l.push(`func main() {`)
 	l.push(`\tif err := cmd.Execute(); err != nil {`)
-	l.push(`\t\tfmt.Fprintln(os.Stderr, err)`)
+	l.push(`\t\tfmt.Fprintln(os.Stderr, cli.Sanitize(err.Error()))`)
 	l.push(`\t\tos.Exit(cli.ExitFor(err))`)
 	l.push(`\t}`)
 	l.push(`}`)
@@ -1039,7 +930,7 @@ function emitGoMod(options: GoCLIOptions, hasEmbeddedSDK: boolean): string {
 	const l: string[] = []
 	l.push(`module ${mod}`)
 	l.push(``)
-	l.push(`go 1.23`)
+	l.push(`go 1.24`)
 	l.push(``)
 	l.push(`require (`)
 	l.push(`\tgithub.com/spf13/cobra v1.8.1`)
@@ -1062,10 +953,10 @@ function emitGoMod(options: GoCLIOptions, hasEmbeddedSDK: boolean): string {
 
 /* ── emit: README.md ── */
 
-function emitReadme(spec: OpenApiSpec, options: GoCLIOptions): string {
+function emitReadme(info: IRInfo, options: GoCLIOptions): string {
 	const envPrefix = options.envPrefix ?? toSnakeUpper(options.binaryName)
 	const configName = options.configName ?? options.binaryName
-	const title = spec.info?.title ?? options.binaryName
+	const title = info.title ?? options.binaryName
 	return [
 		`# ${options.binaryName}`,
 		``,
@@ -1074,22 +965,22 @@ function emitReadme(spec: OpenApiSpec, options: GoCLIOptions): string {
 		`## Install`,
 		``,
 		"```sh",
-		`go build -o ${options.binaryName} ./...`,
+		`go build -ldflags "-X ${resolveModulePath(options)}/internal/cli.Version=1.0.0" -o ${options.binaryName} .`,
 		"```",
 		``,
 		`## Auth`,
 		``,
 		`Resolution order (high → low):`,
 		``,
-		`1. \`--api-key <value>\``,
+		`1. \`--api-key <value>\` (visible in the process list; prefer the env var)`,
 		`2. \`${envPrefix}_API_KEY\` env var`,
-		`3. \`~/.config/${configName}/config.toml\` → \`api_key = "..."\``,
+		`3. \`~/.config/${configName}/config.toml\` → \`api_key = "..."\` (keep it \`chmod 600\`)`,
 		`4. \`$XDG_CONFIG_HOME/${configName}/config.toml\``,
 		``,
 		`## Global flags`,
 		``,
 		`- \`--api-key\`, \`--base-url\`, \`--output\` (json|ndjson|yaml|table)`,
-		`- \`--verbose\`, \`--config\`, \`--timeout\``,
+		`- \`--verbose\`, \`--config\`, \`--timeout\` (regular calls only; streams and uploads are not bounded)`,
 		``,
 		`## Exit codes`,
 		``,
@@ -1097,8 +988,8 @@ function emitReadme(spec: OpenApiSpec, options: GoCLIOptions): string {
 		`- 1: 4xx client error`,
 		`- 2: 5xx server error`,
 		`- 3: network failure / timeout`,
-		`- 4: bad flags / missing api-key`,
-		`- 5: unexpected 3xx`,
+		`- 4: bad flags / bad config / missing api-key`,
+		`- 5: unexpected 3xx (redirects to another host are not followed)`,
 		``,
 	].join("\n")
 }
@@ -1116,12 +1007,10 @@ function copyEmbeddedSDK(spec: Record<string, unknown>, options: GoCLIOptions, o
 }
 
 /* ── ParseSSEStreamExported shim ──
- *   The SDK exports parseSSEStream lowercase (package-private).
- *   We need to re-expose it under the SDK package so the CLI's cmd/*.go can call it.
- *   When embedding, add a small sse_export.go into internal/sdk/.
- *   When using external SDK, we still need the same symbol — emit an adapter file. */
+ * Older generated CLIs call ParseSSEStreamExported; kept so they keep compiling against
+ * an embedded SDK. New code uses the Honey* helpers in export.go. */
 
-function emitSSEExportShim(options: GoCLIOptions, files: Record<string, string>, hasEmbedded: boolean): void {
+function emitSSEExportShim(files: Record<string, string>, hasEmbedded: boolean): void {
 	const shim = [
 		`// Code generated by honey. DO NOT EDIT.`,
 		`package sdk`,
@@ -1138,18 +1027,17 @@ function emitSSEExportShim(options: GoCLIOptions, files: Record<string, string>,
 		`}`,
 		``,
 	].join("\n")
-	if (hasEmbedded) {
-		files["internal/sdk/sse_export.go"] = shim
-	}
-	/* external-SDK mode: consumer's SDK must already export or we rely on ParseSSEStreamExported existing.
-	   We include the shim in embed mode only; external mode assumes SDK regenerated w/ same honey. */
+	if (hasEmbedded) files["internal/sdk/sse_export.go"] = shim
 }
 
 /* ── public entrypoint ── */
 
 export function generateGoCLI(spec: Record<string, unknown>, options: GoCLIOptions): GeneratedGoCLI {
-	const resolved = resolveRefs(spec as Parameters<typeof resolveRefs>[0]) as unknown as OpenApiSpec
-	const { groups, skipped, serviceMap } = collectCLIMethods(spec)
+	const input = spec as unknown as OpenApiSpecInput
+	const model = buildSdkModel(input)
+	const serviceMap = serviceMapOf(model.ir)
+	const pkg = new NameScope(CMD_PACKAGE_NAMES)
+	const { groups, skipped } = collectCLIMethods(model, pkg)
 
 	const hasEmbeddedSDK = !options.sdkModulePath
 	const files: Record<string, string> = {}
@@ -1159,29 +1047,20 @@ export function generateGoCLI(spec: Record<string, unknown>, options: GoCLIOptio
 		files[`internal/cli/${name}`] = content
 	}
 
-	/* main.go */
 	files["main.go"] = emitMainFile(options)
 
-	/* cmd/root.go */
-	const sortedGroups = [...groups.values()].sort((a, b) => a.resource.localeCompare(b.resource))
-	files["cmd/root.go"] = emitRootFile(sortedGroups, options)
+	const sortedGroups = [...groups.values()].sort((a, b) => cmpCodeUnit(a.resource, b.resource))
+	files["cmd/root.go"] = emitRootFile(sortedGroups, options, model.ir.auth)
 
-	/* cmd/<resource>.go */
 	for (const g of sortedGroups) {
 		files[`cmd/${g.fileName}`] = emitResourceFile(g, options)
 	}
 
-	/* go.mod */
 	files["go.mod"] = emitGoMod(options, hasEmbeddedSDK)
+	files["README.md"] = emitReadme(model.ir.info, options)
 
-	/* README.md */
-	files["README.md"] = emitReadme(resolved, options)
-
-	/* SDK embed if sdkModulePath not set */
-	if (hasEmbeddedSDK) {
-		copyEmbeddedSDK(spec, options, files)
-	}
-	emitSSEExportShim(options, files, hasEmbeddedSDK)
+	if (hasEmbeddedSDK) copyEmbeddedSDK(spec, options, files)
+	emitSSEExportShim(files, hasEmbeddedSDK)
 
-	return { files, serviceMap, skippedOperations: skipped }
+	return { files, serviceMap: serviceMap as Record<string, Record<string, unknown>>, skippedOperations: skipped }
 }