diff --git a/.gitignore b/.gitignore
index 8f877a5..1b3d408 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,6 @@ secrets
 
 # Man pages
 man/
+
+# Agent scratch space
+scratch/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..899fde9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,131 @@
+# AGENTS.md — Pinecone CLI
+
+Guide for AI agents and assistants contributing to this repository.
+
+---
+
+## Project overview
+
+`pc` is the official Pinecone CLI — open source, public preview.
+
+- **Entry point:** `cmd/pc/main.go` → `cliRootCmd.Execute()` (package `internal/pkg/cli/command/root`)
+- **Module:** `github.com/pinecone-io/cli`
+
+---
+
+## Tech stack
+
+| Concern | Library |
+|---|---|
+| CLI framework | `github.com/spf13/cobra` — hierarchical subcommands |
+| Config | `github.com/spf13/viper` — YAML config files in `~/.config/pinecone/` |
+| Pinecone client | `github.com/pinecone-io/go-pinecone/v5` |
+| Auth | `github.com/golang-jwt/jwt/v5`, `golang.org/x/oauth2` |
+| TUI / output | `github.com/charmbracelet/bubbletea`, `github.com/charmbracelet/lipgloss`, `github.com/fatih/color` |
+| Logging | `github.com/rs/zerolog` |
+| Testing | `github.com/stretchr/testify` |
+| Go version | 1.24.0 |
+
+---
+
+## Architecture
+
+### Command hierarchy
+
+```
+pc [group] [command] [subcommand]
+# e.g. pc index vector upsert
+```
+
+Four root groups (defined in `internal/pkg/cli/command/root/root.go`):
+
+| Group | Commands |
+|---|---|
+| **Auth** | auth, login, logout, target, whoami |
+| **Admin** | organization, project, apiKey |
+| **VectorDB** | index, collection, backup |
+| **Misc** | version, config |
+
+### Presenter system
+
+Output formatting lives in `internal/pkg/utils/presenters/` — one file per output type. Command handlers stay thin; all rendering is delegated to presenters.
+
+### Credential resolution
+
+Three auth methods, resolved in `internal/pkg/utils/sdk/` and `internal/pkg/utils/oauth/`:
+
+| Priority | Method | Env vars |
+|---|---|---|
+| 1 (highest) | API key | `PINECONE_API_KEY` |
+| 2 | Service account | `PINECONE_CLIENT_ID`, `PINECONE_CLIENT_SECRET` |
+| 3 | User login (OAuth2 PKCE) | stored token in `~/.config/pinecone/secrets.yaml` |
+
+API key mode does not require a target project to be set. OAuth and service account modes do.
+
+Credentials and tokens are stored in `~/.config/pinecone/`. The directory holds two files:
+
+- `config.yaml` — non-secret settings (`color`, `environment`)
+- `secrets.yaml` — credentials and tokens (`api_key`, `client_id`, `client_secret`, `oauth2_token`); created with `0600` permissions
+
+### Input handling
+
+`internal/pkg/utils/argio/` unifies three JSON input methods:
+
+| Method | Usage |
+|---|---|
+| Inline | Pass JSON directly as a flag value |
+| File | Pass a `.json` or `.jsonl` file path |
+| Stdin | Pass `-` to read from stdin |
+
+### `--json` flag
+
+Available on most commands. Forces structured, machine-readable output. Also activated automatically when stdout is not a TTY.
+
+---
+
+## Key directories
+
+| Path | Purpose |
+|---|---|
+| `cmd/pc/` | Entry point |
+| `internal/pkg/cli/command/` | All command implementations, organized by domain (`index/`, `auth/`, `project/`, etc.) |
+| `internal/pkg/utils/` | Shared utilities: presenters, sdk, oauth, argio, flags, configuration, etc. |
+| `test/e2e/` | End-to-end integration tests |
+
+---
+
+## Build & test commands
+
+```bash
+just build                                    # goreleaser build for current OS → ./dist/
+just build-all                                # goreleaser build for all supported OSes
+just test-unit                                # go test -v ./... (no external deps required)
+just test-e2e                                 # builds binary, runs E2E suite (requires credentials)
+just gen-manpages                             # generate man pages → ./man/
+go test -v -run TestNameHere ./internal/...   # run a single test by name
+```
+
+E2E tests require a `.env` file at the repo root:
+
+```
+PINECONE_API_KEY=...
+PINECONE_CLIENT_ID=...
+PINECONE_CLIENT_SECRET=...
+```
+
+---
+
+## Code style & conventions
+
+- Always run `gofmt`. Zero `go vet` warnings allowed.
+- `PascalCase` for exported symbols, `camelCase` for unexported. Acronyms uppercase: `URL`, `HTTP`, `API`, `ID`.
+- All exported symbols require a GoDoc comment starting with the symbol name.
+- Return errors; do not panic. Wrap with `fmt.Errorf("context: %w", err)`.
+- Pass `context.Context` as the first parameter of any function that does I/O.
+- Unit test function names follow the pattern `Test<FunctionName>` or `Test<FunctionName>_<Scenario>`. E2E tests live in `test/e2e/` and use the `//go:build e2e` build tag — `just test-unit` excludes them automatically.
+
+---
+
+## Scratch directory
+
+`scratch/` is gitignored — use it freely for agent-generated temporary files, plans, and notes.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md