gencmd

type DryRun struct {
	Target string     `json:"target"`
	Count  int        `json:"count"`
	Cost   spend.Cost `json:"cost"`
	// OverCap names the spend-guard axis the estimate crosses ("amount" |
	// "characters"), empty when it stays under both. The guard is not applied here —
	// a dry run spends nothing, so there is nothing to gate.
	OverCap string `json:"over_cap,omitempty"`
	// Noun is what one unit of the output is called in the TEXT form, where "take"
	// would be wrong — a storyboard draft is a board, not a candidate to choose
	// between. Empty means "take". Off the wire deliberately: it is prose, and the
	// JSON shape is a contract an MCP client reads.
	Noun string `json:"-"`
	// Uncached suppresses the "served from the cache without spending" line, which
	// is true of every media generation (R-GLOBAL-9) and false of a storyboard
	// draft — there is no content cache on the chat path, so a re-run pays again.
	// Someone acts on that sentence, so it must not be said where it is untrue.
	Uncached bool `json:"-"`
}

type Request struct {
	Target Target
	Dir    string // workspace dir on the target fs
	Card   int    // TargetCard: 1-based card index
	Line   int    // TargetVO: 1-based storyboard line
	Scene  string // TargetCard/TargetCover: the illustration scene
	Theme  string // theme keyword, resolved against the target's theme type
	// Aspect overrides the generated image's frame shape (TargetCover): a reel
	// cover follows the reel's aspect (0029 §9 note 27), not the article theme's.
	Aspect string
	Refs   []provider.RefImage // TargetPortrait: reference photos (image-to-image)
	// Avatars is the card's cast (TargetCard): registered avatar names whose likeness
	// is directed into the scene via image-to-image (spec 0034 D4). Empty = a plain
	// text-to-image card in the theme style (the pre-avatar behaviour).
	Avatars []string
	Count   int // candidate takes
	// LengthMS is the requested music bed length (TargetMusic): 0 = default to the
	// VO-driven total, positive = explicit override.
	LengthMS int
	// Model overrides the TTS model (TargetVO); empty ⇒ theme/default. AllowUnknown
	// accepts a Model outside the allowlist (spec 0022 B).
	Model        string
	AllowUnknown bool
	// Force bypasses the content cache (R-GEN-8): regenerate + refresh the cached set
	// even when the request is unchanged. Maps to the CLI `--force`.
	Force bool
}

type Target int