# internal/app/envelope

Package envelope defines stable JSON response envelopes for CLI automation.

## Envelope

```go
type Envelope[T any] struct {
	OK       bool     `json:"ok"`
	Command  string   `json:"command"`
	Warnings []string `json:"warnings,omitempty"`
	Result   T        `json:"result,omitempty"`
	Error    *Error   `json:"error,omitempty"`
}
```

Envelope is the stable JSON wrapper emitted by automation-facing commands.

- `OK: bool` (json:"ok"): 
- `Command: string` (json:"command"): 
- `Warnings: []string` (json:"warnings,omitempty"): 
- `Result: T` (json:"result,omitempty"): 
- `Error: *Error` (json:"error,omitempty"): 

## Error

```go
type Error struct {
	Code       string        `json:"code"`
	Message    string        `json:"message"`
	Details    []string      `json:"details,omitempty"`
	Gate       *gate.Failure `json:"gate,omitempty"`
	NextAction *NextAction   `json:"next_action,omitempty"`
	ExitCode   int           `json:"exit_code"`
}
```

Error is the stable JSON error payload.

- `Code: string` (json:"code"): 
- `Message: string` (json:"message"): 
- `Details: []string` (json:"details,omitempty"): 
- `Gate: *gate.Failure` (json:"gate,omitempty"): 
- `NextAction: *NextAction` (json:"next_action,omitempty"): 
- `ExitCode: int` (json:"exit_code"): 

## NextAction

```go
type NextAction struct {
	Type    string `json:"type"`
	Command string `json:"command,omitempty"`
	Reason  string `json:"reason,omitempty"`
}
```

NextAction describes the next machine-actionable step for JSON callers.

- `Type: string` (json:"type"): 
- `Command: string` (json:"command,omitempty"): 
- `Reason: string` (json:"reason,omitempty"):