docs: add CONTRIBUTING.md

00_STATE.md

@@ -0,0 +1,64 @@
+# 00_STATE.md — agentmail-cli
+
+## Repository Status
+
+| Field | Value |
+| ----- | ----- |
+| **Upstream** | agentmail-to/agentmail-cli |
+| **Fork** | okwn/agentmail-cli (cloned to /root/oss-pr-campaign/repos/agentmail-cli) |
+| **Archived** | false |
+| **License** | Apache-2.0 |
+| **Language** | Go |
+| **Default Branch** | main |
+| **Stars** | 21 |
+| **Forks** | 7 |
+| **Open Issues** | 3 |
+| **Open PRs** | 2 |
+
+## Current Branch
+
+- Local: `main`
+- Upstream: `upstream/main`
+- All remotes: `origin/*` (fork), `upstream/*`
+
+## CI Status
+
+- `.github/workflows/ci.yml` — lint, build, test jobs on push/PR
+- `.github/workflows/publish-release.yml`
+- `.github/workflows/release-doctor.yml`
+- `.github/workflows/auto-merge-release.yml`
+- Go 1.25, depot-ubuntu-24.04 or ubuntu-latest
+
+## Key Scripts
+
+- `./scripts/bootstrap` — installs Go deps (needs `go` binary)
+- `./scripts/lint` — runs lints
+- `./scripts/test` — runs `go test ./...` + Windows cross-compile test
+- `./scripts/build` — runs goreleaser
+- `./scripts/format`, `./scripts/run`, `./scripts/link`, `./scripts/unlink`
+
+## Go Module
+
+- Module: `github.com/agentmail-to/agentmail-cli`
+- Go version: `1.25`
+- Private deps: `github.com/agentmail-to/agentmail-go`, `github.com/stainless-sdks/agentmail-go`
+- NPM package: `agentmail-cli@0.4.1` (published to npm)
+
+## Release
+
+- Release-please configured (`release-please-config.json`)
+- Goreleaser configured (`.goreleaser.yml`)
+- Version tracked in: `pkg/cmd/version.go`, `README.md`
+- Extra files for release-please: `pkg/cmd/version.go`, `README.md`
+
+## Build/Release Notes
+
+- Bootstrap requires `go` binary in PATH (not available in this environment)
+- npm `postinstall` script present at `npm/scripts/postinstall.js`
+- Binary published via npm (`./npm/bin/agentmail`)
+
+## Environment
+
+- `go` binary NOT available in this environment — cannot run tests/bootstrap
+- GitHub CLI (`gh`) available for API queries
+- Python not noted as required

01_REPO_MAP.md

