Add agent-prompt command and restructure documentation

.changeset/add-agent-prompt-command.md

@@ -0,0 +1,5 @@
+---
+"@alchemy/cli": minor
+---
+
+Add `agent-prompt` command that emits complete automation/agent usage instructions including execution policy, auth methods, error codes, and command schema.

AGENTS.md

@@ -4,7 +4,7 @@
 Keep all terminal output visually consistent with existing Alchemy CLI conventions used by help, tables, and command output.
 
 ## Core Principles
-- Prefer shared style helpers in `src/lib/ui.ts` and `src/lib/output.ts` over ad-hoc ANSI strings.
+- Prefer shared style helpers in `src/lib/ui.ts`, `src/lib/output.ts`, and `src/lib/error-format.ts` over ad-hoc ANSI strings.
 - Use one visual voice: indented blocks, compact spacing, and consistent symbols (`◆` for section headers, `✗` for errors, `✓` for success).
 - Keep copy short and actionable.
 

MAINTAINERS.md

@@ -0,0 +1,119 @@
+# Maintainers Guide
+
+Maintainer-focused operational docs for release management and advanced local testing.
+For general usage and contributor setup, see `README.md`.
+
+## Local Development
+
+Prerequisites:
+
+- [Node.js 22+](https://nodejs.org/)
+- [pnpm](https://pnpm.io/)
+
+### Setup
+
+```bash
+git clone https://github.com/alchemyplatform/alchemy-cli.git
+cd alchemy-cli
+pnpm install
+pnpm build
+pnpm link --global
+```
+
+This makes the local `alchemy` build available globally for testing.
+To unlink later: `pnpm unlink --global`.
+
+### Common Commands
+
+Run during development:
+
+```bash
+# Run without building
+npx tsx src/index.ts balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# Build in watch mode
+pnpm dev
+```
+
+Build:
+
+```bash
+pnpm build
+```
+
+Test:
+
+```bash
+pnpm test
+pnpm test:e2e
+```
+
+Type check:
+
+```bash
+pnpm lint
+```
+
+Coverage:
+
+```bash
+pnpm test:coverage
+```
+
+## Changesets And Releasing
+
+This project uses [Changesets](https://github.com/changesets/changesets) for versioning and release notes.
+
+**When to add a changeset:** Any PR with user-facing changes (new commands, bug fixes, flag changes, output format changes) needs a changeset. Internal changes (CI, refactors with no behavior change, docs) can skip by adding the `no-changeset` label.
+
+**How to add a changeset:**
+
+```bash
+pnpm changeset
+```
+
+You will be prompted to pick the bump type:
+- **patch** - bug fixes, small tweaks (for example fixing `--json` output for a command)
+- **minor** - new commands, new flags, new capabilities
+- **major** - breaking changes (removed commands, changed flag behavior, output format changes)
+
+This creates a file like `.changeset/cool-dogs-fly.md`:
+
+```markdown
+---
+"@alchemy/cli": minor
+---
+
+Add `alchemy portfolio transactions` command for portfolio transaction history.
+```
+
+Write a 1-2 sentence summary of the change from a user's perspective. Commit this file with your PR.
+
+**How releases work:** When PRs with changesets merge to `main`, the publish workflow automatically:
+1. Verifies the build (typecheck, build, test)
+2. Applies version bumps and updates `CHANGELOG.md` via `changeset version`
+3. Creates a signed release commit via the GitHub Git Database API (using a GitHub App token)
+4. Publishes to npm using OIDC trusted publishing (no long-lived npm token)
+5. Creates a GitHub release/tag with notes extracted from `CHANGELOG.md`
+
+If no changesets are pending, the workflow exits cleanly and no release is created.
+
+**Release infrastructure:**
+- Repository write operations use a GitHub App (`APP_ID` variable + `APP_PRIVATE_KEY` secret)
+- npm publish uses [trusted publishing](https://docs.npmjs.com/generating-provenance-statements) (OIDC), so no `NPM_TOKEN` secret is required
+- Required GitHub repo settings: `APP_ID` (variable), `APP_PRIVATE_KEY` (secret)
+- Required npm-side: configure trusted publishing for this repo/workflow at npm package settings
+
+## Endpoint Override Env Vars (Local Testing Only)
+
+These are for local/mock testing, not normal production usage:
+
+- `ALCHEMY_RPC_BASE_URL`
+- `ALCHEMY_ADMIN_API_BASE_URL`
+- `ALCHEMY_X402_BASE_URL`
+
+Safety constraints:
+
+- Only localhost targets are accepted (`localhost`, `127.0.0.1`, `::1`)
+- Non-HTTPS transport is allowed only for localhost
+- Production defaults are unchanged when unset

README.md

@@ -18,6 +18,58 @@ Or run without installing globally:
 npx @alchemy/cli <command>
 ```
 
+## Getting Started
+
+### Authentication Quick Start
+
+Authentication is required before making requests. Configure auth first, then run commands.
+
+If you are using the CLI as a human in an interactive terminal, the easiest path is:
+
+```bash
+alchemy
+```
+
+Then follow the setup flow in the terminal UI to configure auth.
+
+Know which auth method does what:
+
+- **API key** - direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
+- **Access key** - Admin/API app management; app setup/selection can also provide API key auth for blockchain queries
+- **x402 wallet auth** - wallet-authenticated, pay-per-request model for supported blockchain queries
+
+If you use Notify webhooks, add webhook auth on top via `alchemy config set webhook-api-key <key>`, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`.
+
+For setup commands, env vars, and resolution order, see [Authentication Reference](#authentication-reference).
+
+### Usage By Workflow
+
+After auth is configured, use the CLI differently depending on who is driving it:
+
+- **Humans (interactive terminal):** start with `alchemy` and use the terminal UI/setup flow; this is the recommended path for human usage
+- **Agents/scripts (automation):** always use `--json` and prefer non-interactive execution (`--no-interactive`)
+
+Quick usage examples:
+
+```bash
+# Human recommended entrypoint
+alchemy
+
+# Agent/script-friendly command
+alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --json --no-interactive
+```
+
+#### Agent bootstrap
+
+Have your agent run `agent-prompt` as its first step to get a complete, machine-readable contract describing every command, auth method, error code, and execution rule:
+
+```bash
+# Agent runs this once to learn everything the CLI can do
+alchemy --json agent-prompt
+```
+
+This returns a single JSON document with execution policy, preflight instructions, auth matrix, the full command tree with all arguments and options, error codes with recovery actions, and example invocations. No external docs required.
+
 ## Command Reference
 
 Run commands as `alchemy <command>`.
@@ -103,6 +155,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 | `config get <key>` | Gets one config value | `alchemy config get network` |
 | `config list` | Lists all config values | `alchemy config list` |
 | `config reset [key]` | Resets one or all config values | `alchemy config reset --yes` |
+| `agent-prompt` | Emits complete agent/automation usage instructions | `alchemy --json agent-prompt` |
 | `version` | Prints CLI version | `alchemy version` |
 
 ## Flags
@@ -176,13 +229,13 @@ Additional env vars:
 | `network list` | `--configured`, `--app-id <id>` |
 | `config reset` | `-y, --yes` |
 
-## Authentication
+## Authentication Reference
 
 The CLI supports three auth inputs:
 
 - API key for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
-- Access key for Admin API operations (`apps`, `chains`, configured network lookups)
-- x402 wallet key for wallet-authenticated blockchain queries
+- Access key for Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands
+- x402 wallet key for wallet-authenticated blockchain queries in a pay-per-request model
 
 Notify/webhook commands use a webhook API key with resolution order:
 `--webhook-api-key` -> `ALCHEMY_WEBHOOK_API_KEY` -> `ALCHEMY_NOTIFY_AUTH_TOKEN` -> config `webhook-api-key` -> configured app webhook key.
@@ -221,6 +274,9 @@ Resolution order: `--access-key` -> `ALCHEMY_ACCESS_KEY` -> config file.
 
 #### x402 wallet auth
 
+x402 is a wallet-authenticated, pay-per-request usage model for supported blockchain queries.
+The CLI can generate or import the wallet key used for these requests.
+
 ```bash
 # Generate/import a wallet managed by CLI
 alchemy wallet generate
@@ -277,116 +333,3 @@ Errors are structured JSON in JSON mode:
   }
 }
 ```
-
-## Development
-
-Prerequisites:
-
-- [Node.js 22+](https://nodejs.org/)
-- [pnpm](https://pnpm.io/)
-
-### Local development setup
-
-```bash
-git clone https://github.com/alchemyplatform/alchemy-cli.git
-cd alchemy-cli
-pnpm install
-pnpm build
-pnpm link --global
-```
-
-This makes the local `alchemy` build available globally for testing.
-To unlink later: `pnpm unlink --global`.
-
-Run during development:
-
-```bash
-# Run without building
-npx tsx src/index.ts balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-
-# Build in watch mode
-pnpm dev
-```
-
-Build:
-
-```bash
-pnpm build
-```
-
-Test:
-
-```bash
-pnpm test
-pnpm test:e2e
-```
-
-Type check:
-
-```bash
-pnpm lint
-```
-
-Coverage:
-
-```bash
-pnpm test:coverage
-```
-
-### Changesets & Releasing
-
-This project uses [Changesets](https://github.com/changesets/changesets) for versioning and release notes.
-
-**When to add a changeset:** Any PR with user-facing changes (new commands, bug fixes, flag changes, output format changes) needs a changeset. Internal changes (CI, refactors with no behavior change, docs) can skip by adding the `no-changeset` label.
-
-**How to add a changeset:**
-
-```bash
-pnpm changeset
-```
-
-You'll be prompted to pick the bump type:
-- **patch** — bug fixes, small tweaks (e.g. fixing `--json` output for a command)
-- **minor** — new commands, new flags, new capabilities
-- **major** — breaking changes (removed commands, changed flag behavior, output format changes)
-
-This creates a file like `.changeset/cool-dogs-fly.md`:
-
-```markdown
----
-"@alchemy/cli": minor
----
-
-Add `alchemy portfolio transactions` command for portfolio transaction history.
-```
-
-Write a 1-2 sentence summary of the change from a user's perspective. Commit this file with your PR.
-
-**How releases work:** When PRs with changesets merge to `main`, the publish workflow automatically:
-1. Verifies the build (typecheck, build, test)
-2. Applies version bumps and updates `CHANGELOG.md` via `changeset version`
-3. Creates a signed release commit via the GitHub Git Database API (using a GitHub App token)
-4. Publishes to npm using OIDC trusted publishing (no long-lived npm token)
-5. Creates a GitHub release/tag with notes extracted from `CHANGELOG.md`
-
-If no changesets are pending, the workflow exits cleanly — no release is created.
-
-**Release infrastructure:**
-- Repository write operations use a GitHub App (`APP_ID` variable + `APP_PRIVATE_KEY` secret)
-- npm publish uses [trusted publishing](https://docs.npmjs.com/generating-provenance-statements) (OIDC) — no `NPM_TOKEN` secret required
-- Required GitHub repo settings: `APP_ID` (variable), `APP_PRIVATE_KEY` (secret)
-- Required npm-side: configure trusted publishing for this repo/workflow at npmjs.com package settings
-
-### Endpoint Override Env Vars (Local Testing Only)
-
-These are for local/mock testing, not normal production usage:
-
-- `ALCHEMY_RPC_BASE_URL`
-- `ALCHEMY_ADMIN_API_BASE_URL`
-- `ALCHEMY_X402_BASE_URL`
-
-Safety constraints:
-
-- Only localhost targets are accepted (`localhost`, `127.0.0.1`, `::1`)
-- Non-HTTPS transport is allowed only for localhost
-- Production defaults are unchanged when unset