@agnic/wallet-skills 1.3.3 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [2.0.0] - 2026-04-12
+
+### Breaking Changes
+- Removed `agnic` unified meta-skill. Use individual skills instead.
+- `pay-for-service` now requires explicit user invocation (`disable-model-invocation: true`). Claude will no longer auto-invoke payments.
+- Removed all deprecated root-level `.md` skill files. Only `skills/*/SKILL.md` format is supported.
+- `agent-email` migrated from legacy `.md` format to `agent-email/SKILL.md`.
+
+### Added
+- **Headless authentication** via `AGNIC_TOKEN` env var and `--token` flag. AI agents, CI pipelines, and servers can now authenticate without a browser.
+- `agent-email/SKILL.md` — full production-quality skill with proper frontmatter, input validation, and error handling.
+- `context: fork` on `pay-for-service` and `ai-gateway` for execution isolation.
+- Progressive disclosure: `reference/` directories for `ai-gateway` and `pay-for-service` with extracted reference material.
+
+### Changed
+- All skills: standardized authentication section with dual-mode support (browser OAuth + headless token).
+- All skills: optimized descriptions for Claude discovery with front-loaded trigger keywords.
+- All skills: scoped `allowed-tools` patterns (no wildcards).
+- Rebranded "AgnicPay" references to "Agnic" throughout.
+- Updated install command from `agnicpay/` to `agnic-protocol/` org.
+- Updated npm keywords: added `claude-code`, `erc-8004`, `headless-auth`; removed `agnicpay`, `vercel-ai`.
+
+### Fixed
+- **Security**: `pay-for-service` could be auto-invoked by Claude, spending real USDC without explicit user consent.
+- **Headless auth**: AI agents in non-interactive environments now have a working authentication path.
+- `agent-email` had no proper `SKILL.md` — only a deprecated `.md` file with no `allowed-tools` or frontmatter fields.

package/README.md

@@ -1,32 +1,54 @@
-# AgnicPay Agentic Wallet Skills
+# Agnic Wallet Skills for Claude Code
 
-Agent Skills for crypto wallet operations. These skills enable AI agents to authenticate, check balances, make x402 payments, access 340+ AI models, generate images, and verify on-chain identity using the `agnic` CLI.
+Give your AI agent a crypto wallet, payments, email, and on-chain identity.
+
+These skills enable AI agents to authenticate, check balances, make x402 payments, access 340+ AI models, generate images, manage agent email, and verify on-chain identity using the `agnic` CLI.
 
 ## Available Skills
 
-| Skill | Description |
-|-------|-------------|
-| **authenticate-wallet** | Sign in to the wallet via browser OAuth |
-| **check-balance** | Check USDC balance across networks (Base, Solana) |
-| **search-for-service** | Search for paid API services via x402 |
-| **pay-for-service** | Make paid API requests via x402 |
-| **fund-wallet** | Get instructions for adding funds to the wallet |
-| **get-agent-identity** | Check on-chain ERC-8004 identity and trust score |
-| **agent-email** | Manage agent email — send, receive, check inbox |
-| **ai-gateway** | Access 340+ AI models — chat, image generation (GPT, Claude, Gemini, Llama, Flux) |
-| **agnic** | Unified skill — all wallet, payment, email, identity, and AI gateway capabilities |
+| Skill | Description | Side Effects |
+|-------|-------------|--------------|
+| **authenticate-wallet** | Sign in via browser OAuth or headless API token | None |
+| **check-balance** | Check USDC balance across networks (Base, Solana) | None |
+| **search-for-service** | Search for paid API services via x402 bazaar | None |
+| **pay-for-service** | Make paid API requests via x402 (USDC) | Spends USDC |
+| **fund-wallet** | Get instructions for adding funds to the wallet | None |
+| **get-agent-identity** | Check on-chain ERC-8004 identity and trust score | None |
+| **agent-email** | Send, receive, and manage agent email | Sends email |
+| **ai-gateway** | Access 340+ AI models -- chat and image generation | Spends USDC |
 
 ## Installation
 