@@ -0,0 +1,126 @@
+# 01_REPO_MAP.md — agentmail-cli
+
+## Repository Structure
+
+```
+agentmail-cli/
+├── cmd/agentmail/
+│   ├── main.go          # Entry point
+│   └── banner.go        # CLI banner
+├── pkg/cmd/             # All CLI commands (generated from OpenAPI)
+│   ├── cmd.go           # Root command, flag definitions, all subcommands
+│   ├── version.go       # Version constant
+│   ├── cmdutil.go       # Utility functions
+│   ├── flagoptions.go   # Flag option handling
+│   ├── agent.go / agent_test.go
+│   ├── apikey.go / apikey_test.go
+│   ├── domain.go / domain_test.go
+│   ├── draft.go / draft_test.go
+│   ├── inbox.go / inbox_test.go
+│   ├── list.go / list_test.go
+│   ├── metric.go / metric_test.go
+│   ├── organization.go / organization_test.go
+│   ├── pod.go / pod_test.go
+│   ├── podapikey.go / podapikey_test.go
+│   ├── poddomain.go / poddomain_test.go
+│   ├── poddraft.go / poddraft_test.go
+│   ├── podinbox.go / podinbox_test.go
+│   ├── podlist.go / podlist_test.go
+│   ├── podmetric.go / podmetric_test.go
+│   ├── podthread.go / podthread_test.go
+│   ├── thread.go / thread_test.go
+│   ├── webhook.go / webhook_test.go
+│   └── flagoptions_test.go
+├── internal/
+│   ├── apiform/         # Form encoding for requests
+│   ├── apiquery/        # Query encoding
+│   ├── autocomplete/    # Shell completion scripts
+│   │   └── shellscripts/  # bash, zsh, fish, pwsh completions
+│   ├── binaryparam/     # Binary file parameter handling
+│   ├── debugmiddleware/ # Debug HTTP middleware
+│   ├── jsonview/        # JSON explorer/viewer
+│   ├── mocktest/        # Mock testing utilities
+│   └── requestflag/     # Core flag parsing (handles @file, YAML, etc.)
+│       ├── requestflag.go    # Flag[T] generic type, parsing logic
+│       ├── requestflag_test.go
+│       ├── innerflag.go      # Inner flags for nested objects
+│       └── innerflag_test.go
+├── npm/                 # NPM package for distribution
+│   ├── package.json     # 0.4.1, agentmail-cli
+│   ├── bin/agentmail
+│   ├── scripts/postinstall.js
+│   └── README.md
+├── .github/
+│   ├── actions/setup-go/
+│   └── workflows/
+│       ├── ci.yml
+│       ├── publish-release.yml
+│       ├── release-doctor.yml
+│       └── auto-merge-release.yml
+├── scripts/
+│   ├── bootstrap
+│   ├── lint
+│   ├── test
+│   ├── build
+│   ├── format
+│   ├── run
+│   ├── link
+│   ├── unlink
+│   └── utils/upload-artifact.sh
+├── .goreleaser.yml      # Build config (macos, linux, windows; nfpms)
+├── release-please-config.json
+├── go.mod / go.sum
+├── .stats.yml           # 94 configured endpoints
+├── SKILL.md             # Skill documentation
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+├── SECURITY.md
+└── .release-please-manifest.json
+```
+
+## API Resources (from cmd.go)
+
+| Resource Group | Commands |
+|---|---|
+| `agent` | sign-up, verify |
+| `inboxes` | create, update, list, delete, get, list-metrics |
+| `inboxes:drafts` | create, update, list, delete, get, get-attachment, send |
+| `inboxes:messages` | update, list, forward, get, get-attachment, get-raw, reply, reply-all, send |
+| `inboxes:threads` | list, delete, get, get-attachment |
+| `inboxes:lists` | create, list, delete, get |
+| `inboxes:api-keys` | create, list, delete |
+| `pods` | create, list, delete, get |
+| `pods:domains` | create, update, list, delete, get, get-zone-file, verify |
+| `pods:drafts` | list, get, get-attachment |
+| `pods:inboxes` | create, update, list, delete, get |
+| `pods:threads` | list, delete, get, get-attachment |
+| `pods:lists` | create, list, delete, get |
+| `pods:api-keys` | create, list, delete |
+| `pods:metrics` | query |
+| `webhooks` | create, update, list, delete, get |
+| `api-keys` | create, list, delete |
+| `domains` | create, update, list, delete, get, get-zone-file, verify |
+| `drafts` | list, get, get-attachment |
+| `lists` | create, list, delete, get |
+| `metrics` | list |
+| `organizations` | get |
+| `threads` | list, delete, get, get-attachment |
+
+## Key Dependencies
+
+- `github.com/agentmail-to/agentmail-go v0.14.0` — API client
+- `github.com/urfave/cli/v3 v3.3.2` — CLI framework
+- `github.com/charmbracelet/bubbletea v1.3.6` — TUI
+- `github.com/goccy/go-yaml v1.18.0` — YAML parsing
+- `github.com/tidwall/gjson v1.18.0` — JSON query/transform
+
+## Branches
+
+| Branch | Description |
+|---|---|
+| `main` | Primary branch |
+| `next` | Next version branch |
+| `improve-readme` | Upstream branch for README improvement |
+| `jarvis/improve-readme` | Another upstream branch (PR #20) |
+| `generated` | Codegen output branch |

05_PR_CANDIDATES.md

@@ -0,0 +1,49 @@
+# 05_PR_CANDIDATES.md — agentmail-cli
+
+## Open Issues
+
+### Issue #13 — "fix: change goreleaser nfpms bindir to /usr/bin"
+- **Severity**: Low (packaging fix)
+- **Effort**: Very low (1-line change in `.goreleaser.yml`)
+- **PR exists**: Yes — PR #13 from mtzanidakis (open)
+- **Status**: Straightforward. Change `bindir: /usr` → `bindir: /usr/bin` in `.goreleaser.yml` line 71.
+- **Risk**: Very low — only affects Linux package install path
+- **Blocker**: None
+
+### Issue #17 — "CLI parses string flags containing colons as YAML objects"
+- **Severity**: High (functional bug — causes 400 API errors)
+- **Effort**: Medium (requires understanding `requestflag.go` parsing logic)
+- **PR exists**: No
+- **Root cause**: In `internal/requestflag/requestflag.go`, the `parseCLIArg` function falls through to `yaml.Unmarshal` for flags typed as `any`. Valid YAML strings like `"S4: test"` get deserialized as `map[string]any{"S4": "test"}` instead of being kept as plain strings. The `allowAsLiteralString` fallback only triggers when YAML parsing *fails*.
+- **Affected**: any string flag value containing a colon (`:), e.g., `--subject "S4: test"`, `--subject "BCC test"`
+- **Fix approach**: Check if the YAML-parsed result is a map with a single string key before treating it as an object; if so, treat it as a literal string.
+- **Risk**: Low — targeted change in parsing fallback
+- **Blocker**: None
+
+### Issue #20 — "Improve README — add badge, Homebrew install, links"
+- **Severity**: Low (documentation)
+- **Effort**: Very low
+- **PR exists**: Yes — PR #20 from `agentmail-to:jarvis/improve-readme` (open)
+- **Status**: PR already exists on upstream. README is already fairly complete with npm install instructions and usage examples.
+- **Blocker**: None (already addressed by upstream PR)
+
+## Open Pull Requests
+
+### PR #13 — "fix: change goreleaser nfpms bindir to /usr/bin"
+- From: `mtzanidakis/agentmail-cli` (fork)
+- Target: `agentmail-to:main`
+- Head: `main` (ff159d828d4e1c1116c461202acaa0ce35d0e287)
+- Mergeable: Unknown (needs CI check)
+- Status: Needs review/merge
+
+### PR #20 — "Improve README — add badge, Homebrew install, links"
+- From: `agentmail-to:jarvis/improve-readme`
+- Target: `agentmail-to:main`
+- Head: `187b67d10664f774f5666ae18372449274b080a9`
+- Mergeable: Unknown
+- Status: Needs review/merge
+
+## Notes
+
+- The `internal/requestflag/` code is generated from Stainless API spec (`stainless-api/stainless-api-cli`), so any fix to #17 may need to be applied upstream in the generator as well.
+- Bootstrap script requires `go` binary — not available in this environment, so tests cannot be run locally.

06_SELECTED_5_PR_PLAN.md

@@ -0,0 +1,42 @@
+# 06_SELECTED_5_PR_PLAN.md — agentmail-cli
+
+## Selected Candidates (Top 5)
+
+Given the available issues and PRs, the following are ranked by impact and ease:
+
+### 1. Issue #13 — Fix goreleaser nfpms bindir (`/usr` → `/usr/bin`)
+- **File**: `.goreleaser.yml` line 71
+- **Change**: `bindir: /usr` → `bindir: /usr/bin`
+- **Why**: Straightforward, low-risk, already has PR #13 from mtzanidakis that can be reviewed/merged
+- **Impact**: Ensures Linux packages (deb/rpm/apk) install binary to `/usr/bin` instead of `/usr`
+
+### 2. Issue #17 — Fix colon-in-string YAML parsing bug
+- **File**: `internal/requestflag/requestflag.go`
+- **Change**: In `parseCLIArg`, detect when a YAML-parsed map has a single string key and treat as literal string instead of object
+- **Why**: High severity bug causing API 400 errors for legitimate subject lines and other string fields
+- **Impact**: Fixes CLI usability for any user whose data contains colons (e.g., "Re: S4: test", "BCC:", etc.)
+- **Note**: Generated code may need corresponding fix upstream in Stainless CLI generator
+
+### 3. PR #20 Review — README improvement
+- **Action**: Review and potentially merge existing upstream PR #20 (`jarvis/improve-readme`)
+- **Changes**: npm badge, better description, Homebrew install, links
+- **Why**: Low effort, improves first-impression and installation options
+- **Note**: Already exists as upstream PR — no new PR needed, just needs review/merge from maintainers
+
+## What Was Not Selected
+
+- **Issue #20 (as new PR)**: Already addressed by existing PR #20 from upstream branch. Not worth duplicating effort.
+- **Codegen/generated code**: The repository is auto-generated from OpenAPI via Stainless. Direct modifications to generated files (`pkg/cmd/*.go`) would be overwritten by codegen. Changes should go through the Stainless pipeline.
+- **NPM packaging**: Works correctly; no issues filed.
+
+## Execution Plan
+
+1. **For Issue #13**: Apply 1-line fix to `.goreleaser.yml` locally, commit, push to `okwn/agentmail-cli`, open PR targeting `agentmail-to:main`
+2. **For Issue #17**: Study `parseCLIArg` fallback logic in `internal/requestflag/requestflag.go`, implement fix, add test case in `requestflag_test.go`, commit, push, open PR
+3. **For PR #20**: Since it's already an upstream PR, assist by reviewing/testing the existing changes rather than duplicating
+
+## Environment Notes
+
+- `go` binary NOT available — cannot run `bootstrap`, `test`, or `lint` locally
+- Tests must be validated via CI after PR is opened (CI runs on fork PRs)
+- All Go code is syntactically parseable at least

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to AgentMail CLI
+
+Thank you for your interest in contributing to AgentMail CLI!
+
+## Getting Started
+
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Set your API key: `export AGENTMAIL_API_KEY=your_key`
+
+## Development
+
+```sh
+# Run locally
+npm link
+agentmail [command]
+
+# Run tests
+npm test
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Run tests: `npm test`
+5. Submit a pull request
+
+## Style Guide
+
+- Use clear, descriptive commit messages
+- Add tests for new functionality
+- Update documentation as needed