# Coding Guidelines

Hard rules for code quality. Every agent and contributor must reference this document before writing code. These are not suggestions: they are enforced.

## Return Values

Never return more than two values from a function unless one of them is `error`. If you need to return multiple pieces of data, use a struct.

**Bad:**
```go
func fetch(host, path string) (string, string, string, error)
```
Three unnamed strings: what's the order? What does each one mean? The caller has to guess or read the implementation.

**Good:**
```go
type FetchResult struct {
    Status string
    Body   string
    Etag   string
}

func fetch(host, path string) (FetchResult, error)
```

Named fields, self-documenting, impossible to mix up.

## Don't Duplicate Logic

If the same logic exists in more than one place, extract it. Duplicated code leads to inconsistencies when one copy gets updated and the others don't.

**Example:** Token resolution was duplicated across CLI, TUI, and MCP; each had its own inline version of "load store, check env, check flag." One shared `tokens.Resolve` function replaced all of them and ensured consistent behavior everywhere.

When you see duplication:
1. Extract to a shared function in the appropriate package
2. Update all call sites
3. Delete the old copies

## Function Signatures

Keep function signatures honest and minimal:
- If a parameter can be empty/zero and that's fine, document it
- Don't add parameters "for future use": add them when needed
- Prefer structs over long parameter lists (more than 4 parameters is a smell)

## Shared Behavior Across Clients

CLI, TUI, and MCP must behave consistently. If a feature works one way in the CLI, it must work the same way in TUI and MCP. Shared logic belongs in `client/internal/` packages, not duplicated in each `cmd/` directory.

When implementing a feature that touches multiple clients:
1. Put the core logic in an internal package
2. Each client calls the shared code
3. Test the shared code once, not three times

## Error Handling

- Always handle errors at the point they occur
- Never ignore errors silently (except with a documented reason)
- Wrap errors with context: `fmt.Errorf("fetch %s: %w", path, err)`

## Naming

- Use descriptive names that convey meaning
- Avoid single-letter variables except for loop counters and short closures
- Struct fields should be self-documenting: if a field needs a comment, consider renaming it