-Install with Vercel's [Skills CLI](https://github.com/vercel/skills):
+Install with the [Skills CLI](https://github.com/vercel/skills):
+
+```bash
+npx skills add agnic-protocol/agnic-wallet-skills
+```
+
+## Authentication
+
+### Interactive (browser available)
+
+```bash
+npx agnic@latest auth login
+```
+
+Opens a browser for OAuth sign-in. Best for local development.
+
+### Headless (CI, servers, AI agents)
+
+Generate an API token at [app.agnic.ai](https://app.agnic.ai) > Settings > API Tokens, then:
 
 ```bash
-npx skills add agnicpay/agnic-wallet-skills
+export AGNIC_TOKEN=<your-api-token>
+npx agnic@latest status --json
 ```
 
+All commands in the session will authenticate automatically. No browser required.
+
 ## Usage
 
-Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
+Skills are automatically available once installed. The agent uses them when relevant tasks are detected.
 
 Examples:
 
@@ -38,6 +60,18 @@ Examples:
 - `List available AI models`
 - `Ask GPT-4o to explain quantum computing`
 - `Generate an image of a sunset over mountains`
+- `Check my agent email inbox`
+- `Send an email to user@example.com`
+
+## Performance
+
+For faster CLI invocations (avoids downloading on every call):
+
+```bash
+npm install -g agnic
+```
+
+Then all `npx agnic@latest` commands run instantly from the global install.
 
 ## Contributing
 
@@ -45,20 +79,12 @@ To add a new skill:
 
 1. Create a folder in `./skills/` with a lowercase, hyphenated name
 2. Add a `SKILL.md` file with YAML frontmatter and instructions
-3. See the [Agent Skills specification](https://github.com/vercel/skills) for the complete format
-
-### Updating the agnic version
-
-All skills pin `agnic@latest` via `npx agnic@latest`. When testing against a specific version:
-
-```bash
-# Install a specific version
-npm install -g agnic@2.0.0
-```
+3. Optionally add a `reference/` directory for detailed documentation
+4. See the [Skills specification](https://github.com/vercel/skills) for the complete format
 
 ## Documentation
 
-Full docs at [docs.agnic.ai/docs/agnicpay-features/skills](https://docs.agnic.ai/docs/agnicpay-features/skills)
+Full docs at [docs.agnic.ai](https://docs.agnic.ai)
 
 ## License
 

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@agnic/wallet-skills",
-  "version": "1.3.3",
-  "description": "Vercel AI SDK skills for AgnicPay wallet — balance, x402, agent identity, and AI gateway",
+  "version": "2.0.0",
+  "description": "Claude Code skills for the Agnic wallet — payments, x402, AI gateway, agent email, and on-chain identity",
   "keywords": [
     "agnic",
-    "agnicpay",
+    "claude-code",
     "skills",
-    "vercel-ai",
     "x402",
     "wallet",
-    "ai-agent"
+    "ai-agent",
+    "erc-8004",
+    "usdc",
+    "headless-auth"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/agnic-protocol/agnic-wallet-skills"
   },
-  "homepage": "https://docs.agnic.ai/docs/agnicpay-features/skills"
+  "homepage": "https://docs.agnic.ai/docs/agnic-features/skills"
 }

package/skills/agent-email/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: agent-email
+description: >
+  Send and receive email as your AI agent. Use when the user wants to
+  check inbox, send email, reply to messages, set up an email alias,
+  or manage agent email. Covers "check my email", "send an email",
+  "what's my agent email", "set up email", "inbox".
+user-invocable: true
+disable-model-invocation: false
+allowed-tools:
+  - "Bash(npx agnic@latest status*)"
+  - "Bash(npx agnic@latest email *)"
+---
+
+# Agent Email
+
+Each agent gets a unique email address in the format `agent-<id>@agnic.ai`. Use `npx agnic@latest email` commands to manage it.
+
+## Authentication
+
+Run `npx agnic@latest status --json` to verify. If not authenticated:
+- **Headless (CI/server/agent)**: Set `AGNIC_TOKEN` env var or pass `--token <token>`
+- **Interactive (has browser)**: Run `npx agnic@latest auth login`
+
+See the `authenticate-wallet` skill for details.
+
+## Commands
+
+### Set up email alias
+
+```bash
+npx agnic@latest email setup --display-name "My Agent" --json
+```
+
+### Check email address
+
+```bash
+npx agnic@latest email address --json
+```
+
+### Check inbox
+
+```bash
+npx agnic@latest email inbox --limit 10 --json
+```
+
+### Send email
+
+```bash
+npx agnic@latest email send --to <address> --subject "<subject>" --body "<body>"
+```
+
+### Reply to a message
+
+```bash
+npx agnic@latest email reply --message-id <id> --body "<reply text>"
+```
+
+## Input Validation
+
+Before constructing commands, validate user-provided values:
+
+- **--to**: Must be a valid email address. Reject if it contains spaces, semicolons, pipes, or backticks.
+- **--subject**: Single-quote the value. Escape internal single quotes.
+- **--body**: Single-quote the value. Escape internal single quotes.
+- **--message-id**: Must be alphanumeric or UUID format.
+
+Do not pass unvalidated user input into the command.
+
+## Important Notes
+
+- Emails are stored with **30-day retention**
+- Display name can be set once during setup
+- Inbox returns most recent messages first
+
+## Prerequisites
+
+- Must be authenticated (`npx agnic@latest status` to check)
+- Agent identity must exist (created automatically during sign-up)
+
+## Error Handling
+
+Common errors:
+
+- "Not authenticated" -- Run `npx agnic@latest auth login` or set `AGNIC_TOKEN`
+- "No email alias found" -- Run `npx agnic@latest email setup` first
+- "Agent not found" -- The user may not have an agent registered; sign up at [app.agnic.ai](https://app.agnic.ai)
+- "Message not found" -- Check the message ID with `email inbox` first

package/skills/ai-gateway/SKILL.md

@@ -1,119 +1,63 @@
 ---
 name: ai-gateway
-description: Access 340+ AI models through the Agnic AI Gateway. Use when the user wants to chat with an AI model, generate images with AI, list available models, delegate a task to another LLM, or get a second opinion. Covers phrases like "ask GPT", "use Claude", "generate an image", "list AI models", "chat with AI", "call a model", "what models are available".
+description: >
+  Access 340+ AI models via the Agnic AI Gateway -- chat, image generation,
+  model listing. Use when the user wants to chat with AI, generate images,
+  ask GPT, use Claude, list models, delegate to another LLM, or get a
+  second opinion. Covers "ask GPT", "use Claude", "generate an image",
+  "list AI models", "call a model".
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest ai *)"]
+context: fork
+allowed-tools:
+  - "Bash(npx agnic@latest status*)"
+  - "Bash(npx agnic@latest ai *)"
 ---
 
 # AI Gateway
 
-Use `npx agnic@latest ai` commands to access 340+ AI models (OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, and more) through the Agnic AI Gateway. Costs are deducted from your USDC balance per token. Free models available for development.
+Access 340+ AI models (OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, and more) through the Agnic AI Gateway. Costs are deducted from your USDC balance per token. Free models available for development.
 
-## Confirm wallet is initialized and authed
+## Authentication
 
-```bash
-npx agnic@latest status
-```
+Run `npx agnic@latest status --json` to verify. If not authenticated:
+- **Headless (CI/server/agent)**: Set `AGNIC_TOKEN` env var or pass `--token <token>`
+- **Interactive (has browser)**: Run `npx agnic@latest auth login`
 
-If not authenticated, refer to the `authenticate-wallet` skill.
+See the `authenticate-wallet` skill for details.
 
-## Command Syntax
+## Commands
 
 ### List models
 
 ```bash
-npx agnic@latest ai models [options]
+npx agnic@latest ai models [--provider <name>] [--search <term>] [--json]
 ```
 
 ### Chat with a model
 
 ```bash
-npx agnic@latest ai chat --model <id> --prompt "<text>" [options]
+npx agnic@latest ai chat --model <provider/model-name> --prompt "<text>" [--system "<text>"] [--json]
 ```
 
 ### Generate an image
 
 ```bash
-npx agnic@latest ai image --prompt "<text>" [options]
+npx agnic@latest ai image --prompt "<text>" [--aspect-ratio 16:9] [--output file.png] [--json]
 ```
 
-## Model Format
-
-Models use `provider/model-name` format:
-
-| Provider | Example Models |
-| ----------- | ----------------------------------------- |
-| openai | `openai/gpt-4o`, `openai/gpt-4-turbo` |
-| anthropic | `anthropic/claude-3.5-sonnet` |
-| google | `google/gemini-2.5-flash-image`, `google/gemma-*` |
-| meta-llama | `meta-llama/llama-3.3-70b` |
-| mistralai | `mistralai/mistral-large-latest` |
-| deepseek | `deepseek/deepseek-chat` |
-
-Free models: `meta-llama/*`, `google/gemma-*`, `mistralai/*`
-
-## Options
-
-### ai models
-
-| Option | Description |
-| -------------------- | ---------------------------------------- |
-| `--provider <name>` | Filter by provider (e.g., openai) |
-| `--search <term>` | Search in model name |
-| `--json` | Output as JSON |
-
-### ai chat
-
-| Option | Description |
-| ----------------------- | ---------------------------------------- |
-| `--model <id>` | Model ID (required) |
-| `--prompt <text>` | User message (required) |
-| `--system <text>` | System prompt |
-| `--temperature <n>` | Temperature 0-2 (default: 0.7) |
-| `--max-tokens <n>` | Max tokens in response |
-| `--json` | Output as JSON |
-
-### ai image
-
-| Option | Description |
-| ------------------------- | ---------------------------------------- |
-| `--prompt <text>` | Image description (required) |
-| `--model <id>` | Model (default: google/gemini-2.5-flash-image) |
-| `--aspect-ratio <ratio>` | 1:1, 16:9, 9:16, 4:3, 3:2 (default: 1:1)|
-| `--output <path>` | Save image to file |
-| `--json` | Output as JSON |
-
-## Input Validation
-
-Before constructing the command, validate all user-provided values:
-
-- **model**: Must match `^[a-zA-Z0-9_-]+/[a-zA-Z0-9._-]+$` (provider/model format). Reject if it contains spaces, semicolons, pipes, or backticks.
-- **prompt**: Single-quote the value to prevent shell expansion. Escape internal single quotes.
-- **temperature**: Must be a number between 0 and 2 (`^[0-2](\.\d+)?$`).
-- **aspect-ratio**: Must be one of: `1:1`, `16:9`, `9:16`, `4:3`, `3:2`.
-- **output**: Must be a valid file path. Reject if it contains shell metacharacters.
-
-Do not pass unvalidated user input into the command.
+Models use `provider/model-name` format (e.g., `openai/gpt-4o`, `meta-llama/llama-3.3-70b`).
+See `reference/models-and-options.md` for full model list, all options, and input validation rules.
 
 ## Examples
 
 ```bash
-# List all available models
-npx agnic@latest ai models --json
-
-# List only OpenAI models
-npx agnic@latest ai models --provider openai
-
-# Search for GPT models
-npx agnic@latest ai models --search gpt
+# List OpenAI models
+npx agnic@latest ai models --provider openai --json
 
 # Chat with GPT-4o
 npx agnic@latest ai chat --model openai/gpt-4o --prompt 'Explain quantum computing in one sentence'
 
-# Chat with system prompt
-npx agnic@latest ai chat --model anthropic/claude-3.5-sonnet --system 'You are a helpful coding assistant' --prompt 'Write a Python hello world'
-
 # Use a free model
 npx agnic@latest ai chat --model meta-llama/llama-3.3-70b --prompt 'What is 2+2?' --json
 
@@ -122,33 +66,19 @@ npx agnic@latest ai image --prompt 'A sunset over mountains' --output sunset.png
 
 # Generate widescreen image
 npx agnic@latest ai image --prompt 'Cyberpunk cityscape' --aspect-ratio 16:9 --output city.png
-
-# Use a specific image model
-npx agnic@latest ai image --prompt 'A portrait painting' --model openai/gpt-5-image --output portrait.png
-npx agnic@latest ai image --prompt 'Abstract art' --model black-forest-labs/flux.2-max --output art.png
-
-# Get image as JSON (base64)
-npx agnic@latest ai image --prompt 'Logo design for a tech startup' --json
 ```
 
 ## Prerequisites
 
 - Must be authenticated (`npx agnic@latest status` to check)
 - Wallet must have USDC balance (free models available for testing)
-- Image generation models:
-  - `google/gemini-2.5-flash-image` (default) — fast, good quality
-  - `google/gemini-3-pro-image-preview` — highest quality Google model
-  - `google/gemini-3.1-flash-image-preview` — latest flash preview
-  - `openai/gpt-5-image` — OpenAI image generation
-  - `black-forest-labs/flux.2-max` — Flux high quality
-  - `black-forest-labs/flux.2-klein-4b` — Flux lightweight/fast
 
 ## Error Handling
 
 Common errors:
 
-- "Not authenticated" — Run `npx agnic@latest auth login` first
-- "Insufficient balance" — Fund wallet at https://app.agnic.ai
-- "Model not found" — Check available models with `npx agnic@latest ai models`
-- "No image returned" — Try a different model or rephrase the prompt
-- "Rate limit exceeded" — Wait a moment and retry
+- "Not authenticated" -- Run `npx agnic@latest auth login` or set `AGNIC_TOKEN`
+- "Insufficient balance" -- Fund wallet at [app.agnic.ai](https://app.agnic.ai)
+- "Model not found" -- Check available models with `npx agnic@latest ai models`
+- "No image returned" -- Try a different model or rephrase the prompt
+- "Rate limit exceeded" -- Wait a moment and retry

package/skills/ai-gateway/reference/models-and-options.md

@@ -0,0 +1,68 @@
+# AI Gateway — Models & Options Reference
+
+## Model Format
+
+Models use `provider/model-name` format:
+
+| Provider    | Example Models                                    |
+| ----------- | ------------------------------------------------- |
+| openai      | `openai/gpt-4o`, `openai/gpt-4-turbo`            |
+| anthropic   | `anthropic/claude-3.5-sonnet`                     |
+| google      | `google/gemini-2.5-flash-image`, `google/gemma-*` |
+| meta-llama  | `meta-llama/llama-3.3-70b`                        |
+| mistralai   | `mistralai/mistral-large-latest`                  |
+| deepseek    | `deepseek/deepseek-chat`                          |
+
+Free models: `meta-llama/*`, `google/gemma-*`, `mistralai/*`
+
+## ai models Options
+
+| Option             | Description                        |
+| ------------------ | ---------------------------------- |
+| `--provider <name>`| Filter by provider (e.g., openai)  |
+| `--search <term>`  | Search in model name               |
+| `--json`           | Output as JSON                     |
+
+## ai chat Options
+
+| Option                 | Description                        |
+| ---------------------- | ---------------------------------- |
+| `--model <id>`         | Model ID (required)                |
+| `--prompt <text>`      | User message (required)            |
+| `--system <text>`      | System prompt                      |
+| `--temperature <n>`    | Temperature 0-2 (default: 0.7)     |
+| `--max-tokens <n>`     | Max tokens in response             |
+| `--json`               | Output as JSON                     |
+
+## ai image Options
+
+| Option                  | Description                                         |
+| ----------------------- | --------------------------------------------------- |
+| `--prompt <text>`       | Image description (required)                        |
+| `--model <id>`          | Model (default: google/gemini-2.5-flash-image)      |
+| `--aspect-ratio <ratio>`| 1:1, 16:9, 9:16, 4:3, 3:2 (default: 1:1)           |
+| `--output <path>`       | Save image to file                                  |
+| `--json`                | Output as JSON                                      |
+
+## Image Generation Models
+
+| Model                                    | Notes                        |
+| ---------------------------------------- | ---------------------------- |
+| `google/gemini-2.5-flash-image` (default)| Fast, good quality           |
+| `google/gemini-3-pro-image-preview`      | Highest quality Google model |
+| `google/gemini-3.1-flash-image-preview`  | Latest flash preview         |
+| `openai/gpt-5-image`                     | OpenAI image generation      |
+| `black-forest-labs/flux.2-max`           | Flux high quality            |
+| `black-forest-labs/flux.2-klein-4b`      | Flux lightweight/fast        |
+
+## Input Validation
+
+Before constructing the command, validate all user-provided values:
+
+- **model**: Must match `^[a-zA-Z0-9_-]+/[a-zA-Z0-9._-]+$` (provider/model format). Reject if it contains spaces, semicolons, pipes, or backticks.
+- **prompt**: Single-quote the value to prevent shell expansion. Escape internal single quotes.
+- **temperature**: Must be a number between 0 and 2 (`^[0-2](\.\d+)?$`).
+- **aspect-ratio**: Must be one of: `1:1`, `16:9`, `9:16`, `4:3`, `3:2`.
+- **output**: Must be a valid file path. Reject if it contains shell metacharacters.
+
+Do not pass unvalidated user input into the command.

package/skills/authenticate-wallet/SKILL.md

@@ -1,24 +1,47 @@
 ---
 name: authenticate-wallet
-description: Sign in to AgnicPay wallet via browser-based OAuth. Use when you or the user want to authenticate, sign in, log in, connect wallet, or set up the CLI. Covers phrases like "sign in", "log in", "authenticate", "connect my wallet", "set up agnic".
+description: >
+  Authenticate Agnic wallet via browser OAuth or headless API token.
+  Use when the user wants to sign in, log in, authenticate, connect wallet,
+  set up CLI, or resolve "Not authenticated" errors.
+  Supports AGNIC_TOKEN env var for CI/server/agent environments.
 user-invocable: true
 disable-model-invocation: false
-allowed-tools: ["Bash(npx agnic@latest status*)", "Bash(npx agnic@latest auth *)"]
+allowed-tools:
+  - "Bash(npx agnic@latest status*)"
+  - "Bash(npx agnic@latest auth *)"
 ---
 
-# Authenticating the AgnicPay Wallet
+# Authenticating the Agnic Wallet
 
-Use `npx agnic@latest auth login` to authenticate via browser-based OAuth. This opens the user's default browser to AgnicPay where they sign in and set spending limits for the CLI session.
+## Check Current Status
 
-## Confirm wallet is initialized and authed
+```bash
+npx agnic@latest status --json
+```
+
+If already authenticated, no further action needed. If not, choose the appropriate mode below.
+
+## Mode 1: Headless / Token Auth (CI, servers, agents)
 
+Preferred when no browser is available. Generate an API token at [app.agnic.ai](https://app.agnic.ai) > Settings > API Tokens.
+
+**Option A -- Environment variable** (recommended for automation):
 ```bash
-npx agnic@latest status
+export AGNIC_TOKEN=<your-api-token>
+npx agnic@latest status --json
 ```
 
-If already authenticated, no further action is needed. If not authenticated, proceed with login.
+The CLI reads `AGNIC_TOKEN` automatically. All subsequent commands in the same shell session use it without extra flags.
 
-## Login Flow
+**Option B -- Inline flag** (one-off commands):
+```bash
+npx agnic@latest --token <your-api-token> status --json
+```
+
+## Mode 2: Browser OAuth (interactive terminals)
+
+Use when a browser is available:
 
 ```bash
 npx agnic@latest auth login
@@ -26,30 +49,29 @@ npx agnic@latest auth login
 
 This command:
 1. Starts a temporary local server on a random port
-2. Opens the user's default browser to AgnicPay's OAuth consent screen
+2. Opens the default browser to the Agnic OAuth consent screen
 3. The user signs in (email, Google, or wallet) and approves spending limits
 4. The browser redirects back to `http://localhost:<port>/callback`
 5. The CLI exchanges the authorization code for tokens and saves them locally
 
-Wait for the CLI to print `✓ Authenticated!` before proceeding.
+Wait for the CLI to print `Authenticated!` before proceeding.
 
 ## Verify Authentication
 
-After login, confirm the session is active:
-
 ```bash
-npx agnic@latest status
+npx agnic@latest status --json
 ```
 
 Expected output:
 
-```
-Wallet Status
-✓ Authenticated
-
-Email:    user@example.com
-Wallet:   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
-Expires:  2026-05-22 14:30:00 UTC
+```json
+{
+  "authenticated": true,
+  "userId": "did:privy:...",
+  "email": "user@example.com",
+  "walletAddress": "0x...",
+  "tokenExpiry": "2026-05-22T14:30:00Z"
+}
 ```
 
 ## Logout
@@ -62,13 +84,13 @@ npx agnic@latest auth logout
 
 ## Token Storage
 
-Credentials are stored in `~/.agnic/config.json` with restricted permissions (`0600`). Tokens auto-refresh on 401 responses — no manual re-authentication needed until the refresh token expires (90 days).
+- Browser mode: credentials stored in `~/.agnic/config.json` with `0600` permissions. Tokens auto-refresh on 401 responses. Refresh token expires after 90 days.
+- Token mode: no local storage. The token is read from `AGNIC_TOKEN` env var or `--token` flag per invocation.
 
 ## Error Handling
 
-Common errors:
-
-- "Not authenticated" — Run `npx agnic@latest auth login`
-- "Authentication failed" — User cancelled the browser flow or the timeout (5 min) expired
-- "Could not open browser" — The CLI prints a URL to copy and open manually
-- "Token expired" — Tokens auto-refresh; if refresh also fails, re-run `npx agnic@latest auth login`
+- "Not authenticated" -- Set `AGNIC_TOKEN` env var, pass `--token`, or run `auth login`
+- "Authentication failed" -- User cancelled the browser flow or the 5-min timeout expired
+- "Could not open browser" -- The CLI prints a URL to copy and open manually
+- "Token expired" -- Browser tokens auto-refresh; API tokens must be regenerated at app.agnic.ai
+- "Invalid token" -- Check the token value; it may have been revoked or malformed